noecosystem-design 0.2.3 → 0.3.0

package/README.md

@@ -100,8 +100,8 @@ Advanced Security are enabled in repository settings.
 CodeQL is similarly opt-in through `ENABLE_CODEQL=true`: first enable **Code
 Security** for this private repository in GitHub’s security settings, then set the
 variable. This avoids a misleading failed workflow when GitHub cannot accept SARIF
-uploads. The workflows use Node 24; the runner’s Node 20 deprecation notice does not
-require a compatibility override.
+uploads. The workflows configure Node 24 and use `actions/setup-node@v6`, whose
+action runtime is also Node 24.
 
 ## Architecture
 

package/apps/storybook/stories/catalog/checkbox.stories.tsx

@@ -8,11 +8,16 @@ const meta = {
 } satisfies Meta<typeof Checkbox>;
 export default meta;
 type Story = StoryObj<typeof meta>;
-export const Default: Story = {};
+export const Default: Story = {
+  render: () => <Checkbox label="Enable notifications" />,
+};
+export const Bare: Story = {
+  render: () => <Checkbox aria-label="Enable notifications" />,
+};
 export const RTL: Story = {
   render: () => (
     <div dir="rtl">
-      <Checkbox />
+      <Checkbox label="فعال‌سازی اعلان‌ها" />
     </div>
   ),
 };

package/apps/storybook/stories/catalog/data-table.stories.tsx

@@ -1,11 +1,23 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '@noe/ui/button';
+import { EmptyState } from '@noe/ui/empty-state';
+import { Input } from '@noe/ui/input';
 
-import { type DataColumn, DataTable } from '../../../../packages/data-ui/src/data-table';
+import {
+  type DataColumn,
+  DataTable,
+  type DataSort,
+  type FilterSpec,
+  type PageSpec,
+  type RowId,
+} from '../../../../packages/data-ui/src/data-table';
+import { FilterBar } from '../../../../packages/data-ui/src/filter-bar';
 
 type ServiceRow = { id: string; service: string; owner: string; status: string; updated: string };
 
 const columns: DataColumn<ServiceRow>[] = [
-  { key: 'service', header: 'Service' },
+  { key: 'service', header: 'Service', technical: true },
   { key: 'owner', header: 'Owner' },
   { key: 'status', header: 'Status' },
   { key: 'updated', header: 'Updated', technical: true, align: 'end' },
@@ -29,6 +41,18 @@ const rows: ServiceRow[] = [
   },
 ];
 
+const moreRows: ServiceRow[] = [
+  ...rows,
+  {
+    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' },
+];
+
 function DataTableDemo() {
   return (
     <DataTable columns={columns} rows={rows} caption="Service health" empty="No services yet." />
@@ -44,8 +68,207 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
 export const Empty: Story = {
   render: () => (
-    <DataTable columns={columns} rows={[]} caption="Service health" empty="No services yet." />
+    <DataTable
+      columns={columns}
+      rows={[]}
+      caption="Service health"
+      empty={
+        <EmptyState
+          title="No services yet"
+          description="Services appear here once they report health to the platform."
+        />
+      }
+    />
+  ),
+};
+
+function SortingDemo() {
+  const [sorting, setSorting] = useState<DataSort[]>([{ field: 'service', direction: 'asc' }]);
+  return (
+    <DataTable
+      columns={columns}
+      rows={[...moreRows]}
+      caption="Service health"
+      empty="No services yet."
+      sorting={sorting}
+      onSortingChange={setSorting}
+    />
+  );
+}
+export const Sorting: Story = { render: () => <SortingDemo /> };
+
+function SelectionDemo() {
+  const [selected, setSelected] = useState<RowId[]>(['2']);
+  return (
+    <DataTable
+      columns={columns}
+      rows={rows}
+      caption="Service health"
+      empty="No services yet."
+      selection={selected}
+      onSelectionChange={setSelected}
+      selectAllLabel="Select all services"
+      rowSelectionLabel={(row: ServiceRow) => `Select ${row.service}`}
+      selectedCountLabel={(count: number) => `${count} selected`}
+      renderSelectionActions={({ selectedIds }) => (
+        <Button size="sm" variant="outline">
+          Restart {selectedIds.length > 0 ? `(${selectedIds.length})` : ''}
+        </Button>
+      )}
+    />
+  );
+}
+export const Selection: Story = { render: () => <SelectionDemo /> };
+
+function PaginationDemo() {
+  const [page, setPage] = useState<PageSpec>({ index: 0, size: 2 });
+  return (
+    <DataTable
+      columns={columns}
+      rows={[...moreRows]}
+      caption="Service health"
+      empty="No services yet."
+      page={page}
+      onPageChange={setPage}
+      previousPageLabel="Previous page"
+      nextPageLabel="Next page"
+      paginationLabel="Service health pagination"
+    />
+  );
+}
+export const Pagination: Story = { render: () => <PaginationDemo /> };
+
+function WithFiltersDemo() {
+  const [search, setSearch] = useState('');
+  const [filters, setFilters] = useState<FilterSpec[]>([]);
+  return (
+    <div className="flex flex-col gap-3">
+      <FilterBar
+        label="Filter services"
+        search={
+          <Input
+            aria-label="Search services"
+            onChange={(event) => {
+              setSearch(event.target.value);
+              setFilters(
+                event.target.value
+                  ? [{ field: 'service', operator: 'contains', value: event.target.value }]
+                  : [],
+              );
+            }}
+            placeholder="Search services"
+            size="sm"
+            value={search}
+          />
+        }
+      />
+      <DataTable
+        columns={columns}
+        rows={[...moreRows]}
+        caption="Service health"
+        empty="No services match the current filter."
+        filters={filters}
+        onFiltersChange={setFilters}
+      />
+    </div>
+  );
+}
+export const WithFilters: Story = { render: () => <WithFiltersDemo /> };
+
+function CompactDemo() {
+  return (
+    <DataTable
+      columns={columns}
+      rows={[...moreRows]}
+      caption="Service health"
+      density="compact"
+      empty="No services yet."
+      page={{ index: 0, size: 3 }}
+      onPageChange={() => {}}
+      previousPageLabel="Previous page"
+      nextPageLabel="Next page"
+      paginationLabel="Service health pagination"
+    />
+  );
+}
+export const Compact: Story = { render: () => <CompactDemo /> };
+
+function RtlDemo() {
+  const [sorting, setSorting] = useState<DataSort[]>([{ field: 'service', direction: 'asc' }]);
+  const faColumns: DataColumn<ServiceRow>[] = [
+    { key: 'service', header: 'سرویس', technical: true },
+    { key: 'owner', header: 'مالک' },
+    { key: 'status', header: 'وضعیت' },
+    { key: 'updated', header: 'آخرین به‌روزرسانی', align: 'end' },
+  ];
+  return (
+    <div dir="rtl" lang="fa">
+      <DataTable
+        columns={faColumns}
+        rows={rows}
+        caption="وضعیت سرویس‌ها"
+        density="compact"
+        empty="هنوز سرویسی ثبت نشده است."
+        sorting={sorting}
+        onSortingChange={setSorting}
+        selectAllLabel="انتخاب همه سرویس‌ها"
+        rowSelectionLabel={(row: ServiceRow) => `انتخاب ${row.service}`}
+        selectedCountLabel={(count: number) => `${count} مورد انتخاب شده`}
+        page={{ index: 0, size: 2 }}
+        onPageChange={() => {}}
+        previousPageLabel="صفحه قبلی"
+        nextPageLabel="صفحه بعدی"
+        paginationLabel="صفحه‌بندی وضعیت سرویس‌ها"
+      />
+    </div>
+  );
+}
+export const RTL: Story = { render: () => <RtlDemo /> };
+
+function ServerSideDemo() {
+  const [query, setQuery] = useState<{ sorts: DataSort[]; filters: FilterSpec[]; page: PageSpec }>({
+    sorts: [],
+    filters: [],
+    page: { index: 0, size: 2 },
+  });
+  // A real product sends `toDataQuery(query)` to Django and renders the page.
+  const serverPage = moreRows.slice(
+    query.page.index * query.page.size,
+    (query.page.index + 1) * query.page.size,
+  );
+  return (
+    <DataTable
+      columns={columns}
+      rows={serverPage}
+      caption="Service health"
+      empty="No services yet."
+      sorting={query.sorts}
+      onSortingChange={(sorts) => setQuery((q) => ({ ...q, sorts }))}
+      manualSorting
+      page={query.page}
+      onPageChange={(next) => setQuery((q) => ({ ...q, page: next }))}
+      manualPagination
+      totalRowCount={moreRows.length}
+      previousPageLabel="Previous page"
+      nextPageLabel="Next page"
+      paginationLabel="Service health pagination"
+    />
+  );
+}
+export const ServerSide: Story = { render: () => <ServerSideDemo /> };
+
+export const Loading: Story = {
+  render: () => (
+    <DataTable
+      columns={columns}
+      rows={[]}
+      caption="Service health"
+      empty="No services yet."
+      loading
+      loadingRows={3}
+    />
   ),
 };

package/docs/design-system/components.md

@@ -101,6 +101,38 @@ Implemented source includes Button, Input, Field, Dialog, Drawer, Tabs, auto-dir
 - Tab arrow behavior resolves against active direction.
 - Email, URL, telephone, numeric, code and identifier content preserve technical direction.
 
+## Data tables
+
+`DataTable` in `@noe/data-ui` owns the semantic `<table>` markup, NOE tokens,
+RTL behavior and accessibility, while TanStack Table v9 provides the headless
+state engine behind an internal adapter
+(`packages/data-ui/src/table/adapters/tanstack.ts`, per ADR 0008). TanStack
+types never appear in the public API: products program against NOE contracts
+(`DataColumn`, `DataSort`, `FilterSpec`, `PageSpec`, `RowId`, `SelectionState`,
+`DataQuery`) exported from `@noe/data-ui`.
+
+- Sorting headers cycle ascending → descending → unsorted and expose `aria-sort`;
+  icons are direction-neutral so RTL needs no mirroring.
+- Filtering uses NOE `FilterSpec` operators (`contains`, `equals`, `in`,
+  `between`, …). `FilterBar` composes the controls; `DataTable` owns state.
+- Pagination is controlled via `PageSpec` with caller-provided accessible
+  labels, matching the `Pagination` primitive contract.
+- Selection keeps stable row ids (`RowId`), supports single/multiple modes and
+  never selects by positional index.
+- Server mode (`manualSorting`/`manualFiltering`/`manualPagination` +
+  `totalRowCount`) trusts incoming data order and slicing; pair it with
+  `toDataQuery` to serialize state into a Django query.
+- `density="compact"` tightens row rhythm for dense workspaces using the
+  spacing scale; `regular` is the default.
+- `empty` accepts composed content — pass an `EmptyState` for full empty
+  affordances. The `WithFilters` catalog story demonstrates the FilterBar +
+  Input + DataTable composition.
+
+Deterministic visual evidence (light, dark, RTL, selection, loading) is
+captured by `packages/data-ui/src/table/data-table-visual.evidence.browser.test.tsx`
+into `evidence/data-table/`; the browser test project renders with the real
+Tailwind-expanded NOE tokens.
+
 ## Product adapters
 
 Data, chart, agent and workflow packages own the NOE composition. Product screens should never import an unnormalized marketplace component directly.

package/docs/design-system/inventory.md

@@ -386,3 +386,4 @@ Total catalog entries: **129** · registry items: **67**
 - `fab`: Mobile-only floating action button anchored to the logical end edge above the bottom navigation, with safe-area padding and required accessible label.
 - `mobile-screen`: Single-column mobile page scaffold composing an app bar, scrollable content region, optional floating action button and bottom navigation.
 - `bottom-navigation`: Mobile-only bottom tab bar with current-page state, badges, icon slots and safe-area padding; hidden from the medium breakpoint upward.
+

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