@eifi1/ui-kit 0.20.1 → 0.22.0

package/src/components/entity-combobox.tsx

@@ -11,6 +11,7 @@ import {
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { EndHintRow, FieldCaption, LABEL_IN_ROW, StaticLabelRow, useFieldHint } from "./field-parts";
 
 export type { ComboClearValue, ComboOption } from "./combobox-core";
 
@@ -61,6 +62,13 @@ export interface EntityComboboxProps<V extends string | number, C extends ComboC
   /** What is wrong with the value, as {@link Input}'s `error`: rendered under the
    *  field, on the trigger's `aria-describedby`, and implies `invalid`. */
   error?: ReactNode;
+  /**
+   * Standing advice — {@link Combobox}'s `hint`, so the pickers read like every other
+   * field (keksdose K4): plain TEXT is a caption under the field on the trigger's
+   * `aria-describedby`, before any error; a {@link FieldHint} "?" rides the label line,
+   * or with no label sits at the trigger's end edge, outside the box.
+   */
+  hint?: ReactNode;
   /** Narrow `options` client-side by the query. Default `true`; `false` shows them
    *  as given (a server-ranked list). */
   filter?: boolean;
@@ -100,6 +108,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
   className,
   invalid,
   error,
+  hint,
   filter,
   minChars,
   debounceMs,
@@ -123,10 +132,11 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     minChars,
     debounceMs,
   });
+  const hintParts = useFieldHint(hint, ariaDescribedBy);
   const field = useComboboxFieldError(
     error,
     invalid || ariaInvalid === true || ariaInvalid === "true",
-    ariaDescribedBy,
+    hintParts.describedBy,
   );
   // The props are the per-instance overrides, the provider the app-wide ones; a
   // prop left `undefined` falls through to the provider rather than masking it.
@@ -168,94 +178,103 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     // has one. Spread FIRST so the trigger's ARIA and the
     // handlers that open the panel cannot be clobbered from outside.
     <div {...rest} className={cn("relative", className)}>
-      {label !== undefined && <FieldLabel>{label}</FieldLabel>}
-      <button
-        ref={triggerRef}
-        id={id}
-        type="button"
-        // A combobox, not a button. The distinction is not pedantry: this control
-        // carried `aria-invalid`, which `button` does not support, so a required
-        // field left empty painted a rose border and told a reader nothing at all —
-        // and ESLint flagged it as exactly that (`role-supports-aria-props`). The
-        // fix the audit asked for is the role that describes what this IS: a closed
-        // choice that expands into the list named below. `combobox` supports
-        // `aria-invalid`, so the border and the announcement finally agree.
-        role="combobox"
-        aria-expanded={open}
-        aria-controls={listboxId}
-        aria-haspopup="listbox"
-        // The label is a floating <span>, not a <label for>, so without this the
-        // trigger's accessible name is whatever value happens to be selected —
-        // "Checking" with nothing saying it is the account. The label AND the
-        // value, because `aria-label` replaces the content rather than adding to
-        // it, and a control that announces only its name has lost the answer.
-        // A caller's own name wins over the composition: two fields labelled
-        // "Account" on a transfer form are the from and the to, and only the
-        // caller knows which is which.
-        aria-label={
-          ariaLabel ??
-          (typeof label === "string" ? common.fieldValue(label, triggerText) : undefined)
-        }
-        disabled={disabled}
-        aria-invalid={field.isInvalid || undefined}
-        aria-describedby={field.describedBy}
-        aria-required={ariaRequired}
-        onClick={() => !disabled && setOpen((o) => !o)}
-        // Down/Up opens the list from the closed trigger, per the APG. Enter and
-        // Space already do it through the button's own click.
-        onKeyDown={(e) => {
-          if (disabled) return;
-          if (e.key === "ArrowDown" || e.key === "ArrowUp") {
-            e.preventDefault();
-            setOpen(true);
+      {label !== undefined && hintParts.labelHint === undefined && <FieldLabel>{label}</FieldLabel>}
+      <EndHintRow hint={label === undefined ? hintParts.labelHint : undefined}>
+        <button
+          ref={triggerRef}
+          id={id}
+          type="button"
+          // A combobox, not a button. The distinction is not pedantry: this control
+          // carried `aria-invalid`, which `button` does not support, so a required
+          // field left empty painted a rose border and told a reader nothing at all —
+          // and ESLint flagged it as exactly that (`role-supports-aria-props`). The
+          // fix the audit asked for is the role that describes what this IS: a closed
+          // choice that expands into the list named below. `combobox` supports
+          // `aria-invalid`, so the border and the announcement finally agree.
+          role="combobox"
+          aria-expanded={open}
+          aria-controls={listboxId}
+          aria-haspopup="listbox"
+          // The label is a floating <span>, not a <label for>, so without this the
+          // trigger's accessible name is whatever value happens to be selected —
+          // "Checking" with nothing saying it is the account. The label AND the
+          // value, because `aria-label` replaces the content rather than adding to
+          // it, and a control that announces only its name has lost the answer.
+          // A caller's own name wins over the composition: two fields labelled
+          // "Account" on a transfer form are the from and the to, and only the
+          // caller knows which is which.
+          aria-label={
+            ariaLabel ??
+            (typeof label === "string" ? common.fieldValue(label, triggerText) : undefined)
           }
-        }}
-        className={cn(
-          FIELD_TRIGGER,
-          "pe-9",
-          label !== undefined && FIELD_FLOATING_PAD,
-          disabled && "cursor-not-allowed opacity-50",
-          field.isInvalid && FIELD_INVALID,
-        )}
-      >
-        <span className="flex min-w-0 items-center gap-2">
-          {selectedOption?.icon && <span className="shrink-0">{selectedOption.icon}</span>}
-          <span
-            className={cn(
-              "truncate",
-              // A chosen value is the field's VALUE, so it is set in the same ink an
-              // <input>'s value is — FIELD_BASE's own text colour, inherited rather
-              // than restated (Keksdose dev#477). It used to be one notch lighter
-              // than the typeahead fields beside it, which is visible when a picker
-              // and a text field share a form row. Nothing selected keeps the
-              // placeholder tone (`--text-placeholder`), which every field here
-              // agrees on.
-              !selectedOption && "text-[var(--text-placeholder)]",
-            )}
-          >
-            {selectedOption?.label ?? placeholder ?? ""}
-          </span>
-        </span>
-        {showClear ? (
-          /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside
-              the trigger <button>, so it never holds focus and a key handler here could
-              never fire; the keys go to the trigger. A pointer shortcut only. */
-          <span
-            role="button"
-            tabIndex={-1}
-            aria-label={labels.clear}
-            onClick={(e) => {
-              e.stopPropagation();
-              onChange(clearValue);
-            }}
-            className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
-          >
-            <X className="size-4" />
+          disabled={disabled}
+          aria-invalid={field.isInvalid || undefined}
+          aria-describedby={field.describedBy}
+          aria-required={ariaRequired}
+          onClick={() => !disabled && setOpen((o) => !o)}
+          // Down/Up opens the list from the closed trigger, per the APG. Enter and
+          // Space already do it through the button's own click.
+          onKeyDown={(e) => {
+            if (disabled) return;
+            if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+              e.preventDefault();
+              setOpen(true);
+            }
+          }}
+          className={cn(
+            FIELD_TRIGGER,
+            "pe-9",
+            label !== undefined && FIELD_FLOATING_PAD,
+            disabled && "cursor-not-allowed opacity-50",
+            field.isInvalid && FIELD_INVALID,
+          )}
+        >
+          <span className="flex min-w-0 items-center gap-2">
+            {selectedOption?.icon && <span className="shrink-0">{selectedOption.icon}</span>}
+            <span
+              className={cn(
+                "truncate",
+                // A chosen value is the field's VALUE, so it is set in the same ink an
+                // <input>'s value is — FIELD_BASE's own text colour, inherited rather
+                // than restated (Keksdose dev#477). It used to be one notch lighter
+                // than the typeahead fields beside it, which is visible when a picker
+                // and a text field share a form row. Nothing selected keeps the
+                // placeholder tone (`--text-placeholder`), which every field here
+                // agrees on.
+                !selectedOption && "text-[var(--text-placeholder)]",
+              )}
+            >
+              {selectedOption?.label ?? placeholder ?? ""}
+            </span>
           </span>
-        ) : (
-          <FieldChevron />
-        )}
-      </button>
+          {showClear ? (
+            /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside
+                the trigger <button>, so it never holds focus and a key handler here could
+                never fire; the keys go to the trigger. A pointer shortcut only. */
+            <span
+              role="button"
+              tabIndex={-1}
+              aria-label={labels.clear}
+              onClick={(e) => {
+                e.stopPropagation();
+                onChange(clearValue);
+              }}
+              className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+            >
+              <X className="size-4" />
+            </span>
+          ) : (
+            <FieldChevron />
+          )}
+        </button>
+      </EndHintRow>
+      {/* With a "?" the label shares the top strip with it — after the trigger, so the
+          "?" follows the control in the tab order, as on Input and Select. */}
+      {label !== undefined && hintParts.labelHint !== undefined && (
+        <StaticLabelRow hint={hintParts.labelHint}>
+          <FieldLabel className={LABEL_IN_ROW}>{label}</FieldLabel>
+        </StaticLabelRow>
+      )}
       <ComboboxPanel
         core={core}
         listboxId={listboxId}
@@ -275,6 +294,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
         }}
         createContent={labels.create(q)}
       />
+      <FieldCaption parts={hintParts} />
       {field.errorEl}
     </div>
   );

package/src/components/field-anatomy.tsx

@@ -0,0 +1,190 @@
+// Internal — not re-exported from the barrel. The pieces of a field's anatomy (its
+// label line, the caption and the error under it, the label STRIP over a bare group)
+// for the controls that are not built on `FloatingField`: the date and month pickers,
+// whose trigger is a button in a wrapper of their own, and the groups (ToggleGroup,
+// SwatchPicker, IconPicker), which have no field box at all.
+//
+// `Input` and `Select` keep their own copies in ui.tsx; these follow them class for
+// class, so a DatePicker's caption and a Select's caption are the same 11px line in
+// the same place (keksdose K4: "uniform field anatomy … today it is a patchwork").
+
+import { useId } from "react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { FieldLabel } from "./ui";
+
+/** `undefined`, `null`, `false` and `""` are what a caller's `cond && "…"` evaluates to
+ *  when there is nothing to say; none of them is content. A numeric `0` is. */
+export function hasContent(node: ReactNode): boolean {
+  return node !== undefined && node !== null && node !== false && node !== "";
+}
+
+/**
+ * A `hint` that is plain TEXT is a caption under the field; anything else (a
+ * `FieldHint` "?") rides the label line — the rule `Select` set in 0.15: the label
+ * line is 11px of strip shared with the label, and a sentence placed there was set on
+ * top of both the label and the value.
+ */
+export function isTextHint(hint: ReactNode): boolean {
+  return (typeof hint === "string" && hint !== "") || typeof hint === "number";
+}
+
+const FIELD_CAPTION_CLASS = "mt-1 text-[11px] leading-tight text-[var(--text-muted)]";
+const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
+
+export interface FieldMessages {
+  /** `invalid`, a message, or an `aria-invalid` from outside (a form library). */
+  isInvalid: boolean;
+  /** The caller's description, then the caption, then the error — the standing
+   *  advice before the news, as `useFieldError` in ui.tsx orders them. */
+  describedBy: string | undefined;
+  /** The caption and the error, for under the field; `null` when there is neither. */
+  below: ReactNode;
+  /** The hint for the LABEL line (a `FieldHint`), or `undefined` when the hint is a
+   *  caption or there is none. */
+  labelHint: ReactNode;
+}
+
+/** `hint` / `error` / `invalid` resolved the way `Select` resolves them. */
+export function useFieldMessages({
+  hint,
+  error,
+  invalid,
+  describedBy,
+  ariaInvalid,
+}: {
+  hint?: ReactNode;
+  error?: ReactNode;
+  invalid?: boolean;
+  describedBy?: string;
+  ariaInvalid?: unknown;
+}): FieldMessages {
+  const hintId = useId();
+  const errorId = useId();
+  const textHint = isTextHint(hint);
+  const hasError = hasContent(error);
+  return {
+    isInvalid: Boolean(invalid) || hasError || ariaInvalid === true || ariaInvalid === "true",
+    describedBy:
+      [describedBy, textHint && hintId, hasError && errorId].filter(Boolean).join(" ") || undefined,
+    below:
+      textHint || hasError ? (
+        <>
+          {textHint && (
+            <p id={hintId} className={FIELD_CAPTION_CLASS}>
+              {hint}
+            </p>
+          )}
+          {hasError && (
+            <p id={errorId} className={FIELD_ERROR_CLASS}>
+              {error}
+            </p>
+          )}
+        </>
+      ) : null,
+    labelHint: !textHint && hasContent(hint) ? hint : undefined,
+  };
+}
+
+/**
+ * The field and what is under it, as one box — `FieldGroup` in ui.tsx, for the same
+ * reasons written there. Nothing of its own while there is nothing under the field and
+ * the caller passed no `error` key (the DOM is exactly what it was before these props);
+ * once `error` is passed the box is kept even with no message, so the trigger is never
+ * reparented — and remounted, losing focus — as the message comes and goes.
+ */
+export function FieldBox({
+  below,
+  reserve,
+  children,
+}: {
+  below: ReactNode;
+  reserve: boolean;
+  children: ReactNode;
+}) {
+  if (below === null && !reserve) return <>{children}</>;
+  return (
+    <div>
+      {children}
+      {below}
+    </div>
+  );
+}
+
+/**
+ * The static label in a trigger field's top strip — a {@link FieldLabel}, or, with a
+ * `FieldHint`, the label and its "?" laid out on ONE flex row (dev#468: two absolute
+ * offsets guessing at the same baseline put the "?" three pixels above its word).
+ * `FloatingField`'s static-label row, except that it stops at `end-9`: the date and
+ * month triggers keep that column (`pe-9`) for the calendar glyph or the clear ×, and a
+ * long label truncates before it rather than putting the "?" on top of it.
+ */
+export function FieldLabelLine({ label, hint }: { label: ReactNode; hint?: ReactNode }) {
+  if (!hasContent(hint)) return <FieldLabel>{label}</FieldLabel>;
+  return (
+    // `z-10` as FieldLabel has it: the trigger after it is `relative` and would paint
+    // over the row (and take the "?"'s hover) otherwise.
+    <div className="pointer-events-none absolute start-3 end-9 top-1 z-10 flex items-center gap-1">
+      <FieldLabel className="static min-w-0 max-w-full">{label}</FieldLabel>
+      <span className="pointer-events-auto flex shrink-0 items-center">{hint}</span>
+    </div>
+  );
+}
+
+/**
+ * How tall the strip over a bare group is.
+ *
+ *  - `"toggle"` — 16px. keksdose's `ClearedStatusPicker` (live #288 rework, #431,
+ *    measured): *"16px of label strip plus a 26px group is exactly a labelled Input"*,
+ *    so a status group in a row of 42px fields ends where they end. The label's line
+ *    box runs into the group's top hairline, but the ACTIVE fill — the thing feedback
+ *    #117 was about — starts at 19px, below the label's 17.75px.
+ *  - `"tiles"` — 20px, keksdose's `FlagPicker` and location field (`pt-5`). A tile has
+ *    no inset fill: its selection IS its frame, a 2px dark border-and-ring from the
+ *    tile's top edge, so the tile has to start below the whole label line.
+ */
+export const LABEL_STRIP_PAD = { toggle: "pt-4", tiles: "pt-5" } as const;
+
+/**
+ * The 11px label (and its `FieldHint`) over a group that is NOT a field — keksdose K2:
+ * a segmented control or a row of swatches standing in a form row beside labelled
+ * inputs, whose label must sit on the same line as theirs (`top-1`, `inset-x-3`, the
+ * type of a field's static label) without the group growing a field's border round
+ * it. `id` goes on the label so the group can be `aria-labelledby` it.
+ *
+ * `relative` is load-bearing twice over: the row is positioned against it, and a
+ * caller's `sr-only` label cannot escape it (sr-only-containment).
+ */
+export function LabelStrip({
+  labelId,
+  label,
+  hint,
+  disabled,
+  pad,
+  className,
+  children,
+}: {
+  labelId: string;
+  label: ReactNode;
+  hint?: ReactNode;
+  /** Dim the label with its group, as `peer-disabled:` dims a field's own. */
+  disabled?: boolean;
+  pad: keyof typeof LABEL_STRIP_PAD;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className={cn("relative min-w-0", LABEL_STRIP_PAD[pad], className)}>
+      <div className="pointer-events-none absolute inset-x-3 top-1 flex items-center gap-1">
+        {/* `static`: FieldLabel positions itself absolutely; here the ROW is
+            positioned, so the label and its "?" are centred on one line by the flex
+            layout (dev#468). */}
+        <FieldLabel id={labelId} className={cn("static min-w-0 max-w-full", disabled && "opacity-50")}>
+          {label}
+        </FieldLabel>
+        {hasContent(hint) && <span className="pointer-events-auto flex shrink-0 items-center">{hint}</span>}
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/components/field-parts.tsx

@@ -0,0 +1,184 @@
+import { createContext, useId } from "react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Tooltip } from "./tooltip";
+import { useCommitReason } from "./write-lock";
+import { hasMessage, mergeDescribedBy } from "./choice-parts";
+
+/**
+ * Small pieces the fields share for the 0.22.0 anatomy round (keksdose K3/K4, kastlan
+ * 8). Private to the package — not re-exported from the barrel — like `choice-parts`.
+ *
+ * Nothing here imports `ui.tsx`: `ui.tsx` imports this, and so do the combobox family
+ * and the native choice controls, which is the point of keeping the rules in one place.
+ */
+
+/* ── hint ─────────────────────────────────────────────────────────────────── */
+
+/**
+ * Whether a `hint` is a CAPTION (plain text: a non-empty string or a number) or
+ * something for the label line (a {@link FieldHint} "?", or any other node).
+ *
+ * The rule {@link Select} and `NumberInput` already keep: the label line is 11px of
+ * strip shared with the label, and a sentence placed there ran over the label and into
+ * the value; a "?" under the field would be a button floating free of the label it
+ * explains.
+ */
+export function isTextHint(hint: ReactNode): hint is string | number {
+  return (typeof hint === "string" && hint !== "") || typeof hint === "number";
+}
+
+/** The caption under a field — Select's and NumberInput's type, so every field's
+ *  standing advice reads alike. */
+export const FIELD_CAPTION_CLASS = "mt-1 text-[11px] leading-tight text-[var(--text-muted)]";
+
+export interface FieldHintParts {
+  /** The caller's `aria-describedby` with the caption's id appended — standing
+   *  advice first; the error (the news) is appended after this by the field. */
+  describedBy: string | undefined;
+  /** The caption's id while there is one. */
+  captionId: string | undefined;
+  /** The caption itself, or `undefined` for a hint that is not text. */
+  captionText: string | number | undefined;
+  /** A non-text hint (a FieldHint) for the label line — or, on a field with no label
+   *  line, the end edge outside the box. `undefined` when there is none. */
+  labelHint: ReactNode | undefined;
+}
+
+/**
+ * Split a field's `hint` into the caption under it (attached with `aria-describedby`)
+ * or the "?" on its label line. See {@link isTextHint}.
+ */
+export function useFieldHint(hint: ReactNode, describedBy: string | undefined): FieldHintParts {
+  const captionId = useId();
+  const text = isTextHint(hint);
+  return {
+    describedBy: text ? mergeDescribedBy(describedBy, captionId) : describedBy,
+    captionId: text ? captionId : undefined,
+    captionText: text ? hint : undefined,
+    labelHint: !text && hasMessage(hint) ? hint : undefined,
+  };
+}
+
+/** The caption under a field, as {@link Select} draws its own. */
+export function FieldCaption({ parts, className }: { parts: FieldHintParts; className?: string }) {
+  if (parts.captionText === undefined) return null;
+  return (
+    <p id={parts.captionId} className={cn(FIELD_CAPTION_CLASS, className)}>
+      {parts.captionText}
+    </p>
+  );
+}
+
+/**
+ * Classes that take a static floating label (`FLOATING_LABEL_STATIC`: `FieldLabel`,
+ * `ComboboxFieldLabel`) out of its own absolute slot and into a {@link StaticLabelRow}.
+ * `static` wins over `absolute` through `cn`'s merge; `min-w-0` lets it truncate in
+ * the row.
+ */
+export const LABEL_IN_ROW = "static min-w-0";
+
+/**
+ * A static label and its "?" on one line, in the top strip of a field that lays out its
+ * own label — the combobox family, which cannot use {@link FloatingField} because the
+ * trigger, the anchored panel and the label hang off a box of their own.
+ *
+ * FloatingField's static row, with one difference: it stops at `end-9`, the column the
+ * chevron (or the clear "×") takes, so a long label truncates before it rather than
+ * putting the "?" on top of the chevron. The hint keeps its width; the label gives way.
+ */
+export function StaticLabelRow({ hint, children }: { hint: ReactNode; children: ReactNode }) {
+  return (
+    <div className="pointer-events-none absolute start-3 end-9 top-1 z-10 flex items-center gap-1">
+      {children}
+      <span className="pointer-events-auto flex shrink-0 items-center">{hint}</span>
+    </div>
+  );
+}
+
+/**
+ * A field with no label line and a FieldHint "?": the hint at the end edge, OUTSIDE the
+ * box, as an unlabelled {@link Select} has placed it since 0.15.5. Without a hint the
+ * field is returned exactly as it was, so the wrapper costs nothing where it does not
+ * apply.
+ */
+export function EndHintRow({
+  hint,
+  className,
+  children,
+}: {
+  hint: ReactNode | undefined;
+  className?: string;
+  children: ReactNode;
+}) {
+  if (hint === undefined) return <>{children}</>;
+  return (
+    <div className={cn("flex items-center gap-1.5", className)}>
+      <div className="min-w-0 flex-1">{children}</div>
+      <span className="flex shrink-0 items-center">{hint}</span>
+    </div>
+  );
+}
+
+/* ── the write lock on a control that saves itself (keksdose K3) ───────────── */
+
+export interface LockReason {
+  /** The reason in force — the lock's (with `commit` under a locked
+   *  `WriteLockProvider`), else the control's own `disabledReason`. */
+  reason: ReactNode;
+  /** There is a reason: the control is locked the focusable way. */
+  locked: boolean;
+  /** The id of the reason's hidden copy, for the control's `aria-describedby`. */
+  reasonId: string;
+}
+
+/**
+ * {@link Button}'s `commit` + `disabledReason`, for a control that IS its own commit — a
+ * switch, a checkbox or a select that saves on change, a list row whose click writes.
+ * The lock's reason wins over the control's own (`useCommitReason`).
+ */
+export function useLockReason(commit: boolean | undefined, disabledReason: ReactNode): LockReason {
+  const reason = useCommitReason(commit, disabledReason);
+  const reasonId = useId();
+  return { reason, locked: hasMessage(reason), reasonId };
+}
+
+/**
+ * The kit {@link Tooltip} around a locked control, with a `hidden` copy of the reason for
+ * the control's `aria-describedby` — Button's anatomy. The control goes in a FRAGMENT so
+ * the Tooltip does not also clone its bubble's id into the description: the hidden copy
+ * already describes it, and the same sentence twice would be read on every focus.
+ *
+ * `className` is the wrapper's, which becomes the outermost element while locked — a
+ * control moves its own layout classes here so a lock does not reflow the form.
+ */
+export function LockedReason({
+  lock,
+  className,
+  children,
+}: {
+  lock: LockReason;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <Tooltip label={lock.reason} className={className}>
+      <>
+        {children}
+        <span id={lock.reasonId} hidden>
+          {lock.reason}
+        </span>
+      </>
+    </Tooltip>
+  );
+}
+
+/* ── groups ───────────────────────────────────────────────────────────────── */
+
+/**
+ * Set by {@link CheckboxGroup}: its legend carries the one required star, so a box
+ * inside it keeps the native `required` (a form still refuses an empty set) but draws no
+ * star of its own — four stars on four languages would read as four separate demands.
+ * ChoiceCardGroup's `InGroupContext`, for the plain checkbox.
+ */
+export const RequiredStarOnLegend = createContext(false);