@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/tables/DataTable/header-cell.tsx

@@ -0,0 +1,90 @@
+import { ArrowDown, ArrowUp, ChevronsUpDown } from '@gntik-ai/icons';
+import { cn, nextSortDirection, TableHead, tableVariants, type SortDirection } from '@gntik-ai/ui';
+import { stickyTint, type CellLayout } from './column-sizing';
+import { columnAlign, type DataTableColumn } from './data-table-utils';
+import type { DataTableLabels } from './labels';
+import { ColumnResizeHandle } from './resize-handle';
+
+export interface DataTableHeadCellProps<T> {
+  labels?: Partial<DataTableLabels>;
+  column: DataTableColumn<T>;
+  sortDirection: SortDirection;
+  onSortChange: (direction: Exclude<SortDirection, 'none'>) => void;
+  layout?: CellLayout;
+  /** Resize handle props; omitted, the column is not resizable. */
+  resize?: { width: number; min: number; max: number; onResize: (width: number) => void };
+}
+
+/**
+ * Column header of the DataTable. Without a resize handle it is the kit TableHead; with one, the
+ * sort button and the handle sit side by side (the handle never nests inside the button).
+ */
+export function DataTableHeadCell<T>({
+  column,
+  sortDirection,
+  onSortChange,
+  layout,
+  resize,
+  labels,
+}: DataTableHeadCellProps<T>) {
+  const align = columnAlign(column);
+  const pinnedClass = layout?.pinned
+    ? cn(layout.className, 'z-[11]', stickyTint(layout, { head: true }), 'bg-card')
+    : undefined;
+  if (!resize) {
+    return (
+      <TableHead
+        align={align}
+        className={cn(column.headClassName, pinnedClass)}
+        style={layout?.style}
+        sortable={column.sortable}
+        sortDirection={sortDirection}
+        onSortChange={onSortChange}
+        data-column-id={column.id}
+      >
+        {column.header}
+      </TableHead>
+    );
+  }
+  const v = tableVariants({ align: align ?? 'left', active: sortDirection !== 'none' });
+  const SortIcon =
+    sortDirection === 'ascending' ? ArrowUp : sortDirection === 'descending' ? ArrowDown : ChevronsUpDown;
+  return (
+    <TableHead
+      align={align}
+      className={cn('relative overflow-visible', column.headClassName, pinnedClass)}
+      style={layout?.style}
+      aria-sort={column.sortable ? sortDirection : undefined}
+      data-column-id={column.id}
+    >
+      <span
+        className={cn(
+          'block min-w-0 truncate pe-2',
+          align === 'right' && 'text-end',
+          align === 'center' && 'text-center',
+        )}
+      >
+        {column.sortable ? (
+          <button
+            type="button"
+            className={cn(v.sortButton(), 'max-w-full')}
+            onClick={() => onSortChange(nextSortDirection(sortDirection))}
+          >
+            <span className="truncate">{column.header}</span>
+            <SortIcon size={13} aria-hidden className={sortDirection === 'none' ? 'opacity-40' : undefined} />
+          </button>
+        ) : (
+          column.header
+        )}
+      </span>
+      <ColumnResizeHandle
+        labels={labels}
+        label={column.header}
+        width={resize.width}
+        min={resize.min}
+        max={resize.max}
+        onResize={resize.onResize}
+      />
+    </TableHead>
+  );
+}

package/src/tables/DataTable/labels.ts

@@ -0,0 +1,54 @@
+import type { PaginationFooterLabels } from '../PaginationFooter/PaginationFooter';
+
+/** Per-instance table chrome, including the composed PaginationFooter. Caller data stays caller-owned. */
+export interface DataTableLabels extends PaginationFooterLabels {
+  /** Non-virtual table overflow region; virtualized regions keep the caller caption. */
+  scrollRegion: string;
+  selectionCount: (count: number) => string;
+  columns: string;
+  visibleColumns: string;
+  pinColumns: string;
+  pinnedLeft: string;
+  pinnedRight: string;
+  pinLeft: string;
+  pinRight: string;
+  unpinned: string;
+  density: string;
+  comfortable: string;
+  compact: string;
+  resizeColumn: (label: string) => string;
+  columnWidth: (width: number) => string;
+  defaultView: string;
+  defaultViewOption: string;
+  modified: string;
+  views: string;
+  saveChanges: string;
+  saveAs: string;
+  renameView: string;
+  deleteView: string;
+  resetChanges: string;
+  saveViewTitle: string;
+  renameViewTitle: string;
+  viewName: string;
+  cancel: string;
+  saveView: string;
+  rename: string;
+  closeDialog: string;
+  selection: string;
+  selectAll: string;
+  selectRow: (label: string) => string;
+  selectGroup: (group: string) => string;
+  groupRows: (count: number) => string;
+  noGroup: string;
+  actions: string;
+  rowActions: (label: string) => string;
+  emptyTitle: string;
+  emptyDescription: string;
+  loading: (caption: string) => string;
+  editHint: string;
+  editLabel: (column: string, row: string) => string;
+  editError: string;
+  enterNumber: string;
+  minimumValue: (min: number) => string;
+  maximumValue: (max: number) => string;
+}

package/src/tables/DataTable/resize-handle.tsx

@@ -0,0 +1,91 @@
+import { cn } from '@gntik-ai/ui';
+import { useRef, type KeyboardEvent, type PointerEvent } from 'react';
+
+import type { DataTableLabels } from './labels';
+
+export interface ColumnResizeHandleProps {
+  labels?: Partial<DataTableLabels>;
+  /** Column name for the accessible label ("Resize Region column"). */
+  label: string;
+  width: number;
+  min: number;
+  max: number;
+  onResize: (width: number) => void;
+  /** Called once a drag or a key press ends a resize. */
+  onResizeEnd?: (width: number) => void;
+}
+
+const STEP = 10;
+const BIG_STEP = 50;
+
+/**
+ * Column resize handle at the end edge of a header cell: a focusable `role="separator"` with
+ * aria-valuenow/min/max (the width in px). Drag it with a pointer; from the keyboard,
+ * ArrowLeft/ArrowRight change the width by 10px (Shift: 50px), Home/End jump to the limits.
+ */
+export function ColumnResizeHandle({ label, width, min, max, onResize, onResizeEnd, labels }: ColumnResizeHandleProps) {
+  const drag = useRef<{ x: number; width: number; dir: 1 | -1 } | null>(null);
+  const clamp = (w: number) => Math.round(Math.min(max, Math.max(min, w)));
+
+  const onPointerDown = (e: PointerEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+    const rtl = typeof getComputedStyle === 'function' && getComputedStyle(e.currentTarget).direction === 'rtl';
+    drag.current = { x: e.clientX, width, dir: rtl ? -1 : 1 };
+  };
+  const onPointerMove = (e: PointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    if (!d) return;
+    onResize(clamp(d.width + (e.clientX - d.x) * d.dir));
+  };
+  const onPointerUp = (e: PointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    drag.current = null;
+    if (d) onResizeEnd?.(clamp(d.width + (e.clientX - d.x) * d.dir));
+  };
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    const step = e.shiftKey ? BIG_STEP : STEP;
+    const rtl = typeof getComputedStyle === 'function' && getComputedStyle(e.currentTarget).direction === 'rtl';
+    const grow = rtl ? 'ArrowLeft' : 'ArrowRight';
+    const shrink = rtl ? 'ArrowRight' : 'ArrowLeft';
+    let next: number | null = null;
+    if (e.key === grow || e.key === 'ArrowUp') next = width + step;
+    else if (e.key === shrink || e.key === 'ArrowDown') next = width - step;
+    else if (e.key === 'Home') next = min;
+    else if (e.key === 'End') next = max;
+    if (next == null) return;
+    e.preventDefault();
+    const w = clamp(next);
+    onResize(w);
+    onResizeEnd?.(w);
+  };
+
+  return (
+    <div
+      role="separator"
+      tabIndex={0}
+      aria-orientation="vertical"
+      aria-label={labels?.resizeColumn?.(label) ?? `Resize ${label} column`}
+      aria-valuenow={width}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuetext={labels?.columnWidth?.(width) ?? `${width} pixels`}
+      data-column-resizer=""
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      onPointerCancel={onPointerUp}
+      onKeyDown={onKeyDown}
+      className={cn(
+        'group/resizer absolute inset-y-0 -end-1.5 z-[2] flex w-3 cursor-col-resize touch-none justify-center',
+        'focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring',
+      )}
+    >
+      <span
+        aria-hidden
+        className="my-2 w-px bg-border transition-colors group-hover/resizer:w-0.5 group-hover/resizer:bg-primary group-focus-visible/resizer:w-0.5 group-focus-visible/resizer:bg-primary motion-reduce:transition-none"
+      />
+    </div>
+  );
+}

package/src/tables/DataTable/single-selection.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useId, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+
+const mountedNames = new Map<string, number>();
+
+export interface SingleSelection<T> {
+  selectedId: string | null;
+  inputProps: (row: T) => ComponentProps<'input'>;
+  entryProps: (row: T) => ComponentProps<'span'>;
+}
+
+export function useSingleSelection<T>(options: {
+  selectionName?: string;
+  selectedId?: string | null;
+  defaultSelectedId?: string | null;
+  onSelectedIdChange?: (id: string) => void;
+  getRowId: (row: T) => string;
+  getRowLabel: (row: T) => string;
+  rows: readonly T[];
+  isRowDisabled?: (row: T) => boolean;
+}): SingleSelection<T> {
+  const generatedName = useId();
+  const [innerId, setInnerId] = useState(options.defaultSelectedId ?? null);
+  const selectedId = options.selectedId === undefined ? innerId : options.selectedId;
+  const inputs = useRef(new Map<string, HTMLInputElement>());
+  const entry = useRef<HTMLSpanElement>(null);
+  const enabledIds = options.rows.filter((row) => !options.isRowDisabled?.(row)).map(options.getRowId);
+  const tabId = selectedId != null && enabledIds.includes(selectedId) ? selectedId : enabledIds[0];
+  // Chromium excludes every unchecked same-name radio from sequential focus when
+  // a disabled radio is checked. Put the fallback tab stop beside the first
+  // enabled radio so other table controls retain their normal Tab order.
+  const redirectEntry =
+    tabId !== undefined &&
+    options.rows.some((row) => options.getRowId(row) === selectedId && options.isRowDisabled?.(row));
+  const select = (id: string) => {
+    if (id === selectedId) return;
+    setInnerId(id);
+    options.onSelectedIdChange?.(id);
+  };
+  return {
+    selectedId,
+    entryProps: (row) =>
+      redirectEntry && options.getRowId(row) === tabId
+        ? {
+            ref: entry,
+            tabIndex: 0,
+            onFocus: (event) => {
+              if (event.target === event.currentTarget && tabId !== undefined)
+                inputs.current.get(tabId)?.focus({ preventScroll: true });
+            },
+            onPointerDown: (event) => {
+              // Only keyboard entry redirects focus; clicking the wrapper's blank
+              // space must not focus it or interfere with native radio clicks.
+              if (event.target === event.currentTarget) event.preventDefault();
+            },
+            onBlur: (event) => {
+              if (!event.currentTarget.contains(event.relatedTarget)) event.currentTarget.tabIndex = 0;
+            },
+          }
+        : {},
+    inputProps: (row) => {
+      const id = options.getRowId(row);
+      const disabled = options.isRowDisabled?.(row) ?? false;
+      return {
+        type: 'radio',
+        name: options.selectionName ?? generatedName,
+        'aria-label': options.getRowLabel(row),
+        checked: selectedId === id,
+        disabled,
+        tabIndex: !disabled && id === tabId ? 0 : -1,
+        ref: (input) => {
+          if (input) inputs.current.set(id, input);
+          else inputs.current.delete(id);
+        },
+        onChange: () => {
+          if (!disabled) select(id);
+        },
+        onKeyDown: (event) => {
+          // Avoid a second stop on the entry wrapper when leaving its radio.
+          // Its blur handler restores keyboard entry after focus has left.
+          if (event.key === 'Tab' && entry.current) entry.current.tabIndex = -1;
+          const direction = { ArrowDown: 1, ArrowRight: 1, ArrowUp: -1, ArrowLeft: -1 }[event.key];
+          if (direction == null || disabled || enabledIds.length === 0) return;
+          event.preventDefault();
+          const index = enabledIds.indexOf(id);
+          const nextId = enabledIds[(index + direction + enabledIds.length) % enabledIds.length]!;
+          inputs.current.get(nextId)?.focus();
+          select(nextId);
+        },
+      };
+    },
+  };
+}
+
+export function useSingleSelectionWarnings({
+  single,
+  selectionName,
+  paginated,
+  hasLabel,
+}: {
+  single: boolean;
+  selectionName?: string;
+  paginated?: boolean;
+  hasLabel: boolean;
+}) {
+  useEffect(() => {
+    if (single && paginated === true && process.env.NODE_ENV === 'development') {
+      console.warn('DataTable single selection: paginated=true is unsupported; rendering all rows without pagination.');
+    }
+  }, [single, paginated]);
+  useEffect(() => {
+    if (!single || process.env.NODE_ENV !== 'development') return;
+    if (!hasLabel) console.warn('DataTable single selection: supply legend, aria-label or aria-labelledby.');
+  }, [single, hasLabel]);
+  useEffect(() => {
+    if (!single || selectionName === undefined || process.env.NODE_ENV !== 'development') return;
+    const count = mountedNames.get(selectionName) ?? 0;
+    if (count > 0)
+      console.warn(
+        `DataTable single selection: duplicate selectionName "${selectionName}"; supplied names must be unique per page.`,
+      );
+    mountedNames.set(selectionName, count + 1);
+    return () => {
+      const remaining = (mountedNames.get(selectionName) ?? 1) - 1;
+      if (remaining === 0) mountedNames.delete(selectionName);
+      else mountedNames.set(selectionName, remaining);
+    };
+  }, [single, selectionName]);
+}
+
+export function SelectionGroup({
+  single,
+  legend,
+  children,
+  ...label
+}: {
+  single: boolean;
+  legend?: ReactNode;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  children: ReactNode;
+}) {
+  if (!single) return <>{children}</>;
+  return (
+    <fieldset className="m-0 min-w-0 border-0 p-0" {...label}>
+      {legend != null && <legend className="px-3 py-2 text-sm font-medium text-foreground">{legend}</legend>}
+      {children}
+    </fieldset>
+  );
+}

package/src/tables/DataTable/use-table-views.ts

@@ -0,0 +1,79 @@
+import { useState } from 'react';
+import { newViewId, sameViewState, type DataTableView, type DataTableViewState } from './views';
+
+/** A value that is controlled when `value` is defined, otherwise kept in state. */
+export function useControllable<V>(
+  value: V | undefined,
+  initial: V | (() => V),
+  onChange?: (next: V) => void,
+): [V, (next: V) => void] {
+  const [inner, setInner] = useState<V>(initial);
+  const current = value === undefined ? inner : value;
+  const set = (next: V) => {
+    setInner(next);
+    onChange?.(next);
+  };
+  return [current, set];
+}
+
+export interface UseTableViewsOptions {
+  views?: readonly DataTableView[];
+  defaultViews?: readonly DataTableView[];
+  onViewsChange?: (views: DataTableView[]) => void;
+  activeViewId?: string | null;
+  defaultActiveViewId?: string | null;
+  onActiveViewChange?: (id: string | null) => void;
+  /** The table's state right now. */
+  current: DataTableViewState;
+  /** The table's state with no view applied (props' defaults). */
+  defaults: DataTableViewState;
+  /** Applies a complete state to the table. */
+  apply: (state: DataTableViewState) => void;
+}
+
+/** Saved-views state machine for the DataTable: select, save as, save, rename, delete, reset. */
+export function useTableViews({
+  views: viewsProp,
+  defaultViews = [],
+  onViewsChange,
+  activeViewId,
+  defaultActiveViewId = null,
+  onActiveViewChange,
+  current,
+  defaults,
+  apply,
+}: UseTableViewsOptions) {
+  const [views, setViews] = useControllable<readonly DataTableView[]>(viewsProp, defaultViews, (next) =>
+    onViewsChange?.([...next]),
+  );
+  const [activeId, setActiveId] = useControllable<string | null>(activeViewId, defaultActiveViewId, onActiveViewChange);
+  const active = views.find((v) => v.id === activeId) ?? null;
+  const target = (view: DataTableView | null): DataTableViewState => ({ ...defaults, ...(view?.state ?? {}) });
+  const dirty = !sameViewState(current, target(active));
+
+  return {
+    views,
+    activeId: active ? active.id : null,
+    dirty,
+    select: (id: string | null) => {
+      const view = views.find((v) => v.id === id) ?? null;
+      setActiveId(view ? view.id : null);
+      apply(target(view));
+    },
+    saveAs: (name: string) => {
+      const view: DataTableView = { id: newViewId(name, views), name, state: current };
+      setViews([...views, view]);
+      setActiveId(view.id);
+    },
+    save: () => {
+      if (!active) return;
+      setViews(views.map((v) => (v.id === active.id ? { ...v, state: current } : v)));
+    },
+    rename: (id: string, name: string) => setViews(views.map((v) => (v.id === id ? { ...v, name } : v))),
+    remove: (id: string) => {
+      setViews(views.filter((v) => v.id !== id));
+      if (id === activeId) setActiveId(null);
+    },
+    reset: () => apply(target(active)),
+  };
+}

package/src/tables/DataTable/use-virtual-rows.ts

@@ -0,0 +1,83 @@
+import { useEffect, useState, type RefObject } from 'react';
+
+/** The items to render: `[start, end)` of the flattened body, each `rowHeight` px tall. */
+export interface VirtualWindow {
+  start: number;
+  end: number;
+  rowHeight: number;
+}
+
+export interface UseVirtualRowsOptions {
+  enabled: boolean;
+  count: number;
+  rowHeight: number;
+  /** The `<table>`; its parent is the scroll container. */
+  tableRef: RefObject<HTMLTableElement | null>;
+  /** Fallback viewport height before the container is measured (and in jsdom). */
+  viewportHeight: number;
+  /** Extra rows rendered above and below the viewport. */
+  overscan?: number;
+}
+
+/** Computes a virtual window from the table container's scroll position. */
+export function windowFor(
+  count: number,
+  scrollTop: number,
+  viewport: number,
+  rowHeight: number,
+  overscan: number,
+): VirtualWindow {
+  const h = Math.max(1, rowHeight);
+  const first = Math.floor(Math.max(0, scrollTop) / h);
+  const visible = Math.ceil(viewport / h) + 1;
+  const start = Math.max(0, Math.min(count, first - overscan));
+  const end = Math.max(start, Math.min(count, first + visible + overscan));
+  return { start, end, rowHeight: h };
+}
+
+/**
+ * Row virtualization for the DataTable: listens to the scroll container of the table and returns
+ * the window of items to render, or `undefined` when disabled.
+ */
+export function useVirtualRows({
+  enabled,
+  count,
+  rowHeight,
+  tableRef,
+  viewportHeight,
+  overscan = 8,
+}: UseVirtualRowsOptions): VirtualWindow | undefined {
+  const [scroll, setScroll] = useState({ top: 0, height: viewportHeight });
+
+  useEffect(() => {
+    const el = tableRef.current?.parentElement;
+    if (!enabled || !el) return undefined;
+    let frame = 0;
+    const read = () => {
+      frame = 0;
+      setScroll((prev) => {
+        const height = el.clientHeight || prev.height;
+        return prev.top === el.scrollTop && prev.height === height ? prev : { top: el.scrollTop, height };
+      });
+    };
+    const schedule = () => {
+      if (frame) return;
+      frame =
+        typeof requestAnimationFrame === 'function'
+          ? requestAnimationFrame(read)
+          : (setTimeout(read, 0) as unknown as number);
+    };
+    el.addEventListener('scroll', schedule, { passive: true });
+    const ro = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
+    ro?.observe(el);
+    schedule();
+    return () => {
+      el.removeEventListener('scroll', schedule);
+      ro?.disconnect();
+      if (frame && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(frame);
+    };
+  }, [enabled, tableRef]);
+
+  if (!enabled) return undefined;
+  return windowFor(count, scroll.top, scroll.height, rowHeight, overscan);
+}