@tailor-platform/app-shell 1.9.0 → 1.10.0

package/dist/app-shell.d.ts

@@ -4,6 +4,7 @@ import { AutocompleteRootProps } from '@base-ui/react/autocomplete';
 import { Avatar as Avatar_2 } from '@base-ui/react/avatar';
 import { CalendarDate } from '@internationalized/date';
 import { CalendarDateTime } from '@internationalized/date';
+import { Checkbox as Checkbox_2 } from '@base-ui/react/checkbox';
 import { ClassProp } from 'class-variance-authority/types';
 import { Combobox as Combobox_2 } from '@base-ui/react/combobox';
 import { CSSProperties } from 'react';
@@ -256,6 +257,18 @@ declare type Anchor = "start" | "center" | "end";
  */
 export declare function AppearanceSwitcher(): JSX.Element;
 
+export declare type AppInfo = {
+    /** Additional app-defined rows shown on the built-in "/__appinfo" page. */
+    metadata?: readonly AppInfoEntry[];
+};
+
+export declare type AppInfoEntry = {
+    /** Display label shown on the built-in "/__appinfo" page. */
+    label: string;
+    /** Primitive value rendered as text. Format complex values before passing them in. */
+    value: string | number | boolean | null | undefined;
+};
+
 export declare const AppShell: {
     (props: AppShellProps): JSX.Element | null;
     WithPages(pages: PageEntry[]): FC<AppShellProps>;
@@ -269,6 +282,7 @@ declare type AppShellConfigContextType = {
     title?: string;
     icon?: ReactNode;
     favicon?: string;
+    appInfo?: AppInfo;
     configurations: RootConfiguration;
 };
 
@@ -426,10 +440,12 @@ declare type AsyncFetcher<T> = AsyncFetcherFn<T> | {
  * this one — pass it through to `fetch()` so the browser cancels the
  * in-flight HTTP request automatically.
  *
- * **Error handling:** Errors should be handled inside the fetcher.
- * If the fetcher throws, the component silently falls back to an empty
- * item list — there is no `onError` callback. Catch errors in the
- * fetcher to show toasts, log to error tracking, or return fallback data.
+ * **Error handling:** If the fetcher throws or rejects, the component renders
+ * a built-in inline error state (with a Retry affordance) in place of the
+ * empty state — the failure is no longer silently swallowed. Aborted/superseded
+ * requests are ignored. To run a side effect on failure (logging, error
+ * tracking, a toast), pass `onFetchError`; it fires once per outage rather
+ * than once per failed keystroke.
  *
  * The `query` parameter is `null` when the user has not typed anything
  * (e.g. the dropdown was just opened). Return initial / default items
@@ -586,6 +602,20 @@ declare interface AutocompleteAsyncStandaloneProps<T> extends AutocompletePropsB
     fetcher: AutocompleteAsyncFetcher<T>;
     /** Text shown while loading. @default "Loading..." */
     loadingText?: string;
+    /**
+     * Message shown in the popover when the fetcher fails, alongside a Retry
+     * affordance. Replaces the misleading empty state.
+     * @default "Couldn't load results."
+     */
+    errorText?: string;
+    /** Label for the retry button in the error state. @default "Retry" */
+    retryText?: string;
+    /**
+     * Called when a fetch fails. Fires once per outage (not per failed keystroke)
+     * and re-arms after the next success. Use for logging or error tracking — the
+     * inline error state is shown regardless.
+     */
+    onFetchError?: (error: unknown) => void;
 }
 
 declare function AutocompleteClear({ className, children, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Clear>): JSX.Element;
@@ -779,6 +809,8 @@ declare interface AutocompleteUseAsyncReturn<T> {
     value: string;
     /** The error thrown by the last fetch, if any */
     error: unknown;
+    /** Re-runs the most recent fetch immediately (no debounce). Use for a Retry affordance. */
+    retry: () => void;
     /** Value change handler — pass to the Root `onValueChange` prop. */
     onValueChange: (value: string) => void;
 }
@@ -962,6 +994,60 @@ declare type CellProps = React_2.ComponentProps<"td"> & {
     align?: CellAlign;
 };
 
+/**
+ * A styled checkbox for boolean form fields.
+ *
+ * Wraps Base UI's `Checkbox`, so it works with `Field` and React Hook Form the
+ * same way `Input`, `Select`, and `Combobox` do — placed inside a `Field.Root`
+ * it inherits label association, `aria-describedby`, `disabled`, and the
+ * `data-invalid` error state automatically (no `error` prop of its own).
+ *
+ * Supports controlled (`checked`) and uncontrolled (`defaultChecked`) use, plus
+ * an `indeterminate` "partially selected" state.
+ *
+ * @example
+ * ### Standalone with an inline label
+ * ```tsx
+ * const [checked, setChecked] = React.useState(false);
+ *
+ * <Checkbox label="Subscribe to updates" checked={checked} onCheckedChange={setChecked} />
+ * ```
+ *
+ * @example
+ * ### Inside a Field with React Hook Form
+ * ```tsx
+ * <Controller
+ *   name="acceptTerms"
+ *   control={control}
+ *   rules={{ required: "You must accept the terms." }}
+ *   render={({ field, fieldState }) => (
+ *     <Field.Root name={field.name} {...fieldState}>
+ *       <Checkbox
+ *         label="I accept the terms and conditions"
+ *         checked={field.value}
+ *         onCheckedChange={field.onChange}
+ *         onBlur={field.onBlur}
+ *         inputRef={field.ref}
+ *       />
+ *       <Field.Error />
+ *     </Field.Root>
+ *   )}
+ * />
+ * ```
+ *
+ * @example
+ * ### Indeterminate ("select all")
+ * ```tsx
+ * <Checkbox
+ *   aria-label="Select all rows"
+ *   checked={allSelected}
+ *   indeterminate={someSelected && !allSelected}
+ *   onCheckedChange={(checked) => (checked ? selectAll() : clearAll())}
+ * />
+ * ```
+ */
+export declare function Checkbox({ className, label, ...props }: CheckboxProps): JSX.Element;
+
 /** A menu item that toggles a setting on or off. */
 declare function CheckboxItem({ className, ...props }: React_2.ComponentProps<typeof Menu_2.CheckboxItem>): JSX.Element;
 
@@ -976,6 +1062,16 @@ declare namespace CheckboxItemIndicator {
     var displayName: string;
 }
 
+export declare type CheckboxProps = Omit<React_2.ComponentProps<typeof Checkbox_2.Root>, "children" | "render"> & {
+    /**
+     * Optional inline label rendered next to the box. When provided, the box and
+     * text are wrapped in an enclosing `<label>` so clicking the text toggles the
+     * checkbox. Omit it to render the bare box (e.g. a row-select cell with an
+     * `aria-label`, or a `Field.Label` sibling for the stacked form layout).
+     */
+    label?: React_2.ReactNode;
+};
+
 /** A button that closes the dialog. */
 declare function Close({ ...props }: React_2.ComponentProps<typeof Dialog_2.Close>): JSX.Element;
 
@@ -1146,7 +1242,10 @@ declare type ColumnArea = "left" | "main" | "right";
  * column types (e.g. `type MoneyColumn<TRow> = ColumnBase<TRow> & { type: "money"; … }`).
  */
 declare interface ColumnBase<TRow extends Record<string, unknown>> {
-    /** Column header text. Omit for action or icon-only columns. */
+    /**
+     * Column header text. Used as the default header content and passed to
+     * custom `header` renderers.
+     */
     label?: string;
     /**
      * Renders the cell content for a given row. Optional — when omitted, the
@@ -1158,6 +1257,16 @@ declare interface ColumnBase<TRow extends Record<string, unknown>> {
      * across spread-then-override patterns like `column({ ...inferred, render })`.
      */
     render?: (row: TRow) => ReactNode;
+    /**
+     * Custom header renderer.
+     *
+     * When omitted, the built-in header renders `label` and, for sortable
+     * columns, owns the sort button and indicator. When provided, the return
+     * value replaces the built-in header entirely. Sortable custom headers
+     * receive `sortDirection` and `activateSort()` and must render their own
+     * click surface and sort indicator.
+     */
+    header?: (ctx: HeaderRenderContext) => ReactNode;
     /**
      * Stable identifier used for column visibility toggling and as the React key.
      * Falls back to `label` when omitted. Set this explicitly when `label` is
@@ -1166,6 +1275,17 @@ declare interface ColumnBase<TRow extends Record<string, unknown>> {
     id?: string;
     /** Fixed column width in pixels. When omitted the column sizes naturally. */
     width?: number;
+    /**
+     * Freeze this column to the left or right edge so it stays visible while the
+     * table scrolls horizontally. This is the **default** pin; the user can
+     * override it at runtime via the toolbar's `columnSettings` control (persisted when
+     * `tableId` is set).
+     *
+     * Sticky offsets for stacked pinned columns are measured from the rendered
+     * layout, so a `width` is not required — but setting `width` on pinned columns
+     * is recommended so their size stays stable as row content changes.
+     */
+    pin?: "left" | "right";
     /**
      * Horizontal alignment for the header and body cell. When omitted, numeric
      * `type` values (`"number"` and `"money"`) default to `"right"` so digits
@@ -1342,6 +1462,20 @@ declare interface ComboboxAsyncOwnProps<T> {
     fetcher: ComboboxAsyncFetcher<T>;
     /** Text shown while loading. @default "Loading..." */
     loadingText?: string;
+    /**
+     * Message shown in the popover when the fetcher fails, alongside a Retry
+     * affordance. Replaces the misleading empty state.
+     * @default "Couldn't load results."
+     */
+    errorText?: string;
+    /** Label for the retry button in the error state. @default "Retry" */
+    retryText?: string;
+    /**
+     * Called when a fetch fails. Fires once per outage (not per failed keystroke)
+     * and re-arms after the next success. Use for logging or error tracking — the
+     * inline error state is shown regardless.
+     */
+    onFetchError?: (error: unknown) => void;
 }
 
 declare type ComboboxAsyncPlainProps<T> = (ComboboxAsyncOwnProps<T> & ComboboxPropsSingle<T>) | (ComboboxAsyncOwnProps<T> & ComboboxPropsMultiple<T>);
@@ -1979,8 +2113,9 @@ export declare const DataTable: {
      */
     readonly Root: typeof DataTableRoot;
     /**
-     * Container for toolbar content (column visibility, search, etc.).
-     * Place inside `DataTable.Root`, before `DataTable.Table`.
+     * Container for toolbar content (filters, search, etc.). Place inside
+     * `DataTable.Root`, before `DataTable.Table`. Pass `columnSettings` to render
+     * the built-in "Columns" control (show/hide, reorder, pin) at the top-right.
      */
     readonly Toolbar: typeof DataTableToolbar;
     /**
@@ -2057,6 +2192,11 @@ export declare interface DataTableContextValue<TRow extends Record<string, unkno
     showAllColumns: () => void;
     hideAllColumns: () => void;
     isColumnVisible: (fieldOrId: string) => boolean;
+    columnOrder: string[];
+    moveColumn: (key: string, toIndex: number) => void;
+    setColumnOrder: (keys: string[]) => void;
+    pinnedColumns: Record<string, "left" | "right" | "none">;
+    setPin: (key: string, side: "left" | "right" | "none" | null) => void;
     onClickRow?: (row: TRow) => void;
     rowActions?: RowAction<TRow>[];
     selectedIds: string[];
@@ -2082,8 +2222,20 @@ export declare interface DataTableData<TRow> {
 }
 
 /** Use `DataTable.Filters` instead of calling this directly. */
-declare function DataTableFilters({ className }: {
+declare function DataTableFilters({ className, slot, addIconOnly, }: {
     className?: string;
+    /**
+     * Which part to render, for custom toolbar layouts:
+     * - `"all"` (default) — active filter chips plus the **Add filter** trigger.
+     * - `"chips"` — only the active filter chips (renders nothing when there are none).
+     * - `"add"` — only the **Add filter** trigger.
+     *
+     * Render `"add"` and `"chips"` separately to place the trigger and the chips on
+     * different rows (e.g. the trigger in a header row, chips on the row below).
+     */
+    slot?: "all" | "chips" | "add";
+    /** Render the **Add filter** trigger as an icon-only button (label → `aria-label`). */
+    addIconOnly?: boolean;
 }): JSX.Element | null;
 
 declare namespace DataTableFilters {
@@ -2138,8 +2290,15 @@ declare namespace DataTableTable {
 }
 
 /** Use `DataTable.Toolbar` instead of calling this directly. */
-declare function DataTableToolbar({ children, className }: {
-    children: ReactNode;
+declare function DataTableToolbar({ children, columnSettings, className, }: {
+    children?: ReactNode;
+    /**
+     * Render the built-in column-settings control (a "Columns" button that opens
+     * the show/hide + reorder + pin popover) anchored to the top-right of the
+     * toolbar. The button always lives in the same place, so it's a prop rather
+     * than a separately-composed sub-component.
+     */
+    columnSettings?: boolean;
     className?: string;
 }): JSX.Element;
 
@@ -3418,6 +3577,11 @@ declare type HeaderProps = Omit<React_2.ComponentProps<"div">, "title"> & {
     description?: React_2.ReactNode;
 };
 
+/**
+ * Context passed to custom `header` renderers.
+ */
+export declare type HeaderRenderContext = NonSortableHeaderRenderContext | SortableHeaderRenderContext;
+
 declare type HeadProps = React_2.ComponentProps<"th"> & {
     align?: CellAlign;
 };
@@ -3873,6 +4037,14 @@ export declare type NodeType<T extends {
     }[];
 } | null | undefined> = NonNullable<T>["edges"][number]["node"];
 
+/**
+ * Header render context for non-sortable columns.
+ */
+declare interface NonSortableHeaderRenderContext {
+    label?: string;
+    sortable: false;
+}
+
 /** Options for `type: "number"` cells. */
 declare interface NumberCellOptions {
     /** Minimum decimal places. Default: `0`. */
@@ -4262,7 +4434,7 @@ declare namespace Root_3 {
  * </Table.Root>
  * ```
  */
-declare function Root_4({ className, containerClassName, ...props }: RootProps_2): JSX.Element;
+declare function Root_4({ className, containerClassName, containerRef, ...props }: RootProps_2): JSX.Element;
 
 declare namespace Root_4 {
     var displayName: string;
@@ -4404,6 +4576,8 @@ declare type RootProps = React_2.ComponentProps<"div"> & VariantProps<typeof ale
 declare type RootProps_2 = React_2.ComponentProps<"table"> & {
     /** Additional CSS classes for the outer scrollable `<div>` container. Use this to control height, overflow, or container-level layout. */
     containerClassName?: string;
+    /** Ref to the outer scrollable `<div>` container (e.g. to attach a scroll listener). */
+    containerRef?: React_2.Ref<HTMLDivElement>;
 };
 
 declare type RootProps_3 = Pick<React_2.ComponentProps<typeof Tabs_2.Root>, "defaultValue" | "value" | "onValueChange"> & {
@@ -4514,10 +4688,10 @@ export declare const Select: SelectComponent;
  * If caching or deduplication is needed, implement it in the fetcher
  * (e.g. via a query library or a simple cache layer).
  *
- * **Error handling:** Errors should be handled inside the fetcher.
- * If the fetcher throws, the component silently falls back to an empty
- * item list — there is no `onError` callback. Catch errors in the
- * fetcher to show toasts, log to error tracking, or return fallback data.
+ * **Error handling:** If the fetcher throws or rejects, the component renders
+ * a built-in inline error state (with a Retry affordance) in place of the
+ * empty item list — the failure is no longer silently swallowed. To run a side
+ * effect on failure (logging, error tracking, a toast), pass `onFetchError`.
  */
 export declare type SelectAsyncFetcher<T> = (options: {
     signal: AbortSignal;
@@ -4528,6 +4702,20 @@ declare interface SelectAsyncOwnProps<T> {
     fetcher: SelectAsyncFetcher<T>;
     /** Text shown while loading. @default "Loading..." */
     loadingText?: string;
+    /**
+     * Message shown in the dropdown when the fetcher fails, alongside a Retry
+     * affordance. Replaces the misleading empty state.
+     * @default "Couldn't load results."
+     */
+    errorText?: string;
+    /** Label for the retry button in the error state. @default "Retry" */
+    retryText?: string;
+    /**
+     * Called when a fetch fails. Fires once per outage (not on every re-open
+     * while broken) and re-arms after the next success. Use for logging or error
+     * tracking — the inline error state is shown regardless.
+     */
+    onFetchError?: (error: unknown) => void;
     /**
      * Whether the select behaves as a modal (traps focus).
      * Set to `true` when rendering inside a Dialog or Sheet to preserve focus-trap.
@@ -4730,6 +4918,13 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
      * `<link rel="icon">` in `index.html`.
      */
     favicon?: string;
+    /**
+     * Additional application metadata shown on the built-in `/__appinfo` page.
+     *
+     * AppShell always includes its own version there; use this prop to append
+     * app-defined rows such as environment, release, or commit.
+     */
+    appInfo?: AppInfo;
     /**
      * Base path for the app shell
      */
@@ -5133,6 +5328,16 @@ export declare const SidebarSeparator: () => JSX.Element;
 
 declare type Size = "sm" | "md" | "lg" | "xl" | "full";
 
+/**
+ * Header render context for sortable columns.
+ */
+declare interface SortableHeaderRenderContext {
+    label?: string;
+    sortable: true;
+    sortDirection: "Asc" | "Desc" | undefined;
+    activateSort: () => void;
+}
+
 /**
  * Sort configuration for a column.
  * The `type` determines how values are compared when sorting.
@@ -5735,6 +5940,7 @@ export declare const useAppShell: () => {
     title?: string;
     icon?: ReactNode;
     favicon?: string;
+    appInfo?: AppInfo;
     configurations: RootConfiguration;
 };
 
@@ -5818,7 +6024,7 @@ export declare function useAppShellScrollContainer(): RefObject<HTMLElement | nu
  * </Select.Parts.Root>
  * ```
  */
-declare function useAsync<T>({ fetcher }: UseSelectAsyncOptions<T>): UseSelectAsyncReturn<T>;
+declare function useAsync<T>({ fetcher, onFetchError }: UseSelectAsyncOptions<T>): UseSelectAsyncReturn<T>;
 
 /**
  * Hook that encapsulates the async combobox pattern — debounced fetching,
@@ -5855,7 +6061,11 @@ declare function useAsync<T>({ fetcher }: UseSelectAsyncOptions<T>): UseSelectAs
  * >
  *   ...
  *   <Combobox.Empty>
- *     {countries.loading ? "Loading..." : "No results."}
+ *     {countries.loading
+ *       ? "Loading..."
+ *       : countries.error
+ *         ? <button onClick={countries.retry}>Couldn't load results. Retry</button>
+ *         : "No results."}
  *   </Combobox.Empty>
  * </Combobox.Root>
  * ```
@@ -5899,7 +6109,11 @@ declare function useAsync_2<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsR
  * >
  *   ...
  *   <Autocomplete.Empty>
- *     {movies.loading ? "Loading..." : "No results."}
+ *     {movies.loading
+ *       ? "Loading..."
+ *       : movies.error
+ *         ? <button onClick={movies.retry}>Couldn't load results. Retry</button>
+ *         : "No results."}
  *   </Autocomplete.Empty>
  * </Autocomplete.Root>
  * ```
@@ -5929,6 +6143,16 @@ declare interface UseAsyncItemsOptions<T> {
      * ```
      */
     fetcher: AsyncFetcher<T>;
+    /**
+     * Called when a fetch fails (the fetcher throws or rejects with something
+     * other than an abort of a superseded request).
+     *
+     * Fires **once per outage** — i.e. on the transition into the error state,
+     * not on every failed keystroke — and re-arms after the next successful
+     * fetch. Use it for side effects like logging or error tracking; the inline
+     * error state is rendered regardless.
+     */
+    onFetchError?: (error: unknown) => void;
 }
 
 declare interface UseAsyncItemsReturn<T> {
@@ -5940,6 +6164,8 @@ declare interface UseAsyncItemsReturn<T> {
     query: string;
     /** The error thrown by the last fetch, if any */
     error: unknown;
+    /** Re-runs the most recent fetch immediately (no debounce). Use for a Retry affordance. */
+    retry: () => void;
     /** Input change handler — pass to the Root `onInputValueChange` prop */
     onInputValueChange: (value: string) => void;
     /** Open change handler — pass to the Root `onOpenChange` prop to fetch initial items on open */
@@ -6361,6 +6587,12 @@ export declare type UseDataTableOptions<TRow extends Record<string, unknown>, TF
      * using `DataTable.Pagination` or `DataTable.Filters`.
      */
     control?: CollectionControl<TFieldName, TFilter>;
+    /**
+     * Stable id used to persist per-user column layout (visibility, order, and
+     * pinning) to `localStorage`, keyed by this id. When omitted, column layout is
+     * in-memory only and resets on reload.
+     */
+    tableId?: string;
     /** Called when the user clicks a row. Adds a pointer cursor to rows. */
     onClickRow?: (row: TRow) => void;
     /**
@@ -6424,6 +6656,20 @@ export declare interface UseDataTableReturn<TRow extends Record<string, unknown>
     showAllColumns: () => void;
     hideAllColumns: () => void;
     isColumnVisible: (fieldOrId: string) => boolean;
+    /** Column keys in display order (visible and hidden). */
+    columnOrder: string[];
+    /** Move the column with `key` to `toIndex` within the ordered column list. */
+    moveColumn: (key: string, toIndex: number) => void;
+    /** Replace the full column order with `keys`. */
+    setColumnOrder: (keys: string[]) => void;
+    /** Per-user pin overrides, keyed by column key (`"none"` = explicitly unpinned). */
+    pinnedColumns: Record<string, "left" | "right" | "none">;
+    /**
+     * Set the pin for the column with `key`: `"left"`/`"right"` to pin, `"none"` to
+     * explicitly unpin (overriding a default `pin`), or `null` to clear the override
+     * and fall back to the column's default.
+     */
+    setPin: (key: string, side: "left" | "right" | "none" | null) => void;
     /**
      * The resolved page size derived from the collection control.
      * `0` when no control (or `pageSize`) is configured.
@@ -6584,6 +6830,12 @@ export { useSearchParams }
 declare interface UseSelectAsyncOptions<T> {
     /** Fetcher for async item loading. Called each time the dropdown is opened. */
     fetcher: SelectAsyncFetcher<T>;
+    /**
+     * Called when a fetch fails. Fires once per outage (not on every re-open
+     * while broken) and re-arms after the next success. Use for logging or error
+     * tracking; the inline error state is shown regardless.
+     */
+    onFetchError?: (error: unknown) => void;
 }
 
 declare interface UseSelectAsyncReturn<T> {
@@ -6593,6 +6845,8 @@ declare interface UseSelectAsyncReturn<T> {
     loading: boolean;
     /** The error thrown by the last fetch, if any */
     error: unknown;
+    /** Re-runs the fetch immediately. Use for a Retry affordance. */
+    retry: () => void;
     /** Open change handler — pass to the Root `onOpenChange` prop */
     onOpenChange: (open: boolean) => void;
 }