@eifi1/ui-kit 0.12.0 → 0.13.1

package/dist/components/entity-combobox.js

@@ -65,16 +65,16 @@ function EntityCombobox({
     create: createLabel
   });
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  const { open, results, resolve, setOpen } = core;
+  const { open, results, resolve, setOpen, rememberOption, query, triggerRef } = core;
   const listboxId = useId();
   const chosen = value == null || value === clearValue ? null : value;
   const selectedOption = chosen == null ? null : resolve(chosen);
-  const q = core.query.trim();
+  const q = query.trim();
   const showCreate = Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());
   const showClear = Boolean(clearable && chosen != null && !disabled);
   const triggerText = selectedOption?.label ?? placeholder ?? "";
   const choose = (o) => {
-    core.cacheRef.current.set(o.value, o);
+    rememberOption(o);
     onChange(o.value);
     core.closeToTrigger();
   };
@@ -88,7 +88,7 @@ function EntityCombobox({
       /* @__PURE__ */ jsxs(
         "button",
         {
-          ref: core.triggerRef,
+          ref: triggerRef,
           id,
           type: "button",
           role: "combobox",
@@ -136,19 +136,24 @@ function EntityCombobox({
                 }
               )
             ] }),
-            showClear ? /* @__PURE__ */ jsx(
-              "span",
-              {
-                role: "button",
-                tabIndex: -1,
-                "aria-label": labels.clear,
-                onClick: (e) => {
-                  e.stopPropagation();
-                  onChange(clearValue);
-                },
-                className: "absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]",
-                children: /* @__PURE__ */ jsx(X, { className: "size-4" })
-              }
+            showClear ? (
+              /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside
+                  the trigger <button>, so it never holds focus and a key handler here could
+                  never fire; the keys go to the trigger. A pointer shortcut only. */
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  role: "button",
+                  tabIndex: -1,
+                  "aria-label": labels.clear,
+                  onClick: (e) => {
+                    e.stopPropagation();
+                    onChange(clearValue);
+                  },
+                  className: "absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]",
+                  children: /* @__PURE__ */ jsx(X, { className: "size-4" })
+                }
+              )
             ) : /* @__PURE__ */ jsx(FieldChevron, {})
           ]
         }

package/dist/components/entity-combobox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/entity-combobox.tsx"],"sourcesContent":["import { useId } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode } from \"react\";\nimport { X } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { FieldChevron, FieldLabel, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./ui\";\nimport {\n  ComboboxPanel,\n  useComboboxCore,\n  useComboboxFieldError,\n  type ComboClearValue,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from \"../i18n/kit-labels\";\n\nexport type { ComboClearValue, ComboOption } from \"./combobox-core\";\n\n/** `onChange` is the kit's — \"a selection was made\", carrying values — rather\n *  than the div's form event, so the DOM's spelling of it is omitted. */\nexport interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\"> {\n  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */\n  value: V | C | null | undefined;\n  /** Selecting an option emits its value; the clear button emits `clearValue`. */\n  onChange: (value: V | C) => void;\n  /**\n   * What the clear button emits. Default `null`. Pass `\"\"` for a form whose schema\n   * wants an empty string for \"no choice\" (a zod `z.string()` field), rather than\n   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the\n   * mapping cannot be forgotten on one field and not another. The picker also reads\n   * the value back as empty, so `value=\"\"` shows the placeholder and no \"×\".\n   * See {@link ComboClearValue} for why the choice is closed.\n   */\n  clearValue?: C;\n  /** Already-loaded options (client-side filtered). Also used to resolve the\n   *  trigger label for the current `value`. */\n  options?: ComboOption<V>[];\n  /** Async option source, debounced and called on open + as the query changes\n   *  (at `minChars` and up). Stale responses are ignored; a rejection empties the\n   *  list and says `loadErrorLabel` instead of leaving the last query's rows up. When set, `options` is used only for label\n   *  resolution, not as the result list. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** External loading flag (OR-ed with the internal async state). */\n  loading?: boolean;\n  label?: ReactNode;\n  placeholder?: string;\n  searchPlaceholder?: string;\n  emptyLabel?: string;\n  clearable?: boolean;\n  clearLabel?: string;\n  /** The phone sheet's close button. Its own prop rather than a reuse of\n   *  `clearLabel`: \"clear the selection\" and \"close this screen\" are different\n   *  actions, and on a full-screen sheet the close button is the only way out —\n   *  so it is the one control here that MUST be in the reader's language. */\n  closeLabel?: string;\n  disabled?: boolean;\n  /** When set, a \"create\" row appears for a non-empty query with no exact match. */\n  onCreate?: (query: string) => void;\n  createLabel?: (query: string) => string;\n  /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */\n  invalid?: boolean;\n  /** What is wrong with the value, as {@link Input}'s `error`: rendered under the\n   *  field, on the trigger's `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /** Narrow `options` client-side by the query. Default `true`; `false` shows them\n   *  as given (a server-ranked list). */\n  filter?: boolean;\n  /** Offer nothing, and call no `loadOptions`, below this many characters. Default\n   *  `0`, i.e. the list loads as the panel opens. */\n  minChars?: number;\n  /** `loadOptions` debounce. Default 150 ms. */\n  debounceMs?: number;\n  /** Shown when `loadOptions` rejects. Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n}\n\n/**\n * An id-keyed, searchable entity picker: a field-styled trigger showing the\n * selected item's label, and a portalled dropdown of `{label, sublabel, icon}`\n * options — loaded up front via `options` or lazily via `loadOptions`. Built on\n * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking\n * several entities use {@link MultiEntityCombobox}.\n */\nexport function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({\n  value,\n  onChange,\n  clearValue = null as C,\n  options,\n  loadOptions,\n  loading,\n  label,\n  placeholder,\n  searchPlaceholder,\n  emptyLabel,\n  clearable,\n  clearLabel,\n  closeLabel,\n  disabled,\n  onCreate,\n  createLabel,\n  className,\n  invalid,\n  error,\n  filter,\n  minChars,\n  debounceMs,\n  loadErrorLabel,\n  \"aria-label\": ariaLabel,\n  // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than\n  // the wrapper — see MultiEntityCombobox: `Field`'s render-prop spreads `{ id,\n  // aria-describedby, aria-invalid, aria-required }`, and on the role-less wrapper\n  // div the label's `htmlFor` named nothing and the hint described nothing.\n  id,\n  \"aria-describedby\": ariaDescribedBy,\n  \"aria-invalid\": ariaInvalid,\n  \"aria-required\": ariaRequired,\n  ...rest\n}: EntityComboboxProps<V, C>) {\n  const core = useComboboxCore<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n  });\n  const field = useComboboxFieldError(\n    error,\n    invalid || ariaInvalid === true || ariaInvalid === \"true\",\n    ariaDescribedBy,\n  );\n  // The props are the per-instance overrides, the provider the app-wide ones; a\n  // prop left `undefined` falls through to the provider rather than masking it.\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    search: searchPlaceholder,\n    noResults: emptyLabel,\n    clear: clearLabel,\n    create: createLabel,\n  });\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const { open, results, resolve, setOpen } = core;\n  // One id per instance, generated here rather than in the core: `aria-controls` on\n  // the trigger has to name the list while the list is still closed, so the id\n  // belongs to whoever renders both ends of it.\n  const listboxId = useId();\n\n  // The clear value is \"nothing selected\" too, whichever one the caller picked.\n  const chosen: V | null = value == null || value === clearValue ? null : (value as V);\n  const selectedOption = chosen == null ? null : resolve(chosen);\n  const q = core.query.trim();\n  const showCreate =\n    Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());\n  const showClear = Boolean(clearable && chosen != null && !disabled);\n  /** What the closed control is showing — the second half of its accessible name. */\n  const triggerText = selectedOption?.label ?? placeholder ?? \"\";\n\n  const choose = (o: ComboOption<V>) => {\n    core.cacheRef.current.set(o.value, o);\n    onChange(o.value);\n    // Back to the trigger, not to <body>: the panel that held focus is about to\n    // unmount, and a keyboard user who just answered this field should be standing\n    // on it, ready to Tab to the next one.\n    core.closeToTrigger();\n  };\n\n  return (\n    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the\n    // id, description, invalid and required state above — go on the trigger, which\n    // has one. Spread FIRST so the trigger's ARIA and the\n    // handlers that open the panel cannot be clobbered from outside.\n    <div {...rest} className={cn(\"relative\", className)}>\n      {label !== undefined && <FieldLabel>{label}</FieldLabel>}\n      <button\n        ref={core.triggerRef}\n        id={id}\n        type=\"button\"\n        // A combobox, not a button. The distinction is not pedantry: this control\n        // carried `aria-invalid`, which `button` does not support, so a required\n        // field left empty painted a rose border and told a reader nothing at all —\n        // and ESLint flagged it as exactly that (`role-supports-aria-props`). The\n        // fix the audit asked for is the role that describes what this IS: a closed\n        // choice that expands into the list named below. `combobox` supports\n        // `aria-invalid`, so the border and the announcement finally agree.\n        role=\"combobox\"\n        aria-expanded={open}\n        aria-controls={listboxId}\n        aria-haspopup=\"listbox\"\n        // The label is a floating <span>, not a <label for>, so without this the\n        // trigger's accessible name is whatever value happens to be selected —\n        // \"Checking\" with nothing saying it is the account. The label AND the\n        // value, because `aria-label` replaces the content rather than adding to\n        // it, and a control that announces only its name has lost the answer.\n        // A caller's own name wins over the composition: two fields labelled\n        // \"Account\" on a transfer form are the from and the to, and only the\n        // caller knows which is which.\n        aria-label={\n          ariaLabel ??\n          (typeof label === \"string\" ? common.fieldValue(label, triggerText) : undefined)\n        }\n        disabled={disabled}\n        aria-invalid={field.isInvalid || undefined}\n        aria-describedby={field.describedBy}\n        aria-required={ariaRequired}\n        onClick={() => !disabled && setOpen((o) => !o)}\n        // Down/Up opens the list from the closed trigger, per the APG. Enter and\n        // Space already do it through the button's own click.\n        onKeyDown={(e) => {\n          if (disabled) return;\n          if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n            e.preventDefault();\n            setOpen(true);\n          }\n        }}\n        className={cn(\n          FIELD_TRIGGER,\n          \"pe-9\",\n          label !== undefined && FIELD_FLOATING_PAD,\n          disabled && \"cursor-not-allowed opacity-50\",\n          field.isInvalid && FIELD_INVALID,\n        )}\n      >\n        <span className=\"flex min-w-0 items-center gap-2\">\n          {selectedOption?.icon && <span className=\"shrink-0\">{selectedOption.icon}</span>}\n          <span\n            className={cn(\n              \"truncate\",\n              // A chosen value is the field's VALUE, so it is set in the same ink an\n              // <input>'s value is — FIELD_BASE's own text colour, inherited rather\n              // than restated (Keksdose dev#477). It used to be one notch lighter\n              // than the typeahead fields beside it, which is visible when a picker\n              // and a text field share a form row. Nothing selected keeps the\n              // placeholder tone (`--text-placeholder`), which every field here\n              // agrees on.\n              !selectedOption && \"text-[var(--text-placeholder)]\",\n            )}\n          >\n            {selectedOption?.label ?? placeholder ?? \"\"}\n          </span>\n        </span>\n        {showClear ? (\n          <span\n            role=\"button\"\n            tabIndex={-1}\n            aria-label={labels.clear}\n            onClick={(e) => {\n              e.stopPropagation();\n              onChange(clearValue);\n            }}\n            className=\"absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]\"\n          >\n            <X className=\"size-4\" />\n          </span>\n        ) : (\n          <FieldChevron />\n        )}\n      </button>\n      <ComboboxPanel\n        core={core}\n        listboxId={listboxId}\n        // On a phone the panel becomes a full-screen sheet, which needs the field's\n        // own label to say what it is asking for (live #200).\n        sheetTitle={label ?? placeholder}\n        searchPlaceholder={labels.search}\n        emptyLabel={labels.noResults}\n        closeLabel={closeLabel}\n        loadErrorLabel={loadErrorLabel}\n        isSelected={(v) => v === value}\n        onChoose={choose}\n        showCreate={showCreate}\n        onCreate={() => {\n          onCreate?.(q);\n          core.closeToTrigger();\n        }}\n        createContent={labels.create(q)}\n      />\n      {field.errorEl}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/entity-combobox.tsx"],"sourcesContent":["import { useId } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode } from \"react\";\nimport { X } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { FieldChevron, FieldLabel, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./ui\";\nimport {\n  ComboboxPanel,\n  useComboboxCore,\n  useComboboxFieldError,\n  type ComboClearValue,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from \"../i18n/kit-labels\";\n\nexport type { ComboClearValue, ComboOption } from \"./combobox-core\";\n\n/** `onChange` is the kit's — \"a selection was made\", carrying values — rather\n *  than the div's form event, so the DOM's spelling of it is omitted. */\nexport interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\"> {\n  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */\n  value: V | C | null | undefined;\n  /** Selecting an option emits its value; the clear button emits `clearValue`. */\n  onChange: (value: V | C) => void;\n  /**\n   * What the clear button emits. Default `null`. Pass `\"\"` for a form whose schema\n   * wants an empty string for \"no choice\" (a zod `z.string()` field), rather than\n   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the\n   * mapping cannot be forgotten on one field and not another. The picker also reads\n   * the value back as empty, so `value=\"\"` shows the placeholder and no \"×\".\n   * See {@link ComboClearValue} for why the choice is closed.\n   */\n  clearValue?: C;\n  /** Already-loaded options (client-side filtered). Also used to resolve the\n   *  trigger label for the current `value`. */\n  options?: ComboOption<V>[];\n  /** Async option source, debounced and called on open + as the query changes\n   *  (at `minChars` and up). Stale responses are ignored; a rejection empties the\n   *  list and says `loadErrorLabel` instead of leaving the last query's rows up. When set, `options` is used only for label\n   *  resolution, not as the result list. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** External loading flag (OR-ed with the internal async state). */\n  loading?: boolean;\n  label?: ReactNode;\n  placeholder?: string;\n  searchPlaceholder?: string;\n  emptyLabel?: string;\n  clearable?: boolean;\n  clearLabel?: string;\n  /** The phone sheet's close button. Its own prop rather than a reuse of\n   *  `clearLabel`: \"clear the selection\" and \"close this screen\" are different\n   *  actions, and on a full-screen sheet the close button is the only way out —\n   *  so it is the one control here that MUST be in the reader's language. */\n  closeLabel?: string;\n  disabled?: boolean;\n  /** When set, a \"create\" row appears for a non-empty query with no exact match. */\n  onCreate?: (query: string) => void;\n  createLabel?: (query: string) => string;\n  /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */\n  invalid?: boolean;\n  /** What is wrong with the value, as {@link Input}'s `error`: rendered under the\n   *  field, on the trigger's `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /** Narrow `options` client-side by the query. Default `true`; `false` shows them\n   *  as given (a server-ranked list). */\n  filter?: boolean;\n  /** Offer nothing, and call no `loadOptions`, below this many characters. Default\n   *  `0`, i.e. the list loads as the panel opens. */\n  minChars?: number;\n  /** `loadOptions` debounce. Default 150 ms. */\n  debounceMs?: number;\n  /** Shown when `loadOptions` rejects. Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n}\n\n/**\n * An id-keyed, searchable entity picker: a field-styled trigger showing the\n * selected item's label, and a portalled dropdown of `{label, sublabel, icon}`\n * options — loaded up front via `options` or lazily via `loadOptions`. Built on\n * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking\n * several entities use {@link MultiEntityCombobox}.\n */\nexport function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({\n  value,\n  onChange,\n  clearValue = null as C,\n  options,\n  loadOptions,\n  loading,\n  label,\n  placeholder,\n  searchPlaceholder,\n  emptyLabel,\n  clearable,\n  clearLabel,\n  closeLabel,\n  disabled,\n  onCreate,\n  createLabel,\n  className,\n  invalid,\n  error,\n  filter,\n  minChars,\n  debounceMs,\n  loadErrorLabel,\n  \"aria-label\": ariaLabel,\n  // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than\n  // the wrapper — see MultiEntityCombobox: `Field`'s render-prop spreads `{ id,\n  // aria-describedby, aria-invalid, aria-required }`, and on the role-less wrapper\n  // div the label's `htmlFor` named nothing and the hint described nothing.\n  id,\n  \"aria-describedby\": ariaDescribedBy,\n  \"aria-invalid\": ariaInvalid,\n  \"aria-required\": ariaRequired,\n  ...rest\n}: EntityComboboxProps<V, C>) {\n  const core = useComboboxCore<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n  });\n  const field = useComboboxFieldError(\n    error,\n    invalid || ariaInvalid === true || ariaInvalid === \"true\",\n    ariaDescribedBy,\n  );\n  // The props are the per-instance overrides, the provider the app-wide ones; a\n  // prop left `undefined` falls through to the provider rather than masking it.\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    search: searchPlaceholder,\n    noResults: emptyLabel,\n    clear: clearLabel,\n    create: createLabel,\n  });\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const { open, results, resolve, setOpen, rememberOption, query, triggerRef } = core;\n  // One id per instance, generated here rather than in the core: `aria-controls` on\n  // the trigger has to name the list while the list is still closed, so the id\n  // belongs to whoever renders both ends of it.\n  const listboxId = useId();\n\n  // The clear value is \"nothing selected\" too, whichever one the caller picked.\n  const chosen: V | null = value == null || value === clearValue ? null : (value as V);\n  const selectedOption = chosen == null ? null : resolve(chosen);\n  const q = query.trim();\n  const showCreate =\n    Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());\n  const showClear = Boolean(clearable && chosen != null && !disabled);\n  /** What the closed control is showing — the second half of its accessible name. */\n  const triggerText = selectedOption?.label ?? placeholder ?? \"\";\n\n  const choose = (o: ComboOption<V>) => {\n    rememberOption(o);\n    onChange(o.value);\n    // Back to the trigger, not to <body>: the panel that held focus is about to\n    // unmount, and a keyboard user who just answered this field should be standing\n    // on it, ready to Tab to the next one.\n    core.closeToTrigger();\n  };\n\n  return (\n    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the\n    // id, description, invalid and required state above — go on the trigger, which\n    // has one. Spread FIRST so the trigger's ARIA and the\n    // handlers that open the panel cannot be clobbered from outside.\n    <div {...rest} className={cn(\"relative\", className)}>\n      {label !== undefined && <FieldLabel>{label}</FieldLabel>}\n      <button\n        ref={triggerRef}\n        id={id}\n        type=\"button\"\n        // A combobox, not a button. The distinction is not pedantry: this control\n        // carried `aria-invalid`, which `button` does not support, so a required\n        // field left empty painted a rose border and told a reader nothing at all —\n        // and ESLint flagged it as exactly that (`role-supports-aria-props`). The\n        // fix the audit asked for is the role that describes what this IS: a closed\n        // choice that expands into the list named below. `combobox` supports\n        // `aria-invalid`, so the border and the announcement finally agree.\n        role=\"combobox\"\n        aria-expanded={open}\n        aria-controls={listboxId}\n        aria-haspopup=\"listbox\"\n        // The label is a floating <span>, not a <label for>, so without this the\n        // trigger's accessible name is whatever value happens to be selected —\n        // \"Checking\" with nothing saying it is the account. The label AND the\n        // value, because `aria-label` replaces the content rather than adding to\n        // it, and a control that announces only its name has lost the answer.\n        // A caller's own name wins over the composition: two fields labelled\n        // \"Account\" on a transfer form are the from and the to, and only the\n        // caller knows which is which.\n        aria-label={\n          ariaLabel ??\n          (typeof label === \"string\" ? common.fieldValue(label, triggerText) : undefined)\n        }\n        disabled={disabled}\n        aria-invalid={field.isInvalid || undefined}\n        aria-describedby={field.describedBy}\n        aria-required={ariaRequired}\n        onClick={() => !disabled && setOpen((o) => !o)}\n        // Down/Up opens the list from the closed trigger, per the APG. Enter and\n        // Space already do it through the button's own click.\n        onKeyDown={(e) => {\n          if (disabled) return;\n          if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n            e.preventDefault();\n            setOpen(true);\n          }\n        }}\n        className={cn(\n          FIELD_TRIGGER,\n          \"pe-9\",\n          label !== undefined && FIELD_FLOATING_PAD,\n          disabled && \"cursor-not-allowed opacity-50\",\n          field.isInvalid && FIELD_INVALID,\n        )}\n      >\n        <span className=\"flex min-w-0 items-center gap-2\">\n          {selectedOption?.icon && <span className=\"shrink-0\">{selectedOption.icon}</span>}\n          <span\n            className={cn(\n              \"truncate\",\n              // A chosen value is the field's VALUE, so it is set in the same ink an\n              // <input>'s value is — FIELD_BASE's own text colour, inherited rather\n              // than restated (Keksdose dev#477). It used to be one notch lighter\n              // than the typeahead fields beside it, which is visible when a picker\n              // and a text field share a form row. Nothing selected keeps the\n              // placeholder tone (`--text-placeholder`), which every field here\n              // agrees on.\n              !selectedOption && \"text-[var(--text-placeholder)]\",\n            )}\n          >\n            {selectedOption?.label ?? placeholder ?? \"\"}\n          </span>\n        </span>\n        {showClear ? (\n          /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside\n              the trigger <button>, so it never holds focus and a key handler here could\n              never fire; the keys go to the trigger. A pointer shortcut only. */\n          <span\n            role=\"button\"\n            tabIndex={-1}\n            aria-label={labels.clear}\n            onClick={(e) => {\n              e.stopPropagation();\n              onChange(clearValue);\n            }}\n            className=\"absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]\"\n          >\n            <X className=\"size-4\" />\n          </span>\n        ) : (\n          <FieldChevron />\n        )}\n      </button>\n      <ComboboxPanel\n        core={core}\n        listboxId={listboxId}\n        // On a phone the panel becomes a full-screen sheet, which needs the field's\n        // own label to say what it is asking for (live #200).\n        sheetTitle={label ?? placeholder}\n        searchPlaceholder={labels.search}\n        emptyLabel={labels.noResults}\n        closeLabel={closeLabel}\n        loadErrorLabel={loadErrorLabel}\n        isSelected={(v) => v === value}\n        onChoose={choose}\n        showCreate={showCreate}\n        onCreate={() => {\n          onCreate?.(q);\n          core.closeToTrigger();\n        }}\n        createContent={labels.create(q)}\n      />\n      {field.errorEl}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/error-boundary.d.ts

@@ -8,8 +8,24 @@ interface ErrorBoundaryLabels {
     message: string;
     /** The button that clears the error and renders the children again. */
     retry: string;
-    /** The disclosure that opens the error's own text (`showDetails`). */
+    /** The disclosure that opens the full error report (`showDetails`). */
     details: string;
+    /** The button that reloads the whole page (0.13). */
+    reload: string;
+    /** Heading when a lazy chunk failed to load while online — a deploy replaced the
+     *  files this page was built from (0.13). */
+    updateTitle: string;
+    updateMessage: string;
+    /** Heading when the browser says it is offline (0.13). */
+    offlineTitle: string;
+    offlineMessage: string;
+    /** The copy button's words: what it copies is the plain-text report (0.13). */
+    copyReport: string;
+    /** Shown once `onReport` has filed the crash and returned no reference (0.13). */
+    reported: string;
+    /** Shown once `onReport` has filed the crash under a reference — rendered as the
+     *  app returned it, so return `"#123"` if the hash belongs to it (0.13). */
+    reportedAs: (reference: string) => string;
 }
 declare const DEFAULT_ERROR_BOUNDARY_LABELS: ErrorBoundaryLabels;
 /**
@@ -28,6 +44,88 @@ interface ErrorBoundaryDetails {
 }
 /** {@link ErrorBoundaryDetails} of any thrown value, without ever throwing. */
 declare function describeThrown(error: unknown): ErrorBoundaryDetails;
+/**
+ * Is this a failed lazy import — a route chunk that did not arrive?
+ *
+ * Two causes, and neither is a bug in the page: the device is offline and the chunk was
+ * never cached, or a deploy replaced the hashed files the running page still points at.
+ * Both are cured by a reload and by nothing else — `React.lazy` caches the rejected
+ * import, so Try again re-throws the same error without fetching. The patterns are
+ * keksdose's (crash-report.ts), which covers Vite ("dynamically imported module",
+ * "module script failed"), webpack ("ChunkLoadError", "Loading chunk") and the bare
+ * `fetch` failure a service worker hands back.
+ *
+ * Never throws: it runs inside the fallback's own render, where a throw is a white
+ * screen. An error it cannot read is not a chunk failure.
+ */
+declare function isChunkLoadError(error: {
+    name?: string | null;
+    message?: string | null;
+} | null | undefined): boolean;
+/**
+ * Everything a crash report carries, read once when the boundary catches.
+ *
+ * Plain strings only, so it survives `JSON.stringify` into an app's crash endpoint as is
+ * and {@link formatCrashReport} can print it without a single guard. The wording of the
+ * printed report is English on purpose: it is read by whoever fixes the bug, not by the
+ * user who copies it, and a report in nine languages cannot be searched.
+ */
+interface CrashReport {
+    /** The thrown value's `name` ("TypeError"), "Error" for a non-object. */
+    name: string;
+    message: string;
+    stack?: string;
+    /** React's component stack from `componentDidCatch` — the part that names the
+     *  component, which a minified JS stack no longer does. */
+    componentStack?: string;
+    /** `pathname + search` at the moment of the crash. The search may carry what the
+     *  user typed — see `redact`. */
+    page: string;
+    /** ISO 8601, UTC. */
+    time: string;
+    userAgent: string;
+    /** The boundary's `appVersion` prop. */
+    appVersion?: string;
+    /** `navigator.onLine` at the moment of the crash; left out where there is none. */
+    online?: boolean;
+    /** {@link isChunkLoadError} of the thrown value. Such a crash is never handed to
+     *  `onReport` — it is a deploy or a dropped connection, not a defect — but it is
+     *  still in the copied report. */
+    chunkLoad: boolean;
+    /** The boundary's `reportExtras()`, stringified. */
+    extras: Record<string, string>;
+}
+/**
+ * The report as one plain-text block — what the copy button puts on the clipboard and
+ * the details disclosure shows.
+ *
+ * lenkbank's layout, because that is the one that was already being pasted into
+ * feedback messages: the error line first (it is what a search for the bug matches),
+ * then where / when / what, then the two stacks.
+ */
+declare function formatCrashReport(report: CrashReport): string;
+/**
+ * A key for "the same crash again": the error's name and message and the first frames
+ * of its stack.
+ *
+ * Page-load local, not a server-side grouping key (keksdose's crash-report.ts draws the
+ * same line): its only job is to stop one page load filing one bug twice — React's dev
+ * StrictMode, a Try again that crashes again, a render loop that trips the boundary many
+ * times a second. The page and the time are left out on purpose: the same bug on two
+ * routes is still one bug.
+ */
+declare function crashFingerprint(report: Pick<CrashReport, "name" | "message" | "stack">): string;
+/**
+ * What `onReport` may resolve with. `{ reference }` is shown ("Reported as …");
+ * nothing (or `{}`) means filed without one. `{ filed: false }` says the app decided NOT
+ * to file (a demo session, a hot-reload artefact, a report buffered for later): the
+ * screen then claims nothing and keeps the copy button — claiming a report that was
+ * never sent is the same false statement as hiding one that was.
+ */
+type CrashReportResult = {
+    reference?: string;
+    filed?: boolean;
+} | void;
 /** What a render-prop `fallback` is handed. */
 interface ErrorBoundaryFallbackProps {
     /** The thrown value, as it was thrown. Read it with care — see {@link describeThrown}. */
@@ -35,15 +133,20 @@ interface ErrorBoundaryFallbackProps {
     details: ErrorBoundaryDetails;
     /** Clear the error and render the children again. */
     reset: () => void;
+    /** The crash report, once `componentDidCatch` has built it (null on the very first
+     *  render of the fallback, which happens before it). Already `redact`ed. */
+    report: CrashReport | null;
 }
 interface ErrorBoundaryProps {
     children?: ReactNode;
     /** Replaces the default fallback: a node, or a render function handed the error and
-     *  a `reset`. */
+     *  a `reset`. The same rule applies to it as to the default: see the component docs. */
     fallback?: ReactNode | ((props: ErrorBoundaryFallbackProps) => ReactNode);
-    /** Called once per caught error — log it, file a crash report. */
+    /** Called once per caught error with the raw value — log it. A throw from it is
+     *  swallowed: the boundary is the last thing standing. For filing a report, prefer
+     *  `onReport`, which gets the finished report, dedupe and the reference on screen. */
     onError?: (error: unknown, info: ErrorInfo) => void;
-    /** Called when the error is cleared, by Retry, `reset` or a `resetKeys` change —
+    /** Called when the error is cleared, by Try again, `reset` or a `resetKeys` change —
      *  drop a cache, refetch. */
     onReset?: () => void;
     /**
@@ -53,35 +156,121 @@ interface ErrorBoundaryProps {
      * carry its fallback to the next one (keksdose's `resetKey`).
      */
     resetKeys?: ReadonlyArray<unknown>;
-    /** A disclosure under the message with the error's name, message and stack — for an
-     *  internal tool, or while developing. Off by default: a stack means nothing to a user. */
+    /** Quote the error's `name: message` in a monospace box under the hint. Default on
+     *  (0.13): three sentences true of every crash identify none of them, and the one
+     *  line that does is what a user can read out or screenshot (lenkbank P7). Not shown
+     *  for a chunk-load / offline screen, where the message is a URL that explains
+     *  nothing the title does not. */
+    showMessage?: boolean;
+    /** A collapsed disclosure holding the full plain-text report. Default on since 0.13
+     *  (it was an opt-in showing name, message and stack): closed, it costs one line, and
+     *  it is where a support conversation asks the user to look. */
     showDetails?: boolean;
+    /** The copy button for the plain-text report (the kit's CopyButton, which says when
+     *  the clipboard refused). Default on. Hidden once `onReport` has filed the crash —
+     *  there is nothing left to paste anywhere — and shown again whenever it did not. */
+    copyReport?: boolean;
+    /** The app's version, printed in the report — the first question on every crash. */
+    appVersion?: string;
+    /** More `key: value` lines for the report, read when the boundary catches (a tenant
+     *  id, the feature flags). A throw from it is swallowed and the lines are left out. */
+    reportExtras?: () => Record<string, string>;
+    /**
+     * Rewrite the report before anything sees it: the screen, the clipboard and
+     * `onReport` all get the returned one.
+     *
+     * THE REPORT IS STRUCTURE, NEVER CONTENT — and only the app knows which of its query
+     * params hold content. keksdose's register put the free-text search in `?q=` and payee
+     * names in the `f.*` filters, and its crash channel sent them in the clear to a column
+     * every admin reads (crash-report.ts `safeUrl`). The cure there is an ALLOW-list, so a
+     * param added later is dropped until somebody decides otherwise — rebuild `page`
+     * from `new URL(r.page, location.origin)`, keeping only the listed `searchParams`.
+     * `extras` are the app's own and need no second pass. A throw from `redact` falls
+     * back to the pathname alone and no extras — failing closed.
+     *
+     * The same holds inside `onReport`, which is the other place to do it: clamp fields
+     * to what the endpoint accepts, drop what it must not store. The kit cannot know.
+     */
+    redact?: (report: CrashReport) => CrashReport;
+    /**
+     * File the report automatically. Called from `componentDidCatch`, at most once per
+     * {@link crashFingerprint} per page load (and at most five times in all), never for a
+     * chunk-load error. It can NOT throw into the boundary: a synchronous throw and a
+     * rejection both read as "not filed", and the copy button stays.
+     *
+     * Resolve with `{ reference }` and the screen says "Reported as …" instead of the copy
+     * button; see {@link CrashReportResult} for "filed without a reference" and "decided not
+     * to file". Whatever the app's reporter does, it must do without the router, the query
+     * client or the auth store's hooks — a bare `fetch` with `keepalive`, so it survives
+     * the reload the user is about to press (keksdose crash-report.ts `post`).
+     */
+    onReport?: (report: CrashReport) => Promise<CrashReportResult> | CrashReportResult;
+    /** The app's own escape hatches, beside Reload / Try again — keksdose's "Clear local
+     *  data" for a poisoned persisted cache that no in-app action could otherwise break.
+     *  A full-width hint under it: wrap it in `<div className="basis-full">`. */
+    actions?: ReactNode;
     /** The default fallback's heading level. Default `h2`: the fallback often IS the page. */
     headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
     /** Classes for the default fallback's box (`m-8 min-h-[400px]`, kastlan). */
     className?: string;
     labels?: Partial<ErrorBoundaryLabels>;
 }
+type FilingState = "none" | "pending" | "filed" | "failed";
 interface ErrorBoundaryState {
     /** A flag of its own, so `throw undefined` is still an error shown. */
     failed: boolean;
     error: unknown;
     details: ErrorBoundaryDetails | null;
+    report: CrashReport | null;
+    filing: FilingState;
+    reference: string | undefined;
 }
 /**
- * Catch a render error below it and show a fallback instead of an empty page.
+ * Catch a render error below it and show ONE crash screen instead of an empty page.
+ *
+ * The three apps each built one. kastlan's and keksdose's sat on `EmptyState
+ * tone="danger"`; lenkbank's quoted the error and offered a plain-text report to copy;
+ * keksdose's filed the crash itself, told a lazy-chunk failure apart as "offline", and
+ * offered "clear local data" when a poisoned cache made Retry useless (feedback #160).
+ * This is all of that, so the apps reduce to
+ * `<ErrorBoundary resetKeys={[pathname]} appVersion={__VERSION__} />` plus, for an app
+ * with a crash endpoint, `onReport` and `actions`:
  *
- * kastlan (shared/components/error-boundary.tsx) and keksdose (app/error-boundary.tsx)
- * each built one on `EmptyState tone="danger"`: a warning glyph, a title, a line of
- * explanation and a Retry. This is that fallback, translated through the provider
- * (`errorBoundary.*`), with the hooks an app hangs its own behaviour on — `onError`
- * for the crash report, `resetKeys` for the route change, `fallback` for anything else.
+ * - the error's `name: message`, quoted (`showMessage`);
+ * - Try again (reset the boundary) AND Reload (the page) — Try again alone re-renders
+ *   the same subtree from the same state, which a deterministic crash survives;
+ * - a chunk-load error or an offline browser gets its own title and Reload first
+ *   ("A new version is available" / "You're offline");
+ * - the copy button and the report in a disclosure; `onReport` for filing it, deduped
+ *   per page load, with its reference on screen.
+ *
+ * THE RULE for this fallback — and for a `fallback` or `actions` an app passes in: it
+ * must not depend on the router, the query client or the auth store. A crash is exactly
+ * when those may be what broke, and a fallback that throws escalates to the next
+ * boundary up — at the app level there is none, and the user gets the white screen this
+ * exists to prevent. So no `useNavigate`, no `useQuery`, no `useAuth()` in it; reload
+ * with `window.location`, not the router. The kit's own label hooks are the one context
+ * it does read (`errorBoundary.*` from `UiKitProvider`), and they degrade to the English
+ * defaults when there is no provider above — which is why the app-level boundary may
+ * sit OUTSIDE the provider and still render.
  *
  * The fallback is `role="alert"`: a page replaced by an error is news, and a reader
  * that was on it is told.
  */
 declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
     state: ErrorBoundaryState;
+    /** Bumped by every catch and reset, so a filing that settles after the screen moved
+     *  on (Try again, a route change, a second crash) does not write into it. */
+    private generation;
+    /**
+     * Forget which crashes this page load has filed, and the count towards the cap.
+     *
+     * For tests: the dedupe lives in module scope because a page load is what it spans,
+     * and a test file is one page load — so without this, the sixth test that files a
+     * report finds the cap reached and `onReport` never called. Call it in `beforeEach`.
+     * Never needed in an app: a reload is the reset.
+     */
+    static forgetReports(): void;
     static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState>;
     componentDidCatch(error: unknown, info: ErrorInfo): void;
     componentDidUpdate(prev: ErrorBoundaryProps, prevState: ErrorBoundaryState): void;
@@ -89,4 +278,4 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryS
     render(): ReactNode;
 }
 
-export { DEFAULT_ERROR_BOUNDARY_LABELS, ErrorBoundary, type ErrorBoundaryDetails, type ErrorBoundaryFallbackProps, type ErrorBoundaryLabels, type ErrorBoundaryProps, describeThrown };
+export { type CrashReport, type CrashReportResult, DEFAULT_ERROR_BOUNDARY_LABELS, ErrorBoundary, type ErrorBoundaryDetails, type ErrorBoundaryFallbackProps, type ErrorBoundaryLabels, type ErrorBoundaryProps, crashFingerprint, describeThrown, formatCrashReport, isChunkLoadError };