noecosystem-design 0.2.2 → 0.3.0

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

@@ -0,0 +1,116 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import type { FilterSpec } from '../contracts';
+import { createMemoryTableStateAdapter, toDataQuery } from '../contracts';
+import {
+  fromTanStackFilters,
+  fromTanStackSelection,
+  fromTanStackSorting,
+  toTanStackColumns,
+  toTanStackFilters,
+  toTanStackPagination,
+  toTanStackSelection,
+  toTanStackSorting,
+} from './tanstack';
+
+type Row = { id: string; name: string; updated: string };
+
+describe('NOE <-> TanStack sorting', () => {
+  test('maps NOE DataSort to TanStack SortingState without leaking direction', () => {
+    expect(
+      toTanStackSorting([
+        { field: 'name', direction: 'asc' },
+        { field: 'updated', direction: 'desc' },
+      ]),
+    ).toEqual([
+      { id: 'name', desc: false },
+      { id: 'updated', desc: true },
+    ]);
+  });
+
+  test('round-trips back to NOE contracts', () => {
+    const sorts = [{ field: 'name', direction: 'desc' }] as const;
+    expect(fromTanStackSorting(toTanStackSorting(sorts))).toEqual([
+      { field: 'name', direction: 'desc' },
+    ]);
+  });
+});
+
+describe('NOE <-> TanStack filters', () => {
+  test('keeps the NOE operator inside the filter value and collapses per field', () => {
+    const filters: FilterSpec[] = [
+      { field: 'name', operator: 'contains', value: 'api' },
+      { field: 'name', operator: 'equals', value: 'api-2' },
+      { field: 'owner', operator: 'in', value: ['a', 'b'] },
+    ];
+    const tanstack = toTanStackFilters(filters);
+    expect(tanstack).toHaveLength(2);
+    expect(fromTanStackFilters(tanstack)).toEqual([
+      { field: 'name', operator: 'equals', value: 'api-2' },
+      { field: 'owner', operator: 'in', value: ['a', 'b'] },
+    ]);
+  });
+
+  test('evaluates NOE operators client-side', async () => {
+    const { noeTableFeatures } = await import('./tanstack');
+    const registered = (noeTableFeatures as unknown as { filterFns: Record<string, unknown> })
+      .filterFns;
+    expect(registered.noe).toBeTypeOf('function');
+  });
+});
+
+describe('NOE <-> TanStack pagination and selection', () => {
+  test('maps PageSpec to PaginationState', () => {
+    expect(toTanStackPagination({ index: 2, size: 25 })).toEqual({ pageIndex: 2, pageSize: 25 });
+  });
+
+  test('maps stable row ids to selection state and back', () => {
+    const ids = ['row-1', 'row-2'];
+    expect(fromTanStackSelection(toTanStackSelection(ids))).toEqual(ids);
+  });
+});
+
+describe('NOE column contract to engine columns', () => {
+  test('uses the row field as stable id and applies sortable opt-out', () => {
+    const columns = toTanStackColumns<Row>([
+      { key: 'name', header: 'Name' },
+      { key: 'updated', header: 'Updated', sortable: false, sortFn: 'alphanumeric' },
+    ]);
+    expect(columns[0]).toMatchObject({ id: 'name', accessorKey: 'name', enableSorting: true });
+    expect(columns[1]).toMatchObject({
+      id: 'updated',
+      enableSorting: false,
+      sortFn: 'alphanumeric',
+    });
+  });
+});
+
+describe('DataQuery and TableStateAdapter', () => {
+  test('builds a serializable query', () => {
+    expect(
+      toDataQuery({
+        search: 'api',
+        sorts: [{ field: 'name', direction: 'asc' }],
+        filters: [{ field: 'owner', operator: 'equals', value: 'Platform' }],
+        page: { index: 0, size: 10 },
+      }),
+    ).toEqual({
+      search: 'api',
+      sorts: [{ field: 'name', direction: 'asc' }],
+      filters: [{ field: 'owner', operator: 'equals', value: 'Platform' }],
+      page: { index: 0, size: 10 },
+    });
+  });
+
+  test('memory adapter notifies subscribers on set', () => {
+    const adapter = createMemoryTableStateAdapter<{ sorts: string[] }>({ sorts: [] });
+    const listener = vi.fn();
+    const unsubscribe = adapter.subscribe(listener);
+    adapter.set({ sorts: ['name'] });
+    expect(adapter.get()).toEqual({ sorts: ['name'] });
+    expect(listener).toHaveBeenCalledTimes(1);
+    unsubscribe();
+    adapter.set({ sorts: [] });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});

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);
+});