nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/styleEditors/PositionControls.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { LayoutDropdown } from "./LayoutDropdown.js";
+import { LayoutValueField } from "./FlexControls.js";
+import { SpacingField, projectSpacing } from "./SpacingField.js";
+export const POSITION_OPTIONS = ["static", "relative", "absolute", "fixed", "sticky"];
+export const Z_INDEX_PRESETS = ["auto", "0", "1", "10", "100"];
+const OFFSET_PRESETS = ["auto", "0", "50%", "100%"];
+/** Position, z-index and insets for an element that is not static; static elements set these from the options menu. */
+export function PositionControls({ domElement, editTarget, selection, entries, tokenRows, position, revision, onAfterEdit }) {
+    const common = { domElement, editTarget, selection, revision, onAfterEdit };
+    const spacing = projectSpacing(domElement, selection, tokenRows);
+    const spacingProps = { domElement, editTarget, selection, entries, tokenRows, onAfterEdit };
+    const showAnchoredInsets = selection ? selection.supportsRole("inset-position") : position === "absolute" || position === "fixed";
+    const showOffsetInsets = selection ? selection.supportsRole("relative-position") : position === "relative" || position === "sticky";
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "layout__tool-row", "data-test": "layout-position", children: [_jsx(LayoutDropdown, { property: "position", options: POSITION_OPTIONS, ...common }), _jsx(LayoutValueField, { label: "Z-index", property: "z-index", presets: Z_INDEX_PRESETS, inputOnly: true, ...common })] }), showAnchoredInsets ? (_jsx(SpacingField, { property: "inset", projection: spacing.inset, showLabel: false, showEmptyState: false, suggestions: OFFSET_PRESETS, ...spacingProps })) : null, showOffsetInsets ? _jsx(SpacingField, { property: "inset", projection: spacing.inset, ...spacingProps }) : null] }));
+}

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

@@ -0,0 +1,18 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ResolvedProperty, TokenEntry } from "../../css/model/index.js";
+import type { EditTarget } from "../selection/editTarget.js";
+import type { StyleSelection } from "../selection/styleSelection.js";
+export interface SizeSectionProps {
+    /** Rows shown under the min and max fields while expanded, such as flex or grid child controls. */
+    extras?: ReactNode;
+    /** Something behind the expander differs from its initial value. */
+    modified?: boolean;
+    domElement: HTMLElement;
+    editTarget: EditTarget;
+    selection?: StyleSelection | null;
+    entries: TokenEntry[];
+    tokenRows: ResolvedProperty[];
+    revision: number;
+    onAfterEdit?: () => void;
+}
+export declare function SizeSection({ domElement: el, editTarget, selection, entries, tokenRows, revision, onAfterEdit, extras, modified }: SizeSectionProps): ReactElement;

package/dist/inspector/styleEditors/SizeSection.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { IconChevronDown, IconChevronUp, IconLetterH, IconLetterW } from "@tabler/icons-react";
+import { TokenField } from "../tokens/TokenField.js";
+import { AspectRatioField } from "./AspectRatioField.js";
+import { meaningfulLayoutValue } from "./layoutValue.js";
+import { IconButton } from "../ui/IconButton.js";
+import { FieldRow } from "../ui/FieldRow.js";
+import { ControlSurface } from "../ui/ControlSurface.js";
+import { Tooltip } from "../ui/Tooltip.js";
+import { getElementComputedStyle, getElementWindow } from "../runtime/domRealm.js";
+const PLAIN_PIXEL_VALUE = /^-?\d*\.?\d+px$/;
+/** The used pixel size of a dimension, kept current as the element resizes. */
+function useResolvedDimension(el, property, revision) {
+    const [resolved, setResolved] = useState(() => readResolvedDimension(el, property));
+    useEffect(() => {
+        const update = () => setResolved(readResolvedDimension(el, property));
+        update();
+        // SAFETY: the element's window is a same-realm Window, and the runtime realm exposes the observer constructors as project-wide globals.
+        const { ResizeObserver: ResizeObserverCtor } = getElementWindow(el);
+        if (!ResizeObserverCtor)
+            return;
+        const observer = new ResizeObserverCtor(update);
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [el, property, revision]);
+    return resolved;
+}
+function readResolvedDimension(el, property) {
+    try {
+        const pixels = Number.parseFloat(getElementComputedStyle(el)[property]);
+        return Number.isFinite(pixels) ? pixels : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Shows the used size beside an authored keyword or expression, so `auto` still tells you how big the element is. */
+function ResolvedDimension({ el, property, revision }) {
+    const resolved = useResolvedDimension(el, property, revision);
+    const authored = meaningfulLayoutValue(el, property).trim();
+    if (resolved === null || PLAIN_PIXEL_VALUE.test(authored))
+        return null;
+    // Whole pixels keep the label short enough to sit beside the authored value; the title keeps the exact figure.
+    return _jsx("span", { className: "layout__resolved", "data-test": `layout-resolved-${property}`, title: `${Math.round(resolved * 100) / 100}px`, children: Math.round(resolved) });
+}
+const SIZE_PRESETS = ["auto", "0", "100%", "fit-content"];
+const MIN_SIZE_PRESETS = ["0", "min-content", "fit-content"];
+const MAX_WIDTH_PRESETS = ["none", "100%", "100vw", "fit-content"];
+const MAX_HEIGHT_PRESETS = ["none", "100%", "100vh", "fit-content"];
+export function SizeSection({ domElement: el, editTarget, selection, entries, tokenRows, revision, onAfterEdit, extras, modified = false }) {
+    const [expanded, setExpanded] = useState(false);
+    const fields = [
+        { property: "width", presets: SIZE_PRESETS },
+        { property: "height", presets: SIZE_PRESETS },
+        { property: "min-width", presets: MIN_SIZE_PRESETS },
+        { property: "min-height", presets: MIN_SIZE_PRESETS },
+        { property: "max-width", presets: MAX_WIDTH_PRESETS },
+        { property: "max-height", presets: MAX_HEIGHT_PRESETS },
+    ];
+    const multipleSelected = (selection?.domElements.length ?? 1) > 1;
+    function renderTokenField(property, presets) {
+        const dimension = property === "width" || property === "height" ? property : null;
+        return (_jsx(ControlSurface, { className: property === "width" || property === "height" ? "layout__size-field--icon" : undefined, children: _jsx(TokenField, { property: property, selection: selection, tokenRow: tokenRows.find((row) => row.property === property) ?? null, initialValue: meaningfulLayoutValue(el, property), domElement: el, editTarget: editTarget, entries: entries, suggestions: presets, leading: property === "width"
+                    ? _jsx(IconLetterW, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" })
+                    : property === "height"
+                        ? _jsx(IconLetterH, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" })
+                        : undefined, trailing: dimension && !multipleSelected ? _jsx(ResolvedDimension, { el: el, property: dimension, revision: revision }) : undefined, onAfterEdit: onAfterEdit }) }));
+    }
+    return (_jsxs("div", { className: "layout__size", "data-test": "layout-size", "data-expanded": expanded ? "true" : "false", children: [_jsxs("div", { className: "layout__size-grid", children: [_jsx(FieldRow, { label: "Width", hideLabel: true, "data-test": "layout-size-width", className: "layout__size-cell layout__size-cell--width", children: renderTokenField("width", SIZE_PRESETS) }), _jsx(FieldRow, { label: "Height", hideLabel: true, "data-test": "layout-size-height", className: "layout__size-cell layout__size-cell--height", children: renderTokenField("height", SIZE_PRESETS) }), _jsx(Tooltip, { children: _jsx(IconButton, { className: "layout__size-cell layout__size-cell--toggle", variant: "quiet", size: "default", "data-modified": modified ? "true" : undefined, "data-test": expanded ? "layout-size-collapse" : "layout-size-expand", "aria-label": expanded ? "Collapse Size Fields" : "Expand Size Fields", label: expanded ? "Collapse Size Fields" : "Expand Size Fields", onClick: () => setExpanded(!expanded), children: expanded ? (_jsx(IconChevronUp, { size: 16, stroke: 1.8, "aria-hidden": "true" })) : (_jsx(IconChevronDown, { size: 16, stroke: 1.8, "aria-hidden": "true" })) }) }), expanded && fields.slice(2).map(({ property, presets }) => (_jsx(FieldRow, { label: property, "data-test": `layout-size-${property}`, className: `layout__size-cell layout__size-cell--${property}`, children: renderTokenField(property, presets) }, property))), expanded && (_jsx(AspectRatioField, { className: "layout__size-cell layout__size-cell--aspect-ratio", domElement: el, editTarget: editTarget, selection: selection, entries: entries, tokenRow: tokenRows.find((row) => row.property === "aspect-ratio") ?? null, revision: revision, onAfterEdit: onAfterEdit }))] }), expanded ? extras : null] }));
+}

package/dist/inspector/styleEditors/{SpacingBox.d.ts → SpacingField.d.ts}

@@ -1,18 +1,11 @@
 import type { ReactElement } from "react";
 import type { ResolvedProperty } from "../../css/model/index.js";
 import type { TokenEntry } from "../../css/model/index.js";
-import type { SelectedElement } from "../selection/selectionStore.js";
-import { type InspectorSpacingProjection } from "../spacing/projection.js";
+import { projectInspectorValues, type InspectorSpacingProjection } from "../spacing/projection.js";
 import type { EditTarget } from "../selection/editTarget.js";
 import type { StyleSelection } from "../selection/styleSelection.js";
-export interface SpacingBoxProps {
-    element: SelectedElement;
-    selection?: StyleSelection | null;
-    entries?: TokenEntry[];
-    tokenRows?: ResolvedProperty[];
-    onAfterEdit?: () => void;
-}
-export declare function SpacingBox(props: SpacingBoxProps): ReactElement;
+/** Values for one selection, projected from its computed styles or the shared selection model. */
+export declare function projectSpacing(element: HTMLElement, selection: StyleSelection | null | undefined, tokenRows: ResolvedProperty[]): ReturnType<typeof projectInspectorValues>["spacing"];
 export interface SpacingFieldProps {
     property: "padding" | "margin" | "inset";
     projection: InspectorSpacingProjection;

package/dist/inspector/styleEditors/{SpacingBox.js → SpacingField.js}

@@ -5,28 +5,19 @@ import { TokenField, TokenValueField } from "../tokens/TokenField.js";
 import { IconButton } from "../ui/IconButton.js";
 import { SideValuesField, SIDE_NAMES, MarginSideIndicator, } from "../ui/SideValuesField.js";
 import { setStyles, swapTokens } from "../tokens/editActions.js";
+import { isCalcExpression } from "../../css/value-semantics/index.js";
+import { deriveActiveTokenName, isExpressionRow } from "./fieldValue.js";
 import { completeCssValue } from "./completeCssValue.js";
 import { valuePolicyFor } from "./valuePolicy.js";
 import { projectInspectorValues, projectInspectorValuesForSelection, } from "../spacing/projection.js";
-import { getStateStyleValue } from "../shell/stateValue.js";
 import { isZeroCssValue } from "./stylePresence.js";
 import { useFieldVisibility } from "./useFieldVisibility.js";
 import { inlineBlockedBy } from "./inlineAuthored.js";
-export function SpacingBox(props) {
-    const { element, selection, entries, tokenRows = [], onAfterEdit } = props;
-    const el = element.domElement;
-    const allEntries = entries ?? [];
-    const projection = selection
+/** Values for one selection, projected from its computed styles or the shared selection model. */
+export function projectSpacing(element, selection, tokenRows) {
+    return (selection
         ? projectInspectorValuesForSelection(selection)
-        : projectInspectorValues(el, tokenRows);
-    const showRelativeInset = selection
-        ? selection.supportsRole("relative-position")
-        : (() => {
-            const value = getStateStyleValue(el, "position", "static").trim().toLowerCase();
-            return value === "relative" || value === "sticky";
-        })();
-    const editTarget = selection?.target ?? el;
-    return (_jsxs("div", { className: "editor", "data-test": "spacing-box", children: [_jsx("div", { className: "editor__title", children: "Spacing" }), _jsxs("div", { className: "spacing", children: [_jsx(SpacingField, { property: "padding", projection: projection.spacing.padding, domElement: el, editTarget: editTarget, selection: selection, entries: allEntries, tokenRows: tokenRows, onAfterEdit: onAfterEdit }), _jsx(SpacingField, { property: "margin", projection: projection.spacing.margin, domElement: el, editTarget: editTarget, selection: selection, entries: allEntries, tokenRows: tokenRows, onAfterEdit: onAfterEdit }), showRelativeInset ? _jsx(SpacingField, { property: "inset", projection: projection.spacing.inset, domElement: el, editTarget: editTarget, selection: selection, entries: allEntries, tokenRows: tokenRows, onAfterEdit: onAfterEdit }) : null] })] }));
+        : projectInspectorValues(element, tokenRows)).spacing;
 }
 export function SpacingField({ property, projection: spacingProjection, domElement: el, editTarget, selection, entries, tokenRows, onAfterEdit, showLabel = true, showEmptyState = true, suggestions, }) {
     const pairDefinitions = [
@@ -40,12 +31,13 @@ export function SpacingField({ property, projection: spacingProjection, domEleme
         return {
             side,
             icon: null,
-            control: (_jsx(TokenField, { property: sideName, selection: selection, tokenRow: findTokenRow(tokenRows, sideName), domElement: el, editTarget: editTarget, entries: entries, suggestions: suggestions, displayValue: isCalcValue(field.authoredValue) && field.value ? field.value : undefined, editMetadata: metadataFor(findTokenRow(tokenRows, sideName)), onAfterEdit: onAfterEdit, chipVariant: "small", leading: icon })),
+            control: (_jsx(TokenField, { property: sideName, selection: selection, tokenRow: findTokenRow(tokenRows, sideName), domElement: el, editTarget: editTarget, entries: entries, suggestions: suggestions, initialValue: property === "inset" ? "auto" : undefined, displayValue: property === "inset" && !field.tokenName
+                    ? field.authoredValue
+                    : isCalcExpression(field.authoredValue) && field.value ? field.value : undefined, editMetadata: metadataFor(findTokenRow(tokenRows, sideName)), onAfterEdit: onAfterEdit, chipVariant: "small", leading: icon })),
         };
     });
     const hasSpacing = SIDE_NAMES.some((side) => {
-        // Zero spacing is visually empty regardless of whether it came from a
-        // reset, a component rule, or a token. Open editors stay open below.
+        // Zero spacing is visually empty whatever its source; open editors stay open below.
         const value = spacingProjection.fields[side].value.trim();
         return value !== "" && !isZeroCssValue(value) && (property !== "inset" || value !== "auto");
     });
@@ -88,14 +80,11 @@ function PairedTokenField({ displayProperty, sideProperties, domElement: el, edi
     const row = pairTokenRow(displayProperty, axisProjection);
     const groupMixed = axisProjection.fields.some((field) => field.value === "Mixed");
     const valuesMatch = axisProjection.state === "shared" && !groupMixed;
-    const expression = Boolean(row && (row.capability === "raw" || row.capability === "composite"
-        || row.modifiers?.some((modifier) => modifier.kind === "alpha")));
+    const expression = isExpressionRow(row);
     const calcAuthored = row?.authored ?? row?.declaredValue ?? "";
-    const isCalcAuthored = isCalcValue(calcAuthored);
-    const activeTokenName = !valuesMatch || expression || isCalcAuthored ? null : row.tokenName;
-    // Some browsers expose the used pixel size for horizontal auto margins.
-    // Keep the authored keyword visible because replacing it with that transient
-    // size would misrepresent the declaration and change the edit semantics.
+    const isCalcAuthored = isCalcExpression(calcAuthored);
+    const activeTokenName = deriveActiveTokenName({ row, mixed: !valuesMatch, authored: calcAuthored });
+    // Some browsers report the used pixel size for horizontal auto margins; keep the authored keyword.
     const committedValue = groupMixed
         ? "Mixed"
         : valuesMatch
@@ -130,10 +119,7 @@ function PairedTokenField({ displayProperty, sideProperties, domElement: el, edi
         }, onUnlink: commitAxisValue, leading: leading, blockedBy: blockedBy }));
 }
 function fieldDisplayValue(field) {
-    return isCalcValue(field.authoredValue) ? field.value : field.authoredValue.trim() || field.value;
-}
-function isCalcValue(value) {
-    return /\bcalc\s*\(/i.test(value);
+    return isCalcExpression(field.authoredValue) ? field.value : field.authoredValue.trim() || field.value;
 }
 function splitAxisValue(value) {
     let depth = 0;

package/dist/inspector/styleEditors/Typography.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { IconTextSize, IconAlignCenter, IconAlignLeft, IconAlignRight, IconLayoutAlignMiddle, IconLayoutAlignBottom, IconLayoutAlignTop, IconBaseline, IconChevronDown, IconItalic, IconLetterSpacing, IconTypography, } from "@tabler/icons-react";
 import { findTokenRow, metadataFor } from "./rowLookup.js";
+import { isExpressionRow } from "./fieldValue.js";
 import { TokenField } from "../tokens/TokenField.js";
 import { Select } from "../ui/Select.js";
 import { SegmentedControl } from "../ui/SegmentedControl.js";
@@ -36,10 +37,7 @@ function TypographyTokenField(props) {
     const tokenName = selectedProperty
         ? selectedProperty.token.kind === "common" ? selectedProperty.token.name : null
         : tokenRow?.tokenName;
-    const hasTokenChip = Boolean(tokenName
-        && tokenRow?.capability !== "raw"
-        && tokenRow?.capability !== "composite"
-        && !tokenRow?.modifiers?.some((modifier) => modifier.kind === "alpha"));
+    const hasTokenChip = Boolean(tokenName && !isExpressionRow(tokenRow));
     return (_jsx(ControlSurface, { className: `typography__field typography__field--${property}`, children: _jsx(TokenField, { property: property, tokenRow: tokenRow, selection: selection, domElement: domElement, editTarget: editTarget, entries: entries, editMetadata: metadataFor(tokenRow), leading: icon, trailing: metric || hasTokenChip ? undefined : _jsx(IconChevronDown, { size: 17, stroke: 1.8, "aria-hidden": "true" }), label: label, chipVariant: chipVariant, onAfterEdit: onAfterEdit }) }));
 }
 const FONT_STYLE_OPTIONS = [

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

@@ -6,22 +6,17 @@ export type BorderSide = (typeof BORDER_SIDES)[number];
 export type BorderComponent = "width" | "style" | "color";
 /** Reads a property's computed value for the inspected style state. */
 export type ComputedStyleReader = (property: string, fallback: string) => string;
-/** What the border editor knows about one element: its cascade rows and computed style. */
 export interface BorderSource {
     readonly rows: readonly ResolvedProperty[];
     readonly computed: ComputedStyleReader;
 }
 export interface BorderEditorState {
-    /** Every side shares its width, style, and color. Never true for a group selection. */
     readonly sidesLinked: boolean;
-    /** An unstructured `border` shorthand row that only a raw field can edit. */
+    /** Editable only through a raw field. */
     readonly rawShorthandRow: ResolvedProperty | null;
-    /** The linked style draws a line, so linked width and color are meaningful. */
     readonly linkedStyleDraws: boolean;
-    /** Rows backing the linked `border-width`, `border-style`, and `border-color` fields. */
     readonly linkedRows: Readonly<Record<BorderComponent, ResolvedProperty | null>>;
 }
-/** User choices the border editor turns into declarations. */
 export type BorderIntent = {
     readonly kind: "add";
 } | {
@@ -37,6 +32,5 @@ export declare function borderProperty(component: BorderComponent, side?: Border
 export declare function readBorderEditor(source: BorderSource, { group }: {
     readonly group: boolean;
 }): BorderEditorState;
-/** Whether any side draws a visible line, including after stylesheet resets. */
 export declare function hasVisibleBorder(computed: ComputedStyleReader): boolean;
 export declare function borderDeclarations(source: BorderSource, intent: BorderIntent): StyleDeclaration[];

package/dist/inspector/styleEditors/borderModel.js

@@ -18,10 +18,7 @@ function isBorderStyle(value) {
 function sideProperties(component) {
     return BORDER_SIDES.map((side) => borderProperty(component, side));
 }
-/**
- * Effective value of one border width, style, or color property. Structured
- * shorthand parts win, then authored text, then the computed style.
- */
+/** Precedence: structured shorthand parts, then authored text, then computed style. */
 function borderComponentValue(source, component, property) {
     const row = findTokenRow(source.rows, property);
     const fallback = COMPONENT_FALLBACK[component];
@@ -45,11 +42,7 @@ function sideSignature(source, component, property) {
         return value;
     return `${value}|${findTokenRow(source.rows, property)?.tokenName ?? ""}`;
 }
-/**
- * A component is linked when every side shares its value. A lone shorthand row
- * with no per-side rows is linked by construction; four different `border-*`
- * shorthands compare by their structured parts, not their full text.
- */
+/** A lone shorthand row is linked by construction; per-side rows compare by structured parts. */
 function componentLinked(source, component) {
     const properties = sideProperties(component);
     const hasShorthandRow = findTokenRow(source.rows, borderProperty(component)) !== null;
@@ -83,7 +76,6 @@ export function readBorderEditor(source, { group }) {
         },
     };
 }
-/** Whether any side draws a visible line, including after stylesheet resets. */
 export function hasVisibleBorder(computed) {
     return BORDER_SIDES.some((side) => {
         const style = computed(borderProperty("style", side), "none").toLowerCase();
@@ -92,7 +84,6 @@ export function hasVisibleBorder(computed) {
         return !isZeroCssValue(computed(borderProperty("width", side), "0px"));
     });
 }
-/** Linking sides writes each component shorthand from the top side's values. */
 function linkSidesDeclarations(source) {
     const components = ["style", "width", "color"];
     return components.map((component) => ({

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

@@ -1,8 +1,4 @@
 import type { ValuePolicy } from "./valuePolicy.js";
 export declare const CSS_NUMBER_SOURCE = "[+-]?(?:(?:\\d+\\.?\\d*)|(?:\\.\\d+))(?:e[+-]?\\d+)?";
-/**
- * Completes a bare numeric entry with its property's default unit. This is a
- * commit-time formatter; it deliberately does not validate or reinterpret
- * arbitrary CSS supplied by the user.
- */
+/** Commit-time only; never validates or reinterprets arbitrary CSS input. */
 export declare function completeCssValue(rawValue: string, policy: ValuePolicy): string;

package/dist/inspector/styleEditors/completeCssValue.js

@@ -1,15 +1,7 @@
-// CSS <number>, including values such as .5 and 1e3. This intentionally only
-// matches the entire value: units, functions, keywords, and compound values
-// are all valid raw CSS and must be passed through unchanged.
-// Exported as a source fragment so other editors (e.g. nudgeValue) build
-// their number-aware patterns from the same single grammar definition.
+// Exported as a source fragment for reuse in nudgeValue; matches only a complete CSS <number>.
 export const CSS_NUMBER_SOURCE = "[+-]?(?:(?:\\d+\\.?\\d*)|(?:\\.\\d+))(?:e[+-]?\\d+)?";
 const BARE_NUMBER = new RegExp(`^(?:${CSS_NUMBER_SOURCE})$`, "i");
-/**
- * Completes a bare numeric entry with its property's default unit. This is a
- * commit-time formatter; it deliberately does not validate or reinterpret
- * arbitrary CSS supplied by the user.
- */
+/** Commit-time only; never validates or reinterprets arbitrary CSS input. */
 export function completeCssValue(rawValue, policy) {
     const value = rawValue.trim();
     if (!BARE_NUMBER.test(value) || Number(value) === 0) {
@@ -17,9 +9,7 @@ export function completeCssValue(rawValue, policy) {
     }
     if (policy.kind === "line-height") {
         const multiplier = Number(value);
-        // People commonly enter line-height as its CSS multiplier (1.6), while
-        // larger whole values conventionally represent a percentage (120). Keep
-        // both convenient forms while committing a single percentage value.
+        // Values up to 10 are multipliers (1.6); larger values are conventional percentages (120).
         if (multiplier > 0 && multiplier <= 10) {
             return `${formatPercentage(multiplier * 100)}%`;
         }

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

@@ -0,0 +1,20 @@
+import type { ResolvedProperty } from "../../css/model/index.js";
+import type { SelectionProperty } from "../inspection/selectionProperty.js";
+/**
+ * True when a row reports a value the inspector must treat as an expression,
+ * not as a token: raw CSS, a composite shorthand, an alpha modifier, or an
+ * authored color expression such as color-mix().
+ */
+export declare function isExpressionRow(row: ResolvedProperty | null): boolean;
+export interface ActiveTokenInput {
+    readonly row: ResolvedProperty | null;
+    readonly selectedProperty?: SelectionProperty | null;
+    /** A multi-element selection that disagrees on this property shows "Mixed" and no chip. */
+    readonly mixed: boolean;
+    /** The authored CSS value; a calc() expression suppresses the chip. */
+    readonly authored?: string;
+    /** A property-specific token name that outranks the row (opacity's token-backed value). */
+    readonly override?: string | null;
+}
+/** The token a field should show as active, or null when the value is not token-backed. */
+export declare function deriveActiveTokenName(input: ActiveTokenInput): string | null;

package/dist/inspector/styleEditors/fieldValue.js

@@ -0,0 +1,26 @@
+import { isCalcExpression } from "../../css/value-semantics/index.js";
+/**
+ * True when a row reports a value the inspector must treat as an expression,
+ * not as a token: raw CSS, a composite shorthand, an alpha modifier, or an
+ * authored color expression such as color-mix().
+ */
+export function isExpressionRow(row) {
+    return Boolean(row && (row.capability === "raw"
+        || row.capability === "composite"
+        || row.modifiers?.some((modifier) => modifier.kind === "alpha")
+        || row.color?.isExpression));
+}
+/** The token a field should show as active, or null when the value is not token-backed. */
+export function deriveActiveTokenName(input) {
+    const { row, selectedProperty, mixed, authored = "", override } = input;
+    if (mixed)
+        return null;
+    if (override)
+        return override;
+    if (isExpressionRow(row) || isCalcExpression(authored))
+        return null;
+    if (selectedProperty) {
+        return selectedProperty.token.kind === "common" ? selectedProperty.token.name : null;
+    }
+    return row?.tokenName ?? null;
+}

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

@@ -12,6 +12,6 @@ export interface GradientValue {
     stops: GradientStop[];
 }
 export declare function defaultGradient(): GradientValue;
-/** Parse editable computed gradients. Leave unsupported syntax in the CSS field. */
+/** Null for gradients the editor cannot represent; callers keep the raw CSS. */
 export declare function parseGradient(value: string): GradientValue | null;
 export declare function serializeGradient(gradient: GradientValue): string;

package/dist/inspector/styleEditors/gradientValue.js

@@ -16,7 +16,7 @@ function angleDegrees(value) {
         default: return number;
     }
 }
-/** Parse editable computed gradients. Leave unsupported syntax in the CSS field. */
+/** Null for gradients the editor cannot represent; callers keep the raw CSS. */
 export function parseGradient(value) {
     if (splitTopLevel(value, ",").length !== 1)
         return null;
@@ -35,7 +35,7 @@ export function parseGradient(value) {
             const direction = /^(to\s+(?:(?:left|right|top|bottom)(?:\s+|$)){1,2})/.exec(prelude)?.[0]?.trim();
             if (direction) {
                 const directions = { top: 0, "top right": 45, "right top": 45, right: 90, "bottom right": 135, "right bottom": 135, bottom: 180, "bottom left": 225, "left bottom": 225, left: 270, "top left": 315, "left top": 315 };
-                // Corner directions depend on the element's aspect ratio. Keep them as CSS.
+                // Corner directions depend on the element's aspect ratio; keep them as CSS.
                 if (direction.slice(3).includes(" "))
                     return null;
                 angle = directions[direction.slice(3)] ?? 180;
@@ -102,6 +102,7 @@ export function parseGradient(value) {
         }
         start = end;
     }
+    // SAFETY: interpolation above fills every null position, so each stop has a numeric position.
     return { type, repeating: Boolean(match[1]), angle, prelude, stops: stops };
 }
 export function serializeGradient(gradient) {

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

@@ -2,72 +2,32 @@ import type { ChangeRecord } from "../tokens/editActions.js";
 import { type EditTarget } from "../selection/editTarget.js";
 /** One grid axis of a grid item: `column` maps to grid-column-*, `row` to grid-row-*. */
 export type GridAxis = "column" | "row";
-/**
- * Alignment vocabulary for grid children. `default` defers to the container's
- * `justify-items` / `align-items` (authored as `auto`); `fill` is `stretch`.
- */
 export type GridChildAlignment = "auto" | "stretch" | "start" | "center" | "end";
 export interface GridAxisPlacement {
-    /** Authored or computed start line token: "auto", a line number, or a named line. */
     start: string;
-    /**
-     * Span when the placement is expressible as start + span N: the end side is
-     * `span N`, or both sides are definite positive line numbers. Null when the
-     * end side is auto, a negative line, or not derivable.
-     */
+    /** Expressible as start + span N; null when the end side is auto, negative, or underivable. */
     span: number | null;
 }
 export declare const GRID_CHILD_MAX_TRACKS = 12;
-/** Parses a `span N` end-side token into N. */
 export declare function parseSpanToken(value: string): number | null;
-/**
- * Reads one placement axis from authored CSS (preferred) falling back to
- * computed CSS, which stays correct even when the authored rule uses the
- * `grid-column` / `grid-row` shorthand.
- */
+/** Computed CSS stays correct even when the authored rule uses the grid-column/grid-row shorthand. */
 export declare function readGridAxisPlacement(el: HTMLElement, axis: GridAxis): GridAxisPlacement;
-/**
- * Commits one placement axis as managed longhands. The UI model is
- * "start line + span", so editing either side recomposes both:
- * a simple span is rewritten as `span N` (or `auto` for 1), while a negative
- * end line ("to the last line") and plain auto ends are preserved untouched.
- * `span: "keep"` re-commits the currently derived span, if any, so moving the
- * start line keeps the item's size.
- */
+/** `span: "keep"` re-commits the derived span so moving the start line keeps the item's size. */
 export declare function commitGridAxisPlacement(target: EditTarget, axis: GridAxis, commit: {
     start?: string;
     span?: number | "keep";
 }): ChangeRecord[];
-/**
- * Reads one self-alignment axis as a raw CSS token with `normal` mapped to
- * `stretch`: on grid items `normal` has stretch behavior (except replaced
- * elements), so labeling it "Parent default" would misdescribe the rendering
- * and re-committing `auto` for it could change the layout. `auto` alone means
- * the item defers to the container's `justify-items` / `align-items`.
- */
+/** `normal` maps to `stretch`: that is its grid-item behavior, and re-committing `auto` would change layout. */
 export declare function readGridChildAlignment(el: HTMLElement, axis: "h" | "v"): string;
-/** Friendly alignment labels; `auto` resolves to the container's items alignment. */
 export declare const GRID_CHILD_ALIGNMENT_OPTIONS: Array<{
     value: GridChildAlignment;
     label: string;
 }>;
-/**
- * Commits one self-alignment axis. The alignment vocabulary is an open CSS
- * set — the friendly pickers cover the common keywords while authored values
- * such as `self-start` or `normal` round-trip verbatim — so this accepts any
- * self-alignment token the UI puts in its options.
- */
+/** Accepts any self-alignment token, not just the picker's keywords. */
 export declare function commitGridChildAlignment(target: EditTarget, axis: "h" | "v", alignment: string): ChangeRecord[];
-/**
- * Resolved track count of the parent grid on one axis, when CSS makes it
- * definite (auto-fill/auto-fit tracks cannot be counted). Caps at
- * GRID_CHILD_MAX_TRACKS to bound generated line options.
- */
+/** Null for auto-fill/auto-fit tracks, which CSS leaves indefinite. */
 export declare function parentTrackCount(el: HTMLElement, axis: GridAxis): number | null;
-/**
- * Start-line options for one axis: Auto plus explicit line numbers. A grid
- * with N tracks has N+1 lines, so the final start line is count + 1.
- */
+/** A grid with N tracks has N+1 start lines. */
 export declare function startLineOptions(trackCount: number | null): Array<{
     value: string;
     label: string;

package/dist/inspector/styleEditors/gridChildModel.js

@@ -12,16 +12,11 @@ function normalizeToken(value) {
 function isLineNumber(value) {
     return LINE_NUMBER.test(value);
 }
-/** Parses a `span N` end-side token into N. */
 export function parseSpanToken(value) {
     const match = SPAN_TOKEN.exec(value.trim());
     return match ? Number(match[1]) : null;
 }
-/**
- * Reads one placement axis from authored CSS (preferred) falling back to
- * computed CSS, which stays correct even when the authored rule uses the
- * `grid-column` / `grid-row` shorthand.
- */
+/** Computed CSS stays correct even when the authored rule uses the grid-column/grid-row shorthand. */
 export function readGridAxisPlacement(el, axis) {
     const start = getLayoutValue(el, `grid-${axis}-start`);
     const end = getLayoutValue(el, `grid-${axis}-end`);
@@ -42,14 +37,7 @@ export function readGridAxisPlacement(el, axis) {
     }
     return { start: startToken, span };
 }
-/**
- * Commits one placement axis as managed longhands. The UI model is
- * "start line + span", so editing either side recomposes both:
- * a simple span is rewritten as `span N` (or `auto` for 1), while a negative
- * end line ("to the last line") and plain auto ends are preserved untouched.
- * `span: "keep"` re-commits the currently derived span, if any, so moving the
- * start line keeps the item's size.
- */
+/** `span: "keep"` re-commits the derived span so moving the start line keeps the item's size. */
 export function commitGridAxisPlacement(target, axis, commit) {
     const elements = targetElements(target);
     const declarations = [];
@@ -77,20 +65,13 @@ export function commitGridAxisPlacement(target, axis, commit) {
         declarations.push({ property: `grid-${axis}-end`, value: endValue });
     return declarations.length > 0 ? setStyles(target, declarations) : [];
 }
-/**
- * Reads one self-alignment axis as a raw CSS token with `normal` mapped to
- * `stretch`: on grid items `normal` has stretch behavior (except replaced
- * elements), so labeling it "Parent default" would misdescribe the rendering
- * and re-committing `auto` for it could change the layout. `auto` alone means
- * the item defers to the container's `justify-items` / `align-items`.
- */
+/** `normal` maps to `stretch`: that is its grid-item behavior, and re-committing `auto` would change layout. */
 export function readGridChildAlignment(el, axis) {
     const property = axis === "h" ? "justify-self" : "align-self";
     const value = getLayoutValue(el, property);
     const token = normalizeToken(value.authored ?? value.computed);
     return token === "normal" ? "stretch" : token;
 }
-/** Friendly alignment labels; `auto` resolves to the container's items alignment. */
 export const GRID_CHILD_ALIGNMENT_OPTIONS = [
     { value: "auto", label: "Parent default" },
     { value: "stretch", label: "Fill" },
@@ -98,22 +79,13 @@ export const GRID_CHILD_ALIGNMENT_OPTIONS = [
     { value: "center", label: "Center" },
     { value: "end", label: "End" },
 ];
-/**
- * Commits one self-alignment axis. The alignment vocabulary is an open CSS
- * set — the friendly pickers cover the common keywords while authored values
- * such as `self-start` or `normal` round-trip verbatim — so this accepts any
- * self-alignment token the UI puts in its options.
- */
+/** Accepts any self-alignment token, not just the picker's keywords. */
 export function commitGridChildAlignment(target, axis, alignment) {
     const property = axis === "h" ? "justify-self" : "align-self";
     const record = setStyle(target, property, alignment);
     return record ? [record] : [];
 }
-/**
- * Resolved track count of the parent grid on one axis, when CSS makes it
- * definite (auto-fill/auto-fit tracks cannot be counted). Caps at
- * GRID_CHILD_MAX_TRACKS to bound generated line options.
- */
+/** Null for auto-fill/auto-fit tracks, which CSS leaves indefinite. */
 export function parentTrackCount(el, axis) {
     const parent = el.parentElement;
     if (!parent)
@@ -124,10 +96,7 @@ export function parentTrackCount(el, axis) {
         return null;
     return Math.min(count, GRID_CHILD_MAX_TRACKS);
 }
-/**
- * Start-line options for one axis: Auto plus explicit line numbers. A grid
- * with N tracks has N+1 lines, so the final start line is count + 1.
- */
+/** A grid with N tracks has N+1 start lines. */
 export function startLineOptions(trackCount) {
     const lineCount = (trackCount ?? GRID_CHILD_MAX_TRACKS) + 1;
     const options = [{ value: "auto", label: "Auto" }];

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

@@ -0,0 +1,5 @@
+/** True when anything the size expander hides differs from its initial value, so the toggle can flag it. */
+export declare function hasHiddenSizeOverrides(el: HTMLElement, parent: {
+    flexChild: boolean;
+    gridChild: boolean;
+}): boolean;