nudge-ui 0.2.0

package/dist/css/token-inventory/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Token inventory contracts: artifact input, normalized styling contributions,
+ * diagnostics, and immutable snapshots.
+ *
+ * This Node/build-time seam is intentionally absent from the browser-safe
+ * `nudge-ui/css` export graph.
+ */
+import type { TokenCatalogDiagnosticCode, TokenDefinition, TokenDeclaration, TokenEntry, TokenOrigin } from "../model/index.js";
+export type ArtifactStage = "authored" | "transformed";
+export type ArtifactProvenance = TokenOrigin;
+/** One authored or transformed observation supplied by a build-tool Adapter. */
+export interface StylesheetArtifact {
+    readonly buildTool: string;
+    readonly id: string;
+    readonly stage: ArtifactStage;
+    readonly provenance: ArtifactProvenance;
+    /** Authoritative stylesheet/import order, only when the Adapter can prove it. */
+    readonly order?: number;
+    /** Deterministic scan rank when browser/cascade order is not known. */
+    readonly discoveryOrder?: number;
+    readonly content?: string;
+    /** Generic styling-system label propagated onto reconciled non-package rows. */
+    readonly adapter?: string;
+    /** A recoverable transformed-observation failure; authored facts are retained. */
+    readonly failed?: boolean;
+    /** Adapter failures associated with this observation. */
+    readonly diagnostics?: readonly ArtifactDiagnosticInput[];
+}
+export interface ArtifactDiagnosticInput {
+    readonly code: TokenCatalogDiagnosticCode;
+    readonly message: string;
+    readonly module?: string;
+    readonly exportName?: string;
+}
+export interface InventoryDiagnostic {
+    readonly code: TokenCatalogDiagnosticCode;
+    readonly message: string;
+    readonly artifact?: string;
+    readonly module?: string;
+    readonly exportName?: string;
+}
+export type InventoryOrderEvidence = {
+    readonly kind: "stylesheet";
+    readonly index: number;
+} | {
+    readonly kind: "discovery";
+    readonly index: number;
+};
+export type InventoryContribution = {
+    readonly kind: "stylesheet";
+    readonly buildTool: string;
+    readonly id: string;
+    readonly stage: ArtifactStage;
+    readonly provenance: ArtifactProvenance;
+    readonly editable: boolean;
+    readonly orderEvidence: InventoryOrderEvidence;
+} | {
+    readonly kind: "adapter";
+    readonly id: string;
+    readonly provenance?: TokenOrigin;
+    readonly editable?: boolean;
+    readonly order: number;
+};
+export interface InventoryTokenDeclaration extends Omit<TokenDeclaration, "order"> {
+    readonly order: number;
+    readonly contribution: InventoryContribution;
+}
+export interface InventoryTokenDefinition extends Omit<TokenDefinition, "declarations"> {
+    readonly declarations: readonly InventoryTokenDeclaration[];
+}
+/** Declarative metadata rewrite for matching aggregated definitions. */
+export interface TokenDefinitionRelabelling {
+    readonly adapter: string;
+    readonly fromOrigin: TokenOrigin;
+    readonly origin?: TokenOrigin;
+    readonly editable?: boolean;
+}
+/**
+ * A normalized styling contribution. Re-applying the same `id` replaces its
+ * prior facts; contribution order is explicit or deterministically id-based.
+ */
+export interface TokenContribution {
+    readonly id: string;
+    readonly tokens?: readonly TokenEntry[];
+    /** Metadata/declaration enrichment for active definitions with matching cssName. */
+    readonly definitions?: readonly TokenDefinition[];
+    /** Deterministic metadata rewrites, matched by adapter and current origin. */
+    readonly relabellings?: readonly TokenDefinitionRelabelling[];
+    readonly diagnostics?: readonly InventoryDiagnostic[];
+    readonly order?: number;
+}
+export interface InventorySnapshot {
+    readonly generation: string;
+    readonly definitions: readonly InventoryTokenDefinition[];
+    readonly tokens: readonly TokenEntry[];
+    readonly diagnostics: readonly InventoryDiagnostic[];
+}

package/dist/css/token-inventory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/css/value-semantics/borderSemantics.d.ts

@@ -0,0 +1,28 @@
+import { type TokenInterpretationContext, type TokenValueInterpretation } from "./tokenInterpretation.js";
+export declare const BORDER_STYLES: Set<string>;
+export declare const BORDER_WIDTHS: Set<string>;
+export declare const COLOR_KEYWORDS: Set<string>;
+export declare const BORDER_CSS_WIDE: Set<string>;
+/** CSS initial values for omitted `border` / `border-*` shorthand components. */
+export declare const BORDER_INITIAL: {
+    readonly width: "medium";
+    readonly style: "none";
+    readonly color: "currentcolor";
+};
+/** Width/style/color components of a decomposable border value. */
+export interface BorderComponents {
+    width: string;
+    style: string;
+    color: string;
+    widthResult: TokenValueInterpretation;
+    styleResult: TokenValueInterpretation;
+    colorResult: TokenValueInterpretation;
+}
+/**
+ * Conservative border-shorthand classification: splits the authored value
+ * into width/style/color components with CSS initial values for omitted parts,
+ * and interprets each distinct component once. Returns null when the value
+ * cannot be decomposed faithfully (ambiguous component order, image layers,
+ * non-token slash forms, css-wide keywords, or multi-value junk).
+ */
+export declare function parseBorderComponents(value: string, tokenContext: TokenInterpretationContext): BorderComponents | null;

package/dist/css/value-semantics/borderSemantics.js

@@ -0,0 +1,91 @@
+/**
+ * Border shorthand structure (plan slice 3.5).
+ *
+ * One browser-safe Module owns the conservative `border` / `border-side`
+ * shorthand decomposition: width/style/color parts, CSS initial values for
+ * omitted components, css-wide-keyword rejection, and the explicit rejection
+ * of image layers, non-token slash forms, and ambiguous component counts.
+ *
+ * Browser-safe contract: this module imports only the shared model and the
+ * value-semantics token interpreter. It never touches the DOM or CSSOM.
+ */
+import { splitTopLevelWhitespace } from "./cssSyntax.js";
+import { interpretTokenValue, } from "./tokenInterpretation.js";
+export const BORDER_STYLES = new Set(["none", "hidden", "dotted", "dashed", "solid", "double", "groove", "ridge", "inset", "outset"]);
+export const BORDER_WIDTHS = new Set(["thin", "medium", "thick"]);
+export const COLOR_KEYWORDS = new Set(["transparent", "currentcolor", "black", "silver", "gray", "white", "maroon", "red", "purple", "fuchsia", "green", "lime", "olive", "yellow", "navy", "blue", "teal", "aqua", "orange"]);
+export const BORDER_CSS_WIDE = new Set(["inherit", "initial", "unset", "revert", "revert-layer"]);
+/** CSS initial values for omitted `border` / `border-*` shorthand components. */
+export const BORDER_INITIAL = { width: "medium", style: "none", color: "currentcolor" };
+/**
+ * Conservative border-shorthand classification: splits the authored value
+ * into width/style/color components with CSS initial values for omitted parts,
+ * and interprets each distinct component once. Returns null when the value
+ * cannot be decomposed faithfully (ambiguous component order, image layers,
+ * non-token slash forms, css-wide keywords, or multi-value junk).
+ */
+export function parseBorderComponents(value, tokenContext) {
+    const trimmed = value.trim();
+    if (!trimmed || BORDER_CSS_WIDE.has(trimmed.toLowerCase()))
+        return null;
+    const parts = splitTopLevelWhitespace(trimmed);
+    // One to three components in any order; more is multi-value / junk.
+    if (parts.length === 0 || parts.length > 3)
+        return null;
+    let width = "";
+    let style = "";
+    let color = "";
+    const interpretations = new Map();
+    const interpret = (component) => {
+        const cached = interpretations.get(component);
+        if (cached)
+            return cached;
+        const result = interpretTokenValue(component, tokenContext);
+        interpretations.set(component, result);
+        return result;
+    };
+    for (const part of parts) {
+        // Reject image layers and non-token slash forms (e.g. `red / 10%`).
+        if (/^(?:url|image|cross-fade|element|image-set|linear-gradient|radial-gradient|conic-gradient|repeating-linear-gradient|repeating-radial-gradient|repeating-conic-gradient)\(/i.test(part)) {
+            return null;
+        }
+        if (part.includes("/") && !/^var\(/i.test(part))
+            return null;
+        const isVariable = /^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/i.test(part);
+        const interpreted = isVariable ? interpret(part).resolvedValue.trim() : part;
+        // A custom property can substitute an entire shorthand. If its grammar is
+        // unresolved or expands to multiple components, assigning it to one slot
+        // would invent structure that the authored declaration does not prove.
+        if (isVariable && (/^var\(/i.test(interpreted) || splitTopLevelWhitespace(interpreted).length !== 1))
+            return null;
+        const candidate = interpreted.toLowerCase();
+        const isWidth = BORDER_WIDTHS.has(candidate)
+            || /^(?:0|[+-]?(?:\d*\.)?\d+(?:px|rem|em|%)?)$/i.test(interpreted);
+        const isStyle = BORDER_STYLES.has(candidate);
+        const isColor = COLOR_KEYWORDS.has(candidate)
+            || /^(?:#|rgb\(|rgba\(|hsl\(|hsla\(|hwb\(|lab\(|lch\(|oklab\(|oklch\(|color\(|color-mix\()/i.test(interpreted);
+        if (!width && isWidth)
+            width = part;
+        else if (!style && isStyle)
+            style = part;
+        else if (!color && isColor)
+            color = part;
+        else
+            return null;
+    }
+    // Omitted components take the CSS initial for that longhand (not inherited).
+    if (!width)
+        width = BORDER_INITIAL.width;
+    if (!style)
+        style = BORDER_INITIAL.style;
+    if (!color)
+        color = BORDER_INITIAL.color;
+    return {
+        width,
+        style,
+        color,
+        widthResult: interpret(width),
+        styleResult: interpret(style),
+        colorResult: interpret(color),
+    };
+}

package/dist/css/value-semantics/boxSemantics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Box and spacing value semantics (plan slice 3.5).
+ *
+ * One browser-safe Module owns physical and logical box-value expansion:
+ * 1–4 value shorthand expansion for `margin`/`padding`/`inset`, two-value
+ * expansion for `gap`, border-radius corner names, and the logical→physical
+ * side mapping. The logical mapping is a pure function over an explicit
+ * `Directionality` fact supplied by the integration (browser CSS inspection
+ * reads direction/writing-mode from the selected element); this module never
+ * touches the DOM or CSSOM.
+ */
+import type { StringArrayMap } from "./stringMaps.js";
+export declare const SPACING_SIDES: StringArrayMap;
+/** CSS `gap` shorthand order: row gap, then column gap. */
+export declare const GAP_AXES: StringArrayMap;
+export declare const BORDER_RADIUS_CORNERS: StringArrayMap;
+/**
+ * Explicit, DOM-free writing facts for logical→physical side mapping. The
+ * integration reads `direction` and `writing-mode` from the selected element's
+ * computed style and passes them here; the neutral Module applies them.
+ */
+export interface Directionality {
+    /** CSS `direction` value, e.g. `"ltr"` or `"rtl"`. */
+    direction: string;
+    /** CSS `writing-mode` value, e.g. `"horizontal-tb"` or `"vertical-rl"`. */
+    writingMode: string;
+}
+export declare function expandFourValueShorthand<T>(values: readonly T[]): [T, T, T, T] | null;
+export declare function expandTwoValueShorthand<T>(values: readonly T[]): [T, T] | null;
+/**
+ * Maps a logical `margin`/`padding`/`inset` property (inline/block forms,
+ * with optional start/end edges) to the physical sides it paints, using the
+ * element's writing-mode/direction facts. Returns null for non-logical
+ * properties. Without directionality the mapping assumes `ltr` /
+ * `horizontal-tb`, matching the resolver's element-less behaviour.
+ */
+export declare function logicalPhysicalSides(property: string, directionality?: Directionality): string[] | null;

package/dist/css/value-semantics/boxSemantics.js

@@ -0,0 +1,71 @@
+export const SPACING_SIDES = {
+    margin: ["margin-top", "margin-right", "margin-bottom", "margin-left"],
+    padding: ["padding-top", "padding-right", "padding-bottom", "padding-left"],
+    inset: ["top", "right", "bottom", "left"],
+};
+/** CSS `gap` shorthand order: row gap, then column gap. */
+export const GAP_AXES = {
+    gap: ["row-gap", "column-gap"],
+};
+export const BORDER_RADIUS_CORNERS = {
+    "border-radius": [
+        "border-top-left-radius",
+        "border-top-right-radius",
+        "border-bottom-right-radius",
+        "border-bottom-left-radius",
+    ],
+};
+export function expandFourValueShorthand(values) {
+    if (values.length === 0 || values.length > 4)
+        return null;
+    const top = values[0];
+    const right = values[1] ?? top;
+    const bottom = values[2] ?? top;
+    const left = values[3] ?? right;
+    if (values.length === 3)
+        return [top, right, bottom, right];
+    if (values.length === 2)
+        return [top, right, top, right];
+    return [top, right, bottom, left];
+}
+export function expandTwoValueShorthand(values) {
+    if (values.length === 0 || values.length > 2)
+        return null;
+    return values.length === 1 ? [values[0], values[0]] : [values[0], values[1]];
+}
+/**
+ * Maps a logical `margin`/`padding`/`inset` property (inline/block forms,
+ * with optional start/end edges) to the physical sides it paints, using the
+ * element's writing-mode/direction facts. Returns null for non-logical
+ * properties. Without directionality the mapping assumes `ltr` /
+ * `horizontal-tb`, matching the resolver's element-less behaviour.
+ */
+export function logicalPhysicalSides(property, directionality) {
+    const match = /^(margin|padding|inset)-(inline|block)(?:-(start|end))?$/.exec(property.toLowerCase());
+    if (!match)
+        return null;
+    const [family, axis, edge] = [match[1], match[2], match[3]];
+    const physicalPrefix = family === "inset" ? "" : `${family}-`;
+    const direction = directionality?.direction || "ltr";
+    const writingMode = directionality?.writingMode || "horizontal-tb";
+    const vertical = writingMode.startsWith("vertical") || writingMode.startsWith("sideways");
+    let sides;
+    if (!vertical) {
+        sides = axis === "inline"
+            ? direction === "rtl" ? [`${physicalPrefix}right`, `${physicalPrefix}left`] : [`${physicalPrefix}left`, `${physicalPrefix}right`]
+            : [`${physicalPrefix}top`, `${physicalPrefix}bottom`];
+    }
+    else if (axis === "block") {
+        sides = writingMode.includes("-rl")
+            ? [`${physicalPrefix}right`, `${physicalPrefix}left`]
+            : [`${physicalPrefix}left`, `${physicalPrefix}right`];
+    }
+    else {
+        const ltrStartsAtBottom = writingMode === "sideways-lr";
+        const startsAtBottom = direction === "rtl" ? !ltrStartsAtBottom : ltrStartsAtBottom;
+        sides = startsAtBottom
+            ? [`${physicalPrefix}bottom`, `${physicalPrefix}top`]
+            : [`${physicalPrefix}top`, `${physicalPrefix}bottom`];
+    }
+    return edge ? [edge === "start" ? sides[0] : sides[1]] : sides;
+}

package/dist/css/value-semantics/colorSemantics.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Color value semantics (plan slice 3.4).
+ *
+ * One browser-safe Module owns color format recognition, embedded-alpha
+ * detection, opacity modifier interpretation, `color-mix()` handling, color
+ * token replacement, and meaning-preserving opacity edits. Interpretation
+ * takes explicit token knowledge (a token table, local aliases, and an
+ * optional token-reference resolver) and never touches the DOM or CSSOM.
+ *
+ * Interface invariants:
+ * - interpretation never throws on arbitrary input;
+ * - edits either preserve the authored meaning or return an explicit
+ *   `ok: false` result — never a plausible but lossy string;
+ * - token-plus-alpha and opacity-token distinctions survive swaps;
+ * - framework-specific attribution (Tailwind v3 direct literals and `--tw-*`
+ *   aliases) stays behind the injected `resolveTokenReference` context.
+ */
+import type { ColorOpacity, ColorValueFacts, TokenEntry, TokenReference, TokenTable } from "../model/index.js";
+/** The resolved facts about one token-backed component of a color expression. */
+export interface ColorComponentResolution {
+    tokenName: string | null;
+    resolvedValue: string;
+    tokens: TokenReference[];
+}
+/** Explicit, DOM-free facts the color interpretation needs. */
+export interface ColorSemanticsContext {
+    /** Resolved token table (custom-property name → entry). */
+    tokenTable: TokenTable;
+    /** Local aliases collected from the selected element's cascade. */
+    localAliases?: ReadonlyMap<string, string>;
+    /**
+     * Resolves a `var()` component (for example an opacity token) to its
+     * concrete value and attribution. Supplied by the token interpretation so
+     * alias and framework attribution stay in one place. Absent → token-backed
+     * components fall back to local aliases, fallbacks, or the raw text.
+     */
+    resolveTokenReference?: (value: string) => ColorComponentResolution | null;
+}
+/**
+ * A meaning-preserving color edit. `ok: true` carries the rewritten value;
+ * `ok: false` reports explicitly that the transformation cannot be
+ * represented faithfully. Callers must treat `ok: false` as "no change".
+ */
+export type ColorEditResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: "unsupported" | "invalid-opacity";
+};
+/** One high-level color interpretation consumed by token interpretation and UI projection. */
+export interface ColorValueInterpretation {
+    opacity?: ColorOpacity;
+    facts: ColorValueFacts;
+}
+/**
+ * Normalizes an authored opacity to a clamped percent string. Accepts `%`
+ * and `0..1` forms; returns null when the input is not a parseable opacity.
+ */
+export declare function normalizeOpacityPercent(value: string): string | null;
+/**
+ * Interprets the alpha component of one authored color value. Returns a
+ * `ColorOpacity` when the value carries a recognized alpha channel (hex,
+ * rgb/hsl, or color-mix against transparent), and undefined otherwise.
+ */
+export declare function interpretColorOpacity(value: string, ctx: ColorSemanticsContext): ColorOpacity | undefined;
+/** Returns whether a color value carries its own alpha channel. */
+export declare function colorValueHasEmbeddedAlpha(value: string): boolean;
+/** Interprets UI-relevant color shape through the value-semantics seam. */
+export declare function interpretColorValue(value: string, ctx: ColorSemanticsContext): ColorValueInterpretation;
+/**
+ * Rewrites the alpha of a supported color expression to a normalized opacity
+ * percent. Hex alpha channels are rewritten digit-for-digit, rgb/hsl slash or
+ * comma alpha is replaced, `color-mix(... transparent)` reconciles its
+ * percentage (or its 100−p mirror), and a bare `var()` wraps into
+ * `color-mix(in srgb, var(...) <pct>, transparent)` — unwrapping back to the
+ * plain `var()` when the opacity reaches 100%. Unsupported value shapes and
+ * unparseable opacities return an explicit `ok: false`.
+ */
+export declare function applyColorOpacity(value: string, opacity: string): ColorEditResult;
+/**
+ * Replaces only the color token in a separable color expression. Keeping this
+ * separate from a plain token swap preserves authored alpha modifiers, for
+ * example Tailwind's `color-mix(... var(--color-red-500) 10%, transparent)`
+ * keeps its `10%` when the color token changes.
+ */
+export declare function applyColorTokenReplacement(value: string, oldToken: TokenEntry, newToken: TokenEntry): ColorEditResult;
+export type ValueEditRequest = {
+    kind: "color-opacity";
+    authored: string;
+    opacity: string;
+} | {
+    kind: "color-token";
+    authored: string;
+    currentToken: TokenEntry;
+    nextToken: TokenEntry;
+};
+/** The public meaning-preserving edit operation for supported value edits. */
+export declare function applyValueEdit(request: ValueEditRequest): ColorEditResult;