@charcuterie/ui 0.1.1 → 1.0.0

package/README.md

@@ -18,6 +18,15 @@ M3 ships the **P0 pure-presentation** set: `Spinner`, `Skeleton`, `Button`, `Ico
   is a composition that could not be expressed until
   [`Tabs` moved onto `SinglePicker`](../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md).
 
+**M6a ships the nine P1 components**: `Select`, `Field`, `Accordion`, `LogViewer`, `Menu`,
+`Tooltip`, `SortableTableHeader`, `Toast` (with `ToastRegion`), and `FileDropZone`. Twenty
+five components in all. Four of them changed rules this package had already written down —
+a menu is [named by its trigger](../../docs/decisions/2026-07-31-a-menu-is-named-by-its-trigger.md),
+an accordion panel is [a `group` rather than a landmark](../../docs/decisions/2026-07-31-an-accordion-panel-is-a-group-not-a-landmark.md),
+[`Select` owns no state at all](../../docs/decisions/2026-07-31-select-is-uncontrolled-because-the-platform-owns-the-value.md),
+and [not every boolean is a state kind](../../docs/decisions/2026-07-31-not-every-boolean-is-a-state-kind.md).
+Full write-up: [M6a handoff](../../docs/2026-07-31-m6a-the-p1-components.md).
+
 ## Install and wire
 
 ```ts

package/dist/Accordion/Accordion.d.ts

@@ -0,0 +1,82 @@
+import type { ReactNode } from "react";
+export type AccordionHeadingLevel = 2 | 3 | 4 | 5 | 6;
+export type AccordionItem = {
+    content: ReactNode;
+    isDisabled?: boolean;
+    key: string;
+    label: ReactNode;
+};
+export type AccordionProps = {
+    className?: string;
+    /** **Initial** only. Charcuterie owns it from then on. */
+    expandedKeys?: string[];
+    /**
+     * The heading level the triggers sit at. An accordion inside a
+     * `Card` that already has an `<h2>` needs `3`, and getting this
+     * wrong is a document-outline break that no gate here can see —
+     * it depends entirely on the page.
+     */
+    headingLevel?: AccordionHeadingLevel;
+    /**
+     * Several sections open at once. The default is **exclusive**,
+     * because that is what every one of the fleet's disclosure groups
+     * does today.
+     */
+    isMultiple?: boolean;
+    items: AccordionItem[];
+    onChange?: (expandedKeys: string[]) => void;
+};
+/**
+ * Eleven sites in the fleet, and the plan called it "nearly free
+ * once `Tabs` exists". It is — the exclusive mode is
+ * `VisibilityGroup` and nothing else — but the reason it is worth
+ * shipping is not the saving.
+ *
+ * ### The two-owners bug, live, in the app this milestone migrates
+ *
+ * mux-magic's `JobStepsDisclosure` is built on `<details>`, and
+ * `<details>` **owns `open`**. It also wants the state in a Jotai
+ * atom so a job can be expanded from elsewhere. Reconciling the two
+ * takes three separate mechanisms:
+ *
+ * ```tsx
+ * const detailsRef = useRef<HTMLDetailsElement>(null)
+ * const skipNextToggleRef = useRef(isOpen)
+ *
+ * useEffect(() => {
+ *   if (detailsRef.current) detailsRef.current.open = isOpen
+ * }, [isOpen])
+ *
+ * const handleToggle = (event) => {
+ *   if (skipNextToggleRef.current) {
+ *     skipNextToggleRef.current = false
+ *     return          // ← swallow the toggle our own write just fired
+ *   }
+ *   setStepsOpen(…)
+ * }
+ * ```
+ *
+ * That is the Radix argument from `Popover` pointed at the platform:
+ * a ref to reach past React, an effect to push state into the DOM,
+ * and a guard to stop the DOM's echo coming back. Every one of the
+ * three exists only because two things hold one fact.
+ *
+ * So this is a `<button aria-expanded>` and a `role="region"` — the
+ * ARIA Authoring Practices accordion — with `VisibilityGroup`
+ * holding the state alone. `<details name="…">` is the platform's
+ * own exclusive accordion and was rejected for the same reason, plus
+ * one it cannot fix: **a `<summary>` cannot be disabled**, and four
+ * of the fleet's eleven sites have a section that is unreachable
+ * until a job produces it.
+ *
+ * ### Two kinds, one component, and both hooks always run
+ *
+ * `isMultiple` picks between `VisibilityGroup` and `MultiplePicker`,
+ * and hooks cannot be conditional — so both are created and one is
+ * consulted. That is two empty stores and no DOM, which is cheaper
+ * than the alternative: reimplementing exclusivity on top of
+ * `MultiplePicker` by deselecting the others, which is precisely the
+ * logic `VisibilityGroup` exists to own once.
+ */
+export declare const Accordion: ({ className, expandedKeys, headingLevel, isMultiple, items, onChange, }: AccordionProps) => ReactNode;
+//# sourceMappingURL=Accordion.d.ts.map

package/dist/Accordion/Accordion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Accordion.d.ts","sourceRoot":"","sources":["../../src/Accordion/Accordion.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,SAAS,CAAA;IAClB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;CAC5C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,SAAS,GAAI,yEAOvB,cAAc,KAAG,SAkFnB,CAAA"}

package/dist/Accordion/Accordion.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMultiplePicker, useUniqueId, useVisibilityGroup, } from "@charcuterie/logic";
+import { toClassName } from "../toClassName.js";
+import { AccordionSection } from "./AccordionSection.js";
+/**
+ * Eleven sites in the fleet, and the plan called it "nearly free
+ * once `Tabs` exists". It is — the exclusive mode is
+ * `VisibilityGroup` and nothing else — but the reason it is worth
+ * shipping is not the saving.
+ *
+ * ### The two-owners bug, live, in the app this milestone migrates
+ *
+ * mux-magic's `JobStepsDisclosure` is built on `<details>`, and
+ * `<details>` **owns `open`**. It also wants the state in a Jotai
+ * atom so a job can be expanded from elsewhere. Reconciling the two
+ * takes three separate mechanisms:
+ *
+ * ```tsx
+ * const detailsRef = useRef<HTMLDetailsElement>(null)
+ * const skipNextToggleRef = useRef(isOpen)
+ *
+ * useEffect(() => {
+ *   if (detailsRef.current) detailsRef.current.open = isOpen
+ * }, [isOpen])
+ *
+ * const handleToggle = (event) => {
+ *   if (skipNextToggleRef.current) {
+ *     skipNextToggleRef.current = false
+ *     return          // ← swallow the toggle our own write just fired
+ *   }
+ *   setStepsOpen(…)
+ * }
+ * ```
+ *
+ * That is the Radix argument from `Popover` pointed at the platform:
+ * a ref to reach past React, an effect to push state into the DOM,
+ * and a guard to stop the DOM's echo coming back. Every one of the
+ * three exists only because two things hold one fact.
+ *
+ * So this is a `<button aria-expanded>` and a `role="region"` — the
+ * ARIA Authoring Practices accordion — with `VisibilityGroup`
+ * holding the state alone. `<details name="…">` is the platform's
+ * own exclusive accordion and was rejected for the same reason, plus
+ * one it cannot fix: **a `<summary>` cannot be disabled**, and four
+ * of the fleet's eleven sites have a section that is unreachable
+ * until a job produces it.
+ *
+ * ### Two kinds, one component, and both hooks always run
+ *
+ * `isMultiple` picks between `VisibilityGroup` and `MultiplePicker`,
+ * and hooks cannot be conditional — so both are created and one is
+ * consulted. That is two empty stores and no DOM, which is cheaper
+ * than the alternative: reimplementing exclusivity on top of
+ * `MultiplePicker` by deselecting the others, which is precisely the
+ * logic `VisibilityGroup` exists to own once.
+ */
+export const Accordion = ({ className, expandedKeys, headingLevel = 3, isMultiple = false, items, onChange, }) => {
+    const baseId = useUniqueId();
+    const [initialKey] = expandedKeys ?? [];
+    const group = useVisibilityGroup({
+        onChange: (visibleKey) => {
+            if (!isMultiple) {
+                onChange?.(visibleKey === null ? [] : [visibleKey]);
+            }
+        },
+        visibleKey: initialKey ?? null,
+    });
+    const picker = useMultiplePicker({
+        onChange: (selectedValues) => {
+            if (isMultiple) {
+                onChange?.([...selectedValues]);
+            }
+        },
+        selectedValues: expandedKeys,
+    });
+    /**
+     * Visible **or** pending, the same load-bearing fallback `Tabs`
+     * needs and for the same reason: members register from an effect,
+     * so on the first paint the intent still lives in the pending
+     * field. Reading only the settled one renders every section
+     * collapsed and corrects itself a frame later — a flash on a
+     * desktop and a visible jump on the kiosk Pi.
+     *
+     * **And only until something registers**, which `Tabs` never had
+     * to say because it seeds itself from the first *enabled* tab. A
+     * key that can never register — a disabled section's — stays
+     * pending forever, so an unqualified fallback renders it expanded
+     * permanently and `isDisabled` quietly stops meaning anything.
+     * Found by the story that passes a disabled key on purpose.
+     *
+     * Every member registers in one commit, so this really is "before
+     * the first effects ran" rather than a race between them.
+     */
+    const hasRegistered = isMultiple
+        ? picker.registeredValues.length > 0
+        : group.registeredKeys.length > 0;
+    const expanded = isMultiple
+        ? new Set([
+            ...picker.selectedValues,
+            ...(hasRegistered ? [] : picker.pendingValues),
+        ])
+        : new Set([
+            group.visibleKey ??
+                (hasRegistered ? null : group.pendingKey),
+        ].filter((key) => key !== null));
+    return (_jsx("div", { className: toClassName("flex flex-col divide-y divide-border-subtle overflow-hidden rounded-md border border-border-subtle", className), children: items.map((item, index) => (_jsx(AccordionSection, { headingLevel: headingLevel, id: `${baseId}-trigger-${index}`, isExpanded: expanded.has(item.key), item: item, onToggle: isMultiple ? picker.toggle : group.toggle, panelId: `${baseId}-panel-${index}`, register: isMultiple ? picker.register : group.register }, item.key))) }));
+};
+//# sourceMappingURL=Accordion.js.map

package/dist/Accordion/Accordion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Accordion.js","sourceRoot":"","sources":["../../src/Accordion/Accordion.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAwB,CAAA;AAgCzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EACxB,SAAS,EACT,YAAY,EACZ,YAAY,GAAG,CAAC,EAChB,UAAU,GAAG,KAAK,EAClB,KAAK,EACL,QAAQ,GACO,EAAa,EAAE;IAC9B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAE5B,MAAM,CAAC,UAAU,CAAC,GAAG,YAAY,IAAI,EAAE,CAAA;IAEvC,MAAM,KAAK,GAAG,kBAAkB,CAAS;QACvC,QAAQ,EAAE,CAAC,UAAU,EAAE,EAAE;YACvB,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,QAAQ,EAAE,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;YACrD,CAAC;QACH,CAAC;QACD,UAAU,EAAE,UAAU,IAAI,IAAI;KAC/B,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,iBAAiB,CAAS;QACvC,QAAQ,EAAE,CAAC,cAAc,EAAE,EAAE;YAC3B,IAAI,UAAU,EAAE,CAAC;gBACf,QAAQ,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAA;YACjC,CAAC;QACH,CAAC;QACD,cAAc,EAAE,YAAY;KAC7B,CAAC,CAAA;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,aAAa,GAAG,UAAU;QAC9B,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;QACpC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAA;IAEnC,MAAM,QAAQ,GAAG,UAAU;QACzB,CAAC,CAAC,IAAI,GAAG,CAAC;YACN,GAAG,MAAM,CAAC,cAAc;YACxB,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;SAC/C,CAAC;QACJ,CAAC,CAAC,IAAI,GAAG,CACL;YACE,KAAK,CAAC,UAAU;gBACd,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;SAC5C,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAChC,CAAA;IAEL,OAAO,CACL,cACE,SAAS,EAAE,WAAW,CACpB,oGAAoG,EACpG,SAAS,CACV,YAEA,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAC1B,KAAC,gBAAgB,IACf,YAAY,EAAE,YAAY,EAC1B,EAAE,EAAE,GAAG,MAAM,YAAY,KAAK,EAAE,EAChC,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAClC,IAAI,EAAE,IAAI,EAEV,QAAQ,EACN,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAE3C,OAAO,EAAE,GAAG,MAAM,UAAU,KAAK,EAAE,EACnC,QAAQ,EACN,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAN1C,IAAI,CAAC,GAAG,CAQb,CACH,CAAC,GACE,CACP,CAAA;AACH,CAAC,CAAA"}

package/dist/Accordion/AccordionSection.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { AccordionHeadingLevel, AccordionItem } from "./Accordion.tsx";
+export type AccordionSectionProps = {
+    headingLevel: AccordionHeadingLevel;
+    id: string;
+    isExpanded: boolean;
+    item: AccordionItem;
+    onToggle: (key: string) => void;
+    panelId: string;
+    /**
+     * `VisibilityGroup.register` or `MultiplePicker.register`,
+     * whichever kind the accordion is running. Both have this shape,
+     * which is the point of the kinds being separate rather than one
+     * configurable one.
+     */
+    register: (key: string) => () => void;
+};
+/**
+ * Its own file for the same reason `TabTrigger` is: **registration
+ * is an effect**, and an effect cannot run in a loop.
+ *
+ * A disabled section stays out of the group entirely — it is not a
+ * member, so nothing can expand it, including a consumer passing its
+ * key in `expandedKeys`. That is registration-as-membership again,
+ * and it is the behaviour a `<summary>` cannot have at all.
+ */
+export declare const AccordionSection: ({ headingLevel, id, isExpanded, item, onToggle, panelId, register, }: AccordionSectionProps) => ReactNode;
+//# sourceMappingURL=AccordionSection.d.ts.map

package/dist/Accordion/AccordionSection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccordionSection.d.ts","sourceRoot":"","sources":["../../src/Accordion/AccordionSection.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,KAAK,EACV,qBAAqB,EACrB,aAAa,EACd,MAAM,iBAAiB,CAAA;AAmBxB,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,qBAAqB,CAAA;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,OAAO,CAAA;IACnB,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,IAAI,CAAA;CACtC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,qBAAqB,KAAG,SAsG1B,CAAA"}

package/dist/Accordion/AccordionSection.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { FOCUS_RING_CLASS } from "../intentStyles.js";
+import { toClassName } from "../toClassName.js";
+/**
+ * Written out rather than interpolated into a tag name. React
+ * accepts `` `h${level}` `` perfectly well; a reader and a grep do
+ * not, and "which heading levels does this component emit" should be
+ * answerable by looking.
+ */
+const HEADING_TAG = {
+    2: "h2",
+    3: "h3",
+    4: "h4",
+    5: "h5",
+    6: "h6",
+};
+/**
+ * Its own file for the same reason `TabTrigger` is: **registration
+ * is an effect**, and an effect cannot run in a loop.
+ *
+ * A disabled section stays out of the group entirely — it is not a
+ * member, so nothing can expand it, including a consumer passing its
+ * key in `expandedKeys`. That is registration-as-membership again,
+ * and it is the behaviour a `<summary>` cannot have at all.
+ */
+export const AccordionSection = ({ headingLevel, id, isExpanded, item, onToggle, panelId, register, }) => {
+    const { isDisabled = false, key, label } = item;
+    const Heading = HEADING_TAG[headingLevel];
+    useEffect(() => {
+        if (isDisabled) {
+            return;
+        }
+        return register(key);
+    }, [isDisabled, key, register]);
+    return (_jsxs("div", { className: "bg-surface-raised", children: [_jsx(Heading, { className: "m-0 text-md", children: _jsxs("button", { "aria-controls": panelId, "aria-expanded": isExpanded, className: toClassName("flex w-full cursor-pointer items-center justify-between gap-3 bg-transparent px-4 py-3 text-start font-medium text-content-primary text-sm transition-colors duration-(--duration-fast) ease-standard", "hover:bg-intent-neutral-surface", isDisabled &&
+                        "cursor-not-allowed text-content-disabled hover:bg-transparent", FOCUS_RING_CLASS), disabled: isDisabled, id: id, onClick: () => {
+                        onToggle(key);
+                    }, type: "button", children: [label, _jsx("svg", { "aria-hidden": "true", className: toClassName("size-4 shrink-0 text-content-secondary transition-transform duration-(--duration-fast) ease-standard", isExpanded && "rotate-180"), fill: "none", focusable: false, stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 1.75, viewBox: "0 0 24 24", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "m6 9 6 6 6-6" }) })] }) }), _jsx("div", { "aria-labelledby": id, className: "px-4 pt-1 pb-4 text-content-secondary text-sm", 
+                // `hidden` rather than unmounting, matching `Tabs`. A panel
+                // that unmounts loses a scroll position, a partially typed
+                // form, and any subscription its content opened — and the
+                // fleet's log panes are exactly that.
+                hidden: !isExpanded, id: panelId, 
+                // `group`, not `region`. A `group` is explicitly "a set of
+                // UI objects **not** intended to be included in a page
+                // summary", so it carries `aria-labelledby` and the
+                // trigger↔panel relationship without joining the landmark
+                // list — which is exactly the distinction the APG's caveat
+                // is reaching for and does not have a role for.
+                role: "group", children: item.content })] }));
+};
+//# sourceMappingURL=AccordionSection.js.map

package/dist/Accordion/AccordionSection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccordionSection.js","sourceRoot":"","sources":["../../src/Accordion/AccordionSection.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAM/C;;;;;GAKG;AACH,MAAM,WAAW,GAGb;IACF,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;CACR,CAAA;AAkBD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAC/B,YAAY,EACZ,EAAE,EACF,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,QAAQ,GACc,EAAa,EAAE;IACrC,MAAM,EAAE,UAAU,GAAG,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IAE/C,MAAM,OAAO,GAAG,WAAW,CAAC,YAAY,CAAC,CAAA;IAEzC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,UAAU,EAAE,CAAC;YACf,OAAM;QACR,CAAC;QAED,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IACtB,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE/B,OAAO,CACL,eAAK,SAAS,EAAC,mBAAmB,aAChC,KAAC,OAAO,IAAC,SAAS,EAAC,aAAa,YAC9B,mCACiB,OAAO,mBACP,UAAU,EACzB,SAAS,EAAE,WAAW,CACpB,uMAAuM,EACvM,iCAAiC,EACjC,UAAU;wBACR,+DAA+D,EACjE,gBAAgB,CACjB,EACD,QAAQ,EAAE,UAAU,EACpB,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,GAAG,EAAE;wBACZ,QAAQ,CAAC,GAAG,CAAC,CAAA;oBACf,CAAC,EACD,IAAI,EAAC,QAAQ,aAEZ,KAAK,EAEN,6BAGc,MAAM,EAClB,SAAS,EAAE,WAAW,CACpB,sGAAsG,EACtG,UAAU,IAAI,YAAY,CAC3B,EACD,IAAI,EAAC,MAAM,EACX,SAAS,EAAE,KAAK,EAChB,MAAM,EAAC,cAAc,EACrB,aAAa,EAAC,OAAO,EACrB,cAAc,EAAC,OAAO,EACtB,WAAW,EAAE,IAAI,EACjB,OAAO,EAAC,WAAW,EACnB,KAAK,EAAC,4BAA4B,YAElC,eAAM,CAAC,EAAC,cAAc,GAAG,GACrB,IACC,GACD,EA0BV,iCACmB,EAAE,EACnB,SAAS,EAAC,+CAA+C;gBACzD,4DAA4D;gBAC5D,2DAA2D;gBAC3D,0DAA0D;gBAC1D,sCAAsC;gBACtC,MAAM,EAAE,CAAC,UAAU,EACnB,EAAE,EAAE,OAAO;gBACX,2DAA2D;gBAC3D,uDAAuD;gBACvD,oDAAoD;gBACpD,0DAA0D;gBAC1D,2DAA2D;gBAC3D,gDAAgD;gBAChD,IAAI,EAAC,OAAO,YAEX,IAAI,CAAC,OAAO,GACT,IACF,CACP,CAAA;AACH,CAAC,CAAA"}

package/dist/Field/Field.d.ts

@@ -0,0 +1,104 @@
+import type { ReactElement, ReactNode } from "react";
+import type { SlotProps } from "../slotProps.ts";
+export type FieldProps = SlotProps & {
+    /**
+     * The control. **Cloned, not wrapped** — the same slot contract
+     * as `Popover`'s trigger, so a `Field` can go around an `<input>`,
+     * a `<textarea>`, a `Select`, or an app's own control without
+     * changing that control's layout.
+     */
+    children: ReactElement;
+    className?: string;
+    /**
+     * Standing help — units, a format, a warning about what the value
+     * does. Announced with the control, before any error.
+     */
+    description?: ReactNode;
+    /**
+     * Present means invalid. There is no separate `isInvalid`, because
+     * two sources for one fact is how a control ends up
+     * `aria-invalid="true"` with nothing saying why — which is what
+     * `RegexWithFlagsField` does in mux-magic today.
+     */
+    error?: ReactNode;
+    isRequired?: boolean;
+    label: ReactNode;
+};
+/**
+ * Sixteen files in the fleet spell a label, a control, and a hint,
+ * and no two spell the wiring the same way.
+ *
+ * ### What mux-magic's `FieldLabel` actually gets wrong
+ *
+ * An earlier version of this docstring said it "renders a `<label>`
+ * with no `htmlFor` at all". **That is false** — 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`; the other eight either render no id at all or render
+ * a different one — `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>` that points at an id 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.
+ *
+ * ### The ids are static, and that is why `createLinkedIds` is not here
+ *
+ * The plan expected `useLinkedIds` to do this wiring. It does not
+ * fit, for the same reason it did not fit `Tabs`: that kind exists
+ * for a **dynamic** pairing, where the registration multiset is what
+ * stops an `aria-describedby` naming a node React has already
+ * removed. A field renders its own description and its own error, so
+ * it knows at render which of them exist — the ids come from one
+ * `useUniqueId` and a conditional join, and they cannot get out of
+ * step at all.
+ *
+ * That leaves `createLinkedIds` with **no consumer in this package
+ * across twenty-five components**, which is worth saying plainly
+ * rather than manufacturing a use for. It is the one state kind the
+ * component layer has never needed.
+ *
+ * ### Order matters inside `aria-describedby`
+ *
+ * Description first, error second. A screen reader reads the list in
+ * order, and "millisecondsonly — required" is a different sentence
+ * from "required — milliseconds only". Nothing enforces this but the
+ * order of the array below, which is why it is not built from an
+ * object.
+ *
+ * ### The error is described, not announced
+ *
+ * No `role="alert"` and no live region here, deliberately. An error
+ * bound through `aria-describedby` is read when the control takes
+ * focus, which is when the user can act on it; a live region on the
+ * same text announces it a second time, from nowhere, while the
+ * caret is elsewhere. A form that fails on submit should say so
+ * once, at the top, with the `Alert` this library already ships —
+ * and then the user tabs into the field and hears the specific
+ * reason.
+ *
+ * ### A slot is a pass-through
+ *
+ * A `Tooltip` between the field and its control is the obvious thing
+ * to write, and it is what mux-magic's `FieldLabel` does. Both
+ * components clone onto their one child, so everything below used to
+ * land on the `Tooltip` **component** and be dropped in silence —
+ * leaving the `<label htmlFor>` above pointing at nothing, which is
+ * precisely the defect this component was built to make impossible.
+ * `SlotProps` arriving from an outer slot is forwarded down, and
+ * `aria-describedby` is merged rather than replaced.
+ * `slotProps.ts` has the reasoning.
+ */
+export declare const Field: ({ children, className, description, error, isRequired, label, ...receivedSlotProps }: FieldProps) => ReactNode;
+//# sourceMappingURL=Field.d.ts.map

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

@@ -0,0 +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,SA4Ff,CAAA"}

package/dist/Field/Field.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useClonedChild, useUniqueId, } from "@charcuterie/logic";
+import { mergeSlotProps } from "../slotProps.js";
+import { toClassName } from "../toClassName.js";
+/**
+ * Sixteen files in the fleet spell a label, a control, and a hint,
+ * and no two spell the wiring the same way.
+ *
+ * ### What mux-magic's `FieldLabel` actually gets wrong
+ *
+ * An earlier version of this docstring said it "renders a `<label>`
+ * with no `htmlFor` at all". **That is false** — 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`; the other eight either render no id at all or render
+ * a different one — `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>` that points at an id 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.
+ *
+ * ### The ids are static, and that is why `createLinkedIds` is not here
+ *
+ * The plan expected `useLinkedIds` to do this wiring. It does not
+ * fit, for the same reason it did not fit `Tabs`: that kind exists
+ * for a **dynamic** pairing, where the registration multiset is what
+ * stops an `aria-describedby` naming a node React has already
+ * removed. A field renders its own description and its own error, so
+ * it knows at render which of them exist — the ids come from one
+ * `useUniqueId` and a conditional join, and they cannot get out of
+ * step at all.
+ *
+ * That leaves `createLinkedIds` with **no consumer in this package
+ * across twenty-five components**, which is worth saying plainly
+ * rather than manufacturing a use for. It is the one state kind the
+ * component layer has never needed.
+ *
+ * ### Order matters inside `aria-describedby`
+ *
+ * Description first, error second. A screen reader reads the list in
+ * order, and "millisecondsonly — required" is a different sentence
+ * from "required — milliseconds only". Nothing enforces this but the
+ * order of the array below, which is why it is not built from an
+ * object.
+ *
+ * ### The error is described, not announced
+ *
+ * No `role="alert"` and no live region here, deliberately. An error
+ * bound through `aria-describedby` is read when the control takes
+ * focus, which is when the user can act on it; a live region on the
+ * same text announces it a second time, from nowhere, while the
+ * caret is elsewhere. A form that fails on submit should say so
+ * once, at the top, with the `Alert` this library already ships —
+ * and then the user tabs into the field and hears the specific
+ * reason.
+ *
+ * ### A slot is a pass-through
+ *
+ * A `Tooltip` between the field and its control is the obvious thing
+ * to write, and it is what mux-magic's `FieldLabel` does. Both
+ * components clone onto their one child, so everything below used to
+ * land on the `Tooltip` **component** and be dropped in silence —
+ * leaving the `<label htmlFor>` above pointing at nothing, which is
+ * precisely the defect this component was built to make impossible.
+ * `SlotProps` arriving from an outer slot is forwarded down, and
+ * `aria-describedby` is merged rather than replaced.
+ * `slotProps.ts` has the reasoning.
+ */
+export const Field = ({ children, className, description, error, isRequired = false, label, ...receivedSlotProps }) => {
+    const baseId = useUniqueId();
+    /**
+     * A caller's own `id` wins, which is what makes a `Field` usable
+     * where the id has to be predictable — an autofill hint, a deep
+     * link, a server-rendered error summary linking to the control.
+     * `useUniqueId` is still called: hooks are unconditional, and it
+     * costs one counter read.
+     */
+    const controlId = receivedSlotProps.id ?? `${baseId}-control`;
+    const descriptionId = `${baseId}-description`;
+    const errorId = `${baseId}-error`;
+    const describedBy = [
+        description === undefined ? null : descriptionId,
+        error === undefined ? null : errorId,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const clonedControl = useClonedChild(children, mergeSlotProps(receivedSlotProps, {
+        "aria-describedby": describedBy === "" ? undefined : describedBy,
+        // `aria-invalid` is derived from the error's presence, never
+        // passed. A control marked invalid with no described reason is
+        // a screen reader saying "invalid" and stopping.
+        "aria-invalid": error === undefined ? undefined : true,
+        // Both, and they are not redundant: `required` is the
+        // constraint the browser validates and `aria-required` is the
+        // one it announces on a control the browser does not validate
+        // — a `role="combobox"`, or anything composite.
+        "aria-required": isRequired || undefined,
+        id: controlId,
+        required: isRequired || undefined,
+    }));
+    return (_jsxs("div", { className: toClassName("flex flex-col gap-1.5", className), children: [_jsxs("label", { className: "font-medium text-content-primary text-sm", htmlFor: controlId, children: [label, isRequired ? (_jsx("span", { "aria-hidden": "true", className: "ms-1 text-intent-danger-content", children: "*" })) : null] }), clonedControl, description === undefined ? null : (_jsx("p", { className: "text-content-secondary text-xs", id: descriptionId, children: description })), error === undefined ? null : (_jsx("p", { className: "text-intent-danger-content text-xs", id: errorId, children: error }))] }));
+};
+//# sourceMappingURL=Field.js.map

package/dist/Field/Field.js.map

@@ -0,0 +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;;;;;;OAMG;IACH,MAAM,SAAS,GACb,iBAAiB,CAAC,EAAE,IAAI,GAAG,MAAM,UAAU,CAAA;IAE7C,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,aAEjB,KAAK,EAEL,UAAU,CAAC,CAAC,CAAC,CACZ,8BAKc,MAAM,EAClB,SAAS,EAAC,iCAAiC,kBAGtC,CACR,CAAC,CAAC,CAAC,IAAI,IACF,EAEP,aAAa,EAEb,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

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+export type FieldGroupProps = {
+    /**
+     * The controls. **Rendered as-is, not cloned** — that is the whole
+     * difference from `Field`, and it is why this is a separate
+     * component rather than a boolean on that one.
+     */
+    children: ReactNode;
+    className?: string;
+    /** Standing help for the group as a whole. */
+    description?: ReactNode;
+    /** Present means the group is invalid. */
+    error?: ReactNode;
+    isRequired?: boolean;
+    label: ReactNode;
+};
+/**
+ * A label over **several** controls.
+ *
+ * `Field` mints one id and clones it onto one child, which is the
+ * right shape for a text input and the wrong shape the moment there
+ * are two of them: an `id` can only name one element, and a
+ * `<label htmlFor>` can only point at one. Six of mux-magic's sixteen
+ * field components are in that position — `RegexWithFlagsField`
+ * (pattern, flags, sample, and a checkbox), `NumberWithLookupField`
+ * (three inputs), `LanguageCodeField`, `LanguageCodesField`,
+ * `SubtitleTypesField` (a tag input beside a dropdown) and
+ * `RenameRegexField` (a row per rule) — and every one of them renders
+ * a `FieldLabel` whose `htmlFor` names, at best, one of them.
+ *
+ * ### `<fieldset>` and `<legend>`, not a `<label>`
+ *
+ * This is the one place in the library where `<fieldset>` is right.
+ * `AccordionSection` rejected it for its panel and said why — it is a
+ * *form-control grouping*, and dragging `<legend>` semantics onto
+ * prose is wrong. Here the content **is** a form-control grouping,
+ * so the element means what it says, `<legend>` names the group
+ * natively, and no `role="group"` and no `aria-labelledby` are
+ * needed.
+ *
+ * A `<label>` here would be the mux-magic defect deliberately: a
+ * label pointing at one control, or at none.
+ *
+ * ### What a group cannot carry
+ *
+ * `aria-invalid` has no group form — it belongs on the control that
+ * is actually invalid, and this component does not know which one
+ * that is. So `error` here is *described*, not *asserted*: it joins
+ * `aria-describedby` on the `<fieldset>`, which screen readers read
+ * as focus enters the group. A control inside that is itself invalid
+ * should say so itself, in its own `Field`.
+ *
+ * That is a real limitation and it is stated rather than papered
+ * 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;
+//# sourceMappingURL=FieldGroup.d.ts.map

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

@@ -0,0 +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,SAqEpB,CAAA"}