nudge-ui 0.2.0

package/dist/inspector/changes/codecs.js

@@ -0,0 +1,389 @@
+import { isRenderedInstanceOverride, isStyleRuleContextValue, isTextContentChangeValue, } from "./editModel.js";
+import { isComponentChange, isTokenChange, } from "./types.js";
+export function isSerializableChange(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind === "token")
+        return isSerializableTokenChangeValue(value);
+    if (value.kind === "component-prop")
+        return isSerializableComponentChangeValue(value);
+    if (value.kind === "text-content")
+        return isTextContentChangeValue(value);
+    return isSerializableElementChangeValue(value);
+}
+export function isSerializableElementChangeValue(value) {
+    if (!isRecord(value)
+        || !hasOnlyKeys(value, [
+            "kind", "cid", "file", "line", "column", "selector", "property",
+            "sourceProperty", "sourceAuthoredValue", "oldToken", "newToken", "rawValue",
+            "oldRawValue", "source", "runtimeEvidence", "scope", "instanceOverride", "state",
+        ])
+        || (value.kind !== undefined && value.kind !== "element")
+        || typeof value.cid !== "string"
+        || typeof value.file !== "string"
+        || !isFiniteNumber(value.line)
+        || (value.column !== undefined && !isNonNegativeSafeInteger(value.column))
+        || typeof value.selector !== "string"
+        || typeof value.property !== "string"
+        || !isSourceValue(value.source)
+        || !isTokenRefValue(value.oldToken)
+        || !isTokenRefValue(value.newToken)
+        || (value.sourceProperty !== undefined && typeof value.sourceProperty !== "string")
+        || (value.sourceAuthoredValue !== undefined && typeof value.sourceAuthoredValue !== "string")
+        || (value.rawValue !== undefined && typeof value.rawValue !== "string")
+        || (value.oldRawValue !== undefined && typeof value.oldRawValue !== "string")
+        || (value.runtimeEvidence !== undefined && !isRuntimeElementEvidenceValue(value.runtimeEvidence))
+        || !isEditScopeValue(value.scope)
+        || (value.instanceOverride !== undefined && value.scope !== "rendered-instance")
+        || (value.scope === "rendered-instance" && !isRenderedInstanceOverride(value.instanceOverride))
+        || (value.state !== undefined && !isElementStateValue(value.state))) {
+        return false;
+    }
+    return true;
+}
+export function isSerializableTokenChangeValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, [
+            "kind", "tokenName", "file", "line", "selector", "property", "rawValue",
+            "oldRawValue", "important", "context", "contextLabel", "source",
+        ])
+        && value.kind === "token"
+        && typeof value.tokenName === "string"
+        && typeof value.file === "string"
+        && isFiniteNumber(value.line)
+        && typeof value.selector === "string"
+        && typeof value.property === "string"
+        && typeof value.rawValue === "string"
+        && typeof value.oldRawValue === "string"
+        && (value.important === undefined || typeof value.important === "boolean")
+        && isStyleRuleContextValue(value.context)
+        && typeof value.contextLabel === "string"
+        && isSourceValue(value.source);
+}
+export function isSerializableComponentChangeValue(value) {
+    if (!isRecord(value)
+        || !hasOnlyKeys(value, ["kind", "target", "property", "before", "after", "authoredAs", "scope", "evidence"])
+        || value.kind !== "component-prop"
+        || !isComponentTargetValue(value.target)
+        || typeof value.property !== "string"
+        || !isComponentBaselineValue(value.before)
+        || !isComponentPropValue(value.after)
+        || !isAuthoredPropKindValue(value.authoredAs)
+        || !isEditScopeValue(value.scope)
+        || (value.evidence !== undefined && !isComponentInvocationEvidenceValue(value.evidence))) {
+        return false;
+    }
+    const evidence = value.evidence;
+    return !isUnsafeRepeatedSourceOverride(value.authoredAs, value.scope, evidence);
+}
+export function serializeChange(change) {
+    if (isTokenChange(change)) {
+        const serialized = serializeTokenChange(change);
+        return isSerializableTokenChangeValue(serialized) ? serialized : null;
+    }
+    if (isComponentChange(change)) {
+        if (isRepeatedUnsafeSourceOverride(change))
+            return null;
+        const serialized = serializeComponentChange(change);
+        return isSerializableComponentChangeValue(serialized) ? serialized : null;
+    }
+    if (change.kind === "text-content") {
+        const serialized = serializeTextContentChange(change);
+        return isTextContentChangeValue(serialized) ? serialized : null;
+    }
+    const serialized = serializeElementChange(change);
+    return serialized && isSerializableElementChangeValue(serialized) ? serialized : null;
+}
+export function serializeElementChange(change) {
+    if (change.instanceOverride !== undefined && change.scope !== "rendered-instance")
+        return null;
+    if (change.scope === "rendered-instance" && !isRenderedInstanceOverride(change.instanceOverride))
+        return null;
+    return {
+        kind: change.kind,
+        cid: change.cid,
+        file: change.file,
+        line: change.line,
+        column: change.column,
+        selector: change.selector,
+        property: change.property,
+        sourceProperty: change.sourceProperty,
+        sourceAuthoredValue: change.sourceAuthoredValue,
+        oldToken: serializeTokenRef(change.oldToken),
+        newToken: serializeTokenRef(change.newToken),
+        rawValue: change.rawValue,
+        oldRawValue: change.oldRawValue,
+        source: change.source,
+        runtimeEvidence: change.runtimeEvidence ? { ...change.runtimeEvidence } : undefined,
+        scope: change.scope === "rendered-instance" ? "rendered-instance" : "source-site",
+        instanceOverride: change.scope === "rendered-instance" ? change.instanceOverride : undefined,
+        state: change.state,
+    };
+}
+export function serializeTokenChange(change) {
+    const wrappers = change.context?.wrappers;
+    return {
+        kind: "token",
+        tokenName: change.tokenName,
+        file: change.file,
+        line: change.line,
+        selector: change.selector,
+        property: change.property,
+        rawValue: change.rawValue,
+        oldRawValue: change.oldRawValue,
+        important: change.important,
+        context: wrappers ? { wrappers: wrappers.map((wrapper) => ({ ...wrapper })) } : {},
+        contextLabel: change.contextLabel ?? "",
+        source: change.source,
+    };
+}
+export function serializeComponentChange(change) {
+    return {
+        kind: "component-prop",
+        target: { ...change.target },
+        property: change.property,
+        before: change.before.kind === "default"
+            ? { kind: "default" }
+            : { kind: "value", value: change.before.value },
+        after: change.after,
+        authoredAs: change.authoredAs,
+        scope: change.scope,
+        evidence: change.evidence ? { ...change.evidence } : undefined,
+    };
+}
+export function serializeTextContentChange(change) {
+    return {
+        kind: "text-content",
+        id: change.id,
+        target: {
+            sourceSite: { ...change.target.sourceSite },
+            occurrence: change.target.occurrence,
+            props: change.target.props,
+            ariaLabel: change.target.ariaLabel,
+            beforeText: change.target.beforeText,
+            ...(change.target.textNodePath?.length
+                ? { textNodePath: [...change.target.textNodePath] }
+                : {}),
+        },
+        source: { ...change.source },
+        selector: change.selector,
+        before: change.before,
+        after: change.after,
+        authoredAs: change.authoredAs,
+        scope: change.scope,
+        evidence: change.evidence ? { ...change.evidence } : undefined,
+    };
+}
+export function deserializeChange(serialized) {
+    if (serialized.kind === "token")
+        return deserializeTokenChange(serialized);
+    if (serialized.kind === "component-prop")
+        return deserializeComponentChange(serialized);
+    if (serialized.kind === "text-content")
+        return deserializeTextContentChange(serialized);
+    return deserializeElementChange(serialized);
+}
+export function deserializeElementChange(serialized) {
+    return {
+        kind: serialized.kind,
+        cid: serialized.cid,
+        file: serialized.file,
+        line: serialized.line,
+        column: serialized.column,
+        selector: serialized.selector,
+        property: serialized.property,
+        sourceProperty: serialized.sourceProperty,
+        sourceAuthoredValue: serialized.sourceAuthoredValue,
+        oldToken: deserializeTokenRef(serialized.oldToken),
+        newToken: deserializeTokenRef(serialized.newToken),
+        rawValue: serialized.rawValue,
+        oldRawValue: serialized.oldRawValue,
+        source: serialized.source,
+        runtimeEvidence: serialized.runtimeEvidence ? { ...serialized.runtimeEvidence } : undefined,
+        scope: serialized.scope ?? "source-site",
+        instanceOverride: serialized.scope === "rendered-instance" ? serialized.instanceOverride : undefined,
+        state: serialized.state,
+    };
+}
+export function deserializeTokenChange(serialized) {
+    return {
+        kind: "token",
+        tokenName: serialized.tokenName,
+        file: serialized.file,
+        line: serialized.line,
+        selector: serialized.selector,
+        property: serialized.property,
+        rawValue: serialized.rawValue,
+        oldRawValue: serialized.oldRawValue,
+        important: serialized.important ?? false,
+        context: serialized.context ?? {},
+        contextLabel: serialized.contextLabel ?? "",
+        source: serialized.source,
+    };
+}
+export function deserializeComponentChange(serialized) {
+    return {
+        kind: "component-prop",
+        target: { ...serialized.target },
+        property: serialized.property,
+        before: serialized.before.kind === "default"
+            ? { kind: "default" }
+            : { kind: "value", value: serialized.before.value },
+        after: serialized.after,
+        authoredAs: serialized.authoredAs,
+        scope: serialized.scope,
+        evidence: serialized.evidence ? { ...serialized.evidence } : undefined,
+    };
+}
+export function deserializeTextContentChange(serialized) {
+    return {
+        kind: "text-content",
+        id: serialized.id,
+        target: {
+            sourceSite: { ...serialized.target.sourceSite },
+            occurrence: serialized.target.occurrence,
+            props: serialized.target.props,
+            ariaLabel: serialized.target.ariaLabel,
+            beforeText: serialized.target.beforeText,
+            ...(serialized.target.textNodePath?.length
+                ? { textNodePath: [...serialized.target.textNodePath] }
+                : {}),
+        },
+        source: { ...serialized.source },
+        selector: serialized.selector,
+        before: serialized.before,
+        after: serialized.after,
+        authoredAs: serialized.authoredAs,
+        scope: serialized.scope,
+        evidence: serialized.evidence ? { ...serialized.evidence } : undefined,
+    };
+}
+function serializeTokenRef(token) {
+    if (!token)
+        return null;
+    return {
+        name: token.name,
+        value: token.value ?? "",
+        source: token.source ?? "",
+        cssValue: token.cssValue,
+        cssName: token.cssName,
+        adapter: token.adapter,
+        origin: token.origin,
+    };
+}
+function deserializeTokenRef(serialized) {
+    if (!serialized)
+        return null;
+    return {
+        name: serialized.name,
+        value: serialized.value,
+        source: serialized.source,
+        cssValue: serialized.cssValue,
+        cssName: serialized.cssName,
+        adapter: serialized.adapter,
+        origin: serialized.origin,
+    };
+}
+function isUnsafeRepeatedSourceOverride(authoredAs, scope, evidence) {
+    return isComponentInvocationEvidenceValue(evidence)
+        && evidence.mountedCount > 1
+        && (authoredAs === "expression" || authoredAs === "spread")
+        && scope !== "rendered-instance";
+}
+function isRepeatedUnsafeSourceOverride(change) {
+    return isUnsafeRepeatedSourceOverride(change.authoredAs, change.scope, change.evidence);
+}
+function isComponentTargetValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["framework", "componentId", "callsiteId", "componentName", "file", "line", "column"])
+        && value.framework === "react"
+        && typeof value.componentId === "string"
+        && typeof value.callsiteId === "string"
+        && typeof value.componentName === "string"
+        && typeof value.file === "string"
+        && isFiniteNumber(value.line)
+        && isFiniteNumber(value.column);
+}
+function isComponentBaselineValue(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind === "default")
+        return hasOnlyKeys(value, ["kind"]);
+    return hasOnlyKeys(value, ["kind", "value"])
+        && value.kind === "value"
+        && isComponentPropValue(value.value);
+}
+function isComponentInvocationEvidenceValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["occurrence", "props", "ariaLabel", "beforeText", "mountedCount"])
+        && isNonNegativeSafeInteger(value.occurrence)
+        && (typeof value.props === "string" || value.props === null)
+        && (typeof value.ariaLabel === "string" || value.ariaLabel === null)
+        && typeof value.beforeText === "string"
+        && isNonNegativeSafeInteger(value.mountedCount);
+}
+function isRuntimeElementEvidenceValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["reason", "tagName", "text", "props", "ariaLabel"])
+        && (value.reason === undefined || value.reason === "runtime-created" || value.reason === "unannotated")
+        && typeof value.tagName === "string"
+        && (typeof value.text === "string" || value.text === null)
+        && (typeof value.props === "string" || value.props === null)
+        && (typeof value.ariaLabel === "string" || value.ariaLabel === null);
+}
+function isTokenRefValue(value) {
+    if (value === null)
+        return true;
+    return isRecord(value)
+        && hasOnlyKeys(value, ["name", "value", "source", "cssValue", "cssName", "adapter", "origin"])
+        && typeof value.name === "string"
+        && typeof value.value === "string"
+        && typeof value.source === "string"
+        && (value.cssValue === undefined || typeof value.cssValue === "string")
+        && (value.cssName === undefined || typeof value.cssName === "string")
+        && (value.adapter === undefined || typeof value.adapter === "string")
+        && (value.origin === undefined
+            || value.origin === "project"
+            || value.origin === "package"
+            || value.origin === "framework"
+            || value.origin === "generated"
+            || value.origin === "runtime");
+}
+function isSourceValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["file", "line", "component"])
+        && typeof value.file === "string"
+        && isFiniteNumber(value.line)
+        && typeof value.component === "string";
+}
+function isEditScopeValue(value) {
+    return value === undefined || value === "source-site" || value === "rendered-instance";
+}
+function isComponentPropValue(value) {
+    return typeof value === "string"
+        || (typeof value === "number" && Number.isFinite(value))
+        || typeof value === "boolean";
+}
+function isAuthoredPropKindValue(value) {
+    return value === "literal" || value === "expression" || value === "spread" || value === "default";
+}
+function isElementStateValue(value) {
+    return value === "base"
+        || value === "hover"
+        || value === "active"
+        || value === "focus"
+        || value === "focus-visible"
+        || value === "disabled";
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}

package/dist/inspector/changes/editModel.d.ts

@@ -0,0 +1,74 @@
+import type { TokenContextWrapper } from "../../css/model/index.js";
+export type EditScope = "source-site" | "rendered-instance";
+/** A JSX instrumentation site. This is stable across documents. */
+export interface SourceSiteRef {
+    cid: string;
+    src: string;
+}
+/**
+ * Serializable identity for one rendered output. It deliberately contains no
+ * DOM reference or generated node id: each document resolves it independently.
+ */
+export interface RenderedInstanceRef {
+    sourceSite: SourceSiteRef;
+    locator: {
+        kind: "evidence";
+        occurrence: number;
+        props: string | null;
+        text: string | null;
+        /** An accessible name can distinguish icon-only repeated controls. */
+        ariaLabel?: string | null;
+    };
+}
+export interface RenderedInstanceOverride {
+    id: string;
+    target: RenderedInstanceRef;
+}
+/** The browser-independent CSS context retained on a token change. */
+export interface StyleRuleContext {
+    wrappers?: TokenContextWrapper[];
+}
+export declare function isRenderedInstanceRef(value: unknown): value is RenderedInstanceRef;
+export declare function isRenderedInstanceOverride(value: unknown): value is RenderedInstanceOverride;
+/** Validates the serializable context carried by a token change. */
+export declare function isStyleRuleContextValue(value: unknown): value is StyleRuleContext;
+/** A source site shared by text and rendered-instance evidence. */
+export type TextProjectionSourceSite = SourceSiteRef;
+export interface TextProjectionTarget {
+    sourceSite: TextProjectionSourceSite;
+    occurrence: number;
+    props: string | null;
+    ariaLabel: string | null;
+    beforeText: string;
+    /** Document-local evidence for a text node inside safe mixed markup. */
+    textNodePath?: readonly number[];
+}
+export type TextProjectionScope = EditScope;
+/** Bounded semantic evidence retained alongside an instance text projection. */
+export interface TextBindingEvidence {
+    callsiteId: string;
+    componentName: string;
+    property: string;
+    mountedCount: number;
+}
+export interface TextContentChangeRecord {
+    kind: "text-content";
+    property?: undefined;
+    id: string;
+    target: TextProjectionTarget;
+    source: {
+        file: string;
+        line: number;
+        column: number;
+        component: string;
+    };
+    selector: string;
+    before: string;
+    after: string;
+    authoredAs: "literal" | "expression" | "unknown";
+    scope?: TextProjectionScope;
+    evidence?: TextBindingEvidence;
+}
+export declare function isTextProjectionTargetValue(value: unknown): value is TextProjectionTarget;
+export declare function isTextContentChangeValue(value: unknown): value is TextContentChangeRecord;
+export declare function isTextContentChangeListValue(value: unknown): value is TextContentChangeRecord[];

package/dist/inspector/changes/editModel.js

@@ -0,0 +1,120 @@
+export function isRenderedInstanceRef(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["sourceSite", "locator"]))
+        return false;
+    const source = value.sourceSite;
+    const locator = value.locator;
+    if (!isRecord(source)
+        || !hasOnlyKeys(source, ["cid", "src"])
+        || typeof source.cid !== "string"
+        || typeof source.src !== "string"
+        || !isRecord(locator)
+        || !hasOnlyKeys(locator, ["kind", "occurrence", "props", "text", "ariaLabel"]))
+        return false;
+    return locator.kind === "evidence"
+        && Number.isSafeInteger(locator.occurrence) && locator.occurrence >= 0
+        && (typeof locator.props === "string" || locator.props === null)
+        && (typeof locator.text === "string" || locator.text === null)
+        && (locator.ariaLabel === undefined || typeof locator.ariaLabel === "string" || locator.ariaLabel === null);
+}
+export function isRenderedInstanceOverride(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["id", "target"])
+        && typeof value.id === "string"
+        && isRenderedInstanceRef(value.target);
+}
+/** Validates the serializable context carried by a token change. */
+export function isStyleRuleContextValue(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["wrappers"]))
+        return false;
+    const wrappers = value.wrappers;
+    return wrappers === undefined || (Array.isArray(wrappers) && wrappers.every((wrapper) => {
+        if (!isRecord(wrapper) || !hasOnlyKeys(wrapper, ["kind", "params"]))
+            return false;
+        return (wrapper.kind === "media"
+            || wrapper.kind === "supports"
+            || wrapper.kind === "scope"
+            || wrapper.kind === "layer")
+            && typeof wrapper.params === "string";
+    }));
+}
+export function isTextProjectionTargetValue(value) {
+    if (!isRecord(value)
+        || !hasOnlyKeys(value, ["sourceSite", "occurrence", "props", "ariaLabel", "beforeText", "textNodePath"])) {
+        return false;
+    }
+    const occurrence = value.occurrence;
+    const props = value.props;
+    const ariaLabel = value.ariaLabel;
+    const beforeText = value.beforeText;
+    const textNodePath = value.textNodePath;
+    if (!isNonNegativeSafeInteger(occurrence)
+        || (typeof props !== "string" && props !== null)
+        || (typeof ariaLabel !== "string" && ariaLabel !== null)
+        || typeof beforeText !== "string"
+        || (textNodePath !== undefined
+            && (!Array.isArray(textNodePath)
+                || textNodePath.length === 0
+                || !textNodePath.every(isNonNegativeSafeInteger)))) {
+        return false;
+    }
+    const source = value.sourceSite;
+    return isRecord(source)
+        && hasOnlyKeys(source, ["cid", "src"])
+        && typeof source.cid === "string"
+        && source.cid.length > 0
+        && typeof source.src === "string"
+        && source.src.length > 0;
+}
+export function isTextContentChangeValue(value) {
+    if (!isRecord(value)
+        || !hasOnlyKeys(value, ["kind", "id", "target", "source", "selector", "before", "after", "authoredAs", "scope", "evidence"])) {
+        return false;
+    }
+    if (value.kind !== "text-content"
+        || typeof value.id !== "string" || value.id.length === 0
+        || typeof value.selector !== "string" || value.selector.length === 0
+        || typeof value.before !== "string"
+        || typeof value.after !== "string"
+        || (value.authoredAs !== "literal" && value.authoredAs !== "expression" && value.authoredAs !== "unknown")) {
+        return false;
+    }
+    const source = value.source;
+    if (!isRecord(source)
+        || !hasOnlyKeys(source, ["file", "line", "column", "component"])
+        || typeof source.file !== "string" || source.file.length === 0
+        || !isNonNegativeSafeInteger(source.line)
+        || !isNonNegativeSafeInteger(source.column)
+        || typeof source.component !== "string" || source.component.length === 0) {
+        return false;
+    }
+    if (value.scope !== undefined
+        && value.scope !== "source-site"
+        && value.scope !== "rendered-instance")
+        return false;
+    if (value.evidence !== undefined) {
+        const evidence = value.evidence;
+        if (!isRecord(evidence)
+            || !hasOnlyKeys(evidence, ["callsiteId", "componentName", "property", "mountedCount"])
+            || typeof evidence.callsiteId !== "string" || evidence.callsiteId.length === 0
+            || typeof evidence.componentName !== "string" || evidence.componentName.length === 0
+            || typeof evidence.property !== "string" || evidence.property.length === 0
+            || !isNonNegativeSafeInteger(evidence.mountedCount))
+            return false;
+    }
+    return isTextProjectionTargetValue(value.target)
+        && value.target.beforeText === value.before;
+}
+export function isTextContentChangeListValue(value) {
+    if (!Array.isArray(value) || !value.every(isTextContentChangeValue))
+        return false;
+    return new Set(value.map((change) => change.id)).size === value.length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}

package/dist/inspector/changes/managedStyleProjection.d.ts

@@ -0,0 +1,6 @@
+import type { PreviewResult, StyleRule } from "../projection/managedStylesheet.js";
+import { type ChangeRecord, type PreviewableChangeRecord } from "./types.js";
+/** The source selector stays canonical; the projection marker is document-local. */
+export declare function selectorForManagedChange(change: PreviewableChangeRecord): string | null;
+export declare function buildManagedStyleRules(changes: ChangeRecord[]): StyleRule[];
+export declare function verifyManagedStyleProjection(change: PreviewableChangeRecord, selectedElement?: HTMLElement | null): PreviewResult | null;