nudge-ui 0.2.0 → 0.2.1

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

@@ -0,0 +1,423 @@
+import { INTERACTION_STATES } from "../../shell/styleState.js";
+import { collectRules as collectCssomRules, documentRevisions as getDocumentRevisions } from "./cssomCollector.js";
+import { computeSpecificity, hasSelectorPseudoClass, isElementSensitiveSelector, canMatchSelectorSubject, selectorPseudoClasses, splitSelectorAtTopLevel, } from "./selectorSemantics.js";
+const TRANSIENT_PSEUDO_CLASSES = new Set([
+    "hover",
+    "active",
+    "focus",
+    "focus-visible",
+    "focus-within",
+    "visited",
+    "target",
+]);
+const INTERACTION_PSEUDO_CLASSES = new Set(INTERACTION_STATES);
+function selectorForState(selector, state) {
+    const pseudoClasses = selectorPseudoClasses(selector)
+        .filter(({ name }) => INTERACTION_PSEUDO_CLASSES.has(name));
+    const states = new Set(pseudoClasses.map(({ name }) => name));
+    if (state === "base")
+        return states.size === 0 ? selector : null;
+    if (!states.has(state))
+        return states.size === 0 ? selector : null;
+    // CSSOM cannot ask the browser whether a hypothetical pseudo-class matches.
+    // Removing interaction pseudo-classes gives the authored rule a stable
+    // element match for inspection. The real rule remains untouched.
+    let transformed = selector;
+    for (let index = pseudoClasses.length - 1; index >= 0; index--) {
+        const pseudoClass = pseudoClasses[index];
+        transformed = transformed.slice(0, pseudoClass.start) + transformed.slice(pseudoClass.end);
+    }
+    return transformed;
+}
+function specificityForBranch(rule, branch) {
+    // Single-branch selectors reuse the specificity collected from CSSOM; the
+    // matched branch is the whole selector. Multi-branch selectors need the
+    // matched branch's own weight, so recompute per branch.
+    return rule.selectorText.includes(",") ? computeSpecificity(branch) : rule.specificity;
+}
+const transformedRulesMemo = new WeakMap();
+function rulesForTransform(rules, transform) {
+    let byTransform = transformedRulesMemo.get(rules);
+    if (!byTransform) {
+        byTransform = new Map();
+        transformedRulesMemo.set(rules, byTransform);
+    }
+    const cached = byTransform.get(transform);
+    if (cached)
+        return cached;
+    let transformed;
+    if (transform === "live") {
+        transformed = rules.map((rule) => ({ rule, selectorText: rule.selectorText }));
+    }
+    else if (transform === "stable") {
+        transformed = rules
+            .filter((rule) => !hasSelectorPseudoClass(rule.selectorText, TRANSIENT_PSEUDO_CLASSES))
+            .map((rule) => ({ rule, selectorText: rule.selectorText }));
+    }
+    else {
+        transformed = rules.flatMap((rule) => {
+            const selectorText = selectorForState(rule.selectorText, transform);
+            return selectorText ? [{ rule, selectorText }] : [];
+        });
+    }
+    byTransform.set(transform, transformed);
+    return transformed;
+}
+const sourceSiteMatchBucketsMemo = new WeakMap();
+function sourceSiteMatchBuckets(rules, transform) {
+    let byTransform = sourceSiteMatchBucketsMemo.get(rules);
+    if (!byTransform) {
+        byTransform = new Map();
+        sourceSiteMatchBucketsMemo.set(rules, byTransform);
+    }
+    const cached = byTransform.get(transform);
+    if (cached)
+        return cached;
+    const cacheable = [];
+    const elementSensitive = [];
+    for (const entry of rulesForTransform(rules, transform)) {
+        (isElementSensitiveSelector(entry.selectorText) ? elementSensitive : cacheable).push(entry);
+    }
+    const buckets = { cacheable, elementSensitive };
+    byTransform.set(transform, buckets);
+    return buckets;
+}
+const SOURCE_SITE_CACHE_MAX = 4096;
+let sourceSiteMatchCaches = new WeakMap();
+let sourceSiteMatchCacheEntries = 0;
+const concreteElementMatchCaches = new WeakMap();
+// The all-rules sweep shares the active sweep's revision cache for stable
+// selectors. Element-sensitive selectors stay fresh because browser state can
+// change without a mutation observed by the registry.
+const allMatchesMemo = new WeakMap();
+/** Test-only cache reset. */
+export function resetSourceSiteMatchCache() {
+    sourceSiteMatchCaches = new WeakMap();
+    sourceSiteMatchCacheEntries = 0;
+}
+/** Test-only cache size. */
+export function sourceSiteMatchCacheSize() {
+    return sourceSiteMatchCacheEntries;
+}
+/**
+ * Captures selector-relevant state without serializing the whole document.
+ * Element and ancestor attributes cover the common source-site selectors while
+ * child/sibling-sensitive selectors are handled conservatively below.
+ */
+function sourceSiteContextKey(el) {
+    const lineage = [];
+    let current = el;
+    while (current) {
+        const attributes = Array.from(current.attributes)
+            .filter((attribute) => attribute.name !== "data-renderer-id")
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((attribute) => `${attribute.name}=${attribute.value}`)
+            .join("\u0002");
+        lineage.push(`${current.tagName}\u0003${attributes}`);
+        current = current.parentElement;
+    }
+    return lineage.join("\u0001");
+}
+/**
+ * Source-site identity key for the matched-rule cache. The element's class is
+ * part of the key because sibling instances of a source site can carry
+ * different classes (for example rows in a large list), which changes which
+ * rules match even though their `data-cid`/`data-src` are identical.
+ */
+function sourceSiteKey(el, transform) {
+    const cid = el.getAttribute("data-cid") ?? "";
+    const src = el.getAttribute("data-src") ?? "";
+    const instance = el.getAttribute("data-projection-instance") ?? "";
+    const className = typeof el.className === "string" ? el.className : "";
+    return `${cid}\u0000${src}\u0000${instance}\u0000${className}\u0000${transform}`;
+}
+export function matchRuleForElement(el, entry) {
+    const branch = matchingSelectorBranch(el, entry.selectorText);
+    if (!branch)
+        return null;
+    return {
+        rule: entry.rule,
+        selectorText: entry.selectorText,
+        branch,
+        specificity: specificityForBranch({ ...entry.rule, selectorText: entry.selectorText }, branch),
+    };
+}
+/**
+ * Captures the current match outcome for selectors whose truth can change
+ * without a document revision. This keeps the expensive resolved-row cache
+ * usable while invalidating it when states such as `checked` actually change.
+ */
+function elementSensitiveMatchKey(el, rules, transform, sensitiveMatchesByElement) {
+    const entries = sourceSiteMatchBuckets(rules, transform).elementSensitive;
+    if (entries.length === 0)
+        return "";
+    const matches = [];
+    let current = el;
+    let depth = 0;
+    while (current) {
+        const elementMatches = [];
+        for (const entry of entries) {
+            const match = matchRuleForElement(current, entry);
+            if (!match)
+                continue;
+            elementMatches.push(match);
+            matches.push(`${depth}:${entry.rule.sourceOrder ?? 0}:${match.branch}`);
+        }
+        sensitiveMatchesByElement?.set(current, elementMatches);
+        current = current.parentElement;
+        depth++;
+    }
+    return matches.join("\u0001");
+}
+function sensitiveMatchesForElement(el, buckets, matchesByElement) {
+    const cached = matchesByElement.get(el);
+    if (cached)
+        return cached;
+    const matched = buckets.elementSensitive.flatMap((entry) => {
+        const match = matchRuleForElement(el, entry);
+        return match ? [match] : [];
+    });
+    matchesByElement.set(el, matched);
+    return matched;
+}
+/**
+ * Matches transformed rules against one element. Stable source-site identities
+ * reuse revision-keyed matches; unstable identities and relationship-sensitive
+ * selectors are matched on each call.
+ */
+function getCachedElementMatches(el, rules, transform, sensitiveMatchesByElement = new Map()) {
+    const buckets = sourceSiteMatchBuckets(rules, transform);
+    const { cacheable, elementSensitive } = buckets;
+    const collect = (entries) => {
+        const matched = [];
+        for (const entry of entries) {
+            if (entry.rule.active === false)
+                continue;
+            const match = matchRuleForElement(el, entry);
+            if (match)
+                matched.push(match);
+        }
+        return matched;
+    };
+    const cid = el.getAttribute("data-cid");
+    const doc = el.ownerDocument ?? document;
+    const revisions = getDocumentRevisions(doc);
+    if (!cid || cacheable.length === 0) {
+        let cachedMatches = [];
+        if (cacheable.length > 0) {
+            let cache = concreteElementMatchCaches.get(el);
+            if (!cache) {
+                cache = new Map();
+                concreteElementMatchCaches.set(el, cache);
+            }
+            const cached = cache.get(transform);
+            if (cached
+                && cached.elementRevision === revisions.element
+                && cached.stylesheetRevision === revisions.stylesheet) {
+                cachedMatches = cached.matched;
+            }
+            else {
+                cachedMatches = collect(cacheable);
+                cache.set(transform, {
+                    elementRevision: revisions.element,
+                    stylesheetRevision: revisions.stylesheet,
+                    matched: cachedMatches,
+                });
+            }
+        }
+        const sensitiveMatches = elementSensitive.length > 0
+            ? sensitiveMatchesForElement(el, buckets, sensitiveMatchesByElement).filter((match) => match.rule.active !== false)
+            : [];
+        return sensitiveMatches.length === 0 ? cachedMatches : [...cachedMatches, ...sensitiveMatches];
+    }
+    const key = `${sourceSiteKey(el, transform)}\u0000${sourceSiteContextKey(el)}`;
+    let cache = sourceSiteMatchCaches.get(doc);
+    if (!cache) {
+        cache = new Map();
+        sourceSiteMatchCaches.set(doc, cache);
+    }
+    const cached = cache.get(key);
+    let cachedMatches;
+    if (cached
+        && cached.elementRevision === revisions.element
+        && cached.stylesheetRevision === revisions.stylesheet) {
+        cachedMatches = cached.matched;
+    }
+    else {
+        cachedMatches = collect(cacheable);
+        if (sourceSiteMatchCacheEntries >= SOURCE_SITE_CACHE_MAX) {
+            sourceSiteMatchCaches = new WeakMap();
+            sourceSiteMatchCacheEntries = 0;
+            cache = new Map();
+            sourceSiteMatchCaches.set(doc, cache);
+        }
+        if (!cache.has(key))
+            sourceSiteMatchCacheEntries++;
+        cache.set(key, {
+            elementRevision: revisions.element,
+            stylesheetRevision: revisions.stylesheet,
+            matched: cachedMatches,
+        });
+    }
+    // Browser state such as `checked` or `target` can change without a DOM or
+    // stylesheet revision, so element-sensitive matches must stay fresh.
+    const elementMatches = elementSensitive.length > 0
+        ? sensitiveMatchesForElement(el, buckets, sensitiveMatchesByElement).filter((match) => match.rule.active !== false)
+        : [];
+    return elementMatches.length === 0 ? cachedMatches : [...cachedMatches, ...elementMatches];
+}
+/**
+ * Matches selectors without applying conditional wrappers. The result retains
+ * inactive media alternatives for attribution, while transient selectors and
+ * the `live` transform retain their freshness requirements.
+ */
+function getAllElementMatches(el, rules, transform, sensitiveMatchesByElement = new Map()) {
+    const buckets = sourceSiteMatchBuckets(rules, transform);
+    if (transform === "live") {
+        const cacheableMatches = buckets.cacheable.flatMap((entry) => {
+            const match = matchRuleForElement(el, entry);
+            return match ? [match] : [];
+        });
+        return [...cacheableMatches, ...sensitiveMatchesForElement(el, buckets, sensitiveMatchesByElement)];
+    }
+    const { cacheable, elementSensitive } = buckets;
+    const collect = (entries) => entries.flatMap((entry) => {
+        const match = matchRuleForElement(el, entry);
+        return match ? [match] : [];
+    });
+    const doc = el.ownerDocument ?? document;
+    const revisions = getDocumentRevisions(doc);
+    let cachedMatches = [];
+    if (cacheable.length > 0) {
+        let byTransform = allMatchesMemo.get(el);
+        if (!byTransform) {
+            byTransform = new Map();
+            allMatchesMemo.set(el, byTransform);
+        }
+        const cached = byTransform.get(transform);
+        if (cached
+            && cached.elementRevision === revisions.element
+            && cached.stylesheetRevision === revisions.stylesheet) {
+            cachedMatches = cached.matched;
+        }
+        else {
+            cachedMatches = collect(cacheable);
+            byTransform.set(transform, {
+                elementRevision: revisions.element,
+                stylesheetRevision: revisions.stylesheet,
+                matched: cachedMatches,
+            });
+        }
+    }
+    const sensitiveMatches = elementSensitive.length > 0
+        ? sensitiveMatchesForElement(el, buckets, sensitiveMatchesByElement)
+        : [];
+    return sensitiveMatches.length === 0 ? cachedMatches : [...cachedMatches, ...sensitiveMatches];
+}
+// Branch splits repeat across sweeps, so memoize them for the finite selector
+// set in a stylesheet snapshot.
+const SELECTOR_SPLIT_CACHE_MAX = 8192;
+const selectorSplitMemo = new Map();
+// Branch matches are reusable for state-independent selectors. Transient
+// selectors stay uncached because their state is not represented by document
+// revisions.
+const ELEMENT_BRANCH_CACHE_MAX = 16384;
+const elementBranchMemo = new WeakMap();
+function isBranchMemoizable(selectorText) {
+    return !hasSelectorPseudoClass(selectorText, TRANSIENT_PSEUDO_CLASSES)
+        && !isElementSensitiveSelector(selectorText);
+}
+function matchingSelectorBranch(el, selectorText) {
+    const doc = el.ownerDocument ?? document;
+    const revisions = getDocumentRevisions(doc);
+    let bySelector = elementBranchMemo.get(el);
+    const memoizable = isBranchMemoizable(selectorText);
+    if (memoizable) {
+        if (!bySelector) {
+            bySelector = new Map();
+            elementBranchMemo.set(el, bySelector);
+        }
+        const cached = bySelector.get(selectorText);
+        if (cached
+            && cached.elementRevision === revisions.element
+            && cached.stylesheetRevision === revisions.stylesheet) {
+            return cached.branch;
+        }
+    }
+    let branches = selectorSplitMemo.get(selectorText);
+    if (!branches) {
+        branches = splitSelectorAtTopLevel(selectorText, ",");
+        if (selectorSplitMemo.size >= SELECTOR_SPLIT_CACHE_MAX)
+            selectorSplitMemo.clear();
+        selectorSplitMemo.set(selectorText, branches);
+    }
+    let branch = null;
+    for (const candidate of branches) {
+        const trimmedCandidate = candidate.trim();
+        if (!canMatchSelectorSubject(el, trimmedCandidate))
+            continue;
+        try {
+            if (el.matches(trimmedCandidate)) {
+                branch = trimmedCandidate;
+                break;
+            }
+        }
+        catch { /* invalid/unsupported selector */ }
+    }
+    if (memoizable) {
+        if (bySelector.size >= ELEMENT_BRANCH_CACHE_MAX)
+            bySelector.clear();
+        bySelector.set(selectorText, {
+            elementRevision: revisions.element,
+            stylesheetRevision: revisions.stylesheet,
+            branch,
+        });
+    }
+    return branch;
+}
+/** Creates a matcher for one CSSOM snapshot. */
+export function createRuleMatcher(rules, transform) {
+    const sensitiveMatches = new Map();
+    return {
+        dynamicMatchKey: (element) => elementSensitiveMatchKey(element, rules, transform, sensitiveMatches),
+        matchesForElement: (element) => ({
+            matched: getCachedElementMatches(element, rules, transform, sensitiveMatches),
+            allMatched: getAllElementMatches(element, rules, transform, sensitiveMatches),
+        }),
+    };
+}
+/**
+ * Interaction states whose pseudo-class appears in the snapshot. Skipping
+ * absent states avoids a full match sweep after each stylesheet revision.
+ */
+const statesWithPseudoInSnapshot = new WeakMap();
+function statesWithPseudoInSelectors(rules) {
+    let present = statesWithPseudoInSnapshot.get(rules);
+    if (!present) {
+        present = new Set();
+        for (const rule of rules) {
+            for (const state of INTERACTION_STATES) {
+                if (!present.has(state) && rule.selectorText.includes(`:${state}`)) {
+                    present.add(state);
+                }
+            }
+        }
+        statesWithPseudoInSnapshot.set(rules, present);
+    }
+    return present;
+}
+export function getAvailableInteractionStates(el) {
+    const doc = el.ownerDocument ?? document;
+    const { rules } = collectCssomRules(doc);
+    const present = statesWithPseudoInSelectors(rules);
+    const available = ["base"];
+    for (const state of INTERACTION_STATES) {
+        if (!present.has(state))
+            continue;
+        const matched = getCachedElementMatches(el, rules, state);
+        const relevant = matched.some((m) => m.rule.selectorText.includes(`:${state}`));
+        if (relevant)
+            available.push(state);
+    }
+    return available;
+}

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

@@ -1,6 +1,7 @@
-/** Number of unique selector strings actually computed (for tests). */
+export declare function splitSelectorAtTopLevel(selector: string, separator?: string): string[];
+/** Test-only specificity cache size. */
 export declare function specificityComputationCount(): number;
-/** Clears the specificity memo (for tests). */
+/** Test-only specificity cache reset. */
 export declare function resetSpecificityMemo(): void;
 /**
  * Computes the cascade weight for a selector without asking the DOM to match
@@ -8,5 +9,20 @@ export declare function resetSpecificityMemo(): void;
  * still recompute branch specificity (multi-branch selectors).
  */
 export declare function computeSpecificity(selectorText: string): number;
-/** The unmemoized implementation, exposed for equivalence tests. */
+/** Unmemoized implementation used by equivalence tests. */
 export declare function computeSpecificityCore(selectorText: string): number;
+export interface SelectorPseudoClass {
+    name: string;
+    start: number;
+    end: number;
+}
+export declare function selectorPseudoClasses(selector: string): readonly SelectorPseudoClass[];
+export declare function hasSelectorPseudoClass(selector: string, names: ReadonlySet<string>): boolean;
+export declare function isElementSensitiveSelector(selector: string): boolean;
+/**
+ * Rejects selectors whose rightmost compound requires a class the element
+ * does not have. This is a conservative prefilter: it only returns false for
+ * an impossible positive class requirement and leaves all other selectors to
+ * the browser's selector engine.
+ */
+export declare function canMatchSelectorSubject(el: Element, selector: string): boolean;