@godxjp/ui 20.2.1 → 22.0.0

package/dist/props/components/data-entry.prop.d.ts

@@ -1,8 +1,5 @@
 /** Data Entry component prop types — @see docs/COMPONENTS.md#data-entry */
-import type * as CheckboxPrimitive from "@radix-ui/react-checkbox";
-import type * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
 import type * as SliderPrimitive from "@radix-ui/react-slider";
-import type * as SwitchPrimitive from "@radix-ui/react-switch";
 import type { RenderProps as InputOTPRenderProps } from "input-otp";
 import type { DayPickerProps } from "react-day-picker";
 import type { DateRange } from "react-day-picker";
@@ -285,6 +282,22 @@ export type FormFieldProp = {
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
+    /**
+     * Which side of the control the helper line sits on — `after` (default, under the input) or
+     * `before` (between the label and the input).
+     *
+     * `before` is for a helper the reader needs BEFORE they answer rather than after: the
+     * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
+     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
+     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
+     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
+     * a plain string.
+     *
+     * Paint only: the helper keeps its id and stays on the control's `aria-describedby`, so this
+     * never changes what a screen reader reads or the order it reads it in.
+     */
+    helperPlacement?: "before" | "after";
     error?: ErrorProp;
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
@@ -316,6 +329,22 @@ export type FormFieldProp = {
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
+    /**
+     * Which side of the control the helper line sits on — `after` (default, under the input) or
+     * `before` (between the label and the input).
+     *
+     * `before` is for a helper the reader needs BEFORE they answer rather than after: the
+     * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
+     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
+     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
+     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
+     * a plain string.
+     *
+     * Paint only: the helper keeps its id and stays on the control's `aria-describedby`, so this
+     * never changes what a screen reader reads or the order it reads it in.
+     */
+    helperPlacement?: "before" | "after";
     error?: ErrorProp;
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
@@ -386,8 +415,20 @@ export type SearchInputProp = FieldA11yProps & {
     /** Chrome level — antd `variant`. Default `outlined`. */
     variant?: ControlVariantProp;
 };
-/** @see Checkbox — extends Radix checkbox root props. */
-export type CheckboxProp = React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root> & {
+/**
+ * @see Checkbox
+ *
+ * Public shape unchanged from the @radix-ui/react-checkbox era — `checked` / `defaultChecked` take
+ * the tri-state `"indeterminate"`, `onCheckedChange` reports it back, and `disabled` / `required`
+ * keep their HTML spelling. checkbox.tsx translates all of it to react-aria's `isSelected` /
+ * `isIndeterminate` / `onChange` / `isDisabled`; none of those names reach a consumer. Written out
+ * here rather than derived from a primitive that the component no longer uses.
+ */
+export type CheckboxProp = Omit<React.ComponentPropsWithoutRef<"button">, "checked" | "defaultChecked" | "onChange"> & {
+    checked?: boolean | "indeterminate";
+    defaultChecked?: boolean | "indeterminate";
+    onCheckedChange?: (checked: boolean | "indeterminate") => void;
+    required?: boolean;
     /**
      * antd `indeterminate` — paint the PARTIAL mark (a dash) without changing `checked`. Radix
      * spells the same state as `checked="indeterminate"`; this is the antd spelling of it, and the
@@ -442,10 +483,30 @@ export type RadioGroupProp = FieldA11yProps & {
 export type RadioOptionTypeProp = "default" | "button";
 /** antd `RadioGroupButtonStyle` — the selected button is outlined, or filled with the brand. */
 export type RadioButtonStyleProp = "outline" | "solid";
-/** @see Radio.Item — Radix radio group item. */
-export type RadioProp = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>;
-/** @see Switch — extends Radix switch root props. */
-export type SwitchProp = React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root> & {
+/**
+ * @see Radio.Item
+ *
+ * Public shape unchanged from the @radix-ui/react-radio-group era — `value` / `disabled` keep
+ * their HTML spelling; react-aria's `isDisabled` never reaches a consumer.
+ */
+export type RadioProp = Omit<React.ComponentPropsWithoutRef<"button">, "value"> & {
+    value: string;
+};
+/**
+ * @see Switch
+ *
+ * The PUBLIC shape is unchanged from the @radix-ui/react-switch era — `checked` /
+ * `defaultChecked` / `onCheckedChange` / `disabled` / `required` keep their HTML spelling.
+ * react-aria-components spells the same five `isSelected` / `defaultSelected` / `onChange` /
+ * `isDisabled`, and that translation happens inside `switch.tsx`; none of those names reach a
+ * consumer. Written out here rather than derived from a primitive so the surface stops moving
+ * whenever the base does.
+ */
+export type SwitchProp = Omit<React.ComponentPropsWithoutRef<"button">, "checked" | "defaultChecked" | "onChange" | "value"> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    required?: boolean;
     size?: "sm" | "md";
     /**
      * antd `loading` — the toggle is mid-flight: a spinner replaces the thumb glyph and the control
@@ -579,28 +640,90 @@ export type PickerChromeProp = {
 };
 /** date-fns pattern, Intl options (including Japanese era), or a display function. */
 export type PickerDateFormatProp = string | Intl.DateTimeFormatOptions | ((date: Date) => string);
-/** @see DatePicker */
+/**
+ * @see DatePicker — ONE date control for every date-shaped question this library used to ask with
+ * four components (`DatePicker`, `DateRangePicker`, `MonthPicker`, `MonthRangePicker`).
+ *
+ * Two axes, both antd's: `picker` chooses the GRANULARITY of a selection, `range` chooses its
+ * CARDINALITY. Everything else — bounds, disabling, formatting, clearing, the open triad, the
+ * chrome ladder — is written once and therefore behaves the same on all eight combinations.
+ *
+ * ON THE NAME `picker`. It is antd's own prop name for this axis, and it already shipped here with
+ * exactly this union, so keeping it renames nothing and breaks no call site. (`granularity` is
+ * react-aria's spelling; this cluster is not on react-aria.) The house rule stated on `TreeProp` —
+ * map Ant's KEY-SHAPED names onto this package's controlled vocabulary and do not re-spell the
+ * rest — is what the surrounding props already do: `showTime`, `needConfirm`, `allowClear`,
+ * `cellRender`, `disabledDate`, `inputReadOnly`, `preserveInvalidOnBlur`, `renderExtraFooter`,
+ * `presets`, `order`, `minDate`/`maxDate` are all spelled antd's way, while selection is spelled
+ * `value`/`defaultValue`/`onValueChange` rather than antd's `onChange`.
+ */
 export type DatePickerBaseProp = FieldA11yProps & PickerChromeProp & {
     /** Display format; native submission remains ISO. */
     format?: PickerDateFormatProp;
     /** Parser for a custom display function or Intl era display; ISO always remains accepted. */
     parseFormat?: (text: string) => Date | undefined;
+    /**
+     * Selectable bounds, inclusive, at day precision (antd `minDate`/`maxDate`).
+     *
+     * These are the ONLY bounds props. `MonthPicker`/`MonthRangePicker` used to take
+     * `fromYear`/`toYear` numbers instead, which expressed strictly less (a whole year is the
+     * smallest thing they could say) and — measurably — clamped nothing: they only greyed the
+     * grid's year chevrons, while both routes into the value, the grid cells and the typed text,
+     * ignored them. `minDate`/`maxDate` are enforced on BOTH routes for every `picker`, so the
+     * keyboard is not a way around the rule the mouse obeys. Migration is mechanical:
+     * `fromYear={2024}` → `minDate={new Date(2024, 0, 1)}`, `toYear={2027}` →
+     * `maxDate={new Date(2027, 11, 31)}`.
+     */
     minDate?: Date;
     maxDate?: Date;
     showWeek?: boolean;
     needConfirm?: boolean;
+    /**
+     * Which period the PANEL opens on, independently of the value (antd `defaultPickerValue`, and
+     * like antd's it is RE-APPLIED every time the panel opens rather than only at mount).
+     *
+     * Without it a panel can only open on the value or on today, so "open on the fiscal year's
+     * start month" and "open on the month of the row being edited" have no expression — the two
+     * cases the parity audit files as P1. Only the period matters; the day is ignored.
+     */
+    defaultPickerValue?: Date;
+    /** Controlled panel period (antd `pickerValue`) — wins over `defaultPickerValue` and over the value. */
+    pickerValue?: Date;
+    /**
+     * GRANULARITY of one selection (antd `picker`). `date` picks a day from a month grid; `week`
+     * picks a day and normalises it to the locale's week start; `month`, `quarter` and `year` swap
+     * the day grid for a period grid and normalise to the period's first day.
+     *
+     * The emitted value is always a `Date` at the START of the chosen period, so a coarse
+     * selection interoperates with a fine one and with `DateRange`.
+     */
     picker?: "date" | "week" | "month" | "quarter" | "year";
+    /**
+     * Normalise the selection into ascending order (antd `order`; default `true`).
+     *
+     * ONE rule, applied to whichever value shape is in play: a `range` whose endpoints were picked
+     * backwards is SWAPPED, and a `multiple` selection is SORTED. The four split components spelled
+     * this two ways — `DatePicker.order` sorted an array, `DateRangePicker.order` swapped a pair,
+     * `MonthRangePicker` swapped unconditionally with no prop at all — which read as a collision
+     * but is one invariant seen through three value shapes. Set `false` to keep pick order.
+     */
     order?: boolean;
     showTime?: boolean | Pick<TimePickerProp, "hourStep" | "minuteStep" | "secondStep" | "showSeconds" | "use12Hours" | "disabledTime">;
-    presets?: {
-        label: React.ReactNode;
-        value: Date | (() => Date);
-    }[];
     placeholder?: PlaceholderProp;
-    disabled?: DisabledProp;
+    /**
+     * Inert control. With `range`, the TUPLE form `[from, to]` locks one endpoint and leaves the
+     * other editable (antd's RangePicker `disabled`) — "the start date is fixed by the contract,
+     * only the end is negotiable" is a real screen that a scalar cannot say. The tuple is
+     * meaningless without `range` and is ignored there.
+     */
+    disabled?: DisabledProp | [boolean, boolean];
     className?: ClassNameProp;
     id?: IdProp;
-    /** Form field name — emits the value as an ISO-8601 `yyyy-MM-dd` string for native submission. */
+    /**
+     * Form field name. Submits ISO-8601 at the precision `picker` selects — `2026-03-01` for
+     * `date`/`week`, `2026-03` for `month` and `quarter` (the period's first month), `2026` for
+     * `year`. With `range`, the pair submits as `${name}_from` / `${name}_to`.
+     */
     name?: NameProp;
     locale?: DayPickerProps["locale"];
     fromDate?: Date;
@@ -608,11 +731,11 @@ export type DatePickerBaseProp = FieldA11yProps & PickerChromeProp & {
     /** Decorate a day cell — 祝日, a booked day, a deadline. @see CalendarCellRenderProp */
     cellRender?: CalendarCellRenderProp;
     /**
-     * Forbid individual dates by predicate — the rule `fromDate`/`toDate` cannot express, because a
+     * Forbid individual dates by predicate — the rule `minDate`/`maxDate` cannot express, because a
      * business calendar is rarely one contiguous range: 土日, a closed accounting period, a 祝日, a
      * day already fully booked.
      *
-     * Applies to BOTH routes into the value. The calendar greys the cell out, and a date typed into
+     * Applies to BOTH routes into the value. The grid greys the cell out, and a date typed into
      * the field is rejected the same way an unparseable one is — otherwise the keyboard becomes a
      * way around the rule the mouse obeys.
      */
@@ -623,104 +746,50 @@ export type DatePickerBaseProp = FieldA11yProps & PickerChromeProp & {
      */
     allowClear?: AllowClearProp;
 } & Pick<CalendarFooterProp, "showToday" | "showClose">;
-/** Single and multiple selections keep their callback types distinct. */
+/**
+ * CARDINALITY. One `Date`, an array of them, or a `DateRange` — each keeps its own callback type,
+ * so a consumer never has to narrow what it gets back.
+ */
 export type DatePickerProp = DatePickerBaseProp & ({
+    range?: false;
     multiple?: false;
     value?: Date;
     defaultValue?: Date;
     onValueChange?: (value: Date | undefined) => void;
+    presets?: {
+        label: React.ReactNode;
+        value: Date | (() => Date);
+    }[];
 } | {
+    range?: false;
     multiple: true;
     value?: Date[];
     defaultValue?: Date[];
     onValueChange?: (value: Date[] | undefined) => void;
     showTime?: false;
-});
-/** @see MonthPicker */
-export type MonthPickerProp = FieldA11yProps & PickerChromeProp & {
-    value?: ValueProp<Date>;
-    defaultValue?: DefaultValueProp<Date | undefined>;
-    onValueChange?: OnValueChangeProp<Date | undefined>;
-    placeholder?: PlaceholderProp;
-    disabled?: DisabledProp;
-    className?: ClassNameProp;
-    id?: IdProp;
-    /** Form field name — submits the display text (`yyyy/MM`). */
-    name?: NameProp;
-    /** Clamp the year navigation (inclusive). */
-    fromYear?: number;
-    toYear?: number;
-    /**
-     * Show an inline ✕ to clear the value when one is set (default true). The OBJECT form
-     * additionally replaces the icon and/or the accessible label (antd `allowClear`).
-     */
-    allowClear?: AllowClearProp;
-    /** Node appended below the month grid (antd `renderExtraFooter`). */
-    renderExtraFooter?: () => React.ReactNode;
-};
-/**
- * @see MonthRangePicker — both edges are normalized to the FIRST day of their month
- * (the `DateRange` shape is shared with DateRangePicker so ranges interop).
- */
-export type MonthRangePickerProp = FieldA11yProps & PickerChromeProp & {
-    value?: ValueProp<DateRange>;
-    defaultValue?: DefaultValueProp<DateRange | undefined>;
-    onValueChange?: OnValueChangeProp<DateRange | undefined>;
-    placeholder?: PlaceholderProp;
-    disabled?: DisabledProp;
-    className?: ClassNameProp;
-    id?: IdProp;
-    /** Form field name — emits the range as `${name}_from` / `${name}_to` `yyyy/MM` fields. */
-    name?: NameProp;
-    /** Clamp the year navigation (inclusive). */
-    fromYear?: number;
-    toYear?: number;
+    presets?: {
+        label: React.ReactNode;
+        value: Date | (() => Date);
+    }[];
+} | {
     /**
-     * Show an inline ✕ to clear the range when one is set (default true). The OBJECT form
-     * additionally replaces the icon and/or the accessible label (antd `allowClear`).
+     * Two endpoints in one field — antd's `DatePicker.RangePicker`, which this library used to
+     * ship as two separate components (`DateRangePicker`, `MonthRangePicker`). It composes with
+     * `picker`, so a month range is `<DatePicker range picker="month" />`.
      */
-    allowClear?: AllowClearProp;
-    /** Node appended below the month grid (antd `renderExtraFooter`). */
-    renderExtraFooter?: () => React.ReactNode;
-};
-/** @see DateRangePicker */
-export type DateRangePickerProp = FieldA11yProps & PickerChromeProp & {
-    /** Display format; native submission remains ISO. */
-    format?: PickerDateFormatProp;
-    /** Parser for a custom display function or Intl era display; ISO always remains accepted. */
-    parseFormat?: (text: string) => Date | undefined;
-    minDate?: Date;
-    maxDate?: Date;
-    showWeek?: boolean;
-    needConfirm?: boolean;
+    range: true;
+    multiple?: false;
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onValueChange?: (value: DateRange | undefined) => void;
+    showTime?: false;
+    /** Which endpoints may stay empty (antd `allowEmpty`), as `[from, to]`. */
+    allowEmpty?: [boolean, boolean];
     presets?: {
         label: React.ReactNode;
         value: DateRange | (() => DateRange);
     }[];
-    allowEmpty?: [boolean, boolean];
-    order?: boolean;
-    value?: ValueProp<DateRange>;
-    defaultValue?: DefaultValueProp<DateRange | undefined>;
-    onValueChange?: OnValueChangeProp<DateRange | undefined>;
-    placeholder?: PlaceholderProp;
-    disabled?: DisabledProp;
-    className?: ClassNameProp;
-    id?: IdProp;
-    /** Form field name — emits the range as `${name}_from` / `${name}_to` ISO `yyyy-MM-dd` fields. */
-    name?: NameProp;
-    locale?: DayPickerProps["locale"];
-    fromDate?: Date;
-    toDate?: Date;
-    /** Decorate a day cell — see `CalendarCellRenderProp`. */
-    cellRender?: CalendarCellRenderProp;
-    /** Forbid individual dates by predicate — see `DatePickerProp.disabledDate`. */
-    disabledDate?: (date: Date) => boolean;
-    /**
-     * antd `allowClear` — an inline ✕ that clears the range when one is set (default true). The
-     * OBJECT form additionally replaces the icon and/or the accessible label.
-     */
-    allowClear?: AllowClearProp;
-} & Pick<CalendarFooterProp, "showToday" | "showClose">;
+});
 /**
  * Which times a TimePicker refuses, in antd's shape: one call returns the two predicates, so a
  * consumer computing them from the same source (a start time, a shift window) does that work once
@@ -889,6 +958,18 @@ export type SearchSelectBaseProp = {
     readOnly?: boolean;
     /** Trigger height tier — forwarded to the underlying Button. Default matches Button's own default. */
     size?: SizeProp;
+    /**
+     * Trigger width, the SAME axis `SelectTrigger` carries on the compound API — `full` (default,
+     * the width a field wants), `auto` (the width the current label wants), `bounded` (one width
+     * from `--control-bounded-width`, for a trigger whose value varies in length).
+     *
+     * It exists here because the two APIs are one component to a caller: `docs/CONSUMER-RULES.md`
+     * rule 5 tells everyone that "a Select outside a form takes `width=\"auto\"`", and until this
+     * prop existed that sentence was false for the `options` form — a filter bar with two of them
+     * stretched each to full width and stacked them, and the only way out was to wrap each in a
+     * `<Flex width={280}>`.
+     */
+    width?: ControlWidthProp;
     /**
      * Validation status (antd `status`). `error` recolours the trigger AND sets `aria-invalid`;
      * `warning` recolours only. A `status` set here never overrides an `aria-invalid` arriving from
@@ -1376,3 +1457,130 @@ export type BranchScopePickerProp = FieldA11yProps & {
     id?: IdProp;
     className?: ClassNameProp;
 };
+/**
+ * Which keystroke SENDS and which one breaks the line — Ant Design X `Sender.submitType`.
+ *
+ * `enter` (default) is the chat convention: `Enter` sends, `Shift+Enter` inserts a newline.
+ * `shiftEnter` is the inverse, for composers that hold long, deliberately multi-line drafts.
+ * Neither ever fires while an IME conversion is in flight.
+ * @see ChatComposer
+ */
+export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter";
+/**
+ * @see ChatComposer — the message input of a conversation (Ant Design X `Sender`; the industry
+ * calls the control a *composer*, so that is what it is named).
+ *
+ * Built on the real `Textarea` (auto-growing between `--chat-composer-min-height` and
+ * `--chat-composer-max-height`, both derived from the `--control-height` tier) plus real
+ * `Button`s. The `<textarea>` is the semantic focus target: `ref`, `id`, `name` and the whole
+ * `FormField` label/helper/error contract land on it, so a ChatComposer inside a `FormField`
+ * behaves exactly like an `Input` does.
+ */
+export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit" | "defaultValue" | "prefix" | "onChange" | "onKeyDown"> & FieldA11yProps & {
+    /** Controlled draft text. Pair with `onValueChange` or the box freezes. */
+    value?: ValueProp<string>;
+    /** Uncontrolled initial draft text. */
+    defaultValue?: DefaultValueProp<string>;
+    /** Draft-text change handler — fires on every keystroke, including during an IME conversion. */
+    onValueChange?: OnValueChangeProp<string>;
+    /**
+     * Send the draft. Receives the text as typed; never fires for an empty or whitespace-only
+     * draft, and never while `loading`, `disabled` or `readOnly`.
+     */
+    onSubmit?: (value: string) => void;
+    /** Stop the in-flight response. Only reachable while `loading`. */
+    onCancel?: () => void;
+    /**
+     * A response is streaming. The trailing action becomes CANCEL — exactly one trailing action
+     * exists at a time, the same discipline as the picker trailing-action rule.
+     */
+    loading?: PendingProp;
+    /** Which keystroke sends and which breaks the line. Default `enter`. */
+    submitType?: ChatComposerSubmitTypeProp;
+    /** Empty-state text of the draft box; pass it through `t()` at the call site. */
+    placeholder?: PlaceholderProp;
+    /** Disable the whole composer (draft box and every action). */
+    disabled?: DisabledProp;
+    /** Show the draft without allowing an edit; still focusable and selectable. */
+    readOnly?: boolean;
+    /** Slot ABOVE the draft row — attachments, a reply-to banner, a model picker. */
+    header?: React.ReactNode;
+    /** Slot at the inline START of the draft row — an attach button, an avatar. */
+    prefix?: React.ReactNode;
+    /** Slot BELOW the draft row — a hint line, a token counter. */
+    footer?: React.ReactNode;
+    /** Extra trailing actions, rendered BEFORE the send/cancel action. */
+    actions?: React.ReactNode;
+    /** Control height tier on the shared `--control-height` ladder. Default `md`. */
+    size?: SizeProp;
+    /** Hard ceiling on the draft length, forwarded to the textarea. */
+    maxLength?: number;
+    /** Validation state the composer paints. `error` also reports `aria-invalid`. */
+    status?: ControlStatusProp;
+    /** Accessible name override for the send action (localized default otherwise). */
+    submitLabel?: string;
+    /** Accessible name override for the cancel action (localized default otherwise). */
+    cancelLabel?: string;
+    /** Keydown on the draft box — how `ChatSuggestion` drives its list from the composer. */
+    onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+    name?: NameProp;
+    id?: IdProp;
+    className?: ClassNameProp;
+};
+/** @see ChatSuggestion — one row of the trigger-character list. One level of `children` is honoured. */
+export type ChatSuggestionItemProp = {
+    /** Stable value handed to `onValueChange`, and the search haystack when there is no `label`. */
+    value: string;
+    /** Human row label. Falls back to `value`. */
+    label?: string;
+    /** Secondary line under the label. */
+    description?: string;
+    /** Decorative leading node (an icon). */
+    icon?: React.ReactNode;
+    /** Keep the row visible but unselectable. */
+    disabled?: DisabledProp;
+    /** One level of sub-rows; picking the parent drills into them instead of emitting a value. */
+    children?: readonly ChatSuggestionItemProp[];
+};
+/** The render-prop bag `ChatSuggestion` hands to the composer it wraps. */
+export type ChatSuggestionRenderProp = {
+    /**
+     * Re-read the caret and decide whether the list belongs open — call it from the composer's
+     * `onValueChange`. `false` force-closes; no argument force-opens with an empty query.
+     */
+    onTrigger: (value?: string | false) => void;
+    /** Forward to the composer's `onKeyDown`: arrows move, Enter/Tab pick, Escape closes. */
+    onKeyDown: React.KeyboardEventHandler<HTMLTextAreaElement>;
+};
+/**
+ * @see ChatSuggestion — trigger-character autocomplete over a `ChatComposer` (Ant Design X
+ * `Suggestion`).
+ *
+ * The list itself is the existing `Command` (cmdk) inside a `Popover`, so the listbox ARIA comes
+ * from a primitive that already ships it. What this component owns is the part `Command` does not:
+ * spotting the trigger character at the caret in a textarea, tracking the query as the caret
+ * moves, and closing on `Escape` / blur / a word break — `Escape` returns focus to the textarea
+ * and leaves the typed text exactly as it was.
+ */
+export type ChatSuggestionProp = {
+    /** The rows to offer. One level of `children` is honoured. */
+    items: readonly ChatSuggestionItemProp[];
+    /** Fires with the picked row's `value`. The caller owns what that does to the draft text. */
+    onValueChange?: OnValueChangeProp<string>;
+    /** The character that opens the list when typed at a word boundary. Default `/`. */
+    triggerCharacter?: string;
+    /** Controlled open state. */
+    open?: OpenProp;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: DefaultOpenProp;
+    /** Open-state change handler. */
+    onOpenChange?: OnOpenChangeProp;
+    /** The composer to wrap — receives `{ onTrigger, onKeyDown }`. */
+    children: (props: ChatSuggestionRenderProp) => React.ReactNode;
+    /** Text shown when the query matches nothing (localized default otherwise). */
+    emptyMessage?: EmptyMessageProp;
+    /** Accessible name of the suggestion listbox — a plain string (localized default otherwise). */
+    listLabel?: string;
+    id?: IdProp;
+    className?: ClassNameProp;
+};

package/dist/props/components/index.d.ts

@@ -1,6 +1,6 @@
 export type { AppLauncherApp, AppLauncherGroup, AppLauncherLabels, AppLauncherProp, AppShellProp, AuthFooterProp, AuthIdentityProp, OrgSwitcherLabels, OrgSwitcherOrganization, OrgSwitcherProp, PageContainerProp, PageInsetProp, SidebarItemProp, SidebarProductProp, SidebarProp, SidebarSectionProp, TopbarProp, } from "./layout.prop.js";
 export type { ButtonProp } from "./general.prop.js";
-export type { InputProp, TextareaProp, FormFieldProp, SearchInputProp, CheckboxProp, CheckboxGroupProp, ChoiceOptionProp, RadioProp, RadioGroupProp, SwitchProp, SliderProp, CalendarProp, DatePickerProp, DateRangePickerProp, TimePickerProp, ColorPickerProp, UploadProp, UploadFileItemProp, UploadVariantProp, TreeOptionProp, TreeFieldNamesProp, CascaderProp, TreeSelectProp, ShowCheckedStrategyProp, TransferProp, TransferItemProp, } from "./data-entry.prop.js";
+export type { InputProp, TextareaProp, FormFieldProp, SearchInputProp, CheckboxProp, CheckboxGroupProp, ChoiceOptionProp, RadioProp, RadioGroupProp, SwitchProp, SliderProp, CalendarProp, DatePickerProp, TimePickerProp, ColorPickerProp, UploadProp, UploadFileItemProp, UploadVariantProp, TreeOptionProp, TreeFieldNamesProp, CascaderProp, TreeSelectProp, ShowCheckedStrategyProp, TransferProp, TransferItemProp, } from "./data-entry.prop.js";
 export type { AvatarProp, EmptyStateProp, DescriptionsProp, DescriptionsItemProp, BadgeProp, DataTableProp, QrCodeProp, } from "./data-display.prop.js";
 export type { ChartDatum, ChartSeriesProp, LineChartProp, BarChartProp, AreaChartProp, PieChartProp, } from "./charts.prop.js";
 export type { AlertQueryErrorProp, AlertProp, AlertTitleProp, AlertContentProp, AlertDescriptionProp, AlertActionsProp, SheetResponsiveProp, SkeletonRowsProp, } from "./feedback.prop.js";

package/dist/props/components/layout.prop.d.ts

@@ -1,7 +1,7 @@
 /** Layout component prop types — @see docs/COMPONENTS.md#layout */
 import type * as React from "react";
 import type { ComponentType, ReactNode, SVGProps } from "react";
-import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, OrientationProp, TextAlignProp, TextToneProp, BreakpointProp, GapProp, PadProp, PadRawProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp, WidthProp } from "../vocabulary/index.js";
+import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, MobileShellWidthProp, OrientationProp, TextAlignProp, TextToneProp, BreakpointProp, GapProp, PadProp, PadRawProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp, WidthProp } from "../vocabulary/index.js";
 import type { EmptyStateToneProp } from "./data-display.prop.js";
 /**
  * Arrangement of the page header's title band and its `extra` slot below the 640px step.
@@ -505,6 +505,17 @@ export type MobileShellProp = {
      * device-frame preview, a phone view embedded in a wider page).
      */
     height?: MobileShellHeightProp;
+    /**
+     * How wide the shell is allowed to get. `"fill"` (default) takes the whole inline size it is
+     * given — a real handheld, where that IS the phone. `"phone"` caps it at
+     * `--mobile-shell-max-inline-size` and centres the column, for the case `height="fill"` already
+     * names on the other axis: a handheld screen rendered on a viewport wider than a handheld.
+     *
+     * Measured at a 1280px viewport before this axis existed: `max-inline-size: none`, shell 1232px
+     * wide, a four-destination tab bar spread across the whole screen. `height` had two named values
+     * for exactly these two contexts and `width` had none — the asymmetry was the bug.
+     */
+    width?: MobileShellWidthProp;
     className?: ClassNameProp;
 };
 /**

package/dist/props/components/navigation.prop.d.ts

@@ -190,7 +190,19 @@ export type StepItemProp = {
  */
 export type StepsTypeProp = "default" | "dot" | "inline" | "navigation";
 /** @see Steps */
-export type StepsProp = {
+/**
+ * The rest of a native `<ol>`'s attributes ride through to the list element.
+ *
+ * Not a convenience: without them a consumer had no supported handle on the rendered list at all,
+ * so its browser test bound to `.ui-steps-list > li[data-status]` — an INTERNAL class and an
+ * internal data attribute, both of which this package is free to rename. A `data-testid` or an
+ * `id` on the component is what that test wanted, and every sibling primitive already forwards
+ * them.
+ *
+ * `aria-label` is the one exception: the list names itself from the locale, and a caller-supplied
+ * name wins — the same contract Progress and Toolbar follow.
+ */
+export type StepsProp = Omit<React.OlHTMLAttributes<HTMLOListElement>, "onChange" | "defaultValue" | "children" | "type"> & {
     items?: StepItemProp[];
     value?: number;
     defaultValue?: number;
@@ -235,6 +247,17 @@ export type TabItemProp = {
     closable?: boolean;
     /** Ant Design `Tab.closeIcon` — replaces the default × on this item's remove button. */
     closeIcon?: React.ReactNode;
+    /**
+     * Ant Design `Tab.forceRender`. Mounts THIS panel up front and keeps it mounted while another
+     * tab is selected, without turning that on for the whole strip the way `destroyOnHidden={false}`
+     * does — so the one panel holding a live chart, a scroll position or an unsent draft survives a
+     * tab switch while the rest are still destroyed.
+     *
+     * antd 5.25 also grew a per-item `destroyOnHidden`. It is NOT offered here: on this component
+     * "kept mounted" is a single state, so an item-level `destroyOnHidden: false` would be a second
+     * prop spelling exactly what `forceRender: true` already says (cardinal rule #32).
+     */
+    forceRender?: boolean;
 };
 /**
  * @see Tabs — trigger-strip appearance. This is Ant Design's `type` spelled in the library's own
@@ -264,6 +287,32 @@ export type TabsExtraProp = React.ReactNode | {
  * commas, and an inline `(target, action) => void` leaks its second PARAMETER as a phantom prop.
  */
 export type TabsOnEditProp = (target: string | React.MouseEvent<HTMLButtonElement>, action: "add" | "remove") => void;
+/**
+ * @see Tabs — what the trigger strip does when there are more tabs than fit its container.
+ *
+ * This is Ant Design's `more`, mapped onto the `overflow` vocabulary this package already uses
+ * for the same question (`FilterBarOverflowProp` on Toolbar) rather than re-spelled: antd names
+ * the AFFORDANCE it happens to draw, this library names the BEHAVIOUR and owns the affordance.
+ *
+ * `scroll` (the default, and what every strip does today) keeps one bounded row that scrolls its
+ * own inline overflow, with `TabsList` re-pinning the active — or, under manual activation, the
+ * focused — trigger. `menu` keeps all of that AND puts a real button beside the strip listing the
+ * tabs currently outside the scrollport.
+ *
+ * WHERE THIS DELIBERATELY DIVERGES FROM ANTD, and why: antd REMOVES the overflowing tabs from the
+ * bar and re-homes them in the dropdown. The WAI-ARIA APG tab pattern requires the tablist to own
+ * every tab, and a tab hidden with `display: none` cannot take roving focus — so removing them
+ * would make the keyboard route to those tabs disappear along with the pixels. Here the strip
+ * still holds and still scrolls to every tab; the menu is an ADDITIONAL pointer route to the ones
+ * a mouse user cannot currently see. The APG wins; the affordance is kept.
+ */
+export type TabsOverflowProp = "scroll" | "menu";
+/**
+ * @see Tabs — Ant Design `onTabClick`. A NAMED alias rather than an inline signature for the same
+ * reason as `TabsOnEditProp`: the catalog-sync guard splits an object type on top-level commas,
+ * so an inline `(value, event) => void` leaks its second PARAMETER as a phantom prop.
+ */
+export type TabsOnTabClickProp = (value: string, event: React.MouseEvent<HTMLButtonElement>) => void;
 /** @see Tabs — high-level tabs with optional `items` array. */
 export type TabsProp = {
     items?: TabItemProp[];
@@ -292,6 +341,32 @@ export type TabsProp = {
     addIcon?: React.ReactNode;
     /** Ant Design `hideAdd` — keep `editable-card`'s remove buttons but drop the add button. */
     hideAdd?: boolean;
+    /**
+     * Ant Design `removeIcon` — the strip-wide default glyph on `editable-card`'s remove shortcut.
+     * A `TabItemProp.closeIcon` on one item still wins over it, which is antd's own precedence.
+     */
+    closeIcon?: React.ReactNode;
+    /**
+     * Ant Design `more`. Default `scroll` — the behaviour every strip has today, unchanged.
+     * @see TabsOverflowProp for what `menu` adds and where it parts company with antd.
+     *
+     * The default is deliberately NOT `menu`: switching it would change the rendered bar for every
+     * existing consumer at once, and which of the two a dense strip wants is a service decision, not
+     * a library one.
+     */
+    overflow?: TabsOverflowProp;
+    /**
+     * Ant Design `onTabClick`. Fires on EVERY pointer activation of a trigger — including a click on
+     * the tab that is already selected, where `onValueChange` is silent by design. That is the whole
+     * reason it is a separate prop and not a re-spelling of `onValueChange` (cardinal rule #32):
+     * "the user asked for this tab again" (re-fetch, close a drawer, scroll a panel back to the top)
+     * is a different event from "the selection changed".
+     *
+     * Keyboard activation is NOT routed here, and that is the APG winning over antd: under
+     * `activationMode="manual"` the arrow keys move focus without activating, so a key-driven
+     * "click" would be a fiction. Use `onValueChange` for selection, whatever moved it.
+     */
+    onTabClick?: TabsOnTabClickProp;
     className?: ClassNameProp;
     listClassName?: ClassNameProp;
     contentClassName?: ClassNameProp;