division-ds 0.1.2 → 0.2.1

package/public/docs/components/command-palette.md

@@ -0,0 +1,147 @@
+# CommandPalette
+
+> Every action in one place. Press Ctrl+K anywhere, type a few letters, move with the arrow keys and press Enter. Focus (where keyboard input goes) returns to where it was, and then the command runs.
+
+- **Best for:** Every action in one place behind Ctrl+K, with a visible button that opens it too.
+- **Not for:** Searching page content: use Search. A few actions on one control: use DropdownMenu.
+- Organism. Source: `src/components/organisms/command-palette/CommandPalette.tsx`
+- Rendered docs page: `/components/command-palette`
+
+## Import
+
+```tsx
+import { CommandPalette, filterCommands, groupCommands } from 'src/components/organisms/command-palette/CommandPalette'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `commands` | `Command[]` |  | Required. Each has id, label, group, keywords, shortcut, icon and onSelect. |
+| `open` | `boolean` |  | Open state when controlled, meaning your code decides whether it is open. |
+| `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled, meaning the palette keeps track of it itself. |
+| `onOpenChange` | `(open: boolean) => void` |  | Called on every open and close, including Escape and a click on the scrim (the dimmed backdrop). If you refuse the close, the chosen command stays ready to run until the user does anything else in the palette. Closing it yourself later counts as accepting it. |
+| `shortcut` | `boolean` | `true` | Ctrl+K or Cmd+K opens and closes the palette from anywhere. |
+| `label` | `string` | `'Command palette'` | The dialog's accessible name (what a screen reader announces), hidden from view. |
+| `searchLabel` | `string` | `'Search commands'` | The search field's accessible name. |
+| `placeholder` | `string` | `'Type a command or search'` | Shown in the empty search field. |
+| `emptyMessage` | `string` | `'No matching commands'` | Shown when nothing matches the search. |
+| `ref` | `Ref<HTMLInputElement>` |  | The search field, while the palette is open. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Command = {
+  id: string
+  label: string
+  /** Commands with the same group are drawn together under its heading. */
+  group?: string
+  /** Extra words a search matches on. */
+  keywords?: string[]
+  /** A hint shown on the option, e.g. "N". Display only: the palette does not bind it. */
+  shortcut?: string
+  /** Drawn aria-hidden; the label carries the meaning. */
+  icon?: ReactNode
+  onSelect: () => void
+}
+```
+
+```ts
+export type CommandGroup = { group?: string; commands: Command[] }
+```
+
+```ts
+/** Every whitespace-separated term must appear in the label, the group or a keyword, ignoring case.
+ *  A label that starts with the first term ranks first; otherwise the given order holds. */
+export function filterCommands(commands: readonly Command[], query: string): Command[]
+```
+
+```ts
+/** Groups in the order each group first appears; order within a group is kept. */
+export function groupCommands(commands: readonly Command[]): CommandGroup[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Store commands
+
+```tsx
+function StoreCommands() {
+  const [open, setOpen] = useState(false)
+  const [last, setLast] = useState('none')
+  const make = (id: string, label: string, group: string, icon: ReactNode, extra: Partial<Command> = {}): Command => ({
+    id,
+    label,
+    group,
+    icon,
+    onSelect: () => setLast(label),
+    ...extra,
+  })
+  const commands = [
+    make('orders', 'Go to orders', 'Navigate', <Package />, { keywords: ['sales'] }),
+    make('shipments', 'Go to shipments', 'Navigate', <Truck />),
+    make('returns', 'Go to returns', 'Navigate', <Inbox />),
+    make('new-shipment', 'New shipment', 'Create', <Plus />, { shortcut: 'N' }),
+    make('new-product', 'New product', 'Create', <Box />),
+    make('invite', 'Invite a teammate', 'Account', <Users />, { keywords: ['team', 'people'] }),
+    make('settings', 'Open settings', 'Account', <Settings />),
+  ]
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button variant="secondary" aria-keyshortcuts="Control+K Meta+K" onClick={() => setOpen(true)}>
+        Open command palette
+      </Button>
+      <span aria-hidden="true" className="inline-flex gap-1">
+        <Kbd>Ctrl</Kbd>
+        <Kbd>K</Kbd>
+      </span>
+      <p role="status" className="font-mono text-xs text-[var(--color-text-secondary)]">
+        Last command: {last}
+      </p>
+      <CommandPalette commands={commands} open={open} onOpenChange={setOpen} />
+    </div>
+  )
+}
+
+<StoreCommands />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Ctrl` `K` | Opens or closes it from anywhere on the page (Cmd+K on macOS). |
+| `↓` | Next command, wrapping round to the first. |
+| `↑` | Previous command, wrapping round to the last. |
+| `Home` | First command. |
+| `End` | Last command. |
+| `Enter` | Runs the active command. |
+| `Esc` | Closes without running anything. |
+
+## Do
+
+- Name commands as verbs: 'Go to orders', 'New shipment'.
+- Add keywords for the words people actually type.
+- Give it a visible button that opens it too. People won't find a shortcut on its own.
+
+## Don't
+
+- Don't put destructive commands in it without a dialog that asks for confirmation.
+- Don't show a shortcut hint the app doesn't actually set up.
+- Don't put more than one palette on a page. Each one listens for the same Ctrl+K/Cmd+K across the whole page, so a second one fights the first for the shortcut.
+
+## Anatomy
+
+- **Dialog**: Named 'Command palette', with the name hidden from view. Drawn on surface.base with the corner crosshair.
+- **Search field**: A combobox, a text field tied to a list of choices. Focus stays here the whole time.
+- **Listbox**: Named 'Commands'. It's not there at all when nothing matches.
+- **Group**: Named by its heading.
+- **Option**: The active one gets the fill, and the search field points to it as its active descendant, so screen readers announce it while focus stays in the field.
+- **Count**: A status line hidden from view but read by screen readers: '2 commands'.
+- **Shortcut hint**: A Kbd that's hidden from assistive technology (screen readers and similar tools). It's for display only.

package/public/docs/components/data-table.md

@@ -0,0 +1,401 @@
+# DataTable
+
+> Rows of records that people read, compare and sort. It's a real HTML table with a caption, column and row headers, and sortable columns. When there's a job to do, each row gets a checkbox.
+
+- **Best for:** Records people read, compare and sort across columns, with optional bulk selection.
+- **Not for:** A list people scan row by row: use ListItem. A form in every cell.
+- Organism. Source: `src/components/organisms/data-table/DataTable.tsx`
+- Rendered docs page: `/components/data-table`
+
+## Import
+
+```tsx
+import { DataTable, sortRows } from 'src/components/organisms/data-table/DataTable'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `caption` | `string` |  | Required. Names the table and its scroll region. |
+| `hideCaption` | `boolean` | `false` | Hides the caption visually. It still names the table and its scroll region for screen readers. |
+| `columns` | `DataTableColumn<Row>[]` |  | Required. Each column has key, header, cell, sortValue and numeric. |
+| `rows` | `readonly Row[]` |  | Required. |
+| `getRowId` | `(row: Row) => string` |  | Required. |
+| `rowHeader` | `string` |  | Required. The key of the column that heads each row. |
+| `defaultSort` | `DataTableSort` |  | Starts the table sorted. Uncontrolled: the table keeps track of the sort itself after that. |
+| `sort` | `DataTableSort` |  | Controlled sort, meaning your code holds the sort and passes it in. Set it together with onSortChange. A header click then only reports the next sort. |
+| `onSortChange` | `(sort: DataTableSort) => void` |  | Called with the next sort on every header click, whether sort is controlled or not. |
+| `emptyMessage` | `ReactNode` | `'Nothing to show.'` | Shown across every column when rows is empty. |
+| `selectable` | `boolean` | `false` | Turns on the checkbox column. |
+| `rowLabel` | `(row: Row) => string` |  | Required when selectable. Gives each row's checkbox its name. |
+| `selected` | `ReadonlySet<string>` |  | Controlled selection (your code holds it), keyed by getRowId. |
+| `defaultSelected` | `Iterable<string>` |  | The starting selection when it's uncontrolled (the table holds it). |
+| `onSelectedChange` | `(selected: Set<string>) => void` |  | Called with the next selection on every change. |
+| `className` | `string` |  | Goes on the table element. |
+| `ref` | `Ref<HTMLTableElement>` |  | Points at the table element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SortDirection = 'ascending' | 'descending'
+```
+
+```ts
+export type DataTableSort = { key: string; direction: SortDirection }
+```
+
+```ts
+export type DataTableColumn<Row> = {
+  key: string
+  header: string
+  cell: (row: Row) => ReactNode
+  /** Present means sortable: the value rows are ordered by. */
+  sortValue?: (row: Row) => string | number
+  /** Right-aligned, tabular figures. */
+  numeric?: boolean
+}
+```
+
+```ts
+/** Pure and stable: equal rows keep their order in both directions. Strings compare with numeric
+ *  collation, so "2" sorts before "10". */
+export function sortRows<Row>(
+  rows: readonly Row[],
+  sortValue: ((row: Row) => string | number) | undefined,
+  direction: SortDirection
+): Row[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sortable
+
+```tsx
+type Status = 'In transit' | 'Delivered' | 'Held'
+
+type Shipment = { ref: string; destination: string; weight: number; items: number; status: Status }
+
+const SHIPMENTS: Shipment[] = [
+  { ref: 'SHP-201', destination: 'Cluj depot', weight: 8.2, items: 5, status: 'In transit' },
+  { ref: 'SHP-202', destination: 'Arad depot', weight: 14.0, items: 12, status: 'Delivered' },
+  { ref: 'SHP-203', destination: 'Brasov depot', weight: 3.5, items: 2, status: 'Held' },
+  { ref: 'SHP-204', destination: 'Sibiu depot', weight: 22.1, items: 9, status: 'In transit' },
+  { ref: 'SHP-205', destination: 'Oradea depot', weight: 6.0, items: 1, status: 'Delivered' },
+  { ref: 'SHP-206', destination: 'Timisoara depot', weight: 18.4, items: 15, status: 'Held' },
+  { ref: 'SHP-207', destination: 'Iasi depot', weight: 9.9, items: 4, status: 'In transit' },
+  { ref: 'SHP-208', destination: 'Constanta depot', weight: 27.3, items: 20, status: 'Delivered' },
+]
+
+const STATUS_TONE: Record<Status, 'info' | 'ok' | 'warning'> = {
+  'In transit': 'info',
+  Delivered: 'ok',
+  Held: 'warning',
+}
+
+const COLUMNS: DataTableColumn<Shipment>[] = [
+  { key: 'ref', header: 'Reference', cell: s => s.ref, sortValue: s => s.ref },
+  { key: 'destination', header: 'Destination', cell: s => s.destination },
+  { key: 'weight', header: 'Weight (kg)', cell: s => s.weight.toFixed(1), sortValue: s => s.weight, numeric: true },
+  { key: 'items', header: 'Items', cell: s => String(s.items), sortValue: s => s.items, numeric: true },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: s => (
+      <Badge emphasis="solid" tone={STATUS_TONE[s.status]}>
+        {s.status}
+      </Badge>
+    ),
+  },
+]
+
+<DataTable
+  caption="Shipments, sortable"
+  columns={COLUMNS}
+  rows={SHIPMENTS}
+  getRowId={s => s.ref}
+  rowHeader="ref"
+  defaultSort={{ key: 'ref', direction: 'ascending' }}
+/>
+```
+
+### Controlled sort: the page, not the table, keeps track of the sort order
+
+```tsx
+type Status = 'In transit' | 'Delivered' | 'Held'
+
+type Shipment = { ref: string; destination: string; weight: number; items: number; status: Status }
+
+const SHIPMENTS: Shipment[] = [
+  { ref: 'SHP-201', destination: 'Cluj depot', weight: 8.2, items: 5, status: 'In transit' },
+  { ref: 'SHP-202', destination: 'Arad depot', weight: 14.0, items: 12, status: 'Delivered' },
+  { ref: 'SHP-203', destination: 'Brasov depot', weight: 3.5, items: 2, status: 'Held' },
+  { ref: 'SHP-204', destination: 'Sibiu depot', weight: 22.1, items: 9, status: 'In transit' },
+  { ref: 'SHP-205', destination: 'Oradea depot', weight: 6.0, items: 1, status: 'Delivered' },
+  { ref: 'SHP-206', destination: 'Timisoara depot', weight: 18.4, items: 15, status: 'Held' },
+  { ref: 'SHP-207', destination: 'Iasi depot', weight: 9.9, items: 4, status: 'In transit' },
+  { ref: 'SHP-208', destination: 'Constanta depot', weight: 27.3, items: 20, status: 'Delivered' },
+]
+
+const STATUS_TONE: Record<Status, 'info' | 'ok' | 'warning'> = {
+  'In transit': 'info',
+  Delivered: 'ok',
+  Held: 'warning',
+}
+
+const COLUMNS: DataTableColumn<Shipment>[] = [
+  { key: 'ref', header: 'Reference', cell: s => s.ref, sortValue: s => s.ref },
+  { key: 'destination', header: 'Destination', cell: s => s.destination },
+  { key: 'weight', header: 'Weight (kg)', cell: s => s.weight.toFixed(1), sortValue: s => s.weight, numeric: true },
+  { key: 'items', header: 'Items', cell: s => String(s.items), sortValue: s => s.items, numeric: true },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: s => (
+      <Badge emphasis="solid" tone={STATUS_TONE[s.status]}>
+        {s.status}
+      </Badge>
+    ),
+  },
+]
+
+function ControlledSortExample() {
+  const [sort, setSort] = useState<DataTableSort>({ key: 'weight', direction: 'descending' })
+  return (
+    <DataTable
+      caption="Shipments, controlled sort"
+      columns={COLUMNS}
+      rows={SHIPMENTS}
+      getRowId={s => s.ref}
+      rowHeader="ref"
+      sort={sort}
+      onSortChange={setSort}
+    />
+  )
+}
+
+<ControlledSortExample />
+```
+
+### With row selection and an action that applies to every selected row
+
+```tsx
+type Status = 'In transit' | 'Delivered' | 'Held'
+
+type Shipment = { ref: string; destination: string; weight: number; items: number; status: Status }
+
+const SHIPMENTS: Shipment[] = [
+  { ref: 'SHP-201', destination: 'Cluj depot', weight: 8.2, items: 5, status: 'In transit' },
+  { ref: 'SHP-202', destination: 'Arad depot', weight: 14.0, items: 12, status: 'Delivered' },
+  { ref: 'SHP-203', destination: 'Brasov depot', weight: 3.5, items: 2, status: 'Held' },
+  { ref: 'SHP-204', destination: 'Sibiu depot', weight: 22.1, items: 9, status: 'In transit' },
+  { ref: 'SHP-205', destination: 'Oradea depot', weight: 6.0, items: 1, status: 'Delivered' },
+  { ref: 'SHP-206', destination: 'Timisoara depot', weight: 18.4, items: 15, status: 'Held' },
+  { ref: 'SHP-207', destination: 'Iasi depot', weight: 9.9, items: 4, status: 'In transit' },
+  { ref: 'SHP-208', destination: 'Constanta depot', weight: 27.3, items: 20, status: 'Delivered' },
+]
+
+const STATUS_TONE: Record<Status, 'info' | 'ok' | 'warning'> = {
+  'In transit': 'info',
+  Delivered: 'ok',
+  Held: 'warning',
+}
+
+const COLUMNS: DataTableColumn<Shipment>[] = [
+  { key: 'ref', header: 'Reference', cell: s => s.ref, sortValue: s => s.ref },
+  { key: 'destination', header: 'Destination', cell: s => s.destination },
+  { key: 'weight', header: 'Weight (kg)', cell: s => s.weight.toFixed(1), sortValue: s => s.weight, numeric: true },
+  { key: 'items', header: 'Items', cell: s => String(s.items), sortValue: s => s.items, numeric: true },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: s => (
+      <Badge emphasis="solid" tone={STATUS_TONE[s.status]}>
+        {s.status}
+      </Badge>
+    ),
+  },
+]
+
+function BulkExample() {
+  const [rows, setRows] = useState(SHIPMENTS)
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+  const count = selected.size
+
+  const archive = () => {
+    if (count === 0) return
+    setRows(current => current.filter(row => !selected.has(row.ref)))
+    setSelected(new Set())
+  }
+
+  return (
+    <div className="flex flex-col gap-4 w-full">
+      <Button variant="secondary" aria-disabled={count === 0 || undefined} onClick={archive} className="self-start">
+        {count > 0 ? `Archive ${count} shipment${count === 1 ? '' : 's'}` : 'Archive shipments'}
+      </Button>
+      <DataTable
+        caption="Shipments, selectable"
+        columns={COLUMNS}
+        rows={rows}
+        getRowId={s => s.ref}
+        rowHeader="ref"
+        selectable
+        rowLabel={s => s.ref}
+        selected={selected}
+        onSelectedChange={setSelected}
+      />
+    </div>
+  )
+}
+
+<BulkExample />
+```
+
+### With pagination and selection
+
+```tsx
+type Status = 'In transit' | 'Delivered' | 'Held'
+
+type Shipment = { ref: string; destination: string; weight: number; items: number; status: Status }
+
+const SHIPMENTS: Shipment[] = [
+  { ref: 'SHP-201', destination: 'Cluj depot', weight: 8.2, items: 5, status: 'In transit' },
+  { ref: 'SHP-202', destination: 'Arad depot', weight: 14.0, items: 12, status: 'Delivered' },
+  { ref: 'SHP-203', destination: 'Brasov depot', weight: 3.5, items: 2, status: 'Held' },
+  { ref: 'SHP-204', destination: 'Sibiu depot', weight: 22.1, items: 9, status: 'In transit' },
+  { ref: 'SHP-205', destination: 'Oradea depot', weight: 6.0, items: 1, status: 'Delivered' },
+  { ref: 'SHP-206', destination: 'Timisoara depot', weight: 18.4, items: 15, status: 'Held' },
+  { ref: 'SHP-207', destination: 'Iasi depot', weight: 9.9, items: 4, status: 'In transit' },
+  { ref: 'SHP-208', destination: 'Constanta depot', weight: 27.3, items: 20, status: 'Delivered' },
+]
+
+const STATUS_TONE: Record<Status, 'info' | 'ok' | 'warning'> = {
+  'In transit': 'info',
+  Delivered: 'ok',
+  Held: 'warning',
+}
+
+const COLUMNS: DataTableColumn<Shipment>[] = [
+  { key: 'ref', header: 'Reference', cell: s => s.ref, sortValue: s => s.ref },
+  { key: 'destination', header: 'Destination', cell: s => s.destination },
+  { key: 'weight', header: 'Weight (kg)', cell: s => s.weight.toFixed(1), sortValue: s => s.weight, numeric: true },
+  { key: 'items', header: 'Items', cell: s => String(s.items), sortValue: s => s.items, numeric: true },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: s => (
+      <Badge emphasis="solid" tone={STATUS_TONE[s.status]}>
+        {s.status}
+      </Badge>
+    ),
+  },
+]
+
+function PagedExample() {
+  const [perPage, setPerPage] = useState(4)
+  const [page, setPage] = useState(1)
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+  const start = (page - 1) * perPage
+  const visible = SHIPMENTS.slice(start, start + perPage)
+
+  return (
+    <div className="flex flex-col gap-3 w-full">
+      <DataTable
+        caption="Shipments, paged"
+        columns={COLUMNS}
+        rows={visible}
+        getRowId={s => s.ref}
+        rowHeader="ref"
+        selectable
+        rowLabel={s => s.ref}
+        selected={selected}
+        onSelectedChange={setSelected}
+      />
+      <Pagination
+        page={page}
+        pageCount={Math.ceil(SHIPMENTS.length / perPage)}
+        onPageChange={setPage}
+        totalItems={SHIPMENTS.length}
+        pageSize={perPage}
+        onPageSizeChange={size => {
+          setPerPage(size)
+          setPage(1)
+        }}
+        pageSizeOptions={[4, 8, 12]}
+        label="Pagination, shipments"
+      />
+    </div>
+  )
+}
+
+<PagedExample />
+```
+
+### Empty
+
+```tsx
+type Status = 'In transit' | 'Delivered' | 'Held'
+
+type Shipment = { ref: string; destination: string; weight: number; items: number; status: Status }
+
+const STATUS_TONE: Record<Status, 'info' | 'ok' | 'warning'> = {
+  'In transit': 'info',
+  Delivered: 'ok',
+  Held: 'warning',
+}
+
+const COLUMNS: DataTableColumn<Shipment>[] = [
+  { key: 'ref', header: 'Reference', cell: s => s.ref, sortValue: s => s.ref },
+  { key: 'destination', header: 'Destination', cell: s => s.destination },
+  { key: 'weight', header: 'Weight (kg)', cell: s => s.weight.toFixed(1), sortValue: s => s.weight, numeric: true },
+  { key: 'items', header: 'Items', cell: s => String(s.items), sortValue: s => s.items, numeric: true },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: s => (
+      <Badge emphasis="solid" tone={STATUS_TONE[s.status]}>
+        {s.status}
+      </Badge>
+    ),
+  },
+]
+
+<DataTable caption="Returns" columns={COLUMNS} rows={[]} getRowId={s => s.ref} rowHeader="ref" emptyMessage="No returns yet." />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the scroll region, then to each sort button and checkbox in order. |
+| `Enter` | Sorts by that column, or flips its direction. |
+| `Space` | Sorts, or ticks a checkbox. |
+| `←` `→` | Scroll the region sideways while it has focus. |
+
+## Do
+
+- Right-align numbers and mark their column as numeric.
+- Say how many rows there are near the table, and put Pagination below it.
+- Keep a bulk action's button a tab stop (a place the Tab key lands) while nothing is selected, and mark it aria-disabled so screen readers say it's unavailable.
+- You can page or filter the rows freely. Select-all acts on the rows shown and keeps what was selected elsewhere, and the count says how many selected rows are out of view.
+
+## Don't
+
+- Don't make every column sortable. Sort the ones people compare.
+- Don't tint selected or hovered rows. The checkbox and the count already say it.
+- Don't put a form in every cell. That's a different component.
+
+## Anatomy
+
+- **Caption**: Names the table and its scroll region. You can hide it visually and it still works for screen readers.
+- **Scroll region**: It can take keyboard focus, so a wide table scrolls from the keyboard.
+- **Column header**: A sort button when the column sorts. The sorted column carries aria-sort, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers which way it's sorted.
+- **Row header**: The cell from the rowHeader column. It names its row.
+- **Selection**: A checkbox per row, one to select all, and a count above the table. Selected rows don't get a tint.
+- **Empty**: One cell that spans every column.

package/public/docs/components/description-list.md

@@ -0,0 +1,103 @@
+# DescriptionList
+
+> Pairs of a term and its value, all about one thing, in one to three columns. The columns drop away as the space they get narrows. It's a real dl (the HTML description list element): a label in a monospaced font over each value, and a thin line above each pair.
+
+- **Best for:** The fixed fields of one record: serial, firmware, owner, dates.
+- **Not for:** Many records: use DataTable; one headline number: use Stat.
+- Molecule. Source: `src/components/molecules/description-list/DescriptionList.tsx`
+- Rendered docs page: `/components/description-list`
+
+## Import
+
+```tsx
+import { DescriptionList } from 'src/components/molecules/description-list/DescriptionList'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `readonly DescriptionListItem[]` |  | Required. The pairs, in the order people read them. |
+| `columns` | `1 \| 2 \| 3` | `1` | How many columns at full width. It drops to one when the container is narrower than 28rem. |
+| `className` | `string` |  | On the container. |
+| `ref` | `Ref<HTMLDivElement>` |  | Forwarded to the container. |
+| `term (DescriptionListItem)` | `string` |  | Required. The field name: "Serial". |
+| `description (DescriptionListItem)` | `ReactNode` |  | Required. Its value. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type DescriptionListItem = {
+  /** The name of the field: "Serial", "Last seen". Shown as a mono label. */
+  term: string
+  /** Its value: text, a Badge, a Link. */
+  description: ReactNode
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### One column
+
+```tsx
+<div className="w-full max-w-sm">
+  <DescriptionList
+    items={[
+      { term: 'Serial', description: 'HS-4471-B' },
+      { term: 'Status', description: <Badge tone="ok">Online</Badge> },
+      { term: 'Firmware', description: '2.8.1' },
+      { term: 'Last seen', description: '15 Oct, 09:58' },
+    ]}
+  />
+</div>
+```
+
+### Three columns, fewer as the container narrows
+
+```tsx
+<div className="w-full">
+  <DescriptionList
+    columns={3}
+    items={[
+      { term: 'Order', description: 'ORD-2291' },
+      { term: 'Placed', description: '12 Oct 2026' },
+      { term: 'Ships', description: '16 Oct 2026' },
+      { term: 'Depot', description: 'Cluj, bay 4' },
+      { term: 'Carrier', description: 'Regular courier' },
+      { term: 'Weight', description: '22.1 kg' },
+    ]}
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to any link or button inside a description. |
+
+## Do
+
+- Order pairs the way someone reads the record: identity first, then state, then dates.
+- Say "None" or "Not set" for an empty value rather than leaving the description blank.
+- Use two or three columns only for short values; long text reads better in one.
+
+## Don't
+
+- Don't use it for a list of records. That's what DataTable is for.
+- Don't put a form field in a description. A record people can edit is a form.
+- Don't repeat a term inside one list.
+
+## Anatomy
+
+- **Container**: A div with @container (a container query), so the columns follow the width of this box, not of the screen.
+- **List**: A dl laid out as a grid: one column, two from 28rem wide, three from 42rem (as far as columns allows). A rem is the base text size, usually 16 pixels.
+- **Pair**: A div holding one dt (the term) and one dd (its value), with a thin line above.
+- **Term**: The dt, styled as a label: monospaced, uppercase, 11px (pixels).
+- **Description**: The dd, in body text. It holds text, a Badge or a Link.