30:T603,md`# Points Timeline A control to show a points (events) in one line, and select a time instant. Mouse-scroll when hovering the timeline to zoom in or out, click to select the nearest point. This control implements the [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c). Install ~~~js import {points} from '@severo/points-timeline' ~~~ Use ~~~js viewof t = points(options) ~~~ --- ### Options All properties in [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c) and:

\`data\`: an iterable of points: they can be primitives or objects. The rendering order is the iterable order: the first point is painted first and might be occulted behind the following points. Defaults to an empty array []
\`valueof\`: a function that takes a point and returns the value. Defaults to \`d => d\`
\`color\`: a [CSS Color Module Level 3](http://www.w3.org/TR/css3-color/#colorunits) specifier string, or a function that takes a point and returns a color string. Defaults to \`(d, i) => '#CCCCCC88'\`
\`snap\`: snap the click to the nearest point, if any. Defaults to \`true\`

### Returns The control. It's an Observable "view": it has a \`value\` getter, and it dispatches an \`input\` event whenever the value changes. ### Getters and setters The \`.data\` option can be get and set. ### Events See [Zoomable Timeline specification](https://observablehq.com/d/f48b7d02f25f093c) `31:T1ad1,function points(options = {}) { // Validation const { value: currentValue, min, max, step, width, zoomRange, zoomTranslateExtent, zoomScaleExtent, zoomDisabled, data, color, snap, valueof } = validate(options); const height = 20; const pixelRange = [0, width]; // We use the state as an intermediary to throttle the interactions const initState = { value: { currentValue, zoomRange }, timeout: 0 }; const state = createState(initState); function updateCurrentValue(value, by) { if (value !== state.currentValue) { state.set('currentValue', value, { by }); } } function updateZoomRange(value, by) { if (state.zoomRange.some((d, i) => d !== value[i])) { state.set('zoomRange', value, { by }); } } const zoomedScale = d3.scaleLinear().range(pixelRange); function getZoomRangeFromTransform(transform) { const { k, x: tx } = transform; const za = -tx / k; const zb = (width - tx) / k; return [za, zb]; } function getTransformFromZoomRange(zoomRange) { const [za, zb] = zoomRange; const k = width / (zb - za); const tx = -za * k; return d3.zoomIdentity.translate(tx, 0).scale(k); } // Create the control const svg = d3 .create("svg") .attr("viewBox", [0, 0, width, height]) .attr('width', width) .attr('height', height) .classed('points', true); const svgId = DOM.uid().id; svg.attr('id', svgId); svg.node().appendChild(html` `); const control = svg.node(); const controlInvalidation = disposal(control); const zoomBehavior = d3 .zoom() .scaleExtent(zoomScaleExtent) .translateExtent([ [zoomTranslateExtent[0], 0], [zoomTranslateExtent[1], 0] ]); const circleRadius = height * 0.5 - 2; function updateData(data) { const filteredData = data.filter( d => valueof(d) >= min && valueof(d) <= max ); return svg .selectAll('g.point') .data(filteredData, JSON.stringify) .join( enter => { const g = enter.append("g").classed('point', true); g.append('g') .classed('symbol', true) .append('circle') .attr('cx', 0) .attr('cy', 0) .attr('r', circleRadius) .attr('fill', color) .attr('stroke', 'black'); return g; }, update => update, exit => exit.remove() ); } function getPointElements() { return svg.selectAll('g.point'); } function drawPoints() { const { k, x: tx } = d3.zoomTransform(svg.node()); getPointElements().attr( "transform", d => `translate(${tx + k * valueof(d)}, ${height / 2})` ); } function updateZoom() { const transform = getTransformFromZoomRange(state.zoomRange); svg.call(zoomBehavior.transform, transform); } // init updateData(data); updateZoom(); drawPoints(); // React to changes in the state function onStateCurrentValue(event) { // send an event if the update comes from the control's interactions if (event.detail.by !== 'outside') { control.dispatchEvent(new CustomEvent("input")); } // nothing to redraw } state.addEventListener('currentValue', onStateCurrentValue); controlInvalidation.then(() => state.removeEventListener('currentValue', onStateCurrentValue) ); function onStateZoomRange(event) { // send an event if the update comes from the control's interactions if (event.detail.by !== 'outside') { control.dispatchEvent(new CustomEvent("zoomed")); } if (event.detail.by !== zoomBehavior) { updateZoom(); } drawPoints(); } state.addEventListener('zoomRange', onStateZoomRange); controlInvalidation.then(() => state.removeEventListener('zoomRange', onStateZoomRange) ); // Interactions that modify the current value (click, setter) function onPointClick(event) { // ignore the click if a drag has been started - https://observablehq.com/@d3/click-vs-drag if (event.defaultPrevented) return; // dragged const originalElement = d3.select(event.target.closest('g.point')); if (originalElement.size() !== 1) return; updateCurrentValue(valueof(originalElement.datum()), 'click'); // animate the selected element originalElement .select('.symbol') .transition() .attr("transform", "scale(2,2)") .transition() .attr("transform", ""); } function onSvgClick(event) { // ignore the click if a drag has been started - https://observablehq.com/@d3/click-vs-drag if (event.defaultPrevented) return; // dragged // Find the nearest point const pointElements = getPointElements(); if (pointElements.size() === 0) return; const { k, x: tx } = d3.zoomTransform(svg.node()); const clickValue = (d3.pointer(event)[0] - tx) / k; // TODO: optimize const pointsNodes = [...getPointElements()]; const nearestIdx = d3.minIndex(pointsNodes, d => { const pointValue = valueof(d3.select(d).datum()); return Math.abs(pointValue - clickValue); }); const selectedElement = d3.select(pointsNodes[nearestIdx]); if (selectedElement.size() !== 1) return; const newValue = valueof(selectedElement.datum()); updateCurrentValue(newValue, 'click'); // animate the selected element selectedElement .select('.symbol') .transition() .attr("transform", "scale(2,2)") .transition() .attr("transform", ""); } if (snap) { svg.on("click", onSvgClick); controlInvalidation.then(() => svg.on('click', null)); } else { svg.selectAll('.point').on("click", onPointClick); controlInvalidation.then(() => svg.selectAll('.point').on('click', null)); } Object.defineProperty(control, 'value', { enumerable: true, get: () => state.currentValue, set: value => { updateCurrentValue(value, 'outside'); } }); // Interactions that change the zoom range (zoom, setter) if (!zoomDisabled) { function onZoomBehaviorZoom(event) { updateZoomRange(getZoomRangeFromTransform(event.transform), zoomBehavior); } zoomBehavior.on("zoom", onZoomBehaviorZoom); controlInvalidation.then(() => zoomBehavior.on("zoom", null)); svg.call(zoomBehavior); } Object.defineProperty(control, 'zoomRange', { enumerable: true, get: () => state.zoomRange, set: value => { updateZoomRange(value, 'outside'); } }); // Interactions that change the data Object.defineProperty(control, 'data', { enumerable: true, get: () => getPointElements().data(), set: value => { // call validateData? updateData(value); } }); // Return the control return control; }32:[] 2e:{"title":"Points Timeline","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":1995,"value":"md`## Examples\n\nControl with default options:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2002,"value":"viewof t1 = points()","pinned":true,"hidden":false,"mode":"ojs"},{"id":2004,"value":"t1","pinned":true,"hidden":false,"mode":"ojs"},{"id":2007,"value":"md`Control with all the options:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3049,"value":"viewof t2.data","pinned":true,"hidden":false,"mode":"ojs"},{"id":3036,"value":"// Uncomment\n//\n// (viewof t2.data = [{ value: -1 }, { value: 0 }])","pinned":true,"hidden":false,"mode":"ojs"},{"id":790,"value":"viewof t2 = {\n const min = -2;\n const max = 10;\n const colorScale = d3\n .scaleLinear()\n .domain([min, max])\n .range([\"blue\", \"red\"])\n .interpolate(d3.interpolateHcl);\n const color = d => colorScale(d);\n return points({\n value: 5.72,\n min,\n max,\n step: 0.1,\n width: 600,\n zoomRange: [min, max],\n zoomTranslateExtent: [-5, 11],\n zoomScaleExtent: [1, 10000],\n zoomDisabled: false,\n data: [-1, 0, 2, 4, 1.9],\n color,\n snap: true\n });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1052,"value":"t2","pinned":true,"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":12,"value":"md`### Data`","pinned":false,"hidden":false,"mode":"ojs"},{"id":18,"value":"md`\n### CHANGELOG\n\n- 2021/05/11: published\n- 2021/03/21: BREAKING CHANGE add a valueof accessor that defaults to d => d, instead of d.value previously\n- 2021/01/26: add a zoomTranslateExtent option\n- 2021/01/26: don't limit anymore the zoom range based on [min, max]\n- 2021/01/25: \\`.data\\` getter and setter\n- 2021/01/20: creation\n\n### TODO\n\n- don't filter the data in .data getter: we should return what has been set, not what is seen in the zoom range\n- show the current time\n- add precision options\n- add height option\n- add a tooltip with the hovered interval value\n- add an option to select the symbol\n- visually represent the min and max values (currently: points are not shown)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2322,"value":"md`### Data`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2326,"value":"defaultValues = ({\n data: [],\n color: '#CCCCCC88',\n snap: true,\n valueof: d => d\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":27,"value":"md`### Code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2335,"value":"function validateData(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 return [...definedValue];\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2877,"value":"function validateColor(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n const color =\n typeof definedValue === 'string' ? () => definedValue : definedValue;\n if (typeof color != 'function') {\n throw new Error('must be a string or a function');\n }\n return color;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3004,"value":"function validateSnap(value, { defaultValue, mandatory = false }) {\n const definedValue = getDefinedValue({ value, defaultValue, mandatory });\n return !!definedValue;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3087,"value":"function validateValueof(value, { defaultValue, mandatory = false }) {\n const valueof = getDefinedValue({ value, defaultValue, mandatory });\n if (typeof valueof != 'function') {\n throw new Error('must be a function');\n }\n return valueof;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":833,"value":"function validate(options) {\n return {\n ...validateCommon(options),\n data: validateData(options.data, {\n mandatory: false,\n defaultValue: defaultValues.data\n }),\n color: validateColor(options.color, {\n mandatory: false,\n defaultValue: defaultValues.color\n }),\n snap: validateSnap(options.snap, {\n mandatory: false,\n defaultValue: defaultValues.snap\n }),\n valueof: validateValueof(options.valueof, {\n mandatory: false,\n defaultValue: defaultValues.valueof\n })\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2015,"value":"import {\n validate as validateCommon,\n getDefinedValue,\n isIterable\n} from 'f48b7d02f25f093c'","pinned":false,"hidden":false,"mode":"ojs"},{"id":774,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"md`### Dependencies`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2403,"value":"import { intrinsicHeight, intrinsicWidth } from '@severo/canvasimagesource'","pinned":false,"hidden":false,"mode":"ojs"},{"id":781,"value":"import { createState } from '70f545ce6ecf7963'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1187,"value":"d3 = require('d3@6')","pinned":false,"hidden":false,"mode":"ojs"},{"id":2681,"value":"import { disposal } from '@mbostock/disposal'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}