nudge-ui 0.2.0

package/dist/compiler/reactIdentity.js

@@ -0,0 +1,339 @@
+import MagicString, {} from "magic-string";
+import { posix } from "node:path";
+import { elementName, isNode, jsxMemberName, parseModule, SKIP_KEYS, } from "./ast.js";
+import { createComponentInstrumentationPolicy, } from "./componentInstrumentation.js";
+import { relativePath, stripModuleExtension } from "./sourcePaths.js";
+export const DEFAULT_COMPONENT_RUNTIME_MODULE = "nudge-ui/internal/component-runtime";
+const PARSEABLE_EXT = /\.(tsx|jsx)$/;
+const EXPRESSION_SCOPE_TYPES = new Set([
+    "FunctionExpression",
+    "ArrowFunctionExpression",
+    "ClassExpression",
+]);
+// Scopes that contribute an id to the scope stack: declarations push their
+// own name; expressions are pushed at their VariableDeclarator binding, or
+// here by their own id (may be null) when anonymous.
+const ALL_SCOPE_TYPES = new Set([
+    "FunctionDeclaration",
+    "ClassDeclaration",
+    ...EXPRESSION_SCOPE_TYPES,
+]);
+const IDENTITY_ATTRS = new Set(["data-cid", "data-src", "data-cprops"]);
+function isComponentName(name) {
+    return /^[A-Z]/.test(name);
+}
+function getScopeName(node) {
+    const id = node.id;
+    return id?.name ?? "";
+}
+function hasAttr(attrs, attrName) {
+    return attrs.some((a) => a.type === "JSXAttribute" &&
+        a.name?.type ===
+            "JSXIdentifier" &&
+        a.name.name === attrName);
+}
+function resolveCid(openingName, scopeStack) {
+    const name = jsxMemberName(openingName);
+    if (name && isComponentName(name))
+        return name;
+    for (let i = scopeStack.length - 1; i >= 0; i--) {
+        const scope = scopeStack[i];
+        if (scope && isComponentName(scope))
+            return scope;
+    }
+    return "Anonymous";
+}
+function serialiseAttribute(attr) {
+    if (attr.type !== "JSXAttribute")
+        return null;
+    const nameNode = attr.name;
+    if (nameNode?.type !== "JSXIdentifier")
+        return null;
+    const key = nameNode.name ?? "";
+    if (!key || IDENTITY_ATTRS.has(key))
+        return null;
+    const value = attr.value;
+    if (value === null || value === undefined) {
+        return `${key}:true`;
+    }
+    if (value.type === "StringLiteral") {
+        return `${key}:${String(value.value)}`;
+    }
+    if (value.type === "NumericLiteral") {
+        return `${key}:${String(value.value)}`;
+    }
+    if (value.type === "BooleanLiteral") {
+        return `${key}:${value.value ? "true" : "false"}`;
+    }
+    if (value.type === "JSXExpressionContainer") {
+        const expr = value.expression;
+        if (!expr)
+            return null;
+        if (expr.type === "StringLiteral") {
+            return `${key}:${String(expr.value)}`;
+        }
+        if (expr.type === "NumericLiteral") {
+            return `${key}:${String(expr.value)}`;
+        }
+        if (expr.type === "BooleanLiteral") {
+            return `${key}:${expr.value ? "true" : "false"}`;
+        }
+        // Inline function expressions are rendered as `fn(key)` per PLAN.md.
+        // Bare identifiers are omitted (they may reference any type — PLAN.md's
+        // canonical example omits `onClick={handleClick}`).
+        if (expr.type === "ArrowFunctionExpression" ||
+            expr.type === "FunctionExpression") {
+            return `${key}:fn(${key})`;
+        }
+        return null;
+    }
+    return null;
+}
+function buildCprops(attrs) {
+    const parts = [];
+    for (const a of attrs) {
+        const part = serialiseAttribute(a);
+        if (part)
+            parts.push(part);
+    }
+    if (parts.length === 0)
+        return null;
+    return parts.join(",");
+}
+function escapeJsxAttribute(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll('"', """)
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function authoredPropKinds(attrs, children = []) {
+    const result = {};
+    for (const attr of attrs) {
+        if (attr.type === "JSXSpreadAttribute") {
+            result["..."] = "spread";
+            continue;
+        }
+        if (attr.type !== "JSXAttribute")
+            continue;
+        const name = elementName(attr.name);
+        if (!name || IDENTITY_ATTRS.has(name) || name === "key" || name === "ref")
+            continue;
+        const value = attr.value;
+        result[name] = value === null || value === undefined
+            || value.type === "StringLiteral"
+            || (value.type === "JSXExpressionContainer"
+                && isNode(value.expression)
+                && (value.expression.type === "StringLiteral"
+                    || value.expression.type === "NumericLiteral"
+                    || value.expression.type === "BooleanLiteral"))
+            ? "literal"
+            : "expression";
+    }
+    const childKind = authoredChildrenKind(children);
+    if (childKind)
+        result.children = childKind;
+    return result;
+}
+/**
+ * Preserve the authored shape of primitive JSX children in invocation
+ * metadata. This is metadata for the dev runtime only; it does not add a
+ * production attribute or wrapper to the application output.
+ */
+function authoredChildrenKind(children) {
+    if (children.length === 0)
+        return null;
+    let kind = null;
+    for (const child of children) {
+        if (child.type === "JSXText") {
+            if (String(child.value ?? "").trim() === "")
+                continue;
+            kind = kind === "spread" || kind === "expression" ? kind : "literal";
+            continue;
+        }
+        if (child.type === "JSXSpreadChild") {
+            kind = "spread";
+            continue;
+        }
+        if (child.type !== "JSXExpressionContainer")
+            continue;
+        const expression = child.expression;
+        if (!expression || expression.type === "JSXEmptyExpression")
+            continue;
+        const literal = expression.type === "StringLiteral"
+            || expression.type === "NumericLiteral"
+            || expression.type === "BooleanLiteral";
+        if (kind === "spread")
+            continue;
+        kind = literal && (kind === null || kind === "literal") ? "literal" : "expression";
+    }
+    return kind;
+}
+function componentIdFor(componentName, relPath, bindings) {
+    const [rootName, ...members] = componentName.split(".");
+    const binding = rootName ? bindings.get(rootName) : undefined;
+    if (!binding)
+        return `${stripModuleExtension(relPath)}#${componentName}`;
+    const moduleId = binding.source.startsWith(".")
+        ? stripModuleExtension(posix.normalize(posix.join(posix.dirname(relPath), binding.source)))
+        : stripModuleExtension(binding.source);
+    const exportName = binding.namespace
+        ? members.join(".") || rootName
+        : binding.exportName ?? rootName;
+    return `${moduleId}#${exportName}`;
+}
+function walkChildren(node, scopeStack, ms, relPath, options, state, allowComponentWrapping) {
+    const opening = node.type === "JSXElement" ? node.openingElement : node;
+    const componentName = opening.type === "JSXOpeningElement" ? elementName(opening.name) : null;
+    const customElement = componentName !== null && (isComponentName(componentName) || componentName.includes("."));
+    for (const key of Object.keys(node)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (isNode(child)) {
+                    // A component can inspect its children or slot props before React
+                    // renders them. Preserve those element values unless the receiving
+                    // interface explicitly promises to render them.
+                    const renderedChild = !customElement
+                        || (key === "children" && state.componentPolicy.rendersChildren(componentName))
+                        || (key === "attributes" && state.componentPolicy.rendersProp(componentName, elementName(child.name) ?? ""))
+                        || (key !== "children" && key !== "attributes");
+                    walk(child, node, scopeStack, ms, relPath, options, state, allowComponentWrapping && renderedChild);
+                }
+            }
+        }
+        else if (isNode(value)) {
+            walk(value, node, scopeStack, ms, relPath, options, state, allowComponentWrapping);
+        }
+    }
+}
+function walk(node, parent, scopeStack, ms, relPath, options, state, allowComponentWrapping) {
+    // A function/class expression bound to a variable inherits the variable's
+    // name as its component name (arrows have no own id).
+    if (node.type === "VariableDeclarator") {
+        const init = node.init ?? null;
+        const varName = node.id?.name ?? null;
+        if (init && varName && EXPRESSION_SCOPE_TYPES.has(init.type)) {
+            scopeStack.push(varName);
+            walkChildren(init, scopeStack, ms, relPath, options, state, allowComponentWrapping);
+            scopeStack.pop();
+            return;
+        }
+    }
+    if (ALL_SCOPE_TYPES.has(node.type)) {
+        // Named/anonymous function and class scopes: push their own id (may be null).
+        scopeStack.push(getScopeName(node));
+        walkChildren(node, scopeStack, ms, relPath, options, state, allowComponentWrapping);
+        scopeStack.pop();
+        return;
+    }
+    if (node.type === "JSXElement" && options.instrumentComponents && allowComponentWrapping) {
+        const opening = node.openingElement;
+        const openingName = opening?.name;
+        const componentName = elementName(openingName);
+        const start = node.start;
+        const end = node.end;
+        const loc = openingName?.loc;
+        const line = loc?.start?.line;
+        const column = loc?.start?.column;
+        if (componentName
+            && (isComponentName(componentName) || componentName.includes("."))
+            && state.componentPolicy.canWrap(componentName)
+            && typeof start === "number"
+            && typeof end === "number"
+            && typeof line === "number"
+            && typeof column === "number") {
+            const attrs = opening?.attributes ?? [];
+            const meta = {
+                callsiteId: `${relPath}:${line}:${column + 1}`,
+                componentId: state.componentPolicy.componentId(componentName)
+                    ?? componentIdFor(componentName, relPath, state.componentPolicy.bindings),
+                componentName,
+                file: relPath,
+                line,
+                column: column + 1,
+                authoredProps: authoredPropKinds(attrs, node.children ?? []),
+            };
+            const needsExpression = parent?.type === "JSXElement" || parent?.type === "JSXFragment";
+            // appendRight preserves insertion order when two JSX siblings have no
+            // whitespace between them. At the shared `</First><Second>` boundary,
+            // the first component's closing wrapper must be emitted before the
+            // second component's opening wrapper.
+            ms.appendRight(start, `${needsExpression ? "{" : ""}__nudgeUiInstrumentComponent(`);
+            ms.appendRight(end, `, ${JSON.stringify(meta)})${needsExpression ? "}" : ""}`);
+            state.changed = true;
+            state.instrumentedComponents = true;
+        }
+    }
+    if (node.type === "JSXOpeningElement") {
+        const attrs = node.attributes ?? [];
+        const nameNode = node.name;
+        // TypeScript JSX type arguments sit between the component name and its
+        // attributes (`<Button<Props> size="small" />`). Injecting immediately
+        // after the name would produce the invalid `<Button data-cid...<Props>`
+        // shape, so place identity attributes after the complete type argument
+        // list when one is present.
+        const typeArguments = node.typeArguments ??
+            node.typeParameters;
+        const end = typeArguments?.end ??
+            nameNode.end ??
+            null;
+        if (typeof end === "number") {
+            if (!hasAttr(attrs, "data-cid")) {
+                const cid = resolveCid(nameNode, scopeStack);
+                ms.appendRight(end, ` data-cid="${cid}"`);
+                state.changed = true;
+            }
+            if (!hasAttr(attrs, "data-src")) {
+                const loc = nameNode.loc;
+                const line = loc?.start?.line;
+                const col = loc?.start?.column;
+                // Babel columns are 0-indexed; emit 1-indexed to match __source.
+                if (typeof line === "number" && typeof col === "number") {
+                    ms.appendRight(end, ` data-src="${relPath}:${line}:${col + 1}"`);
+                    state.changed = true;
+                }
+            }
+            if (!hasAttr(attrs, "data-cprops")) {
+                const cprops = buildCprops(attrs);
+                if (cprops) {
+                    ms.appendRight(end, ` data-cprops="${escapeJsxAttribute(cprops)}"`);
+                    state.changed = true;
+                }
+            }
+        }
+    }
+    walkChildren(node, scopeStack, ms, relPath, options, state, allowComponentWrapping);
+}
+export function injectIdentity(code, id, root, options = {}) {
+    if (id.includes("/node_modules/"))
+        return null;
+    if (!PARSEABLE_EXT.test(id))
+        return null;
+    const ast = parseModule(code);
+    if (!ast)
+        return null;
+    const ms = new MagicString(code);
+    const relPath = relativePath(id, root);
+    const state = {
+        changed: false,
+        instrumentedComponents: false,
+        componentPolicy: createComponentInstrumentationPolicy(ast, options),
+    };
+    walk(ast, null, [], ms, relPath, options, state, true);
+    if (!state.changed)
+        return null;
+    if (state.instrumentedComponents) {
+        const runtimeModule = options.componentRuntimeModule ?? DEFAULT_COMPONENT_RUNTIME_MODULE;
+        ms.prepend(`import { instrumentReactComponent as __nudgeUiInstrumentComponent } from ${JSON.stringify(runtimeModule)};\n`);
+    }
+    return {
+        code: ms.toString(),
+        map: ms.generateMap({ source: id, hires: true }),
+    };
+}
+export function injectDataCid(code, id, root) {
+    return injectIdentity(code, id, root);
+}

package/dist/compiler/sourcePaths.d.ts

@@ -0,0 +1,12 @@
+/** Strip a TypeScript or JavaScript module extension from a resolved path. */
+export declare function stripModuleExtension(value: string): string;
+/**
+ * Project-relative source path used by `data-src`, callsite identity, and
+ * catalog keys.
+ *
+ * A file outside the project root (an authored workspace package) keeps a
+ * `../`-prefixed relative path, so identity stays unique across packages and
+ * machine paths never reach the DOM or a prompt. Every host Adapter reads this
+ * function so their identity strings cannot drift.
+ */
+export declare function relativePath(id: string, root?: string): string;

package/dist/compiler/sourcePaths.js

@@ -0,0 +1,27 @@
+import { posix } from "node:path";
+/** Strip a TypeScript or JavaScript module extension from a resolved path. */
+export function stripModuleExtension(value) {
+    return value.replace(/\.(?:d\.)?[cm]?[jt]sx?$/, "");
+}
+/**
+ * Project-relative source path used by `data-src`, callsite identity, and
+ * catalog keys.
+ *
+ * A file outside the project root (an authored workspace package) keeps a
+ * `../`-prefixed relative path, so identity stays unique across packages and
+ * machine paths never reach the DOM or a prompt. Every host Adapter reads this
+ * function so their identity strings cannot drift.
+ */
+export function relativePath(id, root) {
+    if (root) {
+        const rootPrefix = root.endsWith("/") ? root : `${root}/`;
+        if (id.startsWith(rootPrefix))
+            return id.slice(rootPrefix.length);
+        if (id.startsWith("/") && root.startsWith("/")) {
+            const relativeId = posix.relative(root, id);
+            if (relativeId && relativeId !== ".")
+                return relativeId;
+        }
+    }
+    return id.replace(/^\//, "");
+}

package/dist/css/dialects/index.d.ts

@@ -0,0 +1,62 @@
+import type { TokenCatalogDiagnostic } from "../model/index.js";
+import type { InventoryDiagnostic, TokenContribution } from "../token-inventory/types.js";
+export * from "./tailwind.js";
+export * from "./vanillaExtract.js";
+/**
+ * Host-neutral interpretation of CSS dialects. Hosts see very different things
+ * — a Vite host watches the whole transform pipeline, a static-file host only
+ * reads `.css` off disk — so each supplies the evidence it can observe and this
+ * module turns exactly that into token knowledge. It is pure, so the same
+ * evidence yields the same tokens on every host and dialect behaviour can be
+ * tested without a build tool. A host that observes less reports less through
+ * `DialectObservation` rather than quietly producing a thinner catalog.
+ */
+export type DialectName = "tailwind-v3" | "tailwind-v4" | "vanilla-extract";
+export interface TailwindV3Evidence {
+    readonly config: unknown;
+    /** Path recorded on the resulting tokens. */
+    readonly source?: string;
+}
+/** A theme contract written inline in host configuration. */
+export interface InlineThemeContractEvidence {
+    readonly contract: unknown;
+    /** Compiled values by custom-property name, when the host observed the CSS. */
+    readonly cssValues?: Readonly<Record<string, string>>;
+    readonly source?: string;
+}
+/** A theme contract loaded from a published module. */
+export interface PublishedThemeContractEvidence {
+    /** Separates "never looked" from "looked and found nothing"; only the latter clears a held contract. */
+    readonly attempted: boolean;
+    readonly contract: unknown;
+    /** Whether the contract came from a dependency rather than project source. */
+    readonly fromPackage?: boolean;
+    readonly prefix?: string;
+    readonly source?: string;
+    readonly diagnostics?: readonly TokenCatalogDiagnostic[];
+}
+/** Everything a host managed to observe about the project's dialects. */
+export interface DialectEvidence {
+    readonly tailwindV3?: TailwindV3Evidence;
+    /** True when any observed stylesheet carried Tailwind v4 markers. */
+    readonly tailwindV4Css?: boolean;
+    readonly inlineThemeContract?: InlineThemeContractEvidence;
+    readonly publishedThemeContract?: PublishedThemeContractEvidence;
+    readonly diagnostics?: readonly InventoryDiagnostic[];
+}
+export interface DialectObservation {
+    readonly dialect: DialectName;
+    readonly evidence: "none" | "config" | "contract" | "css";
+    readonly tokenCount: number;
+}
+export interface DialectInterpretation {
+    /** Apply to the token inventory in this order. */
+    readonly contributions: readonly TokenContribution[];
+    readonly observed: readonly DialectObservation[];
+}
+/**
+ * Every contribution is emitted on every call, empty when a dialect has no
+ * evidence: they are id-keyed and replaceable, so omitting one would leave
+ * stale facts in the inventory rather than clearing them.
+ */
+export declare function interpretDialects(evidence?: DialectEvidence): DialectInterpretation;

package/dist/css/dialects/index.js

@@ -0,0 +1,103 @@
+import { isTailwindV3Config, readTailwindV3Config, tailwindV4Relabelling } from "./tailwind.js";
+import { readThemeContract } from "./vanillaExtract.js";
+export * from "./tailwind.js";
+export * from "./vanillaExtract.js";
+/**
+ * Every contribution is emitted on every call, empty when a dialect has no
+ * evidence: they are id-keyed and replaceable, so omitting one would leave
+ * stale facts in the inventory rather than clearing them.
+ */
+export function interpretDialects(evidence = {}) {
+    const observed = [];
+    const tailwindV3Tokens = readTailwindV3Evidence(evidence.tailwindV3);
+    observed.push({
+        dialect: "tailwind-v3",
+        evidence: evidence.tailwindV3 === undefined ? "none" : "config",
+        tokenCount: tailwindV3Tokens.length,
+    });
+    const inlineTokens = readInlineContract(evidence.inlineThemeContract);
+    const contributions = [{
+            id: "dialect-tokens",
+            order: -1,
+            tokens: [...tailwindV3Tokens, ...inlineTokens],
+            diagnostics: [...(evidence.diagnostics ?? [])],
+        }];
+    const tailwindV4 = evidence.tailwindV4Css === true;
+    contributions.push(tailwindV4 ? tailwindV4Relabelling() : { id: "tailwind-v4-naming", order: 0 });
+    observed.push({
+        dialect: "tailwind-v4",
+        evidence: tailwindV4 ? "css" : "none",
+        // v4 tokens are already in the parsed CSS; this dialect only relabels them.
+        tokenCount: 0,
+    });
+    const published = readPublishedContract(evidence.publishedThemeContract);
+    contributions.push(published.contribution);
+    observed.push({
+        dialect: "vanilla-extract",
+        evidence: inlineTokens.length + published.count > 0 ? "contract" : "none",
+        tokenCount: inlineTokens.length + published.count,
+    });
+    return { contributions, observed };
+}
+function readTailwindV3Evidence(evidence) {
+    if (evidence === undefined || !isTailwindV3Config(evidence.config))
+        return [];
+    return readTailwindV3Config(evidence.config, evidence.source);
+}
+function readInlineContract(evidence) {
+    if (evidence === undefined)
+        return [];
+    return readThemeContract(evidence.contract, {
+        source: evidence.source ?? "theme-contract.ts",
+        origin: "project",
+        editable: true,
+        ...(evidence.cssValues === undefined ? {} : { cssValues: evidence.cssValues }),
+    });
+}
+/**
+ * Contributes identity only: the emitted CSS stays authoritative on value,
+ * cascade, and editability, so entries carry no declarations and merge by CSS name.
+ */
+function readPublishedContract(evidence) {
+    const empty = { id: "vanilla-extract-contract", order: 1 };
+    if (evidence === undefined || !evidence.attempted)
+        return { contribution: empty, count: 0 };
+    const diagnostics = evidence.diagnostics ?? [];
+    if (diagnostics.length > 0) {
+        return {
+            contribution: {
+                ...empty,
+                diagnostics: diagnostics.map((diagnostic) => ({
+                    code: diagnostic.code,
+                    artifact: diagnostic.module,
+                    message: diagnostic.message,
+                    ...(diagnostic.exportName === undefined ? {} : { exportName: diagnostic.exportName }),
+                })),
+            },
+            count: 0,
+        };
+    }
+    if (evidence.contract === null || evidence.contract === undefined) {
+        return { contribution: empty, count: 0 };
+    }
+    const entries = readThemeContract(evidence.contract, {
+        ...(evidence.prefix === undefined ? {} : { prefix: evidence.prefix }),
+        source: evidence.source ?? "theme-contract",
+        origin: evidence.fromPackage === true ? "package" : "project",
+        editable: false,
+    });
+    return {
+        contribution: {
+            ...empty,
+            definitions: entries.map((entry) => ({
+                cssName: entry.cssName ?? entry.name,
+                name: entry.name,
+                adapter: entry.adapter,
+                origin: entry.origin,
+                editable: entry.editable,
+                declarations: [],
+            })),
+        },
+        count: entries.length,
+    };
+}

package/dist/css/dialects/tailwind.d.ts

@@ -0,0 +1,46 @@
+import type { TokenEntry } from "../model/index.js";
+import type { TokenContribution } from "../token-inventory/types.js";
+/** Markers proving a stylesheet participates in Tailwind v4. */
+export declare function detectTailwindV4(css: string): boolean;
+/**
+ * v4 tokens reach the CSS whether authored or Tailwind-generated, and the
+ * generic parser cannot tell those apart. Authored `@theme` entries stay
+ * project-owned and editable; generated ones are framework-owned and are not.
+ */
+export declare function tailwindV4Relabelling(): TokenContribution;
+/** A color utility that applies alpha to a catalog token, e.g. `bg-brand/40`. */
+export interface TailwindAlphaUtility {
+    readonly utility: string;
+    /** The base catalog token the utility draws its color from. */
+    readonly baseName: string;
+    /** Normalized alpha, always percent-suffixed. */
+    readonly alpha: string;
+}
+/**
+ * Null when the class is not an alpha utility. The build-time catalog and the
+ * browser runtime both parse this and must agree, or an edit gets attributed
+ * to the wrong token.
+ */
+export declare function readTailwindV4AlphaUtility(className: string): TailwindAlphaUtility | null;
+/** The CSS Tailwind v4 emits for an alpha utility. */
+export declare function tailwindV4AlphaExpression(baseCssName: string, alpha: string): string;
+/** The parts of a v3 config that carry design tokens. */
+export interface TailwindV3Config {
+    theme?: {
+        colors?: Record<string, unknown>;
+        spacing?: Record<string, unknown>;
+        borderWidth?: Record<string, unknown>;
+        borderRadius?: Record<string, unknown>;
+        fontSize?: Record<string, unknown>;
+        fontWeight?: Record<string, unknown>;
+        lineHeight?: Record<string, unknown>;
+        letterSpacing?: Record<string, unknown>;
+        extend?: Record<string, Record<string, unknown>>;
+    };
+    plugins?: unknown[];
+    [key: string]: unknown;
+}
+/** Distinguishes a v3 config object from a v4 one, which has no `theme` key. */
+export declare function isTailwindV3Config(config: unknown): config is TailwindV3Config;
+/** Flattens a v3 config's theme into token entries, applying `theme.extend`. */
+export declare function readTailwindV3Config(config: TailwindV3Config, source?: string): TokenEntry[];