@charcuterie/ui 0.2.0 → 1.0.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAKrD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAqB,CAAA;AAM5C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAEtC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAK3B,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA6B,CAAA;AAExD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAiC,CAAA;AAE9D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA6B,CAAA;AAExD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAK1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA+C,CAAA;AAKnF,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAKrD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAK7D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAKtC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAK/C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA+B,CAAA;AAE3D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gCAAgC,CAAA;AAKvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAyC,CAAA;AAO1E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAqB,CAAA;AAK5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAyB,CAAA;AAKlD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA+C,CAAA;AAEnF,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAC/C,OAAO,EACL,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAO1B,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAEtC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAKzC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAyB,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAqC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAKrD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAqB,CAAA;AAM5C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAEtC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAK3B,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA6B,CAAA;AAExD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAwB,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAiC,CAAA;AAE9D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA6B,CAAA;AAExD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAK1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA+C,CAAA;AAKnF,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAKrD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA2B,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAK7D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAKtC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAK/C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA+B,CAAA;AAE3D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gCAAgC,CAAA;AAKvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAyC,CAAA;AAO1E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAqB,CAAA;AAK5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAyB,CAAA;AAKlD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA+C,CAAA;AAEnF,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EACL,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAO1B,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAiB,CAAA;AAEtC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAmB,CAAA;AAKzC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAyB,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAuB,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAqC,CAAA"}

package/dist/slotProps.d.ts

@@ -0,0 +1,121 @@
+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.
+ *
+ * ### The wiring is not a value, and does not last-write-win
+ *
+ * `ref` and the `on*` handlers are merged rather than replaced, by
+ * `mergeSlotWiring`. This was the 1.0.0 hole: `mergeSlotProps`
+ * settled the five *attributes* and left the two props that are not
+ * attributes on last-write-wins, so a `Menu` and a `Tooltip` on one
+ * trigger each handed it a floating-ui `refs.setReference` and the
+ * 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.
+ */
+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;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAExC,eAAe,SAAS,EACxB,UAAU,QAAQ,KACjB,QAAQ,GAAG,SA2Bb,CAAA"}

package/dist/slotProps.js

@@ -0,0 +1,55 @@
+import { mergeSlotWiring } from "./slotWiring.js";
+/**
+ * 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.
+ *
+ * ### The wiring is not a value, and does not last-write-win
+ *
+ * `ref` and the `on*` handlers are merged rather than replaced, by
+ * `mergeSlotWiring`. This was the 1.0.0 hole: `mergeSlotProps`
+ * settled the five *attributes* and left the two props that are not
+ * attributes on last-write-wins, so a `Menu` and a `Tooltip` on one
+ * trigger each handed it a floating-ui `refs.setReference` and the
+ * 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.
+ */
+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,
+        // Last, because it is the only merge that has to beat
+        // `definedOwnProps` — it is composing what that spread would
+        // otherwise have thrown away.
+        ...mergeSlotWiring(receivedProps, definedOwnProps),
+    };
+};
+//# sourceMappingURL=slotProps.js.map

package/dist/slotProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotProps.js","sourceRoot":"","sources":["../src/slotProps.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AA6FjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;QAC9C,sDAAsD;QACtD,6DAA6D;QAC7D,8BAA8B;QAC9B,GAAG,eAAe,CAChB,aAAwC,EACxC,eAAe,CAChB;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/slotWiring.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The two props a slot may not overwrite, and how it merges them.
+ *
+ * `mergeSlotProps` next door settles the five *attributes* two
+ * nested slots both write, and last-write-wins is right for four of
+ * them. It is not right for the wiring, because neither of these is
+ * a value:
+ *
+ *  - **`ref`** is a subscription. `Menu` and `Tooltip` on one trigger
+ *    both hand it a floating-ui `refs.setReference` — the anchor each
+ *    of them positions its panel against — and the inner one used to
+ *    replace the outer one's. Nothing threw. The outer panel simply
+ *    had no reference element, so floating-ui left it at
+ *    `left: 0; top: 0` in the corner of the viewport, which reads as
+ *    a CSS bug and is not one.
+ *  - **`on*`** is a listener, and listeners are plural.
+ *
+ * ### Why this is not imported from `@charcuterie/logic`
+ *
+ * `useClonedChild`'s `mergeClonedProps` applies the same rule one
+ * level down — between a slot and the element a caller wrote — and
+ * the two are near-identical. Sharing them means a new public export
+ * on `@charcuterie/logic`, which is a `minor`; this is a patch, and
+ * the duplication is thirty lines against a wrong version number.
+ * Queued in `docs/2026-08-02-reported-by-consumers-queued-for-1-1.md`.
+ */
+/**
+ * The keys of `ownProps` that must not simply replace the ones
+ * `receivedProps` arrived with. Spread **last**, over both.
+ */
+export declare const mergeSlotWiring: (receivedProps: Record<string, unknown>, ownProps: Record<string, unknown>) => Record<string, unknown>;
+//# sourceMappingURL=slotWiring.d.ts.map

package/dist/slotWiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotWiring.d.ts","sourceRoot":"","sources":["../src/slotWiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAuGH;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,eAAe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAqCtB,CAAA"}

package/dist/slotWiring.js

@@ -0,0 +1,115 @@
+/**
+ * The two props a slot may not overwrite, and how it merges them.
+ *
+ * `mergeSlotProps` next door settles the five *attributes* two
+ * nested slots both write, and last-write-wins is right for four of
+ * them. It is not right for the wiring, because neither of these is
+ * a value:
+ *
+ *  - **`ref`** is a subscription. `Menu` and `Tooltip` on one trigger
+ *    both hand it a floating-ui `refs.setReference` — the anchor each
+ *    of them positions its panel against — and the inner one used to
+ *    replace the outer one's. Nothing threw. The outer panel simply
+ *    had no reference element, so floating-ui left it at
+ *    `left: 0; top: 0` in the corner of the viewport, which reads as
+ *    a CSS bug and is not one.
+ *  - **`on*`** is a listener, and listeners are plural.
+ *
+ * ### Why this is not imported from `@charcuterie/logic`
+ *
+ * `useClonedChild`'s `mergeClonedProps` applies the same rule one
+ * level down — between a slot and the element a caller wrote — and
+ * the two are near-identical. Sharing them means a new public export
+ * on `@charcuterie/logic`, which is a `minor`; this is a patch, and
+ * the duplication is thirty lines against a wrong version number.
+ * Queued in `docs/2026-08-02-reported-by-consumers-queued-for-1-1.md`.
+ */
+const isEventHandlerName = (name) => /^on[A-Z]/.test(name);
+const isMergeableRef = (value) => typeof value === "function" ||
+    (typeof value === "object" &&
+        value !== null &&
+        "current" in value);
+const setRef = (ref, node) => {
+    if (typeof ref === "function") {
+        return ref(node);
+    }
+    ref.current = node;
+    return undefined;
+};
+/**
+ * Every pair of refs ever merged, so the same two always come back
+ * as the **same function** — which is load-bearing rather than
+ * frugal.
+ *
+ * React re-runs a callback ref whenever its identity changes between
+ * renders, detaching with the old one and attaching with the new.
+ * Both refs here are floating-ui `setReference`s, and calling one
+ * sets state; a merged ref rebuilt every render would call both
+ * twice per render, each call scheduling the render that rebuilds
+ * it. `mergeSlotProps` is a plain function called during render, so
+ * it cannot reach for `useMemo` — the memo has to be in the identity
+ * of the inputs, which is what a `WeakMap` of `WeakMap`s is.
+ */
+const mergedRefs = new WeakMap();
+const mergeRefs = (first, second) => {
+    const bySecond = mergedRefs.get(first) ??
+        new WeakMap();
+    mergedRefs.set(first, bySecond);
+    const cached = bySecond.get(second);
+    if (cached) {
+        return cached;
+    }
+    const merged = (node) => {
+        const cleanups = [
+            setRef(first, node),
+            setRef(second, node),
+        ];
+        // Per ref: one that returned a cleanup has opted out of being
+        // called with `null`, and one that did not still expects it.
+        return () => {
+            for (const [index, cleanup] of cleanups.entries()) {
+                if (typeof cleanup === "function") {
+                    cleanup();
+                }
+                else {
+                    setRef(index === 0 ? first : second, null);
+                }
+            }
+        };
+    };
+    bySecond.set(second, merged);
+    return merged;
+};
+const chainHandlers = (first, second) => (...args) => {
+    // Outer first, the same order `aria-describedby` is joined in:
+    // the merge order is structural — whoever wrapped whom — and the
+    // author of the nesting is the one who chose it.
+    first(...args);
+    second(...args);
+};
+/**
+ * The keys of `ownProps` that must not simply replace the ones
+ * `receivedProps` arrived with. Spread **last**, over both.
+ */
+export const mergeSlotWiring = (receivedProps, ownProps) => Object.fromEntries(Object.entries(ownProps).flatMap(([name, ownValue]) => {
+    const receivedValue = receivedProps[name];
+    if (name === "ref" &&
+        isMergeableRef(receivedValue) &&
+        isMergeableRef(ownValue)) {
+        return [
+            [name, mergeRefs(receivedValue, ownValue)],
+        ];
+    }
+    if (isEventHandlerName(name) &&
+        typeof receivedValue === "function" &&
+        typeof ownValue === "function") {
+        return [
+            [
+                name,
+                chainHandlers(receivedValue, ownValue),
+            ],
+        ];
+    }
+    return [];
+}));
+//# sourceMappingURL=slotWiring.js.map

package/dist/slotWiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotWiring.js","sourceRoot":"","sources":["../src/slotWiring.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "0.2.0",
+  "version": "1.0.1",
   "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.1",
+    "@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>
+  ),
+}