@tailor-platform/app-shell 0.36.0 → 1.0.0

package/dist/app-shell.d.ts

@@ -728,6 +728,18 @@ declare namespace Body_2 {
     var displayName: string;
 }
 
+/**
+ * Builds a Tailor Platform QueryInput-compatible type from table metadata.
+ */
+export declare type BuildQueryVariables<TTable extends TableMetadata> = {
+    [F in TTable["fields"][number] as F extends {
+        readonly name: infer N extends string;
+        readonly type: infer T;
+    } ? T extends keyof FieldTypeToFilterConfigType ? FieldTypeToFilterConfigType[T] extends never ? never : N : never : never]?: F extends {
+        readonly type: infer T extends keyof FieldTypeToFilterConfigType & keyof FieldTypeToTSType;
+    } ? FieldTypeToFilterConfigType[T] extends infer FCT extends FilterConfig["type"] ? FilterInputForFieldType<FCT, ResolveFieldValueType<F, T>> : never : never;
+};
+
 /**
  * A styled button component with multiple variants and sizes.
  *
@@ -804,6 +816,122 @@ declare namespace Close_2 {
     var displayName: string;
 }
 
+/**
+ * Collection control interface for UI components to interact with
+ * filter, sort, and pagination state.
+ */
+export declare interface CollectionControl<TFieldName extends string = string, TFilter = Filter<TFieldName>> {
+    filters: Filter<TFieldName>[];
+    addFilter<F extends TFieldName>(field: F, operator: OperatorForField<TFilter, F>, value: unknown): void;
+    setFilters: (filters: Filter<TFieldName>[]) => void;
+    removeFilter(field: TFieldName): void;
+    clearFilters: () => void;
+    sortStates: SortState[];
+    setSort(field: TFieldName, direction?: "Asc" | "Desc"): void;
+    clearSort: () => void;
+    pageSize: number;
+    setPageSize: (size: number) => void;
+    cursor: string | null;
+    paginationDirection: "forward" | "backward";
+    nextPage: (cursor: string) => void;
+    prevPage: (cursor: string) => void;
+    resetPage: () => void;
+    goToFirstPage: () => void;
+    /**
+     * Navigate to the last page.
+     *
+     * Requests the last `pageSize` items by setting `paginationDirection` to
+     * `"backward"` with no cursor.
+     */
+    goToLastPage: () => void;
+}
+
+/**
+ * Provider that shares collection control state via React Context.
+ *
+ * > **Note:** `DataTable.Root` automatically wraps its children with this provider
+ * > when `control` is supplied to `useDataTable`. Use `CollectionControlProvider`
+ * > directly only when you need to share control state with components that live
+ * > **outside** of `DataTable.Root` (e.g. a sibling filter panel or pagination
+ * > widget). Wrapping `DataTable.Root` with an outer `CollectionControlProvider`
+ * > while also passing `control` to `useDataTable` results in a double-wrap: the
+ * > inner provider (created by `DataTable.Root`) will silently shadow the outer
+ * > one for all descendants inside the table.
+ *
+ * @example
+ * ```tsx
+ * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
+ *
+ * <CollectionControlProvider value={control}>
+ *   <FilterPanel />
+ *   <DataTable.Root>...</DataTable.Root>
+ *   <Pagination />
+ * </CollectionControlProvider>
+ * ```
+ */
+export declare function CollectionControlProvider({ value, children, }: {
+    value: CollectionControl;
+    children: ReactNode;
+}): JSX.Element;
+
+/**
+ * GraphQL collection result format (Tailor Platform standard).
+ */
+export declare interface CollectionResult<T> {
+    edges: {
+        node: T;
+    }[];
+    pageInfo: PageInfo;
+    total?: number | null;
+}
+
+/**
+ * Collection variables split into explicit sub-properties.
+ */
+export declare interface CollectionVariables {
+    query: Record<string, Record<string, unknown>> | undefined;
+    order: {
+        field: string;
+        direction: "Asc" | "Desc";
+    }[] | undefined;
+    pagination: PaginationVariables;
+}
+
+/**
+ * A column definition for DataTable.
+ */
+export declare interface Column<TRow extends Record<string, unknown>> {
+    /** Column header text. Omit for action or icon-only columns. */
+    label?: string;
+    /** Renders the cell content for a given row. Required. */
+    render: (row: TRow) => 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
+     * absent or not unique.
+     */
+    id?: string;
+    /** Fixed column width in pixels. When omitted the column sizes naturally. */
+    width?: number;
+    /**
+     * Extracts the raw value from a row for purposes such as sorting or
+     * clipboard copying. Not used for rendering — use `render` for that.
+     */
+    accessor?: (row: TRow) => unknown;
+    /**
+     * Sort configuration. When set, the column header becomes clickable and
+     * cycles through `Asc → Desc → undefined`.
+     * Use `fieldTypeToSortConfig` or `inferColumns` to derive this automatically.
+     */
+    sort?: SortConfig;
+    /**
+     * Filter configuration. When set, this column appears as an option in
+     * `DataTable.Filters`.
+     * Use `fieldTypeToFilterConfig` or `inferColumns` to derive this automatically.
+     */
+    filter?: FilterConfig;
+}
+
 /**
  * Supported area values for Layout.Column
  */
@@ -814,6 +942,59 @@ declare type ColumnArea = "left" | "main" | "right";
  */
 declare type ColumnCount = 1 | 2 | 3;
 
+/**
+ * Object returned by `createColumnHelper`.
+ */
+declare interface ColumnHelper<TRow extends Record<string, unknown>> {
+    /**
+     * Define a column with an explicit render function.
+     *
+     * @example
+     * ```tsx
+     * column({ label: "Name", render: (row) => row.name })
+     * column({ label: "Actions", render: (row) => <button>Edit {row.name}</button> })
+     * ```
+     */
+    column: (options: Column<TRow>) => Column<TRow>;
+    /**
+     * Bind table metadata once and return a per-field column factory.
+     *
+     * The returned factory **throws at call time** if the given field name is not
+     * found in `tableMetadata`. This typically happens at module initialisation
+     * (i.e. when columns are defined outside a component), so it surfaces as an
+     * uncaught error rather than a render error. Field-name narrowing is only
+     * active when `tableMetadata` is typed from an `as const` source (e.g. a
+     * file generated by `appShellMetadataPlugin`).
+     *
+     * @throws {Error} If the field name is not found in the provided table metadata.
+     *
+     * @example
+     * ```tsx
+     * const infer = inferColumns(tableMetadata.order);
+     * const columns = [
+     *   column(infer("title")),
+     *   column({
+     *     ...infer("status"),
+     *     render: (row) => <StatusBadge value={row.status} />
+     *   }),
+     * ];
+     * ```
+     */
+    inferColumns: <const TTable extends TableMetadata = TableMetadata>(tableMetadata: TTable) => ColumnInferFn<TRow, TTable>;
+}
+
+/**
+ * Per-field column factory returned by `inferColumns(tableMetadata)`.
+ *
+ * Derives label, sort config, and filter config from the field's metadata.
+ * Sort and filter can be suppressed per call via `options`.
+ *
+ * @param dataKey - A field name from the bound table metadata.
+ * @param options - Optional per-column overrides (label, width, sort, filter).
+ * @throws {Error} If `dataKey` is not found in the metadata passed to `inferColumns`.
+ */
+declare type ColumnInferFn<TRow extends Record<string, unknown>, TTable extends TableMetadata = TableMetadata> = (dataKey: TableFieldName<TTable>, options?: MetadataFieldOptions) => Column<TRow>;
+
 /**
  * Props for individual Layout.Column component
  */
@@ -1274,6 +1455,23 @@ declare interface CreatableProps<T extends object> {
  */
 export declare function createAuthClient(config: AuthClientConfig): EnhancedAuthClient;
 
+/**
+ * Factory that captures the row type once and returns `column` and `inferColumns`
+ * with `TRow` already bound.
+ *
+ * @example
+ * ```tsx
+ * const { column, inferColumns } = createColumnHelper<Order>();
+ *
+ * const infer = inferColumns(tableMetadata.order);
+ * const columns = [
+ *   column(infer("title")),
+ *   column({ label: "Actions", render: (row) => <button>Edit {row.name}</button> }),
+ * ];
+ * ```
+ */
+export declare function createColumnHelper<TRow extends Record<string, unknown>>(): ColumnHelper<TRow>;
+
 /**
  * Create a type-safe path builder from route definitions.
  *
@@ -1430,6 +1628,173 @@ export declare type CsvSchema = {
     columns: readonly CsvColumn[];
 };
 
+export declare const DataTable: {
+    /**
+     * Context/provider root. Wraps all other `DataTable.*` components and
+     * wires state from `useDataTable()` into context.
+     */
+    readonly Root: typeof DataTableRoot;
+    /**
+     * Container for toolbar content (column visibility, search, etc.).
+     * Place inside `DataTable.Root`, before `DataTable.Table`.
+     */
+    readonly Toolbar: typeof DataTableToolbar;
+    /**
+     * Auto-generated filter chips from column filter configs.
+     *
+     * **Requires `control`** — `useDataTable()` must receive `control` from
+     * `useCollectionVariables()`, otherwise this component throws at render time.
+     */
+    readonly Filters: typeof DataTableFilters;
+    /**
+     * Renders `<table>` with built-in `Headers` and `Body`.
+     * Place inside `DataTable.Root`.
+     */
+    readonly Table: typeof DataTableTable;
+    /**
+     * Footer container for pagination and other footer content.
+     * Place inside `DataTable.Root`, after `DataTable.Table`.
+     */
+    readonly Footer: typeof DataTableFooter;
+    /**
+     * Pre-built pagination controls. Place inside `DataTable.Footer`.
+     *
+     * **Requires `control`** — `useDataTable()` must receive `control` from
+     * `useCollectionVariables()`, otherwise this component throws at render time.
+     *
+     * **Go-to-first / go-to-last buttons** — Rendered only when `totalPages` is
+     * non-null (i.e. the backend returns a total count). When `totalPages` is
+     * `null`, these buttons and the page counter are omitted.
+     */
+    readonly Pagination: typeof DataTablePagination;
+};
+
+/**
+ * Context value provided by `DataTable.Root`.
+ *
+ * `control` is intentionally excluded from this context: collection control
+ * (filters, sort, and pagination) is managed by `CollectionControlProvider`
+ * via a separate context. Keeping them separate means `DataTable.Root` works
+ * without any collection control (read-only / static tables), while
+ * `CollectionControlProvider` can optionally wrap it when filtering and
+ * pagination are needed. This also avoids coupling `DataTableContextValue`
+ * to `UseDataTableReturn` — changes to `UseDataTableReturn` require an
+ * explicit decision about whether they should appear in the context.
+ */
+export declare interface DataTableContextValue<TRow extends Record<string, unknown>> {
+    rows: TRow[];
+    loading: boolean;
+    error: Error | null;
+    sortStates: SortState[];
+    onSort?: (field: string, direction?: "Asc" | "Desc") => void;
+    pageInfo: PageInfo;
+    total: number | null;
+    totalPages: number | null;
+    nextPage: (cursor: string) => void;
+    prevPage: (cursor: string) => void;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    /**
+     * The resolved page size from the collection control. `0` when no control is
+     * configured. Used to render the correct number of skeleton / ghost rows.
+     */
+    pageSize: number;
+    columns: Column<TRow>[];
+    visibleColumns: Column<TRow>[];
+    toggleColumn: (fieldOrId: string) => void;
+    showAllColumns: () => void;
+    hideAllColumns: () => void;
+    isColumnVisible: (fieldOrId: string) => boolean;
+    onClickRow?: (row: TRow) => void;
+    rowActions?: RowAction<TRow>[];
+    selectedIds: string[];
+    isRowSelected: (row: TRow) => boolean;
+    toggleRowSelection?: (row: TRow) => void;
+    /**
+     * Selects all rows on the **current page** only. Cross-page selection is not supported.
+     * Undefined when `onSelectionChange` is not provided.
+     */
+    selectAllRows?: () => void;
+    clearSelection?: () => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+}
+
+/**
+ * Data input for `useDataTable` hook.
+ */
+export declare interface DataTableData<TRow> {
+    rows: TRow[];
+    pageInfo?: PageInfo;
+    total?: number | null;
+}
+
+/** Use `DataTable.Filters` instead of calling this directly. */
+declare function DataTableFilters({ className }: {
+    className?: string;
+}): JSX.Element | null;
+
+declare namespace DataTableFilters {
+    var displayName: string;
+}
+
+/** Use `DataTable.Footer` instead of calling this directly. */
+declare function DataTableFooter({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): JSX.Element;
+
+declare namespace DataTableFooter {
+    var displayName: string;
+}
+
+/** Use `DataTable.Pagination` instead of calling this directly. */
+declare function DataTablePagination({ pageSizeOptions }?: DataTablePaginationProps): JSX.Element;
+
+declare namespace DataTablePagination {
+    var displayName: string;
+}
+
+export declare interface DataTablePaginationProps {
+    /**
+     * Available page-size options shown in a dropdown selector.
+     * When provided, a page-size switcher is rendered.
+     */
+    pageSizeOptions?: number[];
+}
+
+/** Use `DataTable.Root` instead of calling this directly. */
+declare function DataTableRoot<TRow extends Record<string, unknown>>({ value, children, className, }: DataTableRootProps<TRow>): JSX.Element;
+
+declare namespace DataTableRoot {
+    var displayName: string;
+}
+
+export declare interface DataTableRootProps<TRow extends Record<string, unknown>> {
+    value: UseDataTableReturn<TRow>;
+    children: ReactNode;
+    className?: string;
+}
+
+/** Use `DataTable.Table` instead of calling this directly. */
+declare function DataTableTable({ className }: {
+    className?: string;
+}): JSX.Element;
+
+declare namespace DataTableTable {
+    var displayName: string;
+}
+
+/** Use `DataTable.Toolbar` instead of calling this directly. */
+declare function DataTableToolbar({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): JSX.Element;
+
+declare namespace DataTableToolbar {
+    var displayName: string;
+}
+
 /**
  * Date format options
  */
@@ -1948,7 +2313,7 @@ declare type FieldConfig = FieldDivider | FieldDefinition;
  */
 declare interface FieldDefinition {
     /** Field type determines rendering (defaults to "text") */
-    type?: FieldType;
+    type?: FieldType_2;
     /** Path to the value in the data object (supports dot notation) */
     key: string;
     /** Display label for the field */
@@ -1992,6 +2357,22 @@ declare interface FieldMeta {
     truncateLines?: number;
 }
 
+/**
+ * Metadata for a single field.
+ */
+export declare interface FieldMetadata {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+    readonly enumValues?: readonly string[];
+    readonly arrayItemType?: FieldType;
+    readonly description?: string;
+    readonly relation?: {
+        readonly fieldName: string;
+        readonly targetTable: string;
+    };
+}
+
 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`. */
@@ -2036,10 +2417,101 @@ declare type FieldsetRootProps = Pick<React_2.ComponentProps<typeof Fieldset_2.R
     children: React_2.ReactNode;
 };
 
+/**
+ * Field type mapping for Data View.
+ */
+export declare type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date" | "time" | "enum" | "array" | "nested" | "file";
+
 /**
  * Supported field types for DescriptionCard
  */
-declare type FieldType = "text" | "badge" | "money" | "date" | "link" | "address" | "reference";
+declare type FieldType_2 = "text" | "badge" | "money" | "date" | "link" | "address" | "reference";
+
+/**
+ * Map metadata field type to FilterConfig.
+ * Returns undefined for types that don't support filtering.
+ */
+export declare function fieldTypeToFilterConfig(field: string, type: FieldType, enumValues?: readonly string[]): FilterConfig | undefined;
+
+/**
+ * Type-level mapping from `FieldType` (metadata) to `FilterConfig["type"]`.
+ */
+declare type FieldTypeToFilterConfigType = {
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    uuid: "uuid";
+    datetime: "date";
+    date: "date";
+    time: "date";
+    enum: "enum";
+    array: never;
+    nested: never;
+    file: never;
+};
+
+/**
+ * Map metadata field type to SortConfig.
+ * Returns undefined for types that don't support sorting.
+ */
+export declare function fieldTypeToSortConfig(field: string, type: FieldType): SortConfig | undefined;
+
+declare type FieldTypeToTSType = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    uuid: string;
+    datetime: string;
+    date: string;
+    time: string;
+    enum: string;
+};
+
+/**
+ * Active filter state.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ */
+export declare interface Filter<TFieldName extends string = string> {
+    field: TFieldName;
+    operator: FilterOperator;
+    value: unknown;
+}
+
+/**
+ * Filter configuration for a column.
+ * The `type` determines which operators are available.
+ * The `field` identifies the backend field name used for filtering.
+ */
+export declare type FilterConfig = {
+    field: string;
+    type: "string";
+} | {
+    field: string;
+    type: "number";
+} | {
+    field: string;
+    type: "date";
+} | {
+    field: string;
+    type: "enum";
+    options: SelectOption[];
+} | {
+    field: string;
+    type: "boolean";
+} | {
+    field: string;
+    type: "uuid";
+};
+
+declare type FilterInputForFieldType<TFilterConfigType extends FilterConfig["type"], TValue> = {
+    [Op in OperatorForFilterType[TFilterConfigType]]?: OperatorValueType<Op, TValue>;
+};
+
+/**
+ * Union of all available filter operators.
+ */
+export declare type FilterOperator = OperatorForFilterType[FilterConfig["type"]];
 
 /** The table footer section (`<tfoot>`). */
 declare function Footer({ className, ...props }: React_2.ComponentProps<"tfoot">): JSX.Element;
@@ -2552,6 +3024,26 @@ declare namespace MenuSeparator {
     var displayName: string;
 }
 
+/**
+ * Options for metadata-based single field inference.
+ */
+export declare interface MetadataFieldOptions {
+    /** Override the column header text. Defaults to the field's `description` or `name` from metadata. */
+    label?: string;
+    /** Fixed column width in pixels. When omitted the column sizes naturally. */
+    width?: number;
+    /**
+     * Set to `false` to suppress the auto-generated sort config for this field.
+     * Defaults to `true` (sort is enabled when the field type supports it).
+     */
+    sort?: boolean;
+    /**
+     * Set to `false` to suppress the auto-generated filter config for this field.
+     * Defaults to `true` (filter is enabled when the field type supports it).
+     */
+    filter?: boolean;
+}
+
 /**
  * MetricCard — Compact card for dashboard KPI display (title, value, optional trend and description).
  *
@@ -2621,6 +3113,54 @@ declare type Module = Omit<CommonPageResource, "meta"> & {
 
 declare type Modules = Array<Module>;
 
+/**
+ * Extract the node type from a cursor connection result.
+ */
+export declare type NodeType<T extends {
+    edges: {
+        node: unknown;
+    }[];
+} | null | undefined> = NonNullable<T>["edges"][number]["node"];
+
+/**
+ * Resolve the operator union for a specific field within a filter type.
+ */
+declare type OperatorForField<TFilter, F extends string> = [Extract<TFilter, {
+    field: F;
+}>] extends [
+never
+] ? FilterOperator : Extract<TFilter, {
+    field: F;
+}> extends {
+    operator: infer O;
+} ? O : FilterOperator;
+
+/**
+ * Maps each filter type to the union of operators it supports.
+ */
+declare type OperatorForFilterType = {
+    [T in FilterConfig["type"]]: (typeof OPERATORS_BY_FILTER_TYPE)[T][number];
+};
+
+/**
+ * Operators available per filter type (Tailor Platform schema).
+ */
+export declare const OPERATORS_BY_FILTER_TYPE: {
+    readonly string: readonly ["eq", "ne", "contains", "notContains", "hasPrefix", "hasSuffix", "notHasPrefix", "notHasSuffix", "in", "nin"];
+    readonly number: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "nin"];
+    readonly date: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "nin"];
+    readonly enum: readonly ["eq", "ne", "in", "nin"];
+    readonly boolean: readonly ["eq", "ne"];
+    readonly uuid: readonly ["eq", "ne", "in", "nin"];
+};
+
+declare type OperatorValueType<TOp extends string, TValue> = TOp extends "in" | "nin" ? TValue[] : TOp extends "between" ? {
+    min: TValue;
+    max: TValue;
+} : TValue;
+
+declare type OrderableFieldType = "string" | "number" | "boolean" | "datetime" | "date" | "time" | "enum";
+
 /**
  * A React component that can be used as a page in file-based routing.
  *
@@ -2645,11 +3185,31 @@ declare type PageEntry = {
     component: PageComponent;
 };
 
+/**
+ * Page info for cursor-based pagination (Relay Connection spec).
+ */
+export declare interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    endCursor: string | null;
+    startCursor: string | null;
+}
+
 export declare type PageMeta = {
     title: string;
     icon?: ReactNode;
 };
 
+/**
+ * Pagination variables for cursor-based pagination (Tailor Platform format).
+ */
+export declare interface PaginationVariables {
+    first?: number;
+    after?: string | null;
+    last?: number;
+    before?: string | null;
+}
+
 /** The row data passed to `onValidate`, after transforms have been applied. */
 export declare type ParsedRow = {
     /** 0-based row index, stable across edits. */
@@ -2724,6 +3284,10 @@ declare namespace RadioItemIndicator {
  */
 export declare const redirectTo: (to: string) => GuardResult;
 
+declare type ResolveFieldValueType<F, T extends keyof FieldTypeToTSType> = T extends "enum" ? F extends {
+    readonly enumValues: readonly (infer V extends string)[];
+} ? V : string : FieldTypeToTSType[T];
+
 /**
  * A resource that can be included in the sub-content in the root resource.
  *
@@ -3001,6 +3565,18 @@ declare namespace Row {
     var displayName: string;
 }
 
+/**
+ * A single row action definition for the actions column.
+ */
+export declare interface RowAction<TRow extends Record<string, unknown>> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    variant?: "default" | "destructive";
+    isDisabled?: (row: TRow) => boolean;
+    onClick: (row: TRow) => void;
+}
+
 /**
  * An async search source that can be plugged into the CommandPalette.
  *
@@ -3099,6 +3675,14 @@ declare namespace SelectItem {
     var displayName: string;
 }
 
+/**
+ * Select option for enum/dropdown filters.
+ */
+export declare interface SelectOption {
+    value: string;
+    label: string;
+}
+
 declare interface SelectPropsBase<T> {
     /** Placeholder text shown when no value is selected */
     placeholder?: string;
@@ -3519,6 +4103,33 @@ export declare type SidebarLayoutProps = {
  */
 export declare const SidebarSeparator: () => JSX.Element;
 
+/**
+ * Sort configuration for a column.
+ * The `type` determines how values are compared when sorting.
+ * The `field` identifies the backend field name used for ordering.
+ */
+export declare type SortConfig = {
+    field: string;
+    type: "string";
+} | {
+    field: string;
+    type: "number";
+} | {
+    field: string;
+    type: "date";
+} | {
+    field: string;
+    type: "boolean";
+};
+
+/**
+ * Active sort state for a single field.
+ */
+export declare interface SortState {
+    field: string;
+    direction: "Asc" | "Desc";
+}
+
 /** Groups all parts of a submenu. */
 declare function SubmenuRoot({ children, ...props }: SubmenuRootProps): JSX.Element;
 
@@ -3548,6 +4159,57 @@ export declare const Table: {
     Caption: typeof Caption;
 };
 
+/**
+ * Extract field names from a single table metadata object.
+ */
+export declare type TableFieldName<TTable extends TableMetadata> = TTable["fields"][number] extends {
+    readonly name: infer N;
+} ? N extends string ? N : never : never;
+
+/**
+ * Metadata for a single table.
+ */
+export declare interface TableMetadata {
+    readonly name: string;
+    readonly pluralForm: string;
+    readonly description?: string;
+    readonly fields: readonly FieldMetadata[];
+    readonly relations?: readonly {
+        readonly relationType: "manyToOne" | "oneToOne" | "oneToMany";
+        readonly fieldName: string;
+        readonly targetTable: string;
+        readonly foreignKeyField: string;
+    }[];
+}
+
+/**
+ * Metadata-aware filter type from a single table metadata object.
+ */
+export declare type TableMetadataFilter<TTable extends TableMetadata> = TTable["fields"][number] extends infer F ? F extends {
+    readonly name: infer N;
+    readonly type: infer T;
+} ? N extends string ? T extends keyof FieldTypeToFilterConfigType ? FieldTypeToFilterConfigType[T] extends never ? never : {
+    field: N;
+    operator: OperatorForFilterType[FieldTypeToFilterConfigType[T]];
+    value: unknown;
+} : never : never : never : never;
+
+/**
+ * Map of all tables.
+ */
+export declare type TableMetadataMap = {
+    readonly [key: string]: TableMetadata;
+};
+
+/**
+ * Extract only orderable field names from a single table metadata object.
+ */
+export declare type TableOrderableFieldName<TTable extends TableMetadata> = Extract<TTable["fields"][number], {
+    readonly type: OrderableFieldType;
+}> extends {
+    readonly name: infer N;
+} ? N extends string ? N : never : never;
+
 declare type Theme = "dark" | "light" | "system";
 
 declare type ThemeProviderState = {
@@ -3936,6 +4598,90 @@ export declare const useAuthSuspense: () => {
     checkAuthStatus: () => Promise<AuthState>;
 };
 
+/**
+ * Hook to access collection control from the nearest `CollectionControlProvider`.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ *
+ * @throws Error if used outside of `CollectionControlProvider`.
+ */
+export declare function useCollectionControl<TFieldName extends string = string>(): CollectionControl<TFieldName>;
+
+/**
+ * Options for `useCollectionVariables` hook.
+ */
+export declare interface UseCollectionOptions<TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> {
+    params?: {
+        initialFilters?: TFilter[];
+        initialSort?: {
+            field: TFieldName;
+            direction: "Asc" | "Desc";
+        }[];
+        pageSize?: number;
+    };
+}
+
+/**
+ * Return type of `useCollectionVariables` hook.
+ */
+export declare interface UseCollectionReturn<TFieldName extends string = string, TVariables = CollectionVariables, TFilter = Filter<TFieldName>> {
+    variables: TVariables;
+    control: CollectionControl<TFieldName, TFilter>;
+}
+
+/**
+ * Hook for managing collection query parameters (filters, sort, pagination)
+ * with metadata-based field name typing and automatic `fieldType` detection.
+ *
+ * Returns `variables` with `query`, `order`, and `pagination` sub-properties
+ * that can be mapped to GraphQL query variables.
+ *
+ * @example
+ * ```tsx
+ * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
+ *
+ * const { variables } = useCollectionVariables({
+ *   tableMetadata: tableMetadata.task,
+ *   params: { pageSize: 20 },
+ * });
+ * const { query, order, pagination } = variables;
+ * const [result] = useQuery({
+ *   query: GET_TASKS,
+ *   variables: { ...pagination, query, order },
+ * });
+ * ```
+ */
+export declare function useCollectionVariables<const TTable extends TableMetadata>(options: UseCollectionOptions<TableFieldName<TTable>, TableMetadataFilter<TTable>> & {
+    tableMetadata: TTable;
+}): UseCollectionReturn<TableFieldName<TTable>, {
+    query: BuildQueryVariables<TTable> | undefined;
+    order: {
+        field: TableOrderableFieldName<TTable>;
+        direction: "Asc" | "Desc";
+    }[] | undefined;
+    pagination: PaginationVariables;
+}, TableMetadataFilter<TTable>>;
+
+/**
+ * Hook for managing collection query parameters (filters, sort, pagination).
+ *
+ * Returns `variables` with `query`, `order`, and `pagination` sub-properties
+ * that can be mapped to GraphQL query variables.
+ *
+ * @example
+ * ```tsx
+ * const { variables } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const { query, order, pagination } = variables;
+ * const [result] = useQuery({
+ *   query: GET_ORDERS,
+ *   variables: { ...pagination, query, order },
+ * });
+ * ```
+ */
+export declare function useCollectionVariables(options: UseCollectionOptions & {
+    tableMetadata?: never;
+}): UseCollectionReturn<string, CollectionVariables>;
+
 /**
  * Hook that encapsulates the "creatable" combobox pattern — allowing users
  * to create new items on-the-fly from the dropdown.
@@ -4095,6 +4841,148 @@ declare type UseCsvImporterOptions<T extends CsvSchema> = {
     maxFileSize?: number;
 };
 
+/**
+ * Hook that integrates data management, column visibility, row operations, and
+ * sort/pagination state for the `DataTable.*` compound component.
+ *
+ * @example
+ * ```tsx
+ * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const [result] = useQuery({
+ *   query: GET_ORDERS,
+ *   variables: { ...variables.pagination, query: variables.query, order: variables.order },
+ * });
+ *
+ * const table = useDataTable<Order>({
+ *   columns,
+ *   data: {
+ *     rows: result.data?.orders?.edges.map(e => e.node) ?? [],
+ *     pageInfo: { ... },
+ *     total: result.data?.orders?.total,
+ *   },
+ *   loading: result.fetching,
+ *   control,
+ * });
+ *
+ * <DataTable.Root value={table}>
+ *   <DataTable.Table />
+ *   <DataTable.Footer>
+ *     <DataTable.Pagination />
+ *   </DataTable.Footer>
+ * </DataTable.Root>
+ * ```
+ */
+export declare function useDataTable<TRow extends Record<string, unknown>, TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>>(options: UseDataTableOptions<TRow, TFieldName, TFilter>): UseDataTableReturn<TRow>;
+
+/**
+ * Hook to access the full DataTable state (rows, columns, sorting, pagination,
+ * column visibility, and row operations) from the nearest `DataTable.Root`.
+ *
+ * This hook is intentionally part of the public API to support **custom
+ * sub-components** rendered inside `DataTable.Root`. Use it when the built-in
+ * `DataTable.*` sub-components (Table, Toolbar, Pagination, etc.) are not
+ * sufficient and you need to build your own compound component that reads from
+ * or writes to the same DataTable context — for example, a column-visibility
+ * toggle panel or a custom row-action toolbar.
+ *
+ * For most use cases, prefer passing values from `useDataTable()` as props
+ * rather than reaching into the context directly.
+ *
+ * @throws Error if used outside of `DataTable.Root`.
+ */
+export declare function useDataTableContext<TRow extends Record<string, unknown>>(): DataTableContextValue<TRow>;
+
+/**
+ * Options for `useDataTable` hook.
+ */
+export declare type UseDataTableOptions<TRow extends Record<string, unknown>, TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> = {
+    /** Column definitions that describe what to render in each column. */
+    columns: Column<TRow>[];
+    /**
+     * Fetched data to display. Pass `undefined` while loading; the table will
+     * show a loading state automatically.
+     */
+    data: DataTableData<TRow> | undefined;
+    /** When `true`, the table renders a loading indicator. */
+    loading?: boolean;
+    /** If set, an error message is rendered in the table body. */
+    error?: Error | null;
+    /**
+     * Collection control returned by `useCollectionVariables()`. Required when
+     * using `DataTable.Pagination` or `DataTable.Filters`.
+     */
+    control?: CollectionControl<TFieldName, TFilter>;
+    /** Called when the user clicks a row. Adds a pointer cursor to rows. */
+    onClickRow?: (row: TRow) => void;
+    /**
+     * Per-row action items rendered in a kebab-menu column on the right.
+     * The column is omitted when this array is empty or not provided.
+     */
+    rowActions?: RowAction<TRow>[];
+    /**
+     * Called with the current array of selected row IDs whenever the selection
+     * changes. Providing this prop enables the checkbox selection column.
+     * Selection is ID-based (`row.id`) and persists across page changes.
+     *
+     * **Requirement:** Each row must have a string or number `id` field.
+     * Rows without `id` are excluded from selection.
+     *
+     * **Note:** `selectAllRows` (triggered by the header checkbox) selects only
+     * the rows on the **current page**, not all pages.
+     */
+    onSelectionChange?: (ids: string[]) => void;
+};
+
+/**
+ * Return type of `useDataTable` hook.
+ */
+export declare interface UseDataTableReturn<TRow extends Record<string, unknown>> {
+    rows: TRow[];
+    loading: boolean;
+    error: Error | null;
+    sortStates: SortState[];
+    onSort?: (field: string, direction?: "Asc" | "Desc") => void;
+    pageInfo: PageInfo;
+    total: number | null;
+    totalPages: number | null;
+    nextPage: (cursor: string) => void;
+    prevPage: (cursor: string) => void;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    columns: Column<TRow>[];
+    visibleColumns: Column<TRow>[];
+    toggleColumn: (fieldOrId: string) => void;
+    showAllColumns: () => void;
+    hideAllColumns: () => void;
+    isColumnVisible: (fieldOrId: string) => boolean;
+    /**
+     * The resolved page size derived from the collection control.
+     * `0` when no control (or `pageSize`) is configured.
+     * Used by `DataTable.Table` to render the correct number of skeleton / ghost rows.
+     */
+    pageSize: number;
+    /**
+     * The collection control passed to `useDataTable`, stored here for
+     * forwarding to `DataTable.Root`.
+     *
+     * **Note:** The type is widened to `CollectionControl` (i.e.
+     * `CollectionControl<string>`) here — field-name and operator narrowing from
+     * `useCollectionVariables({ tableMetadata })` is lost. For type-safe
+     * `addFilter` calls, use the `control` returned directly by
+     * `useCollectionVariables` rather than accessing it via this field.
+     */
+    control: CollectionControl | undefined;
+    onClickRow?: (row: TRow) => void;
+    rowActions?: RowAction<TRow>[];
+    selectedIds: string[];
+    isRowSelected: (row: TRow) => boolean;
+    toggleRowSelection?: (row: TRow) => void;
+    selectAllRows?: () => void;
+    clearSelection?: () => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+}
+
 export { useLocation }
 
 export { useNavigate }