@eifi1/ui-kit 0.22.0 → 0.24.0

package/dist/components/combobox.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
 import { ComboClearValue, ComboOption } from './combobox-core.js';
 import '../hooks/use-anchored-rect.js';
 import '../hooks/use-anchored-panel.js';
@@ -42,6 +42,18 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
      *  stops toggling with it — it is a mouse target the input's own `disabled` does
      *  not reach. */
     disabled?: boolean;
+    /**
+     * Why the value cannot be changed — {@link Button}'s `disabledReason`, for a field
+     * that SAVES itself (an inline editor whose blur writes). The input stays focusable
+     * and `aria-disabled`, is `readOnly`, opens no list and calls neither `onChange` nor
+     * `onSubmit`; the reason is in the kit {@link Tooltip} and on its `aria-describedby`.
+     * Wins over `disabled`. The family's lock (keksdose G2) — see {@link InlineEntityCombobox}.
+     */
+    disabledReason?: ReactNode;
+    /** This field COMMITS. Under a locked {@link WriteLockProvider} it is locked the
+     *  `disabledReason` way with the lock's reason; inside a form with its own Save, leave
+     *  it off and put `commit` on the Save. No provider, or an unlocked one: no effect. */
+    commit?: boolean;
     /** Heading an option belongs under. Supplying it makes this list read exactly
      *  like {@link InlineEntityCombobox}'s — one heading per group with its rows
      *  indented beneath — instead of a flat list (feedback #136 rework: the payee
@@ -78,6 +90,14 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
     maxSuggestions?: number;
     searchPlaceholder?: string;
     closeLabel?: string;
+    /**
+     * The phone sheet's heading — and, as a string, the dialog's accessible name — for a
+     * field whose label is drawn by someone else: a form's `FormLabel` above it,
+     * which `RhfTextCombobox` hands over here (0.24). Default: `label`. Without either, the
+     * full-screen sheet opened untitled and unnamed, the one screen on a phone that has to
+     * say what it is asking for (live #200).
+     */
+    sheetTitle?: ReactNode;
     /**
      * Label for the row that COMMITS a value the list does not contain — e.g.
      * `(v) => \`Add "${v}" as payee\``. Supplying it turns the free text into
@@ -94,6 +114,15 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
      * values are all supposed to already exist.
      */
     createLabel?: (value: string) => string;
+    /**
+     * The `<input>` — the control a reader types in and the one focus belongs on — as a
+     * React 19 ref prop, the way {@link CountrySelect} takes its trigger's (0.24, kastlan:
+     * react-hook-form's focus-on-error calls `focus()` on whatever `field.ref` is handed,
+     * and a combobox with no ref inside a hand-wired `RhfField` gave it nothing, so a
+     * failed submit could not take the user to it). Not the wrapper: a ref is for focus,
+     * measurement and selection, and all three are the input's. `RhfTextCombobox` passes it.
+     */
+    ref?: Ref<HTMLInputElement>;
 }
 /**
  * Free-text combobox that looks like the shared {@link Select} (same FIELD_BASE
@@ -105,7 +134,7 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
  * visually and behaviourally consistent with the other dropdowns (feedback
  * #230 — the payee field looked/behaved differently from every other select).
  */
-declare function Combobox({ value, onChange, options, label, id, placeholder, className, groupBy, maxSuggestions, searchPlaceholder, closeLabel, createLabel, invalid, error, hint, disabled, optionAdornment, autoFocus, onBlur, onSubmit, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, ...rest }: ComboboxProps): react.JSX.Element;
+declare function Combobox(props: ComboboxProps): react.JSX.Element;
 /** `id` is the INPUT's and `onChange` is the field's — see {@link ComboboxProps}
  *  for why the div's spellings of them are omitted. */
 interface InlineEntityComboboxProps<V extends string | number, C extends ComboClearValue = null> extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange"> {
@@ -142,6 +171,11 @@ interface InlineEntityComboboxProps<V extends string | number, C extends ComboCl
      *  list simply does not open. Default: `combobox.noResults` from the provider. */
     emptyLabel?: string;
     closeLabel?: string;
+    /** The phone sheet's heading (and, as a string, its accessible name) for a field
+     *  whose label is drawn by someone else — a form's `FormLabel`;
+     *  `RhfInlineEntityCombobox` hands its label over here (0.24). Default: `label`.
+     *  See {@link Combobox}'s `sheetTitle`. */
+    sheetTitle?: ReactNode;
     /** Offer a clear "×" in place of the chevron whenever something is selected.
      *
      *  Emptying the text already clears (see {@link reconcile}), and on a desktop that
@@ -152,6 +186,82 @@ interface InlineEntityComboboxProps<V extends string | number, C extends ComboCl
      *  affordance both shells share, and it clears without opening anything. */
     clearable?: boolean;
     clearLabel?: string;
+    /**
+     * Why the choice cannot be changed — {@link Button}'s `disabledReason`, for a picker
+     * that SAVES on change. keksdose G2: the statement review's account picker IS the
+     * write (picking re-runs the duplicate check on the server), and on the read-only demo
+     * the app wrapped it in a hand-made Tooltip over a native `disabled` — out of the tab
+     * order, so the reason never reached a keyboard.
+     *
+     * With a reason the input stays focusable and `aria-disabled`, is `readOnly` (the
+     * settled grey), opens no list or sheet, offers no clear "×", and no pick, typed
+     * label or clear reaches `onChange`; the reason is in the kit {@link Tooltip} and on
+     * the input's `aria-describedby`. Wins over `disabled`. Use it CONTROLLED, as the
+     * component always is: the shown label is `value`'s.
+     */
+    disabledReason?: ReactNode;
+    /**
+     * This picker COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is
+     * locked the `disabledReason` way with the lock's reason (which wins over its own).
+     * A picker inside a form with its own Save stays editable under the lock — leave this
+     * off there and put `commit` on the Save. No provider, or an unlocked one: no effect.
+     */
+    commit?: boolean;
+    /**
+     * A last row that makes a new record from what was typed — keksdose G9, whose "Create
+     * cash account" had to become a separate button because this picker had no such row.
+     *
+     * Shown while the typed query is non-empty and names no option exactly
+     * (case-insensitive — an exact hit is a record the list already shows), worded
+     * `createLabel(query)`, default `combobox.create`: "Create “{query}”". The arrow keys
+     * reach it like an option; Enter or a click calls `onCreate(query)` and closes the
+     * list. Making the record, and then passing its id as `value`, is the caller's: the
+     * field shows the old selection until it does.
+     *
+     * The same rule as {@link EntityCombobox}'s `onCreate`, so the family agrees. It is a
+     * row of the LIST, not an option: it is never `aria-selected`, never matched by a
+     * typed label on blur, and never sorted among the records the way a sentinel option
+     * would be (the reason keksdose gave for the separate button).
+     */
+    onCreate?: (query: string) => void;
+    /** The create row's words for a query. Default: `combobox.create` from the
+     *  {@link UiKitProvider}, else English `Create “{query}”`. */
+    createLabel?: (query: string) => string;
+    /**
+     * Offer the create row with NOTHING typed too, worded as this — keksdose's "Create cash
+     * account", which mints an account under a default name and so needs no query.
+     * `onCreate` then receives `""`, and the caller supplies the name. Left out, the row
+     * needs a query.
+     *
+     * One string rather than a switch: a row with no query has nothing to quote, so the
+     * kit cannot word it — "Create “”" says nothing — and naming it is what turns it on.
+     * With both, one handler serves both rows:
+     *
+     * ```tsx
+     * onCreate={(name) => createCash(name || t("cash_account_default_name"))}
+     * createEmptyLabel={t("create_cash_account")}
+     * ```
+     */
+    createEmptyLabel?: string;
+    /**
+     * The create row WRITES while picking does not — keksdose dev#496: on the read-only
+     * demo choosing the cash account is draft state and stays live, minting one is a
+     * write. Under a locked {@link WriteLockProvider} the row stays in the list, dimmed and
+     * passed over by the arrows, with the lock's reason as its second line (a hover is the
+     * one explanation a phone cannot show), and `onCreate` is not called. Not needed with
+     * `commit`: a locked field opens no list at all.
+     */
+    createCommit?: boolean;
+    /**
+     * The `<input>` — the focusable control, the one a reader types in — as a React 19
+     * ref prop (0.24, kastlan). Its account picker is this component inside an
+     * `RhfField` render, and react-hook-form's focus-on-error calls `focus()` on whatever
+     * `field.ref` is handed: with no ref there was nothing to hand it, so a line-item form
+     * whose account was missing failed its submit and left the caret where it was. Pass
+     * `field.ref` here, or use `RhfInlineEntityCombobox`, which does. The wrapper is not
+     * reachable this way — focus and selection are the input's. See {@link Combobox}'s `ref`.
+     */
+    ref?: Ref<HTMLInputElement>;
 }
 /**
  * The id-keyed sibling of {@link Combobox}: identical anatomy (a real text input
@@ -171,6 +281,6 @@ interface InlineEntityComboboxProps<V extends string | number, C extends ComboCl
  * sheet that emptied it to show the full list would read as "the user cleared the
  * field" the moment it closed.
  */
-declare function InlineEntityCombobox<V extends string | number, C extends ComboClearValue = null>({ value: rawValue, onChange, clearValue, options, label, id, placeholder, className, disabled, autoFocus, searchPlaceholder, emptyLabel, closeLabel, clearable, clearLabel, invalid, error, hint, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, ...rest }: InlineEntityComboboxProps<V, C>): react.JSX.Element;
+declare function InlineEntityCombobox<V extends string | number, C extends ComboClearValue = null>(props: InlineEntityComboboxProps<V, C>): react.JSX.Element;
 
 export { Combobox, type ComboboxProps, InlineEntityCombobox, type InlineEntityComboboxProps };