@fusion.dev/helix-headless 0.182.2 → 0.184.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.182.2",
+  "version": "0.184.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -49,14 +49,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.182.2",
-    "@fusion.dev/helix-icons": "0.182.2",
+    "@fusion.dev/helix-core": "0.184.0",
+    "@fusion.dev/helix-icons": "0.184.0",
     "tslib": "^2.8.1",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.182.2",
-    "@fusion.dev/helix-testing": "0.182.2",
+    "@fusion.dev/helix-cem": "0.184.0",
+    "@fusion.dev/helix-testing": "0.184.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.14.5",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -6392,7 +6392,11 @@ whole of it, which Shiki writes, are taken off, so the lines sit level
 with the gutter's numbers and the block keeps one tab stop. The code stays
 in the slot, so the copy button copies it as written and a reader without
 the script still has it. Not called on a server, which has no code to
-read, nor for a diff. */
+read, nor for a diff.
+
+Absent, the block draws with the highlighter `registerHighlighter` gave
+every block, where an entry such as `@fusion.dev/helix-sandbox/code-block`
+registered one, and plain otherwise. */
   highlight?: (HelixHeadlessCodeBlock["highlight"]) | undefined;
 
   /** A file tab showed its file, whose name `file` now holds. */
@@ -6634,7 +6638,11 @@ whole of it, which Shiki writes, are taken off, so the lines sit level
 with the gutter's numbers and the block keeps one tab stop. The code stays
 in the slot, so the copy button copies it as written and a reader without
 the script still has it. Not called on a server, which has no code to
-read, nor for a diff. */
+read, nor for a diff.
+
+Absent, the block draws with the highlighter `registerHighlighter` gave
+every block, where an entry such as `@fusion.dev/helix-sandbox/code-block`
+registered one, and plain otherwise. */
   "prop:highlight"?: (HelixHeadlessCodeBlock["highlight"]) | undefined;
   /** A file tab showed its file, whose name `file` now holds. */
   "on:change"?: ((e: HelixHeadlessCodeBlockElementEvent) => void) | undefined;
@@ -21529,7 +21537,11 @@ Cleared as the menu closes and as a submenu opens or closes, so each page
 starts with every row showing. */
   filter?: (HelixHeadlessMenu["filter"]) | undefined;
   /** Whether the menu shows a field above its rows that narrows them as the
-reader types, with focus staying in the field. */
+reader types, with focus staying in the field, once
+`@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)
+is imported. Without that import it does nothing, so a menu that never
+filters carries none of the filter's code, and a development build says
+which import is missing. */
   filterable?: (HelixHeadlessMenu["filterable"]) | undefined;
   /** The filter field's name and placeholder. */
   "filter-label"?: (HelixHeadlessMenu["filterLabel"]) | undefined;
@@ -21667,7 +21679,11 @@ Cleared as the menu closes and as a submenu opens or closes, so each page
 starts with every row showing. */
   "prop:filter"?: (HelixHeadlessMenu["filter"]) | undefined;
   /** Whether the menu shows a field above its rows that narrows them as the
-reader types, with focus staying in the field. */
+reader types, with focus staying in the field, once
+`@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)
+is imported. Without that import it does nothing, so a menu that never
+filters carries none of the filter's code, and a development build says
+which import is missing. */
   "prop:filterable"?: (HelixHeadlessMenu["filterable"]) | undefined;
   /** The filter field's name and placeholder. */
   "attr:filter-label"?: (HelixHeadlessMenu["filterLabel"]) | undefined;
@@ -31763,6 +31779,12 @@ number, and both are carried as one comma-separated value, which is what a
 form submits. `TimePicker` carries the longer note on the interaction and
 on why a wheel cannot do either. */
   mode?: (HelixHeadlessTimeInput["mode"]) | undefined;
+  /** The words on the list's button that chooses the current time, drawn with
+`show-now`. */
+  "now-label"?: (HelixHeadlessTimeInput["nowLabel"]) | undefined;
+  /** The words on the list's button that chooses the current time, drawn with
+`show-now`. */
+  nowLabel?: (HelixHeadlessTimeInput["nowLabel"]) | undefined;
   /** Placeholder text shown before a time is entered. */
   placeholder?: (HelixHeadlessTimeInput["placeholder"]) | undefined;
   /** The message shown when a range holds more than two times.
@@ -31803,6 +31825,14 @@ removes rather than as "Remove" said once per time. */
 may give them, the field writes them, and the list's `step` counts seconds.
 See Time Picker's `seconds`. */
   seconds?: (HelixHeadlessTimeInput["seconds"]) | undefined;
+  /** Draws a button under the times in the list that chooses the current time,
+moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+are `now-label`. */
+  "show-now"?: (HelixHeadlessTimeInput["showNow"]) | undefined;
+  /** Draws a button under the times in the list that chooses the current time,
+moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+are `now-label`. */
+  showNow?: (HelixHeadlessTimeInput["showNow"]) | undefined;
   /** How far apart the offered times are, in minutes, or in seconds with
 `seconds`. */
   step?: (HelixHeadlessTimeInput["step"]) | undefined;
@@ -32171,6 +32201,12 @@ number, and both are carried as one comma-separated value, which is what a
 form submits. `TimePicker` carries the longer note on the interaction and
 on why a wheel cannot do either. */
   "prop:mode"?: (HelixHeadlessTimeInput["mode"]) | undefined;
+  /** The words on the list's button that chooses the current time, drawn with
+`show-now`. */
+  "attr:now-label"?: (HelixHeadlessTimeInput["nowLabel"]) | undefined;
+  /** The words on the list's button that chooses the current time, drawn with
+`show-now`. */
+  "prop:nowLabel"?: (HelixHeadlessTimeInput["nowLabel"]) | undefined;
   /** Placeholder text shown before a time is entered. */
   "prop:placeholder"?: (HelixHeadlessTimeInput["placeholder"]) | undefined;
   /** The message shown when a range holds more than two times.
@@ -32211,6 +32247,14 @@ removes rather than as "Remove" said once per time. */
 may give them, the field writes them, and the list's `step` counts seconds.
 See Time Picker's `seconds`. */
   "prop:seconds"?: (HelixHeadlessTimeInput["seconds"]) | undefined;
+  /** Draws a button under the times in the list that chooses the current time,
+moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+are `now-label`. */
+  "bool:show-now"?: (HelixHeadlessTimeInput["showNow"]) | undefined;
+  /** Draws a button under the times in the list that chooses the current time,
+moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+are `now-label`. */
+  "prop:showNow"?: (HelixHeadlessTimeInput["showNow"]) | undefined;
   /** How far apart the offered times are, in minutes, or in seconds with
 `seconds`. */
   "prop:step"?: (HelixHeadlessTimeInput["step"]) | undefined;
@@ -36982,6 +37026,13 @@ are rendered at a time.
 An `aria-label` or `aria-labelledby` on the host names the list too, and
 wins over this. */
   label?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** How items of more than one column are laid out. `grid`, the default, puts
+them in lines of equal columns. `waterfall` puts each item, in the order
+of the set, under the column that ends highest, as a wall of photos of
+different heights is: `columns`, or `min-column-width`, says how many
+columns. Rows of a waterfall are measured, and Up and Down move along a
+column. */
+  layout?: (HelixHeadlessVirtualList["layout"]) | undefined;
   /** Marks the list as busy fetching more items, and draws a row after the last
 item that says so.
 
@@ -37014,14 +37065,15 @@ follows the box as it resizes, which `columns` then does not decide. */
   /** Which way the list runs. `horizontal` lays the items out along a line
 and scrolls it sideways: Left and Right move between items, the other
 way round on a right-to-left page, and `estimate` is an item's width. A
-grid always runs down. */
+grid and a waterfall always run down. */
   orientation?: (HelixHeadlessVirtualList["orientation"]) | undefined;
   /** Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
 (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
 with an arrow moves the row the keys are on, and a pointer drags a row.
 The list moves no item itself: you move your `items` on `helix-reorder`.
 Without that import it does nothing, so a list that never moves items
-carries none of the code. A list of one column, without sections. */
+carries none of the code. A list of one column, without sections or a
+waterfall. */
   reorderable?: (HelixHeadlessVirtualList["reorderable"]) | undefined;
   /** The field of each item that names its section, as a key or a path of
 keys. Set, the items are drawn in sections: a header, then the items, in
@@ -37150,6 +37202,13 @@ are rendered at a time.
 An `aria-label` or `aria-labelledby` on the host names the list too, and
 wins over this. */
   "prop:label"?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** How items of more than one column are laid out. `grid`, the default, puts
+them in lines of equal columns. `waterfall` puts each item, in the order
+of the set, under the column that ends highest, as a wall of photos of
+different heights is: `columns`, or `min-column-width`, says how many
+columns. Rows of a waterfall are measured, and Up and Down move along a
+column. */
+  "prop:layout"?: (HelixHeadlessVirtualList["layout"]) | undefined;
   /** Marks the list as busy fetching more items, and draws a row after the last
 item that says so.
 
@@ -37182,14 +37241,15 @@ follows the box as it resizes, which `columns` then does not decide. */
   /** Which way the list runs. `horizontal` lays the items out along a line
 and scrolls it sideways: Left and Right move between items, the other
 way round on a right-to-left page, and `estimate` is an item's width. A
-grid always runs down. */
+grid and a waterfall always run down. */
   "prop:orientation"?: (HelixHeadlessVirtualList["orientation"]) | undefined;
   /** Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
 (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
 with an arrow moves the row the keys are on, and a pointer drags a row.
 The list moves no item itself: you move your `items` on `helix-reorder`.
 Without that import it does nothing, so a list that never moves items
-carries none of the code. A list of one column, without sections. */
+carries none of the code. A list of one column, without sections or a
+waterfall. */
   "prop:reorderable"?: (HelixHeadlessVirtualList["reorderable"]) | undefined;
   /** The field of each item that names its section, as a key or a path of
 keys. Set, the items are drawn in sections: a header, then the items, in
@@ -38870,6 +38930,7 @@ export type CustomElements = {
    * - `bar`: One column. Under `stacked`, one segment of a category's column.
    * - `bar-end`: The bar at a column's far end, the end away from zero, which is the end to round. A column standing alone is its own far end. Under `stacked`, the last positive segment above zero and the last negative one below it. Its `data-end` is `positive` or `negative`. A blank or a zero is never the end. Set together with `bar`.
    * - `bar-end-negative`: A far end below zero, whose far end is its bottom, or its inline start when the bars run across. Set together with `bar-end`.
+   * - `bar-negative`: A bar below zero, standing alone or any segment of a stack below it, whose base is its top, or its inline end when the bars run across. Set together with `bar`.
    * - `bar-wash-end`: The far stop of a bar's gradient, where one is used.
    * - `bar-wash-start`: The stop of a bar's gradient at its base.
    * - `baseline`: The line the columns stand on.
@@ -42110,6 +42171,20 @@ export type CustomElements = {
    * the slot, so the copy button and the page's own text are the code as
    * written.
    *
+   * **Code Block ships no grammar**, so plain code costs you no parser. To color
+   * code without a highlighter of your own, import one more entry beside the
+   * block's. It colors every block by its `language` (`css`, `html`, `js`,
+   * `jsx`, `sh`, `ts`, or `tsx`) with the Lezer grammars of the sandbox's
+   * editor, in the editor's colors:
+   *
+   * ```js
+   * import '@fusion.dev/helix/code-block'
+   * import '@fusion.dev/helix-sandbox/code-block'
+   * ```
+   *
+   * That entry calls `registerHighlighter`, which you can also call yourself to
+   * give every block one highlighter of your own.
+   *
    * Set `expandable` on a block whose height is capped, such as by
    * `--code-block-max-block-size`, and a button under it shows every line and
    * then fewer again, as a docs site's long example does. The button is drawn
@@ -42282,7 +42357,11 @@ export type CustomElements = {
    * with the gutter's numbers and the block keeps one tab stop. The code stays
    * in the slot, so the copy button copies it as written and a reader without
    * the script still has it. Not called on a server, which has no code to
-   * read, nor for a diff. (property only)
+   * read, nor for a diff.
+   *
+   * Absent, the block draws with the highlighter `registerHighlighter` gave
+   * every block, where an entry such as `@fusion.dev/helix-sandbox/code-block`
+   * registered one, and plain otherwise. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -53647,7 +53726,15 @@ export type CustomElements = {
    * opens it from the keyboard, and the trigger is described by
    * `long-press-label`, which says so.
    *
-   * **A filter field.** With `filterable`, the menu opens with focus in a field
+   * **A filter field** is a separate import, `@fusion.dev/helix/menu/filter`, so
+   * a menu that never filters carries none of its code:
+   *
+   * ```js
+   * import '@fusion.dev/helix/menu'
+   * import '@fusion.dev/helix/menu/filter'
+   * ```
+   *
+   * With it imported and `filterable` set, the menu opens with focus in a field
    * above its rows, and typing narrows the rows of the page the keys move in,
    * as React Aria's `Autocomplete` around a `Menu` does. A row is kept where its
    * words hold the filter, in any case, or where `filterMatch` says so. Each
@@ -53680,7 +53767,11 @@ export type CustomElements = {
    * Cleared as the menu closes and as a submenu opens or closes, so each page
    * starts with every row showing.
    * - `filterable`: Whether the menu shows a field above its rows that narrows them as the
-   * reader types, with focus staying in the field.
+   * reader types, with focus staying in the field, once
+   * `@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)
+   * is imported. Without that import it does nothing, so a menu that never
+   * filters carries none of the filter's code, and a development build says
+   * which import is missing.
    * - `filter-label`/`filterLabel`: The filter field's name and placeholder.
    * - `label`: Accessible name for the surface.
    *
@@ -62667,6 +62758,8 @@ export type CustomElements = {
    * number, and both are carried as one comma-separated value, which is what a
    * form submits. `TimePicker` carries the longer note on the interaction and
    * on why a wheel cannot do either.
+   * - `now-label`/`nowLabel`: The words on the list's button that chooses the current time, drawn with
+   * `show-now`.
    * - `placeholder`: Placeholder text shown before a time is entered.
    * - `range-length-message`/`rangeLengthMessage`: The message shown when a range holds more than two times.
    *
@@ -62684,6 +62777,9 @@ export type CustomElements = {
    * - `seconds`: Whether times carry their seconds: the value is `HH:mm:ss`, a typed time
    * may give them, the field writes them, and the list's `step` counts seconds.
    * See Time Picker's `seconds`.
+   * - `show-now`/`showNow`: Draws a button under the times in the list that chooses the current time,
+   * moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+   * are `now-label`.
    * - `step`: How far apart the offered times are, in minutes, or in seconds with
    * `seconds`.
    * - `time-style`/`timeStyle`: Whether the field shows the time in the local style or as the value
@@ -66680,6 +66776,32 @@ export type CustomElements = {
    * smallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns
    * of a grid, by a number of pixels the list counts in each row's place.
    *
+   * A grid without `selection-mode` is a grid to a reader, as the APG's grid
+   * and React Aria's grid list are: the box is a `grid` with `aria-rowcount`
+   * and `aria-colcount`, each line drawn is a `row` with `aria-rowindex`, and
+   * each item a `gridcell` with `aria-colindex`. Each line is a slot of the
+   * list's own, so your rows stay its children: give an item one element. With
+   * `selection-mode` it stays a list box of options, as React Aria's list box
+   * in a grid layout does.
+   *
+   * **A waterfall.** `layout="waterfall"` puts each item, in the order of the
+   * set, under the column that ends highest so far, the leftmost of a tie, as a
+   * wall of photos of different heights is, and as React Aria's waterfall
+   * layout and TanStack Virtual's lanes do. `columns`, or `min-column-width`,
+   * says how many columns. Every item is measured, at the width of its column,
+   * and placed at its column and its height, so items of any height leave no
+   * holes. The list draws the items that reach into the box, and the item
+   * holding focus. A reader hears a list, or a list box, in the order of the
+   * set, which is also the order Tab and a screen reader's own keys take.
+   *
+   * In a waterfall, Down and Up move along the column to the next or the
+   * previous item in it, Right and Left move to the next or the previous
+   * column, to the item there that sits beside this one the most, or the
+   * nearest above where none does, and Page Down and Page Up move a box down
+   * or up the column. Home and End go to the first and the last item of the
+   * set, and Shift with a key takes in the items between in the order of the
+   * set.
+   *
    * **Across.** `orientation="horizontal"` lays the items out along a line and
    * scrolls it sideways, as a strip of cards does, windowed the same way:
    * `estimate` is then an item's width, and the box needs an inline size.
@@ -66698,10 +66820,11 @@ export type CustomElements = {
    *
    * | Key | What it does |
    * |---|---|
-   * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. |
-   * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
-   * | Home, End | Moves to the first or the last item. |
-   * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
+   * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line, or in a waterfall to the next or the previous item down the same column. |
+   * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a waterfall, moves to the item beside in the next or the previous column. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
+   * | Home, End | Moves to the first or the last item. In a grid without `selection-mode`, to the first or the last item of the line. |
+   * | Control or Command with Home or End | In a grid without `selection-mode`, moves to the first or the last item. |
+   * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen, or in a waterfall a box down or up the column. |
    * | A letter or a word | Moves to the next item whose text starts with what you typed. |
    * | Escape | Lets go of every chosen item, in a list with `selection-mode`. |
    * | Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |
@@ -66716,8 +66839,9 @@ export type CustomElements = {
    * or the item itself when it is a string or a number.
    *
    * Each row says its place in the whole set with `aria-posinset` and
-   * `aria-setsize`, so a screen reader says "4,000 of 10,000". The row holding
-   * focus stays drawn when it scrolls out.
+   * `aria-setsize`, so a screen reader says "4,000 of 10,000", and each cell of
+   * a grid its line and its column. The row holding focus stays drawn when it
+   * scrolls out.
    *
    * **Selecting.** `selection-mode` makes the list a list box a reader chooses
    * from: `single` selects one item and `multiple` any number. Space or a press
@@ -66825,6 +66949,12 @@ export type CustomElements = {
    *
    * An `aria-label` or `aria-labelledby` on the host names the list too, and
    * wins over this.
+   * - `layout`: How items of more than one column are laid out. `grid`, the default, puts
+   * them in lines of equal columns. `waterfall` puts each item, in the order
+   * of the set, under the column that ends highest, as a wall of photos of
+   * different heights is: `columns`, or `min-column-width`, says how many
+   * columns. Rows of a waterfall are measured, and Up and Down move along a
+   * column.
    * - `loading`: Marks the list as busy fetching more items, and draws a row after the last
    * item that says so.
    *
@@ -66847,13 +66977,14 @@ export type CustomElements = {
    * - `orientation`: Which way the list runs. `horizontal` lays the items out along a line
    * and scrolls it sideways: Left and Right move between items, the other
    * way round on a right-to-left page, and `estimate` is an item's width. A
-   * grid always runs down.
+   * grid and a waterfall always run down.
    * - `reorderable`: Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
    * (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
    * with an arrow moves the row the keys are on, and a pointer drags a row.
    * The list moves no item itself: you move your `items` on `helix-reorder`.
    * Without that import it does nothing, so a list that never moves items
-   * carries none of the code. A list of one column, without sections.
+   * carries none of the code. A list of one column, without sections or a
+   * waterfall.
    * - `section-field`/`sectionField`: The field of each item that names its section, as a key or a path of
    * keys. Set, the items are drawn in sections: a header, then the items, in
    * an element with the `group` role that the header names. A section starts
@@ -68575,6 +68706,7 @@ export type CustomElementsSolidJs = {
    * - `bar`: One column. Under `stacked`, one segment of a category's column.
    * - `bar-end`: The bar at a column's far end, the end away from zero, which is the end to round. A column standing alone is its own far end. Under `stacked`, the last positive segment above zero and the last negative one below it. Its `data-end` is `positive` or `negative`. A blank or a zero is never the end. Set together with `bar`.
    * - `bar-end-negative`: A far end below zero, whose far end is its bottom, or its inline start when the bars run across. Set together with `bar-end`.
+   * - `bar-negative`: A bar below zero, standing alone or any segment of a stack below it, whose base is its top, or its inline end when the bars run across. Set together with `bar`.
    * - `bar-wash-end`: The far stop of a bar's gradient, where one is used.
    * - `bar-wash-start`: The stop of a bar's gradient at its base.
    * - `baseline`: The line the columns stand on.
@@ -71848,6 +71980,20 @@ export type CustomElementsSolidJs = {
    * the slot, so the copy button and the page's own text are the code as
    * written.
    *
+   * **Code Block ships no grammar**, so plain code costs you no parser. To color
+   * code without a highlighter of your own, import one more entry beside the
+   * block's. It colors every block by its `language` (`css`, `html`, `js`,
+   * `jsx`, `sh`, `ts`, or `tsx`) with the Lezer grammars of the sandbox's
+   * editor, in the editor's colors:
+   *
+   * ```js
+   * import '@fusion.dev/helix/code-block'
+   * import '@fusion.dev/helix-sandbox/code-block'
+   * ```
+   *
+   * That entry calls `registerHighlighter`, which you can also call yourself to
+   * give every block one highlighter of your own.
+   *
    * Set `expandable` on a block whose height is capped, such as by
    * `--code-block-max-block-size`, and a button under it shows every line and
    * then fewer again, as a docs site's long example does. The button is drawn
@@ -72020,7 +72166,11 @@ export type CustomElementsSolidJs = {
    * with the gutter's numbers and the block keeps one tab stop. The code stays
    * in the slot, so the copy button copies it as written and a reader without
    * the script still has it. Not called on a server, which has no code to
-   * read, nor for a diff. (property only)
+   * read, nor for a diff.
+   *
+   * Absent, the block draws with the highlighter `registerHighlighter` gave
+   * every block, where an entry such as `@fusion.dev/helix-sandbox/code-block`
+   * registered one, and plain otherwise. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -83505,7 +83655,15 @@ export type CustomElementsSolidJs = {
    * opens it from the keyboard, and the trigger is described by
    * `long-press-label`, which says so.
    *
-   * **A filter field.** With `filterable`, the menu opens with focus in a field
+   * **A filter field** is a separate import, `@fusion.dev/helix/menu/filter`, so
+   * a menu that never filters carries none of its code:
+   *
+   * ```js
+   * import '@fusion.dev/helix/menu'
+   * import '@fusion.dev/helix/menu/filter'
+   * ```
+   *
+   * With it imported and `filterable` set, the menu opens with focus in a field
    * above its rows, and typing narrows the rows of the page the keys move in,
    * as React Aria's `Autocomplete` around a `Menu` does. A row is kept where its
    * words hold the filter, in any case, or where `filterMatch` says so. Each
@@ -83538,7 +83696,11 @@ export type CustomElementsSolidJs = {
    * Cleared as the menu closes and as a submenu opens or closes, so each page
    * starts with every row showing.
    * - `filterable`: Whether the menu shows a field above its rows that narrows them as the
-   * reader types, with focus staying in the field.
+   * reader types, with focus staying in the field, once
+   * `@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)
+   * is imported. Without that import it does nothing, so a menu that never
+   * filters carries none of the filter's code, and a development build says
+   * which import is missing.
    * - `filter-label`/`filterLabel`: The filter field's name and placeholder.
    * - `label`: Accessible name for the surface.
    *
@@ -92639,6 +92801,8 @@ export type CustomElementsSolidJs = {
    * number, and both are carried as one comma-separated value, which is what a
    * form submits. `TimePicker` carries the longer note on the interaction and
    * on why a wheel cannot do either.
+   * - `now-label`/`nowLabel`: The words on the list's button that chooses the current time, drawn with
+   * `show-now`.
    * - `placeholder`: Placeholder text shown before a time is entered.
    * - `range-length-message`/`rangeLengthMessage`: The message shown when a range holds more than two times.
    *
@@ -92656,6 +92820,9 @@ export type CustomElementsSolidJs = {
    * - `seconds`: Whether times carry their seconds: the value is `HH:mm:ss`, a typed time
    * may give them, the field writes them, and the list's `step` counts seconds.
    * See Time Picker's `seconds`.
+   * - `show-now`/`showNow`: Draws a button under the times in the list that chooses the current time,
+   * moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+   * are `now-label`.
    * - `step`: How far apart the offered times are, in minutes, or in seconds with
    * `seconds`.
    * - `time-style`/`timeStyle`: Whether the field shows the time in the local style or as the value
@@ -96698,6 +96865,32 @@ export type CustomElementsSolidJs = {
    * smallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns
    * of a grid, by a number of pixels the list counts in each row's place.
    *
+   * A grid without `selection-mode` is a grid to a reader, as the APG's grid
+   * and React Aria's grid list are: the box is a `grid` with `aria-rowcount`
+   * and `aria-colcount`, each line drawn is a `row` with `aria-rowindex`, and
+   * each item a `gridcell` with `aria-colindex`. Each line is a slot of the
+   * list's own, so your rows stay its children: give an item one element. With
+   * `selection-mode` it stays a list box of options, as React Aria's list box
+   * in a grid layout does.
+   *
+   * **A waterfall.** `layout="waterfall"` puts each item, in the order of the
+   * set, under the column that ends highest so far, the leftmost of a tie, as a
+   * wall of photos of different heights is, and as React Aria's waterfall
+   * layout and TanStack Virtual's lanes do. `columns`, or `min-column-width`,
+   * says how many columns. Every item is measured, at the width of its column,
+   * and placed at its column and its height, so items of any height leave no
+   * holes. The list draws the items that reach into the box, and the item
+   * holding focus. A reader hears a list, or a list box, in the order of the
+   * set, which is also the order Tab and a screen reader's own keys take.
+   *
+   * In a waterfall, Down and Up move along the column to the next or the
+   * previous item in it, Right and Left move to the next or the previous
+   * column, to the item there that sits beside this one the most, or the
+   * nearest above where none does, and Page Down and Page Up move a box down
+   * or up the column. Home and End go to the first and the last item of the
+   * set, and Shift with a key takes in the items between in the order of the
+   * set.
+   *
    * **Across.** `orientation="horizontal"` lays the items out along a line and
    * scrolls it sideways, as a strip of cards does, windowed the same way:
    * `estimate` is then an item's width, and the box needs an inline size.
@@ -96716,10 +96909,11 @@ export type CustomElementsSolidJs = {
    *
    * | Key | What it does |
    * |---|---|
-   * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. |
-   * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
-   * | Home, End | Moves to the first or the last item. |
-   * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
+   * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line, or in a waterfall to the next or the previous item down the same column. |
+   * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a waterfall, moves to the item beside in the next or the previous column. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
+   * | Home, End | Moves to the first or the last item. In a grid without `selection-mode`, to the first or the last item of the line. |
+   * | Control or Command with Home or End | In a grid without `selection-mode`, moves to the first or the last item. |
+   * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen, or in a waterfall a box down or up the column. |
    * | A letter or a word | Moves to the next item whose text starts with what you typed. |
    * | Escape | Lets go of every chosen item, in a list with `selection-mode`. |
    * | Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |
@@ -96734,8 +96928,9 @@ export type CustomElementsSolidJs = {
    * or the item itself when it is a string or a number.
    *
    * Each row says its place in the whole set with `aria-posinset` and
-   * `aria-setsize`, so a screen reader says "4,000 of 10,000". The row holding
-   * focus stays drawn when it scrolls out.
+   * `aria-setsize`, so a screen reader says "4,000 of 10,000", and each cell of
+   * a grid its line and its column. The row holding focus stays drawn when it
+   * scrolls out.
    *
    * **Selecting.** `selection-mode` makes the list a list box a reader chooses
    * from: `single` selects one item and `multiple` any number. Space or a press
@@ -96843,6 +97038,12 @@ export type CustomElementsSolidJs = {
    *
    * An `aria-label` or `aria-labelledby` on the host names the list too, and
    * wins over this.
+   * - `layout`: How items of more than one column are laid out. `grid`, the default, puts
+   * them in lines of equal columns. `waterfall` puts each item, in the order
+   * of the set, under the column that ends highest, as a wall of photos of
+   * different heights is: `columns`, or `min-column-width`, says how many
+   * columns. Rows of a waterfall are measured, and Up and Down move along a
+   * column.
    * - `loading`: Marks the list as busy fetching more items, and draws a row after the last
    * item that says so.
    *
@@ -96865,13 +97066,14 @@ export type CustomElementsSolidJs = {
    * - `orientation`: Which way the list runs. `horizontal` lays the items out along a line
    * and scrolls it sideways: Left and Right move between items, the other
    * way round on a right-to-left page, and `estimate` is an item's width. A
-   * grid always runs down.
+   * grid and a waterfall always run down.
    * - `reorderable`: Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
    * (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
    * with an arrow moves the row the keys are on, and a pointer drags a row.
    * The list moves no item itself: you move your `items` on `helix-reorder`.
    * Without that import it does nothing, so a list that never moves items
-   * carries none of the code. A list of one column, without sections.
+   * carries none of the code. A list of one column, without sections or a
+   * waterfall.
    * - `section-field`/`sectionField`: The field of each item that names its section, as a key or a path of
    * keys. Set, the items are drawn in sections: a header, then the items, in
    * an element with the `group` role that the header names. A section starts