nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/tokens/TokenField.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { IconLinkOff } from "@tabler/icons-react";
-import { applyValueEdit, normalizeOpacityPercent, selectTokens, } from "../../css/value-semantics/index.js";
+import { applyValueEdit, isCalcExpression, normalizeOpacityPercent, selectTokens, } from "../../css/value-semantics/index.js";
 import { promoteToToken, swapToken } from "./editActions.js";
 import { setStyle } from "./editActions.js";
 import { completeCssValue } from "../styleEditors/completeCssValue.js";
+import { deriveActiveTokenName, isExpressionRow } from "../styleEditors/fieldValue.js";
 import { canNudgeCssValueByDrag, nudgeCssValue, nudgeCssValueByDrag, nudgeOpacityValue, supportsDragNudge, } from "../styleEditors/nudgeValue.js";
 import { valuePolicyFor } from "../styleEditors/valuePolicy.js";
 import { IconButton } from "../ui/IconButton.js";
@@ -78,7 +79,7 @@ function releasePointerCapture(state) {
         // The browser may release capture before pointerup/pointercancel arrives.
     }
 }
-/** Returns the first family in a CSS family list without splitting var() fallbacks. */
+/** First family in a CSS family list; commas inside var() fallbacks are ignored. */
 function primaryFontFamily(value) {
     let depth = 0;
     let quote = null;
@@ -203,11 +204,7 @@ export function TokenValueField(props) {
     const showOpacity = isColor && !activeTokenHasEmbeddedAlpha
         && authoredColor.opacityEditable
         && (Boolean(activeTokenName) || attributionTokens.length === 0 || Boolean(opacity));
-    // One classification pass per entries change. selectTokens costs up to
-    // three CSS.supports calls per token, so classifying per token per render
-    // (chip mode is unbounded; raw mode runs per keystroke) dominates this
-    // field's render cost. Map misses fall back to direct classification for
-    // synthetic entries that are not part of the catalog list.
+    // Classification costs up to three CSS.supports calls per token, so it runs once per entries change.
     const groupByTokenName = useMemo(() => {
         const groups = new Map();
         for (const entry of entries)
@@ -269,8 +266,7 @@ export function TokenValueField(props) {
         onCommitRaw(formatted);
     }
     function handleDelink() {
-        // A token-backed alpha expression is represented by a chip, but unlinking
-        // it should preserve the complete authored color expression and its alpha.
+        // Unlinking must preserve the complete authored color expression and its alpha.
         const value = opacity ? committedValue : activeToken?.value || resolvedValue || committedValue;
         setActiveTokenName(null);
         setRawValue(value);
@@ -510,7 +506,7 @@ function arrowDirection(key) {
     return null;
 }
 export function TokenField(props) {
-    const { property, semanticSlot, tokenRow, selection, initialValue, displayValue, domElement: el, editTarget, entries, suggestions, inputDataTest, onAfterEdit, editMetadata, leading, trailing, className, label, chipVariant, formatRawValue: formatRawValueProp, disabled = false, mixed = false, attributionTokens, inlineWarningDataTest, inlineWarningTooltipDataTest, } = props;
+    const { property, semanticSlot, tokenRow, selection, initialValue, displayValue, domElement: el, editTarget, entries, suggestions, inputDataTest, onAfterEdit, editMetadata, leading, trailing, className, label, chipVariant, formatRawValue: formatRawValueProp, disabled = false, mixed = false, attributionTokens, inlineWarningDataTest, inlineWarningTooltipDataTest, interceptRaw, } = props;
     const selectedProperty = selection && selection.elements.length > 1
         ? selection.getProperty(property)
         : null;
@@ -526,25 +522,18 @@ export function TokenField(props) {
         && tokenRow.opacity.tokenName !== tokenRow.tokenName
         ? tokenRow.tokenName
         : null;
-    const expression = Boolean(tokenRow && (tokenRow.capability === "raw" || tokenRow.capability === "composite"
-        || tokenRow.modifiers?.some((modifier) => modifier.kind === "alpha")
-        || tokenRow.color?.isExpression));
+    const expression = isExpressionRow(tokenRow ?? null);
     const authored = tokenRow?.authored ?? tokenRow?.declaredValue ?? "";
-    const isCalcAuthored = /\bcalc\s*\(/i.test(authored);
-    const selectedTokenName = selectedProperty?.token.kind === "common"
-        ? selectedProperty.token.name
-        : null;
-    const activeTokenName = effectiveMixed
-        ? null
-        : tokenBackedOpacityName
-            ?? (expression || isCalcAuthored
-                ? null
-                : selectedProperty ? selectedTokenName : tokenRow?.tokenName ?? null);
+    const isCalcAuthored = isCalcExpression(authored);
+    const activeTokenName = deriveActiveTokenName({
+        row: tokenRow ?? null,
+        selectedProperty,
+        mixed: effectiveMixed,
+        authored,
+        override: tokenBackedOpacityName,
+    });
     const fallbackValue = initialValue ?? structuredBorderValue(property, tokenRow) ?? computedRaw(el, property);
-    // When a calc() was simplified to a numeric value we suppress the token
-    // chip so the UI shows the resolved pixel value, not the internal
-    // multiplier token (e.g. --spacing).  The authored expression stays
-    // accessible via the row for diagnostics.
+    // Suppress the chip for calc()-derived values so the UI shows the resolved pixel value, not the internal multiplier token.
     const authoredOrComputed = tokenBackedOpacityName
         ? authored
         : expression || (!activeTokenName && !isCalcAuthored)
@@ -560,8 +549,7 @@ export function TokenField(props) {
         : null;
     let resolvedValue = tokenRow?.propertyOpacity?.value ?? tokenRow?.resolvedValue ?? committedValue;
     if (property === "background-color") {
-        // Background rows can contain the complete computed shorthand. Extract
-        // its color before passing it to the color control, preserving alpha.
+        // Background rows can carry the full computed shorthand; the color control needs its color part.
         const style = el.ownerDocument.createElement("span").style;
         style.background = resolvedValue;
         resolvedValue = style.backgroundColor || resolvedValue;
@@ -575,6 +563,8 @@ export function TokenField(props) {
                 return formatRawValueProp(value);
             return completeCssValue(value.trim(), valuePolicyFor(property));
         }, onCommitRaw: (value) => {
+            if (interceptRaw?.(value))
+                return;
             if (setStyle(editTarget ?? el, property, value, effectiveMetadata))
                 onAfterEdit?.();
         }, onCommitOpacity: (value) => {

package/dist/inspector/tokens/catalog.d.ts

@@ -25,16 +25,7 @@ export interface TokenRuntime {
     layerOrder(name: string): number | undefined;
 }
 export declare function isTokenContextActive(context: TokenContext, runtime: TokenRuntime): boolean;
-/**
- * Strips host-declared structural scoping markers from a selector so
- * human-facing labels present only author vocabulary (ADR-0011). The marker
- * grammar — Astro's `[data-astro-cid-<hash>]` attribute selectors or
- * `.astro-<hash>` classes, a future Vue/Svelte equivalent — is declared by
- * the host Adapter through the runtime configuration; the raw selector is
- * retained in `context.selector` so resolution keeps matching the rendered
- * DOM. A `:where(...)` wrapper left empty by the removals disappears
- * entirely.
- */
+/** Strips host-declared scoping markers for labels; `context.selector` keeps the raw selector for matching. */
 export declare function humanizeSelector(selector: string, scopingPattern: RegExp | null): string;
 export declare function contextLabel(context: TokenContext): string;
 export declare function sourceParts(source: string): {
@@ -46,6 +37,7 @@ export declare function selectorForContext(context: TokenContext): string;
 export declare function classifyCatalogToken(name: string, value?: string): TokenCatalogGroup;
 export declare function buildTokenCatalogRows(catalog: TokenDefinition[], root?: HTMLElement, suppliedRuntime?: TokenRuntime): TokenCatalogRow[];
 export declare function filterTokenRows(rows: readonly TokenCatalogRow[], query: string): TokenCatalogRow[];
+/** An alias is a whole-string reference with no fallback; a fallback changes the value. */
 export declare function aliasName(value: string): string | null;
 export declare function createsAliasCycle(tokenName: string, candidateName: string, authoredValues: ReadonlyMap<string, string>): boolean;
 export declare function compatibleTokenNames(row: TokenCatalogRow, rows: readonly TokenCatalogRow[]): Set<string>;

package/dist/inspector/tokens/catalog.js

@@ -1,6 +1,7 @@
 import { getScopingSelectorPattern } from "../runtime/runtimeConfig.js";
 import { getElementComputedStyle, getElementWindow } from "../runtime/domRealm.js";
 import { selectTokens } from "../../css/value-semantics/index.js";
+import { parseSingleVarReference } from "../../css/value-semantics/cssSyntax.js";
 import { cascadeLayerOrder } from "./resolution/cssomCollector.js";
 import { compareAuthorCascade } from "./resolution/cascade.js";
 import { computeSpecificityCore } from "./resolution/selectorSemantics.js";
@@ -83,16 +84,7 @@ function pickWinningDeclaration(declarations, runtime) {
     });
     return winner;
 }
-/**
- * Strips host-declared structural scoping markers from a selector so
- * human-facing labels present only author vocabulary (ADR-0011). The marker
- * grammar — Astro's `[data-astro-cid-<hash>]` attribute selectors or
- * `.astro-<hash>` classes, a future Vue/Svelte equivalent — is declared by
- * the host Adapter through the runtime configuration; the raw selector is
- * retained in `context.selector` so resolution keeps matching the rendered
- * DOM. A `:where(...)` wrapper left empty by the removals disappears
- * entirely.
- */
+/** Strips host-declared scoping markers for labels; `context.selector` keeps the raw selector for matching. */
 export function humanizeSelector(selector, scopingPattern) {
     const stripped = scopingPattern === null ? selector : selector.replace(scopingPattern, "");
     return stripped
@@ -160,9 +152,10 @@ export function filterTokenRows(rows, query) {
         || row.definition.cssName.toLowerCase().includes(needle)
         || row.definition.declarations.some((declaration) => declaration.value.toLowerCase().includes(needle)));
 }
-const EXACT_ALIAS = /^var\(\s*(--[\w-]+)\s*\)$/;
+/** An alias is a whole-string reference with no fallback; a fallback changes the value. */
 export function aliasName(value) {
-    return value.trim().match(EXACT_ALIAS)?.[1] ?? null;
+    const reference = parseSingleVarReference(value);
+    return reference && reference.fallback === undefined ? reference.name : null;
 }
 export function createsAliasCycle(tokenName, candidateName, authoredValues) {
     const visited = new Set([tokenName]);

package/dist/inspector/tokens/dragPointerLock.d.ts

@@ -1,4 +1,3 @@
-/** Keeps mouse drags relative, including when the handle is inside a shadow root. */
 export declare function startDragPointerLock(handle: HTMLElement, point: {
     x: number;
     y: number;

package/dist/inspector/tokens/dragPointerLock.js

@@ -1,5 +1,4 @@
 import { showLockedDragCursor } from "../ui/dragCursor.js";
-/** Keeps mouse drags relative, including when the handle is inside a shadow root. */
 export function startDragPointerLock(handle, point, onMove, onEnd) {
     const doc = handle.ownerDocument;
     const root = handle.getRootNode();
@@ -45,7 +44,7 @@ export function startDragPointerLock(handle, point, onMove, onEnd) {
     doc.addEventListener("pointerlockchange", onLockChange);
     doc.addEventListener("pointerlockerror", onLockError);
     try {
-        // Older implementations return void. Rejections retain pointer-capture dragging.
+        // Older implementations return void; a rejection still leaves pointer-capture dragging.
         const request = handle.requestPointerLock();
         if (request)
             void request.catch(onLockError);
@@ -62,7 +61,7 @@ export function startDragPointerLock(handle, point, onMove, onEnd) {
             doc.removeEventListener("mouseup", onMouseUp);
             if (isLocked())
                 doc.exitPointerLock();
-            // A request can finish after mouse-up or unmount. Release that late lock too.
+            // A pending request can acquire the lock after mouse-up; release that late lock too.
             if (!pending)
                 removeLockListeners();
         },

package/dist/inspector/tokens/editActions.d.ts

@@ -7,7 +7,7 @@ export interface StyleEditMetadata {
     sourceProperty?: string;
     sourceAuthoredValue?: string;
 }
-/** Returns whether a style write can address every element in the target safely. */
+/** True only when a write can address every element in the target. */
 export declare function canEditStyles(target: EditTarget): boolean;
 export declare function buildSelector(cid: string, src: string): string | null;
 export declare function swapToken(target: EditTarget, property: string, newToken: TokenEntry, oldToken: TokenEntry | null, metadata?: StyleEditMetadata): ElementChangeRecord | null;

package/dist/inspector/tokens/editActions.js

@@ -30,9 +30,7 @@ function sourceFields(el) {
         };
     }
     if (!parsed) {
-        // Authored markup whose source annotation is absent or unusable — for
-        // example Astro dev-annotation degraded mode. Prompts must say the
-        // location is unknown instead of rendering a fabricated `file:0`.
+        // Unannotated authored markup (e.g. Astro degraded mode): prompts must report an unknown location, never a fabricated `file:0`.
         return {
             file: "",
             line: 0,
@@ -55,7 +53,7 @@ function sourceFields(el) {
     };
 }
 export { getPendingRules, getChangesList as getChangeRecords, clearActiveDraft as resetPendingRules } from "../drafts/store.js";
-/** Returns whether a style write can address every element in the target safely. */
+/** True only when a write can address every element in the target. */
 export function canEditStyles(target) {
     return canPlanBatchEditScopes(targetElements(target));
 }

package/dist/inspector/tokens/resolution/cascade.d.ts

@@ -6,9 +6,5 @@ export interface AuthorCascadePriority {
     specificity: number;
     sourceOrder: number;
 }
-/**
- * Compares declarations from the author origin. Positive means `a` wins.
- * Normal declarations prefer unlayered rules and later layers; important
- * declarations reverse both relationships as required by the CSS cascade.
- */
+/** Positive means `a` wins; important declarations reverse layer precedence per the CSS cascade. */
 export declare function compareAuthorCascade(a: AuthorCascadePriority, b: AuthorCascadePriority): number;

package/dist/inspector/tokens/resolution/cascade.js

@@ -1,8 +1,4 @@
-/**
- * Compares declarations from the author origin. Positive means `a` wins.
- * Normal declarations prefer unlayered rules and later layers; important
- * declarations reverse both relationships as required by the CSS cascade.
- */
+/** Positive means `a` wins; important declarations reverse layer precedence per the CSS cascade. */
 export function compareAuthorCascade(a, b) {
     const aImportant = Boolean(a.important);
     const bImportant = Boolean(b.important);

package/dist/inspector/tokens/resolution/containerQueryEvaluator.d.ts

@@ -7,9 +7,5 @@ export interface ContainerQueryEvaluator {
     prefetch(pairs: readonly ContainerQueryPair[]): void;
     matches(element: HTMLElement, conditions: readonly string[]): boolean;
 }
-/**
- * Evaluates container conditions in batches for one inspection refresh.
- * Each pair gets its own property, so inherited probe values cannot answer
- * another element's query. No stylesheet or marker survives a batch.
- */
+/** Each pair gets its own probe property so inherited values cannot answer another element's query; nothing survives a batch. */
 export declare function createContainerQueryEvaluator(doc: Document): ContainerQueryEvaluator;

package/dist/inspector/tokens/resolution/containerQueryEvaluator.js

@@ -2,11 +2,7 @@ import { countInspectionWork } from "../../inspection/performanceDiagnostics.js"
 import { adoptStylesheet, allowsStyleElements, releaseAdoptedStylesheet } from "../../runtime/ownedStylesheets.js";
 const PROBE_SHEET_KEY = "nudge-ui-container-probe";
 let nextProbeId = 0;
-/**
- * Evaluates container conditions in batches for one inspection refresh.
- * Each pair gets its own property, so inherited probe values cannot answer
- * another element's query. No stylesheet or marker survives a batch.
- */
+/** Each pair gets its own probe property so inherited values cannot answer another element's query; nothing survives a batch. */
 export function createContainerQueryEvaluator(doc) {
     const results = new WeakMap();
     const key = (conditions) => JSON.stringify(conditions);

package/dist/inspector/tokens/resolution/cssomCollector.d.ts

@@ -3,32 +3,17 @@ export interface DocumentRevisions {
     element: number;
     stylesheet: number;
 }
-/**
- * Subscribes to cascade revisions for one document. This is the narrow
- * document-scoped seam used by the browser inspection Module.
- */
 export declare function subscribeDocumentRevision(doc: Document, cb: (revisions: Readonly<DocumentRevisions>) => void): () => void;
-/**
- * Elements whose attribute changes can affect a cached cascade outcome. The
- * observer only counts attribute mutations against registered elements so
- * unrelated host churn (React commits, hover states, animations) cannot bump
- * the element revision. Registration is idempotent.
- */
+/** Only attribute mutations on registered elements bump the element revision; unrelated host churn is ignored. */
 export declare function registerResolutionElement(el: Element): void;
 export declare function registerResolutionLineage(element: HTMLElement): void;
-/** Releases the observer, listener, and cached state owned by one document. */
 export declare function disposeDocumentResolution(doc: Document): void;
 export declare function retainDocumentResolution(doc: Document): () => void;
 export declare function documentRevisions(doc: Document): DocumentRevisions;
-/** Invalidates CSSOM-derived snapshots after programmatic stylesheet edits. */
 export declare function invalidateStyleResolutionCache(doc?: Document): void;
-/**
- * Reads the declarations the browser accepted for a style rule. This is the
- * semantic source for authored values; it intentionally does not inspect the
- * stylesheet element's original text. CSSOM may expose a shorthand as empty
- * longhand entries through indexed enumeration, so prefer its serialized
- * declaration block and use enumeration as a compatibility fallback.
- */
+/** Inspector-only invalidation; page sheets are re-read only if their objects changed. */
+export declare function invalidateOwnedStyleResolution(doc?: Document): void;
+/** Prefers the serialized declaration block; enumeration is a fallback because a shorthand can enumerate empty longhands. */
 export declare function declarationsFromCssom(style: CSSStyleDeclaration): StyleDeclaration[];
 export declare function collectRules(doc: Document): {
     revision: number;