30:T1526,md`# Timeline controls We present a collection of zoomable timeline inputs that can be used to control and visualize a video, an animation or other temporal data. ![Timelines](${await FileAttachment("timelines@1.png").url()}) Mouse-scroll when hovering the timelines to zoom in or out, and click to select the time (and update the control's value). They can be imported from this notebook: ~~~js import {ruler, springRuler, thumbnails, buttons, intervals, points, stack} from '@severo/timeline' ~~~ See the details of every control: - [ruler](https://observablehq.com/@severo/ruler-timeline) - [springRuler](https://observablehq.com/@severo/spring-ruler-timeline) - [thumbnails](https://observablehq.com/@severo/thumbnails-timeline) - [buttons](https://observablehq.com/@severo/buttons-timeline) - [intervals](https://observablehq.com/@severo/intervals-timeline) - [points](https://observablehq.com/@severo/points-timeline) - [stack](https://observablehq.com/@severo/stack-timeline) For example, they can be used to navigate to a particular frame in a video: - [Video Time Zoom](https://observablehq.com/@severo/video-time-zoom) --- The zoomable timeline specification defines a common API for zoomable horizontal timeline components. Any zoomable timeline component is an Observable input, compatible with viewof. This specification and the common functions provided in this notebook make it easier to combine various timelines in the [stack timeline](https://observablehq.com/d/505ccf83529f32b3) for example. A control that implements the timeline specification MUST: - *define the control width*, providing a \`width\` constructor option. - *provide zoom and pan interactions*. The current zoom is defined by the \`zoomRange\` property (a two values array [t0, t1]). The \`zoomRange\` property can be set using the constructor option and the setter. A \`zoomed\` event is dispatched on every zoom or pan interaction. The zoom linearly maps \`zoomRange\` to the full width of the control, from left (\`t0\`) to right (\`t1\`). - *allow to select a specific value*. The current value is available as the \`value\` property. The \`value\` property can be set using the constructor option and the setter. An \`input\` event is dispatched whenever the value is changed using the input. ### Constructor options

\`value\`: the current value. Defaults to 0
\`min\`: the minimum value. Defaults to -Infinity
\`max\`: the maximum value. Defaults to +Infinity
\`step\`: the number that specifies the granularity that the value must adhere to. It follows the same logic as the [\`\`'s \`step\` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-step). Defaults to 'any'
\`width\`: the control width in pixels. Defaults to Observable's \`width\`
\`zoomRange\`: the zoom range. The \`zoomRange\` property keeps no relation with the \`value\` property, in particular \`value\` is not required to lie inside the zoom range. Defaults to [0, 1]
\`zoomTranslateExtent\`: the extent of zoom range [minZoomRangeStart, maxZoomRangeEnd]. The zoom range start cannot be least than minZoomRangeStart, and the zoom range end cannot be greater than maxZoomRangeEnd. The name and behavior are similar to d3-zoom [.translateExtent()](https://github.com/d3/d3-zoom/#zoom_translateExtent). Defaults to [-Infinity, +Infinity]
\`zoomScaleExtent\`: the extent of zoom scale [minZoomScale, maxZoomScale]. The zoom scale is expressed in pixels per unit of value. Set minZoomScale to \`width / (zoomRange[1]-zoomRange[0])\` in order to forbid zoom out from the initial scale for example. Note that it is relative to \`width\`. The values will typically be 100 or more. The name and behavior are similar to d3-zoom [.zoomScaleExtent()](https://github.com/d3/d3-zoom/#zoom_scaleExtent). Defaults to [0, +Infinity]
\`zoomDisabled\`: disables the zoom interactions. Note that the \`zoomRange\` setter and getter still work. Defaults to false

### Getters and setters \`value\` and \`zoomRange\` can be get and set. Note that it's possible to set a \`value\` that does not respect \`min\`, \`max\` or \`step\` options, and a \`zoomRange\` that does not respect \`zoomRangeExtent\`, similarly to what occurs with the \`\` element. ### Events

\`input\`: The \`input\` event is dispatched whenever \`value\` is changed using the control's interactions (click).
\`zoomed\`: The \`zoomed\` event is dispatched whenever \`zoomRange\` is changed using the control's interactions (pan, zoom).

Note that events are not dispatched when the properties are modified using the setters. --- Note that zoomable timeline controls MIGHT also provide: - specific options, getters and setters - a \`height\` option - \`precision\`, and maybe other [slider input](https://observablehq.com/@jashkenas/inputs#sliderDemo) options - keyboard interaction - touch interaction - hover interaction - a graphical representation of the current time when it lies outside of the time range ("go to current time" link, for example) - apply the \`:invalid\` pseudo-class if the value is invalid regarding min, max and step. `31:T527,md` ### CHANGELOG - 2021/05/11: published - 2021/01/26: add a \`zoomRangeExtent\` option - 2021/01/19: zoomDisabled, step - 2021/01/18: zoomRange, zoomScaleExtent, min, max - 2021/01/12: creation ### TODO - x variable, instead of time. By the way, t is not a time in the sense of HH:MM:SS, it's just a number. - compare to other inputs: - @jashkenas/slider / input[range]: must have min and max values, and does not allow to select precise values - @jashkenas/number / input[number]: precise selection, not graphical - @mbostock/Scrubber: picks an element in an array, selection is not precise since it uses input[range] - log scales? categorical scales? colors? correspondance with d3-scale? - default control for every d3-scale? - \`orientation\`: the orientation of the main axis. Values can be \`lr\` (horizontal, left to right), \`tb\` (vertical, top to bottom) or \`bt\` (vertical, bottom to top). Defaults to \`lr\` - split to separate the "value selection" and "zoom" features - if \`value\` or \`zoomRange\` is set to a value that does not respect its restrictions (\`min\`, \`max\`, \`step\`, \`zoomScaleExtent\`), add the \`:invalid\` pseudo class to the element, and style it in all the Timelines, [similarly to the \`\` element](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid) `32:T5ca,function validate(options) { if (typeof options !== 'object') { throw new Error(`options must be an object. Got ${options}`); } const min = validateMin(options.min, { mandatory: false, defaultValue: defaultValues.min }); const max = validateMax(options.max, { mandatory: false, defaultValue: defaultValues.max }); // Ensure min is less than max. Not the same behavior as const limits = min <= max ? [min, max] : [max, min]; return { value: validateValue(options.value, { mandatory: false, defaultValue: defaultValues.value }), min: limits[0], max: limits[1], step: validateStep(options.step, { mandatory: false, defaultValue: defaultValues.step }), width: validateWidth(options.width, { mandatory: false, defaultValue: defaultValues.width }), zoomRange: validateZoomRange(options.zoomRange, { mandatory: false, defaultValue: defaultValues.zoomRange }), zoomTranslateExtent: validateZoomTranslateExtent( options.zoomTranslateExtent, { mandatory: false, defaultValue: defaultValues.zoomTranslateExtent } ), zoomScaleExtent: validateZoomScaleExtent(options.zoomScaleExtent, { mandatory: false, defaultValue: defaultValues.zoomScaleExtent }), zoomDisabled: validateZoomDisabled(options.zoomDisabled, { mandatory: false, defaultValue: defaultValues.zoomDisabled }) }; }33:[{"id":"f859c733487e3448fe86797fbc6d1fc27b76442e2783822d118e488b13de52b1ed98fcf44b5bfc9d6cbfb9c7c3598fa7609ee5c459364170c1cc46c30af6eb32","href":"https://static.observableusercontent.com/files/f859c733487e3448fe86797fbc6d1fc27b76442e2783822d118e488b13de52b1ed98fcf44b5bfc9d6cbfb9c7c3598fa7609ee5c459364170c1cc46c30af6eb32","name":"timelines@1.png","type":"image/png","lastModified":1620721325688.531,"size":269949}] 2e:{"title":"Timeline controls","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":4,"value":"md`---\n\n### Credits\n\n_Developed for the [LIRIS M2i project](https://projet.liris.cnrs.fr/mi2/) by Sylvain Lesage._\n\n---\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":18,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":2100,"value":"md`### Data`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2104,"value":"defaultValues = ({\n value: 0,\n min: -Infinity,\n max: +Infinity,\n step: 'any',\n width,\n zoomRange: [0, 1],\n zoomTranslateExtent: [-Infinity, +Infinity],\n zoomScaleExtent: [0, +Infinity],\n zoomDisabled: false\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":27,"value":"md`### Code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1183,"value":"function isIterable(obj) {\n // checks for null and undefined\n if (obj == null) {\n return false;\n }\n return typeof obj[Symbol.iterator] === 'function';\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":819,"value":"function getDefinedValue({ value, defaultValue, mandatory }) {\n if (mandatory === true && value === undefined) {\n throw new Error('cannot be undefined');\n }\n return value !== undefined ? value : defaultValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":818,"value":"function validateValue(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (!isFinite(definedValue)) {\n throw new Error('must be a finite number');\n }\n return definedValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1918,"value":"function validateZoomRange(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (!isIterable(definedValue)) {\n throw new Error('must be an iterable');\n }\n const array = [...definedValue];\n if (array.length !== 2 || array.some(d => !isFinite(d))) {\n throw new Error('must be an iterable of two finite numbers');\n }\n const [min, max] = array.sort((a, b) => a - b);\n if (min === max) {\n throw new Error('the zoom range min and max values cannot be the equal');\n }\n return [min, max];\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2424,"value":"function validateZoomTranslateExtent(\n value,\n { defaultValue, mandatory = false }\n) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (!isIterable(definedValue)) {\n throw new Error('must be an iterable');\n }\n const array = [...definedValue];\n if (array.length !== 2 || array.some(d => isNaN(d))) {\n throw new Error('must be an iterable of two numbers');\n }\n const [min, max] = array.sort((a, b) => a - b);\n return [min, max];\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2291,"value":"function validateZoomScaleExtent(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (!isIterable(definedValue)) {\n throw new Error('must be an iterable');\n }\n const array = [...definedValue];\n if (array.length !== 2 || array.some(d => isNaN(d) || d < 0)) {\n throw new Error('must be an iterable of two positive numbers');\n }\n const [min, max] = array.sort((a, b) => a - b);\n return [min, max];\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":845,"value":"function validateWidth(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (!isFinite(definedValue) || definedValue < 0) {\n throw new Error('must be a positive number');\n }\n return definedValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1659,"value":"function validateHeight(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n\n if (!isFinite(definedValue) || definedValue < 0) {\n throw new Error('must be a positive number');\n }\n\n return definedValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2304,"value":"function validateMin(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n const number = +definedValue;\n\n if (isNaN(number) || number === Infinity) {\n throw new Error('must be a finite number, or -Infinity');\n }\n return number;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2319,"value":"function validateMax(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n const number = +definedValue;\n\n if (isNaN(number) || number === -Infinity) {\n throw new Error('must be a finite number, or +Infinity');\n }\n return number;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2375,"value":"function validateStep(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n if (definedValue === 'any') {\n return definedValue;\n }\n const number = +definedValue;\n if (!isFinite(number) || number <= 0) {\n throw new Error('must be a positive finite number');\n }\n return number;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2346,"value":"function validateZoomDisabled(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n return !!definedValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":833,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"md`### Dependencies`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2130,"value":"d3 = require('d3-scale@3')","pinned":false,"hidden":false,"mode":"ojs"},{"id":2260,"value":"// import only to re-export\nimport { ruler } from '9d5f3f56f8013c30'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2416,"value":"// import only to re-export\nimport { springRuler } from '451eb8ab53442510'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2263,"value":"// import only to re-export\nimport { thumbnails } from '944b8108387aabaf'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2266,"value":"// import only to re-export\nimport { stack } from '505ccf83529f32b3'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2279,"value":"import { buttons } from '54b1509d05472a8e'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2401,"value":"import { intervals } from '90116279eaf6d983'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2411,"value":"import { points } from 'd2c77bda6f159deb'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}