@assure-one/design-system 1.37.0 → 1.38.0

package/README.md

@@ -16,6 +16,7 @@ The single source of truth for visual design across all Assure products.
 - [**`docs/integration/css.md`**](./docs/integration/css.md) — how an application loads our CSS: layer order, import sequence, the compatibility preset, removing `@source`, runtime brand theming.
 - [**`docs/testing.md`**](./docs/testing.md) — rendering the real package in your app's Jest tests (`@assure-one/design-system/testing`, experimental).
 - [**`docs/forms.md`**](./docs/forms.md) — building a form: `Field` + design-system controls + a Server Action + zod, reset and `required`, what each control submits, and testing it with `fillField` / `selectOption` / `pickDate`.
+- [**`docs/data-tables.md`**](./docs/data-tables.md) — building a data table: the headless `useDataTable` controller (sorting, pagination, search, selection, column visibility, filters — each controllable), server `manual` mode, and the URL-state recipe.
 - [**`docs/design-system/icons.md`**](./docs/design-system/icons.md) — the icon catalogue and its server-safe entry (`@assure-one/design-system/icons`, experimental): import an icon in a Server Component without a client boundary.
 - [**`docs/adr/010-design-system-provider.md`**](./docs/adr/010-design-system-provider.md) — the optional `DesignSystemProvider` (messages, locale, link adapter) and the `/next` entry; the quick start is [below](#the-provider-and-the-next-entry-experimental).
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
@@ -52,14 +53,14 @@ Alongside it, the package now also publishes the individual stylesheets the new
 CSS mode is built from. They are **experimental**: nothing requires them yet,
 no component reads them, and importing them changes nothing on its own.
 
-| Subpath | What it is |
-| --- | --- |
-| `./css/tokens.css` | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component. |
-| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names. |
-| `./css/tailwind.css` | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in *your* build instead of silently producing nothing. |
-| `./css/shadcn.css` | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override. |
-| `./css/base.css` | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import. |
-| `./css/components.css` | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
+| Subpath                    | What it is                                                                                                                                                                                                                                                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `./css/tokens.css`         | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component.                                                                                                                                                                                                                                              |
+| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names.                                                                                                                                                                                       |
+| `./css/tailwind.css`       | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in _your_ build instead of silently producing nothing.                                                                                                                                                                                                        |
+| `./css/shadcn.css`         | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override.                                                                                                                                                                                   |
+| `./css/base.css`           | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import.                                                                                                                                                                                                                           |
+| `./css/components.css`     | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
 
 Import order is `tokens.css` → `legacy-aliases.css` (optional) → `tailwind.css`
 → `shadcn.css` (optional) → `base.css` (optional) → `components.css`, after your own
@@ -119,11 +120,11 @@ export default function RootLayout({ children }) {
 
 - **`messages`** — any subset of the typed catalogue `DsMessages`, by component
   namespace (`select`, `searchInput`, `combobox`, `field`, `fileUpload`; more
-  join as the overlays adopt it). Resolution is always *component prop >
-  provider > English default*, per key. The full English list is
+  join as the overlays adopt it). Resolution is always _component prop >
+  provider > English default_, per key. The full English list is
   `src/foundation/messages/en.json`; parameterised messages are functions
   (`combobox.create: (query) => string`).
-- **`locale`** — a BCP 47 tag, default `"en-US"` on the server *and* the client.
+- **`locale`** — a BCP 47 tag, default `"en-US"` on the server _and_ the client.
   Pass the locale your app already knows server-side; the design system never
   reads `navigator.language` during render, so server and client HTML agree.
 - **`linkComponent` / `imageComponent`** — what `LinkButton` and `Logo` render
@@ -136,6 +137,34 @@ export default function RootLayout({ children }) {
   the props. `toasts` mounts the toast region for `useToast()`; leave it off if
   you already render `ToastProvider`.
 
+## Lint configs for consumers
+
+Two shareable configs ship with the package (**experimental**, W7-18) so a
+product lints for the same things this repository ratchets on itself. Every
+rule is a **warning**: adopt it on the code you have, record the count, and
+ratchet it down.
+
+```js
+// eslint.config.mjs
+import ds from "@assure-one/design-system/eslint-config";
+export default [...ds.configs.recommended];
+
+// stylelint.config.mjs  (stylelint is yours — an optional peer dependency here)
+export { default } from "@assure-one/design-system/stylelint-config";
+```
+
+| Rule                                     | Reports                                                                                  |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `ds/no-raw-controls`                     | raw `<button>`, `<input>`, `<select>`, `<textarea>` where a design-system control exists |
+| `ds/no-radix-imports`                    | a direct `@radix-ui/*` import instead of the primitive that wraps it                     |
+| `ds/no-deep-imports`                     | an import past the published entries (`dist/…`, `src/…` — ADR-011)                       |
+| `ds/no-ds-token-redefinition`            | a `--ds-*` token set inline, outside a file under `presets/`                             |
+| `assure-ds/no-ds-token-redefinition`     | the same in CSS (stylelint; `presets/` and `*.preset.css` are exempt)                    |
+| `assure-ds/no-important-on-ds-selectors` | `!important` on a `ds:`/`data-slot` selector — pass `className`/`classNames` instead     |
+
+Raise a rule to `"error"` in your own config once you are clean. Adoption per
+app is tracked as W7-19.
+
 ## Develop
 
 ```bash
@@ -153,11 +182,11 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full dev loop, including iter
 3-tier token system, authored as DTCG JSON in [`tokens/src`](./tokens/README.md)
 and generated into `src/tokens/` and the `./css/*` entries (ADR-003):
 
-| Tier | Example (namespaced name → value) | Reads |
-| --- | --- | --- |
-| reference | `--ds-ref-brand-pro-fg: #6c42f8` | a literal; the raw ramps, one per brand |
-| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract** |
-| component | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
+| Tier              | Example (namespaced name → value)                        | Reads                                                               |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
+| reference         | `--ds-ref-brand-pro-fg: #6c42f8`                         | a literal; the raw ramps, one per brand                             |
+| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract**                 |
+| component         | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
 
 Components consume **system tokens**, never reference values directly. Themes
 (colour scheme, per-product brand, a runtime brand from `createBrandTheme()`)

package/codemods/README.md

@@ -120,6 +120,7 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 | CM-10 | R     | `DatePicker onChange={e => f(e.target.value)}` → `onValueChange={value => f(value)}` for the recognisable arrow shapes; handlers by reference, other shapes → report          |
 | CM-08 | R     | `SearchSelect` → `Combobox`: single-mode call sites rewritten (tag, import, `{id,label}` accessors, placeholder → `aria-label`); multi API, extras and unnamed sites → report |
 | CM-09 | R     | `SideDrawer` → `Sheet`: drawers with a `SideDrawer.Header` rewritten (root → `Sheet` + `SheetContent side size`, `onClose` → `onOpenChange`, header → `SheetHeader`/`SheetTitle`/`SheetDescription`, Body/Footer → `SheetBody`/`SheetFooter`, import); no header, dynamic width, spreads → report |
+| CM-18 | A     | `DataTable*` presentational parts → `Table*` (`DataTableHead` → `TableHeader`, `Body`, `Row`, `Cell`, `DataTableHeader` → `TableHead`) where the mapping is 1:1; uncontrolled sorting, a dynamic `sortable` and spreads → "could not be transformed"                    |
 | CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                                                              |
 | CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids                                             |
 | CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()`                                           |
@@ -493,6 +494,45 @@ Not touched: elements already on `Sheet` (idempotency), local components with
 the same name, test files. The rewritten children are re-indented one level;
 run the project's formatter afterwards.
 
+### CM-18 — `DataTable*` parts → `Table*`
+
+Class A. W6-03 made the `DataTable*` table parts aliases of the `Table*` parts
+(contract C-DT-PARTS, removed in 3.0): one styling source, the same props. The
+1:1 parts are a pure rename — tag, closing tag and the named import:
+
+| from              | to            |
+| ----------------- | ------------- |
+| `DataTableHead`   | `TableHeader` |
+| `DataTableBody`   | `TableBody`   |
+| `DataTableRow`    | `TableRow`    |
+| `DataTableCell`   | `TableCell`   |
+| `DataTableHeader` | `TableHead`   |
+
+`DataTableHeader sortable sort={…} onSortChange={…}` loses the `sortable`
+attribute: `TableHead` sorts whenever `sort` is passed (`null` = sortable, not
+sorted). What changes in the DOM is the `data-slot` value (`table-*` instead of
+`data-table-*`) and the dropped `scope="col"` — a `<th>` in a `<thead>` is a
+column header already. Classes and pixels are the same, because since W6-03 the
+`DataTable*` parts render the `Table*` parts.
+
+| rule            | Contract   | What happens                                                        |
+| --------------- | ---------- | ------------------------------------------------------------------- |
+| `part-renamed`  | C-DT-PARTS | tag, closing tag and the named import rewritten (applied, low)      |
+
+Reported under "could not be transformed": `DataTableHeader sortable` with no
+controlled `sort`, or with `defaultSort` (`uncontrolled-sort` — `TableHead` has
+no uncontrolled sort state; wire `sort` + `onSortChange`, e.g. from
+`useDataTable`); `sortable={expr}` (`dynamic-sortable`); a spread on the header
+(`spread-props`).
+
+Not touched: the parts that are not parallel copies of a `Table*` part —
+`DataTable` (the card frame), `DataTableToolbar`, `DataTableSearch`,
+`DataTableSpacer`, `DataTableResultsCount`, `DataTableCellName` / `CellMono` /
+`CellId` / `CellDue`, `DataTableCheckbox`, `DataTablePagination` — an aliased
+import (`DataTableCell as Cell`), a namespace import, local components with the
+same names, and test files. A file that still refers to the old name as a value
+(`typeof DataTableCell`) keeps its import and gains the new name next to it.
+
 ### CM-15 — DOM-selector finder
 
 Report-only. It never modifies a file; the runner throws if it tries. What it

package/codemods/lib/registry.mjs

@@ -14,6 +14,7 @@ export const CODEMODS = [
   { id: "CM-10", module: "../transforms/cm-10-date-picker-value-change.mjs" },
   { id: "CM-08", module: "../transforms/cm-08-search-select-to-combobox.mjs" },
   { id: "CM-09", module: "../transforms/cm-09-side-drawer-to-sheet.mjs" },
+  { id: "CM-18", module: "../transforms/cm-18-data-table-parts.mjs" },
   { id: "CM-14", module: "../transforms/cm-14-hidden-mirrors.mjs" },
   { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
   { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },

package/codemods/transforms/cm-18-data-table-parts.mjs

@@ -0,0 +1,234 @@
+/**
+ * CM-18 — `DataTable*` presentational parts → `Table*` (class A; plan §29
+ * seq 12, registry `C-DT-PARTS`, lands with W6-03).
+ *
+ * W6-03 made the `DataTable*` table parts thin aliases of the `Table*` parts:
+ * one styling source, the same props. Where a part is a 1:1 copy the rename
+ * is mechanical and this codemod applies it — tag, closing tag and the named
+ * import:
+ *
+ * | from              | to            | note                                                        |
+ * | ----------------- | ------------- | ----------------------------------------------------------- |
+ * | `DataTableHead`   | `TableHeader` | `<thead>`                                                    |
+ * | `DataTableBody`   | `TableBody`   | `<tbody>`                                                    |
+ * | `DataTableRow`    | `TableRow`    | `selected` is the same prop                                  |
+ * | `DataTableCell`   | `TableCell`   | same props (`align`, `numeric`, `muted`, `truncate`, `width`)|
+ * | `DataTableHeader` | `TableHead`   | plain, or controlled `sortable sort onSortChange` — `sortable` is dropped because `TableHead` is sortable whenever `sort` is passed |
+ *
+ * What changes for the rendered DOM: the `data-slot` attributes read
+ * `table-*` instead of `data-table-*`, and `TableHead` does not stamp
+ * `scope="col"` (a `<th>` inside `<thead>` is a column header by default).
+ * Classes, geometry and colours are the same — the `DataTable*` parts render
+ * through the `Table*` parts since W6-03.
+ *
+ * ## What it leaves alone, and lists under "could not be transformed"
+ *
+ * - `DataTableHeader sortable` **without** a controlled `sort` (uncontrolled
+ *   sorting, `defaultSort`): `TableHead` has no uncontrolled sort state — the
+ *   consumer wires `sort` from `useDataTable` or its own state.
+ * - `DataTableHeader sortable={expr}`: whether the header is sortable is not
+ *   visible here.
+ * - `DataTableHeader {...props}`: the spread may carry `sortable`.
+ *
+ * Not touched at all (not parallel copies of a `Table*` part, they stay):
+ * `DataTable` (the card frame), `DataTableToolbar`, `DataTableSearch`,
+ * `DataTableSpacer`, `DataTableResultsCount`, `DataTableCellName` /
+ * `DataTableCellMono` / `DataTableCellId` / `DataTableCellDue`,
+ * `DataTableCheckbox`, `DataTablePagination`, and the `DataTable*Props` types.
+ * An aliased import (`DataTableCell as Cell`) and a namespace import are left
+ * alone too. The import specifier is rewritten only when no reference to the
+ * old name remains in the file (a `typeof DataTableCell` keeps it, and the
+ * new name is added next to it). Local components with the same names are
+ * not touched; test files are skipped, as by the scanner that measures
+ * C-DT-PARTS.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyEdits, openingOf, removeAttribute } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-18",
+  title: "DataTable* presentational parts → Table* (pure rename where the part is a 1:1 copy)",
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-DT-PARTS"],
+};
+
+/** `DataTable*` part → the `Table*` part it aliases (src/composites/data-table.tsx, W6-03). */
+export const PART_MAP = {
+  DataTableHead: "TableHeader",
+  DataTableBody: "TableBody",
+  DataTableRow: "TableRow",
+  DataTableCell: "TableCell",
+  DataTableHeader: "TableHead",
+};
+
+export const RULES = {
+  "part-renamed": { action: "applied", severity: "low" },
+};
+
+const DS_PACKAGE = "@assure-one/design-system";
+
+/**
+ * Identifier references to `name` outside its import specifier and outside
+ * JSX tag names — `typeof DataTableCell`, `as={DataTableCell}`, a plain
+ * value use. While one exists the old import must stay.
+ */
+function hasOtherReferences(ts, sf, name) {
+  let found = false;
+  const visit = (node) => {
+    if (found) return;
+    if (ts.isIdentifier(node) && node.text === name) {
+      const parent = node.parent;
+      const isImport = parent && ts.isImportSpecifier(parent);
+      const isTag =
+        parent &&
+        (ts.isJsxOpeningElement(parent) ||
+          ts.isJsxSelfClosingElement(parent) ||
+          ts.isJsxClosingElement(parent)) &&
+        parent.tagName === node;
+      if (!isImport && !isTag) found = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const sf = facts.sf;
+  const findings = [];
+  const notTransformed = [];
+  const edits = [];
+  /** old local name → new name, for the elements that were renamed */
+  const renamed = new Map();
+  /** old local names that still have an element on them */
+  const remaining = new Set();
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !PART_MAP[el.base] || el.component !== el.base) continue;
+    // An aliased import (`DataTableCell as Cell`): the local name is not the part's.
+    if (el.tag !== el.base) {
+      remaining.add(el.tag);
+      continue;
+    }
+    const to = PART_MAP[el.base];
+    const opening = openingOf(ts, el.node);
+    const inner = [];
+    let sortableDropped = false;
+
+    if (el.base === "DataTableHeader") {
+      const sortable = el.props.get("sortable");
+      if (el.spread) {
+        notTransformed.push({
+          line: el.line,
+          reason: "spread-props",
+          detail: `<${el.tag} {…}> — the spread may carry \`sortable\`; rename to \`TableHead\` by hand once you know it does not`,
+        });
+        remaining.add(el.tag);
+        continue;
+      }
+      if (sortable) {
+        if (sortable.text !== "true") {
+          notTransformed.push({
+            line: el.line,
+            reason: "dynamic-sortable",
+            detail: `<${el.tag} sortable={…}> — whether the header sorts is not visible here; \`TableHead\` sorts whenever \`sort\` is passed`,
+          });
+          remaining.add(el.tag);
+          continue;
+        }
+        if (!el.props.has("sort") || el.props.has("defaultSort")) {
+          notTransformed.push({
+            line: el.line,
+            reason: "uncontrolled-sort",
+            detail: `<${el.tag} sortable> without a controlled \`sort\` — \`TableHead\` has no uncontrolled sort state; wire \`sort\` + \`onSortChange\` (from \`useDataTable\`) first`,
+          });
+          remaining.add(el.tag);
+          continue;
+        }
+        const drop = removeAttribute(ts, sf, opening, "sortable");
+        if (drop) {
+          inner.push(drop);
+          sortableDropped = true;
+        }
+      } else if (el.props.has("defaultSort")) {
+        notTransformed.push({
+          line: el.line,
+          reason: "uncontrolled-sort",
+          detail: `<${el.tag} defaultSort> — \`TableHead\` has no uncontrolled sort state`,
+        });
+        remaining.add(el.tag);
+        continue;
+      }
+    }
+
+    inner.push({ pos: opening.tagName.getStart(sf), end: opening.tagName.getEnd(), text: to });
+    if (ts.isJsxElement(el.node)) {
+      const closing = el.node.closingElement.tagName;
+      inner.push({ pos: closing.getStart(sf), end: closing.getEnd(), text: to });
+    }
+    edits.push(...inner);
+    renamed.set(el.base, to);
+    findings.push({
+      line: el.line,
+      registryId: "C-DT-PARTS",
+      rule: "part-renamed",
+      match: `<${el.tag}>`,
+      component: el.component,
+      action: "applied",
+      gate: null,
+      severity: RULES["part-renamed"].severity,
+      detail: { from: el.base, to, sortableDropped },
+    });
+  }
+
+  // The import: each renamed name becomes its `Table*` part when nothing else
+  // in the file still refers to it; otherwise the new name is added next to it.
+  if (renamed.size) {
+    for (const stmt of sf.statements) {
+      if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+      const spec = stmt.moduleSpecifier.text;
+      if (spec !== DS_PACKAGE && !spec.startsWith(`${DS_PACKAGE}/`)) continue;
+      const bindings = stmt.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      const present = new Set(bindings.elements.map((e) => e.name.text));
+      const list = bindings.elements;
+      for (const [from, to] of renamed) {
+        const index = list.findIndex((e) => !e.propertyName && e.name.text === from);
+        if (index < 0) continue;
+        const element = list[index];
+        const keep = remaining.has(from) || hasOtherReferences(ts, sf, from);
+        if (keep) {
+          if (!present.has(to)) {
+            edits.push({ pos: element.getEnd(), text: `, ${to}` });
+            present.add(to);
+          }
+          continue;
+        }
+        if (present.has(to)) {
+          // `TableCell` is already imported: the old specifier goes.
+          const fromPos = index === 0 ? element.getStart(sf) : list[index - 1].getEnd();
+          const toPos = index === 0 && list.length > 1 ? list[1].getStart(sf) : element.getEnd();
+          edits.push({ pos: fromPos, end: toPos, text: "" });
+        } else {
+          edits.push({ pos: element.getStart(sf), end: element.getEnd(), text: to });
+          present.add(to);
+        }
+      }
+    }
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+  };
+}