nudge-ui 0.2.4 → 0.2.6

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

@@ -63,13 +63,7 @@ function copyContribution(contribution) {
 function sameObservationFacts(observation, artifact) {
     return JSON.stringify(observation.artifact) === JSON.stringify(artifact);
 }
-/**
- * Scalar-only equality over stylesheet artifacts, used as a cheap pre-parse
- * no-op guard: identical re-feeds (the common HMR case) must not pay for a
- * PostCSS parse. Every field is enumerated so a future artifact field cannot
- * silently bypass the guard; diagnostics are rare and small, so they alone
- * compare by serialization — content strings never do.
- */
+/** Each artifact field is enumerated so a new one cannot silently bypass the pre-parse no-op guard. */
 function sameArtifactScalars(a, b) {
     return a.buildTool === b.buildTool
         && a.id === b.id
@@ -136,8 +130,7 @@ function reconcileObservations(entry) {
     const authoredNames = new Set(authored?.contribution.definitions.map((definition) => definition.cssName) ?? []);
     return facts.contribution.definitions.map((definition) => {
         const transformOnly = authored !== undefined && !authoredNames.has(definition.cssName);
-        // Project compilers own transform-only names, but package ownership is
-        // stronger provenance and survives compilation.
+        // Transform-only names are compiler-owned; package provenance is stronger and survives compilation.
         const origin = transformOnly && facts.artifact.provenance !== "package"
             ? "generated"
             : facts.artifact.provenance;
@@ -256,8 +249,7 @@ export function createTokenInventory() {
         }
         const current = artifact.stage === "authored" ? entry.authored : entry.transformed;
         const isRecoveringFailedTransform = artifact.stage === "transformed" && entry.transformFailed === true;
-        // Cheap pre-parse guard. A transformed-stage re-feed while the failure
-        // flag is set always falls through so recovery still lands.
+        // A transformed-stage re-feed while the failure flag is set always falls through so recovery lands.
         if (current && !isRecoveringFailedTransform
             && sameArtifactScalars(current.artifact, artifact))
             return;
@@ -340,11 +332,7 @@ export function createTokenInventory() {
                     };
                 }
             }
-            // Definition-level enrichment by cssName: contributed declarations
-            // append, `name`/`adapter` win, and
-            // `origin`/`editable` are applied only when the stylesheet-derived
-            // definition has none. Unmatched entries are ignored (a contract
-            // variable absent from active CSS adds no row).
+            // Contributed declarations append; name/adapter override, origin/editable only fill gaps.
             for (const definition of contribution.definitions ?? []) {
                 const existing = merged.get(definition.cssName);
                 if (!existing)

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

@@ -1,16 +1,8 @@
 import type { TokenDefinition } from "../model/index.js";
 import type { InventoryDiagnostic, StylesheetArtifact } from "./types.js";
-/** The parsed contribution of one stylesheet artifact. */
 export interface ParsedContribution {
     readonly definitions: readonly TokenDefinition[];
     readonly diagnostics: readonly InventoryDiagnostic[];
 }
-/**
- * Parse one stylesheet artifact into grouped definitions plus diagnostics.
- *
- * The returned declarations carry `id` (stable per declaration) and the
- * definition list preserves source order. `order` is assigned by the
- * inventory during snapshot assembly because it is a positional fact across
- * artifacts, not a per-artifact one.
- */
+/** `order` is assigned by the inventory because it is positional across artifacts, not per-artifact. */
 export declare function parseStylesheetArtifact(artifact: StylesheetArtifact): ParsedContribution;

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

@@ -1,28 +1,6 @@
-/**
- * Internal ordinary-CSS parsing for the token inventory.
- *
- * This is the canonical home of the parsing previously owned by the plugin's
- * legacy `parseTokens`/`parseTokenCatalog` projections (removed in S2-D).
- * Behavior is preserved exactly for root/host themes, contextual selectors,
- * wrapper capture, duplicate declarations, importance, and source locations;
- * the two differences are:
- *
- * 1. Declarations carry a deterministic `id` and a `source`-anchored local
- *    order so the inventory can aggregate without Vite.
- * 2. Malformed CSS no longer silently yields an empty list — it produces a
- *    structured `stylesheet-parse-failed` diagnostic plus an empty
- *    contribution for that artifact.
- *
- * This module runs at build time only (Node) and is not reachable from the
- * browser-safe subpaths.
- */
 import postcss, {} from "postcss";
 import { GLOBAL_TOKEN_AT_RULES, MIN_THEME_TABLE_DECLARATIONS } from "./policy.js";
-/**
- * Deterministic declaration identity, keyed by (artifact id, cssName, source
- * line, context, local order). The id does not depend on event-batch timing:
- * the same facts always produce the same ids.
- */
+/** Deterministic per declaration: identical facts always produce the same id. */
 function declarationId(artifact, cssName, source, context, localOrder) {
     return `${artifact.buildTool}\u0000${artifact.id}\u0000${artifact.stage}`
         + `\u0000${cssName}\u0000${source}\u0000${JSON.stringify(context)}\u0000${localOrder}`;
@@ -37,12 +15,7 @@ function isRootOnlySelector(rule) {
     const parts = rule.selector.split(",").map((s) => s.trim());
     return parts.length > 0 && parts.every(isRootSelectorPart);
 }
-/**
- * Scoped theme-table policy — see `policy.ts` for the named constant and
- * rationale. A sufficiently large rule made entirely of custom properties is a
- * theme table, not a component-local variable declaration; its selector is
- * retained in the catalog and resolved against the selected element later.
- */
+/** A large rule made entirely of custom properties is a theme table; see the policy in `policy.ts`. */
 function isScopedThemeTable(rule) {
     const declarations = rule.nodes?.filter((node) => node.type === "decl") ?? [];
     return declarations.length >= MIN_THEME_TABLE_DECLARATIONS
@@ -55,9 +28,7 @@ function isAtRule(node) {
     return node.type === "atrule";
 }
 function nearestGlobalAncestor(decl) {
-    // Walk up; return true ONLY if we encounter a :root rule or a global at-rule
-    // BEFORE encountering any non-:root rule. A non-:root rule (e.g. .button)
-    // inside @layer still means the declaration is local, not a global token.
+    // Global only when a :root rule or global at-rule is reached before any other rule.
     let cur = decl.parent;
     while (cur) {
         if (isRule(cur)) {
@@ -84,8 +55,7 @@ function declarationContext(decl) {
         }
         else if (isAtRule(current)) {
             if (current.name === "media" || current.name === "supports" || current.name === "scope" || current.name === "layer") {
-                // Parents are visited inner-to-outer; prepend to preserve the source
-                // nesting order and retain repeated/interleaved wrapper kinds.
+                // Parents are visited inner-to-outer, so prepend to keep source nesting order.
                 wrappers.unshift({ kind: current.name, params: current.params });
             }
         }
@@ -95,14 +65,7 @@ function declarationContext(decl) {
         context.wrappers = wrappers;
     return context;
 }
-/**
- * Parse one stylesheet artifact into grouped definitions plus diagnostics.
- *
- * The returned declarations carry `id` (stable per declaration) and the
- * definition list preserves source order. `order` is assigned by the
- * inventory during snapshot assembly because it is a positional fact across
- * artifacts, not a per-artifact one.
- */
+/** `order` is assigned by the inventory because it is positional across artifacts, not per-artifact. */
 export function parseStylesheetArtifact(artifact) {
     const content = artifact.content ?? "";
     let root;

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

@@ -1,43 +1,6 @@
-/**
- * Explicit inventory policies behind ordinary CSS parsing.
- *
- * Parsing must not bury heuristics as unexplained constants. This module names
- * each policy, documents its rationale, and pins both directions of the
- * trade-off with tests in `parseStylesheet.test.ts`.
- */
-/**
- * At-rules that make a nested custom-property declaration global regardless of
- * an enclosing selector: `@theme` (Tailwind v4), `@layer`, and `@scope`.
- *
- * Deliberately NOT included: `@media`, `@supports`, and `@container`. A bare
- * custom property directly inside those wrappers (without `:root`/`:host`) is
- * not a global token — see the false-positive guards in the parsing tests.
- */
+/** Custom properties directly under these at-rules are global; `@media`, `@supports` and `@container` deliberately are not. */
 export declare const GLOBAL_TOKEN_AT_RULES: Set<string>;
-/**
- * Minimum declaration count for a scoped rule to be treated as a theme table.
- *
- * Rationale: published design systems often scope an entire theme beneath a
- * class on the application shell (for example to support multiple themes on
- * one page) instead of `:root`. A rule that is large enough AND made entirely
- * of custom-property declarations is treated as a theme table, so its selector
- * is retained in the catalog and resolved against the selected element later.
- *
- * The threshold is a deliberately explicit policy with two documented edges,
- * both pinned by tests:
- *
- * - False positive: a component-local rule with many custom properties (at or
- *   above the threshold) is admitted as a theme table even though it is local
- *   to the component. Accepted so genuine multi-variable theme tables keep
- *   working; a cleaner fix needs selector heuristics that are out of scope for
- *   ordinary-CSS parsing.
- * - False negative: a real theme table with fewer than the threshold
- *   declarations is rejected. Accepted so small component-local rules do not
- *   leak into the global catalog.
- *
- * The threshold is a count of direct custom-property declarations on the rule,
- * not a line count and not an estimate of selector breadth.
- */
+/** At or above this many direct custom-property declarations a scoped rule is treated as a theme table. */
 export declare const MIN_THEME_TABLE_DECLARATIONS = 8;
 export interface ScopedThemeTablePolicy {
     readonly minDeclarations: number;

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

@@ -1,43 +1,6 @@
-/**
- * Explicit inventory policies behind ordinary CSS parsing.
- *
- * Parsing must not bury heuristics as unexplained constants. This module names
- * each policy, documents its rationale, and pins both directions of the
- * trade-off with tests in `parseStylesheet.test.ts`.
- */
-/**
- * At-rules that make a nested custom-property declaration global regardless of
- * an enclosing selector: `@theme` (Tailwind v4), `@layer`, and `@scope`.
- *
- * Deliberately NOT included: `@media`, `@supports`, and `@container`. A bare
- * custom property directly inside those wrappers (without `:root`/`:host`) is
- * not a global token — see the false-positive guards in the parsing tests.
- */
+/** Custom properties directly under these at-rules are global; `@media`, `@supports` and `@container` deliberately are not. */
 export const GLOBAL_TOKEN_AT_RULES = new Set(["theme", "layer", "scope"]);
-/**
- * Minimum declaration count for a scoped rule to be treated as a theme table.
- *
- * Rationale: published design systems often scope an entire theme beneath a
- * class on the application shell (for example to support multiple themes on
- * one page) instead of `:root`. A rule that is large enough AND made entirely
- * of custom-property declarations is treated as a theme table, so its selector
- * is retained in the catalog and resolved against the selected element later.
- *
- * The threshold is a deliberately explicit policy with two documented edges,
- * both pinned by tests:
- *
- * - False positive: a component-local rule with many custom properties (at or
- *   above the threshold) is admitted as a theme table even though it is local
- *   to the component. Accepted so genuine multi-variable theme tables keep
- *   working; a cleaner fix needs selector heuristics that are out of scope for
- *   ordinary-CSS parsing.
- * - False negative: a real theme table with fewer than the threshold
- *   declarations is rejected. Accepted so small component-local rules do not
- *   leak into the global catalog.
- *
- * The threshold is a count of direct custom-property declarations on the rule,
- * not a line count and not an estimate of selector breadth.
- */
+/** At or above this many direct custom-property declarations a scoped rule is treated as a theme table. */
 export const MIN_THEME_TABLE_DECLARATIONS = 8;
 export const SCOPED_THEME_TABLE_POLICY = {
     minDeclarations: MIN_THEME_TABLE_DECLARATIONS,

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

@@ -1,20 +1,12 @@
-/**
- * Token inventory contracts: artifact input, normalized styling contributions,
- * diagnostics, and immutable snapshots.
- *
- * This Node/build-time seam is intentionally absent from the browser-safe
- * `nudge-ui/css` export graph.
- */
 import type { TokenCatalogDiagnosticCode, TokenDefinition, TokenDeclaration, TokenEntry, TokenOrigin } from "../model/index.js";
 export type ArtifactStage = "authored" | "transformed";
 export type ArtifactProvenance = TokenOrigin;
-/** One authored or transformed observation supplied by a build-tool Adapter. */
 export interface StylesheetArtifact {
     readonly buildTool: string;
     readonly id: string;
     readonly stage: ArtifactStage;
     readonly provenance: ArtifactProvenance;
-    /** Authoritative stylesheet/import order, only when the Adapter can prove it. */
+    /** Only when the Adapter can prove the stylesheet/import order. */
     readonly order?: number;
     /** Deterministic scan rank when browser/cascade order is not known. */
     readonly discoveryOrder?: number;
@@ -23,7 +15,6 @@ export interface StylesheetArtifact {
     readonly adapter?: string;
     /** A recoverable transformed-observation failure; authored facts are retained. */
     readonly failed?: boolean;
-    /** Adapter failures associated with this observation. */
     readonly diagnostics?: readonly ArtifactDiagnosticInput[];
 }
 export interface ArtifactDiagnosticInput {
@@ -68,17 +59,13 @@ export interface InventoryTokenDeclaration extends Omit<TokenDeclaration, "order
 export interface InventoryTokenDefinition extends Omit<TokenDefinition, "declarations"> {
     readonly declarations: readonly InventoryTokenDeclaration[];
 }
-/** Declarative metadata rewrite for matching aggregated definitions. */
 export interface TokenDefinitionRelabelling {
     readonly adapter: string;
     readonly fromOrigin: TokenOrigin;
     readonly origin?: TokenOrigin;
     readonly editable?: boolean;
 }
-/**
- * A normalized styling contribution. Re-applying the same `id` replaces its
- * prior facts; contribution order is explicit or deterministically id-based.
- */
+/** Re-applying the same `id` replaces its prior facts. */
 export interface TokenContribution {
     readonly id: string;
     readonly tokens?: readonly TokenEntry[];

package/dist/css/value-semantics/borderSemantics.d.ts

@@ -9,7 +9,6 @@ export declare const BORDER_INITIAL: {
     readonly style: "none";
     readonly color: "currentcolor";
 };
-/** Width/style/color components of a decomposable border value. */
 export interface BorderComponents {
     width: string;
     style: string;
@@ -18,11 +17,5 @@ export interface BorderComponents {
     styleResult: TokenValueInterpretation;
     colorResult: TokenValueInterpretation;
 }
-/**
- * Conservative border-shorthand classification: splits the authored value
- * into width/style/color components with CSS initial values for omitted parts,
- * and interprets each distinct component once. Returns null when the value
- * cannot be decomposed faithfully (ambiguous component order, image layers,
- * non-token slash forms, css-wide keywords, or multi-value junk).
- */
+/** Conservative decomposition; null when the value cannot be split faithfully. */
 export declare function parseBorderComponents(value: string, tokenContext: TokenInterpretationContext): BorderComponents | null;

package/dist/css/value-semantics/borderSemantics.js

@@ -1,15 +1,4 @@
-/**
- * Border shorthand structure (plan slice 3.5).
- *
- * One browser-safe Module owns the conservative `border` / `border-side`
- * shorthand decomposition: width/style/color parts, CSS initial values for
- * omitted components, css-wide-keyword rejection, and the explicit rejection
- * of image layers, non-token slash forms, and ambiguous component counts.
- *
- * Browser-safe contract: this module imports only the shared model and the
- * value-semantics token interpreter. It never touches the DOM or CSSOM.
- */
-import { splitTopLevelWhitespace } from "./cssSyntax.js";
+import { isSingleVarReference, splitTopLevelWhitespace } from "./cssSyntax.js";
 import { interpretTokenValue, } from "./tokenInterpretation.js";
 export const BORDER_STYLES = new Set(["none", "hidden", "dotted", "dashed", "solid", "double", "groove", "ridge", "inset", "outset"]);
 export const BORDER_WIDTHS = new Set(["thin", "medium", "thick"]);
@@ -17,13 +6,7 @@ export const COLOR_KEYWORDS = new Set(["transparent", "currentcolor", "black", "
 export const BORDER_CSS_WIDE = new Set(["inherit", "initial", "unset", "revert", "revert-layer"]);
 /** CSS initial values for omitted `border` / `border-*` shorthand components. */
 export const BORDER_INITIAL = { width: "medium", style: "none", color: "currentcolor" };
-/**
- * Conservative border-shorthand classification: splits the authored value
- * into width/style/color components with CSS initial values for omitted parts,
- * and interprets each distinct component once. Returns null when the value
- * cannot be decomposed faithfully (ambiguous component order, image layers,
- * non-token slash forms, css-wide keywords, or multi-value junk).
- */
+/** Conservative decomposition; null when the value cannot be split faithfully. */
 export function parseBorderComponents(value, tokenContext) {
     const trimmed = value.trim();
     if (!trimmed || BORDER_CSS_WIDE.has(trimmed.toLowerCase()))
@@ -51,11 +34,10 @@ export function parseBorderComponents(value, tokenContext) {
         }
         if (part.includes("/") && !/^var\(/i.test(part))
             return null;
-        const isVariable = /^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/i.test(part);
+        const isVariable = isSingleVarReference(part);
         const interpreted = isVariable ? interpret(part).resolvedValue.trim() : part;
-        // A custom property can substitute an entire shorthand. If its grammar is
-        // unresolved or expands to multiple components, assigning it to one slot
-        // would invent structure that the authored declaration does not prove.
+        // A custom property can substitute an entire shorthand; unresolved or
+        // multi-component results cannot be assigned to one slot.
         if (isVariable && (/^var\(/i.test(interpreted) || splitTopLevelWhitespace(interpreted).length !== 1))
             return null;
         const candidate = interpreted.toLowerCase();

package/dist/css/value-semantics/boxSemantics.d.ts

@@ -1,37 +1,14 @@
-/**
- * Box and spacing value semantics (plan slice 3.5).
- *
- * One browser-safe Module owns physical and logical box-value expansion:
- * 1–4 value shorthand expansion for `margin`/`padding`/`inset`, two-value
- * expansion for `gap`, border-radius corner names, and the logical→physical
- * side mapping. The logical mapping is a pure function over an explicit
- * `Directionality` fact supplied by the integration (browser CSS inspection
- * reads direction/writing-mode from the selected element); this module never
- * touches the DOM or CSSOM.
- */
 import type { StringArrayMap } from "./stringMaps.js";
 export declare const SPACING_SIDES: StringArrayMap;
 /** CSS `gap` shorthand order: row gap, then column gap. */
 export declare const GAP_AXES: StringArrayMap;
 export declare const BORDER_RADIUS_CORNERS: StringArrayMap;
-/**
- * Explicit, DOM-free writing facts for logical→physical side mapping. The
- * integration reads `direction` and `writing-mode` from the selected element's
- * computed style and passes them here; the neutral Module applies them.
- */
+/** Writing facts the integration reads from the selected element's computed style. */
 export interface Directionality {
-    /** CSS `direction` value, e.g. `"ltr"` or `"rtl"`. */
     direction: string;
-    /** CSS `writing-mode` value, e.g. `"horizontal-tb"` or `"vertical-rl"`. */
     writingMode: string;
 }
 export declare function expandFourValueShorthand<T>(values: readonly T[]): [T, T, T, T] | null;
 export declare function expandTwoValueShorthand<T>(values: readonly T[]): [T, T] | null;
-/**
- * Maps a logical `margin`/`padding`/`inset` property (inline/block forms,
- * with optional start/end edges) to the physical sides it paints, using the
- * element's writing-mode/direction facts. Returns null for non-logical
- * properties. Without directionality the mapping assumes `ltr` /
- * `horizontal-tb`, matching the resolver's element-less behaviour.
- */
+/** Maps logical margin/padding/inset properties to physical sides; null for non-logical properties. */
 export declare function logicalPhysicalSides(property: string, directionality?: Directionality): string[] | null;

package/dist/css/value-semantics/boxSemantics.js

@@ -33,13 +33,7 @@ export function expandTwoValueShorthand(values) {
         return null;
     return values.length === 1 ? [values[0], values[0]] : [values[0], values[1]];
 }
-/**
- * Maps a logical `margin`/`padding`/`inset` property (inline/block forms,
- * with optional start/end edges) to the physical sides it paints, using the
- * element's writing-mode/direction facts. Returns null for non-logical
- * properties. Without directionality the mapping assumes `ltr` /
- * `horizontal-tb`, matching the resolver's element-less behaviour.
- */
+/** Maps logical margin/padding/inset properties to physical sides; null for non-logical properties. */
 export function logicalPhysicalSides(property, directionality) {
     const match = /^(margin|padding|inset)-(inline|block)(?:-(start|end))?$/.exec(property.toLowerCase());
     if (!match)

package/dist/css/value-semantics/colorSemantics.d.ts

@@ -1,46 +1,18 @@
-/**
- * Color value semantics (plan slice 3.4).
- *
- * One browser-safe Module owns color format recognition, embedded-alpha
- * detection, opacity modifier interpretation, `color-mix()` handling, color
- * token replacement, and meaning-preserving opacity edits. Interpretation
- * takes explicit token knowledge (a token table, local aliases, and an
- * optional token-reference resolver) and never touches the DOM or CSSOM.
- *
- * Interface invariants:
- * - interpretation never throws on arbitrary input;
- * - edits either preserve the authored meaning or return an explicit
- *   `ok: false` result — never a plausible but lossy string;
- * - token-plus-alpha and opacity-token distinctions survive swaps;
- * - framework-specific attribution (Tailwind v3 direct literals and `--tw-*`
- *   aliases) stays behind the injected `resolveTokenReference` context.
- */
 import type { ColorOpacity, ColorValueFacts, TokenEntry, TokenReference, TokenTable } from "../model/index.js";
-/** The resolved facts about one token-backed component of a color expression. */
 export interface ColorComponentResolution {
     tokenName: string | null;
     resolvedValue: string;
     tokens: TokenReference[];
 }
-/** Explicit, DOM-free facts the color interpretation needs. */
 export interface ColorSemanticsContext {
     /** Resolved token table (custom-property name → entry). */
     tokenTable: TokenTable;
     /** Local aliases collected from the selected element's cascade. */
     localAliases?: ReadonlyMap<string, string>;
-    /**
-     * Resolves a `var()` component (for example an opacity token) to its
-     * concrete value and attribution. Supplied by the token interpretation so
-     * alias and framework attribution stay in one place. Absent → token-backed
-     * components fall back to local aliases, fallbacks, or the raw text.
-     */
+    /** Resolves a `var()` component (e.g. an opacity token); absent → local aliases, fallbacks, or the raw text. */
     resolveTokenReference?: (value: string) => ColorComponentResolution | null;
 }
-/**
- * A meaning-preserving color edit. `ok: true` carries the rewritten value;
- * `ok: false` reports explicitly that the transformation cannot be
- * represented faithfully. Callers must treat `ok: false` as "no change".
- */
+/** Callers must treat `ok: false` as "no change". */
 export type ColorEditResult = {
     ok: true;
     value: string;
@@ -48,46 +20,21 @@ export type ColorEditResult = {
     ok: false;
     reason: "unsupported" | "invalid-opacity";
 };
-/** One high-level color interpretation consumed by token interpretation and UI projection. */
 export interface ColorValueInterpretation {
     opacity?: ColorOpacity;
     facts: ColorValueFacts;
 }
-/**
- * Normalizes an authored opacity to a clamped percent string. Accepts `%`
- * and `0..1` forms; returns null when the input is not a parseable opacity.
- */
+/** Accepts `%` or `0..1` forms; null when the input is not a parseable opacity. */
 export declare function normalizeOpacityPercent(value: string): string | null;
-/**
- * Interprets the alpha component of one authored color value. Returns a
- * `ColorOpacity` when the value carries a recognized alpha channel (hex,
- * rgb/hsl, or color-mix against transparent), and undefined otherwise.
- */
+/** Alpha of hex, rgb/hsl, or `color-mix(... transparent)` values; undefined otherwise. */
 export declare function interpretColorOpacity(value: string, ctx: ColorSemanticsContext): ColorOpacity | undefined;
-/** Returns whether a color value carries its own alpha channel. */
 export declare function colorValueHasEmbeddedAlpha(value: string): boolean;
-/** Interprets UI-relevant color shape through the value-semantics seam. */
 export declare function interpretColorValue(value: string, ctx: ColorSemanticsContext): ColorValueInterpretation;
-/**
- * Rewrites the alpha of a supported color expression to a normalized opacity
- * percent. Hex alpha channels are rewritten digit-for-digit, rgb/hsl slash or
- * comma alpha is replaced, `color-mix(... transparent)` reconciles its
- * percentage (or its 100−p mirror), and a bare `var()` wraps into
- * `color-mix(in srgb, var(...) <pct>, transparent)` — unwrapping back to the
- * plain `var()` when the opacity reaches 100%. Unsupported value shapes and
- * unparseable opacities return an explicit `ok: false`.
- */
 export declare function applyColorOpacity(value: string, opacity: string): ColorEditResult;
-/** Applies opacity using RGB channels for hex colors so field edits retain percentage precision. */
+/** Converts hex to RGB channels so field edits retain percentage precision. */
 export declare function withColorOpacity(color: string, opacity: string): ColorEditResult;
-/** Preserves the previous opacity when the replacement color has no explicit alpha. */
 export declare function replaceColorPreservingOpacity(previous: string, color: string, context: ColorSemanticsContext): ColorEditResult;
-/**
- * Replaces only the color token in a separable color expression. Keeping this
- * separate from a plain token swap preserves authored alpha modifiers, for
- * example Tailwind's `color-mix(... var(--color-red-500) 10%, transparent)`
- * keeps its `10%` when the color token changes.
- */
+/** Replaces only the color token so authored alpha modifiers survive the swap. */
 export declare function applyColorTokenReplacement(value: string, oldToken: TokenEntry, newToken: TokenEntry): ColorEditResult;
 export type ValueEditRequest = {
     kind: "color-opacity";
@@ -99,5 +46,4 @@ export type ValueEditRequest = {
     currentToken: TokenEntry;
     nextToken: TokenEntry;
 };
-/** The public meaning-preserving edit operation for supported value edits. */
 export declare function applyValueEdit(request: ValueEditRequest): ColorEditResult;

package/dist/css/value-semantics/colorSemantics.js

@@ -1,4 +1,4 @@
-import { extractVarCalls, splitTopLevel, splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
+import { extractVarCalls, isSingleVarReference, splitTopLevel, splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
 const MIX_PERCENTAGE_OR_TOKEN = /^(?:\d+\.?\d*|\.\d+)%$|^var\([\s\S]+\)$/i;
 const COLOR_FUNCTIONS_WITH_ALPHA_SYNTAX = new Set(["rgb", "hsl", "hwb", "lab", "lch", "oklab", "oklch", "color"]);
 const COLOR_FUNCTION_NAMES = new Set([
@@ -6,9 +6,8 @@ const COLOR_FUNCTION_NAMES = new Set([
     "rgba",
     "hsla",
 ]);
-// CSS named colors are valid color values even though they do not have an
-// explicit alpha syntax. Opacity edits represent them with color-mix(), while
-// full opacity preserves the authored keyword.
+// Valid color values without an alpha syntax; opacity edits wrap them in
+// color-mix(), while full opacity preserves the authored keyword.
 const NAMED_COLOR_KEYWORDS = new Set([
     "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black",
     "blanchedalmond", "blue", "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse",
@@ -50,10 +49,7 @@ function parseOpacityPercent(value, clamp = true) {
     const percent = isPercent ? numeric : numeric * 100;
     return clamp ? Math.max(0, Math.min(100, percent)) : percent;
 }
-/**
- * Normalizes an authored opacity to a clamped percent string. Accepts `%`
- * and `0..1` forms; returns null when the input is not a parseable opacity.
- */
+/** Accepts `%` or `0..1` forms; null when the input is not a parseable opacity. */
 export function normalizeOpacityPercent(value) {
     const percent = parseOpacityPercent(value);
     return percent === null ? null : formatOpacityPercent(percent);
@@ -121,12 +117,7 @@ function resolveOpacityPercentage(authoredValue, ctx, clamp = true) {
 function resolveOpacityComponent(authoredValue, ctx) {
     return resolveOpacityPercentage(authoredValue, ctx)?.component ?? null;
 }
-/**
- * Derives the alpha component of a `color-mix(...)` whose second argument
- * reconciles a color against `transparent`. The component is the color item's
- * percentage, or the 100−p mirror of the transparent item's percentage when
- * only that one is authored.
- */
+/** Opacity of a `color-mix(... transparent)` value: the color item's percentage, or the 100−p mirror when only the transparent item is authored. */
 function resolveColorMixOpacity(value, ctx) {
     const open = value.indexOf("(");
     const close = value.lastIndexOf(")");
@@ -185,11 +176,7 @@ function resolveColorMixOpacity(value, ctx) {
         source: "color-mix",
     };
 }
-/**
- * Interprets the alpha component of one authored color value. Returns a
- * `ColorOpacity` when the value carries a recognized alpha channel (hex,
- * rgb/hsl, or color-mix against transparent), and undefined otherwise.
- */
+/** Alpha of hex, rgb/hsl, or `color-mix(... transparent)` values; undefined otherwise. */
 export function interpretColorOpacity(value, ctx) {
     const trimmed = value.trim();
     const hex = /^#([\da-f]{4}|[\da-f]{8})$/i.exec(trimmed);
@@ -225,7 +212,6 @@ export function interpretColorOpacity(value, ctx) {
         return resolveColorMixOpacity(trimmed, ctx);
     return undefined;
 }
-/** Returns whether a color value carries its own alpha channel. */
 export function colorValueHasEmbeddedAlpha(value) {
     const trimmed = value.trim();
     if (/^transparent$/i.test(trimmed))
@@ -253,7 +239,6 @@ export function colorValueHasEmbeddedAlpha(value) {
         return item.color.toLowerCase() === "transparent" || colorValueHasEmbeddedAlpha(item.color);
     });
 }
-/** Interprets UI-relevant color shape through the value-semantics seam. */
 export function interpretColorValue(value, ctx) {
     const trimmed = value.trim();
     return {
@@ -338,21 +323,12 @@ function replaceColorMixOpacity(value, opacity) {
     }
     return `${value.slice(0, open + 1)}${updated.join(", ")}${value.slice(close)}`;
 }
-/**
- * Rewrites the alpha of a supported color expression to a normalized opacity
- * percent. Hex alpha channels are rewritten digit-for-digit, rgb/hsl slash or
- * comma alpha is replaced, `color-mix(... transparent)` reconciles its
- * percentage (or its 100−p mirror), and a bare `var()` wraps into
- * `color-mix(in srgb, var(...) <pct>, transparent)` — unwrapping back to the
- * plain `var()` when the opacity reaches 100%. Unsupported value shapes and
- * unparseable opacities return an explicit `ok: false`.
- */
 export function applyColorOpacity(value, opacity) {
     const normalized = normalizeOpacityPercent(opacity);
     if (normalized === null)
         return { ok: false, reason: "invalid-opacity" };
     const trimmed = value.trim();
-    if (/^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/i.test(trimmed)) {
+    if (isSingleVarReference(trimmed)) {
         return normalized === "100%"
             ? { ok: true, value: trimmed }
             : { ok: true, value: `color-mix(in srgb, ${trimmed} ${normalized}, transparent)` };
@@ -398,7 +374,7 @@ export function applyColorOpacity(value, opacity) {
     }
     return { ok: false, reason: "unsupported" };
 }
-/** Applies opacity using RGB channels for hex colors so field edits retain percentage precision. */
+/** Converts hex to RGB channels so field edits retain percentage precision. */
 export function withColorOpacity(color, opacity) {
     const hex = /^#([\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.exec(color.trim());
     if (hex) {
@@ -408,7 +384,6 @@ export function withColorOpacity(color, opacity) {
     }
     return applyColorOpacity(color, opacity);
 }
-/** Preserves the previous opacity when the replacement color has no explicit alpha. */
 export function replaceColorPreservingOpacity(previous, color, context) {
     const opacity = interpretColorOpacity(previous, context);
     return opacity && !colorValueHasEmbeddedAlpha(color)
@@ -498,12 +473,7 @@ function replaceColorMixColor(value, oldValue, nextColor) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/**
- * Replaces only the color token in a separable color expression. Keeping this
- * separate from a plain token swap preserves authored alpha modifiers, for
- * example Tailwind's `color-mix(... var(--color-red-500) 10%, transparent)`
- * keeps its `10%` when the color token changes.
- */
+/** Replaces only the color token so authored alpha modifiers survive the swap. */
 export function applyColorTokenReplacement(value, oldToken, newToken) {
     const nextName = tokenReferenceName(newToken);
     if (nextName) {
@@ -534,7 +504,6 @@ export function applyColorTokenReplacement(value, oldToken, newToken) {
         return { ok: true, value: mixReplacement };
     return { ok: false, reason: "unsupported" };
 }
-/** The public meaning-preserving edit operation for supported value edits. */
 export function applyValueEdit(request) {
     if (request.kind === "color-opacity") {
         return applyColorOpacity(request.authored, request.opacity);