synthesisui 0.16.80 → 0.16.82

package/dist/doctor/variant-read.js

@@ -0,0 +1,584 @@
+/**
+ * THE VARIANT STYLES, READ OUT OF THE SOURCE - deterministically, no model.
+ *
+ * Every imported component arrived with `variants[axis][option] = {}`: the axes came
+ * from the TYPE, which says an axis EXISTS and nothing about what it does. So a real
+ * `Button` with nine variants and six sizes previewed as one look, and you were seeing
+ * a third of the component (dono, 01/08).
+ *
+ * The styling was sitting in the file the whole time, structured:
+ *
+ *     const buttonVariants = cva("inline-flex rounded-[var(--radius-md)] …", {
+ *       variants: {
+ *         variant: { ocean: "bg-ocean-950 text-white hover:bg-ocean-900 dark:…" },
+ *         size:    { sm: "h-10 px-3 [font-size:var(--text-body-s)]" },
+ *       },
+ *       defaultVariants: { variant: "vibrant-purple", size: "md" },
+ *     })
+ *
+ * Nine real colours, six real heights, and their own hover per variant. An object
+ * literal, so reading it needs no model and no guess - which is the whole rule this
+ * codebase runs on: deterministic first, a model only for what genuinely has no form.
+ *
+ * WHAT IT READS
+ *   cva(base, { variants, defaultVariants, compoundVariants })
+ *   tv({ base, variants, defaultVariants })          - tailwind-variants
+ *   cn("always", cond && "sometimes")                - where the condition names a
+ *                                                      prop and a value
+ *
+ * SOURCE ORDER IS PRESERVED, and that is not tidiness. Two classes touching one
+ * property resolve in their app by position in the string; a recipe resolves by
+ * position in `layers`. They agree only if the reader inserts in the order it read.
+ */
+import { parseClass, transcribe } from "./transcribe.js";
+/**
+ * A Tailwind modifier, mapped to the condition it IS.
+ *
+ * `group-hover:` is the whole reason `within` exists: it means "when the thing around
+ * me is hovered", which is a different claim from `hover:` and had no expression at
+ * all before. `peer-*` is the sibling version of the same idea and reads the same way
+ * from a recipe's point of view.
+ */
+const MODIFIER_STATE = {
+    hover: "hover",
+    focus: "focus",
+    "focus-visible": "focusVisible",
+    "focus-within": "focus",
+    active: "active",
+    disabled: "disabled",
+    checked: "checked",
+    indeterminate: "checked",
+    selected: "selected",
+    open: "open",
+    invalid: "invalid",
+    required: "required",
+    "read-only": "readOnly",
+    placeholder: "placeholder",
+    even: "even",
+    odd: "odd",
+    first: "first",
+    last: "last",
+    empty: "empty",
+    "aria-checked": "checked",
+    "aria-selected": "selected",
+    "aria-expanded": "open",
+    "aria-invalid": "invalid",
+    "aria-busy": "loading",
+};
+/** `group-hover`, `group-focus`, `peer-checked` - the state of something ELSE. */
+const RELATIONAL = /^(?:group|peer)-(.+)$/;
+/** `data-[state=open]:`, `data-[checked]:` - how @base-ui and Radix spell a state. */
+const DATA_MODIFIER = /^data-\[(?:state=)?([a-z-]+)\]$/;
+/** A breakpoint is a bare name we cannot read as a state. Their scale names them, so
+ *  the caller decides whether the name exists rather than this guessing a width. */
+const BREAKPOINT = /^(?:xs|sm|md|lg|xl|2xl|3xl|tablet|desktop|wide|mobile)$/;
+/** What a modifier chain means, as a condition. Order inside the chain does not
+ *  matter to CSS, so this folds rather than sequences. */
+export function conditionOf(modifiers) {
+    const out = {};
+    for (const raw of modifiers) {
+        if (raw === "dark") {
+            // The dark half has its own home in the transcription and no slot inside a
+            // layer. Saying so beats writing the light value into a dark rule.
+            out.lost = true;
+            continue;
+        }
+        const relational = RELATIONAL.exec(raw);
+        if (relational) {
+            const state = MODIFIER_STATE[relational[1]];
+            if (state)
+                out.within = state;
+            else
+                out.lost = true;
+            continue;
+        }
+        const data = DATA_MODIFIER.exec(raw);
+        if (data) {
+            const state = MODIFIER_STATE[data[1]];
+            if (state)
+                out.state = state;
+            else
+                out.lost = true;
+            continue;
+        }
+        const state = MODIFIER_STATE[raw];
+        if (state) {
+            out.state = state;
+            continue;
+        }
+        if (BREAKPOINT.test(raw)) {
+            out.at = raw;
+            continue;
+        }
+        out.lost = true;
+    }
+    return out;
+}
+/** A stable key for a condition, so classes sharing one land in one layer. */
+function keyOf(c, variant) {
+    const v = Object.entries(variant ?? {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, o]) => `${k}=${o}`)
+        .join("&");
+    return `${v}|${c.state ?? ""}|${c.within ?? ""}|${c.at ?? ""}`;
+}
+/**
+ * Split a class list into the base and the conditional layers it contains.
+ *
+ * `variant` travels through untouched, so the ghost button's own hover comes out as
+ * `{ variant: { variant: "ghost" }, state: "hover" }` - one selector, which is exactly
+ * what one hover per element could never say.
+ */
+export function splitByCondition(classes, variant) {
+    const base = [];
+    const unslotted = [];
+    // A Map keeps insertion order, which IS the cascade order we promise to preserve.
+    const layers = new Map();
+    for (const cls of classes) {
+        const { modifiers } = parseClass(cls);
+        if (modifiers.length === 0) {
+            if (variant) {
+                const key = keyOf({}, variant);
+                const at = layers.get(key) ?? { when: { variant }, classes: [] };
+                at.classes.push(cls);
+                layers.set(key, at);
+            }
+            else {
+                base.push(cls);
+            }
+            continue;
+        }
+        const cond = conditionOf(modifiers);
+        if (cond.lost) {
+            unslotted.push(cls);
+            continue;
+        }
+        const key = keyOf(cond, variant);
+        const layer = layers.get(key) ??
+            {
+                ...(variant || cond.state || cond.within
+                    ? {
+                        when: {
+                            ...(variant ? { variant } : {}),
+                            ...(cond.state ? { state: cond.state } : {}),
+                            ...(cond.within ? { within: cond.within } : {}),
+                        },
+                    }
+                    : {}),
+                ...(cond.at ? { at: cond.at } : {}),
+                classes: [],
+            };
+        layer.classes.push(cls);
+        layers.set(key, layer);
+    }
+    return { base, layers: [...layers.values()], unslotted };
+}
+// ---------------------------------------------------------------------------
+// Reading the literal
+// ---------------------------------------------------------------------------
+/** From an opening delimiter, the index just past its match. Depth-counted, and
+ *  string-aware so a brace inside a class list cannot end the object early. */
+function endOf(source, open) {
+    const pairs = { "(": ")", "{": "}", "[": "]" };
+    const close = pairs[source[open]];
+    if (!close)
+        return -1;
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === source[open])
+            depth += 1;
+        else if (ch === close) {
+            depth -= 1;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+/**
+ * Every string literal in a fragment, concatenated.
+ *
+ * A real `cva` base is two strings joined by `+` across a line break, and a template
+ * literal with no interpolation is the same thing spelled differently. Anything with
+ * a `${}` in it is a runtime value and is left alone rather than half-read.
+ */
+export function literalClasses(fragment) {
+    const out = [];
+    const re = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|`([^`]*)`/g;
+    for (const m of fragment.matchAll(re)) {
+        const raw = m[1] ?? m[2] ?? m[3] ?? "";
+        if (m[3] != null && raw.includes("${"))
+            continue;
+        out.push(...raw.split(/\s+/).filter(Boolean));
+    }
+    return out;
+}
+/**
+ * Line and block comments removed, quotes respected.
+ *
+ * A real `cva` annotates its sizes - `sm: "h-10 px-3", // 32px` - and without this the
+ * comment became part of the NEXT key: the axis came back with an option literally
+ * called `"// 24px\n        sm"` (probe, 01/08).
+ */
+export function stripComments(body) {
+    let out = "";
+    let quote = null;
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (quote) {
+            out += ch;
+            if (ch === "\\") {
+                out += body[i + 1] ?? "";
+                i += 1;
+            }
+            else if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && body[i + 1] === "/") {
+            const nl = body.indexOf("\n", i);
+            if (nl === -1)
+                break;
+            i = nl - 1;
+            continue;
+        }
+        if (ch === "/" && body[i + 1] === "*") {
+            const close = body.indexOf("*/", i + 2);
+            if (close === -1)
+                break;
+            i = close + 1;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/** `key: <value>` at the top level of an object body, value returned verbatim. */
+function topLevelEntries(raw) {
+    const body = stripComments(raw);
+    const out = [];
+    let i = 0;
+    let quote = null;
+    let depth = 0;
+    let keyStart = 0;
+    let key = null;
+    let valueStart = 0;
+    for (; i < body.length; i++) {
+        const ch = body[i];
+        if (quote) {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if ("([{".includes(ch)) {
+            depth += 1;
+            continue;
+        }
+        if (")]}".includes(ch)) {
+            depth -= 1;
+            continue;
+        }
+        if (depth !== 0)
+            continue;
+        if (ch === ":" && key === null) {
+            key = body
+                .slice(keyStart, i)
+                .trim()
+                .replace(/^["']|["']$/g, "");
+            valueStart = i + 1;
+            continue;
+        }
+        if (ch === "," && key !== null) {
+            out.push({ key, value: body.slice(valueStart, i) });
+            key = null;
+            keyStart = i + 1;
+        }
+    }
+    if (key !== null)
+        out.push({ key, value: body.slice(valueStart) });
+    return out;
+}
+/** The first `{` at the top level of an argument list - the options object. */
+function topLevelBrace(args) {
+    let quote = null;
+    let depth = 0;
+    for (let i = 0; i < args.length; i++) {
+        const ch = args[i];
+        if (quote) {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "{" && depth === 0)
+            return i;
+        if ("([".includes(ch))
+            depth += 1;
+        else if (")]".includes(ch))
+            depth -= 1;
+    }
+    return -1;
+}
+/** The raw value of `name:` in an object body, or null. */
+function valueAt(body, name) {
+    for (const entry of topLevelEntries(body)) {
+        if (entry.key === name)
+            return entry.value;
+    }
+    return null;
+}
+/** The body of `name: { … }` inside an object body, or null. */
+function objectAt(body, name) {
+    for (const entry of topLevelEntries(body)) {
+        if (entry.key !== name)
+            continue;
+        const open = entry.value.indexOf("{");
+        if (open === -1)
+            return null;
+        const end = endOf(entry.value, open);
+        return end === -1 ? null : entry.value.slice(open + 1, end - 1);
+    }
+    return null;
+}
+/** `const NAME = cva(` / `= tv(` - the assignment, so a call site can find it. */
+const VARIANT_CALL = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(cva|tv|cn)\s*\(/g;
+/**
+ * Every variant definition in a file, in source order.
+ *
+ * A file usually has one; a compound component has one per part, which is why the
+ * symbol travels - `cardVariants` and `cardHeaderVariants` are two different things
+ * and only their names say which is which.
+ */
+export function readVariants(source) {
+    const out = [];
+    VARIANT_CALL.lastIndex = 0;
+    for (const m of source.matchAll(VARIANT_CALL)) {
+        const symbol = m[1];
+        const kind = m[2];
+        const open = (m.index ?? 0) + m[0].length - 1;
+        const end = endOf(source, open);
+        if (end === -1)
+            continue;
+        const args = source.slice(open + 1, end - 1);
+        /**
+         * TWO LEVELS, AND CONFLATING THEM READ NOTHING.
+         *
+         * `cva("base classes", { variants: … })` is an argument list whose SECOND item is
+         * the options object. Reading `variants` off the argument list finds nothing,
+         * because at that level `variants:` sits one brace deep - the first version came
+         * back with zero axes from a file declaring fifteen (probe, 01/08).
+         */
+        const optionsOpen = topLevelBrace(args);
+        const optionsEnd = optionsOpen === -1 ? -1 : endOf(args, optionsOpen);
+        const options = optionsOpen === -1 || optionsEnd === -1
+            ? ""
+            : args.slice(optionsOpen + 1, optionsEnd - 1);
+        // `tv({ base: … })` names its base; `cva(base, { … })` puts it first.
+        const leadingBase = kind === "tv" || optionsOpen === -1 ? "" : args.slice(0, optionsOpen);
+        const namedBase = valueAt(options, "base");
+        const read = {
+            symbol,
+            base: literalClasses(leadingBase || namedBase || ""),
+            variants: {},
+            defaults: {},
+            layers: [],
+            unslotted: [],
+        };
+        // The base's own modifiers are layers too: a `cva` base carries
+        // `disabled:opacity-50` and `focus-visible:ring-2` before any variant exists.
+        const split = splitByCondition(read.base);
+        read.base = split.base;
+        read.layers.push(...split.layers);
+        read.unslotted.push(...split.unslotted);
+        const variantsBody = objectAt(options, "variants");
+        if (variantsBody) {
+            for (const axis of topLevelEntries(variantsBody)) {
+                const openBrace = axis.value.indexOf("{");
+                if (openBrace === -1)
+                    continue;
+                const axisEnd = endOf(axis.value, openBrace);
+                if (axisEnd === -1)
+                    continue;
+                const axisBody = axis.value.slice(openBrace + 1, axisEnd - 1);
+                for (const option of topLevelEntries(axisBody)) {
+                    const classes = literalClasses(option.value);
+                    if (classes.length === 0)
+                        continue;
+                    read.variants[axis.key] ??= {};
+                    read.variants[axis.key][option.key] = classes;
+                    const per = splitByCondition(classes, { [axis.key]: option.key });
+                    read.layers.push(...per.layers);
+                    read.unslotted.push(...per.unslotted);
+                }
+            }
+        }
+        const defaultsBody = objectAt(options, "defaultVariants");
+        if (defaultsBody) {
+            for (const entry of topLevelEntries(defaultsBody)) {
+                const value = literalClasses(entry.value)[0];
+                if (value)
+                    read.defaults[entry.key] = value;
+            }
+        }
+        /**
+         * COMPOUND VARIANTS ARE THE CASE `layers` WAS SHAPED FOR.
+         *
+         * `{ variant: "ghost", size: "sm", class: "px-2" }` is two axes holding at once,
+         * which a flat `variants` map cannot express at all - it has one key per axis. It
+         * comes out as one layer with two conditions and one selector.
+         */
+        const compoundIdx = options.search(/compoundVariants\s*:\s*\[/);
+        if (compoundIdx !== -1) {
+            const arrOpen = options.indexOf("[", compoundIdx);
+            const arrEnd = endOf(options, arrOpen);
+            if (arrEnd !== -1) {
+                const arr = options.slice(arrOpen + 1, arrEnd - 1);
+                let cursor = 0;
+                while (cursor < arr.length) {
+                    const objOpen = arr.indexOf("{", cursor);
+                    if (objOpen === -1)
+                        break;
+                    const objEnd = endOf(arr, objOpen);
+                    if (objEnd === -1)
+                        break;
+                    const body = arr.slice(objOpen + 1, objEnd - 1);
+                    const variant = {};
+                    let classes = [];
+                    for (const entry of topLevelEntries(body)) {
+                        if (entry.key === "class" || entry.key === "className") {
+                            classes = literalClasses(entry.value);
+                            continue;
+                        }
+                        const value = literalClasses(entry.value)[0];
+                        if (value)
+                            variant[entry.key] = value;
+                    }
+                    if (classes.length > 0 && Object.keys(variant).length > 0) {
+                        const per = splitByCondition(classes, variant);
+                        read.layers.push(...per.layers);
+                        read.unslotted.push(...per.unslotted);
+                    }
+                    cursor = objEnd;
+                }
+            }
+        }
+        out.push(read);
+    }
+    return out;
+}
+/**
+ * A CONDITIONAL CLASS EXPRESSION - the other half of how real components style.
+ *
+ * `cn("base", variant === "solid" && "bg-primary", disabled && "opacity-50")`. The
+ * literal is right there beside the condition, and when the condition names a prop
+ * and a value it names a variant. When it names only a prop (`disabled && …`) it reads
+ * as that prop being truthy, which for a boolean IS the variant.
+ *
+ * Read separately from `cva` because a file can have both, and because this shape is
+ * what a codebase that never adopted a variant library uses everywhere.
+ */
+const INLINE_COND = /([A-Za-z_$][\w$.]*)\s*(?:===|==)\s*["']([^"']+)["']\s*&&\s*(["'`])((?:(?!\3).)*)\3|([A-Za-z_$][\w$]*)\s*&&\s*(["'`])((?:(?!\6).)*)\6/g;
+export function readInlineConditions(source) {
+    const layers = [];
+    INLINE_COND.lastIndex = 0;
+    for (const m of source.matchAll(INLINE_COND)) {
+        const prop = (m[1] ?? m[5] ?? "").split(".").pop() ?? "";
+        const option = m[2] ?? "true";
+        const raw = m[4] ?? m[7] ?? "";
+        if (!prop || raw.includes("${"))
+            continue;
+        const classes = raw.split(/\s+/).filter(Boolean);
+        if (classes.length === 0)
+            continue;
+        const per = splitByCondition(classes, { [prop]: option });
+        layers.push(...per.layers);
+    }
+    return layers;
+}
+/**
+ * The whole reading of one file's variant styling, transcribed - ready for a recipe.
+ *
+ * `declared` is their own custom properties, so `bg-ocean-950` comes out as a ref to
+ * the token they declared rather than as a hex we looked up.
+ */
+export function transcribeVariants(source, declared) {
+    const reads = readVariants(source);
+    const inline = readInlineConditions(source);
+    const axes = {};
+    const defaults = {};
+    const allLayers = [];
+    const baseClasses = [];
+    const unslotted = [];
+    for (const read of reads) {
+        baseClasses.push(...read.base);
+        allLayers.push(...read.layers);
+        unslotted.push(...read.unslotted);
+        Object.assign(defaults, read.defaults);
+        for (const [axis, options] of Object.entries(read.variants)) {
+            const names = Object.keys(options);
+            // Two options is what makes a closed set somebody chose from - the same rule
+            // the contract writer and the doctor already follow.
+            if (names.length >= 2)
+                axes[axis] = names;
+        }
+    }
+    allLayers.push(...inline);
+    const layers = allLayers
+        .map((layer) => {
+        /**
+         * THE MODIFIER COMES OFF BEFORE THE TRANSCRIPTION.
+         *
+         * The condition is already carried by the layer, so `hover:bg-ocean-900` has to
+         * arrive as `bg-ocean-900`. Left on, `transcribe` correctly filed it under
+         * `states.hover` - and this reads `base`, so every hover in a nine-variant
+         * button vanished (probe, 01/08).
+         */
+        const bare = layer.classes.map((cls) => parseClass(cls).utility);
+        const t = transcribe(bare, declared);
+        const style = { ...t.base, ...t.dark };
+        return {
+            ...(layer.when ? { when: layer.when } : {}),
+            ...(layer.at ? { at: layer.at } : {}),
+            style,
+        };
+    })
+        .filter((layer) => Object.keys(layer.style).length > 0);
+    return {
+        reads,
+        axes,
+        defaults,
+        layers,
+        base: transcribe(baseClasses, declared),
+        unslotted,
+    };
+}

package/dist/progress.js

@@ -0,0 +1,71 @@
+/**
+ * WHAT IS HAPPENING RIGHT NOW, and how much is left.
+ *
+ * "While the design system import is running it would be good to have an animated
+ * progress and underneath the current component and a (10 of 1235)" (dono, 01/08).
+ *
+ * A census over a real monorepo reads 2797 files and the terminal said nothing for
+ * most of it. Twenty silent minutes is indistinguishable from twenty broken ones, and
+ * that is the difference this makes: not speed, but the ability to wait.
+ *
+ * TWO AUDIENCES, ONE API. A person at a terminal gets a bar that redraws in place; the
+ * skill runs the CLI with no TTY and pipes the output, so it gets a plain milestone
+ * line every so often. Neither has to know about the other, and the non-TTY path never
+ * writes a carriage return into a transcript.
+ */
+const BAR_WIDTH = 24;
+/** Every this-many items, the non-TTY path prints one line. Enough to see movement in
+ *  a piped log without turning it into the log. */
+const MILESTONE_EVERY = 25;
+/** A bar that reads as a bar at any width. Two glyphs, no colour: this line is
+ *  overwritten dozens of times a second and anything fancier flickers. */
+function bar(done, total) {
+    const ratio = total > 0 ? Math.min(1, done / total) : 0;
+    const filled = Math.round(ratio * BAR_WIDTH);
+    return `${"█".repeat(filled)}${"░".repeat(BAR_WIDTH - filled)}`;
+}
+/** Truncated from the LEFT, because the end of a path is the part that identifies it. */
+function tail(label, width) {
+    if (label.length <= width)
+        return label;
+    return `…${label.slice(-(width - 1))}`;
+}
+export function startProgress(title, opts) {
+    const write = opts?.write ?? ((s) => process.stdout.write(s));
+    const tty = opts?.isTty ?? Boolean(process.stdout.isTTY);
+    let total = opts?.total ?? 0;
+    let done = 0;
+    let last = "";
+    const paint = () => {
+        const count = total > 0 ? `${done} of ${total}` : String(done);
+        const line = `  ${bar(done, total)}  ${count}  ${tail(last, 40)}`;
+        // Pad to the previous width so a shorter label cannot leave the tail of a
+        // longer one behind on the line.
+        write(`\r${line.padEnd(80)}`);
+    };
+    return {
+        step(label) {
+            done += 1;
+            last = label;
+            if (tty) {
+                paint();
+                return;
+            }
+            // NO CARRIAGE RETURNS IN A TRANSCRIPT. A milestone line every so often, plus
+            // the first one so the reader knows the phase started at all.
+            if (done === 1 || done % MILESTONE_EVERY === 0) {
+                const count = total > 0 ? `${done} of ${total}` : `${done}`;
+                write(`  ${title}: ${count} - ${label}\n`);
+            }
+        },
+        total(n) {
+            total = n;
+        },
+        done(summary) {
+            if (tty)
+                write(`\r${" ".repeat(80)}\r`);
+            if (summary)
+                write(`  ${summary}\n`);
+        },
+    };
+}