@dashforge/tw 0.5.0-beta → 0.7.0-beta

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

@@ -0,0 +1,189 @@
+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 only; per-column UI deferred to v1-bis) ─────
+  filterModel?: TableFilterModel;
+  onFilterChange?: (model: TableFilterModel) => void;
+
+  // ───── 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,144 @@
+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',
+    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>;

package/src/components/Dialog/dialog.variants.ts

@@ -26,21 +26,25 @@ export const dialogVariants = tv({
     ],
     content: [
       'fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2',
-      'w-full bg-white dark:bg-neutral-900 rounded-lg shadow-xl',
-      'border border-neutral-200 dark:border-neutral-800',
+      // bg-white hardcoded (doesn't auto-invert) so `dark:` is needed.
+      // Target `dark:bg-neutral-100` = #171717 in dark mode (one
+      // elevation tier above page surface).
+      'w-full bg-white dark:bg-neutral-100 rounded-lg shadow-xl',
+      // border-neutral-200 auto-inverts — no `dark:` needed.
+      'border border-neutral-200',
       'p-6 flex flex-col gap-4 max-h-[90vh]',
       'focus:outline-none',
       'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
       'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
       'motion-reduce:transition-none motion-reduce:duration-0',
     ],
-    title: 'text-lg font-semibold leading-tight text-neutral-900 dark:text-neutral-50',
-    description: 'text-sm text-neutral-600 dark:text-neutral-400',
+    // All neutral text classes auto-invert via CSS-var swap.
+    title: 'text-lg font-semibold leading-tight text-neutral-900',
+    description: 'text-sm text-neutral-600',
     closeButton: [
       'absolute top-4 right-4 inline-flex items-center justify-center',
       'h-8 w-8 rounded-md text-neutral-500 hover:text-neutral-900',
-      'dark:text-neutral-400 dark:hover:text-neutral-50',
-      'hover:bg-neutral-100 dark:hover:bg-neutral-800',
+      'hover:bg-neutral-100',
       'focus:outline-none focus:ring-2 focus:ring-primary-500',
       'transition-colors',
     ],

package/src/components/Divider/Divider.test.tsx

@@ -66,8 +66,10 @@ describe('<Divider>', () => {
     it('default neutral', () => {
       const { container } = render(<Divider />);
       const cls = container.firstElementChild?.className ?? '';
+      // Sprint 4.3 identity sweep: neutral palette auto-inverts via
+      // the dashforgePreset() CSS-var swap — no `dark:` needed.
       expect(cls).toContain('border-neutral-200');
-      expect(cls).toContain('dark:border-neutral-800');
+      expect(cls).not.toContain('dark:border-neutral-');
     });
 
     it('color="primary"', () => {

package/src/components/Divider/Divider.tsx

@@ -128,7 +128,7 @@ export const Divider = forwardRef<HTMLElement, DividerProps>(
         {...rest}
       >
         <span aria-hidden="true" className={cn(lineCommon, leftStubClass)} />
-        <span className={cn('shrink-0 text-sm text-neutral-500 dark:text-neutral-400', labelPadding)}>
+        <span className={cn('shrink-0 text-sm text-neutral-500', labelPadding)}>
           {children}
         </span>
         <span aria-hidden="true" className={cn(lineCommon, rightStubClass)} />

package/src/components/Divider/divider.variants.ts

@@ -85,7 +85,8 @@ export const dividerLineVariants = tv({
     },
 
     color: {
-      neutral:   'border-neutral-200 dark:border-neutral-800',
+      // Neutral palette auto-inverts via CSS-var swap (no `dark:`).
+      neutral:   'border-neutral-200',
       primary:   'border-primary-300 dark:border-primary-700',
       secondary: 'border-secondary-300 dark:border-secondary-700',
       success:   'border-success-300 dark:border-success-700',

package/src/components/Pagination/Pagination.tsx

@@ -238,7 +238,9 @@ export function Pagination(props: PaginationProps) {
             disabled={disabled}
             aria-label={labels.perPage}
             className={cn(
-              'rounded-md border border-neutral-300 dark:border-neutral-700 bg-white dark:bg-neutral-900 px-2 py-1',
+              // Auto-invert via CSS-var swap — no `dark:` variants needed
+              // on neutral palette.
+              'rounded-md border border-neutral-300 bg-neutral-50 px-2 py-1',
               'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
             )}
           >

package/src/components/Pagination/pagination.variants.ts

@@ -23,28 +23,34 @@ import { tv, type VariantProps } from 'tailwind-variants';
 export const paginationVariants = tv({
   slots: {
     root: 'flex flex-wrap items-center gap-3',
-    summary: 'text-neutral-600 dark:text-neutral-400',
+    // All neutral classes auto-invert via the dashforgePreset() CSS-var
+    // swap. `bg-neutral-50` provides the button surface (matches page
+    // surface; the border gives the separation). `hover:bg-neutral-100`
+    // is the one-tier elevation that works in both modes.
+    summary: 'text-neutral-600',
     list: 'inline-flex items-center gap-1',
     pageButton: [
       'inline-flex items-center justify-center rounded-md',
-      'border border-neutral-300 dark:border-neutral-700',
-      'bg-white dark:bg-neutral-900',
-      'text-neutral-700 dark:text-neutral-300',
-      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'border border-neutral-300',
+      'bg-neutral-50',
+      'text-neutral-700',
+      'hover:bg-neutral-100',
       'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
       'transition-colors motion-reduce:transition-none',
       'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
     ],
     activeButton: [
+      // Primary palette does NOT auto-invert — `dark:` shift is a
+      // design choice for tone refinement (kept).
       'bg-primary-500 text-white border-primary-500',
       'hover:bg-primary-600 dark:hover:bg-primary-400',
     ],
     navButton: [
       'inline-flex items-center justify-center rounded-md',
-      'border border-neutral-300 dark:border-neutral-700',
-      'bg-white dark:bg-neutral-900',
-      'text-neutral-700 dark:text-neutral-300',
-      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'border border-neutral-300',
+      'bg-neutral-50',
+      'text-neutral-700',
+      'hover:bg-neutral-100',
       'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
       'transition-colors motion-reduce:transition-none',
       'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
@@ -52,12 +58,12 @@ export const paginationVariants = tv({
     ellipsis: 'inline-flex items-center justify-center text-neutral-500 px-1',
     pageSizeSelector: [
       'inline-flex items-center gap-2',
-      'text-neutral-700 dark:text-neutral-300',
+      'text-neutral-700',
     ],
     jumpInput: [
-      'rounded-md border border-neutral-300 dark:border-neutral-700',
-      'bg-white dark:bg-neutral-900',
-      'text-neutral-900 dark:text-neutral-50',
+      'rounded-md border border-neutral-300',
+      'bg-neutral-50',
+      'text-neutral-900',
       'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
       'transition-colors motion-reduce:transition-none',
     ],

package/src/components/Popover/popover.variants.ts

@@ -3,15 +3,21 @@ import { tv, type VariantProps } from 'tailwind-variants';
 export const popoverVariants = tv({
   slots: {
     content: [
-      'z-50 rounded-md border border-neutral-200 dark:border-neutral-800',
-      'bg-white dark:bg-neutral-900 p-4 shadow-lg',
-      'text-sm text-neutral-900 dark:text-neutral-50',
+      // Neutral border auto-inverts via CSS-var swap.
+      'z-50 rounded-md border border-neutral-200',
+      // bg-white hardcoded (no auto-invert) so `dark:` is required.
+      // Target `dark:bg-neutral-100` resolves to #171717 in dark mode
+      // (one elevation tier above the page surface).
+      'bg-white dark:bg-neutral-100 p-4 shadow-lg',
+      // Text auto-inverts.
+      'text-sm text-neutral-900',
       'focus:outline-none',
       'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
       'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
       'motion-reduce:transition-none motion-reduce:duration-0',
     ],
-    arrow: 'fill-white dark:fill-neutral-900',
+    // Arrow follows content bg: `fill-white` in light + matching dark target.
+    arrow: 'fill-white dark:fill-neutral-100',
   },
 });
 

package/src/components/Skeleton/skeleton.variants.ts

@@ -35,7 +35,8 @@ export const skeletonVariants = tv({
   slots: {
     root: [
       'block',
-      'bg-neutral-200 dark:bg-neutral-800',
+      // Neutral palette auto-inverts via CSS-var swap (no `dark:`).
+      'bg-neutral-200',
       'motion-reduce:animate-none',
     ],
   },