@eifi1/ui-kit 0.33.1 → 0.35.0

package/dist/components/combobox.d.ts

@@ -1,10 +1,8 @@
-import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
-import { ComboClearValue, ComboOption } from './combobox-core.js';
-import { CommitScope } from './write-lock.js';
-import '../hooks/use-anchored-rect.js';
-import '../hooks/use-anchored-panel.js';
-
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
+import { type DisabledReasonDisplay } from "./field-parts.js";
+import type { CommitScope } from "./write-lock.js";
+export { InlineEntityCombobox } from "./inline-entity-combobox.js";
+export type { InlineEntityComboboxProps } from "./inline-entity-combobox.js";
 /**
  * Four of the div's own attributes are omitted because this component already owns
  * the name, with a different meaning: `id` is the INPUT's (a caller labels or
@@ -12,12 +10,15 @@ import '../hooks/use-anchored-panel.js';
  * are the field's — a value, a departure, and "I mean what I typed" — rather than
  * the DOM events of the wrapper. Everything else a wrapper needs reaches the root.
  */
-interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange" | "onBlur" | "onSubmit"> {
+export interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange" | "onBlur" | "onSubmit"> {
     value: string;
     onChange: (v: string) => void;
     /** Suggestion pool (e.g. existing payee names). */
     options: string[];
-    label?: string;
+    /** The visible label, a `<label for>` above the field: a ReactNode, as on every kit
+     *  field (a string until 0.34, refactor audit 2026-10, API-9). Without one, name the
+     *  field with `aria-label`. */
+    label?: ReactNode;
     id?: string;
     placeholder?: string;
     className?: string;
@@ -55,6 +56,9 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
      *  `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?: CommitScope;
+    /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the
+     *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */
+    disabledReasonDisplay?: DisabledReasonDisplay;
     /** 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
@@ -93,7 +97,7 @@ interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "on
     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,
+     * field whose label is drawn by someone else: a bound field's label 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).
@@ -135,153 +139,4 @@ 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(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"> {
-    /** Selected option id; `null` or `clearValue` when nothing is selected. */
-    value: V | C | null;
-    /** Required and unanswered — see {@link Combobox}'s `invalid`. */
-    invalid?: boolean;
-    /** What is wrong with the value — see {@link Combobox}'s `error`. */
-    error?: ReactNode;
-    /** Standing advice — see {@link Combobox}'s `hint` (keksdose K4). */
-    hint?: ReactNode;
-    /** A picked/typed option emits its id; emptying the field, or the "×", emits
-     *  `clearValue`. */
-    onChange: (v: V | C) => void;
-    /** What a clear emits — `null` by default, `""` for a schema that wants an empty
-     *  string. See {@link EntityCombobox}'s `clearValue`. */
-    clearValue?: C;
-    options: ComboOption<V>[];
-    label?: string;
-    id?: string;
-    placeholder?: string;
-    className?: string;
-    disabled?: boolean;
-    /** Focus on mount, the way `<input autoFocus>` does — and, through `onFocus`
-     *  below, open the list with it. A click-the-value editor needs it: the cell
-     *  the user clicked names the field the editor should land the caret in, and
-     *  without a passthrough this component's fixed prop list puts the `<input>`
-     *  out of a caller's reach entirely (Keksdose feedback live #218). */
-    autoFocus?: boolean;
-    /** Phone sheet only — the anchored list has the field itself to type in. Falls
-     *  back to `placeholder`, then to `combobox.search` from the {@link UiKitProvider}. */
-    searchPlaceholder?: string;
-    /** Phone sheet only: a full screen showing nothing has to say why. The anchored
-     *  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
-     *  is the fast way. It is not a way at all on a PHONE: touching the field opens the
-     *  full-screen sheet, which covers the very input the text would have been deleted
-     *  from — so a field that had been answered could not be UNanswered by any gesture
-     *  the screen offered (Keksdose live #236, filed from a phone). The "×" is the one
-     *  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?: CommitScope;
-    /**
-     * 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?: CommitScope;
-    /**
-     * 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
- * with the shared field styling, chevron and inline as-you-type filtering) but
- * the value is an option id, not free text. Built so an entity picker can sit
- * next to a free-text combobox without any visible difference — a button-trigger
- * panel picker ({@link EntityCombobox}) never matches an input field exactly.
- *
- * Text-vs-value reconciliation: the input's text is transient. Picking a row or
- * typing an exact (unique) label commits that option; emptying the text commits
- * a clear; anything else reverts to the selected option's label on blur/Escape.
- *
- * **On a phone the list opens as a full-screen sheet**, exactly like {@link Combobox}
- * beside it (Keksdose live #200, extended by dev#477 — the account picker moved onto
- * this component and must not lose its sheet). The sheet carries its OWN query state
- * rather than reusing `text`: `text` is what {@link reconcile} judges on blur, so a
- * 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>(props: InlineEntityComboboxProps<V, C>): react.JSX.Element;
-
-export { Combobox, type ComboboxProps, InlineEntityCombobox, type InlineEntityComboboxProps };
+export declare function Combobox(props: ComboboxProps): import("react").JSX.Element;