nudge-ui 0.2.0

package/dist/css/dialects/tailwind.js

@@ -0,0 +1,119 @@
+/**
+ * Tailwind's two major versions keep tokens in different places, so they get
+ * separate treatment rather than a shared "Tailwind" concept. v3 keeps them in
+ * a JavaScript config and compiles literal values into utilities, making the
+ * config the only source of authored names. v4 declares them as custom
+ * properties in `@theme`, so parsed CSS is the source of truth and this module
+ * only corrects provenance the generic parser cannot infer.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------
+// Tailwind v4
+// ---------------------------------------------------------------------------
+/** Markers proving a stylesheet participates in Tailwind v4. */
+export function detectTailwindV4(css) {
+    return /@(?:import\s+["']tailwindcss|theme\b)/i.test(css) || /--tw-[\w-]+/.test(css);
+}
+/**
+ * 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 function tailwindV4Relabelling() {
+    return {
+        id: "tailwind-v4-naming",
+        order: 0,
+        relabellings: [
+            { adapter: "tailwind-v4", fromOrigin: "project", origin: "project", editable: true },
+            { adapter: "tailwind-v4", fromOrigin: "generated", origin: "framework", editable: false },
+        ],
+    };
+}
+const V4_ALPHA_UTILITY = /^bg-([\w-]+)\/(\d{1,3}%?)$/;
+/**
+ * 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 function readTailwindV4AlphaUtility(className) {
+    const match = V4_ALPHA_UTILITY.exec(className.trim());
+    const color = match?.[1];
+    const rawAlpha = match?.[2];
+    if (color === undefined || rawAlpha === undefined)
+        return null;
+    const numeric = Number(rawAlpha.replace(/%$/, ""));
+    if (!Number.isFinite(numeric) || numeric < 0 || numeric > 100)
+        return null;
+    return { utility: className, baseName: `--color-${color}`, alpha: `${numeric}%` };
+}
+/** The CSS Tailwind v4 emits for an alpha utility. */
+export function tailwindV4AlphaExpression(baseCssName, alpha) {
+    return `color-mix(in oklab, var(${baseCssName}) ${alpha}, transparent)`;
+}
+/** Distinguishes a v3 config object from a v4 one, which has no `theme` key. */
+export function isTailwindV3Config(config) {
+    return isRecord(config)
+        && isRecord(config.theme)
+        && !("contentSource" in config)
+        && !("__tailwindVersion" in config && config.__tailwindVersion === 4);
+}
+const TOKEN_SECTIONS = [
+    "colors",
+    "spacing",
+    "borderWidth",
+    "borderRadius",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+];
+function mergeSection(base, extension) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(extension)) {
+        const existing = merged[key];
+        merged[key] = isRecord(existing) && isRecord(value) ? mergeSection(existing, value) : value;
+    }
+    return merged;
+}
+function leafValue(value) {
+    if (typeof value === "string" || typeof value === "number")
+        return String(value);
+    // A font-size may be a [size, lineHeight] tuple; the companion belongs to the lineHeight section.
+    const first = Array.isArray(value) ? value[0] : undefined;
+    if (typeof first === "string" || typeof first === "number")
+        return String(first);
+    return null;
+}
+function sectionEntries(values, section, source, path = []) {
+    const entries = [];
+    for (const [key, value] of Object.entries(values)) {
+        const nextPath = [...path, key];
+        const leaf = leafValue(value);
+        if (leaf !== null) {
+            entries.push({
+                name: ["theme", section, ...nextPath].join("."),
+                // v3 compiles values into utility rules, so this is a literal, not a custom property.
+                value: leaf,
+                cssValue: leaf,
+                source,
+                adapter: "tailwind-v3",
+                origin: "project",
+                editable: true,
+            });
+        }
+        else if (isRecord(value)) {
+            entries.push(...sectionEntries(value, section, source, nextPath));
+        }
+    }
+    return entries;
+}
+/** Flattens a v3 config's theme into token entries, applying `theme.extend`. */
+export function readTailwindV3Config(config, source = "tailwind.config.js") {
+    return TOKEN_SECTIONS.flatMap((section) => {
+        const base = isRecord(config.theme?.[section]) ? config.theme[section] : {};
+        const extend = isRecord(config.theme?.extend?.[section]) ? config.theme.extend[section] : {};
+        return sectionEntries(mergeSection(base, extend), section, source);
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { TokenEntry } from "../model/index.js";
+/**
+ * vanilla-extract generates the custom-property names, so the contract is the
+ * only place the authored path (`theme.color.brand`) survives. Reading it is
+ * how a host recovers names the emitted CSS cannot supply.
+ */
+/** A compiled contract: nested objects whose leaves are `var()` references. */
+export type ThemeContract = Record<string, unknown>;
+export interface ReadThemeContractOptions {
+    /** Prefix for generated token paths. Defaults to `theme`. */
+    readonly prefix?: string;
+    /** Source label recorded on every entry. */
+    readonly source: string;
+    readonly origin: TokenEntry["origin"];
+    readonly editable: boolean;
+    /** Omit when the host did not observe the emitted CSS; entries then keep their `var()` reference. */
+    readonly cssValues?: Readonly<Record<string, string>>;
+}
+/** Flattens a contract into token entries keyed by their authored path. */
+export declare function readThemeContract(contract: unknown, options: ReadThemeContractOptions): TokenEntry[];

package/dist/css/dialects/vanillaExtract.js

@@ -0,0 +1,32 @@
+// Anchored: `var(--border) solid` is a composed style, not a token identity.
+const CONTRACT_REFERENCE = /^var\(\s*(--[\w-]+)(?:\s*,[\s\S]*)?\)$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Flattens a contract into token entries keyed by their authored path. */
+export function readThemeContract(contract, options) {
+    const entries = [];
+    const walk = (value, path) => {
+        if (typeof value === "string") {
+            const cssName = CONTRACT_REFERENCE.exec(value.trim())?.[1];
+            if (cssName === undefined)
+                return;
+            entries.push({
+                name: path.join("."),
+                cssName,
+                value: options.cssValues?.[cssName] ?? value,
+                source: options.source,
+                adapter: "vanilla-extract",
+                origin: options.origin,
+                editable: options.editable,
+            });
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        for (const [key, child] of Object.entries(value))
+            walk(child, [...path, key]);
+    };
+    walk(contract, [options.prefix ?? "theme"]);
+    return entries;
+}

package/dist/css/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `nudge-ui/css` — shared, browser-safe CSS/token knowledge.
+ *
+ * Root entry re-exports the browser-safe subpaths only. The Node/build-time
+ * token-inventory subpath arrives in Stage 2 and must NOT be reachable from
+ * this entry so importing value semantics cannot pull PostCSS or filesystem
+ * assumptions into the inspector bundle.
+ */
+export * from "./model/index.js";
+export * from "./value-semantics/index.js";

package/dist/css/index.js

@@ -0,0 +1,10 @@
+/**
+ * `nudge-ui/css` — shared, browser-safe CSS/token knowledge.
+ *
+ * Root entry re-exports the browser-safe subpaths only. The Node/build-time
+ * token-inventory subpath arrives in Stage 2 and must NOT be reachable from
+ * this entry so importing value semantics cannot pull PostCSS or filesystem
+ * assumptions into the inspector bundle.
+ */
+export * from "./model/index.js";
+export * from "./value-semantics/index.js";

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

@@ -0,0 +1,190 @@
+/**
+ * Shared CSS/token knowledge types for `nudge-ui/css`.
+ *
+ * This module is the browser-safe shared model consumed by the runtime
+ * inspector (`nudge-ui/internal/inspector`), the Vite adapter transport
+ * (`virtual:design-tokens`), and — in later slices — the token inventory
+ * Module. It MUST NOT import React, Vite, PostCSS, Node, or filesystem code;
+ * the import-graph test in `src/importGraph.test.ts` enforces that contract.
+ */
+/** Provenance of a token entry or definition. */
+export type TokenOrigin = "project" | "package" | "framework" | "generated" | "runtime";
+/** How faithfully an authored value can be edited by the inspector. */
+export type EditCapability = "atomic" | "color" | "box-sides" | "structured" | "composite" | "raw";
+export interface TokenReference {
+    name: string;
+    origin: TokenOrigin;
+}
+export interface ValueModifier {
+    kind: "alpha" | "fallback" | "expression";
+    value: string;
+}
+export interface ColorOpacity {
+    value: string;
+    authoredValue: string;
+    source: "hex" | "rgb" | "hsl" | "color-mix";
+    tokenName: string | null;
+    token?: TokenReference;
+}
+/** The effective opacity of an element's `opacity` property. */
+export interface OpacityValue {
+    value: string;
+    authoredValue: string;
+    tokenName: string | null;
+    token?: TokenReference;
+    /** False when the authored expression cannot be rewritten losslessly. */
+    editable: boolean;
+}
+/** UI-relevant color facts derived by value semantics, never by React fields. */
+export interface ColorValueFacts {
+    /** The authored or resolved color already carries an alpha channel. */
+    hasEmbeddedAlpha: boolean;
+    /** The authored color is a compound expression that must remain raw unless separable. */
+    isExpression: boolean;
+    /** The authored shape can represent an opacity edit without losing meaning. */
+    opacityEditable: boolean;
+}
+export interface BorderStructure {
+    kind: "border";
+    sourceProperty: "border" | "border-top" | "border-right" | "border-bottom" | "border-left";
+    width: string;
+    style: string;
+    color: string;
+    colorTokenName: string | null;
+}
+export interface AttributionEvidence {
+    selector?: string;
+    sourceOrder?: number;
+    specificity?: number;
+    important?: boolean;
+    layer?: string;
+    layerOrder?: number;
+    inheritedFrom?: string;
+    inaccessibleStylesheet?: boolean;
+    reason: string;
+}
+/**
+ * A token as published by the Vite transport or materialized by a styling
+ * adapter. `name` is the human/design name, `cssName` is the CSS custom
+ * property implementation name; they may differ and must not be conflated.
+ */
+export interface TokenEntry {
+    name: string;
+    value: string;
+    source: string;
+    /**
+     * CSS to place in a managed preview when this token has no CSS custom
+     * property. Tailwind v3 config tokens compile to literals, for example.
+     */
+    cssValue?: string;
+    adapter?: string;
+    cssName?: string;
+    origin?: TokenOrigin;
+    editable?: boolean;
+}
+export type TokenContextWrapperKind = "media" | "supports" | "scope" | "layer";
+/**
+ * An ordered source wrapper around a token declaration. Keeping one stack
+ * retains nesting and interleaving, including repeated wrapper kinds.
+ */
+export interface TokenContextWrapper {
+    kind: TokenContextWrapperKind;
+    params: string;
+}
+export interface TokenContext {
+    selector?: string;
+    wrappers?: TokenContextWrapper[];
+}
+export interface TokenDeclaration {
+    id?: string;
+    order?: number;
+    value: string;
+    source: string;
+    important: boolean;
+    context: TokenContext;
+}
+/** A grouped token with every authored declaration across the project. */
+export interface TokenDefinition {
+    cssName: string;
+    name: string;
+    declarations: TokenDeclaration[];
+    cssValue?: string;
+    adapter?: string;
+    origin?: TokenOrigin;
+    editable?: boolean;
+}
+/** Diagnostic codes emitted by token sources and the token inventory Module. */
+export type TokenCatalogDiagnosticCode = "vanilla-extract-contract-unresolved" | "vanilla-extract-contract-missing-export" | "vanilla-extract-contract-unsupported-shape" | "stylesheet-unreadable" | "stylesheet-unresolved" | "stylesheet-unsupported" | "stylesheet-parse-failed" | "transform-observation-failed" | "token-order-unresolved";
+export interface TokenCatalogDiagnostic {
+    code: TokenCatalogDiagnosticCode;
+    message: string;
+    module: string;
+    exportName?: string;
+}
+/** Custom-property lookup table keyed by name and cssName. */
+export interface TokenTable {
+    [varName: string]: TokenEntry;
+}
+export interface StyleDeclaration {
+    property: string;
+    value: string;
+    important?: boolean;
+}
+export type AtRuleKind = "media" | "container" | "supports";
+/** A conditional wrapper retained from CSSOM in source nesting order. */
+export interface AtRuleContext {
+    kind: AtRuleKind;
+    /** The CSSOM-normalised prelude, without the leading `@kind`. */
+    params: string;
+}
+/** A conditional wrapper that participates in a property's source candidates. */
+export interface AtRuleCandidate extends AtRuleContext {
+    /** True when this context belongs to the declaration currently winning the cascade. */
+    active: boolean;
+}
+export interface MatchedRule {
+    selectorText: string;
+    declarations: StyleDeclaration[];
+    specificity: number;
+    /** Runtime stylesheet identity, such as Vite's data-vite-dev-id. */
+    source?: string;
+    sourceOrder?: number;
+    layer?: string;
+    /** First-declaration order of the named cascade layer in this document. */
+    layerOrder?: number;
+    active?: boolean;
+    atRules?: AtRuleContext[];
+}
+/** One attributed, resolvable property on the inspected element. */
+export interface ResolvedProperty {
+    property: string;
+    tokenName: string | null;
+    declaredValue: string;
+    resolvedValue: string;
+    /**
+     * CSSOM-declared serialization used by the UI as the authored expression.
+     * This preserves CSS meaning, not the source file's exact spelling.
+     */
+    authored?: string;
+    sourceProperty?: string;
+    computed?: string;
+    tokens?: TokenReference[];
+    opacity?: ColorOpacity;
+    propertyOpacity?: OpacityValue;
+    color?: ColorValueFacts;
+    modifiers?: ValueModifier[];
+    capability?: EditCapability;
+    resolvedTokenValue?: string;
+    diagnostic?: string;
+    structure?: BorderStructure;
+    /**
+     * Conditional source wrappers that apply to the declaration currently
+     * attributed to this field. These include responsive, container, and
+     * capability conditions which can affect the winning declaration.
+     */
+    atRules?: AtRuleContext[];
+    /** All media-query contexts found on declarations for this property. */
+    atRuleCandidates?: AtRuleCandidate[];
+    confidence: "exact" | "probable" | "unknown";
+    evidence: AttributionEvidence;
+}

package/dist/css/model/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared CSS/token knowledge types for `nudge-ui/css`.
+ *
+ * This module is the browser-safe shared model consumed by the runtime
+ * inspector (`nudge-ui/internal/inspector`), the Vite adapter transport
+ * (`virtual:design-tokens`), and — in later slices — the token inventory
+ * Module. It MUST NOT import React, Vite, PostCSS, Node, or filesystem code;
+ * the import-graph test in `src/importGraph.test.ts` enforces that contract.
+ */
+export {};

package/dist/css/token-inventory/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `nudge-ui/css/token-inventory` — Node/build-time stylesheet parsing and
+ * aggregation.
+ *
+ * This subpath is intentionally NOT browser-safe (see the import-graph test):
+ * importing it pulls PostCSS into the consumer. Node consumers use it directly
+ * through `nudge-ui/css/token-inventory`; the root `nudge-ui/css`
+ * entry stays browser-safe and never re-exports this module.
+ *
+ * The deep Interface is `createTokenInventory()` — feed ordered stylesheet
+ * artifacts and Adapter literal tokens, read immutable deterministic snapshots.
+ * Parsing and policy remain internal seams used by the engine and direct tests.
+ *
+ * ## Deletion test
+ *
+ * This Module earns its seam: deleting it would force the Vite Adapter to
+ * re-own PostCSS parsing, authored/transformed reconciliation, declaration
+ * identity and ordering, project/package/generated provenance, contribution
+ * merging, structured diagnostics, and the generation fingerprint that
+ * `BrowserTokenKnowledge` uses to refresh inspection sessions. The Adapter
+ * would also have to re-solve the determinism/no-op guarantees that keep
+ * equivalent HMR event batches from churning the snapshot.
+ */
+export { createTokenInventory } from "./inventory.js";
+export type { TokenInventory } from "./inventory.js";
+export type { ArtifactProvenance, ArtifactStage, TokenDefinitionRelabelling, ArtifactDiagnosticInput, InventoryContribution, InventoryDiagnostic, InventoryOrderEvidence, InventorySnapshot, InventoryTokenDeclaration, InventoryTokenDefinition, StylesheetArtifact, TokenContribution, } from "./types.js";

package/dist/css/token-inventory/index.js

@@ -0,0 +1,24 @@
+/**
+ * `nudge-ui/css/token-inventory` — Node/build-time stylesheet parsing and
+ * aggregation.
+ *
+ * This subpath is intentionally NOT browser-safe (see the import-graph test):
+ * importing it pulls PostCSS into the consumer. Node consumers use it directly
+ * through `nudge-ui/css/token-inventory`; the root `nudge-ui/css`
+ * entry stays browser-safe and never re-exports this module.
+ *
+ * The deep Interface is `createTokenInventory()` — feed ordered stylesheet
+ * artifacts and Adapter literal tokens, read immutable deterministic snapshots.
+ * Parsing and policy remain internal seams used by the engine and direct tests.
+ *
+ * ## Deletion test
+ *
+ * This Module earns its seam: deleting it would force the Vite Adapter to
+ * re-own PostCSS parsing, authored/transformed reconciliation, declaration
+ * identity and ordering, project/package/generated provenance, contribution
+ * merging, structured diagnostics, and the generation fingerprint that
+ * `BrowserTokenKnowledge` uses to refresh inspection sessions. The Adapter
+ * would also have to re-solve the determinism/no-op guarantees that keep
+ * equivalent HMR event batches from churning the snapshot.
+ */
+export { createTokenInventory } from "./inventory.js";

package/dist/css/token-inventory/inventory.d.ts

@@ -0,0 +1,8 @@
+import type { InventorySnapshot, StylesheetArtifact, TokenContribution } from "./types.js";
+export interface TokenInventory {
+    apply(artifact: StylesheetArtifact): void;
+    snapshot(): InventorySnapshot;
+    applyContribution(contribution: TokenContribution): void;
+    removeContribution(id: string): void;
+}
+export declare function createTokenInventory(): TokenInventory;