@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/tables/DataTable/column-sizing.ts

@@ -0,0 +1,166 @@
+import type { CSSProperties } from 'react';
+import type { DataTableColumn } from './data-table-utils';
+
+/** Column widths in px by column id. */
+export type ColumnWidths = Readonly<Record<string, number>>;
+
+/** Columns pinned to the start (left in LTR) and end edges, in display order. */
+export interface PinnedColumns {
+  left?: readonly string[];
+  right?: readonly string[];
+}
+
+export type PinSide = 'left' | 'right';
+
+export const DEFAULT_COLUMN_WIDTH = 160;
+export const MIN_COLUMN_WIDTH = 60;
+export const MAX_COLUMN_WIDTH = 640;
+/** Width of the selection (checkbox) and row-actions columns: `w-10` and `w-12`. */
+export const LEAD_WIDTH = 40;
+export const TRAIL_WIDTH = 48;
+
+/** Width limits of a column. */
+export function widthBounds<T>(column: DataTableColumn<T>): { min: number; max: number } {
+  const min = column.minWidth ?? MIN_COLUMN_WIDTH;
+  return { min, max: Math.max(min, column.maxWidth ?? MAX_COLUMN_WIDTH) };
+}
+
+/** Clamps a width to the column's limits (rounded to whole px). */
+export function clampColumnWidth<T>(column: DataTableColumn<T>, width: number): number {
+  const { min, max } = widthBounds(column);
+  return Math.round(Math.min(max, Math.max(min, width)));
+}
+
+/** Effective width of a column: the widths map, then `column.width`, then the default. */
+export function columnWidthOf<T>(column: DataTableColumn<T>, widths: ColumnWidths): number {
+  return clampColumnWidth(column, widths[column.id] ?? column.width ?? DEFAULT_COLUMN_WIDTH);
+}
+
+export function pinSideOf(id: string, pinned: PinnedColumns): PinSide | null {
+  if (pinned.left?.includes(id)) return 'left';
+  if (pinned.right?.includes(id)) return 'right';
+  return null;
+}
+
+/** Pins a column to a side (appended to that side) or unpins it (`null`). */
+export function setColumnPin(pinned: PinnedColumns, id: string, side: PinSide | null): PinnedColumns {
+  const left = (pinned.left ?? []).filter((c) => c !== id);
+  const right = (pinned.right ?? []).filter((c) => c !== id);
+  if (side === 'left') left.push(id);
+  if (side === 'right') right.push(id);
+  return { left, right };
+}
+
+/** Display order: start-pinned columns (pin order), unpinned columns (column order), end-pinned columns. */
+export function orderColumns<T>(
+  columns: ReadonlyArray<DataTableColumn<T>>,
+  pinned: PinnedColumns,
+): Array<DataTableColumn<T>> {
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const pick = (ids: readonly string[] = []) =>
+    ids.map((id) => byId.get(id)).filter((c): c is DataTableColumn<T> => c != null);
+  const left = pick(pinned.left);
+  const right = pick(pinned.right);
+  const taken = new Set([...left, ...right].map((c) => c.id));
+  return [...left, ...columns.filter((c) => !taken.has(c.id)), ...right];
+}
+
+/** Layout of one column cell: inline style (width, sticky offset) and classes. */
+export interface CellLayout {
+  style?: CSSProperties;
+  className?: string;
+  pinned?: PinSide;
+}
+
+export interface TableLayout {
+  /** Layout per column id. */
+  columns: ReadonlyMap<string, CellLayout>;
+  /** Selection column (sticky at the start when any column is start-pinned). */
+  lead: CellLayout;
+  /** Row-actions column (sticky at the end when any column is end-pinned). */
+  trail: CellLayout;
+  /** Table classes and style (fixed layout and total width when columns are sized). */
+  tableClassName?: string;
+  tableStyle?: CSSProperties;
+}
+
+// Sticky cells need an opaque surface; the row tint (hover, selected) is layered under the content.
+const STICKY = 'sticky z-[1] bg-card';
+const START_EDGE = 'border-e border-border';
+const END_EDGE = 'border-s border-border';
+
+/**
+ * Computes widths and sticky offsets. With `sized` off and nothing pinned the table keeps its
+ * automatic layout (the original behaviour); otherwise it switches to a fixed layout whose width
+ * is the sum of the column widths (at least the container's).
+ */
+export function tableLayout<T>({
+  columns,
+  widths,
+  pinned,
+  sized,
+  lead,
+  trail,
+}: {
+  columns: ReadonlyArray<DataTableColumn<T>>;
+  widths: ColumnWidths;
+  pinned: PinnedColumns;
+  sized: boolean;
+  lead: boolean;
+  trail: boolean;
+}): TableLayout {
+  const map = new Map<string, CellLayout>();
+  const hasStart = columns.some((c) => pinSideOf(c.id, pinned) === 'left');
+  const hasEnd = columns.some((c) => pinSideOf(c.id, pinned) === 'right');
+  const active = sized || hasStart || hasEnd;
+  if (!active) {
+    for (const c of columns) map.set(c.id, {});
+    return { columns: map, lead: {}, trail: {} };
+  }
+  const widthOf = (c: DataTableColumn<T>) => columnWidthOf(c, widths);
+  const fixed = (w: number): CSSProperties => ({ width: w, minWidth: w, maxWidth: w });
+
+  let start = lead ? LEAD_WIDTH : 0;
+  const startIds = columns.filter((c) => pinSideOf(c.id, pinned) === 'left');
+  startIds.forEach((c, i) => {
+    const w = widthOf(c);
+    map.set(c.id, {
+      pinned: 'left',
+      style: { ...fixed(w), insetInlineStart: start },
+      className: [STICKY, i === startIds.length - 1 && START_EDGE].filter(Boolean).join(' '),
+    });
+    start += w;
+  });
+  let end = trail ? TRAIL_WIDTH : 0;
+  const endIds = columns.filter((c) => pinSideOf(c.id, pinned) === 'right');
+  [...endIds].reverse().forEach((c, i) => {
+    const w = widthOf(c);
+    map.set(c.id, {
+      pinned: 'right',
+      style: { ...fixed(w), insetInlineEnd: end },
+      className: [STICKY, i === endIds.length - 1 && END_EDGE].filter(Boolean).join(' '),
+    });
+    end += w;
+  });
+  for (const c of columns) if (!map.has(c.id)) map.set(c.id, { style: fixed(widthOf(c)) });
+
+  const total = columns.reduce((sum, c) => sum + widthOf(c), 0) + (lead ? LEAD_WIDTH : 0) + (trail ? TRAIL_WIDTH : 0);
+  return {
+    columns: map,
+    lead: hasStart ? { pinned: 'left', style: { insetInlineStart: 0 }, className: STICKY } : {},
+    trail: hasEnd ? { pinned: 'right', style: { insetInlineEnd: 0 }, className: STICKY } : {},
+    tableClassName: 'table-fixed',
+    tableStyle: { width: total, minWidth: '100%' },
+  };
+}
+
+/** Under-content tint for sticky cells of a hovered or selected row (and the header surface). */
+export function stickyTint(
+  layout: CellLayout | undefined,
+  { selected = false, head = false } = {},
+): string | undefined {
+  if (!layout?.pinned) return undefined;
+  const base = 'before:pointer-events-none before:absolute before:inset-0 before:-z-10';
+  if (head) return `${base} before:bg-secondary/30`;
+  return `${base} ${selected ? 'before:bg-primary/8' : '[tr:hover>&]:before:bg-accent/30'}`;
+}

package/src/tables/DataTable/data-table-body.tsx

@@ -0,0 +1,194 @@
+import { Inbox } from '@gntik-ai/icons';
+import { cn, EmptyState, Skeleton, TableBody, TableCell, TableRow, useI18n } from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+import { columnAlign } from './data-table-utils';
+import { DataTableRow, GroupHeaderRow, type DataTableBodyGroup, type RowContext } from './data-table-row';
+import type { VirtualWindow } from './use-virtual-rows';
+
+export type { DataTableBodyGroup } from './data-table-row';
+
+export interface DataTableBodyProps<T> extends RowContext<T> {
+  rows: readonly T[];
+  loading: boolean;
+  loadingRows: number;
+  emptyState?: ReactNode;
+  /** Grouped rendering: one `<tbody>` per group with a header row (replaces `rows`). */
+  groups?: ReadonlyArray<DataTableBodyGroup<T>>;
+  /** Keys of collapsed groups. */
+  collapsedGroups?: ReadonlySet<string>;
+  /** Group headers render a collapse button (default true). */
+  collapsibleGroups?: boolean;
+  onToggleGroup?: (key: string) => void;
+  /** Selects or clears every row of a group. */
+  onToggleGroupRows?: (ids: readonly string[]) => void;
+  /** Renders only the items of this window (virtualized rows), with spacers for the rest. */
+  virtual?: VirtualWindow;
+}
+
+/** One rendered line of the body: a group header or a data row. */
+export type DataTableBodyItem<T> =
+  { kind: 'group'; group: DataTableBodyGroup<T>; open: boolean } | { kind: 'row'; row: T; groupKey?: string };
+
+/** Flattens rows (or groups and their open rows) into the lines the body renders. */
+export function flattenBody<T>(
+  rows: readonly T[],
+  groups: ReadonlyArray<DataTableBodyGroup<T>> | undefined,
+  collapsed: ReadonlySet<string> | undefined,
+): Array<DataTableBodyItem<T>> {
+  if (!groups) return rows.map((row) => ({ kind: 'row', row }));
+  const items: Array<DataTableBodyItem<T>> = [];
+  for (const group of groups) {
+    const open = !collapsed?.has(group.key);
+    items.push({ kind: 'group', group, open });
+    if (open) for (const row of group.rows) items.push({ kind: 'row', row, groupKey: group.key });
+  }
+  return items;
+}
+
+function Spacer({ height, span }: { height: number; span: number }) {
+  if (height <= 0) return null;
+  return (
+    <tbody aria-hidden data-virtual-spacer="">
+      <tr role="presentation">
+        <td colSpan={span} style={{ height, padding: 0, border: 0 }} />
+      </tr>
+    </tbody>
+  );
+}
+
+/** Body rows, plus the loading (skeleton rows) and empty (EmptyState) states. */
+export function DataTableBody<T>(props: DataTableBodyProps<T>) {
+  const {
+    rows,
+    columns,
+    selectable,
+    singleSelection,
+    selected,
+    rowActions,
+    loading,
+    loadingRows,
+    emptyState,
+    groups,
+    collapsedGroups,
+    collapsibleGroups = true,
+    onToggleGroup,
+    onToggleGroupRows,
+    virtual,
+  } = props;
+  const { t } = useI18n();
+  const selectionColumn = selectable || singleSelection != null;
+  const span = columns.length + (selectionColumn ? 1 : 0) + (rowActions ? 1 : 0);
+  if (loading) {
+    return (
+      <TableBody>
+        {Array.from({ length: loadingRows }, (_, i) => (
+          <TableRow key={`loading-${i}`}>
+            {selectionColumn && (
+              <TableCell className="w-10">
+                <Skeleton className="size-4 rounded-[4px]" />
+              </TableCell>
+            )}
+            {columns.map((c) => (
+              <TableCell key={c.id} align={columnAlign(c)}>
+                <Skeleton className={cn('h-3.5', columnAlign(c) === 'right' ? 'ms-auto w-16' : 'w-24')} />
+              </TableCell>
+            ))}
+            {rowActions && <TableCell className="w-12" />}
+          </TableRow>
+        ))}
+      </TableBody>
+    );
+  }
+  if (rows.length === 0) {
+    return (
+      <TableBody>
+        <TableRow className="hover:bg-transparent">
+          <TableCell colSpan={span} className="py-10">
+            {emptyState ?? (
+              <EmptyState
+                icon={Inbox}
+                size="sm"
+                title={t('common.noResults')}
+                description={t('table.emptyDescription')}
+              />
+            )}
+          </TableCell>
+        </TableRow>
+      </TableBody>
+    );
+  }
+  const row = (r: T, extra?: { ariaRowIndex?: number; height?: number }) => (
+    <DataTableRow
+      key={props.getRowId(r)}
+      {...props}
+      row={r}
+      ariaRowIndex={extra?.ariaRowIndex}
+      style={extra?.height ? { height: extra.height } : undefined}
+    />
+  );
+  const header = (group: DataTableBodyGroup<T>, open: boolean, extra?: { ariaRowIndex?: number; height?: number }) => (
+    <GroupHeaderRow
+      key={`group-${group.key}`}
+      group={group}
+      open={open}
+      selectable={selectable}
+      selected={selected}
+      span={span - (selectable ? 1 : 0)}
+      collapsible={collapsibleGroups}
+      onToggle={onToggleGroup}
+      onToggleRows={onToggleGroupRows}
+      ariaRowIndex={extra?.ariaRowIndex}
+      style={extra?.height ? { height: extra.height } : undefined}
+    />
+  );
+
+  if (virtual) {
+    const items = flattenBody(rows, groups, collapsedGroups);
+    const { start, end, rowHeight } = virtual;
+    // Consecutive items of the same group share a <tbody> (a rowgroup), as in the full render.
+    const chunks: Array<{ key: string; group?: string; items: Array<{ item: DataTableBodyItem<T>; index: number }> }> =
+      [];
+    for (let i = start; i < Math.min(end, items.length); i++) {
+      const item = items[i]!;
+      const g = item.kind === 'group' ? item.group.key : item.groupKey;
+      const lastChunk = chunks[chunks.length - 1];
+      if (lastChunk && lastChunk.group === g) lastChunk.items.push({ item, index: i });
+      else chunks.push({ key: `${g ?? 'rows'}-${i}`, group: g, items: [{ item, index: i }] });
+    }
+    return (
+      <>
+        <Spacer height={start * rowHeight} span={span} />
+        {chunks.map((chunk) => (
+          <TableBody key={chunk.key} data-group={chunk.group}>
+            {chunk.items.map(({ item, index }) =>
+              item.kind === 'group'
+                ? header(item.group, item.open, { ariaRowIndex: index + 2, height: rowHeight })
+                : row(item.row, { ariaRowIndex: index + 2, height: rowHeight }),
+            )}
+          </TableBody>
+        ))}
+        <Spacer height={Math.max(0, items.length - end) * rowHeight} span={span} />
+      </>
+    );
+  }
+
+  if (!groups) return <TableBody>{rows.map((r) => row(r))}</TableBody>;
+  return (
+    <>
+      {groups.map((group, gi) => {
+        const open = !collapsedGroups?.has(group.key);
+        return (
+          <TableBody
+            key={group.key}
+            data-group={group.key}
+            // Every group but the last keeps the bottom rule of its last row.
+            className={gi < groups.length - 1 ? '[&>tr:last-child>td]:border-b' : undefined}
+          >
+            {header(group, open)}
+            {open && group.rows.map((r) => row(r))}
+          </TableBody>
+        );
+      })}
+    </>
+  );
+}

package/src/tables/DataTable/data-table-props.ts

@@ -0,0 +1,156 @@
+import type { MoreMenuAction, TableDensity } from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+import type { ColumnWidths, PinnedColumns } from './column-sizing';
+import type { DataTableColumn, DataTableGroupBy, SortState } from './data-table-utils';
+import type { DataTableCellEditHandler } from './editable-cell';
+import type { DataTableView } from './views';
+
+interface DataTableCommonProps<T> {
+  rows?: readonly T[];
+  columns?: ReadonlyArray<DataTableColumn<T>>;
+  /** Stable row id (defaults to `row.id`). */
+  getRowId?: (row: T) => string;
+  /** Row name for selection and menu labels (defaults to the first column's value). */
+  getRowLabel?: (row: T) => string;
+  /** Table name (screen-reader caption unless `showCaption`). */
+  caption?: string;
+  showCaption?: boolean;
+
+  /** Row selection with a select-all header checkbox (current page). */
+  selectable?: boolean;
+  /** Native radio name in single mode. Supplied names must be unique per page. */
+  selectionName?: string;
+  selectedId?: string | null;
+  defaultSelectedId?: string | null;
+  onSelectedIdChange?: (id: string) => void;
+  isRowDisabled?: (row: T) => boolean;
+  selectedIds?: readonly string[];
+  defaultSelectedIds?: readonly string[];
+  onSelectionChange?: (ids: string[]) => void;
+  /** Rendered in the toolbar while rows are selected. */
+  bulkActions?: (selectedIds: string[]) => ReactNode;
+  /**
+   * Shows the "N selected" text in the toolbar while rows are selected (default true). Turn it
+   * off when the page renders its own count, e.g. a BulkActionBar.
+   */
+  selectionSummary?: boolean;
+
+  /** Row-actions menu items. */
+  rowActions?: (row: T) => Array<MoreMenuAction | 'separator'>;
+
+  sort?: SortState | null;
+  defaultSort?: SortState | null;
+  onSortChange?: (sort: SortState) => void;
+  /** Rows arrive sorted (server side): headers still toggle, rows are not re-sorted. */
+  manualSorting?: boolean;
+
+  defaultPageSize?: number;
+  pageSizeOptions?: readonly number[];
+
+  /** Controlled row density. */
+  density?: TableDensity;
+  /** Initial density; omitted, the table follows the surrounding DensityProvider (comfortable outside one). */
+  defaultDensity?: TableDensity;
+  onDensityChange?: (density: TableDensity) => void;
+  showDensityToggle?: boolean;
+  showColumnMenu?: boolean;
+
+  loading?: boolean;
+  loadingRows?: number;
+  emptyState?: ReactNode;
+  /**
+   * Groups rows under header rows (a field key or a function returning the group key). Groups keep
+   * the order in which their keys first appear in `rows`; sorting applies inside each group, and
+   * pagination pages through the grouped rows (each header shows the group's full count).
+   */
+  groupBy?: DataTableGroupBy<T>;
+  /** Header text of a group (default: the key, or "No group" for rows without a value). */
+  groupLabel?: (key: string, rows: readonly T[]) => ReactNode;
+  /** Group headers render a keyboard-accessible collapse button (default true). */
+  collapsibleGroups?: boolean;
+  /** Controlled collapsed group keys. */
+  collapsedGroups?: readonly string[];
+  /** Group keys collapsed initially. */
+  defaultCollapsedGroups?: readonly string[];
+  onCollapsedGroupsChange?: (keys: string[]) => void;
+
+  /** Called when a saved view switches grouping (a field key, or `null` for none). */
+  onGroupByChange?: (groupBy: string | null) => void;
+
+  /** Controlled hidden column ids (default: columns with `defaultHidden`). */
+  hiddenColumns?: readonly string[];
+  onHiddenColumnsChange?: (ids: string[]) => void;
+
+  /** Resize handles on the column headers (pointer drag, or arrow keys on the focused handle). */
+  resizable?: boolean;
+  /** Controlled column widths in px by column id. */
+  columnWidths?: ColumnWidths;
+  defaultColumnWidths?: ColumnWidths;
+  onColumnWidthsChange?: (widths: Record<string, number>) => void;
+
+  /** Controlled pinned columns (sticky at the start or end edge while scrolling sideways). */
+  pinnedColumns?: PinnedColumns;
+  defaultPinnedColumns?: PinnedColumns;
+  onPinnedColumnsChange?: (pinned: PinnedColumns) => void;
+  /** Pin / unpin from the column menu (default true when pinning is in use: a pinned prop or callback). */
+  showPinMenu?: boolean;
+
+  /**
+   * Renders only the rows in view (plus overscan) inside a scrolling body with a sticky header.
+   * `'auto'` (default) turns it on above `virtualizeThreshold` rendered rows (with pagination,
+   * the rows of the current page). The table exposes `aria-rowcount` and each row its
+   * `aria-rowindex`; selection (select-all covers every row) and grouping keep working.
+   * Limits: rows get a fixed height (`rowHeight`), so multi-line cells are clipped; a row that
+   * scrolls out of view unmounts, so focus inside it (or an open inline editor) is lost; a group's
+   * header row renders only while it is in view.
+   */
+  virtualize?: boolean | 'auto';
+  virtualizeThreshold?: number;
+  /** Row height in px for virtualization (default by density: 44 comfortable, 36 compact). */
+  rowHeight?: number;
+  /** Classes of the virtualized scroll container: its max height (default `max-h-[32rem]`). */
+  virtualContainerClassName?: string;
+
+  /**
+   * Inline editing of `editable` columns. Return nothing to accept (and update `rows`), or a
+   * message (or throw) to reject: the message is shown inline under the editor.
+   */
+  onCellEdit?: DataTableCellEditHandler<T>;
+
+  /** Saved views (controlled). Each captures filters, sort, visible columns, widths, pinning and grouping. */
+  views?: readonly DataTableView[];
+  defaultViews?: readonly DataTableView[];
+  onViewsChange?: (views: DataTableView[]) => void;
+  activeViewId?: string | null;
+  defaultActiveViewId?: string | null;
+  onActiveViewChange?: (id: string | null) => void;
+  /** Shows the view switcher (default: when views are in use). */
+  showViewSwitcher?: boolean;
+  /** Opaque filter state of the page's toolbar, saved with views. */
+  filters?: unknown;
+  /** Called when a view (or a reset) restores filters. */
+  onFiltersChange?: (filters: unknown) => void;
+
+  /** Left side of the toolbar (title, search, FilterBar…). */
+  toolbar?: ReactNode;
+  className?: string;
+}
+
+export type DataTableProps<T> = DataTableCommonProps<T> &
+  (
+    | {
+        selectionMode: 'single';
+        paginated?: false;
+        /** Consumer-supplied accessible group label; the kit adds no default. */
+        legend?: ReactNode;
+        'aria-label'?: string;
+        'aria-labelledby'?: string;
+      }
+    | {
+        selectionMode?: 'none' | 'multiple';
+        paginated?: boolean;
+        legend?: never;
+        'aria-label'?: never;
+        'aria-labelledby'?: never;
+      }
+  );