synthesisui 0.16.107 → 0.16.109

package/dist/anatomy-read.js

@@ -167,6 +167,7 @@ sketch) {
     const composes = [];
     const external = [];
     const notes = [];
+    const partAt = {};
     let budget = MAX_NODES;
     let coerced = 0;
     /**
@@ -295,6 +296,27 @@ sketch) {
                     notes.push(`part \`${key}\`: \`${cls}\` starts like a design decision and reads as nothing - usually a typo in the source, and the element renders without it today`);
                 }
                 node_.part = key;
+                /**
+                 * WHICH SKETCH NODE BECAME THIS PART.
+                 *
+                 * The only place both facts exist at once. A lookup table whose value is an
+                 * object carries one field per element - their `statusConfig` has `dotClass`
+                 * for the dot and `colorClass` for the label - and the reader can say WHICH
+                 * element by the call site's class string, which is an index. Turning that
+                 * index into a part name is this walk's job and nobody else's.
+                 */
+                if (typeof node.at === "number")
+                    partAt[node.at] = key;
+                /**
+                 * A HAND-WRITTEN READ NAMES ITS CLASSES, not an index - the skill's own
+                 * examples do. The string is the sketch's own, so matching it back is exact,
+                 * and without this the per-part attribution would work on a derived anatomy
+                 * and quietly do nothing on an authored one.
+                 */ else if (raw) {
+                    const found = (sketch ?? []).findIndex((n) => n.classes === raw);
+                    if (found >= 0 && !partAt[found])
+                        partAt[found] = key;
+                }
             }
             const text = typeof node.text === "string" ? node.text.trim() : "";
             if (text)
@@ -434,6 +456,7 @@ sketch) {
         composes,
         external,
         notes,
+        partAt,
         ...(rootOut ? { root: rootOut } : {}),
     };
 }
@@ -454,5 +477,5 @@ export function resolveFlatParts(read, declared) {
         const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
         parts[name] = { base: t.base, dark: t.dark, states: t.states };
     }
-    return { parts, tree: [], composes: [], external: [], notes: [] };
+    return { parts, tree: [], composes: [], external: [], notes: [], partAt: {} };
 }

package/dist/commands/import.js

@@ -16,6 +16,7 @@ import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } fro
 import { moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
+import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
@@ -518,6 +519,24 @@ export async function takeCensus(root, opts) {
                  * the owner's rule, adopted verbatim (dono, 01/08).
                  */
                 const sketch = sketchOf(src, found[0].name);
+                /**
+                 * A PER-PART LAYER FINDS ITS NODE, by the class string of the call site that
+                 * consumes the field. See `ReadLayer.onClasses`: the reader knows a
+                 * `statusConfig.dotClass` is written on the element whose `className` reads
+                 * `cn("relative size-2 rounded-full", config.dotClass)`, and that literal is
+                 * exactly what the sketch stored - so this is a lookup, not a second parse.
+                 *
+                 * An index rather than the string, because the anatomy already names nodes by
+                 * index and `resolveReadParts` moves the layer onto the part that node became.
+                 */
+                const placed = layers.map((layer) => {
+                    const on = layer.onClasses;
+                    if (!on)
+                        return layer;
+                    const { onClasses: _drop, ...rest } = layer;
+                    const at = callSiteNode(sketch, on);
+                    return at === null ? rest : { ...rest, on: at };
+                });
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
                         ...(sketch.length > 0 ? { sketch } : {}),
@@ -529,7 +548,10 @@ export async function takeCensus(root, opts) {
                         ...(tree.length > 0 ? { tree } : {}),
                         ...(tag ? { rootTag: tag } : {}),
                         ...rootPackage(tag, sketch),
-                        ...(layers.length > 0 ? { layers } : {}),
+                        ...(placed.length > 0 ? { layers: placed } : {}),
+                        ...(v.unslotted.length > 0
+                            ? { unplaced: [...new Set(v.unslotted)] }
+                            : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
                         ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
                     };
@@ -873,6 +895,31 @@ export async function takeCensus(root, opts) {
             console.log(body(line));
         console.log(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
     }
+    /**
+     * WHAT THE READER UNDERSTOOD AND REFUSED TO PLACE.
+     *
+     * The other half of the same honesty: a look with nowhere to go is not put on the
+     * component, and a component that quietly lost a decision looks like our bug. See
+     * `Transcription.unplaced` for what earns a line here.
+     */
+    const unplacedByComponent = Object.entries(looks)
+        .filter(([, look]) => (look.unplaced ?? []).length > 0)
+        .map(([component, look]) => ({
+        component,
+        lines: look.unplaced ?? [],
+    }));
+    if (unplacedByComponent.length > 0) {
+        const total = unplacedByComponent.reduce((n, u) => n + u.lines.length, 0);
+        console.log("");
+        console.log(section("Conditional looks that were read and not placed"));
+        console.log(body(`${total} decision${total === 1 ? "" : "s"} across ${unplacedByComponent.length} component${unplacedByComponent.length === 1 ? "" : "s"} were understood and left off, because putting them on the component would paint the wrong element:`));
+        for (const u of unplacedByComponent.slice(0, 8)) {
+            console.log(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
+        }
+        if (unplacedByComponent.length > 8) {
+            console.log(body(paint.faint(`  and ${unplacedByComponent.length - 8} more components`)));
+        }
+    }
     /**
      * THE DROPS, SAID OUT LOUD. `p-spacing-sm` on a real menu popup read as nothing and
      * the popup shipped with no padding, invisibly - "if the compiler drops them, the drop
@@ -1762,13 +1809,46 @@ async function resolveReadParts(census, root) {
                 .map((lib) => ({
                 from: lib.from,
                 ...(pinned[lib.from] ? { version: pinned[lib.from] } : {}),
-                ...(lib.kind === "headless" || lib.kind === "icon"
-                    ? { kind: lib.kind }
-                    : {}),
+                /**
+                 * EVERY KIND, not the two the rule sentence happened to need.
+                 *
+                 * This stamped `headless` and `icon` only, so `motion/react` reached the
+                 * census with no kind and the screen labelled it a third party - a library
+                 * that renders no element of its own (dono, 03/08). The screen now derives
+                 * a missing kind from the package, so this is the census telling the whole
+                 * truth rather than the thing that makes the label work.
+                 */
+                ...(lib.kind !== "own" ? { kind: lib.kind } : {}),
             })),
         ];
+        /**
+         * A PER-PART LAYER LANDS ON ITS PART.
+         *
+         * The reader attributed it to a sketch INDEX (see `Transcription.layers[].on`);
+         * the anatomy is what turns an index into a part name. So this is the first
+         * moment both halves exist - the same reason the reading is resolved here at all.
+         *
+         * A layer whose node no part claims stays OFF the component: pinning it to the
+         * root is exactly the bug, and it is reported instead.
+         */
+        const partAt = resolved.partAt ?? {};
+        const split = placeLayers((look?.layers ?? []), partAt, (look?.sketch ?? []));
+        for (const line of split.unplaced)
+            notes.add(line);
+        /** The per-part layers, merged into the parts the resolution just named. */
+        for (const [part, list] of split.perPart) {
+            const target = resolved.parts[part];
+            if (!target || !list)
+                continue;
+            target.layers = [
+                ...(target.layers ?? []),
+                ...list,
+            ];
+        }
         const carried = {
             ...(hasParts ? { parts: resolved.parts } : {}),
+            /** The root keeps only what is the root's - see the note above. */
+            ...(look?.layers ? { layers: split.root } : {}),
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
             ...(libraries.length > 0 ? { external: libraries } : {}),

package/dist/doctor/place-layers.js

@@ -0,0 +1,78 @@
+/**
+ * WHOSE LOOK IS IT - the step between reading a lookup table and styling anything.
+ *
+ * A conditional look read off a record is not automatically the component's. Their
+ * CollapsibleCard keeps one table for four statuses:
+ *
+ *     statusConfig.success = { dotClass: "bg-success-500 shadow-[…]",
+ *                              colorClass: "text-success-500", text: "Completed" }
+ *
+ * `dotClass` is worn by a 8px dot and `colorClass` by the label beside it, and merging
+ * them onto the component painted a white card with the dot's grey - four runs in a row
+ * where the owner saw a grey card and a status that had nothing to do with it
+ * (dono, 03/08). The same shape with a plain string is the bigger half: their
+ * HorizontalProgress writes `variantColors[variant]` on the FILL, so six colours landed
+ * on the outer wrapper and the whole component turned ocean-500.
+ *
+ * Measured across their library, 36 component files (dono, 03/08):
+ *
+ *     65   conditional looks come off a lookup table
+ *     28   belong to an element INSIDE the component  <- painted the component before
+ *     37   belong to the returned element             <- already correct, unchanged
+ *      0   could not be resolved
+ *
+ * THE READER SAYS WHICH ELEMENT BY ITS CLASS STRING, because that is the one thing
+ * both halves of the pipeline already hold: `ReadLayer.onClasses` is the unconditional
+ * part of the `className` call that consumes the field, and the sketch stored exactly
+ * that string for the node. So this is a lookup rather than a second parse of the JSX.
+ */
+/**
+ * The sketch index of the element whose `className` call was read, or null.
+ *
+ * Exact on the whole string: the sketch and the reader build it from the same
+ * unconditional literals, so a partial match would mean one of them changed its rule
+ * and guessing past that is how a look lands on the wrong element.
+ */
+export function callSiteNode(sketch, onClasses) {
+    const at = sketch.findIndex((node) => node.classes === onClasses);
+    return at >= 0 ? at : null;
+}
+/** True when this index is the element the component returns. */
+export function isRootNode(sketch, at) {
+    const stamped = sketch.findIndex((node) => node.root);
+    return stamped >= 0 ? at === stamped : at === 0;
+}
+/**
+ * Split the layers into the ones the component wears and the ones its parts wear.
+ *
+ * `partAt` is the anatomy's answer - sketch index → the part name that node became,
+ * from `resolveAnatomy`. A layer whose node is the ROOT stays on the component, which
+ * is where a table indexed on the returned element belongs. A layer whose node no part
+ * names goes into `unplaced` instead of onto the component: pinning it to the root is
+ * exactly the bug this exists for.
+ */
+export function placeLayers(layers, partAt, sketch) {
+    const root = [];
+    const perPart = new Map();
+    const unplaced = [];
+    for (const layer of layers) {
+        const { on, ...rest } = layer;
+        if (typeof on !== "number") {
+            root.push(rest);
+            continue;
+        }
+        const part = partAt[on];
+        if (part) {
+            const list = perPart.get(part) ?? [];
+            list.push(rest);
+            perPart.set(part, list);
+            continue;
+        }
+        if (isRootNode(sketch, on)) {
+            root.push(rest);
+            continue;
+        }
+        unplaced.push(`a conditional look belongs to an element the anatomy does not name, so it is not applied to the component - that would paint the wrong element`);
+    }
+    return { root, perPart, unplaced };
+}

package/dist/doctor/variant-read.js

@@ -548,11 +548,120 @@ export function readInlineConditions(source) {
 const LOOKUP_RECORD = /(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::\s*(?:Record|Partial<Record)<[^>]*>+)?\s*=\s*\{/g;
 /** `colorStyles[color]` - the record, and the prop that indexes it. */
 const RECORD_INDEX = /([A-Za-z_$][\w$]*)\s*\[\s*([A-Za-z_$][\w$]*)\s*\]/g;
+/**
+ * The FIELDS of an option whose value is an object, or `[]` when it is a plain
+ * string. `{ dotClass: "bg-x", text: "Waiting" }` → two entries.
+ */
+function objectFields(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{"))
+        return [];
+    const end = endOf(trimmed, 0);
+    if (end === -1)
+        return [];
+    return topLevelEntries(trimmed.slice(1, end - 1));
+}
+/**
+ * THE STATIC CLASSES OF THE `className` CALL THAT CONSUMES A LOOKUP.
+ *
+ * `cn("relative size-2 rounded-full", config.dotClass)` identifies the element
+ * without a second parse of the JSX: that literal is exactly what the sketch stored
+ * for the node, so the caller can resolve it to an index and move the layer onto the
+ * part it belongs to.
+ *
+ * TWO SPELLINGS, because both are real in one library. A field is matched by the FIELD
+ * name and the symbol is matched loosely, since their code reads the record into a
+ * local first (`const config = statusConfig[status]`); a record whose value is a plain
+ * string has no field, and there the indexing expression is what is written at the call
+ * site (`variantColors[variant]`), so the SYMBOL is the reliable half.
+ */
+function callSiteClasses(source, symbol, field) {
+    const use = field
+        ? new RegExp(`\\b[A-Za-z_$][\\w$]*(?:\\[[^\\]]*\\])?\\.${field}\\b`)
+        : new RegExp(`\\b${symbol}\\s*\\[`);
+    for (const m of source.matchAll(/className=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/g)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        const end = endOf(source, open);
+        if (end === -1)
+            continue;
+        const call = source.slice(open + 1, end - 1);
+        if (!use.test(call))
+            continue;
+        const statics = unconditionalClasses(call);
+        return statics.length > 0 ? statics.join(" ") : null;
+    }
+    return null;
+}
+/**
+ * THE CLASSES THE ELEMENT ALWAYS HAS, which is the only half that identifies it.
+ *
+ * Every string literal in the call is not the answer: their Card writes
+ * `borderColor === "vibrant" && variant === "full-border" && "dark:after:…"`, so a
+ * blanket read picks up the mask gradient AND the two comparison operands, and the
+ * result matches no element in the sketch. The sketch stores the unconditional
+ * literals, so this has to read the same thing or the lookup cannot land.
+ *
+ * An argument is unconditional when it is a string and nothing else - one literal,
+ * no `&&`, no `?:`, no identifier.
+ */
+function unconditionalClasses(call) {
+    const out = [];
+    let depth = 0;
+    let quote = "";
+    let start = 0;
+    const args = [];
+    for (let i = 0; i < call.length; i++) {
+        const c = call[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = "";
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`")
+            quote = c;
+        else if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        else if (c === "," && depth === 0) {
+            args.push(call.slice(start, i));
+            start = i + 1;
+        }
+    }
+    args.push(call.slice(start));
+    for (const arg of args) {
+        const trimmed = arg.trim();
+        if (!/^(["'`])/.test(trimmed))
+            continue;
+        // A literal followed by anything else is a condition, not a constant.
+        const closed = endOfString(trimmed);
+        if (closed === -1 || trimmed.slice(closed).trim())
+            continue;
+        out.push(...literalClasses(trimmed));
+    }
+    return out;
+}
+/** The index just past the closing quote of the string that starts at 0, or -1. */
+function endOfString(text) {
+    const quote = text[0];
+    for (let i = 1; i < text.length; i++) {
+        if (text[i] === "\\")
+            i++;
+        else if (text[i] === quote)
+            return i + 1;
+    }
+    return -1;
+}
 export function readLookupRecords(source, 
 /** Filled with axis → options, because the axis NAMES have to travel too: a first pass
  *  sent the styles and not the names, so a Tag with eight colours reported no axis at
  *  all (probe, 01/08). */
-axesOut) {
+axesOut, 
+/** Fields of a per-part table that no `className` call claims - said out loud
+ *  rather than pinned to the root. See `ReadLayer.onClasses`. */
+unattributed) {
     const clean = stripComments(source);
     // Which prop indexes which record. Read first, because a record nobody indexes is a
     // constant rather than a variant axis.
@@ -584,10 +693,49 @@ axesOut) {
             axesOut[axis] = [...new Set([...(axesOut[axis] ?? []), ...names])];
         }
         for (const option of options) {
-            const per = splitByCondition(literalClasses(option.value), {
-                [axis]: option.key,
-            });
-            layers.push(...per.layers);
+            /**
+             * A VALUE THAT IS AN OBJECT IS A PER-PART TABLE, and merging its fields is
+             * what painted a card with its status dot's grey. Read field by field, and
+             * attribute each one to the element that consumes it.
+             */
+            const fields = objectFields(option.value);
+            if (fields.length === 0) {
+                /**
+                 * A STRING-VALUED RECORD IS STILL SOMEBODY'S ELEMENT, and it is the bigger
+                 * half of the form: their HorizontalProgress writes `variantColors[variant]`
+                 * on the FILL, and six colours landed on the outer wrapper - the whole
+                 * component painted ocean-500 instead of the bar inside it.
+                 *
+                 * Unattributed here means the call site could not be found, and that is the
+                 * old behaviour: the layer stays on the component, which is where a record
+                 * consumed at the root belongs anyway.
+                 */
+                const on = callSiteClasses(clean, symbol);
+                const per = splitByCondition(literalClasses(option.value), {
+                    [axis]: option.key,
+                });
+                for (const layer of per.layers)
+                    layers.push(on ? { ...layer, onClasses: on } : layer);
+                continue;
+            }
+            for (const field of fields) {
+                const classes = literalClasses(field.value);
+                if (classes.length === 0)
+                    continue;
+                const on = callSiteClasses(clean, symbol, field.key);
+                if (!on) {
+                    /**
+                     * NOWHERE TO PUT IT IS NOT THE ROOT. A field no `className` claims is a
+                     * decision we cannot place, and placing it on the component would paint
+                     * the wrong element - which is the whole bug this reads around.
+                     */
+                    unattributed?.push(`\`${symbol}.${field.key}\` is a field of a per-element table that no \`className\` call consumes, so there is no element to put it on`);
+                    continue;
+                }
+                const per = splitByCondition(classes, { [axis]: option.key });
+                for (const layer of per.layers)
+                    layers.push({ ...layer, onClasses: on });
+            }
         }
     }
     return layers;
@@ -645,17 +793,17 @@ export function readClassTernaries(source) {
 export function transcribeVariants(source, declared) {
     const reads = readVariants(source);
     const fromRecords = {};
+    const unslotted = [];
     const inline = [
         ...readInlineConditions(source),
         // The two shapes the enumeration found to be five times more common than `cva`.
-        ...readLookupRecords(source, fromRecords),
+        ...readLookupRecords(source, fromRecords, unslotted),
         ...readClassTernaries(source),
     ];
     const axes = {};
     const defaults = {};
     const allLayers = [];
     const baseClasses = [];
-    const unslotted = [];
     for (const read of reads) {
         baseClasses.push(...read.base);
         allLayers.push(...read.layers);
@@ -674,6 +822,51 @@ export function transcribeVariants(source, declared) {
         if (options.length >= 2)
             axes[axis] = options;
     }
+    /**
+     * AN AXIS A LAYER GATES ON MUST BE DECLARED - or the default cannot be emitted.
+     *
+     * The same pass emitted a layer gated on `variant` and did not register `variant`
+     * as an axis: measured on a real library, 30 of 148 root layers name an axis
+     * `declaredAxes` never lists, and four of those are REAL option axes
+     * (`Input.variant`, `Textarea.variant`, `SelectionCard.size`, `RadioCard.status`).
+     * Undeclared means `defaults` cannot name it, so the compiler never emits the
+     * resting option at the bare selector - the same mechanism that made a button
+     * arrive with no fill (dono, 03/08).
+     *
+     * A gate whose values are only `true`/`false` is a BOOLEAN condition, not a design
+     * axis: `isLoading`, `isUser`, `darkMode`, and even an `onInfoClick` handler read
+     * that way. Those keep their layer - their code really does change look - and are
+     * named in `unslotted`, because a consumer has to set the attribute for it to fire
+     * and silence would make it dead CSS nobody knows about.
+     */
+    const BOOLEANISH = new Set(["true", "false"]);
+    const gated = {};
+    for (const layer of allLayers) {
+        for (const [axis, option] of Object.entries(layer.when?.variant ?? {})) {
+            const seen = gated[axis] ?? new Set();
+            seen.add(option);
+            gated[axis] = seen;
+        }
+    }
+    for (const [axis, options] of Object.entries(gated)) {
+        if (axes[axis])
+            continue;
+        const named = [...options].filter((o) => !BOOLEANISH.has(o));
+        /**
+         * TWO OPTIONS IS WHAT MAKES AN AXIS, and that rule is older than this one: one
+         * option is not a closed set somebody chose from, it is how the component is
+         * always used - and declaring it would turn every other value into drift on the
+         * strength of a single sighting.
+         */
+        if (named.length >= 2) {
+            axes[axis] = named;
+            continue;
+        }
+        const attr = axis.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+        unslotted.push(named.length === 0
+            ? `\`${axis}\` gates a look and is a boolean rather than an axis - the layer is kept, and \`data-${attr}\` has to be set for it to apply`
+            : `\`${axis}\` gates a look on one option (\`${named[0]}\`) - one option is not an axis, so the layer is kept and \`data-${attr}="${named[0]}"\` has to be set for it to apply`);
+    }
     const layers = allLayers
         .map((layer) => {
         /**
@@ -690,6 +883,7 @@ export function transcribeVariants(source, declared) {
         return {
             ...(layer.when ? { when: layer.when } : {}),
             ...(layer.at ? { at: layer.at } : {}),
+            ...(layer.onClasses ? { onClasses: layer.onClasses } : {}),
             style,
         };
     })

package/package.json

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