@dynostack/react-grid 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { RowData, ColumnDef, ColumnPinningState, VisibilityState, Column, Table, CellContext, FilterFn } from '@tanstack/react-table';
+import { RowData, ColumnDef, SortingState, ColumnFiltersState, ColumnPinningState, VisibilityState, Column, Table, CellContext, FilterFn } from '@tanstack/react-table';
 import { CSSProperties } from 'react';
 
 type RowActionId = "view" | "edit" | "duplicate" | "delete" | string;
@@ -30,7 +30,7 @@ declare function DataTableRowActions<TData>({ row, actions, customActions, onAct
  * values are emitted as inline CSS variables on the table root, scoped
  * through CSS cascade to that instance only.
  */
-type DataTableTheme = {
+type DataTableTokens = {
     background?: string;
     foreground?: string;
     card?: string;
@@ -55,51 +55,90 @@ type DataTableTheme = {
     /** Font family for the table body. */
     fontFamily?: string;
 };
-/** Convert a DataTableTheme into a `style` object of CSS variables. */
+/**
+ * A theme passed to `<DataTable theme={…}>`.
+ *
+ * Two accepted shapes:
+ *
+ * 1. A flat token map (`DataTableTokens`) — applied as-is, no dark variant.
+ * 2. A moded map (`DataTableModedTheme`) — `light` is applied by default,
+ *    `dark` is swapped in automatically inside `@media (prefers-color-scheme: dark)`
+ *    *and* inside any `.dark` ancestor.
+ */
+type DataTableModedTheme = {
+    light?: DataTableTokens;
+    dark?: DataTableTokens;
+};
+type DataTableTheme = DataTableTokens | DataTableModedTheme;
+/** Convert a DataTableTokens map into a CSS `style` object. */
+declare function tokensToStyle(tokens?: DataTableTokens): CSSProperties;
+/**
+ * Back-compat: original API accepted a flat `DataTableTheme`. Still works,
+ * but if a moded theme is passed it returns the `light` variant only — use
+ * `splitTheme` if you need both variants.
+ */
 declare function themeToStyle(theme?: DataTableTheme): CSSProperties;
-/** A handful of ready-to-use theme presets. */
+/**
+ * Split a theme into its `light` (always applied) and optional `dark` (applied
+ * via `@media (prefers-color-scheme: dark)` and `.dark` ancestor) variants.
+ *
+ * For flat themes, returns `{ light: theme, dark: undefined }`.
+ */
+declare function splitTheme(theme?: DataTableTheme): {
+    light: DataTableTokens | undefined;
+    dark: DataTableTokens | undefined;
+};
+/**
+ * Build a full light+dark token set from a single OKLCH hue.
+ *
+ * @param hue    Hue angle 0–360 (e.g. 285 for violet, 162 for emerald).
+ * @param chroma Optional base chroma for tinted neutrals (default 0.03).
+ */
+declare function buildPreset(hue: number, chroma?: number): DataTableModedTheme;
+/**
+ * Convert a tokens map into a CSS declaration string (no selector, no braces),
+ * e.g. `--background:oklch(1 0 0);--foreground:oklch(0.145 0 0)`.
+ *
+ * Used internally to inject scoped <style> blocks for moded themes.
+ */
+declare function tokensToCssBlock(tokens?: DataTableTokens): string;
+/**
+ * Ready-to-use theme presets.
+ *
+ * Each preset is a full light + dark token set — passing one to
+ * `<DataTable theme={…}>` repaints the entire table and auto-flips on OS
+ * dark mode (or when a `.dark` ancestor is added).
+ *
+ * Custom hues:
+ *
+ * ```ts
+ * import { buildPreset } from "@dynostack/react-grid"
+ * const tealPreset = buildPreset(180)
+ * ```
+ */
 declare const themePresets: {
+    neutral: DataTableModedTheme;
     light: {
-        background: string;
-        foreground: string;
-        card: string;
-        cardForeground: string;
-        primary: string;
-        primaryForeground: string;
-        border: string;
+        light: DataTableTokens | undefined;
     };
     dark: {
-        background: string;
-        foreground: string;
-        card: string;
-        cardForeground: string;
-        primary: string;
-        primaryForeground: string;
-        border: string;
-    };
-    emerald: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
-    };
-    violet: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
-    };
-    amber: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
+        light: DataTableTokens | undefined;
     };
+    violet: DataTableModedTheme;
+    emerald: DataTableModedTheme;
+    amber: DataTableModedTheme;
+    rose: DataTableModedTheme;
+    sky: DataTableModedTheme;
+    slate: DataTableModedTheme;
 };
 type DataTableThemeName = keyof typeof themePresets;
+/**
+ * Bundled fallback tokens used when `<DataTable isolate>` is set. These let
+ * the grid render correctly even when the consumer hasn't imported
+ * `styles.css` or provided any theme of their own.
+ */
+declare const ISOLATE_LIGHT_TOKENS: DataTableTokens;
+declare const ISOLATE_DARK_TOKENS: DataTableTokens;
 
 type CellEditorType = "text" | "number" | "currency" | "date" | "select" | "switch" | "checkbox";
 type FilterType = "text" | "number" | "select" | "multi-select" | "boolean" | "date";
@@ -168,17 +207,54 @@ type DataTableLabels = {
     total?: string;
     noData?: string;
     noResults?: string;
+    loadError?: string;
+    retry?: string;
     refreshing?: string;
     rowsPerPage?: string;
     page?: string;
     of?: string;
 };
 type DataTableDensity = "compact" | "default" | "comfortable";
+type DataTableFetchParams = {
+    pageIndex: number;
+    pageSize: number;
+    sorting: SortingState;
+    columnFilters: ColumnFiltersState;
+    globalFilter: string;
+};
+type DataTableDataSourceResult<TData> = TData[] | {
+    rows: TData[];
+    totalRecords?: number;
+};
+type DataTableErrorContext = {
+    type: "load" | "refresh";
+    message: string;
+};
+type DataTableDataSource<TData> = {
+    /**
+     * Fetch rows internally. In "client" mode, return the full data set and the
+     * table applies client-side sort/filter/pagination. In "server" mode, return
+     * the current page and optionally `totalRecords`.
+     */
+    fetchRows: (params: DataTableFetchParams) => Promise<DataTableDataSourceResult<TData>>;
+    /** "client" by default. Use "server" for API-side pagination/filter/sort. */
+    mode?: "client" | "server";
+    /** Set false to pause fetching. */
+    enabled?: boolean;
+    /** Optional rows to show before the first fetch resolves. */
+    initialData?: TData[];
+    /** Refetch when these external values change. Memoize this array. */
+    deps?: readonly unknown[];
+    /** Called for load/refresh errors so apps can show a toast. */
+    onError?: (error: unknown, context: DataTableErrorContext) => void;
+};
 type DataTableProps<TData extends {
     id: string | number;
 }> = {
-    data: TData[];
+    data?: TData[];
     columns: ColumnDef<TData>[];
+    /** Optional internal fetcher. Omit this when using controlled `data`. */
+    dataSource?: DataTableDataSource<TData>;
     isLoading?: boolean;
     isFetching?: boolean;
     onRefresh?: () => void;
@@ -216,12 +292,35 @@ type DataTableProps<TData extends {
     labels?: DataTableLabels;
     /** Row + cell padding density. Defaults to "default". */
     density?: DataTableDensity;
-    /** CSS-variable overrides (shadcn-compatible) scoped to this instance. */
+    /**
+     * CSS-variable overrides (shadcn-compatible) scoped to this instance.
+     *
+     * Two accepted shapes:
+     *
+     *   theme={{ primary: "...", accent: "..." }}              // flat tokens
+     *   theme={{ light: { ... }, dark: { ... } }}              // moded — auto-flips
+     *
+     * Moded themes apply `light` always and swap to `dark` inside
+     * `@media (prefers-color-scheme: dark)` *and* inside any `.dark` ancestor.
+     *
+     * Use `themePresets.violet` (or any preset) for a ready-made moded theme.
+     */
     theme?: DataTableTheme;
+    /**
+     * When `true`, the grid does NOT inherit CSS variables from the app's
+     * `:root` (shadcn, custom theme, etc.). Instead it renders with the
+     * package's bundled defaults (or whatever you pass via `theme`).
+     *
+     * Useful when embedding the grid inside a heavily-themed shell where you
+     * want the table to keep its own look regardless of surrounding context.
+     *
+     * Defaults to `false` (inherit app theme).
+     */
+    isolate?: boolean;
 };
 declare function DataTable<TData extends {
     id: string | number;
-}>({ data, columns, isLoading, isFetching, onRefresh, totalRecords, exportFileName, enableSelection, renderSubRow, getSubRows, rowActions, customRowActions, onRowAction, onCellEdit, onRowSave, onAddRow, onBulkDelete, initialPageSize, pageSizeOptions, initialColumnPinning, initialColumnVisibility, globalFilter: globalFilterProp, onGlobalFilterChange, className, toolbarSlot, features, labels: labelsProp, density, theme, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
+}>({ data, columns, dataSource, isLoading, isFetching, onRefresh, totalRecords, exportFileName, enableSelection, renderSubRow, getSubRows, rowActions, customRowActions, onRowAction, onCellEdit, onRowSave, onAddRow, onBulkDelete, initialPageSize, pageSizeOptions, initialColumnPinning, initialColumnVisibility, globalFilter: globalFilterProp, onGlobalFilterChange, className, toolbarSlot, features, labels: labelsProp, density, theme, isolate, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
 
 type Props$2<TData, TValue> = {
     column: Column<TData, TValue>;
@@ -313,4 +412,4 @@ declare function ColumnFilterPanel<TData, TValue>(props: CommonProps<TData, TVal
 declare function exportToCsv<TData>(table: Table<TData>, fileName?: string): void;
 declare function exportToExcel<TData>(table: Table<TData>, fileName?: string): void;
 
-export { type AdvFilter, type CellEditorType, ColumnFilterPanel, type Combine, type Condition, type CustomRowAction, DataTable, type DataTableColumn, DataTableColumnHeader, type DataTableDensity, type DataTableFeatures, type DataTableLabels, DataTablePagination, type DataTableProps, DataTableRowActions, type DataTableRowActionsProps, type DataTableTheme, type DataTableThemeName, DataTableToolbar, type DateOp, EditableCell, type FilterType, type NumberOp, type RowAction, type RowActionId, type SelectOption, type SetFilter, type TextOp, booleanFilterFn, dateFilterFn, exportToCsv, exportToExcel, isFilterActive, numberFilterFn, setFilterFn, textFilterFn, themePresets, themeToStyle };
+export { type AdvFilter, type CellEditorType, ColumnFilterPanel, type Combine, type Condition, type CustomRowAction, DataTable, type DataTableColumn, DataTableColumnHeader, type DataTableDataSource, type DataTableDataSourceResult, type DataTableDensity, type DataTableErrorContext, type DataTableFeatures, type DataTableFetchParams, type DataTableLabels, type DataTableModedTheme, DataTablePagination, type DataTableProps, DataTableRowActions, type DataTableRowActionsProps, type DataTableTheme, type DataTableThemeName, type DataTableTokens, DataTableToolbar, type DateOp, EditableCell, type FilterType, ISOLATE_DARK_TOKENS, ISOLATE_LIGHT_TOKENS, type NumberOp, type RowAction, type RowActionId, type SelectOption, type SetFilter, type TextOp, booleanFilterFn, buildPreset, dateFilterFn, exportToCsv, exportToExcel, isFilterActive, numberFilterFn, setFilterFn, splitTheme, textFilterFn, themePresets, themeToStyle, tokensToCssBlock, tokensToStyle };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { RowData, ColumnDef, ColumnPinningState, VisibilityState, Column, Table, CellContext, FilterFn } from '@tanstack/react-table';
+import { RowData, ColumnDef, SortingState, ColumnFiltersState, ColumnPinningState, VisibilityState, Column, Table, CellContext, FilterFn } from '@tanstack/react-table';
 import { CSSProperties } from 'react';
 
 type RowActionId = "view" | "edit" | "duplicate" | "delete" | string;
@@ -30,7 +30,7 @@ declare function DataTableRowActions<TData>({ row, actions, customActions, onAct
  * values are emitted as inline CSS variables on the table root, scoped
  * through CSS cascade to that instance only.
  */
-type DataTableTheme = {
+type DataTableTokens = {
     background?: string;
     foreground?: string;
     card?: string;
@@ -55,51 +55,90 @@ type DataTableTheme = {
     /** Font family for the table body. */
     fontFamily?: string;
 };
-/** Convert a DataTableTheme into a `style` object of CSS variables. */
+/**
+ * A theme passed to `<DataTable theme={…}>`.
+ *
+ * Two accepted shapes:
+ *
+ * 1. A flat token map (`DataTableTokens`) — applied as-is, no dark variant.
+ * 2. A moded map (`DataTableModedTheme`) — `light` is applied by default,
+ *    `dark` is swapped in automatically inside `@media (prefers-color-scheme: dark)`
+ *    *and* inside any `.dark` ancestor.
+ */
+type DataTableModedTheme = {
+    light?: DataTableTokens;
+    dark?: DataTableTokens;
+};
+type DataTableTheme = DataTableTokens | DataTableModedTheme;
+/** Convert a DataTableTokens map into a CSS `style` object. */
+declare function tokensToStyle(tokens?: DataTableTokens): CSSProperties;
+/**
+ * Back-compat: original API accepted a flat `DataTableTheme`. Still works,
+ * but if a moded theme is passed it returns the `light` variant only — use
+ * `splitTheme` if you need both variants.
+ */
 declare function themeToStyle(theme?: DataTableTheme): CSSProperties;
-/** A handful of ready-to-use theme presets. */
+/**
+ * Split a theme into its `light` (always applied) and optional `dark` (applied
+ * via `@media (prefers-color-scheme: dark)` and `.dark` ancestor) variants.
+ *
+ * For flat themes, returns `{ light: theme, dark: undefined }`.
+ */
+declare function splitTheme(theme?: DataTableTheme): {
+    light: DataTableTokens | undefined;
+    dark: DataTableTokens | undefined;
+};
+/**
+ * Build a full light+dark token set from a single OKLCH hue.
+ *
+ * @param hue    Hue angle 0–360 (e.g. 285 for violet, 162 for emerald).
+ * @param chroma Optional base chroma for tinted neutrals (default 0.03).
+ */
+declare function buildPreset(hue: number, chroma?: number): DataTableModedTheme;
+/**
+ * Convert a tokens map into a CSS declaration string (no selector, no braces),
+ * e.g. `--background:oklch(1 0 0);--foreground:oklch(0.145 0 0)`.
+ *
+ * Used internally to inject scoped <style> blocks for moded themes.
+ */
+declare function tokensToCssBlock(tokens?: DataTableTokens): string;
+/**
+ * Ready-to-use theme presets.
+ *
+ * Each preset is a full light + dark token set — passing one to
+ * `<DataTable theme={…}>` repaints the entire table and auto-flips on OS
+ * dark mode (or when a `.dark` ancestor is added).
+ *
+ * Custom hues:
+ *
+ * ```ts
+ * import { buildPreset } from "@dynostack/react-grid"
+ * const tealPreset = buildPreset(180)
+ * ```
+ */
 declare const themePresets: {
+    neutral: DataTableModedTheme;
     light: {
-        background: string;
-        foreground: string;
-        card: string;
-        cardForeground: string;
-        primary: string;
-        primaryForeground: string;
-        border: string;
+        light: DataTableTokens | undefined;
     };
     dark: {
-        background: string;
-        foreground: string;
-        card: string;
-        cardForeground: string;
-        primary: string;
-        primaryForeground: string;
-        border: string;
-    };
-    emerald: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
-    };
-    violet: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
-    };
-    amber: {
-        primary: string;
-        primaryForeground: string;
-        accent: string;
-        accentForeground: string;
-        ring: string;
+        light: DataTableTokens | undefined;
     };
+    violet: DataTableModedTheme;
+    emerald: DataTableModedTheme;
+    amber: DataTableModedTheme;
+    rose: DataTableModedTheme;
+    sky: DataTableModedTheme;
+    slate: DataTableModedTheme;
 };
 type DataTableThemeName = keyof typeof themePresets;
+/**
+ * Bundled fallback tokens used when `<DataTable isolate>` is set. These let
+ * the grid render correctly even when the consumer hasn't imported
+ * `styles.css` or provided any theme of their own.
+ */
+declare const ISOLATE_LIGHT_TOKENS: DataTableTokens;
+declare const ISOLATE_DARK_TOKENS: DataTableTokens;
 
 type CellEditorType = "text" | "number" | "currency" | "date" | "select" | "switch" | "checkbox";
 type FilterType = "text" | "number" | "select" | "multi-select" | "boolean" | "date";
@@ -168,17 +207,54 @@ type DataTableLabels = {
     total?: string;
     noData?: string;
     noResults?: string;
+    loadError?: string;
+    retry?: string;
     refreshing?: string;
     rowsPerPage?: string;
     page?: string;
     of?: string;
 };
 type DataTableDensity = "compact" | "default" | "comfortable";
+type DataTableFetchParams = {
+    pageIndex: number;
+    pageSize: number;
+    sorting: SortingState;
+    columnFilters: ColumnFiltersState;
+    globalFilter: string;
+};
+type DataTableDataSourceResult<TData> = TData[] | {
+    rows: TData[];
+    totalRecords?: number;
+};
+type DataTableErrorContext = {
+    type: "load" | "refresh";
+    message: string;
+};
+type DataTableDataSource<TData> = {
+    /**
+     * Fetch rows internally. In "client" mode, return the full data set and the
+     * table applies client-side sort/filter/pagination. In "server" mode, return
+     * the current page and optionally `totalRecords`.
+     */
+    fetchRows: (params: DataTableFetchParams) => Promise<DataTableDataSourceResult<TData>>;
+    /** "client" by default. Use "server" for API-side pagination/filter/sort. */
+    mode?: "client" | "server";
+    /** Set false to pause fetching. */
+    enabled?: boolean;
+    /** Optional rows to show before the first fetch resolves. */
+    initialData?: TData[];
+    /** Refetch when these external values change. Memoize this array. */
+    deps?: readonly unknown[];
+    /** Called for load/refresh errors so apps can show a toast. */
+    onError?: (error: unknown, context: DataTableErrorContext) => void;
+};
 type DataTableProps<TData extends {
     id: string | number;
 }> = {
-    data: TData[];
+    data?: TData[];
     columns: ColumnDef<TData>[];
+    /** Optional internal fetcher. Omit this when using controlled `data`. */
+    dataSource?: DataTableDataSource<TData>;
     isLoading?: boolean;
     isFetching?: boolean;
     onRefresh?: () => void;
@@ -216,12 +292,35 @@ type DataTableProps<TData extends {
     labels?: DataTableLabels;
     /** Row + cell padding density. Defaults to "default". */
     density?: DataTableDensity;
-    /** CSS-variable overrides (shadcn-compatible) scoped to this instance. */
+    /**
+     * CSS-variable overrides (shadcn-compatible) scoped to this instance.
+     *
+     * Two accepted shapes:
+     *
+     *   theme={{ primary: "...", accent: "..." }}              // flat tokens
+     *   theme={{ light: { ... }, dark: { ... } }}              // moded — auto-flips
+     *
+     * Moded themes apply `light` always and swap to `dark` inside
+     * `@media (prefers-color-scheme: dark)` *and* inside any `.dark` ancestor.
+     *
+     * Use `themePresets.violet` (or any preset) for a ready-made moded theme.
+     */
     theme?: DataTableTheme;
+    /**
+     * When `true`, the grid does NOT inherit CSS variables from the app's
+     * `:root` (shadcn, custom theme, etc.). Instead it renders with the
+     * package's bundled defaults (or whatever you pass via `theme`).
+     *
+     * Useful when embedding the grid inside a heavily-themed shell where you
+     * want the table to keep its own look regardless of surrounding context.
+     *
+     * Defaults to `false` (inherit app theme).
+     */
+    isolate?: boolean;
 };
 declare function DataTable<TData extends {
     id: string | number;
-}>({ data, columns, isLoading, isFetching, onRefresh, totalRecords, exportFileName, enableSelection, renderSubRow, getSubRows, rowActions, customRowActions, onRowAction, onCellEdit, onRowSave, onAddRow, onBulkDelete, initialPageSize, pageSizeOptions, initialColumnPinning, initialColumnVisibility, globalFilter: globalFilterProp, onGlobalFilterChange, className, toolbarSlot, features, labels: labelsProp, density, theme, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
+}>({ data, columns, dataSource, isLoading, isFetching, onRefresh, totalRecords, exportFileName, enableSelection, renderSubRow, getSubRows, rowActions, customRowActions, onRowAction, onCellEdit, onRowSave, onAddRow, onBulkDelete, initialPageSize, pageSizeOptions, initialColumnPinning, initialColumnVisibility, globalFilter: globalFilterProp, onGlobalFilterChange, className, toolbarSlot, features, labels: labelsProp, density, theme, isolate, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
 
 type Props$2<TData, TValue> = {
     column: Column<TData, TValue>;
@@ -313,4 +412,4 @@ declare function ColumnFilterPanel<TData, TValue>(props: CommonProps<TData, TVal
 declare function exportToCsv<TData>(table: Table<TData>, fileName?: string): void;
 declare function exportToExcel<TData>(table: Table<TData>, fileName?: string): void;
 
-export { type AdvFilter, type CellEditorType, ColumnFilterPanel, type Combine, type Condition, type CustomRowAction, DataTable, type DataTableColumn, DataTableColumnHeader, type DataTableDensity, type DataTableFeatures, type DataTableLabels, DataTablePagination, type DataTableProps, DataTableRowActions, type DataTableRowActionsProps, type DataTableTheme, type DataTableThemeName, DataTableToolbar, type DateOp, EditableCell, type FilterType, type NumberOp, type RowAction, type RowActionId, type SelectOption, type SetFilter, type TextOp, booleanFilterFn, dateFilterFn, exportToCsv, exportToExcel, isFilterActive, numberFilterFn, setFilterFn, textFilterFn, themePresets, themeToStyle };
+export { type AdvFilter, type CellEditorType, ColumnFilterPanel, type Combine, type Condition, type CustomRowAction, DataTable, type DataTableColumn, DataTableColumnHeader, type DataTableDataSource, type DataTableDataSourceResult, type DataTableDensity, type DataTableErrorContext, type DataTableFeatures, type DataTableFetchParams, type DataTableLabels, type DataTableModedTheme, DataTablePagination, type DataTableProps, DataTableRowActions, type DataTableRowActionsProps, type DataTableTheme, type DataTableThemeName, type DataTableTokens, DataTableToolbar, type DateOp, EditableCell, type FilterType, ISOLATE_DARK_TOKENS, ISOLATE_LIGHT_TOKENS, type NumberOp, type RowAction, type RowActionId, type SelectOption, type SetFilter, type TextOp, booleanFilterFn, buildPreset, dateFilterFn, exportToCsv, exportToExcel, isFilterActive, numberFilterFn, setFilterFn, splitTheme, textFilterFn, themePresets, themeToStyle, tokensToCssBlock, tokensToStyle };