@tailor-platform/app-shell 1.8.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';
@@ -248,12 +249,26 @@ export declare const alertVariants: (props?: ({
     variant?: "error" | "neutral" | "success" | "warning" | "info" | null | undefined;
 } & ClassProp) | undefined) => string;
 
+declare type Anchor = "start" | "center" | "end";
+
 /**
  * Appearance menu. The end-user controls **color theme** (light / dark / system);
  * the color palette/brand is a developer configuration, so it is not shown here.
  */
 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>;
@@ -267,6 +282,7 @@ declare type AppShellConfigContextType = {
     title?: string;
     icon?: ReactNode;
     favicon?: string;
+    appInfo?: AppInfo;
     configurations: RootConfiguration;
 };
 
@@ -424,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
@@ -584,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;
@@ -777,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;
 }
@@ -796,7 +830,7 @@ export declare const Avatar: {
 export declare type AvatarProps = React_2.ComponentProps<typeof Avatar_2.Root> & VariantProps<typeof avatarVariants>;
 
 export declare const avatarVariants: (props?: ({
-    size?: "default" | "sm" | "lg" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | null | undefined;
 } & ClassProp) | undefined) => string;
 
 export declare function Badge({ className, variant, children, ...props }: BadgeProps): JSX.Element;
@@ -960,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;
 
@@ -974,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;
 
@@ -1144,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
@@ -1156,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
@@ -1164,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
@@ -1340,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>);
@@ -1689,8 +1825,9 @@ declare namespace Content_4 {
 }
 
 /** The tooltip popup that displays additional information. */
-declare function Content_5({ className, position, side: _side, align: _align, sideOffset: _sideOffset, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
+declare function Content_5({ className, position, side: _side, align: _align, sideOffset: _sideOffset, noArrow, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
     position?: PositionProps;
+    noArrow?: boolean;
     /** @deprecated Use `position={{ side }}` instead. */
     side?: PositionProps["side"];
     /** @deprecated Use `position={{ align }}` instead. */
@@ -1976,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;
     /**
@@ -2054,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[];
@@ -2079,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 {
@@ -2135,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;
 
@@ -2160,6 +2322,11 @@ declare interface DateBehaviorProps<T extends DateValue> {
     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). */
     "aria-label"?: string;
@@ -2189,7 +2356,7 @@ declare interface DateCellOptions {
  * <DateField label="Created at" granularity="minute" />
  * ```
  */
-export declare function DateField<T extends DateValue = DateValue>({ label, description, errorMessage, className, locale: localeProp, value, defaultValue, onChange, granularity, hourCycle, placeholderValue, isDisabled, isReadOnly, isInvalid, isRequired, autoFocus, name, "aria-label": ariaLabel, }: DateFieldProps<T>): JSX.Element;
+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;
@@ -2223,7 +2390,6 @@ declare type DateFormat = "short" | "medium" | "long" | "relative";
 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;
 
 export declare type DatePickerProps<T extends DateValue = DateValue> = DateFieldProps<T> & {
-    firstDayOfWeek?: FirstDayOfWeek;
     /** IANA timezone; defaults to the AppShell `timeZone`. */
     timeZone?: string;
 };
@@ -3087,10 +3253,9 @@ declare type FilterInputForFieldType<TFilterConfigType extends FilterConfig["typ
 export declare type FilterOperator = OperatorForFilterType[FilterConfig["type"]];
 
 /**
- * Hand-rolled calendar-grid state — the logic react-aria's `useCalendarState`
- * would otherwise provide. We own: month/week computation (locale + first-day-
- * of-week aware), selection, roving focus, and full APG keyboard navigation
- * (arrows, Home/End, PageUp/Down, Shift+PageUp/Down).
+ * Week-start override for the `weekStart`/`weekEnd` shortcuts (and the calendar
+ * grid). Defined here — with the resolver that consumes it — so the field and
+ * calendar engines share one source of truth.
  */
 declare type FirstDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
 
@@ -3412,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;
 };
@@ -3482,6 +3652,15 @@ export declare function Input({ className, type, ...props }: InputProps): JSX.El
 
 export declare type InputProps = React_2.ComponentProps<"input">;
 
+/**
+ * Positions content across a time range inside a row.
+ */
+declare function Interval({ start, end, children, id, insetY, className, style, }: TimelineIntervalProps): JSX.Element;
+
+declare namespace Interval {
+    var displayName: string;
+}
+
 /**
  * Check if an object type has no keys.
  */
@@ -3666,6 +3845,17 @@ declare namespace Legend {
 
 export { Link }
 
+/**
+ * Draws an orthogonal connector between two row items.
+ *
+ * If either referenced `Timeline.Interval` id is unresolved, nothing is rendered.
+ */
+declare function Link_2({ from, to, fromAnchor, toAnchor, arrow, gap, className, style, strokeWidth, }: TimelineLinkProps): React_2.ReactPortal | null;
+
+declare namespace Link_2 {
+    var displayName: string;
+}
+
 /** Options for `type: "link"` cells. `href` is required. */
 declare interface LinkCellOptions<TRow extends Record<string, unknown>> {
     /**
@@ -3847,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`. */
@@ -3857,6 +4055,11 @@ declare interface NumberCellOptions {
     locale?: string;
 }
 
+export declare type OpenCommandPaletteOptions = {
+    /** Optional initial text to prefill into the palette input. */
+    search?: string;
+};
+
 /**
  * Resolve the operator union for a specific field within a filter type.
  */
@@ -4163,6 +4366,26 @@ declare namespace Root_12 {
     var displayName: string;
 }
 
+/**
+ * Provides the shared time range used by all timeline primitives.
+ *
+ * Example:
+ * ```tsx
+ * <Timeline.Root start={projectStart} end={projectEnd}>
+ *   <Timeline.Viewport axis={axis}>
+ *     <Timeline.Row height={40}>
+ *       <Timeline.Interval start={task.start} end={task.end}>…</Timeline.Interval>
+ *     </Timeline.Row>
+ *   </Timeline.Viewport>
+ * </Timeline.Root>
+ * ```
+ */
+declare function Root_13({ start, end, children, className, style }: TimelineRootProps): JSX.Element;
+
+declare namespace Root_13 {
+    var displayName: string;
+}
+
 declare function Root_2<T extends ActivityCardBaseItem>({ items, title, maxVisible, overflowLabel, groupBy, className, children, }: ActivityCardRootProps<T>): JSX.Element;
 
 declare namespace Root_2 {
@@ -4211,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;
@@ -4353,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"> & {
@@ -4383,6 +4608,25 @@ declare namespace Row {
     var displayName: string;
 }
 
+/**
+ * A single body row.
+ *
+ * Rows control vertical sizing and can optionally provide a background layer:
+ * ```tsx
+ * <Timeline.Row
+ *   height={40}
+ *   background={{ style: { background: "var(--muted)" } }}
+ * >
+ *   <Timeline.Interval start={task.start} end={task.end}>…</Timeline.Interval>
+ * </Timeline.Row>
+ * ```
+ */
+declare function Row_2({ children, className, style, height, background }: TimelineRowProps): JSX.Element;
+
+declare namespace Row_2 {
+    var displayName: string;
+}
+
 /**
  * A single row action definition for the actions column.
  */
@@ -4444,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;
@@ -4458,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.
@@ -4660,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
      */
@@ -5063,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.
@@ -5191,6 +5466,344 @@ declare type TabsVariant = "default" | "line" | "capsule";
 
 export { Time }
 
+/**
+ * Timeline primitives for building app-specific schedule, trace, and dependency UIs.
+ *
+ * Typical usage:
+ * ```tsx
+ * <Timeline.Root start={start} end={end}>
+ *   <Timeline.Viewport axis={axis} decorations={decorations}>
+ *     <Timeline.Row height={40} background={{ style: { background: "var(--muted)" } }}>
+ *       <Timeline.Interval id="task-1" start={task.start} end={task.end}>…</Timeline.Interval>
+ *     </Timeline.Row>
+ *     <Timeline.Link from="task-1" to="task-2" />
+ *   </Timeline.Viewport>
+ * </Timeline.Root>
+ * ```
+ */
+export declare const Timeline: {
+    Root: typeof Root_13;
+    Viewport: typeof Viewport;
+    Row: typeof Row_2;
+    Interval: typeof Interval;
+    Link: typeof Link_2;
+};
+
+/**
+ * Axis configuration owned by `Timeline.Viewport`.
+ *
+ * Example:
+ * ```tsx
+ * axis={{
+ *   guides: boundaries.map((at) => ({
+ *     at,
+ *     axisStyle: { background: "var(--border)" },
+ *     bodyStyle: { background: "var(--border)" },
+ *   })),
+ *   levels: [
+ *     {
+ *       kind: "spans",
+ *       items: timeboxes,
+ *     },
+ *   ],
+ * }}
+ * ```
+ */
+export declare interface TimelineAxis {
+    /** Boundary lines rendered in the axis and/or body. */
+    guides?: TimelineGuide[];
+    /** Stacked header levels rendered above the body. Defaults to `[]` when omitted. */
+    levels?: TimelineAxisLevel[];
+    /** Optional class applied to the axis container. */
+    className?: string;
+}
+
+/**
+ * One stacked axis level.
+ *
+ * Levels let an app compose multi-level headers such as year → month or a
+ * single timebox row such as half-hour slots.
+ */
+export declare type TimelineAxisLevel = (TimelineAxisLevelBase & {
+    /** Interval labels rendered across a time range. */
+    kind: "spans";
+    /** Span items to render in this level. */
+    items: TimelineAxisSpan[];
+    /** Optional class applied to every span in the level. */
+    itemClassName?: string;
+    /** Optional style applied to every span in the level. */
+    itemStyle?: React_2.CSSProperties;
+}) | (TimelineAxisLevelBase & {
+    /** Point labels rendered at specific times. */
+    kind: "ticks";
+    /** Tick items to render in this level. */
+    items: TimelineAxisTick[];
+    /** Horizontal anchor used when placing each tick label. */
+    labelAlign?: Anchor;
+});
+
+declare type TimelineAxisLevelBase = {
+    /** Height of this axis level in pixels. Defaults to `28`. */
+    height?: number;
+    /** Optional class applied to the level container. */
+    className?: string;
+};
+
+/**
+ * A labeled time range rendered inside an axis level.
+ *
+ * Use spans for "timeboxes" such as months, half-hours, sprints, or any
+ * other interval that should be labeled between boundary guides.
+ */
+export declare interface TimelineAxisSpan {
+    /** Stable React key. Falls back to a start/end-based key when omitted. */
+    key?: React_2.Key;
+    /** Start of the timebox. Accepts a `Date` or a millisecond timestamp. */
+    start: TimeValue;
+    /** End of the timebox. Accepts a `Date` or a millisecond timestamp. */
+    end: TimeValue;
+    /** Label rendered inside the span. */
+    label?: React_2.ReactNode;
+    /** Optional class applied to the positioned span element. */
+    className?: string;
+    /** Optional inline style applied to the positioned span element. */
+    style?: React_2.CSSProperties;
+}
+
+/**
+ * A labeled point in an axis level.
+ *
+ * Ticks are useful for point-in-time labels such as milestones or specific
+ * timestamps. For boxed labels between boundaries, prefer `TimelineAxisSpan`.
+ */
+export declare interface TimelineAxisTick {
+    /** Stable React key. Falls back to an `at`-based key when omitted. */
+    key?: React_2.Key;
+    /** Point in time represented by this tick. */
+    at: TimeValue;
+    /** Label rendered for the tick. */
+    label?: React_2.ReactNode;
+    /**
+     * Optional custom label position.
+     *
+     * Defaults to `at`. Use this when the tick represents one time but its label
+     * should be positioned elsewhere.
+     */
+    labelAt?: TimeValue;
+    /** Optional class applied to the tick container. */
+    className?: string;
+    /** Optional inline style applied to the tick container. */
+    style?: React_2.CSSProperties;
+}
+
+/**
+ * A decorative band rendered behind the timeline body.
+ *
+ * Useful for blackout windows, maintenance ranges, release freezes, or any
+ * other highlighted interval.
+ */
+export declare interface TimelineBand {
+    /** Stable React key. Falls back to a start/end-based key when omitted. */
+    key?: React_2.Key;
+    /** Start of the band. */
+    start: TimeValue;
+    /** End of the band. */
+    end: TimeValue;
+    /** Optional background color convenience prop. */
+    color?: string;
+    /** Optional class applied to the band element. */
+    className?: string;
+    /** Optional inline style applied to the band element. */
+    style?: React_2.CSSProperties;
+}
+
+/**
+ * Decorative layers rendered by `Timeline.Viewport`.
+ */
+export declare interface TimelineDecorations {
+    /** Background range highlights rendered behind rows. */
+    bands?: TimelineBand[];
+    /** Vertical markers rendered in the axis and/or body. */
+    markers?: TimelineMarker[];
+}
+
+/**
+ * A vertical guide line projected onto the axis and/or the timeline body.
+ *
+ * Guides are the timeline's "boundaries". Apps usually derive them from their
+ * own scale logic, then pair them with axis spans to label the ranges between
+ * those boundaries.
+ */
+export declare interface TimelineGuide {
+    /** Stable React key. Falls back to an `at`-based key when omitted. */
+    key?: React_2.Key;
+    /** Time position for the guide line. */
+    at: TimeValue;
+    /** Optional class applied to the guide inside the axis area. */
+    axisClassName?: string;
+    /** Optional inline style applied to the guide inside the axis area. */
+    axisStyle?: React_2.CSSProperties;
+    /** Optional class applied to the guide inside the body area. */
+    bodyClassName?: string;
+    /** Optional inline style applied to the guide inside the body area. */
+    bodyStyle?: React_2.CSSProperties;
+}
+
+export declare type TimelineIntervalProps = {
+    /** Start of the interval. */
+    start: TimeValue;
+    /** End of the interval. */
+    end: TimeValue;
+    /** Rendered content for the interval. */
+    children: React_2.ReactNode;
+    /** Optional stable id used by `Timeline.Link`. */
+    id?: string;
+    /** Top and bottom inset in pixels within the row. Defaults to `0`. */
+    insetY?: number;
+    /** Optional class applied to the positioned interval container. */
+    className?: string;
+    /** Optional inline style applied to the positioned interval container. */
+    style?: React_2.CSSProperties;
+};
+
+/**
+ * Shared defaults for `Timeline.Link` instances inside one viewport.
+ */
+export declare interface TimelineLinkDefaults {
+    /** Link routing strategy. Only orthogonal routing is currently supported. */
+    routing?: "orthogonal";
+    /** Whether links end with an arrow marker. Defaults to `true`. */
+    arrow?: boolean;
+    /** Horizontal gap used when routing out of and into items. Defaults to `16`. */
+    gap?: number;
+    /** Optional class applied to each link SVG when the link does not override it. */
+    className?: string;
+    /**
+     * Optional inline style applied to each link SVG when the link does not override it.
+     *
+     * Prefer an opaque `color` here over alpha-based text colors when overlapping links
+     * should not appear darker.
+     */
+    style?: React_2.CSSProperties;
+    /** Optional stroke width used by each link when the link does not override it. */
+    strokeWidth?: number;
+}
+
+export declare type TimelineLinkProps = {
+    /** Source `Timeline.Interval` id. */
+    from: string;
+    /** Target `Timeline.Interval` id. */
+    to: string;
+    /** Source anchor used for routing. Defaults to `"end"`. */
+    fromAnchor?: Anchor;
+    /** Target anchor used for routing. Defaults to `"start"`. */
+    toAnchor?: Anchor;
+    /** Overrides the viewport default arrow visibility. */
+    arrow?: boolean;
+    /** Overrides the viewport default routing gap. */
+    gap?: number;
+    /** Optional class applied to the link SVG. */
+    className?: string;
+    /** Optional inline style applied to the link SVG. */
+    style?: React_2.CSSProperties;
+    /** Optional stroke width for the link path. */
+    strokeWidth?: number;
+};
+
+/**
+ * A decorative vertical marker rendered in the axis and/or body.
+ */
+export declare interface TimelineMarker {
+    /** Stable React key. Falls back to an `at`-based key when omitted. */
+    key?: React_2.Key;
+    /** Time position for the marker. */
+    at: TimeValue;
+    /** Optional line color convenience prop. */
+    color?: string;
+    /** Optional marker label. */
+    label?: React_2.ReactNode;
+    /** Optional class applied to the outer marker wrapper. */
+    className?: string;
+    /** Optional inline style applied to the outer marker wrapper. */
+    style?: React_2.CSSProperties;
+    /** Optional class applied to the marker line. */
+    lineClassName?: string;
+    /** Optional inline style applied to the marker line. */
+    lineStyle?: React_2.CSSProperties;
+    /** Optional class applied to the marker label. */
+    labelClassName?: string;
+    /** Optional inline style applied to the marker label. */
+    labelStyle?: React_2.CSSProperties;
+    /** Controls where the marker is rendered. Defaults to `"body"`. */
+    placement?: "axis" | "body" | "both";
+}
+
+export declare type TimelineRootProps = {
+    /** Inclusive start of the overall timeline range. */
+    start: TimeValue;
+    /** Inclusive end of the overall timeline range. */
+    end: TimeValue;
+    /** Timeline subtree. Usually contains one `Timeline.Viewport`. */
+    children: React_2.ReactNode;
+    /** Optional class applied to the root container. */
+    className?: string;
+    /** Optional inline style applied to the root container. */
+    style?: React_2.CSSProperties;
+};
+
+/**
+ * Background content rendered for a `Timeline.Row` in a dedicated layer.
+ *
+ * Use this when a row background should sit behind guides but in front of body
+ * bands. This is different from `Timeline.Row`'s own `style`, which affects the
+ * row content container itself.
+ */
+export declare interface TimelineRowBackground {
+    /** Optional class applied to the background layer element. */
+    className?: string;
+    /** Optional inline style applied to the background layer element. */
+    style?: React_2.CSSProperties;
+}
+
+export declare type TimelineRowProps = {
+    /** Row contents, typically intervals. */
+    children: React_2.ReactNode;
+    /** Optional class applied to the row content container. */
+    className?: string;
+    /** Optional inline style applied to the row content container. */
+    style?: React_2.CSSProperties;
+    /** Row height in pixels. Defaults to `32`. */
+    height?: number;
+    /**
+     * Optional background rendered in a dedicated layer.
+     *
+     * Use this instead of `style.background` when guides should remain visible in
+     * front of the row background.
+     */
+    background?: TimelineRowBackground | null;
+};
+
+export declare type TimelineViewportProps = {
+    /** Timeline content. Rows and links can be passed in any order. */
+    children: React_2.ReactNode;
+    /** Optional fixed canvas width in pixels for horizontally scrollable timelines. */
+    canvasWidth?: number;
+    /** Keeps the axis pinned to the top of the viewport when scrolling vertically. */
+    stickyAxis?: boolean;
+    /** Axis configuration for guides and header levels. */
+    axis?: TimelineAxis;
+    /** Decorative layers such as bands and markers. */
+    decorations?: TimelineDecorations;
+    /** Shared defaults applied to `Timeline.Link` nodes inside this viewport. */
+    linkDefaults?: TimelineLinkDefaults;
+    /** Optional class applied to the scroll viewport. */
+    className?: string;
+    /** Optional inline style applied to the scroll viewport. */
+    style?: React_2.CSSProperties;
+};
+
+declare type TimeValue = Date | number;
+
 /**
  * Resolved timezone object with helpers bound to the configured timezone.
  */
@@ -5327,6 +5940,7 @@ export declare const useAppShell: () => {
     title?: string;
     icon?: ReactNode;
     favicon?: string;
+    appInfo?: AppInfo;
     configurations: RootConfiguration;
 };
 
@@ -5410,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,
@@ -5447,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>
  * ```
@@ -5491,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>
  * ```
@@ -5521,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> {
@@ -5532,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 */
@@ -5953,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;
     /**
@@ -6016,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.
@@ -6090,6 +6744,14 @@ export { useLocation }
 
 export { useNavigate }
 
+/**
+ * Returns a function that opens the CommandPalette.
+ *
+ * Optionally accepts an initial search string, including prefix-activated
+ * search modes such as `PO: alice`.
+ */
+export declare function useOpenCommandPalette(): (options?: OpenCommandPaletteOptions) => void;
+
 /**
  * Override the breadcrumb title for the current page.
  *
@@ -6168,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> {
@@ -6177,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;
 }
@@ -6278,6 +6948,28 @@ declare namespace Validity {
     var displayName: string;
 }
 
+/**
+ * Owns scrolling, axis rendering, decoration layers, and link layering.
+ *
+ * Example:
+ * ```tsx
+ * <Timeline.Viewport
+ *   canvasWidth={1200}
+ *   axis={{ guides, levels }}
+ *   decorations={{ bands }}
+ *   linkDefaults={{ style: { color: "var(--muted-foreground)" }, strokeWidth: 1.5 }}
+ * >
+ *   {rows}
+ *   {links}
+ * </Timeline.Viewport>
+ * ```
+ */
+declare function Viewport({ children, canvasWidth, stickyAxis, axis, decorations, linkDefaults, className, style, }: TimelineViewportProps): JSX.Element;
+
+declare namespace Viewport {
+    var displayName: string;
+}
+
 /**
  * Conditionally render children based on guard evaluation.
  *