synthesisui 0.16.119 → 0.16.120

package/dist/guide.js

@@ -33,6 +33,90 @@ function customFontFamilies(families) {
     }
     return out;
 }
+/**
+ * THE STRUCTURE, WITH WHAT EACH PART IS FOR AND WHEN IT EXISTS.
+ *
+ * A flat list of class names is enough to STYLE and not enough to BUILD: an agent in
+ * another project reading fifteen of them cannot tell which is the thing you press, which
+ * one holds the revealed content, or which two are not always there. The recipe carries
+ * both facts per node and the guide was printing neither (dono, 04/08).
+ */
+function anatomyLines(cname, nodes, depth = 1) {
+    const out = [];
+    for (const node of nodes ?? []) {
+        if (depth > 6)
+            break;
+        const pad = "  ".repeat(depth);
+        const name = node.part
+            ? `\`.ds-${kebab(cname)}-${kebab(node.part)}\``
+            : node.refName
+                ? `\`<${node.refName}>\``
+                : node.ref
+                    ? `your \`${node.refName ?? node.ref}\``
+                    : node.as;
+        const facts = [node.as];
+        if (node.role && node.role !== node.as)
+            facts.push(node.role);
+        if (node.refName && node.from)
+            facts.push(`from \`${node.from}\``);
+        if (node.expects)
+            facts.push(`holds ${node.expects}`);
+        /**
+         * WHEN IT EXISTS, in the recipe's own words rather than in theirs - see
+         * `PreviewNode.only`. Their `isLoading` means nothing in another project; "only in a
+         * state this component has" is actionable anywhere.
+         */
+        const only = node.only;
+        if (only && "axis" in only)
+            facts.push(`only when \`data-${kebab(only.axis)}="${only.option}"\``);
+        else if (only && "state" in only)
+            facts.push("only in that state");
+        else if (only && "caller" in only)
+            facts.push("only when you pass it");
+        out.push(`${pad}- ${name} - ${facts.join(" · ")}`);
+        out.push(...anatomyLines(cname, node.children, depth + 1));
+    }
+    return out;
+}
+/**
+ * WHAT THE COMPONENT DOES, said without naming a package.
+ *
+ * The recipe says `@base-ui/react/collapsible`. In a project that uses Radix - or nothing -
+ * that is evidence and not an instruction. What travels is the SHAPE of the interaction,
+ * and it is derivable from two facts the recipe already carries: the behaviour belongs to
+ * a headless library, and one part has the `action` role while another holds the content.
+ *
+ * Derived, never invented: with no `action` part and no headless library there is nothing
+ * to say, and this says nothing.
+ */
+function behaviourLine(cname, recipe) {
+    const headless = (recipe.libraries ?? []).some((l) => l.kind === "headless");
+    if (!headless)
+        return null;
+    const flat = [];
+    const walk = (nodes) => {
+        for (const node of nodes ?? []) {
+            flat.push(node);
+            walk(node.children);
+        }
+    };
+    walk(recipe.preview?.parts);
+    const action = flat.find((n) => n.role === "action");
+    if (!action)
+        return null;
+    /**
+     * A part that exists only in a STATE, or a slot, is the region an action reveals - which
+     * is what separates a disclosure from a button that merely has a name.
+     */
+    const revealed = flat.find((n) => n.as === "slot" || (n.only && "state" in n.only));
+    const press = action.part
+        ? `\`.ds-${kebab(cname)}-${kebab(action.part)}\``
+        : "the action";
+    if (!revealed) {
+        return `the interaction: ${press} is the pressable one - wire it yourself or with any headless primitive, and give it the ARIA the pattern calls for.`;
+    }
+    return `the interaction: ${press} is pressed and reveals the region below it. Whatever drives that - a headless library or your own state - the pressable element announces \`aria-expanded\` and points at the region with \`aria-controls\`; the region carries the matching \`id\`. This recipe styles both and drives neither.`;
+}
 /** One entry per component: class, variant data-*, states, and multi-part anatomy. */
 function componentEntry(cname, recipe) {
     const cls = `.ds-${kebab(cname)}`;
@@ -50,7 +134,65 @@ function componentEntry(cname, recipe) {
         });
         partsText = `\n  parts: ${items.join(", ")}`;
     }
-    return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}${partsText}${statesText}`;
+    /**
+     * EVERYTHING ELSE THE RECIPE ALREADY KNOWS, and this entry was throwing away.
+     *
+     * Measured on a real system: the recipe holds 15 fields and the guide read 4 of them, so
+     * an agent in another project got a list of class names and had to invent the rest -
+     * which is the difference between styling this component and building one that behaves
+     * like it (dono, 04/08).
+     */
+    const facts = [];
+    if (recipe.tier)
+        facts.push(`a ${recipe.tier}`);
+    if (recipe.api?.name) {
+        facts.push(recipe.api.from
+            ? `their own \`${recipe.api.name}\`, imported from \`${recipe.api.from}\``
+            : `their own \`${recipe.api.name}\``);
+    }
+    /**
+     * WHO OWNS THE STATE, which is the first question anybody rebuilding it asks. A recipe
+     * that manages itself needs no props to work; one the caller drives needs the pair.
+     */
+    const runtime = recipe.runtime;
+    if (runtime?.stateOwner) {
+        const owner = runtime.stateOwner === "self"
+            ? "manages its own state"
+            : runtime.stateOwner === "caller"
+                ? "the caller owns its state"
+                : "works controlled or uncontrolled";
+        const pairs = (runtime.controlled ?? [])
+            .map((c) => `\`${c.prop}\` + \`${c.event}\``)
+            .join(", ");
+        facts.push(pairs ? `${owner} (${pairs})` : owner);
+    }
+    /**
+     * WHOSE BEHAVIOUR IT IS, and what that means for somebody rebuilding it. `headless` is
+     * the one that changes the answer: the pixels are in this recipe and the interaction is
+     * a library's, so ANY headless primitive of that shape will do - it does not have to be
+     * the one they used.
+     */
+    for (const lib of recipe.libraries ?? []) {
+        if (lib.kind === "headless")
+            facts.push(`behaviour from \`${lib.from}\` - a headless library: every pixel is in this recipe, the interaction is not. Any equivalent primitive works`);
+        else if (lib.kind === "opaque")
+            facts.push(`\`${lib.from}\` draws part of it, and that part is not in this recipe`);
+    }
+    const defaults = Object.entries(recipe.defaults ?? {})
+        .map(([axis, option]) => `\`data-${kebab(axis)}="${option}"\``)
+        .join(", ");
+    const defaultsText = defaults ? `\n  at rest: ${defaults}` : "";
+    const factsText = facts.length ? `\n  ${facts.join("\n  ")}` : "";
+    /** Its own laws, computed from its own usage - and nothing read them (dono, 04/08). */
+    const laws = (recipe.usage ?? []).map((law) => `\n  - ${law}`).join("");
+    const lawsText = laws ? `\n  it obeys:${laws}` : "";
+    const behaviour = behaviourLine(cname, recipe);
+    const behaviourText = behaviour ? `\n  ${behaviour}` : "";
+    const anatomy = anatomyLines(cname, recipe.preview?.parts);
+    const anatomyText = anatomy.length
+        ? `\n  anatomy, in this nesting:\n${anatomy.join("\n")}`
+        : "";
+    return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}${factsText}${defaultsText}${partsText}${statesText}${behaviourText}${anatomyText}${lawsText}`;
 }
 /**
  * Builds GUIDE.md - instructions *for the agent* on how to build components

package/package.json

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