@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/datatable/server-filters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Server-Side Filter Utilities
+ *
+ * Utilities for processing filters in load functions and building Drizzle queries.
+ * Designed to work with the datatable filter system.
+ */
+import { and, or, like, eq, ne, inArray, notInArray, gte, lte, gt, lt, isNull, isNotNull, type SQL } from 'drizzle-orm';
+import { type DatatableColumnMap } from './filter-columns';
+import { type DatatableValue } from './types';
+/**
+ * Filter operators for different filter types
+ */
+export type TextOperator = 'contains' | 'equals' | 'startsWith' | 'endsWith' | 'notContains' | 'notEquals';
+export type NumberOperator = 'equals' | 'notEquals' | 'gt' | 'gte' | 'lt' | 'lte' | 'between';
+export type SelectOperator = 'in' | 'notIn';
+export type DateOperator = 'equals' | 'before' | 'after' | 'between';
+export type BooleanOperator = 'equals';
+/**
+ * Parse filters from URL search parameters
+ *
+ * Extracts all parameters starting with 'filter_' prefix
+ * and attempts to parse their values (JSON or plain string).
+ * Empty plain values are skipped.
+ */
+export declare function parseFiltersFromUrl(searchParams: URLSearchParams): Map<string, DatatableValue>;
+/**
+ * Serialize filters to URL search parameters
+ *
+ * Converts a filter map to URL parameters with 'filter_' prefix.
+ */
+export declare function serializeFiltersToUrl(filters: Map<string, unknown>): URLSearchParams;
+/**
+ * Build Drizzle filter conditions from filter map.
+ *
+ * Filter keys come from the URL, so only entries the column map owns are used and a
+ * mapped value that is not a Drizzle column is ignored.
+ */
+export declare function buildFilterConditions(filters: Map<string, unknown>, columnMap: DatatableColumnMap): SQL | undefined;
+/**
+ * Helper to combine search and filter conditions
+ */
+export declare function combineConditions(...conditions: (SQL | undefined)[]): SQL | undefined;
+/**
+ * Build a search condition across multiple columns
+ */
+export declare function buildSearchCondition(searchTerm: string | undefined | null, columns: unknown[]): SQL | undefined;
+/**
+ * Helper to add filters to an existing query URL
+ */
+export declare function updateUrlWithFilterParams(currentUrl: URL, filters: Map<string, unknown>): URL;
+export { and, or, like, eq, ne, inArray, notInArray, gte, lte, gt, lt, isNull, isNotNull };
+/**
+ * Type helper for defining column maps
+ */
+export type FilterColumnMap<T extends object> = {
+    [K in keyof T]?: DatatableValue;
+};

package/dist/lib/datatable/server-filters.js

@@ -0,0 +1,206 @@
+/**
+ * Server-Side Filter Utilities
+ *
+ * Utilities for processing filters in load functions and building Drizzle queries.
+ * Designed to work with the datatable filter system.
+ */
+import { and, or, like, eq, ne, inArray, notInArray, gte, lte, gt, lt, isNull, isNotNull, not } from 'drizzle-orm';
+import * as z from 'zod/v4';
+import { mappedColumn, resolveColumn } from './filter-columns';
+import { parseFilterMap, readFilterParams, serializeFilterValue, FILTER_PARAM_PREFIX } from './filter-values';
+import { classifyDatatableValue, DatatableValueSchema } from './types';
+/**
+ * Parse filters from URL search parameters
+ *
+ * Extracts all parameters starting with 'filter_' prefix
+ * and attempts to parse their values (JSON or plain string).
+ * Empty plain values are skipped.
+ */
+export function parseFiltersFromUrl(searchParams) {
+    return readFilterParams(searchParams, false);
+}
+/**
+ * Serialize filters to URL search parameters
+ *
+ * Converts a filter map to URL parameters with 'filter_' prefix.
+ */
+export function serializeFiltersToUrl(filters) {
+    const params = new URLSearchParams();
+    for (const [key, value] of parseFilterMap(filters)) {
+        if (value === null || value === undefined || value === '') {
+            continue;
+        }
+        params.set(`${FILTER_PARAM_PREFIX}${key}`, serializeFilterValue(value));
+    }
+    return params;
+}
+/**
+ * Operator-style filter object, as sent by the datatable filter UI. Every field
+ * is optional and a field of the wrong shape counts as absent, so a malformed
+ * filter contributes no condition instead of an invalid one.
+ */
+const ComplexFilterSchema = z.object({
+    operator: z.string().optional().catch(undefined),
+    value: DatatableValueSchema.optional().catch(undefined),
+    values: z.array(DatatableValueSchema).optional().catch(undefined),
+    from: DatatableValueSchema.optional().catch(undefined),
+    to: DatatableValueSchema.optional().catch(undefined),
+    min: DatatableValueSchema.optional().catch(undefined),
+    max: DatatableValueSchema.optional().catch(undefined)
+});
+/**
+ * Build Drizzle filter conditions from filter map.
+ *
+ * Filter keys come from the URL, so only entries the column map owns are used and a
+ * mapped value that is not a Drizzle column is ignored.
+ */
+export function buildFilterConditions(filters, columnMap) {
+    const conditions = [];
+    for (const [key, value] of parseFilterMap(filters)) {
+        const column = mappedColumn(columnMap, key);
+        if (!column || value === null || value === undefined)
+            continue;
+        const classified = classifyDatatableValue(value);
+        switch (classified.kind) {
+            // Handle different value types
+            case 'text':
+                if (classified.value.includes('*')) {
+                    conditions.push(like(column, classified.value.replace(/\*/g, '%')));
+                }
+                else {
+                    conditions.push(like(column, `%${classified.value}%`));
+                }
+                break;
+            case 'boolean':
+            case 'number':
+            case 'date':
+                conditions.push(eq(column, classified.value));
+                break;
+            case 'structured': {
+                const list = z.array(DatatableValueSchema).safeParse(classified.value);
+                if (list.success) {
+                    if (list.data.length > 0)
+                        conditions.push(inArray(column, list.data));
+                }
+                else {
+                    conditions.push(...buildComplexFilter(column, classified.value));
+                }
+                break;
+            }
+            case 'empty':
+                break;
+        }
+    }
+    return conditions.length > 0 ? and(...conditions) : undefined;
+}
+/** A usable date for a range bound; anything that does not parse to one is no bound. */
+function rangeBound(bound) {
+    const classified = classifyDatatableValue(bound);
+    if (classified.kind === 'date')
+        return classified.value;
+    const parsed = new Date(String(bound));
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+/**
+ * Build complex filter conditions for objects with operators
+ */
+function buildComplexFilter(column, filterValue) {
+    const conditions = [];
+    const parsed = ComplexFilterSchema.safeParse(filterValue);
+    if (!parsed.success)
+        return conditions;
+    const { operator, value, values, from, to, min, max } = parsed.data;
+    // Text filter with operator
+    if (operator !== undefined && value !== undefined) {
+        switch (operator) {
+            case 'contains':
+                conditions.push(like(column, `%${value}%`));
+                break;
+            case 'equals':
+                conditions.push(eq(column, value));
+                break;
+            case 'notEquals':
+                conditions.push(ne(column, value));
+                break;
+            case 'startsWith':
+                conditions.push(like(column, `${value}%`));
+                break;
+            case 'endsWith':
+                conditions.push(like(column, `%${value}`));
+                break;
+            case 'notContains':
+                conditions.push(not(like(column, `%${value}%`)));
+                break;
+        }
+    }
+    // Multi-select with operator
+    if (operator !== undefined && values !== undefined && values.length > 0) {
+        switch (operator) {
+            case 'in':
+                conditions.push(inArray(column, values));
+                break;
+            case 'notIn':
+                conditions.push(notInArray(column, values));
+                break;
+        }
+    }
+    // Date range filter
+    const fromDate = from ? rangeBound(from) : undefined;
+    if (fromDate)
+        conditions.push(gte(column, fromDate));
+    const toDate = to ? rangeBound(to) : undefined;
+    if (toDate)
+        conditions.push(lte(column, toDate));
+    // Number range filter
+    if (min !== undefined && min !== null) {
+        conditions.push(gte(column, min));
+    }
+    if (max !== undefined && max !== null) {
+        conditions.push(lte(column, max));
+    }
+    return conditions;
+}
+/**
+ * Helper to combine search and filter conditions
+ */
+export function combineConditions(...conditions) {
+    const validConditions = conditions.filter((c) => c !== undefined);
+    if (validConditions.length === 0)
+        return undefined;
+    if (validConditions.length === 1)
+        return validConditions[0];
+    return and(...validConditions);
+}
+/**
+ * Build a search condition across multiple columns
+ */
+export function buildSearchCondition(searchTerm, columns) {
+    if (!searchTerm || searchTerm.trim() === '')
+        return undefined;
+    const term = searchTerm.trim();
+    const conditions = columns.flatMap((candidate) => {
+        const column = resolveColumn(candidate);
+        return column ? [like(column, `%${term}%`)] : [];
+    });
+    return conditions.length > 0 ? or(...conditions) : undefined;
+}
+/**
+ * Helper to add filters to an existing query URL
+ */
+export function updateUrlWithFilterParams(currentUrl, filters) {
+    const newUrl = new URL(currentUrl);
+    // Remove existing filter parameters
+    Array.from(newUrl.searchParams.keys())
+        .filter((key) => key.startsWith(FILTER_PARAM_PREFIX))
+        .forEach((key) => newUrl.searchParams.delete(key));
+    // Add new filter parameters
+    const filterParams = serializeFiltersToUrl(filters);
+    for (const [key, value] of filterParams.entries()) {
+        newUrl.searchParams.set(key, value);
+    }
+    // Reset to first page when filters change
+    newUrl.searchParams.set('page', '1');
+    return newUrl;
+}
+// Re-export drizzle operators for convenience
+export { and, or, like, eq, ne, inArray, notInArray, gte, lte, gt, lt, isNull, isNotNull };

package/dist/lib/datatable/server.d.ts

@@ -0,0 +1,4 @@
+export { loadDatatableRecords, parseFilters as parseDatatableFilters, buildWhereConditions as buildDatatableWhere, createDatatableUrl, loadFilterOptions, fetchSelectOptions, fetchSelectOptionsWithCount, getEnumSelectOptions } from './datatable-load.server';
+export { encodeFilters, decodeFilters, updateUrlWithFilters, getFiltersFromUrl, createFilterUrl } from './url-filters';
+export { toDataViewServerData } from './data-view-server';
+export type { DataViewServerData, ToDataViewExtras } from './data-view-server';

package/dist/lib/datatable/server.js

@@ -0,0 +1,3 @@
+export { loadDatatableRecords, parseFilters as parseDatatableFilters, buildWhereConditions as buildDatatableWhere, createDatatableUrl, loadFilterOptions, fetchSelectOptions, fetchSelectOptionsWithCount, getEnumSelectOptions } from './datatable-load.server';
+export { encodeFilters, decodeFilters, updateUrlWithFilters, getFiltersFromUrl, createFilterUrl } from './url-filters';
+export { toDataViewServerData } from './data-view-server';

package/dist/lib/datatable/sveltekit.d.ts

@@ -0,0 +1,14 @@
+import type { DataTableStore } from './datatable-store.svelte';
+import { type DatatableNavigateOptions, type DatatableNavigation, type NavigatedDatatableStoreOptions } from './navigation';
+export { buildDatatableDestination, createDatatableNavigation, type DatatableDefaults, type DatatableNavigateOptions, type DatatableNavigation, type DatatableNavigationAdapter, type NavigatedDatatableStoreOptions } from './navigation';
+/** @deprecated Bind `createDatatableNavigation` in the consuming application. */
+export declare function navigateDatatable(options: DatatableNavigateOptions & {
+    navigation: DatatableNavigation;
+}): Promise<void>;
+export type SveltekitDatatableStoreOptions<T> = NavigatedDatatableStoreOptions<T> & {
+    navigation: DatatableNavigation;
+};
+/** @deprecated Bind `createDatatableNavigation` in the consuming application. */
+export declare function createSveltekitPaginatedDataTableStore<T>(options: SveltekitDatatableStoreOptions<T>): DataTableStore<T>;
+/** @deprecated Use `createSveltekitPaginatedDataTableStore`. */
+export declare const createSveltekitDataTableStore: typeof createSveltekitPaginatedDataTableStore;

package/dist/lib/datatable/sveltekit.js

@@ -0,0 +1,14 @@
+import {} from './navigation';
+export { buildDatatableDestination, createDatatableNavigation } from './navigation';
+/** @deprecated Bind `createDatatableNavigation` in the consuming application. */
+export function navigateDatatable(options) {
+    const { navigation, ...navigateOptions } = options;
+    return navigation.navigate(navigateOptions);
+}
+/** @deprecated Bind `createDatatableNavigation` in the consuming application. */
+export function createSveltekitPaginatedDataTableStore(options) {
+    const { navigation, ...storeOptions } = options;
+    return navigation.createPaginatedStore(storeOptions);
+}
+/** @deprecated Use `createSveltekitPaginatedDataTableStore`. */
+export const createSveltekitDataTableStore = createSveltekitPaginatedDataTableStore;

package/dist/lib/datatable/types.d.ts

@@ -0,0 +1,250 @@
+import type { Snippet } from 'svelte';
+import * as z from 'zod/v4';
+import type { SQL } from 'drizzle-orm';
+/**
+ * Any value that is an object: a record, an array, a Date or an application
+ * row. Primitives, `null` and functions are not.
+ */
+export declare const DatatableObjectSchema: z.ZodCustom<object, object>;
+/**
+ * The one value schema of the datatable: a table cell, an accessor result, or
+ * a filter/query value. Scalars, arrays, records and application row objects
+ * are all accepted; `classifyDatatableValue` decides how a consumer treats one.
+ */
+export declare const DatatableValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodNaN, z.ZodLiteral<number>]>, z.ZodBoolean, z.ZodBigInt, z.ZodDate, z.ZodNull, z.ZodUndefined, z.ZodCustom<object, object>]>;
+/** A table cell, an accessor result, or a filter/query value. */
+export type DatatableValue = z.infer<typeof DatatableValueSchema>;
+/** A row of named datatable values. */
+export type DatatableRow = Record<string, DatatableValue>;
+/**
+ * Column definition for the DataTable component
+ */
+export interface Column<T> {
+    /** Unique identifier for the column */
+    id: string;
+    /** Optional sort key to use instead of the id when triggering sort callbacks */
+    sortId?: string;
+    /** Simple string header (used if headerSnippet is not provided) */
+    header?: string;
+    /** Custom header snippet for full control over header rendering */
+    headerSnippet?: Snippet;
+    /** Function to extract the value from a row */
+    accessor?: (row: T) => DatatableValue;
+    /** Custom cell renderer snippet */
+    cell?: Snippet<[CellContext<T>]>;
+    /** Whether this column is sortable */
+    sortable?: boolean;
+    /** Additional CSS classes for this column */
+    className?: string;
+    /** Column width (e.g., '100px', '20%', 'auto') */
+    width?: string;
+    /** Filter type for this column */
+    filterType?: FilterType;
+    /** Filter options (for select/multi-select) */
+    filterOptions?: SelectOption[];
+}
+/**
+ * Props for the DataTable component
+ */
+export interface DataTableProps<T> {
+    /** Array of data to display */
+    data: T[];
+    /** Column definitions */
+    columns: Column<T>[];
+    /** Callback when a row is clicked */
+    onRowClick?: (row: T) => void;
+    /** Message to display when there's no data */
+    emptyMessage?: string;
+    /** Additional CSS classes for the table */
+    className?: string;
+    /** Additional CSS classes for the table container */
+    containerClassName?: string;
+    /** Whether to show a loading state */
+    loading?: boolean;
+    /** Loading message */
+    loadingMessage?: string;
+    /** Enable filtering */
+    filterable?: boolean;
+    /** Enable sorting */
+    sortable?: boolean;
+    /** Current filters */
+    filters?: Map<string, unknown>;
+    /** Filter change handler */
+    onFilterChange?: (filters: Map<string, unknown>) => void;
+    /** Currently applied sort */
+    sort?: Sort | null;
+    /** Sort change handler */
+    onSortChange?: (sort: Sort | null) => void;
+}
+/**
+ * Context provided to cell snippets
+ */
+export interface CellContext<T> {
+    row: T;
+    value: DatatableValue;
+}
+/**
+ * Filter types
+ */
+export type FilterType = 'text' | 'select' | 'multi-select' | 'boolean' | 'date' | 'date-range' | 'number' | 'number-range';
+/**
+ * Select option for filters and cells
+ */
+export declare const SelectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SelectOption = z.infer<typeof SelectOptionSchema>;
+/**
+ * Filter definition
+ */
+export declare const FilterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+        select: "select";
+        text: "text";
+        "multi-select": "multi-select";
+        "date-range": "date-range";
+        "number-range": "number-range";
+    }>;
+    label: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    defaultValue: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type Filter = z.infer<typeof FilterSchema>;
+/**
+ * Sort definition
+ */
+export declare const SortSchema: z.ZodObject<{
+    column: z.ZodString;
+    direction: z.ZodEnum<{
+        desc: "desc";
+        asc: "asc";
+    }>;
+}, z.core.$strip>;
+export type Sort = z.infer<typeof SortSchema>;
+/**
+ * Pagination schema
+ */
+export declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+    total: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    hasNext: z.ZodBoolean;
+    hasPrev: z.ZodBoolean;
+}, z.core.$strip>;
+export type Pagination = z.infer<typeof PaginationSchema>;
+/**
+ * DataTable state schema
+ */
+export declare const DataTableStateSchema: z.ZodObject<{
+    filters: z.ZodMap<z.ZodString, z.ZodUnknown>;
+    sort: z.ZodNullable<z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            desc: "desc";
+            asc: "asc";
+        }>;
+    }, z.core.$strip>>;
+    search: z.ZodNullable<z.ZodString>;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+    selectedRows: z.ZodSet<z.ZodString>;
+}, z.core.$strip>;
+export type DataTableState = z.infer<typeof DataTableStateSchema>;
+/**
+ * DataTable action types
+ */
+export type DataTableAction<T> = {
+    label: string;
+    icon?: Snippet;
+    onclick: (row: T) => void | Promise<void>;
+    variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+    disabled?: boolean | ((row: T) => boolean);
+    hidden?: boolean | ((row: T) => boolean);
+};
+/**
+ * Cell formatter types
+ */
+export type CellFormatter<TValue = unknown, TRow = unknown> = (value: TValue, row: TRow) => string | number | boolean | Date | null | undefined;
+/**
+ * Common cell formatters
+ */
+export declare const cellFormatters: {
+    text: (value: DatatableValue) => string;
+    number: (value: DatatableValue) => number;
+    boolean: (value: DatatableValue) => boolean;
+    date: (value: DatatableValue) => Date;
+    currency: (value: number, currency?: string) => string;
+    percent: (value: number, decimals?: number) => string;
+    truncate: (value: string, length?: number) => string;
+};
+/**
+ * Filter handler type for server-side filtering
+ */
+export type FilterHandler<TColumn = unknown> = (value: DatatableValue, column: TColumn) => SQL | undefined;
+/**
+ * How a consumer should treat one datatable value. Produced by
+ * {@link classifyDatatableValue}, so renderers branch on the kind instead of
+ * probing runtime representations themselves.
+ */
+declare const DatatableValueKindSchema: z.ZodUnion<readonly [z.ZodPipe<z.ZodNull, z.ZodTransform<{
+    readonly kind: "empty";
+}, null>>, z.ZodPipe<z.ZodUndefined, z.ZodTransform<{
+    readonly kind: "empty";
+}, undefined>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<{
+    readonly kind: "boolean";
+    readonly value: boolean;
+}, boolean>>, z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodNaN, z.ZodLiteral<number>]>, z.ZodTransform<{
+    readonly kind: "number";
+    readonly value: number;
+}, number>>, z.ZodPipe<z.ZodString, z.ZodTransform<{
+    readonly kind: "text";
+    readonly value: string;
+}, string>>, z.ZodPipe<z.ZodDate, z.ZodTransform<{
+    readonly kind: "date";
+    readonly value: Date;
+}, Date>>]>;
+export type DatatableValueKind = z.output<typeof DatatableValueKindSchema> | {
+    readonly kind: 'structured';
+    readonly value: DatatableValue;
+};
+/**
+ * Classify a datatable value. Invalid dates and everything that is not a
+ * scalar the table formats itself (arrays, records, bigint, row objects) are
+ * `structured`; consumers render those through `String(value)`.
+ */
+export declare function classifyDatatableValue(value: DatatableValue): DatatableValueKind;
+/**
+ * DataTable load options for server-side loading
+ */
+export interface DataTableLoadOptions {
+    filters?: Map<string, unknown>;
+    sort?: Sort | null;
+    search?: string | null;
+    pagination?: {
+        page: number;
+        perPage: number;
+    };
+}
+/**
+ * DataTable load result
+ */
+export interface DataTableLoadResult<T = unknown> {
+    records: T[];
+    pagination: Pagination;
+    filters: Map<string, unknown>;
+    sort: Sort | null;
+    search: string | null;
+}
+export {};

package/dist/lib/datatable/types.js

@@ -0,0 +1,128 @@
+import * as z from 'zod/v4';
+/**
+ * Every number a cell can hold. Plain `z.number()` refuses NaN and infinities,
+ * which database drivers and `0 / 0` accessors do produce.
+ */
+const DatatableNumberSchema = z.union([
+    z.number(),
+    z.nan(),
+    z.literal([Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])
+]);
+/**
+ * Any value that is an object: a record, an array, a Date or an application
+ * row. Primitives, `null` and functions are not.
+ */
+export const DatatableObjectSchema = z.custom((candidate) => Object(candidate) === candidate && !isCallable(candidate));
+/** Whether a value can be called. */
+function isCallable(value) {
+    return typeof value === 'function';
+}
+/**
+ * The one value schema of the datatable: a table cell, an accessor result, or
+ * a filter/query value. Scalars, arrays, records and application row objects
+ * are all accepted; `classifyDatatableValue` decides how a consumer treats one.
+ */
+export const DatatableValueSchema = z.union([
+    z.string(),
+    DatatableNumberSchema,
+    z.boolean(),
+    z.bigint(),
+    z.date(),
+    z.null(),
+    z.undefined(),
+    DatatableObjectSchema
+]);
+/**
+ * Select option for filters and cells
+ */
+export const SelectOptionSchema = z.object({
+    value: z.string(),
+    label: z.string(),
+    disabled: z.boolean().optional()
+});
+/**
+ * Filter definition
+ */
+export const FilterSchema = z.object({
+    key: z.string(),
+    type: z.enum([
+        'text',
+        'select',
+        'multi-select',
+        'boolean',
+        'date',
+        'date-range',
+        'number',
+        'number-range'
+    ]),
+    label: z.string(),
+    placeholder: z.string().optional(),
+    options: z.array(SelectOptionSchema).optional(),
+    defaultValue: z.unknown().optional()
+});
+/**
+ * Sort definition
+ */
+export const SortSchema = z.object({
+    column: z.string(),
+    direction: z.enum(['asc', 'desc'])
+});
+/**
+ * Pagination schema
+ */
+export const PaginationSchema = z.object({
+    page: z.number().int().positive(),
+    perPage: z.number().int().positive(),
+    total: z.number().int().nonnegative(),
+    totalPages: z.number().int().nonnegative(),
+    hasNext: z.boolean(),
+    hasPrev: z.boolean()
+});
+/**
+ * DataTable state schema
+ */
+export const DataTableStateSchema = z.object({
+    filters: z.map(z.string(), z.unknown()),
+    sort: SortSchema.nullable(),
+    search: z.string().nullable(),
+    page: z.number().int().positive(),
+    perPage: z.number().int().positive(),
+    selectedRows: z.set(z.string())
+});
+/**
+ * Common cell formatters
+ */
+export const cellFormatters = {
+    text: (value) => String(value ?? ''),
+    number: (value) => Number(value ?? 0),
+    boolean: (value) => Boolean(value),
+    date: (value) => (value instanceof Date ? value : new Date(String(value))),
+    currency: (value, currency = 'USD') => new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency
+    }).format(value),
+    percent: (value, decimals = 2) => `${(value * 100).toFixed(decimals)}%`,
+    truncate: (value, length = 50) => value.length > length ? `${value.slice(0, length)}...` : value
+};
+/**
+ * How a consumer should treat one datatable value. Produced by
+ * {@link classifyDatatableValue}, so renderers branch on the kind instead of
+ * probing runtime representations themselves.
+ */
+const DatatableValueKindSchema = z.union([
+    z.null().transform(() => ({ kind: 'empty' })),
+    z.undefined().transform(() => ({ kind: 'empty' })),
+    z.boolean().transform((value) => ({ kind: 'boolean', value })),
+    DatatableNumberSchema.transform((value) => ({ kind: 'number', value })),
+    z.string().transform((value) => ({ kind: 'text', value })),
+    z.date().transform((value) => ({ kind: 'date', value }))
+]);
+/**
+ * Classify a datatable value. Invalid dates and everything that is not a
+ * scalar the table formats itself (arrays, records, bigint, row objects) are
+ * `structured`; consumers render those through `String(value)`.
+ */
+export function classifyDatatableValue(value) {
+    const parsed = DatatableValueKindSchema.safeParse(value);
+    return parsed.success ? parsed.data : { kind: 'structured', value };
+}