npm - @assure-one/design-system - Versions diffs - 1.30.0 → 1.32.0 - Mend

@assure-one/design-system 1.30.0 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/README.md +28 -1
package/codemods/0.2.0-radix-migration.mjs +315 -0
package/codemods/README.md +305 -0
package/codemods/lib/css-selectors.mjs +33 -0
package/codemods/lib/css-values.mjs +223 -0
package/codemods/lib/ds-stylesheet.mjs +168 -0
package/codemods/lib/environment.mjs +72 -0
package/codemods/lib/files.mjs +100 -0
package/codemods/lib/jsx.mjs +0 -0
package/codemods/lib/ledger.mjs +84 -0
package/codemods/lib/registry.mjs +30 -0
package/codemods/lib/report.mjs +119 -0
package/codemods/lib/runner.mjs +164 -0
package/codemods/run.mjs +161 -0
package/codemods/transforms/cm-15-dom-selectors.mjs +573 -0
package/codemods/transforms/cm-16-globals-css.mjs +487 -0
package/dist/css/base.css +60 -0
package/dist/css/legacy-aliases.css +489 -0
package/dist/css/shadcn.css +155 -0
package/dist/css/tailwind.css +233 -0
package/dist/css/tokens.css +439 -0
package/dist/index.d.ts +327 -33
package/dist/index.js +1843 -706
package/dist/index.js.map +1 -1
package/dist/styles.css +1 -1
package/dist/testing/index.cjs +458 -0
package/dist/testing/index.d.cts +253 -0
package/dist/testing/index.d.ts +253 -0
package/dist/testing/index.js +452 -0
package/dist/testing/setup.cjs +123 -0
package/dist/testing/setup.js +121 -0
package/dist/testing/style-stub.cjs +7 -0
package/dist/testing/style-stub.js +5 -0
package/dist/tokens/index.d.ts +114 -96
package/dist/tokens/index.js +67 -48
package/dist/tokens/index.js.map +1 -1
package/package.json +84 -14

package/codemods/transforms/cm-16-globals-css.mjs ADDED Viewed

@@ -0,0 +1,487 @@
+/**
+ * CM-16 — `globals.css` analyser (class X, report-only; plan §29, feeds §12
+ * and the 2.0 gates G1/G2).
+ *
+ * Every consumer renders design-system components on top of its own
+ * independently compiled Tailwind stylesheet, and [CU §12.1] shows that the
+ * application — not the design system — decides what a DS component looks
+ * like. CM-16 finds the five mechanisms that make that true, in the app's own
+ * CSS, with a line number for each:
+ *
+ * | rule                       | contract        | gate | what it is                                                  |
+ * | -------------------------- | --------------- | ---- | ----------------------------------------------------------- |
+ * | `source-into-ds`           | C-CSS-SOURCE    | G2   | `@source` pointing into the design-system package           |
+ * | `ds-styles-import`         | C-CSS-STYLES    | G1   | the all-in-one `styles.css` is loaded                       |
+ * | `duplicate-preflight`      | C-CSS-STYLES    | G1   | the app compiles a second Tailwind preflight                |
+ * | `theme-collision-differs`  | C-TOKENS-LEGACY | —    | `@theme` key that shadows a DS token with another value     |
+ * | `theme-collision-equal`    | C-TOKENS-LEGACY | —    | the same name, the same value today                         |
+ * | `legacy-var-write`         | C-TOKENS-WRITE  | —    | a DS token name declared outside `@theme` ([CU §12.3])      |
+ * | `legacy-var-read`          | C-TOKENS-LEGACY | —    | `var(--<ds token>)` read by app CSS                         |
+ * | `brand-scope-spelling`     | C-CSS-DARKCLASS | —    | DS tokens re-declared under `.dark` / `[data-brand="…"]`    |
+ * | `dark-variant-mismatch`    | C-CSS-DARKCLASS | —    | app `dark` variant that cannot match the `.dark` element    |
+ * | `unlayered-ds-dom`         | (unregistered)  | —    | unlayered app rule that styles DS markup                    |
+ * | `layered-ds-dom`           | (unregistered)  | —    | the same rule inside the app's own `base`/`components` layer |
+ *
+ * Boundary with CM-15: selectors that name design-system **internals**
+ * (`[data-radix-select-viewport]`, `[data-esign-cover]`, `[data-labels]`,
+ * `[cmdk-…]`, the toast region) are DOM coupling and belong to the
+ * `C-DOM-*` contracts — CM-15 reports them, including from CSS, and CM-16
+ * skips them so the two finders never count the same rule twice. What CM-16
+ * owns is the *layering*: element, universal and DS-utility-class selectors
+ * that reach DS markup by being unlayered or later in the cascade.
+ *
+ * Model, and where it is weaker than `derive-consumer-preset` (W1-18):
+ *   - CM-16 reads the **authored** stylesheets of the project. W1-18 reads
+ *     the **compiled** output of the app's own Tailwind, so it also sees the
+ *     theme keys the app inherits from `@import "tailwindcss"`. Collisions
+ *     that neither sheet authors (`--spacing`, `--text-*`, `--container-*`,
+ *     `--font-weight-*`) are therefore invisible to CM-16 by construction.
+ *   - CM-16 resolves values with source order inside one file, on the
+ *     default root scope only; W1-18 runs a layer-, specificity- and
+ *     element-aware cascade over both sheets and can be given the app's
+ *     `<html>` attributes (`data-brand="tax"`).
+ *   Both call two values "different" through the same normalisation
+ *   (`codemods/lib/css-values.mjs`), so the differing counts are comparable.
+ *
+ * Never modifies a file.
+ */
+import {
+  classNamesOf,
+  dsStylesheet,
+  insideAtRule,
+  insideKeyframes,
+  isRootSelector,
+  layerOf,
+  selectorParts,
+} from "../lib/ds-stylesheet.mjs";
+import { computeCustomProperties, referencedVars, sameValue } from "../lib/css-values.mjs";
+export const meta = {
+  id: "CM-16",
+  title: "globals.css analyser: @source, preflight, colliding @theme keys, unlayered globals",
+  class: "X",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code", "css"],
+  includeTests: false,
+  usesTypeScript: false,
+  usesPostcss: true,
+  registryIds: [
+    "C-CSS-SOURCE",
+    "C-CSS-STYLES",
+    "C-CSS-DARKCLASS",
+    "C-TOKENS-LEGACY",
+    "C-TOKENS-WRITE",
+  ],
+};
+const DS_PACKAGE = "@assure-one/design-system";
+const DS_STYLES = `${DS_PACKAGE}/styles.css`;
+/** How a finding is weighted in the report and in the preset work. */
+export const SEVERITY = {
+  high: "high",
+  medium: "medium",
+  low: "low",
+};
+// ---------------------------------------------------------------------------
+// At-rules
+const unquote = (s) =>
+  s
+    .trim()
+    .replace(/^url\(\s*/, "")
+    .replace(/\s*\)$/, "")
+    .replace(/^["']|["']$/g, "");
+/** `@import` target without its layer/media/supports tail. */
+export const importTarget = (params) => unquote(params.split(/\s+(?=layer|supports|screen|\()/)[0]);
+/** Whether an `@source` names the design-system package (never `@source not`). */
+export const sourcesDs = (params) => {
+  const value = params.trim();
+  if (/^not\b/.test(value)) return false;
+  if (/^inline\b/.test(value)) return false;
+  return unquote(value).includes("design-system");
+};
+const APP_PREFLIGHT = new Set([
+  "tailwindcss",
+  "tailwindcss/preflight",
+  "tailwindcss/preflight.css",
+  "tailwindcss/index.css",
+]);
+// ---------------------------------------------------------------------------
+// Selectors that reach design-system markup
+/**
+ * Elements the design system renders itself. A bare type selector on any of
+ * them lands inside DS components, whatever the app meant it for.
+ */
+const DS_ELEMENTS = new Set([
+  "a",
+  "aside",
+  "body",
+  "button",
+  "caption",
+  "code",
+  "dd",
+  "dialog",
+  "div",
+  "dl",
+  "dt",
+  "fieldset",
+  "footer",
+  "form",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "header",
+  "hr",
+  "html",
+  "img",
+  "input",
+  "label",
+  "legend",
+  "li",
+  "main",
+  "nav",
+  "ol",
+  "optgroup",
+  "option",
+  "p",
+  "pre",
+  "section",
+  "select",
+  "span",
+  "strong",
+  "svg",
+  "table",
+  "tbody",
+  "td",
+  "textarea",
+  "tfoot",
+  "th",
+  "thead",
+  "tr",
+  "ul",
+]);
+/**
+ * Attributes and bracket hooks that name design-system internals. CM-15 owns
+ * these (the `C-DOM-*` contracts), so CM-16 stays silent on them.
+ */
+const DS_INTERNALS =
+  /\[data-radix-|\[data-esign-|\[data-slot|\[data-labels|\[data-collapsible|\[data-with-toolbar|\[data-sticky-stack|\[cmdk-|aria-label=["']?Notifications/;
+const SCOPE_SPELLING = /(^|[\s>+~])(?:\.dark\b|\[data-brand)/;
+/** The rightmost compound of one complex selector. */
+export function rightmostCompound(part) {
+  const segments = part.split(/\s*[>+~]\s*|\s+/).filter(Boolean);
+  return segments.length ? segments[segments.length - 1] : part;
+}
+const stripFunctional = (compound) =>
+  compound
+    .replace(/::?[a-z-]+\([^)]*\)/gi, "")
+    .replace(/::?[a-z-]+/gi, "")
+    .replace(/\[[^\]]*\]/g, "");
+/**
+ * How a selector list reaches DS markup, or `null`.
+ * @returns {{ via: "universal" | "element" | "ds-class", detail: string } | null}
+ */
+export function reachesDsDom(selector, dsClasses) {
+  if (DS_INTERNALS.test(selector)) return null; // CM-15's territory
+  let best = null;
+  const rank = { universal: 3, element: 2, "ds-class": 1 };
+  for (const part of selectorParts(selector)) {
+    const compound = rightmostCompound(part);
+    const bare = stripFunctional(compound);
+    let hit = null;
+    if (/\*/.test(bare) || bare === "") {
+      // `*`, `*:focus-visible`, or a bare pseudo-element such as
+      // `::-webkit-scrollbar`: both apply inside DS components.
+      const pseudo = /::?[a-z-]+/i.exec(compound);
+      hit = { via: "universal", detail: /\*/.test(bare) ? "*" : (pseudo?.[0] ?? compound) };
+    } else if (/^[a-z][a-z0-9]*$/i.test(bare) && DS_ELEMENTS.has(bare.toLowerCase())) {
+      hit = { via: "element", detail: bare.toLowerCase() };
+    } else {
+      const shipped = classNamesOf(compound).filter((c) => dsClasses.has(c));
+      if (shipped.length) hit = { via: "ds-class", detail: shipped.sort().join(", ") };
+    }
+    if (hit && (!best || rank[hit.via] > rank[best.via])) best = hit;
+  }
+  return best;
+}
+// ---------------------------------------------------------------------------
+// CSS facts for one file
+function cssFacts(postcss, source, rel) {
+  let root;
+  try {
+    root = postcss.parse(source, { from: rel });
+  } catch (error) {
+    return { error: String(error.reason ?? error.message), line: error.line ?? null };
+  }
+  const atRules = [];
+  const decls = [];
+  const rules = [];
+  const reads = [];
+  root.walkAtRules((at) => {
+    atRules.push({ name: at.name, params: at.params.trim(), line: at.source?.start?.line ?? null });
+  });
+  root.walkDecls((decl) => {
+    const line = decl.source?.start?.line ?? null;
+    for (const name of referencedVars(decl.value)) reads.push({ name, line });
+    if (!decl.prop.startsWith("--") || decl.prop.startsWith("--tw-")) return;
+    if (insideKeyframes(decl)) return;
+    const parent = decl.parent;
+    const theme =
+      insideAtRule(decl, "theme") || (parent?.type === "atrule" && parent.name === "theme");
+    const selector = parent?.type === "rule" ? parent.selector.replace(/\s+/g, " ") : null;
+    decls.push({
+      name: decl.prop,
+      value: decl.value.trim(),
+      line,
+      theme,
+      selector,
+      root: theme || (selector !== null && isRootSelector(selector)),
+      layer: layerOf(decl),
+    });
+  });
+  root.walkRules((rule) => {
+    if (insideKeyframes(rule)) return;
+    rules.push({
+      selector: rule.selector.replace(/\s+/g, " "),
+      line: rule.source?.start?.line ?? null,
+      layer: layerOf(rule),
+      // `@apply` is how the apps write most of their element defaults
+      // (`* { @apply border-border }`), so it counts as a declaration.
+      declarations:
+        rule.nodes?.filter((n) => n.type === "decl" || (n.type === "atrule" && n.name === "apply"))
+          .length ?? 0,
+    });
+  });
+  return { atRules, decls, rules, reads };
+}
+// ---------------------------------------------------------------------------
+export function transform(file, { postcss }) {
+  return file.kind === "css" ? cssFindings(file, postcss) : codeFindings(file, postcss);
+}
+/**
+ * The all-in-one stylesheet is imported from application code, not from CSS
+ * (all four consumers do it in `src/app/layout.tsx`). No parser is needed for
+ * a module specifier.
+ */
+function codeFindings(file) {
+  const findings = [];
+  const lines = file.source.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!lines[i].includes(DS_STYLES)) continue;
+    if (!/^\s*(?:import\s|require\()/.test(lines[i])) continue;
+    findings.push({
+      line: i + 1,
+      registryId: "C-CSS-STYLES",
+      gate: "G1",
+      severity: SEVERITY.high,
+      rule: "ds-styles-import",
+      scope: "import",
+      component: null,
+      match: DS_STYLES,
+      confidence: "high",
+    });
+  }
+  return { findings };
+}
+function cssFindings(file, postcss) {
+  const ds = dsStylesheet(postcss);
+  const facts = cssFacts(postcss, file.source, file.rel);
+  if (facts.error) {
+    return { parseErrors: [{ line: facts.line, message: facts.error }] };
+  }
+  const findings = [];
+  const add = (f) => findings.push({ component: null, confidence: "high", gate: null, ...f });
+  // 1. Loading: `@source` into the package, and a second preflight.
+  let appPreflight = null;
+  for (const at of facts.atRules) {
+    if (at.name === "source" && sourcesDs(at.params)) {
+      add({
+        line: at.line,
+        registryId: "C-CSS-SOURCE",
+        gate: "G2",
+        severity: SEVERITY.high,
+        rule: "source-into-ds",
+        scope: "at-rule",
+        match: `@source ${at.params}`,
+      });
+    }
+    if (at.name === "import") {
+      const target = importTarget(at.params);
+      if (target === DS_STYLES) {
+        add({
+          line: at.line,
+          registryId: "C-CSS-STYLES",
+          gate: "G1",
+          severity: SEVERITY.high,
+          rule: "ds-styles-import",
+          scope: "at-rule",
+          match: `@import "${target}"`,
+        });
+      }
+      if (APP_PREFLIGHT.has(target) && appPreflight === null) appPreflight = { at, target };
+    }
+    if (at.name === "custom-variant" && /^dark\b/.test(at.params)) {
+      // `&:is(.dark *)` styles descendants of `.dark` but not `.dark` itself;
+      // the design system's own variant is `&:where(.dark, .dark *)`.
+      const body = at.params.slice(4).trim();
+      if (/\.dark\s+\*/.test(body) && !/\.dark\s*[,)]/.test(body)) {
+        add({
+          line: at.line,
+          registryId: "C-CSS-DARKCLASS",
+          severity: SEVERITY.low,
+          rule: "dark-variant-mismatch",
+          scope: "at-rule",
+          match: `@custom-variant ${at.params}`,
+          confidence: "medium",
+        });
+      }
+    }
+  }
+  if (appPreflight && ds.preflight) {
+    add({
+      line: appPreflight.at.line,
+      registryId: "C-CSS-STYLES",
+      gate: "G1",
+      severity: SEVERITY.high,
+      rule: "duplicate-preflight",
+      scope: "at-rule",
+      match: `@import "${appPreflight.target}" (the design system's ${ds.from} ships preflight too)`,
+    });
+  }
+  // 2. Token collisions. Values are resolved inside this file, with the
+  //    design system's own values standing in for everything it declares.
+  const rootDecls = facts.decls.filter((d) => d.root);
+  const winners = new Map();
+  for (const d of rootDecls) winners.set(d.name, { value: d.value });
+  const appValues = computeCustomProperties(winners, ds.tokens);
+  const declaredHere = new Set(facts.decls.map((d) => d.name));
+  const lastRoot = new Map();
+  for (const d of rootDecls) lastRoot.set(d.name, d);
+  for (const [name, d] of [...lastRoot].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!ds.tokens.has(name) && !ds.declared.has(name)) continue;
+    const dsValue = ds.tokens.get(name);
+    const appValue = appValues.get(name);
+    const differs = !sameValue(dsValue, appValue);
+    if (d.theme) {
+      add({
+        line: d.line,
+        registryId: "C-TOKENS-LEGACY",
+        severity: differs ? SEVERITY.high : SEVERITY.low,
+        rule: differs ? "theme-collision-differs" : "theme-collision-equal",
+        scope: "theme",
+        match: `${name}: ${d.value}`,
+        detail: { ds: dsValue ?? null, app: appValue ?? null },
+        confidence: differs ? "high" : "medium",
+      });
+    } else {
+      add({
+        line: d.line,
+        registryId: "C-TOKENS-WRITE",
+        severity: differs ? SEVERITY.high : SEVERITY.medium,
+        rule: "legacy-var-write",
+        scope: d.selector ?? "root",
+        match: `${name}: ${d.value}`,
+        detail: { ds: dsValue ?? null, app: appValue ?? null },
+      });
+    }
+  }
+  // 3. DS tokens re-declared inside a scope the design system owns the
+  //    spelling of (`.dark`, `[data-brand="…"]`).
+  for (const d of facts.decls) {
+    if (d.root || !d.selector || !SCOPE_SPELLING.test(d.selector)) continue;
+    if (!ds.tokens.has(d.name) && !ds.declared.has(d.name)) continue;
+    add({
+      line: d.line,
+      registryId: "C-CSS-DARKCLASS",
+      severity: SEVERITY.medium,
+      rule: "brand-scope-spelling",
+      scope: d.selector,
+      match: `${d.name}: ${d.value}`,
+      confidence: "medium",
+    });
+  }
+  // 4. Legacy reads: `var(--<ds token>)` for a token this file does not
+  //    declare itself, so the value comes from the design system.
+  const readLines = new Map();
+  for (const r of facts.reads) {
+    if (declaredHere.has(r.name)) continue;
+    if (!ds.tokens.has(r.name) && !ds.declared.has(r.name)) continue;
+    const key = `${r.line} ${r.name}`;
+    if (readLines.has(key)) continue;
+    readLines.set(key, r);
+  }
+  for (const r of readLines.values()) {
+    add({
+      line: r.line,
+      registryId: "C-TOKENS-LEGACY",
+      severity: SEVERITY.medium,
+      rule: "legacy-var-read",
+      scope: "var",
+      match: `var(${r.name})`,
+      confidence: "medium",
+    });
+  }
+  // 5. App rules that style design-system markup. Unlayered rules beat every
+  //    layer; rules in the app's own `base`/`components` layers land in the
+  //    same layer as the design system's and win on source order alone.
+  for (const rule of facts.rules) {
+    if (!rule.declarations) continue;
+    if (isRootSelector(rule.selector) || SCOPE_SPELLING.test(rule.selector)) continue;
+    const reach = reachesDsDom(rule.selector, ds.classes);
+    if (!reach) continue;
+    const unlayered = rule.layer === null;
+    add({
+      line: rule.line,
+      registryId: null,
+      severity: unlayered
+        ? reach.via === "ds-class"
+          ? SEVERITY.high
+          : SEVERITY.medium
+        : SEVERITY.low,
+      rule: unlayered ? "unlayered-ds-dom" : "layered-ds-dom",
+      scope: rule.layer ?? "unlayered",
+      component: null,
+      match: rule.selector.slice(0, 200),
+      detail: { via: reach.via, names: reach.detail },
+      confidence: reach.via === "ds-class" ? "high" : "medium",
+    });
+  }
+  return {
+    findings,
+    context: {
+      dsSheet: ds.from,
+      dsTokens: ds.tokens.size,
+      appRootDeclarations: rootDecls.length,
+      appPreflight: Boolean(appPreflight),
+    },
+  };
+}

package/dist/css/base.css ADDED Viewed

@@ -0,0 +1,60 @@
+/* Optional document defaults (W1-15).
+ *
+ * Hand-written, not generated: it carries no token values, only references.
+ *
+ * `styles.css` ships a Tailwind preflight, `h1`–`h4` element styles, a global
+ * number-spinner rule, a global `::selection` rule and a body font size into
+ * every host. Target architecture §13 gives all of that back to the
+ * application, and this file is the small, opt-in replacement for the part an
+ * application usually does want: the document's background, ink, font and
+ * colour scheme, expressed as references to `--ds-*` tokens.
+ *
+ * What this file deliberately does NOT contain:
+ *   - no preflight and no reset. DS components are written to be correct given
+ *     a modern reset, which every known consumer already has (an app that has
+ *     none needs its own; §13).
+ *   - no element rules beyond `html` and `body`. No `h1`–`h4` (that is what
+ *     `Heading` is for), no `input[type=number]` spinner rule (scoped to
+ *     `NumberInput` instead), no global `*` box-sizing, no global
+ *     reduced-motion override (durations collapse at the token level).
+ *   - no `@import url(…)`: the design system loads no fonts. The application
+ *     owns font loading and sets `--ds-font-sans` (§14, D2). Until it does,
+ *     `--ds-font-sans` resolves to whatever `css/tokens.css` declares.
+ *   - no `font-size`. `styles.css` sets the body to 14px; this file does not
+ *     restore that, because a document base size is the application's
+ *     decision. Moving an app to the new CSS mode is a deliberate visual
+ *     change for exactly this kind of reason (ADR-004 rule 10, plan §12.4).
+ *
+ * Importing the file is the opt-in. Everything in it sits in `@layer base`, so
+ * an application's own base rules — declared later in the same layer — win,
+ * and any utility in a higher layer wins over all of it.
+ */
+@layer theme, base, ds, components, utilities;
+@layer base {
+  /* Tells the browser which form controls, scrollbars and default canvas to
+   * render. Both spellings of the scope, as everywhere in the new mode. */
+  html {
+    color-scheme: light;
+  }
+  html:where([data-ds-scheme="dark"], .dark) {
+    color-scheme: dark;
+  }
+  body {
+    background-color: var(--ds-color-canvas);
+    color: var(--ds-color-content);
+    font-family: var(--ds-font-sans);
+  }
+  /* Selection ink. Scoped to the document body rather than written as a bare
+   * `::selection`, so the rule cannot reach a shadow host or a detached
+   * subtree the application renders outside `<body>`. */
+  body::selection,
+  body *::selection {
+    background-color: var(--ds-color-action-brand-subtle-bg);
+    color: var(--ds-color-content);
+  }
+}