TimelineChart

Array of events to display on the timeline. The events, each with its machine time.

Container height in pixels. Width is always responsive.

Accessible name, description, data table and keyboard navigation. No announcements: it switches <Chart>'s interaction announcements, which this family does not make.

Alternate labels above/below the axis. Default: true.

The entrance: on, off, duration, easing and the entrance type (ADR-082, LAB-AT17).

Optional className applied to the outer container.

Categorical palette for this chart only: replaces the host palette (--chart-1 … --chart-10) in the chart's colour assignment, and nothing else. It is a data encoding, not a theme: surfaces, text, grid and semantic roles keep coming from the CSS token contract, and a series, datum or annotation that sets its own colour keeps it. Any CSS colour string (a public token reference such as var(--chart-3), hex, oklch).

The context menu. Opened on an event, the host's builder receives a typed TimelineElement (the event and its index) as context.target.element.

The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under <body>.

Left out, the chart inherits the direction of the page around it (the nearest dir attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from locale, and it never reverses an axis or reorders data: reversed stays an explicit axis choice. Under rtl the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction.

Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object ({languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}) carrying language and notation independently. dateShape is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central @workspace/active-format; the package never resolves tenant or application settings itself. When omitted, <ChartDefaults> supplies it; with neither, the chart throws a configuration error (no 'en' fallback, active-format D14). Object inputs must be referentially stable across renders.

The event markers' shape, from the one marker vocabulary of the package. Default: 'circle'. Every shape has the area of the circle of markerSize.

Marker radius in pixels. Default: 6.

The host translator for every text the chart shows or announces. When omitted, <ChartDefaults> supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028).

Without a time axis the events are placed in order, evenly. Place the events by time (T9): an event's x is its time on the events' extent, so a long gap is a long distance and equal times share one x; labels move to avoid each other, markers never. The keyboard, the data table and the announcement then read ascending time (equal times in the host's order); the CSV keeps the host's row order and adds the time column. An event without a readable time (an untyped call) puts the whole chart back on ordinal placement, with a development diagnostic.

Tooltip of the event under the pointer: enabled, renderer and style. The card shows text rows without a value, so no valueFormatter (ADR-082, LAB-AT17).

Optional fixed width in pixels. Default: fill container.

Fired when a chart animation completes.

• 'load': initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active).
• 'update': data-update transition finished.

Not triggered by zoom animations (use onZoomChange) or tooltip fades.

Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative ChartHandle calls.

Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (<ChartDefaults diagnostics>).

Fired exactly once per chart instance, after the first successful mount with valid dimensions and before any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests.

Distinct from onAnimationComplete with type: 'load', which fires *after* the load animation finishes. A chart with animation={false} still fires onReady — animation state has no effect on readiness.

A new React key on the host produces a new component instance and onReady fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance).

Consumer requirement — stable from first render. The latch closes on the first effect run regardless of whether onReady was defined at that moment. If onReady is initially undefined and later resolves to a function, the callback will never fire — the latch has already closed with a no-op. Pass a stable reference (typically via useCallback) or pass the final function unconditionally from the first render.