@eifi1/ui-kit 0.35.0 → 0.37.0

package/dist/components/autocomplete.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/autocomplete.tsx"],"sourcesContent":["import { Fragment, useId, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode, Ref } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./field-base\";\nimport { Spinner } from \"./spinner\";\nimport { useAnchoredPanel } from \"../hooks/use-anchored-panel\";\nimport { takeEscape, useDismissLayer } from \"../hooks/use-dismiss\";\nimport { isImeEnter } from \"../lib/ime\";\nimport { useAnchorDir } from \"./use-anchor-dir\";\nimport {\n  ComboboxFieldLabel,\n  DISABLED_ROW_CLASS,\n  endHintRowProps,\n  isOptionEnabled,\n  stepEnabled,\n  SUGGESTION_LIST_CLASS,\n  suggestionRowClass,\n  useActiveOptionScroll,\n  useOptionSource,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, useKitLabels } from \"../i18n/kit-labels\";\nimport {\n  EndHintRow,\n  FieldCaption,\n  LABEL_IN_ROW,\n  LockedReason,\n  mergeDescribedBy,\n  StaticLabelRow,\n  useFieldError,\n  useFieldHint,\n  useLockReason,\n  type DisabledReasonDisplay,\n} from \"./field-parts\";\nimport type { CommitScope } from \"./write-lock\";\n\n/**\n * `value`/`onChange` are the TEXT's, and `onSelect` is \"a suggestion was taken\" —\n * not the DOM's text-selection event — so the input's own spellings of those three\n * are omitted. Everything else reaches the `<input>`, the way it does on {@link Input}.\n */\nexport interface AutocompleteProps<V extends string | number = string>\n  extends Omit<\n    ComponentPropsWithoutRef<\"input\">,\n    \"value\" | \"defaultValue\" | \"onChange\" | \"onSelect\" | \"children\" | \"type\" | \"size\"\n  > {\n  /** What is in the field. Controlled, and never reset by the component: opening,\n   *  closing and a failed lookup all leave it exactly as typed. */\n  value: string;\n  /** Every keystroke — and, with `fillOnSelect`, the label of a taken suggestion. */\n  onChange: (text: string) => void;\n  /** Suggestions the caller already has (e.g. from its own query hook). Narrowed by\n   *  the text unless `filter={false}`. An option with `disabled: true` is listed but\n   *  cannot be taken — see {@link ComboOption.disabled}. */\n  options?: ComboOption<V>[];\n  /** Or: fetch them. Debounced (`debounceMs`), race-safe, only at `minChars` and up,\n   *  never while the field is idle; a rejection shows `loadErrorLabel` and empties\n   *  the list rather than leaving the previous text's rows under it. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** Narrow `options` by label/sublabel substring. Default `true`. Pass `false` for\n   *  a list a server has already searched and ranked — it is shown as given. */\n  filter?: boolean;\n  /** External loading flag (a caller-side fetch), OR-ed with `loadOptions`'. */\n  loading?: boolean;\n  /** Below this many characters nothing is offered or fetched. Default 1: an empty\n   *  field asks nothing — focusing it is not a search. */\n  minChars?: number;\n  /** Quiet time before `loadOptions` runs. Default 300 ms — an ordinary typist's\n   *  inter-key interval is 150–250 ms, so the pickers' 150 fires on nearly every\n   *  letter, which a rate-limited geocoder cannot afford. */\n  debounceMs?: number;\n  /**\n   * Whether the list MAY show — controlled. Omit (or pass `undefined`) and the field\n   * decides: open while focused, until Escape, Tab or a taken row. `false` keeps it\n   * shut whatever the user does, and stops `loadOptions` asking — keksdose's address\n   * search, with its confirm map up, where it used to pass `minChars={Infinity}`.\n   * `true` shows it even unfocused.\n   *\n   * Even open, the list only APPEARS when it has something to show (rows, or a\n   * status line); `aria-expanded` follows what appears, not this flag.\n   */\n  open?: boolean;\n  /** The field wants the list open or shut — focus, typing, ↓/↑ open it; blur,\n   *  Escape, Tab and taking a row shut it. Called on every change, controlled or not. */\n  onOpenChange?: (open: boolean) => void;\n  /**\n   * `\"sm\"`: the 28px, 12px-type field of {@link Select}'s `size=\"sm\"`, with the icon,\n   * spinner and list rows scaled to match — for a card or toolbar whose buttons are\n   * small. `\"md\"` (default) is the form field. Unlabelled only, as on `Select`: a\n   * floating label needs the tall box, so a labelled field ignores `\"sm\"`.\n   *\n   * A NUMBER is still the native `size` attribute (the width in characters), passed\n   * straight through.\n   */\n  size?: \"sm\" | \"md\" | number;\n  /** A suggestion was taken (click, or Enter on the highlighted row). */\n  onSelect?: (option: ComboOption<V>) => void;\n  /**\n   * Put the taken suggestion's label into the field (`onChange(label)`). Default\n   * `true` — the free-text case, where the text IS the value and a suggestion only\n   * completes it (an address field). Pass `false` where taking a row is an ACTION\n   * and the field is only the search that found it; the text then stays as typed.\n   */\n  fillOnSelect?: boolean;\n  /** A floating label, as on {@link Combobox} — a real `<label for>` on the input.\n   *  Names the field (`aria-labelledby`) unless an `aria-label` is given. */\n  label?: ReactNode;\n  /** Leading decoration inside the field (a pin, a magnifier). Decorative: the\n   *  label names the field. An `<svg>` child is sized by the field — 16px, or 14px\n   *  at `size=\"sm\"` — so a lucide icon needs no class of its own. */\n  icon?: ReactNode;\n  /** Required and unanswered — {@link FIELD_INVALID}. */\n  invalid?: boolean;\n  /** What is wrong with the VALUE, as {@link Input}'s `error`: under the field, on\n   *  its `aria-describedby`, implies `invalid`. Not a failed lookup — that is\n   *  `loadErrorLabel`, shown in the list. */\n  error?: ReactNode;\n  /**\n   * Standing advice — {@link Combobox}'s `hint`, so this field reads like every other\n   * (keksdose K4): plain TEXT is a caption under the field on the input's\n   * `aria-describedby`, before any error; a {@link FieldHint} \"?\" rides the label line,\n   * or with no label sits at the field's end edge, outside the box. Not the list's\n   * `status` line, which talks about the lookup, not the field.\n   *\n   * Pass it — even as `undefined` — on a field whose hint comes and goes (0.24): the\n   * unlabelled field then keeps its end-hint row whether or not a \"?\" is in it, so the\n   * `<input>` is never re-parented, and focus and caret survive the toggle. The rule\n   * the rest of the family has had since 0.23 (and the fields since 0.22).\n   */\n  hint?: ReactNode;\n  /**\n   * The caller's own line in the list, replacing the automatic one (loading / failed\n   * / no results). For what only the caller knows: \"offline\", \"the address service\n   * is switched off\", a privacy note, the hint a caller-fetched list needs below its\n   * own minimum. While set, the list opens even with no rows. Announced politely.\n   */\n  status?: ReactNode;\n  /** Default: `combobox.noResults` from the {@link UiKitProvider}, else English. */\n  emptyLabel?: string;\n  /** Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n  /** Classes for the `<input>` itself; `className` styles the wrapper. */\n  inputClassName?: string;\n  /**\n   * Why the field cannot be changed — {@link Button}'s `disabledReason`, the Combobox\n   * family's write lock (keksdose G2, 0.23), for a field whose pick SAVES: an address\n   * search whose taken row writes the address, a lookup that links a record.\n   *\n   * With a reason the input stays focusable and `aria-disabled`, is `readOnly` (the\n   * settled grey FIELD_BASE gives a `[readonly]` field), opens no list and asks no\n   * `loadOptions` — whatever `open` says — and nothing reaches `onChange`, `onSelect` or\n   * `onOpenChange(true)`. Enter is swallowed, so a locked field does not submit the form\n   * around it, and a caller's `onKeyDown` does not hear it; every other key still\n   * reaches the caller (an Escape that closes its panel) and the caret. The reason is in\n   * the kit {@link Tooltip} and on the input's `aria-describedby`. Wins over `disabled`.\n   */\n  disabledReason?: ReactNode;\n  /**\n   * This field COMMITS. Under a locked {@link WriteLockProvider} it is locked the\n   * `disabledReason` way with the lock's reason (which wins over its own). A search\n   * whose result is only draft state — the form's Save writes it — leaves this off and\n   * stays live under the lock. No provider, or an unlocked one: no effect.\n   */\n  commit?: CommitScope;\n  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the\n   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */\n  disabledReasonDisplay?: DisabledReasonDisplay;\n  /** The `<input>`. A React 19 ref prop since 0.34 (MOD-4, refactor audit 2026-10): it was\n   *  `forwardRef`, cast back to a generic function, with a `displayName` line beside it. */\n  ref?: Ref<HTMLInputElement>;\n}\n\n/**\n * An inline, async-capable text field with a suggestion list under it — the\n * WAI-ARIA APG \"editable combobox with list autocomplete\".\n *\n * Two jobs, one control:\n *  - **free text** (kastlan's address field): the text is the value, the list only\n *    offers completions, and taking one fills the field (`fillOnSelect`, default);\n *  - **search-then-act** (keksdose's address search): the text is a query, taking a\n *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).\n *\n * How it differs from its siblings: {@link Combobox} is free text over a STATIC\n * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.\n * This one keeps no value of its own, never resets the text, asks nothing below\n * `minChars`, and reports a failed lookup instead of showing stale rows.\n *\n * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted\n * row, `aria-controls` the list, and a polite live region says what the list now\n * holds. Keyboard: ↓/↑ move (↓ opens) over every row but a `disabled` one, Enter\n * takes the highlighted row (with none,\n * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay\n * with the caret. An Escape that closes an open list is consumed and never reaches the\n * caller; with the list closed it does. For every other key a caller's `onKeyDown`\n * runs first and may `preventDefault()` to\n * keep a key for itself.\n *\n * The list is portalled and anchored under the field on every screen size: the\n * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear\n * of it on a phone. There is no full-screen sheet as {@link Combobox} has.\n *\n * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.\n */\nexport function Autocomplete<V extends string | number = string>(props: AutocompleteProps<V>) {\n  const {\n    ref,\n    value,\n    onChange,\n    options,\n    loadOptions,\n    filter,\n    loading,\n    minChars = 1,\n    debounceMs = 300,\n    onSelect,\n    fillOnSelect = true,\n    label,\n    icon,\n    invalid,\n    error,\n    hint,\n    status,\n    emptyLabel,\n    loadErrorLabel,\n    open: openProp,\n    onOpenChange,\n    size,\n    className,\n    inputClassName,\n    id,\n    disabled,\n    disabledReason,\n    disabledReasonDisplay,\n    commit,\n    onKeyDown,\n    onFocus,\n    onBlur,\n    \"aria-label\": ariaLabel,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    ...rest\n  } = props;\n  const generated = useId();\n  const fieldId = id ?? generated;\n  // Off the GENERATED id: a caller's `id` is theirs to collide with.\n  const listboxId = `${generated}-listbox`;\n  const labelId = `${generated}-label`;\n  const optionId = (index: number) => `${generated}-option-${index}`;\n  const fieldRef = useRef<HTMLDivElement>(null);\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    noResults: emptyLabel,\n    loadError: loadErrorLabel,\n  });\n  const hintParts = useFieldHint(hint, ariaDescribedBy);\n  // A form library's `aria-invalid` paints as well as announces (DUP-8: it only\n  // announced, through the spread below).\n  const field = useFieldError(error, invalid, hintParts.describedBy, rest[\"aria-invalid\"]);\n\n  /** The user's intent: the field is focused and the list has not been dismissed.\n   *  Whether anything SHOWS is decided below, from what there is to show. */\n  const [ownOpen, setOwnOpen] = useState(false);\n  // Controlled when the caller passes a boolean. The own state is kept up to date\n  // either way, so a caller that controls only SOMETIMES (`open={confirming ? false :\n  // undefined}`) hands back a field that is exactly as open as focus says it is.\n  const open = openProp ?? ownOpen;\n  const setOpen = (next: boolean) => {\n    setOwnOpen(next);\n    if (next !== open) onOpenChange?.(next);\n  };\n  const [active, setActive] = useState(-1);\n  // The lock: focusable, `readOnly`, no list — see `disabledReason`. Folded into `live`,\n  // so a locked field asks nothing and shows nothing even with `open` held true.\n  const lock = useLockReason(commit, disabledReason);\n  const locked = lock.locked;\n  const live = open && !disabled && !locked;\n  const { results, busy, failed, tooShort } = useOptionSource<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n    query: value,\n    active: live,\n  });\n\n  const hasStatus = status !== undefined && status !== null && status !== false && status !== \"\";\n  // The visible line under the rows. Nothing below `minChars` unless the caller has\n  // something to say — an empty field opening a box that says \"type more\" is noise.\n  const statusLine: ReactNode = hasStatus\n    ? status\n    : tooShort\n      ? null\n      : busy && results.length === 0\n        ? labels.loading\n        : failed\n          ? labels.loadError\n          : !busy && results.length === 0\n            ? labels.noResults\n            : null;\n  const expanded = live && (results.length > 0 || statusLine !== null);\n  // A disabled row is never the keyboard's — not even when a list that changed under\n  // the highlight put one there.\n  const activeId = expanded && isOptionEnabled(results[active]) ? optionId(active) : undefined;\n  useActiveOptionScroll(activeId);\n  const { rect, top, bottom, maxHeight, above } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });\n  const dir = useAnchorDir(fieldRef, expanded);\n\n  const close = () => {\n    setOpen(false);\n    setActive(-1);\n  };\n  // The list is a layer on the kit's Escape stack while it shows (Wave 2, DUP-1).\n  useDismissLayer(expanded, close);\n  const take = (o: ComboOption<V>) => {\n    if (o.disabled || locked) return;\n    if (fillOnSelect) onChange(o.label);\n    onSelect?.(o);\n    close();\n  };\n\n  const hasLabel = label !== undefined;\n  // `size=\"sm\"` is for an UNLABELLED field, as on Select: the floating label needs the\n  // tall box. A number is the native attribute.\n  const small = size === \"sm\" && !hasLabel;\n  const nativeSize = typeof size === \"number\" ? size : undefined;\n  // The caller's name wins; else the floating label, by reference so a non-string\n  // label still names the field.\n  const labelledBy =\n    ariaLabel === undefined ? (ariaLabelledBy ?? (hasLabel ? labelId : undefined)) : undefined;\n  // While locked the field sits in the reason's Tooltip — in a fragment with a hidden\n  // copy of the reason, Button's anatomy; `block` so a full-width field stays full width.\n  const withLock = (box: ReactNode) =>\n    locked ? (\n      <LockedReason lock={lock} display={disabledReasonDisplay} className=\"block\">\n        {box}\n      </LockedReason>\n    ) : (\n      box\n    );\n\n  return (\n    // `relative`: the floating label and the live region's `sr-only` both need a\n    // local containing block.\n    <div className={cn(\"relative\", className)}>\n      {/* A real <label for> (lenkbank), and still `aria-labelledby`'s target, so the\n          name — and the listbox's, which borrows it — is exactly what it was. */}\n      {hasLabel && hintParts.labelHint === undefined && (\n        <ComboboxFieldLabel id={labelId} htmlFor={fieldId}>\n          {label}\n        </ComboboxFieldLabel>\n      )}\n      {/* `\"hint\" in props`: the family's 0.22 rule (see `endHintRowProps`) — passed at\n          all, even as `undefined`, a hint keeps the unlabelled field's end-hint row, so\n          a \"?\" coming and going never re-parents the <input> under the caret (0.24, the\n          last of the family to get it; the siblings had it in 0.23). */}\n      <EndHintRow {...endHintRowProps(\"hint\" in props, hasLabel, hintParts.labelHint)}>\n        {withLock(\n          <div ref={fieldRef} className={cn(\"relative\", locked && \"cursor-not-allowed\")}>\n            {icon && (\n              <span\n                aria-hidden\n                className={cn(\n                  \"pointer-events-none absolute flex text-muted\",\n                  small ? \"start-2 [&>svg]:size-3.5\" : \"start-2.5 [&>svg]:size-4\",\n                  // Labelled, the icon sits on the VALUE's line — the one line box below\n                  // FIELD_FLOATING_PAD's `pt-4` and the 1px border — not on the middle of\n                  // the box. Centred on the box it rose into the top strip and sat on the\n                  // label's first letters, which float at the same start inset. On the\n                  // value line it is beside what it describes, and the label keeps the\n                  // start edge every other label in the form's column shares.\n                  // At Large the label stands above the field and the strip is gone\n                  // (0.33, §10.17): the value's line is under FIELD_BASE's `py-2`.\n                  hasLabel\n                    ? \"top-[calc(1rem+1px)] h-5 items-center large:top-[calc(0.5rem+1px)]\"\n                    : \"top-1/2 -translate-y-1/2\",\n                )}\n              >\n                {icon}\n              </span>\n            )}\n            <input\n              {...rest}\n              ref={ref}\n              id={fieldId}\n              size={nativeSize}\n              type=\"text\"\n              value={value}\n              // Locked: focusable, `readOnly`, `aria-disabled` — see `disabledReason`.\n              disabled={locked ? undefined : disabled}\n              readOnly={locked || rest.readOnly}\n              aria-disabled={locked || rest[\"aria-disabled\"]}\n              role=\"combobox\"\n              aria-autocomplete=\"list\"\n              aria-expanded={expanded}\n              // Required by the role, and set while closed too, as on the siblings.\n              aria-controls={listboxId}\n              aria-activedescendant={activeId}\n              aria-label={ariaLabel}\n              aria-labelledby={labelledBy}\n              aria-invalid={field.isInvalid || rest[\"aria-invalid\"] || undefined}\n              aria-describedby={mergeDescribedBy(field.describedBy, locked && lock.reasonId)}\n              autoComplete=\"off\"\n              onFocus={(e) => {\n                onFocus?.(e);\n                // A locked field takes focus to say why, and opens nothing.\n                if (locked) return;\n                // A seeded field (keksdose's `initialQuery`) is looked up as it is\n                // focused; an empty one asks nothing, because of `minChars`.\n                setOpen(true);\n              }}\n              onBlur={(e) => {\n                onBlur?.(e);\n                close();\n              }}\n              onChange={(e) => {\n                if (locked) return;\n                onChange(e.target.value);\n                setOpen(true);\n                setActive(-1);\n              }}\n              onKeyDown={(e) => {\n                // Locked: Enter is swallowed (no form submit, no caller's \"search now\");\n                // every other key is the caller's and the caret's. No list to drive.\n                if (locked) {\n                  if (e.key === \"Enter\") e.preventDefault();\n                  else onKeyDown?.(e);\n                  return;\n                }\n                // An Escape that closes the OPEN list is the list's, and is consumed before\n                // the caller sees it. A caller whose Escape means \"close the panel\" (keksdose's\n                // address search) otherwise closed the whole panel when the user only meant\n                // to dismiss the suggestions — the opposite of what the docs promised.\n                if (e.key === \"Escape\" && expanded && takeEscape(e)) return;\n                onKeyDown?.(e);\n                if (e.defaultPrevented) return;\n                // Disabled rows are passed over; at either end the highlight stays put.\n                if (e.key === \"ArrowDown\") {\n                  e.preventDefault();\n                  if (!open) setOpen(true);\n                  else setActive((i) => stepEnabled(results, i, 1));\n                } else if (e.key === \"ArrowUp\") {\n                  e.preventDefault();\n                  if (!open) setOpen(true);\n                  // From \"nothing highlighted\", Up goes to the bottom, as the APG has it.\n                  else setActive((i) => stepEnabled(results, i < 0 ? results.length : i, -1));\n                } else if (e.key === \"Enter\") {\n                  // No row highlighted: the text is the answer, and a form's own submit\n                  // is left alone. Nor is a row taken by the Enter that confirms an IME\n                  // composition, which is the IME's (BUG-9).\n                  if (expanded && activeId && !isImeEnter(e)) {\n                    e.preventDefault();\n                    take(results[active]);\n                  }\n                } else if (e.key === \"Tab\") {\n                  close();\n                }\n              }}\n              className={cn(\n                FIELD_BASE,\n                hasLabel && FIELD_FLOATING_PAD,\n                // Select's `SELECT_SM` box: a fixed 28px, so the caller's line height\n                // cannot grow it.\n                small && \"h-7 py-0 pe-2 ps-2 text-xs\",\n                icon ? (small ? \"ps-7\" : \"ps-8\") : undefined,\n                busy && (small ? \"pe-7\" : \"pe-9\"),\n                field.isInvalid && FIELD_INVALID,\n                inputClassName,\n              )}\n            />\n            {busy && live && (\n              // Decorative: the live region below already says \"Loading…\".\n              <span\n                className={cn(\n                  \"pointer-events-none absolute top-1/2 flex -translate-y-1/2\",\n                  small ? \"end-2\" : \"end-2.5\",\n                )}\n              >\n                <Spinner label={null} className={small ? \"h-3.5 w-3.5\" : \"h-4 w-4\"} />\n              </span>\n            )}\n          </div>,\n        )}\n      </EndHintRow>\n      {/* With a \"?\" the label shares the top strip with it, after the field so the \"?\"\n          follows the control in the tab order (as on Input and Select). */}\n      {hasLabel && hintParts.labelHint !== undefined && (\n        <StaticLabelRow hint={hintParts.labelHint}>\n          <ComboboxFieldLabel id={labelId} htmlFor={fieldId} className={LABEL_IN_ROW}>\n            {label}\n          </ComboboxFieldLabel>\n        </StaticLabelRow>\n      )}\n      <FieldCaption parts={hintParts} />\n      {field.errorEl}\n      {/* The live region, kept mounted so a change IS an announcement: focus stays\n          in the field, and without it a reader typed into a geocoder and heard only\n          their own letters. The panel's visible line is aria-hidden in favour of\n          this, which also carries the row count the eye reads off the list. */}\n      <div role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n        {!live\n          ? null\n          : statusLine !== null\n            ? statusLine\n            : results.length > 0\n              ? labels.resultCount(results.length)\n              : null}\n      </div>\n      {expanded &&\n        rect &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <div\n            // Every press inside the list keeps focus in the field — rows, the status\n            // line, the scrollbar — or the input's blur would close the list first.\n            role=\"presentation\"\n            // Portalled out of the form's `dir`; the field's is put back. The list is\n            // exactly the field's width, so `left` places it in either direction.\n            dir={dir}\n            onMouseDown={(e) => e.preventDefault()}\n            // The family's suggestion box (DUP-4), as a column: the list scrolls inside\n            // it and the status line stays under the rows.\n            className={cn(SUGGESTION_LIST_CLASS, \"fixed z-50 flex flex-col overflow-hidden py-0\")}\n            // Flipped above, the list hangs from its bottom edge: three rows under a\n            // 256 px cap, placed by `top`, floated ~176 px above the field (keksdose K1),\n            // and the rows come and go as the user types.\n            style={{ ...(above ? { bottom } : { top }), left: rect.left, width: rect.width, maxHeight }}\n          >\n            {results.length > 0 && (\n              <ul\n                id={listboxId}\n                role=\"listbox\"\n                aria-label={ariaLabel}\n                aria-labelledby={labelledBy}\n                className=\"min-h-0 flex-1 overflow-y-auto py-1\"\n              >\n                {results.map((o, i) => {\n                  const startsGroup = o.group != null && o.group !== results[i - 1]?.group;\n                  return (\n                    // Keyed by group AND value, as in the core panel: an option may\n                    // appear once per group.\n                    <Fragment key={`${o.group ?? \"\"}|${String(o.value)}`}>\n                      {startsGroup && (\n                        <li\n                          role=\"presentation\"\n                          className=\"px-3 pb-0.5 pt-2 text-caption font-semibold uppercase tracking-wide text-muted first:pt-1\"\n                        >\n                          {o.group}\n                        </li>\n                      )}\n                      <li role=\"presentation\">\n                        <button\n                          type=\"button\"\n                          id={optionId(i)}\n                          role=\"option\"\n                          // CHOSEN, never \"highlighted\" — the family's rule. This\n                          // field holds no value, so the only row that can be chosen\n                          // is the one whose label the text already is.\n                          aria-selected={fillOnSelect && o.label === value}\n                          // Listed, announced as unavailable, never taken: `take`\n                          // refuses it and the arrows pass it over.\n                          aria-disabled={o.disabled || undefined}\n                          tabIndex={-1}\n                          onClick={() => take(o)}\n                          onMouseEnter={() => {\n                            if (!o.disabled) setActive(i);\n                          }}\n                          className={cn(\n                            // The family's suggestion row (DUP-4): it hand-rolled its\n                            // own with a plain `truncate`, so a long address was cut at\n                            // Large, where Combobox's rows wrap (text size §10.17, T1).\n                            // A flex row here, for the icon and the two lines.\n                            suggestionRowClass(i === active && !o.disabled),\n                            \"flex items-center gap-2\",\n                            small && \"py-1 text-xs\",\n                            o.disabled && DISABLED_ROW_CLASS,\n                            o.group != null && \"ps-6\",\n                          )}\n                        >\n                          {o.icon && (\n                            <span aria-hidden className=\"shrink-0 text-muted\">\n                              {o.icon}\n                            </span>\n                          )}\n                          <span className=\"min-w-0 flex-1\">\n                            <span className=\"block truncate-until-large text-primary\">\n                              {o.label}\n                            </span>\n                            {o.sublabel && (\n                              <span\n                                className={cn(\n                                  \"block truncate-until-large text-placeholder\",\n                                  small ? \"text-caption\" : \"text-xs\",\n                                )}\n                              >\n                                {o.sublabel}\n                              </span>\n                            )}\n                          </span>\n                        </button>\n                      </li>\n                    </Fragment>\n                  );\n                })}\n              </ul>\n            )}\n            {statusLine !== null && (\n              // Visible, not live — the region above speaks for it.\n              <div\n                aria-hidden\n                className={cn(\n                  small ? \"px-3 py-1.5 text-xs\" : \"px-3 py-2 text-sm\",\n                  failed && !hasStatus ? \"text-danger\" : \"text-muted\",\n                  results.length > 0 && \"border-t border-subtle text-xs\",\n                )}\n              >\n                {statusLine}\n              </div>\n            )}\n          </div>,\n          document.body,\n        )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/autocomplete.tsx"],"sourcesContent":["import { Fragment, useId, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode, Ref } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./field-base\";\nimport { Spinner } from \"./spinner\";\nimport { useAnchoredPanel } from \"../hooks/use-anchored-panel\";\nimport { takeEscape, useDismissLayer } from \"../hooks/use-dismiss\";\nimport { isImeEnter } from \"../lib/ime\";\nimport { useAnchorDir } from \"./use-anchor-dir\";\nimport {\n  ComboboxFieldLabel,\n  DISABLED_ROW_CLASS,\n  endHintRowProps,\n  isOptionEnabled,\n  stepEnabled,\n  SUGGESTION_LIST_CLASS,\n  suggestionRowClass,\n  useActiveOptionScroll,\n  useOptionSource,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, useKitLabels } from \"../i18n/kit-labels\";\nimport {\n  EndHintRow,\n  FieldCaption,\n  LABEL_IN_ROW,\n  LockedReason,\n  mergeDescribedBy,\n  StaticLabelRow,\n  useFieldError,\n  useFieldHint,\n  useLockReason,\n  type DisabledReasonDisplay,\n  type FieldHelpProps,\n} from \"./field-parts\";\nimport type { CommitScope } from \"./write-lock\";\n\n/**\n * `value`/`onChange` are the TEXT's, and `onSelect` is \"a suggestion was taken\" —\n * not the DOM's text-selection event — so the input's own spellings of those three\n * are omitted. Everything else reaches the `<input>`, the way it does on {@link Input}.\n */\nexport interface AutocompleteProps<V extends string | number = string>\n  extends Omit<\n    ComponentPropsWithoutRef<\"input\">,\n    \"value\" | \"defaultValue\" | \"onChange\" | \"onSelect\" | \"children\" | \"type\" | \"size\"\n  >,\n    FieldHelpProps {\n  /** What is in the field. Controlled, and never reset by the component: opening,\n   *  closing and a failed lookup all leave it exactly as typed. */\n  value: string;\n  /** Every keystroke — and, with `fillOnSelect`, the label of a taken suggestion. */\n  onChange: (text: string) => void;\n  /** Suggestions the caller already has (e.g. from its own query hook). Narrowed by\n   *  the text unless `filter={false}`. An option with `disabled: true` is listed but\n   *  cannot be taken — see {@link ComboOption.disabled}. */\n  options?: ComboOption<V>[];\n  /** Or: fetch them. Debounced (`debounceMs`), race-safe, only at `minChars` and up,\n   *  never while the field is idle; a rejection shows `loadErrorLabel` and empties\n   *  the list rather than leaving the previous text's rows under it. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** Narrow `options` by label/sublabel substring. Default `true`. Pass `false` for\n   *  a list a server has already searched and ranked — it is shown as given. */\n  filter?: boolean;\n  /** External loading flag (a caller-side fetch), OR-ed with `loadOptions`'. */\n  loading?: boolean;\n  /** Below this many characters nothing is offered or fetched. Default 1: an empty\n   *  field asks nothing — focusing it is not a search. */\n  minChars?: number;\n  /** Quiet time before `loadOptions` runs. Default 300 ms — an ordinary typist's\n   *  inter-key interval is 150–250 ms, so the pickers' 150 fires on nearly every\n   *  letter, which a rate-limited geocoder cannot afford. */\n  debounceMs?: number;\n  /**\n   * Whether the list MAY show — controlled. Omit (or pass `undefined`) and the field\n   * decides: open while focused, until Escape, Tab or a taken row. `false` keeps it\n   * shut whatever the user does, and stops `loadOptions` asking — keksdose's address\n   * search, with its confirm map up, where it used to pass `minChars={Infinity}`.\n   * `true` shows it even unfocused.\n   *\n   * Even open, the list only APPEARS when it has something to show (rows, or a\n   * status line); `aria-expanded` follows what appears, not this flag.\n   */\n  open?: boolean;\n  /** The field wants the list open or shut — focus, typing, ↓/↑ open it; blur,\n   *  Escape, Tab and taking a row shut it. Called on every change, controlled or not. */\n  onOpenChange?: (open: boolean) => void;\n  /**\n   * `\"sm\"`: the 28px, 12px-type field of {@link Select}'s `size=\"sm\"`, with the icon,\n   * spinner and list rows scaled to match — for a card or toolbar whose buttons are\n   * small. `\"md\"` (default) is the form field. Unlabelled only, as on `Select`: a\n   * floating label needs the tall box, so a labelled field ignores `\"sm\"`.\n   *\n   * A NUMBER is still the native `size` attribute (the width in characters), passed\n   * straight through.\n   */\n  size?: \"sm\" | \"md\" | number;\n  /** A suggestion was taken (click, or Enter on the highlighted row). */\n  onSelect?: (option: ComboOption<V>) => void;\n  /**\n   * Put the taken suggestion's label into the field (`onChange(label)`). Default\n   * `true` — the free-text case, where the text IS the value and a suggestion only\n   * completes it (an address field). Pass `false` where taking a row is an ACTION\n   * and the field is only the search that found it; the text then stays as typed.\n   */\n  fillOnSelect?: boolean;\n  /** A floating label, as on {@link Combobox} — a real `<label for>` on the input.\n   *  Names the field (`aria-labelledby`) unless an `aria-label` is given. */\n  label?: ReactNode;\n  /** Leading decoration inside the field (a pin, a magnifier). Decorative: the\n   *  label names the field. An `<svg>` child is sized by the field — 16px, or 14px\n   *  at `size=\"sm\"` — so a lucide icon needs no class of its own. */\n  icon?: ReactNode;\n  /** Required and unanswered — {@link FIELD_INVALID}. */\n  invalid?: boolean;\n  /** What is wrong with the VALUE, as {@link Input}'s `error`: under the field, on\n   *  its `aria-describedby`, implies `invalid`. Not a failed lookup — that is\n   *  `loadErrorLabel`, shown in the list. */\n  error?: ReactNode;\n  /**\n   * Standing advice — {@link Combobox}'s `hint`, so this field reads like every other\n   * (keksdose K4): plain TEXT is a caption under the field on the input's\n   * `aria-describedby`, before any error; a {@link FieldHint} \"?\" rides the label line,\n   * or with no label sits at the field's end edge, outside the box. Not the list's\n   * `status` line, which talks about the lookup, not the field.\n   *\n   * Pass it — even as `undefined` — on a field whose hint comes and goes (0.24): the\n   * unlabelled field then keeps its end-hint row whether or not a \"?\" is in it, so the\n   * `<input>` is never re-parented, and focus and caret survive the toggle. The rule\n   * the rest of the family has had since 0.23 (and the fields since 0.22).\n   */\n  hint?: ReactNode;\n  /**\n   * The caller's own line in the list, replacing the automatic one (loading / failed\n   * / no results). For what only the caller knows: \"offline\", \"the address service\n   * is switched off\", a privacy note, the hint a caller-fetched list needs below its\n   * own minimum. While set, the list opens even with no rows. Announced politely.\n   */\n  status?: ReactNode;\n  /** Default: `combobox.noResults` from the {@link UiKitProvider}, else English. */\n  emptyLabel?: string;\n  /** Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n  /** Classes for the `<input>` itself; `className` styles the wrapper. */\n  inputClassName?: string;\n  /**\n   * Why the field cannot be changed — {@link Button}'s `disabledReason`, the Combobox\n   * family's write lock (keksdose G2, 0.23), for a field whose pick SAVES: an address\n   * search whose taken row writes the address, a lookup that links a record.\n   *\n   * With a reason the input stays focusable and `aria-disabled`, is `readOnly` (the\n   * settled grey FIELD_BASE gives a `[readonly]` field), opens no list and asks no\n   * `loadOptions` — whatever `open` says — and nothing reaches `onChange`, `onSelect` or\n   * `onOpenChange(true)`. Enter is swallowed, so a locked field does not submit the form\n   * around it, and a caller's `onKeyDown` does not hear it; every other key still\n   * reaches the caller (an Escape that closes its panel) and the caret. The reason is in\n   * the kit {@link Tooltip} and on the input's `aria-describedby`. Wins over `disabled`.\n   */\n  disabledReason?: ReactNode;\n  /**\n   * This field COMMITS. Under a locked {@link WriteLockProvider} it is locked the\n   * `disabledReason` way with the lock's reason (which wins over its own). A search\n   * whose result is only draft state — the form's Save writes it — leaves this off and\n   * stays live under the lock. No provider, or an unlocked one: no effect.\n   */\n  commit?: CommitScope;\n  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the\n   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */\n  disabledReasonDisplay?: DisabledReasonDisplay;\n  /** The `<input>`. A React 19 ref prop since 0.34 (MOD-4, refactor audit 2026-10): it was\n   *  `forwardRef`, cast back to a generic function, with a `displayName` line beside it. */\n  ref?: Ref<HTMLInputElement>;\n}\n\n/**\n * An inline, async-capable text field with a suggestion list under it — the\n * WAI-ARIA APG \"editable combobox with list autocomplete\".\n *\n * Two jobs, one control:\n *  - **free text** (kastlan's address field): the text is the value, the list only\n *    offers completions, and taking one fills the field (`fillOnSelect`, default);\n *  - **search-then-act** (keksdose's address search): the text is a query, taking a\n *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).\n *\n * How it differs from its siblings: {@link Combobox} is free text over a STATIC\n * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.\n * This one keeps no value of its own, never resets the text, asks nothing below\n * `minChars`, and reports a failed lookup instead of showing stale rows.\n *\n * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted\n * row, `aria-controls` the list, and a polite live region says what the list now\n * holds. Keyboard: ↓/↑ move (↓ opens) over every row but a `disabled` one, Enter\n * takes the highlighted row (with none,\n * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay\n * with the caret. An Escape that closes an open list is consumed and never reaches the\n * caller; with the list closed it does. For every other key a caller's `onKeyDown`\n * runs first and may `preventDefault()` to\n * keep a key for itself.\n *\n * The list is portalled and anchored under the field on every screen size: the\n * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear\n * of it on a phone. There is no full-screen sheet as {@link Combobox} has.\n *\n * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.\n */\nexport function Autocomplete<V extends string | number = string>(props: AutocompleteProps<V>) {\n  const {\n    ref,\n    value,\n    onChange,\n    options,\n    loadOptions,\n    filter,\n    loading,\n    minChars = 1,\n    debounceMs = 300,\n    onSelect,\n    fillOnSelect = true,\n    label,\n    icon,\n    invalid,\n    error,\n    hint,\n    help,\n    status,\n    emptyLabel,\n    loadErrorLabel,\n    open: openProp,\n    onOpenChange,\n    size,\n    className,\n    inputClassName,\n    id,\n    disabled,\n    disabledReason,\n    disabledReasonDisplay,\n    commit,\n    onKeyDown,\n    onFocus,\n    onBlur,\n    \"aria-label\": ariaLabel,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    ...rest\n  } = props;\n  const generated = useId();\n  const fieldId = id ?? generated;\n  // Off the GENERATED id: a caller's `id` is theirs to collide with.\n  const listboxId = `${generated}-listbox`;\n  const labelId = `${generated}-label`;\n  const optionId = (index: number) => `${generated}-option-${index}`;\n  const fieldRef = useRef<HTMLDivElement>(null);\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    noResults: emptyLabel,\n    loadError: loadErrorLabel,\n  });\n  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });\n  // A form library's `aria-invalid` paints as well as announces (DUP-8: it only\n  // announced, through the spread below).\n  const field = useFieldError(error, invalid, hintParts.describedBy, rest[\"aria-invalid\"]);\n\n  /** The user's intent: the field is focused and the list has not been dismissed.\n   *  Whether anything SHOWS is decided below, from what there is to show. */\n  const [ownOpen, setOwnOpen] = useState(false);\n  // Controlled when the caller passes a boolean. The own state is kept up to date\n  // either way, so a caller that controls only SOMETIMES (`open={confirming ? false :\n  // undefined}`) hands back a field that is exactly as open as focus says it is.\n  const open = openProp ?? ownOpen;\n  const setOpen = (next: boolean) => {\n    setOwnOpen(next);\n    if (next !== open) onOpenChange?.(next);\n  };\n  const [active, setActive] = useState(-1);\n  // The lock: focusable, `readOnly`, no list — see `disabledReason`. Folded into `live`,\n  // so a locked field asks nothing and shows nothing even with `open` held true.\n  const lock = useLockReason(commit, disabledReason);\n  const locked = lock.locked;\n  const live = open && !disabled && !locked;\n  const { results, busy, failed, tooShort } = useOptionSource<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n    query: value,\n    active: live,\n  });\n\n  const hasStatus = status !== undefined && status !== null && status !== false && status !== \"\";\n  // The visible line under the rows. Nothing below `minChars` unless the caller has\n  // something to say — an empty field opening a box that says \"type more\" is noise.\n  const statusLine: ReactNode = hasStatus\n    ? status\n    : tooShort\n      ? null\n      : busy && results.length === 0\n        ? labels.loading\n        : failed\n          ? labels.loadError\n          : !busy && results.length === 0\n            ? labels.noResults\n            : null;\n  const expanded = live && (results.length > 0 || statusLine !== null);\n  // A disabled row is never the keyboard's — not even when a list that changed under\n  // the highlight put one there.\n  const activeId = expanded && isOptionEnabled(results[active]) ? optionId(active) : undefined;\n  useActiveOptionScroll(activeId);\n  const { rect, top, bottom, maxHeight, above } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });\n  const dir = useAnchorDir(fieldRef, expanded);\n\n  const close = () => {\n    setOpen(false);\n    setActive(-1);\n  };\n  // The list is a layer on the kit's Escape stack while it shows (Wave 2, DUP-1).\n  useDismissLayer(expanded, close);\n  const take = (o: ComboOption<V>) => {\n    if (o.disabled || locked) return;\n    if (fillOnSelect) onChange(o.label);\n    onSelect?.(o);\n    close();\n  };\n\n  const hasLabel = label !== undefined;\n  // `size=\"sm\"` is for an UNLABELLED field, as on Select: the floating label needs the\n  // tall box. A number is the native attribute.\n  const small = size === \"sm\" && !hasLabel;\n  const nativeSize = typeof size === \"number\" ? size : undefined;\n  // The caller's name wins; else the floating label, by reference so a non-string\n  // label still names the field.\n  const labelledBy =\n    ariaLabel === undefined ? (ariaLabelledBy ?? (hasLabel ? labelId : undefined)) : undefined;\n  // While locked the field sits in the reason's Tooltip — in a fragment with a hidden\n  // copy of the reason, Button's anatomy; `block` so a full-width field stays full width.\n  const withLock = (box: ReactNode) =>\n    locked ? (\n      <LockedReason lock={lock} display={disabledReasonDisplay} className=\"block\">\n        {box}\n      </LockedReason>\n    ) : (\n      box\n    );\n\n  return (\n    // `relative`: the floating label and the live region's `sr-only` both need a\n    // local containing block.\n    <div className={cn(\"relative\", className)}>\n      {/* A real <label for> (lenkbank), and still `aria-labelledby`'s target, so the\n          name — and the listbox's, which borrows it — is exactly what it was. */}\n      {hasLabel && hintParts.labelHint === undefined && (\n        <ComboboxFieldLabel id={labelId} htmlFor={fieldId}>\n          {label}\n        </ComboboxFieldLabel>\n      )}\n      {/* `\"hint\" in props`: the family's 0.22 rule (see `endHintRowProps`) — passed at\n          all, even as `undefined`, a hint keeps the unlabelled field's end-hint row, so\n          a \"?\" coming and going never re-parents the <input> under the caret (0.24, the\n          last of the family to get it; the siblings had it in 0.23). */}\n      <EndHintRow {...endHintRowProps(\"hint\" in props, hasLabel, hintParts.labelHint)}>\n        {withLock(\n          <div ref={fieldRef} className={cn(\"relative\", locked && \"cursor-not-allowed\")}>\n            {icon && (\n              <span\n                aria-hidden\n                className={cn(\n                  \"pointer-events-none absolute flex text-muted\",\n                  small ? \"start-2 [&>svg]:size-3.5\" : \"start-2.5 [&>svg]:size-4\",\n                  // Labelled, the icon sits on the VALUE's line — the one line box below\n                  // FIELD_FLOATING_PAD's `pt-4` and the 1px border — not on the middle of\n                  // the box. Centred on the box it rose into the top strip and sat on the\n                  // label's first letters, which float at the same start inset. On the\n                  // value line it is beside what it describes, and the label keeps the\n                  // start edge every other label in the form's column shares.\n                  // At Large the label stands above the field and the strip is gone\n                  // (0.33, §10.17): the value's line is under FIELD_BASE's `py-2`.\n                  hasLabel\n                    ? \"top-[calc(1rem+1px)] h-5 items-center large:top-[calc(0.5rem+1px)]\"\n                    : \"top-1/2 -translate-y-1/2\",\n                )}\n              >\n                {icon}\n              </span>\n            )}\n            <input\n              {...rest}\n              ref={ref}\n              id={fieldId}\n              size={nativeSize}\n              type=\"text\"\n              value={value}\n              // Locked: focusable, `readOnly`, `aria-disabled` — see `disabledReason`.\n              disabled={locked ? undefined : disabled}\n              readOnly={locked || rest.readOnly}\n              aria-disabled={locked || rest[\"aria-disabled\"]}\n              role=\"combobox\"\n              aria-autocomplete=\"list\"\n              aria-expanded={expanded}\n              // Required by the role, and set while closed too, as on the siblings.\n              aria-controls={listboxId}\n              aria-activedescendant={activeId}\n              aria-label={ariaLabel}\n              aria-labelledby={labelledBy}\n              aria-invalid={field.isInvalid || rest[\"aria-invalid\"] || undefined}\n              aria-describedby={mergeDescribedBy(field.describedBy, locked && lock.reasonId)}\n              autoComplete=\"off\"\n              onFocus={(e) => {\n                onFocus?.(e);\n                // A locked field takes focus to say why, and opens nothing.\n                if (locked) return;\n                // A seeded field (keksdose's `initialQuery`) is looked up as it is\n                // focused; an empty one asks nothing, because of `minChars`.\n                setOpen(true);\n              }}\n              onBlur={(e) => {\n                onBlur?.(e);\n                close();\n              }}\n              onChange={(e) => {\n                if (locked) return;\n                onChange(e.target.value);\n                setOpen(true);\n                setActive(-1);\n              }}\n              onKeyDown={(e) => {\n                // Locked: Enter is swallowed (no form submit, no caller's \"search now\");\n                // every other key is the caller's and the caret's. No list to drive.\n                if (locked) {\n                  if (e.key === \"Enter\") e.preventDefault();\n                  else onKeyDown?.(e);\n                  return;\n                }\n                // An Escape that closes the OPEN list is the list's, and is consumed before\n                // the caller sees it. A caller whose Escape means \"close the panel\" (keksdose's\n                // address search) otherwise closed the whole panel when the user only meant\n                // to dismiss the suggestions — the opposite of what the docs promised.\n                if (e.key === \"Escape\" && expanded && takeEscape(e)) return;\n                onKeyDown?.(e);\n                if (e.defaultPrevented) return;\n                // Disabled rows are passed over; at either end the highlight stays put.\n                if (e.key === \"ArrowDown\") {\n                  e.preventDefault();\n                  if (!open) setOpen(true);\n                  else setActive((i) => stepEnabled(results, i, 1));\n                } else if (e.key === \"ArrowUp\") {\n                  e.preventDefault();\n                  if (!open) setOpen(true);\n                  // From \"nothing highlighted\", Up goes to the bottom, as the APG has it.\n                  else setActive((i) => stepEnabled(results, i < 0 ? results.length : i, -1));\n                } else if (e.key === \"Enter\") {\n                  // No row highlighted: the text is the answer, and a form's own submit\n                  // is left alone. Nor is a row taken by the Enter that confirms an IME\n                  // composition, which is the IME's (BUG-9).\n                  if (expanded && activeId && !isImeEnter(e)) {\n                    e.preventDefault();\n                    take(results[active]);\n                  }\n                } else if (e.key === \"Tab\") {\n                  close();\n                }\n              }}\n              className={cn(\n                FIELD_BASE,\n                hasLabel && FIELD_FLOATING_PAD,\n                // Select's `SELECT_SM` box: a fixed 28px, so the caller's line height\n                // cannot grow it.\n                small && \"h-7 py-0 pe-2 ps-2 text-xs\",\n                icon ? (small ? \"ps-7\" : \"ps-8\") : undefined,\n                busy && (small ? \"pe-7\" : \"pe-9\"),\n                field.isInvalid && FIELD_INVALID,\n                inputClassName,\n              )}\n            />\n            {busy && live && (\n              // Decorative: the live region below already says \"Loading…\".\n              <span\n                className={cn(\n                  \"pointer-events-none absolute top-1/2 flex -translate-y-1/2\",\n                  small ? \"end-2\" : \"end-2.5\",\n                )}\n              >\n                <Spinner label={null} className={small ? \"h-3.5 w-3.5\" : \"h-4 w-4\"} />\n              </span>\n            )}\n          </div>,\n        )}\n      </EndHintRow>\n      {/* With a \"?\" the label shares the top strip with it, after the field so the \"?\"\n          follows the control in the tab order (as on Input and Select). */}\n      {hasLabel && hintParts.labelHint !== undefined && (\n        <StaticLabelRow hint={hintParts.labelHint}>\n          <ComboboxFieldLabel id={labelId} htmlFor={fieldId} className={LABEL_IN_ROW}>\n            {label}\n          </ComboboxFieldLabel>\n        </StaticLabelRow>\n      )}\n      <FieldCaption parts={hintParts} />\n      {field.errorEl}\n      {/* The live region, kept mounted so a change IS an announcement: focus stays\n          in the field, and without it a reader typed into a geocoder and heard only\n          their own letters. The panel's visible line is aria-hidden in favour of\n          this, which also carries the row count the eye reads off the list. */}\n      <div role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n        {!live\n          ? null\n          : statusLine !== null\n            ? statusLine\n            : results.length > 0\n              ? labels.resultCount(results.length)\n              : null}\n      </div>\n      {expanded &&\n        rect &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <div\n            // Every press inside the list keeps focus in the field — rows, the status\n            // line, the scrollbar — or the input's blur would close the list first.\n            role=\"presentation\"\n            // Portalled out of the form's `dir`; the field's is put back. The list is\n            // exactly the field's width, so `left` places it in either direction.\n            dir={dir}\n            onMouseDown={(e) => e.preventDefault()}\n            // The family's suggestion box (DUP-4), as a column: the list scrolls inside\n            // it and the status line stays under the rows.\n            className={cn(SUGGESTION_LIST_CLASS, \"fixed z-50 flex flex-col overflow-hidden py-0\")}\n            // Flipped above, the list hangs from its bottom edge: three rows under a\n            // 256 px cap, placed by `top`, floated ~176 px above the field (keksdose K1),\n            // and the rows come and go as the user types.\n            style={{ ...(above ? { bottom } : { top }), left: rect.left, width: rect.width, maxHeight }}\n          >\n            {results.length > 0 && (\n              <ul\n                id={listboxId}\n                role=\"listbox\"\n                aria-label={ariaLabel}\n                aria-labelledby={labelledBy}\n                className=\"min-h-0 flex-1 overflow-y-auto py-1\"\n              >\n                {results.map((o, i) => {\n                  const startsGroup = o.group != null && o.group !== results[i - 1]?.group;\n                  return (\n                    // Keyed by group AND value, as in the core panel: an option may\n                    // appear once per group.\n                    <Fragment key={`${o.group ?? \"\"}|${String(o.value)}`}>\n                      {startsGroup && (\n                        <li\n                          role=\"presentation\"\n                          className=\"px-3 pb-0.5 pt-2 text-caption font-semibold uppercase tracking-wide text-muted first:pt-1\"\n                        >\n                          {o.group}\n                        </li>\n                      )}\n                      <li role=\"presentation\">\n                        <button\n                          type=\"button\"\n                          id={optionId(i)}\n                          role=\"option\"\n                          // CHOSEN, never \"highlighted\" — the family's rule. This\n                          // field holds no value, so the only row that can be chosen\n                          // is the one whose label the text already is.\n                          aria-selected={fillOnSelect && o.label === value}\n                          // Listed, announced as unavailable, never taken: `take`\n                          // refuses it and the arrows pass it over.\n                          aria-disabled={o.disabled || undefined}\n                          tabIndex={-1}\n                          onClick={() => take(o)}\n                          onMouseEnter={() => {\n                            if (!o.disabled) setActive(i);\n                          }}\n                          className={cn(\n                            // The family's suggestion row (DUP-4): it hand-rolled its\n                            // own with a plain `truncate`, so a long address was cut at\n                            // Large, where Combobox's rows wrap (text size §10.17, T1).\n                            // A flex row here, for the icon and the two lines.\n                            suggestionRowClass(i === active && !o.disabled),\n                            \"flex items-center gap-2\",\n                            small && \"py-1 text-xs\",\n                            o.disabled && DISABLED_ROW_CLASS,\n                            o.group != null && \"ps-6\",\n                          )}\n                        >\n                          {o.icon && (\n                            <span aria-hidden className=\"shrink-0 text-muted\">\n                              {o.icon}\n                            </span>\n                          )}\n                          <span className=\"min-w-0 flex-1\">\n                            <span className=\"block truncate-until-large text-primary\">\n                              {o.label}\n                            </span>\n                            {o.sublabel && (\n                              <span\n                                className={cn(\n                                  \"block truncate-until-large text-placeholder\",\n                                  small ? \"text-caption\" : \"text-xs\",\n                                )}\n                              >\n                                {o.sublabel}\n                              </span>\n                            )}\n                          </span>\n                        </button>\n                      </li>\n                    </Fragment>\n                  );\n                })}\n              </ul>\n            )}\n            {statusLine !== null && (\n              // Visible, not live — the region above speaks for it.\n              <div\n                aria-hidden\n                className={cn(\n                  small ? \"px-3 py-1.5 text-xs\" : \"px-3 py-2 text-sm\",\n                  failed && !hasStatus ? \"text-danger\" : \"text-muted\",\n                  results.length > 0 && \"border-t border-subtle text-xs\",\n                )}\n              >\n                {statusLine}\n              </div>\n            )}\n          </div>,\n          document.body,\n        )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/button-look.d.ts

@@ -58,7 +58,7 @@ export declare const buttonVariantClasses: Record<ButtonVariant, string>;
  * solid danger or brand button would be a second variant under another name.
  */
 export type ButtonTone = "default" | "muted" | "danger";
-export declare const BUTTON_LINK_PRESSED = "font-medium text-brand hover:text-brand disabled:hover:text-brand";
+export declare const BUTTON_LINK_PRESSED = "font-medium text-brand hover:text-brand disabled:hover:text-brand contrast:text-brand-muted contrast:hover:text-brand-muted contrast:disabled:hover:text-brand-muted";
 /** The second argument of {@link buttonClasses} in its options form. */
 export interface ButtonClassesOptions {
     /** See {@link ButtonProps.size}. */

package/dist/components/button-look.js

@@ -32,11 +32,16 @@ const buttonVariantClasses = {
   // the base's focus ring stays: those copies had `outline-none` and no ring, so
   // a keyboard user tabbing onto them saw nothing at all. `rounded-sm` keeps that
   // ring hugging the word instead of drawing a pill round it.
-  link: "rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand"
+  //
+  // Under More contrast the word reads `--brand-muted`, the brand AS TEXT (0.36,
+  // colour-roles §13.3 decision 8): `--brand` is solved as a mark (3:1), and on More
+  // contrast's darker light well Moss's read 3.68:1; the derived dark brands sit at 3.0
+  // as text too. Both modes, since `contrast:` does not split them.
+  link: "rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand contrast:text-brand-muted"
 };
 const BUTTON_TONES = {
-  muted: "text-secondary hover:text-primary disabled:hover:text-secondary",
-  danger: "text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary"
+  muted: "text-secondary hover:text-primary disabled:hover:text-secondary contrast:text-secondary",
+  danger: "text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary contrast:text-secondary"
 };
 const TONED_VARIANTS = /* @__PURE__ */ new Set(["link", "ghost"]);
 const BUTTON_BOXED_DANGER = {
@@ -47,7 +52,7 @@ const BUTTON_BOXED_DANGER = {
   secondary: "border-danger bg-transparent text-danger hover:bg-danger-soft focus-visible:ring-danger-strong",
   primary: "border-danger bg-danger-soft text-danger hover:border-[var(--danger)] hover:bg-danger hover:text-danger-contrast focus-visible:ring-danger-strong disabled:hover:border-danger disabled:hover:bg-danger-soft disabled:hover:text-danger"
 };
-const BUTTON_LINK_PRESSED = "font-medium text-brand hover:text-brand disabled:hover:text-brand";
+const BUTTON_LINK_PRESSED = "font-medium text-brand hover:text-brand disabled:hover:text-brand contrast:text-brand-muted contrast:hover:text-brand-muted contrast:disabled:hover:text-brand-muted";
 function buttonClasses(variant = "primary", classNameOrOptions) {
   const { size = "md", className } = typeof classNameOrOptions === "object" ? classNameOrOptions : { className: classNameOrOptions };
   return cn(

package/dist/components/button-look.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/button-look.ts"],"sourcesContent":["import { cn } from \"../lib/cn\";\nimport { FOCUS_RING_WIDTH } from \"./focus-ring\";\nimport type { KitLinkComponent, KitLinkProps } from \"../i18n/kit-labels\";\n\n/**\n * The button look, which {@link Button} and {@link IconButton} share (0.34, MOD-2, refactor\n * audit 2026-10). In ui.tsx it was the one knot in an otherwise one-way graph: Button drew\n * IconButton's pressed look, and IconButton drew Button's variant colours, its hover ink\n * and its router link. Both now draw from this module, which renders nothing, so neither\n * imports the other.\n *\n * Public through ./ui by name: `buttonClasses`, `TOUCH_TARGET_LARGE` and the four types.\n * The other exports are the two buttons' shared parts (`@internal`).\n */\n\nexport type ButtonVariant = \"primary\" | \"secondary\" | \"ghost\" | \"danger\" | \"brand\" | \"link\";\n\n// Shared base ring for every button-styled element. Kept as a named const so the\n// <Button> component and the {@link buttonClasses} helper draw from one source and\n// can never drift apart.\n//\n// The ring is the kit's focus frame (§5): {@link FOCUS_RING_WIDTH} wide, on keyboard focus\n// (`focus-visible`) — a tap or a click no longer leaves a ring on the button — in each\n// variant's own colour below.\n//\n// `[&_svg]:shrink-0` (0.32.2, kastlan's 0.32.1 report): an icon beside a label keeps its\n// size when the label wraps at Large. Without it the svg was a flex item like the text,\n// and a two-line label squeezed it to a sliver (\"New invoice\" in a page header at 360 px\n// / Extra large).\nconst BUTTON_BASE = cn(\n  \"inline-flex items-center justify-center rounded-md font-medium transition-colors focus:outline-none disabled:opacity-50 disabled:cursor-not-allowed [&_svg]:shrink-0\",\n  FOCUS_RING_WIDTH,\n);\n\n/**\n * The touch target at Large and Extra large (docs/text-size-harmonization.md §4): at\n * least 48 px, the size a finger needs whatever the type. In px on purpose, like the\n * field floor ({@link FIELD_TOUCH_TEXT}): it is a physical threshold, not a size that\n * follows the text. Normal keeps the kit's own heights; a `large:` variant, so it costs\n * no render and is right on the first paint.\n */\nexport const TOUCH_TARGET_LARGE = \"large:min-h-[48px] large:min-w-[48px]\";\n\nexport type ButtonSize = \"sm\" | \"md\";\n\n// Box geometry per size, split out of the base so the two cannot be merged into one\n// string that a size then has to fight. `md` is the pre-0.8.0 look, unchanged. `sm` is\n// the compact secondary action keksdose repeats by hand as `px-2 py-1 text-xs` (and\n// `px-2 py-0.5 text-xs`) on the buttons in a toolbar or a table header; one rung is\n// enough, so the two spellings meet at `py-1`. There is no `lg`: no app has asked for\n// a bigger text button (IconButton's `lg` is a touch target, not a text size). The\n// variant map comes AFTER the size, so `link`'s `p-0` still wins at either size.\n//\n// At Large and above (§4) `sm` grows to `md`'s height — the padding that makes its\n// 1rem line as tall as `md`'s 1.25rem one — and both reach the 48 px touch target. The\n// type stays `sm`'s: the compact button is still the quieter one. Not on `link`, which\n// is a word in a sentence and has no box to grow (see `buttonLook`).\nconst BUTTON_SIZES: Record<ButtonSize, string> = {\n  md: \"gap-2 px-3 py-2 text-sm\",\n  sm: \"gap-1.5 px-2 py-1 text-xs\",\n};\nconst BUTTON_SIZES_LARGE: Record<ButtonSize, string> = {\n  md: \"large:min-h-[48px]\",\n  sm: \"large:min-h-[48px] large:py-2.5\",\n};\n\n/**\n * The hover of a control that may sit on the page, a card or a well (0.33, B′ —\n * docs/colour-roles-harmonization.md §12.1, §12.10): the body ink at 7 %, TRANSLUCENT,\n * so it darkens (in dark, lightens) whatever is under it by the same step — 1.11:1 or\n * more on all three surfaces, both themes, with the label at 7:1 and up. It was\n * `--bg-surface-2`, which since 0.33 is the page itself in light: a ghost button on the\n * page would not have moved at all. Not `--bg-hover` either, which is mixed against the\n * CARD and stands only 1.04:1 from the page. IconButton's `custom` tone uses the same\n * recipe at 12 %.\n */\nexport const HOVER_INK = \"hover:bg-[color-mix(in_srgb,var(--text-primary)_7%,transparent)]\";\n\n// Warm, palette-token-driven so buttons blend with the fields + cards in every theme.\n// Actions default to a warm bordered look (primary = filled warm chip, secondary =\n// outline); `brand` stays the solid accent for the rare strong CTA; `danger` takes the\n// semantic `--danger` family (destructive semantics), so a consumer can re-point the\n// destructive hue instead of inheriting a hard-coded red. Focus rings follow each\n// variant's own accent: brand for the four neutral ones, danger for `danger`.\nexport const buttonVariantClasses: Record<ButtonVariant, string> = {\n  primary:\n    // Hovers onto `--bg-active`, not `--border` (0.33, §12.9): More contrast steps the\n    // border until it is a 3:1 LINE, and as a fill under the label that left 2.7:1.\n    \"border border-subtle bg-surface-2 text-primary hover:bg-active focus-visible:ring-brand\",\n  secondary: `border border-subtle bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,\n  ghost: `bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,\n  danger:\n    \"bg-danger text-danger-contrast hover:bg-danger-hover focus-visible:ring-danger-strong\",\n  brand:\n    \"bg-brand text-brand-contrast hover:bg-brand-hover focus-visible:ring-brand\",\n  // A text link that is still a `<button>` — keksdose's six hand-rolled\n  // `<button className=\"text-brand underline\">` sites (\"Resend code\", \"Show all\",\n  // \"Undo\" in a toast…), which act rather than navigate and so must not be anchors.\n  // The box padding goes (`p-0`) so it sits in a sentence at the text's own size, but\n  // the base's focus ring stays: those copies had `outline-none` and no ring, so\n  // a keyboard user tabbing onto them saw nothing at all. `rounded-sm` keeps that\n  // ring hugging the word instead of drawing a pill round it.\n  link:\n    \"rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand\",\n};\n\n/**\n * The text colour of a `link` or `ghost` button, over the variant's own.\n *\n * `muted` is the QUIET link keksdose hand-rolls in six places (tours-page:321's \"Mark\n * undone\", transaction-fields:176/215's \"Add line\" / \"Fill total\",\n * invoice-lines-table:376, invoice-review:464): secondary text that darkens to the\n * body colour under the pointer, for an action that must be findable but not compete\n * with the brand-coloured one beside it. `danger` is the same quiet look turning\n * `--danger` on hover — transaction-editor:401's \"Remove split\", which is a text\n * action that destroys something.\n *\n * A `tone` rather than a `link-muted` variant, because it is the axis IconButton\n * already has (`tone=\"muted\"`, `tone=\"danger\"`, same quiet-until-hover meaning), and\n * because the same two looks are wanted on `ghost`.\n *\n * `danger` also reaches the two NEUTRAL boxed variants, where the box carries it:\n * `secondary` becomes an outlined destructive button (`--danger` text and a\n * `--danger-border` outline, the quiet danger fill on hover) and `primary` a soft one\n * (the quiet fill at rest, solid `--danger` on hover). kastlan's meeting-invitations-\n * tab.tsx \"Remove all\" is `variant=\"secondary\" className=\"text-destructive\"` — a\n * destructive action that must sit in a row of secondary buttons without shouting\n * like the solid `variant=\"danger\"` would, and whose red text alone left the border\n * and hover saying \"neutral\". `muted` stays a text look and does nothing on a box, and\n * `danger`, `brand` and `link`'s own colours are left alone: a tone that recoloured a\n * solid danger or brand button would be a second variant under another name.\n */\nexport type ButtonTone = \"default\" | \"muted\" | \"danger\";\n\nconst BUTTON_TONES: Record<Exclude<ButtonTone, \"default\">, string> = {\n  muted:\n    \"text-secondary hover:text-primary disabled:hover:text-secondary\",\n  danger:\n    \"text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary\",\n};\n\n/** Only the two transparent variants take every tone; see {@link ButtonTone}. */\nconst TONED_VARIANTS = new Set<ButtonVariant>([\"link\", \"ghost\"]);\n\n// `tone=\"danger\"` on the neutral boxed variants — see {@link ButtonTone}. Each string\n// restates every colour the variant sets (border, fill, text, hover, ring) so none of\n// the neutral ones survives the merge.\nconst BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {\n  // Not boxed, but its hover is a fill: the danger wash under the danger text, as\n  // IconButton's danger tone (0.33). On B′'s translucent ink `--danger` fell to 4.2:1\n  // over a light page.\n  ghost: \"hover:bg-danger-soft\",\n  secondary:\n    \"border-danger bg-transparent text-danger hover:bg-danger-soft focus-visible:ring-danger-strong\",\n  primary:\n    \"border-danger bg-danger-soft text-danger hover:border-[var(--danger)] hover:bg-danger hover:text-danger-contrast focus-visible:ring-danger-strong disabled:hover:border-danger disabled:hover:bg-danger-soft disabled:hover:text-danger\",\n};\n\n// `pressed` on a `link`: the brand colour and a heavier weight, which is exactly what\n// lenkbank's \"All speeds\" toggle paints by hand (gear/hysteresis-charts.tsx:482). After\n// the tone, so a pressed muted link is brand, and an unpressed one is quiet grey.\nexport const BUTTON_LINK_PRESSED =\n  \"font-medium text-brand hover:text-brand disabled:hover:text-brand\";\n\n/** The second argument of {@link buttonClasses} in its options form. */\nexport interface ButtonClassesOptions {\n  /** See {@link ButtonProps.size}. */\n  size?: ButtonSize;\n  className?: string;\n}\n\n/**\n * Button classes for the rare case where the styling must land on a non-`<button>`\n * element that {@link Button} can't render — e.g. a router `<Link>` or a Radix\n * AlertDialog Action/Cancel (which must stay the Radix element). Everywhere a real\n * button works, prefer `<Button>`. Draws from the same base, size and variant maps as\n * `<Button>`, so the two stay in lockstep.\n *\n * The second argument is either the extra classes (the pre-0.8.0 form) or\n * `{ size, className }` — `buttonClasses(\"secondary\", { size: \"sm\" })` for keksdose's\n * compact toolbar links.\n */\nexport function buttonClasses(\n  variant: ButtonVariant = \"primary\",\n  classNameOrOptions?: string | ButtonClassesOptions,\n): string {\n  const { size = \"md\", className } =\n    typeof classNameOrOptions === \"object\" ? classNameOrOptions : { className: classNameOrOptions };\n  return cn(\n    BUTTON_BASE,\n    BUTTON_SIZES[size],\n    variant !== \"link\" && BUTTON_SIZES_LARGE[size],\n    buttonVariantClasses[variant],\n    className,\n  );\n}\n\n// `pressed`: a toggle that is on. The brand glyph on the quiet brand fill — the\n// \"selected\" look of a Chip or a SegmentedControl option, so an on toggle reads as on\n// beside them. After the tone, so a pressed `muted` button is brand, not grey. On hover\n// the glyph turns brand-muted: `--brand` on `--brand-bg-hover` is 2.69–2.80 in four dark\n// presets, under an icon's 3:1 (colour-roles §12.12). Button's `pressed` draws it on its\n// boxed variants too, which is why it lives here and not in ./icon-button.\nexport const ICON_BUTTON_PRESSED =\n  \"bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted disabled:hover:bg-brand-soft disabled:hover:text-brand\";\n\n/** @internal The button look shared by the `<button>` and the `<a>` form. */\nexport function buttonLook(variant: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {\n  return cn(\n    BUTTON_BASE,\n    BUTTON_SIZES[size],\n    // §4: `sm` at `md`'s height and the 48 px target at Large — not on a `link`. In the\n    // order `buttonClasses` has it, so the two strings stay identical.\n    variant !== \"link\" && BUTTON_SIZES_LARGE[size],\n    // In a flex row next to a taller labelled field, `stretch` makes the button\n    // fill the field's height so the two line up (self-stretch overrides the row's\n    // align-items). No effect outside a flex row / when it's already the tallest.\n    stretch && \"self-stretch\",\n    buttonVariantClasses[variant],\n    tone !== \"default\" && TONED_VARIANTS.has(variant) && BUTTON_TONES[tone],\n    tone === \"danger\" && BUTTON_BOXED_DANGER[variant],\n  );\n}\n\n/** @internal Calls a `renderLink` / provider link as a function, as ListItem and Chip\n *  do — an inline `renderLink` arrow would otherwise be a new component type every\n *  render. Both buttons' link forms render through it. */\nexport function RenderedButtonLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {\n  return render(props);\n}\n"],"mappings":";AAAA,SAAS,UAAU;AACnB,SAAS,wBAAwB;AA4BjC,MAAM,cAAc;AAAA,EAClB;AAAA,EACA;AACF;AASO,MAAM,qBAAqB;AAgBlC,MAAM,eAA2C;AAAA,EAC/C,IAAI;AAAA,EACJ,IAAI;AACN;AACA,MAAM,qBAAiD;AAAA,EACrD,IAAI;AAAA,EACJ,IAAI;AACN;AAYO,MAAM,YAAY;AAQlB,MAAM,uBAAsD;AAAA,EACjE;AAAA;AAAA;AAAA,IAGE;AAAA;AAAA,EACF,WAAW,oDAAoD,SAAS;AAAA,EACxE,OAAO,+BAA+B,SAAS;AAAA,EAC/C,QACE;AAAA,EACF,OACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQF,MACE;AACJ;AA8BA,MAAM,eAA+D;AAAA,EACnE,OACE;AAAA,EACF,QACE;AACJ;AAGA,MAAM,iBAAiB,oBAAI,IAAmB,CAAC,QAAQ,OAAO,CAAC;AAK/D,MAAM,sBAA8D;AAAA;AAAA;AAAA;AAAA,EAIlE,OAAO;AAAA,EACP,WACE;AAAA,EACF,SACE;AACJ;AAKO,MAAM,sBACX;AAoBK,SAAS,cACd,UAAyB,WACzB,oBACQ;AACR,QAAM,EAAE,OAAO,MAAM,UAAU,IAC7B,OAAO,uBAAuB,WAAW,qBAAqB,EAAE,WAAW,mBAAmB;AAChG,SAAO;AAAA,IACL;AAAA,IACA,aAAa,IAAI;AAAA,IACjB,YAAY,UAAU,mBAAmB,IAAI;AAAA,IAC7C,qBAAqB,OAAO;AAAA,IAC5B;AAAA,EACF;AACF;AAQO,MAAM,sBACX;AAGK,SAAS,WAAW,SAAwB,MAAkB,SAA8B,MAAkB;AACnH,SAAO;AAAA,IACL;AAAA,IACA,aAAa,IAAI;AAAA;AAAA;AAAA,IAGjB,YAAY,UAAU,mBAAmB,IAAI;AAAA;AAAA;AAAA;AAAA,IAI7C,WAAW;AAAA,IACX,qBAAqB,OAAO;AAAA,IAC5B,SAAS,aAAa,eAAe,IAAI,OAAO,KAAK,aAAa,IAAI;AAAA,IACtE,SAAS,YAAY,oBAAoB,OAAO;AAAA,EAClD;AACF;AAKO,SAAS,mBAAmB,EAAE,QAAQ,GAAG,MAAM,GAAgD;AACpG,SAAO,OAAO,KAAK;AACrB;","names":[]}
+{"version":3,"sources":["../../src/components/button-look.ts"],"sourcesContent":["import { cn } from \"../lib/cn\";\nimport { FOCUS_RING_WIDTH } from \"./focus-ring\";\nimport type { KitLinkComponent, KitLinkProps } from \"../i18n/kit-labels\";\n\n/**\n * The button look, which {@link Button} and {@link IconButton} share (0.34, MOD-2, refactor\n * audit 2026-10). In ui.tsx it was the one knot in an otherwise one-way graph: Button drew\n * IconButton's pressed look, and IconButton drew Button's variant colours, its hover ink\n * and its router link. Both now draw from this module, which renders nothing, so neither\n * imports the other.\n *\n * Public through ./ui by name: `buttonClasses`, `TOUCH_TARGET_LARGE` and the four types.\n * The other exports are the two buttons' shared parts (`@internal`).\n */\n\nexport type ButtonVariant = \"primary\" | \"secondary\" | \"ghost\" | \"danger\" | \"brand\" | \"link\";\n\n// Shared base ring for every button-styled element. Kept as a named const so the\n// <Button> component and the {@link buttonClasses} helper draw from one source and\n// can never drift apart.\n//\n// The ring is the kit's focus frame (§5): {@link FOCUS_RING_WIDTH} wide, on keyboard focus\n// (`focus-visible`) — a tap or a click no longer leaves a ring on the button — in each\n// variant's own colour below.\n//\n// `[&_svg]:shrink-0` (0.32.2, kastlan's 0.32.1 report): an icon beside a label keeps its\n// size when the label wraps at Large. Without it the svg was a flex item like the text,\n// and a two-line label squeezed it to a sliver (\"New invoice\" in a page header at 360 px\n// / Extra large).\nconst BUTTON_BASE = cn(\n  \"inline-flex items-center justify-center rounded-md font-medium transition-colors focus:outline-none disabled:opacity-50 disabled:cursor-not-allowed [&_svg]:shrink-0\",\n  FOCUS_RING_WIDTH,\n);\n\n/**\n * The touch target at Large and Extra large (docs/text-size-harmonization.md §4): at\n * least 48 px, the size a finger needs whatever the type. In px on purpose, like the\n * field floor ({@link FIELD_TOUCH_TEXT}): it is a physical threshold, not a size that\n * follows the text. Normal keeps the kit's own heights; a `large:` variant, so it costs\n * no render and is right on the first paint.\n */\nexport const TOUCH_TARGET_LARGE = \"large:min-h-[48px] large:min-w-[48px]\";\n\nexport type ButtonSize = \"sm\" | \"md\";\n\n// Box geometry per size, split out of the base so the two cannot be merged into one\n// string that a size then has to fight. `md` is the pre-0.8.0 look, unchanged. `sm` is\n// the compact secondary action keksdose repeats by hand as `px-2 py-1 text-xs` (and\n// `px-2 py-0.5 text-xs`) on the buttons in a toolbar or a table header; one rung is\n// enough, so the two spellings meet at `py-1`. There is no `lg`: no app has asked for\n// a bigger text button (IconButton's `lg` is a touch target, not a text size). The\n// variant map comes AFTER the size, so `link`'s `p-0` still wins at either size.\n//\n// At Large and above (§4) `sm` grows to `md`'s height — the padding that makes its\n// 1rem line as tall as `md`'s 1.25rem one — and both reach the 48 px touch target. The\n// type stays `sm`'s: the compact button is still the quieter one. Not on `link`, which\n// is a word in a sentence and has no box to grow (see `buttonLook`).\nconst BUTTON_SIZES: Record<ButtonSize, string> = {\n  md: \"gap-2 px-3 py-2 text-sm\",\n  sm: \"gap-1.5 px-2 py-1 text-xs\",\n};\nconst BUTTON_SIZES_LARGE: Record<ButtonSize, string> = {\n  md: \"large:min-h-[48px]\",\n  sm: \"large:min-h-[48px] large:py-2.5\",\n};\n\n/**\n * The hover of a control that may sit on the page, a card or a well (0.33, B′ —\n * docs/colour-roles-harmonization.md §12.1, §12.10): the body ink at 7 %, TRANSLUCENT,\n * so it darkens (in dark, lightens) whatever is under it by the same step — 1.11:1 or\n * more on all three surfaces, both themes, with the label at 7:1 and up. It was\n * `--bg-surface-2`, which since 0.33 is the page itself in light: a ghost button on the\n * page would not have moved at all. Not `--bg-hover` either, which is mixed against the\n * CARD and stands only 1.04:1 from the page. IconButton's `custom` tone uses the same\n * recipe at 12 %.\n */\nexport const HOVER_INK = \"hover:bg-[color-mix(in_srgb,var(--text-primary)_7%,transparent)]\";\n\n// Warm, palette-token-driven so buttons blend with the fields + cards in every theme.\n// Actions default to a warm bordered look (primary = filled warm chip, secondary =\n// outline); `brand` stays the solid accent for the rare strong CTA; `danger` takes the\n// semantic `--danger` family (destructive semantics), so a consumer can re-point the\n// destructive hue instead of inheriting a hard-coded red. Focus rings follow each\n// variant's own accent: brand for the four neutral ones, danger for `danger`.\nexport const buttonVariantClasses: Record<ButtonVariant, string> = {\n  primary:\n    // Hovers onto `--bg-active`, not `--border` (0.33, §12.9): More contrast steps the\n    // border until it is a 3:1 LINE, and as a fill under the label that left 2.7:1.\n    \"border border-subtle bg-surface-2 text-primary hover:bg-active focus-visible:ring-brand\",\n  secondary: `border border-subtle bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,\n  ghost: `bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,\n  danger:\n    \"bg-danger text-danger-contrast hover:bg-danger-hover focus-visible:ring-danger-strong\",\n  brand:\n    \"bg-brand text-brand-contrast hover:bg-brand-hover focus-visible:ring-brand\",\n  // A text link that is still a `<button>` — keksdose's six hand-rolled\n  // `<button className=\"text-brand underline\">` sites (\"Resend code\", \"Show all\",\n  // \"Undo\" in a toast…), which act rather than navigate and so must not be anchors.\n  // The box padding goes (`p-0`) so it sits in a sentence at the text's own size, but\n  // the base's focus ring stays: those copies had `outline-none` and no ring, so\n  // a keyboard user tabbing onto them saw nothing at all. `rounded-sm` keeps that\n  // ring hugging the word instead of drawing a pill round it.\n  //\n  // Under More contrast the word reads `--brand-muted`, the brand AS TEXT (0.36,\n  // colour-roles §13.3 decision 8): `--brand` is solved as a mark (3:1), and on More\n  // contrast's darker light well Moss's read 3.68:1; the derived dark brands sit at 3.0\n  // as text too. Both modes, since `contrast:` does not split them.\n  link:\n    \"rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-brand contrast:text-brand-muted\",\n};\n\n/**\n * The text colour of a `link` or `ghost` button, over the variant's own.\n *\n * `muted` is the QUIET link keksdose hand-rolls in six places (tours-page:321's \"Mark\n * undone\", transaction-fields:176/215's \"Add line\" / \"Fill total\",\n * invoice-lines-table:376, invoice-review:464): secondary text that darkens to the\n * body colour under the pointer, for an action that must be findable but not compete\n * with the brand-coloured one beside it. `danger` is the same quiet look turning\n * `--danger` on hover — transaction-editor:401's \"Remove split\", which is a text\n * action that destroys something.\n *\n * A `tone` rather than a `link-muted` variant, because it is the axis IconButton\n * already has (`tone=\"muted\"`, `tone=\"danger\"`, same quiet-until-hover meaning), and\n * because the same two looks are wanted on `ghost`.\n *\n * `danger` also reaches the two NEUTRAL boxed variants, where the box carries it:\n * `secondary` becomes an outlined destructive button (`--danger` text and a\n * `--danger-border` outline, the quiet danger fill on hover) and `primary` a soft one\n * (the quiet fill at rest, solid `--danger` on hover). kastlan's meeting-invitations-\n * tab.tsx \"Remove all\" is `variant=\"secondary\" className=\"text-destructive\"` — a\n * destructive action that must sit in a row of secondary buttons without shouting\n * like the solid `variant=\"danger\"` would, and whose red text alone left the border\n * and hover saying \"neutral\". `muted` stays a text look and does nothing on a box, and\n * `danger`, `brand` and `link`'s own colours are left alone: a tone that recoloured a\n * solid danger or brand button would be a second variant under another name.\n */\nexport type ButtonTone = \"default\" | \"muted\" | \"danger\";\n\n// `contrast:text-secondary` restates the tone's own colour under the `contrast:` variant,\n// so tailwind-merge drops the link's `contrast:text-brand-muted` (0.36): a quiet link\n// stays quiet under More contrast. On `ghost` it reads the same either way.\nconst BUTTON_TONES: Record<Exclude<ButtonTone, \"default\">, string> = {\n  muted:\n    \"text-secondary hover:text-primary disabled:hover:text-secondary contrast:text-secondary\",\n  danger:\n    \"text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary contrast:text-secondary\",\n};\n\n/** Only the two transparent variants take every tone; see {@link ButtonTone}. */\nconst TONED_VARIANTS = new Set<ButtonVariant>([\"link\", \"ghost\"]);\n\n// `tone=\"danger\"` on the neutral boxed variants — see {@link ButtonTone}. Each string\n// restates every colour the variant sets (border, fill, text, hover, ring) so none of\n// the neutral ones survives the merge.\nconst BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {\n  // Not boxed, but its hover is a fill: the danger wash under the danger text, as\n  // IconButton's danger tone (0.33). On B′'s translucent ink `--danger` fell to 4.2:1\n  // over a light page.\n  ghost: \"hover:bg-danger-soft\",\n  secondary:\n    \"border-danger bg-transparent text-danger hover:bg-danger-soft focus-visible:ring-danger-strong\",\n  primary:\n    \"border-danger bg-danger-soft text-danger hover:border-[var(--danger)] hover:bg-danger hover:text-danger-contrast focus-visible:ring-danger-strong disabled:hover:border-danger disabled:hover:bg-danger-soft disabled:hover:text-danger\",\n};\n\n// `pressed` on a `link`: the brand colour and a heavier weight, which is exactly what\n// lenkbank's \"All speeds\" toggle paints by hand (gear/hysteresis-charts.tsx:482). After\n// the tone, so a pressed muted link is brand, and an unpressed one is quiet grey. Under\n// More contrast the brand as text, `--brand-muted`, at rest and hovered (0.36, as the\n// `link` variant), whatever the tone.\nexport const BUTTON_LINK_PRESSED =\n  \"font-medium text-brand hover:text-brand disabled:hover:text-brand contrast:text-brand-muted contrast:hover:text-brand-muted contrast:disabled:hover:text-brand-muted\";\n\n/** The second argument of {@link buttonClasses} in its options form. */\nexport interface ButtonClassesOptions {\n  /** See {@link ButtonProps.size}. */\n  size?: ButtonSize;\n  className?: string;\n}\n\n/**\n * Button classes for the rare case where the styling must land on a non-`<button>`\n * element that {@link Button} can't render — e.g. a router `<Link>` or a Radix\n * AlertDialog Action/Cancel (which must stay the Radix element). Everywhere a real\n * button works, prefer `<Button>`. Draws from the same base, size and variant maps as\n * `<Button>`, so the two stay in lockstep.\n *\n * The second argument is either the extra classes (the pre-0.8.0 form) or\n * `{ size, className }` — `buttonClasses(\"secondary\", { size: \"sm\" })` for keksdose's\n * compact toolbar links.\n */\nexport function buttonClasses(\n  variant: ButtonVariant = \"primary\",\n  classNameOrOptions?: string | ButtonClassesOptions,\n): string {\n  const { size = \"md\", className } =\n    typeof classNameOrOptions === \"object\" ? classNameOrOptions : { className: classNameOrOptions };\n  return cn(\n    BUTTON_BASE,\n    BUTTON_SIZES[size],\n    variant !== \"link\" && BUTTON_SIZES_LARGE[size],\n    buttonVariantClasses[variant],\n    className,\n  );\n}\n\n// `pressed`: a toggle that is on. The brand glyph on the quiet brand fill — the\n// \"selected\" look of a Chip or a SegmentedControl option, so an on toggle reads as on\n// beside them. After the tone, so a pressed `muted` button is brand, not grey. On hover\n// the glyph turns brand-muted: `--brand` on `--brand-bg-hover` is 2.69–2.80 in four dark\n// presets, under an icon's 3:1 (colour-roles §12.12). Button's `pressed` draws it on its\n// boxed variants too, which is why it lives here and not in ./icon-button.\nexport const ICON_BUTTON_PRESSED =\n  \"bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted disabled:hover:bg-brand-soft disabled:hover:text-brand\";\n\n/** @internal The button look shared by the `<button>` and the `<a>` form. */\nexport function buttonLook(variant: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {\n  return cn(\n    BUTTON_BASE,\n    BUTTON_SIZES[size],\n    // §4: `sm` at `md`'s height and the 48 px target at Large — not on a `link`. In the\n    // order `buttonClasses` has it, so the two strings stay identical.\n    variant !== \"link\" && BUTTON_SIZES_LARGE[size],\n    // In a flex row next to a taller labelled field, `stretch` makes the button\n    // fill the field's height so the two line up (self-stretch overrides the row's\n    // align-items). No effect outside a flex row / when it's already the tallest.\n    stretch && \"self-stretch\",\n    buttonVariantClasses[variant],\n    tone !== \"default\" && TONED_VARIANTS.has(variant) && BUTTON_TONES[tone],\n    tone === \"danger\" && BUTTON_BOXED_DANGER[variant],\n  );\n}\n\n/** @internal Calls a `renderLink` / provider link as a function, as ListItem and Chip\n *  do — an inline `renderLink` arrow would otherwise be a new component type every\n *  render. Both buttons' link forms render through it. */\nexport function RenderedButtonLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {\n  return render(props);\n}\n"],"mappings":";AAAA,SAAS,UAAU;AACnB,SAAS,wBAAwB;AA4BjC,MAAM,cAAc;AAAA,EAClB;AAAA,EACA;AACF;AASO,MAAM,qBAAqB;AAgBlC,MAAM,eAA2C;AAAA,EAC/C,IAAI;AAAA,EACJ,IAAI;AACN;AACA,MAAM,qBAAiD;AAAA,EACrD,IAAI;AAAA,EACJ,IAAI;AACN;AAYO,MAAM,YAAY;AAQlB,MAAM,uBAAsD;AAAA,EACjE;AAAA;AAAA;AAAA,IAGE;AAAA;AAAA,EACF,WAAW,oDAAoD,SAAS;AAAA,EACxE,OAAO,+BAA+B,SAAS;AAAA,EAC/C,QACE;AAAA,EACF,OACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaF,MACE;AACJ;AAiCA,MAAM,eAA+D;AAAA,EACnE,OACE;AAAA,EACF,QACE;AACJ;AAGA,MAAM,iBAAiB,oBAAI,IAAmB,CAAC,QAAQ,OAAO,CAAC;AAK/D,MAAM,sBAA8D;AAAA;AAAA;AAAA;AAAA,EAIlE,OAAO;AAAA,EACP,WACE;AAAA,EACF,SACE;AACJ;AAOO,MAAM,sBACX;AAoBK,SAAS,cACd,UAAyB,WACzB,oBACQ;AACR,QAAM,EAAE,OAAO,MAAM,UAAU,IAC7B,OAAO,uBAAuB,WAAW,qBAAqB,EAAE,WAAW,mBAAmB;AAChG,SAAO;AAAA,IACL;AAAA,IACA,aAAa,IAAI;AAAA,IACjB,YAAY,UAAU,mBAAmB,IAAI;AAAA,IAC7C,qBAAqB,OAAO;AAAA,IAC5B;AAAA,EACF;AACF;AAQO,MAAM,sBACX;AAGK,SAAS,WAAW,SAAwB,MAAkB,SAA8B,MAAkB;AACnH,SAAO;AAAA,IACL;AAAA,IACA,aAAa,IAAI;AAAA;AAAA;AAAA,IAGjB,YAAY,UAAU,mBAAmB,IAAI;AAAA;AAAA;AAAA;AAAA,IAI7C,WAAW;AAAA,IACX,qBAAqB,OAAO;AAAA,IAC5B,SAAS,aAAa,eAAe,IAAI,OAAO,KAAK,aAAa,IAAI;AAAA,IACtE,SAAS,YAAY,oBAAoB,OAAO;AAAA,EAClD;AACF;AAKO,SAAS,mBAAmB,EAAE,QAAQ,GAAG,MAAM,GAAgD;AACpG,SAAO,OAAO,KAAK;AACrB;","names":[]}

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { type CommitScope } from "./write-lock.js";
+import { type FieldHelpProps } from "./field-parts.js";
 /** One box of a {@link CheckboxGroup}. */
 export interface CheckboxGroupOption<T extends string = string> {
     value: T;
@@ -14,7 +15,7 @@ export interface CheckboxGroupOption<T extends string = string> {
 /** 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> {
+export interface CheckboxGroupProps<T extends string = string> extends FieldHelpProps {
     /** The question the boxes answer — the fieldset's `<legend>`, which names the group.
      *  Without one, pass `aria-label`. */
     legend?: ReactNode;
@@ -56,6 +57,8 @@ export interface CheckboxGroupProps<T extends string = string> {
     /**
      * 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.
+     * A `help` beside it (0.36) is a "?" after the legend — with a visible legend only —
+     * and names nothing: the fieldset is then named by the legend's words alone.
      */
     hint?: ReactNode;
     /** What is wrong with the set, in the caller's words. Under the boxes, on the
@@ -98,4 +101,4 @@ export interface CheckboxGroupProps<T extends string = string> {
  * error describe the fieldset. For a choice of ONE, use radios ({@link ChoiceCardGroup},
  * {@link ToggleGroup}).
  */
-export 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>): import("react").JSX.Element;
+export declare function CheckboxGroup<T extends string = string>({ legend, legendVisibility, "aria-label": ariaLabel, options, value, onChange, layout, columns, name, disabled, required, hint, help, error, invalid, commit, disabledReason, id, className, listClassName, "aria-describedby": ariaDescribedBy, }: CheckboxGroupProps<T>): import("react").JSX.Element;

package/dist/components/checkbox-group.js

@@ -5,7 +5,13 @@ import { cn } from "../lib/cn.js";
 import { Checkbox } from "./checkbox.js";
 import { hasContent } from "../lib/presence.js";
 import { useCommitReason } from "./write-lock.js";
-import { FIELD_ERROR_CLASS, mergeDescribedBy, RequiredStarOnLegend, useInlineHint } from "./field-parts.js";
+import {
+  FIELD_ERROR_CLASS,
+  fieldHelpMark,
+  mergeDescribedBy,
+  RequiredStarOnLegend,
+  useInlineHint
+} from "./field-parts.js";
 const COLUMNS = {
   1: "flex flex-col gap-2",
   2: "grid grid-cols-1 gap-2 sm:grid-cols-2",
@@ -25,6 +31,7 @@ function CheckboxGroup({
   disabled,
   required,
   hint,
+  help,
   error,
   invalid,
   commit,
@@ -37,7 +44,9 @@ function CheckboxGroup({
   const generated = useId();
   const hintId = `${generated}-hint`;
   const errorId = `${generated}-error`;
-  const shownHint = useInlineHint(hint);
+  const helpMark = fieldHelpMark(legend !== void 0 && legendVisibility === "visible" ? help : void 0, legend);
+  const legendTextId = `${generated}-legend`;
+  const shownHint = useInlineHint(hint, helpMark !== void 0);
   const showHint = hasContent(shownHint);
   const showError = hasContent(error);
   const isInvalid = Boolean(invalid) || showError;
@@ -60,6 +69,7 @@ function CheckboxGroup({
     {
       id,
       "aria-label": ariaLabel,
+      "aria-labelledby": helpMark !== void 0 && ariaLabel === void 0 ? legendTextId : void 0,
       "aria-describedby": mergeDescribedBy(ariaDescribedBy, showHint && hintId, showError && errorId),
       disabled: disabled && !locked,
       className: cn("relative m-0 min-w-0 border-0 p-0", className),
@@ -69,8 +79,9 @@ function CheckboxGroup({
           {
             className: legendVisibility === "sr-only" ? "sr-only" : cn("mb-2 p-0 text-sm font-medium text-primary", (disabled || locked) && "opacity-60"),
             children: [
-              legend,
-              required && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "ms-0.5 text-danger", children: "*" })
+              helpMark === void 0 ? legend : /* @__PURE__ */ jsx("span", { id: legendTextId, children: legend }),
+              required && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "ms-0.5 text-danger", children: "*" }),
+              helpMark !== void 0 && /* @__PURE__ */ jsx("span", { className: "ms-1 inline-flex align-middle font-normal", children: helpMark })
             ]
           }
         ),

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

@@ -1 +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 { hasContent } from \"../lib/presence\";\nimport { useCommitReason, type CommitScope } from \"./write-lock\";\nimport { FIELD_ERROR_CLASS, mergeDescribedBy, RequiredStarOnLegend, useInlineHint } 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?: CommitScope;\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  // §4: a FieldHint under the group is its words at Large and on a touch screen, not a\n  // lone \"?\" (DUP-2, refactor audit 2026-10). A HelpPopover stays a \"?\".\n  const shownHint = useInlineHint(hint);\n  const showHint = hasContent(shownHint);\n  const showError = hasContent(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 = hasContent(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-primary\", (disabled || locked) && \"opacity-60\")\n          }\n        >\n          {legend}\n          {required && (\n            <span aria-hidden className=\"ms-0.5 text-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-caption leading-tight text-muted\">\n          {shownHint}\n        </div>\n      )}\n      {showError && (\n        <p id={errorId} className={FIELD_ERROR_CLASS}>\n          {error}\n        </p>\n      )}\n    </fieldset>\n  );\n}\n"],"mappings":"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","names":[]}
+{"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 { hasContent } from \"../lib/presence\";\nimport { useCommitReason, type CommitScope } from \"./write-lock\";\nimport {\n  FIELD_ERROR_CLASS,\n  fieldHelpMark,\n  mergeDescribedBy,\n  RequiredStarOnLegend,\n  useInlineHint,\n  type FieldHelpProps,\n} 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> extends FieldHelpProps {\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   * A `help` beside it (0.36) is a \"?\" after the legend — with a visible legend only —\n   * and names nothing: the fieldset is then named by the legend's words alone.\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?: CommitScope;\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  help,\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  // §4: a FieldHint under the group is its words at Large and on a touch screen, not a\n  // lone \"?\" (DUP-2, refactor audit 2026-10). A HelpPopover stays a \"?\".\n  // A `help` \"?\" after a VISIBLE legend (0.36): the label line a group has. Its FieldHint\n  // hint is then its words at every size, as everywhere a help stands beside one.\n  const helpMark = fieldHelpMark(legend !== undefined && legendVisibility === \"visible\" ? help : undefined, legend);\n  const legendTextId = `${generated}-legend`;\n  const shownHint = useInlineHint(hint, helpMark !== undefined);\n  const showHint = hasContent(shownHint);\n  const showError = hasContent(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 = hasContent(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      // With a help \"?\" inside the legend, the legend's WORDS name the group: a legend\n      // names its fieldset by its whole content, the \"?\"'s \"About …\" included.\n      aria-labelledby={helpMark !== undefined && ariaLabel === undefined ? legendTextId : undefined}\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-primary\", (disabled || locked) && \"opacity-60\")\n          }\n        >\n          {helpMark === undefined ? legend : <span id={legendTextId}>{legend}</span>}\n          {required && (\n            <span aria-hidden className=\"ms-0.5 text-danger\">\n              *\n            </span>\n          )}\n          {helpMark !== undefined && <span className=\"ms-1 inline-flex align-middle font-normal\">{helpMark}</span>}\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-caption leading-tight text-muted\">\n          {shownHint}\n        </div>\n      )}\n      {showError && (\n        <p id={errorId} className={FIELD_ERROR_CLASS}>\n          {error}\n        </p>\n      )}\n    </fieldset>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/column-mapper.d.ts

@@ -2,6 +2,7 @@ import type { HTMLAttributes, ReactNode } from "react";
 import { type LabelOverride } from "../i18n/kit-labels.js";
 import type { ColumnMapperResult, ColumnMapping, ColumnRole } from "../lib/column-mapping.js";
 import type { TextTable } from "../lib/table-text.js";
+import type { FieldHelpProps } from "./field-parts.js";
 import { DEFAULT_COLUMN_MAPPER_LABELS } from "./column-mapper-labels.js";
 /**
  * A table pasted, dropped or chosen as a file, and which of its columns plays which
@@ -189,7 +190,7 @@ export interface ColumnRoleTableProps<R extends string, M extends ColumnMapping<
  * wrapper says which ends are cut in `data-overflow`.
  */
 export declare function ColumnRoleTable<R extends string, M extends ColumnMapping<R> = ColumnMapping<R>>({ header, rows, width: widthProp, roles, mapping, onMappingChange, previewRows, totalRows, disabled, bodyProps, rowProps, labels: labelsProp, className, }: ColumnRoleTableProps<R, M>): import("react").JSX.Element;
-export interface ColumnMapperProps<R extends string> {
+export interface ColumnMapperProps<R extends string> extends FieldHelpProps {
     /** The parts the columns play — translated labels, which are required, which must
      *  be numbers. See {@link ColumnRole}. */
     roles: readonly ColumnRole<R>[];
@@ -204,7 +205,8 @@ export interface ColumnMapperProps<R extends string> {
     onChange: (result: ColumnMapperResult<R> | null) => void;
     /** The paste box's label. Default: `labels.paste`. */
     label?: ReactNode;
-    /** The caption under the paste box. Default: `labels.pasteHint`. */
+    /** The caption under the paste box. Default: `labels.pasteHint`. The paste box's
+     *  `help` (0.36) is `help`. */
     hint?: ReactNode;
     /** What the file dialog offers, and what a drop is checked against. Default:
      *  `.csv,.tsv,.txt,.dat,.asc`. */
@@ -249,4 +251,4 @@ export interface ColumnMapperProps<R extends string> {
  * parts: {@link parseTextTable} or its own server's sniff, then {@link ColumnRoleTable},
  * then {@link readMappedTable}.
  */
-export declare function ColumnMapper<R extends string>({ roles, onChange, label, hint, accept, maxSize, defaultText, previewRows, guess, disabled, bodyProps, rowProps, labels: labelsProp, className, }: ColumnMapperProps<R>): import("react").JSX.Element;
+export declare function ColumnMapper<R extends string>({ roles, onChange, label, hint, help, accept, maxSize, defaultText, previewRows, guess, disabled, bodyProps, rowProps, labels: labelsProp, className, }: ColumnMapperProps<R>): import("react").JSX.Element;

package/dist/components/column-mapper.js

@@ -161,6 +161,7 @@ function ColumnMapper({
   onChange,
   label,
   hint,
+  help,
   accept = DEFAULT_ACCEPT,
   maxSize,
   defaultText = "",
@@ -245,6 +246,7 @@ function ColumnMapper({
           {
             label: label ?? labels.paste,
             hint: hint ?? labels.pasteHint,
+            help,
             rows: 5,
             wrap: "off",
             spellCheck: false,