nudge-ui 0.2.0

package/dist/inspector/inspection/browserCssInspectionRegistry.js

@@ -0,0 +1,66 @@
+import { createBrowserCssInspection, } from "./browserCssInspection.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+const sessions = new WeakMap();
+let catalogReference = null;
+let catalogSignature = "";
+let catalogRevision = 0;
+function currentTokenKnowledge() {
+    const { tokenCatalog, tokenGeneration } = getNudgeUiRuntimeConfig();
+    // The inventory snapshot generation is the authoritative fingerprint: when
+    // observable inventory facts change, the virtual module re-evaluates and
+    // `tokenGeneration` carries a new value, so document sessions recreate with
+    // the new definitions instead of freezing the first catalog snapshot.
+    //
+    // A catalog signature supplements the inventory generation because S2-B
+    // still has temporary post-snapshot Tailwind/vanilla-extract enrichment.
+    // It advances only when those observable transport definitions change, not
+    // for a no-op virtual-module replacement.
+    if (catalogReference !== tokenCatalog) {
+        catalogReference = tokenCatalog;
+        const nextSignature = JSON.stringify(tokenCatalog);
+        if (nextSignature !== catalogSignature) {
+            catalogSignature = nextSignature;
+            catalogRevision++;
+        }
+    }
+    const generation = tokenGeneration === ""
+        ? catalogRevision
+        : catalogRevision === 0 ? tokenGeneration : `${tokenGeneration}:${catalogRevision}`;
+    return { definitions: tokenCatalog, generation };
+}
+/**
+ * Binds a document to token knowledge. When generation changes, the previous
+ * session is disposed and replaced so callers never keep a stale catalog.
+ */
+export function bindBrowserCssInspection(doc, knowledge) {
+    const existing = sessions.get(doc);
+    if (existing && existing.generation === knowledge.generation) {
+        return existing.session;
+    }
+    if (existing) {
+        existing.session.dispose();
+        sessions.delete(doc);
+    }
+    const session = createBrowserCssInspection({
+        document: doc,
+        tokenKnowledge: knowledge,
+    });
+    sessions.set(doc, { session, generation: knowledge.generation });
+    return session;
+}
+/** Returns the one browser inspection session owned by a document. */
+export function getBrowserCssInspection(doc = document) {
+    return bindBrowserCssInspection(doc, currentTokenKnowledge());
+}
+/** Invalidates every browser-inspection snapshot affected by a CSSOM write. */
+export function notifyBrowserStylesheetChange(doc = document) {
+    getBrowserCssInspection(doc).notifyStylesheetChange();
+}
+/** Releases a document session when its inspector/Canvas lifecycle ends. */
+export function disposeBrowserCssInspection(doc) {
+    const entry = sessions.get(doc);
+    if (!entry)
+        return;
+    entry.session.dispose();
+    sessions.delete(doc);
+}

package/dist/inspector/inspection/selectionProperty.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedProperty } from "../../css/model/index.js";
+export type SelectionValue = {
+    kind: "common";
+    value: string;
+} | {
+    kind: "mixed";
+};
+export type SelectionToken = {
+    kind: "none";
+} | {
+    kind: "common";
+    name: string;
+} | {
+    kind: "mixed";
+};
+/** One CSS property projected across every element in the current selection. */
+export interface SelectionProperty {
+    property: string;
+    value: SelectionValue;
+    token: SelectionToken;
+    primaryRow: ResolvedProperty | null;
+}
+/**
+ * Projects browser values and authored inspection rows into group-safe facts.
+ * The returned type cannot masquerade as an authored CSS row.
+ */
+export declare function projectSelectionProperty(property: string, rows: readonly (ResolvedProperty | null)[], values: readonly string[], primaryIndex: number): SelectionProperty | null;
+/** Returns the token entries available to every inspected target. */
+export declare function intersectTokenEntries<T extends {
+    name: string;
+    value: string;
+}>(entries: readonly (readonly T[])[]): T[];

package/dist/inspector/inspection/selectionProperty.js

@@ -0,0 +1,33 @@
+function tokenFor(rows) {
+    const names = rows.map((row) => row?.tokenName ?? null);
+    if (names.every((name) => name === null))
+        return { kind: "none" };
+    const first = names[0];
+    return first && names.every((name) => name === first)
+        ? { kind: "common", name: first }
+        : { kind: "mixed" };
+}
+/**
+ * Projects browser values and authored inspection rows into group-safe facts.
+ * The returned type cannot masquerade as an authored CSS row.
+ */
+export function projectSelectionProperty(property, rows, values, primaryIndex) {
+    if (values.length === 0 || rows.length !== values.length)
+        return null;
+    const normalizedValues = values.map((value) => value.trim());
+    const first = normalizedValues[0] ?? "";
+    const common = normalizedValues.every((value) => value === first);
+    return {
+        property,
+        value: common ? { kind: "common", value: first } : { kind: "mixed" },
+        token: tokenFor(rows),
+        primaryRow: rows[primaryIndex] ?? null,
+    };
+}
+/** Returns the token entries available to every inspected target. */
+export function intersectTokenEntries(entries) {
+    const first = entries[0];
+    if (!first)
+        return [];
+    return first.filter((entry) => entries.every((candidateEntries) => candidateEntries.some((candidate) => candidate.name === entry.name && candidate.value === entry.value)));
+}

package/dist/inspector/inspection/useBrowserCssInspection.d.ts

@@ -0,0 +1,20 @@
+import type { SelectedElement } from "../selection/selectionStore.js";
+import type { InteractionState } from "../shell/styleState.js";
+import type { ResolvedProperty } from "../../css/model/index.js";
+import type { BrowserCssInspection, DocumentTokenInspectionSnapshot, InspectionSnapshot } from "./browserCssInspection.js";
+export interface BrowserCssInspectionView {
+    element: InspectionSnapshot | null;
+    elements: readonly InspectionSnapshot[];
+    stableProperties: readonly ResolvedProperty[];
+    documentTokens: DocumentTokenInspectionSnapshot | null;
+}
+export interface BrowserCssInspectionViewOptions {
+    includeDocumentTokens?: boolean;
+    session?: BrowserCssInspection;
+}
+/**
+ * React Adapter for one revision-aware browser inspection view. This is the
+ * sole owner of subscription and scheduling policy; UI callers only project
+ * the returned snapshots.
+ */
+export declare function useBrowserCssInspection(selected: SelectedElement | readonly SelectedElement[] | null, state?: InteractionState, options?: BrowserCssInspectionViewOptions): BrowserCssInspectionView;

package/dist/inspector/inspection/useBrowserCssInspection.js

@@ -0,0 +1,159 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { getBrowserCssInspection } from "./browserCssInspectionRegistry.js";
+const SELECTION_DEBOUNCE_MS = 8;
+const EMPTY_SELECTION = [];
+function isSelectedElementList(selected) {
+    return Array.isArray(selected);
+}
+function normalizeSelection(selected) {
+    if (!selected)
+        return EMPTY_SELECTION;
+    if (isSelectedElementList(selected))
+        return selected;
+    return [selected];
+}
+function inspectAuthoredElements(session, selected, state) {
+    return selected.map((element) => session.inspect(element.domElement, { state, cascade: "authored" }));
+}
+function inspectStableView(session, selected, state, includeDocumentTokens, elements) {
+    const primary = elements[0] ?? null;
+    const stableProperties = selected[0] && state === "base"
+        ? session.inspect(selected[0].domElement, { cascade: "stable" }).properties
+        : [];
+    const documentTokens = includeDocumentTokens ? session.inspectTokens() : null;
+    return {
+        element: primary,
+        elements,
+        stableProperties,
+        documentTokens,
+    };
+}
+/**
+ * React Adapter for one revision-aware browser inspection view. This is the
+ * sole owner of subscription and scheduling policy; UI callers only project
+ * the returned snapshots.
+ */
+export function useBrowserCssInspection(selected, state = "base", options = {}) {
+    const selectedElements = useMemo(() => normalizeSelection(selected), [selected]);
+    const selectedDocument = selectedElements[0]?.domElement.ownerDocument ?? document;
+    const session = options.session ?? getBrowserCssInspection(selectedDocument);
+    const includeDocumentTokens = options.includeDocumentTokens ?? false;
+    const latest = useRef({ selected: selectedElements, state, session, includeDocumentTokens });
+    latest.current = { selected: selectedElements, state, session, includeDocumentTokens };
+    const [view, setView] = useState(() => inspectStableView(session, selectedElements, state, includeDocumentTokens, inspectAuthoredElements(session, selectedElements, state)));
+    const timerRef = useRef(null);
+    const lastSelectionResolveAtRef = useRef(0);
+    const revisionFrameRef = useRef(null);
+    const revisionSecondFrameRef = useRef(null);
+    const revisionThirdFrameRef = useRef(null);
+    const revisionWarmFrameRef = useRef(null);
+    const stableFrameRef = useRef(null);
+    const cancelScheduledInspection = () => {
+        if (timerRef.current !== null) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        if (revisionFrameRef.current !== null) {
+            cancelAnimationFrame(revisionFrameRef.current);
+            revisionFrameRef.current = null;
+        }
+        if (revisionSecondFrameRef.current !== null) {
+            cancelAnimationFrame(revisionSecondFrameRef.current);
+            revisionSecondFrameRef.current = null;
+        }
+        if (revisionThirdFrameRef.current !== null) {
+            cancelAnimationFrame(revisionThirdFrameRef.current);
+            revisionThirdFrameRef.current = null;
+        }
+        if (revisionWarmFrameRef.current !== null) {
+            cancelAnimationFrame(revisionWarmFrameRef.current);
+            revisionWarmFrameRef.current = null;
+        }
+        if (stableFrameRef.current !== null) {
+            cancelAnimationFrame(stableFrameRef.current);
+            stableFrameRef.current = null;
+        }
+    };
+    const resolveSync = () => {
+        const current = latest.current;
+        lastSelectionResolveAtRef.current = performance.now();
+        setView(inspectStableView(current.session, current.selected, current.state, current.includeDocumentTokens, inspectAuthoredElements(current.session, current.selected, current.state)));
+    };
+    const resolveSplit = () => {
+        const current = latest.current;
+        // Post-commit refresh: the authored cascade resolves in this task and the
+        // secondary stable cascade continues one frame later. Rapid successive
+        // edits therefore cancel the pending refresh (revision bumps reschedule)
+        // instead of finding a long blocking task already running, and the two
+        // resolution sweeps never block one task for their combined duration.
+        // The view still commits once, with the same data and ordering.
+        const elements = inspectAuthoredElements(current.session, current.selected, current.state);
+        stableFrameRef.current = requestAnimationFrame(() => {
+            stableFrameRef.current = null;
+            setView(inspectStableView(current.session, current.selected, current.state, current.includeDocumentTokens, elements));
+        });
+    };
+    const scheduleSelectionInspection = () => {
+        cancelScheduledInspection();
+        // Leading-edge resolve: a selection change resolves immediately instead
+        // of always waiting out the debounce. Rapid re-selections inside the
+        // trailing window still coalesce onto one trailing resolve, so the final
+        // view is identical and repeated selections cannot stack full sweeps.
+        const sinceLast = performance.now() - lastSelectionResolveAtRef.current;
+        if (sinceLast >= SELECTION_DEBOUNCE_MS) {
+            resolveSync();
+            return;
+        }
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            resolveSync();
+        }, SELECTION_DEBOUNCE_MS - sinceLast);
+    };
+    const scheduleRevisionInspection = () => {
+        cancelScheduledInspection();
+        // Let the host commit and paint before refreshing the inspector
+        // projection. The extra frames keep the refresh start past the gap
+        // between rapid successive edits, so a new revision cancels the pending
+        // refresh instead of colliding with a running one, and they give the
+        // stylesheet walk its own frame so no single refresh task blocks for the
+        // combined duration of the walk plus a cascade sweep.
+        revisionFrameRef.current = requestAnimationFrame(() => {
+            revisionFrameRef.current = null;
+            revisionSecondFrameRef.current = requestAnimationFrame(() => {
+                revisionSecondFrameRef.current = null;
+                revisionThirdFrameRef.current = requestAnimationFrame(() => {
+                    revisionThirdFrameRef.current = null;
+                    latest.current.session.prewarmRules?.();
+                    revisionWarmFrameRef.current = requestAnimationFrame(() => {
+                        revisionWarmFrameRef.current = null;
+                        resolveSplit();
+                    });
+                });
+            });
+        });
+    };
+    useEffect(() => {
+        scheduleSelectionInspection();
+        return cancelScheduledInspection;
+    }, [includeDocumentTokens, selectedElements, state, session]);
+    useEffect(() => session.subscribe(scheduleRevisionInspection), [session]);
+    // Warm the CSSOM rule snapshot during idle time so the first selection does
+    // not pay the stylesheet walk inside its own interaction. The idle timeout
+    // bounds the wait without competing with page-load paint; the walk is
+    // idempotent per stylesheet revision, so this is a no-op once warm.
+    const prewarmedSessionRef = useRef(null);
+    useEffect(() => {
+        if (prewarmedSessionRef.current === session)
+            return;
+        prewarmedSessionRef.current = session;
+        const ownerWindow = selectedDocument.defaultView;
+        const warm = () => session.prewarmRules?.();
+        if (ownerWindow && typeof ownerWindow.requestIdleCallback === "function") {
+            const idleId = ownerWindow.requestIdleCallback(() => warm(), { timeout: 2000 });
+            return () => ownerWindow.cancelIdleCallback(idleId);
+        }
+        const timeoutId = setTimeout(warm, 200);
+        return () => clearTimeout(timeoutId);
+    }, [session, selectedDocument]);
+    return view;
+}

package/dist/inspector/overlay/DropGuideOverlay.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import type { DropGuideRect } from "./dropGuide.js";
+export interface ViewportDropGuide {
+    orientation: "horizontal" | "vertical";
+    line: DropGuideRect;
+    target?: DropGuideRect;
+}
+interface DropGuideOverlayProps {
+    guide: ViewportDropGuide | null;
+    lineClassName: string;
+    lineTestId: string;
+    targetClassName?: string;
+    targetTestId?: string;
+}
+/** Shared visual wrapper; each view only supplies its projected viewport geometry. */
+export declare function DropGuideOverlay({ guide, lineClassName, lineTestId, targetClassName, targetTestId, }: DropGuideOverlayProps): ReactElement | null;
+export {};

package/dist/inspector/overlay/DropGuideOverlay.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+function fixedRect(rect) {
+    return {
+        position: "fixed",
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        pointerEvents: "none",
+    };
+}
+/** Shared visual wrapper; each view only supplies its projected viewport geometry. */
+export function DropGuideOverlay({ guide, lineClassName, lineTestId, targetClassName, targetTestId, }) {
+    if (!guide)
+        return null;
+    return (_jsxs(_Fragment, { children: [guide.target && targetClassName && targetTestId ? (_jsx("div", { className: targetClassName, "data-test": targetTestId, style: fixedRect(guide.target), "aria-hidden": "true" })) : null, _jsx("div", { className: lineClassName, "data-test": lineTestId, "data-orientation": guide.orientation, style: fixedRect(guide.line), "aria-hidden": "true" })] }));
+}

package/dist/inspector/overlay/InspectorOverlay.d.ts

@@ -0,0 +1,5 @@
+import type { ReactElement } from "react";
+export { getMarginFills, getMarginGuides, type MarginFill, type MarginGuide, type MarginGuideSide, } from "./overlayGeometry.js";
+export declare function InspectorOverlay({ host }: {
+    host: HTMLElement;
+}): ReactElement;