@charcuterie/ui 3.5.0 → 3.7.0

package/src/Checkbox/Checkbox.tsx

@@ -1,3 +1,4 @@
+import { useUniqueId } from "@charcuterie/logic"
 import type { ControlSize } from "@charcuterie/tokens"
 import type { ChangeEvent, ReactNode } from "react"
 
@@ -6,6 +7,20 @@ import { toClassName } from "../toClassName.ts"
 
 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
@@ -77,6 +92,25 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
   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: Record<
+  ControlSize,
+  string
+> = {
+  sm: "ps-5.5",
+  md: "ps-6",
+  lg: "ps-7",
+}
+
 /**
  * A single boolean, on or off, that owns nothing but itself.
  *
@@ -97,6 +131,30 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
  * 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
@@ -108,6 +166,7 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
  */
 export const Checkbox = ({
   className,
+  description,
   id,
   isChecked = false,
   isDisabled = false,
@@ -116,142 +175,192 @@ export const Checkbox = ({
   onChange,
   size = "md",
   value,
-}: CheckboxProps): ReactNode => (
-  <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,
-    )}
-  >
-    <span className="relative grid shrink-0 place-items-center">
-      <input
-        aria-readonly={isReadOnly || undefined}
+}: CheckboxProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const descriptionId = `${baseId}-description`
+
+  return (
+    <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,
+      )}
+    >
+      <label
         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",
+          "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",
-          BOX_SIZE_CLASS[size],
-          FOCUS_RING_CLASS,
+          // 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",
         )}
-        defaultChecked={isChecked}
-        disabled={isDisabled}
-        id={id}
-        onChange={(
-          event: ChangeEvent<HTMLInputElement>,
-        ) => {
-          if (isReadOnly) {
-            return
-          }
+      >
+        <span className="relative grid shrink-0 place-items-center">
+          <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: ChangeEvent<HTMLInputElement>,
+            ) => {
+              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}
-      />
+              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}
+          />
 
-      <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"
-      >
-        <path d="M20 6 9 17l-5-5" />
-      </svg>
+          <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"
+          >
+            <path d="M20 6 9 17l-5-5" />
+          </svg>
 
-      {/* The mixed mark — a dash, not a tick. Its own element rather
+          {/* The mixed mark — a dash, not a tick. Its own element rather
           than a second `<path>` in the tick's `<svg>`, because the
           two states have to be able to hide independently and a
           `<path>` cannot carry a `peer-*` variant of its own. */}
-      <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"
-      >
-        <path d="M6 12h12" />
-      </svg>
-    </span>
+          <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"
+          >
+            <path d="M6 12h12" />
+          </svg>
+        </span>
 
-    <span>{label}</span>
-  </label>
-)
+        <span>{label}</span>
+      </label>
+
+      {/*
+        `text-sm` and `content-secondary`, the same two the `Field`
+        description wears — one hint typography for the whole library,
+        so a `Checkbox` and a `Field` in the same box do not disagree
+        about how big a hint is. That disagreement is what kept
+        queuepilot's dyn editor on an app-styled `<p>` for one hint out
+        of three.
+      */}
+      {description === undefined ? null : (
+        <p
+          className={toClassName(
+            "text-content-secondary text-sm",
+            DESCRIPTION_INDENT_CLASS[size],
+          )}
+          id={descriptionId}
+        >
+          {description}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/Field/Field.mdx

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

package/src/Field/Field.stories.tsx

@@ -329,3 +329,82 @@ export const Group: Story = {
     </StoryGrid>
   ),
 }
+
+/**
+ * Where a prop lands, in both components, side by side.
+ *
+ * `FieldProps` and `FieldGroupProps` were **closed** types until
+ * 2026-08-21: the only prop a caller could legally pass was
+ * `className`, so a component whose whole purpose is "configured by
+ * props, not a borrowed class" forced the borrowed class. queuepilot's
+ * `#dyn-lineup` gave up an `id` its screenshot suite drives by, and
+ * the box beside it stayed a hand-rolled `<fieldset>` because it
+ * needed `hidden`.
+ *
+ * The rule that opens them is one sentence with two readings, because
+ * the two components own different elements:
+ *
+ *  - **`Field` clones its child**, so its props are that **control's**
+ *    props. `name`, `placeholder`, `autoFocus`, `aria-describedby` and
+ *    `id` all reach the `<input>` — `id` always did, which is why the
+ *    rest go with it rather than moving it.
+ *  - **`FieldGroup` wraps its children**, so its props are the
+ *    **`<fieldset>`'s**. `id`, `hidden`, `ref`, and the element's own
+ *    `disabled`, `form` and `name`.
+ *
+ * `className` is the exception on `Field` alone: a class describes the
+ * box a parent lays out, so it stays on the wrapping `<div>`.
+ */
+export const ForwardsRestProps: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="field: the props are the control's">
+        <Field
+          // Composed with the field's own description and error, not
+          // replaced by them — `aria-describedby` is the one prop in
+          // the set that is a list.
+          aria-describedby="scratch-path-policy"
+          description="Absolute paths only."
+          error="That path is not writable."
+          label="Scratch path"
+          name="scratchPath"
+          placeholder="/mnt/scratch"
+        >
+          <input className={TEXT_INPUT_CLASS} type="text" />
+        </Field>
+
+        <p
+          className="mt-1.5 text-content-secondary text-sm"
+          id="scratch-path-policy"
+        >
+          Cleared between runs.
+        </p>
+      </StoryCell>
+
+      <StoryCell label="group: the props are the fieldset's">
+        <FieldGroup
+          description="The whole group is turned off by the element itself."
+          // `disabled` on a `<fieldset>` is not decoration: the
+          // platform disables every control inside it. A `<div>`-based
+          // group could not have offered this at all.
+          disabled
+          id="playback-lineup"
+          label="Playback"
+        >
+          <input
+            aria-label="Episodes"
+            className={TEXT_INPUT_CLASS}
+            defaultValue="12"
+            type="number"
+          />
+        </FieldGroup>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}