nudge-ui 0.2.0

package/dist/inspector/tokens/catalog.js

@@ -0,0 +1,184 @@
+import { getScopingSelectorPattern } from "../runtime/runtimeConfig.js";
+import { getElementComputedStyle, getElementWindow } from "../runtime/domRealm.js";
+import { selectTokens } from "../../css/value-semantics/index.js";
+import { cascadeLayerOrder } from "./resolution/cssomCollector.js";
+import { compareAuthorCascade } from "./resolution/cascade.js";
+import { computeSpecificityCore } from "./resolution/selectorSemantics.js";
+export { TOKEN_GROUP_LABELS, TOKEN_GROUP_ORDER } from "../../css/value-semantics/index.js";
+function defaultRuntime(root) {
+    const ownerWindow = getElementWindow(root);
+    const ownerDocument = root.ownerDocument;
+    const ownerCss = ownerWindow.CSS;
+    return {
+        root,
+        mediaMatches: (query) => typeof ownerWindow.matchMedia === "function" ? ownerWindow.matchMedia(query).matches : false,
+        supports: (condition) => typeof ownerCss?.supports === "function" ? ownerCss.supports(condition) : false,
+        computedToken: (name) => getElementComputedStyle(root).getPropertyValue(name).trim(),
+        selectorMatches: (selector) => selector
+            .split(",")
+            .map((part) => part.trim())
+            .filter(Boolean)
+            .some((part) => {
+            try {
+                return root.matches(part);
+            }
+            catch {
+                return false;
+            }
+        }),
+        scopeMatches: (scope) => {
+            const start = scope.match(/^\s*\((.+)\)/)?.[1]?.trim();
+            if (!start)
+                return true;
+            try {
+                return root.matches(start) || root.closest(start) !== null || ownerDocument.querySelector(start) !== null;
+            }
+            catch {
+                return false;
+            }
+        },
+        layerOrder: (name) => cascadeLayerOrder(ownerDocument, name),
+    };
+}
+export function isTokenContextActive(context, runtime) {
+    if (context.selector && !runtime.selectorMatches(context.selector))
+        return false;
+    return (context.wrappers ?? []).every((wrapper) => {
+        if (wrapper.kind === "media")
+            return runtime.mediaMatches(wrapper.params);
+        if (wrapper.kind === "supports")
+            return runtime.supports(wrapper.params);
+        if (wrapper.kind === "scope")
+            return runtime.scopeMatches(wrapper.params);
+        return true;
+    });
+}
+function pickWinningDeclaration(declarations, runtime) {
+    const priority = (declaration, index) => {
+        const layers = (declaration.context.wrappers ?? [])
+            .filter((wrapper) => wrapper.kind === "layer")
+            .map((wrapper) => wrapper.params.trim())
+            .filter(Boolean);
+        const layer = layers.length > 0 ? layers.join(".") : undefined;
+        return {
+            important: declaration.important,
+            layer,
+            layerOrder: layer ? runtime.layerOrder(layer) : undefined,
+            specificity: declaration.context.selector
+                ? computeSpecificityCore(declaration.context.selector)
+                : 0,
+            sourceOrder: declaration.order ?? index,
+        };
+    };
+    let winner = null;
+    let winnerIndex = -1;
+    declarations.forEach((candidate, candidateIndex) => {
+        if (!isTokenContextActive(candidate.context, runtime))
+            return;
+        if (!winner
+            || compareAuthorCascade(priority(candidate, candidateIndex), priority(winner, winnerIndex)) >= 0) {
+            winner = candidate;
+            winnerIndex = candidateIndex;
+        }
+    });
+    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.
+ */
+export function humanizeSelector(selector, scopingPattern) {
+    const stripped = scopingPattern === null ? selector : selector.replace(scopingPattern, "");
+    return stripped
+        .replace(/:where\(\s*\)/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function contextLabel(context) {
+    const labels = [];
+    if (context.selector && context.selector !== ":root") {
+        const selectorLabel = humanizeSelector(context.selector, getScopingSelectorPattern());
+        labels.push(selectorLabel === "" || selectorLabel === ":root" ? "Default" : selectorLabel);
+    }
+    else if (context.selector === ":root") {
+        labels.push("Default");
+    }
+    for (const wrapper of context.wrappers ?? []) {
+        labels.push(`@${wrapper.kind} ${wrapper.params}`);
+    }
+    return labels.join(" · ") || "Default";
+}
+export function sourceParts(source) {
+    const match = source.match(/^(.*):(\d+)$/);
+    return match ? { file: match[1], line: Number(match[2]) } : { file: source, line: 0 };
+}
+export function styleContext(context) {
+    const wrappers = context.wrappers?.map((wrapper) => ({ ...wrapper }));
+    return wrappers && wrappers.length > 0 ? { wrappers } : {};
+}
+export function selectorForContext(context) {
+    return context.selector?.trim() || ":root";
+}
+export function classifyCatalogToken(name, value = "") {
+    return selectTokens({ entries: [{ name, value, source: "" }] }).candidates[0]?.group ?? "generic";
+}
+export function buildTokenCatalogRows(catalog, root = document.documentElement, suppliedRuntime) {
+    const runtime = suppliedRuntime ?? defaultRuntime(root);
+    return catalog
+        .map((definition) => {
+        const activeDeclaration = pickWinningDeclaration(definition.declarations, runtime);
+        const source = activeDeclaration?.source ?? definition.declarations[0]?.source ?? "";
+        const parts = sourceParts(source);
+        const context = activeDeclaration?.context ?? {};
+        const authoredValue = activeDeclaration?.value ?? "";
+        return {
+            definition,
+            activeDeclaration,
+            authoredValue,
+            resolvedValue: activeDeclaration ? runtime.computedToken(definition.cssName) : "",
+            selector: selectorForContext(context),
+            styleContext: styleContext(context),
+            contextLabel: activeDeclaration ? contextLabel(context) : "Inactive in current theme",
+            file: parts.file,
+            line: parts.line,
+            group: classifyCatalogToken(definition.name || definition.cssName, authoredValue),
+        };
+    })
+        .sort((a, b) => a.definition.name.localeCompare(b.definition.name));
+}
+export function filterTokenRows(rows, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return [...rows];
+    return rows.filter((row) => row.definition.name.toLowerCase().includes(needle)
+        || row.definition.cssName.toLowerCase().includes(needle)
+        || row.definition.declarations.some((declaration) => declaration.value.toLowerCase().includes(needle)));
+}
+const EXACT_ALIAS = /^var\(\s*(--[\w-]+)\s*\)$/;
+export function aliasName(value) {
+    return value.trim().match(EXACT_ALIAS)?.[1] ?? null;
+}
+export function createsAliasCycle(tokenName, candidateName, authoredValues) {
+    const visited = new Set([tokenName]);
+    let current = candidateName;
+    while (current) {
+        if (visited.has(current))
+            return true;
+        visited.add(current);
+        current = aliasName(authoredValues.get(current) ?? "");
+    }
+    return false;
+}
+export function compatibleTokenNames(row, rows) {
+    const authored = new Map(rows.map((candidate) => [candidate.definition.cssName, candidate.authoredValue]));
+    return new Set(rows
+        .filter((candidate) => candidate.group === row.group)
+        .filter((candidate) => !createsAliasCycle(row.definition.cssName, candidate.definition.cssName, authored))
+        .map((candidate) => candidate.definition.cssName));
+}

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

@@ -0,0 +1,35 @@
+import type { TokenEntry } from "../../css/model/index.js";
+import type { ElementChangeRecord } from "../changes/changesLog.js";
+import { type EditTarget } from "../selection/editTarget.js";
+export type { ChangeRecord } from "../changes/changesLog.js";
+export { getPendingRules, getChangesList as getChangeRecords, clearWorkspace as resetPendingRules } from "../changes/changesLog.js";
+export interface StyleEditMetadata {
+    sourceProperty?: string;
+    sourceAuthoredValue?: string;
+}
+/** Returns whether a style write can address every element in the target safely. */
+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;
+export interface TokenSwap {
+    property: string;
+    newToken: TokenEntry;
+    oldToken: TokenEntry | null;
+    metadata?: StyleEditMetadata;
+}
+/** Applies several token swaps as one history batch. */
+export declare function swapTokens(target: EditTarget, changes: readonly TokenSwap[]): ElementChangeRecord[];
+export interface StyleDeclaration {
+    property: string;
+    value: string;
+    metadata?: StyleEditMetadata;
+}
+export interface ElementStyleEdit {
+    element: HTMLElement;
+    declarations: readonly StyleDeclaration[];
+}
+export declare function setStyle(target: EditTarget, property: string, value: string, metadata?: StyleEditMetadata): ElementChangeRecord | null;
+export declare function setStyles(target: EditTarget, declarations: readonly StyleDeclaration[], metadata?: StyleEditMetadata): ElementChangeRecord[];
+/** Applies element-specific declarations as one history batch. */
+export declare function setElementStyles(edits: readonly ElementStyleEdit[]): ElementChangeRecord[];
+export declare function promoteToToken(el: EditTarget, property: string, newToken: TokenEntry, metadata?: StyleEditMetadata): ElementChangeRecord | null;

package/dist/inspector/tokens/editActions.js

@@ -0,0 +1,164 @@
+import { parseDataSrc } from "../selection/resolveSelection.js";
+import { appendChanges, } from "../changes/changesLog.js";
+import { canPlanBatchEditScopes, planBatchEditScopes, selectorForElement, sourceSiteSelector } from "../selection/editScope.js";
+import { getActiveStyleState, selectorForInteractionState } from "../shell/styleState.js";
+import { getStateStyleValue } from "../shell/stateValue.js";
+import { boundRuntimeEvidence, isRuntimeCreatedElement, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, } from "../runtime/staticHtmlRuntimeIdentity.js";
+import { targetElements } from "../selection/editTarget.js";
+import { changeKey } from "../changes/model.js";
+function boundedRenderedText(el) {
+    return normalizeRuntimeText(el.textContent);
+}
+function sourceFields(el) {
+    const src = el.getAttribute("data-src") ?? "";
+    const parsed = parseDataSrc(src);
+    const evidence = (reason) => ({
+        reason,
+        tagName: normalizeRuntimeTag(el.tagName),
+        text: boundedRenderedText(el),
+        props: boundRuntimeEvidence(el.getAttribute("data-cprops")),
+        ariaLabel: boundRuntimeEvidence(el.getAttribute("aria-label")),
+    });
+    if (isRuntimeCreatedElement(el) || isRuntimeGeneratedSource(src)) {
+        return {
+            file: "",
+            line: 0,
+            column: 0,
+            runtimeEvidence: evidence("runtime-created"),
+        };
+    }
+    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`.
+        return {
+            file: "",
+            line: 0,
+            column: 0,
+            runtimeEvidence: evidence("unannotated"),
+        };
+    }
+    return {
+        file: parsed.file,
+        line: parsed.line,
+        column: parsed.column,
+    };
+}
+export { getPendingRules, getChangesList as getChangeRecords, clearWorkspace as resetPendingRules } from "../changes/changesLog.js";
+/** Returns whether a style write can address every element in the target safely. */
+export function canEditStyles(target) {
+    return canPlanBatchEditScopes(targetElements(target));
+}
+export function buildSelector(cid, src) {
+    return sourceSiteSelector(cid, src);
+}
+function stateFields(el) {
+    const state = getActiveStyleState();
+    const selector = selectorForElement(el);
+    return { state, selector: selector ? selectorForInteractionState(selector, state) : null };
+}
+export function swapToken(target, property, newToken, oldToken, metadata) {
+    return swapTokens(target, [{ property, newToken, oldToken, metadata }])[0] ?? null;
+}
+/** Applies several token swaps as one history batch. */
+export function swapTokens(target, changes) {
+    const elements = targetElements(target);
+    const scopePlan = planBatchEditScopes(elements);
+    if (!scopePlan)
+        return [];
+    const records = [];
+    const verificationTargets = new Map();
+    for (const el of elements) {
+        for (const change of changes) {
+            const cid = el.getAttribute("data-cid") ?? "";
+            const { selector, state } = stateFields(el);
+            if (!selector)
+                continue;
+            const source = sourceFields(el);
+            const record = {
+                cid,
+                file: source.file,
+                line: source.line,
+                column: source.column,
+                selector,
+                property: change.property,
+                ...change.metadata,
+                oldToken: change.oldToken,
+                newToken: change.newToken,
+                source: { file: source.file, line: source.line, component: cid },
+                runtimeEvidence: source.runtimeEvidence,
+                state,
+                ...scopePlan.get(el),
+            };
+            records.push(record);
+            verificationTargets.set(changeKey(record), el);
+        }
+    }
+    appendChanges(records, { verificationTargets });
+    return records;
+}
+function commitElementStyles(edits) {
+    if (edits.every(({ declarations }) => declarations.length === 0))
+        return [];
+    const elements = [...new Set(edits.map(({ element }) => element))];
+    const scopePlan = planBatchEditScopes(elements);
+    if (!scopePlan)
+        return [];
+    const records = [];
+    for (const { element, declarations } of edits) {
+        for (const declaration of declarations) {
+            const record = buildStyleRecord(element, scopePlan, declaration);
+            if (record)
+                records.push({ record, element });
+        }
+    }
+    const verificationTargets = new Map();
+    for (const { record, element } of records)
+        verificationTargets.set(changeKey(record), element);
+    appendChanges(records.map(({ record }) => record), { verificationTargets });
+    return records.map(({ record }) => record);
+}
+export function setStyle(target, property, value, metadata) {
+    return setStyles(target, [{ property, value, metadata }])[0] ?? null;
+}
+export function setStyles(target, declarations, metadata) {
+    const normalizedDeclarations = declarations.map((declaration) => ({
+        ...declaration,
+        metadata: declaration.metadata ?? metadata,
+    }));
+    return commitElementStyles(targetElements(target).map((element) => ({
+        element,
+        declarations: normalizedDeclarations,
+    })));
+}
+/** Applies element-specific declarations as one history batch. */
+export function setElementStyles(edits) {
+    return commitElementStyles(edits);
+}
+function buildStyleRecord(el, scopePlan, { property, value, metadata }) {
+    const cid = el.getAttribute("data-cid") ?? "";
+    const { selector, state } = stateFields(el);
+    if (!selector)
+        return null;
+    const source = sourceFields(el);
+    return {
+        cid,
+        file: source.file,
+        line: source.line,
+        column: source.column,
+        selector,
+        property,
+        ...metadata,
+        oldToken: null,
+        newToken: null,
+        rawValue: value,
+        oldRawValue: getStateStyleValue(el, property) || undefined,
+        source: { file: source.file, line: source.line, component: cid },
+        runtimeEvidence: source.runtimeEvidence,
+        state,
+        ...scopePlan.get(el),
+    };
+}
+export function promoteToToken(el, property, newToken, metadata) {
+    return swapToken(el, property, newToken, null, metadata);
+}

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

@@ -0,0 +1,14 @@
+export interface AuthorCascadePriority {
+    important?: boolean;
+    inline?: boolean;
+    layer?: string;
+    layerOrder?: number;
+    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.
+ */
+export declare function compareAuthorCascade(a: AuthorCascadePriority, b: AuthorCascadePriority): number;

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export function compareAuthorCascade(a, b) {
+    const aImportant = Boolean(a.important);
+    const bImportant = Boolean(b.important);
+    if (aImportant !== bImportant)
+        return aImportant ? 1 : -1;
+    const aInline = Boolean(a.inline);
+    const bInline = Boolean(b.inline);
+    if (aInline !== bInline)
+        return aInline ? 1 : -1;
+    const aLayered = a.layer !== undefined;
+    const bLayered = b.layer !== undefined;
+    if (aLayered !== bLayered) {
+        if (aImportant)
+            return aLayered ? 1 : -1;
+        return aLayered ? -1 : 1;
+    }
+    if (aLayered && bLayered && a.layer !== b.layer) {
+        const aOrder = a.layerOrder ?? a.sourceOrder;
+        const bOrder = b.layerOrder ?? b.sourceOrder;
+        if (aOrder !== bOrder)
+            return aImportant ? bOrder - aOrder : aOrder - bOrder;
+    }
+    if (a.specificity !== b.specificity)
+        return a.specificity - b.specificity;
+    return a.sourceOrder - b.sourceOrder;
+}

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

@@ -0,0 +1,43 @@
+import type { MatchedRule, StyleDeclaration } from "../../../css/model/index.js";
+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.
+ */
+export declare function registerResolutionElement(el: Element): void;
+/** Releases the observer, listener, and cached state owned by one document. */
+export declare function disposeDocumentResolution(doc: Document): void;
+/** Keeps one document's CSSOM observer alive for a browser inspection owner. */
+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.
+ */
+export declare function declarationsFromCssom(style: CSSStyleDeclaration): StyleDeclaration[];
+export declare function collectRules(doc: Document): {
+    revision: number;
+    rules: MatchedRule[];
+    layerOrder: Map<string, number>;
+    inaccessible: boolean;
+} | {
+    rules: MatchedRule[];
+    layerOrder: ReadonlyMap<string, number>;
+    inaccessible: boolean;
+};
+export declare function cascadeLayerOrder(doc: Document, name: string): number | undefined;