@cronocode/react-box 3.1.10 → 3.1.12

package/BOX_AI_CONTEXT.md

@@ -603,6 +603,24 @@ Box.components({
 </Box>;
 ```
 
+#### Component Inheritance with `extends`
+
+Components can inherit from other components using the `extends` property. The base component's full style tree (styles, variants, children) is used as the foundation, and the extending component's definitions are deep-merged on top:
+
+```tsx
+Box.components({
+  subgrid: {
+    extends: 'datagrid', // inherit all datagrid styles, variants, and children
+    styles: { b: 0, borderRadius: 0, shadow: 'none' },
+    children: {
+      header: { children: { cell: { styles: { fontSize: 12 } } } },
+    },
+  },
+});
+```
+
+This is especially useful for DataGrid, where the internal style tree is complex (pinning, sticky headers, hover groups, etc.). With `extends`, you only need to declare overrides.
+
 ---
 
 ## Extension System
@@ -858,250 +876,102 @@ resetStyles();
 
 ## DataGrid Component
 
-A powerful data grid with sorting, filtering, grouping, row selection, column pinning, and virtualization.
+> **Full documentation:** See [`../docs/DATAGRID.md`](../docs/DATAGRID.md) for complete API reference, all features, component tree, style customization, and designs system.
 
-### Import and Basic Usage
+A feature-rich data grid with sorting, filtering, grouping, row selection, column pinning, row detail, server-side pagination, virtualization, and full style customization via the component design system.
 
 ```tsx
 import DataGrid from '@cronocode/react-box/components/dataGrid';
+```
 
-const data = [
-  { id: 1, name: 'John', email: 'john@example.com', age: 30 },
-  { id: 2, name: 'Jane', email: 'jane@example.com', age: 25 },
-];
+### Quick Reference
 
+```tsx
 <DataGrid
-  data={data}
+  data={users}
   def={{
+    rowKey: 'id',
+    title: 'Users',
+    topBar: true,
+    bottomBar: true,
+    globalFilter: true,
+    rowSelection: { pinned: true },
+    showRowNumber: { pinned: true },
+    rowHeight: 40,
+    visibleRowsCount: 15,         // or 'all' to disable virtualization
     columns: [
-      { key: 'name', header: 'Name' },
-      { key: 'email', header: 'Email' },
-      { key: 'age', header: 'Age', align: 'right' },
+      { key: 'name', header: 'Name', filterable: true },
+      { key: 'age', header: 'Age', width: 80, align: 'right', filterable: { type: 'number' } },
+      { key: 'email', header: 'Email', width: 250, filterable: true },
+      { key: 'status', header: 'Status', filterable: { type: 'multiselect' } },
+      { key: 'country', header: 'Country', pin: 'RIGHT' },
     ],
+    rowDetail: {
+      content: (user) => <UserDetails user={user} />,
+      height: 'auto',
+      expandOnRowClick: true,
+    },
+    // pagination: { totalCount: 500, pageSize: 25 },  // for server-side pagination
   }}
-/>;
+  component="subgrid"               // optional: use a different component style tree
+  onSelectionChange={(e) => console.log(e.selectedRowKeys)}
+  // page={1}                       // controlled pagination
+  // onPageChange={(p, size) => {}} // page change handler
+  // onSortChange={(col, dir) => {}} // server-side sort handler
+  // onServerStateChange={(state) => fetch(state)} // unified server state callback
+/>
 ```
 
-### GridDefinition Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `columns` | `ColumnType[]` | Column definitions (required) |
-| `rowKey` | `keyof TRow \| (row) => Key` | Unique key for each row |
-| `rowHeight` | `number` | Row height in pixels (default: 36) |
-| `visibleRowsCount` | `number` | Number of visible rows (default: 10) |
-| `showRowNumber` | `boolean \| { pinned?: boolean; width?: number }` | Show row numbers |
-| `rowSelection` | `boolean \| { pinned?: boolean }` | Enable row selection checkboxes |
-| `topBar` | `boolean` | Show top bar with title and controls |
-| `bottomBar` | `boolean` | Show bottom bar with row count |
-| `title` | `ReactNode` | Title displayed in top bar |
-| `topBarContent` | `ReactNode` | Custom content in top bar |
-| `globalFilter` | `boolean` | Enable global search filter |
-| `globalFilterKeys` | `Key[]` | Columns to search (default: all) |
-| `sortable` | `boolean` | Enable sorting globally (default: true) |
-| `resizable` | `boolean` | Enable column resizing globally (default: true) |
-| `noDataComponent` | `ReactNode` | Custom empty state component |
-
-### ColumnType Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `key` | `string \| number` | Column key matching data property (required) |
-| `header` | `string` | Column header text |
-| `width` | `number` | Column width in pixels |
-| `align` | `'left' \| 'right' \| 'center'` | Text alignment |
-| `pin` | `'LEFT' \| 'RIGHT'` | Pin column to side |
-| `columns` | `ColumnType[]` | Nested columns for grouping |
-| `sortable` | `boolean` | Override global sortable setting |
-| `resizable` | `boolean` | Override global resizable setting |
-| `flexible` | `boolean` | Participate in flex distribution (default: true) |
-| `filterable` | `boolean \| FilterConfig` | Enable column filtering |
-| `Cell` | `React.ComponentType<{ cell }>` | Custom cell renderer |
-
-### DataGridProps
+### Key Props
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `data` | `TRow[]` | Data array (required) |
-| `def` | `GridDefinition` | Grid definition (required) |
-| `loading` | `boolean` | Show loading state |
+| `data` | `TRow[]` | Row data array (required) |
+| `def` | `GridDefinition` | Grid configuration (required) |
+| `component` | `string` | Component style tree name (default: `'datagrid'`) |
+| `loading` | `boolean` | Loading state |
+| `filters` | `((row: TRow) => boolean)[]` | External predicate filters |
+| `page` | `number` | Controlled page (1-indexed) |
+| `onPageChange` | `(page, pageSize) => void` | Page change callback |
+| `onSortChange` | `(columnKey, direction) => void` | Sort change callback |
+| `onServerStateChange` | `(state: ServerState) => void` | Unified callback with full state (page, pageSize, sort, filters) |
 | `onSelectionChange` | `(event) => void` | Selection change callback |
-| `globalFilterValue` | `string` | Controlled global filter |
-| `onGlobalFilterChange` | `(value) => void` | Global filter change callback |
-| `columnFilters` | `ColumnFilters` | Controlled column filters |
-| `onColumnFiltersChange` | `(filters) => void` | Column filters change callback |
+| `expandedRowKeys` | `Key[]` | Controlled expanded rows |
 
 ### Filter Types
 
 ```tsx
-// Text filter (default) - fuzzy search
-{ key: 'name', filterable: true }
-{ key: 'name', filterable: { type: 'text', placeholder: 'Search...' } }
-
-// Number filter - with comparison operators
-{ key: 'age', filterable: { type: 'number', min: 0, max: 100 } }
-
-// Multiselect filter - dropdown with checkboxes
-{ key: 'status', filterable: { type: 'multiselect' } }
-{ key: 'status', filterable: {
-  type: 'multiselect',
-  options: [
-    { label: 'Active', value: 'active' },
-    { label: 'Inactive', value: 'inactive' },
-  ]
-}}
+{ key: 'name', filterable: true }                              // Text (fuzzy)
+{ key: 'age', filterable: { type: 'number', min: 0, max: 100 } } // Number
+{ key: 'status', filterable: { type: 'multiselect' } }         // Multiselect
 ```
 
-### Column Grouping (Nested Headers)
-
-```tsx
-columns: [
-  {
-    key: 'personal',
-    header: 'Personal Info',
-    columns: [
-      { key: 'firstName', header: 'First Name' },
-      { key: 'lastName', header: 'Last Name' },
-    ],
-  },
-  {
-    key: 'contact',
-    header: 'Contact',
-    columns: [
-      { key: 'email', header: 'Email' },
-      { key: 'phone', header: 'Phone' },
-    ],
-  },
-]
-```
+### Style Customization
 
-### Custom Cell Renderer
+Every subcomponent is customizable via `Box.components()`. Register a separate component tree for different visual styles:
 
 ```tsx
-columns: [
-  {
-    key: 'status',
-    header: 'Status',
-    Cell: ({ cell }) => (
-      <Box
-        px={2}
-        py={1}
-        borderRadius={4}
-        bgColor={cell.value === 'active' ? 'green-100' : 'red-100'}
-        color={cell.value === 'active' ? 'green-800' : 'red-800'}
-      >
-        {cell.value}
-      </Box>
-    ),
+Box.components({
+  // Customize default datagrid
+  datagrid: {
+    children: {
+      body: { children: { detailRow: { styles: { bgColor: 'blue-50' } } } },
+      header: { children: { cell: { styles: { textTransform: 'uppercase' } } } },
+    },
   },
-  {
-    key: 'actions',
-    header: 'Actions',
-    Cell: ({ cell }) => (
-      <Button onClick={() => handleEdit(cell.row)}>Edit</Button>
-    ),
+  // Extend datagrid styles for embedded grids — inherits all internal styles (pinning, sticky, etc.)
+  subgrid: {
+    extends: 'datagrid',
+    styles: { b: 0, shadow: 'none', bgColor: 'transparent' },
+    children: {
+      header: { children: { cell: { styles: { fontSize: 12, py: 1 } } } },
+      body: { children: { cell: { styles: { fontSize: 13 } } } },
+    },
   },
-]
-```
-
-The `cell` object provides:
-- `cell.value` - Cell value
-- `cell.row` - Full row data
-- `cell.column` - Column model
-
-### Row Selection
-
-```tsx
-<DataGrid
-  data={data}
-  def={{
-    rowSelection: true,  // or { pinned: true } to pin checkbox column
-    columns: [...],
-  }}
-  onSelectionChange={(event) => {
-    console.log('Selected keys:', event.selectedRowKeys);
-    console.log('Action:', event.action); // 'select' | 'deselect'
-    console.log('All selected:', event.isAllSelected);
-  }}
-/>
-```
-
-### Sorting and Resizing Control
-
-```tsx
-// Disable globally
-def={{
-  sortable: false,
-  resizable: false,
-  columns: [...]
-}}
-
-// Override per column
-def={{
-  sortable: false,  // Global: no sorting
-  columns: [
-    { key: 'id', header: 'ID' },  // Not sortable (inherits global)
-    { key: 'name', header: 'Name', sortable: true },  // Sortable (override)
-  ]
-}}
-```
-
-### Flexible Column Sizing
-
-Columns automatically fill available space proportionally. Use `flexible: false` for fixed-width columns.
-
-```tsx
-columns: [
-  { key: 'id', header: 'ID', width: 60, flexible: false },  // Fixed at 60px
-  { key: 'name', header: 'Name', width: 200 },  // Flexes (200 base)
-  { key: 'email', header: 'Email', width: 300 },  // Flexes more (300 base)
-]
-```
-
-### Custom Empty State
-
-```tsx
-def={{
-  columns: [...],
-  noDataComponent: (
-    <Flex d="column" ai="center" gap={4} p={8}>
-      <Box fontSize={48}>📭</Box>
-      <Box color="gray-500">No records found</Box>
-    </Flex>
-  ),
-}}
-```
-
-### Full-Featured Example
+});
 
-```tsx
-<DataGrid
-  data={users}
-  def={{
-    title: 'Users Table',
-    topBar: true,
-    bottomBar: true,
-    globalFilter: true,
-    rowSelection: { pinned: true },
-    showRowNumber: { pinned: true },
-    rowHeight: 40,
-    visibleRowsCount: 10,
-    columns: [
-      {
-        key: 'personal',
-        header: 'Personal',
-        columns: [
-          { key: 'name', header: 'Name', filterable: true },
-          { key: 'age', header: 'Age', width: 80, align: 'right', filterable: { type: 'number' } },
-        ],
-      },
-      { key: 'email', header: 'Email', width: 250, filterable: true },
-      { key: 'status', header: 'Status', filterable: { type: 'multiselect' } },
-      { key: 'country', header: 'Country', pin: 'RIGHT' },
-    ],
-  }}
-  onSelectionChange={(e) => setSelected(e.selectedRowKeys)}
-/>
+// Use it — all children automatically resolve under "subgrid.*"
+<DataGrid component="subgrid" data={data} def={def} />
 ```
 
 ---

package/components/dataGrid/components/dataGridCellRowDetail.d.ts

@@ -0,0 +1,6 @@
+import { default as CellModel } from '../models/cellModel';
+interface Props<TRow> {
+    cell: CellModel<TRow>;
+}
+export default function DataGridCellRowDetail<TRow>(props: Props<TRow>): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/dataGrid/components/dataGridDetailRow.d.ts

@@ -0,0 +1,6 @@
+import { default as DetailRowModel } from '../models/detailRowModel';
+interface Props<TRow> {
+    row: DetailRowModel<TRow>;
+}
+export default function DataGridDetailRow<TRow>(props: Props<TRow>): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/dataGrid/components/dataGridEmptyColumns.d.ts

@@ -1 +1,6 @@
-export default function DataGridEmptyColumns(): import("react/jsx-runtime").JSX.Element;
+import { default as GridModel } from '../models/gridModel';
+interface Props<TRow> {
+    grid: GridModel<TRow>;
+}
+export default function DataGridEmptyColumns<TRow>(props: Props<TRow>): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/dataGrid/components/dataGridPagination.d.ts

@@ -2,5 +2,5 @@ import { default as GridModel } from '../models/gridModel';
 interface Props<TRow> {
     grid: GridModel<TRow>;
 }
-export default function DataGridPagination<TRow>(_props: Props<TRow>): import("react/jsx-runtime").JSX.Element;
+export default function DataGridPagination<TRow>(props: Props<TRow>): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/components/dataGrid/contracts/dataGridContract.d.ts

@@ -1,3 +1,4 @@
+import { ComponentsAndVariants } from '../../../types';
 import { default as CellModel } from '../models/cellModel';
 export type Key = string | number;
 export type PinPosition = 'LEFT' | 'RIGHT';
@@ -15,9 +16,22 @@ export interface PaginationState {
     totalItems: number;
     totalPages: number;
 }
-export type Pagination = boolean | {
+/** Server-side pagination configuration on GridDefinition */
+export interface PaginationConfig {
+    /** Total number of items across all pages (from server response) */
+    totalCount: number;
+    /** Page size override. If omitted, defaults to visibleRowsCount (or 10). */
+    pageSize?: number;
+}
+/** Snapshot of all server-relevant grid state, passed to onServerStateChange */
+export interface ServerState<TRow> {
+    page: number;
     pageSize: number;
-};
+    sortColumn: Key | undefined;
+    sortDirection: SortDirection | undefined;
+    columnFilters: ColumnFilters<TRow>;
+    globalFilterValue: string;
+}
 /** Filter type for column-level filtering */
 export type ColumnFilterType = 'text' | 'number' | 'multiselect';
 /** Text filter configuration (fuzzy search) */
@@ -58,6 +72,19 @@ export interface ColumnFilterConfig {
     /** For number: max value */
     max?: number;
 }
+/** Configuration for expandable row detail panel */
+export interface RowDetailConfig<TRow> {
+    /** Render function for the detail content */
+    content: (row: TRow) => React.ReactNode;
+    /** Height of the detail row. 'auto' sizes to content. Default: 'auto' */
+    height?: 'auto' | number | ((row: TRow) => number);
+    /** Whether clicking the row also toggles expansion. Default: false */
+    expandOnRowClick?: boolean;
+    /** Pin the expand column to LEFT. Default: false */
+    pinned?: boolean;
+    /** Width of the expand column. Default: 50 */
+    expandColumnWidth?: number;
+}
 export interface ColumnType<TRow> {
     key: Key;
     header?: string;
@@ -88,7 +115,8 @@ export interface GridDefinition<TRow> {
         pinned?: boolean;
     };
     rowHeight?: number;
-    visibleRowsCount?: number;
+    /** Number of visible rows. Set to 'all' to render all rows without virtualization or vertical scrollbar. */
+    visibleRowsCount?: number | 'all';
     topBar?: boolean;
     bottomBar?: boolean;
     /** Title displayed in the top bar */
@@ -105,8 +133,14 @@ export interface GridDefinition<TRow> {
     resizable?: boolean;
     /** Custom component to render when data is empty */
     noDataComponent?: React.ReactNode;
+    /** Enable expandable row detail panel */
+    rowDetail?: RowDetailConfig<TRow>;
+    /** Server-side pagination. Provide totalCount from the API response. */
+    pagination?: PaginationConfig;
 }
 export interface DataGridProps<TRow> {
+    /** Component name for style resolution. Default: 'datagrid'. Set to a custom name to use a different component style tree. */
+    component?: keyof ComponentsAndVariants;
     data: TRow[];
     def: GridDefinition<TRow>;
     loading?: boolean;
@@ -121,6 +155,18 @@ export interface DataGridProps<TRow> {
     onColumnFiltersChange?: (filters: ColumnFilters<TRow>) => void;
     /** External predicate filters applied before global/column filters. Memoize with useMemo for performance. */
     filters?: ((row: TRow) => boolean)[];
+    /** Controlled expanded detail row keys */
+    expandedRowKeys?: Key[];
+    /** Callback when expanded detail rows change */
+    onExpandedRowKeysChange?: (keys: Key[]) => void;
+    /** Controlled current page (1-indexed). Used with pagination. */
+    page?: number;
+    /** Callback when page changes. Receives page (1-indexed) and pageSize. */
+    onPageChange?: (page: number, pageSize: number) => void;
+    /** Callback when sort changes. For server-side sorting with pagination. */
+    onSortChange?: (columnKey: Key | undefined, direction: SortDirection | undefined) => void;
+    /** Fires on any server-relevant state change (page, sort, filter). Provides full state snapshot for API calls. */
+    onServerStateChange?: (state: ServerState<TRow>) => void;
 }
 interface SelectionChangeEvent<TRow, TKey = TRow[keyof TRow] | number | string> {
     action: 'select' | 'deselect';

package/components/dataGrid/models/detailRowModel.d.ts

@@ -0,0 +1,16 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+import { default as RowModel } from './rowModel';
+export default class DetailRowModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly parentRow: RowModel<TRow>;
+    constructor(grid: GridModel<TRow>, parentRow: RowModel<TRow>);
+    get key(): Key;
+    static readonly AUTO_HEIGHT_ESTIMATE = 200;
+    get height(): 'auto' | number;
+    /** Numeric height for virtualization offset calculations. Uses estimate for 'auto'. */
+    get heightForOffset(): number;
+    readonly count = 0;
+    get flatRows(): this[];
+    get allRows(): RowModel<TRow>[];
+}

package/components/dataGrid/models/gridModel.d.ts

@@ -1,5 +1,7 @@
-import { ColumnFilters, DataGridProps, FilterValue, Key, PinPosition } from '../contracts/dataGridContract';
+import { ComponentsAndVariants } from '../../../types';
+import { ColumnFilters, DataGridProps, FilterValue, Key, PaginationState, PinPosition } from '../contracts/dataGridContract';
 import { default as ColumnModel } from './columnModel';
+import { default as DetailRowModel } from './detailRowModel';
 import { default as GroupRowModel } from './groupRowModel';
 import { default as RowModel } from './rowModel';
 export declare const EMPTY_CELL_KEY: Key;
@@ -7,10 +9,12 @@ export declare const ROW_NUMBER_CELL_KEY: Key;
 export declare const DEFAULT_ROW_NUMBER_COLUMN_WIDTH = 70;
 export declare const ROW_SELECTION_CELL_KEY: Key;
 export declare const GROUPING_CELL_KEY: Key;
+export declare const ROW_DETAIL_CELL_KEY: Key;
 export default class GridModel<TRow> {
     props: DataGridProps<TRow>;
     readonly update: () => void;
     constructor(props: DataGridProps<TRow>, update: () => void);
+    get componentName(): keyof ComponentsAndVariants;
     readonly sourceColumns: import('../../../utils/memo').Memo<ColumnModel<TRow>[]>;
     readonly columns: import('../../../utils/memo').Memo<{
         left: ColumnModel<TRow>[];
@@ -48,6 +52,7 @@ export default class GridModel<TRow> {
      * Get filtered data (applies external, global, then column filters)
      */
     get filteredData(): TRow[];
+    private fireServerStateChange;
     /**
      * Set global filter value
      */
@@ -80,7 +85,7 @@ export default class GridModel<TRow> {
         total: number;
     };
     readonly rows: import('../../../utils/memo').Memo<GroupRowModel<TRow>[] | RowModel<TRow>[]>;
-    readonly flatRows: import('../../../utils/memo').Memo<(GroupRowModel<TRow> | RowModel<TRow>)[]>;
+    readonly flatRows: import('../../../utils/memo').Memo<(GroupRowModel<TRow> | RowModel<TRow> | DetailRowModel<TRow>)[]>;
     get rowHeight(): number;
     readonly sizes: import('../../../utils/memo').Memo<Record<string, string>>;
     private _containerWidth;
@@ -92,6 +97,19 @@ export default class GridModel<TRow> {
     readonly MIN_COLUMN_WIDTH_PX = 48;
     readonly DEFAULT_COLUMN_WIDTH_PX = 200;
     expandedGroupRow: Set<Key>;
+    private _expandedDetailRows;
+    get expandedDetailRows(): Set<Key>;
+    toggleDetailRow: (rowKey: Key) => void;
+    private _page;
+    get page(): number;
+    get pageSize(): number;
+    get isPaginated(): boolean;
+    get paginationState(): PaginationState | undefined;
+    changePage: (page: number) => void;
+    readonly rowOffsets: import('../../../utils/memo').Memo<{
+        offsets: number[];
+        totalHeight: number;
+    }>;
     selectedRows: Set<Key>;
     get leftEdge(): number;
     get rightEdge(): number;

package/components/dataGrid/models/groupRowModel.d.ts

@@ -1,5 +1,6 @@
 import { Key } from '../contracts/dataGridContract';
 import { default as ColumnModel } from './columnModel';
+import { default as DetailRowModel } from './detailRowModel';
 import { default as GridModel } from './gridModel';
 import { default as GroupRowCellModel } from './groupRowCellModel';
 import { default as RowModel } from './rowModel';
@@ -18,7 +19,7 @@ export default class GroupRowModel<TRow> {
     get expanded(): boolean;
     get depth(): number;
     get count(): number;
-    get flatRows(): (RowModel<TRow> | GroupRowModel<TRow>)[];
+    get flatRows(): (RowModel<TRow> | GroupRowModel<TRow> | DetailRowModel<TRow>)[];
     get allRows(): RowModel<TRow>[];
     get groupingColumn(): ColumnModel<TRow>;
     get groupingColumnGridColumn(): number;

package/components/dataGrid/models/rowModel.d.ts

@@ -1,5 +1,6 @@
 import { Key } from '../contracts/dataGridContract';
 import { default as CellModel } from './cellModel';
+import { default as DetailRowModel } from './detailRowModel';
 import { default as GridModel } from './gridModel';
 import { default as GroupRowModel } from './groupRowModel';
 export default class RowModel<TRow> {
@@ -12,6 +13,7 @@ export default class RowModel<TRow> {
     readonly count = 1;
     get cells(): CellModel<TRow>[];
     get selected(): boolean;
-    get flatRows(): this;
+    get expanded(): boolean;
+    get flatRows(): (RowModel<TRow> | DetailRowModel<TRow>)[];
     get allRows(): this;
 }