noecosystem-design 0.2.3 → 0.3.0

package/packages/data-ui/src/table/adapters/tanstack.ts

@@ -0,0 +1,179 @@
+import {
+  columnFilteringFeature,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  tableFeatures,
+} from '@tanstack/react-table';
+import type {
+  ColumnDef,
+  ColumnFiltersState,
+  PaginationState,
+  Row,
+  RowData,
+  RowSelectionState,
+  SortingState,
+  TableFeatures,
+} from '@tanstack/react-table';
+
+import type { DataColumn, DataSort, FilterSpec, PageSpec, RowId } from '../contracts';
+
+/**
+ * Internal TanStack Table v9 adapter.
+ *
+ * This module is the only place in @noe/data-ui that knows about TanStack.
+ * Public NOE types (contracts.ts) never reference TanStack, and TanStack types
+ * must never be re-exported from the package entry point.
+ */
+
+/**
+ * Client-side evaluator for NOE FilterSpec operators. Registered in the
+ * feature set as `noe` and attached to every filterable column.
+ */
+function noeFilterFn<TFeatures extends TableFeatures, TData extends RowData>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  const spec = filterValue as { operator: FilterSpec['operator']; value: unknown };
+  const cell = row.getValue<unknown>(columnId);
+  const target = spec.value;
+
+  switch (spec.operator) {
+    case 'contains':
+      return String(cell ?? '')
+        .toLowerCase()
+        .includes(String(target ?? '').toLowerCase());
+    case 'equals':
+      return cell === target;
+    case 'startsWith':
+      return String(cell ?? '')
+        .toLowerCase()
+        .startsWith(String(target ?? '').toLowerCase());
+    case 'endsWith':
+      return String(cell ?? '')
+        .toLowerCase()
+        .endsWith(String(target ?? '').toLowerCase());
+    case 'gt':
+      return compareValues(cell, target) > 0;
+    case 'gte':
+      return compareValues(cell, target) >= 0;
+    case 'lt':
+      return compareValues(cell, target) < 0;
+    case 'lte':
+      return compareValues(cell, target) <= 0;
+    case 'in':
+      return Array.isArray(target) && target.includes(cell);
+    case 'between': {
+      const [min, max] = Array.isArray(target) ? target : [undefined, undefined];
+      return compareValues(cell, min) >= 0 && compareValues(cell, max) <= 0;
+    }
+    default:
+      return true;
+  }
+}
+
+function compareValues(a: unknown, b: unknown): number {
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a ?? '').localeCompare(String(b ?? ''));
+}
+
+/**
+ * The NOE feature set: sorting, filtering, pagination and selection are
+ * registered explicitly (never `stockFeatures`), so unsupported behavior
+ * stays out of the bundle while DataTable keeps one static feature identity.
+ */
+export const noeTableFeatures = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { noe: noeFilterFn },
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: {
+    text: sortFn_text,
+    alphanumeric: sortFn_alphanumeric,
+    basic: sortFn_basic,
+    datetime: sortFn_datetime,
+  },
+});
+
+export type NoeTableFeatures = typeof noeTableFeatures;
+
+// --- Sorting -----------------------------------------------------------------
+
+export function toTanStackSorting(sorts: readonly DataSort[]): SortingState {
+  return sorts.map((sort) => ({ id: sort.field, desc: sort.direction === 'desc' }));
+}
+
+export function fromTanStackSorting(sorting: SortingState): DataSort[] {
+  return sorting.map((sort) => ({
+    field: sort.id,
+    direction: sort.desc ? 'desc' : 'asc',
+  }));
+}
+
+// --- Filtering ---------------------------------------------------------------
+// One TanStack column filter per field; the NOE operator travels inside the
+// filter value so `fromTanStackFilters` can reconstruct the NOE contract.
+
+export function toTanStackFilters(filters: readonly FilterSpec[]): ColumnFiltersState {
+  const byField = new Map<string, FilterSpec>();
+  for (const filter of filters) byField.set(filter.field, filter);
+  return [...byField.values()].map((filter) => ({
+    id: filter.field,
+    value: { operator: filter.operator, value: filter.value },
+  }));
+}
+
+export function fromTanStackFilters(filters: ColumnFiltersState): FilterSpec[] {
+  return filters.map((filter) => {
+    const value = filter.value as { operator: FilterSpec['operator']; value: unknown };
+    return { field: filter.id, operator: value.operator, value: value.value };
+  });
+}
+
+// --- Pagination ---------------------------------------------------------------
+
+export function toTanStackPagination(page: PageSpec | undefined): PaginationState {
+  return { pageIndex: page?.index ?? 0, pageSize: page?.size ?? Number.MAX_SAFE_INTEGER };
+}
+
+export function fromTanStackPagination(pagination: PaginationState): PageSpec {
+  return { index: pagination.pageIndex, size: pagination.pageSize };
+}
+
+// --- Selection -----------------------------------------------------------------
+
+export function toTanStackSelection(ids: readonly RowId[]): RowSelectionState {
+  const state: RowSelectionState = {};
+  for (const id of ids) state[id] = true;
+  return state;
+}
+
+export function fromTanStackSelection(selection: RowSelectionState): RowId[] {
+  return Object.keys(selection);
+}
+
+// --- Columns --------------------------------------------------------------------
+
+export function toTanStackColumns<Row extends { id: string }>(
+  columns: readonly DataColumn<Row>[],
+): ColumnDef<NoeTableFeatures, Row, unknown>[] {
+  return columns.map((column) => ({
+    id: column.key,
+    accessorKey: column.key,
+    enableSorting: column.sortable !== false,
+    ...(column.sortFn ? { sortFn: column.sortFn } : {}),
+    filterFn: 'noe' as const,
+  }));
+}

package/packages/data-ui/src/table/contracts.ts

@@ -0,0 +1,133 @@
+import type * as React from 'react';
+
+/**
+ * NOE data-table public contracts.
+ *
+ * These types are the stable public API of the NOE DataTable. Internal engines
+ * (currently TanStack Table v9) adapt to these contracts and must never leak
+ * through them. See ADR 0008 for the capability-library boundary.
+ */
+
+/** Stable application-level row identifier. Never a positional index. */
+export type RowId = string;
+
+/** NOE sort direction. Logical, not visual: RTL rendering stays start/end based. */
+export type DataSortDirection = 'asc' | 'desc';
+
+/** A single sort entry over a data field. */
+export interface DataSort {
+  field: string;
+  direction: DataSortDirection;
+}
+
+/**
+ * NOE filter operators. In server mode these travel to the backend verbatim;
+ * in client mode they are evaluated by the internal engine adapter.
+ */
+export type FilterOperator =
+  | 'contains'
+  | 'equals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  | 'between';
+
+/** A single filter entry over a data field. */
+export interface FilterSpec {
+  field: string;
+  operator: FilterOperator;
+  value: unknown;
+}
+
+/** Zero-based page index plus page size. */
+export interface PageSpec {
+  /** Zero-based page index. */
+  index: number;
+  /** Number of rows per page. */
+  size: number;
+}
+
+/** A serializable description of the current table query state. */
+export interface DataQuery {
+  search?: string;
+  filters: FilterSpec[];
+  sorts: DataSort[];
+  page?: PageSpec;
+}
+
+export interface DataQueryInput {
+  search?: string;
+  filters?: readonly FilterSpec[];
+  sorts?: readonly DataSort[];
+  page?: PageSpec;
+}
+
+/** Builds a serializable DataQuery from table state pieces. */
+export function toDataQuery(input: DataQueryInput): DataQuery {
+  return {
+    ...(input.search !== undefined ? { search: input.search } : {}),
+    filters: [...(input.filters ?? [])],
+    sorts: [...(input.sorts ?? [])],
+    ...(input.page !== undefined ? { page: { ...input.page } } : {}),
+  };
+}
+
+/** Row selection behavior: one row at a time, or many. */
+export type SelectionMode = 'single' | 'multiple';
+
+/** Selected row ids as stable application identifiers. */
+export type SelectionState = readonly RowId[];
+
+/**
+ * Store-agnostic state ownership contract (OpenStatus-inspired BYOS pattern).
+ * Products can back table state with URL, React state, a query cache, or any
+ * external store without coupling NOE to a specific transport or framework.
+ */
+export interface TableStateAdapter<TState> {
+  get(): TState;
+  set(next: TState): void;
+  subscribe(listener: () => void): () => void;
+}
+
+/** Minimal in-memory TableStateAdapter for non-persisted table state. */
+export function createMemoryTableStateAdapter<TState>(initial: TState): TableStateAdapter<TState> {
+  let value = initial;
+  const listeners = new Set<() => void>();
+  return {
+    get: () => value,
+    set: (next: TState) => {
+      value = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export type DataColumnSortFn = 'text' | 'alphanumeric' | 'basic' | 'datetime';
+
+/**
+ * NOE column contract. `key` addresses a row field; presentation stays with
+ * NOE (semantic markup, alignment, bidi handling), while the internal engine
+ * uses the key as a stable accessor id for sorting and filtering.
+ */
+export type DataColumn<Row> = {
+  /** Row field this column reads and sorts/filters by. */
+  key: keyof Row & string;
+  header: React.ReactNode;
+  /** Logical alignment: `start`/`end`, never left/right. */
+  align?: 'start' | 'end';
+  /** Render with LTR isolation for technical identifiers. */
+  technical?: boolean;
+  render?: (row: Row) => React.ReactNode;
+  /** Opt out of sorting for this column. Default: sortable. */
+  sortable?: boolean;
+  /** Client-side sort strategy. Default: engine auto-detection. */
+  sortFn?: DataColumnSortFn;
+};

package/packages/data-ui/src/table/data-table-visual.evidence.browser.test.tsx

@@ -0,0 +1,157 @@
+import type * as React from 'react';
+import { expect, test } from 'vitest';
+import { render } from 'vitest-browser-react';
+
+import '../../../design-tokens/src/tailwind.css';
+
+import type { DataColumn, DataSort } from './contracts';
+import { DataTable } from './data-table';
+
+/**
+ * Deterministic PNG evidence for the NOE DataTable (docs/design-system/visual-qa.md).
+ * Captures regular/compact density, RTL Persian, selection and loading states
+ * into evidence/data-table/. Pure layout evidence: no mock data leaves the repo.
+ *
+ * All variants render once; per-variant wrappers are captured individually
+ * because repeated render/unmount cycles invalidate the shared mount wrapper.
+ */
+
+// Resolved relative to this test file by the browser screenshot driver.
+const OUT = '../../../../evidence/data-table';
+
+type Row = { id: string; service: string; owner: string; status: string; updated: string };
+
+const columns: DataColumn<Row>[] = [
+  { key: 'service', header: 'Service', technical: true },
+  { key: 'owner', header: 'Owner' },
+  { key: 'status', header: 'Status' },
+  { key: 'updated', header: 'Updated', technical: true, align: 'end' },
+];
+
+const rows: Row[] = [
+  { id: '1', service: 'catalog-api', owner: 'Platform', status: 'Healthy', updated: '2m ago' },
+  {
+    id: '2',
+    service: 'agent-runner',
+    owner: 'AI Platform',
+    status: 'Degraded',
+    updated: '11m ago',
+  },
+  {
+    id: '3',
+    service: 'registry-sync',
+    owner: 'Design Systems',
+    status: 'Healthy',
+    updated: '1h ago',
+  },
+  {
+    id: '4',
+    service: 'registry-api',
+    owner: 'Design Systems',
+    status: 'Healthy',
+    updated: '3h ago',
+  },
+  { id: '5', service: 'agent-gateway', owner: 'AI Platform', status: 'Healthy', updated: '5h ago' },
+];
+
+const faColumns: DataColumn<Row>[] = [
+  { key: 'service', header: 'سرویس', technical: true },
+  { key: 'owner', header: 'مالک' },
+  { key: 'status', header: 'وضعیت' },
+];
+const faSorting: DataSort[] = [{ field: 'service', direction: 'asc' }];
+
+const captures: Array<{ name: string; ui: React.ReactElement }> = [
+  {
+    name: 'data-table-regular-en-light',
+    ui: (
+      <DataTable columns={columns} rows={rows} caption="Service health" empty="No services yet." />
+    ),
+  },
+  {
+    name: 'data-table-compact-fa-rtl',
+    ui: (
+      <div dir="rtl" lang="fa">
+        <DataTable
+          columns={faColumns}
+          rows={rows}
+          caption="وضعیت سرویس‌ها"
+          density="compact"
+          empty="هنوز سرویسی ثبت نشده است."
+          sorting={faSorting}
+          onSortingChange={() => {}}
+        />
+      </div>
+    ),
+  },
+  {
+    name: 'data-table-selection',
+    ui: (
+      <DataTable
+        columns={columns}
+        rows={rows}
+        caption="Service health"
+        empty="No services yet."
+        defaultSelection={['2']}
+        selectAllLabel="Select all services"
+        selectedCountLabel={(count: number) => `${count} selected`}
+        renderSelectionActions={() => <button type="button">Restart</button>}
+      />
+    ),
+  },
+  {
+    name: 'data-table-loading',
+    ui: (
+      <DataTable
+        columns={columns}
+        rows={[]}
+        caption="Service health"
+        empty="No services yet."
+        loading
+        loadingRows={4}
+      />
+    ),
+  },
+  {
+    name: 'data-table-selection-fa-dark-compact',
+    ui: (
+      <div
+        data-theme="dark"
+        dir="rtl"
+        lang="fa"
+        className="rounded-lg bg-background p-3 text-foreground"
+      >
+        <DataTable
+          columns={faColumns}
+          rows={rows}
+          caption="وضعیت سرویس‌ها"
+          density="compact"
+          empty="هنوز سرویسی ثبت نشده است."
+          defaultSelection={['2']}
+          selectAllLabel="انتخاب همه سرویس‌ها"
+          selectedCountLabel={(count: number) => `${count} مورد انتخاب شده`}
+        />
+      </div>
+    ),
+  },
+];
+
+test('captures DataTable visual evidence', async () => {
+  const screen = await render(
+    <div className="flex flex-col">
+      {captures.map(({ name, ui }) => (
+        <div data-testid={`capture-${name}`} key={name}>
+          {ui}
+        </div>
+      ))}
+    </div>,
+  );
+
+  for (const { name } of captures) {
+    await screen
+      .getByTestId(`capture-${name}`)
+      .screenshot({ animations: 'disabled', caret: 'hide', path: `${OUT}/${name}.png` });
+  }
+
+  expect(captures).toHaveLength(5);
+});

package/packages/data-ui/src/table/data-table.browser.test.tsx

@@ -0,0 +1,180 @@
+import { useState } from 'react';
+import { expect, test, vi } from 'vitest';
+import { render } from 'vitest-browser-react';
+
+import type { DataColumn } from './contracts';
+import { DataTable } from './data-table';
+
+type Row = { id: string; service: string; owner: string };
+
+const columns: DataColumn<Row>[] = [
+  { key: 'service', header: 'Service', technical: true },
+  { key: 'owner', header: 'Owner' },
+];
+
+const rows: Row[] = [
+  { id: '1', service: 'catalog-api', owner: 'Platform' },
+  { id: '2', service: 'agent-runner', owner: 'AI Platform' },
+  { id: '3', service: 'registry-sync', owner: 'Design Systems' },
+];
+
+interface ScreenLike {
+  getByRole(
+    role: 'table' | 'button' | 'checkbox' | 'columnheader',
+    options?: { name?: string },
+  ): {
+    element(): Element;
+    click(): Promise<void>;
+  };
+  getByText(text: string): { element(): Element };
+}
+
+const bodyRows = (screen: ScreenLike) =>
+  (screen.getByRole('table').element() as HTMLTableElement).querySelectorAll('tbody tr');
+
+test('renders a semantic table with logical alignment metadata', async () => {
+  const screen = await render(
+    <DataTable columns={columns} rows={rows} caption="Service health" empty="No services yet." />,
+  );
+
+  const table = screen.getByRole('table').element() as HTMLTableElement;
+  expect(table.querySelector('caption')?.textContent).toBe('Service health');
+  const header = screen
+    .getByRole('columnheader', { name: 'Service' })
+    .element() as HTMLTableCellElement;
+  expect(header.getAttribute('data-align')).toBe('start');
+  expect(header.getAttribute('aria-sort')).toBe('none');
+  expect(bodyRows(screen)).toHaveLength(3);
+});
+
+test('sorting cycles ascending, descending, then unsorted with aria-sort state', async () => {
+  const onSortingChange = vi.fn();
+  const screen = await render(
+    <DataTable
+      columns={columns}
+      rows={rows}
+      caption="Service health"
+      empty="No services yet."
+      onSortingChange={onSortingChange}
+    />,
+  );
+
+  const header = () =>
+    screen.getByRole('columnheader', { name: 'Service' }).element() as HTMLTableCellElement;
+  const firstRowService = () =>
+    (bodyRows(screen)[0] as HTMLTableRowElement).querySelector('td')?.textContent;
+
+  await screen.getByRole('button', { name: 'Service' }).click();
+  expect(header().getAttribute('aria-sort')).toBe('ascending');
+  expect(firstRowService()).toBe('agent-runner');
+  expect(onSortingChange).toHaveBeenLastCalledWith([{ field: 'service', direction: 'asc' }]);
+
+  await screen.getByRole('button', { name: 'Service' }).click();
+  expect(header().getAttribute('aria-sort')).toBe('descending');
+  expect(firstRowService()).toBe('registry-sync');
+  expect(onSortingChange).toHaveBeenLastCalledWith([{ field: 'service', direction: 'desc' }]);
+
+  await screen.getByRole('button', { name: 'Service' }).click();
+  expect(header().getAttribute('aria-sort')).toBe('none');
+  expect(firstRowService()).toBe('catalog-api');
+});
+
+test('selection keeps stable row ids and reflects indeterminate state', async () => {
+  const onSelectionChange = vi.fn();
+  const screen = await render(
+    <DataTable
+      columns={columns}
+      rows={rows}
+      caption="Service health"
+      empty="No services yet."
+      defaultSelection={['2']}
+      onSelectionChange={onSelectionChange}
+      selectAllLabel="Select all rows"
+      rowSelectionLabel={(row: Row) => `Select ${row.service}`}
+      selectedCountLabel={(count: number) => `${count} selected`}
+    />,
+  );
+
+  await screen.getByRole('checkbox', { name: 'Select catalog-api' }).click();
+  expect(onSelectionChange).toHaveBeenLastCalledWith(['1', '2']);
+  expect(
+    screen.getByRole('checkbox', { name: 'Select all rows' }).element() as HTMLInputElement,
+  ).toBePartiallyChecked();
+
+  await screen.getByRole('checkbox', { name: 'Select all rows' }).click();
+  expect(onSelectionChange).toHaveBeenLastCalledWith(['1', '2', '3']);
+  expect(screen.getByText('3 selected').element()).toBeTruthy();
+});
+
+test('client-side pagination slices rows and reports status', async () => {
+  function PaginationHost() {
+    const [page, setPage] = useState({ index: 0, size: 2 });
+    return (
+      <DataTable
+        columns={columns}
+        rows={rows}
+        caption="Service health"
+        empty="No services yet."
+        page={page}
+        onPageChange={setPage}
+        previousPageLabel="Previous page"
+        nextPageLabel="Next page"
+      />
+    );
+  }
+  const screen = await render(<PaginationHost />);
+
+  expect(bodyRows(screen)).toHaveLength(2);
+  expect(screen.getByRole('button', { name: 'Previous page' })).toBeDisabled();
+  expect(screen.getByText('1–2 / 3').element()).toBeTruthy();
+
+  await screen.getByRole('button', { name: 'Next page' }).click();
+  expect(bodyRows(screen)).toHaveLength(1);
+  expect(screen.getByRole('button', { name: 'Next page' })).toBeDisabled();
+  expect(screen.getByText('3–3 / 3').element()).toBeTruthy();
+});
+
+test('renders logical alignment inside an RTL container without mirroring hacks', async () => {
+  const screen = await render(
+    <div dir="rtl">
+      <DataTable columns={columns} rows={rows} caption="Service health" empty="No services yet." />
+    </div>,
+  );
+
+  const header = screen
+    .getByRole('columnheader', { name: 'Owner' })
+    .element() as HTMLTableCellElement;
+  expect(header.getAttribute('data-align')).toBe('start');
+  expect(header.className).toContain('text-start');
+  const technicalCell = screen
+    .getByRole('cell', { name: 'catalog-api' })
+    .element() as HTMLTableCellElement;
+  expect(technicalCell.querySelector('[dir="ltr"]')).toBeTruthy();
+});
+
+test('loading renders skeleton rows instead of data', async () => {
+  const screen = await render(
+    <DataTable
+      columns={columns}
+      rows={rows}
+      caption="Service health"
+      empty="No services yet."
+      loading
+      loadingRows={2}
+    />,
+  );
+
+  expect(
+    (screen.getByRole('table').element() as HTMLTableElement).querySelectorAll(
+      '[data-slot="data-table-loading-row"]',
+    ),
+  ).toHaveLength(2);
+});
+
+test('empty model renders the empty affordance', async () => {
+  const screen = await render(
+    <DataTable columns={columns} rows={[]} caption="Service health" empty="No services yet." />,
+  );
+
+  expect(screen.getByText('No services yet.').element()).toBeTruthy();
+});