@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/autocomplete.tsx

@@ -22,6 +22,16 @@ import {
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
+import {
+  EndHintRow,
+  FieldCaption,
+  LABEL_IN_ROW,
+  LockedReason,
+  StaticLabelRow,
+  useFieldHint,
+  useLockReason,
+} from "./field-parts";
+import { mergeDescribedBy } from "./choice-parts";
 
 /**
  * `value`/`onChange` are the TEXT's, and `onSelect` is "a suggestion was taken" —
@@ -104,6 +114,14 @@ export interface AutocompleteProps<V extends string | number = string>
    *  its `aria-describedby`, implies `invalid`. Not a failed lookup — that is
    *  `loadErrorLabel`, shown in the list. */
   error?: ReactNode;
+  /**
+   * Standing advice — {@link Combobox}'s `hint`, so this field reads like every other
+   * (keksdose K4): plain TEXT is a caption under the field on the input's
+   * `aria-describedby`, before any error; a {@link FieldHint} "?" rides the label line,
+   * or with no label sits at the field's end edge, outside the box. Not the list's
+   * `status` line, which talks about the lookup, not the field.
+   */
+  hint?: ReactNode;
   /**
    * The caller's own line in the list, replacing the automatic one (loading / failed
    * / no results). For what only the caller knows: "offline", "the address service
@@ -117,6 +135,27 @@ export interface AutocompleteProps<V extends string | number = string>
   loadErrorLabel?: string;
   /** Classes for the `<input>` itself; `className` styles the wrapper. */
   inputClassName?: string;
+  /**
+   * Why the field cannot be changed — {@link Button}'s `disabledReason`, the Combobox
+   * family's write lock (keksdose G2, 0.23), for a field whose pick SAVES: an address
+   * search whose taken row writes the address, a lookup that links a record.
+   *
+   * With a reason the input stays focusable and `aria-disabled`, is `readOnly` (the
+   * settled grey FIELD_BASE gives a `[readonly]` field), opens no list and asks no
+   * `loadOptions` — whatever `open` says — and nothing reaches `onChange`, `onSelect` or
+   * `onOpenChange(true)`. Enter is swallowed, so a locked field does not submit the form
+   * around it, and a caller's `onKeyDown` does not hear it; every other key still
+   * reaches the caller (an Escape that closes its panel) and the caret. The reason is in
+   * the kit {@link Tooltip} and on the input's `aria-describedby`. Wins over `disabled`.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * This field COMMITS. Under a locked {@link WriteLockProvider} it is locked the
+   * `disabledReason` way with the lock's reason (which wins over its own). A search
+   * whose result is only draft state — the form's Save writes it — leaves this off and
+   * stays live under the lock. No provider, or an unlocked one: no effect.
+   */
+  commit?: boolean;
 }
 
 function AutocompleteInner<V extends string | number = string>(
@@ -135,6 +174,7 @@ function AutocompleteInner<V extends string | number = string>(
     icon,
     invalid,
     error,
+    hint,
     status,
     emptyLabel,
     loadErrorLabel,
@@ -145,6 +185,8 @@ function AutocompleteInner<V extends string | number = string>(
     inputClassName,
     id,
     disabled,
+    disabledReason,
+    commit,
     onKeyDown,
     onFocus,
     onBlur,
@@ -166,7 +208,8 @@ function AutocompleteInner<V extends string | number = string>(
     noResults: emptyLabel,
     loadError: loadErrorLabel,
   });
-  const field = useComboboxFieldError(error, invalid, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const field = useComboboxFieldError(error, invalid, hintParts.describedBy);
 
   /** The user's intent: the field is focused and the list has not been dismissed.
    *  Whether anything SHOWS is decided below, from what there is to show. */
@@ -180,7 +223,11 @@ function AutocompleteInner<V extends string | number = string>(
     if (next !== open) onOpenChange?.(next);
   };
   const [active, setActive] = useState(-1);
-  const live = open && !disabled;
+  // The lock: focusable, `readOnly`, no list — see `disabledReason`. Folded into `live`,
+  // so a locked field asks nothing and shows nothing even with `open` held true.
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const live = open && !disabled && !locked;
   const { results, busy, failed, tooShort } = useOptionSource<V>({
     options,
     loadOptions,
@@ -219,7 +266,7 @@ function AutocompleteInner<V extends string | number = string>(
     setActive(-1);
   };
   const take = (o: ComboOption<V>) => {
-    if (o.disabled) return;
+    if (o.disabled || locked) return;
     if (fillOnSelect) onChange(o.label);
     onSelect?.(o);
     close();
@@ -234,6 +281,16 @@ function AutocompleteInner<V extends string | number = string>(
   // label still names the field.
   const labelledBy =
     ariaLabel === undefined ? (ariaLabelledBy ?? (hasLabel ? labelId : undefined)) : undefined;
+  // While locked the field sits in the reason's Tooltip — in a fragment with a hidden
+  // copy of the reason, Button's anatomy; `block` so a full-width field stays full width.
+  const withLock = (box: ReactNode) =>
+    locked ? (
+      <LockedReason lock={lock} className="block">
+        {box}
+      </LockedReason>
+    ) : (
+      box
+    );
 
   return (
     // `relative`: the floating label and the live region's `sr-only` both need a
@@ -241,124 +298,151 @@ function AutocompleteInner<V extends string | number = string>(
     <div className={cn("relative", className)}>
       {/* A real <label for> (lenkbank), and still `aria-labelledby`'s target, so the
           name — and the listbox's, which borrows it — is exactly what it was. */}
-      {hasLabel && (
+      {hasLabel && hintParts.labelHint === undefined && (
         <ComboboxFieldLabel id={labelId} htmlFor={fieldId}>
           {label}
         </ComboboxFieldLabel>
       )}
-      <div ref={fieldRef} className="relative">
-        {icon && (
-          <span
-            aria-hidden
-            className={cn(
-              "pointer-events-none absolute flex text-[var(--text-muted)]",
-              small ? "start-2 [&>svg]:size-3.5" : "start-2.5 [&>svg]:size-4",
-              // Labelled, the icon sits on the VALUE's line — the one line box below
-              // FIELD_FLOATING_PAD's `pt-4` and the 1px border — not on the middle of
-              // the box. Centred on the box it rose into the top strip and sat on the
-              // label's first letters, which float at the same start inset. On the
-              // value line it is beside what it describes, and the label keeps the
-              // start edge every other label in the form's column shares.
-              hasLabel
-                ? "top-[calc(1rem+1px)] h-5 items-center"
-                : "top-1/2 -translate-y-1/2",
+      <EndHintRow hint={hasLabel ? undefined : hintParts.labelHint}>
+        {withLock(
+          <div ref={fieldRef} className={cn("relative", locked && "cursor-not-allowed")}>
+            {icon && (
+              <span
+                aria-hidden
+                className={cn(
+                  "pointer-events-none absolute flex text-[var(--text-muted)]",
+                  small ? "start-2 [&>svg]:size-3.5" : "start-2.5 [&>svg]:size-4",
+                  // Labelled, the icon sits on the VALUE's line — the one line box below
+                  // FIELD_FLOATING_PAD's `pt-4` and the 1px border — not on the middle of
+                  // the box. Centred on the box it rose into the top strip and sat on the
+                  // label's first letters, which float at the same start inset. On the
+                  // value line it is beside what it describes, and the label keeps the
+                  // start edge every other label in the form's column shares.
+                  hasLabel
+                    ? "top-[calc(1rem+1px)] h-5 items-center"
+                    : "top-1/2 -translate-y-1/2",
+                )}
+              >
+                {icon}
+              </span>
             )}
-          >
-            {icon}
-          </span>
-        )}
-        <input
-          {...rest}
-          ref={ref}
-          id={fieldId}
-          size={nativeSize}
-          type="text"
-          value={value}
-          disabled={disabled}
-          role="combobox"
-          aria-autocomplete="list"
-          aria-expanded={expanded}
-          // Required by the role, and set while closed too, as on the siblings.
-          aria-controls={listboxId}
-          aria-activedescendant={activeId}
-          aria-label={ariaLabel}
-          aria-labelledby={labelledBy}
-          aria-invalid={field.isInvalid || rest["aria-invalid"] || undefined}
-          aria-describedby={field.describedBy}
-          autoComplete="off"
-          onFocus={(e) => {
-            onFocus?.(e);
-            // A seeded field (keksdose's `initialQuery`) is looked up as it is
-            // focused; an empty one asks nothing, because of `minChars`.
-            setOpen(true);
-          }}
-          onBlur={(e) => {
-            onBlur?.(e);
-            close();
-          }}
-          onChange={(e) => {
-            onChange(e.target.value);
-            setOpen(true);
-            setActive(-1);
-          }}
-          onKeyDown={(e) => {
-            // An Escape that closes the OPEN list is the list's, and is consumed before
-            // the caller sees it. A caller whose Escape means "close the panel" (keksdose's
-            // address search) otherwise closed the whole panel when the user only meant
-            // to dismiss the suggestions — the opposite of what the docs promised.
-            if (e.key === "Escape" && expanded) {
-              e.preventDefault();
-              e.stopPropagation();
-              close();
-              return;
-            }
-            onKeyDown?.(e);
-            if (e.defaultPrevented) return;
-            // Disabled rows are passed over; at either end the highlight stays put.
-            if (e.key === "ArrowDown") {
-              e.preventDefault();
-              if (!open) setOpen(true);
-              else setActive((i) => stepEnabled(results, i, 1));
-            } else if (e.key === "ArrowUp") {
-              e.preventDefault();
-              if (!open) setOpen(true);
-              // From "nothing highlighted", Up goes to the bottom, as the APG has it.
-              else setActive((i) => stepEnabled(results, i < 0 ? results.length : i, -1));
-            } else if (e.key === "Enter") {
-              // No row highlighted: the text is the answer, and a form's own submit
-              // is left alone.
-              if (expanded && activeId) {
-                e.preventDefault();
-                take(results[active]);
-              }
-            } else if (e.key === "Tab") {
-              close();
-            }
-          }}
-          className={cn(
-            FIELD_BASE,
-            hasLabel && FIELD_FLOATING_PAD,
-            // Select's `SELECT_SM` box: a fixed 28px, so the caller's line height
-            // cannot grow it.
-            small && "h-7 py-0 pe-2 ps-2 text-xs",
-            icon ? (small ? "ps-7" : "ps-8") : undefined,
-            busy && (small ? "pe-7" : "pe-9"),
-            field.isInvalid && FIELD_INVALID,
-            inputClassName,
-          )}
-        />
-        {busy && live && (
-          // Decorative: the live region below already says "Loading…".
-          <span
-            className={cn(
-              "pointer-events-none absolute top-1/2 flex -translate-y-1/2",
-              small ? "end-2" : "end-2.5",
+            <input
+              {...rest}
+              ref={ref}
+              id={fieldId}
+              size={nativeSize}
+              type="text"
+              value={value}
+              // Locked: focusable, `readOnly`, `aria-disabled` — see `disabledReason`.
+              disabled={locked ? undefined : disabled}
+              readOnly={locked || rest.readOnly}
+              aria-disabled={locked || rest["aria-disabled"]}
+              role="combobox"
+              aria-autocomplete="list"
+              aria-expanded={expanded}
+              // Required by the role, and set while closed too, as on the siblings.
+              aria-controls={listboxId}
+              aria-activedescendant={activeId}
+              aria-label={ariaLabel}
+              aria-labelledby={labelledBy}
+              aria-invalid={field.isInvalid || rest["aria-invalid"] || undefined}
+              aria-describedby={mergeDescribedBy(field.describedBy, locked && lock.reasonId)}
+              autoComplete="off"
+              onFocus={(e) => {
+                onFocus?.(e);
+                // A locked field takes focus to say why, and opens nothing.
+                if (locked) return;
+                // A seeded field (keksdose's `initialQuery`) is looked up as it is
+                // focused; an empty one asks nothing, because of `minChars`.
+                setOpen(true);
+              }}
+              onBlur={(e) => {
+                onBlur?.(e);
+                close();
+              }}
+              onChange={(e) => {
+                if (locked) return;
+                onChange(e.target.value);
+                setOpen(true);
+                setActive(-1);
+              }}
+              onKeyDown={(e) => {
+                // Locked: Enter is swallowed (no form submit, no caller's "search now");
+                // every other key is the caller's and the caret's. No list to drive.
+                if (locked) {
+                  if (e.key === "Enter") e.preventDefault();
+                  else onKeyDown?.(e);
+                  return;
+                }
+                // An Escape that closes the OPEN list is the list's, and is consumed before
+                // the caller sees it. A caller whose Escape means "close the panel" (keksdose's
+                // address search) otherwise closed the whole panel when the user only meant
+                // to dismiss the suggestions — the opposite of what the docs promised.
+                if (e.key === "Escape" && expanded) {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  close();
+                  return;
+                }
+                onKeyDown?.(e);
+                if (e.defaultPrevented) return;
+                // Disabled rows are passed over; at either end the highlight stays put.
+                if (e.key === "ArrowDown") {
+                  e.preventDefault();
+                  if (!open) setOpen(true);
+                  else setActive((i) => stepEnabled(results, i, 1));
+                } else if (e.key === "ArrowUp") {
+                  e.preventDefault();
+                  if (!open) setOpen(true);
+                  // From "nothing highlighted", Up goes to the bottom, as the APG has it.
+                  else setActive((i) => stepEnabled(results, i < 0 ? results.length : i, -1));
+                } else if (e.key === "Enter") {
+                  // No row highlighted: the text is the answer, and a form's own submit
+                  // is left alone.
+                  if (expanded && activeId) {
+                    e.preventDefault();
+                    take(results[active]);
+                  }
+                } else if (e.key === "Tab") {
+                  close();
+                }
+              }}
+              className={cn(
+                FIELD_BASE,
+                hasLabel && FIELD_FLOATING_PAD,
+                // Select's `SELECT_SM` box: a fixed 28px, so the caller's line height
+                // cannot grow it.
+                small && "h-7 py-0 pe-2 ps-2 text-xs",
+                icon ? (small ? "ps-7" : "ps-8") : undefined,
+                busy && (small ? "pe-7" : "pe-9"),
+                field.isInvalid && FIELD_INVALID,
+                inputClassName,
+              )}
+            />
+            {busy && live && (
+              // Decorative: the live region below already says "Loading…".
+              <span
+                className={cn(
+                  "pointer-events-none absolute top-1/2 flex -translate-y-1/2",
+                  small ? "end-2" : "end-2.5",
+                )}
+              >
+                <Spinner label={null} className={small ? "h-3.5 w-3.5" : "h-4 w-4"} />
+              </span>
             )}
-          >
-            <Spinner label={null} className={small ? "h-3.5 w-3.5" : "h-4 w-4"} />
-          </span>
+          </div>,
         )}
-      </div>
+      </EndHintRow>
+      {/* With a "?" the label shares the top strip with it, after the field so the "?"
+          follows the control in the tab order (as on Input and Select). */}
+      {hasLabel && hintParts.labelHint !== undefined && (
+        <StaticLabelRow hint={hintParts.labelHint}>
+          <ComboboxFieldLabel id={labelId} htmlFor={fieldId} className={LABEL_IN_ROW}>
+            {label}
+          </ComboboxFieldLabel>
+        </StaticLabelRow>
+      )}
+      <FieldCaption parts={hintParts} />
       {field.errorEl}
       {/* The live region, kept mounted so a change IS an announcement: focus stays
           in the field, and without it a reader typed into a geocoder and heard only

package/src/components/checkbox-group.tsx

@@ -0,0 +1,229 @@
+import { useId } from "react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Checkbox } from "./checkbox";
+import { hasMessage, mergeDescribedBy } from "./choice-parts";
+import { useCommitReason } from "./write-lock";
+import { RequiredStarOnLegend } from "./field-parts";
+
+/** One box of a {@link CheckboxGroup}. */
+export 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. */
+export type CheckboxGroupLegendVisibility = "visible" | "sr-only";
+
+export 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;
+}
+
+// Literal class strings so Tailwind's scanner sees each one.
+const COLUMNS: Record<NonNullable<CheckboxGroupProps["columns"]>, string> = {
+  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",
+};
+
+/**
+ * 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}).
+ */
+export function CheckboxGroup<T extends string = string>({
+  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,
+}: CheckboxGroupProps<T>) {
+  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);
+  // Resolved here rather than per box: a reason has to keep the fieldset from being
+  // natively `disabled` too, or it would take every box out of the tab order — the
+  // thing a reason exists to prevent.
+  const reason = useCommitReason(commit, disabledReason);
+  const locked = hasMessage(reason);
+
+  const toggle = (v: T, on: boolean) => {
+    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 (
+    <fieldset
+      id={id}
+      aria-label={ariaLabel}
+      aria-describedby={mergeDescribedBy(ariaDescribedBy, showHint && hintId, showError && errorId)}
+      disabled={disabled && !locked}
+      // `relative` holds an `sr-only` legend (sr-only-containment.test); `min-w-0`
+      // undoes a fieldset's `min-width: min-content`, which would otherwise push a long
+      // label past a phone's edge instead of wrapping it.
+      className={cn("relative m-0 min-w-0 border-0 p-0", className)}
+    >
+      {legend !== undefined && (
+        <legend
+          className={
+            legendVisibility === "sr-only"
+              ? "sr-only"
+              : cn("mb-2 p-0 text-sm font-medium text-[var(--text-primary)]", (disabled || locked) && "opacity-60")
+          }
+        >
+          {legend}
+          {required && (
+            <span aria-hidden className="ms-0.5 text-[var(--danger)]">
+              *
+            </span>
+          )}
+        </legend>
+      )}
+      <RequiredStarOnLegend.Provider value={true}>
+        <div
+          className={cn(
+            layout === "horizontal" ? "flex flex-wrap gap-x-4 gap-y-2" : COLUMNS[columns],
+            listClassName,
+          )}
+        >
+          {options.map((o) => (
+            <Checkbox
+              key={o.value}
+              name={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 || undefined}
+              required={required && value.length === 0 ? true : undefined}
+              disabledReason={reason}
+            />
+          ))}
+        </div>
+      </RequiredStarOnLegend.Provider>
+      {showHint && (
+        // A `div`, not a `p`: a hint may be a node with a link in it.
+        <div id={hintId} className="mt-1.5 text-[11px] leading-tight text-[var(--text-muted)]">
+          {hint}
+        </div>
+      )}
+      {showError && (
+        <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
+          {error}
+        </p>
+      )}
+    </fieldset>
+  );
+}