@dashforge/tw 1.1.0 → 1.2.0

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

@@ -1,238 +0,0 @@
-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

@@ -1,152 +0,0 @@
-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>;