@dashforge/tw 0.6.0-beta → 0.8.0-beta

package/src/components/DataGrid/dataGrid.types.ts

@@ -0,0 +1,238 @@
+import type { ReactNode } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { DataGridVariants } from './dataGrid.variants.js';
+import type {
+  TableColumn,
+  TableSortModel,
+  TableFilterModel,
+  TableRowSelectionMode,
+  TableLabels,
+} from '../Table/table.types.js';
+
+// Re-export the column type unchanged — DataGrid uses the SAME shape
+// as Table. Consumers writing `cols: TableColumn<T>[]` get autocomplete
+// and don't need a parallel `DataGridColumn<T>` type.
+
+// ───── Selection scope ─────
+
+/**
+ * Determines what the "select all" header checkbox covers when
+ * `rowSelection="multiple"` is enabled.
+ *
+ *  - `'visible'` — only the rows currently in the viewport (after
+ *    virtualization windowing) are toggled. Useful when the
+ *    underlying data is paginated server-side and "all" semantically
+ *    refers to the screen.
+ *  - `'allLoaded'` (default) — all rows currently in the `rows` prop
+ *    are toggled. The standard "select everything I can see in this
+ *    dataset" pattern.
+ *
+ * For "select all in server-side dataset", the consumer wires it
+ * themselves (e.g. fetch all ids + setSelectedRowIds).
+ */
+export type DataGridSelectAllScope = 'visible' | 'allLoaded';
+
+// ───── Server-side mode flags ─────
+
+/**
+ * Independent opt-in flags that delegate the corresponding pipeline
+ * step to the consumer. With each flag enabled, DataGrid emits the
+ * `onXChange` callback but does NOT perform the operation locally
+ * — the consumer is expected to provide the resulting `rows` array.
+ */
+export interface DataGridServerSideFlags {
+  serverSideSort?: boolean;
+  serverSideFilter?: boolean;
+  serverSideSearch?: boolean;
+  /**
+   * When true, DataGrid does NOT slice `rows` for pagination. The
+   * virtualization math uses `totalCount` (required) to size the
+   * scroll container.
+   */
+  serverSidePagination?: boolean;
+}
+
+// ───── Pagination (DataGrid-internal, opt-in) ─────
+
+export interface DataGridPaginationConfig {
+  page: number;
+  pageSize: number;
+  onPageChange: (page: number) => void;
+  onPageSizeChange?: (pageSize: number) => void;
+  pageSizeOptions?: number[];
+}
+
+// ───── Slot props ─────
+
+export interface DataGridSlotProps {
+  root?: { className?: string };
+  toolbar?: { className?: string };
+  search?: { className?: string };
+  scroll?: { className?: string };
+  table?: { className?: string };
+  thead?: { className?: string };
+  tbody?: { className?: string };
+  headerRow?: { className?: string };
+  headerCell?: { className?: string };
+  row?: { className?: string };
+  cell?: { className?: string };
+  emptyState?: { className?: string };
+  loadingOverlay?: { className?: string };
+  selectionCell?: { className?: string };
+  rowActionsCell?: { className?: string };
+  bulkActionFooter?: { className?: string };
+  /** Optional Pagination wrapper below the virtualized scroll. */
+  pagination?: { className?: string };
+}
+
+// ───── Main props ─────
+
+/**
+ * Props for `<DataGrid>`.
+ *
+ * Companion to `<Table>` for large data sets. Where Table renders
+ * every row in DOM, DataGrid uses **homemade virtualization**
+ * (`IntersectionObserver` + scroll-event + `requestAnimationFrame`
+ * — no external libs) to render only a window of visible rows.
+ *
+ * Required:
+ *  - `rows`, `cols`, `getRowId` — same as Table
+ *  - `rowHeight` (fixed in v1; variable-height deferred to v1-bis)
+ *  - `height` — explicit container height in CSS units, OR
+ *    consumer sets it via `sx` / parent layout (the scroll container
+ *    needs a bounded height for virtualization to work)
+ *
+ * Optional:
+ *  - `overscan` — extra rows above/below viewport (default 5)
+ *  - Server-side mode flags (4 independent opt-ins)
+ *  - Internal pagination (opt-in via `pagination` config)
+ *  - `selectAllScope` — `'visible'` vs `'allLoaded'` for header
+ *    select-all checkbox
+ *  - Everything Table accepts: sort / filter / search / selection /
+ *    row actions / RBAC / variants / i18n labels / sx / slotProps
+ */
+export interface DataGridProps<T extends object>
+  extends Pick<DataGridVariants, 'variant' | 'size' | 'density'>,
+    DataGridServerSideFlags {
+  // ───── Data ─────
+  rows: T[];
+  cols: TableColumn<T>[];
+  getRowId: (row: T, index: number) => string;
+
+  /** Required: total dataset count. In client-side mode equals
+   *  `rows.length`; in `serverSidePagination` mode the consumer
+   *  provides the full count so the virtual scroll height matches. */
+  totalCount?: number;
+
+  // ───── Virtualization (REQUIRED) ─────
+  /** Fixed row height in pixels. Required for windowing math. */
+  rowHeight: number;
+  /** Rows rendered above/below the viewport. @default 5 */
+  overscan?: number;
+  /** Container height in CSS units (e.g. `"600px"`, `"100vh"`).
+   *  Required for the scroll container to bound the virtualization. */
+  height?: string;
+
+  // ───── Sort ─────
+  sortModel?: TableSortModel;
+  onSortChange?: (model: TableSortModel) => void;
+  defaultSortModel?: TableSortModel;
+
+  // ───── Search ─────
+  enableSearch?: boolean;
+  searchQuery?: string;
+  onSearchQueryChange?: (q: string) => void;
+  searchPlaceholder?: string;
+  searchDebounceMs?: number;
+
+  // ───── Filter (model + in-header per-column UI) ─────
+  filterModel?: TableFilterModel;
+  onFilterChange?: (model: TableFilterModel) => void;
+
+  // ───── Column visibility (dialog UI in toolbar) ─────
+  /**
+   * List of column `field`s currently hidden. Drives the column
+   * visibility dialog. When omitted, the dialog manages state
+   * internally (seeded from each column's `defaultHidden`).
+   */
+  hiddenColumns?: string[];
+  /** Called when the user commits a change in the visibility dialog. */
+  onHiddenColumnsChange?: (next: string[]) => void;
+  /**
+   * Show the "Columns" button in the toolbar. Defaults to `true` so
+   * the dialog is discoverable; set `false` for embedded / compact
+   * grids where columns are externally controlled.
+   * @default true
+   */
+  enableColumnVisibility?: boolean;
+
+  // ───── Column resize (drag the right edge of a <th>) ─────
+  /**
+   * Map of `field → width (px)` for user-resized columns. When
+   * omitted, DataGrid manages widths internally — seeded from each
+   * column's `width` prop.
+   */
+  columnWidths?: Record<string, number>;
+  /** Called when the user finishes (or actively drags) a resize. */
+  onColumnWidthsChange?: (next: Record<string, number>) => void;
+  /**
+   * Allow user-driven column resize via drag on the right edge of
+   * each `<th>`. Per-column opt-out via `col.resizable = false`.
+   * @default true
+   */
+  enableColumnResize?: boolean;
+
+  // ───── Column reorder (drag a header to reposition) ─────
+  /**
+   * Custom display order, as a list of `field`s. Columns not in the
+   * list are appended in their original order at the end. When
+   * omitted, DataGrid uses the order from the `cols` prop.
+   */
+  columnOrder?: string[];
+  /** Called when the user finishes a reorder drag. */
+  onColumnOrderChange?: (next: string[]) => void;
+  /**
+   * Allow user-driven column reorder via native HTML5 drag-and-drop
+   * on each `<th>`. Per-column opt-out via `col.reorderable = false`.
+   * @default true
+   */
+  enableColumnReorder?: boolean;
+
+  // ───── Selection ─────
+  rowSelection?: TableRowSelectionMode;
+  selectedRowIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+  /** Bulk action sticky footer (visible only when selection > 0). */
+  bulkActions?: (selectedRows: T[]) => ReactNode;
+  /**
+   * Scope of the "select all" header checkbox.
+   * @default 'allLoaded'
+   */
+  selectAllScope?: DataGridSelectAllScope;
+
+  // ───── Internal pagination (opt-in) ─────
+  pagination?: DataGridPaginationConfig;
+
+  // ───── Row actions ─────
+  rowActions?: (row: T) => ReactNode;
+
+  // ───── States ─────
+  loading?: boolean;
+  loadingRowCount?: number;
+  emptyState?: ReactNode;
+
+  // ───── A11Y ─────
+  stickyHeader?: boolean;
+  caption?: ReactNode;
+  showCaption?: boolean;
+
+  // ───── RBAC ─────
+  access?: AccessRequirement;
+
+  // ───── i18n ─────
+  labels?: TableLabels;
+
+  // ───── Customization ─────
+  sx?: string;
+  slotProps?: DataGridSlotProps;
+}

package/src/components/DataGrid/dataGrid.variants.ts

@@ -0,0 +1,152 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<DataGrid>` variant recipe.
+ *
+ * Sibling of `tableVariants` — shares the same visual axes (variant /
+ * size / density) and the same identity-rule patterns:
+ *  - No `dark:` variants on neutral palette (auto-invert via the
+ *    dashforgePreset() CSS var swap).
+ *  - Selected row uses LeftNav `itemActive` pattern
+ *    (`bg-primary-100 text-primary-900`) — guaranteed contrast.
+ *  - Hover uses one-tier elevation (`bg-neutral-100`).
+ *
+ * DataGrid-specific slot additions vs Table:
+ *  - `stickyLeftCell` — column that uses `cols[i].sticky === 'left'`.
+ *    Z-index ordering: `thead` (z-10) < `stickyLeftCell` (z-11) <
+ *    `header × stickyLeft top-left corner cell` (z-20).
+ *  - `paginationFooter` — wraps the optional `<Pagination>`.
+ */
+export const dataGridVariants = tv({
+  slots: {
+    root: 'w-full',
+    toolbar: 'flex flex-wrap items-center gap-3 mb-3',
+    search: [
+      'inline-flex items-center gap-2',
+      'w-full max-w-sm rounded-md',
+      'border border-neutral-300',
+      'bg-neutral-50',
+      'focus-within:ring-2 focus-within:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+    ],
+    // The scroll container needs an explicit bounded height for
+    // virtualization to compute the window. The consumer passes
+    // `height` prop (inline style) or sets it via `sx` / parent
+    // layout — DataGrid does NOT default a height (would be wrong
+    // for most layouts).
+    scroll: 'relative w-full overflow-auto rounded-md',
+    table: 'w-full caption-bottom text-left',
+    thead: 'bg-neutral-50 sticky top-0 z-10',
+    tbody: '',
+    headerRow: '',
+    headerCell: [
+      'text-neutral-700',
+      'font-semibold whitespace-nowrap select-none',
+      'border-b border-neutral-200',
+      'bg-neutral-50',
+    ],
+    headerCellButton: [
+      'group inline-flex items-center gap-1 select-none',
+      'hover:text-neutral-900',
+      'focus:outline-none focus-visible:underline',
+      'transition-colors motion-reduce:transition-none',
+    ],
+    row: [
+      'group/row transition-colors motion-reduce:transition-none',
+      'hover:bg-neutral-100',
+      'data-[selected=true]:bg-primary-100',
+      'data-[selected=true]:text-primary-900',
+      'data-[selected=true]:font-medium',
+    ],
+    cell: [
+      'text-neutral-900',
+      'border-b border-neutral-200',
+      'align-middle',
+    ],
+    selectionCell: 'w-10 text-center',
+    rowActionsCell: [
+      'w-12 text-right',
+      'opacity-0 group-hover/row:opacity-100 group-focus-within/row:opacity-100',
+      'transition-opacity motion-reduce:transition-none',
+    ],
+    emptyState: 'py-12 text-center text-neutral-500',
+    loadingOverlay: 'pointer-events-none',
+    bulkActionFooter: [
+      'sticky bottom-0 z-20',
+      'flex flex-wrap items-center justify-between gap-3',
+      'px-3 py-2',
+      'border-t border-neutral-200',
+      'bg-neutral-50 shadow-md',
+    ],
+    // Sticky LEFT column — uses `position: sticky; left: 0` + z-index
+    // so the column stays pinned during horizontal scroll. The
+    // `bg-neutral-50` ensures the column doesn't bleed when content
+    // scrolls underneath.
+    stickyLeftCell: 'sticky left-0 z-[1] bg-neutral-50',
+    // Sticky left × header intersection (top-left corner): higher
+    // z-index than both header (`z-10`) and sticky col (`z-[1]`).
+    stickyLeftHeaderCell: 'sticky left-0 z-20 bg-neutral-50',
+    // Sticky RIGHT column — mirror of stickyLeftCell. The first
+    // right-sticky column gets a `border-l` to separate it visually
+    // from the scrollable area (the consumer can override via
+    // slotProps if they don't want it).
+    stickyRightCell:
+      'sticky right-0 z-[1] bg-neutral-50 border-l border-neutral-200',
+    stickyRightHeaderCell:
+      'sticky right-0 z-20 bg-neutral-50 border-l border-neutral-200',
+    paginationFooter: 'flex justify-end mt-3',
+  },
+  variants: {
+    variant: {
+      plain: {},
+      lines: {},
+      striped: {
+        row: 'odd:bg-neutral-100/60',
+      },
+      bordered: {
+        table: 'border border-neutral-200',
+        cell: 'border-r last:border-r-0 border-neutral-200',
+        headerCell:
+          'border-r last:border-r-0 border-neutral-200',
+      },
+    },
+    size: {
+      sm: {
+        headerCell: 'text-xs',
+        cell: 'text-xs',
+        search: 'text-xs',
+      },
+      md: {
+        headerCell: 'text-sm',
+        cell: 'text-sm',
+        search: 'text-sm',
+      },
+      lg: {
+        headerCell: 'text-base',
+        cell: 'text-base',
+        search: 'text-base',
+      },
+    },
+    density: {
+      compact: {
+        headerCell: 'px-2 py-1',
+        cell: 'px-2 py-1',
+      },
+      comfortable: {
+        headerCell: 'px-3 py-2',
+        cell: 'px-3 py-2',
+      },
+      spacious: {
+        headerCell: 'px-4 py-3',
+        cell: 'px-4 py-3',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'lines',
+    size: 'md',
+    density: 'comfortable',
+  },
+});
+
+export type DataGridVariants = VariantProps<typeof dataGridVariants>;