# Timeline (``) Phases on a shared time axis, one lane per track: a production schedule, a project plan, two methods compared side by side. The server's `` is the data of record: the element reads it, draws the lanes, and keeps it for screen readers and no-script readers. Self-registering, light DOM, no words of its own. ```html
…
Two schedules
MethodPhaseStarts (day)DaysSource
Standard toppingRooting010Fig. 2
Standard toppingVegetative growth1014Fig. 2
Standard toppingRecovery2414Fig. 2
Standard toppingFlowering3856Fig. 2
Early toppingMother-plant wait−1414Fig. 2
``` Without JS, or without a `` child, the page shows the table and nothing else. Join a reference with a no-break space (`Fig. 2`) so that no line ends between its parts. ## The table One body row per segment. Its cells, in order: | cell | meaning | |---|---| | 1 | the track (consecutive or not: rows group by this text, in first-appearance order) | | 2 | the segment's label, shown on the bar when it fits, in the legend and the tooltip | | 3 | where it starts, in the table's unit | | 4 | how long it lasts, in the same unit | | 5… | anything else: tooltip lines, each under its column's header | - A row whose start or length isn't a number is skipped (a totals row, say); dev builds warn. - Numbers are read leniently: `−14`, `1 000`, `13,4`. A cell with `data-value` uses that instead of its text, for a page that formats numbers for its readers. - Row attributes: `data-series="1"`…`"8"` picks a palette slot, `"muted"` the neutral one; without one, each distinct label takes the next slot, in order. `data-texture="hatch"` lays the 45° hatch over the fill (for "the same kind, but extra", like a recovery period). **The page owns the table.** Rewriting its rows (a toggle on the page, an htmx swap) redraws the lanes; the element never fetches. It writes two marks on each segment row, for the table view (below), and with `show-table` it moves the table into a scroll region; it removes the marks and puts the table back where it was when it disconnects. ## The table view With `show-table`, the table shows under the plot as a quiet data table, in the chart's tokens: a small muted caption, the header row in `--pebble-chart-ink-2`, hairline row rules in `--pebble-chart-grid`, start and length (the 3rd and 4th cells) right-aligned on tabular figures, and a swatch before each segment's label in its segment's fill and texture. A firmer rule (`--pebble-chart-tick`, like the header's) marks where a track's run of rows starts; its name is repeated in `ink-2` on the rows after. Under 30rem the type is smaller and the cells tighter. **The table is never squeezed: it scrolls.** The element moves the page's table into a scroll region it renders after the plot: ```html
…the page's table, the same node…
``` - The table keeps an auto layout at 100% of the region: every column is at least as wide as its longest word, wider when there is room. **No word is ever broken.** The sheet sets `white-space: normal`, `overflow-wrap: normal`, `word-break: normal` and `hyphens: manual` on it, whatever the page sets around it. A line can still end after a hyphen the page wrote ("Pied-|Mère", "LOT-2019-|1004-A") or at a soft hyphen (`­`); join what must stay together with a no-break space (`Fig. 2`). - **When the table is wider than the element, the region scrolls sideways, never the page.** The region is a tab stop after the plot, with a 2px focus ring in `--pebble-chart-focus`, and the arrow keys scroll it (the browser's own scrolling: the element binds no keys there). It is named by the caption: `aria-labelledby` when the caption has an `id`, else an `aria-label` with the caption's text. Give the table a caption: without one the region is still a tab stop, with no name for a screen reader to announce. - An inset shadow at an edge says there is more that way: a scroll-driven animation (`animation-timeline: scroll(self inline)`), so CSS only, and nothing where the region does not scroll. Where the browser lacks scroll timelines, the region still scrolls, without the shadow. The shadow follows the physical left and right edges, so a right-to-left page gets it on the wrong sides. - **The table is the page's.** It moves into the region once the element has inserted what it renders, and goes back exactly where the page had it, before the same sibling, when `show-table` is removed or the element disconnects: the host's markup is then what the server sent. The element keeps observing the same node, so rewriting rows works the same in either place. The move uses `moveBefore` where the browser has it, which keeps focus inside the table (a focused link stays focused, measured in Chromium); elsewhere it is a remove and insert, which loses that focus and a text selection inside the table. Either way the region starts scrolled to the start again when the table comes back into it. - Without `show-table` the table stays where the page put it, visually hidden, and screen readers keep it. Toggling `show-table` moves it in and out; the region is `hidden` while the table is not in it. What that gives, measured in headless Chromium with its `system-ui` font and 16px page margins, for the sample's five columns (with long capitalised labels: "Recovery (Supplementary Vegetative Growth)") and for 7 and 9 columns (adding a long note, a DOI, a cultivar, a batch): | table | its narrowest (the region scrolls below it) | at 280, 320, 360, 390 and 1280px | |---|---|---| | 5 columns, English | 311px | scrolls at 280 and 320px, fits from 360px | | 5 columns, French | 326px | scrolls at 280 and 320px, fits from 360px | | 7 columns (a note and a DOI) | 613px (English), 631px (French) | scrolls up to 390px, fits at 1280px | | 9 columns | 722px (English), 738px (French) | scrolls up to 390px, fits at 1280px | The honest limits: - **When the table scrolls, every column is as narrow as its longest word.** An auto table that cannot fit takes its minimum width, so a long note wraps into a tall, narrow column: with nine columns, from 280 to 390px, the English note runs eight lines in a column as wide as "Supplementary", every row is 147px tall and the table 1,249px (French: seven lines, 131px, 1,115px). Nothing is broken and nothing is hidden, but it is a long read. A page that knows one of its columns is prose can give it room of its own, since the page owns the cells: `pebble-timeline td:nth-child(6) { min-width: 16em }` makes that note four lines, the rows 80px and the table 712px tall (measured). The element sets no such floor, because any floor that helps a note at 320px would also make the five-column sample scroll at 360 and 390px, where it fits today. - A table that scrolls hides its right-hand columns until the reader scrolls. The edge shadow is the only hint, and only where scroll timelines exist. - The region is a tab stop even when it does not scroll (tabbing to it then does nothing visible but the ring). Knowing whether it scrolls means measuring, which this view gave up on purpose. - Screen-reader reading order follows the DOM: with `show-table` the table comes after the legend and the plot; without it, first, where the page put it. The marks: `data-fill` is the row's palette slot (`1`…`8`, `muted`), the same as its segment's `data-series`. A row without `data-series` gets its slot from its label, which CSS cannot work out, so the element writes it. `data-track-start` is on the first row of each run of one track. Rows that stop being segments (a totals row) lose both. Writing them never triggers a re-read: the element only watches the attributes it reads (`data-series`, `data-texture`, `data-value`). ## Attributes and props | attribute | type | default | meaning | |---|---|---|---| | `min`, `max` | number | the data's extent (and the baseline) | the axis' ends, in the table's unit; set them to keep the axis still while rows change | | `step` | number | a round step, about 6 | the distance between ticks | | `per` | number | 1 | how many table units make one displayed unit (`per="7"`: days in, weeks shown) | | `unit` | string | none | appended to totals (`wk`, `sem.`) | | `axis` | string | none | the axis title | | `baseline` | number | 0 | where totals are counted from; its gridline is darker | | `show-table` | boolean | absent | also show the table to sighted readers, in a scroll region under the plot ([The table view](#the-table-view)); it is always there for screen readers | ## Behavior - **Totals:** each track's end, from the baseline, at the end of its lane, in `per` units with `unit`. Tracks after the first also show their difference from the first (`−2 wk`). - **Hover or keyboard:** the plot is one tab stop; arrows, Home and End move through the segments in reading order, Escape lets go, Enter emits `select`. The tooltip shows the segment's label, its track, and every remaining cell under its header, value first. - **Labels:** a segment's label shows when it fits, and is hidden (never clipped) when it doesn't; the legend, the tooltip and the table still carry it. During a glide, a label is fitted against both the segment's current width and the width it is heading to: it hides as soon as a shrink starts, and shows once a grow has ended (the label's `max-width` is its segment's target width, in the lane's `cqw`; it is fitted again at `transitionend`). - **Motion:** when the page rewrites rows, each segment that is still there glides to its new place and width (`left` and `width`, computed from `--pebble-timeline-start` and `--pebble-timeline-size`, 350ms ease-out), only under `prefers-reduced-motion: no-preference`. Segments are kept by track and label: a changed start or length moves the segment, while a renamed label or a new track draws a new one. A label repeated within one track is kept by its first occurrence; the repeats are redrawn. A resize never animates (the positions are percentages). - **Narrow** (under 30rem of its own width): each track's label and total move above its lane, which takes the full width, and the gridlines go; the ticks stay. - Numbers are formatted in the language of the nearest `[lang]` ancestor. ## Events | event | detail | when | |---|---|---| | `select` | `{ index, track, label }` | a segment is clicked, or Enter is pressed on the active one | ## Parts `timeline` · `legend` · `plot` · `track-label` · `lane` · `segment` · `total` · `axis` · `axis-title` · `tooltip` · `table-view` State is in attributes: `[data-series]`, `[data-texture]`, `[data-first]`, `[data-last]`, `[data-active]`, `[data-unlabelled]` on segments; `[data-open]` on the tooltip; `[data-enhanced]` and `[show-table]` on the host; `[data-fill]` and `[data-track-start]` on the table's segment rows. ## CSS hooks Shared by every library chart, so one set of page tokens themes them all: `--pebble-chart-series-1` … `-8` · `--pebble-chart-muted` · `--pebble-chart-ink` · `--pebble-chart-ink-2` · `--pebble-chart-tick` · `--pebble-chart-grid` · `--pebble-chart-axis` · `--pebble-chart-surface` · `--pebble-chart-border` · `--pebble-chart-hatch` · `--pebble-chart-focus` (falls back to `--accent`) The timeline's own: `--pebble-timeline-bar` (24px) · `--pebble-timeline-gap` (2px) · `--pebble-timeline-radius` (4px) · `--pebble-timeline-row-gap` (0.75rem) · `--pebble-timeline-font-size` (0.875rem) · `--pebble-timeline-label-on-fill` (#fff) · `--pebble-timeline-label-on-light` (#0b0b0b, on slot 4) Defaults are the dataviz reference palette, light and dark steps picked by `prefers-color-scheme`. A page with its own theme toggle sets the `--pebble-chart-*` tokens for both of its themes. The raw sheet ships as `dist/timeline.css`. ## Inside - `chart/state.ts` is saison's chart reducer, lifted unchanged; `chart/scale.ts` generalises its `niceScale` to an axis that needn't start at 0. They are the library's chart core, and move out of this package when a second chart needs them (a package's types must stand alone). - Nothing is measured for layout: the plot is one CSS grid, segments are placed as fractions of their lane, the tooltip is an absolute grid item in the active lane's area, kept inside it by moving its own anchor, and the table view is an auto table in a scroll region. One thing is measured: whether a segment's label fits it. Each lane is a size container (`container-type: inline-size`) so that a label's `max-width` can be its segment's target width; the segment's own width stays a percentage, so a resize never animates. - The table view replaced three rounds of fitting the table into the element (a fixed layout, then a measured choice between whole words, hyphenated labels and a fixed layout). Each still broke words somewhere: Blink never hyphenates a capitalised English word, so a five-column English table with a long label fell to the fixed layout at 320 and 360px and broke words mid-word with no hyphen. A scroll region is the standard accessible pattern for a data table wider than its room, and it needs no measuring. - The move into the region waits a microtask, until `define()` has inserted what the element renders: `define()` keeps the host's children as it finds them at that moment, and removes the rest when the element disconnects, so a table moved earlier would be removed with them. - Lanes and segments are keyed lists (`For` with `key`: track name, then label), because `readTable` builds new objects on every read: keyed by reference, every re-read would redraw every segment, and nothing could transition. - `--pebble-timeline-start` and `--pebble-timeline-size` are registered with `@property` (`properties.css`: ``, `inherits: false`, initial value `0`). They are typed numbers: a value that isn't a number falls back to 0 rather than invalidating `left` and `width`, and a segment's children don't inherit them. A label reads its segment's target width through `--_target`, which the segment sets. `left` and `width` still transition rather than the properties themselves, because the label's cap must jump to the target at once. - **The registration is page-wide, hence the names.** `@property` is ignored inside `@scope`, and `define()` wraps the component's CSS string in `@scope (pebble-timeline)`. So the element passes the registrations as a separate `CSSStyleSheet` in `define`'s `styles` array, which `define()` adopts as it is, unscoped, into `document.adoptedStyleSheets`. As soon as the bundle loads, the two names are ``s that don't inherit everywhere on the page. They are in the element's own namespace so that a page's own properties keep their meaning (0.2.0's first cut registered `--start` and `--size`, which turned a page's `--size: 2rem` into 0): ```html
``` A page should not set `--pebble-timeline-start` or `--pebble-timeline-size` itself. - The edge shadow's `@keyframes pebble-timeline-edges` sits in the scoped sheet (Chromium accepts it inside `@scope`), but keyframe names are global: the name is prefixed for that. Size: 12,273 B gz whole bundle, 8,253 B over the floor (0.1.1: 11,054 and 7,034), over the ~6 kB a chart was meant to cost (pebble/library#2). The table fit's measuring and fallbacks are gone; the region's markup, the move and the longer property names cost about as much.