@aglyn/shared-ui-jsx-forms 1.0.0-beta.143

package/src/lib/mapper/css-dimension.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CssUnit } from '@aglyn/shared-data-enums';
+import { type FormFieldGridProps } from './form-field-grid';
+import type { ThemeScaleOption } from './theme-scale';
+import type { BaseFieldProps } from './types';
+/**
+ * CssDimension (AGL-1219): a number box plus a unit picker for anything
+ * holding a CSS length — an image's Width, a drawer's Width, a video
+ * block's Height, and every length in the styles panel's field groups.
+ * Authors used to type the whole string (`920px`) into a free-text field
+ * and were expected to remember the unit, while the box stylers right
+ * above them had a number+unit pair all along.
+ *
+ * The PERSISTED value is unchanged: still one CSS string (`"920px"`,
+ * `"100%"`, `"auto"`, `""`). This is purely an input affordance, so nothing
+ * downstream — renderers, published documents, existing nodes — has to know
+ * about it. The unit list is {@link CSS_UNITS} (the box styler's list), and
+ * parse/serialize is the shared pair in `@aglyn/shared-data-enums` so the
+ * two surfaces cannot drift.
+ *
+ * Values that are not `<number><unit>` — `calc(100% - 2rem)`, `min-content`,
+ * a `{{token}}` binding — must NOT be clobbered by an editor that cannot
+ * model them, so the field falls back to a plain text box holding the raw
+ * string. It flips back to number+unit the moment the text becomes a plain
+ * dimension again, which keeps the mode derived from the value rather than
+ * remembered in a flag that can go stale.
+ */
+/** Draft state: what the two controls show, before serialization. */
+interface DimensionDraft {
+    /** Numeric text (or the whole raw string in custom mode). */
+    text: string;
+    /** Selected unit, `''` when none is chosen. */
+    unit: CssUnit | '';
+    /** The value is not `<number><unit>` — the text box holds it verbatim. */
+    custom: boolean;
+}
+/**
+ * How a value stored as a bare NUMBER is to be read (AGL-1219). A node prop
+ * is plain CSS, so a number is pixels — the default.
+ *
+ * `'mui-sizing'` is for the styles panel's `sx` sizing keys, where a number
+ * is NOT pixels: MUI's `sizingTransform` renders any number in (0, 1] as a
+ * fraction of the parent, so `width: 0.5` is 50%. Read as pixels it would
+ * show "0.5" with no unit and the first nudge would turn a half-width
+ * element into a 0.6px one.
+ */
+export type DimensionNumberAs = 'px' | 'mui-sizing';
+/**
+ * The CSS string a stored value stands for — the only place a bare number
+ * is given its meaning. Mirrors MUI's `sizingTransform` for `'mui-sizing'`.
+ */
+export declare const dimensionValueToCss: (value: unknown, numberAs?: DimensionNumberAs) => string;
+export declare const seedDimensionDraft: (value: unknown, numberAs?: DimensionNumberAs) => DimensionDraft;
+export declare const serializeDimensionDraft: (draft: DimensionDraft) => string;
+export interface CssDimensionProps extends BaseFieldProps {
+    placeholder?: string;
+    /** Units offered; defaults to the full shared list. */
+    units?: CssUnit[];
+    /** How a bare number is read. See {@link DimensionNumberAs}. */
+    numberAs?: DimensionNumberAs;
+    /**
+     * Theme scale offered alongside the raw length (AGL-2486). Each option's
+     * `value` is a token path MUI's sx system resolves itself — `h4.fontSize`
+     * against `theme.typography` — so picking one keeps the element following
+     * the theme instead of freezing the number it had when it was styled. An
+     * empty list renders no scale menu at all.
+     */
+    scaleOptions?: ThemeScaleOption[];
+    /** Offer the reset-to-unset affordance (AGL-2486). */
+    clearable?: boolean;
+    FormFieldGridProps?: FormFieldGridProps;
+}
+export declare const CssDimensionField: (props: CssDimensionProps) => import("react").JSX.Element;
+export default CssDimensionField;

package/src/lib/mapper/css-dimension.js

@@ -0,0 +1,327 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { buildCssDimension, CSS_UNITS, CssUnit, isGlobalUnit, parseCssDimension } from "@aglyn/shared-data-enums";
+import { InputAdornment, MenuItem, Select, TextField as MuiTextField } from "@mui/material";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useFieldApi } from "../vendor/data-driven-forms.js";
+import FormFieldGrid, { buildFieldClear } from "./form-field-grid.js";
+import { validationError } from "./validation-error.js";
+/**
+ * The CSS string a stored value stands for — the only place a bare number
+ * is given its meaning. Mirrors MUI's `sizingTransform` for `'mui-sizing'`.
+ */ export const dimensionValueToCss = (value, numberAs = 'px')=>{
+    if (typeof value === 'string') return value;
+    if (typeof value !== 'number' || !Number.isFinite(value)) return '';
+    if (numberAs === 'mui-sizing' && value <= 1 && value !== 0) {
+        // `0.3 * 100` is 30.000000000000004 in binary floating point — MUI
+        // emits that verbatim; showing it in a number box would be absurd.
+        return `${Number((value * 100).toFixed(4))}%`;
+    }
+    return `${value}px`;
+};
+export const seedDimensionDraft = (value, numberAs = 'px')=>{
+    var _parsed_unit;
+    const parsed = parseCssDimension(dimensionValueToCss(value, numberAs));
+    if (parsed.raw !== undefined) {
+        return {
+            text: parsed.raw,
+            unit: '',
+            custom: true
+        };
+    }
+    return {
+        text: parsed.value === undefined ? '' : `${parsed.value}`,
+        unit: (_parsed_unit = parsed.unit) != null ? _parsed_unit : '',
+        custom: false
+    };
+};
+export const serializeDimensionDraft = (draft)=>{
+    if (draft.custom) return draft.text;
+    const trimmed = draft.text.trim();
+    return buildCssDimension({
+        value: trimmed === '' ? undefined : Number(trimmed),
+        unit: draft.unit || undefined
+    });
+};
+export const CssDimensionField = (props)=>{
+    const _useFieldApi = useFieldApi(props), { input, isReadOnly, isDisabled, isRequired, label, placeholder, helperText, description, validateOnMount, meta, help, units = CSS_UNITS, numberAs = 'px', scaleOptions = [], clearable, FormFieldGridProps = {}, // Free-text leftovers from the attribute schema that must never reach
+    // the DOM (the attributes it was authored with as a TEXT_FIELD).
+    inputProps: _inputProps, InputProps: _InputProps, multiline: _multiline } = _useFieldApi, rest = _object_without_properties_loose(_useFieldApi, [
+        "input",
+        "isReadOnly",
+        "isDisabled",
+        "isRequired",
+        "label",
+        "placeholder",
+        "helperText",
+        "description",
+        "validateOnMount",
+        "meta",
+        "help",
+        "units",
+        "numberAs",
+        "scaleOptions",
+        "clearable",
+        "FormFieldGridProps",
+        "inputProps",
+        "InputProps",
+        "multiline"
+    ]);
+    const invalid = validationError(meta, validateOnMount);
+    // A value authored as a bare number (`width: 320`, or `width: 0.5` in an
+    // sx) is still a value the author has to see — reading only strings would
+    // blank the field and then overwrite the number on the first edit. The
+    // number is resolved to the CSS it stands for HERE, not in the form value,
+    // so an untouched field still emits nothing and the stored number survives.
+    const value = dimensionValueToCss(input.value, numberAs);
+    const [draft, setDraft] = useState(()=>seedDimensionDraft(value));
+    // Re-seed only when the value changed OUTSIDE this field (a different
+    // node selected, an undo). Re-seeding from our own emits would round
+    // half-typed decimals ("1." -> 1 -> "1") out from under the caret.
+    const emittedRef = useRef(value);
+    useEffect(()=>{
+        if (value === emittedRef.current) return;
+        emittedRef.current = value;
+        setDraft(seedDimensionDraft(value));
+    }, [
+        value
+    ]);
+    const commit = useCallback((next)=>{
+        const serialized = serializeDimensionDraft(next);
+        emittedRef.current = serialized;
+        // A custom value the author edited back into a plain dimension gets
+        // the structured controls back immediately.
+        const reparsed = parseCssDimension(serialized);
+        setDraft(next.custom && serialized.trim() !== '' && reparsed.raw === undefined ? seedDimensionDraft(serialized) : next);
+        input.onChange(serialized);
+    }, [
+        input
+    ]);
+    const keywordUnit = !draft.custom && !!draft.unit && isGlobalUnit(draft.unit);
+    // Clearing a length has to drop the UNIT too (AGL-2486). Emptying the
+    // number box alone leaves `px` selected, and the next keystroke silently
+    // re-adopts it — which is why "delete the number" was never a way back to
+    // unset.
+    const clear = buildFieldClear({
+        clearable,
+        label,
+        hasValue: value !== '',
+        locked: Boolean(isDisabled || isReadOnly),
+        onClear: ()=>commit({
+                text: '',
+                unit: '',
+                custom: false
+            })
+    });
+    const handleTextChange = useCallback((event)=>{
+        const text = event.target.value;
+        // Typing a number into a field with no unit yet means pixels — a
+        // bare `320` is not a valid CSS length and silently did nothing
+        // when these were free-text fields.
+        const unit = !draft.custom && !draft.unit && text.trim() !== '' ? CssUnit.PIXELS : draft.unit;
+        commit(_extends({}, draft, {
+            text,
+            unit
+        }));
+    }, [
+        commit,
+        draft
+    ]);
+    const handleUnitChange = useCallback((event)=>{
+        const unit = event.target.value || '';
+        // Keyword units (`auto`) ARE the whole value, so the quantity goes
+        // away with them; it comes back when a real unit is picked again.
+        commit(_extends({}, draft, {
+            unit,
+            text: unit && isGlobalUnit(unit) ? '' : draft.text
+        }));
+    }, [
+        commit,
+        draft
+    ]);
+    // Theme scale alongside the raw length (AGL-2486, item 12). A token like
+    // `h4.fontSize` is not a `<number><unit>`, so the field already holds it
+    // fine — in custom mode, as raw text — and all that was missing was a way
+    // to PICK one. Rendered as its own menu rather than folded into the unit
+    // list because it does not choose a unit, it replaces the whole value:
+    // MUI's sx resolves `fontSize: 'h4.fontSize'` against `theme.typography`,
+    // which is what keeps the element following the type scale.
+    const activeScaleOption = scaleOptions.find((option)=>option.value === value);
+    const scaleSelect = scaleOptions.length ? /*#__PURE__*/ _jsx(InputAdornment, {
+        position: "end",
+        sx: {
+            ml: 0,
+            mr: 0.5
+        },
+        children: /*#__PURE__*/ _jsxs(Select, {
+            value: activeScaleOption ? activeScaleOption.value : '',
+            onChange: (event)=>{
+                var _event_target_value;
+                const picked = `${(_event_target_value = event.target.value) != null ? _event_target_value : ''}`;
+                // Empty means "back to a raw length"; the number box takes over
+                // again and the author is not stranded on a token they undid.
+                commit(picked ? {
+                    text: picked,
+                    unit: '',
+                    custom: true
+                } : {
+                    text: '',
+                    unit: '',
+                    custom: false
+                });
+            },
+            disabled: isDisabled || isReadOnly,
+            variant: "standard",
+            disableUnderline: true,
+            displayEmpty: true,
+            renderValue: ()=>activeScaleOption ? activeScaleOption.label : 'theme',
+            inputProps: {
+                'aria-label': 'Theme scale'
+            },
+            sx: {
+                '& .MuiSelect-select': {
+                    pr: '20px !important',
+                    py: 0,
+                    // The token label is the part that may be clipped when the
+                    // row is tight — never the value (AGL-2486).
+                    textOverflow: 'ellipsis'
+                },
+                fontSize: '0.8125rem',
+                color: 'text.secondary',
+                minWidth: 0,
+                maxWidth: 92
+            },
+            children: [
+                /*#__PURE__*/ _jsx(MenuItem, {
+                    value: "",
+                    children: /*#__PURE__*/ _jsx("em", {
+                        children: 'raw value'
+                    })
+                }),
+                scaleOptions.map((option)=>/*#__PURE__*/ _jsx(MenuItem, {
+                        value: option.value,
+                        children: option.hint ? `${option.label} — ${option.hint}` : option.label
+                    }, option.value))
+            ]
+        })
+    }) : null;
+    const unitSelect = /*#__PURE__*/ _jsx(InputAdornment, {
+        position: "end",
+        sx: {
+            ml: 0
+        },
+        children: /*#__PURE__*/ _jsxs(Select, {
+            value: draft.custom ? '' : draft.unit,
+            onChange: handleUnitChange,
+            disabled: isDisabled || isReadOnly || draft.custom,
+            variant: "standard",
+            disableUnderline: true,
+            // Without displayEmpty an unset unit renders nothing at all, which
+            // reads as a broken control rather than "no unit yet".
+            displayEmpty: true,
+            renderValue: (selected)=>draft.custom ? 'custom' : selected || '—',
+            inputProps: {
+                'aria-label': 'Unit'
+            },
+            sx: {
+                '& .MuiSelect-select': {
+                    pr: '20px !important',
+                    py: 0
+                },
+                fontSize: '0.8125rem',
+                color: 'text.secondary',
+                minWidth: 44,
+                flexShrink: 0
+            },
+            children: [
+                /*#__PURE__*/ _jsx(MenuItem, {
+                    value: "",
+                    children: /*#__PURE__*/ _jsx("em", {
+                        children: '—'
+                    })
+                }),
+                units.map((unit)=>/*#__PURE__*/ _jsx(MenuItem, {
+                        value: unit,
+                        children: unit
+                    }, unit))
+            ]
+        })
+    });
+    return /*#__PURE__*/ _jsx(FormFieldGrid, _extends({
+        help: help,
+        clear: clear
+    }, FormFieldGridProps, {
+        children: /*#__PURE__*/ _jsx(MuiTextField, _extends({}, rest, {
+            name: input.name,
+            value: keywordUnit ? '' : draft.text,
+            onChange: handleTextChange,
+            onBlur: input.onBlur,
+            onFocus: input.onFocus,
+            fullWidth: true,
+            error: !!invalid,
+            helperText: invalid || (meta.touched || validateOnMount) && meta.warning || helperText || description,
+            disabled: isDisabled,
+            label: label,
+            placeholder: keywordUnit ? `${draft.unit}` : placeholder,
+            required: isRequired,
+            // A keyword unit has no quantity to type, and a custom expression
+            // is free text — only the plain number+unit case is numeric.
+            type: draft.custom || keywordUnit ? 'text' : 'number',
+            slotProps: {
+                // A keyword value (`auto`) is shown through the PLACEHOLDER,
+                // and MUI hides a placeholder behind CSS while the label is
+                // un-shrunk — so the field printed its label over an empty box
+                // on a node that demonstrably had a value (AGL-2486). Only this
+                // case: an ordinary empty length has nothing to reveal, and
+                // shrinking it would be a restyle rather than a fix.
+                inputLabel: keywordUnit ? {
+                    shrink: true
+                } : undefined,
+                input: {
+                    readOnly: isReadOnly || keywordUnit,
+                    endAdornment: /*#__PURE__*/ _jsxs(_Fragment, {
+                        children: [
+                            scaleSelect,
+                            unitSelect
+                        ]
+                    })
+                },
+                /**
+           * The VALUE is never the control that gets squeezed (AGL-2486).
+           *
+           * The number box is the only part of this row with no width of
+           * its own — the two pickers are `endAdornment` siblings with
+           * fixed widths, so the input is whatever is left, and in a
+           * narrow docked panel that is a couple of characters: Font
+           * Size renders as `2.:`. A floor here makes the PICKERS give way
+           * instead, which is the right order — a clipped unit label is
+           * a nuisance, a clipped value is unreadable.
+           */ htmlInput: {
+                    inputMode: 'decimal',
+                    style: {
+                        minWidth: '4.5ch'
+                    }
+                }
+            }
+        }))
+    }));
+};
+export default CssDimensionField;
+
+//# sourceMappingURL=css-dimension.js.map

package/src/lib/mapper/css-dimension.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx-forms/src/lib/mapper/css-dimension.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  buildCssDimension,\n  CSS_UNITS,\n  CssUnit,\n  isGlobalUnit,\n  parseCssDimension,\n} from '@aglyn/shared-data-enums'\nimport {\n  InputAdornment,\n  MenuItem,\n  Select,\n  TextField as MuiTextField,\n} from '@mui/material'\nimport { useCallback, useEffect, useRef, useState } from 'react'\n\nimport { useFieldApi } from '../vendor/data-driven-forms'\nimport FormFieldGrid, {\n  buildFieldClear,\n  type FormFieldGridProps,\n} from './form-field-grid'\nimport type { ThemeScaleOption } from './theme-scale'\nimport type { BaseFieldProps } from './types'\nimport { type ExtendedFieldMeta, validationError } from './validation-error'\n\n/**\n * CssDimension (AGL-1219): a number box plus a unit picker for anything\n * holding a CSS length — an image's Width, a drawer's Width, a video\n * block's Height, and every length in the styles panel's field groups.\n * Authors used to type the whole string (`920px`) into a free-text field\n * and were expected to remember the unit, while the box stylers right\n * above them had a number+unit pair all along.\n *\n * The PERSISTED value is unchanged: still one CSS string (`\"920px\"`,\n * `\"100%\"`, `\"auto\"`, `\"\"`). This is purely an input affordance, so nothing\n * downstream — renderers, published documents, existing nodes — has to know\n * about it. The unit list is {@link CSS_UNITS} (the box styler's list), and\n * parse/serialize is the shared pair in `@aglyn/shared-data-enums` so the\n * two surfaces cannot drift.\n *\n * Values that are not `<number><unit>` — `calc(100% - 2rem)`, `min-content`,\n * a `{{token}}` binding — must NOT be clobbered by an editor that cannot\n * model them, so the field falls back to a plain text box holding the raw\n * string. It flips back to number+unit the moment the text becomes a plain\n * dimension again, which keeps the mode derived from the value rather than\n * remembered in a flag that can go stale.\n */\n\n/** Draft state: what the two controls show, before serialization. */\ninterface DimensionDraft {\n  /** Numeric text (or the whole raw string in custom mode). */\n  text: string\n  /** Selected unit, `''` when none is chosen. */\n  unit: CssUnit | ''\n  /** The value is not `<number><unit>` — the text box holds it verbatim. */\n  custom: boolean\n}\n\n/**\n * How a value stored as a bare NUMBER is to be read (AGL-1219). A node prop\n * is plain CSS, so a number is pixels — the default.\n *\n * `'mui-sizing'` is for the styles panel's `sx` sizing keys, where a number\n * is NOT pixels: MUI's `sizingTransform` renders any number in (0, 1] as a\n * fraction of the parent, so `width: 0.5` is 50%. Read as pixels it would\n * show \"0.5\" with no unit and the first nudge would turn a half-width\n * element into a 0.6px one.\n */\nexport type DimensionNumberAs = 'px' | 'mui-sizing'\n\n/**\n * The CSS string a stored value stands for — the only place a bare number\n * is given its meaning. Mirrors MUI's `sizingTransform` for `'mui-sizing'`.\n */\nexport const dimensionValueToCss = (\n  value: unknown,\n  numberAs: DimensionNumberAs = 'px',\n): string => {\n  if (typeof value === 'string') return value\n  if (typeof value !== 'number' || !Number.isFinite(value)) return ''\n  if (numberAs === 'mui-sizing' && value <= 1 && value !== 0) {\n    // `0.3 * 100` is 30.000000000000004 in binary floating point — MUI\n    // emits that verbatim; showing it in a number box would be absurd.\n    return `${Number((value * 100).toFixed(4))}%`\n  }\n  return `${value}px`\n}\n\nexport const seedDimensionDraft = (\n  value: unknown,\n  numberAs: DimensionNumberAs = 'px',\n): DimensionDraft => {\n  const parsed = parseCssDimension(dimensionValueToCss(value, numberAs))\n  if (parsed.raw !== undefined) {\n    return { text: parsed.raw, unit: '', custom: true }\n  }\n  return {\n    text: parsed.value === undefined ? '' : `${parsed.value}`,\n    unit: parsed.unit ?? '',\n    custom: false,\n  }\n}\n\nexport const serializeDimensionDraft = (draft: DimensionDraft): string => {\n  if (draft.custom) return draft.text\n  const trimmed = draft.text.trim()\n  return buildCssDimension({\n    value: trimmed === '' ? undefined : Number(trimmed),\n    unit: draft.unit || undefined,\n  })\n}\n\nexport interface CssDimensionProps extends BaseFieldProps {\n  placeholder?: string\n  /** Units offered; defaults to the full shared list. */\n  units?: CssUnit[]\n  /** How a bare number is read. See {@link DimensionNumberAs}. */\n  numberAs?: DimensionNumberAs\n  /**\n   * Theme scale offered alongside the raw length (AGL-2486). Each option's\n   * `value` is a token path MUI's sx system resolves itself — `h4.fontSize`\n   * against `theme.typography` — so picking one keeps the element following\n   * the theme instead of freezing the number it had when it was styled. An\n   * empty list renders no scale menu at all.\n   */\n  scaleOptions?: ThemeScaleOption[]\n  /** Offer the reset-to-unset affordance (AGL-2486). */\n  clearable?: boolean\n  FormFieldGridProps?: FormFieldGridProps\n}\n\nexport const CssDimensionField = (props: CssDimensionProps) => {\n  const {\n    input,\n    isReadOnly,\n    isDisabled,\n    isRequired,\n    label,\n    placeholder,\n    helperText,\n    description,\n    validateOnMount,\n    meta,\n    help,\n    units = CSS_UNITS,\n    numberAs = 'px',\n    scaleOptions = [],\n    clearable,\n    FormFieldGridProps = {},\n    // Free-text leftovers from the attribute schema that must never reach\n    // the DOM (the attributes it was authored with as a TEXT_FIELD).\n    inputProps: _inputProps,\n    InputProps: _InputProps,\n    multiline: _multiline,\n    ...rest\n  } = useFieldApi(props)\n  const invalid = validationError(meta as ExtendedFieldMeta, validateOnMount)\n  // A value authored as a bare number (`width: 320`, or `width: 0.5` in an\n  // sx) is still a value the author has to see — reading only strings would\n  // blank the field and then overwrite the number on the first edit. The\n  // number is resolved to the CSS it stands for HERE, not in the form value,\n  // so an untouched field still emits nothing and the stored number survives.\n  const value = dimensionValueToCss(input.value, numberAs)\n\n  const [draft, setDraft] = useState<DimensionDraft>(() =>\n    seedDimensionDraft(value),\n  )\n  // Re-seed only when the value changed OUTSIDE this field (a different\n  // node selected, an undo). Re-seeding from our own emits would round\n  // half-typed decimals (\"1.\" -> 1 -> \"1\") out from under the caret.\n  const emittedRef = useRef(value)\n  useEffect(() => {\n    if (value === emittedRef.current) return\n    emittedRef.current = value\n    setDraft(seedDimensionDraft(value))\n  }, [value])\n\n  const commit = useCallback(\n    (next: DimensionDraft) => {\n      const serialized = serializeDimensionDraft(next)\n      emittedRef.current = serialized\n      // A custom value the author edited back into a plain dimension gets\n      // the structured controls back immediately.\n      const reparsed = parseCssDimension(serialized)\n      setDraft(\n        next.custom && serialized.trim() !== '' && reparsed.raw === undefined\n          ? seedDimensionDraft(serialized)\n          : next,\n      )\n      input.onChange(serialized)\n    },\n    [input],\n  )\n\n  const keywordUnit = !draft.custom && !!draft.unit && isGlobalUnit(draft.unit)\n\n  // Clearing a length has to drop the UNIT too (AGL-2486). Emptying the\n  // number box alone leaves `px` selected, and the next keystroke silently\n  // re-adopts it — which is why \"delete the number\" was never a way back to\n  // unset.\n  const clear = buildFieldClear({\n    clearable,\n    label,\n    hasValue: value !== '',\n    locked: Boolean(isDisabled || isReadOnly),\n    onClear: () => commit({ text: '', unit: '', custom: false }),\n  })\n\n  const handleTextChange = useCallback(\n    (event: { target: { value: string } }) => {\n      const text = event.target.value\n      // Typing a number into a field with no unit yet means pixels — a\n      // bare `320` is not a valid CSS length and silently did nothing\n      // when these were free-text fields.\n      const unit =\n        !draft.custom && !draft.unit && text.trim() !== ''\n          ? CssUnit.PIXELS\n          : draft.unit\n      commit({ ...draft, text, unit })\n    },\n    [commit, draft],\n  )\n\n  const handleUnitChange = useCallback(\n    (event: { target: { value: unknown } }) => {\n      const unit = (event.target.value || '') as CssUnit | ''\n      // Keyword units (`auto`) ARE the whole value, so the quantity goes\n      // away with them; it comes back when a real unit is picked again.\n      commit({ ...draft, unit, text: unit && isGlobalUnit(unit) ? '' : draft.text })\n    },\n    [commit, draft],\n  )\n\n  // Theme scale alongside the raw length (AGL-2486, item 12). A token like\n  // `h4.fontSize` is not a `<number><unit>`, so the field already holds it\n  // fine — in custom mode, as raw text — and all that was missing was a way\n  // to PICK one. Rendered as its own menu rather than folded into the unit\n  // list because it does not choose a unit, it replaces the whole value:\n  // MUI's sx resolves `fontSize: 'h4.fontSize'` against `theme.typography`,\n  // which is what keeps the element following the type scale.\n  const activeScaleOption = scaleOptions.find(\n    (option) => option.value === value,\n  )\n  const scaleSelect = scaleOptions.length ? (\n    <InputAdornment position=\"end\" sx={{ ml: 0, mr: 0.5 }}>\n      <Select\n        value={activeScaleOption ? activeScaleOption.value : ''}\n        onChange={(event) => {\n          const picked = `${event.target.value ?? ''}`\n          // Empty means \"back to a raw length\"; the number box takes over\n          // again and the author is not stranded on a token they undid.\n          commit(\n            picked\n              ? { text: picked, unit: '', custom: true }\n              : { text: '', unit: '', custom: false },\n          )\n        }}\n        disabled={isDisabled || isReadOnly}\n        variant=\"standard\"\n        disableUnderline\n        displayEmpty\n        renderValue={() =>\n          activeScaleOption ? activeScaleOption.label : 'theme'\n        }\n        inputProps={{ 'aria-label': 'Theme scale' }}\n        sx={{\n          '& .MuiSelect-select': {\n            pr: '20px !important',\n            py: 0,\n            // The token label is the part that may be clipped when the\n            // row is tight — never the value (AGL-2486).\n            textOverflow: 'ellipsis',\n          },\n          fontSize: '0.8125rem',\n          color: 'text.secondary',\n          minWidth: 0,\n          maxWidth: 92,\n        }}\n      >\n        <MenuItem value=\"\">\n          <em>{'raw value'}</em>\n        </MenuItem>\n        {scaleOptions.map((option) => (\n          <MenuItem key={option.value} value={option.value}>\n            {option.hint ? `${option.label} — ${option.hint}` : option.label}\n          </MenuItem>\n        ))}\n      </Select>\n    </InputAdornment>\n  ) : null\n\n  const unitSelect = (\n    <InputAdornment position=\"end\" sx={{ ml: 0 }}>\n      <Select\n        value={draft.custom ? '' : draft.unit}\n        onChange={handleUnitChange}\n        disabled={isDisabled || isReadOnly || draft.custom}\n        variant=\"standard\"\n        disableUnderline\n        // Without displayEmpty an unset unit renders nothing at all, which\n        // reads as a broken control rather than \"no unit yet\".\n        displayEmpty\n        renderValue={(selected) =>\n          draft.custom ? 'custom' : (selected as string) || '—'\n        }\n        inputProps={{ 'aria-label': 'Unit' }}\n        sx={{\n          '& .MuiSelect-select': { pr: '20px !important', py: 0 },\n          fontSize: '0.8125rem',\n          color: 'text.secondary',\n          minWidth: 44,\n          flexShrink: 0,\n        }}\n      >\n        <MenuItem value=\"\">\n          <em>{'—'}</em>\n        </MenuItem>\n        {units.map((unit) => (\n          <MenuItem key={unit} value={unit}>\n            {unit}\n          </MenuItem>\n        ))}\n      </Select>\n    </InputAdornment>\n  )\n\n  return (\n    <FormFieldGrid help={help} clear={clear} {...FormFieldGridProps}>\n      <MuiTextField\n        // Schema leftovers first: the controlled value/handlers below must\n        // win over anything the attribute was authored with.\n        {...rest}\n        name={input.name}\n        value={keywordUnit ? '' : draft.text}\n        onChange={handleTextChange}\n        onBlur={input.onBlur}\n        onFocus={input.onFocus}\n        fullWidth\n        error={!!invalid}\n        helperText={\n          invalid ||\n          ((meta.touched || validateOnMount) && meta.warning) ||\n          helperText ||\n          description\n        }\n        disabled={isDisabled}\n        label={label}\n        placeholder={keywordUnit ? `${draft.unit}` : placeholder}\n        required={isRequired}\n        // A keyword unit has no quantity to type, and a custom expression\n        // is free text — only the plain number+unit case is numeric.\n        type={draft.custom || keywordUnit ? 'text' : 'number'}\n        slotProps={{\n          // A keyword value (`auto`) is shown through the PLACEHOLDER,\n          // and MUI hides a placeholder behind CSS while the label is\n          // un-shrunk — so the field printed its label over an empty box\n          // on a node that demonstrably had a value (AGL-2486). Only this\n          // case: an ordinary empty length has nothing to reveal, and\n          // shrinking it would be a restyle rather than a fix.\n          inputLabel: keywordUnit ? { shrink: true } : undefined,\n          input: {\n            readOnly: isReadOnly || keywordUnit,\n            endAdornment: (\n              <>\n                {scaleSelect}\n                {unitSelect}\n              </>\n            ),\n          },\n          /**\n           * The VALUE is never the control that gets squeezed (AGL-2486).\n           *\n           * The number box is the only part of this row with no width of\n           * its own — the two pickers are `endAdornment` siblings with\n           * fixed widths, so the input is whatever is left, and in a\n           * narrow docked panel that is a couple of characters: Font\n           * Size renders as `2.:`. A floor here makes the PICKERS give way\n           * instead, which is the right order — a clipped unit label is\n           * a nuisance, a clipped value is unreadable.\n           */\n          htmlInput: {\n            inputMode: 'decimal',\n            style: { minWidth: '4.5ch' },\n          },\n        }}\n      />\n    </FormFieldGrid>\n  )\n}\n\nexport default CssDimensionField\n"],"names":["buildCssDimension","CSS_UNITS","CssUnit","isGlobalUnit","parseCssDimension","InputAdornment","MenuItem","Select","TextField","MuiTextField","useCallback","useEffect","useRef","useState","useFieldApi","FormFieldGrid","buildFieldClear","validationError","dimensionValueToCss","value","numberAs","Number","isFinite","toFixed","seedDimensionDraft","parsed","raw","undefined","text","unit","custom","serializeDimensionDraft","draft","trimmed","trim","CssDimensionField","props","input","isReadOnly","isDisabled","isRequired","label","placeholder","helperText","description","validateOnMount","meta","help","units","scaleOptions","clearable","FormFieldGridProps","inputProps","_inputProps","InputProps","_InputProps","multiline","_multiline","rest","invalid","setDraft","emittedRef","current","commit","next","serialized","reparsed","onChange","keywordUnit","clear","hasValue","locked","Boolean","onClear","handleTextChange","event","target","PIXELS","handleUnitChange","activeScaleOption","find","option","scaleSelect","length","position","sx","ml","mr","picked","disabled","variant","disableUnderline","displayEmpty","renderValue","pr","py","textOverflow","fontSize","color","minWidth","maxWidth","em","map","hint","unitSelect","selected","flexShrink","name","onBlur","onFocus","fullWidth","error","touched","warning","required","type","slotProps","inputLabel","shrink","readOnly","endAdornment","htmlInput","inputMode","style"],"mappings":"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"}

package/src/lib/mapper/css-gradient.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ColorPickerProps as AglynColorPickerProps } from '@aglyn/shared-ui-color-picker';
+import { type CssGradientStop, type CssGradientType } from '@aglyn/shared-data-enums';
+import { type FormFieldGridProps } from './form-field-grid';
+import type { BaseFieldProps } from './types';
+/**
+ * CssGradient (AGL-1331): the Background Fill editor.
+ *
+ * The Styles panel's Colors group offered *Text Color* and *Background
+ * Color* and nothing else, so a gradient could not be authored at all —
+ * and typing one into Background Color was accepted, stored as
+ * `background-color: linear-gradient(…)`, and dropped by the CSS parser
+ * with no error anywhere. This is the control that expresses the value,
+ * and `describeCssColorProblem` is the guard that stops the silent store;
+ * the two ship together on purpose.
+ *
+ * The PERSISTED value is ONE CSS string under `backgroundImage` — the same
+ * contract as `CssDimensionField`, so nothing downstream has to know
+ * this editor exists. A **Solid** fill writes the explicit keyword
+ * `none`, which paints no image and leaves the neighbouring Background
+ * Color field to do the job; the two never fight over one property.
+ * **Default** writes `''`, which clears the property entirely.
+ *
+ * Solid and Default are two states, not one (AGL-1338). Solid shipped as
+ * "write nothing" — and on a reusable-component INSTANCE, where the panel
+ * edits an override slice, writing nothing IS "no override": the field
+ * could not be used to take a gradient off one placement, because the
+ * absence it produced was indistinguishable from never having touched it.
+ * `none` is a value, so it merges over the component's gradient and wins.
+ *
+ * Stops bind to palette TOKENS or to literals, and a single gradient can
+ * mix them: the marketing CTA's endpoints are `primary.main` /
+ * `secondary.main` while its mid stop `#7A5CF0` has no token at all. A
+ * token stop persists as `var(--mui-palette-primary-main, #00B0FF)` and is
+ * substituted against the site theme by the node renderer
+ * (`resolvePaletteVarsSx`) — see that module for why the reference is not
+ * left to the browser.
+ *
+ * Anything the editor cannot model — `conic-gradient`, `to bottom right`,
+ * a comma-stacked image list — falls back to a free-text box holding the
+ * raw string, so no existing value is destroyed by an editor that cannot
+ * show it. The stacked case reaches that box only because `parseCssGradient`
+ * splits top-level layers first (AGL-1336); until it did, a tint over a
+ * photo opened in the STOP editor and the author's first edit deleted the
+ * photo.
+ */
+/**
+ * The CSS an explicit **Solid** fill persists — `background-image`'s own
+ * initial value, so it renders identically to no declaration at all while
+ * remaining a VALUE that can override an inherited one (AGL-1338).
+ */
+export declare const SOLID_FILL_VALUE = "none";
+/**
+ * What the fill-type switch offers. Three states, because "no gradient"
+ * and "no opinion" are different answers on a component instance:
+ *
+ * - `''` — unset: the property is not written at all. On a plain node
+ *   that is the browser default; in an instance's override slice it is
+ *   how "this instance does not override the fill" is stored, so the
+ *   component's own fill keeps painting.
+ * - `solid` — an explicit {@link SOLID_FILL_VALUE}: paint no image and
+ *   let Background Color show. A real value, so it beats a gradient the
+ *   component set.
+ * - `linear` / `radial` — the gradient the stop editor builds.
+ */
+type GradientFillType = '' | 'solid' | CssGradientType;
+interface GradientDraft {
+    fill: GradientFillType;
+    angle: string;
+    /** Radial centre, percent, as typed. Empty means CSS's default (centre). */
+    positionX: string;
+    positionY: string;
+    stops: CssGradientStop[];
+    /** The value is not a gradient this editor can model — held verbatim. */
+    raw?: string;
+}
+export declare const seedGradientDraft: (value: unknown) => GradientDraft;
+export declare const serializeGradientDraft: (draft: GradientDraft) => string;
+export interface CssGradientProps extends BaseFieldProps {
+    /** Swatches offered on the custom stage, same as the colour field. */
+    presetColors?: string[];
+    /**
+     * What the unset choice is called (AGL-1338). Defaults to the panel's
+     * usual `Default`; a caller editing a component instance's override
+     * slice says so, because there "unset" means the component's own fill
+     * keeps painting rather than nothing painting.
+     */
+    unsetLabel?: string;
+    /** Offer the reset-to-unset affordance (AGL-2486). */
+    clearable?: boolean;
+    ColorPickerProps?: Partial<AglynColorPickerProps>;
+    FormFieldGridProps?: FormFieldGridProps;
+}
+export declare const CssGradientField: (props: CssGradientProps) => import("react").JSX.Element;
+export default CssGradientField;