tobogganSe connecter

library

Prebuilt pebble components: drop-in custom elements, no compiler needed

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

Dernier runAucun
0Étoiles
0Forks
2Issues
253 lignes · 16458 octetsBrut · Historique

Timeline (<pebble-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 <table> 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.

<script type="module" src="vendor/pebble-library/timeline.js"></script>
<pebble-timeline min="-14" max="105" step="14" per="7" unit="wk" axis="Weeks from taking the cutting">
  <table>
    <caption>Two schedules</caption>
    <thead><tr><th>Method</th><th>Phase</th><th>Starts (day)</th><th>Days</th><th>Source</th></tr></thead>
    <tbody>
      <tr><th>Standard topping</th><td>Rooting</td><td>0</td><td>10</td><td>Fig.&nbsp;2</td></tr>
      <tr data-series="2"><th>Standard topping</th><td>Vegetative growth</td><td>10</td><td>14</td><td>Fig.&nbsp;2</td></tr>
      <tr data-series="2" data-texture="hatch"><th>Standard topping</th><td>Recovery</td><td>24</td><td>14</td><td>Fig.&nbsp;2</td></tr>
      <tr data-series="3"><th>Standard topping</th><td>Flowering</td><td>38</td><td>56</td><td>Fig.&nbsp;2</td></tr>
      <tr data-series="muted"><th>Early topping</th><td>Mother-plant wait</td><td>−14</td><td>14</td><td>Fig.&nbsp;2</td></tr>
      …
    </tbody>
  </table>
</pebble-timeline>

Without JS, or without a <table> child, the page shows the table and nothing else. Join a reference with a no-break space (Fig.&nbsp;2) so that no line ends between its parts.

The table

One body row per segment. Its cells, in order:

cellmeaning
1the track (consecutive or not: rows group by this text, in first-appearance order)
2the segment's label, shown on the bar when it fits, in the legend and the tooltip
3where it starts, in the table's unit
4how 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:

<div class="table-view" part="table-view" role="region" tabindex="0" aria-label="Two schedules">
  <table>…the page's table, the same node…</table>
</div>
  • 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 (&shy;); join what must stay together with a no-break space (Fig.&nbsp;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):

tableits narrowest (the region scrolls below it)at 280, 320, 360, 390 and 1280px
5 columns, English311pxscrolls at 280 and 320px, fits from 360px
5 columns, French326pxscrolls 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 columns722px (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

attributetypedefaultmeaning
min, maxnumberthe data's extent (and the baseline)the axis' ends, in the table's unit; set them to keep the axis still while rows change
stepnumbera round step, about 6the distance between ticks
pernumber1how many table units make one displayed unit (per="7": days in, weeks shown)
unitstringnoneappended to totals (wk, sem.)
axisstringnonethe axis title
baselinenumber0where totals are counted from; its gridline is darker
show-tablebooleanabsentalso show the table to sighted readers, in a scroll region under the plot (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

eventdetailwhen
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: <number>, 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 <number>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):

    <div style="--size: 2rem; width: var(--size)">  <!-- 32px, before and after the bundle loads -->
    

    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.