@jovertical/mise-design-system 1.0.0 → 1.1.0

package/skills/mise/components/data-display.md

@@ -0,0 +1,728 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Data display
+
+## Avatar
+
+`import { Avatar, AvatarFallback, AvatarImage, AvatarStatus, PresenceDot } from '@jovertical/mise-design-system'`
+
+`size-8` by default; a caller resizing it sets the initials' size too.
+
+Also takes: bits-ui `Avatar.Root` props.
+
+### `AvatarFallback`
+
+Renders while the image loads, and stays if it fails.
+
+Also takes: bits-ui `Avatar.Fallback` props.
+
+### `AvatarImage`
+
+Also takes: bits-ui `Avatar.Image` props.
+
+### `AvatarStatus`
+
+An avatar with a `PresenceDot` on its edge while someone is here. It wraps an `Avatar` rather than sitting inside it: `Avatar` clips its children to a circle, and the dot has to overhang the edge to read as a badge.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isOnline` (required) | `boolean` |  | Shows the dot: someone is here right now. |
+| `label` | `string` |  | Read to screen readers while online, e.g. "Has this ticket open". |
+
+Also takes: every `<span>` attribute.
+
+### `PresenceDot`
+
+The live "here now" mark: an 8px success dot, ringed in the card colour so it separates from whatever it sits on, with a ping so it reads as live rather than as a status colour. On its own so it can sit on any edge.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | Read to screen readers, e.g. "Has this ticket open". |
+
+Also takes: every `<span>` attribute.
+
+## Badge
+
+`import { Badge, badgeVariants } from '@jovertical/mise-design-system'`
+
+A short label on a row: a status, a tag, a count. Colour and shape are two props because they are two decisions. Whether a badge is a state (`soft`), a thing done (`solid`) or a tag (`outline`) is the composition's call; what that state is (`success`, `critical`) is the data's.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'soft'` | `soft` is a state something is in. `solid` is a thing that was done, and shouts. `outline` is a tag: metadata the reader may want, not a state to act on. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'neutral'` |  |
+| `count` | `boolean` | `false` | A number on its own: one digit draws a circle and more stretch it into a pill of the same height, so a column of counts keeps one silhouette. |
+| `children` | `Snippet` |  |  |
+
+Also takes: every `<a>` attribute.
+
+Also exports: `badgeVariants`.
+
+Types: `BadgeVariant` (`'solid' | 'soft' | 'outline'`).
+
+## ChartContainer
+
+`import { ChartContainer, ChartStyle, ChartTooltip, chartAreaFillOpacity, chartComparisonSeriesClass, chartGrid, chartLineStrokeWidth, getPayloadConfigFromPayload, useChart } from '@jovertical/mise-design-system'`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` (required) | `ChartConfig` |  | Each series' label and colour; colours are written as `--color-<key>`. |
+
+Also takes: every HTML attribute.
+
+### `ChartStyle`
+
+The scoped `<style>` that writes a chart's colours for light and dark.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` (required) | `string` |  |  |
+| `config` (required) | `ChartConfig` |  |  |
+
+### `ChartTooltip`
+
+The hover card a chart draws: the point's label, then a row per series with its indicator, its config label and its value.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hideLabel` | `boolean` | `false` |  |
+| `label` | `string` |  |  |
+| `indicator` | `'line' \| 'dot' \| 'dashed'` | `'dot'` |  |
+| `nameKey` | `string` |  |  |
+| `labelKey` | `string` |  |  |
+| `hideIndicator` | `boolean` | `false` |  |
+| `labelClassName` | `string` |  |  |
+| `labelFormatter` | `\| ((value: unknown, payload: TooltipPayload[]) => string \| number \| Snippet) \| null` | `defaultFormatter` |  |
+| `formatter` | `Snippet< [ { value: unknown name: string item: TooltipPayload index: number payload: TooltipPayload[] }, ] >` |  |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+Also exports: `chartAreaFillOpacity`, `chartComparisonSeriesClass`, `chartGrid`, `chartLineStrokeWidth`, `getPayloadConfigFromPayload`, `useChart`.
+
+Types: `ChartConfig`.
+
+## Checklist
+
+`import { Checklist, ChecklistCard } from '@jovertical/mise-design-system'`
+
+The full "Get started" list: setup steps grouped into cards, each row folding open to its description and whatever the caller hangs off it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `groups` (required) | `ChecklistGroup[]` |  |  |
+| `expandedId` | `string` |  | The `id` of the one open row, or nothing open. Controlled, with no internal fallback, so it can follow a URL fragment without disagreeing with it. One row at a time by construction. |
+| `onExpandedChange` | `(id: string \| null) => void` |  | The id to move to, or `null` when the open row was closed. |
+
+Also takes: every `<div>` attribute except `children`.
+
+### `ChecklistCard`
+
+A progress card small enough to live above a sidebar's nav: a ring, a heading, and the next few unmet rows.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  |  |
+| `percent` (required) | `number` |  | 0–100, clamped, rounded for the figure only. Not derived from `items`: the card shows the next few rows and the ring counts all of them. |
+| `items` (required) | `ChecklistCardItem[]` |  |  |
+| `collapsed` | `boolean` | `false` | The sidebar's icon-rail mode: no card, just a solid icon button at a nav icon's width, with the share in its accessible name. |
+| `collapsedControl` | `Snippet` |  | Replaces the collapsed button, so it can match the caller's own nav buttons. |
+| `size` | `'sm' \| 'md'` | `'md'` | `md` for a card on its own; `sm` for one pinned above a sidebar's nav. `sm` scales the ring, the title, the rows and the card's padding together. |
+| `variant` | `'default' \| 'outline'` | `'default'` | `outline` drops the fill and the shadow for a visible ring: on a dark sidebar a dark fill barely reads as a card, and a border separates it. |
+| `action` | `Snippet` |  | The header's corner: a "Hide" button. |
+| `footer` | `Snippet` |  | The way to the full list: "See all steps". |
+
+Also takes: everything `Card` takes except `title`, `children`, `variant`.
+
+Types: `ChecklistCardItem`, `ChecklistGroup`, `ChecklistTask`, `ChecklistTaskState` (`'completed' | 'skipped' | 'pending'`).
+
+## DataTable
+
+`import { DataTable, DataTableColumnHeader, DataTableColumnToggle, DataTableExportMenu, DataTableFacetedFilter, DataTableRowActions, DataTableToolbar, DataTableViewToggle, dataTableColumns, dataTableFeatures } from '@jovertical/mise-design-system'`
+
+A listing: a card holding an optional title, a toolbar, the table and a closing strip, or a grid of cards in `grid` view. Sorting and filtering are the server's; the table reports what the reader asked for and the caller refetches.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` (required) | `DataTableColumn<TData>[]` |  |  |
+| `data` (required) | `TData[]` |  |  |
+| `isLoading` | `boolean` | `false` |  |
+| `isFetchingNextPage` | `boolean` | `false` | A next page is being fetched; the load-more control spins. |
+| `hasNextPage` | `boolean` | `false` | There are more rows to load; the closing strip offers them. |
+| `fetchNextPage` | `() => void` |  |  |
+| `defaultSort` | `string` |  | The first sort, a column id, prefixed with `-` for descending. |
+| `filters` | `DataTableFilterState` | `{ globalFilter: '', columnFilters: [], sorting: sortingFromDefault(defaultSort), }` | The search, the column filters and the sort. Bind it to mirror it into a URL; a new value from outside is applied. |
+| `onFiltersChange` | `(filters: DataTableFilterState) => void` |  | Called when the reader changes the search, a filter or the sort. |
+| `title` | `string \| Snippet` |  | A heading inside the table's card, above the toolbar: what the rows are. Table view only. |
+| `description` | `string \| Snippet` |  | One muted line under `title`. |
+| `toolbar` | `Snippet<[DataTableInstance<TData>, DataTableFilterState]>` |  | The row above the table. Receives the table and the current filters. |
+| `emptyState` | `Snippet` |  | What an empty table shows. |
+| `footer` | `Snippet` |  | Replaces the closing strip's contents, for a summary card that wants one "View all" link rather than a count and a load-more. |
+| `withPadding` | `boolean` | `true` | Page padding around the table, on by default. |
+| `getRowId` | `(row: TData) => string` |  | The row's id. Without it, rows are keyed by index, which breaks selection and expansion: supply it whenever either is on. |
+| `viewMode` | `'table' \| 'grid'` | `'table'` |  |
+| `card` | `Snippet<[TData]>` |  | One item in `grid` view. |
+| `cardSkeleton` | `Snippet` |  | One placeholder card while `grid` view loads. |
+| `gridClass` | `string` |  | Classes for the grid, replacing the responsive one-to-three columns. |
+| `getItemKey` | `(item: TData) => string \| number` |  |  |
+| `getRowClass` | `(item: TData) => string \| undefined` |  | Classes for one row. |
+| `initialColumnVisibility` | `ColumnVisibilityState` |  |  |
+| `onRowClick` | `(item: TData) => void` |  | Makes rows a click target, with a pointer and a hover. |
+| `getSubRows` | `(row: TData) => TData[] \| undefined` |  | A row's children, or undefined when it has none. Supplying it turns expansion on; the cells render the disclosure from `row.getCanExpand()`, `row.getIsExpanded()` and `row.depth`. |
+| `enableRowSelection` | `boolean` | `false` | A leading checkbox column, for bulk actions. |
+| `rowSelection` | `RowSelectionState` | `{}` |  |
+| `isRowSelectable` | `(item: TData) => boolean` |  | Only these rows get an enabled checkbox: keep a user from selecting themselves. |
+| `class` | `string` |  |  |
+
+### `DataTableColumnHeader`
+
+A column's heading, with a sort menu when the column sorts. A sortable header is a button and an unsortable one bare text, so the button is pinned to the type `TableHead` already sets (12px, medium, muted) and the two read as one kind of heading.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `column` (required) | `Column<DataTableFeatures, TData, TValue>` |  |  |
+| `title` (required) | `string \| Snippet` |  |  |
+| `class` | `string` |  |  |
+
+### `DataTableColumnToggle`
+
+The columns a reader can hide, as checkboxes in a menu. Icon-only: a label beside the glyph would wrap a toolbar that already holds several filters.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `table` (required) | `DataTableInstance<TData>` |  |  |
+
+### `DataTableExportMenu`
+
+Export actions behind one trigger. Each item shows only when the page wires it, so the menu never offers something that does nothing.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onExportCsv` | `() => void` |  | Opens the page's full export flow, usually a dialog queuing a server job. |
+| `getCopyText` | `() => string` |  | The loaded rows as tab-separated text, ready to paste into a spreadsheet. The page builds it, since only it knows which fields are worth copying. |
+| `onPrint` | `() => void` |  | Defaults to printing the window. |
+
+### `DataTableFacetedFilter`
+
+A multi-select facet, drawn as a select: a filled pill summarising the choice rather than a dashed "add filter" chip, since a row of five dashed outlines is noisier than the values it filters. One choice shows its name; more show a count.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `column` | `Column<DataTableFeatures, TData, TValue>` |  |  |
+| `title` | `string` |  | Singular noun for the facet: "Status". |
+| `allLabel` | `string` |  | Shown when nothing is chosen. Falls back to "All {title}"; pass it where the plural is irregular. |
+| `selected` | `string[]` |  | The chosen values, for a caller that holds them. Read off the column otherwise. |
+| `options` (required) | `DataTableFacetedFilterOption[]` |  |  |
+
+### `DataTableRowActions`
+
+The ⋯ at the end of a table row, and the menu it opens: a round, soft, neutral button whose hover dims its own chip, never `--accent`, which means the active nav row. The menu opens leftward (`align="end"`) to stay inside the table.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `Snippet` |  | The menu's items: `DropdownMenuItem`s, separators, a destructive item last. |
+| `label` | `string` | `'Open menu'` | Announced in place of the glyph. Name the row when you can ("Actions for Riverside") so a screen reader down the column hears which row it is. |
+| `disabled` | `boolean` | `false` | For a row with no actions it may take. The trigger stays, so the column keeps its rhythm, and `label` says why it is off. |
+| `class` | `string` |  |  |
+
+### `DataTableToolbar`
+
+The row above a table: what narrows it on the left, what acts on it on the right. Written once because it was written twenty-three times, and nineteen had drifted into putting export and the column toggle on the left, where they read as another filter. Strings are props: a package cannot reach the consumer's copy.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `table` (required) | `DataTableInstance<TData>` |  |  |
+| `search` | `DataTableToolbarSearch` |  | Omit for a table with nothing worth searching: a ledger, a feed. |
+| `filters` | `DataTableToolbarFilter[]` | `[]` |  |
+| `leading` | `Snippet` |  | On the left, beside the filters: scopes such as a location or a date range. |
+| `actions` | `Snippet` |  | On the right, ahead of clear: things you do, such as an import link or a bulk action. |
+| `exports` | `DataTableExportMenuProps` |  | Omit for a table with nothing to export. |
+| `viewMode` | `'table' \| 'grid'` |  | Bind it to show the table/grid toggle; the page owns the mode. |
+| `columnToggle` | `boolean` | `true` | True by default. False for a table whose columns are all essential. |
+| `clearLabel` | `string` | `'Clear filters'` | The clear button's accessible name. |
+| `class` | `string` |  |  |
+
+### `DataTableViewToggle`
+
+Table or grid, as a segmented control of two glyphs. The cells are square rather than the segmented default's pill: a pill wider than its icon reads as a button missing its label.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `'table' \| 'grid'` | `'table'` |  |
+
+Also exports: `dataTableColumns`, `dataTableFeatures`.
+
+Types: `DataTableInstance`, `DataTableFacetedFilterOption`, `DataTableToolbarFilter`, `DataTableToolbarSearch`, `DataTableColumn`, `DataTableFeatures`, `DataTableFilterState`, `DataTableViewMode` (`'table' | 'grid'`).
+
+## DeltaBadge
+
+`import { DeltaBadge } from '@jovertical/mise-design-system'`
+
+A period-over-period change, as a tinted pill.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `number` |  | The change, signed. `2.4` renders `+2.4%`, `-2.4` renders `-2.4%`. |
+| `unit` | `string` | `'%'` | Appended to the number. `%` for a rate, `x` for a multiple. |
+| `prefix` | `string` | `''` | Ahead of the number, after the sign: `$` renders `+$1.25`. Pass `unit=""` with it, or the `%` default trails the figure. |
+| `precision` | `number` | `1` | Decimal places. A delta is a direction, not a measurement; one is usually right. |
+| `invert` | `boolean` | `false` | Set when falling is the good outcome: failed payments, time to fulfil, stock at risk. The arrow still follows the sign; only the colour flips. |
+| `variant` | `'pill' \| 'plain'` | `'pill'` | `pill`, the default, is a tinted, self-contained badge, for beside a bare figure. `plain` drops the fill and padding, for inline in a muted sentence where a pill would compete with the text sharing its line. |
+
+Also takes: every `<span>` attribute.
+
+## EntityLabel
+
+`import { EntityLabel } from '@jovertical/mise-design-system'`
+
+Names one thing (a person, a supplier, a document, a line item) with its mark and one qualifying line, wherever it appears: a table cell, a picker option, the head of a menu.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string \| Snippet` |  | The name. |
+| `description` | `string \| Snippet` |  | One qualifying line: a size, a code, a role. |
+| `icon` | `Snippet` |  | A glyph, drawn in an `IconChip`. Takes precedence over `media`. |
+| `media` | `Snippet` |  | A mark given as is: an `Avatar` for a person or a supplier. |
+| `iconShape` | `'square' \| 'circle'` |  |  |
+| `iconTone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` |  | When the entity itself is in a state worth a colour. The name stays in ink. |
+
+Also takes: every `<div>` attribute except `title`.
+
+## FactList
+
+`import { FactList, FactListItem } from '@jovertical/mise-design-system'`
+
+The `dl` a column of facts sits in. An item's `dt`/`dd` pair is only valid inside a `dl`; left to callers, the wrapper was typed thirty times, drifted into other gaps, and was left out altogether on five cards.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | `gap-1` instead of `gap-2`, for an aside where the list is a footnote to a preview above it rather than the card's content. |
+
+Also takes: every `<dlist>` attribute.
+
+### `FactListItem`
+
+One labelled fact.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string \| Snippet` |  |  |
+| `value` | `string \| number \| Snippet \| null` |  | An em dash when missing: a blank cell reads as a bug, not as "none". |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
+| `icon` | `Snippet` |  | Vertical only. An `IconChip` ahead of the fact, for one that identifies (a location, a person, a category) rather than one field among several. |
+| `iconShape` | `'square' \| 'circle'` | `'square'` | Vertical only. `square` by default, for a column of facts under a heading; `circle` for a strip of identity facts read across, where round chips keep several of them from reading as a form. |
+| `multiline` | `boolean` | `false` | Vertical only. Lets the value wrap instead of truncating: a name is one line, but a description is worth reading past the card edge. |
+| `valueClass` | `string` |  | Classes for the value, such as a sign colour on a total. |
+
+Also takes: every `<div>` attribute.
+
+## IconChip
+
+`import { IconChip, iconChipClassName, iconChipVariants } from '@jovertical/mise-design-system'`
+
+A glyph on a tinted tile: the leading mark of a fact, a heading, a tile, a row. `sm` by default because most chips sit beside a line of text; `md` and `lg` stand in open space. Neutral is muted ink on `--muted`: a chip takes a colour only when the thing it marks is in a state worth one.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | `sm` 32px, `md` 40px, `lg` 48px. |
+| `shape` | `'square' \| 'circle'` | `'square'` | `square` is a squircle whose radius steps with the size; `circle` is for a composition that has chosen it. The slot owns the shape, not what sits in it. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'neutral'` |  |
+
+Also takes: every `<span>` attribute.
+
+Also exports: `iconChipClassName`, `iconChipVariants`.
+
+Types: `IconChipShape` (`'square' | 'circle'`).
+
+## Item
+
+`import { Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle, itemMediaVariants, itemVariants } from '@jovertical/mise-design-system'`
+
+A **list row**, not a menu row. `DropdownMenuItem` is a command: it lives in a `role="menu"`, moves with the arrow keys and closes on select. This carries media, a title, a description and its own actions, and `ItemGroup` is a `role="list"`. A notification feed or a device list is this; a set of commands is the other.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` |  |
+| `size` | `'md' \| 'sm' \| 'flush'` | `'md'` |  |
+| `href` | `string` |  | Renders the row as an `a` to this address. |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  |  |
+
+Also takes: every HTML attribute.
+
+### `ItemActions`
+
+Also takes: every `<div>` attribute.
+
+### `ItemContent`
+
+Also takes: every `<div>` attribute.
+
+### `ItemDescription`
+
+Clamped to two lines for a list; pass `line-clamp-none` where the block is the point (an address).
+
+Also takes: every `<p>` attribute.
+
+### `ItemFooter`
+
+Also takes: every `<div>` attribute.
+
+### `ItemGroup`
+
+A list of `Item` rows. `flex flex-col` with no gap: rows that share a field touch, and a group of outlined rows takes `gap-2` so two borders do not meet as an accidental 2px rule.
+
+Also takes: every `<div>` attribute.
+
+### `ItemHeader`
+
+Also takes: every `<div>` attribute.
+
+### `ItemMedia`
+
+`variant="icon"` is `IconChip`'s chip, drawn on this element rather than nested inside it, so the slot's alignment (top-aligned beside a description) stays on the chip. Size it up to `md` for an entity standing alone under a card title; `sm` is tuned for a dense list.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'icon' \| 'image'` | `'default'` |  |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | `variant="icon"` only: the chip's footprint, `sm` 32px, `md` 40px, `lg` 48px. |
+| `shape` | `'square' \| 'circle'` | `'square'` | `variant="icon"` only. `circle` where the row stands for a person. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'neutral'` | `variant="icon"` only. Neutral unless the row is in a state worth a colour. |
+
+Also takes: every `<div>` attribute.
+
+### `ItemSeparator`
+
+Also takes: everything `Separator` takes.
+
+### `ItemTitle`
+
+Also takes: every `<div>` attribute.
+
+Also exports: `itemMediaVariants`, `itemVariants`.
+
+Types: `ItemMediaVariant` (`'default' | 'icon' | 'image'`), `ItemSize` (`'md' | 'sm' | 'flush'`), `ItemVariant` (`'default' | 'outline' | 'muted'`).
+
+## MetricBar
+
+`import { MetricBar, MetricRank } from '@jovertical/mise-design-system'`
+
+One measure, stated and then drawn. The figure is the answer and the bar is the context: a reader who wants the value should not estimate it from a length, and a reader comparing rows scans the bars, not the digits. So the figure sits on the label's line.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string \| Snippet` |  |  |
+| `percent` (required) | `number` |  | How full the bar is, 0–100. Clamped: over 100 is a bug upstream. |
+| `value` | `string \| number \| Snippet` |  | The figure the bar shows, at the label's right edge. |
+| `description` | `string \| Snippet` |  | A muted line under the label. |
+| `icon` | `Snippet` |  | A glyph in a `md` `IconChip` before the label: what the row is about. |
+| `rank` | `number` |  | The row's place in a ranking, as a `MetricRank` before the label, for a list whose order is the point. Pass `icon` or `rank`, not both. |
+| `trailing` | `string \| Snippet` |  | Beside the bar, on its line: `398 / 500 units`. The bar shortens to make room; a figure that qualifies the bar belongs on the bar's line. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'primary'` | The fill. `primary` by default; a status only where the reader should act. |
+
+Also takes: every `<div>` attribute.
+
+### `MetricRank`
+
+A place in a ranking, `1`, `2`, `3`, in a small muted circle. Smaller than an `IconChip` on purpose: the number orders the rows, it is not what they are about.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rank` (required) | `number` |  |  |
+
+Also takes: every `<span>` attribute.
+
+## MetricGrid
+
+`import { MetricGrid } from '@jovertical/mise-design-system'`
+
+A breakdown as a grid of bordered cells rather than a list of rows. A reader comparing sub-groups against each other wants them adjacent, not in order; `CardList` is the shape when the order means something.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `MetricGridItem[]` |  |  |
+| `columns` | `2 \| 3` | `3` | Columns at `md` and up; one below, where two cells side by side leave no room for a label and a bar. The caller picks it, knowing how many items there are: three columns and four items leaves an orphan. |
+
+Also takes: every `<div>` attribute.
+
+Types: `MetricGridItem`.
+
+## MetricRow
+
+`import { MetricRow } from '@jovertical/mise-design-system'`
+
+A subject, the figures that describe it, and one bar beneath them all.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `Snippet` |  | A glyph in a `md` `IconChip` before the label. |
+| `rank` | `number` |  | A place in a ranking, as `MetricRank`. Pass `icon` or `rank`, not both. |
+| `label` (required) | `string \| Snippet` |  |  |
+| `description` | `string \| Snippet` |  | A muted line under the title. |
+| `stats` | `MetricRowStat[]` |  | The figures along the top right, each under its own caption. |
+| `percent` (required) | `number` |  | How full the bar is, 0–100. Clamped: over 100 is a bug upstream. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'primary'` |  |
+| `trailing` | `string \| Snippet \| null` |  | Beside the bar: `398 / 500 units`. Inline, it takes a right-aligned slot with a floor width, so every row's bar starts and ends at the same x. `null` holds the slot empty; leave it out to give the slot up. |
+| `barPlacement` | `'below' \| 'inline'` | `'below'` | `below`, the default, runs the bar the full width under the row, for a row whose bar belongs to no figure in particular. `inline` puts it before the figures at a fixed width, for one figure the bar is a picture of. |
+| `hideBar` | `boolean` | `false` | Hides the bar, for a row with nothing to measure: an empty bar reads as a failure. |
+
+Also takes: every `<div>` attribute.
+
+Types: `MetricRowStat`.
+
+## RadialStat
+
+`import { RadialStat } from '@jovertical/mise-design-system'`
+
+A share, drawn as an arc with the figure inside it. A circle has an obvious whole, so the ring says "roughly a quarter" without the reader converting a length. Right for a handful of parts side by side; wrong for a list, where twenty rings are a wall of dials.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `percent` (required) | `number` |  | 0–100. Clamped: a share over 100 is a bug upstream, not a full ring plus. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'primary'` |  |
+| `diameter` | `number` | `72` | Outer diameter in pixels; the stroke scales with it. `diameter`, not `size`, which across the package means `sm \| md \| lg`. |
+| `thickness` | `'regular' \| 'thick'` | `'regular'` | Ring weight. `thick` for a ring that is the subject of its own card. |
+| `children` | `Snippet` |  | Replaces the printed percentage: a count, or a short word. |
+| `'aria-label'` | `string` |  | Read by assistive tech in place of the ring. |
+
+Also takes: every `<div>` attribute.
+
+Types: `RadialThickness` (`'regular' | 'thick'`).
+
+## ReadinessChecklist
+
+`import { ReadinessChecklist, ReadinessSummary, summariseReadiness } from '@jovertical/mise-design-system'`
+
+One row per requirement, answering "what does this page still need from me". Deliberately not wrapped in a card: it goes in an AsideCard on one page and a page body on another, and a component that brought its own surface would make the second impossible.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `ReadinessItem[]` |  |  |
+| `emptyMessage` | `string` | `'Nothing to check yet.'` | Shown when nothing is applicable: a server returning no rows. |
+| `showRequirement` | `boolean` | `true` | Drops the "Required" / "Optional" tag from unmet rows, for a progress list (what a server is doing), where a queued step tagged Required in warning colour reads as a problem when it simply has not started. |
+
+Also takes: every `<ul>` attribute except `children`.
+
+### `ReadinessSummary`
+
+The count, the bar, and one line naming what is missing: naming it beats reporting that something is.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `ReadinessItem[]` |  |  |
+| `ready` | `boolean` |  | Whether the thing is actually ready, when something other than this list decides. Omit it and readiness is "every required item met", the only authority a form has; pass it where a server owns the gate. |
+| `readyMessage` | `string` | `'Everything required is done.'` |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+Also exports: `summariseReadiness`.
+
+Types: `ReadinessItem`, `ReadinessStatus` (`'met' | 'unmet' | 'pending' | 'not-applicable'`), `ReadinessSummaryData`.
+
+## SegmentedBar
+
+`import { SegmentedBar } from '@jovertical/mise-design-system'`
+
+A whole, divided into named parts. One bar rather than one per part, because the question is how the total splits.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `segments` (required) | `Segment[]` |  |  |
+| `showShare` | `boolean` | `true` | Print each share inside its segment. Off when the bar heads a list below. |
+| `showLabels` | `boolean` | `true` | Captions above the bar, each over the segment it names. |
+| `size` | `'sm' \| 'md'` | `'md'` |  |
+
+Also takes: every `<div>` attribute.
+
+Types: `Segment`, `SegmentedBarSize` (`'sm' | 'md'`).
+
+## SegmentedCode
+
+`import { SegmentedCode } from '@jovertical/mise-design-system'`
+
+A code to read off a screen and type in somewhere else, in joined boxes of a few characters each, so a key reads here in the same groups the device asks for it in. The operator reads a box, types a box.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `string` |  | The code as issued (`66G6D-ME7021KJ6JBFN82MAWQA9VCV`). Hyphens and spaces are dropped before it is split, so the groups decide where it breaks. |
+| `groups` (required) | `readonly number[]` |  | How many characters each box holds, left to right: `[5, 4, 4, 4, 4, 4, 4]`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+## Sparkline
+
+`import { Sparkline } from '@jovertical/mise-design-system'`
+
+A figure's recent shape, drawn small enough to sit beside it. No axes, no grid, no tooltip, no labels: it answers "is that number climbing or falling" in the space of a word. Anything that invites closer reading belongs in a chart on its own card.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` (required) | `number[]` |  | The series, oldest first. Fewer than two points draws nothing. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'primary'` |  |
+| `height` | `number` | `40` | Height in pixels. The width comes from whatever holds it. |
+| `'aria-label'` | `string` |  | Read by assistive tech: the shape says nothing without it. |
+
+Also takes: every `<div>` attribute.
+
+## StatTile
+
+`import { StatTile } from '@jovertical/mise-design-system'`
+
+The dashboard's headline number. One tile states one figure, and the rest qualifies it: a unit, a delta, a description, a sparkline, a few rows. The icon sits in a chip so the eye lands on the number, and colour is kept for tone; a tile merely reporting a total stays in ink.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string` |  | A short caption above the figure. |
+| `value` (required) | `string \| number \| Snippet \| null` |  | The figure, already formatted: the package has no opinion about currencies or locales. `null` renders an em dash. |
+| `unit` | `string \| Snippet` |  | What the figure is counted in: `orders`, `per order`. Its own small line under the figure, since beside it a delta and a visual made every tile in a row wrap at a different point. |
+| `exactValue` | `string` |  | The unabbreviated figure, on hover: `$45,612.40` under `$45.6k`. |
+| `icon` | `Snippet` |  |  |
+| `hint` | `Snippet` |  | An explanation trigger after the label; it belongs to the caption it explains. |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'neutral'` | Colours the figure only, never the chip or the card: "this figure has a direction", not "this is a problem". |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
+| `surface` | `'card' \| 'inset'` | `'card'` |  |
+| `iconShape` | `'square' \| 'circle'` | `'square'` | `square` by default. A chip holding a face or initials is a circle; for icon chips the screen picks, and every chip in the row takes the same one. |
+| `description` | `string \| Snippet` |  | A muted line under the figure. |
+| `delta` | `Snippet` |  | After the figure, on its line: a `DeltaBadge`, so `$45.6k ↗ +15.7%` reads as one statement. Dropped on error. |
+| `action` | `Snippet` |  | Top right, on the label's line: a link out to what the figure summarises. Keep it short; the label is the one that wraps. |
+| `visual` | `Snippet` |  | A shape beside the figure, a `Sparkline` usually. It takes half the row and yields: a long figure squeezes the shape, never the reverse. |
+| `rows` | `StatRow[]` |  | Supporting facts under the figure, ruled off from it and from each other. |
+| `footer` | `Snippet` |  | Below everything else: a bar, a total. |
+| `iconPosition` | `'left' \| 'right'` | `'right'` | Right by default: the icon is ornament, so label, figure and description run straight down the left edge. Left for an icon that carries meaning. |
+| `iconAlignment` | `'center' \| 'top'` | `'center'` |  |
+| `iconTone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` | `'neutral'` |  |
+| `iconSize` | `'sm' \| 'md' \| 'lg'` |  |  |
+| `applyToneToIcon` | `boolean` | `false` | Lets the chip follow `tone`, so one threshold colours both and the two cannot drift into an ink figure in a red chip. Off by default: a tinted chip beside a tinted figure says the same thing twice. Supersedes `iconTone`. |
+| `loading` | `boolean` | `false` |  |
+| `error` | `boolean` | `false` |  |
+
+Also takes: every `<div>` attribute.
+
+Types: `StatIconAlignment` (`'center' | 'top'`), `StatIconSize` (`'sm' | 'md' | 'lg'`), `StatRow`, `StatSize` (`'sm' | 'md' | 'lg'`), `StatSurface` (`'card' | 'inset'`).
+
+## Table
+
+`import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow } from '@jovertical/mise-design-system'`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Tightens every row, the head included. The default suits a listing, where a row is a click target; `compact` is for a table being read (line items, totals, a mapping preview), where the extra height pushes the summary off the card. |
+
+Also takes: every `<table>` attribute.
+
+### `TableBody`
+
+The rows. The last row drops its rule; the table edge is enough.
+
+Also takes: every `<thead>` attribute.
+
+### `TableCaption`
+
+A caption under the table.
+
+Also takes: every HTML attribute.
+
+### `TableCell`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `numeric` | `boolean` | `false` | Right-aligned with tabular figures, so a column of numbers lines up. |
+
+Also takes: every `<td>` attribute.
+
+### `TableFooter`
+
+Totals, on a muted band under the body.
+
+Also takes: every `<thead>` attribute.
+
+### `TableHead`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `numeric` | `boolean` | `false` | Right-aligns the column. Pair it with `numeric` on the column's cells. |
+| `strong` | `boolean` | `false` | For a header that names the things compared rather than labelling a column of values (the roles across a permission matrix): ink at body size instead of the muted caption. |
+
+Also takes: every `<th>` attribute.
+
+### `TableHeader`
+
+The column labels, muted, ruled off from the body.
+
+Also takes: every `<thead>` attribute.
+
+### `TableRow`
+
+One row. `data-state="selected"` tints it as the active nav row is tinted.
+
+Also takes: every `<tr>` attribute.
+
+## Timeline
+
+`import { Timeline, TimelineConnector, TimelineContent, TimelineDot, TimelineItem, TimelineSkeleton, TimelineTitle, timelineDotVariants } from '@jovertical/mise-design-system'`
+
+A list of events, newest first by convention, each a badge, a title and a body joined by a vertical rule.
+
+Also takes: every `<ol>` attribute.
+
+### `TimelineConnector`
+
+The rule under a badge. Rendered by every item except the last. `min-h-6` keeps a visible run of line under a one-line body, so a short entry does not collapse the badge spacing.
+
+Also takes: every `<hr>` attribute.
+
+### `TimelineContent`
+
+The body. `pb-5` is the gap between entries; it sits here rather than on the item so the connector, which shares the row, runs the full distance.
+
+Also takes: every `<div>` attribute.
+
+### `TimelineDot`
+
+The badge. Renders whatever icon it is given, and a small filled circle when given nothing: an empty 32px disc reads as a component that failed to load.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tone` | `'primary' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical'` |  |  |
+| `indicator` | `Snippet` |  | A mark on the badge's lower-right edge (a `PresenceDot` while that entry's author is here now), drawn over the badge so the columns do not move. |
+
+Also takes: every `<div>` attribute.
+
+### `TimelineItem`
+
+Also takes: every `<li>` attribute.
+
+### `TimelineSkeleton`
+
+A timeline's loading state: neutral pulsing badges and bars in place of text.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` | `number` | `3` | How many placeholder entries. |
+
+Also takes: everything `Timeline` takes except `children`.
+
+### `TimelineTitle`
+
+The row's heading. A `div`, not a `p`: the slot takes any children, a `Skeleton` among them, and a block inside a paragraph is invalid HTML.
+
+Also takes: every `<div>` attribute.
+
+Also exports: `timelineDotVariants`.
+
+Types: `TimelineDotTone` (`'primary' | 'neutral' | 'info' | 'success' | 'warning' | 'critical'`).
+
+## TreeLeaf
+
+`import { TreeLeaf } from '@jovertical/mise-design-system'`
+
+One row of a nested list: a stem down its left edge, an elbow into the row, a media chip, a label, and an optional trailing figure.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `position` | `keyof typeof STEM_CLASS` | `'middle'` | `last` shortens the stem to half height, so it does not run past the final row. |
+| `icon` (required) | `Snippet` |  |  |
+| `label` (required) | `string \| Snippet` |  |  |
+| `trailing` | `string \| Snippet` |  |  |
+| `mediaSize` | `keyof typeof MEDIA_SIZE_CLASS` | `'md'` |  |
+
+Also takes: every `<li>` attribute except `children`.