@tailor-platform/app-shell 1.11.0 → 1.12.0

package/dist/app-shell.d.ts

@@ -21,12 +21,15 @@ import { JSX } from 'react/jsx-runtime';
 import { Link } from 'react-router';
 import { LoaderFunctionArgs } from 'react-router';
 import { Menu as Menu_2 } from '@base-ui/react/menu';
+import { Navigate } from 'react-router';
 import { parseAbsolute } from '@internationalized/date';
 import { parseDate } from '@internationalized/date';
 import { parseDateTime } from '@internationalized/date';
 import { parseZonedDateTime } from '@internationalized/date';
 import * as React_2 from 'react';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RefObject } from 'react';
 import { Select as Select_2 } from '@base-ui/react/select';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -2210,6 +2213,14 @@ export declare interface DataTableContextValue<TRow extends Record<string, unkno
     clearSelection?: () => void;
     isAllSelected: boolean;
     isIndeterminate: boolean;
+    /** Ids of the currently expanded rows. */
+    expandedIds?: string[];
+    /** Whether `row` is currently expanded. Always `false` for rows without an `id`. */
+    isRowExpanded?: (row: TRow) => boolean;
+    toggleRowExpansion?: (row: TRow) => void;
+    collapseAllRows?: () => void;
+    /** Expansion config. Its presence enables the expand column and detail rows. */
+    rowExpansion?: RowExpansionOptions<TRow>;
 }
 
 /**
@@ -2309,10 +2320,30 @@ declare namespace DataTableToolbar {
     var displayName: string;
 }
 
-declare interface DateBehaviorProps<T extends DateValue> {
+/** Options for `type: "date"` cells. */
+declare interface DateCellOptions {
+    /**
+     * Format style. `"short"` → `Apr 9, 2026`; `"long"` → `April 9, 2026`;
+     * `"datetime"` → `Apr 9, 2026, 3:45 PM`. Default: `"short"`.
+     */
+    dateFormat?: "short" | "long" | "datetime";
+    /** BCP 47 locale tag. Defaults to the runtime locale. */
+    locale?: string;
+}
+
+/**
+ * Public date controls.
+ *
+ * These are standalone composite widgets built on plain accessible markup and a
+ * proxy input for form value / native validity. Inside `Field.Root`, they also
+ * register with Base UI's label, description, and validation plumbing. All of
+ * that coupling lives in `useDateFieldFieldBridge` (see `./use-date-field-bridge`).
+ */
+declare interface DateControlProps<T extends DateValue> {
     value?: T | null;
     defaultValue?: T | null;
     onChange?: (value: T | null) => void;
+    onBlur?: () => void;
     granularity?: Granularity;
     minValue?: DateValue;
     maxValue?: DateValue;
@@ -2323,52 +2354,32 @@ declare interface DateBehaviorProps<T extends DateValue> {
     isInvalid?: boolean;
     autoFocus?: boolean;
     hourCycle?: HourCycle;
-    hideTimeZone?: boolean;
     placeholderValue?: DateValue;
-    /**
-     * First day of the week (0 = Sunday … 6 = Saturday); defaults to the locale.
-     * Only affects the `w`/`k` (start/end of week) keyboard shortcuts here.
-     */
     firstDayOfWeek?: FirstDayOfWeek;
     name?: string;
-    /** Accessible name when no visible `label` is provided (e.g. a compact filter input). */
+    className?: string;
+    id?: string;
+    /** Accessible name when there is no visible label. */
     "aria-label"?: string;
+    /** ID of the element(s) that label the control. */
+    "aria-labelledby"?: string;
+    /** ID of the element(s) that describe the control. */
+    "aria-describedby"?: string;
     /** BCP-47 locale override; defaults to the AppShell formatting locale. */
     locale?: string;
 }
 
-/** Options for `type: "date"` cells. */
-declare interface DateCellOptions {
-    /**
-     * Format style. `"short"` → `Apr 9, 2026`; `"long"` → `April 9, 2026`;
-     * `"datetime"` → `Apr 9, 2026, 3:45 PM`. Default: `"short"`.
-     */
-    dateFormat?: "short" | "long" | "datetime";
-    /** BCP 47 locale tag. Defaults to the runtime locale. */
-    locale?: string;
-}
-
 /**
  * A segmented date/time input field with no popover.
  *
- * @example
- * ```tsx
- * import { DateField } from "@tailor-platform/app-shell";
- *
- * <DateField label="Invoice date" />
- * <DateField label="Created at" granularity="minute" />
- * ```
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
  */
-export declare function DateField<T extends DateValue = DateValue>({ label, description, errorMessage, className, locale: localeProp, value, defaultValue, onChange, granularity, hourCycle, placeholderValue, minValue, maxValue, isDateUnavailable, isDisabled, isReadOnly, isInvalid, isRequired, autoFocus, firstDayOfWeek, name, "aria-label": ariaLabel, }: DateFieldProps<T>): JSX.Element;
-
-declare interface DateFieldMetaProps {
-    label?: LocalizedString;
-    description?: LocalizedString;
-    errorMessage?: LocalizedString;
-    className?: string;
-}
+export declare const DateField: <T extends DateValue = DateValue>(props: DateFieldProps<T> & {
+    ref?: Ref<HTMLInputElement>;
+}) => ReactElement;
 
-export declare type DateFieldProps<T extends DateValue = DateValue> = DateFieldMetaProps & DateBehaviorProps<T>;
+export declare type DateFieldProps<T extends DateValue = DateValue> = DateControlProps<T>;
 
 /**
  * Date format options
@@ -2378,21 +2389,92 @@ declare type DateFormat = "short" | "medium" | "long" | "relative";
 /**
  * A date/time input with a popover calendar.
  *
- * Value type is driven by `granularity`:
- * - `"day"` (default) → `CalendarDate`
- * - `"hour" | "minute" | "second"` → `CalendarDateTime` (or `ZonedDateTime` when a `timeZone` is set)
- *
- * @example
- * ```tsx
- * import { DatePicker, today, getLocalTimeZone, type CalendarDate } from "@tailor-platform/app-shell";
+ * Compose with `Field.Root` for label / description / error presentation, or
+ * provide standalone ARIA wiring yourself.
+ */
+export declare const DatePicker: <T extends DateValue = DateValue>(props: DatePickerProps<T> & {
+    ref?: Ref<HTMLInputElement>;
+}) => ReactElement;
+
+export declare type DatePickerProps<T extends DateValue = DateValue> = DateControlProps<T> & {
+    /** IANA timezone; defaults to the AppShell `timeZone`. */
+    timeZone?: string;
+};
+
+/**
+ * Range calendar state — the logic react-aria's `useRangeCalendarState` would
+ * otherwise provide, on top of the shared `useCalendarGridState` engine.
  *
- * const [date, setDate] = useState<CalendarDate | null>(null);
- * <DatePicker label="Ship date" value={date} onChange={setDate} />
- * ```
+ * Selection is the react-aria two-click model: the first confirmed day sets an
+ * *anchor*; while the anchor is set the highlighted range live-extends to the
+ * focused day (keyboard nav and pointer hover both move it); the second
+ * confirmed day commits `{ start, end }` in one `onChange`. Picking a day
+ * before the anchor swaps the endpoints, so a committed range is always
+ * ordered — a reversed range can only be produced by typing into the field.
  */
-export declare function DatePicker<T extends DateValue = DateValue>({ label, description, errorMessage, className, locale: localeProp, timeZone: timeZoneProp, value, defaultValue, onChange, granularity, hourCycle, placeholderValue, minValue, maxValue, isDateUnavailable, isDisabled, isReadOnly, isInvalid, isRequired, autoFocus, firstDayOfWeek, name, "aria-label": ariaLabel, }: DatePickerProps<T>): JSX.Element;
+/** An inclusive date range. `start` and `end` may be the same day. */
+export declare interface DateRange<T extends DateValue = DateValue> {
+    start: T;
+    end: T;
+}
 
-export declare type DatePickerProps<T extends DateValue = DateValue> = DateFieldProps<T> & {
+export declare const DateRangePicker: <T extends DateValue = DateValue>(props: DateRangePickerProps<T> & {
+    ref?: Ref<HTMLInputElement>;
+}) => ReactElement;
+
+/**
+ * Public date-range control — the @internationalized/date + Base UI
+ * implementation, mirroring react-aria's `DateRangePicker` interaction spec.
+ *
+ * Like `DateField`/`DatePicker`, it is a standalone composite widget that also
+ * composes inside `Field.Root` (label / description / error / form validation).
+ * A single combined proxy input is registered as the one Field control (its
+ * value is empty until BOTH ends are complete, so `required` blocks a partial
+ * range); two optional plain hidden inputs (`startName` / `endName`) provide
+ * classic form-POST parity. A range typed in reverse is flagged invalid rather
+ * than swapped — only the calendar normalizes endpoint order.
+ */
+export declare type DateRangePickerProps<T extends DateValue = DateValue> = {
+    value?: DateRange<T> | null;
+    defaultValue?: DateRange<T> | null;
+    /**
+     * Fired with a complete `{ start, end }` range, or `null` when the range is
+     * cleared or becomes incomplete. Never fired for half-typed intermediates.
+     */
+    onChange?: (value: DateRange<T> | null) => void;
+    onBlur?: () => void;
+    granularity?: Granularity;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isRequired?: boolean;
+    isInvalid?: boolean;
+    autoFocus?: boolean;
+    hourCycle?: HourCycle;
+    placeholderValue?: DateValue;
+    firstDayOfWeek?: FirstDayOfWeek;
+    /**
+     * Name for the combined hidden proxy input — a single `name=start/end` field
+     * for native form POST, mirroring `DateField` / `DatePicker`. Inside
+     * `Field.Root`, the Field's `name` takes precedence. For two separate fields,
+     * use `startName` / `endName` instead.
+     */
+    name?: string;
+    /** Names for the two plain hidden start/end inputs (classic form POST). */
+    startName?: string;
+    endName?: string;
+    className?: string;
+    id?: string;
+    /** Accessible name when there is no visible label. */
+    "aria-label"?: string;
+    /** ID of the element(s) that label the control. */
+    "aria-labelledby"?: string;
+    /** ID of the element(s) that describe the control. */
+    "aria-describedby"?: string;
+    /** BCP-47 locale override; defaults to the AppShell formatting locale. */
+    locale?: string;
     /** IANA timezone; defaults to the AppShell `timeZone`. */
     timeZone?: string;
 };
@@ -2743,6 +2825,8 @@ declare namespace Description_4 {
  * Renders structured key-value information with automatic layout.
  * Use { type: "divider" } in the fields array to add dividers between sections.
  *
+ * Pass `render` on a field to draw it yourself when no built-in `type` fits.
+ *
  * @example
  * ```tsx
  * <DescriptionCard
@@ -2753,22 +2837,26 @@ declare namespace Description_4 {
  *     { key: "orderNumber", label: "Order #", meta: { copyable: true } },
  *     { type: "divider" },
  *     { key: "total", label: "Total", type: "money" },
+ *     { key: "deliveryBreakdown", label: "Delivery", render: (d) => <PieChart data={d.deliveryBreakdown} /> },
  *   ]}
  * />
  * ```
  */
-export declare function DescriptionCard({ data, title, fields, columns, className, style, headerAction, }: DescriptionCardProps): JSX.Element;
+export declare function DescriptionCard<TData extends object = Record<string, unknown>>({ data, title, fields, columns, className, style, headerAction, }: DescriptionCardProps<TData>): JSX.Element;
 
 /**
  * Props for the DescriptionCard component
+ *
+ * `TData` is inferred from `data`; constrained to `object` rather than
+ * `Record<string, unknown>` so interfaces are accepted.
  */
-export declare interface DescriptionCardProps {
+export declare interface DescriptionCardProps<TData extends object = Record<string, unknown>> {
     /** Raw backend data object */
-    data: Record<string, unknown>;
+    data: TData;
     /** Card title */
     title: string;
     /** Ordered list of field definitions (use { type: "divider" } for dividers) */
-    fields: FieldConfig[];
+    fields: FieldConfig<TData>[];
     /** Number of columns on desktop (3 or 4) */
     columns?: Columns;
     /** Additional CSS classes */
@@ -3030,12 +3118,12 @@ export declare const Field: {
 /**
  * A field configuration - either a divider or a field definition
  */
-declare type FieldConfig = FieldDivider | FieldDefinition;
+declare type FieldConfig<TData extends object = Record<string, unknown>> = FieldDivider | FieldDefinition<TData>;
 
 /**
  * Field definition - renders a key-value pair
  */
-declare interface FieldDefinition {
+declare interface FieldDefinition<TData extends object = Record<string, unknown>> {
     /** Field type determines rendering (defaults to "text") */
     type?: FieldType_2;
     /** Path to the value in the data object (supports dot notation) */
@@ -3046,6 +3134,12 @@ declare interface FieldDefinition {
     meta?: FieldMeta;
     /** Behavior when value is empty (defaults to "dash") */
     emptyBehavior?: EmptyBehavior;
+    /**
+     * Draws the field from `data` instead of using `type`. Wins over `type` and
+     * replaces the built-in output, so `meta` is not applied. Still runs when the
+     * value at `key` is empty; `emptyBehavior: "hide"` is checked first.
+     */
+    render?: FieldRender<TData>;
 }
 
 /**
@@ -3108,6 +3202,9 @@ export declare interface FieldMetadata {
     };
 }
 
+/** Renders a field from the whole `data` object, like `render` on DataTable's `Column`. */
+declare type FieldRender<TData extends object = Record<string, unknown>> = (data: TData) => ReactNode;
+
 declare type FieldRootProps = Pick<React_2.ComponentProps<typeof Field_2.Root>, "name" | "disabled" | "validate" | "validationMode" | "validationDebounceTime" | "className" | "style"> & {
     children: React_2.ReactNode;
     /** Whether the field has been blurred. Maps to Base UI's `touched`. */
@@ -4031,6 +4128,8 @@ declare interface MoneyCellOptions<TRow extends Record<string, unknown>> {
     locale?: string;
 }
 
+export { Navigate }
+
 /**
  * Extract the node type from a cursor connection result.
  */
@@ -4225,6 +4324,48 @@ declare namespace RadioItemIndicator {
     var displayName: string;
 }
 
+/**
+ * A standalone inline range calendar. The first click sets one end of the
+ * range, the highlight follows the pointer (or arrow keys), and the second
+ * click completes it — picking a day before the first swaps the endpoints.
+ *
+ * @example
+ * ```tsx
+ * import { RangeCalendar, type DateRange } from "@tailor-platform/app-shell";
+ *
+ * const [range, setRange] = useState<DateRange | null>(null);
+ * <RangeCalendar aria-label="Stay dates" value={range} onChange={setRange} />
+ * ```
+ */
+export declare function RangeCalendar<T extends DateValue = DateValue>({ value, defaultValue, onChange, minValue, maxValue, isDateUnavailable, isDisabled, isReadOnly, focusedValue, defaultFocusedValue, onFocusChange, firstDayOfWeek, timeZone: timeZoneProp, locale: localeProp, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: RangeCalendarProps<T>): JSX.Element;
+
+/**
+ * Public, closed-API standalone range calendar — the @internationalized/date +
+ * Base UI implementation. Same surface as the react-aria variant; only the
+ * internals differ. Consumers never see Base UI or the calendar engine.
+ */
+export declare interface RangeCalendarProps<T extends DateValue = DateValue> {
+    value?: DateRange<T> | null;
+    defaultValue?: DateRange<T> | null;
+    /** Fired once per selection, when the second date completes the range. */
+    onChange?: (value: DateRange<T>) => void;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    focusedValue?: DateValue;
+    defaultFocusedValue?: DateValue;
+    onFocusChange?: (date: CalendarDate) => void;
+    firstDayOfWeek?: FirstDayOfWeek;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    timeZone?: string;
+    className?: string;
+    /** BCP-47 locale override; defaults to the AppShell formatting locale. */
+    locale?: string;
+}
+
 /**
  * Redirect to another path.
  *
@@ -4642,6 +4783,54 @@ export declare interface RowAction<TRow extends Record<string, unknown>> {
     onClick: (row: TRow) => void;
 }
 
+/**
+ * Expandable-row configuration for `useDataTable`.
+ *
+ * The union is what makes an invalid setup unrepresentable: pass `expandedIds`
+ * and you must pass `onChange` with it (controlled), or pass neither and let
+ * the hook own the state. `onChange` alone is still allowed — in uncontrolled
+ * mode it is a notification.
+ */
+declare type RowExpansionOptions<TRow extends Record<string, unknown>> = {
+    /** Renders the detail panel for an expanded row. */
+    render: (row: TRow) => ReactNode;
+    /**
+     * Decides whether a row can be expanded. Rows returning `false` render an
+     * empty cell in place of the chevron. Defaults to `true` for rows with an
+     * `id`. Gates the panel in both directions: an id in `expandedIds` never
+     * opens a panel for a row this rejects.
+     */
+    canExpand?: (row: TRow) => boolean;
+    /**
+     * The row's record identity — a **bare identifier** such as `"INV-1001"`, not
+     * a sentence. The built-in i18n labels compose it into the accessible names of
+     * the chevron ("Expand row INV-1001") and the panel ("INV-1001 details").
+     * Without it, the generic "Expand row" / "Row details" fallbacks are used.
+     */
+    getLabel?: (row: TRow) => string;
+} & ({
+    /**
+     * Ids of the expanded rows. Passing this switches expansion to
+     * **controlled** mode: internal state is never written and you update this
+     * array from `onChange`.
+     *
+     * **Batching caveat:** each toggle derives the next array from this
+     * value, so two toggles dispatched before your state commits share a base
+     * and the first is lost. Relevant behind an async store (a debounced URL
+     * sync, `startTransition`) or when looping the toggle over many rows.
+     */
+    expandedIds: string[];
+    /** Called with the full array of expanded ids. Fires once per toggle. */
+    onChange: (ids: string[]) => void;
+} | {
+    expandedIds?: never;
+    /**
+     * Optional notification in uncontrolled mode, called with the full array
+     * of expanded ids. Fires once per toggle, including under StrictMode.
+     */
+    onChange?: (ids: string[]) => void;
+});
+
 /**
  * Setter shape compatible with `useSearchParams()`.
  */
@@ -6615,6 +6804,22 @@ export declare type UseDataTableOptions<TRow extends Record<string, unknown>, TF
      * the rows on the **current page**, not all pages.
      */
     onSelectionChange?: (ids: string[]) => void;
+    /**
+     * Expandable detail rows. Providing this enables the whole feature: a chevron
+     * column is added at the left edge (auto-pinned left, after the selection
+     * column) and `render`'s output appears in a full-width row beneath its parent.
+     *
+     * Grouped rather than flat so the parts can't be configured in a broken
+     * combination — a label or predicate without a renderer, or `expandedIds`
+     * without `onChange`, are all compile errors.
+     *
+     * **Requirement:** Each row must have a string or number `id` field.
+     * Expansion is keyed by `id`, so rows without one render no chevron.
+     *
+     * **Note:** Expansion is **not** cleared on page change — ids of rows no
+     * longer on the page simply do not render. Call `collapseAllRows()` to reset.
+     */
+    rowExpansion?: RowExpansionOptions<TRow>;
     /**
      * Sort behaviour configuration.
      *
@@ -6699,6 +6904,16 @@ export declare interface UseDataTableReturn<TRow extends Record<string, unknown>
     clearSelection?: () => void;
     isAllSelected: boolean;
     isIndeterminate: boolean;
+    /** Ids of the currently expanded rows. */
+    expandedIds: string[];
+    /** Whether `row` is currently expanded. Always `false` for rows without an `id`. */
+    isRowExpanded: (row: TRow) => boolean;
+    /** Toggle `row`'s detail panel. Undefined when `rowExpansion` is not provided. */
+    toggleRowExpansion?: (row: TRow) => void;
+    /** Collapse every expanded row. Undefined when `rowExpansion` is not provided. */
+    collapseAllRows?: () => void;
+    /** Expansion config (passthrough for `DataTable.Root`). */
+    rowExpansion?: RowExpansionOptions<TRow>;
 }
 
 /**