@godxjp/ui 21.0.0 → 23.0.0

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

@@ -1,8 +1,4 @@
 /** 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";
@@ -39,8 +35,15 @@ export type InputOTPMaskProp = boolean | string;
  * The value is ALWAYS driven from here (`value` controlled, or `defaultValue` + internal state), so
  * `formatter` and `readOnly` hold for typing AND for paste — `input-otp` writes its own internal
  * state on paste, which a wrapper that only intercepted `onChange` could not undo.
+ *
+ * `style` is OMITTED because it cannot be honoured: `input-otp` owns both elements it could land
+ * on and writes their geometry itself — the field's own style object replaces anything passed in
+ * (measured: `style={{ color: "red" }}` left the input at the library's `color: transparent`) and
+ * the container's is hard-coded too. A type that accepts a prop the render can never deliver is
+ * the defect gh#477 reported for `id`; `id` is real and forwarded, this one was not. The paint of
+ * the field is reached through `className` / `containerClassName` and the `--otp-*` tokens.
  */
-export type InputOTPProp = Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "size" | "children"> & {
+export type InputOTPProp = Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "size" | "children" | "style"> & {
     /** Number of slots — antd `length`. Required by `input-otp`. */
     maxLength: number;
     value?: string;
@@ -285,6 +288,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 +335,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 +421,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 +489,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
@@ -467,43 +534,157 @@ export type FieldProp = {
     children: React.ReactNode;
 };
 /**
- * Tick marks on a slider rail — antd `SliderMarks`. Keyed by the value the mark sits on; the
- * value is the label. `null` renders the tick with no label.
+ * One tick on a slider rail — antd's two spellings: the label itself, or `{ label, style }` where
+ * the object also carries a per-mark inline style. `null` renders the tick with no label.
  */
-export type SliderMarksProp = Record<number, React.ReactNode>;
+export type SliderMarkProp = React.ReactNode | {
+    label?: React.ReactNode;
+    /** antd's per-mark style. Prefer styling the `label` node — it is already a ReactNode. */
+    style?: React.CSSProperties;
+};
 /**
- * antd `tooltip` — the value bubble over a dragging thumb. `false` switches it off, `true` uses
- * the raw value, and the object form formats it (a unit, a currency, a 全角 label).
+ * Tick marks on a slider rail — antd `SliderMarks`. Keyed by the value the mark sits on. With
+ * `step={null}` the marks (plus `min` and `max`) are the ONLY values the slider can take.
+ */
+export type SliderMarksProp = Record<number, SliderMarkProp>;
+/**
+ * antd `tooltip` — the value bubble over a thumb. `false` switches it off, `true` uses the raw
+ * value, and the object form formats and places it.
  */
 export type SliderTooltipProp = boolean | {
-    /** Force the bubble on/off instead of following hover/drag. */
+    /**
+     * `true` keeps the bubble visible; `false` keeps it hidden even while dragging or hovering —
+     * both exactly as antd. Unset, it follows hover, keyboard focus and drag.
+     */
     open?: boolean;
-    /** Render the bubble's content. `null` switches the bubble off, exactly as antd's does. */
+    /**
+     * Which side of the thumb. `left` / `right` are the INLINE sides and mirror under RTL like
+     * the rest of the slider. Defaults to `top`, or `right` on a vertical slider (antd's default).
+     */
+    placement?: "top" | "bottom" | "left" | "right";
+    /** Flip to the opposite side when the bubble would leave the viewport. Default `true`. */
+    autoAdjustOverflow?: boolean;
+    /**
+     * Render the bubble's content. `null` switches the bubble off, exactly as antd's does. A
+     * string or number result is ALSO the thumb's `aria-valuetext`, so a `¥50,000` slider is
+     * announced as ¥50,000 and not as a bare 50000.
+     */
     formatter?: ((value: number) => React.ReactNode) | null;
 };
-/** @see Slider — numeric range (Radix Slider). */
-export type SliderProp = React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> & {
+/**
+ * antd's range object — `range={{ editable, minCount, maxCount, draggableTrack }}`. Any object is
+ * a range, exactly like `range={true}`.
+ */
+export type SliderRangeConfigProp = {
+    /**
+     * Thumbs can be added and removed: a press on the rail ADDS one there, and Delete / Backspace on
+     * a focused thumb removes it. Ignored while any thumb is disabled, and wins over `draggableTrack`
+     * — both exactly as antd.
+     */
+    editable?: boolean;
+    /** Fewest thumbs `editable` may leave. Default 0. */
+    minCount?: number;
+    /** Most thumbs `editable` may create. Default unlimited. */
+    maxCount?: number;
+    /** Drag the painted span to move every thumb at once, keeping their distance. */
+    draggableTrack?: boolean;
+};
+/**
+ * @see Slider — numeric slider on react-aria-components, antd 6 `Slider` API.
+ *
+ * Written out rather than derived from the primitive, so what is public is exactly what is listed
+ * here: the Radix-era spelling (`number[]` values, `onValueChange`, `onValueCommit`, `inverted`,
+ * `dir`, `minStepsBetweenThumbs`) keeps compiling beside antd's (`number` values, `onChange`,
+ * `onChangeComplete`, `reverse`, `vertical`, `range` objects, `step={null}`).
+ *
+ * The union is on `range`, as in antd: without it `onChange` reports a `number`, with a literal
+ * `range` (or a range object) it reports `number[]`. A `range` held in a boolean variable cannot
+ * say which, so that spelling takes `onValueChange` — which always reports every thumb.
+ */
+export type SliderProp = Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange" | "dir" | "children"> & {
+    /** The low end of the scale. Default 0. */
+    min?: number;
+    /** The high end of the scale. Default 100. */
+    max?: number;
     /**
-     * antd `range` — two thumbs bounding a span rather than one thumb over a point. It is a
-     * DECLARATION, not an inference: a single-thumb slider whose `defaultValue` happens to be a
-     * two-element array used to become a range by accident, and a range whose value arrived
-     * asynchronously used to render as a point.
+     * Granularity. `null` is antd's marks-only mode: the thumbs can only rest on a mark, `min` or
+     * `max`. Default 1.
      */
-    range?: boolean;
+    step?: number | null;
+    /**
+     * Disable the whole slider, or — antd's array form — one thumb each: `[true, false]` locks the
+     * first thumb of a range. A disabled thumb leaves the tab order and does not submit.
+     */
+    disabled?: boolean | boolean[];
+    /** Layout axis. Default `horizontal`. Wins over `vertical`, as in antd 6. */
+    orientation?: "horizontal" | "vertical";
+    /** antd's boolean spelling of `orientation="vertical"`. */
+    vertical?: boolean;
+    /**
+     * Reading direction of a horizontal slider — which end is `min` and which arrow increases.
+     * Defaults to the locale's direction (the `I18nProvider` that `AppProvider` sets).
+     */
+    dir?: "ltr" | "rtl";
+    /** antd `reverse` — run the scale the other way (`min` at the inline end, or at the top). */
+    reverse?: boolean;
+    /** The Radix-era name for `reverse`. When both are given, `inverted` wins. */
+    inverted?: boolean;
+    /** Radix-era: the fewest steps two neighbouring thumbs may be apart. Default 0. */
+    minStepsBetweenThumbs?: number;
+    /** Every change, with EVERY thumb — the Radix-era callback, valid in every spelling. */
+    onValueChange?: (value: number[]) => void;
+    /** Once per finished gesture (pointer release, key press), with every thumb. */
+    onValueCommit?: (value: number[]) => void;
+    /**
+     * Native form field name. One thumb submits `name`; several submit `name[]`, once each.
+     */
+    name?: string;
+    /** Associate the thumbs' inputs with a form elsewhere in the document, by id. */
+    form?: string;
     /** antd `marks` — labelled ticks along the rail. */
     marks?: SliderMarksProp;
-    /** antd `dots` — a tick at every `step`. Requires a `step`. */
+    /** antd `dots` — a tick at every `step` (at every mark when `step={null}`). */
     dots?: boolean;
     /**
-     * antd `included` — whether the painted range is the span from the start to the thumb
-     * (`true`, the default) or nothing at all (`false`, for a rail that only holds marks).
+     * antd `included` — whether the painted span runs from the start to the thumb (`true`, the
+     * default) or nothing is painted at all (`false`, for a rail that only holds marks).
      */
     included?: boolean;
-    /** antd `reverse` — run the scale the other way. Radix spells the same thing `inverted`. */
-    reverse?: boolean;
-    /** antd `tooltip` — the value bubble over a dragging thumb. Off by default. */
+    /** antd `tooltip` — the value bubble over a thumb. Off by default. */
     tooltip?: SliderTooltipProp;
-};
+} & ({
+    /**
+     * One thumb. An array `value` with no `range` still draws a thumb per entry — the
+     * Radix-era inference — but `onChange` then reports only the first; use `onValueChange`
+     * for all of them, or declare `range`.
+     */
+    range?: false;
+    /** Controlled value — a number, or the Radix-era `number[]`. */
+    value?: number | number[];
+    /** Uncontrolled initial value. With nothing given the thumb starts at `min`. */
+    defaultValue?: number | number[];
+    /** antd `onChange` — every change, as a number. */
+    onChange?: (value: number) => void;
+    /** antd `onChangeComplete` — pointer release / key press, as a number. */
+    onChangeComplete?: (value: number) => void;
+} | {
+    /**
+     * antd `range` — two or more thumbs bounding spans. A DECLARATION: a range whose value is
+     * still loading does not render as a point, and without a value it spans `[min, max]`.
+     */
+    range: true | SliderRangeConfigProp;
+    value?: number[];
+    defaultValue?: number[];
+    onChange?: (value: number[]) => void;
+    onChangeComplete?: (value: number[]) => void;
+} | {
+    /** A `range` known only at run time (a boolean variable) — report through `onValueChange`. */
+    range: boolean;
+    value?: number | number[];
+    defaultValue?: number | number[];
+    onChange?: never;
+    onChangeComplete?: never;
+});
 /** @see Calendar — react-day-picker DayPicker plus an opt-in footer. */
 /**
  * Decorate one day cell — antd's `cellRender`, in the shape the Japanese market actually needs it:
@@ -579,28 +760,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 +851,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 +866,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
@@ -841,13 +1030,77 @@ export type SearchSelectLoadResultProp = {
     /** True if another page is available (drives infinite scroll). */
     hasMore?: boolean;
 };
+/**
+ * antd `fieldNames` — read rows in a FOREIGN shape (`{id, name}`, `{code, title}`) without mapping
+ * them first. The spelling matches the `fieldNames` Cascader and TreeSelect already take.
+ */
+export type SelectFieldNamesProp = {
+    label?: string;
+    value?: string;
+    /** Key holding a group's child rows — antd nests a group's options under the group. */
+    options?: string;
+    /** Key holding a group's heading; defaults to `label`, as in antd. */
+    groupLabel?: string;
+    disabled?: string;
+};
+/**
+ * A GROUP in antd's nested `options` shape — a heading plus its own rows. The flat
+ * `option.group` spelling this library already had keeps working; both arrive at the same list.
+ */
+export type SelectOptionGroupProp = {
+    label: string;
+    options: SearchSelectOptionProp[];
+    disabled?: boolean;
+};
+/** What `<Select options>` accepts: a row, a group of rows, or (with `fieldNames`) a foreign row. */
+export type SelectOptionInputProp = SearchSelectOptionProp | SelectOptionGroupProp | Record<string, unknown>;
+/**
+ * antd `labelInValue` — the value carries its own label, so a screen that only ever sees
+ * `{ value, label }` never has to keep the option list around to render what was picked (an async
+ * edit form whose page has not loaded yet is the case that needs it).
+ */
+export type SelectLabeledValueProp = {
+    value: string;
+    label: React.ReactNode;
+};
+/**
+ * antd `placement`, spelled on the LOGICAL inline axis — the same vocabulary
+ * `DropdownMenuPlacementProp` publishes, and for the same reason: antd's `bottomLeft` / `topRight`
+ * cannot mirror for an Arabic or Hebrew layout.
+ */
+export type SelectPlacementProp = "bottomStart" | "bottomEnd" | "topStart" | "topEnd";
+/**
+ * antd `showSearch`'s OBJECT form. Every field is the antd one, including
+ * `filterOption(input, option)` — note the argument order is antd's here, while the long-standing
+ * top-level `filterOption(option, query)` keeps this library's. Pass whichever you prefer; the
+ * object form wins when both are given.
+ */
+export type SelectShowSearchProp = {
+    /** `false` keeps every row (a server-filtered list); a function decides per row. */
+    filterOption?: boolean | ((input: string, option: SearchSelectOptionProp) => boolean);
+    /** Which field the default filter matches. antd's default is `value`; `label` is the common one. */
+    optionFilterProp?: "label" | "value" | "sublabel";
+    filterSort?: (a: SearchSelectOptionProp, b: SearchSelectOptionProp, info: {
+        searchValue: string;
+    }) => number;
+    searchValue?: string;
+    onSearch?: (value: string) => void;
+    autoClearSearchValue?: boolean;
+};
 /**
  * @see Select — the data-driven entry point (`<Select options|loadOptions showSearch …/>`).
  * This is the shape of its internal engine (`SelectDataProp` extends it); use `Select` directly.
  */
 export type SearchSelectBaseProp = {
-    /** Static option list (client-side filtered). Provide this OR `loadOptions`, not both. */
-    options?: SearchSelectOptionProp[];
+    /**
+     * Static option list (client-side filtered). Provide this OR `loadOptions`, not both.
+     *
+     * A row, or one of antd's nested GROUPS (`{ label, options }`) — both land in the same list, the
+     * group's heading becoming the `group` this library's flat rows already carry. Rows in a foreign
+     * shape go through `fieldNames` and need a cast at the call site, exactly as Cascader's and
+     * TreeSelect's do.
+     */
+    options?: (SearchSelectOptionProp | SelectOptionGroupProp)[];
     /** Remote fetcher — debounced search + infinite-scroll pagination call into this. Provide this
      *  OR `options`. */
     loadOptions?: (params: SearchSelectLoadParamsProp) => Promise<SearchSelectLoadResultProp>;
@@ -889,6 +1142,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
@@ -987,6 +1252,45 @@ export type SearchSelectBaseProp = {
     "data-testid"?: string;
     /** Normally injected by `FormField`. */
     "data-field"?: string;
+    /**
+     * antd `fieldNames` — map `{label, value, options, groupLabel, disabled}` onto foreign rows, so a
+     * server payload can be passed straight through instead of being copied into a second array.
+     */
+    fieldNames?: SelectFieldNamesProp;
+    /**
+     * antd `prefix` — a node pinned BEFORE the value on the trigger (a currency mark, an icon, a
+     * "To:" label). Decorative: it is not part of the control's accessible name.
+     */
+    prefix?: React.ReactNode;
+    /**
+     * antd `suffixIcon` — replaces the trailing chevron. `null` removes the indicator entirely (antd
+     * spells that `showArrow={false}`, which it deprecated in favour of exactly this).
+     */
+    suffixIcon?: React.ReactNode;
+    /**
+     * antd `placement`, on the logical inline axis. Absent = `bottomStart` with collision flipping,
+     * which is what a picker wants; set it only when the popup must open a specific way.
+     */
+    placement?: SelectPlacementProp;
+    /**
+     * antd `popupRender` — wrap the popup's own node (add a footer, a "create" action, a hint line).
+     * Receives the list and must render it: dropping `originNode` leaves a popup with no options.
+     */
+    popupRender?: (originNode: React.ReactNode) => React.ReactNode;
+    /**
+     * antd `listHeight` — the option list's maximum height in px. It overrides
+     * `--select-content-max-height` for this one control; the token stays the default everywhere
+     * else, so this is a per-instance override of a knob, not a new hard-coded height.
+     */
+    listHeight?: number;
+    /** antd `onPopupScroll` — fires on the option list's own scroll (an infinite-scroll hook). */
+    onPopupScroll?: (event: React.UIEvent<HTMLElement>) => void;
+    /**
+     * antd `optionFilterProp` — which field the default filter matches while searching. antd's
+     * default is `value`; this library keeps matching BOTH label and value when it is unset, because
+     * every call site that has ever relied on the default expects a label search.
+     */
+    optionFilterProp?: "label" | "value" | "sublabel";
 };
 /**
  * Single-select (the default): one `string` in, one `string` out — `""` means nothing selected.
@@ -994,6 +1298,8 @@ export type SearchSelectBaseProp = {
  */
 export type SearchSelectSingleProp = {
     mode?: undefined;
+    /** @see SelectLabelInValueSingleProp for the `{value,label}` dialect. */
+    labelInValue?: false;
     value?: ValueProp;
     /** Uncontrolled initial value — the trigger shows its option's label at rest (controlled-triad). */
     defaultValue?: DefaultValueProp;
@@ -1011,7 +1317,13 @@ export type SearchSelectSingleProp = {
  * per-chip remove button inside it would be a button nested in a button.
  */
 export type SearchSelectMultipleProp = {
-    mode: "multiple";
+    /**
+     * `multiple` picks from the list; `tags` also ACCEPTS what was typed, so a value that is not in
+     * the list can still be committed (antd's own distinction between the two).
+     */
+    mode: "multiple" | "tags";
+    /** @see SelectLabelInValueMultipleProp for the `{value,label}` dialect. */
+    labelInValue?: false;
     value?: ValueProp<string[]>;
     /** Uncontrolled initial selection (controlled-triad). */
     defaultValue?: DefaultValueProp<string[]>;
@@ -1030,6 +1342,64 @@ export type SearchSelectMultipleProp = {
     maxTagCount?: MaxTagCountProp;
     /** The node standing in for what `maxTagCount` hid (antd `maxTagPlaceholder`). */
     maxTagPlaceholder?: MaxTagPlaceholderProp;
+    /**
+     * antd `maxTagTextLength` — cut each chip's text to this many characters (an ellipsis marks the
+     * cut). It trims what the TRIGGER shows only; the value keeps its whole label.
+     */
+    maxTagTextLength?: number;
+    /**
+     * antd `tagRender` — render one chip yourself. Exactly the shape `TagInput`'s `tagRender` takes,
+     * so the two chip surfaces in this library are configured the same way. The `onClose` handed in
+     * is the same remover the built-in ✕ calls, so a custom chip cannot end up unremovable.
+     */
+    tagRender?: (props: {
+        value: string;
+        label: React.ReactNode;
+        onClose: () => void;
+        index: number;
+        disabled: boolean;
+    }) => React.ReactNode;
+    /**
+     * antd `tokenSeparators` — characters that commit what has been typed. Typing or PASTING
+     * "a,b,c" with `[","]` commits three values in one change, which is the point: a run pasted out
+     * of a spreadsheet becomes a selection instead of one long nonsense token. In `mode="multiple"`
+     * a token only counts when it matches a row; in `mode="tags"` it is accepted as it stands.
+     */
+    tokenSeparators?: string[];
+};
+/**
+ * antd `labelInValue`, single. The value carries its own label, so a screen that never sees the
+ * option list can still render what was picked.
+ */
+export type SelectLabelInValueSingleProp = {
+    labelInValue: true;
+    mode?: undefined;
+    value?: SelectLabeledValueProp | null;
+    defaultValue?: SelectLabeledValueProp | null;
+    onValueChange?: (value: SelectLabeledValueProp | undefined, option?: SearchSelectOptionProp) => void;
+    onSelect?: (value: SelectLabeledValueProp, option: SearchSelectOptionProp) => void;
+};
+/** antd `labelInValue`, multiple/tags. */
+export type SelectLabelInValueMultipleProp = {
+    labelInValue: true;
+    mode: "multiple" | "tags";
+    value?: SelectLabeledValueProp[];
+    defaultValue?: SelectLabeledValueProp[];
+    onValueChange?: (value: SelectLabeledValueProp[], options?: SearchSelectOptionProp[]) => void;
+    onSelect?: (value: SelectLabeledValueProp, option: SearchSelectOptionProp) => void;
+    onDeselect?: (value: SelectLabeledValueProp, option: SearchSelectOptionProp) => void;
+    maxCount?: number;
+    maxTagCount?: MaxTagCountProp;
+    maxTagPlaceholder?: MaxTagPlaceholderProp;
+    maxTagTextLength?: number;
+    tokenSeparators?: string[];
+    tagRender?: (props: {
+        value: string;
+        label: React.ReactNode;
+        onClose: () => void;
+        index: number;
+        disabled: boolean;
+    }) => React.ReactNode;
 };
 /** @see Select — the searchable engine. Single by default; `mode="multiple"` switches the shape. */
 export type SearchSelectProp = SearchSelectBaseProp & (SearchSelectSingleProp | SearchSelectMultipleProp);
@@ -1040,11 +1410,15 @@ export type SearchSelectProp = SearchSelectBaseProp & (SearchSelectSingleProp |
  */
 export type SelectDataProp = SearchSelectBaseProp & {
     /**
-     * Show the search box (combobox). Defaults to true when `loadOptions` is set or
-     * `mode="multiple"` is in force (antd's own defaults), otherwise false.
+     * Show the search box (combobox). Defaults to true when `loadOptions` is set or a multi-value
+     * `mode` is in force (antd's own defaults), otherwise false.
+     *
+     * The OBJECT form is antd's, and configures the search in one place —
+     * `{ filterOption, optionFilterProp, filterSort, searchValue, onSearch, autoClearSearchValue }`.
+     * Passing it also turns the search on.
      */
-    showSearch?: boolean;
-} & (SearchSelectSingleProp | SearchSelectMultipleProp);
+    showSearch?: boolean | SelectShowSearchProp;
+} & (SearchSelectSingleProp | SearchSelectMultipleProp | SelectLabelInValueSingleProp | SelectLabelInValueMultipleProp);
 /** @see UploadFileItem */
 export type UploadFileItemProp = UploadFileItem;
 /** @see Upload */