dowel-ui 0.20.3 → 0.22.0

package/README.md

@@ -11,7 +11,7 @@ A dowel is the hidden peg that joins two boards so the seam does not show. That
 **[Documentation](https://lacodda.github.io/dowel/)** — what everything is and why it is that way.
 **[The stand](https://lacodda.github.io/dowel/stand/)** — every component, live, in either theme and in the accent of any product of the line.
 
-**Status:** v0.20.3 - the theme, the scales, an accent per product, forty-five components - overlays, menus, the command palette and the three ways of saying something happened - and the gates each one passes: axe, the keyboard, a dependency budget and a picture in both themes. Every component has a page of its own on the stand, which remembers the theme and the accent you left it in. Components install from a versioned registry, the docs are served in the form an agent reads, and `dowel check` tells a project what stands between it and the vocabulary. Two products of the line live on it. See the [roadmap](#roadmap).
+**Status:** v0.22.0 - the theme, the scales, an accent per product, fifty-five components - overlays, menus, the command palette, the table, a hundred thousand rows and the three ways of saying something happened - and the gates each one passes: axe, the keyboard, a dependency budget and a picture in both themes. Every component has a page of its own on the stand, which remembers the theme and the accent you left it in. Components install from a versioned registry, the docs are served in the form an agent reads, and `dowel check` tells a project what stands between it and the vocabulary. Two products of the line live on it. See the [roadmap](#roadmap).
 
 ## The theme
 
@@ -98,16 +98,21 @@ snapshot the cross-references point into the same snapshot, so a component and
 the sibling it reuses are the pair that shipped together. See
 [installing from the registry](https://lacodda.github.io/dowel/guides/registry/).
 
-Forty-five of them so far. The everyday ones - Button, Input, Textarea, Panel,
+Fifty-five of them so far. The everyday ones - Button, Input, Textarea, Panel,
 Badge, Chip, Kbd, Spinner, Truncate and Copyable; Field and the three controls
 that answer a question - Checkbox, RadioGroup and Switch; five for a number or
 a judgement - NumberField, Slider, RatingScale, DurationField and
-PasswordField; five for a date or a time - Calendar, DatePicker,
+PasswordField; the harder half of a form - TagInput, FileDrop, ColorField,
+ActionBar and SaveState; five for a date or a time - Calendar, DatePicker,
 DateRangePicker, TimeField and the `calendar-math` under them; the six that
 float above the page - Dialog, ConfirmDialog, Drawer, Popover, PreviewCard and
 Tooltip; four for choosing something - Menu, ContextMenu, Select and Combobox;
 three for finding it - SearchField, CommandPalette and the `useShortcut` behind
-them; and three for saying that something happened: Toast, Alert and Banner.
+them; three for saying that something happened - Toast, Alert and Banner; six
+for showing rows of data - Table, Pagination, PageSize, NumberFormat,
+RelativeTime and the `table-sort` with no React in it; and four for a long list
+or a deep one: VirtualList, TreeView with the `tree-rows` under it, and
+KeyValue.
 
 Those last three are the ones products keep confusing, so each page names all
 four options: a **toast** goes away, an **alert** is still true after a reload,

package/dist/registry.json

@@ -293,7 +293,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -312,7 +312,7 @@
       "description": "A message that stays on the screen, in the flow of the page, about the thing next to it: this field could not be saved, this profile has no axes yet, this export is out of date.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -331,7 +331,7 @@
       "description": "A small piece of state attached to something else: a count, a status, a label. It is not a button and never was - if it can be clicked it is a Chip.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -350,7 +350,7 @@
       "description": "A strip across the top of the application, about the application: you are offline, this build is a preview, your licence expires on Friday, a new version is ready to install.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -370,7 +370,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -404,7 +404,7 @@
       "title": "Calendar",
       "description": "The sums live next door in `calendar-math`, which has no React in it; this is the grid that draws them and the keyboard that moves around it.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/calendar-math.json"
@@ -425,7 +425,7 @@
       "description": "The interesting part is the words. A checkbox on its own is a nine-pixel target that says nothing; wired to a label it is the whole row, and the row is what a finger and a pointer both aim at. So the label is part of the component rather than something a caller remembers to add - the commonest bug in a hand-rolled checkbox is a `<label>` that is next to the input instead of tied to it, which looks identical and does nothing.",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -444,7 +444,7 @@
       "description": "A badge you can act on: a filter that can be removed, a tag with a count, a selected value in a field. The difference from a Badge is entirely about whether something happens when you click it - and if something does, that part is a real `<button>` with a real label, not a decorative cross.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -462,7 +462,7 @@
       "title": "Color-field",
       "description": "Picking a colour for something the product stores: a tag, a project, a calendar. Note what that is *not* - it is not choosing the appearance of the interface. The theme decides that, from one accent, and a field that let a reader repaint the chrome would undo the argument the whole system rests on.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -484,7 +484,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json",
@@ -507,7 +507,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/combobox.json",
@@ -530,7 +530,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -549,7 +549,7 @@
       "description": "The same list of actions as Menu, opened the other way round: by right click, or by a long press on a touch screen, over an *area* rather than from a button. So the trigger is not a control - it is the region the menu belongs to, a row, a canvas, a file tile - and it renders a `<div>`.",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/menu.json"
@@ -569,7 +569,7 @@
       "title": "Copyable",
       "description": "Any text that someone will eventually want to copy - an id, a path, a hash, a token - copied with one click. The rule comes from nitid: if a value is worth showing, it is worth being able to take away, and selecting a monospaced id by hand is a small daily tax.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -587,7 +587,7 @@
       "title": "Date-picker",
       "description": "The trigger is a button rather than a text input, and that is the decision worth stating. A typable date field has to answer \"what does `03/04/26` mean\" in a locale it cannot be sure of, and it answers wrong for half the world; a button showing the date spelled out has no such question. Where typing genuinely matters - a birth date, forty years back - the calendar is the wrong control anyway and a product should reach for a plain field.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/calendar.json",
@@ -610,7 +610,7 @@
       "title": "Date-range-picker",
       "description": "The interesting part is the state between them. After the first click there is a start and no end, and that is not an incomplete range to be hidden or a range of one day - it is the normal middle of the interaction, and the calendar has to show it: the first day marked, the days under the pointer shading as the reader moves, the popup staying open. Products that skip it end up with a picker that seems to do nothing until the second click.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/calendar.json",
@@ -635,7 +635,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -655,7 +655,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -673,7 +673,7 @@
       "title": "Duration-field",
       "description": "The alternative is what products keep building: two number boxes labelled \"hours\" and \"minutes\", which means two tab stops, two validations, and a reader who has to divide 90 minutes in their head before typing. Here they write `1h 30m`, or `90m`, or `1.5h`, and it means the same thing.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -694,7 +694,7 @@
       "description": "Every form is the same four parts repeated: a name for the control, the control, sometimes a hint, and sometimes an error. Written by hand each time, they drift - the label loses its `htmlFor`, the hint is a `<div>` no screen reader mentions, the error appears in red and is announced by nothing at all. This is that arrangement, once.",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -712,7 +712,7 @@
       "title": "File-drop",
       "description": "A place to put files: drag them onto it, or press it and pick them. It takes files and hands them over - it does not upload them. Where they go, with which credentials, retried how - that is the product's transport, and a primitive that owned it would be wrong for every product whose upload does not look like the one it guessed.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -730,7 +730,7 @@
       "title": "Input",
       "description": "A single-line field. It is a plain `<input>` with the line's clothes on, so everything a browser gives an input for free - autofill, spellcheck, the right keyboard on a phone, `type=\"email\"` validation - still works.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -748,7 +748,7 @@
       "title": "Kbd",
       "description": "A key, as printed in a menu or a hint: `Ctrl` `K`. It is a `<kbd>` element because that is what the element is for - a screen reader announces it as keyboard input rather than reading a stray capital letter.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -760,6 +760,25 @@
         }
       ]
     },
+    {
+      "name": "key-value",
+      "type": "registry:ui",
+      "title": "Key-value",
+      "description": "The shape every product builds out of two `<div>`s in a flex row, and the reason it is worth having once: it is a `<dl>`, and the pairing is what a screen reader announces. Two divs read as four unrelated pieces of text - \"Created\", \"2 hours ago\", \"Owner\", \"Ines\" - and nothing says which value belongs to which name. The right element says it for free.",
+      "dependencies": [
+        "class-variance-authority",
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/key-value.tsx",
+          "target": "@ui/key-value.tsx",
+          "type": "registry:ui",
+          "content": "import { createContext, useContext, type HTMLAttributes, type ReactNode } from 'react'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from 'dowel-ui'\n\n/*\n * A list of facts: a name, and what it is.\n *\n * The shape every product builds out of two `<div>`s in a flex row, and the\n * reason it is worth having once: it is a `<dl>`, and the pairing is what a\n * screen reader announces. Two divs read as four unrelated pieces of text -\n * \"Created\", \"2 hours ago\", \"Owner\", \"Ines\" - and nothing says which value\n * belongs to which name. The right element says it for free.\n *\n * Two layouts, and both exist because the same list sits in two places: beside\n * something (a panel of properties, names in one column) and under a heading\n * (a card, name above value). A product moving a panel should not have to\n * change component.\n *\n * The layouts need *different markup*, and that is why the row reads the\n * layout from context rather than taking a prop:\n *\n *   **rows** puts `<dt>`/`<dd>` directly in the grid, so every value lines up\n *   in one column. Wrap each pair in a `<div>` and each pair becomes its own\n *   box - the values then sit at a different place on every line, which is\n *   exactly the ragged look this component exists to stop.\n *\n *   **stacked** wraps each pair, because without a wrapper the column gaps\n *   fall between `dt` and `dd` as readily as between pairs, and a list of six\n *   facts reads as twelve unrelated lines.\n *\n * Both are valid `<dl>`: the spec allows `dt`/`dd` as direct children, and\n * allows a `<div>` per pair. What it does not allow is any other element\n * between them, which is why the pair is a component rather than something the\n * caller assembles.\n */\n\nexport const keyValueVariants = cva('text-sm', {\n  variants: {\n    layout: {\n      rows: 'grid grid-cols-[minmax(0,auto)_minmax(0,1fr)] items-baseline gap-x-4 gap-y-2',\n      stacked: 'flex flex-col gap-3',\n    },\n  },\n  defaultVariants: { layout: 'rows' },\n})\n\ntype Layout = NonNullable<VariantProps<typeof keyValueVariants>['layout']>\n\n/* The row has to know the layout to know whether to wrap. Context rather than\n * a prop on every row: a list whose rows disagree with it is not a thing\n * anyone wants, and repeating the value at each row is how they come to. */\nconst LayoutContext = createContext<Layout>('rows')\n\nexport interface KeyValueProps\n  extends HTMLAttributes<HTMLDListElement>,\n    VariantProps<typeof keyValueVariants> {}\n\nexport function KeyValue({ layout, className, ...props }: KeyValueProps) {\n  return (\n    <LayoutContext.Provider value={layout ?? 'rows'}>\n      <dl className={cn(keyValueVariants({ layout }), className)} {...props} />\n    </LayoutContext.Provider>\n  )\n}\n\nexport interface KeyValueRowProps {\n  /** The name of the fact. */\n  label: ReactNode\n  /** What it is. A node rather than a string: half the values in a real panel\n   * are a Badge, a RelativeTime or a link. */\n  children: ReactNode\n  className?: string\n}\n\n/** One pair. */\nexport function KeyValueRow({ label, children, className }: KeyValueRowProps) {\n  const layout = useContext(LayoutContext)\n\n  const value = <dd className=\"min-w-0 text-text\">{children}</dd>\n\n  // Wrapped, so the column's gap falls between pairs rather than inside one,\n  // and the caller's class dresses the pair as a whole.\n  if (layout === 'stacked') {\n    return (\n      <div className={cn('flex flex-col gap-0.5', className)}>\n        <dt className=\"text-dim\">{label}</dt>\n        {value}\n      </div>\n    )\n  }\n\n  /* Directly in the grid, so every value shares one column - there is no\n   * wrapper here to carry the caller's class, so it dresses the term. That is\n   * the half a caller styles: the value's own appearance comes from whatever\n   * it renders. */\n  return (\n    <>\n      <dt className={cn('text-dim', className)}>{label}</dt>\n      {value}\n    </>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "name": "menu",
       "type": "registry:ui",
@@ -768,7 +787,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -787,7 +806,7 @@
       "description": "A number typed into a text input is a string that happens to look like a number, and every product then writes the same four fixes: strip the letters, clamp to a range, round to a step, and decide what an empty box means. This is those four, once, plus the stepper - because a value with a small range is faster nudged than typed.",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -801,6 +820,64 @@
         }
       ]
     },
+    {
+      "name": "number-format",
+      "type": "registry:ui",
+      "title": "Number-format",
+      "description": "Two things, and the second is the reason this is a component rather than a call to `toLocaleString` at each site.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/number-format.tsx",
+          "target": "@ui/number-format.tsx",
+          "type": "registry:ui",
+          "content": "import type { HTMLAttributes } from 'react'\nimport { cn } from 'dowel-ui'\n\n/*\n * A number, written the way the reader's language writes numbers.\n *\n * Two things, and the second is the reason this is a component rather than a\n * call to `toLocaleString` at each site.\n *\n * **The separators are the reader's.** A thousand is `1,000` here, `1 000`\n * there and `1.000` somewhere else, and the last one is the same string\n * another reader would read as one. `Intl` knows this and a product does not\n * have to.\n *\n * **The figures line up.** `tabular-nums` makes every digit the same width, so\n * a column of numbers has its digits above each other and the eye can compare\n * lengths without reading. Without it a proportional font gives `1` less room\n * than `8`, the column ripples, and the only way to tell 9,999 from 10,000 is\n * to count. This is the part that gets left out, because it looks fine in the\n * one number a developer tries it on and only fails in a column - which is\n * exactly where numbers live.\n *\n * `Intl.NumberFormat` covers plain numbers, currency, percentages and units\n * with the same options object, so those are not four components. What it does\n * not cover is a \"compact\" number that must not lose meaning - `1.2M` is a\n * choice about how much precision the reader is owed, and it is made by the\n * caller, in `notation`.\n *\n * No locale is defaulted. `undefined` means the reader's own, which is what a\n * product almost always wants; passing `'en-US'` to be safe is how a German\n * reader is shown American separators for the life of the product.\n */\n\n/* `style` belongs to both halves of these props and means opposite things:\n * `'currency'` to `Intl`, a CSS object to the DOM. The `Intl` one wins, since\n * it is the option a number component is actually asked for; inline styles are\n * given up in exchange, which costs nothing here - a primitive's appearance is\n * the theme's business, and `className` is still there. */\nexport interface NumberFormatProps\n  extends Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'style'>,\n    Intl.NumberFormatOptions {\n  /* Required, and a number rather than `number | null`. A row with no value\n   * shows whatever the product says absence looks like - a dash, a word, an\n   * empty cell - and that is a decision about the data, not about formatting.\n   * Accepting `null` here would put a default answer to it inside a primitive,\n   * and the default would be wrong wherever absence means something. */\n  value: number\n  /** The reader's own by default. */\n  locale?: string | string[]\n}\n\n/** Format a number without rendering it. For a `title`, an `aria-label`, a\n * CSV, or anywhere the string is needed rather than an element. */\nexport function formatNumber(\n  value: number,\n  locale?: string | string[],\n  options?: Intl.NumberFormatOptions,\n): string {\n  return new Intl.NumberFormat(locale, options).format(value)\n}\n\nexport function NumberFormat({\n  value,\n  locale,\n  className,\n  // Everything `Intl.NumberFormat` understands, pulled out of the props so\n  // what remains can go on the element. Listed rather than inferred, because\n  // the two sets overlap - `style` is a valid option and a valid DOM\n  // attribute, and spreading `style: 'currency'` onto a `<span>` is a runtime\n  // error the type system will not catch.\n  style,\n  currency,\n  currencyDisplay,\n  currencySign,\n  unit,\n  unitDisplay,\n  notation,\n  compactDisplay,\n  signDisplay,\n  useGrouping,\n  minimumIntegerDigits,\n  minimumFractionDigits,\n  maximumFractionDigits,\n  minimumSignificantDigits,\n  maximumSignificantDigits,\n  numberingSystem,\n  ...props\n}: NumberFormatProps) {\n  const formatted = formatNumber(value, locale, {\n    style,\n    currency,\n    currencyDisplay,\n    currencySign,\n    unit,\n    unitDisplay,\n    notation,\n    compactDisplay,\n    signDisplay,\n    useGrouping,\n    minimumIntegerDigits,\n    minimumFractionDigits,\n    maximumFractionDigits,\n    minimumSignificantDigits,\n    maximumSignificantDigits,\n    numberingSystem,\n  })\n\n  return (\n    <span className={cn('tabular-nums', className)} {...props}>\n      {formatted}\n    </span>\n  )\n}\n"
+        }
+      ]
+    },
+    {
+      "name": "page-size",
+      "type": "registry:ui",
+      "title": "Page-size",
+      "description": "Its own file rather than a part of `Pagination`, because the two are needed apart often enough: a list that scrolls for ever wants \"how many to load at a time\" and no page buttons, and a table with a fixed page size wants the buttons and no choice. Together they were also over the size gate, which asked the right question.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [
+        "https://lacodda.github.io/dowel/r/select.json"
+      ],
+      "files": [
+        {
+          "path": "ui/page-size.tsx",
+          "target": "@ui/page-size.tsx",
+          "type": "registry:ui",
+          "content": "import type { ReactNode } from 'react'\nimport { cn } from 'dowel-ui'\nimport { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from './select'\n\n/*\n * How many rows to a page.\n *\n * Its own file rather than a part of `Pagination`, because the two are needed\n * apart often enough: a list that scrolls for ever wants \"how many to load at\n * a time\" and no page buttons, and a table with a fixed page size wants the\n * buttons and no choice. Together they were also over the size gate, which\n * asked the right question.\n *\n * A `Select`, because the line has no native `<select>` anywhere - and this is\n * the control most likely to reintroduce one, since it is three numbers in a\n * box and looks like the case where it would not matter.\n */\n\nexport interface PageSizeProps {\n  pageSize: number\n  options?: number[]\n  onPageSizeChange: (pageSize: number) => void\n  /** Names the control for a screen reader, e.g. \"Rows per page\". */\n  label: string\n  /** The visible label, when there is room for one. */\n  children?: ReactNode\n  className?: string\n}\n\nexport function PageSize({\n  pageSize,\n  options = [10, 25, 50, 100],\n  onPageSizeChange,\n  label,\n  children,\n  className,\n}: PageSizeProps) {\n  return (\n    <div className={cn('flex items-center gap-2 text-sm text-dim', className)}>\n      {children}\n      <Select\n        value={String(pageSize)}\n        onValueChange={(value: unknown) => onPageSizeChange(Number(value))}\n      >\n        <SelectTrigger aria-label={label} className=\"w-auto min-w-16\">\n          <SelectValue />\n        </SelectTrigger>\n        <SelectPopup>\n          {options.map((option) => (\n            <SelectItem key={option} value={String(option)}>\n              {option}\n            </SelectItem>\n          ))}\n        </SelectPopup>\n      </Select>\n    </div>\n  )\n}\n"
+        }
+      ]
+    },
+    {
+      "name": "pagination",
+      "type": "registry:ui",
+      "title": "Pagination",
+      "description": "The arithmetic is exported separately from the component for the same reason `table-sort` is a file of its own: a product that pages on the server needs the page numbers and not the buttons, and computing them a second time in a different place is how the two disagree about where the last page ends.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [
+        "https://lacodda.github.io/dowel/r/button.json"
+      ],
+      "files": [
+        {
+          "path": "ui/pagination.tsx",
+          "target": "@ui/pagination.tsx",
+          "type": "registry:ui",
+          "content": "import { cn } from 'dowel-ui'\nimport { Button } from './button'\n\n/*\n * Paging through a list, and choosing how much of it to see at once.\n *\n * The arithmetic is exported separately from the component for the same reason\n * `table-sort` is a file of its own: a product that pages on the server needs\n * the page numbers and not the buttons, and computing them a second time in a\n * different place is how the two disagree about where the last page ends.\n *\n * Two things this deliberately does not do.\n *\n * It does not fetch, and it does not slice. It is told the page and the total\n * and it says which page was asked for - because whether paging means an\n * `OFFSET` or an `Array.prototype.slice` is the product's business, and a\n * component that guesses gets it wrong for the other one.\n *\n * It does not show every page number. A list of forty pages drawn in full is a\n * row of forty targets nobody aims at; `pageWindow` gives first, last, the\n * neighbourhood of the current page, and a gap where the rest were.\n *\n * How many rows to a page is next door, in `PageSize`. They are two controls\n * that usually sit together and are needed apart often enough to be separate:\n * a list that scrolls for ever wants \"how many to load at a time\" and no page\n * buttons, and a table with a fixed page size wants the buttons and no choice.\n */\n\n/** A step in the row of pages: a page to go to, or the gap where pages were\n * left out. The gap is not a page and is never clickable - rendering it as a\n * disabled button gives a keyboard three stops that lead nowhere. */\nexport type PageStep = number | 'gap'\n\n/** How many pages a list of this size has. At least one: a list with nothing\n * in it is on page 1 of 1, not page 1 of 0, and the second reads as broken. */\nexport function pageCount(total: number, pageSize: number): number {\n  if (pageSize <= 0) return 1\n  return Math.max(1, Math.ceil(total / pageSize))\n}\n\n/** The row of pages to draw: first, last, the current page and its\n * neighbours, with a gap standing in for the rest.\n *\n * `around` is how many pages sit either side of the current one. The row keeps\n * a steady width as the reader pages through it, because a row that grows and\n * shrinks moves the buttons under the pointer.\n */\nexport function pageWindow(page: number, pages: number, around = 1): PageStep[] {\n  const total = Math.max(1, pages)\n  const current = Math.min(Math.max(1, page), total)\n\n  // How many places the row has: first, last, a gap at each end, and the\n  // neighbourhood between them. This is the number the row always fills.\n  const width = around * 2 + 5\n  if (total <= width) {\n    return Array.from({ length: total }, (_, index) => index + 1)\n  }\n\n  /* The row is built to a fixed number of places, and that is the whole\n   * difficulty. A window of a fixed number of *pages* looks right in the\n   * middle and comes up short at the ends, where one of the gaps is not\n   * needed: the row loses a place, and the \"next\" button moves as you use it.\n   *\n   * So the run of middle pages is grown to whatever fills the row - which\n   * depends on how many gaps there are, which depends on where the run sits.\n   * Rather than iterate towards that (it oscillates on the pages either side\n   * of an end, where dropping a gap moves the run and moving the run brings\n   * the gap back), each possible number of gaps is tried and the one that\n   * describes itself is kept.\n   */\n  for (const gaps of [2, 1, 0]) {\n    // Places for pages: the row, less the two ends, less the gaps.\n    const run = width - 2 - gaps\n    if (run > total - 2) continue\n    // Centre the run on the current page, then slide it inside the ends. The\n    // clamp is what pushes the neighbourhood away from an edge rather than\n    // clipping it there.\n    let from = Math.min(Math.max(2, current - Math.floor((run - 1) / 2)), total - run)\n\n    // A gap that stands for a single page is a lie that costs a click: `1 … 3`\n    // hides only page 2, which the row had room for. The fix is to slide the\n    // run onto the end rather than to drop the page: leaving it out silently\n    // is worse than the gap, because then the row says 1 is followed by 3 and\n    // gives no sign that anything is missing.\n    if (from === 3) from = 2\n    if (from + run - 1 === total - 2) from += 1\n    const to = from + run - 1\n\n    const before = from > 2\n    const after = to < total - 1\n    if (Number(before) + Number(after) !== gaps) continue\n\n    const steps: PageStep[] = [1]\n    if (before) steps.push('gap')\n    for (let page = from; page <= to; page += 1) steps.push(page)\n    if (after) steps.push('gap')\n    steps.push(total)\n    return steps\n  }\n\n  // Unreachable for `total > width`: with no gaps the run covers every middle\n  // page, which is the case handled above. Kept so the function has an answer\n  // for every input rather than an implicit `undefined`.\n  return Array.from({ length: total }, (_, index) => index + 1)\n}\n\n/** Which rows this page holds: `[from, to]`, counting from one, for the \"1-20\n * of 97\" a reader is shown. `to` is clamped to the total, so the last page\n * says what it actually holds rather than what a full page would. */\nexport function pageRange(page: number, pageSize: number, total: number): [number, number] {\n  if (total <= 0) return [0, 0]\n  const from = (page - 1) * pageSize + 1\n  return [from, Math.min(page * pageSize, total)]\n}\n\nexport interface PaginationProps {\n  page: number\n  pageSize: number\n  total: number\n  onPageChange: (page: number) => void\n  /** How many pages either side of the current one. */\n  around?: number\n  /** What a screen reader hears for the region and its buttons. Required\n   * rather than defaulted: a default here would be English shipped inside a\n   * primitive, and these are the only words the control has. */\n  labels: PaginationLabels\n  className?: string\n}\n\nexport interface PaginationLabels {\n  /** Names the whole control, e.g. \"Pages\". */\n  region: string\n  previous: string\n  next: string\n  /** Names one page button. Given the number, because \"Page 3\" is a sentence\n   * only the product's language can build. */\n  page: (page: number) => string\n}\n\nexport function Pagination({\n  page,\n  pageSize,\n  total,\n  onPageChange,\n  around = 1,\n  labels,\n  className,\n}: PaginationProps) {\n  const pages = pageCount(total, pageSize)\n  const current = Math.min(Math.max(1, page), pages)\n  const steps = pageWindow(current, pages, around)\n\n  return (\n    <nav aria-label={labels.region} className={cn('flex items-center gap-1', className)}>\n      <Button\n        variant=\"ghost\"\n        size=\"sm\"\n        aria-label={labels.previous}\n        disabled={current <= 1}\n        onClick={() => onPageChange(current - 1)}\n      >\n        ‹\n      </Button>\n\n      {steps.map((step, index) =>\n        step === 'gap' ? (\n          // Not a button, and not `aria-hidden` either: the gap is real\n          // information - there are pages here that are not shown - and a\n          // reader that skips it hears a jump from 2 to 40 with no reason.\n          <span\n            // The index is the key on purpose: two gaps in a row are\n            // indistinguishable, and there is never more than one at each end.\n            key={`gap-${index}`}\n            className=\"px-1 text-dim select-none\"\n          >\n            …\n          </span>\n        ) : (\n          <Button\n            key={step}\n            variant={step === current ? 'primary' : 'ghost'}\n            size=\"sm\"\n            // The current page is announced, not only coloured. `aria-current`\n            // rather than `aria-selected`, which belongs to a listbox.\n            aria-current={step === current ? 'page' : undefined}\n            aria-label={labels.page(step)}\n            onClick={() => onPageChange(step)}\n            className=\"tabular-nums\"\n          >\n            {step}\n          </Button>\n        ),\n      )}\n\n      <Button\n        variant=\"ghost\"\n        size=\"sm\"\n        aria-label={labels.next}\n        disabled={current >= pages}\n        onClick={() => onPageChange(current + 1)}\n      >\n        ›\n      </Button>\n    </nav>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "name": "panel",
       "type": "registry:ui",
@@ -808,7 +885,7 @@
       "description": "The raised surface everything else sits on. It is the one place a screen gets its structure from, so it stays deliberately plain: a ground, a hairline, a corner.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -826,7 +903,7 @@
       "title": "Password-field",
       "description": "The reveal is the whole component, and it is not a convenience. A masked field is the only one in a form where a typo cannot be seen, so people either paste (fine) or type slowly and get it wrong anyway; the toggle is what turns an unverifiable field into a checkable one, and it is why long passphrases became usable at all.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -848,7 +925,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -868,7 +945,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -888,7 +965,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -906,7 +983,7 @@
       "title": "Rating-scale",
       "description": "Generalised from kilna, where it is how a work is scored on each of its axes. The shape is a row of marks rather than stars: stars carry a meaning of their own - a review, a public verdict - and this is as often \"how hard was this\" or \"how finished is it\" as it is \"how good\".",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -918,13 +995,31 @@
         }
       ]
     },
+    {
+      "name": "relative-time",
+      "type": "registry:ui",
+      "title": "Relative-time",
+      "description": "The relative-time primitive.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/relative-time.tsx",
+          "target": "@ui/relative-time.tsx",
+          "type": "registry:ui",
+          "content": "import { useState, type TimeHTMLAttributes } from 'react'\nimport { cn } from 'dowel-ui'\n\n/*\n * \"3 minutes ago\", in the reader's language, over a date they can still read.\n *\n * The rule the component is built on: **relative time is a convenience, never\n * the only copy of the fact.** \"Last week\" is quicker to read than a date and\n * useless the moment the reader needs to say when something actually happened\n * - and they cannot get it back, because the page has thrown it away. So the\n * element is a `<time dateTime=…>` with the exact moment in its `title`: the\n * machine-readable value stays, hovering shows the real date, and copying the\n * text still yields something a person can act on.\n *\n * `Intl.RelativeTimeFormat` writes the phrase, which is the whole reason there\n * is no date library here. \"yesterday\", \"3 недели назад\", \"in 2 months\" - the\n * plural rules and the special words for the nearest units are the part a\n * hand-written version gets wrong first, and it gets it wrong only in the\n * languages its author does not read.\n *\n * What `Intl` does not decide is which unit to use: it is told \"3\" and\n * \"weeks\". Choosing between them is `relativeParts` below, and it is the one\n * piece of arithmetic here.\n *\n * Deliberately not self-updating. A component that re-renders every second to\n * keep \"2 minutes ago\" honest costs a timer per instance - a table of fifty\n * rows is fifty timers - to correct a number nobody is watching change. A\n * product that needs it re-renders the list on its own schedule; the `now`\n * prop is there so it can, and so tests are not written against the clock.\n */\n\n/** The thresholds, largest unit first: how many seconds it takes to earn one,\n * and the unit `Intl` should be handed.\n *\n * A month is 30 days and a year is 365. Both are approximations, and they are\n * the right ones: this is a phrase saying roughly how long ago, and a reader\n * who needs the exact interval is reading the date in the `title` instead. */\nconst UNITS: [seconds: number, unit: Intl.RelativeTimeFormatUnit][] = [\n  [60 * 60 * 24 * 365, 'year'],\n  [60 * 60 * 24 * 30, 'month'],\n  [60 * 60 * 24 * 7, 'week'],\n  [60 * 60 * 24, 'day'],\n  [60 * 60, 'hour'],\n  [60, 'minute'],\n  [1, 'second'],\n]\n\n/** How long ago, as a count and a unit: what `Intl.RelativeTimeFormat` needs.\n *\n * The sign is the one `Intl` wants - negative for the past - and the count is\n * rounded towards zero. Rounding to nearest is the tempting alternative and\n * says \"in 1 hour\" 31 minutes before the meeting; truncating never claims more\n * time has passed than has. */\nexport function relativeParts(\n  from: Date | number | string,\n  now: Date | number = Date.now(),\n): [value: number, unit: Intl.RelativeTimeFormatUnit] {\n  const then = new Date(from).getTime()\n  const seconds = (then - new Date(now).getTime()) / 1000\n  const magnitude = Math.abs(seconds)\n\n  for (const [size, unit] of UNITS) {\n    if (magnitude >= size) return [Math.trunc(seconds / size), unit]\n  }\n  // Under a second either way. Zero seconds rather than the smallest unit,\n  // because `Intl` turns that into \"now\" in every language it knows.\n  return [0, 'second']\n}\n\n/** The phrase alone, for a `title`, an `aria-label` or a string. */\nexport function formatRelative(\n  from: Date | number | string,\n  now: Date | number = Date.now(),\n  locale?: string | string[],\n  options?: Intl.RelativeTimeFormatOptions,\n): string {\n  const [value, unit] = relativeParts(from, now)\n  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto', ...options }).format(value, unit)\n}\n\nexport interface RelativeTimeProps extends Omit<TimeHTMLAttributes<HTMLTimeElement>, 'title'> {\n  /** The moment being described. A `Date`, epoch milliseconds, or an ISO\n   * string - whichever the data already holds. */\n  value: Date | number | string\n  /** What counts as now. Given rather than read from the clock so a list can\n   * re-render on its own schedule, and so a test is not written against the\n   * time it runs at. */\n  now?: Date | number\n  locale?: string | string[]\n  /** `'auto'` by default, which is what produces \"yesterday\" rather than \"1\n   * day ago\" where the language has a word for it. Pass `'always'` for a\n   * column where every row should read the same way. */\n  numeric?: Intl.RelativeTimeFormatOptions['numeric']\n  /** How the exact moment is written in the `title`. The reader's own format\n   * by default. */\n  titleOptions?: Intl.DateTimeFormatOptions\n}\n\nexport function RelativeTime({\n  value,\n  now,\n  locale,\n  numeric = 'auto',\n  titleOptions = { dateStyle: 'medium', timeStyle: 'short' },\n  className,\n  ...props\n}: RelativeTimeProps) {\n  /* Read once, at mount, rather than in a default argument.\n   *\n   * `now = Date.now()` in the parameter list is the obvious spelling and is\n   * impure: it is evaluated on every render, so \"now\" moves whenever the\n   * parent happens to re-render and the phrase changes for reasons that have\n   * nothing to do with this component. Caught by `react-hooks/purity`, and\n   * worth keeping caught - a component that deliberately does not update\n   * itself must not update itself by accident either.\n   *\n   * With `now` given, the state is initialised and never read, which is what a\n   * product paging a list wants: every row is measured from the same moment. */\n  const [mountedAt] = useState(() => Date.now())\n  const moment = new Date(value)\n  const invalid = Number.isNaN(moment.getTime())\n\n  if (invalid) {\n    // A date that is not a date renders as nothing rather than as \"Invalid\n    // Date\", which is a string no reader can do anything with and which looks\n    // like a value. The `<time>` element with no `dateTime` says the same to a\n    // machine: there is no moment here.\n    return <time className={className} {...props} />\n  }\n\n  return (\n    <time\n      dateTime={moment.toISOString()}\n      // The fact itself, kept. The phrase above it is the convenience.\n      title={new Intl.DateTimeFormat(locale, titleOptions).format(moment)}\n      className={cn('whitespace-nowrap', className)}\n      {...props}\n    >\n      {formatRelative(moment, now ?? mountedAt, locale, { numeric })}\n    </time>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "name": "save-state",
       "type": "registry:ui",
       "title": "Save-state",
       "description": "The quiet line beside a field that saves itself: \"saving…\", then a tick that fades. It exists because a form without a Save button has to say what it did anyway - otherwise the reader is left guessing whether their edit survived, and the usual answer to that guess is to press Ctrl+S at a page that has no such thing.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/spinner.json"
@@ -944,7 +1039,7 @@
       "title": "Search-field",
       "description": "An Input that knows it is a search box, which is three small things the products kept not doing:\n *   - a magnifier, so the field is recognisable before it is read;   - a way to clear it that is not \"select all and delete\" - and one that a     keyboard can reach, which a decorative `<span>` cannot;   - the shortcut that focuses it, shown in the field rather than learned.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json",
@@ -968,7 +1063,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1005,7 +1100,7 @@
       "description": "The case for it over a NumberField is that the number does not matter much: a volume, an opacity, a weight in a search filter. Where the exact figure does matter, a slider is a worse field with more pixels - it cannot be typed into, it cannot be pasted into, and it has no state for \"empty\".",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1024,7 +1119,7 @@
       "description": "Something is happening and the answer has not arrived. It carries no text of its own - what is loading is the product's word, not the system's - but it does have to say *something* to a screen reader, or a page that is busy is silently identical to a page that is empty.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1043,7 +1138,7 @@
       "description": "The difference from Checkbox is not how it looks, and getting it wrong is the commonest mistake in the pair. A checkbox is an answer collected now and submitted later, with the rest of the form; a switch is a setting that applies the moment it moves. Put a switch in a form with a Save button and the reader cannot tell whether anything happened - they flipped it, and nothing said so.",
       "dependencies": [
         "@base-ui/react",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1055,6 +1150,43 @@
         }
       ]
     },
+    {
+      "name": "table-sort",
+      "type": "registry:ui",
+      "title": "Table-sort",
+      "description": "Split out of the Table for the reason `calendar-math` was split out of the Calendar: these are the sums, and the component is the thing that draws them. A product sorting its own rows - on the server, in a worker, before the data ever reaches a component - imports this and nothing else.",
+      "dependencies": [],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/table-sort.tsx",
+          "target": "@ui/table-sort.tsx",
+          "type": "registry:ui",
+          "content": "/*\n * How a column is ordered, with no React in it.\n *\n * Split out of the Table for the reason `calendar-math` was split out of the\n * Calendar: these are the sums, and the component is the thing that draws\n * them. A product sorting its own rows - on the server, in a worker, before\n * the data ever reaches a component - imports this and nothing else.\n *\n * No table library, deliberately. The obvious choice here is TanStack Table,\n * and it would be the first dependency a product has to install beyond Base\n * UI. What it offers is a model of columns, pages and sorting state; what the\n * line's one real table needed was the rule below, which the model does not\n * have. So the model is the part that is written here, and it is small.\n *\n * The rule, and the reason this file exists at all:\n *\n *   **Absence sorts last, whichever way the column points.**\n *\n * A row with no value in this column is not the smallest - it is unknown, and\n * the two are different facts. Rank absence with the rest and flip the sign,\n * and a descending sort floats every empty row to the top: the reader asks for\n * \"highest first\" and is handed the rows that have no value at all. This is\n * measured rather than assumed - it is what the first version of the line's\n * catalogue did, and the fix is the shape below, where presence is settled\n * before the direction is applied.\n *\n * It is the same fact `RatingScale` is built on: not judged yet is a state,\n * not a zero. A table that sorts them together loses it on the first click.\n */\n\n/** Which way a column points. */\nexport type SortDirection = 'asc' | 'desc'\n\n/** A column, and which way it points. `column` is the caller's own key - the\n * id it gave the column, not an index, so reordering columns cannot silently\n * change what is sorted. */\nexport interface Sort<Column extends string = string> {\n  column: Column\n  direction: SortDirection\n}\n\n/** What can be compared. `null` and `undefined` both mean absent - a product\n * gets whichever its data uses, and having to normalise them before sorting\n * is the kind of step that gets forgotten in one branch of a switch. */\nexport type SortValue = string | number | boolean | null | undefined\n\n/** Reads the value of a column out of a row.\n *\n * Given rather than inferred: a column id is not always a field name, and a\n * sortable column is often a computed one - a duration that is stored as two\n * timestamps, a name that sorts by surname. */\nexport type SortAccessor<Row, Column extends string = string> = (\n  row: Row,\n  column: Column,\n) => SortValue\n\nexport interface SortOptions<Row> {\n  /** The tiebreaker: what decides the order of rows that compare equal.\n   *\n   * Without one, `Array.prototype.sort` is stable and therefore leaves ties in\n   * input order - which sounds fine until the input is re-fetched and arrives\n   * in a different order, and a column of ties reshuffles under the reader\n   * with no click. Pass the row's id. */\n  tiebreak?: (row: Row) => SortValue\n  /** The locale text is compared in. Passed to `Intl.Collator`, so `ä` sorts\n   * where the reader expects rather than after `z`. */\n  locale?: string\n}\n\n/** Order the rows. Returns a new array; the input is not touched, because a\n * component that sorts its own prop in place mutates the caller's state. */\nexport function sortRows<Row, Column extends string = string>(\n  rows: readonly Row[],\n  sort: Sort<Column>,\n  accessor: SortAccessor<Row, Column>,\n  options: SortOptions<Row> = {},\n): Row[] {\n  const sign = sort.direction === 'asc' ? 1 : -1\n  // One collator for the whole sort rather than one `localeCompare` per\n  // comparison: building it is the expensive half, and a sort of n rows asks\n  // for it n log n times.\n  const collator = new Intl.Collator(options.locale)\n\n  return [...rows].sort((a, b) => {\n    const left = accessor(a, sort.column)\n    const right = accessor(b, sort.column)\n\n    // Presence first, and outside the sign. This is the whole point of the\n    // file: absence is last in both directions.\n    const absent = presence(left, right)\n    if (absent !== 0) return absent\n\n    const ranked = compareValues(left, right, collator) * sign\n    if (ranked !== 0) return ranked\n\n    if (options.tiebreak) {\n      const tied = compareValues(options.tiebreak(a), options.tiebreak(b), collator)\n      // Deliberately not multiplied by the sign. The tiebreaker is there to\n      // make the order stable, and an order that reverses with the column is\n      // not stable - the rows that tie would swap places on every click.\n      if (tied !== 0) return tied\n    }\n    return 0\n  })\n}\n\n/** Whether a value counts as absent.\n *\n * Both spellings of nothing, and neither `0` nor `''` nor `false`, which are\n * values a row genuinely has.\n *\n * `NaN` counts too, and that is not tidiness. Subtraction with it returns\n * `NaN`, which `sort` reads as \"these two are equal\" - so a row whose number\n * is not a number takes whatever place the input happened to give it, and the\n * order changes when the data is re-fetched. A number that is not a number is\n * not a small number; it is unknown, which is what this file already has a\n * place for. */\nexport function isAbsent(value: SortValue): boolean {\n  if (value === null || value === undefined) return true\n  return typeof value === 'number' && Number.isNaN(value)\n}\n\n/** Which of the two lacks a value; absent sorts last, always. */\nfunction presence(left: SortValue, right: SortValue): number {\n  const leftHas = !isAbsent(left)\n  const rightHas = !isAbsent(right)\n  if (leftHas === rightHas) return 0\n  return leftHas ? -1 : 1\n}\n\n/** Compare two present values of the same column.\n *\n * Numbers by subtraction, text by collator, and booleans as false-then-true.\n * A column whose values are of mixed type compares as text: that is a data\n * problem the table cannot fix, and ordering by `String` at least gives the\n * same answer twice. */\nfunction compareValues(left: SortValue, right: SortValue, collator: Intl.Collator): number {\n  if (isAbsent(left) || isAbsent(right)) return presence(left, right)\n\n  // NaN never reaches here: `isAbsent` counts it as absent, so `presence`\n  // settles it above, outside the sign.\n  if (typeof left === 'number' && typeof right === 'number') return left - right\n  if (typeof left === 'boolean' && typeof right === 'boolean') {\n    return Number(left) - Number(right)\n  }\n  return collator.compare(String(left), String(right))\n}\n\n/** What clicking a column heading does.\n *\n * Three states rather than two, and the third is the reason this is a function\n * and not `direction === 'asc' ? 'desc' : 'asc'`: clicking a *different*\n * column starts it ascending rather than inheriting the direction of the one\n * before. Inheriting is what a two-state toggle does, and it means the first\n * click on a new column can hand back an order nobody asked for. */\nexport function toggleSort<Column extends string>(\n  sort: Sort<Column>,\n  column: Column,\n): Sort<Column> {\n  if (sort.column !== column) return { column, direction: 'asc' }\n  return { column, direction: sort.direction === 'asc' ? 'desc' : 'asc' }\n}\n\n/** What a column heading announces: `ascending`, `descending`, or nothing.\n *\n * The value belongs in `aria-sort` on the `<th>`, and only on the one that is\n * sorted - `aria-sort=\"none\"` on every other heading is allowed by the spec\n * and read out by some screen readers on every cell, which turns a table into\n * a recital. `undefined` removes the attribute. */\nexport function ariaSort(\n  sort: Sort<string> | undefined,\n  column: string,\n): 'ascending' | 'descending' | undefined {\n  if (!sort || sort.column !== column) return undefined\n  return sort.direction === 'asc' ? 'ascending' : 'descending'\n}\n"
+        }
+      ]
+    },
+    {
+      "name": "table",
+      "type": "registry:ui",
+      "title": "Table",
+      "description": "Parts rather than a `columns` prop, and that is the decision worth stating: a `<DataTable columns={…} rows={…} />` is quicker to write for the first table and then owns every cell in the product forever. The moment one column needs a Badge, another a link, and a third the row's own menu, the prop grows a `render` for each - at which point it is JSX with extra steps, spelt in a shape only this component understands.",
+      "dependencies": [
+        "class-variance-authority",
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [
+        "https://lacodda.github.io/dowel/r/table-sort.json"
+      ],
+      "files": [
+        {
+          "path": "ui/table.tsx",
+          "target": "@ui/table.tsx",
+          "type": "registry:ui",
+          "content": "import type { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from 'dowel-ui'\nimport { ariaSort, type Sort } from './table-sort'\n\n/*\n * A table of rows, and the heading that reorders them.\n *\n * Parts rather than a `columns` prop, and that is the decision worth stating:\n * a `<DataTable columns={…} rows={…} />` is quicker to write for the first\n * table and then owns every cell in the product forever. The moment one column\n * needs a Badge, another a link, and a third the row's own menu, the prop\n * grows a `render` for each - at which point it is JSX with extra steps, spelt\n * in a shape only this component understands.\n *\n * So the parts are the ones HTML already has, dressed: a caller writes\n * `<TableRow>` and `<TableCell>` and puts whatever it likes inside. What is\n * bought by having them here rather than in the product is that every table of\n * the line has the same row height, the same heading, the same hairline and\n * the same behaviour when a column is sorted - and that a heading that sorts\n * announces it, which is the part hand-rolled tables get wrong.\n *\n * The sorting arithmetic is next door in `table-sort`, with no React in it -\n * a product that sorts on the server imports that and never this.\n *\n * `<TableScroll>` exists because a table cannot scroll itself: `overflow` on a\n * `<table>` does nothing, so the wrapper is not decoration but the only place\n * a scrollbar can live. It is also what makes the sticky heading work, since\n * `position: sticky` needs a scroll container to stick inside.\n */\n\nexport const tableVariants = cva('w-full border-collapse text-left text-sm', {\n  variants: {\n    density: {\n      /* Comfortable, and the default: a row a finger can hit, for a table a\n       * person reads. */\n      base: '[&_td]:py-2.5 [&_th]:py-2.5',\n      /* For a table a person scans - a log, a ledger, a list of a thousand\n       * things. Half the padding, same font: shrinking the text too is how a\n       * dense table becomes an unreadable one. */\n      dense: '[&_td]:py-1.5 [&_th]:py-1.5',\n    },\n  },\n  defaultVariants: { density: 'base' },\n})\n\nexport interface TableProps\n  extends HTMLAttributes<HTMLTableElement>,\n    VariantProps<typeof tableVariants> {}\n\nexport function Table({ density, className, ...props }: TableProps) {\n  return <table className={cn(tableVariants({ density }), className)} {...props} />\n}\n\n/** The scroll container a table needs, and the one a sticky heading sticks in.\n *\n * The scrollbar is the theme's - an overlay that takes no room in the layout,\n * so a table that grows past the fold does not shift the column beside it. */\nexport function TableScroll({ className, ...props }: HTMLAttributes<HTMLDivElement>) {\n  return <div className={cn('w-full overflow-x-auto', className)} {...props} />\n}\n\nexport interface TableHeadProps extends HTMLAttributes<HTMLTableSectionElement> {\n  /** Keep the heading in view while the body scrolls under it.\n   *\n   * Off by default. A sticky heading needs a container with a height to stick\n   * inside; switched on by default it would silently do nothing in the common\n   * case - a table that scrolls with the page - and look broken in the other. */\n  sticky?: boolean\n}\n\nexport function TableHead({ sticky = false, className, ...props }: TableHeadProps) {\n  return (\n    <thead\n      className={cn(\n        'text-xs text-dim',\n        // The heading needs its own ground when it is sticky: transparent, it\n        // would have the body's rows sliding visibly beneath its text.\n        sticky && 'sticky top-0 z-sticky bg-bg',\n        className,\n      )}\n      {...props}\n    />\n  )\n}\n\nexport function TableBody({ className, ...props }: HTMLAttributes<HTMLTableSectionElement>) {\n  return <tbody className={cn('', className)} {...props} />\n}\n\nexport interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {\n  /** The row the reader has picked out - the one open in the panel beside the\n   * table, the one a keyboard cursor is on. Not a hover state. */\n  selected?: boolean\n}\n\nexport function TableRow({ selected = false, className, ...props }: TableRowProps) {\n  return (\n    <tr\n      // Announced rather than only drawn: a row picked out by colour alone is\n      // a row nobody using a screen reader knows about.\n      aria-selected={selected || undefined}\n      className={cn(\n        'border-b border-line transition-colors last:border-b-0',\n        selected ? 'bg-accent-soft' : 'hover:bg-soft',\n        className,\n      )}\n      {...props}\n    />\n  )\n}\n\nexport interface TableCellProps extends TdHTMLAttributes<HTMLTableCellElement> {\n  /** Right-align and use the lining figures. For a column of numbers, and the\n   * reason it is a prop rather than a class the caller adds: a column of\n   * numbers that is not aligned is the most common defect in a table, and the\n   * one nobody files a bug about. */\n  numeric?: boolean\n}\n\nexport function TableCell({ numeric = false, className, ...props }: TableCellProps) {\n  return (\n    <td\n      className={cn('px-3 align-middle', numeric && 'text-right tabular-nums', className)}\n      {...props}\n    />\n  )\n}\n\nexport interface TableHeaderProps extends ThHTMLAttributes<HTMLTableCellElement> {\n  numeric?: boolean\n}\n\n/** A plain heading, for a column that does not sort. */\nexport function TableHeader({ numeric = false, className, ...props }: TableHeaderProps) {\n  return (\n    <th\n      scope=\"col\"\n      className={cn(\n        'px-3 font-medium',\n        numeric && 'text-right tabular-nums',\n        className,\n      )}\n      {...props}\n    />\n  )\n}\n\nexport interface TableSortHeaderProps extends Omit<TableHeaderProps, 'onClick'> {\n  /** This column's id - the key the accessor sorts by. */\n  column: string\n  /** What is sorted now, across the whole table. */\n  sort: Sort | undefined\n  onSortChange: (column: string) => void\n}\n\n/** A heading that reorders the table when clicked.\n *\n * A real `<button>` inside the `<th>`, not a click handler on the cell: the\n * cell is not focusable, gets no keyboard, and announces nothing. This is the\n * part a hand-rolled table almost always gets wrong, and it is invisible to\n * everyone who reorders with a mouse.\n *\n * The arrow is `aria-hidden`, because `aria-sort` on the cell already says\n * which way the column points - a reader would otherwise hear the direction\n * twice, once as a word and once as a character nobody meant to publish. */\nexport function TableSortHeader({\n  column,\n  sort,\n  onSortChange,\n  numeric = false,\n  className,\n  children,\n  ...props\n}: TableSortHeaderProps) {\n  const active = sort?.column === column\n  const direction = sort?.direction\n\n  return (\n    <th\n      scope=\"col\"\n      // Only on the sorted column. `aria-sort=\"none\"` on every other heading\n      // is valid and gets announced by some readers on every cell.\n      aria-sort={ariaSort(sort, column)}\n      className={cn('px-3 font-medium', numeric && 'tabular-nums', className)}\n      {...props}\n    >\n      <button\n        type=\"button\"\n        onClick={() => onSortChange(column)}\n        className={cn(\n          'group -mx-1 inline-flex w-[calc(100%+0.5rem)] cursor-pointer items-center gap-1 rounded-sm px-1',\n          'transition-colors hover:text-text',\n          'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',\n          active && 'text-text',\n          numeric && 'justify-end',\n        )}\n      >\n        {children}\n        <span\n          aria-hidden\n          className={cn(\n            'text-2xs transition-opacity',\n            // The arrow of the unsorted column appears on hover rather than\n            // never: a heading that gives no sign it can be clicked is one\n            // nobody clicks. It stays out of the way until the pointer is on\n            // it, so a table of eight columns is not a row of eight arrows.\n            active ? 'opacity-100' : 'opacity-0 group-hover:opacity-40',\n          )}\n        >\n          {direction === 'desc' && active ? '▼' : '▲'}\n        </span>\n      </button>\n    </th>\n  )\n}\n\n/** What the table says when it has no rows.\n *\n * A row spanning every column rather than a block below the table, so the\n * heading stays where it is and the table does not change shape between having\n * rows and not. `colSpan` is required: without it the message sits under the\n * first column and the rest of the header hangs over nothing. */\nexport interface TableEmptyProps extends TdHTMLAttributes<HTMLTableCellElement> {\n  colSpan: number\n}\n\nexport function TableEmpty({ colSpan, className, ...props }: TableEmptyProps) {\n  return (\n    <tr>\n      <td\n        colSpan={colSpan}\n        className={cn('px-3 py-10 text-center text-sm text-dim', className)}\n        {...props}\n      />\n    </tr>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "name": "tag-input",
       "type": "registry:ui",
@@ -1062,7 +1194,7 @@
       "description": "Free text turned into a list: type a word, press Enter, it becomes a chip.",
       "dependencies": [
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/chip.json",
@@ -1083,7 +1215,7 @@
       "title": "Textarea",
       "description": "A multi-line field that can grow with what is typed into it, which is the only interesting part: a fixed box makes someone scroll inside a scroll, and a box that grows without limit pushes the button they are trying to reach off the screen. `autoResize` grows it; `maxRows` says when to stop and let it scroll after all.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1103,7 +1235,7 @@
       "title": "Time-field",
       "description": "No donor for this one: neither product of the line had a time field, so this is written from the same shape as DurationField, and for the same reason. Anything a person plausibly types is accepted - `9`, `9:30`, `930`, `9.30`, `9pm`, `21:30` - and what comes back is always `HH:MM`.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1125,7 +1257,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1145,7 +1277,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1157,13 +1289,49 @@
         }
       ]
     },
+    {
+      "name": "tree-rows",
+      "type": "registry:ui",
+      "title": "Tree-rows",
+      "description": "Split out of the TreeView for the reason `table-sort` and `calendar-math` were split out of their components: these are the sums, and the component is the thing that draws them. A product that windows a large tree needs to know how many rows it has before rendering any of them - that is this file, and it never touches the DOM.",
+      "dependencies": [],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/tree-rows.tsx",
+          "target": "@ui/tree-rows.tsx",
+          "type": "registry:ui",
+          "content": "import type { ReactNode } from 'react'\n\n/*\n * What a tree shows, with no React in it.\n *\n * Split out of the TreeView for the reason `table-sort` and `calendar-math`\n * were split out of their components: these are the sums, and the component is\n * the thing that draws them. A product that windows a large tree needs to know\n * how many rows it has before rendering any of them - that is this file, and\n * it never touches the DOM.\n */\n\nexport interface TreeNode {\n  /** Stable identity. Not the label: two folders can hold a file of the same\n   * name, and keying by label collapses them into one. */\n  id: string\n  label: ReactNode\n  /** Absent or empty means a leaf. An empty array is deliberately *not* an\n   * empty folder - a folder with nothing in it still opens, and saying so\n   * needs a real value rather than the absence of one. */\n  children?: TreeNode[]\n  /** An empty folder: opens, and shows nothing. */\n  empty?: boolean\n}\n\n/** One visible row: the node, how deep it sits, and the branch it belongs to. */\nexport interface TreeRow {\n  node: TreeNode\n  depth: number\n  /** The id of the folder this row is inside, if any. What Left uses to get\n   * out of a deep branch in one press. */\n  parent?: string\n}\n\n/** The rows a tree shows, in the order the eye and the keyboard travel.\n *\n * Flattening is what makes the keyboard simple: Down is the next row of this\n * list, Up the previous, and neither has to know about nesting. A recursive\n * walk at every keystroke would ask the same question - what is visually next\n * - and answer it differently at each depth.\n *\n * It is also the answer to \"how many rows is this tree\", which is what a\n * product needs to put a tree inside a VirtualList. */\nexport function visibleRows(\n  nodes: readonly TreeNode[],\n  open: ReadonlySet<string>,\n  depth = 0,\n  parent?: string,\n): TreeRow[] {\n  const rows: TreeRow[] = []\n  for (const node of nodes) {\n    rows.push({ node, depth, parent })\n    if (node.children?.length && open.has(node.id)) {\n      rows.push(...visibleRows(node.children, open, depth + 1, node.id))\n    }\n  }\n  return rows\n}\n\n/** Whether this node is a folder - something that opens, even if empty. */\nexport function isBranch(node: TreeNode): boolean {\n  return Boolean(node.empty) || Boolean(node.children?.length)\n}\n"
+        }
+      ]
+    },
+    {
+      "name": "tree-view",
+      "type": "registry:ui",
+      "title": "Tree-view",
+      "description": "The shape products reach for and then get wrong in the same place every time. A tree is not a nest of lists with click handlers - it is one control with a cursor in it, and the difference is the whole component:\n *   **One tab stop, not one per node.** A tree of four hundred files with a   `tabIndex` on each is four hundred stops between the sidebar and the   editor. The container is what the keyboard reaches, and the arrows move a   cursor inside it - the arrangement a `RadioGroup` has, for the same   reason.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [
+        "https://lacodda.github.io/dowel/r/tree-rows.json"
+      ],
+      "files": [
+        {
+          "path": "ui/tree-view.tsx",
+          "target": "@ui/tree-view.tsx",
+          "type": "registry:ui",
+          "content": "import { useMemo, useState, type KeyboardEvent } from 'react'\nimport { cn } from 'dowel-ui'\nimport { isBranch, visibleRows, type TreeNode } from './tree-rows'\n\n/*\n * A tree: folders that open, one tab stop, arrows to move.\n *\n * The shape products reach for and then get wrong in the same place every\n * time. A tree is not a nest of lists with click handlers - it is one control\n * with a cursor in it, and the difference is the whole component:\n *\n *   **One tab stop, not one per node.** A tree of four hundred files with a\n *   `tabIndex` on each is four hundred stops between the sidebar and the\n *   editor. The container is what the keyboard reaches, and the arrows move a\n *   cursor inside it - the arrangement a `RadioGroup` has, for the same\n *   reason.\n *\n *   **Right and left do different things depending on where you are.** Right\n *   on a closed folder opens it; on an open one it steps into the first child;\n *   on a leaf it does nothing. Left closes an open folder, and on a leaf or a\n *   closed one it jumps to the parent - which is how a reader gets out of a\n *   deep branch without walking back up through every sibling.\n *\n * Both come from the ARIA tree pattern, and neither is guessable from looking\n * at a finished tree, which is why every hand-rolled one implements Up and\n * Down and stops there.\n *\n * The nodes are given, not discovered: a tree that loads its children when a\n * folder opens is a different component with a different problem (a spinner\n * per node, a request per open, an error state inside a row). This one is\n * handed everything and decides what to show.\n *\n * Which rows are visible is next door in `tree-rows`, with no React in it - a\n * product windowing a large tree imports that and never this.\n */\n\nexport interface TreeViewProps {\n  nodes: readonly TreeNode[]\n  /** Which folders are open. Uncontrolled if omitted. */\n  open?: ReadonlySet<string>\n  onOpenChange?: (open: Set<string>) => void\n  /** Which row is chosen - the file being edited, not the one the cursor is\n   * on. The two move apart: a reader walks the tree with arrows without\n   * opening anything until Enter. */\n  selected?: string\n  onSelect?: (id: string) => void\n  /** What a screen reader calls the tree. Required: a bare tree announces\n   * \"tree\" and nothing else, and the word belongs to the product. */\n  label: string\n  className?: string\n}\n\nexport function TreeView({\n  nodes,\n  open: openProp,\n  onOpenChange,\n  selected,\n  onSelect,\n  label,\n  className,\n}: TreeViewProps) {\n  const [openState, setOpenState] = useState<ReadonlySet<string>>(() => new Set())\n  const open = openProp ?? openState\n\n  const setOpen = (next: Set<string>) => {\n    if (openProp === undefined) setOpenState(next)\n    onOpenChange?.(next)\n  }\n\n  const rows = useMemo(() => visibleRows(nodes, open), [nodes, open])\n\n  /* Where the keyboard is, which is not where the selection is. The cursor\n   * starts on the selected row when there is one, so arrowing into a tree\n   * continues from what is open rather than from the top. */\n  const [cursor, setCursor] = useState<string | undefined>(undefined)\n  const active = rows.find((row) => row.node.id === cursor)\n    ? cursor\n    : (rows.find((row) => row.node.id === selected)?.node.id ?? rows[0]?.node.id)\n\n  const index = rows.findIndex((row) => row.node.id === active)\n\n  const move = (to: number) => {\n    const row = rows[Math.min(Math.max(0, to), rows.length - 1)]\n    if (row) setCursor(row.node.id)\n  }\n\n  const toggle = (id: string, next: boolean) => {\n    const copy = new Set(open)\n    if (next) copy.add(id)\n    else copy.delete(id)\n    setOpen(copy)\n  }\n\n  const onKeyDown = (event: KeyboardEvent) => {\n    const current = rows[index]\n    if (!current) return\n    const branch = isBranch(current.node)\n    const isOpen = open.has(current.node.id)\n\n    switch (event.key) {\n      case 'ArrowDown':\n        event.preventDefault()\n        move(index + 1)\n        break\n      case 'ArrowUp':\n        event.preventDefault()\n        move(index - 1)\n        break\n      case 'ArrowRight':\n        event.preventDefault()\n        // Open, then step in. Two presses rather than one that does both,\n        // because opening a folder and moving into it are different intents -\n        // and a reader who wanted only to look inside would have lost the row\n        // they were on.\n        if (branch && !isOpen) toggle(current.node.id, true)\n        else if (branch && isOpen) move(index + 1)\n        break\n      case 'ArrowLeft': {\n        event.preventDefault()\n        if (branch && isOpen) {\n          toggle(current.node.id, false)\n          break\n        }\n        // Out of the branch rather than up one row. This is the escape from a\n        // deep folder, and the part hand-rolled trees leave out: without it\n        // the only way back to the parent is through every sibling below.\n        const parent = current.parent\n        if (parent) setCursor(parent)\n        break\n      }\n      case 'Home':\n        event.preventDefault()\n        move(0)\n        break\n      case 'End':\n        event.preventDefault()\n        move(rows.length - 1)\n        break\n      case 'Enter':\n      case ' ':\n        event.preventDefault()\n        if (branch) toggle(current.node.id, !isOpen)\n        else onSelect?.(current.node.id)\n        break\n      default:\n        break\n    }\n  }\n\n  return (\n    <div\n      role=\"tree\"\n      aria-label={label}\n      // One stop for the whole tree. A `tabIndex` per node is how a sidebar of\n      // four hundred files becomes four hundred stops before the editor.\n      tabIndex={0}\n      onKeyDown={onKeyDown}\n      // The cursor is published rather than only drawn: this is what a screen\n      // reader follows, and what makes the tree one control instead of a\n      // collection of rows.\n      aria-activedescendant={active ? `tree-${active}` : undefined}\n      className={cn(\n        'text-sm',\n        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',\n        className,\n      )}\n    >\n      {rows.map(({ node, depth }) => {\n        const branch = isBranch(node)\n        const isOpen = open.has(node.id)\n        return (\n          <div\n            key={node.id}\n            id={`tree-${node.id}`}\n            role=\"treeitem\"\n            // Only on folders. On a leaf it would announce \"collapsed\" for\n            // something that never opens.\n            aria-expanded={branch ? isOpen : undefined}\n            aria-selected={node.id === selected || undefined}\n            // One-based, and the level a reader is told - the indent is the\n            // sighted half of the same fact.\n            aria-level={depth + 1}\n            onClick={() => {\n              setCursor(node.id)\n              if (branch) toggle(node.id, !isOpen)\n              else onSelect?.(node.id)\n            }}\n            className={cn(\n              'flex cursor-pointer items-center gap-1 rounded-sm py-1 pr-2 transition-colors',\n              node.id === selected ? 'bg-accent-soft text-text' : 'hover:bg-soft',\n              node.id === active && node.id !== selected && 'bg-softer',\n            )}\n            // Indent by depth. A padding rather than a nested box, because the\n            // rows are one flat list - which is what lets the keyboard treat\n            // Down as \"the next row\" without knowing about nesting.\n            style={{ paddingLeft: `${depth * 16 + 8}px` }}\n          >\n            <span aria-hidden className={cn('w-3 shrink-0 text-2xs text-dim', !branch && 'opacity-0')}>\n              {isOpen ? '▾' : '▸'}\n            </span>\n            <span className=\"truncate\">{node.label}</span>\n          </div>\n        )\n      })}\n    </div>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "name": "truncate",
       "type": "registry:ui",
       "title": "Truncate",
       "description": "Text that does not fit, cut with an ellipsis - and, importantly, still readable in full: the element carries its own text as a `title`, so hovering shows what was cut. Every product wrote the one-line version of this and none of them remembered the title.",
       "dependencies": [
-        "dowel-ui@^0.20.3"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1175,6 +1343,24 @@
         }
       ]
     },
+    {
+      "name": "virtual-list",
+      "type": "registry:ui",
+      "title": "Virtual-list",
+      "description": "The browser is fine with long lists until it is not: a hundred thousand `<div>`s is a layout the machine recomputes on every change, and the page stops responding while it does. What is drawn instead is the window the reader can actually see, held in place by a tall spacer, so the scrollbar still says how much there is.",
+      "dependencies": [
+        "dowel-ui@^0.22.0"
+      ],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "ui/virtual-list.tsx",
+          "target": "@ui/virtual-list.tsx",
+          "type": "registry:ui",
+          "content": "import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'\nimport { cn } from 'dowel-ui'\n\n/*\n * A list of a hundred thousand rows that puts a screenful in the DOM.\n *\n * The browser is fine with long lists until it is not: a hundred thousand\n * `<div>`s is a layout the machine recomputes on every change, and the page\n * stops responding while it does. What is drawn instead is the window the\n * reader can actually see, held in place by a tall spacer, so the scrollbar\n * still says how much there is.\n *\n * No virtualisation library. `react-window`, `react-virtuoso` and\n * `@tanstack/react-virtual` all solve the general problem - variable heights\n * measured at runtime, horizontal windows, grids - and the general problem is\n * not the one a design system has: every long list in a product is a column of\n * rows of one height. That case is the arithmetic below, and it is small\n * enough to read.\n *\n * The arithmetic is exported separately, and that is the part worth stating.\n * A window computed inside an effect can only be tested by a browser, and\n * jsdom gives every element a height of zero - so a test would assert against\n * a list that believes it is invisible, and pass whatever the code did. As\n * plain functions the rules are checkable: given a scroll offset and a height,\n * these rows are drawn.\n *\n * Variable row heights are deliberately not supported. Measuring them means\n * rendering to find out, which means a second pass, a cache, and a scrollbar\n * that changes length as the reader travels. When a product needs that, it\n * needs a library rather than a bigger version of this.\n */\n\nexport interface Window {\n  /** Index of the first row to render. */\n  start: number\n  /** Index one past the last row to render. */\n  end: number\n  /** The height of the whole list, drawn or not - what makes the scrollbar\n   * honest. */\n  totalHeight: number\n  /** How far down the first drawn row sits. Applied as a translation rather\n   * than as a top margin, so the rows are not re-laid-out on every scroll. */\n  offsetTop: number\n}\n\nexport interface WindowInput {\n  /** How many rows there are in total. */\n  count: number\n  /** How tall one row is, in pixels. One height for every row. */\n  rowHeight: number\n  /** How tall the scrolling box is. */\n  viewportHeight: number\n  /** How far the box is scrolled. */\n  scrollTop: number\n  /** How many extra rows to draw beyond each edge.\n   *\n   * Not decoration: without it a fast scroll paints blank where rows have not\n   * been drawn yet, because the scroll event arrives after the pixels. Three\n   * rows is enough to cover a frame at ordinary speeds and cheap enough not to\n   * matter. */\n  overscan?: number\n}\n\n/** Which rows to draw. Pure arithmetic, so it can be checked without a browser.\n *\n * Every edge case here is one that shows as a blank list rather than as an\n * error: a viewport of zero (the box has not been measured yet), a scroll\n * position past the end (the list shrank under the reader), a negative one\n * (elastic scrolling on a trackpad). */\nexport function windowFor({\n  count,\n  rowHeight,\n  viewportHeight,\n  scrollTop,\n  overscan = 3,\n}: WindowInput): Window {\n  const rows = Math.max(0, Math.floor(count))\n  const height = Math.max(1, rowHeight)\n  const totalHeight = rows * height\n\n  if (rows === 0) return { start: 0, end: 0, totalHeight: 0, offsetTop: 0 }\n\n  // Clamped rather than trusted. A negative scrollTop is what a trackpad hands\n  // over at the top of an elastic scroll, and `Math.floor` of it walks the\n  // start index backwards into rows that do not exist.\n  const top = Math.min(Math.max(0, scrollTop), Math.max(0, totalHeight - 1))\n\n  const first = Math.floor(top / height)\n  /* One more row than fits, so the row cut by the bottom edge is drawn rather\n   * than appearing as the reader scrolls into it.\n   *\n   * The `+ 1` is also what keeps the first frame from being empty: before the\n   * effect measures the box, `viewportHeight` is 0 and this is 1. A\n   * `Math.max(1, ...)` around it looks like the guard for that and is dead\n   * code - the expression cannot reach zero. Mutation found it: removing the\n   * floor changed nothing at all. */\n  const visible = Math.ceil(Math.max(0, viewportHeight) / height) + 1\n\n  const start = Math.max(0, first - overscan)\n  const end = Math.min(rows, first + visible + overscan)\n\n  return { start, end, totalHeight, offsetTop: start * height }\n}\n\nexport interface VirtualListProps<Row> {\n  rows: readonly Row[]\n  /** How tall one row is. Fixed, and the component enforces it - a row that\n   * grows past this height overlaps its neighbour, which is why the value is\n   * required rather than measured. */\n  rowHeight: number\n  children: (row: Row, index: number) => ReactNode\n  /** A stable identity per row. Without it React keys by index, and a list\n   * that is sorted or filtered reuses the wrong DOM node - the row moves but\n   * its input keeps the text that was typed into a different row. */\n  rowKey: (row: Row, index: number) => string | number\n  overscan?: number\n  /** What a screen reader calls the list. Required: a scrolling box of rows\n   * with no name is announced as \"list\" and nothing else, and the word is the\n   * product's to give. */\n  label: string\n  className?: string\n}\n\nexport function VirtualList<Row>({\n  rows,\n  rowHeight,\n  children,\n  rowKey,\n  overscan = 3,\n  label,\n  className,\n}: VirtualListProps<Row>) {\n  const viewport = useRef<HTMLDivElement>(null)\n  const [scrollTop, setScrollTop] = useState(0)\n  const [viewportHeight, setViewportHeight] = useState(0)\n\n  const measure = useCallback(() => {\n    const element = viewport.current\n    if (!element) return\n    setViewportHeight(element.clientHeight)\n    setScrollTop(element.scrollTop)\n  }, [])\n\n  useEffect(() => {\n    const element = viewport.current\n    if (!element) return\n    measure()\n\n    /* The height is watched, not read once. A list inside a panel that opens,\n     * a window the reader resizes, a font that loads late - all change the\n     * viewport after mount, and a list that measured once draws the wrong\n     * number of rows until something scrolls. */\n    if (typeof ResizeObserver === 'undefined') return\n    const observer = new ResizeObserver(measure)\n    observer.observe(element)\n    return () => observer.disconnect()\n  }, [measure])\n\n  const { start, end, totalHeight, offsetTop } = windowFor({\n    count: rows.length,\n    rowHeight,\n    viewportHeight,\n    scrollTop,\n    overscan,\n  })\n\n  return (\n    <div\n      ref={viewport}\n      onScroll={(event) => setScrollTop(event.currentTarget.scrollTop)}\n      // `tabIndex` because a box that scrolls has to be reachable: a keyboard\n      // user with no focusable row inside cannot otherwise page through it.\n      tabIndex={0}\n      role=\"list\"\n      aria-label={label}\n      className={cn(\n        'relative overflow-y-auto',\n        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',\n        className,\n      )}\n    >\n      {/* The spacer is what the scrollbar measures. Without it the box is only\n        * as tall as the rows drawn, and the reader can never scroll past the\n        * first screenful. */}\n      <div style={{ height: totalHeight }} className=\"relative\">\n        <div\n          // Translated rather than positioned with `top`: a transform is\n          // composited, while changing `top` re-lays-out the subtree on every\n          // scroll event.\n          style={{ transform: `translateY(${offsetTop}px)` }}\n          className=\"absolute inset-x-0 top-0\"\n        >\n          {rows.slice(start, end).map((row, offset) => {\n            const index = start + offset\n            return (\n              <div\n                key={rowKey(row, index)}\n                role=\"listitem\"\n                /* The pair that makes a window honest to a screen reader.\n                 *\n                 * Without them the reader counts the rows it can see and says\n                 * \"3 of 20\" in a list of a hundred thousand - the rows in the\n                 * DOM are a screenful, and that is exactly what a virtual list\n                 * hides. `aria-setsize` is the real total, `aria-posinset` the\n                 * real position.\n                 *\n                 * Deliberately not `aria-rowcount`/`aria-rowindex`, which were\n                 * the obvious names and are wrong: those belong to `grid`,\n                 * `table` and `treegrid`. On a `list` they are unsupported -\n                 * axe rejects them, and a reader would simply ignore them,\n                 * which is the worse half: the markup would look like it said\n                 * something. */\n                aria-setsize={rows.length}\n                aria-posinset={index + 1}\n                style={{ height: rowHeight }}\n              >\n                {children(row, index)}\n              </div>\n            )\n          })}\n        </div>\n      </div>\n    </div>\n  )\n}\n"
+        }
+      ]
+    },
     {
       "extends": "none",
       "name": "app",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dowel-ui",
-  "version": "0.20.3",
+  "version": "0.22.0",
   "description": "The lacodda line design system: theme tokens and React primitives, distributed as a shadcn-compatible registry.",
   "license": "MIT",
   "type": "module",