@sckyzo/cosmos-react 0.3.0 → 0.4.0

package/README.md

@@ -125,6 +125,12 @@ chat messages stay a plain `<a>`, and a provider inside another one replaces it
 - `Input`, `Select` and `Textarea` `success="Username is available."`: the message under a field whose value is valid, with a green border (and a check icon on `Input` and `Select`). It is linked as the description and announced politely; `error` wins when both are set. `OtpInput success`: a green border on every cell, the message is yours.
 - `SegmentedControl` options take a `badge` (a count in a small pill, part of the radio's accessible name).
 - `PageHeader icon={Plug} iconIntent="brand"`: a decorative icon tile left of the title.
+- `PageHeader breadcrumb={…} description="…"`: the breadcrumb sits above the title and the description under it; both can be passed together. Below `sm` the `actions` wrap under the meta, at the start of the line, and the icon tile stays beside the text column.
+- `ErrorState onRetry={reload} retryLabel="Reload" action={<Button>Back to tickets</Button>}`: `retryLabel` renames the retry button (default "Try again"); `action` is a way out that is not a retry, next to it (the retry first), or alone without `onRetry`.
+- `EmptyState` `children`: rendered under the description and before the `action`, start-aligned and up to 28rem wide: a short numbered list of setup steps, for instance.
+- `FormRow`: label and description at the start, the control at the end. Below `sm` they stack, the label and its description above the control, which takes the row's width (a `Select` with `fullWidth={false}` stays at its own width, at the start).
+- `StickyScrollNav sections={[{ id, label }]}` (a long page with anchors, such as a settings page): below `sm` the row of buttons folds into a native select, named "Jump to section" (`jumpLabel`), that shows the section being read and scrolls to the one picked, below the nav like the buttons do. From `sm` up nothing changes. `VerticalNavigation` is a list of links to pages, not anchors, and keeps its look.
+- `KpiCard value="€12.4M" exactValue="€12,418,906.40"`: the exact figure behind an abbreviated value. A tooltip shows it on hover and focus, and it is read as part of the card's name ("…€12.4M, exact value €12,418,906.40"). On a plain card the value becomes a tab stop to reach the tooltip; a link or button card shows it when the card takes keyboard focus, and stays one tab stop.
 - `Rating value={4.5} allowHalf readOnly showValue count="(128 reviews)"`: stars on the warning hue with an outlined empty star, announced as `role="img"` ("Rated 4.5 out of 5"). Without `readOnly` it is a `radiogroup` (one tab stop, arrows, Home/End, hover preview) with `defaultValue`/`value` and `onChange(value)`; `0` is "no rating".
 - `Carousel.Thumbnails`: a scrolling row of buttons under the slides, one child per slide, named "Go to slide N" with `aria-current` on the current one and scrolled into view as it changes.
 - `ProfileHeader`: the top of a profile page. A `cover` (a gradient of the accent's tints by default), an `avatar` overlapping its bottom edge, the `name` with `badges`, a `headline` and `meta`, `actions`, `stats` read as a `<dl>`, and a `tabs` slot for a `Tabs.List` under a border. Below `sm` it stacks and the actions share the width.
@@ -186,8 +192,8 @@ checkbox, the action column, a link or button in another cell) never counts as a
 row click. `RowActionsMenu` is the ⋮ button and menu of a row, for
 `renderRowAction`: give it `Menu.Item`s, a destructive one with
 `intent="danger"`. On a narrow screen the edge of a table that scrolls sideways
-fades, and `stickyFirstColumn` pins its first column (after the checkbox on
-`DataTable`). `TableIdentityCell`, `TableIdCell`, `TableDescriptionCell` and
+fades, and `Table`'s `stickyFirstColumn` pins its first column (`DataTable` pins
+columns with `pin`, below). `TableIdentityCell`, `TableIdCell`, `TableDescriptionCell` and
 `TableAmountCell` are the cells tables keep rebuilding.
 
 `DataTable`'s column filters can be controlled: `filters`, `defaultFilters` and
@@ -201,11 +207,137 @@ filters bar; the counts come from you, the table never computes them.
 instead of scrolling: the checkbox, the column marked `mobile: 'title'` and the
 row action on the first line, then a label/value pair per other column
 (`mobileLabel` renames a label, `mobile: 'hidden'` drops a column). The toolbar
-gets a "Sort by" select for the sortable columns. The default, `scroll`, keeps
-the table.
+gets a "Sort by" select for the sortable columns and, when a column is
+filterable, a "Filters" button with the number of values filtered: it opens a
+bottom sheet with the filter of each filterable column, "Clear all" and "Show n
+rows", and sets the same `filters` as the column headers, controlled or not. The
+default, `scroll`, keeps the table.
+
+With `selectable`, a selection puts a tinted bar on one row: the count, "Clear"
+and the bulk actions on the start side, the search and the toolbar on the end
+side. `bulkActionItems` takes the actions as data (`{ key, label, icon,
+intent, disabled, onClick(selectedRows) }`) so the bar can adapt: the first is a
+button and, under 1152px of bar, the others fold into an "Actions" menu; the
+toolbar buttons go icon-only and the search narrows under 1360px; under 640px
+the bar wraps to two lines; with `mobileLayout="cards"` on a phone each action is
+an icon button named by its `label`. `bulkActions(selectedRows)` still renders
+any node after them, as given at every width. While rows are selected the
+toolbar's Export follows them ("Export 3" downloads those rows, in the table's
+sort order, and `onExport` gets their keys as `selection`); with none selected it
+exports the filtered rows.
+
+`emptyAction` puts a call to action under the empty state ("Create the first
+order"). When a search or filters hide every row it gives way to a "Clear
+filters" button, which clears both.
+
+`DataTable` rows can expand: `renderExpandedRow(row)` adds a first column of
+chevron buttons (`aria-expanded`, `aria-controls` the detail row while it is
+open, named "Show details for <row key>") and draws what it returns in a row
+below, spanning every column. The open rows are a set of row keys, like the
+selection: `expandedRows`, `defaultExpandedRows` and
+`onExpandedRowsChange(expanded)`. A toggle never selects a row nor counts as a
+click on it. Limit: with `virtualize` nothing expands (its rows have one fixed
+height), and the prop is ignored. With `mobileLayout="cards"` the chevron sits on
+the card's title line and the content opens inside the card, under its fields.
+
+`pin: 'start' | 'end'` on a column keeps it in place while the table scrolls
+sideways, several per side: list the `start` ones first and the `end` ones last
+in `columns`. A pinned cell sticks after the widths of the pinned columns before
+it, measured, so percentage widths, a resize and the text size keep it right.
+The selection and toggle columns are pinned with the start columns, the action
+column with the end ones. A shadow marks an edge only while content scrolls
+under it, and the scroll fade leaves a pinned side alone. `pin` replaces
+`DataTable`'s `stickyFirstColumn` (removed): put `pin: 'start'` on the first
+column. With `rowHref`, the link covers its own column when that is pinned and
+a click on the rest of the row follows it from a handler. The cards of
+`mobileLayout="cards"` ignore `pin`.
+
+```tsx
+<DataTable
+  rows={hosts}
+  rowKey={(r) => r.host}
+  selectable
+  renderExpandedRow={(r) => <HostDetail host={r} />}
+  columns={[
+    { key: 'host', label: 'Host', pin: 'start', render: (r) => r.host },
+    { key: 'rack', label: 'Rack', render: (r) => r.rack },
+    // …
+    {
+      key: 'status',
+      label: 'Status',
+      pin: 'end',
+      render: (r) => <StatusBadge status={r.status} />,
+    },
+  ]}
+/>
+```
+
+Inline editing: `edit` on a column is `{ initialValue(row), render(editor) }`,
+and `render` draws an existing form field from the editor: `editor.value` (the
+draft, a string: parse it yourself), `setValue`, `commit`, `cancel`, `saving`
+and `fieldProps` (the field's name, "Rack for node-a02", its error tie, `disabled`
+while saving and a red border on `aria-invalid`), which an `Input` or a `Select`
+takes as it is. `editTrigger` picks how an editable cell opens, one per table:
+
+- `'cell'` (default): the cell's content is a button that fills it; a click,
+  Enter or F2 opens the editor in place, focused. Keep that content to text and
+  badges, with no link or button in it.
+- `'button'`: a pencil button in each editable cell ("Edit Rack for node-a02"),
+  shown on the hovered or focused row and always on a screen with no hover; the
+  editor has Save and Cancel buttons beside the field.
+- `'row'`: an Edit button in the row's action column turns every editable cell
+  of the row into its field, with Cancel and Save in place of the button.
+
+In `'cell'` and `'button'`, Enter or blur saves and Escape cancels, putting the
+focus back on the cell's trigger. `onCellEdit(row, columnKey, value)` is called
+only when the draft changed, and may return a promise: the cell is `aria-busy`
+with a spinner until it settles. If it rejects (or throws), the editor opens
+again with what was typed, and the error's message shows under the cell, tied to
+the field by `aria-describedby`. In `'row'`, Save (or Enter in a field) calls
+`onRowEdit(row, changes)` once, `changes` being column `key` to draft for the
+cells that changed only; a promise makes the row `aria-busy` and the fields
+disabled, and a rejection keeps the fields open with the error in a row under
+the row. Escape or Cancel drops the changes. Only one cell or row edits at a
+time, and nothing opens while a save is pending. The table never changes
+`rows`: update them from the handler. Limits: editing is off with `virtualize`
+(a fixed-height cell would clip an editor and its error) and in the cards of
+`mobileLayout="cards"`.
+
+```tsx
+<DataTable
+  rows={hosts}
+  rowKey={(r) => r.host}
+  editTrigger="cell"
+  onCellEdit={async (row, key, value) => {
+    await api.patchHost(row.host, { [key]: value }); // a rejection shows under the cell
+    setHosts((all) => all.map((h) => (h.host === row.host ? { ...h, [key]: value } : h)));
+  }}
+  columns={[
+    { key: 'host', label: 'Host', render: (r) => r.host },
+    {
+      key: 'rack',
+      label: 'Rack',
+      render: (r) => r.rack,
+      edit: {
+        initialValue: (r) => r.rack,
+        render: (e) => (
+          <Input
+            {...e.fieldProps}
+            size="sm"
+            value={e.value}
+            onChange={(ev) => e.setValue(ev.target.value)}
+          />
+        ),
+      },
+    },
+  ]}
+/>
+```
 
 `DataTable`'s `density` is controllable like the rest: `density`, `defaultDensity`
-and `onDensityChange(density)`. As with `pageSize`, a `density` passed without
+and `onDensityChange(density)`: `compact`, `default` or `comfortable`. Without
+`density` and `defaultDensity` the table follows the page's `data-density`; set,
+it is a local override of the page. As with `pageSize`, a `density` passed without
 `onDensityChange` is a controlled value that never moves, so a saved view
 reports its density and the table keeps the one you pass.
 
@@ -222,7 +354,8 @@ mark (U+FEFF), so that spreadsheets read accents. Fields follow RFC 4180
 header or string value that starts with `=`, `+`, `-`, `@`, a tab or a carriage
 return gets a `'` prefix so a spreadsheet never runs it as a formula; a
 `number` is left alone. To export on the server, `onExport(query)` receives `{ search, filters,
-sort, columns }` (the visible column keys, in order) and builds no file.
+sort, columns }` (the visible column keys, in order, plus `selection`, the
+selected keys, while rows are selected) and builds no file.
 `toCsv(rows, columns)` gives the same text, without the byte order mark, for an
 export outside a table (prepend U+FEFF for a file meant for spreadsheets).
 
@@ -332,13 +465,13 @@ scrolling. Its limits:
 
 - The table needs a height (`className="max-h-96"`): its own area is what
   scrolls, and without a height every row is in view.
-- Every row has one fixed height, from `density`: 49px, or 61px when
-  `comfortable`, at the default text size, and growing with the text size
+- Every row has one fixed height, from the density: 41px when `compact`, 49px,
+  or 61px when `comfortable`, at the default text size, and growing with the text size
   setting. Content taller than that is clipped, so keep a cell to a line of text
   or a control, as in a standard row.
 - It applies to the table layout only: with `mobileLayout="cards"` below `sm`
   the cards keep the pagination.
-- It is not for expandable rows.
+- It is not for expandable rows or inline editing: both are off with it.
 - On paper only the drawn rows print.
 
 ```tsx
@@ -352,11 +485,12 @@ scrolling. Its limits:
 />
 ```
 
-`Table` takes `density` (`default` or `comfortable`, as on `DataTable`),
+`Table` takes `density` (`compact`, `default` or `comfortable`, as on `DataTable`; the
+page's by default),
 `striped`, `stickyHeader` (give the wrapper a height with
 `containerClassName`, e.g. `max-h-80`) and `stickyFirstColumn`. While data
 loads, `TableSkeletonRows` fills the `TableBody` under the header row. Cells take `align` and `numeric`
-(right-aligned, tabular figures). `TableHeaderCell` sets `scope` to `col` in the
+(`start`, `center` or `end`; `numeric` aligns to the end, with tabular figures). `TableHeaderCell` sets `scope` to `col` in the
 head and `row` elsewhere. The wrapper scrolls horizontally, so a wide table
 stays inside the page on small screens.
 
@@ -487,6 +621,144 @@ the locale nor the zone, and keep the room of their text until then.
 Every one of them takes `now`, which freezes it at that moment and sets no timer: use it for
 stories, screenshots and tests.
 
+## Health checks
+
+`HealthSummary`, `HealthCheckList` and `HealthMatrix` show whether a system and its parts are
+healthy, and why not. They build on `HealthStatus` (`OK`, `WARN`, `CRIT`, `UNKNOWN`, `INFO`) and on
+the dots and badges of the same folder.
+
+A check is plain data. A group holds checks and, below them, other groups: one level per dependency
+reads as a tree. A group has no status of its own, it is the worst status under it.
+
+```tsx
+const checks: HealthCheck[] = [
+  {
+    id: 'queue',
+    name: 'Job queue',
+    status: 'WARN',
+    target: 'redis://queue:6379/0',
+    message: '312 jobs waiting (limit 200)',
+    latency: 4, // milliseconds
+    checkedAt: '2026-01-15T09:59:30Z', // a Date, a timestamp or an ISO string
+    output: 'queue=default depth=312 oldest=94s', // shown in a code block, on demand
+  },
+];
+const groups: HealthCheckGroup[] = [{ id: 'queue', name: 'Queue', checks, groups: [] }];
+
+<HealthSummary checks={flattenChecks(groups)} refresh={{ onRefresh, autoRefreshMs, onIntervalChange }} />
+<HealthCheckList groups={groups} sort="severity" />
+<HealthMatrix ariaLabel="Services by node" columns={nodes} rows={services} />
+```
+
+Everything that sorts or rolls up uses one **severity order**, worst first: `CRIT`, `WARN`,
+`UNKNOWN`, `INFO`, `OK`. A check nobody could run weighs more than one that passes. `SEVERITY_ORDER`,
+`compareSeverity` and `worstStatus` are exported, as are `flattenChecks` and `groupWorst`. A set with
+nothing in it is `UNKNOWN`.
+
+- `HealthSummary` takes the worst status of its `checks`, and `status` overrides it when you weigh the
+  checks differently (the counts still come from `checks`). The headlines are "All systems
+  operational", "Degraded performance", "Major outage", "Status unknown" and "Operational, with
+  notices"; `labels` replaces any of them. It also shows the count per status, the last check
+  (`RelativeTime`, from the latest `checkedAt`, or `checkedAt`) and, with `refresh` (the props of
+  `RefreshButton`), a refresh action. `variant="banner"` is full width and tinted by the status,
+  `variant="compact"` is one line for a card or a topbar.
+- `HealthCheckList` draws rows with the status in words, the name, target, message, latency and last
+  check. A check with an `output` has a toggle on its name. Pass `checks`, `groups` or both. A group
+  header shows the worst status and the counts under it and collapses
+  (`collapsedGroups` / `defaultCollapsedGroups` / `onCollapsedGroupsChange`, by group id).
+  `sort="severity"` puts the failing checks, and the groups holding them, first. `variant="list"` is
+  rows, `variant="grid"` one small card per check, for a wall screen.
+- `HealthMatrix` is one cell per service (`rows`) and per environment, node or region (`columns`),
+  with sticky headers, in a `role="grid"` that takes one tab stop: arrow keys move between cells,
+  Home and End go to the ends of the row. A cell opens its detail in a popover (`message`, `latency`,
+  `checkedAt`, and a `detail` node of your own) with Enter, Space or a click; Escape closes it and the
+  focus returns to the cell. Each cell is named like "API on par-2b: Warning", and a column with no
+  entry is an empty cell. `variant="dots"` is dense, and every dot has a shape as well as a colour: OK a
+  filled circle, warning a diamond, critical a square, unknown a hollow ring, info a triangle. The
+  legend above the grid shows the same shapes. `variant="pills"` writes the status in each cell. The
+  grid scrolls in its own box when it is wider than the screen; `maxHeight` also scrolls it
+  vertically. `rowHeader` names the first header cell ("Service" by default; a cluster says "Rack").
+  `attentionStrip` adds a "Needs attention" strip above the grid: one chip per row that holds a
+  warning or a critical cell, with its counts in words ("2 Critical, 1 Warning"), the worst rows
+  first. Picking a chip scrolls its row into view, in the grid's own box when `maxHeight` is set,
+  and moves the focus to its worst cell; on a phone the strip scrolls sideways.
+
+`HealthSummary`, `HealthMatrix` and `MonitorRow` (see Uptime monitoring) take `stale`, the time of the
+last data, for a source that has stopped answering. The status colours turn grey, the component says
+"Stale · 4 minutes ago" and the stale state is in the accessible text (the headline, each matrix
+cell, the monitor's state chip). The statuses shown stay those of the last data.
+
+Every one takes `now`, which freezes the relative times, for stories and tests. One check shown as a
+card, and a dependency tree, need no component of their own: see the stories of the Monitoring group.
+
+## Uptime monitoring
+
+`HeartbeatBar`, `UptimeBars`, `UptimeStat` and `MonitorRow` draw what a monitor found: its recent
+checks, its uptime over days and periods, and one monitor as a line or a tile. A monitor checks a
+target every N seconds; these show the result, and the host brings the data.
+
+A **beat** is one check, and a **day** is one day of history. `time` and `date` take a `Date`, a
+timestamp in milliseconds or an ISO 8601 string (a bare `YYYY-MM-DD` names that calendar day for every
+reader, whatever their time zone).
+
+```tsx
+const beats: Beat[] = [
+  { time: '2026-01-15T06:41:10Z', status: 'up', latency: 182 },
+  { time: '2026-01-15T06:42:10Z', status: 'down', latency: 5003, message: 'Timeout after 5 s' },
+]; // oldest first; status: 'up' | 'down' | 'degraded' | 'maintenance' | 'pending'
+const days: UptimeDay[] = [
+  { date: '2026-01-14', uptime: 0.9995, incidents: 1 }, // 0 to 1; null is a day with no data
+  { date: '2026-01-15', uptime: null },
+];
+
+<HeartbeatBar beats={beats} />
+<UptimeBars days={days} title="API" legend />
+<UptimeStat periods={[{ label: '30 days', uptime: 0.9991 }]} responseTime={182} certificate={{ daysLeft: 12 }} />
+<MonitorRow name="API" type="HTTP" beats={beats} uptime={0.9992} />
+```
+
+**Thresholds.** An uptime is coloured by one shared rule: 99.9 % and up is green, 99 % up to 99.9 %
+is amber, below 99 % is red, and `null` is grey ("No data"). Every component that colours by uptime
+(`UptimeBars`, `UptimeStat`, `MonitorRow`) takes `thresholds`, a partial `{ good, warning }` in shares
+from 0 to 1 (`{ good: 0.9999, warning: 0.999 }`), and the legend of `UptimeBars` follows it. A
+`warning` limit above `good` is lowered to it. `DEFAULT_THRESHOLDS`, `resolveThresholds` and
+`uptimeLevel` are exported, to colour your own figures the same way. The status colours are the
+theme's (`--color-status-ok`, `-warn`, `-crit`), so a theme or an accent repaints them.
+
+- `HeartbeatBar` draws one mark per beat, the newest at the end. `variant` is `bars` (default),
+  `blocks` or `dots`; `size` is `md` (32px, default) or `sm` (24px, the height inside a `MonitorRow`).
+  It holds as many beats as its width allows and drops the oldest, so a 375px screen still shows the
+  latest history: give it the width of its container. A `down` beat differs by shape as well as
+  colour (a taller bar, a block crossed by a diagonal, a square dot) and every beat is named in words
+  (status, time, latency, message). The bar is one tab stop on the newest beat; the arrow keys, Home
+  and End move between beats, and hovering or focusing one shows its tooltip (Escape hides it).
+  `legend` writes the key of the statuses under the bar.
+- `UptimeBars` draws one bar per day over `period` 30, 60 or 90 days (default 90), coloured by the
+  thresholds. The header gives `title` and the uptime of the period (the mean of the days with data,
+  or `uptime` when you have the exact figure), the captions read "90 days ago" and "Today". When the
+  width cannot hold every day, the oldest are dropped and the caption and the figure describe what is
+  drawn. Days are named ("Jan 15, 2026: 99.95% uptime, 1 incident"), reached with the same keyboard
+  model as `HeartbeatBar`, and `legend` writes the thresholds. `compact` is the form for a card: lower
+  bars, no header, captions or legend.
+- `UptimeStat` has two variants. `row` (default) puts the uptime of each of your `periods` side by
+  side (`{ label: '24 hours', uptime }`: you name the periods), then `responseTime` and the
+  `certificate`: days left, a warning (an icon, and the amber colour) under `warnBelow` days, 14 by
+  default. `card` is one figure for a dashboard tile: the first period, and the downtime it stands for
+  ("39 min down") when the period has a `duration` in milliseconds, with `days` drawn as compact bars.
+  It is a variant of its own, not a `KpiCard` preset.
+- `MonitorRow` shows the state (the status of the last beat, `status` to force it, `paused` to
+  pause it), the name (a link with `href`) and `type` (any string: `HTTP`, `TCP`, `DNS`, `ping`,
+  `keyword`), a 24px `HeartbeatBar`, the uptime over 24 hours, and the current latency (default: the
+  last beat's). `variant="row"` is a line of a list, which the host draws: it stacks on a narrow
+  screen. `variant="card"` is a tile for a grid. `stale` (with `now` to freeze its text) greys the
+  chip, the beats and the uptime and adds a "Stale · 4 minutes ago" tag under the name.
+
+The response time (a `LineAreaChart` from `@sckyzo/cosmos-charts`, its `referenceBands` shading the
+down periods; the stories draw a plain SVG, since this package has no chart dependency), the timeline
+of an incident (`Timeline`) and a maintenance notice (`AlertBanner`) need no component of their own:
+see the stories of the Monitoring group, and the two example pages (a public status page and a
+monitors dashboard).
+
 ## Auth layouts
 
 `AuthLayout` wraps the sign-in, sign-up, reset and two-step forms. `variant` picks the page:
@@ -656,17 +928,229 @@ only http(s) URLs become links.
   Cancel and Escape return the focus to the button that opened it. Delete calls back at once:
   confirm in the host if needed.
 - Replies are one level, `Comment`s passed as `replies`, folded beyond `maxReplies` (default
-  `2`) behind a "Show 3 more replies" button. A reply has no Reply of its own.
+  `2`) behind a "Show 3 more replies" button. A reply has no Reply of its own. For a ticket, where
+  the latest exchanges matter, `keepReplies="last"` keeps the last `maxReplies` visible and folds
+  the older ones behind a button above them ("Show 3 earlier replies", `labels.showEarlierReplies`).
 - `variant="internal"` tints a note and labels it "Internal note" with a lock, so it reads as one
   without the color.
 - `CommentComposer` is a `Textarea` with `autoResize`: Enter adds a line, Ctrl or Cmd+Enter and the
   submit button send, Escape cancels when `onCancel` is given. Submit is disabled while the text
   is empty or `submitting`. `value` / `defaultValue` / `onChange` work as on other fields.
+- `modes` gives the composer a segmented control above the field, for what is being written
+  (`{ value: 'reply', label: 'Reply to customer' }`, `{ value: 'note', label: 'Internal note',
+internal: true }`). `onSubmit(text, mode)` receives the selected mode's `value`; without `modes`
+  it gets the text alone, as before. `mode` / `defaultMode` / `onModeChange` work as on other
+  fields, and a mode may carry its own `placeholder` and `submitLabel`. An `internal` mode tints
+  the field and the submit button like `variant="internal"` tints a comment, with a lock and the
+  line `internalNotice` ("Internal note: only your team sees this."), announced when the mode
+  changes. `modeLabel` names the control.
 - `time` is a node, as in `Timeline`: a `RelativeTime`, a `<time>` or your own text.
 - Every text can be translated: `labels` on `CommentThread` reaches all its comments (a
   comment's own `labels` win), `emptyTitle` and `label` on the thread, and the composer's own
   `label`, `placeholder`, `submitLabel` and `cancelLabel`.
 
+## Log views
+
+`LogViewer`, `LogToolbar`, `LogLevelBadge` and `LogEntryDetail` read a log: the live tail, its
+controls, a level label and one record in full. The host owns the data: it fetches the snapshot,
+streams the new lines (SSE, WebSocket), trims the buffer and decides what "clear" and "download"
+do. The components draw what they are given.
+
+```tsx
+const [lines, setLines] = useState<LogLine[]>([]); // oldest first, ids unique and stable
+const [follow, setFollow] = useState(true);
+const [levels, setLevels] = useState<readonly LogLevelKey[]>(['debug', 'info', 'warn', 'error']);
+const [search, setSearch] = useState('');
+const [active, setActive] = useState(0);
+const [matches, setMatches] = useState(0);
+
+<LogToolbar
+  live={follow}
+  onLiveChange={setFollow}
+  levels={['debug', 'info', 'warn', 'error']}
+  levelCounts={countLogLevels(lines)}
+  activeLevels={levels}
+  onActiveLevelsChange={setLevels}
+  search={search}
+  onSearchChange={(text) => {
+    setSearch(text);
+    setActive(0); // a new search starts at its first match
+  }}
+  matchCount={matches}
+  activeMatch={active}
+  onActiveMatchChange={setActive}
+  onClear={() => setLines([])}
+/>
+<LogViewer
+  aria-label="Backend logs"
+  lines={lines}
+  follow={follow}
+  onFollowChange={setFollow}
+  activeLevels={levels}
+  search={search}
+  activeMatch={active}
+  onMatchCountChange={setMatches}
+/>
+```
+
+**Data model.** A `LogLine` is `{ id, time, level?, source?, message, fields?, stack? }`. `time` is
+a `Date`, a timestamp in milliseconds or an ISO string, shown with milliseconds. `level` is
+`trace`, `debug`, `info`, `warn`, `error` or `fatal` in any case; anything else (`warning`,
+`notice`, nothing) is `unknown`. `lines` is always oldest first, whatever the `order` it is drawn
+in, and each `id` must stay the same from one render to the next: the viewer uses it to key rows
+and to count the lines that arrived while it was paused.
+
+**`LogViewer`**
+
+- `tone`: `terminal` (default) is a dark panel in every theme, as a console is; `surface` follows
+  the theme, for a card on a dashboard. `density`: `compact` (default) is one line per record,
+  `comfortable` puts the message under its time, level and source. `columns` hides parts of the
+  row (`['time']`), `lineNumbers` numbers the lines in the order of `lines`.
+- `follow` / `defaultFollow` / `onFollowChange`: it stays at the newest line while lines arrive.
+  Scrolling away from the end pauses it and shows "Jump to latest (12 new)"; the button, or
+  scrolling back to the end, resumes it; a filter that shortens the list does not. `order` puts
+  the newest line last (`newest-last`, the default, a tail) or first.
+- The row follows the width of the viewer, not the screen's: the viewer is a container. Under
+  28rem the source column is hidden; without `wrap` the row stays on one line and the viewer
+  scrolls sideways inside itself, with `wrap` the message goes on a line of its own under the
+  time and the level. Give the viewer a width (it fills a block parent; in a flex row, a `flex-1`
+  or a width class), since a container takes none from its content.
+- `activeLevels` and `activeSources` filter the lines (left out or, for sources, empty, shows
+  all). `search` highlights a case-insensitive term in the messages and sources, `searchRegex`
+  reads it as a pattern (one that does not compile finds nothing). `activeMatch` is the active
+  match, counted from 0 among the lines that match; it is drawn stronger and scrolled into view
+  when it changes. `onMatchCountChange` reports how many lines match. Reset `activeMatch` to 0
+  when the search changes, as the example does; `LogToolbar` steps it with previous and next
+  (and Enter / Shift+Enter), wrapping around the ends.
+- A row with `fields` or a `stack` has a button that expands it in place
+  (`expandedIds` / `defaultExpandedIds` / `onExpandedIdsChange`). `onOpenLine` adds an "Open
+  details" button to the expanded row, to open a `LogEntryDetail` in a drawer.
+- Messages, sources, fields and stacks are text, never HTML. A bidirectional control character
+  stays inside its own message.
+
+**`LogToolbar`.** Each control is there when its props are given: Live / Paused
+(`onLiveChange`), level toggles with counts (`levels`), search (`onSearchChange`) with a regex
+toggle (`onSearchRegexChange`) and previous / next (`matchCount` and `onActiveMatchChange`), a
+source filter on `MultiSelect` (`sources`), `onWrapChange`, `onOrderChange`, `onDownload` and
+`onClear`. From `sm` up it is one bar. Below, Live / Paused and the search stay in the bar and
+the levels, sources and view options move into a "Filters" popover; its button shows how many
+filters are active (levels narrowed, sources chosen). The state pairs (`live`, `activeLevels`,
+`search`, `searchRegex`, `activeSources`, `wrap`, `order`) work controlled or not, as on other
+fields. It holds none of the log: pass the same filters to the viewer.
+
+**`LogLevelBadge`** is the level as a word in its colour (`ERROR`, `WARN`), on the `surface` tone
+by default or the `terminal` one. Use it in a table cell, a card or a detail.
+
+**`LogEntryDetail`** shows one record in full for a drawer or a side panel: level, time, source
+and message, the fields as key / value pairs with a copy button each, the stack trace, the raw
+JSON, and "Show context", the lines around it (a `context` prop, or fetched through
+`onShowContext`). `onFilterValue` and `onExcludeValue` add "Filter on this value" and "Exclude
+this value" buttons to each field. A structured table is a `DataTable` with a `LogLevelBadge`
+column and, once rows can expand, a `LogEntryDetail` in them.
+
+**Accessibility.** The viewer is `role="log"` with `aria-live="off"`: a fast stream read aloud
+line by line cannot be followed, so new lines are not announced. `announceErrors` reads the
+error and fatal lines that arrive (three at most, then the count of the rest) in a polite live
+region of its own. The scroller takes a tab stop, so the arrow keys scroll it, and every level is
+a word, not only a colour. Each level colour holds 4.5:1 on both tones in the four themes.
+
+**Limits.**
+
+- The default mode is windowed: only the rows in view are drawn, so tens of thousands of lines
+  stay smooth. The row height is measured, so it follows the text size, and a row that scrolls out
+  of view and back is redrawn: a button on it loses the focus when it leaves the window.
+- An expanded row takes a fixed room of up to 12 rows (a row per field and per stack line); a
+  longer detail scrolls inside it.
+- `wrap` lines have no fixed height, so they cannot be windowed: all of them are drawn (the
+  browser skips the ones out of view with `content-visibility`). Keep the buffer to a few
+  thousand lines with `wrap` on, as rackscope does with 2,000. Newest first and paused, wrapped
+  lines do not stay put when new ones arrive.
+- Without `wrap` a long line scrolls sideways: the scroll width is that of the widest row drawn.
+- The labels ("Jump to latest", "Filters"…) are English.
+- Not here: the log volume chart (stacked `BarChart` of `@sckyzo/cosmos-charts`, as the lines per
+  level over time) and a structured logs table. The output of a job is `JobLog`, below.
+
+## Job logs
+
+`JobLog` is the output of a CI job or a build: collapsible steps, each with its status and
+duration, and the lines of each step numbered and coloured. It is read differently from a live
+tail, hence a component of its own; it shares the tones, the clock format and the windowing of
+`LogViewer`. The host owns the data and the clock: it passes the steps, their durations (`JobLog`
+runs no timer) and the new lines as they come.
+
+```tsx
+const steps: JobLogStep[] = [
+  { id: 'install', name: 'Install dependencies', status: 'passed', duration: 41_000, lines: [...] },
+  {
+    id: 'run-tests',
+    name: 'Run tests',
+    status: 'failed',
+    duration: 72_000,
+    startedAt: '2026-01-15T09:30:44Z',
+    // A string, or { text, timestamp } when the line has a time.
+    lines: ['$ pnpm test', '\x1b[31m✗ sortRows keeps empty values last\x1b[0m', ...],
+  },
+  { id: 'build', name: 'Build', status: 'skipped', lines: [] },
+];
+
+<JobLog title="Build #1287" meta="main · 4f2c1a9" status="failed" duration={123_000} steps={steps} />
+```
+
+- **Steps.** `status` is `queued`, `running`, `passed`, `failed` or `skipped`. `duration` is in
+  milliseconds; `startedAt` is the origin of the elapsed times (it defaults to the first
+  timestamp of the step). `id` is unique and stays the same from one render to the next. The
+  optional header (`title`, `status`, `meta`, `duration`) is drawn when any of them is given.
+- **Open steps.** The failed and the running steps start open, the others closed, and a step that
+  starts running later opens. `expandedSteps` / `defaultExpandedSteps` / `onExpandedStepsChange`
+  work as on other controls. The header of an open step sticks to the top of the log while its
+  lines scroll, and each step is windowed on its own, so a step of tens of thousands of lines
+  stays smooth.
+- **Line numbers.** They restart at 1 in each step and are links: `href="#<idPrefix><step id>-L<n>"`.
+  A click calls `onCurrentLineChange({ step, line })` and does not touch `location`; a click with a
+  modifier key is the browser's own, so "open in a new tab" works. `currentLine` /
+  `defaultCurrentLine` is the line in focus: when it changes its step opens, the line scrolls into
+  view and takes `aria-current="location"`. One line at a time. To make the links shareable, sync
+  it with the URL hash in the host: read `parseJobLogHash(location.hash, idPrefix)` into
+  `currentLine` on load and on `hashchange`, and write `jobLogLineHref(idPrefix, line)` back from
+  `onCurrentLineChange` (the `Monitoring/JobLog` "Synced with the URL hash" story does).
+- **Toolbar.** Search across all the steps (a match in a closed step opens it) with the count and
+  previous / next, a timestamps toggle, wrap, expand or collapse all, and download as plain text
+  (ANSI codes stripped, `fileName`). `controls` picks which are drawn (`['search']`; `[]` leaves
+  the toolbar out). Below `md` of the log's own width, as a container, the search stays and the
+  rest moves into a "More options" menu. `timestamps`, `wrap` and `search` each come with a
+  `default*` and an `on*Change`.
+- **Timestamps.** Off by default. `timestampFormat="clock"` (default) is the time of each line, as
+  `LogViewer` writes it (`locale`, `timeZone`); `"elapsed"` is the time since its step started,
+  `+0:04.2`.
+- **Following.** While a step runs the log stays at the end, pauses when the reader scrolls up,
+  and has a footer button: Pause, then "Jump to latest (12 new)". `follow` / `defaultFollow` /
+  `onFollowChange`. Moving to a line (a `currentLine`, a search match) leaves the end too.
+- **Tone.** `terminal` (default) is a dark panel in every theme, `surface` follows the theme.
+
+**ANSI.** Colour codes are read into styled spans, never HTML. Kept: the 16 colours and their
+bright variants as a foreground and as a background, bold, dim, italic, underline and the resets.
+A 256-colour or truecolor code lands on the nearest of the 16. Every other escape sequence (cursor
+moves, window titles, links) and control character is dropped, and a carriage return keeps only the
+last segment of the line, so a progress bar reads as its last state. Black and white are mapped to
+what reads on the tone (a black text on the terminal panel is the muted gray). Each colour holds
+4.5:1 on both tones in the four themes. On a background colour, the text takes the colour that
+reads on that background and its own is dropped (`31;47` is dark text on a light fill), and dim
+mutes only the default text: a coloured text keeps its colour.
+
+**Accessibility.** The log is a named `region` with a tab stop. A step header is a button with
+`aria-expanded` and `aria-controls`, its status an image with a text name (never a colour alone),
+and the lines of an open step a named group. A line number is a link named "Line 6".
+
+**Limits.**
+
+- The windowing needs a row of a fixed height, so it is off with `wrap`: all the lines of an open
+  step are then drawn (the browser skips the ones out of view). Keep a step to a few thousand lines
+  with `wrap` on. A line link that scrolls out of the window loses the focus.
+- Without `wrap`, the lines of a step scroll sideways inside the step, under its header.
+- A search compiles the plain text of every line of every step: for logs of hundreds of thousands
+  of lines, filter on the host.
+- The labels ("Jump to latest", "More options"…) are English.
+
 ## Slider
 
 `Slider` is a position on a scale, or a range of it. One `value` (with `defaultValue` and
@@ -729,10 +1213,11 @@ the Sidebar does with `collapseControl="sidebar"`.
 Below `lg` the sidebar leaves the layout and the Topbar's hamburger opens it as a 288px
 drawer over a scrim (`defaultSidebarOpen`, or `sidebarOpen` and `onSidebarOpenChange`
 to control it). It is always expanded there, with a close button in `Sidebar.Brand`, and it
-closes on the scrim, Escape, a swipe to the left, a click on a `Sidebar.Item` and when the
+closes on the scrim, Escape, a swipe toward its edge, a click on a `Sidebar.Item` and when the
 viewport grows past `lg`. Pass the product logo as the Topbar's `brand` to keep it in
 view while the sidebar is off screen. Any `Drawer` can close on a swipe too, with
-`swipeToClose`: toward its edge on `left` and `right`, downward on `side="bottom"`, the
+`swipeToClose`: toward its edge on `side="start"` and `side="end"` (the left and right, swapped
+under `dir="rtl"`), downward on `side="bottom"`, the
 bottom sheet (full width, as tall as its content up to 85% of the viewport, a grab `handle`
 you can turn off with `handle={false}`, and a `Drawer.Body` that scrolls past that height).
 
@@ -750,7 +1235,7 @@ drawer, and it does not touch the collapsed state: `onCollapsedChange` is not ca
 toggles keep their state.
 
 `SidebarToggle` is that toggle, to place anywhere else in the Shell (a header of
-your own, the Topbar's `leftActions`, the Sidebar's `footer`) with no props: it
+your own, the Topbar's `startActions`, the Sidebar's `footer`) with no props: it
 reads the Shell's state, and every toggle stays in sync. Outside a Shell, pass it
 `collapsed` and `onCollapsedChange`.
 
@@ -763,6 +1248,78 @@ reads the Shell's state, and every toggle stays in sync. Outside a Shell, pass i
 </Shell>
 ```
 
+### Search in the Topbar
+
+`CommandPaletteTrigger` is a button drawn like a search field (a magnifier, a placeholder and the
+hotkey as a key hint, `⌘K` on Apple platforms and `Ctrl K` elsewhere) that opens a
+`CommandPalette`. It is not an input: the palette holds the field, so a screen reader announces a
+button that opens a dialog. Put it in the Topbar's `center` slot. Below `sm` it is a square icon
+button, and the placeholder stays as its accessible name. `size` takes the form fields' `sm`, `md`
+and `lg`.
+
+The palette owns the hotkey (`hotkey`, `mod+k` by default) and the open state; the button
+registers no listener of its own. Open the palette from its `onClick`, and pass the same hotkey
+as `shortcut` so the hint is the right one (`shortcut={null}` for a palette without a hotkey).
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Topbar
+  pageTitle="Projects"
+  center={<CommandPaletteTrigger placeholder="Search projects" onClick={() => setOpen(true)} />}
+/>
+<CommandPalette open={open} onOpenChange={setOpen}>
+  <CommandPalette.Input placeholder="Search…" />
+  <CommandPalette.List>{/* items */}</CommandPalette.List>
+</CommandPalette>
+```
+
+### Layout modes
+
+`Sidebar variant="compact"` is a fixed 88px rail with the label under each icon, on two lines
+at most (a tooltip carries the full name of a label that is cut). A `Sidebar.SubMenu` opens in a
+flyout, as in the collapsed rail. It has no collapsed state, so `collapsed`, `expandOnHover` and
+the bottom button do nothing: inside a Shell, set `collapseControl="sidebar"` so the Topbar shows
+no hamburger that would do nothing. Below `lg` the drawer shows the default sidebar.
+
+`Shell container="boxed"` centres the topbar, the sidebar and the page in a column of at most
+1440px, with the page background on both sides. `fluid`, the default, spans the window.
+
+A top navigation is a composition: a `Shell` with no `sidebar` and a `Navbar` in `topbar`. Its
+`Navbar.Items` take `Navbar.Item` and `Navbar.Menu`, a dropdown group of links (`Menu.Item` with
+an `href`, a `Menu.Group`, a `Menu.Separator`) that follows the menu button pattern: Enter, Space
+and the arrows open it, the arrows move between the links, Escape closes it and gives the focus
+back to the trigger, Tab leaves it. Mark the group `active` while one of its links is the current
+page, and that link with `aria-current="page"`. Items that do not fit move, from the last, into a
+"More" menu (`moreLabel` renames it) and come back when there is room. Only `Navbar.Item` and
+`Navbar.Menu` placed directly in `Navbar.Items` move; `Navbar.Items` inside a `Navbar.Brand` takes
+the room the bar leaves, and anywhere else it needs a bounded width (`min-w-0 flex-1`) to measure
+against. Below `md` the items leave the bar and `Navbar.MobileMenuButton` opens your own menu.
+
+```tsx
+<Shell
+  container="boxed"
+  topbar={
+    <Navbar>
+      <Navbar.Brand>
+        <Navbar.MobileMenuButton />
+        <Navbar.Items>
+          <Navbar.Item href="/" active>
+            Dashboard
+          </Navbar.Item>
+          <Navbar.Menu label="Settings">
+            <Menu.Item href="/profile">Profile</Menu.Item>
+            <Menu.Item href="/team">Team</Menu.Item>
+          </Navbar.Menu>
+        </Navbar.Items>
+      </Navbar.Brand>
+    </Navbar>
+  }
+>
+  {/* page */}
+</Shell>
+```
+
 ## Split panes
 
 `SplitView` puts two or three `SplitView.Pane` side by side in one bordered frame (mail,
@@ -784,10 +1341,294 @@ place.
 </SplitView>
 ```
 
+## Code
+
+`CodeBlock` shows a snippet with a copy button. It needs no highlighter, and takes a few variants:
+`lineNumbers`, `highlightLines={[3, '5-7']}`, `filename` (a header with the name, the language and
+the copy button), `wrap`, `maxHeight` (the block scrolls inside, takes a Tab stop and scrolls with the
+arrow keys), `diff` (the first column of each line is its sign, `+`, `-` or a space; changes are
+tinted and marked, the sign column is not copied) and `variant="terminal"` (a line starting with
+`$` and a space is a command, the others are its output; only the commands are copied). A block that a long line
+makes scroll sideways is a Tab stop too. The copy button copies the code, never the line numbers, the
+signs or the prompts.
+
+To colour it, use the `/code` entry. It needs [Shiki](https://shiki.style), an optional peer
+dependency that only the apps using this entry install:
+
+```bash
+pnpm add shiki
+```
+
+```tsx
+import { CodeBlock } from '@sckyzo/cosmos-react/code';
+
+<CodeBlock language="yaml" filename="deployment.yaml" code={manifest} lineNumbers />;
+```
+
+The colours are the `--color-code-*` tokens of the theme, so they follow the theme, accent and text
+size. The JavaScript regex engine is used (no WebAssembly), and each language is its own chunk,
+loaded when a block shows it: until then, and for a language Cosmos has no grammar for, the block
+shows plain text. The languages are shell (`bash`, `sh`, `zsh`), `shellsession`, `yaml`, `json`,
+`toml`, `ini`, `dockerfile`, `sql`, `typescript`, `javascript`, `tsx`, `jsx`, `python`, `go`, `html`,
+`xml`, `css`, `diff`, `nginx`, `hcl`, `terraform`, `rust`, `java`, `php`, `markdown` and `promql`.
+A `highlight` prop still replaces the built-in highlighter. The main entry never imports Shiki:
+an app that does not use `/code` ships none of it. Imported without `shiki` installed, a block
+throws an error that names the package.
+
+## Editor
+
+`RichTextEditor` is a formatted text field: bold, italic, strike, headings, bulleted and numbered
+lists, quotes, code, links, undo and redo. It lives in the `/editor` entry and is built on
+[Tiptap](https://tiptap.dev) (MIT), whose packages are optional peer dependencies that only the apps
+using this entry install:
+
+```bash
+pnpm add @tiptap/react @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extensions
+```
+
+```tsx
+import { RichTextEditor } from '@sckyzo/cosmos-react/editor';
+
+<RichTextEditor
+  label="Reply"
+  placeholder="Write a reply…"
+  value={html}
+  onChange={setHtml}
+  maxLength={2000}
+/>;
+```
+
+`value`, `defaultValue` and `onChange` carry HTML by default, or the ProseMirror JSON document with
+`format="json"`; an empty HTML document is `''`. `variant` picks the chrome: `toolbar` (default,
+buttons on top; `toolbar={['bold', 'italic', 'link']}` picks them), `bubble` (a small toolbar over
+the selection; Alt+F10 moves the focus into it, Escape gives it back) or `minimal` (no toolbar, the
+shortcuts and Markdown-like input rules only: `##` and a space, `-` and a space, `**bold**`).
+`labels` replaces every text the editor draws, tooltips included. `readOnly`, `disabled`, `rows`,
+`autoFocus` and `name` (a hidden input, for a native form) work as on a Textarea, and so do `label`,
+`description`, `error` and `required`: the label and the error are linked to the editable text.
+`maxLength` counts the text characters and stops typing and pasting at the limit.
+
+Links accept `http(s):`, `mailto:` and relative URLs only: a
+`javascript:` link is refused whether it is typed in the link field, typed as Markdown, pasted or
+passed in `value`. The schema holds paragraphs, headings 2 and 3, lists, quotes, hard breaks and the
+marks above; images, tables and anything else are dropped on paste. **That is the editor's
+guarantee, not yours: sanitise the stored HTML again on the server before you render it elsewhere.**
+The main entry never imports Tiptap: an app that does not use `/editor` ships none of it.
+
+## Map
+
+`MapView` draws places on a map: pins in the theme's colours with an icon or a number, a popup per
+pin, groups of close pins as a counted circle, zoom buttons and a fit to the markers. It lives in
+the `/map` entry and needs [MapLibre GL JS](https://maplibre.org) (BSD-3), an optional peer
+dependency that only the apps using this entry install:
+
+```bash
+pnpm add maplibre-gl
+```
+
+MapLibre draws in a web worker. Since `maplibre-gl` 6, an app built with a bundler tells it where
+the worker is, once, before the first map; without that the map stays empty. With Vite:
+
+```ts
+import { setWorkerUrl } from 'maplibre-gl';
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+
+setWorkerUrl(workerUrl);
+```
+
+MapLibre's [installation guide](https://maplibre.org/maplibre-gl-js/docs/#installation) gives the
+line for webpack, Rollup, esbuild and Next.js, and the extra setting for server rendering.
+`maplibre-gl` 5 needs none of this.
+
+Load MapLibre's stylesheet once in the app, and import the component from `/map`:
+
+```tsx
+import { useState } from 'react';
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { MapMarkerList, MapView, type MapMarker } from '@sckyzo/cosmos-react/map';
+
+const stores: MapMarker[] = [
+  { id: 'harbour', label: 'Harbour', position: [4.81, 45.71], description: '12 quay street' },
+  { id: 'station', label: 'Station', position: [4.9, 45.75], intent: 'success', icon: 3 },
+];
+
+export const Stores = () => {
+  const [selected, setSelected] = useState<string | null>(null);
+  return (
+    <>
+      <MapMarkerList markers={stores} selectedId={selected} onSelect={setSelected} />
+      <MapView
+        markers={stores}
+        style="https://tiles.example.com/styles/light.json"
+        darkStyle="https://tiles.example.com/styles/dark.json"
+        ariaLabel="Stores"
+        selectedId={selected}
+        onSelectedIdChange={setSelected}
+      />
+    </>
+  );
+};
+```
+
+- **The base map is yours.** Cosmos ships no tiles: a tile server has its own terms and sees every
+  visitor. `style` is a MapLibre style (a URL or an object) and its attribution stays visible.
+  `darkStyle` is optional: under the dark themes (`.dark`, `.deep-blue`) the map switches to it,
+  and without it keeps `style`. Pass constants, not a new object on each render. A markers array
+  is the same: define it once, or the pins are redrawn each time.
+- **Pins, popups and buttons are React and HTML**, coloured by `intent` with the theme's classes,
+  so a theme, accent or text size switch repaints them with no code. A title or description with
+  markup shows as text.
+- **`variant="static"`** is a fixed view for a card or a detail page: no gesture, no zoom buttons,
+  no focus stop, no popup, and the pins are pictures.
+- **Keyboard and screen readers.** The interactive map is one focus stop with the name given by
+  `ariaLabel`: the arrow keys pan, `+` and `-` zoom. A map alone cannot be used with a screen
+  reader, so show the same `markers` as a `MapMarkerList` next to it: choosing a row opens the
+  popup on the map. On a static map, the list is the only way to the places.
+- `cluster` (default on) groups close pins; a click on a group zooms in to split it. `fit` frames
+  the markers on the first draw and when the set of markers changes; otherwise `initialCenter` and
+  `initialZoom` give the view. `onViewChange` reports each pan or zoom.
+- A browser without WebGL shows `unavailableMessage` in place of the map. The main entry never
+  imports MapLibre: an app that does not use `/map` ships none of it. Imported without
+  `maplibre-gl` installed, a map throws an error that names the package.
+
+## Right to left
+
+Set the native `dir` attribute on `<html>`, or on any ancestor of the components, and
+they follow it. There is no prop and no `data-` attribute:
+
+```html
+<html lang="ar" dir="rtl"></html>
+```
+
+What mirrors is what follows the reading direction: the side an icon, a ribbon, a floating
+panel or a status dot sits on, the padding and margins, the corners of a button group, a
+chevron that points forward, the `start` and `end` alignments of panels. A prop that names
+a side of the line takes `start` or `end`, never `left` or `right` (`Ribbon`'s
+`position="top-end"`, `BackToTopFab`'s `position="bottom-end"`, `iconPosition="start"`,
+`align="end"`), so the side swaps under `dir="rtl"`. `top` and `bottom` stay as they are.
+Left to right renders as it always did.
+
+Text that comes from you and sits inside a label or a sentence (a name, a value, a key) is
+wrapped in `<bdi>`, so a Latin name in an Arabic page, or the reverse, keeps its own order
+and does not drag the punctuation around it. The package's own copy stays in English, as it
+is everywhere else. A Latin text cut short by an ellipsis in a right-to-left page (a long file
+name in a narrow tile) shows its end rather than its beginning: the line ends on the left, where
+Latin text starts.
+
+What you put in a slot (a table cell, a card's title, a list item, a toast's message) is drawn
+as you pass it. A Latin value that starts with a number reorders in a right-to-left line, "248 W"
+showing as "W 248": wrap it in `<bdi>` yourself.
+
+```tsx
+<TableCell>
+  <bdi>248 W</bdi>
+</TableCell>
+```
+
+A text field (`Input`, `SearchInput`, `Textarea`, the inputs of `Combobox`, `MultiSelect` and
+`TagInput`) follows the direction of what is typed in it: Arabic aligns and flows right to
+left, a URL left to right, each paragraph of a `Textarea` on its own. It does that with
+`unicode-bidi: plaintext` rather than `dir="auto"`, which would also turn the field's own
+direction around for a Latin text and leave the room reserved for a trailing icon or button
+on the wrong side. A `PasswordInput` does the same once its value is shown; hidden, it keeps
+the page's direction, as HTML leaves password fields out of `dir="auto"`, so how it aligns
+says nothing of what is typed. A value that is a code reads left to right in any page: the cells of
+`OtpInput`, the country button and number of `PhoneInput`, and the swatch and hex of
+`ColorInput` are `dir="ltr"` islands. `Slider` and `Calendar` hand the direction to Radix and
+react-day-picker, which lay out the handles and read the arrow keys from a `dir` prop and not
+from the page.
+
+Tailwind's `rtl:` variant (redefined by the theme to follow the nearest `dir`) is the tool
+for what has no logical form, such as `rtl:-scale-x-100` on an arrow. In your own markup,
+prefer the logical utilities (`ms-`, `pe-`, `text-start`, `border-s`, `rounded-e`, `inset-s-`)
+to the physical ones.
+
+A component draws the icon you pass it as it is. An icon that points along the line (a
+forward arrow, a back chevron, undo) turns around through its own class:
+
+```tsx
+import { clsx } from 'clsx';
+import { ArrowRight, type LucideProps } from 'lucide-react';
+
+const Forward = ({ className, ...props }: LucideProps) => (
+  <ArrowRight {...props} className={clsx(className, 'rtl:-scale-x-100')} />
+);
+
+<Button icon={Forward} iconPosition="end">
+  Continue
+</Button>;
+```
+
+The overlays name their sides `start` and `end`, which follow the reading direction: left and
+right under `dir="ltr"`, right and left under `dir="rtl"`. That is `Drawer`'s `side`
+(`start` | `end` | `bottom`, default `end`), the `align` of `Menu`, `Dropdown`, `UserMenu` and
+`NotificationsPanel` (`start` | `end`), and the `position` of `Tooltip` and `Popover.Content`
+(`top` | `bottom` | `start` | `end`). A panel that opens next to a trigger takes the direction of
+that trigger, even though it renders at the end of `<body>`, and flips to the other side as before
+when the screen would cut it. A `Drawer`, a `Modal`, a `ConfirmationModal` and a `CommandPalette` are
+not next to anything: they read the `dir` of `<html>`, so set it there rather than on a wrapper.
+`Toaster` stacks its toasts at the bottom corner at the end of the line (bottom left under
+`dir="rtl"`, from its `dir` prop or `<html>`); sonner's own `position` is a corner of the screen,
+so one you pass is kept as it is. A keyboard shortcut (the `shortcut` of a `Menu.Item`,
+`CommandPalette.Item` or `Tooltip`, the keys of a `HelpOverlay.Shortcut`) keeps the order the keys
+are pressed in.
+
+Two things stay as they are on purpose. A chevron that points down, or turns over when a
+panel opens (`Accordion`), and a trend arrow that points up or down, are not turned around.
+And the arrow keys that move a card across a `KanbanBoard` follow where the columns are, not
+the reading direction: with the first column on the right, ArrowLeft takes the card to the
+next one.
+
+The page layout follows the line too. A `Shell` puts its `Sidebar` at the start (on the right
+under `dir="rtl"`, with its edge, its collapse toggle and the drawer of the phone layout on that
+side) and its `secondary` panel at the end; `SplitView` runs its panes from the start. `Tabs`
+and the settings pickers swap ArrowLeft and ArrowRight with the direction, and a scrolling strip
+fades the side with more to see. The pinned columns of `DataTable` (`pin: 'start'` | `'end'`)
+and `Table`'s `stickyFirstColumn` stick to the start or end edge, with their shadow on the side
+that faces the columns scrolling under them. In a `Chat`, a person's own messages sit at the end
+of the line and the others' at the start, and what was typed in a message or the composer reads in its own script. The `hotkeys` of a
+`RecordPager` are literal keys and do not follow the direction: give Previous the arrow that
+points toward it where the page reads right to left.
+
+Output keeps its order. Code (`CodeBlock`), logs (`LogViewer`, `JobLog`, and the message, fields
+and stack of `LogEntryDetail`) and keyboard keys (`Kbd`) read left to right in any page: they are
+`dir="ltr"` islands, so a number gutter stays at the left of its lines and a log scrolls from the
+left. What surrounds them follows the page: the title bar and copy button of a code block, the
+toolbar and the "Jump to latest" button of a log, the step headers of a `JobLog` (their chevron
+turns around). Time keeps its order too, as the axis of a chart does: `HeartbeatBar` and
+`UptimeBars` draw their oldest mark on the left and their newest on the right in both directions,
+with "N days ago" at the left and "Today" at the right, and ArrowLeft moves to the older mark. A
+percentage, a latency or a count the components write (`99.95%`, `182 ms`, `3 of 12`) is wrapped in
+`<bdi>`, so it reads in order inside an Arabic line.
+
+`Carousel` hands the direction to Embla, which lays the slides out from the end of the line: the
+first slide is at the start, the next one comes in from the end, a swipe follows, and the arrows
+and their chevrons sit on their sides. The play triangle of a `VideoEmbed` points right in both
+directions, as the time of a video runs from the left. `MapView` does not mirror the map; its zoom
+buttons and the popup of a pin follow the page. Arabic and Hebrew labels in the tiles of a map
+need MapLibre's RTL text plugin (`setRTLTextPlugin` in `maplibre-gl`), which a host sets once
+for the page: Cosmos adds no dependency for it. In `RichTextEditor`, each block follows what is
+typed in it (the same `unicode-bidi: plaintext` as a `Textarea`), lists are indented and quotes
+edged on the start side, the arrow keys along the toolbar swap, and the link field reads left to
+right.
+
+The pages follow the same rules. The back arrow of `ResetPasswordForm` and `TwoStepVerificationForm`
+turns around, the address or number a form says it sent the code to is wrapped in `<bdi>`, and
+`AuthLayout`'s `asidePosition` (`start` | `end`) puts the panel at the start or the end of the line.
+
+Every group of the Storybook sidebar is converted: **Atoms**, **Actions**, **Forms**, **Data**,
+**Lists**, **Feedback**, **Overlays**, **Navigation**, **Layout**, **Chat**, **Tables**,
+**Settings**, **Monitoring**, **Media**, **Status**, **Typography**, **Foundations** and
+**Examples**. A check in the repository refuses a physical inline utility (`ml-`, `pr-`, `left-`,
+`text-left`…) in any source file of the package, and every story is rendered right to left in CI.
+In Storybook, the **Direction** menu of the toolbar (`&globals=direction:rtl`) renders any story
+right to left.
+
 ## Themes and accents
 
-The theme is a class on `<html>`; the accent, the font and the text size are
-the `data-accent`, `data-font` and `data-text-size` attributes, see the
+The theme is a class on `<html>`; the accent, the font, the text size, the
+density and the corner radius are the `data-accent`, `data-font`,
+`data-text-size`, `data-density` and `data-radius` attributes, see the
 [theme README](../theme#themes--accents). `AppearanceSettings` renders a picker
 for each, and `applyAppearance` sets them on the document:
 
@@ -801,6 +1642,7 @@ function Appearance() {
     accent: 'blue',
     font: 'outfit',
     textSize: 'md',
+    density: 'default',
   });
   useEffect(() => applyAppearance(appearance), [appearance]);
   const update = (patch: Partial<CosmosAppearance>) => setAppearance((a) => ({ ...a, ...patch }));
@@ -811,17 +1653,18 @@ function Appearance() {
       onAccentChange={(accent) => update({ accent })}
       onFontChange={(font) => update({ font })}
       onTextSizeChange={(textSize) => update({ textSize })}
+      onDensityChange={(density) => update({ density })}
     />
   );
 }
 ```
 
-The font and text size groups show only when their handlers are set. Pass
+The font, text size and density groups show only when their handlers are set. Pass
 `fonts` to offer only the fonts whose CSS the app imports
 (`@sckyzo/cosmos-theme/fonts/<name>`).
 
 For a top bar, `AppearanceMenu` takes the same props and puts the pickers in a
-panel behind an icon button, for example in `Topbar`'s `rightActions`. Set `onReset`
+panel behind an icon button, for example in `Topbar`'s `endActions`. Set `onReset`
 to add a Reset button under the groups.
 
 To offer a **System** choice that follows the device's `prefers-color-scheme`,
@@ -844,9 +1687,63 @@ useEffect(() => {
 
 Saving the choice (local storage, user profile) is left to the app.
 
+`applyAppearance` also takes a `direction` (`'ltr'` or `'rtl'`): it sets `dir="rtl"` on
+`<html>`, and removes `dir` for `ltr`, like the other defaults.
+
 Charts live in a separate package, [`@sckyzo/cosmos-charts`](../charts), so apps
 that don't render charts don't ship a chart library.
 
+### Customizer
+
+`Customizer` is a panel on the end side (a `Drawer`) that puts the choices above in one place,
+plus the shell's layout, sidebar mode and container, with optional presets, a Reset and a
+"Copy config" that copies the value as JSON. It only **holds** the choice: it is controlled
+(`value`, `onChange`, with the whole new value on each click) and applies nothing itself. The
+host applies it on every change:
+
+```tsx
+const [value, setValue] = useState<CustomizerValue>(CUSTOMIZER_DEFAULT_VALUE);
+const [open, setOpen] = useState(false);
+useEffect(() => applyAppearance(value), [value]);
+const { layout, sidebar, container } = { ...CUSTOMIZER_DEFAULT_VALUE, ...value };
+
+<Shell
+  container={container}
+  sidebarCollapsed={sidebar === 'collapsed' || sidebar === 'hover'}
+  topbar={layout === 'horizontal' ? <Navbar>…</Navbar> : <Topbar />}
+  sidebar={
+    layout === 'horizontal' ? undefined : (
+      <Sidebar
+        variant={sidebar === 'compact' ? 'compact' : 'default'}
+        expandOnHover={sidebar === 'hover' ? 'overlay' : false}
+      >
+        …
+      </Sidebar>
+    )
+  }
+>
+  …
+</Shell>
+<Customizer open={open} onClose={() => setOpen(false)} value={value} onChange={setValue} />
+```
+
+| Value                                                                   | What the host does                                                               |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `theme`, `accent`, `font`, `textSize`, `density`, `radius`, `direction` | `applyAppearance(value)`                                                         |
+| `container`                                                             | `Shell`'s `container`                                                            |
+| `sidebar: 'collapsed'`                                                  | `Shell`'s `sidebarCollapsed`                                                     |
+| `sidebar: 'hover'`                                                      | collapsed, plus `Sidebar`'s `expandOnHover="overlay"`                            |
+| `sidebar: 'compact'`                                                    | `Sidebar`'s `variant="compact"` (and `collapseControl="sidebar"` on the `Shell`) |
+| `layout: 'horizontal'`                                                  | a `Navbar` in `Shell`'s `topbar` in place of the `Sidebar`                       |
+
+Keep the `Customizer` outside what `layout` swaps, so the panel keeps its focus as the shell
+re-renders. Cosmos ships no presets: pass `presets` (`{ id, label, value }`, the value being
+a part of the whole) to show the section. `sections` lists the sections to show (a host with a
+fixed layout leaves out `layout`, `sidebar` and `container`), `defaultValue` is what Reset
+restores, and `themes`, `accents`, `fonts`, `textSizes`, `densities` and `radii` narrow the choices as
+they do on `AppearanceSettings`. The `Settings/Customizer` stories wire all of it, with local
+storage.
+
 ## License
 
 MIT — see [LICENSE](../../LICENSE).