@charcuterie/ui 3.6.0 → 3.7.0

package/src/Field/Field.mdx

@@ -78,6 +78,47 @@ floating node with no trigger and no anchor.
 
 <Canvas of={FieldStories.Nested} />
 
+## Where a prop lands
+
+`FieldProps` and `FieldGroupProps` were **closed** types until 2026-08-21: the only prop a
+caller could legally pass was `className`. That is the sharpest argument for opening them —
+a component whose whole purpose is *configured by props, not a borrowed class* accepted only
+the escape hatch that rule exists to close, so it forced the very thing the rule forbids.
+queuepilot paid for it twice in one modal: a `FieldGroup` that gave up the `id` its
+screenshot suite drives by, and a box beside it that stayed a hand-rolled `<fieldset>`
+because it needed `hidden`.
+
+The rule that opens them is one sentence — **a component's props land on the element it
+owns** — and it reads differently in each component because they own different elements:
+
+| | `Field` | `FieldGroup` |
+| --- | --- | --- |
+| Renders | `<div>` around a **cloned** child | a `<fieldset>` around children rendered as-is |
+| Rest props land on | the **control** | the **`<fieldset>`** |
+| `className` lands on | the `<div>` | the `<fieldset>` |
+| So you can pass | `name`, `placeholder`, `autoFocus`, `aria-*`, `ref` | `id`, `hidden`, `ref`, and `disabled` / `form` / `name` |
+
+`Field`'s destination is not a new one, it is the existing one finally declared: the runtime
+already spread everything it received into the clone, and `id` has named the control since
+the component shipped. Routing the rest to the `<div>` would have moved that `id`, silently,
+in every consumer.
+
+It also could not have been done safely. A slot is a pass-through and **cannot tell who
+wrote a prop** — a `Tooltip` above hands down `getReferenceProps()`, and the author types on
+the same object. Holding the author's props back at the `<div>` needs a closed runtime
+allow-list, and an allow-list is `FieldTooltip`'s silent drop rebuilt inside the fix for it:
+the first slot that writes an `aria-expanded` breaks, and nothing says so.
+
+So a caller who wants a handle on the **box** — an `id` for a screenshot, a `hidden` that
+takes the label with it — wants `FieldGroup`. It wraps rather than clones, so its props have
+nowhere else to go.
+
+`disabled` on a `<fieldset>` is worth knowing before reaching for it: the platform disables
+every control inside the element, not just the box. That is usually what a caller means, and
+it is something a `<div>`-based group could not have offered at all.
+
+<Canvas of={FieldStories.ForwardsRestProps} />
+
 ## Several controls are a `FieldGroup`, not a `Field`
 
 `Field` mints one id and clones it onto one child. An `id` names one element and a

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/slotProps.ts

@@ -127,13 +127,27 @@ export type SlotProps = Pick<
  * inner one won. The outer panel had no anchor and rendered in the
  * corner of the viewport — no error, no failing test, and it looks
  * like a CSS bug.
+ *
+ * ### A wrapping component uses it too, and keeps its own prop type
+ *
+ * `receivedProps` is generic in `ReceivedProps extends SlotProps`
+ * rather than plain `SlotProps`, so the return type carries whatever
+ * the caller actually holds instead of narrowing it to the five keys.
+ * `FieldGroup` is the reason: it does not clone, its rest props land
+ * on its own `<fieldset>`, and it writes an `aria-describedby` that
+ * has to **join** a caller's rather than replace it. Narrowing to
+ * `SlotProps` on the way out would have dropped `disabled`, `form`,
+ * `name` and every `data-*` from the type of the object it spreads
+ * onto that element — the props would still arrive at runtime, and
+ * only the type would have lied.
  */
 export const mergeSlotProps = <
+  ReceivedProps extends SlotProps,
   OwnProps extends Record<string, unknown>,
 >(
-  receivedProps: SlotProps,
+  receivedProps: ReceivedProps,
   ownProps: OwnProps,
-): OwnProps & SlotProps => {
+): OwnProps & ReceivedProps => {
   const definedOwnProps = Object.fromEntries(
     Object.entries(ownProps).filter(
       ([, value]) => value !== undefined,