@eifi1/ui-kit 0.21.0 → 0.23.0

package/dist/components/iban-input.js

@@ -0,0 +1,125 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { forwardRef, useCallback, useLayoutEffect, useRef, useState } from "react";
+import { useKitLabels } from "../i18n/kit-labels.js";
+import { cn } from "../lib/cn.js";
+import { IBAN_LENGTHS, compactIban, formatIban, ibanProblem } from "../lib/iban.js";
+import { assignRef, hasMessage } from "./choice-parts.js";
+import { Input } from "./ui.js";
+const DEFAULT_IBAN_INPUT_LABELS = {
+  format: "An IBAN starts with a two-letter country code and two check digits.",
+  country: (code) => `\u201C${code}\u201D is not the country code of an IBAN.`,
+  length: (actual, expected) => `An IBAN from this country has ${expected} characters \u2014 this one has ${actual}.`,
+  checksum: "The check digits don\u2019t match \u2014 a character is probably mistyped.",
+  qrRequired: "This is a regular IBAN. A QR-bill needs the account\u2019s QR-IBAN.",
+  qrNotAllowed: "This is a QR-IBAN, which only receives QR-bill payments. Enter the account\u2019s regular IBAN."
+};
+function useIbanInputLabels(prop) {
+  const labels = useKitLabels("ibanInput", DEFAULT_IBAN_INPUT_LABELS, prop);
+  return labels;
+}
+const alnumCount = (text) => text.replace(/[^0-9A-Za-z]/g, "").length;
+function indexAfter(text, count) {
+  if (count <= 0) return 0;
+  let seen = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (/[0-9A-Za-z]/.test(text[i])) seen += 1;
+    if (seen === count) return i + 1;
+  }
+  return text.length;
+}
+function visibleProblem(compact, kind, focused) {
+  if (compact === "") return null;
+  const problem = ibanProblem(compact, kind);
+  if (problem === null || !focused) return problem;
+  if (compact.length < 4) return null;
+  if (problem === "format" || problem === "country") return problem;
+  return compact.length >= IBAN_LENGTHS[compact.slice(0, 2)] ? problem : null;
+}
+function messageFor(problem, compact, labels) {
+  switch (problem) {
+    case "format":
+      return labels.format;
+    case "country":
+      return labels.country(compact.slice(0, 2));
+    case "length":
+      return labels.length(compact.length, IBAN_LENGTHS[compact.slice(0, 2)]);
+    case "checksum":
+      return labels.checksum;
+    case "qrRequired":
+      return labels.qrRequired;
+    case "qrNotAllowed":
+      return labels.qrNotAllowed;
+  }
+}
+const IbanInput = forwardRef(function IbanInput2({ value, onValueChange, onChange, onFocus, onBlur, kind = "any", labels, error, inputClassName, ...rest }, ref) {
+  const text = useIbanInputLabels(labels);
+  const compact = compactIban(value);
+  const shown = formatIban(compact);
+  const [focused, setFocused] = useState(false);
+  const innerRef = useRef(null);
+  const caretRef = useRef(null);
+  const setRefs = useCallback(
+    (el) => {
+      innerRef.current = el;
+      assignRef(ref, el);
+    },
+    [ref]
+  );
+  useLayoutEffect(() => {
+    const el = innerRef.current;
+    const count = caretRef.current;
+    if (el === null || count === null) return;
+    caretRef.current = null;
+    if (el.ownerDocument.activeElement !== el) return;
+    const at = indexAfter(el.value, count);
+    el.setSelectionRange(at, at);
+  });
+  const handleChange = (e) => {
+    onChange?.(e);
+    const el = e.target;
+    const raw = el.value;
+    const next = compactIban(raw);
+    const dropped = alnumCount(raw) - next.length;
+    const count = Math.max(0, alnumCount(raw.slice(0, el.selectionStart ?? raw.length)) - dropped);
+    if (next === compact) {
+      el.value = shown;
+      const at = indexAfter(shown, count);
+      el.setSelectionRange(at, at);
+    } else {
+      caretRef.current = count;
+    }
+    onValueChange?.(next);
+  };
+  const problem = visibleProblem(compact, kind, focused);
+  return /* @__PURE__ */ jsx(
+    Input,
+    {
+      ref: setRefs,
+      ...rest,
+      type: "text",
+      value: shown,
+      onChange: handleChange,
+      onFocus: (e) => {
+        setFocused(true);
+        onFocus?.(e);
+      },
+      onBlur: (e) => {
+        setFocused(false);
+        onBlur?.(e);
+      },
+      autoComplete: rest.autoComplete ?? "off",
+      autoCapitalize: rest.autoCapitalize ?? "characters",
+      autoCorrect: rest.autoCorrect ?? "off",
+      spellCheck: rest.spellCheck ?? false,
+      error: hasMessage(error) ? error : problem ? messageFor(problem, compact, text) : void 0,
+      inputClassName: cn("tabular-nums", inputClassName)
+    }
+  );
+});
+IbanInput.displayName = "IbanInput";
+export {
+  DEFAULT_IBAN_INPUT_LABELS,
+  IbanInput
+};
+//# sourceMappingURL=iban-input.js.map

package/dist/components/iban-input.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/iban-input.tsx"],"sourcesContent":["import { forwardRef, useCallback, useLayoutEffect, useRef, useState } from \"react\";\nimport type { ChangeEvent, FocusEvent, ReactNode } from \"react\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { cn } from \"../lib/cn\";\nimport { IBAN_LENGTHS, compactIban, formatIban, ibanProblem } from \"../lib/iban\";\nimport type { IbanKind, IbanProblem } from \"../lib/iban\";\nimport { assignRef, hasMessage } from \"./choice-parts\";\nimport { Input, type InputProps } from \"./ui\";\n\n// ── Labels ────────────────────────────────────────────────────────────────────\n\n/** The messages {@link IbanInput} shows under itself, one per {@link IbanProblem}. */\nexport interface IbanInputLabels {\n  /** The value does not start with a two-letter country code and two check digits. */\n  format: string;\n  /** The first two letters are no country in the IBAN registry. `code` is those two\n   *  letters, as typed (upper case). */\n  country: (code: string) => string;\n  /** The wrong length for the country: `actual` characters typed, `expected` for that\n   *  country (spaces not counted in either). */\n  length: (actual: number, expected: number) => string;\n  /** The mod-97 check digits do not match — a mistyped or swapped character. */\n  checksum: string;\n  /** `kind=\"qr\"`: a valid IBAN, but not a QR-IBAN. */\n  qrRequired: string;\n  /** `kind=\"plain\"`: a QR-IBAN, which cannot receive an ordinary transfer. */\n  qrNotAllowed: string;\n}\n\nexport const DEFAULT_IBAN_INPUT_LABELS: IbanInputLabels = {\n  format: \"An IBAN starts with a two-letter country code and two check digits.\",\n  country: (code) => `“${code}” is not the country code of an IBAN.`,\n  length: (actual, expected) =>\n    `An IBAN from this country has ${expected} characters — this one has ${actual}.`,\n  checksum: \"The check digits don’t match — a character is probably mistyped.\",\n  qrRequired: \"This is a regular IBAN. A QR-bill needs the account’s QR-IBAN.\",\n  qrNotAllowed: \"This is a QR-IBAN, which only receives QR-bill payments. Enter the account’s regular IBAN.\",\n};\n\n/**\n * The `ibanInput` namespace: prop > `<UiKitProvider labels>` > English (0.22.0).\n */\nfunction useIbanInputLabels(prop: Partial<IbanInputLabels> | undefined): IbanInputLabels {\n  const labels: IbanInputLabels = useKitLabels(\"ibanInput\", DEFAULT_IBAN_INPUT_LABELS, prop);\n  return labels;\n}\n\n// ── Helpers ───────────────────────────────────────────────────────────────────\n\nconst alnumCount = (text: string) => text.replace(/[^0-9A-Za-z]/g, \"\").length;\n\n/** The index just after the `count`-th letter or digit of `text` — where the caret\n *  goes once the grouping has moved the characters it was between. */\nfunction indexAfter(text: string, count: number): number {\n  if (count <= 0) return 0;\n  let seen = 0;\n  for (let i = 0; i < text.length; i++) {\n    if (/[0-9A-Za-z]/.test(text[i])) seen += 1;\n    if (seen === count) return i + 1;\n  }\n  return text.length;\n}\n\n/**\n * The problem worth SHOWING right now. Settled (not focused): whatever is wrong. While\n * typing: only what more typing cannot fix — a broken start or an unknown country from\n * the fourth character, and the rest once the country's full length is there. A\n * half-typed IBAN is not wrong, and a field that says \"wrong length\" from the first\n * keystroke is a field people learn to ignore.\n */\nfunction visibleProblem(compact: string, kind: IbanKind, focused: boolean): IbanProblem | null {\n  if (compact === \"\") return null;\n  const problem = ibanProblem(compact, kind);\n  if (problem === null || !focused) return problem;\n  if (compact.length < 4) return null;\n  if (problem === \"format\" || problem === \"country\") return problem;\n  return compact.length >= IBAN_LENGTHS[compact.slice(0, 2)]! ? problem : null;\n}\n\nfunction messageFor(problem: IbanProblem, compact: string, labels: IbanInputLabels): string {\n  switch (problem) {\n    case \"format\":\n      return labels.format;\n    case \"country\":\n      return labels.country(compact.slice(0, 2));\n    case \"length\":\n      return labels.length(compact.length, IBAN_LENGTHS[compact.slice(0, 2)]!);\n    case \"checksum\":\n      return labels.checksum;\n    case \"qrRequired\":\n      return labels.qrRequired;\n    case \"qrNotAllowed\":\n      return labels.qrNotAllowed;\n  }\n}\n\n// ── Component ─────────────────────────────────────────────────────────────────\n\nexport interface IbanInputProps extends Omit<InputProps, \"type\" | \"value\" | \"defaultValue\"> {\n  /** The IBAN, compact or not — it is shown in groups of four either way. `\"\"` is\n   *  \"no IBAN\". */\n  value: string;\n  /** The compact, upper-case IBAN (the electronic format, what to store) on every\n   *  change — valid or not: a half-typed IBAN is still the field's value. Plain\n   *  `onChange` still fires alongside it with the raw event, whose text is the GROUPED\n   *  one, so bind this rather than `onChange` to a form. */\n  onValueChange?: (value: string) => void;\n  /** Which IBANs the field accepts. Default `\"any\"`. `\"qr\"` / `\"plain\"`: see\n   *  {@link IbanKind} — and why the difference matters, {@link isQrIban}. */\n  kind?: IbanKind;\n  /** The messages, per field. See {@link IbanInputLabels}. */\n  labels?: Partial<IbanInputLabels>;\n  /** The caller's own message, shown INSTEAD of the built-in one while it is set (a\n   *  server's \"this account is already on file\"). `null`, `false` and `\"\"` are no\n   *  message, so `touched && errors.iban` can be passed as it is. */\n  error?: ReactNode;\n}\n\n/**\n * An IBAN field (kastlan, keksdose): typed in any shape, shown in groups of four,\n * reported compact.\n *\n * Both apps had a text field and a regex. What that left out is everything between\n * the keyboard and the stored value: a pasted \"ch09 0000-0000…\" stayed lower case\n * with its hyphens, the grouping that makes 21 characters checkable by eye was\n * missing, and a wrong IBAN was found out by the bank. Here:\n *\n *  - **Grouped as you type.** The field shows the paper format ({@link formatIban});\n *    spaces, hyphens and lower case in what is typed or pasted are folded away, and\n *    the caret stays between the same two characters while the groups move around it.\n *  - **Compact out.** `onValueChange` gets the electronic format — upper case, no\n *    spaces — which is the one to store and to compare.\n *  - **Checked, never blocked.** A wrong country, length or checksum shows a message\n *    under the field, through the kit's `error` (so it is the field's\n *    `aria-describedby` and paints it), but every keystroke still lands: a field that\n *    refuses characters cannot be corrected one character at a time. While the field\n *    has focus only what more typing cannot fix is shown; the rest waits for the full\n *    length or for blur. Whether the field is REQUIRED stays the form's rule — an empty\n *    field says nothing.\n *  - **QR-IBAN or not** (kastlan): `kind=\"qr\"` refuses a regular IBAN and\n *    `kind=\"plain\"` refuses a QR-IBAN — a QR-bill can only be paid to a QR-IBAN, and a\n *    QR-IBAN can receive nothing else. See {@link isQrIban}.\n *\n * It is {@link Input} underneath, so `label`, `hint`, `error`, `invalid` and the rest\n * are Input's own and the field reads like every other. A form that must not submit\n * an invalid IBAN checks {@link isValidIban} / {@link ibanProblem} itself — the field\n * shows the problem but does not own the submit.\n */\nexport const IbanInput = forwardRef<HTMLInputElement, IbanInputProps>(function IbanInput(\n  { value, onValueChange, onChange, onFocus, onBlur, kind = \"any\", labels, error, inputClassName, ...rest },\n  ref,\n) {\n  const text = useIbanInputLabels(labels);\n  const compact = compactIban(value);\n  const shown = formatIban(compact);\n  const [focused, setFocused] = useState(false);\n  const innerRef = useRef<HTMLInputElement | null>(null);\n  // Letters and digits before the caret, kept across the re-render that regroups.\n  const caretRef = useRef<number | null>(null);\n  const setRefs = useCallback(\n    (el: HTMLInputElement | null) => {\n      innerRef.current = el;\n      assignRef(ref, el);\n    },\n    [ref],\n  );\n\n  // Every render: when a change moved the groups, put the caret back after the same\n  // character it followed. Only while focused — a value set from outside moves nothing.\n  useLayoutEffect(() => {\n    const el = innerRef.current;\n    const count = caretRef.current;\n    if (el === null || count === null) return;\n    caretRef.current = null;\n    if (el.ownerDocument.activeElement !== el) return;\n    const at = indexAfter(el.value, count);\n    el.setSelectionRange(at, at);\n  });\n\n  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {\n    onChange?.(e);\n    const el = e.target;\n    const raw = el.value;\n    const next = compactIban(raw);\n    // Characters compactIban dropped from the front (a pasted \"IBAN \" label) are not\n    // in the value, so they are not counted before the caret either.\n    const dropped = alnumCount(raw) - next.length;\n    const count = Math.max(0, alnumCount(raw.slice(0, el.selectionStart ?? raw.length)) - dropped);\n    if (next === compact) {\n      // Nothing the value holds changed — a space typed, a group's space deleted — so\n      // no re-render will come to regroup it. Regroup now, and keep the caret: after\n      // a Backspace on a group's space, that is just before it.\n      el.value = shown;\n      const at = indexAfter(shown, count);\n      el.setSelectionRange(at, at);\n    } else {\n      caretRef.current = count;\n    }\n    onValueChange?.(next);\n  };\n\n  const problem = visibleProblem(compact, kind, focused);\n  return (\n    <Input\n      ref={setRefs}\n      {...rest}\n      type=\"text\"\n      value={shown}\n      onChange={handleChange}\n      onFocus={(e: FocusEvent<HTMLInputElement>) => {\n        setFocused(true);\n        onFocus?.(e);\n      }}\n      onBlur={(e: FocusEvent<HTMLInputElement>) => {\n        setFocused(false);\n        onBlur?.(e);\n      }}\n      autoComplete={rest.autoComplete ?? \"off\"}\n      autoCapitalize={rest.autoCapitalize ?? \"characters\"}\n      autoCorrect={rest.autoCorrect ?? \"off\"}\n      spellCheck={rest.spellCheck ?? false}\n      // ALWAYS passed, even while there is no message: a field that takes `error`\n      // keeps its box, so the message coming and going under the caret never remounts\n      // the input (see Input's FieldGroup) — this one comes and goes as you type.\n      error={hasMessage(error) ? error : problem ? messageFor(problem, compact, text) : undefined}\n      // Groups of four line up only when every digit is the same width.\n      inputClassName={cn(\"tabular-nums\", inputClassName)}\n    />\n  );\n});\nIbanInput.displayName = \"IbanInput\";\n"],"mappings":"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","names":["IbanInput"]}

package/dist/components/icon-picker.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentType, ComponentPropsWithoutRef } from 'react';
+import { ComponentType, ReactNode, ComponentPropsWithoutRef } from 'react';
 import { TileSize } from './tile-radio.js';
 
 interface IconPickerLabels {
@@ -31,7 +31,16 @@ interface IconOption<T extends string> {
     /** A remark read after the name and shown under it in the bubble ("used by
      *  Leisure"). The tile wears a dot while it has one. */
     note?: string;
+    /** Out of the choice and out of reach — skipped by the arrow keys and Tab. With a
+     *  `disabledReason` the tile stays reachable instead and says why. */
     disabled?: boolean;
+    /**
+     * Why THIS symbol cannot be chosen right now — {@link SwatchOption.disabledReason}'s
+     * twin: the tile is `aria-disabled` but reachable by Tab and the arrow keys, the reason
+     * shows in its bubble under its name and describes it, and choosing it does nothing.
+     * Wins over `disabled`. Kept through a search like any other tile.
+     */
+    disabledReason?: ReactNode;
 }
 interface IconPickerProps<T extends string> extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "children" | "defaultValue"> {
     options: IconOption<T>[];
@@ -65,6 +74,16 @@ interface IconPickerProps<T extends string> extends Omit<ComponentPropsWithoutRe
     tileClassName?: string;
     disabled?: boolean;
     labels?: Partial<IconPickerLabels>;
+    /**
+     * An 11px static label in a strip over the picker, naming the grid — keksdose K2,
+     * {@link SwatchPickerProps.label}'s twin: a symbol picker standing in a form row
+     * beside labelled fields, with its label on their line. With `searchable` the strip
+     * is over the search box too, which keeps its own name. With a label, `className`
+     * styles the wrapper.
+     */
+    label?: ReactNode;
+    /** A {@link FieldHint} beside the label. Only with `label`. */
+    hint?: ReactNode;
 }
 /**
  * A grid of symbols that is one radio group, with an optional search.
@@ -76,6 +95,6 @@ interface IconPickerProps<T extends string> extends Omit<ComponentPropsWithoutRe
  * Keyboard is {@link SwatchPicker}'s: one tab stop, arrows to move (flipped in a
  * right-to-left page), Home and End.
  */
-declare function IconPicker<T extends string>({ options, value, onChange, allowNone, mixed, activation, searchable, size, tileClassName, disabled, labels, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: IconPickerProps<T>): react.JSX.Element;
+declare function IconPicker<T extends string>({ options, value, onChange, allowNone, mixed, activation, searchable, size, tileClassName, disabled, labels, label, hint, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: IconPickerProps<T>): react.JSX.Element;
 
 export { DEFAULT_ICON_PICKER_LABELS, type IconOption, IconPicker, type IconPickerLabels, type IconPickerProps };

package/dist/components/icon-picker.js

@@ -5,6 +5,7 @@ import { cn } from "../lib/cn.js";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
 import { SearchField } from "./search-field.js";
 import { TILE_SIZE, TileRadioGroup } from "./tile-radio.js";
+import { hasContent, LabelStrip } from "./field-parts.js";
 const DEFAULT_ICON_PICKER_LABELS = {
   none: "No icon",
   mixed: "Mixed: the selected items have different icons",
@@ -27,6 +28,8 @@ function IconPicker({
   tileClassName,
   disabled = false,
   labels,
+  label,
+  hint,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
@@ -37,6 +40,8 @@ function IconPicker({
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const locale = useKitLocale();
   const mixedId = useId();
+  const labelId = useId();
+  const labelled = hasContent(label);
   const [query, setQuery] = useState("");
   const needle = fold(query.trim(), locale);
   const visible = useMemo(
@@ -50,9 +55,15 @@ function IconPicker({
     // "None" stays through a search: it is the way back to no icon, and it matches
     // no word anybody would type for it.
     ...allowNone ? [{ key: null, label: text.none }] : [],
-    ...visible.map((o) => ({ key: o.value, label: o.label, note: o.note, disabled: o.disabled }))
+    ...visible.map((o) => ({
+      key: o.value,
+      label: o.label,
+      note: o.note,
+      disabled: o.disabled,
+      disabledReason: o.disabledReason
+    }))
   ];
-  return /* @__PURE__ */ jsxs("div", { ...rest, className: cn("space-y-2", className), children: [
+  const picker = /* @__PURE__ */ jsxs("div", { ...rest, className: cn("space-y-2", !labelled && className), children: [
     searchable && /* @__PURE__ */ jsx(
       SearchField,
       {
@@ -68,7 +79,7 @@ function IconPicker({
       {
         role: "radiogroup",
         "aria-label": ariaLabel,
-        "aria-labelledby": ariaLabelledBy,
+        "aria-labelledby": labelled && ariaLabel === void 0 && ariaLabelledBy === void 0 ? labelId : ariaLabelledBy,
         "aria-describedby": [ariaDescribedBy, mixed && mixedId].filter(Boolean).join(" ") || void 0,
         "aria-disabled": disabled || void 0,
         className: "flex flex-wrap items-center gap-1.5",
@@ -77,7 +88,9 @@ function IconPicker({
           {
             items,
             checked: mixed ? void 0 : value,
-            onSelect: onChange,
+            onSelect: (next) => {
+              if (!hasContent(next === null ? void 0 : byValue.get(next)?.disabledReason)) onChange(next);
+            },
             activation,
             disabled,
             size,
@@ -100,6 +113,8 @@ function IconPicker({
     // the document height (see tokens.css).
     /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", "aria-atomic": true, className: "sr-only-fixed", children: needle ? text.resultCount(visible.length) : "" })
   ] });
+  if (!labelled) return picker;
+  return /* @__PURE__ */ jsx(LabelStrip, { labelId, label, hint, disabled, pad: "clear", className, children: picker });
 }
 export {
   DEFAULT_ICON_PICKER_LABELS,

package/dist/components/icon-picker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/icon-picker.tsx"],"sourcesContent":["import { useId, useMemo, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, ComponentType } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport { SearchField } from \"./search-field\";\nimport { TILE_SIZE, TileRadioGroup } from \"./tile-radio\";\nimport type { TileItem, TileSize } from \"./tile-radio\";\n\nexport interface IconPickerLabels {\n  /** The \"no icon\" tile's name, when `allowNone` is set. */\n  none: string;\n  /** Describes the group while `mixed` is set — a bulk edit over rows that disagree. */\n  mixed: string;\n  /** The search box's accessible name and placeholder, when `searchable` is set. */\n  search: string;\n  /** Shown in place of the tiles when the search matches nothing. */\n  noResults: string;\n  /** Announced as the search narrows the grid. Receives the number of matches. */\n  resultCount: (count: number) => string;\n}\n\nexport const DEFAULT_ICON_PICKER_LABELS: IconPickerLabels = {\n  none: \"No icon\",\n  mixed: \"Mixed: the selected items have different icons\",\n  search: \"Search icons\",\n  noResults: \"No icons match\",\n  resultCount: (count) => (count === 1 ? \"1 icon\" : `${count} icons`),\n};\n\nexport interface IconOption<T extends string> {\n  value: T;\n  /** A Lucide icon, or any component that takes a `className`. Rendered `aria-hidden`\n   *  — the tile's name is `label`. */\n  icon: ComponentType<{ className?: string; \"aria-hidden\"?: boolean }>;\n  /** What the symbol IS, in the user's language (\"Game controller\") — not the icon\n   *  library's identifier (`Gamepad2`), which is nobody's word for anything. */\n  label: string;\n  /** More words the search matches (\"games\", \"play\"), besides `label`. */\n  keywords?: string[];\n  /** A remark read after the name and shown under it in the bubble (\"used by\n   *  Leisure\"). The tile wears a dot while it has one. */\n  note?: string;\n  disabled?: boolean;\n}\n\nexport interface IconPickerProps<T extends string>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"children\" | \"defaultValue\"> {\n  options: IconOption<T>[];\n  /** The chosen icon, or `null` for none. */\n  value: T | null;\n  onChange: (value: T | null) => void;\n  /** Lead with a \"no icon\" tile whose value is `null`. */\n  allowNone?: boolean;\n  /** See {@link SwatchPickerProps.mixed}: nothing is checked, and the group is\n   *  described as mixed. */\n  mixed?: boolean;\n  /**\n   * \"automatic\" (default): an arrow key moves AND chooses, the APG radio group.\n   * \"manual\": arrows move focus only; Space or Enter chooses. For a picker whose every\n   * change is expensive — a bulk edit that saves as it goes.\n   */\n  activation?: \"automatic\" | \"manual\";\n  /** A search box above the grid, matching `label` and `keywords`. For a set large\n   *  enough that scanning it is slower than typing. */\n  searchable?: boolean;\n  /** 28 / 32 / 44px tiles. Default \"md\"; \"lg\" is the touch-target size. */\n  size?: TileSize;\n  /**\n   * Classes for every tile's frame, merged after the kit's own — so a caller's\n   * `size-*` beats `size`'s. For a tile that has to follow a container query or a\n   * breakpoint (keksdose grows its tiles to 40px in a narrow card:\n   * `tileClassName=\"@max-md:size-10\"`) without reaching into the kit's markup with an\n   * `[&_[role=radio]]` selector. The swatch dot / glyph inside keeps `size`'s\n   * dimensions; the tile grows round it.\n   */\n  tileClassName?: string;\n  disabled?: boolean;\n  labels?: Partial<IconPickerLabels>;\n}\n\n/** Case- and accent-insensitive, so \"cafe\" finds \"Café\". */\nfunction fold(text: string, locale: string | undefined): string {\n  return text.normalize(\"NFD\").replace(/\\p{M}/gu, \"\").toLocaleLowerCase(locale);\n}\n\n/**\n * A grid of symbols that is one radio group, with an optional search.\n *\n * Name the group with `aria-label` or `aria-labelledby`. The name lands on the\n * radiogroup itself, not on the outer box: with `searchable` the outer box also holds\n * the search field, which has a name of its own.\n *\n * Keyboard is {@link SwatchPicker}'s: one tab stop, arrows to move (flipped in a\n * right-to-left page), Home and End.\n */\nexport function IconPicker<T extends string>({\n  options,\n  value,\n  onChange,\n  allowNone = false,\n  mixed = false,\n  activation = \"automatic\",\n  searchable = false,\n  size = \"md\",\n  tileClassName,\n  disabled = false,\n  labels,\n  className,\n  \"aria-label\": ariaLabel,\n  \"aria-labelledby\": ariaLabelledBy,\n  \"aria-describedby\": ariaDescribedBy,\n  ...rest\n}: IconPickerProps<T>) {\n  const text = useKitLabels(\"iconPicker\", DEFAULT_ICON_PICKER_LABELS, labels);\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const locale = useKitLocale();\n  const mixedId = useId();\n  const [query, setQuery] = useState(\"\");\n  const needle = fold(query.trim(), locale);\n\n  const visible = useMemo(\n    () =>\n      needle\n        ? options.filter((o) =>\n            [o.label, ...(o.keywords ?? [])].some((w) => fold(w, locale).includes(needle)),\n          )\n        : options,\n    [options, needle, locale],\n  );\n  const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);\n  const items: TileItem<T>[] = [\n    // \"None\" stays through a search: it is the way back to no icon, and it matches\n    // no word anybody would type for it.\n    ...(allowNone ? [{ key: null, label: text.none }] : []),\n    ...visible.map((o) => ({ key: o.value, label: o.label, note: o.note, disabled: o.disabled })),\n  ];\n\n  return (\n    <div {...rest} className={cn(\"space-y-2\", className)}>\n      {searchable && (\n        <SearchField\n          value={query}\n          onChange={setQuery}\n          aria-label={text.search}\n          clearLabel={common.clear}\n          disabled={disabled}\n        />\n      )}\n      <div\n        role=\"radiogroup\"\n        aria-label={ariaLabel}\n        aria-labelledby={ariaLabelledBy}\n        aria-describedby={[ariaDescribedBy, mixed && mixedId].filter(Boolean).join(\" \") || undefined}\n        aria-disabled={disabled || undefined}\n        className=\"flex flex-wrap items-center gap-1.5\"\n      >\n        <TileRadioGroup\n          items={items}\n          checked={mixed ? undefined : value}\n          onSelect={onChange}\n          activation={activation}\n          disabled={disabled}\n          size={size}\n          renderTile={(item) => {\n            const Icon = item.key === null ? undefined : byValue.get(item.key)?.icon;\n            return Icon ? <Icon aria-hidden className={TILE_SIZE[size].glyph} /> : null;\n          }}\n          tileClassName={(_item, selected) =>\n            cn(\n              selected ? \"text-[var(--text-primary)]\" : \"text-[var(--text-secondary)]\",\n              tileClassName,\n            )\n          }\n        />\n      </div>\n      {needle && visible.length === 0 && (\n        <p className=\"text-xs text-[var(--text-muted)]\">{text.noResults}</p>\n      )}\n      {mixed && (\n        <span id={mixedId} hidden>\n          {text.mixed}\n        </span>\n      )}\n      {searchable && (\n        // Typing moves no focus and the grid changes silently, so the count is said.\n        // `sr-only-fixed`: this sits inside a consumer's markup and must not extend\n        // the document height (see tokens.css).\n        <span role=\"status\" aria-live=\"polite\" aria-atomic className=\"sr-only-fixed\">\n          {needle ? text.resultCount(visible.length) : \"\"}\n        </span>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/icon-picker.tsx"],"sourcesContent":["import { useId, useMemo, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, ComponentType, ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport { SearchField } from \"./search-field\";\nimport { TILE_SIZE, TileRadioGroup } from \"./tile-radio\";\nimport type { TileItem, TileSize } from \"./tile-radio\";\nimport { hasContent, LabelStrip } from \"./field-parts\";\n\nexport interface IconPickerLabels {\n  /** The \"no icon\" tile's name, when `allowNone` is set. */\n  none: string;\n  /** Describes the group while `mixed` is set — a bulk edit over rows that disagree. */\n  mixed: string;\n  /** The search box's accessible name and placeholder, when `searchable` is set. */\n  search: string;\n  /** Shown in place of the tiles when the search matches nothing. */\n  noResults: string;\n  /** Announced as the search narrows the grid. Receives the number of matches. */\n  resultCount: (count: number) => string;\n}\n\nexport const DEFAULT_ICON_PICKER_LABELS: IconPickerLabels = {\n  none: \"No icon\",\n  mixed: \"Mixed: the selected items have different icons\",\n  search: \"Search icons\",\n  noResults: \"No icons match\",\n  resultCount: (count) => (count === 1 ? \"1 icon\" : `${count} icons`),\n};\n\nexport interface IconOption<T extends string> {\n  value: T;\n  /** A Lucide icon, or any component that takes a `className`. Rendered `aria-hidden`\n   *  — the tile's name is `label`. */\n  icon: ComponentType<{ className?: string; \"aria-hidden\"?: boolean }>;\n  /** What the symbol IS, in the user's language (\"Game controller\") — not the icon\n   *  library's identifier (`Gamepad2`), which is nobody's word for anything. */\n  label: string;\n  /** More words the search matches (\"games\", \"play\"), besides `label`. */\n  keywords?: string[];\n  /** A remark read after the name and shown under it in the bubble (\"used by\n   *  Leisure\"). The tile wears a dot while it has one. */\n  note?: string;\n  /** Out of the choice and out of reach — skipped by the arrow keys and Tab. With a\n   *  `disabledReason` the tile stays reachable instead and says why. */\n  disabled?: boolean;\n  /**\n   * Why THIS symbol cannot be chosen right now — {@link SwatchOption.disabledReason}'s\n   * twin: the tile is `aria-disabled` but reachable by Tab and the arrow keys, the reason\n   * shows in its bubble under its name and describes it, and choosing it does nothing.\n   * Wins over `disabled`. Kept through a search like any other tile.\n   */\n  disabledReason?: ReactNode;\n}\n\nexport interface IconPickerProps<T extends string>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"children\" | \"defaultValue\"> {\n  options: IconOption<T>[];\n  /** The chosen icon, or `null` for none. */\n  value: T | null;\n  onChange: (value: T | null) => void;\n  /** Lead with a \"no icon\" tile whose value is `null`. */\n  allowNone?: boolean;\n  /** See {@link SwatchPickerProps.mixed}: nothing is checked, and the group is\n   *  described as mixed. */\n  mixed?: boolean;\n  /**\n   * \"automatic\" (default): an arrow key moves AND chooses, the APG radio group.\n   * \"manual\": arrows move focus only; Space or Enter chooses. For a picker whose every\n   * change is expensive — a bulk edit that saves as it goes.\n   */\n  activation?: \"automatic\" | \"manual\";\n  /** A search box above the grid, matching `label` and `keywords`. For a set large\n   *  enough that scanning it is slower than typing. */\n  searchable?: boolean;\n  /** 28 / 32 / 44px tiles. Default \"md\"; \"lg\" is the touch-target size. */\n  size?: TileSize;\n  /**\n   * Classes for every tile's frame, merged after the kit's own — so a caller's\n   * `size-*` beats `size`'s. For a tile that has to follow a container query or a\n   * breakpoint (keksdose grows its tiles to 40px in a narrow card:\n   * `tileClassName=\"@max-md:size-10\"`) without reaching into the kit's markup with an\n   * `[&_[role=radio]]` selector. The swatch dot / glyph inside keeps `size`'s\n   * dimensions; the tile grows round it.\n   */\n  tileClassName?: string;\n  disabled?: boolean;\n  labels?: Partial<IconPickerLabels>;\n  /**\n   * An 11px static label in a strip over the picker, naming the grid — keksdose K2,\n   * {@link SwatchPickerProps.label}'s twin: a symbol picker standing in a form row\n   * beside labelled fields, with its label on their line. With `searchable` the strip\n   * is over the search box too, which keeps its own name. With a label, `className`\n   * styles the wrapper.\n   */\n  label?: ReactNode;\n  /** A {@link FieldHint} beside the label. Only with `label`. */\n  hint?: ReactNode;\n}\n\n/** Case- and accent-insensitive, so \"cafe\" finds \"Café\". */\nfunction fold(text: string, locale: string | undefined): string {\n  return text.normalize(\"NFD\").replace(/\\p{M}/gu, \"\").toLocaleLowerCase(locale);\n}\n\n/**\n * A grid of symbols that is one radio group, with an optional search.\n *\n * Name the group with `aria-label` or `aria-labelledby`. The name lands on the\n * radiogroup itself, not on the outer box: with `searchable` the outer box also holds\n * the search field, which has a name of its own.\n *\n * Keyboard is {@link SwatchPicker}'s: one tab stop, arrows to move (flipped in a\n * right-to-left page), Home and End.\n */\nexport function IconPicker<T extends string>({\n  options,\n  value,\n  onChange,\n  allowNone = false,\n  mixed = false,\n  activation = \"automatic\",\n  searchable = false,\n  size = \"md\",\n  tileClassName,\n  disabled = false,\n  labels,\n  label,\n  hint,\n  className,\n  \"aria-label\": ariaLabel,\n  \"aria-labelledby\": ariaLabelledBy,\n  \"aria-describedby\": ariaDescribedBy,\n  ...rest\n}: IconPickerProps<T>) {\n  const text = useKitLabels(\"iconPicker\", DEFAULT_ICON_PICKER_LABELS, labels);\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const locale = useKitLocale();\n  const mixedId = useId();\n  const labelId = useId();\n  const labelled = hasContent(label);\n  const [query, setQuery] = useState(\"\");\n  const needle = fold(query.trim(), locale);\n\n  const visible = useMemo(\n    () =>\n      needle\n        ? options.filter((o) =>\n            [o.label, ...(o.keywords ?? [])].some((w) => fold(w, locale).includes(needle)),\n          )\n        : options,\n    [options, needle, locale],\n  );\n  const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);\n  const items: TileItem<T>[] = [\n    // \"None\" stays through a search: it is the way back to no icon, and it matches\n    // no word anybody would type for it.\n    ...(allowNone ? [{ key: null, label: text.none }] : []),\n    ...visible.map((o) => ({\n      key: o.value,\n      label: o.label,\n      note: o.note,\n      disabled: o.disabled,\n      disabledReason: o.disabledReason,\n    })),\n  ];\n\n  const picker = (\n    <div {...rest} className={cn(\"space-y-2\", !labelled && className)}>\n      {searchable && (\n        <SearchField\n          value={query}\n          onChange={setQuery}\n          aria-label={text.search}\n          clearLabel={common.clear}\n          disabled={disabled}\n        />\n      )}\n      <div\n        role=\"radiogroup\"\n        aria-label={ariaLabel}\n        // The strip's label names the GRID, unless the caller named it already.\n        aria-labelledby={labelled && ariaLabel === undefined && ariaLabelledBy === undefined ? labelId : ariaLabelledBy}\n        aria-describedby={[ariaDescribedBy, mixed && mixedId].filter(Boolean).join(\" \") || undefined}\n        aria-disabled={disabled || undefined}\n        className=\"flex flex-wrap items-center gap-1.5\"\n      >\n        <TileRadioGroup\n          items={items}\n          checked={mixed ? undefined : value}\n          // A locked tile is refused by the tiles themselves; asked again here so a\n          // reason can never become a change, whatever the tiles do.\n          onSelect={(next) => {\n            if (!hasContent(next === null ? undefined : byValue.get(next)?.disabledReason)) onChange(next);\n          }}\n          activation={activation}\n          disabled={disabled}\n          size={size}\n          renderTile={(item) => {\n            const Icon = item.key === null ? undefined : byValue.get(item.key)?.icon;\n            return Icon ? <Icon aria-hidden className={TILE_SIZE[size].glyph} /> : null;\n          }}\n          tileClassName={(_item, selected) =>\n            cn(\n              selected ? \"text-[var(--text-primary)]\" : \"text-[var(--text-secondary)]\",\n              tileClassName,\n            )\n          }\n        />\n      </div>\n      {needle && visible.length === 0 && (\n        <p className=\"text-xs text-[var(--text-muted)]\">{text.noResults}</p>\n      )}\n      {mixed && (\n        <span id={mixedId} hidden>\n          {text.mixed}\n        </span>\n      )}\n      {searchable && (\n        // Typing moves no focus and the grid changes silently, so the count is said.\n        // `sr-only-fixed`: this sits inside a consumer's markup and must not extend\n        // the document height (see tokens.css).\n        <span role=\"status\" aria-live=\"polite\" aria-atomic className=\"sr-only-fixed\">\n          {needle ? text.resultCount(visible.length) : \"\"}\n        </span>\n      )}\n    </div>\n  );\n  if (!labelled) return picker;\n  return (\n    <LabelStrip labelId={labelId} label={label} hint={hint} disabled={disabled} pad=\"clear\" className={className}>\n      {picker}\n    </LabelStrip>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/inline-edit-field.d.ts

@@ -0,0 +1,167 @@
+import * as react from 'react';
+import { ReactNode, InputHTMLAttributes } from 'react';
+
+/**
+ * Every string {@link InlineEditField} says on its own behalf — the `inlineEdit`
+ * namespace of `<UiKitProvider labels>`, overridable per instance through `labels`.
+ */
+interface InlineEditLabels {
+    /** The display button's tooltip and description — what pressing it does. Receives
+     *  the field's `label` ("Budget name" → "Edit Budget name"). */
+    edit: (label: string) => string;
+    /** Shown (and spoken) when `onCommit` rejects and no `formatError` says better. */
+    failed: string;
+    /** What the display shows for an empty value, when no `placeholder` is given. */
+    empty: string;
+}
+declare const DEFAULT_INLINE_EDIT_LABELS: InlineEditLabels;
+/** What an `editor` render prop is handed: the draft and the means to end the edit. */
+interface InlineEditorProps<T> {
+    /** The draft — seeded from `value` each time the editor opens. */
+    value: T;
+    /** Replace the draft (every keystroke). */
+    onChange: (next: T) => void;
+    /**
+     * End the edit and save. Without an argument it saves the draft; WITH one it saves
+     * that — for an editor whose own commit hands over a resolved value (`NumberInput`'s
+     * `onCommit` gives "1050" for a typed "1100-50"). Called twice (the editor's own
+     * Enter, then the field's), the second call does nothing.
+     */
+    commit: (next?: T) => void;
+    /** End the edit and drop the draft — what Escape does. */
+    cancel: () => void;
+    /** The save is in flight: make the control read-only (not disabled — it has focus). */
+    pending: boolean;
+    /** The field's `label`, for the control's accessible name. */
+    label: string;
+    /** The last save failed and the draft has not been touched since. */
+    invalid: boolean;
+    /** The id of the failure message while there is one, for `aria-describedby`. */
+    describedBy: string | undefined;
+    /** The four above as attributes — spread them on a kit field that takes the DOM
+     *  spelling: `<AmountInput {...p.inputProps} … />`. */
+    inputProps: {
+        "aria-label": string;
+        "aria-invalid": true | undefined;
+        "aria-describedby": string | undefined;
+        readOnly: boolean;
+    };
+}
+interface InlineEditFieldBaseProps<T> {
+    /** The saved value — what the display shows, and what the editor opens on. */
+    value: T;
+    /**
+     * Save `next`. Return a promise and the field waits: the editor stays open and
+     * read-only with a spinner until it settles, closes when it resolves, and STAYS OPEN
+     * with the failure under it when it rejects (or throws) — the typed value is kept for
+     * a retry. Not called when the draft equals `value` (see `isEqual`): opening the
+     * editor and leaving it unchanged is not a write.
+     */
+    onCommit: (next: T) => void | Promise<unknown>;
+    /** What the value is ("Budget name", "Assigned") — the editor's accessible name and
+     *  the subject of the display's "Edit …" description. Not drawn: inline, the row or
+     *  the column header is the visible label. */
+    label: string;
+    /** The value as the display shows it — a formatted amount, a date. Default: the
+     *  value as text. */
+    display?: (value: T) => ReactNode;
+    /** Whether the draft is unchanged, so leaving the editor is not a write. Default
+     *  `Object.is`. keksdose compares assigned amounts as NUMBERS — "1100" is the
+     *  server's "1100.0000". */
+    isEqual?: (a: T, b: T) => boolean;
+    /** What the display shows for an empty value (`""`, `null`, an empty `display`).
+     *  Default `labels.empty`. */
+    placeholder?: ReactNode;
+    /** `"end"` for a figure in a right-aligned money column. Default `"start"`. */
+    align?: "start" | "end";
+    /** Look, do not touch — a guest's view: the value as plain text, no button. */
+    readOnly?: boolean;
+    /**
+     * Why it cannot be edited now — the write lock's sentence, a closed period. The
+     * value stays a BUTTON (focusable, `aria-disabled`) with the reason in the kit
+     * Tooltip and its description; it opens no editor. An editor that is open when the
+     * reason arrives closes, its draft dropped: a field you can type into must be one
+     * whose value can be saved (keksdose dev#496).
+     */
+    disabledReason?: ReactNode;
+    /** This field COMMITS — under a locked {@link WriteLockProvider} it takes the
+     *  `disabledReason` path with the lock's reason (which wins over its own). No
+     *  provider, or an unlocked one: no effect. */
+    commit?: boolean;
+    /** The value is the user's own data: `data-private` on the display and the editor,
+     *  so the app's demo-mode blur covers both. */
+    redact?: boolean;
+    /** Turns a rejection into words. Default `labels.failed`. */
+    formatError?: (error: unknown) => ReactNode;
+    /** Controlled open state — a row's swipe action that opens the editor from outside
+     *  (keksdose's assigned cell). Left out, the field keeps its own. */
+    editing?: boolean;
+    /** Called with the next open state: on open, on a save that resolved, on cancel. */
+    onEditingChange?: (editing: boolean) => void;
+    /** Attributes for the DEFAULT text editor's `<input>` — `maxLength`, `inputMode`,
+     *  `autoComplete`. Ignored with `editor`. */
+    inputProps?: Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "type">;
+    /** Classes for the root. */
+    className?: string;
+    labels?: Partial<InlineEditLabels>;
+}
+type EditorRender<T> = (props: InlineEditorProps<T>) => ReactNode;
+/**
+ * The editor. Optional for a string value — the kit's `Input`, compact — and
+ * REQUIRED for anything else, since only the caller knows how to edit a number or an
+ * amount. Render a kit field from the props it is handed:
+ *
+ * ```tsx
+ * editor={(p) => (
+ *   <NumberInput calculator={false} ariaLabel={p.label} value={p.value} onChange={p.onChange}
+ *     onCommit={p.commit} aria-invalid={p.invalid || undefined} aria-describedby={p.describedBy} />
+ * )}
+ * ```
+ *
+ * The field itself handles Enter (save), Escape (cancel) and focus leaving the editor
+ * (save) around whatever is rendered — a key the editor has already handled
+ * (`preventDefault`, as a listbox does for its Enter) is left to it. Focus counts as
+ * "inside" across a portal, so a picker or a phone keypad the editor opens does not
+ * end the edit.
+ */
+type InlineEditFieldProps<T = string> = InlineEditFieldBaseProps<T> & ([T] extends [string] ? {
+    editor?: EditorRender<T>;
+} : {
+    editor: EditorRender<T>;
+});
+/**
+ * A value that edits in place: a quiet button showing the value; click it (or Enter
+ * on it) and it becomes a field; Enter or leaving the field saves, Escape cancels
+ * (keksdose K9).
+ *
+ * keksdose has three of them by hand — the budget's assigned cell (budget-cells.tsx),
+ * the invoice line's value cells (invoice-lines-table.tsx `EditableCell`) and the
+ * budget rename (budgets-page.tsx, an `Input` + Save + Cancel with no Escape) — and
+ * each had to learn the same rules:
+ *
+ *  - **The display's accessible name is the VALUE.** A cell named "Edit" reads a table
+ *    of "edit, edit, edit"; the action is the description instead ("Edit Assigned"),
+ *    in the kit Tooltip on hover and focus.
+ *  - **An unchanged draft is not a write.** Opening the editor and leaving it was a PUT
+ *    in keksdose until `isEqual` compared numbers, and on a sealed budget an outbox row
+ *    for a change nobody made.
+ *  - **A failed save keeps the editor.** The typed value is the user's work; the
+ *    failure is shown under it (attached with `aria-describedby`, and spoken), and the
+ *    next keystroke clears it. Escape still drops the draft.
+ *  - **Locked means a disabled BUTTON, not a disabled field** (keksdose dev#496): at
+ *    rest a real row shows this button, so a locked page shows the same, with the
+ *    reason — never a field that takes keys it cannot save.
+ *
+ * Inside a {@link DataTable} cell it needs nothing extra: the table already leaves a
+ * click or a key on a control of the cell to that control. Focus returns to the value
+ * after Enter or Escape; after a save that came from focus leaving, it stays where the
+ * user put it.
+ *
+ * ```tsx
+ * <InlineEditField label={t("budgets.name")} value={budget.name}
+ *   onCommit={(name) => rename.mutateAsync({ id: budget.id, name })} inputProps={{ maxLength: 120 }} />
+ * ```
+ */
+declare function InlineEditField<T = string>(props: InlineEditFieldProps<T>): react.JSX.Element;
+
+export { DEFAULT_INLINE_EDIT_LABELS, InlineEditField, type InlineEditFieldProps, type InlineEditLabels, type InlineEditorProps };