@assure-one/design-system 1.37.0 → 1.39.0

package/codemods/transforms/cm-01-entry-imports.mjs

@@ -0,0 +1,202 @@
+/**
+ * CM-01 — root imports → `/suite` and `/legacy` (class R; plan §29 seq 1,
+ * registry `C-ROOT-SUITE`, lands with W8-02).
+ *
+ * W8-02 gave the shared Assure patterns their own entry and put the frozen and
+ * product-owned modules behind `/legacy`. Both are re-export barrels over the
+ * very same module instances the root exports, so moving an import is a pure
+ * path change: no duplicated context, no behaviour difference, nothing to test
+ * afterwards. The root keeps the names through 1.x and drops them in 2.0.
+ *
+ * ## What it rewrites
+ *
+ * ```tsx
+ * import { Button, AgreementViewer, TimeLogger } from "@assure-one/design-system";
+ * ```
+ *
+ * becomes
+ *
+ * ```tsx
+ * import { Button } from "@assure-one/design-system";
+ * import { AgreementViewer } from "@assure-one/design-system/suite";
+ * import { TimeLogger } from "@assure-one/design-system/legacy";
+ * ```
+ *
+ * A declaration whose names all move keeps its shape and only its module
+ * specifier changes. `import type` and per-specifier `type` prefixes, aliases
+ * (`X as Y`), quote style and a default import are preserved; the default
+ * import always stays on the root.
+ *
+ * Which entry owns which name comes from `codemods/lib/entry-map.mjs`, which
+ * `pnpm entry-map` generates from `architecture/entry-map.json` — so the
+ * installed copy of the codemod always knows the map of its own version.
+ *
+ * ## What it reports
+ *
+ * | rule               | action  | severity | why                                                                                     |
+ * | ------------------ | ------- | -------- | --------------------------------------------------------------------------------------- |
+ * | `moved-to-suite`   | applied | low      | shared Assure patterns now import from `/suite`                                          |
+ * | `moved-to-legacy`  | applied | low      | frozen modules with no known consumer now import from `/legacy`                          |
+ * | `product-owned`    | applied | medium   | the import moved to `/legacy`, but the module is leaving for a product repository        |
+ * | `namespace-import` | review  | high     | `import * as DS` cannot be split; the named members have to be imported one by one first |
+ *
+ * Imports already on `/suite` or `/legacy` are not touched (idempotency), and
+ * neither is a name the root still owns. Test files are skipped.
+ */
+import { ENTRY_BY_SYMBOL, ENTRY_SPECIFIER, PRODUCT_TARGET } from "../lib/entry-map.mjs";
+import { applyEdits } from "../lib/jsx-edit.mjs";
+import { analyseForms } from "../lib/forms.mjs";
+
+export const meta = {
+  id: "CM-01",
+  title: "Root imports of suite, legacy and product-owned names → /suite and /legacy",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-ROOT-SUITE"],
+};
+
+export const RULES = {
+  "moved-to-suite": { action: "applied", severity: "low" },
+  "moved-to-legacy": { action: "applied", severity: "low" },
+  "product-owned": { action: "applied", severity: "medium" },
+  "namespace-import": { action: "review", severity: "high" },
+};
+
+const ROOT = "@assure-one/design-system";
+
+/** The entry that owns an imported name, or `null` when the root keeps it. */
+export const entryOf = (name) => ENTRY_BY_SYMBOL[name] ?? null;
+
+const ruleFor = (name, entry) =>
+  PRODUCT_TARGET[name] ? "product-owned" : entry === "suite" ? "moved-to-suite" : "moved-to-legacy";
+
+/** One `import …` statement built from the specifiers of the original one. */
+function declaration({ typeOnly, defaultName, specifiers, quote, semi }, specifier) {
+  const clause = [defaultName, specifiers.length ? `{ ${specifiers.join(", ")} }` : null].filter(
+    Boolean,
+  );
+  return `import ${typeOnly ? "type " : ""}${clause.join(", ")} from ${quote}${specifier}${quote}${semi}`;
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const sf = facts.sf;
+  const findings = [];
+  const edits = [];
+
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (stmt.moduleSpecifier.text !== ROOT) continue;
+    const clause = stmt.importClause;
+    if (!clause) continue;
+
+    const line = sf.getLineAndCharacterOfPosition(stmt.getStart(sf)).line + 1;
+    const base = { line, registryId: "C-ROOT-SUITE", component: null, gate: null };
+
+    // `import * as DS` — the members are reached through the namespace, so the
+    // import cannot be split by name. Only worth reporting when the file
+    // actually reads a name that moved.
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+      const ns = clause.namedBindings.name.text;
+      const used = new Set();
+      const visit = (node) => {
+        if (
+          ts.isPropertyAccessExpression(node) &&
+          ts.isIdentifier(node.expression) &&
+          node.expression.text === ns &&
+          entryOf(node.name.text)
+        ) {
+          used.add(node.name.text);
+        }
+        if (ts.isQualifiedName(node) && ts.isIdentifier(node.left) && node.left.text === ns) {
+          if (entryOf(node.right.text)) used.add(node.right.text);
+        }
+        ts.forEachChild(node, visit);
+      };
+      ts.forEachChild(sf, visit);
+      if (used.size) {
+        findings.push({
+          ...base,
+          rule: "namespace-import",
+          ...RULES["namespace-import"],
+          match: `import * as ${ns}`,
+          detail: { namespace: ns, symbols: [...used].sort() },
+        });
+      }
+      continue;
+    }
+
+    const named = clause.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+
+    const buckets = { root: [], suite: [], legacy: [] };
+    const movedNames = { suite: [], legacy: [] };
+    for (const element of named.elements) {
+      const imported = (element.propertyName ?? element.name).text;
+      const entry = entryOf(imported);
+      const bucket = entry ?? "root";
+      buckets[bucket].push(element.getText(sf));
+      if (entry) movedNames[entry].push(imported);
+    }
+    if (!movedNames.suite.length && !movedNames.legacy.length) continue;
+
+    const text = stmt.getText(sf);
+    const shape = {
+      typeOnly: clause.isTypeOnly,
+      defaultName: clause.name ? clause.name.text : null,
+      quote: stmt.moduleSpecifier.getText(sf)[0],
+      semi: text.endsWith(";") ? ";" : "",
+    };
+    const rows = [];
+    if (buckets.root.length || shape.defaultName) {
+      rows.push(declaration({ ...shape, specifiers: buckets.root }, ROOT));
+    }
+    for (const entry of ["suite", "legacy"]) {
+      if (!buckets[entry].length) continue;
+      rows.push(
+        declaration(
+          { ...shape, defaultName: null, specifiers: buckets[entry] },
+          ENTRY_SPECIFIER[entry],
+        ),
+      );
+    }
+    edits.push({ pos: stmt.getStart(sf), end: stmt.getEnd(), text: rows.join("\n") });
+
+    for (const entry of ["suite", "legacy"]) {
+      const byRule = new Map();
+      for (const name of movedNames[entry]) {
+        const rule = ruleFor(name, entry);
+        if (!byRule.has(rule)) byRule.set(rule, []);
+        byRule.get(rule).push(name);
+      }
+      for (const [rule, names] of byRule) {
+        findings.push({
+          ...base,
+          rule,
+          ...RULES[rule],
+          match: `{ ${names.sort().join(", ")} }`,
+          detail: {
+            from: ROOT,
+            to: ENTRY_SPECIFIER[entry],
+            symbols: names,
+            ...(rule === "product-owned"
+              ? { owners: [...new Set(names.map((n) => PRODUCT_TARGET[n]))].sort() }
+              : {}),
+          },
+        });
+      }
+    }
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

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

package/dist/brand-theme-B6rem2II.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The seed a host supplies per tenant.
+ *
+ * @experimental Gated by decision D7.
+ */
+interface BrandThemeSeed {
+    /**
+     * The brand fill, as `#rgb` or `#rrggbb`. Drives the `action.brand` family,
+     * the focus ring and the brand gradient.
+     */
+    brand: string;
+    /**
+     * An optional second hue for the `action.accent` family, as `#rgb` or
+     * `#rrggbb`. `undefined` or `null` means "the same as `brand`", which is what
+     * the built-in `[data-ds-brand]` scopes do.
+     */
+    accent?: string | null;
+}
+/** Every custom property `createBrandTheme()` sets, in output order. */
+declare const BRAND_THEME_PROPERTIES: readonly ["--ds-color-action-brand-bg", "--ds-color-action-brand-bg-hover", "--ds-color-action-brand-bg-active", "--ds-color-action-brand-bg-disabled", "--ds-color-action-brand-subtle-bg", "--ds-color-action-brand-subtle-bg-hover", "--ds-color-action-brand-subtle-bg-active", "--ds-color-action-brand-border", "--ds-color-action-brand-ring", "--ds-color-action-brand-fg", "--ds-color-action-accent-bg", "--ds-color-action-accent-bg-strong", "--ds-color-action-accent-bg-hover", "--ds-color-action-accent-bg-active", "--ds-color-action-accent-subtle-bg", "--ds-color-action-accent-ring", "--ds-color-action-accent-fg", "--ds-color-border-focus", "--ds-focus-ring-color", "--ds-focus-ring-border", "--ds-gradient-brand", "--ds-compat-color-brand-soft", "--ds-compat-color-brand-soft-foreground"];
+/** One of the custom properties `createBrandTheme()` sets. */
+type BrandThemeProperty = (typeof BRAND_THEME_PROPERTIES)[number];
+/**
+ * The style object `createBrandTheme()` returns: every property of
+ * {@link BRAND_THEME_PROPERTIES} with a CSS value.
+ *
+ * React types `style` as `CSSProperties`, which has no index signature for
+ * custom properties, so spread it or cast it at the call site:
+ * `style={{ ...createBrandTheme(seed) }}`.
+ *
+ * @experimental Gated by decision D7.
+ */
+type BrandTheme = {
+    readonly [P in BrandThemeProperty]: string;
+};
+/**
+ * Turn a tenant's colours into the design system's brand and accent tokens.
+ *
+ * ```tsx
+ * const theme = createBrandTheme({ brand: firm.primaryColor, accent: firm.accentColor });
+ * return <div style={{ ...theme }}>{children}</div>;
+ * ```
+ *
+ * Apply it to the element that scopes the brand — `<body>` for a whole-tenant
+ * theme, a wrapper for a preview. The properties are the same ones a built-in
+ * `[data-ds-brand]` scope declares, so anything reading them (every design
+ * system component, and any application CSS reading `--ds-*`) follows.
+ *
+ * @param seed - `brand`, and optionally `accent` (decision D7).
+ * @returns A frozen object of custom property names to CSS values.
+ * @throws TypeError when the seed is not an object, carries an unknown key, or
+ * a colour is missing or not `#rgb`/`#rrggbb`.
+ *
+ * @experimental Gated by decision D7. The property set may grow, and the seed
+ * shape may change, until D7 is resolved.
+ */
+declare function createBrandTheme(seed: BrandThemeSeed): BrandTheme;
+
+export { BRAND_THEME_PROPERTIES as B, type BrandTheme as a, type BrandThemeProperty as b, type BrandThemeSeed as c, createBrandTheme as d };