@karmo-co/drift-kit-reference 0.0.0-stage → 23.4.0

package/manifest/components/switch.md

@@ -0,0 +1,45 @@
+# Switch (`switch`)
+
+An on/off setting that takes effect immediately. Checkbox's label, description, sizes and states on a track and a thumb, with a settings-row treatment of its own.
+
+
+## Anatomy (HTML)
+
+```text
+label.dk-component-switch[data-variant][data-size][data-align]
+  input.dk-component-switch__input          (role="switch")
+  span.dk-component-switch__track            (the thumb is its ::after)
+  span.dk-component-switch__icon             (optional, a settings row)
+  span.dk-component-switch__text
+    span.dk-component-switch__label
+    span.dk-component-switch__desc
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `end` |
+| `data-pseudo-class` | `active`, `focus`, `hover` |
+| `data-size` | `large`, `small` |
+| `data-variant` | `inset`, `plain`, `raised` |
+
+## React
+
+```tsx
+import { Switch } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | The visible label. Optional for the reason Checkbox's is: a switch in a toolbar or a table row takes its name from what it sits in. Without one, pass aria-label or aria-labelledby; a switch with neither announces as "switch, on" and nothing else, which is the one shape to keep hard. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `variant` | `'ghost' \| 'raised' \| 'plain' \| 'inset'` | A container around the row; the switch itself never changes. ghost (the default) has none; raised stands the row on the raised surface with a lift, plain draws an edge around it, inset sinks it into the control fill. |
+| `description` | `ReactNode` | A second line under the label. The control's DESCRIPTION, never part of its name: rendered outside the naming path and wired with aria-describedby, so a reader hears "Weekly summary, switch, on" and then the explanation. |
+| `align` | `'start' \| 'end'` | The control at the far end of the row rather than before the label: the settings-row arrangement, and the half of dk-component-switch-field worth keeping. Presentation only, so the DOM order, the reading order and the tab order are unchanged. The recessed BOX that class also drew is deliberately not here: a padded, bordered container is something a page puts around this component rather than something the component owns. |
+| `icon` | `ReactNode` | A leading glyph, for a settings row that wants one. Decoration: it sits outside the label text and is hidden from assistive technology. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-switch-track-height`, `--dk-component-switch-small-track-height`, `--dk-component-switch-large-track-height`, `--dk-component-switch-track-ratio`, `--dk-component-switch-border-width`, `--dk-component-switch-thumb-inset`, `--dk-component-switch-thumb-radius`, `--dk-component-switch-thumb-shadow`, `--dk-component-switch-thumb-scale-active`, `--dk-component-switch-focus-ring-width`, `--dk-component-switch-gap`, `--dk-component-switch-text-gap`, `--dk-component-switch-group-gap`, `--dk-component-switch-group-legend-gap`, `--dk-component-switch-icon-color`, `--dk-component-switch-icon-size`, `--dk-component-switch-small-icon-size`, `--dk-component-switch-large-icon-size`, `--dk-component-switch-label-font-family`, `--dk-component-switch-label-font-size`, `--dk-component-switch-label-line-height`, `--dk-component-switch-small-label-font-size`, `--dk-component-switch-small-label-line-height`, `--dk-component-switch-large-label-font-size`, `--dk-component-switch-large-label-line-height`, `--dk-component-switch-label-font-weight`, `--dk-component-switch-desc-font-weight`, `--dk-component-switch-surface-default`, `--dk-component-switch-surface-hover`, `--dk-component-switch-surface-active`, `--dk-component-switch-border-default`, `--dk-component-switch-border-hover`, `--dk-component-switch-border-active`, `--dk-component-switch-thumb`, `--dk-component-switch-thumb-hover`, `--dk-component-switch-checked-surface-default`, `--dk-component-switch-checked-surface-hover`, `--dk-component-switch-checked-surface-active`, `--dk-component-switch-checked-border-default`, `--dk-component-switch-checked-border-hover`, `--dk-component-switch-checked-border-active`, `--dk-component-switch-checked-thumb`, `--dk-component-switch-checked-thumb-hover`, `--dk-component-switch-small-container-padding`, `--dk-component-switch-container-padding`, `--dk-component-switch-large-container-padding`, `--dk-component-switch-small-container-radius`, `--dk-component-switch-container-radius`, `--dk-component-switch-large-container-radius`, `--dk-component-switch-container-border-width`, `--dk-component-switch-raised-container-surface`, `--dk-component-switch-raised-container-surface-hover`, `--dk-component-switch-raised-container-border`, `--dk-component-switch-raised-container-border-hover`, `--dk-component-switch-raised-container-shadow`, `--dk-component-switch-plain-container-surface`, `--dk-component-switch-plain-container-surface-hover`, `--dk-component-switch-plain-container-border`, `--dk-component-switch-plain-container-border-hover`, `--dk-component-switch-inset-container-surface`, `--dk-component-switch-inset-container-surface-hover`, `--dk-component-switch-inset-container-shadow`, `--dk-component-switch-halo`, `--dk-component-switch-halo-width`, `--dk-component-switch-ring`, `--dk-component-switch-focus-border`, `--dk-component-switch-disabled-surface`, `--dk-component-switch-disabled-border`, `--dk-component-switch-disabled-thumb`, `--dk-component-switch-disabled-checked-surface`, `--dk-component-switch-disabled-checked-border`, `--dk-component-switch-disabled-checked-thumb`, `--dk-component-switch-label-color`, `--dk-component-switch-desc-color`, `--dk-component-switch-disabled-label-color`, `--dk-component-switch-disabled-desc-color`, `--dk-component-switch-disabled-icon-color`, `--dk-component-switch-duration`, `--dk-component-switch-easing`

package/manifest/components/table.md

@@ -0,0 +1,77 @@
+# Table (`table`)
+
+Rows and columns, as a real <table>. Sorting, selection, sticky edges and the two rows that stand in for rows.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-table__scroll[role=region][tabindex=0][aria-label]
+  table.dk-component-table[data-size][data-zebra][data-sticky-head]
+                           [data-sticky-col][data-interactive]
+    caption.dk-component-table__caption
+    thead > tr > th[scope=col][data-numeric|data-align][aria-sort]
+              > button.dk-component-table__sort > svg.…__sort-icon
+    tbody > tr[data-selected] > td[data-numeric|data-align]
+            tr > td.dk-component-table__empty[colspan]
+            tr > td.dk-component-table__loading[colspan]
+    tfoot > tr > td
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `right` |
+| `data-dk-table-dragging` | (present or absent) |
+| `data-fits` | (present or absent) |
+| `data-interactive` | (present or absent) |
+| `data-nowrap` | (present or absent) |
+| `data-numeric` | (present or absent) |
+| `data-placeholder` | (present or absent) |
+| `data-pressed` | (present or absent) |
+| `data-reorder` | (present or absent) |
+| `data-reordering` | (present or absent) |
+| `data-selected` | (present or absent) |
+| `data-size` | `large`, `small` |
+| `data-sort-ready` | (present or absent) |
+| `data-sticky-col` | (present or absent) |
+| `data-sticky-head` | (present or absent) |
+| `data-tone-fill` | `solid` |
+| `data-zebra` | (present or absent) |
+
+## React
+
+```tsx
+import { Table } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `columns` (required) | `TableColumn[]` |  |
+| `rows` (required) | `TableRow[]` |  |
+| `label` (required) | `string` | The scroll region's accessible name. REQUIRED, and not for form's sake: the box scrolls, so it is focusable, so a screen reader stops on it and has to be able to say what it is. |
+| `caption` | `ReactNode` | A visible description above the table, rendered as its <caption>, which is also how a table announces its own name. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `zebra` | `boolean` |  |
+| `interactive` | `boolean` | The rows respond to the pointer. What makes a row clickable is a real link or button inside it, stretched over the row the way Card does it: this is the feedback, not the behaviour. |
+| `stickyHead` | `boolean` |  |
+| `stickyCol` | `boolean` |  |
+| `sortRows` | `boolean` | Sort the rows that are in the DOM, as well as firing onSort. For a list that is all here already; leave it off when the sort is server-side. |
+| `selectable` | `boolean` |  |
+| `selectAllLabel` | `string` |  |
+| `onSort` | `(detail: { key: string \| null; column: number; direction: TableSortDirection }) => void` | Fires on every header press: ascending, descending, then none, which is the order the rows arrived in. |
+| `reorderable` | `boolean` | Drag a header, or Alt + Left / Right on it, to move its column. React owns the columns, so the behaviour only says what the order should be and this re-renders in it. |
+| `columnOrder` | `string[]` | Controlled order, by column key. Without it the table keeps its own. |
+| `defaultColumnOrder` | `string[]` |  |
+| `onColumnOrderChange` | `(order: string[]) => void` |  |
+| `persistColumnOrder` | `{ key: string; storage?: TableOrderStorage }` | Remember the order in the browser, per key: 'session' for this tab, 'local' across visits. A product saving it to the user's profile would use onColumnOrderChange instead. |
+| `onSelectionChange` | `(detail: { values: string[]; count: number; all: boolean }) => void` | NOT `onSelect`: that name belongs to the DOM's own select event, which <table> inherits, and taking it would shadow a handler a caller might legitimately pass. |
+| `empty` | `ReactNode` | What the table says when it has no rows. A table with an empty body is a header and a silence. |
+| `loading` | `boolean` |  |
+| `loadingLabel` | `string` | The words under the spinner, and what a screen reader hears. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-table-small-padding-y`, `--dk-component-table-padding-y`, `--dk-component-table-large-padding-y`, `--dk-component-table-padding-inline`, `--dk-component-table-head-surface`, `--dk-component-table-head-radius`, `--dk-component-table-head-font-size`, `--dk-component-table-head-line-height`, `--dk-component-table-head-font-weight`, `--dk-component-table-head-color`, `--dk-component-table-font-family`, `--dk-component-table-font-size`, `--dk-component-table-line-height`, `--dk-component-table-large-font-size`, `--dk-component-table-large-line-height`, `--dk-component-table-font-weight`, `--dk-component-table-color`, `--dk-component-table-rule`, `--dk-component-table-rule-width`, `--dk-component-table-row-hover`, `--dk-component-table-row-active`, `--dk-component-table-row-selected`, `--dk-component-table-row-selected-hover`, `--dk-component-table-row-duration`, `--dk-component-table-row-easing`, `--dk-component-table-zebra-mix`, `--dk-component-table-zebra`, `--dk-component-table-sort-icon-size`, `--dk-component-table-sort-gap`, `--dk-component-table-sort-hover`, `--dk-component-table-sort-active`, `--dk-component-table-sort-radius`, `--dk-component-table-sort-color`, `--dk-component-table-sort-color-hover`, `--dk-component-table-sort-color-active`, `--dk-component-table-sort-icon-mix-rest`, `--dk-component-table-sort-icon-mix-hover`, `--dk-component-table-sort-icon-mix-active`, `--dk-component-table-sort-icon-color`, `--dk-component-table-sort-icon-color-hover`, `--dk-component-table-sort-icon-color-active`, `--dk-component-table-sort-icon-sorted-mix-rest`, `--dk-component-table-sort-icon-sorted-mix-hover`, `--dk-component-table-sort-icon-color-sorted`, `--dk-component-table-sort-icon-color-sorted-hover`, `--dk-component-table-sort-icon-color-sorted-active`, `--dk-component-table-empty-color`, `--dk-component-table-empty-padding-y`, `--dk-component-table-loading-padding-bottom`, `--dk-component-table-sticky-offset`, `--dk-component-table-placeholder-surface`, `--dk-component-table-placeholder-border`, `--dk-component-table-placeholder-border-width`, `--dk-component-table-ghost-surface`, `--dk-component-table-ghost-shadow`, `--dk-component-table-ghost-radius`, `--dk-component-table-reorder-duration`, `--dk-component-table-reorder-easing`, `--dk-component-table-drop-duration`, `--dk-component-table-actions-padding-block`, `--dk-component-table-actions-padding-inline`, `--dk-component-table-chip-padding-block`, `--dk-component-table-caption-font-size`, `--dk-component-table-caption-line-height`, `--dk-component-table-caption-color`

package/manifest/components/tabs.md

@@ -0,0 +1,43 @@
+# Tabs (`tabs`)
+
+A strip of tabs that switch between panels of one page, on a hairline with a bar that slides to the selected tab.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-tabs[role="tablist"][data-size]?
+  button.__tab[role="tab"][data-value][aria-selected]
+    span.__icon?
+    span.__label
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-direction` | `back`, `forward` |
+| `data-full-width` | (present or absent) |
+| `data-size` | `large`, `small` |
+
+## React
+
+```tsx
+import { Tabs } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `items` (required) | `TabsItem[]` |  |
+| `'aria-label'` (required) | `string` |  |
+| `value` | `string` | Controlled: the strip shows this one, and a click asks through onChange. It must be one of the items' values; one that matches none leaves the runtime showing the first enabled tab. |
+| `defaultValue` | `string` | Uncontrolled: where it starts; the first enabled tab when absent. |
+| `onChange` | `(value: string) => void` |  |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `fullWidth` | `boolean` | The tabs share the strip's width equally. |
+| `activation` | `'automatic' \| 'manual'` | automatic (the default) selects as the arrows move; manual waits for Enter, Space or a click. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-tabs-height`, `--dk-component-tabs-small-height`, `--dk-component-tabs-large-height`, `--dk-component-tabs-padding-inline`, `--dk-component-tabs-small-padding-inline`, `--dk-component-tabs-large-padding-inline`, `--dk-component-tabs-gap`, `--dk-component-tabs-font-family`, `--dk-component-tabs-font-size`, `--dk-component-tabs-line-height`, `--dk-component-tabs-small-font-size`, `--dk-component-tabs-small-line-height`, `--dk-component-tabs-large-font-size`, `--dk-component-tabs-large-line-height`, `--dk-component-tabs-font-weight`, `--dk-component-tabs-selected-font-weight`, `--dk-component-tabs-icon-size`, `--dk-component-tabs-small-icon-size`, `--dk-component-tabs-large-icon-size`, `--dk-component-tabs-icon-gap`, `--dk-component-tabs-color`, `--dk-component-tabs-color-hover`, `--dk-component-tabs-color-active`, `--dk-component-tabs-selected-color`, `--dk-component-tabs-color-disabled`, `--dk-component-tabs-hairline`, `--dk-component-tabs-hairline-width`, `--dk-component-tabs-underline-thickness`, `--dk-component-tabs-underline-surface`, `--dk-component-tabs-radius`, `--dk-component-tabs-count-size`, `--dk-component-tabs-count-radius`, `--dk-component-tabs-count-font-size`, `--dk-component-tabs-count-font-weight`, `--dk-component-tabs-count-surface`, `--dk-component-tabs-count-color`, `--dk-component-tabs-count-selected-surface`, `--dk-component-tabs-count-selected-color`, `--dk-component-tabs-focus-ring`, `--dk-component-tabs-focus-ring-width`, `--dk-component-tabs-transition-duration`, `--dk-component-tabs-slide-duration`, `--dk-component-tabs-easing`, `--dk-component-tabs-slide-lag`, `--dk-component-tabs-slide-easing`, `--dk-component-tabs-hover-line`, `--dk-component-tabs-hover-line-from`, `--dk-component-tabs-press-scale`, `--dk-component-tabs-press-duration`

package/manifest/components/tag.md

@@ -0,0 +1,43 @@
+# Tag (`tag`)
+
+A label, a category, a status. Six statuses, three variants, and a dot for the column where the word is already there.
+
+
+## Anatomy (HTML)
+
+```text
+span.dk-component-tag[data-status|data-hue][data-variant][data-size]
+  span.dk-component-tag__dot     (optional, aria-hidden)
+  span.dk-component-tag__icon    (optional, aria-hidden, holds an svg)
+  the text
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-hue` | `next1`, `next2`, `next3`, `next4`, `prev1`, `prev2`, `prev3`, `prev4`, `primary` |
+| `data-size` | `large`, `small` |
+| `data-status` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-tone-fill` | `solid` |
+| `data-variant` | `outline`, `solid` |
+
+## React
+
+```tsx
+import { Tag } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `status` | `'neutral' \| 'primary' \| 'success' \| 'error' \| 'warning' \| 'information'` | Neutral when absent, where the component library's Tag defaults to primary. A tag with no status is a label rather than a signal, and a page whose every unmarked label arrives in the brand colour has spent it. |
+| `hue` | `'prev4' \| 'prev3' \| 'prev2' \| 'prev1' \| 'primary' \| 'next1' \| 'next2' \| 'next3' \| 'next4'` | A category colour instead of a status, for departments, series and filters. |
+| `variant` | `'subtle' \| 'solid' \| 'outline'` |  |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `dot` | `boolean` | A coloured circle before the label, for the status that has a word beside it already. Decorative, and hidden from the reader for that reason. |
+| `icon` | `ReactNode` | A glyph before the label. It takes the tag's own colour rather than the status tone: on a tint the text IS the status colour, and on a fill anything else would fail. |
+| `children` | `ReactNode` |  |
+
+## Component tokens
+
+`--dk-component-tag-padding-block`, `--dk-component-tag-padding-inline`, `--dk-component-tag-small-padding-inline`, `--dk-component-tag-large-padding-inline`, `--dk-component-tag-gap`, `--dk-component-tag-font-family`, `--dk-component-tag-font-size`, `--dk-component-tag-line-height`, `--dk-component-tag-small-font-size`, `--dk-component-tag-small-line-height`, `--dk-component-tag-large-font-size`, `--dk-component-tag-large-line-height`, `--dk-component-tag-font-weight`, `--dk-component-tag-icon-size`, `--dk-component-tag-small-icon-size`, `--dk-component-tag-large-icon-size`, `--dk-component-tag-dot-size`, `--dk-component-tag-primary-solid`, `--dk-component-tag-success-solid`, `--dk-component-tag-error-solid`, `--dk-component-tag-warning-solid`, `--dk-component-tag-information-solid`, `--dk-component-tag-radius`, `--dk-component-tag-border-width`

package/manifest/components/textarea.md

@@ -0,0 +1,52 @@
+# Text area (`textarea`)
+
+Several lines of text: notes, messages, comments. Input's field, sized in rows, with auto-grow, a character counter and a submit shortcut.
+
+
+## Anatomy (HTML)
+
+```text
+  div.dk-component-textarea[data-size][data-resize][data-autogrow][data-max-rows]
+                           [data-limit][data-count][data-submit-shortcut]
+    label.dk-component-textarea__label
+    div.dk-component-textarea__field > textarea.dk-component-textarea__control
+    p.dk-component-textarea__caption      optional
+    span.dk-component-textarea__count     runtime, when there is a limit or data-count
+    p.dk-component-textarea__error        optional
+The root is a two-column grid: the label and field span it, the caption
+sits left and the counter right on the same line, the error under both.
+── 
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-autogrow` | (present or absent) |
+| `data-resize` | `none` |
+| `data-size` | `large`, `small` |
+| `data-state` | `over`, `warning` |
+
+## React
+
+```tsx
+import { Textarea } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` |  |
+| `caption` | `ReactNode` | Helper text, wired as the control's description. |
+| `error` | `ReactNode` | The message AND the invalid state, as Input spells it. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `autoGrow` | `boolean` | Grows with the text from rows up to maxRows, then scrolls. |
+| `maxRows` | `number` |  |
+| `resize` | `'vertical' \| 'none'` |  |
+| `limit` | `number` | A SOFT limit: you can go past it, and then it is an error. maxLength is the hard one, the native attribute. Either shows the counter. |
+| `showCount` | `boolean` | The count with no limit. |
+| `submitShortcut` | `boolean` | Cmd or Ctrl + Enter submits the form. |
+| `className` | `string` | On the root. The textarea takes every other native attribute, and the ref, controlled or not. |
+
+## Component tokens
+
+`--dk-component-textarea-gap`, `--dk-component-textarea-count-gap`, `--dk-component-textarea-label-font-family`, `--dk-component-textarea-label-font-size`, `--dk-component-textarea-label-line-height`, `--dk-component-textarea-label-letter-spacing`, `--dk-component-textarea-label-font-weight`, `--dk-component-textarea-font-family`, `--dk-component-textarea-font-weight`, `--dk-component-textarea-small-font-size`, `--dk-component-textarea-small-line-height`, `--dk-component-textarea-font-size`, `--dk-component-textarea-line-height`, `--dk-component-textarea-large-font-size`, `--dk-component-textarea-large-line-height`, `--dk-component-textarea-small-height`, `--dk-component-textarea-height`, `--dk-component-textarea-large-height`, `--dk-component-textarea-small-padding-block`, `--dk-component-textarea-padding-block`, `--dk-component-textarea-large-padding-block`, `--dk-component-textarea-padding-inline`, `--dk-component-textarea-large-padding-inline`, `--dk-component-textarea-radius`, `--dk-component-textarea-border-width`, `--dk-component-textarea-focus-ring-width`, `--dk-component-textarea-caption-font-size`, `--dk-component-textarea-caption-line-height`, `--dk-component-textarea-caption-color`, `--dk-component-textarea-error-color`, `--dk-component-textarea-count-color`, `--dk-component-textarea-count-warning-color`, `--dk-component-textarea-count-over-color`

package/manifest/components/toast.md

@@ -0,0 +1,52 @@
+# Toast (`toast`)
+
+A message that arrives, says one thing and goes: a card with a badge, a title and a description, or a compact one-liner.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-toast[data-status][data-variant="compact"]?[role="status"]
+  div.__panel
+    div.dk-component-feedback-badge?
+    div.__text > p.__title + p.__description?
+    button.dk-component-icon-button.__close?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-counter` | (present or absent) |
+| `data-paused` | (present or absent) |
+| `data-placement` | `bottom-center`, `bottom-left`, `bottom-right`, `top-center`, `top-left`, `top-right` |
+| `data-state` | `leaving` |
+| `data-status` | `error`, `information`, `neutral`, `primary`, `success`, `warning` |
+| `data-variant` | `compact` |
+
+## React
+
+An imperative API rather than a component:
+
+```tsx
+import { toast } from '@karmo-co/drift-kit/react';
+toast.show({ /* options */ });
+```
+
+| Option | Type | Notes |
+|---|---|---|
+| `variant` | `'default' \| 'compact'` |  |
+| `status` | `'primary' \| 'neutral' \| 'success' \| 'error' \| 'warning' \| 'information'` |  |
+| `title` | `string` |  |
+| `description` | `string` |  |
+| `placement` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` |  |
+| `icon` | `boolean \| string` | true for the status glyph, false for none, or kit icon markup. |
+| `dismissible` | `boolean` |  |
+| `counter` | `boolean` |  |
+| `duration` | `number` | ms before it closes itself; 0 keeps it. |
+| `replace` | `boolean` |  |
+| `onClose` | `() => void` |  |
+
+## Component tokens
+
+`--dk-component-toast-max-width`, `--dk-component-toast-compact-max-width`, `--dk-component-toast-radius`, `--dk-component-toast-ring-width`, `--dk-component-toast-compact-border-width`, `--dk-component-toast-ring`, `--dk-component-toast-surface`, `--dk-component-toast-compact-surface`, `--dk-component-toast-shadow`, `--dk-component-toast-padding`, `--dk-component-toast-compact-padding-block`, `--dk-component-toast-compact-padding-start`, `--dk-component-toast-compact-padding-end`, `--dk-component-toast-content-gap`, `--dk-component-toast-compact-gap`, `--dk-component-toast-compact-close-gap`, `--dk-component-toast-gap`, `--dk-component-toast-region-offset`, `--dk-component-toast-region-offset-small`, `--dk-component-toast-slide`, `--dk-component-toast-compact-slide`, `--dk-component-toast-enter-duration`, `--dk-component-toast-exit-duration`, `--dk-component-toast-enter-easing`, `--dk-component-toast-exit-easing`, `--dk-component-toast-compact-enter-duration`, `--dk-component-toast-compact-exit-duration`, `--dk-component-toast-compact-enter-easing`, `--dk-component-toast-title-font-size`, `--dk-component-toast-title-line-height`, `--dk-component-toast-title-font-weight`, `--dk-component-toast-title-color`, `--dk-component-toast-description-color`, `--dk-component-toast-compact-icon-size`, `--dk-component-toast-compact-glyph-size`, `--dk-component-toast-z-index`

package/manifest/components/tooltip.md

@@ -0,0 +1,42 @@
+# Tooltip (`tooltip`)
+
+A floating label for an element that needs one word more than it can show.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-tooltip[role="tooltip"]   (one shared bubble, rendered by the runtime)
+  div.__surface > span.__icon? + span.__label | dl.__rows
+  span.__arrow
+The trigger is any element: [data-dk-tooltip="<text>"], with
+[data-dk-tooltip-placement]?, [data-dk-tooltip-trigger]?, [data-dk-tooltip-delay]?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-placement` | `bottom`, `left`, `right`, `top` |
+| `data-rows` | (present or absent) |
+| `data-total` | (present or absent) |
+
+## React
+
+```tsx
+import { Tooltip } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `content` | `string` | The words. A string, because the runtime reads it from an attribute. Leave it out when `rows` gives a breakdown instead. |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | The preferred side; it flips when there is no room there. |
+| `trigger` | `'hover' \| 'click'` | hover (the default) also shows on focus, so it is reachable by keyboard. click makes it a disclosure for a tip worth opening on purpose. |
+| `icon` | `string` | A glyph name from the icon library, shown before the words. |
+| `delay` | `number` | Milliseconds to rest before it shows. 0 shows at once. |
+| `rows` | `string` | A selector for a <dl> in the page to show as label and value rows, instead of a sentence. |
+| `children` (required) | `ReactElement` | The one element it describes. It keeps its own markup; the tooltip is attributes on it. |
+
+## Component tokens
+
+`--dk-component-tooltip-font-weight`, `--dk-component-tooltip-font-size`, `--dk-component-tooltip-line-height`, `--dk-component-tooltip-max-width`, `--dk-component-tooltip-padding-block`, `--dk-component-tooltip-padding-inline`, `--dk-component-tooltip-radius`, `--dk-component-tooltip-gap`, `--dk-component-tooltip-icon-size`, `--dk-component-tooltip-rows-max-width`, `--dk-component-tooltip-rows-column-gap`, `--dk-component-tooltip-rows-row-gap`, `--dk-component-tooltip-rows-label-weight`, `--dk-component-tooltip-rule-width`, `--dk-component-tooltip-rule-color`, `--dk-component-tooltip-arrow-size`, `--dk-component-tooltip-viewport-gap`, `--dk-component-tooltip-travel`, `--dk-component-tooltip-delay`

package/manifest/components/top-bar.md

@@ -0,0 +1,60 @@
+# Top bar (`top-bar`)
+
+The page's banner: the brand, an optional row of links, and what the page puts at the end, from a help line to the account.
+
+
+## Anatomy (HTML)
+
+```text
+header.dk-component-top-bar[data-variant="glass"]?[data-sticky]?
+  div.__inner
+    a.__brand                  (a dk-component-logo)
+    nav.__links?
+    div.__end                  (help, the account, actions)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-dk-sidebar-open` | (present or absent) |
+| `data-help-compact` | (present or absent) |
+| `data-hidden` | (present or absent) |
+| `data-idle` | (present or absent) |
+| `data-indicator` | (present or absent) |
+| `data-nav-collapsed` | (present or absent) |
+| `data-open` | (present or absent) |
+| `data-phone` | (present or absent) |
+| `data-scrolled` | (present or absent) |
+| `data-sticky` | (present or absent) |
+| `data-variant` | `glass`, `transparent` |
+| `data-width` | `full` |
+
+## React
+
+```tsx
+import { TopBar } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `brand` | `ReactNode` |  |
+| `brandHref` | `string` |  |
+| `brandLabel` | `string` | The brand link's name, when the brand is a picture. |
+| `links` | `TopBarLink[]` |  |
+| `linksLabel` | `string` | The links' landmark name, and the menu button's when they fold. |
+| `help` | `{ icon: ReactNode; title: ReactNode; text: ReactNode }` | The component library's help line: an icon, an overline title and a line with a link in it. |
+| `end` | `ReactNode` | Actions, the account: anything, at the end. |
+| `variant` | `'solid' \| 'glass' \| 'transparent'` |  |
+| `sticky` | `boolean` |  |
+| `hideOnScroll` | `boolean` |  |
+| `fullWidth` | `boolean` | No max width: the bar's contents run edge to edge. |
+| `drawer` | `string` | The id of a drawer Sidebar: a menu button that opens it shows while it is one. |
+| `drawerLabel` | `string` |  |
+| `renderLink` | `(props: TopBarLinkProps) => ReactElement` |  |
+| `theme` | `'light' \| 'dark'` | Dark chrome: 'dark' makes it dark on a light page and one step deeper than a dark one. Everything inside resolves dark, menus included. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-top-bar-height`, `--dk-component-top-bar-padding-inline`, `--dk-component-top-bar-phone-padding-inline`, `--dk-component-top-bar-gap`, `--dk-component-top-bar-max-width`, `--dk-component-top-bar-brand-width`, `--dk-component-top-bar-brand-height`, `--dk-component-top-bar-solid-surface`, `--dk-component-top-bar-glass-surface`, `--dk-component-top-bar-blur`, `--dk-component-top-bar-border`, `--dk-component-top-bar-border-width`, `--dk-component-top-bar-shadow`, `--dk-component-top-bar-z-index`, `--dk-component-top-bar-link-font-family`, `--dk-component-top-bar-link-font-size`, `--dk-component-top-bar-link-line-height`, `--dk-component-top-bar-link-font-weight`, `--dk-component-top-bar-link-padding-block`, `--dk-component-top-bar-link-padding-inline`, `--dk-component-top-bar-link-radius`, `--dk-component-top-bar-link-text`, `--dk-component-top-bar-link-text-hover`, `--dk-component-top-bar-link-text-active`, `--dk-component-top-bar-link-text-current`, `--dk-component-top-bar-link-surface-hover`, `--dk-component-top-bar-link-surface-active`, `--dk-component-top-bar-link-press-scale`, `--dk-component-top-bar-indicator`, `--dk-component-top-bar-indicator-thickness`, `--dk-component-top-bar-focus-ring`, `--dk-component-top-bar-focus-ring-width`, `--dk-component-top-bar-help-gap`, `--dk-component-top-bar-help-icon-size`, `--dk-component-top-bar-help-icon`, `--dk-component-top-bar-help-title-font-size`, `--dk-component-top-bar-help-title-line-height`, `--dk-component-top-bar-help-title-font-weight`, `--dk-component-top-bar-help-title-letter-spacing`, `--dk-component-top-bar-help-title-color`, `--dk-component-top-bar-help-text-font-size`, `--dk-component-top-bar-help-text-line-height`, `--dk-component-top-bar-help-text-color`, `--dk-component-top-bar-help-link`, `--dk-component-top-bar-help-link-hover`, `--dk-component-top-bar-account-ring`, `--dk-component-top-bar-duration`, `--dk-component-top-bar-indicator-duration`, `--dk-component-top-bar-easing`, `--dk-component-top-bar-hide-duration`

package/manifest/components/vehicle.md

@@ -0,0 +1,43 @@
+# Vehicle (`vehicle`)
+
+A photo of a vehicle, from the car-line photo catalogue trimmed to the car: on its own at any size, or stood on a panel the car overflows. 304 models ship with the kit.
+
+
+## Anatomy (HTML)
+
+```text
+figure.dk-component-vehicle[data-variant="plain|showcase"][data-padding][data-size][data-tone][data-tone-fill][data-surface]
+  img.dk-component-vehicle__image[alt]
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-padding` | `large`, `medium`, `small` |
+| `data-size` | `large`, `small` |
+| `data-surface` | (present or absent) |
+| `data-tone` | `none` |
+| `data-variant` | `showcase` |
+
+## React
+
+```tsx
+import { Vehicle } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `src` (required) | `string` | A photo, trimmed to the car: one of drift-kit's vehicle photos (the vehicles export), or a car line's image_url from the vehicle catalogue. |
+| `alt` (required) | `string` | Required. The make and model, or '' when the name sits right beside it. |
+| `variant` | `'plain' \| 'showcase'` | plain (the default) is the photo alone; showcase stands it on a panel whose bottom edge is two thirds down the car. |
+| `padding` | `'none' \| 'small' \| 'medium' \| 'large'` | Plain only: room around the photo, so the car does not touch the edges of what holds it (a card's media): none (the default), small, medium or large, on the responsive spacing tier. |
+| `size` | `'small' \| 'medium' \| 'large'` | Showcase only: the space around the car, 12, 24 (the default) or 32. |
+| `tone` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'information' \| 'inverse'` | Showcase only: the kit tone for the panel; a solid fill with toneFill. |
+| `toneFill` | `'solid'` |  |
+| `surface` | `1 \| 2` | A step down the neutral ladder for the panel. |
+| `className` | `string` | className and style go on the figure, not the image: sizing the figure sizes the photo and its panel together. |
+
+## Component tokens
+
+`--dk-component-vehicle-ratio`, `--dk-component-vehicle-small-padding`, `--dk-component-vehicle-padding`, `--dk-component-vehicle-large-padding`, `--dk-component-vehicle-small-inset`, `--dk-component-vehicle-inset`, `--dk-component-vehicle-large-inset`, `--dk-component-vehicle-headroom`, `--dk-component-vehicle-panel-reach`, `--dk-component-vehicle-radius`, `--dk-component-vehicle-panel`