@charcuterie/ui 0.2.0 → 1.0.0

package/dist/slotProps.d.ts

@@ -0,0 +1,110 @@
+import type { InputHTMLAttributes } from "react";
+/**
+ * The props a **cloning ancestor** injects into the control below it.
+ *
+ * `Field` and `Tooltip` both take one child and `cloneElement` onto
+ * it — "cloned, not wrapped", which is what lets a `Field` go around
+ * an `<input>`, a `Select`, or an app's own control without changing
+ * that control's layout. The contract has a hole in it the moment two
+ * of them are nested:
+ *
+ * ```tsx
+ * <Field label="Pattern" isRequired>
+ *   <Tooltip label="A JavaScript regular expression">
+ *     <input />
+ *   </Tooltip>
+ * </Field>
+ * ```
+ *
+ * `Field` clones onto the **`Tooltip` element**, so `id`,
+ * `aria-describedby`, `aria-invalid` and `required` are handed to a
+ * component that declares none of them — and `cloneElement` does not
+ * care. React drops them without a warning, TypeScript never sees
+ * them (`Children.only` returns a `ReactElement` with `any` props),
+ * every test still passes, and the render is pixel-identical. The
+ * `<label>` then points at an `id` that is nowhere in the document.
+ *
+ * **Silent prop-dropping is the worst version of this**, so the rule
+ * is: *a slot component is a pass-through*. Anything in `SlotProps`
+ * that arrives from above is forwarded to the child this component
+ * clones onto, so a chain of slots behaves like the one control at
+ * the bottom of it.
+ *
+ * ### The list is closed, the forwarding is not
+ *
+ * Worth being exact, because the two are easy to conflate. This type
+ * is a closed list of five keys rather than an index signature: it is
+ * exactly the wiring `Field` writes plus the wiring `Tooltip` writes,
+ * it is greppable, and it is the set whose **merge semantics are
+ * defined** — which for four of them is last-write-wins and for
+ * `aria-describedby` is a join.
+ *
+ * The *runtime* forwards everything. Both components collect their
+ * received props with a rest spread and `mergeSlotProps` starts from
+ * `...receivedProps`, so an ancestor's `onPointerEnter`, its
+ * `onFocus`, its `ref` — none of which are named here — reach the
+ * control at the bottom too. That is not an oversight, it is load
+ * bearing: a `Tooltip` around a `Field` hands down `useHover`,
+ * `useFocus`, `useDismiss` and `refs.setReference`, and a `Field`
+ * that forwarded only the five keys below would leave the tip with no
+ * trigger and no anchor. A closed *runtime* filter would be
+ * mux-magic's `FieldTooltip` defect rebuilt inside the fix for it.
+ *
+ * The five keys, and who writes them:
+ *
+ * | Key | Written by |
+ * | --- | --- |
+ * | `aria-describedby` | `Field` (its description and its error) **and** `Tooltip` (its tip) — the one key that is a list, and the reason `mergeSlotProps` exists |
+ * | `aria-invalid` | `Field`, derived from `error` being present |
+ * | `aria-required` | `Field`, from `isRequired` — the announced constraint, for a composite control the browser does not validate |
+ * | `id` | `Field`, so its `<label htmlFor>` has something to point at. A caller may also pass one directly, which is how a consumer pins a stable id for a deep link or an autofill hint |
+ * | `required` | `Field`, from `isRequired` — the constraint the browser validates |
+ *
+ * ### Why these are `Pick`ed and not written out
+ *
+ * Three of the five are booleans whose names cannot start with `is`
+ * or `has`, because they are not our names — they are the DOM's, and
+ * they are spread onto a DOM node verbatim. The house rule has
+ * [no carve-out](../../../docs/decisions/2026-07-29-is-has-rule-has-no-external-api-carve-out.md)
+ * for that: a *type property* is a shape we own, an object literal
+ * key is someone else's contract, and no `eslint-disable` is
+ * available because unused disable directives are themselves an
+ * error.
+ *
+ * So this type does not declare a shape. It **selects** one out of
+ * React's own `InputHTMLAttributes`, which is the honest description
+ * of what it is: five keys of the props React already types for an
+ * `<input>`, forwarded unchanged. The same reasoning as the
+ * `Record<string, boolean>` in `createReactAdapter` — we are not
+ * describing React's shape, we are naming the keys of it we touch —
+ * and it has the side benefit that `aria-invalid` gets React's real
+ * type (`"grammar"` and `"spelling"` are legal values) rather than
+ * the `boolean` a hand-written version would have narrowed it to.
+ */
+export type SlotProps = Pick<InputHTMLAttributes<HTMLElement>, "aria-describedby" | "aria-invalid" | "aria-required" | "id" | "required">;
+/**
+ * Merge what arrived from above with what this component writes
+ * itself.
+ *
+ * Everything here is a single value and last-write-wins is correct
+ * for it — **except `aria-describedby`, which is a list**. Two slot
+ * components each writing their own onto one control is the entire
+ * nesting problem in one attribute: a `Field` naming its description
+ * and its error, and a `Tooltip` naming its tip. A plain spread keeps
+ * one of them and loses the other, which is the same silent drop by a
+ * shorter route.
+ *
+ * **Outer first.** A screen reader reads the list in order, and the
+ * field's own description and error are the control's primary
+ * explanation; a tip is supplementary by construction. The ordering
+ * inside a single `Field` — description, then error — is `Field`'s
+ * own concern and is unaffected.
+ *
+ * `undefined` in `ownProps` is *absence*, not an instruction to
+ * clear. Both callers spell their optional wiring as
+ * `isRequired || undefined`, so a plain spread would let an inner
+ * `Field` with no error erase an outer one's `aria-invalid` — the
+ * same silent drop, one level down.
+ */
+export declare const mergeSlotProps: <OwnProps extends Record<string, unknown>>(receivedProps: SlotProps, ownProps: OwnProps) => OwnProps & SlotProps;
+//# sourceMappingURL=slotProps.d.ts.map

package/dist/slotProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotProps.d.ts","sourceRoot":"","sources":["../src/slotProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAC1B,mBAAmB,CAAC,WAAW,CAAC,EAC9B,kBAAkB,GAClB,cAAc,GACd,eAAe,GACf,IAAI,GACJ,UAAU,CACb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAExC,eAAe,SAAS,EACxB,UAAU,QAAQ,KACjB,QAAQ,GAAG,SAoBb,CAAA"}

package/dist/slotProps.js

@@ -0,0 +1,39 @@
+/**
+ * Merge what arrived from above with what this component writes
+ * itself.
+ *
+ * Everything here is a single value and last-write-wins is correct
+ * for it — **except `aria-describedby`, which is a list**. Two slot
+ * components each writing their own onto one control is the entire
+ * nesting problem in one attribute: a `Field` naming its description
+ * and its error, and a `Tooltip` naming its tip. A plain spread keeps
+ * one of them and loses the other, which is the same silent drop by a
+ * shorter route.
+ *
+ * **Outer first.** A screen reader reads the list in order, and the
+ * field's own description and error are the control's primary
+ * explanation; a tip is supplementary by construction. The ordering
+ * inside a single `Field` — description, then error — is `Field`'s
+ * own concern and is unaffected.
+ *
+ * `undefined` in `ownProps` is *absence*, not an instruction to
+ * clear. Both callers spell their optional wiring as
+ * `isRequired || undefined`, so a plain spread would let an inner
+ * `Field` with no error erase an outer one's `aria-invalid` — the
+ * same silent drop, one level down.
+ */
+export const mergeSlotProps = (receivedProps, ownProps) => {
+    const definedOwnProps = Object.fromEntries(Object.entries(ownProps).filter(([, value]) => value !== undefined));
+    const describedBy = [
+        receivedProps["aria-describedby"],
+        ownProps["aria-describedby"],
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return {
+        ...receivedProps,
+        ...definedOwnProps,
+        "aria-describedby": describedBy === "" ? undefined : describedBy,
+    };
+};
+//# sourceMappingURL=slotProps.js.map

package/dist/slotProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotProps.js","sourceRoot":"","sources":["../src/slotProps.ts"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAG5B,aAAwB,EACxB,QAAkB,EACI,EAAE;IACxB,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CACxC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CACnC,CACU,CAAA;IAEb,MAAM,WAAW,GAAG;QAClB,aAAa,CAAC,kBAAkB,CAAC;QACjC,QAAQ,CAAC,kBAAkB,CAAC;KAC7B;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO;QACL,GAAG,aAAa;QAChB,GAAG,eAAe;QAClB,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;KAC/C,CAAA;AACH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",
@@ -43,8 +43,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@charcuterie/logic": "0.1.0",
-    "@charcuterie/tokens": "0.2.0",
+    "@charcuterie/logic": "1.0.0",
+    "@charcuterie/tokens": "1.0.0",
     "@floating-ui/react": "^0.27.20"
   },
   "peerDependencies": {

package/src/Field/Field.mdx

@@ -7,9 +7,23 @@ import * as FieldStories from "./Field.stories";
 # Field
 
 Sixteen files in the fleet spell a label, a control, and a hint, and no two spell the
-wiring the same way. mux-magic's `FieldLabel` renders a `<label>` with **no `htmlFor`** —
-which looks correct, reads correctly to a sighted user, and gives a screen reader an
-unnamed textbox.
+wiring the same way.
+
+An earlier version of this page said mux-magic's `FieldLabel` renders a `<label>` with
+**no `htmlFor`**. That is false, and worth correcting rather than quietly deleting: it
+renders ``htmlFor={`${stepId}-${field.name}`}``, and has since it was written. The defect
+is at the *other* end of the pair — **8 of its 16 call sites never render that id on
+anything**. Measured on `mux-magic@master`, the eight that do are `BooleanField`,
+`ChapterSplitsField`, `EnumField`, `NumberField`, `NumberWithLookupField`, `PathField`,
+`StringArrayField` and `StringField`. Of the rest, `RegexWithFlagsField` mints its own
+`patternId` / `flagsId` / `sampleId` and `SubtitleRulesField` spells
+``${step.command}-hasDefaultRules`` where the label says ``${step.id}-…``.
+
+The outcome is the same unnamed textbox by a worse route: a `<label>` pointing at an id
+that is nowhere in the document reads as correct in the label's own file, and is only
+wrong in the *other* file. Half of them are broken and nothing says which half. That is
+the argument for a component rather than a convention — here the id is minted and consumed
+in one place and cannot be spelled twice.
 
 <Canvas of={FieldStories.Default} />
 
@@ -25,6 +39,62 @@ Cloned, not wrapped — the same contract as `Popover`'s trigger. An `<input>`,
 
 <Canvas of={FieldStories.AllVariants} />
 
+## A slot is a pass-through
+
+Which is a rule this component needed and did not have. `Field` and `Tooltip` both clone
+onto their single child, so the obvious thing to write —
+
+```tsx
+<Field label="Rename pattern" isRequired>
+  <Tooltip label="A JavaScript regular expression.">
+    <input />
+  </Tooltip>
+</Field>
+```
+
+— handed `id`, `aria-describedby`, `aria-invalid` and `required` to the **`Tooltip`
+component**, which declares none of them. `cloneElement` does not care. React drops all
+four without a warning, TypeScript never sees it (`Children.only` returns a `ReactElement`
+whose props are `any`), every test still passed, and the render was pixel-identical. The
+only symptom was a `<label htmlFor>` pointing at an id nowhere in the document — the exact
+defect above, reproduced by the component built to prevent it, and this time by the
+library rather than by a consumer.
+
+**Silent prop-dropping is the worst version of this**, so anything a slot receives from
+above is forwarded to the child it clones onto, and a chain of slots behaves like the one
+control at the bottom of it. `aria-describedby` — the one prop that is a *list* — is
+merged rather than overwritten, outer first.
+
+It works in both orders, and the second is not symmetrical: a `Tooltip` around a `Field`
+hands down not one attribute but a working component — floating-ui's hover, focus and
+dismiss handlers and `refs.setReference`. Those reach the control too, or the tip is a
+floating node with no trigger and no anchor.
+
+<Canvas of={FieldStories.Nested} />
+
+## 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
+`<label htmlFor>` points at one, so the moment there are two controls the label names one
+of them and leaves the rest anonymous. Six of mux-magic's sixteen field components are in
+that position — `RegexWithFlagsField` (pattern, flags, sample, and a checkbox),
+`NumberWithLookupField`, `LanguageCodeField`, `LanguageCodesField`, `SubtitleTypesField`
+and `RenameRegexField`.
+
+`FieldGroup` renders `<fieldset>` + `<legend>` and does **not** clone. This is the one
+place in the library where `<fieldset>` is right: `AccordionSection` rejected it for its
+panel precisely because that element means *form-control grouping*, and here the content
+really is one. `<legend>` names the group natively, so no `role="group"` and no
+`aria-labelledby`.
+
+What a group cannot carry is `aria-invalid`, which has no group form — it belongs on the
+control that is actually invalid, and a `FieldGroup` does not know which one that is. So
+`error` here is **described, not asserted**: it joins the `<fieldset>`'s
+`aria-describedby`. Cloning `aria-invalid` onto every child would mark the valid ones
+invalid. A control that is itself invalid says so in its own `Field`.
+
+<Canvas of={FieldStories.Group} />
+
 ## `createLinkedIds` is *not* here, and that is the finding
 
 The plan expected `useLinkedIds` to do this wiring. It does not fit, for the same reason it

package/src/Field/Field.stories.tsx

@@ -5,7 +5,9 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { Select } from "../Select/Select.tsx"
+import { Tooltip } from "../Tooltip/Tooltip.tsx"
 import { Field } from "./Field.tsx"
+import { FieldGroup } from "./FieldGroup.tsx"
 
 const TEXT_INPUT_CLASS =
   "w-full rounded-md border border-border-default bg-surface-raised px-3 py-2 text-content-primary text-sm focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-offset-(--focus-ring-offset) focus-visible:outline-focus-ring"
@@ -142,3 +144,137 @@ export const AllStates: Story = {
     </StoryGrid>
   ),
 }
+
+/**
+ * Two slot components around one control, in both orders.
+ *
+ * `Field` and `Tooltip` each clone onto their single child, so
+ * nesting them used to hand `Field`'s `id`, `aria-describedby`,
+ * `aria-invalid` and `required` to the `Tooltip` **component** —
+ * which declares none of them and dropped all four, silently, with an
+ * identical render and a `<label>` pointing at an id that was nowhere
+ * in the document.
+ *
+ * A slot is a pass-through: whatever arrives from above is forwarded
+ * to the child at the bottom of the chain, and `aria-describedby` —
+ * the one prop that is a *list* — is merged rather than overwritten,
+ * outer first.
+ */
+export const Nested: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="tooltip inside field">
+        <Field
+          description="Applied to every title."
+          isRequired
+          label="Rename pattern"
+        >
+          <Tooltip label="A JavaScript regular expression.">
+            <input
+              className={TEXT_INPUT_CLASS}
+              defaultValue="^(.*)$"
+              type="text"
+            />
+          </Tooltip>
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="field inside tooltip">
+        <Tooltip label="Where finished rips are moved.">
+          <Field error="Not writable." label="Archive path">
+            <input
+              className={TEXT_INPUT_CLASS}
+              defaultValue="/mnt/readonly"
+              type="text"
+            />
+          </Field>
+        </Tooltip>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * `FieldGroup` — one label over **several** controls, which is where
+ * `Field` cannot go: an `id` names one element and a
+ * `<label htmlFor>` points at one.
+ *
+ * Six of mux-magic's sixteen field components are in this position,
+ * and every one of them renders a `FieldLabel` whose `htmlFor` names
+ * at best one of the controls under it. The element for the job is a
+ * `<fieldset>` with a `<legend>` — the one place in this library
+ * where `<fieldset>` is right, because here the content really *is* a
+ * form-control grouping.
+ */
+export const Group: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="several controls">
+        <FieldGroup
+          description="Applied to every title in the disc."
+          isRequired
+          label="Rename pattern"
+        >
+          <div className="flex gap-2">
+            <input
+              aria-label="Pattern"
+              className={TEXT_INPUT_CLASS}
+              defaultValue="^(.*)$"
+              type="text"
+            />
+
+            <input
+              aria-label="Flags"
+              className={TEXT_INPUT_CLASS}
+              defaultValue="gi"
+              type="text"
+            />
+          </div>
+
+          <input
+            aria-label="Sample"
+            className={TEXT_INPUT_CLASS}
+            defaultValue="Disc 1 — Title 04"
+            type="text"
+          />
+        </FieldGroup>
+      </StoryCell>
+
+      <StoryCell label="invalid group">
+        <FieldGroup
+          error="A pattern needs at least one capture group."
+          label="Chapter split"
+        >
+          <div className="flex gap-2">
+            <Select
+              label="Unit"
+              options={[
+                { label: "Chapters", value: "chapters" },
+                { label: "Minutes", value: "minutes" },
+              ]}
+            />
+
+            <input
+              aria-label="Every"
+              className={TEXT_INPUT_CLASS}
+              defaultValue="5"
+              type="number"
+            />
+          </div>
+        </FieldGroup>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Field/Field.test.tsx

@@ -1,5 +1,5 @@
 import { composeStories } from "@storybook/react"
-import { expect } from "storybook/test"
+import { expect, waitFor } from "storybook/test"
 import { test } from "vitest"
 
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Field.stories.tsx"
 
-const { AllStates, AllVariants, Default } =
+const { AllStates, AllVariants, Default, Group, Nested } =
   composeStories(stories)
 
 test("the label names the control it points at", async () => {
@@ -16,9 +16,10 @@ test("the label names the control it points at", async () => {
 
   // The whole point of the component in one query: the control is
   // findable by the *label's* text, which is only true if `htmlFor`
-  // and the control's `id` agree. mux-magic's `FieldLabel` renders
-  // a `<label>` with no `htmlFor` at all — it looks right, reads
-  // right to a sighted user, and gives this query nothing.
+  // and the control's `id` agree. mux-magic's `FieldLabel` does
+  // render a `htmlFor` — 8 of its 16 call sites just never render
+  // that id on anything, so the pair agrees in one file and not in
+  // the other, and this query gets nothing.
   const control = expectAgentDrivable(canvas, {
     name: "Output directory",
     role: "textbox",
@@ -114,6 +115,146 @@ test("an error is the only source of invalidity", async () => {
   await expectNoAxeViolations(canvasElement)
 })
 
+/**
+ * The nesting defect, and the reason `SlotProps` exists.
+ *
+ * `Field` clones onto its one child. With a `Tooltip` in between, the
+ * child is the **`Tooltip` element**, so `id`, `aria-describedby`,
+ * `aria-invalid` and `required` were handed to a component that
+ * declares none of them. `cloneElement` does not care, TypeScript
+ * never sees it, and the render is pixel-identical — the only
+ * symptom is a `<label htmlFor>` pointing at an id that is nowhere in
+ * the document, which is exactly the unnamed textbox this component
+ * exists to prevent.
+ *
+ * The query below is the proof: finding the control **by the label's
+ * text** is only possible if the `id` reached the `<input>` at the
+ * bottom of the chain.
+ */
+test("a slot forwards what an outer slot gave it", async () => {
+  const { canvas, canvasElement } = await mountStory(Nested)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Rename pattern",
+    role: "textbox",
+  })
+
+  await expect(control).toBeRequired()
+
+  await expect(control).toHaveAttribute(
+    "aria-required",
+    "true",
+  )
+
+  await expect(
+    document.getElementById(
+      control.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent("Applied to every title.")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The same drop in reverse — and the half that nearly shipped
+ * untested.
+ *
+ * The first draft of the test above closed with an `aria-invalid`
+ * assertion on the inner control of the *other* cell and called that
+ * the reverse case. It is not: `Field` writes `aria-invalid` itself,
+ * from its own `error` prop, so that assertion holds whether or not a
+ * single thing arrived from the `Tooltip` above it. Reverting
+ * `Field`'s half of the fix left the whole file green.
+ *
+ * What a `Tooltip` hands down is not one attribute, it is a working
+ * component: `getReferenceProps()`'s hover, focus and dismiss
+ * handlers, `refs.setReference`, and an `aria-describedby` naming the
+ * tip. All of it lands on the `Field` **element**, and `Field` has to
+ * pass every bit of it through to the control at the bottom or the
+ * tip is a floating node with no trigger, no anchor and nobody
+ * pointed at it — mux-magic's `FieldTooltip` defect 1, reproduced by
+ * a library that shipped the fix for it.
+ *
+ * So the assertion is the tip *opening from the inner control's own
+ * focus* and then being named by it, which needs the handlers, the
+ * ref and the attribute to have all three arrived.
+ */
+test("a slot forwards what an outer slot gave it, in the other order", async () => {
+  const { canvas } = await mountStory(Nested)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Archive path",
+    role: "textbox",
+  })
+
+  // Focus on the control, not on the `Field` — `Field` renders a
+  // `<div>`, which cannot take focus, so a tip that opens here can
+  // only have been wired to the `<input>`.
+  control.focus()
+
+  await waitFor(() => {
+    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+      "Where finished rips are moved.",
+    )
+  })
+
+  const [tipId, errorId] = (
+    control.getAttribute("aria-describedby") ?? ""
+  ).split(" ")
+
+  // Outer first, which here is the tip: the merge order is
+  // structural — whoever wrapped whom — and the author of the nesting
+  // is the one who chose it.
+  await expect(
+    document.getElementById(tipId ?? ""),
+  ).toHaveTextContent("Where finished rips are moved.")
+
+  await expect(
+    document.getElementById(errorId ?? ""),
+  ).toHaveTextContent("Not writable.")
+})
+
+/**
+ * `aria-describedby` is the one slot prop that is a **list**, so the
+ * merge is not last-write-wins. A `Field` names its description and
+ * its error; a `Tooltip` names its tip. A plain spread keeps one and
+ * loses the other — the same silent drop by a shorter route.
+ *
+ * Outer first: the field's own explanation before the supplementary
+ * tip.
+ */
+test("a tip is described alongside the field's own text, not instead of it", async () => {
+  const { canvas } = await mountStory(Nested)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Rename pattern",
+    role: "textbox",
+  })
+
+  control.focus()
+
+  // `useFocus` is what opens it — the line mux-magic's hand-rolled
+  // tip is missing, and the reason this is testable without a
+  // pointer at all.
+  await waitFor(() => {
+    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+      "A JavaScript regular expression.",
+    )
+  })
+
+  const [descriptionId, tipId] = (
+    control.getAttribute("aria-describedby") ?? ""
+  ).split(" ")
+
+  await expect(
+    document.getElementById(descriptionId ?? ""),
+  ).toHaveTextContent("Applied to every title.")
+
+  await expect(
+    document.getElementById(tipId ?? ""),
+  ).toHaveTextContent("A JavaScript regular expression.")
+})
+
 /**
  * Order inside `aria-describedby` is behaviour, not formatting. A
  * screen reader reads the list in sequence, and "absolute paths only
@@ -140,3 +281,64 @@ test("description is described before error", async () => {
     document.getElementById(errorId ?? ""),
   ).toHaveTextContent("That path is not writable.")
 })
+
+/**
+ * `Field` cannot go here and the failure is quiet: an `id` names one
+ * element and a `<label htmlFor>` points at one, so a label over three
+ * inputs names one of them and leaves the other two anonymous. Six of
+ * mux-magic's sixteen field components are in exactly that state.
+ *
+ * `<fieldset>` + `<legend>` is the platform's answer, and it is the
+ * one place in this library where the element is right — the content
+ * really is a form-control grouping.
+ */
+test("a group is named by its legend, and its controls keep their own names", async () => {
+  const { canvas, canvasElement } = await mountStory(Group)
+
+  const group = expectAgentDrivable(canvas, {
+    // "Rename pattern", not "Rename pattern *" — the asterisk is
+    // `aria-hidden`, so it is decoration and stays out of the name.
+    name: "Rename pattern",
+    role: "group",
+  })
+
+  // Every control inside is still individually findable. A group
+  // that swallows its members' names is the same defect one level up.
+  for (const name of ["Pattern", "Flags", "Sample"]) {
+    expectAgentDrivable(canvas, { name, role: "textbox" })
+  }
+
+  await expect(
+    document.getElementById(
+      group.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent("Applied to every title in the disc.")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `aria-invalid` has no group form — it belongs on the control that
+ * is actually invalid, and a `FieldGroup` does not know which one
+ * that is. So the error is *described*, not *asserted*, and the
+ * alternative — cloning `aria-invalid` onto every child — would mark
+ * the valid ones invalid.
+ */
+test("a group describes its error rather than asserting invalidity", async () => {
+  const { canvas } = await mountStory(Group)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Chapter split",
+    role: "group",
+  })
+
+  await expect(group).not.toHaveAttribute("aria-invalid")
+
+  await expect(
+    document.getElementById(
+      group.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent(
+    "A pattern needs at least one capture group.",
+  )
+})