@charcuterie/ui 3.6.0 → 3.7.0

package/dist/Checkbox/Checkbox.d.ts

@@ -2,6 +2,20 @@ import type { ControlSize } from "@charcuterie/tokens";
 import type { ReactNode } from "react";
 export type CheckboxProps = {
     className?: string;
+    /**
+     * Standing help under the box — units, a consequence, a warning
+     * about what ticking it does. Same slot, same words and same
+     * announcement order as `Field`'s: bound with `aria-describedby`,
+     * so a screen reader reads it **with** the control rather than
+     * announcing it from nowhere.
+     *
+     * It renders **outside** the `<label>` on purpose. A `<label>`'s
+     * text content *is* the control's accessible name, so a hint put
+     * inside it would be read twice — once as part of the name, once as
+     * the description — and a pointer press anywhere on the hint would
+     * toggle the box.
+     */
+    description?: ReactNode;
     /**
      * The caller's own id, when it has one — a stable target for an
      * autofill hint or a deep link. Left to React's `useId` on the
@@ -74,6 +88,30 @@ export type CheckboxProps = {
  * also the one label association that needs no `for` at all, so there
  * is no minted-then-dropped id to get wrong.
  *
+ * ### A description is the one thing that cannot go in the `<label>`
+ *
+ * `Field` has had a `description` since it shipped and this component
+ * had none, so a hint could not follow its checkbox. Downstream that
+ * meant one hint out of three in a group stayed an app-styled
+ * paragraph and the box carried two hint typographies.
+ *
+ * The slot is here now, and it renders **outside** the `<label>`.
+ * A `<label>`'s text content is the control's accessible name, so a
+ * hint inside it is announced twice — once inside the name, once
+ * again as the description — and a pointer press on the hint toggles
+ * the box, which is not what a sentence of explanation should do. So
+ * the `<label>` is no longer the outermost element: a `<div>` holds
+ * the row and the hint, `className` moves out to it (`className` is
+ * the outermost box a component renders, and that rule does not bend
+ * for this one), and `aria-describedby` binds the two back together.
+ *
+ * There is no `error` here to go with it. `Field` derives
+ * `aria-invalid` from its error, and a lone boolean is almost never
+ * the invalid thing — a **group** of them is, and a group's error
+ * belongs on the `FieldGroup` around it, described rather than
+ * asserted. Adding one per box would put `aria-invalid` on a control
+ * that is not itself wrong.
+ *
  * ### The `<input>` is the store
  *
  * `defaultChecked`, not `checked`. The DOM owns a checkbox's state
@@ -83,5 +121,5 @@ export type CheckboxProps = {
  * `<input>`'s job. `isChecked` seeds the first paint and nothing
  * after.
  */
-export declare const Checkbox: ({ className, id, isChecked, isDisabled, isReadOnly, label, onChange, size, value, }: CheckboxProps) => ReactNode;
+export declare const Checkbox: ({ className, description, id, isChecked, isDisabled, isReadOnly, label, onChange, size, value, }: CheckboxProps) => ReactNode;
 //# sourceMappingURL=Checkbox.d.ts.map

package/dist/Checkbox/Checkbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../src/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAKnD,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IACvC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,GAAI,qFAUtB,aAAa,KAAG,SA0IlB,CAAA"}
+{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../src/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAKnD,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IACvC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,eAAO,MAAM,QAAQ,GAAI,kGAWtB,aAAa,KAAG,SA4LlB,CAAA"}

package/dist/Checkbox/Checkbox.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUniqueId } from "@charcuterie/logic";
 import { FOCUS_RING_CLASS } from "../intentStyles.js";
 import { toClassName } from "../toClassName.js";
 const BOX_SIZE_CLASS = {
@@ -16,6 +17,21 @@ const TEXT_SIZE_CLASS = {
     md: "text-md",
     lg: "text-lg",
 };
+/**
+ * The description hangs under the **label text**, not under the box,
+ * so the hint and the words it explains share a left edge.
+ *
+ * Written out per size rather than computed, because the offset is
+ * `BOX_SIZE_CLASS` plus the label row's `gap-2` and a class name is
+ * never interpolated — `` `ps-${…}` `` generates nothing and fails
+ * silently. sm is 0.875rem + 0.5rem, md is 1rem + 0.5rem, lg is
+ * 1.25rem + 0.5rem.
+ */
+const DESCRIPTION_INDENT_CLASS = {
+    sm: "ps-5.5",
+    md: "ps-6",
+    lg: "ps-7",
+};
 /**
  * A single boolean, on or off, that owns nothing but itself.
  *
@@ -36,6 +52,30 @@ const TEXT_SIZE_CLASS = {
  * also the one label association that needs no `for` at all, so there
  * is no minted-then-dropped id to get wrong.
  *
+ * ### A description is the one thing that cannot go in the `<label>`
+ *
+ * `Field` has had a `description` since it shipped and this component
+ * had none, so a hint could not follow its checkbox. Downstream that
+ * meant one hint out of three in a group stayed an app-styled
+ * paragraph and the box carried two hint typographies.
+ *
+ * The slot is here now, and it renders **outside** the `<label>`.
+ * A `<label>`'s text content is the control's accessible name, so a
+ * hint inside it is announced twice — once inside the name, once
+ * again as the description — and a pointer press on the hint toggles
+ * the box, which is not what a sentence of explanation should do. So
+ * the `<label>` is no longer the outermost element: a `<div>` holds
+ * the row and the hint, `className` moves out to it (`className` is
+ * the outermost box a component renders, and that rule does not bend
+ * for this one), and `aria-describedby` binds the two back together.
+ *
+ * There is no `error` here to go with it. `Field` derives
+ * `aria-invalid` from its error, and a lone boolean is almost never
+ * the invalid thing — a **group** of them is, and a group's error
+ * belongs on the `FieldGroup` around it, described rather than
+ * asserted. Adding one per box would put `aria-invalid` on a control
+ * that is not itself wrong.
+ *
  * ### The `<input>` is the store
  *
  * `defaultChecked`, not `checked`. The DOM owns a checkbox's state
@@ -45,75 +85,95 @@ const TEXT_SIZE_CLASS = {
  * `<input>`'s job. `isChecked` seeds the first paint and nothing
  * after.
  */
-export const Checkbox = ({ className, id, isChecked = false, isDisabled = false, isReadOnly = false, label, onChange, size = "md", value, }) => (_jsxs("label", { className: toClassName("inline-flex items-center gap-2 text-content-secondary select-none", TEXT_SIZE_CLASS[size], 
-    // One cursor, chosen by state — two cursor utilities of the same
-    // specificity do not resolve by class-list order.
-    isDisabled
-        ? "cursor-not-allowed"
-        : isReadOnly
-            ? "cursor-default"
-            : "cursor-pointer", 
-    // Disabled dims the whole control with opacity rather than fading
-    // the box to a quieter token. The token scale has no step between
-    // `border-default` and `border-strong`, so a muted outline was
-    // either invisible or indistinguishable from enabled; `opacity-60`
-    // keeps the full shape and colour and just turns them down, which
-    // is the "present but inactive" the box actually is. Read-only is
-    // *not* dimmed — its whole point is that the value stays readable.
-    // The same treatment is on `Switch` and `RadioGroup`.
-    isDisabled && "opacity-60", className), children: [_jsxs("span", { className: "relative grid shrink-0 place-items-center", children: [_jsx("input", { "aria-readonly": isReadOnly || undefined, className: toClassName(
-                    // `border-2` is the family's shared weight — the `Switch`
-                    // track's `ring-2` and the `RadioGroup` ring match it, so the
-                    // three read as one set — and a 2px edge is also what keeps a
-                    // disabled box visible where a 1px one washed out.
-                    "peer appearance-none rounded-sm border-2 bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard", 
-                    // Read-only wears the **neutral** intent, not the accent: full
-                    // contrast (so the value reads) but plainly not an actionable
-                    // accent control, with a softer `border-default` resting edge.
-                    // Three distinct states result — enabled (accent, crisp),
-                    // disabled (accent, dimmed by the wrapper), read-only (neutral).
-                    // No `disabled:` colour override; the wrapper's `opacity-60`
-                    // does the dimming, and doubling it on the box is what made a
-                    // disabled checkbox vanish.
-                    // `indeterminate:` wears the same fill as `checked:`. It is
-                    // the state a *group* box is in when some of its members are
-                    // ticked, and it cannot be written in markup at all —
-                    // `indeterminate` is a DOM property with no HTML attribute —
-                    // so the only way to reach it is a consumer writing to the
-                    // input. `DataTable`'s select-all box does exactly that, and
-                    // before this line it painted **nothing**: the property was
-                    // set, screen readers announced "mixed", and the box on
-                    // screen was indistinguishable from empty.
-                    isReadOnly
-                        ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid indeterminate:border-intent-neutral-solid indeterminate:bg-intent-neutral-solid"
-                        : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid indeterminate:border-intent-accent-solid indeterminate:bg-intent-accent-solid", isDisabled
-                        ? "cursor-not-allowed"
-                        : isReadOnly
-                            ? "cursor-default"
-                            : "cursor-pointer", BOX_SIZE_CLASS[size], FOCUS_RING_CLASS), defaultChecked: isChecked, disabled: isDisabled, id: id, onChange: (event) => {
-                        if (isReadOnly) {
-                            return;
-                        }
-                        onChange?.(event.target.checked);
-                    }, onClick: (clickEvent) => {
-                        // Native checkboxes have no `readonly`, so the toggle is
-                        // blocked here — `preventDefault` on the click stops the
-                        // checked flip a pointer would make.
-                        if (isReadOnly) {
-                            clickEvent.preventDefault();
-                        }
-                    }, onKeyDown: (keyEvent) => {
-                        // …and Space, the keyboard toggle a click block does not
-                        // cover.
-                        if (isReadOnly && keyEvent.key === " ") {
-                            keyEvent.preventDefault();
-                        }
-                    }, type: "checkbox", value: value }), _jsx("svg", { "aria-hidden": "true", className: toClassName("pointer-events-none invisible absolute peer-checked:visible peer-indeterminate:invisible", 
-                    // Matches whichever fill the box wears, so the tick keeps its
-                    // guaranteed on-solid contrast in either intent.
-                    isReadOnly
-                        ? "text-intent-neutral-on-solid"
-                        : "text-intent-accent-on-solid", CHECK_SIZE_CLASS[size]), fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 3, viewBox: "0 0 24 24", children: _jsx("path", { d: "M20 6 9 17l-5-5" }) }), _jsx("svg", { "aria-hidden": "true", className: toClassName("pointer-events-none invisible absolute peer-indeterminate:visible", isReadOnly
-                        ? "text-intent-neutral-on-solid"
-                        : "text-intent-accent-on-solid", CHECK_SIZE_CLASS[size]), fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeWidth: 3, viewBox: "0 0 24 24", children: _jsx("path", { d: "M6 12h12" }) })] }), _jsx("span", { children: label })] }));
+export const Checkbox = ({ className, description, id, isChecked = false, isDisabled = false, isReadOnly = false, label, onChange, size = "md", value, }) => {
+    const baseId = useUniqueId();
+    const descriptionId = `${baseId}-description`;
+    return (_jsxs("div", { className: toClassName(
+        // The row and its hint stack, and the box stays inline-level so
+        // a `Checkbox` still sits in a sentence, a table cell or a flex
+        // row exactly where the bare `<label>` used to.
+        "inline-flex flex-col gap-1", className), children: [_jsxs("label", { className: toClassName("inline-flex items-center gap-2 text-content-secondary select-none", TEXT_SIZE_CLASS[size], 
+                // One cursor, chosen by state — two cursor utilities of the same
+                // specificity do not resolve by class-list order.
+                isDisabled
+                    ? "cursor-not-allowed"
+                    : isReadOnly
+                        ? "cursor-default"
+                        : "cursor-pointer", 
+                // Disabled dims the whole control with opacity rather than fading
+                // the box to a quieter token. The token scale has no step between
+                // `border-default` and `border-strong`, so a muted outline was
+                // either invisible or indistinguishable from enabled; `opacity-60`
+                // keeps the full shape and colour and just turns them down, which
+                // is the "present but inactive" the box actually is. Read-only is
+                // *not* dimmed — its whole point is that the value stays readable.
+                // The same treatment is on `Switch` and `RadioGroup`.
+                //
+                // It stays on the `<label>` and does NOT reach the description
+                // below, which is a contrast decision rather than an oversight.
+                // axe exempts a disabled control and its own label from the
+                // colour-contrast rule; a sibling paragraph gets no such
+                // exemption, and `content-secondary` at 60% measures **3.77:1**
+                // on `midnight` against a 4.5 threshold. A hint nobody can read
+                // is worse than a hint that does not dim with its control, and
+                // the hint is the part a user reads precisely when they are
+                // asking why the box is turned off.
+                isDisabled && "opacity-60"), children: [_jsxs("span", { className: "relative grid shrink-0 place-items-center", children: [_jsx("input", { "aria-describedby": description === undefined
+                                    ? undefined
+                                    : descriptionId, "aria-readonly": isReadOnly || undefined, className: toClassName(
+                                // `border-2` is the family's shared weight — the `Switch`
+                                // track's `ring-2` and the `RadioGroup` ring match it, so the
+                                // three read as one set — and a 2px edge is also what keeps a
+                                // disabled box visible where a 1px one washed out.
+                                "peer appearance-none rounded-sm border-2 bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard", 
+                                // Read-only wears the **neutral** intent, not the accent: full
+                                // contrast (so the value reads) but plainly not an actionable
+                                // accent control, with a softer `border-default` resting edge.
+                                // Three distinct states result — enabled (accent, crisp),
+                                // disabled (accent, dimmed by the wrapper), read-only (neutral).
+                                // No `disabled:` colour override; the wrapper's `opacity-60`
+                                // does the dimming, and doubling it on the box is what made a
+                                // disabled checkbox vanish.
+                                // `indeterminate:` wears the same fill as `checked:`. It is
+                                // the state a *group* box is in when some of its members are
+                                // ticked, and it cannot be written in markup at all —
+                                // `indeterminate` is a DOM property with no HTML attribute —
+                                // so the only way to reach it is a consumer writing to the
+                                // input. `DataTable`'s select-all box does exactly that, and
+                                // before this line it painted **nothing**: the property was
+                                // set, screen readers announced "mixed", and the box on
+                                // screen was indistinguishable from empty.
+                                isReadOnly
+                                    ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid indeterminate:border-intent-neutral-solid indeterminate:bg-intent-neutral-solid"
+                                    : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid indeterminate:border-intent-accent-solid indeterminate:bg-intent-accent-solid", isDisabled
+                                    ? "cursor-not-allowed"
+                                    : isReadOnly
+                                        ? "cursor-default"
+                                        : "cursor-pointer", BOX_SIZE_CLASS[size], FOCUS_RING_CLASS), defaultChecked: isChecked, disabled: isDisabled, id: id, onChange: (event) => {
+                                    if (isReadOnly) {
+                                        return;
+                                    }
+                                    onChange?.(event.target.checked);
+                                }, onClick: (clickEvent) => {
+                                    // Native checkboxes have no `readonly`, so the toggle is
+                                    // blocked here — `preventDefault` on the click stops the
+                                    // checked flip a pointer would make.
+                                    if (isReadOnly) {
+                                        clickEvent.preventDefault();
+                                    }
+                                }, onKeyDown: (keyEvent) => {
+                                    // …and Space, the keyboard toggle a click block does not
+                                    // cover.
+                                    if (isReadOnly && keyEvent.key === " ") {
+                                        keyEvent.preventDefault();
+                                    }
+                                }, type: "checkbox", value: value }), _jsx("svg", { "aria-hidden": "true", className: toClassName("pointer-events-none invisible absolute peer-checked:visible peer-indeterminate:invisible", 
+                                // Matches whichever fill the box wears, so the tick keeps its
+                                // guaranteed on-solid contrast in either intent.
+                                isReadOnly
+                                    ? "text-intent-neutral-on-solid"
+                                    : "text-intent-accent-on-solid", CHECK_SIZE_CLASS[size]), fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 3, viewBox: "0 0 24 24", children: _jsx("path", { d: "M20 6 9 17l-5-5" }) }), _jsx("svg", { "aria-hidden": "true", className: toClassName("pointer-events-none invisible absolute peer-indeterminate:visible", isReadOnly
+                                    ? "text-intent-neutral-on-solid"
+                                    : "text-intent-accent-on-solid", CHECK_SIZE_CLASS[size]), fill: "none", stroke: "currentColor", strokeLinecap: "round", strokeWidth: 3, viewBox: "0 0 24 24", children: _jsx("path", { d: "M6 12h12" }) })] }), _jsx("span", { children: label })] }), description === undefined ? null : (_jsx("p", { className: toClassName("text-content-secondary text-sm", DESCRIPTION_INDENT_CLASS[size]), id: descriptionId, children: description }))] }));
+};
 //# sourceMappingURL=Checkbox.js.map

package/dist/Checkbox/Checkbox.js.map

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

package/dist/Field/Field.d.ts

@@ -1,6 +1,39 @@
-import type { ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithRef, ReactElement, ReactNode, Ref } from "react";
 import type { SlotProps } from "../slotProps.ts";
-export type FieldProps = SlotProps & {
+/**
+ * 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>`,
@@ -8,6 +41,10 @@ export type FieldProps = SlotProps & {
      * 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
@@ -23,6 +60,11 @@ export type FieldProps = SlotProps & {
     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,
@@ -99,6 +141,29 @@ 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 declare const Field: ({ children, className, description, error, isRequired, label, ...receivedSlotProps }: FieldProps) => ReactNode;
+export {};
 //# sourceMappingURL=Field.d.ts.map

package/dist/Field/Field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,eAAO,MAAM,KAAK,GAAI,sFAQnB,UAAU,KAAG,SAkIf,CAAA"}
+{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,qBAAqB,EACrB,YAAY,EACZ,SAAS,EACT,GAAG,EACJ,MAAM,OAAO,CAAA;AAEd,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,KAAK,qBAAqB,GAAG,IAAI,CAC/B,qBAAqB,CAAC,OAAO,CAAC,EAC9B,UAAU,GAAG,WAAW,GAAG,KAAK,CACjC,CAAA;AAED,MAAM,MAAM,UAAU,GAAG,qBAAqB,GAC5C,SAAS,GAAG;IACV;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,CAAA;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAA;CACvB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,eAAO,MAAM,KAAK,GAAI,sFAQnB,UAAU,KAAG,SAkIf,CAAA"}

package/dist/Field/Field.js

@@ -77,6 +77,28 @@ import { toClassName } from "../toClassName.js";
  * `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, className, description, error, isRequired = false, label, ...receivedSlotProps }) => {
     const baseId = useUniqueId();

package/dist/Field/Field.js.map

@@ -1 +1 @@
-{"version":3,"file":"Field.js","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA2B/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EACpB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,EACL,UAAU,GAAG,KAAK,EAClB,KAAK,EACL,GAAG,iBAAiB,EACT,EAAa,EAAE;IAC1B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,OAAO,GAAI,QAAQ,CAAC,KAAyB,CAAC,EAAE,CAAA;IAEtD,MAAM,SAAS,GACb,iBAAiB,CAAC,EAAE,IAAI,OAAO,IAAI,GAAG,MAAM,UAAU,CAAA;IAExD,MAAM,aAAa,GAAG,GAAG,MAAM,cAAc,CAAA;IAE7C,MAAM,OAAO,GAAG,GAAG,MAAM,QAAQ,CAAA;IAEjC,MAAM,WAAW,GAAG;QAClB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;QAChD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;KACrC;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,MAAM,aAAa,GAAG,cAAc,CAClC,QAAQ,EACR,cAAc,CAAC,iBAAiB,EAAE;QAChC,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QAC9C,6DAA6D;QAC7D,+DAA+D;QAC/D,iDAAiD;QACjD,cAAc,EACZ,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QACxC,sDAAsD;QACtD,8DAA8D;QAC9D,8DAA8D;QAC9D,gDAAgD;QAChD,eAAe,EAAE,UAAU,IAAI,SAAS;QACxC,EAAE,EAAE,SAAS;QACb,QAAQ,EAAE,UAAU,IAAI,SAAS;KAClC,CAAC,CACH,CAAA;IAED,OAAO,CACL,eACE,SAAS,EAAE,WAAW,CACpB,uBAAuB,EACvB,SAAS,CACV,aAED,iBACE,SAAS,EAAC,0CAA0C,EACpD,OAAO,EAAE,SAAS;gBAClB;;;;;;;;;;;;;;;;mBAgBG;gBACH,EAAE,EAAE,GAAG,SAAS,QAAQ,aAEvB,KAAK,EAEL,UAAU,CAAC,CAAC,CAAC,CACZ,8BAKc,MAAM,EAClB,SAAS,EAAC,iCAAiC,kBAGtC,CACR,CAAC,CAAC,CAAC,IAAI,IACF,EAEP,aAAa,EAUb,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAClC,YACE,SAAS,EAAC,gCAAgC,EAC1C,EAAE,EAAE,aAAa,YAEhB,WAAW,GACV,CACL,EAEA,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,YACE,SAAS,EAAC,oCAAoC,EAC9C,EAAE,EAAE,OAAO,YAEV,KAAK,GACJ,CACL,IACG,CACP,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"Field.js","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAS3B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA0E/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EACpB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,EACL,UAAU,GAAG,KAAK,EAClB,KAAK,EACL,GAAG,iBAAiB,EACT,EAAa,EAAE;IAC1B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,OAAO,GAAI,QAAQ,CAAC,KAAyB,CAAC,EAAE,CAAA;IAEtD,MAAM,SAAS,GACb,iBAAiB,CAAC,EAAE,IAAI,OAAO,IAAI,GAAG,MAAM,UAAU,CAAA;IAExD,MAAM,aAAa,GAAG,GAAG,MAAM,cAAc,CAAA;IAE7C,MAAM,OAAO,GAAG,GAAG,MAAM,QAAQ,CAAA;IAEjC,MAAM,WAAW,GAAG;QAClB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;QAChD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;KACrC;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,MAAM,aAAa,GAAG,cAAc,CAClC,QAAQ,EACR,cAAc,CAAC,iBAAiB,EAAE;QAChC,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QAC9C,6DAA6D;QAC7D,+DAA+D;QAC/D,iDAAiD;QACjD,cAAc,EACZ,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QACxC,sDAAsD;QACtD,8DAA8D;QAC9D,8DAA8D;QAC9D,gDAAgD;QAChD,eAAe,EAAE,UAAU,IAAI,SAAS;QACxC,EAAE,EAAE,SAAS;QACb,QAAQ,EAAE,UAAU,IAAI,SAAS;KAClC,CAAC,CACH,CAAA;IAED,OAAO,CACL,eACE,SAAS,EAAE,WAAW,CACpB,uBAAuB,EACvB,SAAS,CACV,aAED,iBACE,SAAS,EAAC,0CAA0C,EACpD,OAAO,EAAE,SAAS;gBAClB;;;;;;;;;;;;;;;;mBAgBG;gBACH,EAAE,EAAE,GAAG,SAAS,QAAQ,aAEvB,KAAK,EAEL,UAAU,CAAC,CAAC,CAAC,CACZ,8BAKc,MAAM,EAClB,SAAS,EAAC,iCAAiC,kBAGtC,CACR,CAAC,CAAC,CAAC,IAAI,IACF,EAEP,aAAa,EAUb,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAClC,YACE,SAAS,EAAC,gCAAgC,EAC1C,EAAE,EAAE,aAAa,YAEhB,WAAW,GACV,CACL,EAEA,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,YACE,SAAS,EAAC,oCAAoC,EAC9C,EAAE,EAAE,OAAO,YAEV,KAAK,GACJ,CACL,IACG,CACP,CAAA;AACH,CAAC,CAAA"}

package/dist/Field/FieldGroup.d.ts

@@ -1,11 +1,36 @@
-import type { ReactNode } from "react";
-export type FieldGroupProps = {
+import type { ComponentPropsWithRef, ReactNode } from "react";
+/**
+ * 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;
@@ -54,5 +79,5 @@ export type FieldGroupProps = {
  * over — the alternative was to clone `aria-invalid` onto every
  * child, which marks the valid ones invalid.
  */
-export declare const FieldGroup: ({ children, className, description, error, isRequired, label, }: FieldGroupProps) => ReactNode;
+export declare const FieldGroup: ({ children, className, description, error, isRequired, label, ...receivedFieldsetProps }: FieldGroupProps) => ReactNode;
 //# sourceMappingURL=FieldGroup.d.ts.map

package/dist/Field/FieldGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldGroup.d.ts","sourceRoot":"","sources":["../../src/Field/FieldGroup.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,UAAU,GAAI,iEAOxB,eAAe,KAAG,SAuEpB,CAAA"}
+{"version":3,"file":"FieldGroup.d.ts","sourceRoot":"","sources":["../../src/Field/FieldGroup.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACV,MAAM,OAAO,CAAA;AAKd;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GACzB,qBAAqB,CAAC,UAAU,CAAC,GAAG;IAClC;;;;OAIG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,UAAU,GAAI,0FAQxB,eAAe,KAAG,SAiFpB,CAAA"}

package/dist/Field/FieldGroup.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useUniqueId } from "@charcuterie/logic";
+import { mergeSlotProps } from "../slotProps.js";
 import { toClassName } from "../toClassName.js";
 /**
  * A label over **several** controls.
@@ -41,7 +42,7 @@ import { toClassName } from "../toClassName.js";
  * over — the alternative was to clone `aria-invalid` onto every
  * child, which marks the valid ones invalid.
  */
-export const FieldGroup = ({ children, className, description, error, isRequired = false, label, }) => {
+export const FieldGroup = ({ children, className, description, error, isRequired = false, label, ...receivedFieldsetProps }) => {
     const baseId = useUniqueId();
     const descriptionId = `${baseId}-description`;
     const errorId = `${baseId}-error`;
@@ -54,7 +55,9 @@ export const FieldGroup = ({ children, className, description, error, isRequired
     ]
         .filter(Boolean)
         .join(" ");
-    return (_jsxs("fieldset", { "aria-describedby": describedBy === "" ? undefined : describedBy, className: toClassName(
+    return (_jsxs("fieldset", { ...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
         // last of which makes it refuse to shrink inside a flex or

package/dist/Field/FieldGroup.js.map

@@ -1 +1 @@
-{"version":3,"file":"FieldGroup.js","sourceRoot":"","sources":["../../src/Field/FieldGroup.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAkB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EACzB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,EACL,UAAU,GAAG,KAAK,EAClB,KAAK,GACW,EAAa,EAAE;IAC/B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAE5B,MAAM,aAAa,GAAG,GAAG,MAAM,cAAc,CAAA;IAE7C,MAAM,OAAO,GAAG,GAAG,MAAM,QAAQ,CAAA;IAEjC,iEAAiE;IACjE,gEAAgE;IAChE,2BAA2B;IAC3B,MAAM,WAAW,GAAG;QAClB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;QAChD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;KACrC;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO,CACL,wCAEI,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAE9C,SAAS,EAAE,WAAW;QACpB,4DAA4D;QAC5D,0DAA0D;QAC1D,2DAA2D;QAC3D,4DAA4D;QAC5D,4CAA4C;QAC5C,gDAAgD,EAChD,SAAS,CACV,aAED,kBAAQ,SAAS,EAAC,qDAAqD,aACpE,KAAK,EAEL,UAAU,CAAC,CAAC,CAAC,CACZ,8BAIc,MAAM,EAClB,SAAS,EAAC,iCAAiC,kBAGtC,CACR,CAAC,CAAC,CAAC,IAAI,IACD,EAER,QAAQ,EAIR,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAClC,YACE,SAAS,EAAC,gCAAgC,EAC1C,EAAE,EAAE,aAAa,YAEhB,WAAW,GACV,CACL,EAEA,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,YACE,SAAS,EAAC,oCAAoC,EAC9C,EAAE,EAAE,OAAO,YAEV,KAAK,GACJ,CACL,IACQ,CACZ,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"FieldGroup.js","sourceRoot":"","sources":["../../src/Field/FieldGroup.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAMhD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA4C/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EACzB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,EACL,UAAU,GAAG,KAAK,EAClB,KAAK,EACL,GAAG,qBAAqB,EACR,EAAa,EAAE;IAC/B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAE5B,MAAM,aAAa,GAAG,GAAG,MAAM,cAAc,CAAA;IAE7C,MAAM,OAAO,GAAG,GAAG,MAAM,QAAQ,CAAA;IAEjC,iEAAiE;IACjE,gEAAgE;IAChE,2BAA2B;IAC3B,MAAM,WAAW,GAAG;QAClB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;QAChD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;KACrC;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO,CACL,uBAUM,cAAc,CAAC,qBAAqB,EAAE;YACxC,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;SAC/C,CAAC,EACF,SAAS,EAAE,WAAW;QACpB,4DAA4D;QAC5D,0DAA0D;QAC1D,2DAA2D;QAC3D,4DAA4D;QAC5D,4CAA4C;QAC5C,gDAAgD,EAChD,SAAS,CACV,aAED,kBAAQ,SAAS,EAAC,qDAAqD,aACpE,KAAK,EAEL,UAAU,CAAC,CAAC,CAAC,CACZ,8BAIc,MAAM,EAClB,SAAS,EAAC,iCAAiC,kBAGtC,CACR,CAAC,CAAC,CAAC,IAAI,IACD,EAER,QAAQ,EAIR,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAClC,YACE,SAAS,EAAC,gCAAgC,EAC1C,EAAE,EAAE,aAAa,YAEhB,WAAW,GACV,CACL,EAEA,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,YACE,SAAS,EAAC,oCAAoC,EAC9C,EAAE,EAAE,OAAO,YAEV,KAAK,GACJ,CACL,IACQ,CACZ,CAAA;AACH,CAAC,CAAA"}

package/dist/slotProps.d.ts

@@ -116,6 +116,19 @@ export type SlotProps = Pick<InputHTMLAttributes<HTMLElement>, "aria-describedby
  * 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 declare const mergeSlotProps: <OwnProps extends Record<string, unknown>>(receivedProps: SlotProps, ownProps: OwnProps) => OwnProps & SlotProps;
+export declare const mergeSlotProps: <ReceivedProps extends SlotProps, OwnProps extends Record<string, unknown>>(receivedProps: ReceivedProps, ownProps: OwnProps) => OwnProps & ReceivedProps;
 //# sourceMappingURL=slotProps.d.ts.map

package/dist/slotProps.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,cAAc,GACzB,aAAa,SAAS,SAAS,EAC/B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAExC,eAAe,aAAa,EAC5B,UAAU,QAAQ,KACjB,QAAQ,GAAG,aA2Bb,CAAA"}

package/dist/slotProps.js

@@ -33,6 +33,19 @@ import { mergeSlotWiring } from "./slotWiring.js";
  * 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, ownProps) => {
     const definedOwnProps = Object.fromEntries(Object.entries(ownProps).filter(([, value]) => value !== undefined));