synthesisui 0.1.24 → 0.2.0

package/dist/commands/component.js

@@ -1,27 +1,70 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveRegistry } from "../config.js";
-import { fetchComponent } from "../registry.js";
+import { generateComponentFiles } from "../component-codegen.js";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchComponent, RegistryError } from "../registry.js";
+/** 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]+)*$/;
 /**
  * Brings ONE component from a design system into the project (granular "bring
- * specific", INS-18 fatia 3) - its recipe + compiled CSS, written under
- * `_synthesisui/ds/<slug>/components/`. Handy for a component you refit/created
- * on the platform. The component's styles reference the DS tokens, so the system
- * itself must be installed (`synthesisui add <slug>`) for `tokens.css` to resolve.
+ * specific", INS-18 fatia 3):
+ *
+ * 1. Artifacts (source of truth) → `_synthesisui/ds/<slug>/components/`:
+ *    the recipe (.json, for agents/tooling) + compiled CSS (.css).
+ * 2. YOUR component (unless --artifacts-only, target "next") →
+ *    `<componentsDir>/<name>/` from `_synthesisui/config.json`: a real
+ *    `export function <Pascal>()` with variants as typed props, in the
+ *    project's chosen flavor (`styles: "css" | "tailwind"`).
+ *
+ * The component's styles reference the DS tokens, so the system itself must be
+ * installed (`synthesisui add <slug>`) for `tokens.css`/`theme.css` to resolve.
  */
 export async function component(slug, name, opts) {
     const base = resolveRegistry(opts.registry);
     const root = opts.dir ?? process.cwd();
+    if (!SAFE_NAME.test(slug)) {
+        throw new RegistryError(`Invalid slug "${slug}".`);
+    }
     console.log(`→ fetching "${name}" from "${slug}" …`);
     const res = await fetchComponent(base, slug, name, opts.version);
+    // The server should only ever return a kebab-case name, but never trust a
+    // network value as a path segment.
+    if (!SAFE_NAME.test(res.name)) {
+        throw new RegistryError(`Registry returned an unsafe component name.`);
+    }
     const dir = join(root, "_synthesisui", "ds", slug, "components");
     await mkdir(dir, { recursive: true });
     await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
     await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
     console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
+    // 2. YOUR component - a real, importable `export function <Pascal>()` in the
+    //    project's flavor (config: styles css|tailwind), under componentsDir.
+    const config = await readProjectConfig(root);
+    if (!opts.artifactsOnly && config.target === "next") {
+        const compDir = join(root, config.componentsDir, res.name);
+        await mkdir(compDir, { recursive: true });
+        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+        for (const file of files) {
+            await writeFile(join(compDir, file.filename), file.code, "utf8");
+        }
+        const names = files.map((f) => f.filename).join(", ");
+        console.log(`✓ ${config.componentsDir}/${res.name}/ → ${names}  (styles: ${config.styles})`);
+    }
     console.log("");
     console.log("Use it:");
-    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
-    console.log(`  • @import "_synthesisui/ds/${slug}/components/${res.name}.css" in your CSS`);
-    console.log(`  • <div data-ds="${slug}"><div class="ds-${res.name}">…</div></div>`);
+    console.log(`  • once per app: synthesisui add ${slug} (tokens.css${config.styles === "tailwind" ? " + theme.css" : ""}), import it globally,`);
+    console.log(`    and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">)`);
+    if (!opts.artifactsOnly && config.target === "next") {
+        const pascalName = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        console.log(`  • import { ${pascalName} } from "./${config.componentsDir}/${res.name}" and render <${pascalName} />`);
+        console.log(`  • or ask your agent: "use the ${pascalName} component from ${config.componentsDir}/${res.name} (SynthesisUI ${slug})"`);
+    }
+    else {
+        console.log(`  • @import "_synthesisui/ds/${slug}/components/${res.name}.css" and use <div class="ds-${res.name}">…</div>`);
+    }
 }

package/dist/commands/init.js

@@ -14,12 +14,14 @@ export async function init(opts) {
         target,
         pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
         componentsDir: opts.componentsDir ?? DEFAULT_CONFIG.componentsDir,
+        styles: opts.styles === "tailwind" ? "tailwind" : "css",
     };
     await writeProjectConfig(root, config);
     console.log("✓ wrote _synthesisui/config.json");
     console.log(`  target:        ${config.target}`);
     console.log(`  pagesDir:      ${config.pagesDir}`);
     console.log(`  componentsDir: ${config.componentsDir}`);
+    console.log(`  styles:        ${config.styles}`);
     // --ds bootstraps the project with a system in one step (tokens + philosophy
     // + rules + CLAUDE.md all arrive via `add`).
     if (opts.ds) {

package/dist/component-codegen.js

@@ -0,0 +1,382 @@
+const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+const pascal = (name) => name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join("");
+const camel = (name) => {
+    const p = pascal(name);
+    return p[0].toLowerCase() + p.slice(1);
+};
+/** Intrinsic element + extra attrs per component, chosen like the platform
+ *  renderer does (name first, then preview.kind). Fallback: div + children. */
+function elementFor(name, recipe) {
+    const byName = {
+        input: { tag: "input" },
+        textarea: { tag: "textarea" },
+        select: { tag: "select" },
+        checkbox: { tag: "input", attrs: ' type="checkbox"' },
+        radio: { tag: "input", attrs: ' type="radio"' },
+        switch: { tag: "input", attrs: ' type="checkbox" role="switch"' },
+        slider: { tag: "input", attrs: ' type="range"' },
+        button: { tag: "button", attrs: ' type="button"' },
+        "icon-button": { tag: "button", attrs: ' type="button"' },
+        badge: { tag: "span" },
+        tag: { tag: "span" },
+        avatar: { tag: "span" },
+        divider: { tag: "hr" },
+        link: { tag: "a" },
+    };
+    const hit = byName[name] ??
+        (recipe.preview?.kind === "action"
+            ? { tag: "button", attrs: ' type="button"' }
+            : undefined);
+    const tag = hit?.tag ?? "div";
+    return {
+        tag,
+        attrs: hit?.attrs ?? "",
+        voidEl: tag === "input" || tag === "hr",
+    };
+}
+/** Variant axes → typed props. An axis whose options ⊆ {true,false} is a
+ *  boolean prop; empty axes (no visual effect) are skipped. */
+function axesOf(variants) {
+    const axes = [];
+    for (const [axis, options] of Object.entries(variants ?? {})) {
+        const keys = Object.keys(options).filter((k) => Object.keys(options[k] ?? {}).length > 0);
+        if (keys.length === 0)
+            continue;
+        axes.push({
+            key: axis,
+            prop: camel(axis),
+            attr: kebab(axis),
+            boolean: keys.every((k) => k === "true" || k === "false"),
+            styledFalse: keys.includes("false"),
+            options: keys,
+        });
+    }
+    return axes;
+}
+function propsType(axes, tag) {
+    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}`;
+}
+function dataAttrLines(axes) {
+    return axes
+        .map((a) => a.boolean
+        ? a.styledFalse
+            ? `      data-${a.attr}={${a.prop} ? "true" : "false"}`
+            : `      data-${a.attr}={${a.prop} ? "true" : undefined}`
+        : `      data-${a.attr}={${a.prop}}`)
+        .join("\n");
+}
+// ── Tailwind translation ─────────────────────────────────────────────────────
+/**
+ * Namespace-aware token key: returns the utility suffix ONLY when the ref
+ * lives in a namespace the `theme.css` @theme adapter actually maps
+ * (semantic/series colors, spacing, radius, shadow, families, weights, type
+ * scale). Anything else (e.g. color primitives) must use the --ds-* fallback.
+ */
+const nsKey = (v, ns) => {
+    const m = v.match(new RegExp(`^\\{${ns.replace(/\./g, "\\.")}\\.([a-zA-Z0-9-]+)\\}$`));
+    return m ? kebab(m[1]) : null;
+};
+/** Color refs the adapter maps: semantic → <role>, series → series-<n>. */
+const colorKey = (v) => {
+    const semantic = nsKey(v, "color.semantic");
+    if (semantic)
+        return semantic;
+    const series = nsKey(v, "color.series");
+    if (series)
+        return `series-${series}`;
+    return null;
+};
+/** "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility). */
+const scaleKey = (v) => {
+    const m = v.match(/^\{typography\.scale\.([a-zA-Z0-9-]+)\.fontSize\}$/);
+    return m ? kebab(m[1]) : null;
+};
+/** "{color.semantic.primary}" → "var(--ds-color-semantic-primary)" - the raw
+ *  scoped vars always exist, so arbitrary-property fallbacks never dangle. */
+const refToDsVar = (v) => v.replace(/\{([a-z0-9.-]+)\}/gi, (_, path) => {
+    return `var(--ds-${path.split(".").map(kebab).join("-")})`;
+});
+/** Arbitrary-property escape hatch: guaranteed-faithful when no pretty utility
+ *  exists. Spaces become underscores per Tailwind's arbitrary syntax. */
+const arbitrary = (prop, value) => `[${kebab(prop)}:${refToDsVar(value).replace(/\s+/g, "_")}]`;
+const STATIC = {
+    display: {
+        flex: "flex",
+        "inline-flex": "inline-flex",
+        grid: "grid",
+        block: "block",
+        "inline-block": "inline-block",
+        none: "hidden",
+    },
+    alignItems: {
+        center: "items-center",
+        "flex-start": "items-start",
+        "flex-end": "items-end",
+        baseline: "items-baseline",
+        stretch: "items-stretch",
+    },
+    justifyContent: {
+        center: "justify-center",
+        "space-between": "justify-between",
+        "flex-start": "justify-start",
+        "flex-end": "justify-end",
+    },
+    flexDirection: { column: "flex-col", row: "flex-row" },
+    textAlign: { center: "text-center", left: "text-left", right: "text-right" },
+    cursor: { pointer: "cursor-pointer", "not-allowed": "cursor-not-allowed" },
+    width: { "100%": "w-full" },
+    height: { "100%": "h-full" },
+    textDecoration: { none: "no-underline", underline: "underline" },
+};
+/** One declaration → Tailwind classes (pretty when mappable, arbitrary-property
+ *  otherwise - never dropped). */
+function declToTailwind(prop, value) {
+    const stat = STATIC[prop]?.[value];
+    if (stat)
+        return [stat];
+    switch (prop) {
+        case "backgroundColor": {
+            if (value === "transparent")
+                return ["bg-transparent"];
+            const key = colorKey(value);
+            if (key)
+                return [`bg-${key}`];
+            break;
+        }
+        case "color": {
+            const key = colorKey(value);
+            if (key)
+                return [`text-${key}`];
+            break;
+        }
+        case "borderColor": {
+            const key = colorKey(value);
+            if (key)
+                return [`border-${key}`];
+            break;
+        }
+        case "border": {
+            // "1px solid {color.semantic.x}" → border + border-<x>
+            const m = value.match(/^1px\s+solid\s+(\{[^}]+\})$/);
+            if (m) {
+                const key = colorKey(m[1]);
+                if (key)
+                    return ["border", `border-${key}`];
+            }
+            break;
+        }
+        case "borderRadius": {
+            const key = nsKey(value, "radius");
+            if (key)
+                return [`rounded-${key}`];
+            break;
+        }
+        case "gap": {
+            const key = nsKey(value, "spacing");
+            if (key)
+                return [`gap-${key}`];
+            break;
+        }
+        case "padding": {
+            const keys = value.split(/\s+/).map((v) => nsKey(v, "spacing"));
+            if (keys.length === 1 && keys[0])
+                return [`p-${keys[0]}`];
+            if (keys.length === 2 && keys[0] && keys[1])
+                return [`py-${keys[0]}`, `px-${keys[1]}`];
+            break;
+        }
+        case "fontSize": {
+            const key = scaleKey(value);
+            if (key)
+                return [`text-${key}`];
+            break;
+        }
+        case "fontFamily": {
+            const key = nsKey(value, "typography.families");
+            if (key)
+                return [`font-${key}`];
+            break;
+        }
+        case "fontWeight": {
+            const key = nsKey(value, "typography.weights");
+            if (key)
+                return [`font-${key}`];
+            break;
+        }
+        case "boxShadow": {
+            const key = nsKey(value, "shadow");
+            if (key)
+                return [`shadow-${key}`];
+            break;
+        }
+        case "lineHeight":
+            // usually paired with the same scale's fontSize (text-<key> carries the
+            // scale's line-height via --text-<key>--line-height)
+            if (/^\{typography\.scale\./.test(value))
+                return [];
+            break;
+    }
+    return [arbitrary(prop, value)];
+}
+const STATE_PREFIX = {
+    hover: "hover:",
+    focus: "focus:",
+    focusVisible: "focus-visible:",
+    active: "active:",
+    disabled: "disabled:",
+};
+function blockToTailwind(block, prefix = "") {
+    return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value).map((cls) => `${prefix}${cls}`));
+}
+function tailwindClassList(recipe) {
+    const classes = [
+        ...blockToTailwind(recipe.base),
+        ...Object.entries(recipe.states ?? {}).flatMap(([state, block]) => STATE_PREFIX[state] ? blockToTailwind(block, STATE_PREFIX[state]) : []),
+    ];
+    return classes.join(" ");
+}
+// ── Emission ─────────────────────────────────────────────────────────────────
+function header(slug, name, version, mode) {
+    const setup = mode === "tailwind"
+        ? `import _synthesisui/ds/${slug}/theme.css (Tailwind adapter) + tokens.css`
+        : `import _synthesisui/ds/${slug}/tokens.css`;
+    return [
+        `// Generated by SynthesisUI - "${name}" from the "${slug}" design system (v${version}).`,
+        `// On-system by construction: every style resolves to the DS tokens.`,
+        `// Global setup (once per app): ${setup}`,
+        `// and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">).`,
+    ].join("\n");
+}
+const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
+function emitCssMode(slug, name, recipe, version) {
+    const { tag, attrs, voidEl } = elementFor(name, recipe);
+    const axes = axesOf(recipe.variants);
+    const comp = pascal(name);
+    const propNames = axes.map((a) => a.prop);
+    const destructure = [...propNames, "className", "...props"].join(", ");
+    void voidEl; // both void and container elements self-close ({...props} carries children)
+    const rootJsx = `    <${tag}${attrs}\n      className={${joinCls([`"ds-${name}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    />`;
+    const parts = Object.entries(recipe.parts ?? {}).map(([partName, part]) => {
+        const partAxes = axesOf(part.variants ?? {});
+        const partComp = `${comp}${pascal(partName)}`;
+        const partDestructure = [
+            ...partAxes.map((a) => a.prop),
+            "className",
+            "...props",
+        ].join(", ");
+        return `
+/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, "div")}) {
+  return (
+    <div
+      className={${joinCls([`"ds-${name}-${kebab(partName)}"`, "className"])}}
+${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
+    />
+  );
+}`;
+    });
+    return `${header(slug, name, version, "css")}
+import "./${name}.css";
+
+import type { ComponentPropsWithoutRef } from "react";
+
+type ${comp}Props = ${propsType(axes, tag)};
+
+export function ${comp}({ ${destructure} }: ${comp}Props) {
+  return (
+${rootJsx}
+  );
+}
+${parts.join("\n")}`;
+}
+function emitTailwindMode(slug, name, recipe, version) {
+    const { tag, attrs, voidEl } = elementFor(name, recipe);
+    const axes = axesOf(recipe.variants);
+    const comp = pascal(name);
+    const variantConsts = axes
+        .filter((a) => !a.boolean)
+        .map((a) => {
+        const entries = a.options
+            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.[o] ?? {}).join(" "))},`)
+            .join("\n");
+        return `const ${a.prop.toUpperCase()}: Record<string, string> = {\n${entries}\n};`;
+    });
+    const booleanConsts = axes
+        .filter((a) => a.boolean)
+        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.true ?? {}).join(" "))};`);
+    const clsParts = [
+        "BASE",
+        ...axes.map((a) => a.boolean
+            ? `${a.prop} ? ${a.prop.toUpperCase()} : ""`
+            : `${a.prop} ? ${a.prop.toUpperCase()}[${a.prop}] : ""`),
+        "className",
+    ];
+    const destructure = [
+        ...axes.map((a) => a.prop),
+        "className",
+        "...props",
+    ].join(", ");
+    void voidEl;
+    return `${header(slug, name, version, "tailwind")}
+
+import type { ComponentPropsWithoutRef } from "react";
+
+const BASE = ${JSON.stringify(tailwindClassList(recipe))};
+${[...variantConsts, ...booleanConsts].join("\n")}
+
+type ${comp}Props = ${propsType(axes, tag)};
+
+export function ${comp}({ ${destructure} }: ${comp}Props) {
+  return (
+    <${tag}${attrs}
+      className={${joinCls(clsParts)}}
+      {...props}
+    />
+  );
+}
+${Object.entries(recipe.parts ?? {})
+        .map(([partName, part]) => {
+        const partComp = `${comp}${pascal(partName)}`;
+        return `
+/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
+export function ${partComp}({ className, ...props }: ComponentPropsWithoutRef<"div">) {
+  return (
+    <div 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) {
+    const comp = pascal(name);
+    const files = [];
+    if (styles === "css") {
+        files.push({
+            filename: `${name}.tsx`,
+            code: `${emitCssMode(slug, name, recipe, version)}\n`,
+        });
+        files.push({ filename: `${name}.css`, code: `${css}\n` });
+    }
+    else {
+        files.push({
+            filename: `${name}.tsx`,
+            code: `${emitTailwindMode(slug, name, recipe, version)}\n`,
+        });
+    }
+    files.push({
+        filename: "index.ts",
+        code: `export * from "./${name}";\n`,
+    });
+    void comp;
+    return files;
+}

package/dist/config.js

@@ -40,6 +40,7 @@ export const DEFAULT_CONFIG = {
     target: "next",
     pagesDir: "app",
     componentsDir: "components",
+    styles: "css",
 };
 const projectConfigPath = (root) => join(root, "_synthesisui", "config.json");
 /** Reads the project config, falling back to defaults when absent/invalid. */
@@ -55,6 +56,7 @@ export async function readProjectConfig(root) {
             componentsDir: typeof parsed.componentsDir === "string" && parsed.componentsDir
                 ? parsed.componentsDir
                 : DEFAULT_CONFIG.componentsDir,
+            styles: parsed.styles === "tailwind" ? "tailwind" : "css",
         };
     }
     catch {

package/dist/guide.js

@@ -145,6 +145,18 @@ place** - wire real data, split into components, swap the chart/icon/media place
 \`data-ds="${slug}"\` wrapper and the \`.ds-*\` / layout classes so it stays on-system. Run
 \`synthesisui init\` once to set the target (next/general) and the output folder.
 
+## Single components as YOUR code
+
+Bring one component in as a real, typed React component (variants become props):
+\`\`\`bash
+synthesisui component ${slug} button
+\`\`\`
+It writes \`<componentsDir>/button/\` with \`button.tsx\` (+ colocated \`button.css\` in the default
+\`styles: "css"\` flavor, or Tailwind utilities inline with \`styles: "tailwind"\` - set once via
+\`synthesisui init --styles tailwind\`). Import and render: \`import { Button } from "components/button"\`.
+The boundary: tokens are global (\`tokens.css\` + the \`data-ds\` root attribute, once per app);
+everything a component owns lives in its own folder.
+
 ---
 `
         : "";

package/dist/index.js

@@ -17,7 +17,7 @@ Usage:
   synthesisui list [options]               list the published design systems
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
   synthesisui template <slug> <name>       materialize a whole page from a DS template
-  synthesisui component <slug> <name>      bring one component (recipe + css) into the project
+  synthesisui component <slug> <name>      bring one component in - artifacts + YOUR <Pascal>.tsx in componentsDir
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui advise "<value prop>"        engagement-pattern proposals for this project (login required)
   synthesisui generate "<desc>"            generate a token-only component recipe for your DS (login required)
@@ -31,6 +31,8 @@ Options:
   --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
   --components-dir <dir>  init: folder where components live (default: components)
+  --styles <s>       init: component code flavor: css | tailwind (default: css)
+  --artifacts-only   component: skip the .tsx materialization (recipe + css only)
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
@@ -125,7 +127,16 @@ async function main() {
                 ? flags["components-dir"]
                 : undefined;
             const ds = typeof flags.ds === "string" ? flags.ds : undefined;
-            await init({ dir, registry, target, pagesDir, componentsDir, ds });
+            const styles = typeof flags.styles === "string" ? flags.styles : undefined;
+            await init({
+                dir,
+                registry,
+                target,
+                pagesDir,
+                componentsDir,
+                styles,
+                ds,
+            });
             break;
         }
         // `page` is the legacy alias (renamed to `template`); it still works so
@@ -173,7 +184,12 @@ async function main() {
                     return;
                 }
             }
-            await component(slug, name, { registry, dir, version });
+            await component(slug, name, {
+                registry,
+                dir,
+                version,
+                artifactsOnly: flags["artifacts-only"] === true,
+            });
             break;
         }
         case "use": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.1.24",
+  "version": "0.2.0",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {