@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/DataTable/columnShift.ts

@@ -0,0 +1,117 @@
+/**
+ * Pure geometry for the whole-column drag preview. No DOM access — everything
+ * here is a plain function so the maths can be unit-tested without rendering
+ * a table or simulating a pointer.
+ */
+
+/** Inputs describing one frame of an in-progress column drag. */
+export interface ColumnShiftArgs {
+  /**
+   * ALL unpinned column ids in their current visual order — including columns
+   * with `enableReorder: false`. A non-reorderable column still occupies space
+   * and is still displaced when a reorderable column is dragged past it, so
+   * omitting it makes the preview overlap two columns.
+   */
+  orderedIds: string[];
+  /** Id of the column being dragged. */
+  activeId: string;
+  /** Id of the column currently hovered, or `null` when over nothing. */
+  overId: string | null;
+  /** Rendered width per column id, in px. */
+  widths: Record<string, number>;
+  /** Pointer delta on the x axis since drag start, in px. */
+  deltaX: number;
+}
+
+/**
+ * Translation in px for each column that moves this frame, keyed by column id.
+ * Columns absent from the result do not move — callers treat a missing key as
+ * `0` rather than writing an explicit zero for every untouched column.
+ *
+ * The active column follows the pointer; every column between its origin and
+ * the hovered column slides one active-column-width in the opposite direction,
+ * opening the gap the active column will drop into.
+ */
+export function computeColumnShifts({
+  orderedIds,
+  activeId,
+  overId,
+  widths,
+  deltaX,
+}: ColumnShiftArgs): Record<string, number> {
+  const shifts: Record<string, number> = {};
+
+  const from = orderedIds.indexOf(activeId);
+  if (from === -1) return shifts;
+
+  shifts[activeId] = deltaX;
+
+  if (overId == null || overId === activeId) return shifts;
+  const to = orderedIds.indexOf(overId);
+  if (to === -1) return shifts;
+
+  // A missing width means the column has no tracked size yet; shifting by 0 is
+  // wrong-but-harmless, whereas NaN would poison the CSS value.
+  const activeWidth = widths[activeId] ?? 0;
+
+  if (to > from) {
+    // Active column travels right: everything it passed slides left to fill in.
+    for (let i = from + 1; i <= to; i++) shifts[orderedIds[i]] = -activeWidth;
+  } else {
+    // Active column travels left: everything it passed slides right.
+    for (let i = to; i < from; i++) shifts[orderedIds[i]] = activeWidth;
+  }
+
+  return shifts;
+}
+
+/**
+ * How far the active column may travel left and right, in px, relative to
+ * where it started. Produced by `measureDragRangeX` in `useColumnDragShift`
+ * from real header rects — NOT from declared column widths, which understate
+ * the rendered ones whenever the table stretches to fill its scroll wrap.
+ */
+export interface DragRangeX {
+  /**
+   * Lower bound for the x translation, in px. Non-positive under normal
+   * left-to-right layout, where the first slot sits at or left of the active
+   * column's own position.
+   */
+  min: number;
+  /**
+   * Upper bound for the x translation, in px. Non-negative under normal
+   * left-to-right layout, where the last slot sits at or right of the active
+   * column's own position.
+   */
+  max: number;
+}
+
+/** Clamp an x translation into `range`. */
+export function clampX(x: number, range: DragRangeX): number {
+  return Math.min(range.max, Math.max(range.min, x));
+}
+
+/**
+ * Turn an arbitrary column id into a fragment that is legal inside a CSS
+ * custom-property name. Column ids are consumer-supplied and routinely contain
+ * dots, spaces, or non-ASCII text, none of which are safe to interpolate.
+ *
+ * Sanitizing alone would collide (`a.b` and `a b` both become `a_b`), so a
+ * stable hash of the original id is appended.
+ */
+export function cssIdent(columnId: string): string {
+  const safe = columnId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  // Java String.hashCode-style rolling hash (×31) — deterministic, no crypto
+  // needed, collisions are
+  // vanishingly unlikely across one table's column set.
+  let hash = 0;
+  for (let i = 0; i < columnId.length; i++) {
+    hash = (hash * 31 + columnId.charCodeAt(i)) | 0;
+  }
+  return `${safe}-${(hash >>> 0).toString(36)}`;
+}
+
+/** Full custom-property name carrying a column's current drag offset. */
+export function shiftVarName(columnId: string): string {
+  return `--dt-shift-${cssIdent(columnId)}`;
+}

package/src/components/DataTable/index.ts

@@ -0,0 +1,23 @@
+export { DataTable } from './DataTable';
+export type { DataTableProps } from './DataTable';
+
+export { useDataTable } from './useDataTable';
+export { ColumnVisibilityTrigger } from './ColumnVisibilityTrigger';
+export type { ColumnVisibilityTriggerProps } from './ColumnVisibilityTrigger';
+
+export type {
+  ColumnDef,
+  ColumnAlign,
+  ColumnOrderState,
+  ColumnSizingState,
+  ColumnVisibilityState,
+  ColumnPinningState,
+  RowSelectionState,
+  ExpandedRowsState,
+  SortState,
+  Updater,
+  HeaderContext,
+  CellContext,
+  UseDataTableOptions,
+  DataTableInstance,
+} from './types';

package/src/components/DataTable/pinStyle.ts

@@ -0,0 +1,47 @@
+import type { DataTableInstance } from './types';
+
+/**
+ * Width of the auto-prepended selection cell. Kept here as the single source
+ * of truth so DataTable.tsx and pinStyle.ts agree on the offset shift.
+ */
+export const AUTO_CELL_WIDTH = 44;
+
+export interface PinStyle {
+  position?: 'sticky';
+  left?: number;
+  right?: number;
+  pinSide?: 'left' | 'right';
+}
+
+/**
+ * Compute the sticky-positioning inline style for a column cell.
+ *
+ * - Unpinned columns return an empty object (no sticky styles).
+ * - Left-pinned columns return `{ position: 'sticky', left: <px>, pinSide: 'left' }`.
+ *   The `left` value is the column's cumulative offset from the hook
+ *   (`instance.leftPinOffsets[columnId]`), shifted by one `AUTO_CELL_WIDTH`
+ *   per active auto-cell on the left: `enableRowSelection` and
+ *   `hasExpansion` each contribute when true.
+ * - Right-pinned columns return `{ position: 'sticky', right: <px>, pinSide: 'right' }`.
+ *   No auto-cell shift on the right (selection + expand cells both live on the left).
+ */
+export function getPinStyle<T>(columnId: string, instance: DataTableInstance<T>): PinStyle {
+  const leftPinned = instance.columnPinning.left.includes(columnId);
+  const rightPinned = instance.columnPinning.right.includes(columnId);
+
+  if (leftPinned) {
+    const offset = instance.leftPinOffsets[columnId] ?? 0;
+    // Each auto-cell on the left contributes AUTO_CELL_WIDTH to the
+    // sticky-left offset of the first data column. In sliding order:
+    //   [ select? ][ expand? ][ left-pinned data... ]
+    const shift =
+      (instance.enableRowSelection ? AUTO_CELL_WIDTH : 0) +
+      (instance.hasExpansion ? AUTO_CELL_WIDTH : 0);
+    return { position: 'sticky', left: offset + shift, pinSide: 'left' };
+  }
+  if (rightPinned) {
+    const offset = instance.rightPinOffsets[columnId] ?? 0;
+    return { position: 'sticky', right: offset, pinSide: 'right' };
+  }
+  return {};
+}

package/src/components/DataTable/reorderColumns.ts

@@ -0,0 +1,66 @@
+import type { ColumnOrderState, ColumnPinningState } from './types';
+
+/**
+ * True when both columns are on the same pin "side": both unpinned, both
+ * left-pinned, or both right-pinned. Used to reject cross-pin-boundary drag
+ * drops. A column can be pinned to at most one side; if data is malformed
+ * (in both lists), the function treats it as left-pinned (left checked first).
+ */
+export function sameSide(a: string, b: string, pinning: ColumnPinningState): boolean {
+  const aSide = pinning.left.includes(a)
+    ? 'left'
+    : pinning.right.includes(a)
+      ? 'right'
+      : 'unpinned';
+  const bSide = pinning.left.includes(b)
+    ? 'left'
+    : pinning.right.includes(b)
+      ? 'right'
+      : 'unpinned';
+  return aSide === bSide;
+}
+
+export interface ReorderArgs {
+  prev: ColumnOrderState;
+  activeId: string;
+  overId: string;
+  visibleIds: string[];
+  pinning: ColumnPinningState;
+}
+
+/**
+ * Reorder columns within their pin side. Returns the new `ColumnOrderState`,
+ * or `null` if the move should be rejected:
+ *
+ * - active and over are not on the same pin side (cross-boundary drag)
+ * - active === over (no-op)
+ * - active or over not found in `prev`
+ *
+ * The reorder operates on the visible-column slice and then re-slots the
+ * reordered ids back into `prev` at the same absolute positions, so hidden
+ * columns retain their positions in `columnOrder`. (Same algorithm as Phase 1's
+ * inline reorder; just adds the same-side check.)
+ */
+export function reorderRespectingPins(args: ReorderArgs): ColumnOrderState | null {
+  const { prev, activeId, overId, visibleIds, pinning } = args;
+  if (activeId === overId) return null;
+  if (!prev.includes(activeId) || !prev.includes(overId)) return null;
+  if (!sameSide(activeId, overId, pinning)) return null;
+
+  const visible = prev.filter((id) => visibleIds.includes(id));
+  const fromIdx = visible.indexOf(activeId);
+  const toIdx = visible.indexOf(overId);
+  if (fromIdx === -1 || toIdx === -1) return null;
+
+  const reorderedVisible = [...visible];
+  const [moved] = reorderedVisible.splice(fromIdx, 1);
+  reorderedVisible.splice(toIdx, 0, moved!);
+
+  let cursor = 0;
+  return prev.map((id) => {
+    if (visibleIds.includes(id)) {
+      return reorderedVisible[cursor++]!;
+    }
+    return id;
+  });
+}

package/src/components/DataTable/types.ts

@@ -0,0 +1,289 @@
+import type { ReactNode, MouseEvent as ReactMouseEvent } from 'react';
+
+/** Cell / header text alignment. */
+export type ColumnAlign = 'start' | 'center' | 'end';
+
+/** Single-column sort state. v1 is single-column only; multi-column is a future extension. */
+export interface SortState {
+  columnId: string;
+  direction: 'asc' | 'desc';
+}
+
+/** Ordered list of column ids (includes hidden columns at their absolute positions). */
+export type ColumnOrderState = string[];
+
+/** Map column id → resolved width in px. Missing entries fall back to `ColumnDef.size` or the default (120). */
+export type ColumnSizingState = Record<string, number>;
+
+/** Map column id → visible flag. Missing entries are treated as `true` (visible). */
+export type ColumnVisibilityState = Record<string, boolean>;
+
+/**
+ * Ordered pin lists per side. Phase 1 plumbs this state but does not render
+ * the sticky CSS — rendering effects ship in Phase 2.
+ */
+export interface ColumnPinningState {
+  left: string[];
+  right: string[];
+}
+
+/** Map row id → selected flag. Missing entries treated as `false`. */
+export type RowSelectionState = Record<string, boolean>;
+
+/** Map row id → expanded flag. Phase 1 plumbs state; rendering ships in Phase 3. */
+export type ExpandedRowsState = Record<string, boolean>;
+
+/** setState-style updater: either the next value, or a function (prev) => next. */
+export type Updater<S> = S | ((prev: S) => S);
+
+/** Header render-prop context. */
+export interface HeaderContext<T = unknown> {
+  column: ColumnDef<T>;
+  instance: DataTableInstance<T>;
+}
+
+/** Cell render-prop context. */
+export interface CellContext<T> {
+  row: T;
+  rowId: string;
+  column: ColumnDef<T>;
+  instance: DataTableInstance<T>;
+}
+
+/** Descriptor for one column. Keyed by `id` — used as the key for all per-column state. */
+export interface ColumnDef<T> {
+  /** Stable id. Used as key for column order, sizing, visibility, pinning state. */
+  id: string;
+  /** Header content. String, node, or a render-prop receiving HeaderContext. */
+  header: ReactNode | ((ctx: HeaderContext<T>) => ReactNode);
+  /** Cell content for a row. */
+  cell: (row: T, ctx: CellContext<T>) => ReactNode;
+  /** Cell text alignment. Defaults to 'start'. */
+  align?: ColumnAlign;
+  /** Default width in px when no entry in ColumnSizingState. Defaults to 120. */
+  size?: number;
+  /** Min width during resize (px). Defaults to 40. */
+  minSize?: number;
+  /** Max width during resize (px). Defaults to undefined (no max). */
+  maxSize?: number;
+  /** Whether the column can be reordered via drag. Defaults true. */
+  enableReorder?: boolean;
+  /** Whether the column can be resized via the handle. Defaults true. */
+  enableResize?: boolean;
+  /** Whether the column can be hidden via the visibility menu. Defaults true. */
+  enableHide?: boolean;
+  /** Whether the column can be pinned. Defaults true. (Phase 2 will use this.) */
+  enablePin?: boolean;
+  /**
+   * Server-side sortable. When true, the header label is clickable and
+   * keyboard-actionable; toggling fires onSortChange. DataTable does
+   * not perform client-side sorting.
+   */
+  sortable?: boolean;
+  /**
+   * Plain-text column label. Used by the visibility menu and, when
+   * `DataTable.collapseBelow` is set, by the visual card-field label and resize
+   * separator name. Falls back to a string `header`; card fields with neither
+   * stay visually unlabelled, and the visibility menu falls back to `id` —
+   * that menu is the one place a column's raw id can still reach a user.
+   * Resize separators do NOT: they take a generic "Resize this column".
+   *
+   * It also NAMES the column header, but only when `header` is not a
+   * text-rendering string — i.e. a ReactNode, a render function, or `''`. So
+   * `<span>Rev</span>` with `visibilityLabel: "Revenue (USD)"` announces
+   * "Revenue (USD)", NOT "Rev". A string header always names itself and this
+   * never overrides it.
+   *
+   * That override is deliberate. Deciding at runtime whether a ReactNode names
+   * itself needs the accessible name, and seven attempts to approximate that
+   * from the DOM each shipped either a raw `column.id` in the announcement or
+   * an unnamed column header. The rule is static instead, and the cost is that
+   * a node which DOES name itself is overridden when you also set this.
+   *
+   * Set it on every non-text header. Without it the component will not invent
+   * a name: `column.id` is the only candidate left and a developer identifier
+   * is not something to read aloud, so it is used for nothing — not the
+   * header, not the drag grip, not the resize handle.
+   *
+   * What such a header announces, measured off Chromium's AX tree: it falls
+   * through to NAME-FROM-CONTENT, because an `aria-labelledby` resolving to no
+   * text is marked invalid rather than treated as a name. So the cell's own
+   * controls name it — "Drag to reorder this column", or under `collapseBelow`
+   * the resize handle's live pixel width. `header: ''` is special-cased to a
+   * generic label so the width cannot win; a ReactNode that renders nothing is
+   * indistinguishable from one that names itself, so it is not.
+   *
+   * None of those is a name you chose. Set this prop on every text-less
+   * header; your axe run flags what is left via `empty-table-header`.
+   *
+   * An EMPTY string counts as unset, not as an explicit name, in ALL THREE
+   * places that read this prop — the column header (`HeaderCell`), the
+   * responsive card's field label (`BodyRow`) and the visibility menu row
+   * (`ColumnVisibilityTrigger`). Each falls back to a string `header` rather
+   * than discarding it, and the menu falls on past that to `id`. #534
+   * converted only the first, which left one prop meaning "unset" in the
+   * header and "render nothing" two files over; #536 made them agree.
+   *
+   * There is deliberately no way to blank a column's label with `''`. The menu
+   * row is the case that decides it: a blank checkbox row is unidentifiable,
+   * which is strictly worse than the raw `id` the fallback chain already
+   * treats as a last resort.
+   *
+   * A WHITESPACE-ONLY `header` is treated the same way, in all three, for the
+   * same reason: `'   '` renders no text, so it is not a label. Only the menu
+   * trimmed at first, which left the sentence above true of `''` but not of
+   * `'   '`.
+   */
+  visibilityLabel?: string;
+  /**
+   * Initial pin side for this column. Used as the derived default for
+   * `columnPinning` when the consumer doesn't pass `columnPinning` or
+   * `defaultColumnPinning`. Lower-precedence than either — explicit
+   * `defaultColumnPinning` on the hook always wins.
+   *
+   * Runtime pinning (e.g. `instance.pinColumn(id, 'right')`) updates the
+   * `columnPinning` state and takes over from this initial value.
+   */
+  pin?: 'left' | 'right';
+}
+
+/** Public options to `useDataTable<T>(...)`. */
+export interface UseDataTableOptions<T> {
+  // pure data
+  data: T[];
+  pinnedRows?: T[];
+  columns: ColumnDef<T>[];
+  /** Required. Stable id per row — used by selection, expansion, and `getRowId`. */
+  getRowId: (row: T) => string;
+  /** Total server-side row count. Surfaced as `aria-rowcount` for screen readers. */
+  rowCount?: number;
+  /** Opt-in to the selection auto-column. Defaults false. */
+  enableRowSelection?: boolean;
+
+  // each state piece: controlled / default / onChange (Radix pattern)
+
+  /** Controlled column order. Pass with `onColumnOrderChange` to manage state externally. */
+  columnOrder?: ColumnOrderState;
+  /** Initial column order when uncontrolled. Defaults to `columns.map(c => c.id)`. */
+  defaultColumnOrder?: ColumnOrderState;
+  /** Fires when the order changes (drag-reorder or programmatic set). */
+  onColumnOrderChange?: (next: ColumnOrderState) => void;
+
+  /** Controlled column sizing map (column id → width in px). Pass with `onColumnSizingChange`. */
+  columnSizing?: ColumnSizingState;
+  /** Initial column sizing when uncontrolled. Missing entries fall back to `ColumnDef.size` or 120px. */
+  defaultColumnSizing?: ColumnSizingState;
+  /** Fires when any column is resized. */
+  onColumnSizingChange?: (next: ColumnSizingState) => void;
+
+  /** Controlled column visibility map (column id → visible flag). Pass with `onColumnVisibilityChange`. */
+  columnVisibility?: ColumnVisibilityState;
+  /** Initial column visibility when uncontrolled. Missing entries are treated as visible. */
+  defaultColumnVisibility?: ColumnVisibilityState;
+  /** Fires when column visibility toggles (e.g. via `<ColumnVisibilityTrigger>`). */
+  onColumnVisibilityChange?: (next: ColumnVisibilityState) => void;
+
+  /**
+   * Controlled column pinning state. Pass with `onColumnPinningChange`.
+   * Note: Phase 1 plumbs this state — sticky rendering ships in Phase 2.
+   */
+  columnPinning?: ColumnPinningState;
+  /**
+   * Initial column pinning when uncontrolled. Defaults to `{ left: [], right: [] }`.
+   * Note: Phase 1 plumbs this state — sticky rendering ships in Phase 2.
+   */
+  defaultColumnPinning?: ColumnPinningState;
+  /** Fires when a column is pinned or unpinned. */
+  onColumnPinningChange?: (next: ColumnPinningState) => void;
+
+  /** Controlled row selection map (row id → selected flag). Pass with `onRowSelectionChange`. */
+  rowSelection?: RowSelectionState;
+  /** Initial row selection when uncontrolled. Defaults to `{}` (nothing selected). */
+  defaultRowSelection?: RowSelectionState;
+  /** Fires when any row selection changes (per-row toggle or select-all). */
+  onRowSelectionChange?: (next: RowSelectionState) => void;
+
+  /**
+   * Controlled expanded-rows map (row id → expanded flag). Pass with `onExpandedRowsChange`.
+   * Note: Phase 1 plumbs this state — expansion rendering ships in Phase 3.
+   */
+  expandedRows?: ExpandedRowsState;
+  /**
+   * Initial expanded rows when uncontrolled. Defaults to `{}` (all collapsed).
+   * Note: Phase 1 plumbs this state — expansion rendering ships in Phase 3.
+   */
+  defaultExpandedRows?: ExpandedRowsState;
+  /** Fires when a row is expanded or collapsed. */
+  onExpandedRowsChange?: (next: ExpandedRowsState) => void;
+
+  /** Controlled single-column sort state. Pass with `onSortChange` for server-driven sorting. */
+  sort?: SortState | null;
+  /** Initial sort when uncontrolled. Defaults to `null` (unsorted). */
+  defaultSort?: SortState | null;
+  /** Fires when the sort state changes (column header click cycles null → asc → desc → null). */
+  onSortChange?: (next: SortState | null) => void;
+
+  // interactivity
+  onRowClick?: (row: T, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  /** Phase 1 plumbs this prop but does not render expansion. Rendering ships in Phase 3. */
+  renderExpandedRow?: (row: T) => ReactNode;
+}
+
+/** Returned by `useDataTable<T>(...)`. Passed into `<DataTable instance={...} />`. */
+export interface DataTableInstance<T> {
+  // echoed inputs
+  data: T[];
+  pinnedRows: T[];
+  columns: ColumnDef<T>[];
+  getRowId: (row: T) => string;
+  rowCount?: number;
+  enableRowSelection: boolean;
+  hasExpansion: boolean;
+  onRowClick?: UseDataTableOptions<T>['onRowClick'];
+  renderExpandedRow?: UseDataTableOptions<T>['renderExpandedRow'];
+
+  // resolved current state
+  columnOrder: ColumnOrderState;
+  columnSizing: ColumnSizingState;
+  columnVisibility: ColumnVisibilityState;
+  columnPinning: ColumnPinningState;
+  rowSelection: RowSelectionState;
+  expandedRows: ExpandedRowsState;
+  sort: SortState | null;
+
+  // derived view-models (memoized)
+  visibleColumns: ColumnDef<T>[];
+  leftPinnedColumns: ColumnDef<T>[];
+  rightPinnedColumns: ColumnDef<T>[];
+  unpinnedColumns: ColumnDef<T>[];
+  columnSizesPx: Record<string, number>;
+  leftPinOffsets: Record<string, number>;
+  rightPinOffsets: Record<string, number>;
+
+  // setState-style mutators
+  setColumnOrder: (updater: Updater<ColumnOrderState>) => void;
+  setColumnSizing: (updater: Updater<ColumnSizingState>) => void;
+  setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void;
+  setColumnPinning: (updater: Updater<ColumnPinningState>) => void;
+  setRowSelection: (updater: Updater<RowSelectionState>) => void;
+  setExpandedRows: (updater: Updater<ExpandedRowsState>) => void;
+  setSort: (updater: Updater<SortState | null>) => void;
+
+  // higher-level helpers
+  /** Toggle selection of a single row by id. */
+  toggleRowSelection: (rowId: string) => void;
+  /** Toggle selection of all rows in `data` (does not affect `pinnedRows`). */
+  toggleAllOnPage: () => void;
+  /** All rows in `data` are selected (excludes `pinnedRows`). */
+  isAllOnPageSelected: () => boolean;
+  /** Some but not all rows in `data` are selected — drives the header checkbox indeterminate state. */
+  isSomeOnPageSelected: () => boolean;
+  /** Toggle expansion of a single row by id. */
+  toggleRowExpanded: (rowId: string) => void;
+  /** Toggle visibility of a column by id. Guarded against hiding the last visible hidable column when called via `<ColumnVisibilityTrigger>`. */
+  toggleColumnVisibility: (columnId: string) => void;
+  /** Pin a column to `left`, `right`, or `false` to unpin. Pinning order within a side is append-on-pin. */
+  pinColumn: (columnId: string, side: 'left' | 'right' | false) => void;
+  /** Cycle sort state for a column: null → asc → desc → null. */
+  toggleSort: (columnId: string) => void;
+}