iryx-ui 0.11.0 → 0.12.0

package/README.md

@@ -252,7 +252,7 @@ Tweak a single instance with `class` (conflicts are merged smartly) or per-slot
 
 ```vue
 <IButton class="rounded-full">
-Pill button
+  Pill button
 </IButton>
 
 <ISwitch :ui="{ thumb: 'bg-zinc-900' }" />
@@ -262,7 +262,7 @@ Or drop all built-in styles and take over completely:
 
 ```vue
 <IButton unstyled class="my-own-button">
-Headless
+  Headless
 </IButton>
 ```
 
@@ -287,22 +287,19 @@ app.use(createIryxUi({ unstyled: true }))
 | --- | --- |
 | `IForm` | Validating form wrapper — any Standard Schema validator, or your own function |
 | `IFormField` | Label, description, hint, help and error text around a control |
+| `ILabel` | Field label with optional `required` asterisk |
 | `IInput` | Text field with `sm`/`md`/`lg` sizes, `invalid` state, `v-model`, `leading`/`trailing` slots, `clearable`, `loading`, `debounce` |
+| `ITextarea` | Multi-line field with matching sizes, `invalid` state and optional `autosize` |
 | `INumberInput` | Decimal-safe numeric field — the model is a **string**, with `min`/`max`/`step`, `precision` and locale-aware display |
-| `ISparkline` | Tiny inline trend chart — pure SVG, no charting dependency |
-| `IBarChart` | Categorical bar chart with a round-number axis, hover tooltip and a table view |
-| `ILineChart` | Line or area chart with a crosshair, hover marker and a table view |
+| `IPasswordInput` | Masked field with a show/hide toggle and an optional strength meter |
 | `IFileUpload` | Drag-and-drop file field with `accept` / `maxSize` / `maxFiles`, thumbnails and a remove action |
 | `IDatePicker` | Calendar in a popover; the model is an ISO `YYYY-MM-DD` **string** |
 | `IDateRangePicker` | Two-month range calendar; the model is `{ start, end }` ISO strings |
-| `IPasswordInput` | Masked field with a show/hide toggle and an optional strength meter |
-| `ITextarea` | Multi-line field with matching sizes, `invalid` state and optional `autosize` |
-| `ILabel` | Field label with optional `required` asterisk |
 | `ICheckbox` | Tri-state checkbox (`true` / `false` / `'indeterminate'`), optional `label` + `description` |
+| `ISwitch` | Accessible toggle, optional `label` + `description` |
+| `IRadioGroup` | Radio list with labels wired up automatically; items take a `description` |
 | `ISelect` | Listbox with keyboard nav and typeahead, driven by an `items` array, with optional groups |
 | `ICombobox` | Searchable select — filters as you type, with optional groups, virtualized rows and a "create from query" row |
-| `IRadioGroup` | Radio list with labels wired up automatically; items take a `description` |
-| `ISwitch` | Accessible toggle, optional `label` + `description` |
 
 **Actions**
 
@@ -312,6 +309,15 @@ app.use(createIryxUi({ unstyled: true }))
 | `IButtonGroup` | Joins any children into a segmented control — split buttons, toolbars, pagers |
 | `IDropdownMenu` | Menu driven by an `items` array, with separators, group labels, danger items and nested submenus |
 
+**Overlays**
+
+| Component | Description |
+| --- | --- |
+| `IDialog` | Modal with header/body/footer slots, `dismissible` and `showClose` |
+| `IDrawer` | Panel or sheet attached to any edge — swipe to dismiss, optional snap points |
+| `IConfirmDialog` | Host for `useConfirm()` — renders the promise-based confirmation |
+| `ITooltip` | Hover/focus tooltip with side, align, delay and optional arrow |
+
 **Feedback**
 
 | Component | Description |
@@ -320,14 +326,11 @@ app.use(createIryxUi({ unstyled: true }))
 | `IBanner` | Page-level announcement — full-bleed, six variants, sticky top or fixed bottom |
 | `IBadge` | Status pill — five variants × three sizes; `dot` moves the colour onto a leading dot |
 | `IToaster` | Host for `useToast()`; six viewport positions, stacking, action buttons |
-| `IDialog` | Modal with header/body/footer slots, `dismissible` and `showClose` |
-| `IConfirmDialog` | Host for `useConfirm()` — renders the promise-based confirmation |
 | `IProgress` | Determinate or `indeterminate` bar, five variants, `formatValue` |
 | `ISkeleton` | Loading placeholder — `text`/`rect`/`circle`, stackable with `lines` |
 | `IEmptyState` | Icon, title, description and an `actions` slot for empty lists |
-| `ITooltip` | Hover/focus tooltip with side, align, delay and optional arrow |
 
-**Navigation & data display**
+**Navigation**
 
 | Component | Description |
 | --- | --- |
@@ -335,8 +338,22 @@ app.use(createIryxUi({ unstyled: true }))
 | `IBreadcrumb` | Trail from an `items` array; the last crumb is marked as the current page |
 | `IPagination` | Page list with ellipsis, edge pages and prev/next controls; `align` places it, `size` sets the button scale |
 | `IStepper` | Multi-step progress, horizontal or vertical, optional `linear` ordering |
-| `IStat` | KPI tile — label, value, signed delta with trend colour, and a hint |
+
+**Data display**
+
+| Component | Description |
+| --- | --- |
 | `ITable` | Data table — sorting, selection, expansion and per-cell slots, client- or server-driven |
+| `IStat` | KPI tile — label, value, signed delta with trend colour, and a hint |
+
+**Charts** — pure SVG, no charting dependency; see [Charts](#charts)
+
+| Component | Description |
+| --- | --- |
+| `ISparkline` | Tiny inline trend line, sized to whatever box you put it in |
+| `IBarChart` | Bar chart — vertical or horizontal, grouped or stacked, with a round-number axis and a hover tooltip |
+| `ILineChart` | Line or area chart, single or multi-series, with a crosshair and hover marker |
+| `IChartLegend` | Standalone legend; shown automatically from two series up |
 
 Every component supports `unstyled` and a `class` override; multi-part ones take a `ui` prop for per-slot classes.
 
@@ -405,9 +422,47 @@ if (await confirm({ title: 'Delete this draft?', danger: true }))
 
 `confirm()` resolves `true` on confirmation and `false` on cancel or dismissal.
 
+### Drawers and sheets
+
+`IDrawer` is a panel attached to an edge of the viewport. It shares `IDialog`'s slots — `trigger`, `header` / `title` / `description`, the default body slot and `footer` (which receives `close`) — plus `dismissible`, `showClose` and `closeLabel`:
+
+```vue
+<IDrawer v-model:open="filtersOpen" title="Filters" description="Narrow the list down.">
+  <IInput v-model="search" placeholder="Reference or name" clearable />
+  <template #footer="{ close }">
+    <IButton variant="outline" @click="close()">
+      Reset
+    </IButton>
+    <IButton @click="close()">
+      Apply
+    </IButton>
+  </template>
+</IDrawer>
+```
+
+`side` picks the edge — `right` (default), `left`, `top` or `bottom` — and doubles as the direction you drag to dismiss. `size` means width on a `left`/`right` drawer and maximum height on a `top`/`bottom` sheet, so `sm`–`xl` and `full` read naturally either way. A sheet gets a drag handle by default and a side drawer does not; `handle` overrides that in both directions.
+
+Add `snapPoints` for a sheet that rests part-way. Points are fractions of the viewport (`0.45`), pixel numbers, or CSS lengths (`'20rem'`), and `v-model:snapPoint` reads or sets the current one:
+
+```vue
+<IDrawer
+  v-model:open="open"
+  v-model:snap-point="snap"
+  side="bottom"
+  :snap-points="[0.45, 1]"
+  title="Payment method"
+/>
+```
+
+Snap points position the panel by translating it rather than resizing it, so `size` stops capping the height when they are set — otherwise the fully expanded state would be clipped instead of parked below the fold.
+
+`modal` controls how much of the page the drawer takes over: `true` (default) traps focus and blocks everything behind it, `'trap-focus'` keeps the page interactive while still holding the Tab ring — what a persistent side panel wants — and `false` does neither.
+
+Dragging is real pointer work, so it only happens in a browser. The panel follows the finger, snaps back when the drag is too short, and dismisses when it is not; `dismissible: false` refuses the swipe along with Escape and the overlay, while the corner button still closes.
+
 ### Internationalisation
 
-No English string is baked in without an escape hatch. `IAlert`, `IDialog` and `IToaster` take a `closeLabel`, `IPagination` takes `prevLabel` / `nextLabel` / `label`, `IBreadcrumb` and `ISkeleton` take a `label`, and `IProgress` and `IStat` take `formatValue` / `formatDelta` for locale-aware numbers.
+No English string is baked in without an escape hatch. `IAlert`, `IDialog`, `IDrawer` and `IToaster` take a `closeLabel`, `IPagination` takes `prevLabel` / `nextLabel` / `label`, `IBreadcrumb` and `ISkeleton` take a `label`, and `IProgress` and `IStat` take `formatValue` / `formatDelta` for locale-aware numbers.
 
 ### Forms
 
@@ -483,577 +538,290 @@ chrome; use `ui` to reach the parts (`root`, `input`, `leading`, `trailing`,
 forwarded to the `<input>` itself. `ref` exposes the element as `.input` for
 focus management.
 
-#### Multiple series
-
-Both charts take plain rows plus a `series` descriptor — the same shape
-`ITable` uses. Omit `series` for the single-measure case.
+#### Files
 
 ```vue
-<IBarChart
-  :data="[
-    { label: 'Jan', revenue: 4200, expenses: 3100 },
-    { label: 'Feb', revenue: 5600, expenses: 3400 },
-  ]"
-  :series="[
-    { key: 'revenue', name: 'Revenue', slot: 0 },
-    { key: 'expenses', name: 'Expenses', slot: 1 },
-  ]"
-  label="Cashflow by month"
-/>
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const logo = ref<File[]>([])
+</script>
+
+<template>
+  <IFileUpload
+    v-model="logo"
+    accept="image/*"
+    :max-size="2 * 1024 * 1024"
+    label="Drag your logo here"
+    browse-label="Browse images"
+    hint="PNG, JPG or SVG up to 2 MB"
+    @reject="onReject"
+  />
+</template>
 ```
 
-Bars group inside their category; lines draw one path each. One hover reports
-**every** series for that category in a single tooltip, so the reader compares
-in one place instead of chasing marks.
+The model is **always a `File[]`**, even without `multiple` — a `File | File[]`
+union would make every caller narrow the type before touching it, and the
+single case is just an array holding at most one. Without `multiple`, picking
+again replaces rather than appends.
 
-**`slot` pins a series to a palette colour.** Without it, colour follows array
-position — so filtering a series out repaints the survivors and the reader has
-to relearn the chart. Pin the slots whenever series can be toggled.
+| Prop | Effect |
+| --- | --- |
+| `multiple` | Accept more than one file |
+| `accept` | Native syntax: `image/*`, `.pdf`, `image/png` |
+| `maxSize` | Largest accepted size, in bytes |
+| `maxFiles` | Cap on how many files may be held at once |
+| `label` | Prompt in the zone, above the hint |
+| `browseLabel` | Text on the browse button |
+| `hint` | Fine print under the prompt — the accepted types belong here |
 
-**The legend is mandatory from two series up.** `legend: false` only silences
-the single-series case, where the title already names what is plotted. Colour
-alone is never a dependable identity channel, so this is not configurable.
+Every string is a prop, including `removeLabel` and the three rejection
+messages, so nothing bakes in English.
 
-Past eight series the colours stop identifying anything; the chart warns in
-development and you should fold the tail into "Other" or switch to small
-multiples.
+`accept` is enforced in the component as well as on the input, because a
+dragged-in file bypasses the native filter entirely. Refused files raise
+`@reject` with `{ file, reason }` — `'type'`, `'size'` or `'count'` — so you
+can word your own message; the built-in text is available through the
+`tooLargeText`, `wrongTypeText` and `tooManyText` props.
 
-`variant="area"` is ignored for multiple series — overlapping washes muddy into
-a colour that belongs to neither.
+Image files get a thumbnail, anything else a placeholder of the same size so
+rows stay aligned. The object URLs behind those thumbnails are revoked as soon
+as a file leaves the list or the component unmounts.
 
-#### Annotations, and why there is no plugin API
+#### Dates
 
-Chart.js has plugins because canvas is opaque — once painted you cannot select
-or style anything, so the only way in is an imperative draw hook. SVG has no
-such problem, so these charts hand you the layout and let you write ordinary
-markup into it:
+The model is an ISO `YYYY-MM-DD` **string**, never a `Date`.
 
 ```vue
-<ILineChart :data="revenue" label="Revenue against target">
-  <template #overlay="{ plot, value }">
-    <line
-      :x1="plot.left" :y1="value(7000)"
-      :x2="plot.left + plot.width" :y2="value(7000)"
-      stroke="var(--iryx-warning)" stroke-width="2" stroke-dasharray="4 4"
-    />
-  </template>
-</ILineChart>
-```
+<script setup lang="ts">
+import { ref } from 'vue'
 
-`#underlay` renders behind the marks — target bands, shaded regions. `#overlay`
-renders in front — reference lines, callouts. Both sit below the hit targets,
-so hovering keeps working through whatever you draw.
+const issuedOn = ref<string | null>('2026-08-15')
+const period = ref({ start: '2026-08-01', end: '2026-08-31' })
+</script>
 
-Both receive the `CartesianLayout`:
+<template>
+  <IDatePicker v-model="issuedOn" clearable />
+  <IDateRangePicker v-model="period" clearable />
+</template>
+```
 
-| Prop | What it gives you |
-| --- | --- |
-| `plot` | `{ left, top, width, height }` of the plot rectangle, in px |
-| `value(n)` | A data value to its pixel on the value axis |
-| `bandCentre(i)` | The centre of category `i`, in px |
-| `bandWidth` | Size of one category slot |
-| `ticks` | The axis values actually drawn |
-| `orientation` | `'vertical'` or `'horizontal'` |
+A `Date` is a timestamp, so it always carries a time zone. `new Date('2026-08-15')`
+parses as UTC midnight, and a user west of Greenwich formatting it locally sees
+the 14th — which silently moves a record into the wrong reporting period. A
+calendar date has no zone, so it stays the day you picked. Internally the
+components use `@internationalized/date`; that never reaches your model, so
+formatting the string with `dayjs` or anything else on the way out is fine.
 
-That's strictly more capable than a draw hook: it's declarative, reactive, and
-type-checked, with no lifecycle or registration order to learn.
+| Prop | Effect |
+| --- | --- |
+| `min` / `max` | Selectable bounds, as ISO strings |
+| `locale` | Month names, weekday initials, and the trigger's text |
+| `format` | `Intl.DateTimeFormatOptions` for the trigger, e.g. `{ dateStyle: 'full' }` |
+| `weekStartsOn` | `0` is Sunday. Defaults to the locale's convention |
+| `clearable` | Adds a clear action to the footer |
+| `months` | Range picker only — months side by side, default `2` |
+| `separator` | Range picker only — text between the two dates |
 
-For a chart type that doesn't exist here, the same primitives are exported —
-`cartesianLayout`, `linearScale`, `niceTicks`, `seriesColor` — so you can build
-one on the same spine rather than starting over.
+Navigation and footer labels (`todayLabel`, `clearLabel`, `previousLabel`,
+`nextLabel`) are all props, so nothing bakes in English.
 
-#### Chart colours
+Both render their calendar at a fixed six weeks, so a short month cannot stretch
+its rows to match a taller neighbour and the popover does not resize as you page
+through it. The range picker draws only the committed range — the days between
+the endpoints take a flat tint while the two ends take the solid fill, so a long
+span still shows where it begins and ends.
 
-Eight categorical slots, `--iryx-chart-1` … `--iryx-chart-8`, usable as Tailwind
-colours (`text-chart-3`, `fill-chart-5`). They encode **identity** — which
-series a mark belongs to — never magnitude.
+The helpers behind them are exported, for formatting the same values elsewhere:
 
-```vue
-<!-- One series per slot, assigned in order. -->
-<ISparkline :data="revenue" class="text-chart-1" />
+```ts
+import { formatIsoDate, isoToday, toCalendarDate, toIsoDate } from 'iryx-ui'
 
-<ISparkline :data="expenses" class="text-chart-2" />
+formatIsoDate('2026-08-15', 'en-GB', { dateStyle: 'long' }) // '15 August 2026'
+formatIsoDate('nonsense') // '' — malformed input is "no selection", not a crash
 ```
 
-Three rules, and they are not stylistic:
-
-- **Assign in order, never cycle.** A ninth series is not a generated ninth
-  hue — fold it into "Other", or switch to small multiples. A generated colour
-  hasn't been checked for separation against its neighbours.
-- **Status colours are never series colours.** A series that happens to land in
-  slot 4 must not read as a warning. `success`/`warning`/`danger`/`info` stay
-  reserved.
-- **Colour follows the entity, not its rank.** If a filter removes a series,
-  the survivors keep their slots rather than shifting up.
+#### Passwords
 
-Tailwind scans source text, so a class name assembled at runtime is never
-generated — write the slots out, or reach for the variable:
+`IPasswordInput` is `IInput` with a reveal toggle in the trailing area, plus an
+optional four-segment strength meter.
 
 ```vue
-<!-- Silently unstyled: Tailwind never sees this string -->
-<ISparkline :class="`text-chart-${index + 1}`" />
+<IPasswordInput v-model="password" strength />
 
-<!-- Either of these works -->
-<ISparkline :class="['text-chart-1', 'text-chart-2'][index]" />
+<!-- Toggle only, no meter -->
+<IPasswordInput v-model="password" />
 
-<ISparkline :style="{ color: `var(--iryx-chart-${index + 1})` }" />
+<!-- No toggle either -->
+<IPasswordInput v-model="password" :toggle="false" />
 ```
 
-The steps are not eyeballed. Each clears a lightness band, a chroma floor, and
-protanopia/deuteranopia separation against its own surface, checked with a
-validator rather than by eye. **Dark has its own steps**, validated against the
-dark background — not an automatic flip of the light ones.
-
-Two caps worth knowing before you design around them:
-
-| Chart form | Max series |
-| --- | --- |
-| Bars, lines, stacks — only neighbours touch | **8** |
-| Scatter, bubble, small multiples — any two marks can sit side by side | **3** |
-
-Past those, the answer is fewer series or facets, not more colours. If you
-re-step any slot, re-run the validator for **both** modes.
+The score counts length (8 and 12 characters), mixed case, a digit and a
+symbol, capped at four. It is a deliberately transparent nudge toward better
+passwords, **not** a security control — enforce real policy in the `IForm`
+validator, where it can actually reject a value.
 
-#### Line charts
+Every string is overridable, since components must not bake in English:
 
 ```vue
-<ILineChart
-  :data="[
-    { label: 'Jan', value: 4200 },
-    { label: 'Feb', value: null },
-    { label: 'Mar', value: 5600 },
-  ]"
-  variant="area"
-  label="Revenue by month"
+<IPasswordInput
+  v-model="password"
+  strength
+  show-label="Afficher le mot de passe"
+  hide-label="Masquer le mot de passe"
+  :strength-labels="['Faible', 'Moyen', 'Bon', 'Fort']"
 />
 ```
 
-Same `data`, `height`, `ticks`, `axis`, `locale`, `format` and `label` props as
-`IBarChart`, plus:
+`class` lands on the wrapper that stacks the field above the meter; `ui` reaches
+`root`, `input`, `toggle`, `meter`, `track`, `segment` and `label`.
 
-| Prop | Effect |
-| --- | --- |
-| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
-| `zero` | Force zero onto the axis. **Off by default** |
+#### Autosizing textareas
 
-**`zero` is off here and always on for bars, deliberately.** A bar is read by
-length, so a truncated baseline lies about the comparison. A line is read by
-its *shape*, and a series hovering around 8,000 flattens into a straight edge
-once the axis starts at nothing. Turn it on when the distance from zero is the
-point.
+```vue
+<!-- Grows without limit -->
+<ITextarea v-model="note" autosize />
 
-`null` breaks the line rather than bridging it, so a missing reading never
-draws a slope that didn't happen.
+<!-- Between 2 and 8 rows, then scrolls -->
+<ITextarea v-model="note" :autosize="{ min: 2, max: 8 }" />
+```
 
-Hovering shows a crosshair and a single ringed marker on the reading under the
-cursor — not a dot on every point, which is noise the axis and tooltip already
-cover.
+`autosize` overrides `rows` and drops the drag handle, since the measured
+height is the point. The field shrinks as well as grows, and re-measures when
+the model changes from outside — a reset or a prefill resizes correctly.
 
-#### Bar charts
+`ISelect` and `IRadioGroup` accept plain strings or `{ label, value, disabled }` objects. Both also take a default slot if you'd rather compose the Reka primitives yourself.
+
+`ISelect` also takes groups — an entry with its own `items` becomes a labelled
+heading, the same shape `ICombobox` uses:
 
 ```vue
-<IBarChart
-  :data="[
-    { label: 'Jan', value: 4200 },
-    { label: 'Feb', value: 5600 },
-    { label: 'Mar', value: null },
+<ISelect
+  v-model="framework"
+  :items="[
+    { label: 'Virtual DOM', items: ['Vue', 'React'] },
+    { label: 'Compiled', items: [{ label: 'Svelte', value: 'svelte' }] },
   ]"
-  label="Revenue by month"
-  locale="de-DE"
-  :format="{ style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }"
 />
 ```
 
-| Prop | Effect |
-| --- | --- |
-| `data` | `{ label, value }[]`. `value: null` is a **missing reading** — no bar, which is not a zero |
-| `height` | Rendered height in px (default 240). Width fills the container |
-| `ticks` | Target tick count. A hint — the axis lands on round numbers first |
-| `axis` | Set `false` to drop the value axis and gridlines |
-| `locale` / `format` | `Intl.NumberFormat` settings, applied to ticks and tooltip alike |
-| `label` | Accessible name for the figure |
-
-**The axis picks the domain, not the data.** Values are snapped outwards to a
-1/2/5 step, so an axis reads `0 / 2,000 / 4,000` rather than `0 / 1,726.8`.
-Zero is always included, because bars are compared by length and a truncated
-baseline makes that comparison a lie.
-
-Bars are capped at 24px and never fill their slot — the gap between them is
-what separates them. They're rounded at the data end and square at the
-baseline, so the rounding reads as the tip of the value.
-
-Hovering a bar dims the rest and shows a tooltip; hit targets span the full
-band and plot height, so a short bar is no harder to hit than a tall one.
-
-**Accessibility:** the SVG is `aria-hidden` and the data is exposed as a
-visually-hidden table instead, so a screen reader gets the actual numbers
-rather than a blank graphic. That table renders even before the container has
-been measured — the data is never gated behind layout.
+### Searchable selects
 
-**`stacked`** turns grouped series into one bar per category:
+`ICombobox` takes the same `items` as `ISelect` and filters them against what
+the user types, which is what you want once a list runs to hundreds of entries.
+The field shows the selected option's **label** while the model holds its value.
 
 ```vue
-<IBarChart :data="cashflow" :series="series" stacked label="Cashflow" />
+<ICombobox
+  v-model="clientId"
+  :items="clients"
+  placeholder="Search clients"
+  empty-text="No clients found."
+/>
 ```
 
-Stacking answers *"what makes up the total"*; grouping answers *"how do these
-compare"*. Only the bottom segment shares a baseline, so segments above it are
-hard to compare across categories — stay with grouped bars when the comparison
-matters more than the total.
-
-The axis is sized against the running totals, only the outermost segment is
-rounded, and the tooltip adds a **Total** row (`totalLabel` to rename it).
-Negative values stack downward from zero rather than cancelling positives out,
-so a mixed stack shows both sides at full length. Stacking is ignored for a
-single series, and works horizontally too.
-
-**`orientation="horizontal"`** runs the categories down the side:
+Set `create` to offer a row for whatever the user typed when nothing matches.
+Choosing it emits `create` with the query and does **not** change the model —
+the option doesn't exist yet, so you add it and select it yourself:
 
 ```vue
-<IBarChart :data="spend" orientation="horizontal" label="Spend by category" />
+<ICombobox
+  v-model="clientId"
+  :items="clients"
+  create
+  :create-label="query => `Add ${query}`"
+  @create="query => clients.push({ label: query, value: addClient(query) })"
+/>
 ```
 
-Vertical charts thin colliding labels to every *n*th, which is fine for `Jan`
-/ `Feb` and lossy for `Travel and accommodation`. Turn the chart and the names
-get real width, so nothing is dropped — that's the case horizontal is for.
-Everything else behaves the same: grouped series, the tooltip, the round-number
-axis anchored at zero.
-
-#### Sparklines
+Both `empty-text` and `create-label` are props precisely so a non-English app
+never inherits an English string; `empty` and `create` slots take over the
+markup entirely if you need more than text.
 
-A trend at a glance, for a stat tile or a table cell. Plain SVG — no charting
-library, no canvas, nothing to install.
+An entry with its own `items` becomes a labelled group. A group disappears on
+its own once nothing inside it matches:
 
 ```vue
-<ISparkline
-  :data="[4200, 4600, 4100, 5200, 5800, 6300]"
-  variant="area"
-  end-dot
-  label="Revenue over six months, trending up"
+<ICombobox
+  v-model="clientId"
+  :items="[
+    { label: 'Recent', items: ['Acme Industries', 'Bolt Logistics'] },
+    { label: 'Archived', items: [{ label: 'Cirrus Systems', value: 'cirrus' }] },
+  ]"
 />
 ```
 
-Because it is SVG, colour comes from `currentColor`: recolour it with a text
-utility, and it follows your theme preset and light/dark automatically with no
-JavaScript. A canvas chart cannot read CSS variables, so it would need a
-re-render on every theme change.
-
-| Prop | Effect |
-| --- | --- |
-| `data` | Values, oldest first. `null` is a **gap**, not a zero — the line breaks |
-| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
-| `endDot` | Marks the most recent point |
-| `baseline` | Lower edge of the `area` wash: `min` (default) or `zero` |
-| `min` / `max` | Pin the domain — set both to put several sparklines on one scale |
-| `muted` | Draw in muted ink, for a de-emphasised trend |
-| `height` | Rendered height in px (default 32). Width always fills the container |
-
-Width is fluid and the stroke never distorts: the drawing stretches via
-`preserveAspectRatio="none"`, while every stroke carries
-`vector-effect="non-scaling-stroke"`, so a 2px line stays 2px and the end dot
-stays circular at any aspect ratio.
-
-`label` sets an accessible description. **Without one the sparkline is hidden
-from assistive tech as decorative** — which is correct when it sits beside a
-value that already states the number, and wrong if it is the only thing
-carrying the information.
-
-Edge cases behave: an empty series draws nothing, a flat series draws through
-the middle rather than collapsing to an edge, and a single reading is a dot.
+For lists in the thousands, `virtual` renders only the rows on screen:
 
-The scale helpers are exported for building your own marks:
+```vue
+<ICombobox v-model="sku" virtual :items="fiveThousandItems" :estimate-size="32" />
+```
 
-```ts
-import { extent, linearScale } from 'iryx-ui'
+`virtual` and grouped items are **mutually exclusive** — the underlying
+virtualizer is a flat window with no notion of group headings, so groups are
+flattened and their labels dropped (with a warning in dev). `estimate-size` is
+the assumed row height in px, used to size the scrollbar before rows are
+measured; set it if you have restyled rows to a different height.
 
-extent([3, null, 9, 1]) // [1, 9] — gaps ignored
-linearScale([0, 10], [100, 0])(10) // 0 — ranges may be inverted for SVG's y-axis
-```
+### Numbers and money
 
-#### Files
+`INumberInput` never turns your value into a `number`. The model is a decimal
+**string**, because binary floating point cannot represent decimal money —
+`0.1 + 0.2` is `0.30000000000000004`, and `10.00` becomes `10`. Values are
+added, compared and rounded with `BigInt` internally, so precision survives
+regardless of magnitude.
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
 
-const logo = ref<File[]>([])
+// A string, and it stays one.
+const amount = ref('1234.56')
 </script>
 
 <template>
-  <IFileUpload
-    v-model="logo"
-    accept="image/*"
-    :max-size="2 * 1024 * 1024"
-    label="Drag your logo here"
-    browse-label="Browse images"
-    hint="PNG, JPG or SVG up to 2 MB"
-    @reject="onReject"
-  />
+  <INumberInput v-model="amount" locale="sl" :precision="2" step="0.01" min="0" />
 </template>
 ```
 
-The model is **always a `File[]`**, even without `multiple` — a `File | File[]`
-union would make every caller narrow the type before touching it, and the
-single case is just an array holding at most one. Without `multiple`, picking
-again replaces rather than appends.
+`locale` affects the **display only** — `sl` shows `1.234,56` while the model
+stays `"1234.56"`. Typing in the locale's own format works too. While the field
+is focused it shows the canonical value so separators can't fight your typing.
 
-| Prop | Effect |
-| --- | --- |
-| `multiple` | Accept more than one file |
-| `accept` | Native syntax: `image/*`, `.pdf`, `image/png` |
-| `maxSize` | Largest accepted size, in bytes |
-| `maxFiles` | Cap on how many files may be held at once |
-| `label` | Prompt in the zone, above the hint |
-| `browseLabel` | Text on the browse button |
-| `hint` | Fine print under the prompt — the accepted types belong here |
+`precision` fixes the number of decimal places, rounding half-up, and preserves
+trailing zeros (`"10.00"` stays `"10.00"`). `min`, `max` and `step` are decimal
+strings as well, and stepping is exact: `0.1 + 0.2` gives `"0.3"`.
 
-Every string is a prop, including `removeLabel` and the three rejection
-messages, so nothing bakes in English.
+The underlying helpers are exported if you need them elsewhere:
 
-`accept` is enforced in the component as well as on the input, because a
-dragged-in file bypasses the native filter entirely. Refused files raise
-`@reject` with `{ file, reason }` — `'type'`, `'size'` or `'count'` — so you
-can word your own message; the built-in text is available through the
-`tooLargeText`, `wrongTypeText` and `tooManyText` props.
+```ts
+import { addDecimals, compareDecimals, roundDecimal } from 'iryx-ui'
 
-Image files get a thumbnail, anything else a placeholder of the same size so
-rows stay aligned. The object URLs behind those thumbnails are revoked as soon
-as a file leaves the list or the component unmounts.
+addDecimals('0.1', '0.2') // '0.3'
+roundDecimal('1.005', 2) // '1.01'
+compareDecimals('1.10', '1.1') // 0
+```
 
-#### Dates
+### Validated forms
 
-The model is an ISO `YYYY-MM-DD` **string**, never a `Date`.
+`IForm` handles client-side validation. It accepts any [Standard Schema](https://standardschema.dev) validator — Zod 3.24+, Valibot, ArkType — so Iryx doesn't depend on a validation library. Wrap each control in an `IFormField` with a `name` matching the schema path and errors wire themselves up.
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
+import { reactive } from 'vue'
+import * as z from 'zod'
 
-const issuedOn = ref<string | null>('2026-08-15')
-const period = ref({ start: '2026-08-01', end: '2026-08-31' })
-</script>
+const schema = z.object({
+  email: z.string().email('That doesn\'t look like an email'),
+  password: z.string().min(8, 'Use at least 8 characters'),
+})
 
-<template>
-  <IDatePicker v-model="issuedOn" clearable />
-  <IDateRangePicker v-model="period" clearable />
-</template>
-```
+const state = reactive({ email: '', password: '' })
 
-A `Date` is a timestamp, so it always carries a time zone. `new Date('2026-08-15')`
-parses as UTC midnight, and a user west of Greenwich formatting it locally sees
-the 14th — which silently moves a record into the wrong reporting period. A
-calendar date has no zone, so it stays the day you picked. Internally the
-components use `@internationalized/date`; that never reaches your model, so
-formatting the string with `dayjs` or anything else on the way out is fine.
-
-| Prop | Effect |
-| --- | --- |
-| `min` / `max` | Selectable bounds, as ISO strings |
-| `locale` | Month names, weekday initials, and the trigger's text |
-| `format` | `Intl.DateTimeFormatOptions` for the trigger, e.g. `{ dateStyle: 'full' }` |
-| `weekStartsOn` | `0` is Sunday. Defaults to the locale's convention |
-| `clearable` | Adds a clear action to the footer |
-| `months` | Range picker only — months side by side, default `2` |
-| `separator` | Range picker only — text between the two dates |
-
-Navigation and footer labels (`todayLabel`, `clearLabel`, `previousLabel`,
-`nextLabel`) are all props, so nothing bakes in English.
-
-Both render their calendar at a fixed six weeks, so a short month cannot stretch
-its rows to match a taller neighbour and the popover does not resize as you page
-through it. The range picker draws only the committed range — the days between
-the endpoints take a flat tint while the two ends take the solid fill, so a long
-span still shows where it begins and ends.
-
-The helpers behind them are exported, for formatting the same values elsewhere:
-
-```ts
-import { formatIsoDate, isoToday, toCalendarDate, toIsoDate } from 'iryx-ui'
-
-formatIsoDate('2026-08-15', 'en-GB', { dateStyle: 'long' }) // '15 August 2026'
-formatIsoDate('nonsense') // '' — malformed input is "no selection", not a crash
-```
-
-#### Passwords
-
-`IPasswordInput` is `IInput` with a reveal toggle in the trailing area, plus an
-optional four-segment strength meter.
-
-```vue
-<IPasswordInput v-model="password" strength />
-
-<!-- Toggle only, no meter -->
-<IPasswordInput v-model="password" />
-
-<!-- No toggle either -->
-<IPasswordInput v-model="password" :toggle="false" />
-```
-
-The score counts length (8 and 12 characters), mixed case, a digit and a
-symbol, capped at four. It is a deliberately transparent nudge toward better
-passwords, **not** a security control — enforce real policy in the `IForm`
-validator, where it can actually reject a value.
-
-Every string is overridable, since components must not bake in English:
-
-```vue
-<IPasswordInput
-  v-model="password"
-  strength
-  show-label="Afficher le mot de passe"
-  hide-label="Masquer le mot de passe"
-  :strength-labels="['Faible', 'Moyen', 'Bon', 'Fort']"
-/>
-```
-
-`class` lands on the wrapper that stacks the field above the meter; `ui` reaches
-`root`, `input`, `toggle`, `meter`, `track`, `segment` and `label`.
-
-#### Autosizing textareas
-
-```vue
-<!-- Grows without limit -->
-<ITextarea v-model="note" autosize />
-
-<!-- Between 2 and 8 rows, then scrolls -->
-<ITextarea v-model="note" :autosize="{ min: 2, max: 8 }" />
-```
-
-`autosize` overrides `rows` and drops the drag handle, since the measured
-height is the point. The field shrinks as well as grows, and re-measures when
-the model changes from outside — a reset or a prefill resizes correctly.
-
-`ISelect` and `IRadioGroup` accept plain strings or `{ label, value, disabled }` objects. Both also take a default slot if you'd rather compose the Reka primitives yourself.
-
-`ISelect` also takes groups — an entry with its own `items` becomes a labelled
-heading, the same shape `ICombobox` uses:
-
-```vue
-<ISelect
-  v-model="framework"
-  :items="[
-    { label: 'Virtual DOM', items: ['Vue', 'React'] },
-    { label: 'Compiled', items: [{ label: 'Svelte', value: 'svelte' }] },
-  ]"
-/>
-```
-
-### Searchable selects
-
-`ICombobox` takes the same `items` as `ISelect` and filters them against what
-the user types, which is what you want once a list runs to hundreds of entries.
-The field shows the selected option's **label** while the model holds its value.
-
-```vue
-<ICombobox
-  v-model="clientId"
-  :items="clients"
-  placeholder="Search clients"
-  empty-text="No clients found."
-/>
-```
-
-Set `create` to offer a row for whatever the user typed when nothing matches.
-Choosing it emits `create` with the query and does **not** change the model —
-the option doesn't exist yet, so you add it and select it yourself:
-
-```vue
-<ICombobox
-  v-model="clientId"
-  :items="clients"
-  create
-  :create-label="query => `Add ${query}`"
-  @create="query => clients.push({ label: query, value: addClient(query) })"
-/>
-```
-
-Both `empty-text` and `create-label` are props precisely so a non-English app
-never inherits an English string; `empty` and `create` slots take over the
-markup entirely if you need more than text.
-
-An entry with its own `items` becomes a labelled group. A group disappears on
-its own once nothing inside it matches:
-
-```vue
-<ICombobox
-  v-model="clientId"
-  :items="[
-    { label: 'Recent', items: ['Acme Industries', 'Bolt Logistics'] },
-    { label: 'Archived', items: [{ label: 'Cirrus Systems', value: 'cirrus' }] },
-  ]"
-/>
-```
-
-For lists in the thousands, `virtual` renders only the rows on screen:
-
-```vue
-<ICombobox v-model="sku" virtual :items="fiveThousandItems" :estimate-size="32" />
-```
-
-`virtual` and grouped items are **mutually exclusive** — the underlying
-virtualizer is a flat window with no notion of group headings, so groups are
-flattened and their labels dropped (with a warning in dev). `estimate-size` is
-the assumed row height in px, used to size the scrollbar before rows are
-measured; set it if you have restyled rows to a different height.
-
-### Numbers and money
-
-`INumberInput` never turns your value into a `number`. The model is a decimal
-**string**, because binary floating point cannot represent decimal money —
-`0.1 + 0.2` is `0.30000000000000004`, and `10.00` becomes `10`. Values are
-added, compared and rounded with `BigInt` internally, so precision survives
-regardless of magnitude.
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-
-// A string, and it stays one.
-const amount = ref('1234.56')
-</script>
-
-<template>
-  <INumberInput v-model="amount" locale="sl" :precision="2" step="0.01" min="0" />
-</template>
-```
-
-`locale` affects the **display only** — `sl` shows `1.234,56` while the model
-stays `"1234.56"`. Typing in the locale's own format works too. While the field
-is focused it shows the canonical value so separators can't fight your typing.
-
-`precision` fixes the number of decimal places, rounding half-up, and preserves
-trailing zeros (`"10.00"` stays `"10.00"`). `min`, `max` and `step` are decimal
-strings as well, and stepping is exact: `0.1 + 0.2` gives `"0.3"`.
-
-The underlying helpers are exported if you need them elsewhere:
-
-```ts
-import { addDecimals, compareDecimals, roundDecimal } from 'iryx-ui'
-
-addDecimals('0.1', '0.2') // '0.3'
-roundDecimal('1.005', 2) // '1.01'
-compareDecimals('1.10', '1.1') // 0
-```
-
-### Validated forms
-
-`IForm` handles client-side validation. It accepts any [Standard Schema](https://standardschema.dev) validator — Zod 3.24+, Valibot, ArkType — so Iryx doesn't depend on a validation library. Wrap each control in an `IFormField` with a `name` matching the schema path and errors wire themselves up.
-
-```vue
-<script setup lang="ts">
-import { reactive } from 'vue'
-import * as z from 'zod'
-
-const schema = z.object({
-  email: z.string().email('That doesn\'t look like an email'),
-  password: z.string().min(8, 'Use at least 8 characters'),
-})
-
-const state = reactive({ email: '', password: '' })
-
-function onSubmit(event) {
-  console.log(event.data) // only fires when valid
-}
-</script>
+function onSubmit(event) {
+  console.log(event.data) // only fires when valid
+}
+</script>
 
 <template>
   <IForm :state="state" :schema="schema" @submit="onSubmit">
@@ -1115,6 +883,20 @@ The control inside a field automatically inherits its `id`, invalid styling and
 
 Use the `#label` / `#description` slots instead of the props when you need markup (a link, a badge) inside the text.
 
+Where a component has no visible label — a search field, a bare select — put `aria-label` on it directly. Attributes always land on the control the label belongs to, not on whatever wrapper the component happens to render around it:
+
+```vue
+<template>
+  <IInput v-model="q" aria-label="Search invoices" />
+  <ISelect v-model="status" :items="statuses" aria-label="Filter by status" />
+  <INumberInput v-model="amount" aria-label="Amount" />
+</template>
+```
+
+The same holds for `name`, `autocomplete`, `maxlength` and `data-*`. `IProgress` is the one that needs saying twice: its `label` prop renders visible text *and* names the bar for assistive tech, so pass `aria-label` only when there is no visible label to use.
+
+An automated axe sweep runs over every component on each commit. It is a floor rather than a guarantee — it catches roughly a third of real barriers, and contrast rules need a real browser — but nothing ships with an unlabelled control or a nested interactive element.
+
 ### Alerts and banners
 
 They look similar and do different jobs, so they're separate components.
@@ -1297,6 +1079,304 @@ const table = useDataTable({
 // table.pageRows, table.toggleSort, table.headerSelection, …
 ```
 
+### Charts
+
+A small set of chart types done properly, in plain SVG — no charting
+dependency, nothing to register, and no canvas. They inherit the theme the
+same way every other component does, so they follow light/dark and any token
+override for free. For the exotic five percent, reach for Chart.js; that is
+the intended escape hatch, not a gap.
+
+Every chart is `aria-hidden` with a screen-reader table carrying the numbers,
+and that table renders before measurement — the data is never gated behind
+layout.
+
+#### Sparklines
+
+A trend at a glance, for a stat tile or a table cell.
+
+```vue
+<ISparkline
+  :data="[4200, 4600, 4100, 5200, 5800, 6300]"
+  variant="area"
+  end-dot
+  label="Revenue over six months, trending up"
+/>
+```
+
+Because it is SVG, colour comes from `currentColor`: recolour it with a text
+utility, and it follows your theme preset and light/dark automatically with no
+JavaScript. A canvas chart cannot read CSS variables, so it would need a
+re-render on every theme change.
+
+| Prop | Effect |
+| --- | --- |
+| `data` | Values, oldest first. `null` is a **gap**, not a zero — the line breaks |
+| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
+| `endDot` | Marks the most recent point |
+| `baseline` | Lower edge of the `area` wash: `min` (default) or `zero` |
+| `min` / `max` | Pin the domain — set both to put several sparklines on one scale |
+| `muted` | Draw in muted ink, for a de-emphasised trend |
+| `height` | Rendered height in px (default 32). Width always fills the container |
+
+Width is fluid and the stroke never distorts: the drawing stretches via
+`preserveAspectRatio="none"`, while every stroke carries
+`vector-effect="non-scaling-stroke"`, so a 2px line stays 2px and the end dot
+stays circular at any aspect ratio.
+
+`label` sets an accessible description. **Without one the sparkline is hidden
+from assistive tech as decorative** — which is correct when it sits beside a
+value that already states the number, and wrong if it is the only thing
+carrying the information.
+
+Edge cases behave: an empty series draws nothing, a flat series draws through
+the middle rather than collapsing to an edge, and a single reading is a dot.
+
+The scale helpers are exported for building your own marks:
+
+```ts
+import { extent, linearScale } from 'iryx-ui'
+
+extent([3, null, 9, 1]) // [1, 9] — gaps ignored
+linearScale([0, 10], [100, 0])(10) // 0 — ranges may be inverted for SVG's y-axis
+```
+
+#### Line charts
+
+```vue
+<ILineChart
+  :data="[
+    { label: 'Jan', value: 4200 },
+    { label: 'Feb', value: null },
+    { label: 'Mar', value: 5600 },
+  ]"
+  variant="area"
+  label="Revenue by month"
+/>
+```
+
+Same `data`, `height`, `ticks`, `axis`, `locale`, `format` and `label` props as
+`IBarChart`, plus:
+
+| Prop | Effect |
+| --- | --- |
+| `variant` | `line` (default) or `area`, which adds a wash beneath the line |
+| `zero` | Force zero onto the axis. **Off by default** |
+
+**`zero` is off here and always on for bars, deliberately.** A bar is read by
+length, so a truncated baseline lies about the comparison. A line is read by
+its *shape*, and a series hovering around 8,000 flattens into a straight edge
+once the axis starts at nothing. Turn it on when the distance from zero is the
+point.
+
+`null` breaks the line rather than bridging it, so a missing reading never
+draws a slope that didn't happen.
+
+Hovering shows a crosshair and a single ringed marker on the reading under the
+cursor — not a dot on every point, which is noise the axis and tooltip already
+cover.
+
+#### Bar charts
+
+```vue
+<IBarChart
+  :data="[
+    { label: 'Jan', value: 4200 },
+    { label: 'Feb', value: 5600 },
+    { label: 'Mar', value: null },
+  ]"
+  label="Revenue by month"
+  locale="de-DE"
+  :format="{ style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }"
+/>
+```
+
+| Prop | Effect |
+| --- | --- |
+| `data` | `{ label, value }[]`. `value: null` is a **missing reading** — no bar, which is not a zero |
+| `height` | Rendered height in px (default 240). Width fills the container |
+| `ticks` | Target tick count. A hint — the axis lands on round numbers first |
+| `axis` | Set `false` to drop the value axis and gridlines |
+| `locale` / `format` | `Intl.NumberFormat` settings, applied to ticks and tooltip alike |
+| `label` | Accessible name for the figure |
+
+**The axis picks the domain, not the data.** Values are snapped outwards to a
+1/2/5 step, so an axis reads `0 / 2,000 / 4,000` rather than `0 / 1,726.8`.
+Zero is always included, because bars are compared by length and a truncated
+baseline makes that comparison a lie.
+
+Bars are capped at 24px and never fill their slot — the gap between them is
+what separates them. They're rounded at the data end and square at the
+baseline, so the rounding reads as the tip of the value.
+
+Hovering a bar dims the rest and shows a tooltip; hit targets span the full
+band and plot height, so a short bar is no harder to hit than a tall one.
+
+**Accessibility:** the SVG is `aria-hidden` and the data is exposed as a
+visually-hidden table instead, so a screen reader gets the actual numbers
+rather than a blank graphic. That table renders even before the container has
+been measured — the data is never gated behind layout.
+
+**`stacked`** turns grouped series into one bar per category:
+
+```vue
+<IBarChart :data="cashflow" :series="series" stacked label="Cashflow" />
+```
+
+Stacking answers *"what makes up the total"*; grouping answers *"how do these
+compare"*. Only the bottom segment shares a baseline, so segments above it are
+hard to compare across categories — stay with grouped bars when the comparison
+matters more than the total.
+
+The axis is sized against the running totals, only the outermost segment is
+rounded, and the tooltip adds a **Total** row (`totalLabel` to rename it).
+Negative values stack downward from zero rather than cancelling positives out,
+so a mixed stack shows both sides at full length. Stacking is ignored for a
+single series, and works horizontally too.
+
+**`orientation="horizontal"`** runs the categories down the side:
+
+```vue
+<IBarChart :data="spend" orientation="horizontal" label="Spend by category" />
+```
+
+Vertical charts thin colliding labels to every *n*th, which is fine for `Jan`
+/ `Feb` and lossy for `Travel and accommodation`. Turn the chart and the names
+get real width, so nothing is dropped — that's the case horizontal is for.
+Everything else behaves the same: grouped series, the tooltip, the round-number
+axis anchored at zero.
+
+#### Multiple series
+
+Both charts take plain rows plus a `series` descriptor — the same shape
+`ITable` uses. Omit `series` for the single-measure case.
+
+```vue
+<IBarChart
+  :data="[
+    { label: 'Jan', revenue: 4200, expenses: 3100 },
+    { label: 'Feb', revenue: 5600, expenses: 3400 },
+  ]"
+  :series="[
+    { key: 'revenue', name: 'Revenue', slot: 0 },
+    { key: 'expenses', name: 'Expenses', slot: 1 },
+  ]"
+  label="Cashflow by month"
+/>
+```
+
+Bars group inside their category; lines draw one path each. One hover reports
+**every** series for that category in a single tooltip, so the reader compares
+in one place instead of chasing marks.
+
+**`slot` pins a series to a palette colour.** Without it, colour follows array
+position — so filtering a series out repaints the survivors and the reader has
+to relearn the chart. Pin the slots whenever series can be toggled.
+
+**The legend is mandatory from two series up.** `legend: false` only silences
+the single-series case, where the title already names what is plotted. Colour
+alone is never a dependable identity channel, so this is not configurable.
+
+Past eight series the colours stop identifying anything; the chart warns in
+development and you should fold the tail into "Other" or switch to small
+multiples.
+
+`variant="area"` is ignored for multiple series — overlapping washes muddy into
+a colour that belongs to neither.
+
+#### Chart colours
+
+Eight categorical slots, `--iryx-chart-1` … `--iryx-chart-8`, usable as Tailwind
+colours (`text-chart-3`, `fill-chart-5`). They encode **identity** — which
+series a mark belongs to — never magnitude.
+
+```vue
+<!-- One series per slot, assigned in order. -->
+<ISparkline :data="revenue" class="text-chart-1" />
+
+<ISparkline :data="expenses" class="text-chart-2" />
+```
+
+Three rules, and they are not stylistic:
+
+- **Assign in order, never cycle.** A ninth series is not a generated ninth
+  hue — fold it into "Other", or switch to small multiples. A generated colour
+  hasn't been checked for separation against its neighbours.
+- **Status colours are never series colours.** A series that happens to land in
+  slot 4 must not read as a warning. `success`/`warning`/`danger`/`info` stay
+  reserved.
+- **Colour follows the entity, not its rank.** If a filter removes a series,
+  the survivors keep their slots rather than shifting up.
+
+Tailwind scans source text, so a class name assembled at runtime is never
+generated — write the slots out, or reach for the variable:
+
+```vue
+<!-- Silently unstyled: Tailwind never sees this string -->
+<ISparkline :class="`text-chart-${index + 1}`" />
+
+<!-- Either of these works -->
+<ISparkline :class="['text-chart-1', 'text-chart-2'][index]" />
+
+<ISparkline :style="{ color: `var(--iryx-chart-${index + 1})` }" />
+```
+
+The steps are not eyeballed. Each clears a lightness band, a chroma floor, and
+protanopia/deuteranopia separation against its own surface, checked with a
+validator rather than by eye. **Dark has its own steps**, validated against the
+dark background — not an automatic flip of the light ones.
+
+Two caps worth knowing before you design around them:
+
+| Chart form | Max series |
+| --- | --- |
+| Bars, lines, stacks — only neighbours touch | **8** |
+| Scatter, bubble, small multiples — any two marks can sit side by side | **3** |
+
+Past those, the answer is fewer series or facets, not more colours. If you
+re-step any slot, re-run the validator for **both** modes.
+
+#### Annotations, and why there is no plugin API
+
+Chart.js has plugins because canvas is opaque — once painted you cannot select
+or style anything, so the only way in is an imperative draw hook. SVG has no
+such problem, so these charts hand you the layout and let you write ordinary
+markup into it:
+
+```vue
+<ILineChart :data="revenue" label="Revenue against target">
+  <template #overlay="{ plot, value }">
+    <line
+      :x1="plot.left" :y1="value(7000)"
+      :x2="plot.left + plot.width" :y2="value(7000)"
+      stroke="var(--iryx-warning)" stroke-width="2" stroke-dasharray="4 4"
+    />
+  </template>
+</ILineChart>
+```
+
+`#underlay` renders behind the marks — target bands, shaded regions. `#overlay`
+renders in front — reference lines, callouts. Both sit below the hit targets,
+so hovering keeps working through whatever you draw.
+
+Both receive the `CartesianLayout`:
+
+| Prop | What it gives you |
+| --- | --- |
+| `plot` | `{ left, top, width, height }` of the plot rectangle, in px |
+| `value(n)` | A data value to its pixel on the value axis |
+| `bandCentre(i)` | The centre of category `i`, in px |
+| `bandWidth` | Size of one category slot |
+| `ticks` | The axis values actually drawn |
+| `orientation` | `'vertical'` or `'horizontal'` |
+
+That's strictly more capable than a draw hook: it's declarative, reactive, and
+type-checked, with no lifecycle or registration order to learn.
+
+For a chart type that doesn't exist here, the same primitives are exported —
+`cartesianLayout`, `linearScale`, `niceTicks`, `seriesColor` — so you can build
+one on the same spine rather than starting over.
+
 ## License
 
 [MIT](https://github.com/therok1/iryx-ui/blob/main/LICENSE)