nudge-ui 0.2.0

package/dist/inspector/styleEditors/layoutValue.js

@@ -0,0 +1,103 @@
+import { getActiveStyleState } from "../shell/styleState.js";
+import { getStateStyleValue } from "../shell/stateValue.js";
+import { getElementComputedStyle } from "../runtime/domRealm.js";
+import { getBrowserCssInspection } from "../inspection/browserCssInspectionRegistry.js";
+const DEFAULT_LAYOUT_VALUES = {
+    width: "auto",
+    height: "auto",
+    "min-width": "0",
+    "min-height": "0",
+    "max-width": "none",
+    "max-height": "none",
+    "aspect-ratio": "auto",
+    top: "auto",
+    right: "auto",
+    bottom: "auto",
+    left: "auto",
+};
+/**
+ * Returns the authored CSS value when one is available, without replacing
+ * keywords such as `auto` with the browser's used pixel value.
+ */
+export function meaningfulLayoutValue(el, property) {
+    const authored = readAuthoredStyleValue(el, property);
+    if (authored)
+        return authored;
+    const computed = getStateStyleValue(el, property);
+    // Aspect-ratio's computed serialization remains a meaningful authored-like
+    // value, unlike used dimensions such as a block's computed pixel width.
+    if (property === "aspect-ratio" && computed && computed !== "auto")
+        return computed;
+    return DEFAULT_LAYOUT_VALUES[property] ?? computed;
+}
+export function readAuthoredStyleValue(el, property) {
+    try {
+        const state = getActiveStyleState();
+        const row = getBrowserCssInspection(el.ownerDocument ?? document)
+            .inspect(el, { state }).properties
+            .find((candidate) => candidate.property === property);
+        const authored = row?.authored ?? row?.declaredValue;
+        if (authored?.trim())
+            return authored.trim();
+    }
+    catch {
+        // CSSOM can reject cross-origin stylesheets. Fall through to explicit
+        // inline CSS and the computed-value fallback used by the field layer.
+    }
+    const inline = el.style.getPropertyValue(property).trim();
+    return inline || null;
+}
+/**
+ * Shorthands that also author the keyed longhand when present in a `style`
+ * attribute. Managed-stylesheet previews lose the cascade to any of these,
+ * so fields must treat the longhand as inline-blocked either way.
+ */
+const INLINE_SHORTHAND_SOURCES = {
+    "row-gap": ["gap"],
+    "column-gap": ["gap"],
+    "margin-top": ["margin"],
+    "margin-right": ["margin"],
+    "margin-bottom": ["margin"],
+    "margin-left": ["margin"],
+    "padding-top": ["padding"],
+    "padding-right": ["padding"],
+    "padding-bottom": ["padding"],
+    "padding-left": ["padding"],
+    top: ["inset"],
+    right: ["inset"],
+    bottom: ["inset"],
+    left: ["inset"],
+};
+/**
+ * Returns the inline-authored source when `el` carries the property — or a
+ * shorthand that sets it — in its `style` attribute. Managed previews can
+ * never beat inline styles in the cascade, so a non-null result means the
+ * field must present as blocked instead of accepting edits that silently
+ * revert (see `verifyPreview`'s "inline-style" conflict).
+ */
+export function inlineAuthoredValue(el, property) {
+    const direct = el.style.getPropertyValue(property).trim();
+    if (direct)
+        return `${property}: ${direct}`;
+    for (const shorthand of INLINE_SHORTHAND_SOURCES[property] ?? []) {
+        const value = el.style.getPropertyValue(shorthand).trim();
+        if (value)
+            return `${shorthand}: ${value}`;
+    }
+    return null;
+}
+/**
+ * Reads both representations needed by a layout editor. Authored CSS is the
+ * editable source of truth; computed CSS is only the browser preview/fallback.
+ */
+export function getLayoutValue(el, property) {
+    const authored = readAuthoredStyleValue(el, property);
+    let computed = "";
+    try {
+        computed = getElementComputedStyle(el).getPropertyValue(property).trim();
+    }
+    catch {
+        computed = getStateStyleValue(el, property);
+    }
+    return { property, authored, computed };
+}

package/dist/inspector/styleEditors/nudgeValue.d.ts

@@ -0,0 +1,8 @@
+export type NudgeDirection = -1 | 1;
+/**
+ * Returns a nudged CSS numeric literal, or null when the value is not a
+ * standalone number that the inspector can safely edit.
+ */
+export declare function nudgeCssValue(property: string, rawValue: string, direction: NudgeDirection, large?: boolean): string | null;
+/** Returns a clamped opacity percentage nudged by 1%, or 10% with Shift. */
+export declare function nudgeOpacityValue(rawValue: string, direction: NudgeDirection, large?: boolean): string | null;

package/dist/inspector/styleEditors/nudgeValue.js

@@ -0,0 +1,71 @@
+import { completeCssValue, CSS_NUMBER_SOURCE } from "./completeCssValue.js";
+import { valuePolicyFor } from "./valuePolicy.js";
+const CSS_NUMBER = new RegExp(`^(?:${CSS_NUMBER_SOURCE})$`, "i");
+const CSS_NUMERIC_LITERAL = new RegExp(`^(${CSS_NUMBER_SOURCE})(px|rem|em|%)?$`, "i");
+/**
+ * Returns a nudged CSS numeric literal, or null when the value is not a
+ * standalone number that the inspector can safely edit.
+ */
+export function nudgeCssValue(property, rawValue, direction, large = false) {
+    const normalised = normaliseForNudge(property, rawValue);
+    const parsed = parseNumericLiteral(normalised);
+    if (!parsed)
+        return null;
+    const step = nudgeStep(property, parsed.unit, large);
+    if (step === null)
+        return null;
+    let next = parsed.number + direction * step;
+    if (isFontWeight(property))
+        next = Math.min(1000, Math.max(1, next));
+    if (isLineHeight(property))
+        next = Math.max(0, next);
+    return `${formatNumber(next)}${parsed.unit}`;
+}
+/** Returns a clamped opacity percentage nudged by 1%, or 10% with Shift. */
+export function nudgeOpacityValue(rawValue, direction, large = false) {
+    const parsed = parseNumericLiteral(rawValue);
+    if (!parsed || parsed.unit !== "%")
+        return null;
+    const step = large ? 10 : 1;
+    const next = Math.min(100, Math.max(0, parsed.number + direction * step));
+    return `${formatNumber(next)}%`;
+}
+function normaliseForNudge(property, rawValue) {
+    const value = rawValue.trim();
+    if (!CSS_NUMBER.test(value))
+        return value;
+    const normalised = completeCssValue(value, valuePolicyFor(isLineHeight(property) ? "line-height" : property));
+    return isLineHeight(property) && normalised === "0" ? "0%" : normalised;
+}
+function parseNumericLiteral(value) {
+    const match = CSS_NUMERIC_LITERAL.exec(value.trim());
+    if (!match)
+        return null;
+    const number = Number(match[1]);
+    if (!Number.isFinite(number))
+        return null;
+    // SAFETY: the regex guarantees match[2] is one of the known CSS unit strings.
+    const unit = (match[2] ?? "").toLowerCase();
+    return { number, unit };
+}
+function nudgeStep(property, unit, large) {
+    if (isFontWeight(property))
+        return large ? 800 : 100;
+    if (isLineHeight(property) && unit === "%")
+        return large ? 80 : 10;
+    if (unit === "px" || unit === "%" || unit === "")
+        return large ? 8 : 1;
+    if (unit === "rem" || unit === "em")
+        return large ? 1 : 0.125;
+    return null;
+}
+function isLineHeight(property) {
+    return property === "line-height" || property.includes("line-height");
+}
+function isFontWeight(property) {
+    return property === "font-weight" || property.includes("font-weight");
+}
+function formatNumber(value) {
+    const rounded = Number(value.toFixed(12));
+    return Object.is(rounded, -0) ? "0" : String(rounded);
+}

package/dist/inspector/styleEditors/rowLookup.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedProperty } from "../../css/model/index.js";
+/** Finds the resolved row for one CSS property, or null when it is absent. */
+export declare function findTokenRow(rows: readonly ResolvedProperty[], property: string): ResolvedProperty | null;
+/**
+ * Source provenance for an edit, taken from the row that produced it. Omitted
+ * when the row carries no authored origin, so the caller sends no metadata.
+ */
+export declare function metadataFor(row: ResolvedProperty | null | undefined): {
+    sourceProperty: string;
+    sourceAuthoredValue: string;
+} | undefined;

package/dist/inspector/styleEditors/rowLookup.js

@@ -0,0 +1,13 @@
+/** Finds the resolved row for one CSS property, or null when it is absent. */
+export function findTokenRow(rows, property) {
+    return rows.find((row) => row.property === property) ?? null;
+}
+/**
+ * Source provenance for an edit, taken from the row that produced it. Omitted
+ * when the row carries no authored origin, so the caller sends no metadata.
+ */
+export function metadataFor(row) {
+    return row?.sourceProperty
+        ? { sourceProperty: row.sourceProperty, sourceAuthoredValue: row.authored ?? row.declaredValue }
+        : undefined;
+}

package/dist/inspector/styleEditors/stringRecord.d.ts

@@ -0,0 +1,4 @@
+/** A string-keyed string map used for default style values. */
+export type StringRecord = Record<string, string>;
+/** A string-keyed map from a longhand property to the shorthands that set it. */
+export type StringListRecord = Record<string, readonly string[]>;

package/dist/inspector/styleEditors/stringRecord.js

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

package/dist/inspector/styleEditors/valuePolicy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Describes the small amount of CSS value semantics the inspector can safely
+ * assist with. Values outside these policies remain raw CSS.
+ */
+export type CssUnit = "px" | "rem" | "em" | "%" | "";
+export type ValuePolicy = {
+    kind: "raw" | "number";
+    defaultUnit: null;
+    allowedUnits: readonly [];
+} | {
+    kind: "unit";
+    defaultUnit: CssUnit;
+    allowedUnits: readonly CssUnit[];
+} | {
+    kind: "line-height";
+    defaultUnit: "%";
+    allowedUnits: readonly ["%", "px", ""];
+};
+/** Returns the default and supported units for an editable CSS property. */
+export declare function valuePolicyFor(property: string): ValuePolicy;

package/dist/inspector/styleEditors/valuePolicy.js

@@ -0,0 +1,82 @@
+const RAW_VALUE = { kind: "raw", defaultUnit: null, allowedUnits: [] };
+const NUMBER_VALUE = { kind: "number", defaultUnit: null, allowedUnits: [] };
+const PIXEL_LENGTH = {
+    kind: "unit",
+    defaultUnit: "px",
+    allowedUnits: ["px", "rem", "em", "%"],
+};
+const BORDER_WIDTH = {
+    kind: "unit",
+    defaultUnit: "px",
+    allowedUnits: ["px", "rem", "em"],
+};
+const FONT_SIZE = {
+    kind: "unit",
+    defaultUnit: "px",
+    allowedUnits: ["px", "rem", "em", "%"],
+};
+const LINE_HEIGHT = {
+    kind: "line-height",
+    defaultUnit: "%",
+    allowedUnits: ["%", "px", ""],
+};
+const LETTER_SPACING = {
+    kind: "unit",
+    defaultUnit: "em",
+    allowedUnits: ["em"],
+};
+const FLEX_BASIS = {
+    kind: "unit",
+    defaultUnit: "px",
+    allowedUnits: ["px", "%"],
+};
+const NUMBER_PROPERTIES = new Set(["flex-grow", "flex-shrink", "order", "font-weight"]);
+const PIXEL_LENGTH_PROPERTIES = new Set([
+    "margin",
+    "margin-top",
+    "margin-right",
+    "margin-bottom",
+    "margin-left",
+    "padding",
+    "padding-top",
+    "padding-right",
+    "padding-bottom",
+    "padding-left",
+    "row-gap",
+    "column-gap",
+    "gap",
+    "top",
+    "right",
+    "bottom",
+    "left",
+    "inset",
+    "inset-block",
+    "inset-inline",
+    "width",
+    "height",
+    "min-width",
+    "min-height",
+    "max-width",
+    "max-height",
+    "border-radius",
+]);
+/** Returns the default and supported units for an editable CSS property. */
+export function valuePolicyFor(property) {
+    if (NUMBER_PROPERTIES.has(property))
+        return NUMBER_VALUE;
+    if (property === "font-size")
+        return FONT_SIZE;
+    if (property === "line-height")
+        return LINE_HEIGHT;
+    if (property === "letter-spacing")
+        return LETTER_SPACING;
+    if (property === "flex-basis")
+        return FLEX_BASIS;
+    if (/^border(?:-(?:top|right|bottom|left))?-width$/.test(property))
+        return BORDER_WIDTH;
+    if (/^(?:inset|margin|padding)-(?:horizontal|vertical)$/.test(property))
+        return PIXEL_LENGTH;
+    if (PIXEL_LENGTH_PROPERTIES.has(property))
+        return PIXEL_LENGTH;
+    return RAW_VALUE;
+}

package/dist/inspector/testing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test and conformance helpers for validating the inspector through a
+ * consumer-facing entry point. Keep these exports out of the runtime entry.
+ */
+export { assertConformanceFixture, runConformanceFixture } from "./conformance/fixture.js";
+export type { ConformanceFixture, ConformanceResult, ConformancePropertyExpectation, ConformanceProjectionExpectation, ConformanceProjectionFieldExpectation, } from "./conformance/fixture.js";
+export { BORDER_CASES } from "./conformance/borderCases.js";
+export { COLOR_CASES } from "./conformance/colorCases.js";
+export { SPACING_CASES } from "./conformance/spacingCases.js";
+export { TYPOGRAPHY_CASES } from "./conformance/typographyCases.js";

package/dist/inspector/testing.js

@@ -0,0 +1,9 @@
+/**
+ * Test and conformance helpers for validating the inspector through a
+ * consumer-facing entry point. Keep these exports out of the runtime entry.
+ */
+export { assertConformanceFixture, runConformanceFixture } from "./conformance/fixture.js";
+export { BORDER_CASES } from "./conformance/borderCases.js";
+export { COLOR_CASES } from "./conformance/colorCases.js";
+export { SPACING_CASES } from "./conformance/spacingCases.js";
+export { TYPOGRAPHY_CASES } from "./conformance/typographyCases.js";

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

@@ -0,0 +1,24 @@
+import type { HTMLAttributes, ReactElement } from "react";
+export type TokenChipSize = "default" | "small";
+export interface TokenChipProps extends HTMLAttributes<HTMLSpanElement> {
+    size?: TokenChipSize;
+    "data-test"?: string;
+    "data-group"?: string;
+}
+interface TokenChipSlotProps extends HTMLAttributes<HTMLSpanElement> {
+    "data-test"?: string;
+}
+declare function TokenChipRoot({ size, className, children, ...props }: TokenChipProps): ReactElement;
+declare function TokenChipPicker({ className, children, ...props }: TokenChipSlotProps): ReactElement;
+declare function TokenChipLabel({ className, children, ...props }: TokenChipSlotProps): ReactElement;
+declare function TokenChipAction({ className, children, ...props }: TokenChipSlotProps): ReactElement;
+/**
+ * Layout for a token's selected value. Callers compose the picker and actions
+ * so their interaction semantics remain independent of the chip's visuals.
+ */
+export declare const TokenChip: typeof TokenChipRoot & {
+    Picker: typeof TokenChipPicker;
+    Label: typeof TokenChipLabel;
+    Action: typeof TokenChipAction;
+};
+export {};

package/dist/inspector/tokens/TokenChip.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TokenLabel } from "./TokenLabel.js";
+function TokenChipRoot({ size = "default", className, children, ...props }) {
+    return (_jsx("span", { ...props, className: `token-chip token-chip--${size}${className ? ` ${className}` : ""}`, children: children }));
+}
+function TokenChipPicker({ className, children, ...props }) {
+    return (_jsx("span", { ...props, className: `token-chip__picker${className ? ` ${className}` : ""}`, children: children }));
+}
+function TokenChipLabel({ className, children, ...props }) {
+    return (_jsx(TokenLabel, { ...props, className: `token-chip__label${className ? ` ${className}` : ""}`, children: children }));
+}
+function TokenChipAction({ className, children, ...props }) {
+    return (_jsx("span", { ...props, className: `token-chip__action${className ? ` ${className}` : ""}`, children: children }));
+}
+/**
+ * Layout for a token's selected value. Callers compose the picker and actions
+ * so their interaction semantics remain independent of the chip's visuals.
+ */
+export const TokenChip = Object.assign(TokenChipRoot, {
+    Picker: TokenChipPicker,
+    Label: TokenChipLabel,
+    Action: TokenChipAction,
+});

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

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import type { TokenEntry } from "../../css/model/index.js";
+import type { ResolvedProperty } from "../../css/model/index.js";
+import type { CssValueGrammar, TokenSemanticSlot } from "../../css/value-semantics/index.js";
+export interface TokenDropdownProps {
+    row: ResolvedProperty;
+    domElement: HTMLElement;
+    entries: TokenEntry[];
+    slot?: TokenSemanticSlot;
+    grammar?: CssValueGrammar;
+    onAfterEdit?: () => void;
+}
+export declare function TokenDropdown(props: TokenDropdownProps): ReactElement;

package/dist/inspector/tokens/TokenDropdown.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { swapToken, promoteToToken } from "./editActions.js";
+import { Select } from "../ui/Select.js";
+import { selectTokens, TOKEN_GROUP_LABELS, TOKEN_GROUP_ORDER, } from "../../css/value-semantics/index.js";
+function groupTokens(entries) {
+    const map = new Map();
+    for (const entry of entries) {
+        const group = entry.group;
+        let list = map.get(group);
+        if (!list) {
+            list = [];
+            map.set(group, list);
+        }
+        list.push(entry);
+    }
+    return map;
+}
+export function TokenDropdown(props) {
+    const { row, domElement, entries, slot, grammar, onAfterEdit } = props;
+    const candidates = useMemo(() => selectTokens({
+        element: domElement,
+        property: row.property,
+        slot,
+        entries,
+        currentToken: row.tokenName,
+        grammar,
+    }).candidates, [domElement, entries, grammar, row.property, row.tokenName, slot]);
+    const grouped = useMemo(() => groupTokens(candidates), [candidates]);
+    function handleSelect(value) {
+        const chosen = candidates.find(({ entry }) => entry.name === value)?.entry;
+        if (!chosen)
+            return;
+        const oldToken = row.tokenName
+            ? entries.find((entry) => entry.name === row.tokenName || entry.cssName === row.tokenName) ?? null
+            : null;
+        swapToken(domElement, row.property, chosen, oldToken);
+        onAfterEdit?.();
+    }
+    function handlePromote(value) {
+        const chosen = entries.find((entry) => entry.name === value);
+        if (!chosen)
+            return;
+        promoteToToken(domElement, row.property, chosen);
+        onAfterEdit?.();
+    }
+    const hasToken = row.tokenName !== null;
+    const selectValue = row.tokenName ?? "";
+    const selectGroups = TOKEN_GROUP_ORDER.flatMap((group) => {
+        const list = grouped.get(group);
+        if (!list || list.length === 0)
+            return [];
+        return [{
+                label: TOKEN_GROUP_LABELS[group],
+                options: list.map(({ entry }) => ({ value: entry.name, label: entry.name })),
+            }];
+    });
+    return (_jsx("span", { className: "token-dropdown", "data-test": "token-dropdown", children: hasToken ? (_jsx(Select, { "data-test": "token-select", value: selectValue, groups: selectGroups, searchable: true, searchPlaceholder: "Search", searchAriaLabel: "Search tokens", onValueChange: handleSelect })) : (_jsx("span", { className: "token-promote", "data-test": "token-promote", children: _jsx(Select, { "data-test": "token-promote-select", value: "", placeholder: "Replace with token\u2026", groups: selectGroups, searchable: true, searchPlaceholder: "Search", searchAriaLabel: "Search tokens", onValueChange: handlePromote }) })) }));
+}

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

@@ -0,0 +1,68 @@
+import type { ReactElement, ReactNode } from "react";
+import type { TokenEntry } from "../../css/model/index.js";
+import type { AtRuleContext, ColorOpacity, ColorValueFacts, ResolvedProperty } from "../../css/model/index.js";
+import type { TokenSemanticSlot } from "../../css/value-semantics/index.js";
+import type { StyleEditMetadata } from "./editActions.js";
+import { type EditTarget } from "../selection/editTarget.js";
+import type { StyleSelection } from "../selection/styleSelection.js";
+export interface TokenValueFieldProps {
+    property: string;
+    domElement?: HTMLElement;
+    semanticSlot?: TokenSemanticSlot;
+    committedValue: string;
+    resolvedValue?: string;
+    activeTokenName?: string | null;
+    entries: TokenEntry[];
+    suggestions?: ReadonlyArray<string>;
+    inputDataTest?: string;
+    allowedTokenNames?: ReadonlySet<string>;
+    isColor?: boolean;
+    disabled?: boolean;
+    mixed?: boolean;
+    formatRawValue?: (value: string) => string;
+    onCommitRaw(value: string): void;
+    onSelectToken(token: TokenEntry): boolean | void;
+    onUnlink(value: string): void;
+    /** Referenced tokens used for raw color-field behavior; not rendered inline. */
+    attributionTokens?: string[];
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    className?: string;
+    label?: string;
+    opacity?: ColorOpacity;
+    color?: ColorValueFacts;
+    onCommitOpacity?(value: string): boolean | void;
+    atRules?: readonly AtRuleContext[];
+    chipVariant?: "default" | "small";
+}
+export interface TokenFieldProps {
+    property: string;
+    semanticSlot?: TokenSemanticSlot;
+    tokenRow?: ResolvedProperty | null;
+    selection?: StyleSelection | null;
+    initialValue?: string;
+    /** Optional normalized value shown when an authored row is not token-backed. */
+    displayValue?: string;
+    domElement: HTMLElement;
+    /** Optional group target. `domElement` remains the primary inspection node. */
+    editTarget?: EditTarget;
+    entries: TokenEntry[];
+    suggestions?: ReadonlyArray<string>;
+    inputDataTest?: string;
+    onAfterEdit?: () => void;
+    editMetadata?: StyleEditMetadata;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    className?: string;
+    label?: string;
+    chipVariant?: "default" | "small";
+    formatRawValue?: (value: string) => string;
+    disabled?: boolean;
+    /** Shows a mixed value without accidentally committing the placeholder. */
+    mixed?: boolean;
+    /** Referenced tokens used for raw color-field behavior; not rendered inline. */
+    attributionTokens?: string[];
+}
+export declare function colorValueToHex(value: string): string | null;
+export declare function TokenValueField(props: TokenValueFieldProps): ReactElement;
+export declare function TokenField(props: TokenFieldProps): ReactElement;