<!-- 04_VISUAL/xwui/xwui-lib/xwui-lib-super/src/charts/XWUITrendPlot/XWUITrendPlot.md -->
# XWUITrendPlot

Series over a time or numeric axis. Each series draws as a line, a dashed line, an area, a step, a moving forecast
dash or dots. The plot can add bands between two curves (forecast cone, short and over fills), reference lines with
tags (BAC, data date, a glowing "today" beam), a secondary scale and a faint dashed baseline per series. Three
layouts: `overlay` (one plot), `lanes` (one lane per series on a shared scale, the `parent` links drawn as a branch
tree) and `ridge` (overlapping offset rows, painted front to back). Sizes run from `micro` (a KPI card) to
`standard`. A keyboard and pointer scrub reads every series at a stop, and every drawing has a summary and a table
twin. Spec: plnx `REF_06_GAPS.md` 2.2, C09. It shares the tone and axis conventions of `XWUIBarPlot` (C08): token
names, never colour values; domains in data units; an LTR island for the axis.

## Basic Usage

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: Earned value S-curve: planned dashed, earned and a forecast with its cone, BAC and a today beam (PX-ProjectControl).
```

```example
file: examples/ScenarioLanes.ts
html: examples/ScenarioLanes.html
title: Scenario lanes
description: One lane per scenario on a shared scale, branches drawn from Base, low point and break-even markers, end values, a pending downside (PX-Scenarios).
```

```example
file: examples/DemandRidge.ts
html: examples/DemandRidge.html
title: Demand ridge
description: Overlapping day rows of staff needed per hour over the staffed steps, short hours filled (PX-Shifts).
```

```example
file: examples/KpiTrend.ts
html: examples/KpiTrend.html
title: KPI trend
description: A micro plot for a KPI card (Web-ForCorporate).
```

## Data

| Field | Shape | Notes |
| --- | --- | --- |
| `series[]` | `{ id, label, points: [x, y \| null][], style?, hue?, axis?, baseline?, parent?, endLabel?, ghost?, markers? }` | `style`: `line` (default), `dashed`, `area`, `step`, `forecast`, `dots`. A `null` y is a gap. A repeated id is suffixed `~n`. `axis: 'secondary'` reads the inline-end scale (overlay only). `parent` makes a branch (lanes). `ghost` draws a pending series faint and dashed. `markers[]`: `{ at, kind: 'low' \| 'cross' \| 'point' \| 'custom', label }` sit on the series' value at `at`. |
| `bands[]` | `{ id, upper: [x, y][], lower: [x, y][], meaning: 'cone' \| 'short' \| 'over', hue?, label?, seriesId? }` | `seriesId` puts the band in that lane or ridge row (ignored in overlay). |
| `refs[]` | `{ axis: 'x' \| 'y', at, label?, style?: 'solid' \| 'dashed' \| 'dotted' \| 'beam', hue? }` | `y`: a value line, tag at the end (neighbours alternate ends). `x`: a position line, tag above (a tag within 16 percent of the previous drops low inside the plot). `beam`: glowing "today". |
| `xTicks`, `yTicks`, `y2Ticks` | `{ at, label }[]` | Unset: round ticks formatted by `formatX` / `formatY` (standard size only). |
| `xDomain`, `yDomain`, `y2Domain` | `[min, max]` | Unset: the data extent; a value axis snaps to zero when zero is nearer than the spread. |
| `status` | `'ready' \| 'loading' \| 'error' \| 'stale'` | `loading` and `error` replace the plot; `stale` dims it and says so. |

Colours are token NAMES: an extended hue (`teal indigo purple sky fuchsia rose slate yellow`, declared in every
theme by `theme/viz-tokens.css`), a status tone (`ok info warn error neutral accent`), a health state, or a host
name (`--xwui-hue-<name>`). The nine core hues (`lime cyan violet ...`) exist only in xwflow-neon; a missing name
falls back to slate. Series without a hue take the default cycle `indigo teal yellow rose sky purple fuchsia slate`.

## Options (`conf_comp`)

| Option | Default | What it does |
| --- | --- | --- |
| `layout` | `'overlay'` | `'lanes'` or `'ridge'`. |
| `size` | `'standard'` | `'micro'`: no axes; legend and scrub off unless set. |
| `legend` | standard: `true` | Series buttons (overlay) plus baseline and band swatches. Swatches differ in shape (dash, dot, area, band outline), never colour alone. |
| `hover` | standard: `'scrub'` | `'none'` removes the scrub. |
| `height` | standard `'md'`, micro `'xs'` | Overlay plot height: `xs sm md lg xl`. |
| `laneHeight` | `'sm'` | Lane and ridge row height. |
| `ridgeOverlap` | `0.55` | Share of a row the next row overlaps (0 to 0.85); rows never come closer than two lines of tick text. |
| `selectedId` | none | Highlights one series (lanes: its ancestry too); the others dim. |
| `mirrorInRtl` | `false` | Off: the frame is a `dir="ltr"` island under Arabic (time reads left to right, primary axis on the left, secondary on the right, the lane tree beside the line starts). On: the whole plot mirrors. |
| `tableTwin` | `true` | The visually hidden table of every value. |
| `tickThinning` | `true` | x tick labels thin by container width (every other below 40rem, every fourth below 26rem). |
| `curve` | `'linear'` | `'smooth'`: a monotone cubic (never overshoots a peak or dips below a reached total). `step` series always step. |
| `unit`, `ariaLabel`, `emptyText`, `labels`, `locale`, `numberingSystem`, `className` | | Copy and number options. `labels` overrides `xwui.trend_plot.*` per key. Western digits unless `numberingSystem` says otherwise. |

## Events and methods

Events (logic `on(...)`, and DOM `CustomEvent`s on the host): `select { seriesId }`, `hover { x, values } | null`,
`scrub { x }`. Methods: `select(id)`, `getSelectedId()`, `scrubTo(x)` (rests on the nearest stop), `clearScrub()`,
`appendPoints(seriesId, points)` (redraws one series), `setStatus(status)`, `setFormatX(fn)`, `setFormatY(fn)`
(trusted host formatters for dates and money), `onSelect`, `onHover`, `onScrub`, `updateData`, `updateConfig`,
`getElement`, `destroy`. `XWUITrendPlot.projectView(data, config)` composes a still render into a parent tree.

## Accessibility and RTL

- The drawing is `role="img"` with a generated summary (series ranges, lows and highs, markers, references, bands);
  each lane and ridge row is its own `role="img"` with that series' sentence. The table twin carries every value.
- The scrub is a `role="slider"` over the plot: Left and Right (or Up and Down) step between the x values the
  series have, Page keys jump a tenth, Home and End go to the ends, Escape closes the readout. Its
  `aria-valuetext` reads every series at the stop; a polite region repeats it, throttled to one announcement per
  450 ms. A mirrored axis swaps Left and Right so the key follows the line it points at.
- Series controls (legend items, lane nodes, ridge labels) are buttons with `aria-pressed`, one roving tab stop,
  arrows in the page direction, Home and End; selection is also a border and weight change.
- Logical properties only; direction comes from the parent `dir`. Reduced motion stops the forecast dashes and the
  beam pulse in CSS and in JS (`--still`). Coarse pointers get 2.75rem controls; vertical swipes over the plot
  still scroll the page (`touch-action: pan-y`).
- Model text is always text (`dir="auto"` where it is user copy), never HTML.

```api
```