synthesisui 0.16.16 → 0.16.17

package/dist/commands/component.js

@@ -1,10 +1,32 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
 import { fetchComponent, RegistryError } from "../registry.js";
+/**
+ * The consumer's React major, or null when we cannot tell.
+ *
+ * It decides whether the generated components can take a `ref`: from 19 that is
+ * an ordinary prop, before it a function component needs `forwardRef`. Guessing
+ * high on an older project would emit a type that accepts a ref React then
+ * silently drops, so anything unreadable falls back to the ref-less type.
+ */
+async function reactMajorOf(root) {
+    const raw = await readFile(join(root, "package.json"), "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const pkg = JSON.parse(raw);
+        const spec = pkg.dependencies?.react ?? pkg.devDependencies?.react;
+        const major = /(\d+)/.exec(spec ?? "")?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Slugs/names are kebab-case by contract; reject anything else before it ever
  *  reaches a filesystem path (defense-in-depth against `../` traversal). */
 const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -59,7 +81,7 @@ export async function component(slug, name, opts) {
             filenames = [`${res.name}.tsx`, `${res.name}.css`, "index.ts"];
         }
         else {
-            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, await reactMajorOf(root));
             for (const file of files) {
                 await writeFile(join(compDir, file.filename), file.code, "utf8");
             }

package/dist/component-codegen.js

@@ -8,6 +8,28 @@ const camel = (name) => {
     const p = pascal(name);
     return p[0].toLowerCase() + p.slice(1);
 };
+/**
+ * A PART THAT STYLES FOCUS IS A CONTROL, AND EVERY ONE OF THEM SHIPPED AS A DIV.
+ *
+ * Found by an agent building a carousel (27/07). `PaginationItem` came out as a
+ * `<div>` carrying `cursor-pointer`, `hover:text-foreground`,
+ * `focus-visible:[outline:2px]` and `disabled:[opacity:0.4]` - every affordance
+ * of a button on an element that is not focusable, is not announced as a
+ * control, and where `disabled:` can never match. It worked around us by
+ * putting the class on a real `<button>` instead of using the component.
+ *
+ * The recipe already knew. Nobody writes a focus ring on a div by accident, so
+ * `focus`/`focusVisible`/`disabled` in a part's states IS the declaration that
+ * it is operable. `hover` deliberately does not count: a card that lifts under
+ * the cursor is still a card.
+ *
+ * Conservative by construction. Across the shipped catalogue this promotes
+ * three parts of fifty - stepper.button, tabs.trigger, pagination.item - and
+ * all three are buttons that were wearing the wrong tag.
+ */
+export function partIsInteractive(part) {
+    return Object.keys(part.states ?? {}).some((s) => /^(focus|focusVisible|focus-visible|disabled)$/i.test(s));
+}
 /** Intrinsic element + extra attrs per component, chosen like the platform
  *  renderer does (name first, then preview.kind). Fallback: div + children. */
 function elementFor(name, recipe) {
@@ -82,13 +104,36 @@ function axesOf(variants) {
     }
     return axes;
 }
-function propsType(axes, tag) {
+/**
+ * THE COMPONENTS COULD NOT TAKE A REF, AND SOME UI CANNOT BE BUILT WITHOUT ONE.
+ *
+ * `ComponentPropsWithoutRef` is the correct type under React 18, where a
+ * function component needs `forwardRef` to receive one. Under React 19 `ref` is
+ * an ordinary prop, so the same code works and the type is simply lying about
+ * what the component accepts.
+ *
+ * It costs real things. An agent building a dense screen (28/07) had to address
+ * rows by DOM id and reach for `document.getElementById`, because roving focus
+ * needs a ref. And `indeterminate` on a checkbox is a DOM property with no HTML
+ * attribute: a partial select-all is impossible without one.
+ *
+ * Read from the consumer's own package.json, never assumed. Unknown or older
+ * keeps today's behaviour, because emitting a ref-taking type onto React 18
+ * trades a missing feature for a silent one - the ref is quietly undefined and
+ * only a dev-mode warning says so.
+ */
+export function propsTypeName(reactMajor) {
+    return reactMajor !== null && reactMajor >= 19
+        ? "ComponentProps"
+        : "ComponentPropsWithoutRef";
+}
+function propsType(axes, tag, base) {
     const extras = axes.map((a) => a.boolean
         ? `  ${a.prop}?: boolean;`
         : `  ${a.prop}?: ${a.options.map((o) => `"${o}"`).join(" | ")};`);
     if (extras.length === 0)
-        return `ComponentPropsWithoutRef<"${tag}">`;
-    return `ComponentPropsWithoutRef<"${tag}"> & {\n${extras.join("\n")}\n}`;
+        return `${base}<"${tag}">`;
+    return `${base}<"${tag}"> & {\n${extras.join("\n")}\n}`;
 }
 function dataAttrLines(axes) {
     return axes
@@ -403,7 +448,7 @@ ${inner}
  *   </${comp}>
  */`;
 }
-function emitCssMode(slug, name, recipe, version) {
+function emitCssMode(slug, name, recipe, version, props) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const axes = axesOf(recipe.variants);
     const comp = pascal(name);
@@ -418,11 +463,14 @@ function emitCssMode(slug, name, recipe, version) {
             "className",
             "...props",
         ].join(", ");
+        const control = partIsInteractive(part);
+        const partTag = control ? "button" : "div";
+        const partAttrs = control ? '\n      type="button"' : "";
         return `
 /** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, "div")}) {
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props)}) {
   return (
-    <div
+    <${partTag}${partAttrs}
       className={${joinCls([`"ds-${name}-${kebab(partName)}"`, "className"])}}
 ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     />
@@ -432,9 +480,9 @@ ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     return `${header(slug, name, version, "css")}
 import "./${name}.css";
 
-import type { ComponentPropsWithoutRef } from "react";
+import type { ${props} } from "react";
 
-type ${comp}Props = ${propsType(axes, tag)};
+type ${comp}Props = ${propsType(axes, tag, props)};
 
 ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
@@ -444,7 +492,7 @@ ${rootJsx}
 }
 ${parts.join("\n")}`;
 }
-function emitTailwindMode(slug, name, recipe, version) {
+function emitTailwindMode(slug, name, recipe, version, props) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const axes = axesOf(recipe.variants);
     const comp = pascal(name);
@@ -479,12 +527,12 @@ function emitTailwindMode(slug, name, recipe, version) {
     ].join(", ");
     return `${header(slug, name, version, "tailwind")}
 
-import type { ComponentPropsWithoutRef } from "react";
+import type { ${props} } from "react";
 
 const BASE = ${JSON.stringify(tailwindClassList(recipe, excluded))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
 
-type ${comp}Props = ${propsType(axes, tag)};
+type ${comp}Props = ${propsType(axes, tag, props)};
 
 ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
@@ -498,31 +546,38 @@ export function ${comp}({ ${destructure} }: ${comp}Props) {
 ${Object.entries(recipe.parts ?? {})
         .map(([partName, part]) => {
         const partComp = `${comp}${pascal(partName)}`;
+        const control = partIsInteractive(part);
+        const partTag = control ? "button" : "div";
+        const partAttrs = control ? ' type="button"' : "";
         return `
 /** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ className, ...props }: ComponentPropsWithoutRef<"div">) {
+export function ${partComp}({ className, ...props }: ${props}<"${partTag}">) {
   return (
-    <div className={${joinCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
+    <${partTag}${partAttrs} className={${joinCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
   );
 }`;
     })
         .join("\n")}`;
 }
 /** All files for one component, under `<componentsDir>/<name>/`. */
-export function generateComponentFiles(slug, name, recipe, css, version, styles) {
+export function generateComponentFiles(slug, name, recipe, css, version, styles, 
+/** Consumer's React major, read from its package.json. Null = unknown, which
+ *  keeps the ref-less type rather than guessing in the unsafe direction. */
+reactMajor = null) {
     const comp = pascal(name);
     const files = [];
+    const props = propsTypeName(reactMajor);
     if (styles === "css") {
         files.push({
             filename: `${name}.tsx`,
-            code: `${emitCssMode(slug, name, recipe, version)}\n`,
+            code: `${emitCssMode(slug, name, recipe, version, props)}\n`,
         });
         files.push({ filename: `${name}.css`, code: `${css}\n` });
     }
     else {
         files.push({
             filename: `${name}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version)}\n`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props)}\n`,
         });
     }
     files.push({

package/dist/doctor/scan.js

@@ -31,11 +31,32 @@ const IGNORE_LINE = /^\s*(import|@import|\/\/|\*|\/\*)/;
  * 3/6/8 digit run terminated by a non-hex character.
  */
 const COLOR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b|rgba?\([^)]*\)|hsla?\([^)]*\)/g;
-/** `rounded-[14px]`, `border-radius: 14px`. Zero and full pills are idiom,
- *  not drift - nobody tokenizes `0` or `9999px`. */
-const RADIUS = /(?:border-radius\s*:\s*|rounded(?:-[a-z]+)?-\[)(-?\d*\.?\d+)(px|rem|em)/g;
-/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`. */
-const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*)(-?\d*\.?\d+)(px|rem)/g;
+/**
+ * THE QUOTE THAT MADE HALF THE DRIFT INVISIBLE.
+ *
+ * Both patterns below used to require `property:` followed directly by a digit.
+ * CSS writes `padding: 2rem` and matches. JSX writes `padding: "2rem"`, and the
+ * quote ends the match before it starts - so a component built with an inline
+ * style object was scanned for colour and nothing else.
+ *
+ * Colour escaped it by luck: that pattern hunts `#hex` anywhere and never
+ * needed a property in front. Which is exactly why nobody noticed, because
+ * every test file had a colour in it and the colour always came back.
+ *
+ * Found 28/07 writing a file with `gap: "1.25rem"` and `padding: "2rem"` on
+ * purpose - both exact tokens of the system - and being told six colours, zero
+ * spacings.
+ *
+ * JSX also camelCases, so `borderRadius` has to be as welcome as
+ * `border-radius`.
+ */
+const OPEN = `["']?`;
+/** `rounded-[14px]`, `border-radius: 14px`, `borderRadius: "14px"`. Zero and
+ *  full pills are idiom, not drift - nobody tokenizes `0` or `9999px`. */
+const RADIUS = new RegExp(`(?:border-?[Rr]adius\\s*:\\s*${OPEN}|rounded(?:-[a-z]+)?-\\[)(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
+/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
+ *  The JSX side also writes `paddingLeft`, `marginTop` and friends. */
+const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem)`, "g");
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
 /**
@@ -252,7 +273,9 @@ export function scanSource(file, source, table) {
                 kind,
                 line: at,
                 literal,
-                token: tokenFor(table, literal),
+                // The kind is already known here, and without passing it the lookup
+                // answers a `gap` with a radius token.
+                token: tokenFor(table, literal, kind),
                 excerpt: clip(line),
             });
         };

package/dist/doctor/tokens.js

@@ -416,11 +416,35 @@ export function nearestToken(table, literal) {
     const limit = unit === "rem" ? Math.max(n * 0.25, 0.5) : Math.max(n * 0.25, 8);
     return best.delta <= limit ? best : null;
 }
-export function tokenFor(table, literal) {
+/**
+ * The family a token belongs to, from the drift it was found in.
+ *
+ * Without this the lookup is by VALUE alone, and a value belongs to more than
+ * one family: `1.25rem` is both `--ds-spacing-sm` and `--ds-radius-lg` in the
+ * same system. Measured 28/07 on `gap-[1.25rem]`, which was correctly counted as
+ * spacing and then told to use a radius token.
+ *
+ * That is worse than saying nothing. A tool that answers a gap with a corner
+ * radius is one a person stops reading, and this one has exactly one job that
+ * nobody else does: naming the right token.
+ */
+const FAMILY = {
+    color: "--ds-color-",
+    radius: "--ds-radius-",
+    spacing: "--ds-spacing-",
+    font: "--ds-typography-",
+};
+export function tokenFor(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal));
     if (!hit || hit.length === 0)
         return null;
+    // Narrow to the family first, and only fall back to the whole set when the
+    // system has no token of that kind holding this value - a fallback is still
+    // better than silence, it just stops being a recommendation.
+    const prefix = kind ? FAMILY[kind] : undefined;
+    const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
+    const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.
-    const semantic = hit.find((n) => n.includes("-semantic-"));
-    return semantic ?? hit[0];
+    const semantic = pool.find((n) => n.includes("-semantic-"));
+    return semantic ?? pool[0];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.16",
+  "version": "0.16.17",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {