@eifi1/ui-kit 0.20.1 → 0.22.0

package/src/components/autocomplete.tsx

@@ -22,6 +22,7 @@ import {
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { EndHintRow, FieldCaption, LABEL_IN_ROW, StaticLabelRow, useFieldHint } from "./field-parts";
 
 /**
  * `value`/`onChange` are the TEXT's, and `onSelect` is "a suggestion was taken" —
@@ -104,6 +105,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
@@ -135,6 +144,7 @@ function AutocompleteInner<V extends string | number = string>(
     icon,
     invalid,
     error,
+    hint,
     status,
     emptyLabel,
     loadErrorLabel,
@@ -166,7 +176,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. */
@@ -241,124 +252,136 @@ 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",
-            )}
-          >
-            {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();
+      <EndHintRow hint={hasLabel ? undefined : hintParts.labelHint}>
+        <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",
+              )}
+            >
+              {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();
-              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) {
+            }}
+            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();
-                take(results[active]);
+                e.stopPropagation();
+                close();
+                return;
               }
-            } 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
+              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(
-              "pointer-events-none absolute top-1/2 flex -translate-y-1/2",
-              small ? "end-2" : "end-2.5",
+              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,
             )}
-          >
-            <Spinner label={null} className={small ? "h-3.5 w-3.5" : "h-4 w-4"} />
-          </span>
-        )}
-      </div>
+          />
+          {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>
+          )}
+        </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>
+  );
+}