@charcuterie/ui 3.6.0 → 3.8.0

package/src/Field/Field.stories.tsx

@@ -329,3 +329,82 @@ export const Group: Story = {
     </StoryGrid>
   ),
 }
+
+/**
+ * Where a prop lands, in both components, side by side.
+ *
+ * `FieldProps` and `FieldGroupProps` were **closed** types until
+ * 2026-08-21: the only prop a caller could legally pass was
+ * `className`, so a component whose whole purpose is "configured by
+ * props, not a borrowed class" forced the borrowed class. queuepilot's
+ * `#dyn-lineup` gave up an `id` its screenshot suite drives by, and
+ * the box beside it stayed a hand-rolled `<fieldset>` because it
+ * needed `hidden`.
+ *
+ * The rule that opens them is one sentence with two readings, because
+ * the two components own different elements:
+ *
+ *  - **`Field` clones its child**, so its props are that **control's**
+ *    props. `name`, `placeholder`, `autoFocus`, `aria-describedby` and
+ *    `id` all reach the `<input>` — `id` always did, which is why the
+ *    rest go with it rather than moving it.
+ *  - **`FieldGroup` wraps its children**, so its props are the
+ *    **`<fieldset>`'s**. `id`, `hidden`, `ref`, and the element's own
+ *    `disabled`, `form` and `name`.
+ *
+ * `className` is the exception on `Field` alone: a class describes the
+ * box a parent lays out, so it stays on the wrapping `<div>`.
+ */
+export const ForwardsRestProps: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="field: the props are the control's">
+        <Field
+          // Composed with the field's own description and error, not
+          // replaced by them — `aria-describedby` is the one prop in
+          // the set that is a list.
+          aria-describedby="scratch-path-policy"
+          description="Absolute paths only."
+          error="That path is not writable."
+          label="Scratch path"
+          name="scratchPath"
+          placeholder="/mnt/scratch"
+        >
+          <input className={TEXT_INPUT_CLASS} type="text" />
+        </Field>
+
+        <p
+          className="mt-1.5 text-content-secondary text-sm"
+          id="scratch-path-policy"
+        >
+          Cleared between runs.
+        </p>
+      </StoryCell>
+
+      <StoryCell label="group: the props are the fieldset's">
+        <FieldGroup
+          description="The whole group is turned off by the element itself."
+          // `disabled` on a `<fieldset>` is not decoration: the
+          // platform disables every control inside it. A `<div>`-based
+          // group could not have offered this at all.
+          disabled
+          id="playback-lineup"
+          label="Playback"
+        >
+          <input
+            aria-label="Episodes"
+            className={TEXT_INPUT_CLASS}
+            defaultValue="12"
+            type="number"
+          />
+        </FieldGroup>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Field/Field.test.tsx

@@ -13,6 +13,7 @@ const {
   AllStates,
   AllVariants,
   Default,
+  ForwardsRestProps,
   Group,
   Nested,
 } = composeStories(stories)
@@ -447,3 +448,139 @@ test("a group describes its error rather than asserting invalidity", async () =>
     "A pattern needs at least one capture group.",
   )
 })
+
+/**
+ * The gap this closes, stated as the two things that were impossible.
+ *
+ * `FieldProps` and `FieldGroupProps` were closed types, so the only
+ * prop that reached an element was `className` — which is the escape
+ * hatch the "configured by props, not a borrowed class" rule exists to
+ * close. A component that accepts only `className` forces the very
+ * thing the rule forbids, and queuepilot paid for it twice: a
+ * `FieldGroup` that had to give up the `id` its screenshot suite
+ * drives by, and a box beside it that stayed a hand-rolled
+ * `<fieldset>` because it needed `hidden`.
+ *
+ * `Field` clones its child, so its props are the **control's**. The
+ * assertion is which element they landed on, because that is the half
+ * that could have gone silently wrong: routing them to the wrapper
+ * would have moved every consumer's `id` off the control the
+ * `<label htmlFor>` points at.
+ */
+test("a rest prop reaches the control, not the box around it", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    ForwardsRestProps,
+  )
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Scratch path",
+    role: "textbox",
+  })
+
+  await expect(control).toHaveAttribute(
+    "name",
+    "scratchPath",
+  )
+
+  await expect(control).toHaveAttribute(
+    "placeholder",
+    "/mnt/scratch",
+  )
+
+  // …and the `<div>` did not take them. `Field`'s own `className` is
+  // the one prop that stays on the box, so the two destinations have
+  // to be distinguishable in the DOM rather than merely documented.
+  await expect(
+    canvasElement.querySelector("[name='scratchPath']"),
+  ).toBe(control)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `aria-describedby` is a **list**, and opening the type is what makes
+ * a caller able to write one at all. A plain spread would keep one
+ * side and drop the other — the same silent drop `mergeSlotProps`
+ * exists to prevent between two nested slots, arriving by a shorter
+ * route now that the outer writer can be the author.
+ *
+ * Order is behaviour, not formatting: what the caller passed is the
+ * outer declaration and reads first, then the field's own description,
+ * then its error.
+ */
+test("a caller's aria-describedby composes with the description and the error", async () => {
+  const { canvas } = await mountStory(ForwardsRestProps)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Scratch path",
+    role: "textbox",
+  })
+
+  const [policyId, descriptionId, errorId] = (
+    control.getAttribute("aria-describedby") ?? ""
+  ).split(" ")
+
+  await expect(
+    document.getElementById(policyId ?? ""),
+  ).toHaveTextContent("Cleared between runs.")
+
+  await expect(
+    document.getElementById(descriptionId ?? ""),
+  ).toHaveTextContent("Absolute paths only.")
+
+  await expect(
+    document.getElementById(errorId ?? ""),
+  ).toHaveTextContent("That path is not writable.")
+
+  // The error is still the only source of invalidity, and a caller's
+  // own description did not disturb it.
+  await expect(control).toHaveAttribute(
+    "aria-invalid",
+    "true",
+  )
+})
+
+/**
+ * The other reading of the same rule. `FieldGroup` renders its
+ * children as-is, so the only element it owns is the `<fieldset>` and
+ * a prop has nowhere else to go — including `disabled`, which on this
+ * element is not decoration: the platform disables every control
+ * inside it.
+ *
+ * This is the case queuepilot's `#dyn-lineup` needed and could not
+ * have: an `id` on the group's own element.
+ */
+test("a rest prop reaches the fieldset, and the fieldset disables what is inside it", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    ForwardsRestProps,
+  )
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Playback",
+    role: "group",
+  })
+
+  await expect(group).toHaveAttribute(
+    "id",
+    "playback-lineup",
+  )
+
+  await expect(group.tagName).toBe("FIELDSET")
+
+  // The `<legend>` still names the group, and the group's own
+  // description still reaches it, so the rest props did not overwrite
+  // the wiring they were spread beside.
+  await expect(
+    document.getElementById(
+      group.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent(
+    "The whole group is turned off by the element itself.",
+  )
+
+  await expect(
+    canvasElement.querySelector("input[type='number']"),
+  ).toBeDisabled()
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Field/Field.tsx

@@ -2,36 +2,88 @@ import {
   useClonedChild,
   useUniqueId,
 } from "@charcuterie/logic"
-import type { ReactElement, ReactNode } from "react"
+import type {
+  ComponentPropsWithRef,
+  ReactElement,
+  ReactNode,
+  Ref,
+} from "react"
 
 import type { SlotProps } from "../slotProps.ts"
 import { mergeSlotProps } from "../slotProps.ts"
 import { toClassName } from "../toClassName.ts"
 
-export type FieldProps = SlotProps & {
-  /**
-   * The control. **Cloned, not wrapped** — the same slot contract
-   * as `Popover`'s trigger, so a `Field` can go around an `<input>`,
-   * a `<textarea>`, a `Picker`, or an app's own control without
-   * changing that control's layout.
-   */
-  children: ReactElement
-  className?: string
-  /**
-   * Standing help — units, a format, a warning about what the value
-   * does. Announced with the control, before any error.
-   */
-  description?: ReactNode
-  /**
-   * Present means invalid. There is no separate `isInvalid`, because
-   * two sources for one fact is how a control ends up
-   * `aria-invalid="true"` with nothing saying why — which is what
-   * `RegexWithFlagsField` does in mux-magic today.
-   */
-  error?: ReactNode
-  isRequired?: boolean
-  label: ReactNode
-}
+/**
+ * Everything else a caller writes on a `Field` reaches **the control
+ * it clones onto**, not the `<div>` around it.
+ *
+ * That is not a new destination, it is the existing one finally
+ * declared. `SlotProps` was a *closed* five-key type over a runtime
+ * that already spread `...receivedSlotProps` into the clone, so
+ * `name`, `placeholder`, `autoFocus`, `onBlur` and every `aria-*` all
+ * arrived at the `<input>` and none of them type-checked. The only
+ * prop a consumer could legally pass was `className` — which is the
+ * one escape hatch the fleet's "configured by props, not a borrowed
+ * class" rule is trying to close, so the closed type forced the very
+ * thing the rule forbids
+ * ([decision](../../../../docs/decisions/2026-08-21-a-slot-components-rest-props-are-the-controls-props.md)).
+ *
+ * `className` stays on the `<div>`, alone, because a class is a
+ * statement about the box a **parent** lays out
+ * ([decision](../../../../docs/decisions/2026-08-19-classname-is-the-outermost-box-a-component-renders.md)).
+ * Every other prop is a statement about the control, and `id` is the
+ * proof: it has named the control since the component shipped, and a
+ * dated record settles its precedence
+ * ([decision](../../../../docs/decisions/2026-08-05-field-adopts-the-childs-own-id.md)).
+ * Routing the rest to the `<div>` would have moved it, silently, in
+ * every consumer.
+ *
+ * `"input"` because `SlotProps` already picks from
+ * `InputHTMLAttributes` and this is the same set widened, not a
+ * second opinion about what a control is. `ref` is re-declared over
+ * `HTMLElement`: the child may be a `Picker`'s `<button>` or a
+ * `contenteditable` `<div>`, so `Ref<HTMLInputElement>` would be a
+ * narrower claim than the slot makes.
+ */
+type ForwardedControlProps = Omit<
+  ComponentPropsWithRef<"input">,
+  "children" | "className" | "ref"
+>
+
+export type FieldProps = ForwardedControlProps &
+  SlotProps & {
+    /**
+     * The control. **Cloned, not wrapped** — the same slot contract
+     * as `Popover`'s trigger, so a `Field` can go around an `<input>`,
+     * a `<textarea>`, a `Picker`, or an app's own control without
+     * changing that control's layout.
+     */
+    children: ReactElement
+    /**
+     * The `<div>` around the label, the control and the messages —
+     * the one prop that does **not** reach the control.
+     */
+    className?: string
+    /**
+     * Standing help — units, a format, a warning about what the value
+     * does. Announced with the control, before any error.
+     */
+    description?: ReactNode
+    /**
+     * Present means invalid. There is no separate `isInvalid`, because
+     * two sources for one fact is how a control ends up
+     * `aria-invalid="true"` with nothing saying why — which is what
+     * `RegexWithFlagsField` does in mux-magic today.
+     */
+    error?: ReactNode
+    isRequired?: boolean
+    label: ReactNode
+    /**
+     * Merged onto the control's own, never replacing it — the wiring
+     * rule `mergeSlotWiring` states for every slot.
+     */
+    ref?: Ref<HTMLElement>
+  }
 
 /**
  * Sixteen files in the fleet spell a label, a control, and a hint,
@@ -108,6 +160,28 @@ export type FieldProps = SlotProps & {
  * `SlotProps` arriving from an outer slot is forwarded down, and
  * `aria-describedby` is merged rather than replaced.
  * `slotProps.ts` has the reasoning.
+ *
+ * ### …and a pass-through cannot tell who wrote the prop
+ *
+ * Which is why the rest props are the **control's** props and not the
+ * `<div>`'s. `receivedSlotProps` below is one object holding two
+ * things that are indistinguishable at runtime: what a cloning
+ * ancestor injected, and what the author typed on the `Field` itself.
+ * A `Tooltip` above hands down `getReferenceProps()` — hover, focus
+ * and dismiss handlers, `refs.setReference`, and an
+ * `aria-describedby` naming the tip — and every bit of it has to
+ * reach the `<input>` at the bottom. Sending the rest to the wrapper
+ * would need a closed runtime allow-list to hold that case back, and
+ * an allow-list is `FieldTooltip`'s silent drop rebuilt inside the
+ * fix for it: the first slot that writes an `aria-expanded` is broken
+ * and nothing says so.
+ *
+ * So there is one rule, and it has no exceptions to remember:
+ * `className` is the box, everything else is the control. A caller
+ * that needs a handle on the **box** — an `id` for a screenshot, a
+ * `hidden` that takes the label with it — wants `FieldGroup`, which
+ * wraps rather than clones and whose rest props land on its own
+ * `<fieldset>`.
  */
 export const Field = ({
   children,

package/src/Field/FieldGroup.tsx

@@ -1,23 +1,53 @@
 import { useUniqueId } from "@charcuterie/logic"
-import type { ReactNode } from "react"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
 
+import { mergeSlotProps } from "../slotProps.ts"
 import { toClassName } from "../toClassName.ts"
 
-export type FieldGroupProps = {
-  /**
-   * The controls. **Rendered as-is, not cloned** — that is the whole
-   * difference from `Field`, and it is why this is a separate
-   * component rather than a boolean on that one.
-   */
-  children: ReactNode
-  className?: string
-  /** Standing help for the group as a whole. */
-  description?: ReactNode
-  /** Present means the group is invalid. */
-  error?: ReactNode
-  isRequired?: boolean
-  label: ReactNode
-}
+/**
+ * Everything a caller writes on a `FieldGroup` reaches the
+ * `<fieldset>` — `id`, `hidden`, `data-*`, `aria-*`, `ref`, and the
+ * three attributes that are the element's own: `disabled`, `form`
+ * and `name`.
+ *
+ * This is the **opposite** destination from `Field`'s, and the
+ * difference is not a preference. `Field` clones onto its child, so
+ * its props are that control's props; `FieldGroup` renders its
+ * children as-is, so the only element it owns is the `<fieldset>` and
+ * a prop has nowhere else to go. One rule reads both:
+ * ***a component's props land on the element it owns***
+ * ([decision](../../../../docs/decisions/2026-08-21-a-slot-components-rest-props-are-the-controls-props.md)).
+ *
+ * `disabled` is worth knowing about before reaching for it. On a
+ * `<fieldset>` it is not decoration — the platform disables every
+ * form control inside the element, not just the box itself. That is
+ * usually what a caller wants and occasionally a surprise, and it is
+ * a thing a `<div>`-based group could not have offered at all.
+ */
+export type FieldGroupProps =
+  ComponentPropsWithRef<"fieldset"> & {
+    /**
+     * The controls. **Rendered as-is, not cloned** — that is the whole
+     * difference from `Field`, and it is why this is a separate
+     * component rather than a boolean on that one.
+     */
+    children: ReactNode
+    /**
+     * The `<fieldset>`, which is also the outermost element this
+     * component renders — so `className` is not the exception here that
+     * it is on `Field`.
+     */
+    className?: string
+    /** Standing help for the group as a whole. */
+    description?: ReactNode
+    /** Present means the group is invalid. */
+    error?: ReactNode
+    isRequired?: boolean
+    label: ReactNode
+  }
 
 /**
  * A label over **several** controls.
@@ -66,6 +96,7 @@ export const FieldGroup = ({
   error,
   isRequired = false,
   label,
+  ...receivedFieldsetProps
 }: FieldGroupProps): ReactNode => {
   const baseId = useUniqueId()
 
@@ -85,9 +116,19 @@ export const FieldGroup = ({
 
   return (
     <fieldset
-      aria-describedby={
-        describedBy === "" ? undefined : describedBy
-      }
+      /*
+        Through `mergeSlotProps`, not around it. A caller may now pass
+        an `aria-describedby` of its own, and that attribute is the
+        one prop in the set that is a **list** — a plain spread keeps
+        whichever side is written last and drops the other, silently,
+        which is the defect `mergeSlotProps` exists to prevent one
+        level down. Received first, then this group's description and
+        error, for the reason the ordering array above gives.
+      */
+      {...mergeSlotProps(receivedFieldsetProps, {
+        "aria-describedby":
+          describedBy === "" ? undefined : describedBy,
+      })}
       className={toClassName(
         // A `<fieldset>` arrives with a border, an inline margin, a
         // block padding, and `min-inline-size: min-content` — the

package/src/VirtualizedGrid/VirtualizedGrid.mdx

@@ -0,0 +1,110 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as VirtualizedGridStories from "./VirtualizedGrid.stories";
+
+<Meta of={VirtualizedGridStories} />
+
+# VirtualizedGrid
+
+**`AdaptiveGrid`, with only the rows you can see mounted.** Same column rule, same
+two-box structure, same content cap. The one difference is that a list of 2,000 costs
+about as much as a list of 40.
+
+<Canvas of={VirtualizedGridStories.Default} />
+
+## Props
+
+<Controls />
+
+## When to reach for it
+
+Not by default. `AdaptiveGrid` renders everything it is handed, and that is the right
+behaviour: the DOM is searchable with `Ctrl+F`, `Ctrl+End` goes where you expect, and
+nothing has to be measured. Reach for this one when the item count is genuinely
+unbounded — a library listing, an inbox, a backlog that grows.
+
+The number that prompted it, measured on QueuePilot's Pending page:
+
+| | Every item rendered |
+| --- | --- |
+| Items | 2,162 |
+| DOM nodes | 19,933 |
+| `<img>` elements | 2,162 |
+| `<button>` elements | 4,371 |
+| Time to settle | 7.8 s |
+| Scroll rate | ~43 fps |
+
+Nothing about that page was wrong except how much of it existed at once.
+
+## Rows are the unit
+
+The virtualizer counts **rows**, not items. An item-level virtualizer would have to place
+every item on both axes; a row-level one gets the inline axis from CSS grid for free and
+only ever answers "how far down".
+
+So `itemBlockSize` is a row-height estimate, and unlike `AdaptiveGrid`'s it is not a
+commitment — every mounted row is measured and the estimate corrected. It still wants to
+be close, because it is what the scrollbar is sized from before anything has been
+measured. A bad guess makes the bar jump under the thumb on the first scroll.
+
+## It scrolls the page, not a box of its own
+
+`useWindowVirtualizer`, so the page scrolls the way every other page in the fleet
+scrolls — the header leaves, the scrollbar is the browser's, `Ctrl+End` works. A
+component that grew its own `overflow: auto` well would trap the wheel and strand the
+page header above it.
+
+The cost is that the grid has to know how far down the document it starts, which it
+measures in a layout effect and feeds to the virtualizer as `scrollMargin`. Get that
+wrong and every row is offset by the height of the header above it.
+
+## The column rule is inherited, not reimplemented
+
+<Canvas of={VirtualizedGridStories.AllVariants} />
+
+Columns come from `useAdaptiveColumns` — the identical hook `AdaptiveGrid` calls. The
+consequence that reads backwards holds here too: a **taller** window takes **fewer**
+columns, because height is what a column is bought with.
+
+This is deliberate. A second column heuristic that windowed lists followed and flow lists
+did not would be a fleet where the same content lays out two ways depending on how many
+of it there are.
+
+## The states that are easy to miss
+
+<Canvas of={VirtualizedGridStories.AllStates} />
+
+An empty list draws a zero-height box and no rows — a windowed grid must not reserve
+space for a list that is not there, and it is the state a filter lands on. One item is
+one column, the same answer `AdaptiveGrid` gives.
+
+## It is still read from the container
+
+<Canvas of={VirtualizedGridStories.Responsive} />
+
+The browser never moves and the column count still falls. Inline size comes off a
+`ResizeObserver` on the container, so a grid beside a rail gets the room it actually has
+rather than the room the window claims.
+
+## Accessibility
+
+A mounted window is a lie about length, so the true length is stated rather than implied:
+
+- `role="list"` on the grid, with the `label` prop as its accessible name.
+- `aria-setsize` on every cell, carrying the **full** item count.
+- `aria-posinset` naming each cell's real position in that full list.
+- `role="presentation"` on the row wrappers — they are a positioning device and have no
+  business appearing in the structure.
+
+Without `aria-setsize` a screen reader announces "list, 40 items" on a list of 2,000.
+
+Two things windowing genuinely costs, and neither has a fix at this layer: the browser's
+`Ctrl+F` only searches what is mounted, and so does "select all". A page that needs
+either owes its users a search field of its own.
+
+## `getItemKey`
+
+Pass one. Without it the key is the array index, which is wrong the moment the list is
+filtered or an item is removed from the middle — React reuses the mounted subtree and the
+wrong tile inherits the wrong open menu. That is not hypothetical; it is what a
+dismiss-an-item list does on every interaction.