30:T693,md`# Stack Timeline A UI control to stack various timelines into one. Install ~~~js import {stack} from '@severo/stack-timeline' ~~~ Use ~~~js viewof t = stack(options) ~~~ --- ### Options All properties in [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c) and:

\`tracks\`

an iterable of tracks. Each track must be a \`{constructor, options}\` object, where:

\`constructor\` is a Timeline constructor (eg [\`ruler\`](https://observablehq.com/d/9d5f3f56f8013c30) or [\`thumbnails\`](https://observablehq.com/d/944b8108387aabaf))
\`options\` are the timeline constructor's options. Note that the [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c) options such as \`value\`, \`zoomRange\` or \`width\` will override \`options\`, and that the options field itself is optional.
\`bindZoomRange\` defines if the track's zoomRange property will be synchronized. Defaults to \`true\`

Defaults to an empty array.

### Returns The control. It's an Observable "view": it has a \`value\` getter, and it dispatches an \`input\` event whenever the value changes. ### Getters You can access the array of timelines objects in the stack with the \`.timelines\` getter. It allows to set their data for example, with \`stack.timelines[i].data = [...]\` ### Events See [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c). The events dispatched by a stack provide an additional information: \`event.detail.timeline\` is the timeline instance that originated the event (see \`stack.timelines\` getter). `31:T5da,viewof t2 = { const colorScale = d3 .scaleLinear() .domain([0, 5]) .range(["blue", "red"]) .interpolate(d3.interpolateHcl); return stack({ value: 5.3, min: 0, max: video.duration, step: 0.1, width: 600, zoomRange: [0, 10], zoomTranslateExtent: [-5, 11], zoomScaleExtent: [width / video.duration, 5000], tracks: [ { constructor: thumbnails, options: { frameAt: t => frameAt(video.currentSrc, t, { crossOrigin: 'anonymous' }), aspectRatio: video.videoWidth / video.videoHeight } }, { constructor: ruler }, { constructor: buttons }, ...[ [{ start: -1, end: 1 }, { start: 2.5, end: 7 }], [{ start: 0, end: 2 }], [{ start: 1, end: 2 }], [{ start: 3, end: 5 }] ].map(data => ({ constructor: intervals, options: { data, color: d => colorScale(d.start) } })), { constructor: points, options: { data: [ { value: -1 }, { value: 2 }, { value: 4 }, { value: 1.9 }, { value: 9 } ], color: d => colorScale(d.value), snap: true, valueof: d => d.value }, bindZoomRange: false }, { constructor: springRuler, options: { speed: 5 }, bindZoomRange: false } ] }); }32:T4f4,md` ### CHANGELOG - 2021/05/11: published - 2021/03/16: don't check for equality when setting the properties - 2021/03/16: provide event.detail.timeline to refer to the originating timeline - 2021/03/16: rename stack.children (which is a reserved property for Node) to stack.timelines - 2021/01/26: add a \`zoomTranslateExtent\` option - 2021/01/26: ensure all the children are initialized with the same value and zoomRange. The bug was: springRuler couples currentValue and zoomRange, and generally modifies zoomRange on init before any event listener could have been registered. We now update the common state after every children creation with the value and zoomRange of the initialized children. - 2021/01/25: add \`.children\` getter - 2021/01/22: bindZoomRange - 2021/01/19: zoomDisabled, step - 2021/01/18: zoomRange, zoomScaleExtent, min, max - 2021/01/14: creation ### TODO - [maybe] replace tracks by an array of Timeline objects, so that the synchronization is done through their setters. It would require that all the objects provide a \`width\` setter. It would also mean that we don't create, thus we don't own these objects because they could be referenced in other parts, which complicates the code in order to avoid memory leaks (eventListeners). `33:T403,function validateTracks(value, { defaultValue, mandatory = false }) { const definedValue = getDefinedValue({ value, defaultValue, mandatory }); const tracks = []; // It can be any iterable of track objects for (const track of definedValue) { if (typeof track !== 'object') { throw new Error('must be an object'); } if ( track.constructor === undefined || typeof track.constructor !== 'function' ) { throw new Error( `track.constructor property must be a function. Got ${track.constructor}` ); } const constructor = track.constructor; if (track.options !== undefined && typeof track.options !== 'object') { throw new Error( `track.options property, if defined, must be an object. Got ${track.options}` ); } const options = track.options || {}; const bindZoomRange = track.bindZoomRange === undefined ? true : !!track.bindZoomRange; tracks.push({ constructor, options, bindZoomRange }); } return tracks; }34:Tfaf,function stack(options = {}) { // Validation const { value: currentValue, min, max, step, width, zoomRange, zoomTranslateExtent, zoomScaleExtent, zoomDisabled, tracks } = validate(options); // We use the state as an intermediary that throttles the changes, // and decides the actual state (consensus) const initState = { value: { currentValue, zoomRange }, timeout: 40 }; const state = createState(initState); // Create the control const control = html`

`; const controlInvalidation = disposal(control); const id = DOM.uid().id; control.setAttribute('id', id); control.append(html` `); const timelines = []; // React to changes in the state function onStateCurrentValue(event) { // update the timelines except the origin of the event, if any for (const timeline of timelines) { if (timeline !== event.detail.by) { timeline.value = state.currentValue; } } } state.addEventListener('currentValue', onStateCurrentValue); controlInvalidation.then(() => state.removeEventListener('currentValue', onStateCurrentValue) ); function onStateZoomRange(event) { // update the timelines expect the origin of the event, if any for (const timeline of timelines) { if (timeline !== event.detail.by && timeline._track.bindZoomRange) { timeline.zoomRange = state.zoomRange; } } } state.addEventListener('zoomRange', onStateZoomRange); controlInvalidation.then(() => state.removeEventListener('zoomRange', onStateZoomRange) ); for (const track of tracks) { const timeline = track.constructor({ ...track.options, value: state.currentValue, min, max, step, width, zoomRange: state.zoomRange, zoomTranslateExtent, zoomScaleExtent, zoomDisabled }); timeline._track = track; function onTimelineInput() { state.set('currentValue', timeline.value, { by: timeline }); control.dispatchEvent(new CustomEvent("input", { detail: { timeline } })); } timeline.addEventListener('input', onTimelineInput); controlInvalidation.then(() => timeline.removeEventListener('input', onTimelineInput) ); // Note that zoomDisabled is not taken into account here, but passed to every // timeline that is responsible for its own behavior. Not sure if it's OK. function onTimelineZoomed(event) { if (timeline._track.bindZoomRange) { state.set('zoomRange', timeline.zoomRange, { by: timeline }); control.dispatchEvent( new CustomEvent("zoomed", { detail: { timeline } }) ); } else { event && event.stopPropagation(); } } timeline.addEventListener('zoomed', onTimelineZoomed); controlInvalidation.then(() => timeline.removeEventListener('zoomed', onTimelineZoomed) ); // init // as the value might have changed before the event listeners registration, // we better ensure the state is up to date. state.set('currentValue', timeline.value, { by: timeline }); state.set('zoomRange', timeline.zoomRange, { by: timeline }); timelines.push(timeline); } control.append(...timelines); // Getters and setters Object.defineProperty(control, 'value', { enumerable: true, get: () => state.currentValue, set: value => { state.set('currentValue', value, { by: 'outside' }); } }); Object.defineProperty(control, 'zoomRange', { enumerable: true, get: () => state.zoomRange, set: value => { state.set('zoomRange', value, { by: 'outside' }); } }); // Getter Object.defineProperty(control, 'timelines', { enumerable: true, get: () => [...timelines] // TODO: cache the result? or give access to the local variable? }); // Return the control return control; }35:[] 2e:{"title":"Stack Timeline","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":2047,"value":"md`## Examples\n\nControl with default options:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2050,"value":"viewof t1 = stack()","pinned":true,"hidden":false,"mode":"ojs"},{"id":2052,"value":"t1","pinned":true,"hidden":false,"mode":"ojs"},{"id":2054,"value":"md`Various options, on a video`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2225,"value":"// uncomment to change the data in the 5th timeline (intervals)\n// (viewof t2.children[5].data = [{ start: 1, end: 4 }])","pinned":true,"hidden":false,"mode":"ojs"},{"id":2340,"value":"a = d3\n .scaleLinear()\n .domain([0, video.duration])\n .range([\"#a52a2a88\", \"#4682b488\"])\n .interpolate(d3.interpolateHcl)","pinned":true,"hidden":false,"mode":"ojs"},{"id":2342,"value":"a(0)","pinned":true,"hidden":false,"mode":"ojs"},{"id":790,"value":"$31","pinned":true,"hidden":false,"mode":"ojs"},{"id":1052,"value":"t2","pinned":true,"hidden":false,"mode":"ojs"},{"id":2256,"value":"viewof t3 = stack({\n value: 1.3,\n min: 0,\n max: video.duration,\n step: 0.1,\n width: 600,\n zoomRange: [0, 10],\n // zoomTranslateExtent: [-5, 11], // don't set it: springRuler already limits the zoom translation\n zoomScaleExtent: [width / video.duration, 5000],\n tracks: [\n {\n constructor: thumbnails,\n options: {\n frameAt: t =>\n frameAt(video.currentSrc, t, { crossOrigin: 'anonymous' }),\n aspectRatio: video.videoWidth / video.videoHeight\n }\n },\n {\n constructor: springRuler,\n options: { speed: 5 }\n }\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":2258,"value":"t3","pinned":true,"hidden":false,"mode":"ojs"},{"id":2068,"value":"video = {\n const video = html`