@granite-elements/granite-timeline 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] - 2026-06-06
+
+Full rewrite. See the [migration guide](README.md#migration-from-v2) in the README.
+
+### Changed
+
+- **Lit 3** replaces Polymer 3.
+- **Native d3 v7 rendering** (`src/timeline-renderer.js`, a pure module usable
+  without the element) replaces the abandoned `d3-timelines` plugin.
+- d3 is now a regular ES-module dependency: no more runtime script loading via
+  `granite-js-dependencies-grabber`, no more webcomponentsjs polyfills.
+- Responsive redraw via `ResizeObserver` (v2 read the width once at startup).
+- `tickFormat` is a single value — a d3 time-format specifier string (usable as
+  an HTML attribute) or a `(date) => string` function — instead of the v2 object.
+- `tickTime` takes a modern d3-time interval (`import { timeHour } from 'd3-time'`)
+  instead of the old `d3.time.*`.
+- Default color palette changed from `d3.scale.category20()` (removed in d3 v7)
+  to `scaleOrdinal(schemeCategory10)`.
+- Wheel zooming (with `axisZoom`) now requires Ctrl/⌘ so the chart doesn't
+  hijack page scrolling; trackpad pinch works without modifier.
+- The chart renders in shadow DOM: page CSS no longer styles the internals.
+  Use the CSS custom properties (`--granite-timeline-label-color`,
+  `--granite-timeline-axis-color`) or `::part(timeline)`.
+
+### Added
+
+- `zoom` event reporting the visible domain: `detail: {start, end, transform}`.
+- `resetZoom()` method restoring the full-domain view.
+- Zoom/pan transform persists across redraws (resize, data updates).
+- Bars, bar labels and the today line are clipped to the plot area when zooming.
+
+### Removed
+
+- `displayCircles`, `relativeTime`, `showBorderLine` (+ `borderLine*` format
+  properties), `showTimeAxisTick` (+ `timeAxisTick*`), `xAxisClass`.
+- `scroll` event, and the redundant `i` field of event details (use `index`).
+- Bower support and the Polymer toolchain (`polymer.json`).
+
+## [2.0.0] - 2018-06-04
+
+### Changed
+
+- Migrated to npm-based Polymer 3 (ES modules instead of HTML imports).
+
+## 1.0.x - 2017-2018
+
+- Initial Polymer 1.x/2.x element wrapping the d3-timelines plugin,
+  distributed via Bower.
+
+[3.0.0]: https://github.com/LostInBrittany/granite-timeline/compare/2.0.0...3.0.0
+[2.0.0]: https://github.com/LostInBrittany/granite-timeline/compare/1.0.9...2.0.0

package/README.md

@@ -2,74 +2,171 @@
 
 # granite-timeline
 
-A timeline rendering element using d3 and d3-timeline plugin
+A timeline rendering web component built with [Lit](https://lit.dev) and [d3](https://d3js.org) v7.
 
-> Based on Polymer 2.x.
-
-
-
-## Doc & demo
-
-[https://lostinbrittany.github.io/granite-timeline](https://lostinbrittany.github.io/granite-timeline)
-
-
-## Usage
-
-<!---
-```
-<custom-element-demo>
-  <template>
-    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
-    <link rel="import" href="granite-timeline.html">
-    <next-code-block></next-code-block>
-  </template>
-</custom-element-demo>
-```
--->
-```html
-<granite-timeline 
-    data='[{"times":[{"starting_time":1355752800000,"ending_time":1355759900000}, {"starting_time":1355767900000,"ending_time":1355774400000}]},{"times":[{"starting_time":1355759910000,"ending_time":1355761900000}]},{"times":[{"starting_time":1355761910000,"ending_time":1355763910000}]}]'          
-    debug></granite-timeline>
-```
+> **v3.0.0** is a full rewrite: Lit instead of Polymer, native d3 v7 rendering instead of the
+> abandoned `d3-timelines` plugin, plain ES modules, no polyfills, no runtime script loading.
+> See [Migration from v2](#migration-from-v2).
 
 ## Install
 
-Install the component using [Bower](http://bower.io/):
-
 ```sh
-$ bower install LostInBrittany/granite-timeline --save
+npm install @granite-elements/granite-timeline
 ```
 
-Or [download as ZIP](https://github.com/LostInBrittany/granite-timeline/archive/gh-pages.zip).
-
 ## Usage
 
-1. Import Web Components' polyfill (if needed):
-
-    ```html
-    <script src="bower_components/webcomponentsjs/webcomponents.min.js"></script>
-    ```
+```js
+import '@granite-elements/granite-timeline';
+```
 
-2. Import Custom Element:
+```html
+<granite-timeline
+    data='[{"times":[{"starting_time":1355752800000,"ending_time":1355759900000}, {"starting_time":1355767900000,"ending_time":1355774400000}]},{"times":[{"starting_time":1355759910000,"ending_time":1355761900000}]}]'
+    show-time-axis></granite-timeline>
+```
 
-    ```html
-    <link rel="import" href="bower_components/granite-timeline/granite-timeline.html">
-    ```
+Function- and object-valued options are set as properties:
+
+```js
+import { scaleOrdinal } from 'd3-scale';
+import { timeHour } from 'd3-time';
+
+const el = document.querySelector('granite-timeline');
+el.data = [
+  { label: 'fruit 1', fruit: 'orange', times: [
+    { starting_time: 1355759910000, ending_time: 1355761900000 }] },
+  { label: 'fruit 2', fruit: 'apple', times: [
+    { starting_time: 1355752800000, ending_time: 1355759900000 }] },
+];
+el.colors = scaleOrdinal().domain(['apple', 'orange']).range(['#6b0000', '#ef9b0f']);
+el.colorsProperty = 'fruit';
+el.tickTime = timeHour;
+```
 
-3. Start using it!
+## Data format
+
+```js
+[
+  {
+    label: 'series label',     // optional, shown on the left when `stack` is set
+    times: [
+      {
+        starting_time: 1355752800000,  // ms epoch
+        ending_time: 1355759900000,    // ms epoch
+        label: 'bar label',            // optional
+        color: '#6b0000',              // optional, overrides the color scale
+      },
+    ],
+  },
+]
+```
 
-    ```html
-    <granite-timeline data="{{data}}" axis="{{axis}}"></granite-timeline>
-    ```
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|---|---|---|---|---|
+| `data` | `data` | Array | `[]` | The timeline data (see above) |
+| `width` | `width` | Number | element width | Width of the timeline in pixels |
+| `height` | `height` | Number | computed | Height of the timeline in pixels |
+| `itemHeight` | `item-height` | Number | `20` | Height of a data series row |
+| `itemMargin` | `item-margin` | Number | `5` | Margin between data series rows |
+| `marginTop` | `margin-top` | Number | `30` | Top margin |
+| `marginBottom` | `margin-bottom` | Number | `30` | Bottom margin |
+| `marginLeft` | `margin-left` | Number | `30` | Left margin |
+| `marginRight` | `margin-right` | Number | `30` | Right margin |
+| `tickFormat` | `tick-format` | String\|Function | `'%I %p'` | d3 time-format specifier, or a `(date) => string` function (property only) |
+| `tickTime` | — | d3-time interval | — | Tick time unit, e.g. `timeHour` from `d3-time` |
+| `tickInterval` | `tick-interval` | Number | `1` | Tick interval, used with `tickTime` |
+| `numTicks` | `num-ticks` | Number | — | Number of ticks, used when `tickTime` is unset |
+| `tickSize` | `tick-size` | Number | `6` | Tick size in pixels |
+| `tickValues` | — | Array | — | Explicit tick values (Date or ms epoch) |
+| `rotateTicks` | `rotate-ticks` | Number | `0` | Rotation of the tick labels in degrees |
+| `axisTop` | `axis-top` | Boolean | `false` | Places the time axis on top |
+| `axisZoom` | `axis-zoom` | Boolean | `false` | Enables zooming (Ctrl/⌘ + wheel, pinch, double-click) and panning (drag) of the time axis |
+| `colors` | — | d3 ordinal scale | `scaleOrdinal(schemeCategory10)` | Color scale for the series |
+| `colorsProperty` | `colors-property` | String | — | Data property mapped to the `colors` scale |
+| `beginning` | `beginning` | Date\|Number\|String | computed | Start of the timeline |
+| `ending` | `ending` | Date\|Number\|String | computed | End of the timeline |
+| `stack` | `stack` | Boolean | `false` | Stacks each data series on its own row |
+| `showToday` | `show-today` | Boolean | `false` | Shows a vertical line at the current time |
+| `todayMarginTop` | `today-margin-top` | Number | `25` | Top margin of the today line |
+| `todayMarginBottom` | `today-margin-bottom` | Number | `0` | Bottom margin of the today line |
+| `todayWidth` | `today-width` | Number | `2` | Stroke width of the today line |
+| `todayColor` | `today-color` | String | `rgb(245, 157, 0)` | Color of the today line |
+| `showTimeAxis` | `show-time-axis` | Boolean | `false` | Shows the time axis |
+| `background` | `background` | String | — | Background color of the rows |
+| `rowSeparators` | `row-separators` | String | — | Color of the separator lines between rows |
+| `labelFormat` | — | Function | — | Maps a raw `label` value to its display text |
+| `debug` | `debug` | Boolean | `false` | Logs debug information to the console |
+
+Color resolution order for each bar: `time.color` → `colors(time[colorsProperty])` →
+`colors(series[colorsProperty])` → `colors(seriesIndex)`.
+
+## Events
+
+All events are `CustomEvent`s dispatched from the element, with
+`detail: { d, index, datum, mouse, evt }` where `d` is the time entry, `index` its index
+in the series, `datum` the series object, `mouse` the `[x, y]` pointer position in the
+SVG, and `evt` the originating DOM event.
+
+| Event | Fired on |
+|---|---|
+| `click` | Click on a timeline bar |
+| `mouseover` | Pointer enters a bar |
+| `mouseout` | Pointer leaves a bar |
+| `hover` | Pointer moves over a bar |
+
+Note: a `click` listener also receives native click events from the element; check
+`event.detail?.d` to distinguish bar clicks.
+
+When `axisZoom` is enabled, a `zoom` event is fired on every zoom/pan, with
+`detail: { start, end, transform }` where `start`/`end` are the `Date` bounds of the
+visible domain and `transform` the d3 zoom transform.
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `resetZoom()` | Resets the axis zoom/pan to the initial full-domain view |
+
+## Styling
+
+The chart renders in shadow DOM. Customization hooks:
+
+| Hook | Description |
+|---|---|
+| `--granite-timeline-label-color` | Color of the series and bar labels |
+| `--granite-timeline-axis-color` | Color of the time axis |
+| `::part(timeline)` | The chart container |
+
+## Demo
 
-## Contributing
+```sh
+npm install
+npm run dev    # open http://localhost:5173/demo/
+```
 
-1. Fork it!
-2. Create your feature branch: `git checkout -b my-new-feature`
-3. Commit your changes: `git commit -m 'Add some feature'`
-4. Push to the branch: `git push origin my-new-feature`
-5. Submit a pull request :D
+## Migration from v2
+
+- **No more script loading**: d3 is now a regular ES-module dependency. Remove any
+  `granite-js-dependencies-grabber` setup; `bower` and the webcomponentsjs polyfills are gone.
+- **Dropped properties**: `displayCircles`, `relativeTime`, `showBorderLine` (+ its
+  `borderLine*` format properties), `showTimeAxisTick` (+ `timeAxisTick*`),
+  `xAxisClass`. Open an issue if you need one of them back.
+- **`axisZoom`** is kept, but zooming with the mouse wheel now requires
+  <kbd>Ctrl</kbd>/<kbd>⌘</kbd> so the chart doesn't hijack page scrolling; drag pans,
+  and a `zoom` event reports the visible domain.
+- **Dropped events**: `scroll`. The `i` field of event details is gone — use `index`.
+- **Tick intervals**: `tickTime` now takes a modern d3-time interval
+  (`import { timeHour } from 'd3-time'`) instead of the old `d3.time.hours`.
+- **`tickFormat`** is now a single value (string specifier or function) instead of the
+  v2 object — the other tick options moved to top-level properties (unchanged names).
+- **Default palette** changed from `d3.scale.category20()` (removed in d3 v7) to
+  `scaleOrdinal(schemeCategory10)`.
+- **Shadow DOM styling**: page CSS no longer reaches the chart internals. Use the CSS
+  custom properties / `part` listed above.
 
 ## License
 
-[MIT License](http://opensource.org/licenses/MIT)
+[MIT License](http://opensource.org/licenses/MIT)