@eifi1/ui-kit 0.21.0 → 0.23.0

package/dist/components/checkbox-group.d.ts

@@ -0,0 +1,104 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** One box of a {@link CheckboxGroup}. */
+interface CheckboxGroupOption<T extends string = string> {
+    value: T;
+    /** The words beside the box — its accessible name. */
+    label: ReactNode;
+    /** A line under the label ("Imprint, Privacy Policy and Terms only"), attached to the
+     *  box with `aria-describedby` — {@link Checkbox}'s `description`. */
+    hint?: ReactNode;
+    /** This box cannot be changed; the others can. */
+    disabled?: boolean;
+}
+/** Whether the legend is drawn. `"sr-only"` keeps it as the group's name for a screen
+ *  reader where the dialog's title already says it to the eye. */
+type CheckboxGroupLegendVisibility = "visible" | "sr-only";
+interface CheckboxGroupProps<T extends string = string> {
+    /** The question the boxes answer — the fieldset's `<legend>`, which names the group.
+     *  Without one, pass `aria-label`. */
+    legend?: ReactNode;
+    /** Default `"visible"`. */
+    legendVisibility?: CheckboxGroupLegendVisibility;
+    "aria-label"?: string;
+    /** One box per option, in this order. */
+    options: CheckboxGroupOption<T>[];
+    /** The ticked values. Controlled. */
+    value: T[];
+    /**
+     * The new set on every tick. In the ORDER OF `options`, not the order the boxes were
+     * ticked, so a list saved from it does not change with the order someone clicked in
+     * (ChoiceCardGroup's rule). A value in `value` that no option carries — a grant for a
+     * locale the app no longer offers — is kept, after the known ones: a picker that
+     * dropped what it could not show would delete it on the next unrelated tick.
+     */
+    onChange: (value: T[]) => void;
+    /**
+     * `"vertical"` (default): one box per line. `"horizontal"`: a wrapping row, for a few
+     * short labels. With `columns`, vertical becomes a grid of that many columns from the
+     * `sm` breakpoint up and stays one column on a phone — the reviewer dialog's shape.
+     */
+    layout?: "vertical" | "horizontal";
+    /** Columns for a vertical group, from `sm` up (one on a phone). Default 1. */
+    columns?: 1 | 2 | 3 | 4;
+    /** Shared by every box — what a plain form submits the values under. */
+    name?: string;
+    /** Every box: the fieldset's own `disabled` (which disables them all natively), each
+     *  box faded as a disabled Checkbox is, and the legend with them. */
+    disabled?: boolean;
+    /**
+     * At least one box must be ticked. Draws the required star after the legend, and puts
+     * the native `required` on every box while NONE is ticked — so a form refuses an
+     * empty set — and on none once one is (ChoiceCardGroup's rule: checkboxes cannot say
+     * "at least one" natively).
+     */
+    required?: boolean;
+    /**
+     * Standing advice for the group, under the boxes, attached to the fieldset with
+     * `aria-describedby` before the error — the field anatomy every kit field keeps.
+     */
+    hint?: ReactNode;
+    /** What is wrong with the set, in the caller's words. Under the boxes, on the
+     *  fieldset's `aria-describedby`, and paints every box invalid. */
+    error?: ReactNode;
+    /** Paints every box invalid without a message (the message lives elsewhere). */
+    invalid?: boolean;
+    /**
+     * The group SAVES on change — each tick is written straight away (a reviewer's
+     * per-locale grants). Under a locked {@link WriteLockProvider} every box is locked
+     * the focusable way with the lock's reason. See {@link Checkbox}'s `commit`.
+     */
+    commit?: boolean;
+    /** Why no box can be changed — every box gets it, and it wins over `disabled` (the
+     *  boxes stay focusable to say it). See {@link Checkbox}'s `disabledReason`. */
+    disabledReason?: ReactNode;
+    /** The fieldset's id. */
+    id?: string;
+    /** Classes for the fieldset — the outermost element, where layout belongs. */
+    className?: string;
+    /** Classes for the box list (the grid or the row). */
+    listClassName?: string;
+    /** Ids of something else on the page that describes the group; merged before the
+     *  group's own hint and error. */
+    "aria-describedby"?: string;
+}
+/**
+ * A set of kit {@link Checkbox}es answering one question, in a `<fieldset>`.
+ *
+ * Kurvenschmiede's reviewer dialog (features/admin/reviewer-dialog.tsx) builds this by
+ * hand — a fieldset, an `sr-only` legend, a grid of checkboxes, a `toggle(code, on)`
+ * that adds or filters a `string[]` — and keksdose's and kastlan's reviewer grants build
+ * the same picker for the same per-locale grant. The hand-built ones differ in the parts
+ * that are easy to get wrong: whether the legend names the group, whether a hint or an
+ * error is attached to anything, what order the saved list comes out in, and whether a
+ * value the picker cannot show survives a tick.
+ *
+ * Every box is a kit {@link Checkbox}, so the native checkbox semantics stay (each box
+ * submits under `name` in a plain form). The legend is the group's name; the hint and
+ * error describe the fieldset. For a choice of ONE, use radios ({@link ChoiceCardGroup},
+ * {@link ToggleGroup}).
+ */
+declare function CheckboxGroup<T extends string = string>({ legend, legendVisibility, "aria-label": ariaLabel, options, value, onChange, layout, columns, name, disabled, required, hint, error, invalid, commit, disabledReason, id, className, listClassName, "aria-describedby": ariaDescribedBy, }: CheckboxGroupProps<T>): react.JSX.Element;
+
+export { CheckboxGroup, type CheckboxGroupLegendVisibility, type CheckboxGroupOption, type CheckboxGroupProps };

package/dist/components/checkbox-group.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { cn } from "../lib/cn.js";
+import { Checkbox } from "./checkbox.js";
+import { hasMessage, mergeDescribedBy } from "./choice-parts.js";
+import { useCommitReason } from "./write-lock.js";
+import { RequiredStarOnLegend } from "./field-parts.js";
+const COLUMNS = {
+  1: "flex flex-col gap-2",
+  2: "grid grid-cols-1 gap-2 sm:grid-cols-2",
+  3: "grid grid-cols-1 gap-2 sm:grid-cols-3",
+  4: "grid grid-cols-1 gap-2 sm:grid-cols-2 md:grid-cols-4"
+};
+function CheckboxGroup({
+  legend,
+  legendVisibility = "visible",
+  "aria-label": ariaLabel,
+  options,
+  value,
+  onChange,
+  layout = "vertical",
+  columns = 1,
+  name,
+  disabled,
+  required,
+  hint,
+  error,
+  invalid,
+  commit,
+  disabledReason,
+  id,
+  className,
+  listClassName,
+  "aria-describedby": ariaDescribedBy
+}) {
+  const generated = useId();
+  const hintId = `${generated}-hint`;
+  const errorId = `${generated}-error`;
+  const showHint = hasMessage(hint);
+  const showError = hasMessage(error);
+  const isInvalid = Boolean(invalid) || showError;
+  const ticked = new Set(value);
+  const reason = useCommitReason(commit, disabledReason);
+  const locked = hasMessage(reason);
+  const toggle = (v, on) => {
+    const next = new Set(value);
+    if (on) next.add(v);
+    else next.delete(v);
+    const known = new Set(options.map((o) => o.value));
+    onChange([
+      ...options.map((o) => o.value).filter((x) => next.has(x)),
+      // Values no option carries, kept in their own order — see `onChange`.
+      ...value.filter((x) => !known.has(x))
+    ]);
+  };
+  return /* @__PURE__ */ jsxs(
+    "fieldset",
+    {
+      id,
+      "aria-label": ariaLabel,
+      "aria-describedby": mergeDescribedBy(ariaDescribedBy, showHint && hintId, showError && errorId),
+      disabled: disabled && !locked,
+      className: cn("relative m-0 min-w-0 border-0 p-0", className),
+      children: [
+        legend !== void 0 && /* @__PURE__ */ jsxs(
+          "legend",
+          {
+            className: legendVisibility === "sr-only" ? "sr-only" : cn("mb-2 p-0 text-sm font-medium text-[var(--text-primary)]", (disabled || locked) && "opacity-60"),
+            children: [
+              legend,
+              required && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "ms-0.5 text-[var(--danger)]", children: "*" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx(RequiredStarOnLegend.Provider, { value: true, children: /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              layout === "horizontal" ? "flex flex-wrap gap-x-4 gap-y-2" : COLUMNS[columns],
+              listClassName
+            ),
+            children: options.map((o) => /* @__PURE__ */ jsx(
+              Checkbox,
+              {
+                name,
+                value: o.value,
+                label: o.label,
+                description: o.hint,
+                checked: ticked.has(o.value),
+                onCheckedChange: (on) => toggle(o.value, on),
+                disabled: disabled || o.disabled,
+                invalid: isInvalid || void 0,
+                required: required && value.length === 0 ? true : void 0,
+                disabledReason: reason
+              },
+              o.value
+            ))
+          }
+        ) }),
+        showHint && // A `div`, not a `p`: a hint may be a node with a link in it.
+        /* @__PURE__ */ jsx("div", { id: hintId, className: "mt-1.5 text-[11px] leading-tight text-[var(--text-muted)]", children: hint }),
+        showError && /* @__PURE__ */ jsx("p", { id: errorId, className: "mt-1 text-[11px] leading-tight text-[var(--danger)]", children: error })
+      ]
+    }
+  );
+}
+export {
+  CheckboxGroup
+};
+//# sourceMappingURL=checkbox-group.js.map

package/dist/components/checkbox-group.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/checkbox-group.tsx"],"sourcesContent":["import { useId } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { Checkbox } from \"./checkbox\";\nimport { hasMessage, mergeDescribedBy } from \"./choice-parts\";\nimport { useCommitReason } from \"./write-lock\";\nimport { RequiredStarOnLegend } from \"./field-parts\";\n\n/** One box of a {@link CheckboxGroup}. */\nexport interface CheckboxGroupOption<T extends string = string> {\n  value: T;\n  /** The words beside the box — its accessible name. */\n  label: ReactNode;\n  /** A line under the label (\"Imprint, Privacy Policy and Terms only\"), attached to the\n   *  box with `aria-describedby` — {@link Checkbox}'s `description`. */\n  hint?: ReactNode;\n  /** This box cannot be changed; the others can. */\n  disabled?: boolean;\n}\n\n/** Whether the legend is drawn. `\"sr-only\"` keeps it as the group's name for a screen\n *  reader where the dialog's title already says it to the eye. */\nexport type CheckboxGroupLegendVisibility = \"visible\" | \"sr-only\";\n\nexport interface CheckboxGroupProps<T extends string = string> {\n  /** The question the boxes answer — the fieldset's `<legend>`, which names the group.\n   *  Without one, pass `aria-label`. */\n  legend?: ReactNode;\n  /** Default `\"visible\"`. */\n  legendVisibility?: CheckboxGroupLegendVisibility;\n  \"aria-label\"?: string;\n  /** One box per option, in this order. */\n  options: CheckboxGroupOption<T>[];\n  /** The ticked values. Controlled. */\n  value: T[];\n  /**\n   * The new set on every tick. In the ORDER OF `options`, not the order the boxes were\n   * ticked, so a list saved from it does not change with the order someone clicked in\n   * (ChoiceCardGroup's rule). A value in `value` that no option carries — a grant for a\n   * locale the app no longer offers — is kept, after the known ones: a picker that\n   * dropped what it could not show would delete it on the next unrelated tick.\n   */\n  onChange: (value: T[]) => void;\n  /**\n   * `\"vertical\"` (default): one box per line. `\"horizontal\"`: a wrapping row, for a few\n   * short labels. With `columns`, vertical becomes a grid of that many columns from the\n   * `sm` breakpoint up and stays one column on a phone — the reviewer dialog's shape.\n   */\n  layout?: \"vertical\" | \"horizontal\";\n  /** Columns for a vertical group, from `sm` up (one on a phone). Default 1. */\n  columns?: 1 | 2 | 3 | 4;\n  /** Shared by every box — what a plain form submits the values under. */\n  name?: string;\n  /** Every box: the fieldset's own `disabled` (which disables them all natively), each\n   *  box faded as a disabled Checkbox is, and the legend with them. */\n  disabled?: boolean;\n  /**\n   * At least one box must be ticked. Draws the required star after the legend, and puts\n   * the native `required` on every box while NONE is ticked — so a form refuses an\n   * empty set — and on none once one is (ChoiceCardGroup's rule: checkboxes cannot say\n   * \"at least one\" natively).\n   */\n  required?: boolean;\n  /**\n   * Standing advice for the group, under the boxes, attached to the fieldset with\n   * `aria-describedby` before the error — the field anatomy every kit field keeps.\n   */\n  hint?: ReactNode;\n  /** What is wrong with the set, in the caller's words. Under the boxes, on the\n   *  fieldset's `aria-describedby`, and paints every box invalid. */\n  error?: ReactNode;\n  /** Paints every box invalid without a message (the message lives elsewhere). */\n  invalid?: boolean;\n  /**\n   * The group SAVES on change — each tick is written straight away (a reviewer's\n   * per-locale grants). Under a locked {@link WriteLockProvider} every box is locked\n   * the focusable way with the lock's reason. See {@link Checkbox}'s `commit`.\n   */\n  commit?: boolean;\n  /** Why no box can be changed — every box gets it, and it wins over `disabled` (the\n   *  boxes stay focusable to say it). See {@link Checkbox}'s `disabledReason`. */\n  disabledReason?: ReactNode;\n  /** The fieldset's id. */\n  id?: string;\n  /** Classes for the fieldset — the outermost element, where layout belongs. */\n  className?: string;\n  /** Classes for the box list (the grid or the row). */\n  listClassName?: string;\n  /** Ids of something else on the page that describes the group; merged before the\n   *  group's own hint and error. */\n  \"aria-describedby\"?: string;\n}\n\n// Literal class strings so Tailwind's scanner sees each one.\nconst COLUMNS: Record<NonNullable<CheckboxGroupProps[\"columns\"]>, string> = {\n  1: \"flex flex-col gap-2\",\n  2: \"grid grid-cols-1 gap-2 sm:grid-cols-2\",\n  3: \"grid grid-cols-1 gap-2 sm:grid-cols-3\",\n  4: \"grid grid-cols-1 gap-2 sm:grid-cols-2 md:grid-cols-4\",\n};\n\n/**\n * A set of kit {@link Checkbox}es answering one question, in a `<fieldset>`.\n *\n * Kurvenschmiede's reviewer dialog (features/admin/reviewer-dialog.tsx) builds this by\n * hand — a fieldset, an `sr-only` legend, a grid of checkboxes, a `toggle(code, on)`\n * that adds or filters a `string[]` — and keksdose's and kastlan's reviewer grants build\n * the same picker for the same per-locale grant. The hand-built ones differ in the parts\n * that are easy to get wrong: whether the legend names the group, whether a hint or an\n * error is attached to anything, what order the saved list comes out in, and whether a\n * value the picker cannot show survives a tick.\n *\n * Every box is a kit {@link Checkbox}, so the native checkbox semantics stay (each box\n * submits under `name` in a plain form). The legend is the group's name; the hint and\n * error describe the fieldset. For a choice of ONE, use radios ({@link ChoiceCardGroup},\n * {@link ToggleGroup}).\n */\nexport function CheckboxGroup<T extends string = string>({\n  legend,\n  legendVisibility = \"visible\",\n  \"aria-label\": ariaLabel,\n  options,\n  value,\n  onChange,\n  layout = \"vertical\",\n  columns = 1,\n  name,\n  disabled,\n  required,\n  hint,\n  error,\n  invalid,\n  commit,\n  disabledReason,\n  id,\n  className,\n  listClassName,\n  \"aria-describedby\": ariaDescribedBy,\n}: CheckboxGroupProps<T>) {\n  const generated = useId();\n  const hintId = `${generated}-hint`;\n  const errorId = `${generated}-error`;\n  const showHint = hasMessage(hint);\n  const showError = hasMessage(error);\n  const isInvalid = Boolean(invalid) || showError;\n  const ticked = new Set(value);\n  // Resolved here rather than per box: a reason has to keep the fieldset from being\n  // natively `disabled` too, or it would take every box out of the tab order — the\n  // thing a reason exists to prevent.\n  const reason = useCommitReason(commit, disabledReason);\n  const locked = hasMessage(reason);\n\n  const toggle = (v: T, on: boolean) => {\n    const next = new Set(value);\n    if (on) next.add(v);\n    else next.delete(v);\n    const known = new Set(options.map((o) => o.value));\n    onChange([\n      ...options.map((o) => o.value).filter((x) => next.has(x)),\n      // Values no option carries, kept in their own order — see `onChange`.\n      ...value.filter((x) => !known.has(x)),\n    ]);\n  };\n\n  return (\n    <fieldset\n      id={id}\n      aria-label={ariaLabel}\n      aria-describedby={mergeDescribedBy(ariaDescribedBy, showHint && hintId, showError && errorId)}\n      disabled={disabled && !locked}\n      // `relative` holds an `sr-only` legend (sr-only-containment.test); `min-w-0`\n      // undoes a fieldset's `min-width: min-content`, which would otherwise push a long\n      // label past a phone's edge instead of wrapping it.\n      className={cn(\"relative m-0 min-w-0 border-0 p-0\", className)}\n    >\n      {legend !== undefined && (\n        <legend\n          className={\n            legendVisibility === \"sr-only\"\n              ? \"sr-only\"\n              : cn(\"mb-2 p-0 text-sm font-medium text-[var(--text-primary)]\", (disabled || locked) && \"opacity-60\")\n          }\n        >\n          {legend}\n          {required && (\n            <span aria-hidden className=\"ms-0.5 text-[var(--danger)]\">\n              *\n            </span>\n          )}\n        </legend>\n      )}\n      <RequiredStarOnLegend.Provider value={true}>\n        <div\n          className={cn(\n            layout === \"horizontal\" ? \"flex flex-wrap gap-x-4 gap-y-2\" : COLUMNS[columns],\n            listClassName,\n          )}\n        >\n          {options.map((o) => (\n            <Checkbox\n              key={o.value}\n              name={name}\n              value={o.value}\n              label={o.label}\n              description={o.hint}\n              checked={ticked.has(o.value)}\n              onCheckedChange={(on) => toggle(o.value, on)}\n              disabled={disabled || o.disabled}\n              invalid={isInvalid || undefined}\n              required={required && value.length === 0 ? true : undefined}\n              disabledReason={reason}\n            />\n          ))}\n        </div>\n      </RequiredStarOnLegend.Provider>\n      {showHint && (\n        // A `div`, not a `p`: a hint may be a node with a link in it.\n        <div id={hintId} className=\"mt-1.5 text-[11px] leading-tight text-[var(--text-muted)]\">\n          {hint}\n        </div>\n      )}\n      {showError && (\n        <p id={errorId} className=\"mt-1 text-[11px] leading-tight text-[var(--danger)]\">\n          {error}\n        </p>\n      )}\n    </fieldset>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/checkbox.d.ts

@@ -44,6 +44,25 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "typ
      * label WITHOUT a literal "*". No mark without a label.
      */
     required?: boolean;
+    /**
+     * Why the box cannot be changed — {@link Button}'s `disabledReason`, for a checkbox
+     * that SAVES on change (keksdose K3: a setting ticked straight into the server, kept
+     * behind a hand-rolled `SaveGuard` that forced a native `disabled` — out of the tab
+     * order, so the reason never reached a keyboard).
+     *
+     * With a reason the box is `aria-disabled` instead: still focusable, a click or Space
+     * changes nothing and fires no `onChange` / `onCheckedChange`, the reason is in the
+     * kit {@link Tooltip} on the box and on its `aria-describedby`, and the row fades as a
+     * disabled one does. It wins over `disabled`. Changing the lock mounts the box anew (it
+     * moves in or out of the Tooltip), as a locked Button is.
+     */
+    disabledReason?: ReactNode;
+    /**
+     * This box COMMITS — ticking it saves. Under a locked {@link WriteLockProvider} it is
+     * locked the `disabledReason` way with the lock's reason (which wins over its own).
+     * No provider, or an unlocked one: no effect. Button's `commit`, for keksdose K3.
+     */
+    commit?: boolean;
 }
 /**
  * A native checkbox in the kit's tokens, with an optional label, description and

package/dist/components/checkbox.js

@@ -1,9 +1,10 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useRef } from "react";
+import { forwardRef, useCallback, useContext, useEffect, useId, useRef } from "react";
 import { Check, Minus } from "lucide-react";
 import { cn } from "../lib/cn.js";
 import { assignRef, hasMessage, mergeDescribedBy } from "./choice-parts.js";
+import { LockedReason, RequiredStarOnLegend, useLockReason } from "./field-parts.js";
 const BOX = "peer size-4 shrink-0 cursor-pointer appearance-none rounded-[4px] border border-[var(--border-strong)] bg-[var(--bg-surface)] shadow-sm transition-colors checked:border-[var(--brand)] checked:bg-[var(--brand)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-surface)] disabled:cursor-not-allowed";
 const BOX_MIXED = "border-[var(--brand)] bg-[var(--brand)]";
 const BOX_INVALID = "border-[var(--danger-border-strong)] ring-1 ring-[var(--danger-border-strong)] checked:border-[var(--danger-border-strong)] focus-visible:ring-[var(--danger)]";
@@ -21,10 +22,17 @@ const Checkbox = forwardRef(function Checkbox2({
   id,
   disabled,
   required,
+  disabledReason,
+  commit,
+  onClick,
   ...rest
 }, ref) {
   const generated = useId();
   const inputId = id ?? generated;
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const looksDisabled = Boolean(disabled) || locked;
+  const starOnLegend = useContext(RequiredStarOnLegend);
   const descriptionId = `${inputId}-description`;
   const errorId = `${inputId}-error`;
   const showError = hasMessage(error);
@@ -42,27 +50,41 @@ const Checkbox = forwardRef(function Checkbox2({
   useEffect(() => {
     if (local.current) local.current.indeterminate = indeterminate;
   });
-  const box = /* @__PURE__ */ jsxs("span", { className: cn("relative inline-flex shrink-0", bare && className), children: [
+  const control = /* @__PURE__ */ jsxs("span", { className: cn("relative inline-flex shrink-0", bare && !locked && className), children: [
     /* @__PURE__ */ jsx(
       "input",
       {
         ref: setRef,
         id: bare ? id : inputId,
-        disabled,
+        disabled: locked ? void 0 : disabled,
         required,
         ...rest,
         type: "checkbox",
+        "aria-disabled": locked || rest["aria-disabled"] || void 0,
         "aria-invalid": isInvalid || rest["aria-invalid"] || void 0,
         "aria-describedby": mergeDescribedBy(
           rest["aria-describedby"],
           showDescription && descriptionId,
+          locked && lock.reasonId,
           showError && errorId
         ),
+        onClick: locked ? void 0 : onClick,
         onChange: (e) => {
+          if (locked) {
+            e.currentTarget.checked = !e.currentTarget.checked;
+            e.currentTarget.indeterminate = indeterminate;
+            return;
+          }
           onChange?.(e);
           onCheckedChange?.(e.target.checked);
         },
-        className: cn(BOX, indeterminate && BOX_MIXED, isInvalid && BOX_INVALID, inputClassName)
+        className: cn(
+          BOX,
+          indeterminate && BOX_MIXED,
+          isInvalid && BOX_INVALID,
+          locked && "cursor-not-allowed",
+          inputClassName
+        )
       }
     ),
     indeterminate ? /* @__PURE__ */ jsx(
@@ -81,6 +103,7 @@ const Checkbox = forwardRef(function Checkbox2({
       }
     )
   ] });
+  const box = locked ? /* @__PURE__ */ jsx(LockedReason, { lock, className: cn("shrink-0", bare && className), children: control }) : control;
   if (bare) return box;
   return /* @__PURE__ */ jsxs(
     "div",
@@ -92,7 +115,7 @@ const Checkbox = forwardRef(function Checkbox2({
         "flex items-start gap-2",
         // The whole row fades, the way ToggleGroup and the fields do, so the label does
         // not stay at full strength beside a box you cannot change.
-        disabled && "opacity-60",
+        looksDisabled && "opacity-60",
         className
       ),
       children: [
@@ -106,11 +129,11 @@ const Checkbox = forwardRef(function Checkbox2({
                 "block text-sm leading-5 text-[var(--text-primary)]",
                 // `select-none`: a double-click to toggle twice would otherwise select the
                 // words, and a drag that starts on them starts a native text drag.
-                disabled ? "cursor-not-allowed" : "cursor-pointer select-none"
+                looksDisabled ? "cursor-not-allowed" : "cursor-pointer select-none"
               ),
               children: [
                 label,
-                required && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "ms-0.5 text-[var(--danger)]", children: "*" })
+                required && !starOnLegend && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "ms-0.5 text-[var(--danger)]", children: "*" })
               ]
             }
           ),

package/dist/components/checkbox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/checkbox.tsx"],"sourcesContent":["import { forwardRef, useCallback, useEffect, useId, useRef } from \"react\";\nimport { Check, Minus } from \"lucide-react\";\nimport type { ChangeEvent, InputHTMLAttributes, ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { assignRef, hasMessage, mergeDescribedBy } from \"./choice-parts\";\n\n/**\n * A checkbox that is still `<input type=\"checkbox\">`.\n *\n * The three consuming apps had three answers: ~30 raw inputs in Keksdose leaning on\n * `tokens.css`'s `accent-color`, a label-plus-box `CheckboxField` in Lenkbank, and a\n * Radix `<button role=\"checkbox\">` in Kastlan. The native element is the one that\n * needs no ARIA to be a checkbox — it submits with its form, answers to `required`,\n * resets with the form and takes a `<label for>` click — so it stays underneath, and\n * only its paint is replaced (`appearance-none`, a token-coloured box, and a glyph\n * laid over it that ignores the pointer so the click still lands on the input).\n *\n * `accent-color` alone was not enough: it tints the native box but cannot change its\n * border, so an INVALID checkbox had no way to say so, and the unchecked box kept the\n * browser's own grey outline in both themes.\n */\n\n// The box. 16px, like every raw checkbox it replaces, so a migration moves nothing.\n//\n// `focus-visible`, with an offset in the surface colour: a --brand ring touching a\n// --brand-filled (checked) box would be a ring painted in the colour it sits on —\n// present in the DOM and invisible on screen. The offset is what separates the two.\nconst BOX =\n  \"peer size-4 shrink-0 cursor-pointer appearance-none rounded-[4px] border border-[var(--border-strong)] bg-[var(--bg-surface)] shadow-sm transition-colors \" +\n  \"checked:border-[var(--brand)] checked:bg-[var(--brand)] \" +\n  \"focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-surface)] \" +\n  \"disabled:cursor-not-allowed\";\n\n// A mixed box wears the checked fill whether or not the underlying input is checked:\n// `indeterminate` is a property the browser keeps separately from `checked`, and the\n// dash means \"some\", which is neither answer.\nconst BOX_MIXED = \"border-[var(--brand)] bg-[var(--brand)]\";\n\n// The same geometry as FIELD_INVALID — a border plus a 1px ring, so the highlight\n// survives fractional display scaling on every edge (see the note in ui.tsx). The\n// focus ring turns danger too, so focusing a wrong box does not repaint it as fine.\nconst BOX_INVALID =\n  \"border-[var(--danger-border-strong)] ring-1 ring-[var(--danger-border-strong)] checked:border-[var(--danger-border-strong)] focus-visible:ring-[var(--danger)]\";\n\nconst ERROR_CLASS = \"mt-1 text-[11px] leading-tight text-[var(--danger)]\";\n\nexport interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, \"type\"> {\n  /**\n   * The words beside the box. Rendered as a `<label for>` rather than a label that\n   * wraps the input, so `description` and `error` can sit under it without becoming\n   * part of the accessible NAME — a wrapping label would have the screen reader read\n   * the whole paragraph as the checkbox's name.\n   */\n  label?: ReactNode;\n  /** Secondary text under the label (\"Used when no account is chosen\"). Pointed at by\n   *  `aria-describedby`, merged with any the caller passed. Kastlan's\n   *  `CheckboxField` `description` variant. */\n  description?: ReactNode;\n  /**\n   * \"Some but not all\" — the header box of a list whose rows are partly selected.\n   * A DOM property with no HTML attribute, so it is set on the element after every\n   * render; it does not touch `checked`, and a click clears it (the browser's rule,\n   * and the caller's `onChange` decides what the click means).\n   */\n  indeterminate?: boolean;\n  /** See {@link Input}'s `invalid`: paints the box and sets `aria-invalid` together,\n   *  so the two cannot be spelled separately. */\n  invalid?: boolean;\n  /** What is wrong, in the caller's words (\"Accept the terms to continue\"). Rendered\n   *  under the label, attached with `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /** The checked state as a boolean — the `(next) => …` shape Lenkbank's\n   *  `CheckboxField` and Radix's `onCheckedChange` both used, so a migration does not\n   *  have to unwrap `event.target.checked` at every call site. Fires alongside\n   *  `onChange`, never instead of it. */\n  onCheckedChange?: (checked: boolean) => void;\n  /** Classes for the `<input>` itself. `className` styles the OUTERMOST element —\n   *  the row when there is a label, the box's own wrapper when there is not — which\n   *  is where layout (`self-end pb-2` to sit on a field's baseline) belongs. */\n  inputClassName?: string;\n  /**\n   * Must be ticked to submit — a consent, an acceptance before paying. Reaches the\n   * `<input>` as the native `required` (so a `<form>` refuses to submit without it and a\n   * screen reader announces \"required\"), and draws the kit's required mark after the\n   * label, the same `aria-hidden` star as {@link Label}'s: the word is announced from\n   * the control, so a star inside the name would only be read out as noise. Write the\n   * label WITHOUT a literal \"*\". No mark without a label.\n   */\n  required?: boolean;\n}\n\n/**\n * A native checkbox in the kit's tokens, with an optional label, description and\n * error.\n *\n * Without `label`, `description` or `error` it renders the box and nothing else, so\n * it drops into a table cell or a caller's own `<label>` exactly as the raw input\n * did — give it an `aria-label` there. Every other prop reaches the `<input>`\n * (`checked`, `defaultChecked`, `name`, `required`, `data-*`, `aria-*`), so it works\n * controlled, uncontrolled, and inside a plain `<form>`.\n */\nexport const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(\n  {\n    label,\n    description,\n    indeterminate = false,\n    invalid,\n    error,\n    onCheckedChange,\n    onChange,\n    className,\n    inputClassName,\n    id,\n    disabled,\n    required,\n    ...rest\n  },\n  ref,\n) {\n  const generated = useId();\n  const inputId = id ?? generated;\n  const descriptionId = `${inputId}-description`;\n  const errorId = `${inputId}-error`;\n  const showError = hasMessage(error);\n  const showDescription = hasMessage(description);\n  const isInvalid = Boolean(invalid) || showError;\n  // Nothing to lay out beside the box: render the box alone, as the raw input was.\n  const bare = label === undefined && !showDescription && !showError;\n\n  const local = useRef<HTMLInputElement | null>(null);\n  const setRef = useCallback(\n    (node: HTMLInputElement | null) => {\n      local.current = node;\n      assignRef(ref, node);\n    },\n    [ref],\n  );\n  // After EVERY render, not only when the prop changes: a click clears the property\n  // in the DOM, and a controlled caller that keeps `indeterminate` true expects the\n  // dash back on the next render even though the prop never changed.\n  useEffect(() => {\n    if (local.current) local.current.indeterminate = indeterminate;\n  });\n\n  const box = (\n    <span className={cn(\"relative inline-flex shrink-0\", bare && className)}>\n      <input\n        ref={setRef}\n        id={bare ? id : inputId}\n        disabled={disabled}\n        required={required}\n        {...rest}\n        // After the spread, like Switch: a props object spread at a checkbox must not\n        // be able to turn it into something else.\n        type=\"checkbox\"\n        // OR-ed with the spread so a caller's own `aria-invalid` survives — Input's rule.\n        aria-invalid={isInvalid || rest[\"aria-invalid\"] || undefined}\n        aria-describedby={mergeDescribedBy(\n          rest[\"aria-describedby\"],\n          showDescription && descriptionId,\n          showError && errorId,\n        )}\n        onChange={(e: ChangeEvent<HTMLInputElement>) => {\n          onChange?.(e);\n          onCheckedChange?.(e.target.checked);\n        }}\n        className={cn(BOX, indeterminate && BOX_MIXED, isInvalid && BOX_INVALID, inputClassName)}\n      />\n      {/* The glyph is drawn over the box, not inside it (an input has no children),\n          and ignores the pointer so a click on the tick still toggles the input. The\n          tick is shown by `peer-checked`, so an UNCONTROLLED box shows it too; the\n          dash replaces it outright while `indeterminate` holds. */}\n      {indeterminate ? (\n        <Minus\n          aria-hidden\n          strokeWidth={3}\n          className=\"pointer-events-none absolute inset-0 m-auto size-3 text-[var(--brand-contrast)]\"\n        />\n      ) : (\n        <Check\n          aria-hidden\n          strokeWidth={3}\n          className=\"pointer-events-none invisible absolute inset-0 m-auto size-3 text-[var(--brand-contrast)] peer-checked:visible\"\n        />\n      )}\n    </span>\n  );\n\n  if (bare) return box;\n\n  return (\n    <div\n      className={cn(\n        // `items-start` + a 20px cell for the box: the box centres on the label's FIRST\n        // line (text-sm is 20px tall), so a label that wraps keeps the box at the top\n        // rather than floating to the middle of a paragraph.\n        \"flex items-start gap-2\",\n        // The whole row fades, the way ToggleGroup and the fields do, so the label does\n        // not stay at full strength beside a box you cannot change.\n        disabled && \"opacity-60\",\n        className,\n      )}\n    >\n      <span className=\"flex h-5 shrink-0 items-center\">{box}</span>\n      <span className=\"min-w-0\">\n        {label !== undefined && (\n          <label\n            htmlFor={inputId}\n            className={cn(\n              \"block text-sm leading-5 text-[var(--text-primary)]\",\n              // `select-none`: a double-click to toggle twice would otherwise select the\n              // words, and a drag that starts on them starts a native text drag.\n              disabled ? \"cursor-not-allowed\" : \"cursor-pointer select-none\",\n            )}\n          >\n            {label}\n            {required && (\n              <span aria-hidden className=\"ms-0.5 text-[var(--danger)]\">\n                *\n              </span>\n            )}\n          </label>\n        )}\n        {showDescription && (\n          <span id={descriptionId} className=\"mt-0.5 block text-xs text-[var(--text-muted)]\">\n            {description}\n          </span>\n        )}\n        {showError && (\n          <span id={errorId} className={cn(\"block\", ERROR_CLASS)}>\n            {error}\n          </span>\n        )}\n      </span>\n    </div>\n  );\n});\nCheckbox.displayName = \"Checkbox\";\n"],"mappings":"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","names":["Checkbox"]}
+{"version":3,"sources":["../../src/components/checkbox.tsx"],"sourcesContent":["import { forwardRef, useCallback, useContext, useEffect, useId, useRef } from \"react\";\nimport { Check, Minus } from \"lucide-react\";\nimport type { ChangeEvent, InputHTMLAttributes, ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { assignRef, hasMessage, mergeDescribedBy } from \"./choice-parts\";\nimport { LockedReason, RequiredStarOnLegend, useLockReason } from \"./field-parts\";\n\n/**\n * A checkbox that is still `<input type=\"checkbox\">`.\n *\n * The three consuming apps had three answers: ~30 raw inputs in Keksdose leaning on\n * `tokens.css`'s `accent-color`, a label-plus-box `CheckboxField` in Lenkbank, and a\n * Radix `<button role=\"checkbox\">` in Kastlan. The native element is the one that\n * needs no ARIA to be a checkbox — it submits with its form, answers to `required`,\n * resets with the form and takes a `<label for>` click — so it stays underneath, and\n * only its paint is replaced (`appearance-none`, a token-coloured box, and a glyph\n * laid over it that ignores the pointer so the click still lands on the input).\n *\n * `accent-color` alone was not enough: it tints the native box but cannot change its\n * border, so an INVALID checkbox had no way to say so, and the unchecked box kept the\n * browser's own grey outline in both themes.\n */\n\n// The box. 16px, like every raw checkbox it replaces, so a migration moves nothing.\n//\n// `focus-visible`, with an offset in the surface colour: a --brand ring touching a\n// --brand-filled (checked) box would be a ring painted in the colour it sits on —\n// present in the DOM and invisible on screen. The offset is what separates the two.\nconst BOX =\n  \"peer size-4 shrink-0 cursor-pointer appearance-none rounded-[4px] border border-[var(--border-strong)] bg-[var(--bg-surface)] shadow-sm transition-colors \" +\n  \"checked:border-[var(--brand)] checked:bg-[var(--brand)] \" +\n  \"focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-surface)] \" +\n  \"disabled:cursor-not-allowed\";\n\n// A mixed box wears the checked fill whether or not the underlying input is checked:\n// `indeterminate` is a property the browser keeps separately from `checked`, and the\n// dash means \"some\", which is neither answer.\nconst BOX_MIXED = \"border-[var(--brand)] bg-[var(--brand)]\";\n\n// The same geometry as FIELD_INVALID — a border plus a 1px ring, so the highlight\n// survives fractional display scaling on every edge (see the note in ui.tsx). The\n// focus ring turns danger too, so focusing a wrong box does not repaint it as fine.\nconst BOX_INVALID =\n  \"border-[var(--danger-border-strong)] ring-1 ring-[var(--danger-border-strong)] checked:border-[var(--danger-border-strong)] focus-visible:ring-[var(--danger)]\";\n\nconst ERROR_CLASS = \"mt-1 text-[11px] leading-tight text-[var(--danger)]\";\n\nexport interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, \"type\"> {\n  /**\n   * The words beside the box. Rendered as a `<label for>` rather than a label that\n   * wraps the input, so `description` and `error` can sit under it without becoming\n   * part of the accessible NAME — a wrapping label would have the screen reader read\n   * the whole paragraph as the checkbox's name.\n   */\n  label?: ReactNode;\n  /** Secondary text under the label (\"Used when no account is chosen\"). Pointed at by\n   *  `aria-describedby`, merged with any the caller passed. Kastlan's\n   *  `CheckboxField` `description` variant. */\n  description?: ReactNode;\n  /**\n   * \"Some but not all\" — the header box of a list whose rows are partly selected.\n   * A DOM property with no HTML attribute, so it is set on the element after every\n   * render; it does not touch `checked`, and a click clears it (the browser's rule,\n   * and the caller's `onChange` decides what the click means).\n   */\n  indeterminate?: boolean;\n  /** See {@link Input}'s `invalid`: paints the box and sets `aria-invalid` together,\n   *  so the two cannot be spelled separately. */\n  invalid?: boolean;\n  /** What is wrong, in the caller's words (\"Accept the terms to continue\"). Rendered\n   *  under the label, attached with `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /** The checked state as a boolean — the `(next) => …` shape Lenkbank's\n   *  `CheckboxField` and Radix's `onCheckedChange` both used, so a migration does not\n   *  have to unwrap `event.target.checked` at every call site. Fires alongside\n   *  `onChange`, never instead of it. */\n  onCheckedChange?: (checked: boolean) => void;\n  /** Classes for the `<input>` itself. `className` styles the OUTERMOST element —\n   *  the row when there is a label, the box's own wrapper when there is not — which\n   *  is where layout (`self-end pb-2` to sit on a field's baseline) belongs. */\n  inputClassName?: string;\n  /**\n   * Must be ticked to submit — a consent, an acceptance before paying. Reaches the\n   * `<input>` as the native `required` (so a `<form>` refuses to submit without it and a\n   * screen reader announces \"required\"), and draws the kit's required mark after the\n   * label, the same `aria-hidden` star as {@link Label}'s: the word is announced from\n   * the control, so a star inside the name would only be read out as noise. Write the\n   * label WITHOUT a literal \"*\". No mark without a label.\n   */\n  required?: boolean;\n  /**\n   * Why the box cannot be changed — {@link Button}'s `disabledReason`, for a checkbox\n   * that SAVES on change (keksdose K3: a setting ticked straight into the server, kept\n   * behind a hand-rolled `SaveGuard` that forced a native `disabled` — out of the tab\n   * order, so the reason never reached a keyboard).\n   *\n   * With a reason the box is `aria-disabled` instead: still focusable, a click or Space\n   * changes nothing and fires no `onChange` / `onCheckedChange`, the reason is in the\n   * kit {@link Tooltip} on the box and on its `aria-describedby`, and the row fades as a\n   * disabled one does. It wins over `disabled`. Changing the lock mounts the box anew (it\n   * moves in or out of the Tooltip), as a locked Button is.\n   */\n  disabledReason?: ReactNode;\n  /**\n   * This box COMMITS — ticking it saves. Under a locked {@link WriteLockProvider} it is\n   * locked the `disabledReason` way with the lock's reason (which wins over its own).\n   * No provider, or an unlocked one: no effect. Button's `commit`, for keksdose K3.\n   */\n  commit?: boolean;\n}\n\n/**\n * A native checkbox in the kit's tokens, with an optional label, description and\n * error.\n *\n * Without `label`, `description` or `error` it renders the box and nothing else, so\n * it drops into a table cell or a caller's own `<label>` exactly as the raw input\n * did — give it an `aria-label` there. Every other prop reaches the `<input>`\n * (`checked`, `defaultChecked`, `name`, `required`, `data-*`, `aria-*`), so it works\n * controlled, uncontrolled, and inside a plain `<form>`.\n */\nexport const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(\n  {\n    label,\n    description,\n    indeterminate = false,\n    invalid,\n    error,\n    onCheckedChange,\n    onChange,\n    className,\n    inputClassName,\n    id,\n    disabled,\n    required,\n    disabledReason,\n    commit,\n    onClick,\n    ...rest\n  },\n  ref,\n) {\n  const generated = useId();\n  const inputId = id ?? generated;\n  const lock = useLockReason(commit, disabledReason);\n  const locked = lock.locked;\n  // Locked is disabled the focusable way: the row fades and the words stop inviting a\n  // click exactly as they do for `disabled`.\n  const looksDisabled = Boolean(disabled) || locked;\n  // In a CheckboxGroup the legend carries the star; the box keeps `required` itself.\n  const starOnLegend = useContext(RequiredStarOnLegend);\n  const descriptionId = `${inputId}-description`;\n  const errorId = `${inputId}-error`;\n  const showError = hasMessage(error);\n  const showDescription = hasMessage(description);\n  const isInvalid = Boolean(invalid) || showError;\n  // Nothing to lay out beside the box: render the box alone, as the raw input was.\n  const bare = label === undefined && !showDescription && !showError;\n\n  const local = useRef<HTMLInputElement | null>(null);\n  const setRef = useCallback(\n    (node: HTMLInputElement | null) => {\n      local.current = node;\n      assignRef(ref, node);\n    },\n    [ref],\n  );\n  // After EVERY render, not only when the prop changes: a click clears the property\n  // in the DOM, and a controlled caller that keeps `indeterminate` true expects the\n  // dash back on the next render even though the prop never changed.\n  useEffect(() => {\n    if (local.current) local.current.indeterminate = indeterminate;\n  });\n\n  const control = (\n    <span className={cn(\"relative inline-flex shrink-0\", bare && !locked && className)}>\n      <input\n        ref={setRef}\n        id={bare ? id : inputId}\n        // A reason wins over `disabled`, as on Button: the point of giving one is that\n        // the box stays reachable.\n        disabled={locked ? undefined : disabled}\n        required={required}\n        {...rest}\n        // After the spread, like Switch: a props object spread at a checkbox must not\n        // be able to turn it into something else.\n        type=\"checkbox\"\n        aria-disabled={locked || rest[\"aria-disabled\"] || undefined}\n        // OR-ed with the spread so a caller's own `aria-invalid` survives — Input's rule.\n        aria-invalid={isInvalid || rest[\"aria-invalid\"] || undefined}\n        aria-describedby={mergeDescribedBy(\n          rest[\"aria-describedby\"],\n          showDescription && descriptionId,\n          locked && lock.reasonId,\n          showError && errorId,\n        )}\n        // A locked box's click is swallowed, as a locked Button's is.\n        onClick={locked ? undefined : onClick}\n        onChange={(e: ChangeEvent<HTMLInputElement>) => {\n          if (locked) {\n            // Put the tick back, and report nothing. Undone here rather than by\n            // cancelling the click: a cancelled click is reverted by the browser AFTER\n            // React has restored a controlled box, and jsdom reverts it by toggling, which\n            // turned a restored tick back over (the suites the apps run would have seen a\n            // locked box change). Setting the property also keeps React's own record of\n            // the value in step, so an uncontrolled box reports its next real change.\n            // Covers a click on the label and Space too — both arrive as a click.\n            e.currentTarget.checked = !e.currentTarget.checked;\n            e.currentTarget.indeterminate = indeterminate;\n            return;\n          }\n          onChange?.(e);\n          onCheckedChange?.(e.target.checked);\n        }}\n        className={cn(\n          BOX,\n          indeterminate && BOX_MIXED,\n          isInvalid && BOX_INVALID,\n          locked && \"cursor-not-allowed\",\n          inputClassName,\n        )}\n      />\n      {/* The glyph is drawn over the box, not inside it (an input has no children),\n          and ignores the pointer so a click on the tick still toggles the input. The\n          tick is shown by `peer-checked`, so an UNCONTROLLED box shows it too; the\n          dash replaces it outright while `indeterminate` holds. */}\n      {indeterminate ? (\n        <Minus\n          aria-hidden\n          strokeWidth={3}\n          className=\"pointer-events-none absolute inset-0 m-auto size-3 text-[var(--brand-contrast)]\"\n        />\n      ) : (\n        <Check\n          aria-hidden\n          strokeWidth={3}\n          className=\"pointer-events-none invisible absolute inset-0 m-auto size-3 text-[var(--brand-contrast)] peer-checked:visible\"\n        />\n      )}\n    </span>\n  );\n  // The reason's Tooltip goes round the BOX, not the row: the row is the caller's\n  // layout (`className`), and a wrapper round it would move that into a span. A bare\n  // box hands its `className` to the wrapper, which is then the outermost element.\n  const box = locked ? (\n    <LockedReason lock={lock} className={cn(\"shrink-0\", bare && className)}>\n      {control}\n    </LockedReason>\n  ) : (\n    control\n  );\n\n  if (bare) return box;\n\n  return (\n    <div\n      className={cn(\n        // `items-start` + a 20px cell for the box: the box centres on the label's FIRST\n        // line (text-sm is 20px tall), so a label that wraps keeps the box at the top\n        // rather than floating to the middle of a paragraph.\n        \"flex items-start gap-2\",\n        // The whole row fades, the way ToggleGroup and the fields do, so the label does\n        // not stay at full strength beside a box you cannot change.\n        looksDisabled && \"opacity-60\",\n        className,\n      )}\n    >\n      <span className=\"flex h-5 shrink-0 items-center\">{box}</span>\n      <span className=\"min-w-0\">\n        {label !== undefined && (\n          <label\n            htmlFor={inputId}\n            className={cn(\n              \"block text-sm leading-5 text-[var(--text-primary)]\",\n              // `select-none`: a double-click to toggle twice would otherwise select the\n              // words, and a drag that starts on them starts a native text drag.\n              looksDisabled ? \"cursor-not-allowed\" : \"cursor-pointer select-none\",\n            )}\n          >\n            {label}\n            {required && !starOnLegend && (\n              <span aria-hidden className=\"ms-0.5 text-[var(--danger)]\">\n                *\n              </span>\n            )}\n          </label>\n        )}\n        {showDescription && (\n          <span id={descriptionId} className=\"mt-0.5 block text-xs text-[var(--text-muted)]\">\n            {description}\n          </span>\n        )}\n        {showError && (\n          <span id={errorId} className={cn(\"block\", ERROR_CLASS)}>\n            {error}\n          </span>\n        )}\n      </span>\n    </div>\n  );\n});\nCheckbox.displayName = \"Checkbox\";\n"],"mappings":"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","names":["Checkbox"]}

package/dist/components/chip.d.ts

@@ -209,6 +209,8 @@ type ChipProps = ChipBaseProps & ({
      * href, whichever element draws it.
      */
     renderLink?: (props: ChipLinkProps) => ReactElement;
+    commit?: never;
+    disabledReason?: never;
 } | {
     /** The link shape again, with an `onClick`. `href` is a required string here,
      *  which is what lets TypeScript tell this shape from the button's: a bare
@@ -221,12 +223,28 @@ type ChipProps = ChipBaseProps & ({
     onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
     /** See the link shape above. */
     renderLink?: (props: ChipLinkProps) => ReactElement;
+    commit?: never;
+    disabledReason?: never;
 } | {
     href?: never;
     renderLink?: never;
     /** Renders the chip as a toggle button. Mutually exclusive with `href`. Receives
      *  the click, so a chip inside a clickable row can `stopPropagation()`. */
     onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Why the toggle cannot be pressed right now — {@link Button}'s
+     * `disabledReason`, on the chip's button shape (keksdose K3: a filter or flag
+     * chip that saves on press, under a read-only lock). The chip stays focusable
+     * and `aria-disabled`, a press (and its `onRemove` ×) does nothing, and the
+     * reason shows in the kit {@link Tooltip} and describes the chip. Wins over
+     * `disabled`. A link chip navigates rather than commits, so it takes neither
+     * this nor `commit`; an inert chip has nothing to refuse.
+     */
+    disabledReason?: ReactNode;
+    /** This chip COMMITS — pressing it saves. Under a locked
+     *  {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
+     *  reason, as {@link Button}'s `commit` does. */
+    commit?: boolean;
 });
 /**
  * Note on `onRemove` with `href`/`onClick`: a button cannot be nested inside a button or

package/dist/components/chip.js

@@ -7,6 +7,8 @@ import { horizontalStep } from "../lib/direction.js";
 import { FIELD_INVALID } from "./ui.js";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLink, useKitLocale } from "../i18n/kit-labels.js";
 import { pickLinkRenderer } from "./text-link.js";
+import { Tooltip } from "./tooltip.js";
+import { useCommitReason } from "./write-lock.js";
 const TONE = {
   neutral: {
     idle: "border-[var(--border)] bg-[var(--bg-surface-2)] text-[var(--text-secondary)]",
@@ -310,9 +312,14 @@ const Chip = forwardRef(function Chip2({
   onKeyDown,
   onFocus,
   snapEdges = false,
+  disabledReason: ownDisabledReason,
+  commit,
   ...rest
 }, ref) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS, { remove: removeLabel });
+  const reasonId = useId();
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
+  const locked = Boolean(onClick) && !href && hasReason(disabledReason);
   const kitLink = useKitLink();
   const s = SIZE[size];
   const interactive = !!href || !!onClick;
@@ -321,7 +328,10 @@ const Chip = forwardRef(function Chip2({
   const type = cn(caps && CAPS[size], variant === "solid" && "justify-center tabular-nums");
   const surface = cn(
     surfaceOf(tone, variant, selected),
-    disabled && "cursor-default opacity-50"
+    // A reason wins over `disabled`: the focusable kind of disabled, with the cursor
+    // that says "refused" rather than "nothing here".
+    disabled && !locked && "cursor-default opacity-50",
+    locked && "cursor-not-allowed opacity-50"
   );
   const snap = snapEdges && !dot;
   const snapRef = useSnapEdges(snap);
@@ -338,7 +348,7 @@ const Chip = forwardRef(function Chip2({
     type,
     radius,
     surface,
-    interactive && !disabled && "cursor-pointer hover:brightness-[0.97] dark:hover:brightness-110",
+    interactive && !disabled && !locked && "cursor-pointer hover:brightness-[0.97] dark:hover:brightness-110",
     // An inert dot chip is text in a column: no inset, so it aligns with the header.
     dot && !interactive && "px-0",
     // The under-4px a snap adds is split between the two sides, not stacked at the end.
@@ -381,15 +391,20 @@ const Chip = forwardRef(function Chip2({
       onClick: (e) => {
         e.preventDefault();
         e.stopPropagation();
+        if (locked) return;
         onRemove();
       },
-      disabled: disabled || removeDisabled,
+      disabled: disabled && !locked || removeDisabled,
+      "aria-disabled": locked || void 0,
+      "aria-describedby": locked ? reasonId : void 0,
       className: cn(
         // Logical margins: the × sits at the END of the pill, which is the left in RTL.
         "-me-0.5 ms-0.5 shrink-0 p-0.5 transition-colors",
         shape === "square" ? "rounded-sm" : "rounded-full",
-        "hover:bg-[var(--bg-active)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
-        (disabled || removeDisabled) && "pointer-events-none",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        !locked && "hover:bg-[var(--bg-active)]",
+        locked && "cursor-not-allowed",
+        (disabled && !locked || removeDisabled) && "pointer-events-none",
         // A disabled chip is already dimmed as a whole; dimming the × again on top
         // would take it to a quarter. `removeDisabled` alone dims just the ×.
         removeDisabled && !disabled && "opacity-40"
@@ -407,8 +422,9 @@ const Chip = forwardRef(function Chip2({
     CHIP_RING,
     s.split,
     type,
-    !disabled && "cursor-pointer hover:bg-current/10",
-    disabled && "cursor-default"
+    !disabled && !locked && "cursor-pointer hover:bg-current/10",
+    disabled && !locked && "cursor-default",
+    locked && "cursor-not-allowed"
   );
   if (href && !disabled) {
     const onLinkClick = onClick;
@@ -442,22 +458,40 @@ const Chip = forwardRef(function Chip2({
   }
   if (onClick && !href) {
     const onButtonClick = onClick;
+    const ownDescribedBy = rest["aria-describedby"];
     const button = /* @__PURE__ */ jsx(
       "button",
       {
         ref: remove ? ref : ownRef,
         type: "button",
-        onClick: onButtonClick,
-        disabled,
+        onClick: (e) => {
+          if (locked) {
+            e.preventDefault();
+            return;
+          }
+          onButtonClick(e);
+        },
+        disabled: disabled && !locked,
         role: isCheckbox ? "checkbox" : void 0,
         "aria-pressed": isCheckbox ? void 0 : selected,
         "aria-checked": isCheckbox ? !!selected : void 0,
         className: remove ? inner : look,
         ...rest,
+        "aria-disabled": locked || rest["aria-disabled"],
+        "aria-describedby": locked ? [ownDescribedBy, reasonId].filter(Boolean).join(" ") : ownDescribedBy,
         children: body
       }
     );
-    return remove ? pill(button) : button;
+    const shaped = remove ? pill(button) : button;
+    if (!locked) return shaped;
+    return (
+      // The chip in a FRAGMENT, as a locked Button is: the bubble is visual, and the
+      // hidden copy beside it is what the chip (and its ×) is described by.
+      /* @__PURE__ */ jsx(Tooltip, { label: disabledReason, children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        shaped,
+        /* @__PURE__ */ jsx("span", { id: reasonId, hidden: true, children: disabledReason })
+      ] }) })
+    );
   }
   return (
     /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- the handlers are
@@ -481,6 +515,9 @@ const Chip = forwardRef(function Chip2({
     )
   );
 });
+function hasReason(node) {
+  return node !== void 0 && node !== null && node !== false && node !== "";
+}
 function RenderedLink({
   render,
   ...props