synthesisui 0.1.21 → 0.1.24

package/dist/commands/component.js

@@ -0,0 +1,27 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveRegistry } from "../config.js";
+import { fetchComponent } from "../registry.js";
+/**
+ * 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.
+ */
+export async function component(slug, name, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    console.log(`→ fetching "${name}" from "${slug}" …`);
+    const res = await fetchComponent(base, slug, name, opts.version);
+    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})`);
+    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>`);
+}

package/dist/commands/init.js

@@ -2,7 +2,7 @@ import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
 import { add } from "./add.js";
 /**
  * Bootstraps a project for SynthesisUI: writes `_synthesisui/config.json`
- * (where `page` materializes pages, where components live, which framework to
+ * (where `template` materializes pages, where components live, which framework to
  * target) and - with `--ds <slug>` - immediately brings that system in, so the
  * project lands with tokens, philosophy, rules and a CLAUDE.md in one step.
  * Committable; safe to re-run.
@@ -30,5 +30,5 @@ export async function init(opts) {
     console.log("");
     console.log("Next steps:");
     console.log("  • synthesisui add <slug>              bring a design system in");
-    console.log("  • synthesisui page <slug> <template>  materialize a full page");
+    console.log("  • synthesisui template <slug> <name>  materialize a full page");
 }

package/dist/commands/template.js

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchTemplate } from "../registry.js";
+/**
+ * Materializes a whole page from a DS template into the project (hybrid
+ * codegen-first): the server codegens deterministic files, we write them, and
+ * the agent refines them in place. The page uses the DS's `.ds-*` classes +
+ * path classes; the co-located CSS (Next target) carries the responsive media
+ * queries + the CSS-only hamburger, so it re-vests once `tokens.css` is in.
+ */
+export async function template(slug, name, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    const config = await readProjectConfig(root);
+    const target = opts.target === "general" || opts.target === "next"
+        ? opts.target
+        : config.target;
+    console.log(`→ generating "${name}" from "${slug}" (${target}) …`);
+    const generated = await fetchTemplate(base, slug, name, target, opts.version);
+    // --out targets the page (1st file); sibling files (e.g. the CSS) land in the
+    // same directory. Without --out, everything goes under <pagesDir>.
+    const [pageFile, ...siblings] = generated.files;
+    const pageRel = opts.out ?? join(config.pagesDir, pageFile.filename);
+    const pageDir = dirname(join(root, pageRel));
+    await mkdir(pageDir, { recursive: true });
+    await writeFile(join(root, pageRel), pageFile.code, "utf8");
+    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
+    for (const f of siblings) {
+        const rel = opts.out
+            ? join(dirname(pageRel), f.filename)
+            : join(config.pagesDir, f.filename);
+        await writeFile(join(root, rel), f.code, "utf8");
+        console.log(`✓ wrote ${rel}`);
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    console.log("  • refine the file: wire real data, split into components, swap placeholders");
+    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
+}

package/dist/guide.js

@@ -84,6 +84,32 @@ its typographic identity. Load them once (any one approach):
 - **Next.js** (\`next/font/google\`), **Fontsource**, or self-hosted \`@font-face\` work too - just
   register the families above. If a family isn't on Google Fonts, self-host it.
 
+---
+`
+        : "";
+    // Libraries the system references but doesn't bundle - the agent should
+    // install them when it actually renders icons/charts (INS-19).
+    const iconLibraries = doc.icons?.libraries ?? [];
+    const hasCharts = !!doc.charts && Object.keys(doc.charts).length > 0;
+    const depLines = [
+        iconLibraries.includes("lucide")
+            ? "- **Icons** - components reference Lucide icon names. Run `npm i lucide-react` " +
+                "(or swap in your own icon set) to render them."
+            : "",
+        hasCharts
+            ? "- **Charts** - charts are themed through your series tokens, but you bring the " +
+                "renderer. Run `npm i recharts` (the gallery uses Recharts)."
+            : "",
+    ].filter(Boolean);
+    const depsSection = depLines.length
+        ? `
+## Dependencies
+
+Beyond loading the fonts above, the system references libraries it doesn't bundle - install them
+when you actually render that UI:
+
+${depLines.join("\n")}
+
 ---
 `
         : "";
@@ -109,8 +135,8 @@ This system ships whole-page templates: ${layoutNames.map((n) => `\`${n}\``).joi
 
 Materialize one as a real file:
 \`\`\`bash
-synthesisui page ${slug} ${layoutNames[0]}                 # Next .tsx + .css (default)
-synthesisui page ${slug} ${layoutNames[0]} --target general  # single self-contained HTML
+synthesisui template ${slug} ${layoutNames[0]}                 # Next .tsx + .css (default)
+synthesisui template ${slug} ${layoutNames[0]} --target general  # single self-contained HTML
 \`\`\`
 It writes a **deterministic scaffold**: the page uses this DS's \`.ds-*\` recipe classes + layout
 path-classes, paired with a co-located scoped CSS (Next target) that carries the **responsive** media
@@ -186,7 +212,7 @@ ${hasAlt
    root.toggleAttribute("data-scheme"); // present = ${altScheme}, absent = ${meta.scheme}
    \`\`\`
 `
-        : ""}${fontsSection}${hasTailwind
+        : ""}${fontsSection}${depsSection}${hasTailwind
         ? `
 ## Styling with Tailwind v4 (preferred in this project)
 

package/dist/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { add } from "./commands/add.js";
 import { advise } from "./commands/advise.js";
+import { component } from "./commands/component.js";
 import { generate } from "./commands/generate.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
-import { page } from "./commands/page.js";
+import { template } from "./commands/template.js";
 import { use } from "./commands/use.js";
 import { RegistryError } from "./registry.js";
 const HELP = `synthesisui - bring SynthesisUI design systems into your project
@@ -15,7 +16,8 @@ Usage:
   synthesisui init [options]               write _synthesisui/config.json (target, dirs); --ds to bring one in
   synthesisui list [options]               list the published design systems
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
-  synthesisui page <slug> <template>       materialize a whole page from a DS template
+  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 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)
@@ -26,10 +28,10 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
-  --target <t>       page/init target: next | general (default: next)
+  --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)
-  --out <path>       output path for the generated page (default: <pagesDir>/<file>)
+  --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
 Examples:
@@ -39,8 +41,9 @@ Examples:
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
-  synthesisui page halogen dashboard-sidebar
-  synthesisui page halogen landing --out app/page.tsx
+  synthesisui template halogen dashboard-sidebar
+  synthesisui template halogen landing --out app/page.tsx
+  synthesisui component halogen pricing-tier
   synthesisui use halogen "a pricing section with three tiers and a highlighted plan"
   synthesisui use halogen "make the card shadow softer in components/StatCard.tsx"
   synthesisui advise "habit-building app for tracking personal finances"
@@ -125,11 +128,17 @@ async function main() {
             await init({ dir, registry, target, pagesDir, componentsDir, ds });
             break;
         }
-        case "page": {
+        // `page` is the legacy alias (renamed to `template`); it still works so
+        // GUIDE.md files materialized before the rename don't break.
+        case "page":
+        case "template": {
+            if (command === "page") {
+                console.error("note: `synthesisui page` was renamed to `synthesisui template` - the old name still works for now.");
+            }
             const slug = args[0];
-            const template = args[1];
-            if (!slug || !template) {
-                console.error("error: provide slug and template - `synthesisui page <slug> <template>`");
+            const name = args[1];
+            if (!slug || !name) {
+                console.error("error: provide slug and template name - `synthesisui template <slug> <name>`");
                 process.exitCode = 1;
                 return;
             }
@@ -144,7 +153,27 @@ async function main() {
             }
             const target = typeof flags.target === "string" ? flags.target : undefined;
             const out = typeof flags.out === "string" ? flags.out : undefined;
-            await page(slug, template, { registry, dir, out, target, version });
+            await template(slug, name, { registry, dir, out, target, version });
+            break;
+        }
+        case "component": {
+            const slug = args[0];
+            const name = args[1];
+            if (!slug || !name) {
+                console.error("error: provide slug and component name - `synthesisui component <slug> <name>`");
+                process.exitCode = 1;
+                return;
+            }
+            let version;
+            if (typeof flags.version === "string") {
+                version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);
+                if (!Number.isInteger(version) || version < 1) {
+                    console.error(`error: invalid --version "${flags.version}" - use an integer ≥ 1`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            await component(slug, name, { registry, dir, version });
             break;
         }
         case "use": {

package/dist/registry.js

@@ -43,12 +43,12 @@ export async function fetchDesignSystem(base, slug, version) {
     return (await res.json());
 }
 /**
- * Fetches a whole page generated from a DS template (`?page=&target=`). The
+ * Fetches a whole page generated from a DS template (`?template=&target=`). The
  * server codegens it from `document.layouts[<template>]`; the CLI just writes it.
  */
-export async function fetchPage(base, slug, template, target, version) {
+export async function fetchTemplate(base, slug, template, target, version) {
     const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
-    url.searchParams.set("page", template);
+    url.searchParams.set("template", template);
     url.searchParams.set("target", target);
     if (version != null)
         url.searchParams.set("version", String(version));
@@ -63,6 +63,27 @@ export async function fetchPage(base, slug, template, target, version) {
     }
     return (await res.json());
 }
+/**
+ * Fetches ONE component from a DS (`?component=<name>`): its recipe + compiled
+ * CSS. Granular "bring specific" - the system must exist; works for public DS
+ * without login (private/owned needs the token).
+ */
+export async function fetchComponent(base, slug, name, version) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    url.searchParams.set("component", name);
+    if (version != null)
+        url.searchParams.set("version", String(version));
+    const res = await request(url.toString());
+    if (res.status === 404) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ??
+            `No component "${name}" in "${slug}". Run \`synthesisui add ${slug}\` and check its components.`);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`Registry responded ${res.status} while fetching "${name}".`);
+    }
+    return (await res.json());
+}
 /**
  * Calls the hosted advisor (`POST /api/ai/advisor`). Gated + metered server-side:
  * 401 = not logged in, 429 = daily quota reached. Sends the Bearer token if present.

package/package.json

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