noecosystem-design 0.2.3 → 0.4.0

package/docs/design-system/visual-qa.md

@@ -7,4 +7,10 @@ The capture script generates deterministic PNG evidence for:
 - Consumer, dashboard, agent and workflow surfaces at representative desktop conditions.
 - Pseudo-LTR and pseudo-RTL stress views.
 
+The NOE DataTable has its own deterministic component-level evidence:
+`packages/data-ui/src/table/data-table-visual.evidence.browser.test.tsx`
+renders regular and compact density, Persian RTL, selection (light and dark)
+and loading states with the real Tailwind-expanded tokens into
+`evidence/data-table/`.
+
 Review checks include overflow, clipped Persian, bidi corruption, arrow direction, sidebar collapse, technical-value isolation, table scrolling, excessive cards, random shadows, coral overuse, mirrored brand marks, focus order and mobile composition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noecosystem-design",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "private": false,
   "description": "Agent-readable NOE design-system source, registry metadata, and verification contracts.",
   "keywords": [

package/packages/data-ui/package.json

@@ -5,11 +5,16 @@
   "type": "module",
   "dependencies": {
     "@noe/icons": "workspace:*",
-    "@noe/ui": "workspace:*"
+    "@noe/ui": "workspace:*",
+    "@tanstack/react-table": "^9.2.4"
   },
   "peerDependencies": {
     "react": "^19.2.0"
   },
+  "devDependencies": {
+    "vitest": "4.1.11",
+    "vitest-browser-react": "2.2.0"
+  },
   "exports": {
     ".": "./src/index.ts"
   }

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

@@ -1,99 +1,2 @@
-import { useId } from 'react';
-import type * as React from 'react';
-import { TechnicalValue } from '@noe/ui/bidi';
-import { cn } from '@noe/ui/lib/cn';
-
-export type DataColumn<Row> = {
-  key: keyof Row & string;
-  header: React.ReactNode;
-  align?: 'start' | 'end';
-  technical?: boolean;
-  render?: (row: Row) => React.ReactNode;
-};
-
-export function DataTable<Row extends { id: string }>({
-  columns,
-  rows,
-  caption,
-  empty,
-  className,
-}: {
-  columns: DataColumn<Row>[];
-  rows: Row[];
-  caption: string;
-  empty: React.ReactNode;
-  className?: string;
-}) {
-  const captionId = useId();
-  if (!rows.length)
-    return (
-      <div
-        className={cn(
-          'flex min-h-32 items-center justify-center rounded-lg border border-dashed border-border bg-surface-sunken/30 p-6 text-center text-sm text-muted-foreground',
-          className,
-        )}
-        data-slot="data-table-empty"
-      >
-        {empty}
-      </div>
-    );
-
-  return (
-    // WCAG 2.1: keyboard-accessible scrollable container for overflow tables.
-    <section
-      aria-labelledby={captionId}
-      className={cn('overflow-x-auto rounded-lg border border-border', className)}
-      data-slot="data-table-scroll"
-      // biome-ignore lint/a11y/noNoninteractiveTabindex: scrollable region focus pattern
-      tabIndex={0}
-    >
-      <table className="w-full min-w-full border-collapse text-sm" data-slot="data-table">
-        <caption className="sr-only" id={captionId}>
-          {caption}
-        </caption>
-        <thead>
-          <tr className="border-b border-border bg-surface-sunken/60">
-            {columns.map((column) => (
-              <th
-                className={cn(
-                  'whitespace-nowrap px-4 py-2.5 text-xs font-medium text-muted-foreground',
-                  column.align === 'end' ? 'text-end' : 'text-start',
-                )}
-                data-align={column.align ?? 'start'}
-                key={column.key}
-                scope="col"
-              >
-                {column.header}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody>
-          {rows.map((row) => {
-            const cells = columns.map((column) => {
-              const content = column.render ? column.render(row) : String(row[column.key] ?? '');
-              const value = column.technical ? <TechnicalValue>{content}</TechnicalValue> : content;
-              return (
-                <td
-                  className={cn(
-                    'whitespace-nowrap px-4 py-2.5 text-foreground',
-                    column.align === 'end' ? 'text-end' : 'text-start',
-                  )}
-                  data-align={column.align ?? 'start'}
-                  key={column.key}
-                >
-                  {value}
-                </td>
-              );
-            });
-            return (
-              <tr className="border-b border-border last:border-b-0 hover:bg-muted/50" key={row.id}>
-                {cells}
-              </tr>
-            );
-          })}
-        </tbody>
-      </table>
-    </section>
-  );
-}
+export * from './table/contracts';
+export * from './table/data-table';

package/packages/data-ui/src/pagination.tsx

@@ -8,8 +8,8 @@ export interface PaginationProps extends React.ComponentProps<'nav'> {
   status: React.ReactNode;
   previousLabel: string;
   nextLabel: string;
-  onPrevious?: () => void;
-  onNext?: () => void;
+  onPrevious?: (() => void) | undefined;
+  onNext?: (() => void) | undefined;
   canPrevious?: boolean;
   canNext?: boolean;
 }

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