@gntik-ai/blocks 0.0.0-stage → 0.5.0

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

@@ -0,0 +1,274 @@
+import { cn, Input } from '@gntik-ai/ui';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type FocusEvent,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import type { DataTableColumn } from './data-table-utils';
+
+/** One committed cell edit, as `onCellEdit` receives it. */
+export interface DataTableCellEdit<T> {
+  row: T;
+  rowId: string;
+  columnId: string;
+  /** Parsed value: a string (text, select) or a number / null (number editor). */
+  value: string | number | null;
+  /** Value the editor started from. */
+  previous: string | number | null;
+}
+
+/**
+ * Result of `onCellEdit`: nothing or `true` accepts the edit (the parent updates `rows`); a string
+ * rejects it and is shown inline as the error; `false` rejects with a generic message. A thrown
+ * error (or a rejected promise) rejects with its message.
+ */
+export type DataTableCellEditResult = void | boolean | string;
+
+export type DataTableCellEditHandler<T> = (
+  edit: DataTableCellEdit<T>,
+) => DataTableCellEditResult | Promise<DataTableCellEditResult>;
+
+export interface EditableCellProps<T> {
+  row: T;
+  rowId: string;
+  rowLabel: string;
+  column: DataTableColumn<T>;
+  onCellEdit: DataTableCellEditHandler<T>;
+  /** Id of the shared "Press Enter or F2 to edit" hint. */
+  hintId: string;
+  /** The cell's display content. */
+  children: ReactNode;
+}
+
+const GENERIC_ERROR = 'The change could not be saved.';
+type Move = 'self' | 'next' | 'prev' | null;
+
+/** Starting value of the editor for a row. */
+function startValue<T>(row: T, column: DataTableColumn<T>): string | number | null {
+  const raw = column.editValue ? column.editValue(row) : column.accessor?.(row);
+  if (raw == null) return null;
+  if (typeof raw === 'number' || typeof raw === 'string') return raw;
+  if (raw instanceof Date) return raw.toISOString();
+  return String(raw);
+}
+
+/** Focuses the next or previous editable cell of the table (Tab / Shift+Tab while editing). */
+function focusSibling(from: HTMLElement | null, dir: 'next' | 'prev') {
+  const table = from?.closest('table');
+  if (!table || !from) return;
+  const all = [...table.querySelectorAll<HTMLElement>('[data-cell-edit-trigger]')];
+  const i = all.indexOf(from);
+  const target = all[dir === 'next' ? i + 1 : i - 1];
+  (target ?? from).focus();
+}
+
+/**
+ * An editable body cell's content. At rest it is a button showing the value (Enter, F2 or a click
+ * edits); while editing, an input or a select: Enter or Tab commits, Escape cancels. `onCellEdit`
+ * can reject the value with a message, shown inline under the editor.
+ */
+export function EditableCell<T>({ row, rowId, rowLabel, column, onCellEdit, hintId, children }: EditableCellProps<T>) {
+  const errorId = useId();
+  const editor = column.editor ?? { type: 'text' as const };
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+  const trigger = useRef<HTMLButtonElement>(null);
+  const field = useRef<HTMLInputElement | HTMLSelectElement | null>(null);
+  const move = useRef<Move>(null);
+  const busy = useRef(false);
+
+  useEffect(() => {
+    if (editing || !move.current) return;
+    const dir = move.current;
+    move.current = null;
+    if (dir === 'self') trigger.current?.focus();
+    else focusSibling(trigger.current, dir);
+  }, [editing]);
+
+  const focusOnMount = useCallback((el: HTMLInputElement | HTMLSelectElement | null) => {
+    field.current = el;
+    if (!el) return;
+    el.focus();
+    if (el instanceof HTMLInputElement) el.select();
+  }, []);
+
+  const start = () => {
+    const v = startValue(row, column);
+    setDraft(v == null ? '' : String(v));
+    setError(null);
+    setEditing(true);
+  };
+  const cancel = () => {
+    move.current = 'self';
+    setError(null);
+    setEditing(false);
+  };
+
+  const parse = (): { ok: true; value: string | number | null } | { ok: false; message: string } => {
+    if (editor.type !== 'number') return { ok: true, value: draft };
+    const text = draft.trim();
+    if (text === '') return { ok: true, value: null };
+    const n = Number(text);
+    if (!Number.isFinite(n)) return { ok: false, message: 'Enter a number.' };
+    if (editor.min != null && n < editor.min) return { ok: false, message: `Enter ${editor.min} or more.` };
+    if (editor.max != null && n > editor.max) return { ok: false, message: `Enter ${editor.max} or less.` };
+    return { ok: true, value: n };
+  };
+
+  const commit = async (after: Move) => {
+    if (busy.current) return;
+    const parsed = parse();
+    if (!parsed.ok) {
+      setError(parsed.message);
+      field.current?.focus();
+      return;
+    }
+    const previous = startValue(row, column);
+    if (
+      parsed.value === previous ||
+      (previous != null && String(previous) === String(parsed.value) && editor.type !== 'number')
+    ) {
+      move.current = after;
+      setError(null);
+      setEditing(false);
+      return;
+    }
+    busy.current = true;
+    setPending(true);
+    let result: DataTableCellEditResult;
+    try {
+      result = await onCellEdit({ row, rowId, columnId: column.id, value: parsed.value, previous });
+    } catch (err) {
+      result = err instanceof Error && err.message ? err.message : GENERIC_ERROR;
+    }
+    busy.current = false;
+    setPending(false);
+    if (result === false) result = GENERIC_ERROR;
+    if (typeof result === 'string') {
+      setError(result);
+      if (after) field.current?.focus();
+      return;
+    }
+    move.current = after;
+    setError(null);
+    setEditing(false);
+  };
+
+  const onEditorKeyDown = (e: KeyboardEvent<HTMLInputElement | HTMLSelectElement>) => {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      cancel();
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      void commit('self');
+    } else if (e.key === 'Tab') {
+      e.preventDefault();
+      void commit(e.shiftKey ? 'prev' : 'next');
+    }
+  };
+  const onEditorBlur = (e: FocusEvent<HTMLInputElement | HTMLSelectElement>) => {
+    // Focus left the editor (a click elsewhere): commit in place, without moving focus.
+    if (!editing || busy.current || e.currentTarget.contains(e.relatedTarget as Node | null)) return;
+    void commit(null);
+  };
+
+  if (!editing) {
+    return (
+      <button
+        ref={trigger}
+        type="button"
+        data-cell-edit-trigger=""
+        aria-describedby={hintId}
+        onClick={start}
+        onKeyDown={(e) => {
+          if (e.key === 'F2') {
+            e.preventDefault();
+            start();
+          }
+        }}
+        className={cn(
+          '-mx-1.5 -my-1 block max-w-[calc(100%+0.75rem)] min-w-[calc(100%+0.75rem)] cursor-text truncate rounded-sm px-1.5 py-1 text-inherit',
+          'hover:bg-secondary/60 focus-visible:outline-2 focus-visible:outline-offset-0 focus-visible:outline-focus-ring',
+          column.align === 'right' || column.variant === 'numeric' ? 'text-end' : 'text-start',
+        )}
+      >
+        {children}
+      </button>
+    );
+  }
+
+  const label = `${column.header} for ${rowLabel}`;
+  const common = {
+    'aria-label': label,
+    'aria-invalid': error ? true : undefined,
+    'aria-describedby': error ? errorId : undefined,
+    'aria-busy': pending || undefined,
+    // Not `disabled`: the field keeps focus while an async onCellEdit runs.
+    'aria-disabled': pending || undefined,
+    onKeyDown: onEditorKeyDown,
+    onBlur: onEditorBlur,
+  };
+  return (
+    <div className="-my-1 min-w-0" data-cell-editor="">
+      {editor.type === 'select' ? (
+        <select
+          ref={focusOnMount}
+          value={draft}
+          onChange={(e) => {
+            if (!pending) setDraft(e.target.value);
+          }}
+          className={cn(
+            'h-8 w-full rounded-md border border-input bg-background px-2 text-[13px] text-foreground',
+            'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring',
+            error && 'border-destructive',
+          )}
+          {...common}
+        >
+          {editor.options.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+      ) : (
+        <Input
+          ref={focusOnMount}
+          type={editor.type === 'number' ? 'number' : 'text'}
+          inputMode={editor.type === 'number' ? 'decimal' : undefined}
+          min={editor.type === 'number' ? editor.min : undefined}
+          max={editor.type === 'number' ? editor.max : undefined}
+          step={editor.type === 'number' ? editor.step : undefined}
+          placeholder={editor.type === 'text' ? editor.placeholder : undefined}
+          value={draft}
+          readOnly={pending}
+          onChange={(e) => setDraft(e.target.value)}
+          invalid={error != null}
+          className="w-full"
+          {...common}
+        />
+      )}
+      {error && (
+        <p
+          id={errorId}
+          role="alert"
+          className="mt-1 text-start text-[11.5px] font-medium whitespace-normal text-destructive-text"
+        >
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/** Whether a column is editable for a row. */
+export function isCellEditable<T>(column: DataTableColumn<T>, row: T): boolean {
+  return typeof column.editable === 'function' ? column.editable(row) : column.editable === true;
+}

package/src/tables/DataTable/examples/editable.tsx

@@ -0,0 +1,71 @@
+import { StatusTag } from '@gntik-ai/ui';
+import { useState } from 'react';
+import { DataTable } from '../DataTable';
+import type { DataTableColumn } from '../data-table-utils';
+import { DEPLOYMENT_ROWS, type DeploymentRow } from '../fixtures';
+
+const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
+const STATUS_OPTIONS = ['running', 'queued', 'paused', 'degraded', 'failed'].map((s) => ({
+  value: s,
+  label: s[0]!.toUpperCase() + s.slice(1),
+}));
+
+const COLUMNS: Array<DataTableColumn<DeploymentRow>> = [
+  {
+    id: 'name',
+    header: 'Deployment',
+    accessor: (r) => r.name,
+    sortable: true,
+    hideable: false,
+    className: 'font-semibold',
+    editable: true,
+  },
+  { id: 'region', header: 'Region', accessor: (r) => r.region, variant: 'mono' },
+  {
+    id: 'status',
+    header: 'Status',
+    accessor: (r) => r.status,
+    cell: (r) => <StatusTag status={r.status} />,
+    editable: true,
+    editor: { type: 'select', options: STATUS_OPTIONS },
+  },
+  {
+    id: 'cost',
+    header: 'Budget',
+    accessor: (r) => r.cost,
+    cell: (r) => money.format(r.cost),
+    variant: 'numeric',
+    editable: true,
+    editor: { type: 'number', min: 0, step: 0.01 },
+  },
+];
+
+/**
+ * Inline editing: Enter or F2 edits a cell, Enter or Tab saves, Escape cancels. Names must be
+ * unique and budgets above $1,000 are rejected by the (simulated) server, with the error inline.
+ */
+export default function EditableDataTable() {
+  const [rows, setRows] = useState(() => DEPLOYMENT_ROWS.slice(0, 8));
+  return (
+    <DataTable<DeploymentRow>
+      caption="Deployment settings"
+      rows={rows}
+      columns={COLUMNS}
+      paginated={false}
+      selectable={false}
+      onCellEdit={async ({ rowId, columnId, value }) => {
+        if (columnId === 'name') {
+          const name = String(value ?? '').trim();
+          if (!name) return 'Enter a name.';
+          if (rows.some((r) => r.id !== rowId && r.name === name)) return `“${name}” is already taken.`;
+        }
+        if (columnId === 'cost') {
+          await new Promise((resolve) => setTimeout(resolve, 150));
+          if (typeof value !== 'number') return 'Enter a budget.';
+          if (value > 1000) return 'Budgets above $1,000 need approval.';
+        }
+        setRows((prev) => prev.map((r) => (r.id === rowId ? { ...r, [columnId]: value } : r)));
+      }}
+    />
+  );
+}

package/src/tables/DataTable/examples/grouped.tsx

@@ -0,0 +1,18 @@
+import { DataTable } from '../DataTable';
+import { DEPLOYMENT_COLUMNS, DEPLOYMENT_ROWS, type DeploymentRow } from '../fixtures';
+
+/** Deployments grouped by region: collapsible group headers with a row count, sorting inside groups. */
+export default function GroupedDataTable() {
+  return (
+    <DataTable<DeploymentRow>
+      caption="Deployments by region"
+      rows={DEPLOYMENT_ROWS}
+      columns={DEPLOYMENT_COLUMNS}
+      groupBy="region"
+      groupLabel={(region) => <span className="font-mono">{region}</span>}
+      defaultCollapsedGroups={['ap-south-1']}
+      paginated={false}
+      defaultSort={{ columnId: 'cost', direction: 'descending' }}
+    />
+  );
+}

package/src/tables/DataTable/examples/resizable-pinned.tsx

@@ -0,0 +1,20 @@
+import { DataTable } from '../DataTable';
+import { DEPLOYMENT_COLUMNS, DEPLOYMENT_ROWS, type DeploymentRow } from '../fixtures';
+
+/**
+ * Resizable columns (drag a header edge, or focus it and use the arrow keys) with the name pinned
+ * to the start and the cost pinned to the end: they stay in view while the table scrolls sideways.
+ */
+export default function ResizablePinnedDataTable() {
+  return (
+    <DataTable<DeploymentRow>
+      caption="Deployments"
+      rows={DEPLOYMENT_ROWS}
+      columns={DEPLOYMENT_COLUMNS}
+      resizable
+      defaultColumnWidths={{ name: 220, region: 180, status: 160, requests: 160, cost: 140, updated: 160 }}
+      defaultPinnedColumns={{ left: ['name'], right: ['cost'] }}
+      rowActions={() => [{ label: 'Open' }, { label: 'Redeploy' }]}
+    />
+  );
+}

package/src/tables/DataTable/examples/saved-views.tsx

@@ -0,0 +1,61 @@
+import { SimpleSelect } from '@gntik-ai/ui';
+import { useState } from 'react';
+import { DataTable } from '../DataTable';
+import { DEPLOYMENT_COLUMNS, DEPLOYMENT_ROWS, type DeploymentRow } from '../fixtures';
+import type { DataTableView } from '../views';
+
+interface Filters {
+  status: string;
+}
+
+const VIEWS: DataTableView[] = [
+  {
+    id: 'expensive',
+    name: 'Most expensive',
+    state: { sort: { columnId: 'cost', direction: 'descending' }, hiddenColumns: ['region', 'updated'] },
+  },
+  { id: 'by-region', name: 'By region', state: { groupBy: 'region', pinnedColumns: { left: ['name'] } } },
+  {
+    id: 'failing',
+    name: 'Needs attention',
+    state: { filters: { status: 'failed' }, sort: { columnId: 'updated', direction: 'descending' }, hiddenColumns: [] },
+  },
+];
+
+const STATUS_FILTER = [
+  { value: 'all', label: 'All statuses' },
+  { value: 'running', label: 'Running' },
+  { value: 'failed', label: 'Failed' },
+  { value: 'degraded', label: 'Degraded' },
+];
+
+/**
+ * Saved views: switch between views, change the table (sort, columns, widths, pinning,
+ * grouping, the status filter) and save the result as a new view, rename, delete or reset it.
+ */
+export default function SavedViewsDataTable() {
+  const [views, setViews] = useState<DataTableView[]>(VIEWS);
+  const [filters, setFilters] = useState<Filters>({ status: 'all' });
+  const rows = filters.status === 'all' ? DEPLOYMENT_ROWS : DEPLOYMENT_ROWS.filter((r) => r.status === filters.status);
+  return (
+    <DataTable<DeploymentRow>
+      caption="Deployments"
+      rows={rows}
+      columns={DEPLOYMENT_COLUMNS}
+      resizable
+      views={views}
+      onViewsChange={setViews}
+      filters={filters}
+      onFiltersChange={(f) => setFilters((f as Filters | undefined) ?? { status: 'all' })}
+      toolbar={
+        <SimpleSelect
+          aria-label="Status"
+          size="sm"
+          value={filters.status}
+          onValueChange={(status) => setFilters({ status: status ?? 'all' })}
+          items={STATUS_FILTER}
+        />
+      }
+    />
+  );
+}

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

@@ -0,0 +1,55 @@
+import { useState } from 'react';
+import { DataTable } from '../DataTable';
+
+const items = [
+  { id: 'item-a', name: 'Item A' },
+  { id: 'item-b', name: 'Item B' },
+  { id: 'item-c', name: 'Item C' },
+];
+const itemColumns = [{ id: 'name', header: 'Name', accessor: (row: (typeof items)[number]) => row.name }];
+const versions = [
+  { id: 'v3', name: 'Version 3', eligible: true },
+  { id: 'v2', name: 'Version 2', eligible: false },
+  { id: 'v1', name: 'Version 1', eligible: true },
+];
+const versionColumns = [
+  { id: 'name', header: 'Version', accessor: (row: (typeof versions)[number]) => row.name, sortable: true },
+];
+
+/** Supplied selectionName values must be unique per page; omitted names are instance-unique. */
+export default function SingleSelectionExample() {
+  const [selectedId, setSelectedId] = useState<string | null>('v2');
+  return (
+    <div className="space-y-4">
+      <DataTable
+        rows={items}
+        columns={itemColumns}
+        caption="Items"
+        selectionMode="single"
+        paginated={false}
+        legend="Available items"
+        selectionName="example-item-choice"
+        defaultSelectedId="item-a"
+        showColumnMenu={false}
+        showDensityToggle={false}
+      />
+      <DataTable
+        rows={versions}
+        columns={versionColumns}
+        caption="Versions"
+        selectionMode="single"
+        legend="Available versions"
+        selectionName="example-version-choice"
+        getRowLabel={(row) => row.name}
+        selectedId={selectedId}
+        onSelectedIdChange={setSelectedId}
+        isRowDisabled={(row) => !row.eligible}
+        resizable
+        groupBy={() => 'Version history'}
+        collapsibleGroups
+        showColumnMenu={false}
+        showDensityToggle={false}
+      />
+    </div>
+  );
+}

package/src/tables/DataTable/examples/virtualized.tsx

@@ -0,0 +1,20 @@
+import { DataTable } from '../DataTable';
+import { DEPLOYMENT_COLUMNS, generateDeployments, type DeploymentRow } from '../fixtures';
+
+const ROWS = generateDeployments(5_000);
+
+/**
+ * 5,000 rows without pagination: only the rows in view are rendered (aria-rowcount and
+ * aria-rowindex keep the full count). Select-all still covers every row.
+ */
+export default function VirtualizedDataTable() {
+  return (
+    <DataTable<DeploymentRow>
+      caption="All deployments"
+      rows={ROWS}
+      columns={DEPLOYMENT_COLUMNS}
+      paginated={false}
+      virtualContainerClassName="max-h-[28rem]"
+    />
+  );
+}

package/src/tables/DataTable/fixtures.ts

@@ -0,0 +1,119 @@
+import { StatusTag } from '@gntik-ai/ui';
+import { createElement } from 'react';
+import type { DataTableColumn } from './data-table-utils';
+
+export interface DeploymentRow {
+  id: string;
+  name: string;
+  region: string;
+  status: 'running' | 'queued' | 'paused' | 'degraded' | 'failed';
+  requests: number;
+  cost: number;
+  updatedAt: Date;
+}
+
+const NAMES = [
+  'orders-api',
+  'billing-sync',
+  'invoice-worker',
+  'search-index',
+  'auth-gateway',
+  'media-resizer',
+  'nightly-export',
+  'webhooks',
+  'reports',
+  'notifications',
+  'checkout-web',
+  'audit-log',
+];
+const REGIONS = ['eu-west-1', 'us-east-1', 'ap-south-1', 'eu-central-1'];
+const STATUSES: DeploymentRow['status'][] = [
+  'running',
+  'running',
+  'running',
+  'queued',
+  'paused',
+  'degraded',
+  'running',
+  'failed',
+];
+const BASE = Date.UTC(2026, 8, 30, 12, 0, 0);
+
+const SUFFIXES = ['', '-staging', '-canary', '-preview'];
+
+/** Deterministic deployments (the first 24 are DEPLOYMENT_ROWS); large counts exercise virtualization. */
+export function generateDeployments(count: number): DeploymentRow[] {
+  return Array.from({ length: count }, (_, i) => {
+    const round = Math.floor(i / NAMES.length);
+    const suffix = round < SUFFIXES.length ? SUFFIXES[round] : `-${round}`;
+    return {
+      id: `dep_${(1000 + i * 37).toString(36)}`,
+      name: `${NAMES[i % NAMES.length]}${suffix}`,
+      region: REGIONS[(i * 3) % REGIONS.length] ?? 'eu-west-1',
+      status: STATUSES[(i * 5) % STATUSES.length] ?? 'running',
+      requests: ((i * 7919) % 90_000) + 1_200,
+      cost: Math.round((((i * 3571) % 900) + 40) * 100) / 100,
+      updatedAt: new Date(BASE - i * 3_700_000 * 5),
+    };
+  });
+}
+
+/** 24 deployments: enough for two pages at the default page size. */
+export const DEPLOYMENT_ROWS: DeploymentRow[] = generateDeployments(24);
+
+const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
+const count = new Intl.NumberFormat('en-US');
+
+/** Columns for DEPLOYMENT_ROWS. */
+export const DEPLOYMENT_COLUMNS: DataTableColumn<DeploymentRow>[] = [
+  {
+    id: 'name',
+    header: 'Deployment',
+    accessor: (r) => r.name,
+    sortable: true,
+    hideable: false,
+    className: 'font-semibold',
+  },
+  {
+    id: 'region',
+    header: 'Region',
+    accessor: (r) => r.region,
+    sortable: true,
+    className: 'font-mono text-[12px] text-muted-foreground',
+  },
+  {
+    id: 'status',
+    header: 'Status',
+    accessor: (r) => r.status,
+    cell: (r) => createElement(StatusTag, { status: r.status }),
+    sortable: true,
+  },
+  {
+    id: 'requests',
+    header: 'Requests',
+    accessor: (r) => r.requests,
+    cell: (r) => count.format(r.requests),
+    sortable: true,
+    align: 'right',
+    className: 'font-mono text-[12.5px]',
+  },
+  {
+    id: 'cost',
+    header: 'Cost',
+    accessor: (r) => r.cost,
+    cell: (r) => money.format(r.cost),
+    sortable: true,
+    align: 'right',
+    className: 'font-mono text-[12.5px]',
+  },
+  {
+    id: 'updated',
+    header: 'Updated',
+    accessor: (r) => r.updatedAt,
+    cell: (r) => r.updatedAt.toLocaleDateString('en-US', { month: 'short', day: 'numeric' }),
+    sortable: true,
+    align: 'right',
+    defaultHidden: true,
+    className: 'text-[12px] text-muted-foreground',
+  },
+];