noecosystem-design 0.2.3 → 0.3.0

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

@@ -0,0 +1,524 @@
+import { useId, useMemo, useState } from 'react';
+import type * as React from 'react';
+import { ArrowDown2, ArrowUp2 } from '@noe/icons';
+import { TechnicalValue } from '@noe/ui/bidi';
+import { Button } from '@noe/ui/button';
+import { Checkbox } from '@noe/ui/checkbox';
+import { cn } from '@noe/ui/lib/cn';
+import { Skeleton } from '@noe/ui/skeleton';
+import { functionalUpdate, useTable } from '@tanstack/react-table';
+import type {
+  ColumnFiltersState,
+  OnChangeFn,
+  RowSelectionState,
+  SortingState,
+} from '@tanstack/react-table';
+
+import { Pagination } from '../pagination';
+import {
+  fromTanStackFilters,
+  fromTanStackSelection,
+  fromTanStackSorting,
+  noeTableFeatures,
+  toTanStackColumns,
+  toTanStackFilters,
+  toTanStackSelection,
+  toTanStackSorting,
+} from './adapters/tanstack';
+import type { DataColumn, DataSort, FilterSpec, PageSpec, RowId, SelectionMode } from './contracts';
+
+export type {
+  DataColumn,
+  DataColumnSortFn,
+  DataQuery,
+  DataQueryInput,
+  DataSort,
+  DataSortDirection,
+  FilterOperator,
+  FilterSpec,
+  PageSpec,
+  RowId,
+  SelectionMode,
+  SelectionState,
+  TableStateAdapter,
+} from './contracts';
+export { createMemoryTableStateAdapter, toDataQuery } from './contracts';
+
+export interface DataTablePaginationStatusInfo {
+  /** One-based index of the first row on the page. */
+  startIndex: number;
+  /** One-based index of the last row on the page. */
+  endIndex: number;
+  /** Total row count across pages. */
+  total: number;
+}
+
+export interface DataTableSelectionInfo {
+  selectedIds: RowId[];
+}
+
+type DataTableFeatureProps<Row extends { id: string }> = {
+  /** Controlled NOE sorting state. */
+  sorting?: readonly DataSort[];
+  /** Initial sorting state for uncontrolled usage. */
+  defaultSorting?: readonly DataSort[];
+  onSortingChange?: (sorting: DataSort[]) => void;
+  /** Server owns row order; the table only reflects sorting state. */
+  manualSorting?: boolean;
+} & (
+  | {
+      filters?: undefined;
+      defaultFilters?: undefined;
+      onFiltersChange?: undefined;
+      manualFiltering?: undefined;
+    }
+  | {
+      /** Controlled NOE filter state. */
+      filters: readonly FilterSpec[];
+      defaultFilters?: undefined;
+      onFiltersChange: (filters: FilterSpec[]) => void;
+      manualFiltering?: boolean;
+    }
+  | {
+      filters?: undefined;
+      /** Initial filter state for uncontrolled usage. */
+      defaultFilters?: readonly FilterSpec[];
+      onFiltersChange?: (filters: FilterSpec[]) => void;
+      manualFiltering?: boolean;
+    }
+) &
+  (
+    | {
+        page?: undefined;
+        onPageChange?: undefined;
+        previousPageLabel?: undefined;
+        nextPageLabel?: undefined;
+        paginationLabel?: undefined;
+        paginationStatus?: undefined;
+        totalRowCount?: undefined;
+        manualPagination?: undefined;
+      }
+    | {
+        /** Controlled zero-based page state. */
+        page: PageSpec;
+        onPageChange: (page: PageSpec) => void;
+        /** Accessible names for the icon-only pagination controls. */
+        previousPageLabel: string;
+        nextPageLabel: string;
+        paginationLabel?: string;
+        paginationStatus?: (info: DataTablePaginationStatusInfo) => React.ReactNode;
+        /** Server-side total; required for accurate status in manual mode. */
+        totalRowCount?: number;
+        /** Server owns row slicing; `rows` holds exactly the current page. */
+        manualPagination?: boolean;
+      }
+  ) &
+  (
+    | {
+        selection?: undefined;
+        defaultSelection?: undefined;
+        onSelectionChange?: undefined;
+        selectionMode?: undefined;
+        selectAllLabel?: undefined;
+        rowSelectionLabel?: undefined;
+        selectedCountLabel?: undefined;
+        renderSelectionActions?: undefined;
+      }
+    | {
+        /** Controlled selected row ids. */
+        selection?: readonly RowId[];
+        /** Initial selection for uncontrolled usage. */
+        defaultSelection?: readonly RowId[];
+        onSelectionChange?: (ids: RowId[]) => void;
+        selectionMode?: SelectionMode;
+        /** Accessible name for the select-all header control. */
+        selectAllLabel: string;
+        /** Accessible name factory for row selection controls. */
+        rowSelectionLabel?: (row: Row) => string;
+        selectedCountLabel?: (count: number) => React.ReactNode;
+        renderSelectionActions?: (info: DataTableSelectionInfo) => React.ReactNode;
+      }
+  );
+
+export type DataTableProps<Row extends { id: string }> = {
+  columns: DataColumn<Row>[];
+  rows: Row[];
+  caption: string;
+  empty: React.ReactNode;
+  className?: string;
+  loading?: boolean;
+  /** Skeleton row count while `loading` is true. Default: 5. */
+  loadingRows?: number;
+  /** Visual rhythm: `regular` (default) or `compact` for dense workspaces. */
+  density?: 'compact' | 'regular';
+} & DataTableFeatureProps<Row>;
+
+/** Pagination state that keeps every row visible when paging is disabled. */
+const ALL_ROWS_PAGINATION = { pageIndex: 0, pageSize: Number.MAX_SAFE_INTEGER };
+
+export function DataTable<Row extends { id: string }>({
+  columns,
+  rows,
+  caption,
+  empty,
+  className,
+  loading = false,
+  loadingRows = 5,
+  density = 'regular',
+  sorting,
+  defaultSorting,
+  onSortingChange,
+  manualSorting,
+  filters,
+  defaultFilters,
+  onFiltersChange,
+  manualFiltering,
+  page,
+  onPageChange,
+  previousPageLabel,
+  nextPageLabel,
+  paginationLabel,
+  paginationStatus,
+  totalRowCount,
+  manualPagination,
+  selection,
+  defaultSelection,
+  onSelectionChange,
+  selectionMode = 'multiple',
+  selectAllLabel,
+  rowSelectionLabel,
+  selectedCountLabel,
+  renderSelectionActions,
+}: DataTableProps<Row>) {
+  const captionId = useId();
+  const selectionEnabled = selectAllLabel !== undefined;
+  const paginationEnabled = page !== undefined;
+
+  const [internalSorting, setInternalSorting] = useState<SortingState>(() =>
+    toTanStackSorting(defaultSorting ?? []),
+  );
+  const [internalFilters, setInternalFilters] = useState<ColumnFiltersState>(() =>
+    toTanStackFilters(defaultFilters ?? []),
+  );
+  const [internalSelection, setInternalSelection] = useState<RowSelectionState>(() =>
+    toTanStackSelection(defaultSelection ?? []),
+  );
+
+  const controlledSorting = useMemo(
+    () => (sorting !== undefined ? toTanStackSorting(sorting) : undefined),
+    [sorting],
+  );
+  const controlledFilters = useMemo(
+    () => (filters !== undefined ? toTanStackFilters(filters) : undefined),
+    [filters],
+  );
+  const controlledSelection = useMemo(
+    () => (selection !== undefined ? toTanStackSelection(selection) : undefined),
+    [selection],
+  );
+
+  const sortingState = controlledSorting ?? internalSorting;
+  const filtersState = controlledFilters ?? internalFilters;
+  const selectionState = controlledSelection ?? internalSelection;
+  const paginationState = useMemo(
+    () =>
+      page !== undefined ? { pageIndex: page.index, pageSize: page.size } : ALL_ROWS_PAGINATION,
+    [page],
+  );
+
+  const tanstackColumns = useMemo(() => toTanStackColumns(columns), [columns]);
+
+  const handleSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = functionalUpdate(updater, sortingState);
+    setInternalSorting(next);
+    onSortingChange?.(fromTanStackSorting(next));
+  };
+
+  const handleFiltersChange: OnChangeFn<ColumnFiltersState> = (updater) => {
+    const next = functionalUpdate(updater, filtersState);
+    setInternalFilters(next);
+    onFiltersChange?.(fromTanStackFilters(next));
+  };
+
+  const handleSelectionChange: OnChangeFn<RowSelectionState> = (updater) => {
+    const next = functionalUpdate(updater, selectionState);
+    setInternalSelection(next);
+    onSelectionChange?.(fromTanStackSelection(next));
+  };
+
+  const table = useTable({
+    features: noeTableFeatures,
+    columns: tanstackColumns,
+    data: rows,
+    getRowId: (row: Row) => row.id,
+    state: {
+      sorting: sortingState,
+      columnFilters: filtersState,
+      rowSelection: selectionState,
+      pagination: paginationState,
+    },
+    onSortingChange: handleSortingChange,
+    onColumnFiltersChange: handleFiltersChange,
+    onRowSelectionChange: handleSelectionChange,
+    enableMultiSort: false,
+    autoResetPageIndex: false,
+    ...(manualSorting !== undefined ? { manualSorting } : {}),
+    ...(manualFiltering !== undefined ? { manualFiltering } : {}),
+    ...(manualPagination !== undefined ? { manualPagination } : {}),
+    ...(totalRowCount !== undefined ? { rowCount: totalRowCount } : {}),
+  });
+
+  const modelRows = table.getRowModel().rows;
+  const selectedIds =
+    selection !== undefined ? [...selection] : fromTanStackSelection(selectionState);
+
+  const toggleRowSelection = (rowId: RowId) => {
+    const isSelected = selectedIds.includes(rowId);
+    if (selectionMode === 'single') {
+      handleSelectionChange(isSelected ? {} : toTanStackSelection([rowId]));
+      return;
+    }
+    handleSelectionChange(
+      toTanStackSelection(
+        isSelected ? selectedIds.filter((id) => id !== rowId) : [...selectedIds, rowId],
+      ),
+    );
+  };
+
+  const allRowsSelected = table.getIsAllRowsSelected();
+  const someRowsSelected = table.getIsSomeRowsSelected();
+
+  const pageSize = page?.size ?? ALL_ROWS_PAGINATION.pageSize;
+  const pageIndex = page?.index ?? 0;
+  const totalRows =
+    manualPagination === true
+      ? (totalRowCount ?? pageIndex * pageSize + modelRows.length)
+      : table.getSortedRowModel().rows.length;
+  const canPreviousPage = paginationEnabled && pageIndex > 0;
+  const canNextPage = paginationEnabled
+    ? manualPagination === true
+      ? totalRowCount !== undefined
+        ? (pageIndex + 1) * pageSize < totalRowCount
+        : modelRows.length === pageSize
+      : pageIndex + 1 < table.getPageCount()
+    : false;
+  const paginationInfo: DataTablePaginationStatusInfo | undefined = paginationEnabled
+    ? {
+        startIndex: totalRows === 0 ? 0 : pageIndex * pageSize + 1,
+        endIndex: Math.min(totalRows, (pageIndex + 1) * pageSize),
+        total: totalRows,
+      }
+    : undefined;
+
+  const cellPadding = density === 'compact' ? 'px-3 py-1.5' : 'px-4 py-2.5';
+
+  if (!loading && modelRows.length === 0) {
+    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>
+    );
+  }
+
+  const showSelectionBar =
+    selectionEnabled &&
+    selectedIds.length > 0 &&
+    (selectedCountLabel !== undefined || renderSelectionActions !== undefined);
+
+  return (
+    <div className={cn('flex flex-col gap-3', className)} data-slot="data-table-root">
+      {showSelectionBar ? (
+        <div
+          className="flex items-center gap-3 rounded-md border border-border bg-surface-sunken/40 px-4 py-2.5 text-sm"
+          data-slot="data-table-selection-bar"
+        >
+          {selectedCountLabel ? (
+            <span className="tabular-nums text-muted-foreground">
+              {selectedCountLabel(selectedIds.length)}
+            </span>
+          ) : null}
+          {renderSelectionActions ? (
+            <div className="ms-auto flex items-center gap-2">
+              {renderSelectionActions({ selectedIds })}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+      {/* WCAG 2.1: keyboard-accessible scrollable container for overflow tables. */}
+      <section
+        aria-labelledby={captionId}
+        className="overflow-x-auto rounded-lg border border-border"
+        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-density={density}
+          data-slot="data-table"
+        >
+          <caption className="sr-only" id={captionId}>
+            {caption}
+          </caption>
+          <thead>
+            <tr className="border-b border-border bg-surface-sunken/60">
+              {selectionEnabled && selectionMode === 'multiple' ? (
+                <th className={cn('w-10', cellPadding)} data-slot="data-table-select-header">
+                  <Checkbox
+                    aria-label={selectAllLabel}
+                    checked={allRowsSelected}
+                    onChange={() => table.toggleAllRowsSelected(!allRowsSelected)}
+                    ref={(element) => {
+                      if (element) element.indeterminate = someRowsSelected && !allRowsSelected;
+                    }}
+                  />
+                </th>
+              ) : null}
+              {columns.map((column) => {
+                const tanstackColumn = table.getColumn(column.key);
+                const canSort = tanstackColumn?.getCanSort() ?? false;
+                const sorted = tanstackColumn?.getIsSorted() ?? false;
+                return (
+                  <th
+                    aria-sort={
+                      sorted === 'asc'
+                        ? 'ascending'
+                        : sorted === 'desc'
+                          ? 'descending'
+                          : canSort
+                            ? 'none'
+                            : undefined
+                    }
+                    className={cn(
+                      'whitespace-nowrap text-xs font-medium text-muted-foreground',
+                      cellPadding,
+                      column.align === 'end' ? 'text-end' : 'text-start',
+                    )}
+                    data-align={column.align ?? 'start'}
+                    key={column.key}
+                    scope="col"
+                  >
+                    {canSort && tanstackColumn ? (
+                      <Button
+                        className="-ms-2 text-muted-foreground hover:text-foreground"
+                        data-slot="data-table-sort-button"
+                        onClick={(event) => tanstackColumn.getToggleSortingHandler()?.(event)}
+                        size="sm"
+                        variant="ghost"
+                      >
+                        {column.header}
+                        {sorted === 'desc' ? (
+                          <ArrowDown2 className="size-3.5" />
+                        ) : (
+                          <ArrowUp2 className={cn('size-3.5', sorted === false && 'opacity-40')} />
+                        )}
+                      </Button>
+                    ) : (
+                      column.header
+                    )}
+                  </th>
+                );
+              })}
+            </tr>
+          </thead>
+          <tbody>
+            {loading
+              ? Array.from(
+                  { length: loadingRows },
+                  (_, index) => `data-table-loading-${index}`,
+                ).map((rowKey) => (
+                  <tr
+                    className="border-b border-border last:border-b-0"
+                    data-slot="data-table-loading-row"
+                    key={rowKey}
+                  >
+                    {selectionEnabled ? (
+                      <td className={cellPadding}>
+                        <Skeleton className="size-4" />
+                      </td>
+                    ) : null}
+                    {columns.map((column) => (
+                      <td className={cellPadding} key={column.key}>
+                        <Skeleton className="h-4 w-full max-w-32" />
+                      </td>
+                    ))}
+                  </tr>
+                ))
+              : modelRows.map((tanstackRow) => {
+                  const row = tanstackRow.original;
+                  const isSelected = tanstackRow.getIsSelected();
+                  return (
+                    <tr
+                      className="border-b border-border last:border-b-0 hover:bg-muted/50"
+                      data-selected={isSelected || undefined}
+                      key={tanstackRow.id}
+                    >
+                      {selectionEnabled ? (
+                        <td className={cellPadding} data-slot="data-table-select-cell">
+                          <Checkbox
+                            aria-label={rowSelectionLabel?.(row)}
+                            checked={isSelected}
+                            onChange={() => toggleRowSelection(tanstackRow.id)}
+                          />
+                        </td>
+                      ) : null}
+                      {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 text-foreground',
+                              cellPadding,
+                              column.align === 'end' ? 'text-end' : 'text-start',
+                            )}
+                            data-align={column.align ?? 'start'}
+                            key={column.key}
+                          >
+                            {value}
+                          </td>
+                        );
+                      })}
+                    </tr>
+                  );
+                })}
+          </tbody>
+        </table>
+      </section>
+      {paginationEnabled && paginationInfo ? (
+        <Pagination
+          canNext={canNextPage}
+          canPrevious={canPreviousPage}
+          label={paginationLabel ?? caption}
+          nextLabel={nextPageLabel}
+          onNext={
+            canNextPage ? () => onPageChange({ index: pageIndex + 1, size: pageSize }) : undefined
+          }
+          onPrevious={
+            canPreviousPage
+              ? () => onPageChange({ index: pageIndex - 1, size: pageSize })
+              : undefined
+          }
+          previousLabel={previousPageLabel}
+          status={
+            paginationStatus
+              ? paginationStatus(paginationInfo)
+              : `${paginationInfo.startIndex}–${paginationInfo.endIndex} / ${paginationInfo.total}`
+          }
+        />
+      ) : null}
+    </div>
+  );
+}

package/packages/design-tokens/src/tokens.css

@@ -13,11 +13,11 @@
   --noe-primitive-color-ink-500: #565c58;
   --noe-primitive-color-ink-600: #302f2e;
   --noe-primitive-color-ink-700: #252423;
-  --noe-primitive-color-ink-800: #302f2e;
-  --noe-primitive-color-ink-850: #302f2e;
+  --noe-primitive-color-ink-800: #2a2a2a;
+  --noe-primitive-color-ink-850: #202020;
   --noe-primitive-color-ink-900: #171918;
-  --noe-primitive-color-ink-950: #252423;
-  --noe-primitive-color-ink-1000: #1c1b1b;
+  --noe-primitive-color-ink-950: #161616;
+  --noe-primitive-color-ink-1000: #111111;
   --noe-primitive-color-mint-100: #98e8cf;
   --noe-primitive-color-mint-200: #abefd9;
   --noe-primitive-color-mint-300: #1dbf98;
@@ -140,6 +140,8 @@
   --noe-color-surface: var(--noe-primitive-color-paper-50);
   --noe-color-surface-raised: var(--noe-primitive-color-paper-0);
   --noe-color-surface-sunken: var(--noe-primitive-color-paper-200);
+  --noe-color-sidebar: var(--noe-primitive-color-paper-200);
+  --noe-color-sidebar-active: var(--noe-primitive-color-paper-0);
   --noe-color-foreground: var(--noe-primitive-color-ink-900);
   --noe-color-muted: var(--noe-primitive-color-paper-200);
   --noe-color-muted-foreground: var(--noe-primitive-color-ink-500);
@@ -170,6 +172,8 @@
   --noe-color-surface: var(--noe-primitive-color-ink-850);
   --noe-color-surface-raised: var(--noe-primitive-color-ink-800);
   --noe-color-surface-sunken: var(--noe-primitive-color-ink-1000);
+  --noe-color-sidebar: var(--noe-primitive-color-ink-850);
+  --noe-color-sidebar-active: var(--noe-primitive-color-ink-800);
   --noe-color-foreground: var(--noe-primitive-color-paper-250);
   --noe-color-muted: var(--noe-primitive-color-ink-800);
   --noe-color-muted-foreground: var(--noe-primitive-color-ink-400);
@@ -201,6 +205,8 @@
     --noe-color-surface: var(--noe-primitive-color-ink-850);
     --noe-color-surface-raised: var(--noe-primitive-color-ink-800);
     --noe-color-surface-sunken: var(--noe-primitive-color-ink-1000);
+    --noe-color-sidebar: var(--noe-primitive-color-ink-850);
+    --noe-color-sidebar-active: var(--noe-primitive-color-ink-800);
     --noe-color-foreground: var(--noe-primitive-color-paper-250);
     --noe-color-muted: var(--noe-primitive-color-ink-800);
     --noe-color-muted-foreground: var(--noe-primitive-color-ink-400);

package/packages/design-tokens/src/tokens.json

@@ -15,11 +15,11 @@
         "500": "#565c58",
         "600": "#302f2e",
         "700": "#252423",
-        "800": "#302f2e",
-        "850": "#302f2e",
+        "800": "#2a2a2a",
+        "850": "#202020",
         "900": "#171918",
-        "950": "#252423",
-        "1000": "#1c1b1b"
+        "950": "#161616",
+        "1000": "#111111"
       },
       "mint": {
         "100": "#98e8cf",
@@ -106,6 +106,8 @@
       "surface": "{primitive.color.paper.50}",
       "surfaceRaised": "{primitive.color.paper.0}",
       "surfaceSunken": "{primitive.color.paper.200}",
+      "sidebar": "{primitive.color.paper.200}",
+      "sidebarActive": "{primitive.color.paper.0}",
       "foreground": "{primitive.color.ink.900}",
       "muted": "{primitive.color.paper.200}",
       "mutedForeground": "{primitive.color.ink.500}",
@@ -131,6 +133,8 @@
       "surface": "{primitive.color.ink.850}",
       "surfaceRaised": "{primitive.color.ink.800}",
       "surfaceSunken": "{primitive.color.ink.1000}",
+      "sidebar": "{primitive.color.ink.850}",
+      "sidebarActive": "{primitive.color.ink.800}",
       "foreground": "{primitive.color.paper.250}",
       "muted": "{primitive.color.ink.800}",
       "mutedForeground": "{primitive.color.ink.400}",

package/packages/design-tokens/src/tokens.mjs

@@ -16,11 +16,11 @@ export const tokens = {
         "500": "#565c58",
         "600": "#302f2e",
         "700": "#252423",
-        "800": "#302f2e",
-        "850": "#302f2e",
+        "800": "#2a2a2a",
+        "850": "#202020",
         "900": "#171918",
-        "950": "#252423",
-        "1000": "#1c1b1b"
+        "950": "#161616",
+        "1000": "#111111"
       },
       "mint": {
         "100": "#98e8cf",
@@ -107,6 +107,8 @@ export const tokens = {
       "surface": "{primitive.color.paper.50}",
       "surfaceRaised": "{primitive.color.paper.0}",
       "surfaceSunken": "{primitive.color.paper.200}",
+      "sidebar": "{primitive.color.paper.200}",
+      "sidebarActive": "{primitive.color.paper.0}",
       "foreground": "{primitive.color.ink.900}",
       "muted": "{primitive.color.paper.200}",
       "mutedForeground": "{primitive.color.ink.500}",
@@ -132,6 +134,8 @@ export const tokens = {
       "surface": "{primitive.color.ink.850}",
       "surfaceRaised": "{primitive.color.ink.800}",
       "surfaceSunken": "{primitive.color.ink.1000}",
+      "sidebar": "{primitive.color.ink.850}",
+      "sidebarActive": "{primitive.color.ink.800}",
       "foreground": "{primitive.color.paper.250}",
       "muted": "{primitive.color.ink.800}",
       "mutedForeground": "{primitive.color.ink.400}",

package/packages/registry/catalog-index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-29T09:30:43.936Z",
+  "generatedAt": "2026-08-30T12:09:40.539Z",
   "items": [
     {
       "id": "bidi-text",
@@ -208,7 +208,7 @@
       "package": "@noe/data-ui",
       "status": "available",
       "maturity": "beta",
-      "description": "Data Table — Data component. data-table provides data behavior with RTL, i18n and accessibility built-in.",
+      "description": "Semantic data table with TanStack Table v9 as a headless engine behind the internal NOE adapter: sorting, NOE filter operators, controlled pagination, stable-id selection, loading skeletons and server mode.",
       "registryItem": "data-table"
     },
     {