@charcuterie/ui 3.5.0 → 3.7.0

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/Stepper/Stepper.mdx

@@ -0,0 +1,86 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as StepperStories from "./Stepper.stories";
+
+<Meta of={StepperStories} />
+
+# Stepper
+
+An ordered sequence of steps, with **what belongs to each one** under it.
+
+Docket asked for this. Its phases — *"these 3 cards have to be done in order"* — were a
+hand-rolled numbered rail with a connector drawn in a `::before`, and a `ProgressBar` per
+phase for the count. Neither says which things go together.
+
+<Canvas of={StepperStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why a step carries content
+
+This is the difference between a stepper and a progress bar with a legend. A bar says a
+sequence is half done; only the contents say **which three things go together and which
+one is next**.
+
+```tsx
+<Stepper
+  label="Ingest sequence"
+  steps={phases.map((phase) => ({
+    content: <TaskList tasks={tasksIn(phase)} />,
+    description: gateReason(phase),
+    key: phase.id,
+    label: phase.name,
+    status: statusOf(phase),
+  }))}
+/>
+```
+
+## The four statuses, and why `blocked` is not a worse `upcoming`
+
+| Status | Means |
+| --- | --- |
+| `done` | Finished. |
+| `current` | Being worked on. |
+| `upcoming` | Its turn has not come. |
+| `blocked` | Its turn **has** come and something is in the way. |
+
+The last two look alike and are not. `upcoming` is a thing to wait for; `blocked` is a
+thing to go and fix, and collapsing them hides the second behind the first. Docket's case
+is exact: a phase gated behind an *unfinished* phase is normal, and a phase gated behind an
+**empty** one is a mistake somebody has to correct — the same grey pill for both is how
+that sits unnoticed.
+
+## Status is never colour alone
+
+Four marker colours is four colours as far as assistive technology, a greyscale print and
+the ePaper build are concerned — a WCAG 1.4.1 failure however clear it looks. So the status
+reaches a screen reader as a **word**, in a `VisuallyHidden` beside the label, and gets a
+second visual channel besides hue: a filled marker for finished work, an outlined one
+ahead of it, and a connector that is solid behind and subdued in front.
+
+## The marker is the ordinal, never a tick
+
+This library
+[ships no icons and no symbol glyphs](?path=/docs/guides-decisions--docs). A `✓` renders as
+an empty box wherever the font lacks it — the sandbox chromium, the kiosk image, the ePaper
+build — and an empty box in the "done" position reads as an *error*, which is the opposite
+of what it meant. The ordinal always renders. An app that owns a glyph set passes one as
+`marker`.
+
+## `horizontal` is a request, not a promise
+
+It collapses to the vertical column below `cq-md`. Four steps side by side in a narrow
+container squash into `2. / De- / dupe` — measured, in the app this came out of, before any
+of them contained anything. A step carrying `content` should stay vertical regardless: a
+column cannot hold a list.
+
+<Canvas of={StepperStories.Responsive} />
+
+## There is nothing to focus
+
+A stepper is a **document outline**, not a widget: an `<ol>` of headings. Advancing is the
+app's operation and the component only reports where the sequence got to, so there is no
+roving focus, no `aria-current` on a control, and nothing to arrow between. If your steps
+are *navigable* — a checkout you can click back into — you want `Tabs`.