@eifi1/ui-kit 0.11.0 → 0.12.0

package/dist/components/entity-combobox.d.ts

@@ -68,6 +68,6 @@ interface EntityComboboxProps<V extends string | number, C extends ComboClearVal
  * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking
  * several entities use {@link MultiEntityCombobox}.
  */
-declare function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({ value, onChange, clearValue, options, loadOptions, loading, label, placeholder, searchPlaceholder, emptyLabel, clearable, clearLabel, closeLabel, disabled, onCreate, createLabel, className, invalid, error, filter, minChars, debounceMs, loadErrorLabel, "aria-label": ariaLabel, ...rest }: EntityComboboxProps<V, C>): react.JSX.Element;
+declare function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({ value, onChange, clearValue, options, loadOptions, loading, label, placeholder, searchPlaceholder, emptyLabel, clearable, clearLabel, closeLabel, disabled, onCreate, createLabel, className, invalid, error, filter, minChars, debounceMs, loadErrorLabel, "aria-label": ariaLabel, id, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, ...rest }: EntityComboboxProps<V, C>): react.JSX.Element;
 
 export { ComboClearValue, ComboOption, EntityCombobox, type EntityComboboxProps };

package/dist/components/entity-combobox.js

@@ -35,6 +35,14 @@ function EntityCombobox({
   debounceMs,
   loadErrorLabel,
   "aria-label": ariaLabel,
+  // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than
+  // the wrapper — see MultiEntityCombobox: `Field`'s render-prop spreads `{ id,
+  // aria-describedby, aria-invalid, aria-required }`, and on the role-less wrapper
+  // div the label's `htmlFor` named nothing and the hint described nothing.
+  id,
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }) {
   const core = useComboboxCore({
@@ -45,7 +53,11 @@ function EntityCombobox({
     minChars,
     debounceMs
   });
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy
+  );
   const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
     search: searchPlaceholder,
     noResults: emptyLabel,
@@ -67,8 +79,9 @@ function EntityCombobox({
     core.closeToTrigger();
   };
   return (
-    // `rest` dresses the wrapper, which has no role; the accessible NAME goes on
-    // the trigger, which has one. Spread FIRST so the trigger's ARIA and the
+    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the
+    // id, description, invalid and required state above — go on the trigger, which
+    // has one. Spread FIRST so the trigger's ARIA and the
     // handlers that open the panel cannot be clobbered from outside.
     /* @__PURE__ */ jsxs("div", { ...rest, className: cn("relative", className), children: [
       label !== void 0 && /* @__PURE__ */ jsx(FieldLabel, { children: label }),
@@ -76,6 +89,7 @@ function EntityCombobox({
         "button",
         {
           ref: core.triggerRef,
+          id,
           type: "button",
           role: "combobox",
           "aria-expanded": open,
@@ -85,6 +99,7 @@ function EntityCombobox({
           disabled,
           "aria-invalid": field.isInvalid || void 0,
           "aria-describedby": field.describedBy,
+          "aria-required": ariaRequired,
           onClick: () => !disabled && setOpen((o) => !o),
           onKeyDown: (e) => {
             if (disabled) return;

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  ...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(error, invalid);\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 goes on\n    // the trigger, which 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        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        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":";AA6J8B,cAgDtB,YAhDsB;AA7J9B,SAAS,aAAa;AAEtB,SAAS,SAAS;AAClB,SAAS,UAAU;AACnB,SAAS,cAAc,YAAY,eAAe,oBAAoB,qBAAqB;AAC3F;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,yBAAyB,uBAAuB,oBAAoB;AAsEtE,SAAS,eAA4E;AAAA,EAC1F;AAAA,EACA;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,cAAc;AAAA,EACd,GAAG;AACL,GAA8B;AAC5B,QAAM,OAAO,gBAAmB;AAAA,IAC9B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACD,QAAM,QAAQ,sBAAsB,OAAO,OAAO;AAGlD,QAAM,SAAS,aAAa,YAAY,yBAAyB;AAAA,IAC/D,QAAQ;AAAA,IACR,WAAW;AAAA,IACX,OAAO;AAAA,IACP,QAAQ;AAAA,EACV,CAAC;AACD,QAAM,SAAS,aAAa,UAAU,qBAAqB;AAC3D,QAAM,EAAE,MAAM,SAAS,SAAS,QAAQ,IAAI;AAI5C,QAAM,YAAY,MAAM;AAGxB,QAAM,SAAmB,SAAS,QAAQ,UAAU,aAAa,OAAQ;AACzE,QAAM,iBAAiB,UAAU,OAAO,OAAO,QAAQ,MAAM;AAC7D,QAAM,IAAI,KAAK,MAAM,KAAK;AAC1B,QAAM,aACJ,QAAQ,QAAQ,KAAK,EAAE,SAAS,KAAK,CAAC,QAAQ,KAAK,CAAC,MAAM,EAAE,MAAM,YAAY,MAAM,EAAE,YAAY,CAAC;AACrG,QAAM,YAAY,QAAQ,aAAa,UAAU,QAAQ,CAAC,QAAQ;AAElE,QAAM,cAAc,gBAAgB,SAAS,eAAe;AAE5D,QAAM,SAAS,CAAC,MAAsB;AACpC,SAAK,SAAS,QAAQ,IAAI,EAAE,OAAO,CAAC;AACpC,aAAS,EAAE,KAAK;AAIhB,SAAK,eAAe;AAAA,EACtB;AAEA;AAAA;AAAA;AAAA;AAAA,IAIE,qBAAC,SAAK,GAAG,MAAM,WAAW,GAAG,YAAY,SAAS,GAC/C;AAAA,gBAAU,UAAa,oBAAC,cAAY,iBAAM;AAAA,MAC3C;AAAA,QAAC;AAAA;AAAA,UACC,KAAK,KAAK;AAAA,UACV,MAAK;AAAA,UAQL,MAAK;AAAA,UACL,iBAAe;AAAA,UACf,iBAAe;AAAA,UACf,iBAAc;AAAA,UASd,cACE,cACC,OAAO,UAAU,WAAW,OAAO,WAAW,OAAO,WAAW,IAAI;AAAA,UAEvE;AAAA,UACA,gBAAc,MAAM,aAAa;AAAA,UACjC,oBAAkB,MAAM;AAAA,UACxB,SAAS,MAAM,CAAC,YAAY,QAAQ,CAAC,MAAM,CAAC,CAAC;AAAA,UAG7C,WAAW,CAAC,MAAM;AAChB,gBAAI,SAAU;AACd,gBAAI,EAAE,QAAQ,eAAe,EAAE,QAAQ,WAAW;AAChD,gBAAE,eAAe;AACjB,sBAAQ,IAAI;AAAA,YACd;AAAA,UACF;AAAA,UACA,WAAW;AAAA,YACT;AAAA,YACA;AAAA,YACA,UAAU,UAAa;AAAA,YACvB,YAAY;AAAA,YACZ,MAAM,aAAa;AAAA,UACrB;AAAA,UAEA;AAAA,iCAAC,UAAK,WAAU,mCACb;AAAA,8BAAgB,QAAQ,oBAAC,UAAK,WAAU,YAAY,yBAAe,MAAK;AAAA,cACzE;AAAA,gBAAC;AAAA;AAAA,kBACC,WAAW;AAAA,oBACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAQA,CAAC,kBAAkB;AAAA,kBACrB;AAAA,kBAEC,0BAAgB,SAAS,eAAe;AAAA;AAAA,cAC3C;AAAA,eACF;AAAA,YACC,YACC;AAAA,cAAC;AAAA;AAAA,gBACC,MAAK;AAAA,gBACL,UAAU;AAAA,gBACV,cAAY,OAAO;AAAA,gBACnB,SAAS,CAAC,MAAM;AACd,oBAAE,gBAAgB;AAClB,2BAAS,UAAU;AAAA,gBACrB;AAAA,gBACA,WAAU;AAAA,gBAEV,8BAAC,KAAE,WAAU,UAAS;AAAA;AAAA,YACxB,IAEA,oBAAC,gBAAa;AAAA;AAAA;AAAA,MAElB;AAAA,MACA;AAAA,QAAC;AAAA;AAAA,UACC;AAAA,UACA;AAAA,UAGA,YAAY,SAAS;AAAA,UACrB,mBAAmB,OAAO;AAAA,UAC1B,YAAY,OAAO;AAAA,UACnB;AAAA,UACA;AAAA,UACA,YAAY,CAAC,MAAM,MAAM;AAAA,UACzB,UAAU;AAAA,UACV;AAAA,UACA,UAAU,MAAM;AACd,uBAAW,CAAC;AACZ,iBAAK,eAAe;AAAA,UACtB;AAAA,UACA,eAAe,OAAO,OAAO,CAAC;AAAA;AAAA,MAChC;AAAA,MACC,MAAM;AAAA,OACT;AAAA;AAEJ;","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 } = 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":[]}

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

@@ -0,0 +1,92 @@
+import { Component, ReactNode, ErrorInfo } from 'react';
+
+/** The words of the default fallback. */
+interface ErrorBoundaryLabels {
+    /** The fallback's heading. */
+    title: string;
+    /** The line under it. */
+    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`). */
+    details: string;
+}
+declare const DEFAULT_ERROR_BOUNDARY_LABELS: ErrorBoundaryLabels;
+/**
+ * What was thrown, as flat strings, read ONCE when it arrives.
+ *
+ * React stores whatever was thrown, hostile or not — `throw { get message() { throw … } }`,
+ * `throw { name: Symbol() }`, `throw undefined` — and reading one of those during the
+ * fallback's own render would throw INSIDE the boundary, escalating to the next one up
+ * (keksdose's error-boundary.tsx learned this as feedback #160: at the app level there is
+ * none, and the result is the white screen the boundary exists to prevent).
+ */
+interface ErrorBoundaryDetails {
+    name: string;
+    message: string;
+    stack?: string;
+}
+/** {@link ErrorBoundaryDetails} of any thrown value, without ever throwing. */
+declare function describeThrown(error: unknown): ErrorBoundaryDetails;
+/** What a render-prop `fallback` is handed. */
+interface ErrorBoundaryFallbackProps {
+    /** The thrown value, as it was thrown. Read it with care — see {@link describeThrown}. */
+    error: unknown;
+    details: ErrorBoundaryDetails;
+    /** Clear the error and render the children again. */
+    reset: () => void;
+}
+interface ErrorBoundaryProps {
+    children?: ReactNode;
+    /** Replaces the default fallback: a node, or a render function handed the error and
+     *  a `reset`. */
+    fallback?: ReactNode | ((props: ErrorBoundaryFallbackProps) => ReactNode);
+    /** Called once per caught error — log it, file a crash report. */
+    onError?: (error: unknown, info: ErrorInfo) => void;
+    /** Called when the error is cleared, by Retry, `reset` or a `resetKeys` change —
+     *  drop a cache, refetch. */
+    onReset?: () => void;
+    /**
+     * When any of these changes (compared with `Object.is`) AFTER an error was caught, the
+     * error is cleared and the children render again — a change in the same update that
+     * threw does not count (it is what the error was shown under) — pass the route path so leaving a broken page does not
+     * 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. */
+    showDetails?: boolean;
+    /** 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>;
+}
+interface ErrorBoundaryState {
+    /** A flag of its own, so `throw undefined` is still an error shown. */
+    failed: boolean;
+    error: unknown;
+    details: ErrorBoundaryDetails | null;
+}
+/**
+ * Catch a render error below it and show a fallback instead of an empty page.
+ *
+ * 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 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;
+    static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(prev: ErrorBoundaryProps, prevState: ErrorBoundaryState): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
+export { DEFAULT_ERROR_BOUNDARY_LABELS, ErrorBoundary, type ErrorBoundaryDetails, type ErrorBoundaryFallbackProps, type ErrorBoundaryLabels, type ErrorBoundaryProps, describeThrown };

package/dist/components/error-boundary.js

@@ -0,0 +1,111 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Component } from "react";
+import { AlertTriangle } from "lucide-react";
+import { useKitLabels } from "../i18n/kit-labels.js";
+import { Button, EmptyState } from "./ui.js";
+import { Disclosure } from "./disclosure.js";
+const DEFAULT_ERROR_BOUNDARY_LABELS = {
+  title: "Something went wrong",
+  message: "This part of the page could not be shown. Try again, or reload the page.",
+  retry: "Try again",
+  details: "Error details"
+};
+function read(get) {
+  try {
+    const v = get();
+    return typeof v === "string" ? v : v === void 0 || v === null ? void 0 : String(v);
+  } catch {
+    return void 0;
+  }
+}
+function describeThrown(error) {
+  if (typeof error === "object" && error !== null) {
+    const e = error;
+    return {
+      name: read(() => e.name) ?? "Error",
+      message: read(() => e.message) ?? "",
+      stack: read(() => e.stack)
+    };
+  }
+  return { name: "Error", message: read(() => error) ?? "" };
+}
+const CLEAR = { failed: false, error: null, details: null };
+function keysChanged(a, b) {
+  if (a === b) return false;
+  if (!a || !b || a.length !== b.length) return true;
+  return a.some((v, i) => !Object.is(v, b[i]));
+}
+class ErrorBoundary extends Component {
+  state = CLEAR;
+  static getDerivedStateFromError(error) {
+    return { failed: true, error, details: describeThrown(error) };
+  }
+  componentDidCatch(error, info) {
+    this.props.onError?.(error, info);
+  }
+  componentDidUpdate(prev, prevState) {
+    if (this.state.failed && prevState.failed && keysChanged(prev.resetKeys, this.props.resetKeys)) {
+      this.reset();
+    }
+  }
+  reset = () => {
+    this.props.onReset?.();
+    this.setState(CLEAR);
+  };
+  render() {
+    const { failed, error, details } = this.state;
+    if (!failed || !details) return this.props.children;
+    const { fallback } = this.props;
+    if (typeof fallback === "function") return fallback({ error, details, reset: this.reset });
+    if (fallback !== void 0) return fallback;
+    return /* @__PURE__ */ jsx(
+      ErrorFallback,
+      {
+        details,
+        reset: this.reset,
+        showDetails: this.props.showDetails ?? false,
+        headingAs: this.props.headingAs ?? "h2",
+        className: this.props.className,
+        labels: this.props.labels
+      }
+    );
+  }
+}
+function ErrorFallback({
+  details,
+  reset,
+  showDetails,
+  headingAs,
+  className,
+  labels
+}) {
+  const text = useKitLabels("errorBoundary", DEFAULT_ERROR_BOUNDARY_LABELS, labels);
+  return /* @__PURE__ */ jsx(
+    EmptyState,
+    {
+      role: "alert",
+      tone: "danger",
+      headingAs,
+      className,
+      icon: /* @__PURE__ */ jsx(AlertTriangle, {}),
+      title: text.title,
+      hint: text.message,
+      action: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: reset, children: text.retry }),
+        showDetails && /* @__PURE__ */ jsx(Disclosure, { variant: "bare", title: text.details, className: "basis-full text-start", children: /* @__PURE__ */ jsxs("pre", { className: "max-h-60 overflow-auto whitespace-pre-wrap break-words text-xs text-[var(--text-secondary)]", children: [
+          details.message ? `${details.name}: ${details.message}` : details.name,
+          details.stack ? `
+
+${details.stack}` : null
+        ] }) })
+      ] })
+    }
+  );
+}
+export {
+  DEFAULT_ERROR_BOUNDARY_LABELS,
+  ErrorBoundary,
+  describeThrown
+};
+//# sourceMappingURL=error-boundary.js.map

package/dist/components/error-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/error-boundary.tsx"],"sourcesContent":["import { Component } from \"react\";\nimport type { ErrorInfo, ReactNode } from \"react\";\nimport { AlertTriangle } from \"lucide-react\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { Button, EmptyState } from \"./ui\";\nimport { Disclosure } from \"./disclosure\";\n\n/** The words of the default fallback. */\nexport interface ErrorBoundaryLabels {\n  /** The fallback's heading. */\n  title: string;\n  /** The line under it. */\n  message: string;\n  /** The button that clears the error and renders the children again. */\n  retry: string;\n  /** The disclosure that opens the error's own text (`showDetails`). */\n  details: string;\n}\n\nexport const DEFAULT_ERROR_BOUNDARY_LABELS: ErrorBoundaryLabels = {\n  title: \"Something went wrong\",\n  message: \"This part of the page could not be shown. Try again, or reload the page.\",\n  retry: \"Try again\",\n  details: \"Error details\",\n};\n\n/**\n * What was thrown, as flat strings, read ONCE when it arrives.\n *\n * React stores whatever was thrown, hostile or not — `throw { get message() { throw … } }`,\n * `throw { name: Symbol() }`, `throw undefined` — and reading one of those during the\n * fallback's own render would throw INSIDE the boundary, escalating to the next one up\n * (keksdose's error-boundary.tsx learned this as feedback #160: at the app level there is\n * none, and the result is the white screen the boundary exists to prevent).\n */\nexport interface ErrorBoundaryDetails {\n  name: string;\n  message: string;\n  stack?: string;\n}\n\nfunction read(get: () => unknown): string | undefined {\n  try {\n    const v = get();\n    return typeof v === \"string\" ? v : v === undefined || v === null ? undefined : String(v);\n  } catch {\n    return undefined;\n  }\n}\n\n/** {@link ErrorBoundaryDetails} of any thrown value, without ever throwing. */\nexport function describeThrown(error: unknown): ErrorBoundaryDetails {\n  if (typeof error === \"object\" && error !== null) {\n    const e = error as { name?: unknown; message?: unknown; stack?: unknown };\n    return {\n      name: read(() => e.name) ?? \"Error\",\n      message: read(() => e.message) ?? \"\",\n      stack: read(() => e.stack),\n    };\n  }\n  return { name: \"Error\", message: read(() => error) ?? \"\" };\n}\n\n/** What a render-prop `fallback` is handed. */\nexport interface ErrorBoundaryFallbackProps {\n  /** The thrown value, as it was thrown. Read it with care — see {@link describeThrown}. */\n  error: unknown;\n  details: ErrorBoundaryDetails;\n  /** Clear the error and render the children again. */\n  reset: () => void;\n}\n\nexport interface ErrorBoundaryProps {\n  children?: ReactNode;\n  /** Replaces the default fallback: a node, or a render function handed the error and\n   *  a `reset`. */\n  fallback?: ReactNode | ((props: ErrorBoundaryFallbackProps) => ReactNode);\n  /** Called once per caught error — log it, file a crash report. */\n  onError?: (error: unknown, info: ErrorInfo) => void;\n  /** Called when the error is cleared, by Retry, `reset` or a `resetKeys` change —\n   *  drop a cache, refetch. */\n  onReset?: () => void;\n  /**\n   * When any of these changes (compared with `Object.is`) AFTER an error was caught, the\n   * error is cleared and the children render again — a change in the same update that\n   * threw does not count (it is what the error was shown under) — pass the route path so leaving a broken page does not\n   * carry its fallback to the next one (keksdose's `resetKey`).\n   */\n  resetKeys?: ReadonlyArray<unknown>;\n  /** A disclosure under the message with the error's name, message and stack — for an\n   *  internal tool, or while developing. Off by default: a stack means nothing to a user. */\n  showDetails?: boolean;\n  /** The default fallback's heading level. Default `h2`: the fallback often IS the page. */\n  headingAs?: \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\";\n  /** Classes for the default fallback's box (`m-8 min-h-[400px]`, kastlan). */\n  className?: string;\n  labels?: Partial<ErrorBoundaryLabels>;\n}\n\ninterface ErrorBoundaryState {\n  /** A flag of its own, so `throw undefined` is still an error shown. */\n  failed: boolean;\n  error: unknown;\n  details: ErrorBoundaryDetails | null;\n}\n\nconst CLEAR: ErrorBoundaryState = { failed: false, error: null, details: null };\n\nfunction keysChanged(a: ReadonlyArray<unknown> | undefined, b: ReadonlyArray<unknown> | undefined): boolean {\n  if (a === b) return false;\n  if (!a || !b || a.length !== b.length) return true;\n  return a.some((v, i) => !Object.is(v, b[i]));\n}\n\n/**\n * Catch a render error below it and show a fallback instead of an empty page.\n *\n * kastlan (shared/components/error-boundary.tsx) and keksdose (app/error-boundary.tsx)\n * each built one on `EmptyState tone=\"danger\"`: a warning glyph, a title, a line of\n * explanation and a Retry. This is that fallback, translated through the provider\n * (`errorBoundary.*`), with the hooks an app hangs its own behaviour on — `onError`\n * for the crash report, `resetKeys` for the route change, `fallback` for anything else.\n *\n * The fallback is `role=\"alert\"`: a page replaced by an error is news, and a reader\n * that was on it is told.\n */\nexport class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {\n  state: ErrorBoundaryState = CLEAR;\n\n  static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState> {\n    return { failed: true, error, details: describeThrown(error) };\n  }\n\n  componentDidCatch(error: unknown, info: ErrorInfo): void {\n    this.props.onError?.(error, info);\n  }\n\n  componentDidUpdate(prev: ErrorBoundaryProps, prevState: ErrorBoundaryState): void {\n    // Only a change AFTER the error was caught clears it (react-error-boundary's rule).\n    // `prevState.failed` is false in the update that caught it: that update may well be\n    // the one that changed the keys too — a navigation to a page that throws, with\n    // `resetKeys={[pathname]}` — and resetting then would fire `onReset` for nothing and\n    // render the failing child a second time. From then on `prev.resetKeys` are the\n    // keys the error was shown under, so any change clears it.\n    if (this.state.failed && prevState.failed && keysChanged(prev.resetKeys, this.props.resetKeys)) {\n      this.reset();\n    }\n  }\n\n  reset = (): void => {\n    this.props.onReset?.();\n    this.setState(CLEAR);\n  };\n\n  render(): ReactNode {\n    const { failed, error, details } = this.state;\n    if (!failed || !details) return this.props.children;\n    const { fallback } = this.props;\n    if (typeof fallback === \"function\") return fallback({ error, details, reset: this.reset });\n    if (fallback !== undefined) return fallback;\n    return (\n      <ErrorFallback\n        details={details}\n        reset={this.reset}\n        showDetails={this.props.showDetails ?? false}\n        headingAs={this.props.headingAs ?? \"h2\"}\n        className={this.props.className}\n        labels={this.props.labels}\n      />\n    );\n  }\n}\n\nfunction ErrorFallback({\n  details,\n  reset,\n  showDetails,\n  headingAs,\n  className,\n  labels,\n}: {\n  details: ErrorBoundaryDetails;\n  reset: () => void;\n  showDetails: boolean;\n  headingAs: NonNullable<ErrorBoundaryProps[\"headingAs\"]>;\n  className?: string;\n  labels?: Partial<ErrorBoundaryLabels>;\n}) {\n  const text = useKitLabels(\"errorBoundary\", DEFAULT_ERROR_BOUNDARY_LABELS, labels);\n  return (\n    <EmptyState\n      role=\"alert\"\n      tone=\"danger\"\n      headingAs={headingAs}\n      className={className}\n      icon={<AlertTriangle />}\n      title={text.title}\n      hint={text.message}\n      action={\n        <>\n          <Button variant=\"secondary\" onClick={reset}>\n            {text.retry}\n          </Button>\n          {showDetails && (\n            <Disclosure variant=\"bare\" title={text.details} className=\"basis-full text-start\">\n              <pre className=\"max-h-60 overflow-auto whitespace-pre-wrap break-words text-xs text-[var(--text-secondary)]\">\n                {details.message ? `${details.name}: ${details.message}` : details.name}\n                {details.stack ? `\\n\\n${details.stack}` : null}\n              </pre>\n            </Disclosure>\n          )}\n        </>\n      }\n    />\n  );\n}\n"],"mappings":";AAiKM,SAsCE,UAtCF,KA4CQ,YA5CR;AAjKN,SAAS,iBAAiB;AAE1B,SAAS,qBAAqB;AAC9B,SAAS,oBAAoB;AAC7B,SAAS,QAAQ,kBAAkB;AACnC,SAAS,kBAAkB;AAcpB,MAAM,gCAAqD;AAAA,EAChE,OAAO;AAAA,EACP,SAAS;AAAA,EACT,OAAO;AAAA,EACP,SAAS;AACX;AAiBA,SAAS,KAAK,KAAwC;AACpD,MAAI;AACF,UAAM,IAAI,IAAI;AACd,WAAO,OAAO,MAAM,WAAW,IAAI,MAAM,UAAa,MAAM,OAAO,SAAY,OAAO,CAAC;AAAA,EACzF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,SAAS,eAAe,OAAsC;AACnE,MAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,UAAM,IAAI;AACV,WAAO;AAAA,MACL,MAAM,KAAK,MAAM,EAAE,IAAI,KAAK;AAAA,MAC5B,SAAS,KAAK,MAAM,EAAE,OAAO,KAAK;AAAA,MAClC,OAAO,KAAK,MAAM,EAAE,KAAK;AAAA,IAC3B;AAAA,EACF;AACA,SAAO,EAAE,MAAM,SAAS,SAAS,KAAK,MAAM,KAAK,KAAK,GAAG;AAC3D;AA6CA,MAAM,QAA4B,EAAE,QAAQ,OAAO,OAAO,MAAM,SAAS,KAAK;AAE9E,SAAS,YAAY,GAAuC,GAAgD;AAC1G,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,OAAQ,QAAO;AAC9C,SAAO,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;AAC7C;AAcO,MAAM,sBAAsB,UAAkD;AAAA,EACnF,QAA4B;AAAA,EAE5B,OAAO,yBAAyB,OAA6C;AAC3E,WAAO,EAAE,QAAQ,MAAM,OAAO,SAAS,eAAe,KAAK,EAAE;AAAA,EAC/D;AAAA,EAEA,kBAAkB,OAAgB,MAAuB;AACvD,SAAK,MAAM,UAAU,OAAO,IAAI;AAAA,EAClC;AAAA,EAEA,mBAAmB,MAA0B,WAAqC;AAOhF,QAAI,KAAK,MAAM,UAAU,UAAU,UAAU,YAAY,KAAK,WAAW,KAAK,MAAM,SAAS,GAAG;AAC9F,WAAK,MAAM;AAAA,IACb;AAAA,EACF;AAAA,EAEA,QAAQ,MAAY;AAClB,SAAK,MAAM,UAAU;AACrB,SAAK,SAAS,KAAK;AAAA,EACrB;AAAA,EAEA,SAAoB;AAClB,UAAM,EAAE,QAAQ,OAAO,QAAQ,IAAI,KAAK;AACxC,QAAI,CAAC,UAAU,CAAC,QAAS,QAAO,KAAK,MAAM;AAC3C,UAAM,EAAE,SAAS,IAAI,KAAK;AAC1B,QAAI,OAAO,aAAa,WAAY,QAAO,SAAS,EAAE,OAAO,SAAS,OAAO,KAAK,MAAM,CAAC;AACzF,QAAI,aAAa,OAAW,QAAO;AACnC,WACE;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA,OAAO,KAAK;AAAA,QACZ,aAAa,KAAK,MAAM,eAAe;AAAA,QACvC,WAAW,KAAK,MAAM,aAAa;AAAA,QACnC,WAAW,KAAK,MAAM;AAAA,QACtB,QAAQ,KAAK,MAAM;AAAA;AAAA,IACrB;AAAA,EAEJ;AACF;AAEA,SAAS,cAAc;AAAA,EACrB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAOG;AACD,QAAM,OAAO,aAAa,iBAAiB,+BAA+B,MAAM;AAChF,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,MAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA,MAAM,oBAAC,iBAAc;AAAA,MACrB,OAAO,KAAK;AAAA,MACZ,MAAM,KAAK;AAAA,MACX,QACE,iCACE;AAAA,4BAAC,UAAO,SAAQ,aAAY,SAAS,OAClC,eAAK,OACR;AAAA,QACC,eACC,oBAAC,cAAW,SAAQ,QAAO,OAAO,KAAK,SAAS,WAAU,yBACxD,+BAAC,SAAI,WAAU,+FACZ;AAAA,kBAAQ,UAAU,GAAG,QAAQ,IAAI,KAAK,QAAQ,OAAO,KAAK,QAAQ;AAAA,UAClE,QAAQ,QAAQ;AAAA;AAAA,EAAO,QAAQ,KAAK,KAAK;AAAA,WAC5C,GACF;AAAA,SAEJ;AAAA;AAAA,EAEJ;AAEJ;","names":[]}

package/dist/components/field.d.ts

@@ -14,6 +14,29 @@ interface FieldControlProps {
      *  is what a screen reader hears instead. */
     "aria-required": true | undefined;
 }
+/**
+ * The second argument of a `Field`'s render-prop children: what a GROUP needs that
+ * a single control does not. `htmlFor` names an `<input>`, but a `<label>` pointing
+ * at a `role="radiogroup"` div names nothing — so a group (a {@link ToggleGroup})
+ * takes `aria-labelledby={labelId}` instead. Kept out of {@link FieldControlProps}
+ * so the spread every existing control takes is unchanged.
+ */
+interface FieldRenderMeta {
+    /** The label element's id, or `undefined` when the field has no label. */
+    labelId: string | undefined;
+}
+/**
+ * Where the label is visible. `"visible"` (default); `"sr-only"`: never drawn, still
+ * the control's name; `"below-sm"` / `"below-md"` / `"below-lg"`: drawn only under
+ * that breakpoint and screen-reader-only from it up.
+ *
+ * For table-like editors — kastlan's journal entry lines
+ * (accounting/components/wizard/journal-entry-lines-step.tsx) — where a desktop
+ * row sits under column headers that already say "Account" and "Amount", but the
+ * phone layout stacks each line as a card and needs the labels back. The name stays
+ * on the control at every width; only the ink changes.
+ */
+type FieldLabelVisibility = "visible" | "sr-only" | "below-sm" | "below-md" | "below-lg";
 interface FieldProps {
     /** The label above the control. Omit it for a group whose control is labelled
      *  some other way; the hint and error still render. */
@@ -33,11 +56,14 @@ interface FieldProps {
     disabled?: boolean;
     /** The label's size: `sm` for a dense row, `md` otherwise. */
     labelSize?: "sm" | "md";
+    /** See {@link FieldLabelVisibility}. */
+    labelVisibility?: FieldLabelVisibility;
     /** Wrapper className. */
     className?: string;
-    /** The control. A function receives {@link FieldControlProps} to spread on it. */
-    children: ReactNode | ((control: FieldControlProps) => ReactNode);
+    /** The control. A function receives {@link FieldControlProps} to spread on it, and
+     *  {@link FieldRenderMeta} (the label's id, for a group). */
+    children: ReactNode | ((control: FieldControlProps, meta: FieldRenderMeta) => ReactNode);
 }
-declare function Field({ label, required, hint, error, htmlFor, disabled, labelSize, className, children, }: FieldProps): react.JSX.Element;
+declare function Field({ label, required, hint, error, htmlFor, disabled, labelSize, labelVisibility, className, children, }: FieldProps): react.JSX.Element;
 
-export { Field, type FieldControlProps, type FieldProps };
+export { Field, type FieldControlProps, type FieldLabelVisibility, type FieldProps, type FieldRenderMeta };

package/dist/components/field.js

@@ -3,6 +3,13 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { cn } from "../lib/cn.js";
 import { Label } from "./ui.js";
+const LABEL_VISIBILITY = {
+  visible: void 0,
+  "sr-only": "sr-only",
+  "below-sm": "sm:sr-only",
+  "below-md": "md:sr-only",
+  "below-lg": "lg:sr-only"
+};
 const isShown = (node) => node !== void 0 && node !== null && node !== false && node !== "";
 function Field({
   label,
@@ -12,6 +19,7 @@ function Field({
   htmlFor,
   disabled,
   labelSize,
+  labelVisibility = "visible",
   className,
   children
 }) {
@@ -19,6 +27,7 @@ function Field({
   const id = htmlFor ?? `${generated}-control`;
   const hintId = `${generated}-hint`;
   const errorId = `${generated}-error`;
+  const labelId = `${generated}-label`;
   const hasHint = isShown(hint);
   const hasError = isShown(error);
   const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
@@ -28,23 +37,37 @@ function Field({
     "aria-invalid": hasError || void 0,
     "aria-required": required || void 0
   };
-  return /* @__PURE__ */ jsxs("div", { "data-slot": "field", className: cn("grid gap-1.5", className), children: [
-    label !== void 0 && /* @__PURE__ */ jsx(
-      Label,
-      {
-        htmlFor: id,
-        required,
-        disabled,
-        size: labelSize,
-        "data-error": hasError || void 0,
-        className: "data-[error=true]:text-[var(--danger)]",
-        children: label
-      }
-    ),
-    typeof children === "function" ? children(control) : children,
-    hasHint && /* @__PURE__ */ jsx("p", { id: hintId, className: "text-[11px] leading-tight text-[var(--text-muted)]", children: hint }),
-    hasError && /* @__PURE__ */ jsx("p", { id: errorId, className: "text-[11px] leading-tight text-[var(--danger)]", children: error })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "field",
+      className: cn(
+        "grid gap-1.5",
+        // A hidden label is `position: absolute`; `relative` keeps its containing
+        // block here rather than the page's (see sr-only-containment.test).
+        labelVisibility !== "visible" && "relative",
+        className
+      ),
+      children: [
+        label !== void 0 && /* @__PURE__ */ jsx(
+          Label,
+          {
+            id: labelId,
+            htmlFor: id,
+            required,
+            disabled,
+            size: labelSize,
+            "data-error": hasError || void 0,
+            className: cn("data-[error=true]:text-[var(--danger)]", LABEL_VISIBILITY[labelVisibility]),
+            children: label
+          }
+        ),
+        typeof children === "function" ? children(control, { labelId: label !== void 0 ? labelId : void 0 }) : children,
+        hasHint && /* @__PURE__ */ jsx("p", { id: hintId, className: "text-[11px] leading-tight text-[var(--text-muted)]", children: hint }),
+        hasError && /* @__PURE__ */ jsx("p", { id: errorId, className: "text-[11px] leading-tight text-[var(--danger)]", children: error })
+      ]
+    }
+  );
 }
 export {
   Field

package/dist/components/field.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/field.tsx"],"sourcesContent":["/**\n * A field group with its label ABOVE the control: label, control, hint, error.\n *\n * ```tsx\n * <Field label=\"IBAN\" required hint=\"22 characters\" error={errors.iban}>\n *   {(ids) => <Input {...ids} value={iban} onChange={…} />}\n * </Field>\n * ```\n *\n * The kit's `Input` and `Select` float their label inside the field, and the pickers\n * draw theirs the same way. That is the wrong shape for a control the kit did not\n * render, a radio group, a range slider, or a form that sets its labels above the\n * fields throughout — which is what kastlan's wizards are, and why it kept its own\n * `WizardField` after the kit dropped the one it had never rendered. This is that\n * group, with the wiring the old one left to the caller: the label names the control\n * through `htmlFor`, and the control is described by the hint and the error that are\n * actually on screen.\n *\n * ## Wiring\n *\n * Pass a function as `children` and it receives {@link FieldControlProps} — `id`,\n * `aria-describedby`, `aria-invalid` and `aria-required` — to spread on the control.\n * Plain children render as they are, for a control that wires itself (a checkbox that\n * carries its own label, a group with `aria-labelledby`); `htmlFor` then points the\n * label at the control's own id, and the hint and error are on screen but describe\n * nothing — the same as the `WizardField` this replaces.\n *\n * ## Decoupled\n *\n * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain\n * value. Pass `wizard.fieldErrors.iban`, a step-local error, or\n * `fieldState.error?.message` from a `FormField` render — the markup is the same\n * whichever of them gates the step, so a step can move between them without its\n * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from\n * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)\n *\n * The error is NOT `role=\"alert\"`, for the reason the kit's `error` prop gives (see\n * `useFieldError` in components/ui.tsx): it is read when focus reaches the control.\n */\nimport { useId, type ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { Label } from \"./ui\";\n\n/** What a `Field` hands its render-prop children, to spread on the control. */\nexport interface FieldControlProps {\n  /** The id the label's `htmlFor` points at. */\n  id: string;\n  /** The ids of the hint and the error that are rendered, or `undefined` when\n   *  neither is. */\n  \"aria-describedby\": string | undefined;\n  /** `true` while the field has an error, `undefined` otherwise. */\n  \"aria-invalid\": true | undefined;\n  /** `true` when the field is `required`. The label's star is `aria-hidden`; this\n   *  is what a screen reader hears instead. */\n  \"aria-required\": true | undefined;\n}\n\nexport interface FieldProps {\n  /** The label above the control. Omit it for a group whose control is labelled\n   *  some other way; the hint and error still render. */\n  label?: ReactNode;\n  /** Draws the kit's required mark after the label, and sets `aria-required` on the\n   *  render-prop control. */\n  required?: boolean;\n  /** Muted helper text below the control. */\n  hint?: ReactNode;\n  /** The error below the control. `null`, `false` and `\"\"` are no error — what a\n   *  `touched && errors.x` evaluates to on the happy path. */\n  error?: ReactNode;\n  /** The control's id. Defaults to a generated one; set it when the control carries\n   *  its own id (plain children). */\n  htmlFor?: string;\n  /** Dims the label with its control. */\n  disabled?: boolean;\n  /** The label's size: `sm` for a dense row, `md` otherwise. */\n  labelSize?: \"sm\" | \"md\";\n  /** Wrapper className. */\n  className?: string;\n  /** The control. A function receives {@link FieldControlProps} to spread on it. */\n  children: ReactNode | ((control: FieldControlProps) => ReactNode);\n}\n\nconst isShown = (node: ReactNode) =>\n  node !== undefined && node !== null && node !== false && node !== \"\";\n\nexport function Field({\n  label,\n  required,\n  hint,\n  error,\n  htmlFor,\n  disabled,\n  labelSize,\n  className,\n  children,\n}: FieldProps) {\n  const generated = useId();\n  const id = htmlFor ?? `${generated}-control`;\n  const hintId = `${generated}-hint`;\n  const errorId = `${generated}-error`;\n  const hasHint = isShown(hint);\n  const hasError = isShown(error);\n  const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(\" \");\n  const control: FieldControlProps = {\n    id,\n    \"aria-describedby\": describedBy || undefined,\n    \"aria-invalid\": hasError || undefined,\n    \"aria-required\": required || undefined,\n  };\n  return (\n    <div data-slot=\"field\" className={cn(\"grid gap-1.5\", className)}>\n      {label !== undefined && (\n        <Label\n          htmlFor={id}\n          required={required}\n          disabled={disabled}\n          size={labelSize}\n          data-error={hasError || undefined}\n          className=\"data-[error=true]:text-[var(--danger)]\"\n        >\n          {label}\n        </Label>\n      )}\n      {typeof children === \"function\" ? children(control) : children}\n      {hasHint && (\n        <p id={hintId} className=\"text-[11px] leading-tight text-[var(--text-muted)]\">\n          {hint}\n        </p>\n      )}\n      {hasError && (\n        <p id={errorId} className=\"text-[11px] leading-tight text-[var(--danger)]\">\n          {error}\n        </p>\n      )}\n    </div>\n  );\n}\n"],"mappings":";AA8GI,SAEI,KAFJ;AAvEJ,SAAS,aAA6B;AACtC,SAAS,UAAU;AACnB,SAAS,aAAa;AAyCtB,MAAM,UAAU,CAAC,SACf,SAAS,UAAa,SAAS,QAAQ,SAAS,SAAS,SAAS;AAE7D,SAAS,MAAM;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAe;AACb,QAAM,YAAY,MAAM;AACxB,QAAM,KAAK,WAAW,GAAG,SAAS;AAClC,QAAM,SAAS,GAAG,SAAS;AAC3B,QAAM,UAAU,GAAG,SAAS;AAC5B,QAAM,UAAU,QAAQ,IAAI;AAC5B,QAAM,WAAW,QAAQ,KAAK;AAC9B,QAAM,cAAc,CAAC,WAAW,QAAQ,YAAY,OAAO,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG;AACrF,QAAM,UAA6B;AAAA,IACjC;AAAA,IACA,oBAAoB,eAAe;AAAA,IACnC,gBAAgB,YAAY;AAAA,IAC5B,iBAAiB,YAAY;AAAA,EAC/B;AACA,SACE,qBAAC,SAAI,aAAU,SAAQ,WAAW,GAAG,gBAAgB,SAAS,GAC3D;AAAA,cAAU,UACT;AAAA,MAAC;AAAA;AAAA,QACC,SAAS;AAAA,QACT;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN,cAAY,YAAY;AAAA,QACxB,WAAU;AAAA,QAET;AAAA;AAAA,IACH;AAAA,IAED,OAAO,aAAa,aAAa,SAAS,OAAO,IAAI;AAAA,IACrD,WACC,oBAAC,OAAE,IAAI,QAAQ,WAAU,sDACtB,gBACH;AAAA,IAED,YACC,oBAAC,OAAE,IAAI,SAAS,WAAU,kDACvB,iBACH;AAAA,KAEJ;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/field.tsx"],"sourcesContent":["/**\n * A field group with its label ABOVE the control: label, control, hint, error.\n *\n * ```tsx\n * <Field label=\"IBAN\" required hint=\"22 characters\" error={errors.iban}>\n *   {(ids) => <Input {...ids} value={iban} onChange={…} />}\n * </Field>\n * ```\n *\n * The kit's `Input` and `Select` float their label inside the field, and the pickers\n * draw theirs the same way. That is the wrong shape for a control the kit did not\n * render, a radio group, a range slider, or a form that sets its labels above the\n * fields throughout — which is what kastlan's wizards are, and why it kept its own\n * `WizardField` after the kit dropped the one it had never rendered. This is that\n * group, with the wiring the old one left to the caller: the label names the control\n * through `htmlFor`, and the control is described by the hint and the error that are\n * actually on screen.\n *\n * ## Wiring\n *\n * Pass a function as `children` and it receives {@link FieldControlProps} — `id`,\n * `aria-describedby`, `aria-invalid` and `aria-required` — to spread on the control.\n * Plain children render as they are, for a control that wires itself (a checkbox that\n * carries its own label, a group with `aria-labelledby`); `htmlFor` then points the\n * label at the control's own id, and the hint and error are on screen but describe\n * nothing — the same as the `WizardField` this replaces.\n *\n * ## Decoupled\n *\n * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain\n * value. Pass `wizard.fieldErrors.iban`, a step-local error, or\n * `fieldState.error?.message` from a `FormField` render — the markup is the same\n * whichever of them gates the step, so a step can move between them without its\n * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from\n * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)\n *\n * The error is NOT `role=\"alert\"`, for the reason the kit's `error` prop gives (see\n * `useFieldError` in components/ui.tsx): it is read when focus reaches the control.\n */\nimport { useId, type ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { Label } from \"./ui\";\n\n/** What a `Field` hands its render-prop children, to spread on the control. */\nexport interface FieldControlProps {\n  /** The id the label's `htmlFor` points at. */\n  id: string;\n  /** The ids of the hint and the error that are rendered, or `undefined` when\n   *  neither is. */\n  \"aria-describedby\": string | undefined;\n  /** `true` while the field has an error, `undefined` otherwise. */\n  \"aria-invalid\": true | undefined;\n  /** `true` when the field is `required`. The label's star is `aria-hidden`; this\n   *  is what a screen reader hears instead. */\n  \"aria-required\": true | undefined;\n}\n\n/**\n * The second argument of a `Field`'s render-prop children: what a GROUP needs that\n * a single control does not. `htmlFor` names an `<input>`, but a `<label>` pointing\n * at a `role=\"radiogroup\"` div names nothing — so a group (a {@link ToggleGroup})\n * takes `aria-labelledby={labelId}` instead. Kept out of {@link FieldControlProps}\n * so the spread every existing control takes is unchanged.\n */\nexport interface FieldRenderMeta {\n  /** The label element's id, or `undefined` when the field has no label. */\n  labelId: string | undefined;\n}\n\n/**\n * Where the label is visible. `\"visible\"` (default); `\"sr-only\"`: never drawn, still\n * the control's name; `\"below-sm\"` / `\"below-md\"` / `\"below-lg\"`: drawn only under\n * that breakpoint and screen-reader-only from it up.\n *\n * For table-like editors — kastlan's journal entry lines\n * (accounting/components/wizard/journal-entry-lines-step.tsx) — where a desktop\n * row sits under column headers that already say \"Account\" and \"Amount\", but the\n * phone layout stacks each line as a card and needs the labels back. The name stays\n * on the control at every width; only the ink changes.\n */\nexport type FieldLabelVisibility = \"visible\" | \"sr-only\" | \"below-sm\" | \"below-md\" | \"below-lg\";\n\n// Literal class strings so Tailwind's scanner sees each one.\nconst LABEL_VISIBILITY: Record<FieldLabelVisibility, string | undefined> = {\n  visible: undefined,\n  \"sr-only\": \"sr-only\",\n  \"below-sm\": \"sm:sr-only\",\n  \"below-md\": \"md:sr-only\",\n  \"below-lg\": \"lg:sr-only\",\n};\n\nexport interface FieldProps {\n  /** The label above the control. Omit it for a group whose control is labelled\n   *  some other way; the hint and error still render. */\n  label?: ReactNode;\n  /** Draws the kit's required mark after the label, and sets `aria-required` on the\n   *  render-prop control. */\n  required?: boolean;\n  /** Muted helper text below the control. */\n  hint?: ReactNode;\n  /** The error below the control. `null`, `false` and `\"\"` are no error — what a\n   *  `touched && errors.x` evaluates to on the happy path. */\n  error?: ReactNode;\n  /** The control's id. Defaults to a generated one; set it when the control carries\n   *  its own id (plain children). */\n  htmlFor?: string;\n  /** Dims the label with its control. */\n  disabled?: boolean;\n  /** The label's size: `sm` for a dense row, `md` otherwise. */\n  labelSize?: \"sm\" | \"md\";\n  /** See {@link FieldLabelVisibility}. */\n  labelVisibility?: FieldLabelVisibility;\n  /** Wrapper className. */\n  className?: string;\n  /** The control. A function receives {@link FieldControlProps} to spread on it, and\n   *  {@link FieldRenderMeta} (the label's id, for a group). */\n  children: ReactNode | ((control: FieldControlProps, meta: FieldRenderMeta) => ReactNode);\n}\n\nconst isShown = (node: ReactNode) =>\n  node !== undefined && node !== null && node !== false && node !== \"\";\n\nexport function Field({\n  label,\n  required,\n  hint,\n  error,\n  htmlFor,\n  disabled,\n  labelSize,\n  labelVisibility = \"visible\",\n  className,\n  children,\n}: FieldProps) {\n  const generated = useId();\n  const id = htmlFor ?? `${generated}-control`;\n  const hintId = `${generated}-hint`;\n  const errorId = `${generated}-error`;\n  const labelId = `${generated}-label`;\n  const hasHint = isShown(hint);\n  const hasError = isShown(error);\n  const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(\" \");\n  const control: FieldControlProps = {\n    id,\n    \"aria-describedby\": describedBy || undefined,\n    \"aria-invalid\": hasError || undefined,\n    \"aria-required\": required || undefined,\n  };\n  return (\n    <div\n      data-slot=\"field\"\n      className={cn(\n        \"grid gap-1.5\",\n        // A hidden label is `position: absolute`; `relative` keeps its containing\n        // block here rather than the page's (see sr-only-containment.test).\n        labelVisibility !== \"visible\" && \"relative\",\n        className,\n      )}\n    >\n      {label !== undefined && (\n        <Label\n          id={labelId}\n          htmlFor={id}\n          required={required}\n          disabled={disabled}\n          size={labelSize}\n          data-error={hasError || undefined}\n          className={cn(\"data-[error=true]:text-[var(--danger)]\", LABEL_VISIBILITY[labelVisibility])}\n        >\n          {label}\n        </Label>\n      )}\n      {typeof children === \"function\"\n        ? children(control, { labelId: label !== undefined ? labelId : undefined })\n        : children}\n      {hasHint && (\n        <p id={hintId} className=\"text-[11px] leading-tight text-[var(--text-muted)]\">\n          {hint}\n        </p>\n      )}\n      {hasError && (\n        <p id={errorId} className=\"text-[11px] leading-tight text-[var(--danger)]\">\n          {error}\n        </p>\n      )}\n    </div>\n  );\n}\n"],"mappings":";AAqJI,SAWI,KAXJ;AA9GJ,SAAS,aAA6B;AACtC,SAAS,UAAU;AACnB,SAAS,aAAa;AA0CtB,MAAM,mBAAqE;AAAA,EACzE,SAAS;AAAA,EACT,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,YAAY;AACd;AA8BA,MAAM,UAAU,CAAC,SACf,SAAS,UAAa,SAAS,QAAQ,SAAS,SAAS,SAAS;AAE7D,SAAS,MAAM;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB;AAAA,EAClB;AAAA,EACA;AACF,GAAe;AACb,QAAM,YAAY,MAAM;AACxB,QAAM,KAAK,WAAW,GAAG,SAAS;AAClC,QAAM,SAAS,GAAG,SAAS;AAC3B,QAAM,UAAU,GAAG,SAAS;AAC5B,QAAM,UAAU,GAAG,SAAS;AAC5B,QAAM,UAAU,QAAQ,IAAI;AAC5B,QAAM,WAAW,QAAQ,KAAK;AAC9B,QAAM,cAAc,CAAC,WAAW,QAAQ,YAAY,OAAO,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG;AACrF,QAAM,UAA6B;AAAA,IACjC;AAAA,IACA,oBAAoB,eAAe;AAAA,IACnC,gBAAgB,YAAY;AAAA,IAC5B,iBAAiB,YAAY;AAAA,EAC/B;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,WAAW;AAAA,QACT;AAAA;AAAA;AAAA,QAGA,oBAAoB,aAAa;AAAA,QACjC;AAAA,MACF;AAAA,MAEC;AAAA,kBAAU,UACT;AAAA,UAAC;AAAA;AAAA,YACC,IAAI;AAAA,YACJ,SAAS;AAAA,YACT;AAAA,YACA;AAAA,YACA,MAAM;AAAA,YACN,cAAY,YAAY;AAAA,YACxB,WAAW,GAAG,0CAA0C,iBAAiB,eAAe,CAAC;AAAA,YAExF;AAAA;AAAA,QACH;AAAA,QAED,OAAO,aAAa,aACjB,SAAS,SAAS,EAAE,SAAS,UAAU,SAAY,UAAU,OAAU,CAAC,IACxE;AAAA,QACH,WACC,oBAAC,OAAE,IAAI,QAAQ,WAAU,sDACtB,gBACH;AAAA,QAED,YACC,oBAAC,OAAE,IAAI,SAAS,WAAU,kDACvB,iBACH;AAAA;AAAA;AAAA,EAEJ;AAEJ;","names":[]}