nudge-ui 0.2.4 → 0.2.6

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

@@ -1,19 +1,19 @@
+export interface VarReference {
+    readonly name: string;
+    readonly fallback?: string;
+}
 /**
- * Low-level, browser-safe CSS value splitting helpers shared by the
- * value-semantics Modules (plan slice 3.4). These are internal parsing seams,
- * not public Interface: they split structure, they do not interpret meaning.
- */
-/**
- * Balanced `var()` scanning. Handles nested parentheses and takes the first
- * top-level comma as the fallback separator.
+ * Parses a value that is exactly one `var()` reference. The fallback may
+ * contain nested parentheses; trailing text is rejected rather than swallowed.
  */
+export declare function parseSingleVarReference(value: string): VarReference | null;
+export declare function isSingleVarReference(value: string): boolean;
+export declare function isCalcExpression(value: string): boolean;
+/** Scans balanced `var()` calls; the first top-level comma separates the fallback. */
 export declare function extractVarCalls(value: string): Array<{
     name: string;
     fallback?: string;
 }>;
-/** Index of the first top-level `/` in a value, or -1 when none exists. */
 export declare function topLevelSlashIndex(value: string): number;
-/** Splits CSS values at top-level combinators or an optional delimiter. */
 export declare function splitTopLevel(s: string, sep?: string): string[];
-/** Splits a value at top-level whitespace, honoring quotes and nesting. */
 export declare function splitTopLevelWhitespace(value: string): string[];

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

@@ -1,12 +1,44 @@
 /**
- * Low-level, browser-safe CSS value splitting helpers shared by the
- * value-semantics Modules (plan slice 3.4). These are internal parsing seams,
- * not public Interface: they split structure, they do not interpret meaning.
- */
-/**
- * Balanced `var()` scanning. Handles nested parentheses and takes the first
- * top-level comma as the fallback separator.
+ * Parses a value that is exactly one `var()` reference. The fallback may
+ * contain nested parentheses; trailing text is rejected rather than swallowed.
  */
+export function parseSingleVarReference(value) {
+    const trimmed = value.trim();
+    if (!/^var\(/i.test(trimmed))
+        return null;
+    let depth = 0;
+    let comma = -1;
+    for (let index = 3; index < trimmed.length; index++) {
+        const char = trimmed[index];
+        if (char === "(") {
+            depth++;
+            continue;
+        }
+        if (char === ")") {
+            depth--;
+            if (depth !== 0)
+                continue;
+            if (index !== trimmed.length - 1)
+                return null;
+            const body = trimmed.slice(4, index);
+            const name = (comma < 0 ? body : body.slice(0, comma - 4)).trim();
+            if (!/^--[\w-]+$/.test(name))
+                return null;
+            const fallback = comma < 0 ? undefined : body.slice(comma - 3).trim();
+            return fallback ? { name, fallback } : { name };
+        }
+        if (char === "," && depth === 1 && comma < 0)
+            comma = index;
+    }
+    return null;
+}
+export function isSingleVarReference(value) {
+    return parseSingleVarReference(value) !== null;
+}
+export function isCalcExpression(value) {
+    return /\bcalc\s*\(/i.test(value);
+}
+/** Scans balanced `var()` calls; the first top-level comma separates the fallback. */
 export function extractVarCalls(value) {
     const calls = [];
     let i = 0;
@@ -37,7 +69,6 @@ export function extractVarCalls(value) {
     }
     return calls;
 }
-/** Index of the first top-level `/` in a value, or -1 when none exists. */
 export function topLevelSlashIndex(value) {
     let depth = 0;
     for (let index = 0; index < value.length; index++) {
@@ -51,7 +82,6 @@ export function topLevelSlashIndex(value) {
     }
     return -1;
 }
-/** Splits CSS values at top-level combinators or an optional delimiter. */
 export function splitTopLevel(s, sep) {
     const parts = [];
     let depth = 0;
@@ -66,7 +96,6 @@ export function splitTopLevel(s, sep) {
             start = i + 1;
         }
         else if (depth === 0 && !sep && (s[i] === " " || s[i] === ">" || s[i] === "+" || s[i] === "~")) {
-            // Only split on combinators that have non-space around them.
             if (i > start)
                 parts.push(s.slice(start, i).trim());
             start = i + 1;
@@ -77,7 +106,6 @@ export function splitTopLevel(s, sep) {
         parts.push(last);
     return parts;
 }
-/** Splits a value at top-level whitespace, honoring quotes and nesting. */
 export function splitTopLevelWhitespace(value) {
     const parts = [];
     let depth = 0;

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

@@ -1,12 +1,3 @@
-/**
- * Supported `font` shorthand decomposition (plan slice 3.5).
- *
- * One browser-safe Module decomposes the unambiguous typography longhands
- * affected by a `font` shorthand — family, size, style, weight, and
- * line-height. Omitted optional components are represented by their shorthand
- * reset value. System-font shorthands, percentage-sized variants, and complex
- * family/function forms stay raw so the author's meaning is never guessed.
- */
 export declare const FONT_SYSTEM_KEYWORDS: Set<string>;
 export declare const FONT_SIZE_KEYWORDS: Set<string>;
 export declare const FONT_WEIGHT_KEYWORDS: Set<string>;
@@ -18,18 +9,11 @@ export interface FontShorthandParts {
     "font-weight": string;
     "line-height": string;
 }
-/**
- * Splits a font shorthand without losing quoted family names or functions.
- * The slash is a token only at top level, which lets us distinguish the
- * optional `font-size / line-height` portion from a slash in a URL/function.
- */
+/** The slash is a token only at top level, so URLs and functions survive. */
 export declare function splitFontShorthand(value: string): string[];
 export declare function isFontSize(value: string): boolean;
 /**
- * Returns the supported typography longhands affected by an unambiguous
- * `font` shorthand. Omitted optional components are projected as `normal`
- * because a font shorthand resets them; dropping those reset rows would let
- * earlier declarations survive the cascade incorrectly. System-font
- * shorthands and percentage-sized variants remain raw.
+ * Omitted optional components project as their shorthand reset value; dropping
+ * those rows would let earlier declarations survive the cascade.
  */
 export declare function parseFontShorthand(value: string): FontShorthandParts | null;

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

@@ -1,12 +1,3 @@
-/**
- * Supported `font` shorthand decomposition (plan slice 3.5).
- *
- * One browser-safe Module decomposes the unambiguous typography longhands
- * affected by a `font` shorthand — family, size, style, weight, and
- * line-height. Omitted optional components are represented by their shorthand
- * reset value. System-font shorthands, percentage-sized variants, and complex
- * family/function forms stay raw so the author's meaning is never guessed.
- */
 export const FONT_SYSTEM_KEYWORDS = new Set([
     "caption", "icon", "menu", "message-box", "small-caption", "status-bar",
 ]);
@@ -16,11 +7,7 @@ export const FONT_SIZE_KEYWORDS = new Set([
 ]);
 export const FONT_WEIGHT_KEYWORDS = new Set(["normal", "bold", "bolder", "lighter"]);
 export const FONT_STYLE_KEYWORDS = new Set(["normal", "italic", "oblique"]);
-/**
- * Splits a font shorthand without losing quoted family names or functions.
- * The slash is a token only at top level, which lets us distinguish the
- * optional `font-size / line-height` portion from a slash in a URL/function.
- */
+/** The slash is a token only at top level, so URLs and functions survive. */
 export function splitFontShorthand(value) {
     const parts = [];
     let start = -1;
@@ -73,11 +60,8 @@ export function isFontSize(value) {
         || /^(?:[+-]?(?:\d*\.)?\d+(?:[a-z]+|%)|(?:var|calc|min|max|clamp|env)\()/i.test(value);
 }
 /**
- * Returns the supported typography longhands affected by an unambiguous
- * `font` shorthand. Omitted optional components are projected as `normal`
- * because a font shorthand resets them; dropping those reset rows would let
- * earlier declarations survive the cascade incorrectly. System-font
- * shorthands and percentage-sized variants remain raw.
+ * Omitted optional components project as their shorthand reset value; dropping
+ * those rows would let earlier declarations survive the cascade.
  */
 export function parseFontShorthand(value) {
     const source = value.trim();
@@ -88,8 +72,8 @@ export function parseFontShorthand(value) {
     if (sizeIndex < 0)
         return null;
     const fontSize = parts[sizeIndex];
-    // Percentages may be a preceding font-stretch component or the required
-    // size. Keep this uncommon form raw rather than choose arbitrarily.
+    // A leading percentage may be font-stretch, not the required size; keep this
+    // uncommon form raw rather than choose arbitrarily.
     if (/^[+-]?(?:\d*\.)?\d+%$/.test(fontSize) && sizeIndex > 0)
         return null;
     let cursor = sizeIndex + 1;
@@ -115,10 +99,8 @@ export function parseFontShorthand(value) {
             weight = part;
             continue;
         }
-        // Variant, stretch, angle-bearing oblique, duplicate, and unknown prefix
-        // components are valid in wider font grammar but outside this supported
-        // projection. Keep the whole shorthand conservative instead of dropping
-        // their meaning.
+        // Components outside this supported projection keep the whole shorthand
+        // conservative instead of dropping their meaning.
         return null;
     }
     return {

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

@@ -1,16 +1,5 @@
-/**
- * Browser-safe value-semantics seam for `nudge-ui/css`.
- *
- * The Interface has three conceptual operations: interpret one authored value,
- * select compatible tokens, and apply a meaning-preserving edit. Token, color,
- * property-family, and structured parsers remain internal Implementation seams.
- * Framework-specific attribution arrives as explicit Adapter facts in the
- * interpretation context.
- *
- * Browser-safe contract: this module imports only the shared model and must
- * never pull React, Vite, PostCSS, Node, or filesystem code into a bundle.
- */
 export { interpretValue } from "./structuredValues.js";
+export { isCalcExpression, isSingleVarReference, parseSingleVarReference } from "./cssSyntax.js";
 export type { StructuredField as InterpretedValueField, StructuredValuesContext as ValueSemanticsContext } from "./structuredValues.js";
 export type { Directionality } from "./boxSemantics.js";
 export type { AliasAttribution, AliasInnerResult, TokenInterpretationContext, } from "./tokenInterpretation.js";

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

@@ -1,15 +1,4 @@
-/**
- * Browser-safe value-semantics seam for `nudge-ui/css`.
- *
- * The Interface has three conceptual operations: interpret one authored value,
- * select compatible tokens, and apply a meaning-preserving edit. Token, color,
- * property-family, and structured parsers remain internal Implementation seams.
- * Framework-specific attribution arrives as explicit Adapter facts in the
- * interpretation context.
- *
- * Browser-safe contract: this module imports only the shared model and must
- * never pull React, Vite, PostCSS, Node, or filesystem code into a bundle.
- */
 export { interpretValue } from "./structuredValues.js";
+export { isCalcExpression, isSingleVarReference, parseSingleVarReference } from "./cssSyntax.js";
 export { selectTokens, TOKEN_GROUP_LABELS, TOKEN_GROUP_ORDER, } from "./propertyPolicy.js";
 export { applyValueEdit, normalizeOpacityPercent } from "./colorSemantics.js";

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

@@ -1,15 +1,3 @@
-/**
- * Property/value policy (plan slice 3.3).
- *
- * One implementation owns capability classification, property→semantic-slot
- * knowledge, token presentation grouping, and compatible-token candidate
- * selection for value semantics. Eligibility always uses the resolved concrete
- * value plus browser grammar; a token name is a presentation preference and
- * never grants eligibility.
- *
- * Browser-safe contract: this module imports only the shared model and must
- * never pull React, Vite, PostCSS, Node, or filesystem code into a bundle.
- */
 import type { ColorValueFacts, EditCapability, TokenEntry } from "../model/index.js";
 declare global {
     interface Window {
@@ -19,9 +7,7 @@ declare global {
         };
     }
 }
-/** Semantic slot vocabulary for a CSS property. */
 export type TokenSemanticSlot = "color" | "length" | "radius" | "font-family" | "font-size" | "font-weight" | "line-height" | "letter-spacing" | "shadow" | "opacity";
-/** Presentation category for token pickers and catalog rows. */
 export type TokenGroup = "color" | "spacing" | "radius" | "typography" | "shadow" | "generic";
 export declare const TOKEN_GROUP_LABELS: {
     color: string;
@@ -32,7 +18,6 @@ export declare const TOKEN_GROUP_LABELS: {
     generic: string;
 };
 export declare const TOKEN_GROUP_ORDER: TokenGroup[];
-/** Browser grammar is injectable so the policy stays unit-testable. */
 export interface CssValueGrammar {
     supports(property: string, value: string): boolean;
 }
@@ -49,9 +34,8 @@ export interface TokenCandidate {
     isCurrent: boolean;
 }
 export interface TokenCompatibilityRequest {
-    /** The selected host element, used to resolve custom properties in its cascade. */
+    /** Resolves custom properties in this element's cascade. */
     element?: HTMLElement;
-    /** The outer CSS property being edited. */
     property: string;
     /** A scalar slot inside a composite property, such as the color in a shadow. */
     slot?: TokenSemanticSlot;
@@ -72,47 +56,16 @@ export interface TokenSelection {
     candidates: TokenCandidate[];
     preferredGroup: TokenGroup;
 }
-/**
- * Property knowledge lives here rather than in every picker. It supplies a
- * presentation preference and validation slot; it never filters a candidate
- * merely because of that candidate's name.
- */
+/** Property knowledge lives here rather than in every picker: a presentation preference and validation slot, never a name-based filter. */
 export declare function semanticSlotForProperty(property: string): TokenSemanticSlot | null;
 export declare function groupForProperty(property: string, slot?: TokenSemanticSlot): TokenGroup;
-/**
- * Edit-capability classification for a property and its authored value.
- * Preserves the resolver's original precedence exactly: raw functions first,
- * then spacing families, border structure, colors, atomic var(), composites,
- * then literal atomic values.
- */
+/** Precedence is load-bearing and must match the resolver's. */
 export declare function classifyEditCapability(property: string, value: string): EditCapability;
-/**
- * Name-prefix presentation hint. This is a display preference only: it never
- * makes an invalid value eligible for a slot. `value` is a secondary hint used
- * for concrete values with an unfamiliar name.
- */
+/** Presentation hint only; a name never makes an invalid value eligible for a slot. */
 export declare function classifyToken(name: string, value?: string): TokenGroup;
-/**
- * Host-realm grammar factory. Uses the element's window CSS when available,
- * then `globalThis.CSS`, and falls back to a conservative non-browser matcher.
- */
 export declare function browserCssGrammar(element?: HTMLElement): CssValueGrammar;
-/**
- * Presentation may use a name to make familiar token sets easier to scan, but
- * a name never grants eligibility. Unfamiliar concrete colors still group as
- * Color via the same CSS grammar used by the candidate selector.
- */
 export declare function presentationForToken(entry: TokenEntry, grammar?: CssValueGrammar): TokenPresentation;
-/**
- * The single candidate-selection seam for every token-editing control and the
- * inspection bridge. Concrete values are checked in the selected element's
- * cascade, then the browser grammar decides eligibility. Presentation labels
- * only rank results.
- */
+/** The single candidate-selection seam; presentation labels only rank results. */
 export declare function getCompatibleTokenCandidates(request: TokenCompatibilityRequest): TokenCandidate[];
-/**
- * The public token-selection operation. With a property it returns only
- * browser-compatible candidates; without one it returns presentation metadata
- * for inventory rows without inventing eligibility.
- */
+/** Without a property, returns presentation metadata only — never invents eligibility. */
 export declare function selectTokens(request: TokenSelectionRequest): TokenSelection;

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

@@ -1,4 +1,5 @@
 import { interpretColorValue } from "./colorSemantics.js";
+import { isSingleVarReference } from "./cssSyntax.js";
 export const TOKEN_GROUP_LABELS = {
     color: "Color",
     spacing: "Spacing",
@@ -68,11 +69,7 @@ const SLOT_PROPERTIES = {
 function normaliseProperty(property) {
     return property.trim().toLowerCase();
 }
-/**
- * Property knowledge lives here rather than in every picker. It supplies a
- * presentation preference and validation slot; it never filters a candidate
- * merely because of that candidate's name.
- */
+/** Property knowledge lives here rather than in every picker: a presentation preference and validation slot, never a name-based filter. */
 export function semanticSlotForProperty(property) {
     const normalized = normaliseProperty(property);
     if (COLOR_PROPERTIES.has(normalized) || /(^|-)color$/.test(normalized))
@@ -114,18 +111,12 @@ export function groupForProperty(property, slot) {
     }
     return "generic";
 }
-/**
- * Edit-capability classification for a property and its authored value.
- * Preserves the resolver's original precedence exactly: raw functions first,
- * then spacing families, border structure, colors, atomic var(), composites,
- * then literal atomic values.
- */
+/** Precedence is load-bearing and must match the resolver's. */
 export function classifyEditCapability(property, value) {
     const p = property.toLowerCase();
     const v = value.trim().toLowerCase();
-    // Functions whose authored expression cannot be represented faithfully by
-    // a numeric side control remain raw even when the property itself is a
-    // spacing property. The computed value is still available as a preview.
+    // A numeric side control cannot represent these functions faithfully, so
+    // the authored expression stays raw even on a spacing property.
     if (/\b(?:min|max|clamp|env|anchor-size)\s*\(/.test(v))
         return "raw";
     if (["margin", "padding", "inset", "inset-block", "inset-inline"].includes(p)
@@ -135,10 +126,10 @@ export function classifyEditCapability(property, value) {
         return "structured";
     if (p === "color" || /(^|-)color$/.test(p) || p === "background-color" || p === "fill" || p === "stroke")
         return "color";
-    if (/^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/.test(v))
+    if (isSingleVarReference(v))
         return "atomic";
     if (p === "font" || /(gradient|shadow|transform|transition|animation|grid|background)/.test(p)
-        || (v.includes(",") && !/^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/.test(v)))
+        || (v.includes(",") && !isSingleVarReference(v)))
         return "composite";
     if (/\b(min|max|clamp|color-mix)\s*\(/.test(v))
         return "raw";
@@ -147,11 +138,7 @@ export function classifyEditCapability(property, value) {
         return "atomic";
     return "raw";
 }
-/**
- * Name-prefix presentation hint. This is a display preference only: it never
- * makes an invalid value eligible for a slot. `value` is a secondary hint used
- * for concrete values with an unfamiliar name.
- */
+/** Presentation hint only; a name never makes an invalid value eligible for a slot. */
 export function classifyToken(name, value = "") {
     if (name.startsWith("--color-"))
         return "color";
@@ -177,15 +164,17 @@ function tokenVariableName(entry) {
 function hasUnresolvedVariable(value) {
     return /\bvar\s*\(/i.test(value);
 }
-function resolveValueInElement(entry, element) {
+/** Hoisted so one request resolves each token against a single computed style. */
+function elementStyle(element) {
+    const view = element?.ownerDocument.defaultView;
+    return element && view && typeof view.getComputedStyle === "function" ? view.getComputedStyle(element) : null;
+}
+function resolveValueInElement(entry, style) {
     const variableName = tokenVariableName(entry);
-    if (element && variableName.startsWith("--")) {
-        const view = element.ownerDocument.defaultView;
-        if (view && typeof view.getComputedStyle === "function") {
-            const computed = view.getComputedStyle(element).getPropertyValue(variableName).trim();
-            if (computed)
-                return computed;
-        }
+    if (style && variableName.startsWith("--")) {
+        const computed = style.getPropertyValue(variableName).trim();
+        if (computed)
+            return computed;
     }
     return entry.value.trim();
 }
@@ -204,11 +193,7 @@ function isColor(value) {
 function isOpacity(value) {
     return /^[+-]?(?:\d+\.?\d*|\.\d+)(?:%)?$/.test(value.trim());
 }
-/**
- * Modern browsers provide CSS.supports. The small fallback keeps non-browser
- * unit environments conservative and never treats a var() expression as a
- * resolved value.
- */
+/** Conservative fallback for non-browser environments that lack CSS.supports. */
 function fallbackSupports(property, value) {
     const normalized = normaliseProperty(property);
     if (COLOR_PROPERTIES.has(normalized) || /(^|-)color$/.test(normalized))
@@ -229,19 +214,34 @@ function fallbackSupports(property, value) {
         return isLength(value);
     return false;
 }
-/**
- * Host-realm grammar factory. Uses the element's window CSS when available,
- * then `globalThis.CSS`, and falls back to a conservative non-browser matcher.
- */
+const SUPPORTS_CACHE_LIMIT = 20_000;
+const supportsCaches = new WeakMap();
+/** Cached per CSS object: pickers repeat the same questions for every field on every selection. */
+function cachedSupports(css, property, value) {
+    if (typeof css.supports !== "function")
+        return null;
+    let cache = supportsCaches.get(css);
+    if (!cache) {
+        cache = new Map();
+        supportsCaches.set(css, cache);
+    }
+    const key = `${property}\n${value}`;
+    let supported = cache.get(key);
+    if (supported === undefined) {
+        if (cache.size >= SUPPORTS_CACHE_LIMIT)
+            cache.clear();
+        supported = css.supports(property, value);
+        cache.set(key, supported);
+    }
+    return supported;
+}
 export function browserCssGrammar(element) {
     const css = browserCss(element);
     return {
         supports(property, value) {
             if (hasUnresolvedVariable(value) || !value.trim())
                 return false;
-            if (typeof css?.supports === "function")
-                return css.supports(property, value);
-            return fallbackSupports(property, value);
+            return (css ? cachedSupports(css, property, value) : null) ?? fallbackSupports(property, value);
         },
     };
 }
@@ -259,11 +259,6 @@ function nameHint(name) {
         return "spacing";
     return null;
 }
-/**
- * Presentation may use a name to make familiar token sets easier to scan, but
- * a name never grants eligibility. Unfamiliar concrete colors still group as
- * Color via the same CSS grammar used by the candidate selector.
- */
 export function presentationForToken(entry, grammar = browserCssGrammar()) {
     const value = entry.value.trim();
     const group = !hasUnresolvedVariable(value) && grammar.supports("color", value)
@@ -290,20 +285,16 @@ function compareCandidates(preferred) {
         return left.entry.name.localeCompare(right.entry.name);
     };
 }
-/**
- * The single candidate-selection seam for every token-editing control and the
- * inspection bridge. Concrete values are checked in the selected element's
- * cascade, then the browser grammar decides eligibility. Presentation labels
- * only rank results.
- */
+/** The single candidate-selection seam; presentation labels only rank results. */
 export function getCompatibleTokenCandidates(request) {
     const grammar = request.grammar ?? browserCssGrammar(request.element);
     const slot = request.slot ?? semanticSlotForProperty(request.property) ?? undefined;
     const property = validationProperty(request.property, slot);
     const preferredGroup = groupForProperty(request.property, slot);
+    const style = elementStyle(request.element);
     return request.entries
         .map((entry) => {
-        const resolvedValue = resolveValueInElement(entry, request.element);
+        const resolvedValue = resolveValueInElement(entry, style);
         const presentation = presentationForToken({ ...entry, value: resolvedValue }, grammar);
         return {
             entry,
@@ -317,11 +308,7 @@ export function getCompatibleTokenCandidates(request) {
         && grammar.supports(property, candidate.resolvedValue)))
         .sort(compareCandidates(preferredGroup));
 }
-/**
- * The public token-selection operation. With a property it returns only
- * browser-compatible candidates; without one it returns presentation metadata
- * for inventory rows without inventing eligibility.
- */
+/** Without a property, returns presentation metadata only — never invents eligibility. */
 export function selectTokens(request) {
     if (request.property) {
         const slot = request.slot ?? semanticSlotForProperty(request.property) ?? undefined;
@@ -338,9 +325,10 @@ export function selectTokens(request) {
         };
     }
     const grammar = request.grammar ?? browserCssGrammar(request.element);
+    const style = elementStyle(request.element);
     return {
         candidates: request.entries.map((entry) => {
-            const resolvedValue = resolveValueInElement(entry, request.element);
+            const resolvedValue = resolveValueInElement(entry, style);
             const presentation = presentationForToken({ ...entry, value: resolvedValue }, grammar);
             return {
                 entry,

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

@@ -1,2 +1 @@
-/** A read-only string-array map used for physical side and corner expansion. */
 export type StringArrayMap = Record<string, readonly string[]>;

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

@@ -1,30 +1,7 @@
-/**
- * Structured and box value interpretation (plan slice 3.5).
- *
- * One browser-safe Module turns an authored CSSOM value for a box/border/
- * radius/font property into a structured projection tree: the physical sides,
- * border longhands, radius corners, or font longhands it expands to, each with
- * source-property provenance and its own token interpretation.
- *
- * One interpretation tree: each distinct authored component is token-interpreted
- * once and every projected field that carries that component reuses the same
- * interpretation (tokenName, tokens, opacity, modifiers, cycle). A border color
- * token, a multi-value spacing token, or a radius token is therefore resolved
- * once per declaration, not once per projected longhand.
- *
- * Conservative fallbacks: ambiguous borders, slash-separated radius forms,
- * complex fonts, and everything outside the supported families stay a single
- * raw/composite row with the resolution's existing capability classification.
- *
- * Browser-safe contract: this module imports only the shared model and the
- * other value-semantics Modules. Directionality is an explicit input fact; it
- * never walks the DOM or CSSOM.
- */
 import type { BorderStructure, ColorOpacity, EditCapability, OpacityValue, TokenReference, ValueModifier } from "../model/index.js";
 import { type TokenInterpretationContext, type TokenValueInterpretation } from "./tokenInterpretation.js";
 import { type Directionality } from "./boxSemantics.js";
 export type { Directionality } from "./boxSemantics.js";
-/** One projected longhand row from the structured interpretation. */
 export interface StructuredField {
     property: string;
     /** The authored value projected to this field (per-side/corner/longhand). */
@@ -42,23 +19,12 @@ export interface StructuredField {
     structure?: BorderStructure;
     diagnostic?: string;
 }
-/** Explicit, DOM-free facts the structured interpretation needs. */
 export interface StructuredValuesContext {
-    /** Token table plus the integration's token-interpretation policies. */
     tokenContext: TokenInterpretationContext;
-    /**
-     * Writing-mode/direction facts for logical→physical mapping. Absent →
-     * `ltr` / `horizontal-tb`.
-     */
+    /** Writing-mode/direction facts for logical→physical mapping; defaults to `ltr`/`horizontal-tb`. */
     directionality?: Directionality;
 }
-/**
- * Interprets one authored value for a property into a structured projection
- * tree. Returns the projected fields, or a single conservative raw/composite
- * field when the value cannot be decomposed faithfully. The declared order of
- * the families mirrors CSS projection precedence: logical sides, border, font,
- * border-radius corners, gap, physical spacing, then the raw fallback.
- */
+/** Values that cannot be decomposed faithfully collapse to one conservative raw/composite field; families are checked in CSS precedence order. */
 export declare function interpretValue(property: string, authored: string, ctx: StructuredValuesContext): StructuredField[];
-/** @internal Use the package-level `interpretValue` Interface in production. */
+/** @internal Use `interpretValue` in production. */
 export declare const interpretStructuredValue: typeof interpretValue;