dowel-ui 0.21.0 → 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.21.0 - the theme, the scales, an accent per product, fifty-one components - overlays, menus, the command palette, the table 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,7 +98,7 @@ 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/).
 
-Fifty-one 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
@@ -108,9 +108,11 @@ 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; three for saying that something happened - Toast, Alert and Banner; and
-six for showing rows of data: Table, Pagination, PageSize, NumberFormat,
-RelativeTime and the `table-sort` with no React in it.
+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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -370,7 +370,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -655,7 +655,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -807,7 +826,7 @@
       "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -825,7 +844,7 @@
       "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/select.json"
@@ -845,7 +864,7 @@
       "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/button.json"
@@ -866,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -884,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -906,7 +925,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -926,7 +945,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -946,7 +965,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -964,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -982,7 +1001,7 @@
       "title": "Relative-time",
       "description": "The relative-time primitive.",
       "dependencies": [
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1000,7 +1019,7 @@
       "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/spinner.json"
@@ -1020,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json",
@@ -1044,7 +1063,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1081,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1100,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1119,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1154,7 +1173,7 @@
       "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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/table-sort.json"
@@ -1175,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/chip.json",
@@ -1196,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1216,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [
         "https://lacodda.github.io/dowel/r/input.json"
@@ -1238,7 +1257,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1258,7 +1277,7 @@
       "dependencies": [
         "@base-ui/react",
         "class-variance-authority",
-        "dowel-ui@^0.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1270,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.21.0"
+        "dowel-ui@^0.22.0"
       ],
       "registryDependencies": [],
       "files": [
@@ -1288,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.21.0",
+  "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",