@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/utils/style-target.js

@@ -0,0 +1,203 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { mergeNodeSx, REUSABLE_INSTANCE_COMPONENT_ID, STYLE_OVERRIDES_ROOT_KEY } from "@aglyn/aglyn";
+import { expandSxAliases } from "@aglyn/shared-data-enums";
+import isEqual from "lodash-es/isEqual.js";
+import { action, toJS } from "mobx";
+const isPlainRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * A node's `props.sx` — the SECOND sx record every node can carry
+ * (AGL-1346).
+ *
+ * `Leaf` composes `mergeSxProps(sx, props.sx, node.sx)` and MUI's array
+ * form lets later entries win, so `node.sx` shadows `props.sx` key by key
+ * — but only the keys it names. Everything `props.sx` sets and `node.sx`
+ * does not is rendering, unshadowed, and until this issue no panel could
+ * see it: the Styles panel read `node.sx` alone and reported "Margin:
+ * default on all four edges" over a `marginInline: auto` that was
+ * genuinely in the layout. Presets authored the record (`props: { sx: … }`)
+ * and nothing could unauthor it.
+ *
+ * Returned as a live read, undefined when the node carries no such record
+ * or carries a non-record one (an array/callback sx composes but does not
+ * merge).
+ */ function nodePropsSx(node) {
+    var _node_props;
+    const value = node == null ? void 0 : (_node_props = node.props) == null ? void 0 : _node_props['sx'];
+    return isPlainRecord(value) ? value : undefined;
+}
+/**
+ * What the panel SHOWS for a plain node: `props.sx` with `node.sx` merged
+ * over it — the same precedence the renderer applies, so the displayed
+ * value is the effective one (AGL-1346).
+ *
+ * `mergeNodeSx` is the house merge (AGL-1306): responsive breakpoint
+ * objects cascade mobile-first, `@scheme dark` and nested selector blocks
+ * merge key by key, plain properties replace. Reusing it is what keeps the
+ * panel's reading of a shadowed value identical to the graft's.
+ *
+ * A node with no `props.sx` — every node but the ones presets touched —
+ * gets `node.sx` back BY IDENTITY, so nothing downstream re-renders or
+ * re-computes because this function exists.
+ */ function composedNodeSx(node) {
+    const nodeSx = node == null ? void 0 : node.sx;
+    const propsSx = nodePropsSx(node);
+    if (!propsSx) return nodeSx;
+    if (nodeSx !== undefined && !isPlainRecord(nodeSx)) return nodeSx;
+    return mergeNodeSx(toJS(propsSx), toJS(nodeSx));
+}
+/**
+ * Splits the panel's write back across the two records (AGL-1346).
+ *
+ * The panel hands us the whole intended sx — it always builds `next` from
+ * `target.sx`, which is now the COMPOSED record — so a naive
+ * `node.sx = next` would copy every `props.sx` key up into `node.sx` on the
+ * first unrelated edit. That is the migration this issue explicitly does
+ * NOT want: the mega-menu panels keep their entire positioning
+ * (`position: absolute`, `top: 100%`, `zIndex: 1300`, `bgcolor`, `p`,
+ * `marginInline`) in `props.sx`, and re-emitting those declarations from a
+ * later slot changes shorthand/longhand resolution order. So the write is a
+ * DIFF against the composed baseline:
+ *
+ * - a key already in `node.sx` keeps its position there and takes the new
+ *   value (or goes, if the author cleared it);
+ * - a key whose new value is what `props.sx` already says is NOT copied up
+ *   — nothing changed, so nothing is written;
+ * - a key the author genuinely changed is appended to `node.sx`, where it
+ *   wins exactly as the Styles panel's output has always won;
+ * - a key the author CLEARED is deleted from `props.sx` as well, which is
+ *   the half that makes the panel able to unauthor what a preset wrote.
+ *
+ * That last rule is why this edits `props.sx` in place rather than writing
+ * a neutralising override: there is no value that reliably means "no
+ * declaration" across sx keys — `unset`/`revert` are cascade keywords with
+ * their own meaning, and system props (`p`, `bgcolor`, `zIndex`) run
+ * through theme transforms first. Deleting the key is exact, and it is the
+ * only record involved when nothing shadows it.
+ *
+ * The invariant that makes this safe on 8,000 authored nodes: writing back
+ * an UNCHANGED composed record leaves both stored records byte-identical,
+ * key order included. Only a key the author actually touched moves.
+ */ function writeComposedNodeSx(node, next) {
+    const propsSx = nodePropsSx(node);
+    const current = node.sx;
+    if (!propsSx || current !== undefined && !isPlainRecord(current)) {
+        // No second record to reconcile (or an sx form that composes rather
+        // than merges): the write is what it always was.
+        node.sx = next != null ? next : {};
+        return;
+    }
+    const nextSx = next != null ? next : {};
+    // Both stored records are read in the panel's spelling (AGL-2207). The
+    // composed baseline the panel edits comes through `mergeNodeSx`, which
+    // canonicalizes MUI's system-prop aliases, so diffing against the RAW
+    // records would read every `p`/`bgcolor` as a key the author had just
+    // cleared and migrate the positioning on the first unrelated edit — the
+    // exact thing this function exists to prevent. Expanded, the byte-
+    // identical invariant holds; `props.sx` is only ever REWRITTEN below,
+    // when the author genuinely cleared one of its values.
+    const currentSx = expandSxAliases(isPlainRecord(current) ? toJS(current) : {}, {
+        deep: true
+    });
+    const propsRecord = expandSxAliases(toJS(propsSx), {
+        deep: true
+    });
+    const sx = {};
+    for (const key of Object.keys(currentSx)){
+        if (key in nextSx) sx[key] = nextSx[key];
+    }
+    for (const [key, value] of Object.entries(nextSx)){
+        if (key in sx) continue;
+        if (key in propsRecord && isEqual(propsRecord[key], value)) continue;
+        sx[key] = value;
+    }
+    node.sx = sx;
+    const cleared = Object.keys(propsRecord).filter((key)=>!(key in nextSx));
+    if (!cleared.length) return;
+    const remaining = _extends({}, propsRecord);
+    for (const key of cleared)delete remaining[key];
+    // Assigned as a fresh props object rather than mutated in place: the
+    // Attributes form reads `node.props` as its initial values, and a
+    // replaced reference is the signal it re-reads on (`updateNodeProps`
+    // replaces it too, for the same reason). Not routed through
+    // `updateNodeProps`, though — that records its own history entry, and
+    // this write is already inside the panel's coalesced `transact` step.
+    const props = _extends({}, toJS(node.props));
+    if (Object.keys(remaining).length) props['sx'] = remaining;
+    else delete props['sx'];
+    node.props = props;
+}
+/**
+ * The style target for a selected node — see {@link NodeStyleTarget}.
+ *
+ * `overrideKey` selects WHICH slice of an instance's overrides is edited;
+ * it is ignored for a plain node. A falsy key falls back to the root, so a
+ * caller that has not resolved a definition yet still edits something real
+ * rather than writing an `undefined`-keyed slice no renderer reads.
+ */ export function getNodeStyleTarget(node, overrideKey) {
+    const isInstance = (node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID;
+    if (!node || !isInstance) {
+        return {
+            isInstanceOverride: false,
+            overrideKey: '',
+            isLeafOverride: false,
+            get sx () {
+                // The COMPOSED record, not `node.sx` alone (AGL-1346) — see
+                // `composedNodeSx`. Identity is preserved when the node has no
+                // `props.sx`, which is every node but the handful presets touched.
+                return composedNodeSx(node);
+            },
+            setSx: action((next)=>{
+                if (!node) return;
+                writeComposedNodeSx(node, next);
+            })
+        };
+    }
+    // An instance's target is deliberately NOT composed with anything
+    // (AGL-1346): an override slice starts empty and empty MEANS "whatever
+    // the component does" (AGL-1338) — merging a base into the reading is
+    // exactly the distinction the override badge and the Background Fill
+    // control exist to keep. A `props.sx` on a definition node is shown and
+    // cleared where it lives, by selecting that node inside the component.
+    const key = overrideKey || STYLE_OVERRIDES_ROOT_KEY;
+    return {
+        isInstanceOverride: true,
+        overrideKey: key,
+        isLeafOverride: key !== STYLE_OVERRIDES_ROOT_KEY,
+        get sx () {
+            var _node_styleOverrides;
+            return (_node_styleOverrides = node.styleOverrides) == null ? void 0 : _node_styleOverrides[key];
+        },
+        setSx: action((next)=>{
+            var _node_styleOverrides;
+            const overrides = _extends({}, toJS((_node_styleOverrides = node.styleOverrides) != null ? _node_styleOverrides : {}));
+            if (next && Object.keys(next).length > 0) {
+                overrides[key] = next;
+            } else {
+                // An emptied override is REMOVED, not stored as `{}`: the panel's
+                // override badge and the graft's "has an override" check must both
+                // read a cleared instance as clean. Only THIS slice goes — the
+                // instance's other targets keep theirs.
+                delete overrides[key];
+            }
+            node.styleOverrides = Object.keys(overrides).length > 0 ? overrides : undefined;
+        })
+    };
+}
+export default getNodeStyleTarget;
+
+//# sourceMappingURL=style-target.js.map

package/src/lib/utils/style-target.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/style-target.ts"],"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 type * as Aglyn from '@aglyn/aglyn'\nimport {\n  mergeNodeSx,\n  REUSABLE_INSTANCE_COMPONENT_ID,\n  STYLE_OVERRIDES_ROOT_KEY,\n} from '@aglyn/aglyn'\nimport { expandSxAliases } from '@aglyn/shared-data-enums'\nimport isEqual from 'lodash-es/isEqual.js'\nimport { action, toJS } from 'mobx'\n\n/**\n * Where the Styles panel's edits land for the selected node (AGL-1306,\n * AGL-1332, AGL-1346).\n *\n * A plain node's edits read and write `node.sx`, exactly as they always\n * have. A reusable-component INSTANCE's edits read and write one slice of\n * `node.styleOverrides` instead — the root slice by default, or the slice\n * keyed by a DEFINITION-internal node id when the author has picked a leaf\n * inside the component. Either way the panel behaves like it does on a\n * fresh plain node (empty until this instance overrides something), and\n * the canvas/Preview/tenant render the override merged over the matching\n * component node via `composeReusableComponentNodes`. Mutating the\n * component itself from a placing document is exactly what this layer\n * exists to avoid — a leaf target styles the instance's copy of that leaf,\n * and never unlocks the component's content, which stays the component's.\n *\n * `sx` is a GETTER so observer components track the underlying MobX state\n * at read time; a snapshot captured when the target was built would go\n * stale after the first write.\n */\nexport interface NodeStyleTarget {\n  /**\n   * The sx record edits read from and write to (live view).\n   *\n   * For a plain node this is the COMPOSED record — `props.sx` with\n   * `node.sx` merged over it (AGL-1346) — so what the panel displays is\n   * what renders. Writes are split back across the two records by\n   * {@link writeComposedNodeSx}.\n   */\n  readonly sx: Record<string, any> | undefined\n  /** True when edits land in one of the instance's override slices. */\n  readonly isInstanceOverride: boolean\n  /**\n   * The `styleOverrides` key being edited — `root`, or a definition-internal\n   * node id. Empty string for a plain node, which has no override layer.\n   */\n  readonly overrideKey: string\n  /** True when the target is a leaf inside the component, not its root. */\n  readonly isLeafOverride: boolean\n  /** Replaces the target sx wholesale (MobX action inside). */\n  setSx(next: Record<string, any> | undefined): void\n}\n\nconst isPlainRecord = (value: unknown): value is Record<string, any> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * A node's `props.sx` — the SECOND sx record every node can carry\n * (AGL-1346).\n *\n * `Leaf` composes `mergeSxProps(sx, props.sx, node.sx)` and MUI's array\n * form lets later entries win, so `node.sx` shadows `props.sx` key by key\n * — but only the keys it names. Everything `props.sx` sets and `node.sx`\n * does not is rendering, unshadowed, and until this issue no panel could\n * see it: the Styles panel read `node.sx` alone and reported \"Margin:\n * default on all four edges\" over a `marginInline: auto` that was\n * genuinely in the layout. Presets authored the record (`props: { sx: … }`)\n * and nothing could unauthor it.\n *\n * Returned as a live read, undefined when the node carries no such record\n * or carries a non-record one (an array/callback sx composes but does not\n * merge).\n */\nfunction nodePropsSx(\n  node: Aglyn.NodeSchema<any> | null | undefined,\n): Record<string, any> | undefined {\n  const value = (node?.props as Record<string, any> | undefined)?.['sx']\n  return isPlainRecord(value) ? value : undefined\n}\n\n/**\n * What the panel SHOWS for a plain node: `props.sx` with `node.sx` merged\n * over it — the same precedence the renderer applies, so the displayed\n * value is the effective one (AGL-1346).\n *\n * `mergeNodeSx` is the house merge (AGL-1306): responsive breakpoint\n * objects cascade mobile-first, `@scheme dark` and nested selector blocks\n * merge key by key, plain properties replace. Reusing it is what keeps the\n * panel's reading of a shadowed value identical to the graft's.\n *\n * A node with no `props.sx` — every node but the ones presets touched —\n * gets `node.sx` back BY IDENTITY, so nothing downstream re-renders or\n * re-computes because this function exists.\n */\nfunction composedNodeSx(\n  node: Aglyn.NodeSchema<any> | null | undefined,\n): Record<string, any> | undefined {\n  const nodeSx = node?.sx as Record<string, any> | undefined\n  const propsSx = nodePropsSx(node)\n  if (!propsSx) return nodeSx\n  if (nodeSx !== undefined && !isPlainRecord(nodeSx)) return nodeSx\n  return mergeNodeSx(toJS(propsSx), toJS(nodeSx)) as Record<string, any>\n}\n\n/**\n * Splits the panel's write back across the two records (AGL-1346).\n *\n * The panel hands us the whole intended sx — it always builds `next` from\n * `target.sx`, which is now the COMPOSED record — so a naive\n * `node.sx = next` would copy every `props.sx` key up into `node.sx` on the\n * first unrelated edit. That is the migration this issue explicitly does\n * NOT want: the mega-menu panels keep their entire positioning\n * (`position: absolute`, `top: 100%`, `zIndex: 1300`, `bgcolor`, `p`,\n * `marginInline`) in `props.sx`, and re-emitting those declarations from a\n * later slot changes shorthand/longhand resolution order. So the write is a\n * DIFF against the composed baseline:\n *\n * - a key already in `node.sx` keeps its position there and takes the new\n *   value (or goes, if the author cleared it);\n * - a key whose new value is what `props.sx` already says is NOT copied up\n *   — nothing changed, so nothing is written;\n * - a key the author genuinely changed is appended to `node.sx`, where it\n *   wins exactly as the Styles panel's output has always won;\n * - a key the author CLEARED is deleted from `props.sx` as well, which is\n *   the half that makes the panel able to unauthor what a preset wrote.\n *\n * That last rule is why this edits `props.sx` in place rather than writing\n * a neutralising override: there is no value that reliably means \"no\n * declaration\" across sx keys — `unset`/`revert` are cascade keywords with\n * their own meaning, and system props (`p`, `bgcolor`, `zIndex`) run\n * through theme transforms first. Deleting the key is exact, and it is the\n * only record involved when nothing shadows it.\n *\n * The invariant that makes this safe on 8,000 authored nodes: writing back\n * an UNCHANGED composed record leaves both stored records byte-identical,\n * key order included. Only a key the author actually touched moves.\n */\nfunction writeComposedNodeSx(\n  node: Aglyn.NodeSchema<any>,\n  next: Record<string, any> | undefined,\n): void {\n  const propsSx = nodePropsSx(node)\n  const current = node.sx as Record<string, any> | undefined\n  if (!propsSx || (current !== undefined && !isPlainRecord(current))) {\n    // No second record to reconcile (or an sx form that composes rather\n    // than merges): the write is what it always was.\n    node.sx = (next ?? {}) as any\n    return\n  }\n  const nextSx = (next ?? {}) as Record<string, any>\n  // Both stored records are read in the panel's spelling (AGL-2207). The\n  // composed baseline the panel edits comes through `mergeNodeSx`, which\n  // canonicalizes MUI's system-prop aliases, so diffing against the RAW\n  // records would read every `p`/`bgcolor` as a key the author had just\n  // cleared and migrate the positioning on the first unrelated edit — the\n  // exact thing this function exists to prevent. Expanded, the byte-\n  // identical invariant holds; `props.sx` is only ever REWRITTEN below,\n  // when the author genuinely cleared one of its values.\n  const currentSx = expandSxAliases(\n    isPlainRecord(current) ? toJS(current) : {},\n    { deep: true },\n  )\n  const propsRecord = expandSxAliases(toJS(propsSx), { deep: true })\n\n  const sx: Record<string, any> = {}\n  for (const key of Object.keys(currentSx)) {\n    if (key in nextSx) sx[key] = nextSx[key]\n  }\n  for (const [key, value] of Object.entries(nextSx)) {\n    if (key in sx) continue\n    if (key in propsRecord && isEqual(propsRecord[key], value)) continue\n    sx[key] = value\n  }\n  node.sx = sx as any\n\n  const cleared = Object.keys(propsRecord).filter((key) => !(key in nextSx))\n  if (!cleared.length) return\n  const remaining = { ...propsRecord }\n  for (const key of cleared) delete remaining[key]\n  // Assigned as a fresh props object rather than mutated in place: the\n  // Attributes form reads `node.props` as its initial values, and a\n  // replaced reference is the signal it re-reads on (`updateNodeProps`\n  // replaces it too, for the same reason). Not routed through\n  // `updateNodeProps`, though — that records its own history entry, and\n  // this write is already inside the panel's coalesced `transact` step.\n  const props = { ...(toJS(node.props) as Record<string, any>) }\n  if (Object.keys(remaining).length) props['sx'] = remaining\n  else delete props['sx']\n  node.props = props as any\n}\n\n/**\n * The style target for a selected node — see {@link NodeStyleTarget}.\n *\n * `overrideKey` selects WHICH slice of an instance's overrides is edited;\n * it is ignored for a plain node. A falsy key falls back to the root, so a\n * caller that has not resolved a definition yet still edits something real\n * rather than writing an `undefined`-keyed slice no renderer reads.\n */\nexport function getNodeStyleTarget(\n  node: Aglyn.NodeSchema<any> | null | undefined,\n  overrideKey?: string | null,\n): NodeStyleTarget {\n  const isInstance =\n    node?.componentId === REUSABLE_INSTANCE_COMPONENT_ID\n  if (!node || !isInstance) {\n    return {\n      isInstanceOverride: false,\n      overrideKey: '',\n      isLeafOverride: false,\n      get sx() {\n        // The COMPOSED record, not `node.sx` alone (AGL-1346) — see\n        // `composedNodeSx`. Identity is preserved when the node has no\n        // `props.sx`, which is every node but the handful presets touched.\n        return composedNodeSx(node)\n      },\n      setSx: action((next: Record<string, any> | undefined) => {\n        if (!node) return\n        writeComposedNodeSx(node, next)\n      }),\n    }\n  }\n  // An instance's target is deliberately NOT composed with anything\n  // (AGL-1346): an override slice starts empty and empty MEANS \"whatever\n  // the component does\" (AGL-1338) — merging a base into the reading is\n  // exactly the distinction the override badge and the Background Fill\n  // control exist to keep. A `props.sx` on a definition node is shown and\n  // cleared where it lives, by selecting that node inside the component.\n  const key = overrideKey || STYLE_OVERRIDES_ROOT_KEY\n  return {\n    isInstanceOverride: true,\n    overrideKey: key,\n    isLeafOverride: key !== STYLE_OVERRIDES_ROOT_KEY,\n    get sx() {\n      return (node.styleOverrides as Record<string, any> | undefined)?.[key]\n    },\n    setSx: action((next: Record<string, any> | undefined) => {\n      const overrides: Record<string, any> = {\n        ...toJS(node.styleOverrides ?? {}),\n      }\n      if (next && Object.keys(next).length > 0) {\n        overrides[key] = next\n      } else {\n        // An emptied override is REMOVED, not stored as `{}`: the panel's\n        // override badge and the graft's \"has an override\" check must both\n        // read a cleared instance as clean. Only THIS slice goes — the\n        // instance's other targets keep theirs.\n        delete overrides[key]\n      }\n      node.styleOverrides =\n        Object.keys(overrides).length > 0 ? overrides : undefined\n    }),\n  }\n}\n\nexport default getNodeStyleTarget\n"],"names":["mergeNodeSx","REUSABLE_INSTANCE_COMPONENT_ID","STYLE_OVERRIDES_ROOT_KEY","expandSxAliases","isEqual","action","toJS","isPlainRecord","value","Array","isArray","nodePropsSx","node","props","undefined","composedNodeSx","nodeSx","sx","propsSx","writeComposedNodeSx","next","current","nextSx","currentSx","deep","propsRecord","key","Object","keys","entries","cleared","filter","length","remaining","getNodeStyleTarget","overrideKey","isInstance","componentId","isInstanceOverride","isLeafOverride","setSx","styleOverrides","overrides"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,WAAW,EACXC,8BAA8B,EAC9BC,wBAAwB,QACnB,eAAc;AACrB,SAASC,eAAe,QAAQ,2BAA0B;AAC1D,OAAOC,aAAa,uBAAsB;AAC1C,SAASC,MAAM,EAAEC,IAAI,QAAQ,OAAM;AA6CnC,MAAMC,gBAAgB,CAACC,QACrB,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACC,MAAMC,OAAO,CAACF;AAEhE;;;;;;;;;;;;;;;;CAgBC,GACD,SAASG,YACPC,IAA8C;QAE/BA;IAAf,MAAMJ,QAASI,yBAAAA,cAAAA,KAAMC,KAAK,qBAAZ,AAACD,WAAiD,CAAC,KAAK;IACtE,OAAOL,cAAcC,SAASA,QAAQM;AACxC;AAEA;;;;;;;;;;;;;CAaC,GACD,SAASC,eACPH,IAA8C;IAE9C,MAAMI,SAASJ,wBAAAA,KAAMK,EAAE;IACvB,MAAMC,UAAUP,YAAYC;IAC5B,IAAI,CAACM,SAAS,OAAOF;IACrB,IAAIA,WAAWF,aAAa,CAACP,cAAcS,SAAS,OAAOA;IAC3D,OAAOhB,YAAYM,KAAKY,UAAUZ,KAAKU;AACzC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,SAASG,oBACPP,IAA2B,EAC3BQ,IAAqC;IAErC,MAAMF,UAAUP,YAAYC;IAC5B,MAAMS,UAAUT,KAAKK,EAAE;IACvB,IAAI,CAACC,WAAYG,YAAYP,aAAa,CAACP,cAAcc,UAAW;QAClE,oEAAoE;QACpE,iDAAiD;QACjDT,KAAKK,EAAE,GAAIG,eAAAA,OAAQ,CAAC;QACpB;IACF;IACA,MAAME,SAAUF,eAAAA,OAAQ,CAAC;IACzB,uEAAuE;IACvE,uEAAuE;IACvE,sEAAsE;IACtE,sEAAsE;IACtE,wEAAwE;IACxE,mEAAmE;IACnE,sEAAsE;IACtE,uDAAuD;IACvD,MAAMG,YAAYpB,gBAChBI,cAAcc,WAAWf,KAAKe,WAAW,CAAC,GAC1C;QAAEG,MAAM;IAAK;IAEf,MAAMC,cAActB,gBAAgBG,KAAKY,UAAU;QAAEM,MAAM;IAAK;IAEhE,MAAMP,KAA0B,CAAC;IACjC,KAAK,MAAMS,OAAOC,OAAOC,IAAI,CAACL,WAAY;QACxC,IAAIG,OAAOJ,QAAQL,EAAE,CAACS,IAAI,GAAGJ,MAAM,CAACI,IAAI;IAC1C;IACA,KAAK,MAAM,CAACA,KAAKlB,MAAM,IAAImB,OAAOE,OAAO,CAACP,QAAS;QACjD,IAAII,OAAOT,IAAI;QACf,IAAIS,OAAOD,eAAerB,QAAQqB,WAAW,CAACC,IAAI,EAAElB,QAAQ;QAC5DS,EAAE,CAACS,IAAI,GAAGlB;IACZ;IACAI,KAAKK,EAAE,GAAGA;IAEV,MAAMa,UAAUH,OAAOC,IAAI,CAACH,aAAaM,MAAM,CAAC,CAACL,MAAQ,CAAEA,CAAAA,OAAOJ,MAAK;IACvE,IAAI,CAACQ,QAAQE,MAAM,EAAE;IACrB,MAAMC,YAAY,aAAKR;IACvB,KAAK,MAAMC,OAAOI,QAAS,OAAOG,SAAS,CAACP,IAAI;IAChD,qEAAqE;IACrE,kEAAkE;IAClE,qEAAqE;IACrE,4DAA4D;IAC5D,sEAAsE;IACtE,sEAAsE;IACtE,MAAMb,QAAQ,aAAMP,KAAKM,KAAKC,KAAK;IACnC,IAAIc,OAAOC,IAAI,CAACK,WAAWD,MAAM,EAAEnB,KAAK,CAAC,KAAK,GAAGoB;SAC5C,OAAOpB,KAAK,CAAC,KAAK;IACvBD,KAAKC,KAAK,GAAGA;AACf;AAEA;;;;;;;CAOC,GACD,OAAO,SAASqB,mBACdtB,IAA8C,EAC9CuB,WAA2B;IAE3B,MAAMC,aACJxB,CAAAA,wBAAAA,KAAMyB,WAAW,MAAKpC;IACxB,IAAI,CAACW,QAAQ,CAACwB,YAAY;QACxB,OAAO;YACLE,oBAAoB;YACpBH,aAAa;YACbI,gBAAgB;YAChB,IAAItB;gBACF,4DAA4D;gBAC5D,+DAA+D;gBAC/D,mEAAmE;gBACnE,OAAOF,eAAeH;YACxB;YACA4B,OAAOnC,OAAO,CAACe;gBACb,IAAI,CAACR,MAAM;gBACXO,oBAAoBP,MAAMQ;YAC5B;QACF;IACF;IACA,kEAAkE;IAClE,uEAAuE;IACvE,sEAAsE;IACtE,qEAAqE;IACrE,wEAAwE;IACxE,uEAAuE;IACvE,MAAMM,MAAMS,eAAejC;IAC3B,OAAO;QACLoC,oBAAoB;QACpBH,aAAaT;QACba,gBAAgBb,QAAQxB;QACxB,IAAIe;gBACML;YAAR,QAAQA,uBAAAA,KAAK6B,cAAc,qBAApB,AAAC7B,oBAAyD,CAACc,IAAI;QACxE;QACAc,OAAOnC,OAAO,CAACe;gBAEHR;YADV,MAAM8B,YAAiC,aAClCpC,MAAKM,uBAAAA,KAAK6B,cAAc,YAAnB7B,uBAAuB,CAAC;YAElC,IAAIQ,QAAQO,OAAOC,IAAI,CAACR,MAAMY,MAAM,GAAG,GAAG;gBACxCU,SAAS,CAAChB,IAAI,GAAGN;YACnB,OAAO;gBACL,kEAAkE;gBAClE,mEAAmE;gBACnE,+DAA+D;gBAC/D,wCAAwC;gBACxC,OAAOsB,SAAS,CAAChB,IAAI;YACvB;YACAd,KAAK6B,cAAc,GACjBd,OAAOC,IAAI,CAACc,WAAWV,MAAM,GAAG,IAAIU,YAAY5B;QACpD;IACF;AACF;AAEA,eAAeoB,mBAAkB"}

package/src/lib/utils/theme-scale-options.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @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 { PresetChoiceOption, ThemeScaleOption } from '@aglyn/shared-ui-jsx-forms';
+/**
+ * The theme scales the styles panel offers for Font Size, Font Weight and
+ * Z-Index (AGL-2486, item 12).
+ *
+ * Every option's `value` is a token path MUI's sx system resolves ITSELF —
+ * `fontSize` and `fontWeight` are declared with `themeKey: 'typography'` and
+ * `zIndex` with `themeKey: 'zIndex'`, so `h4.fontSize`, `fontWeightBold` and
+ * `appBar` behave exactly like `color: 'primary.main'` does. Nothing new has
+ * to resolve them and nothing downstream has to know these lists exist: the
+ * panel stores a string, the theme turns it into a number.
+ *
+ * They are built from the SITE theme rather than hardcoded, so a host that
+ * has retuned its type scale or added a z-index layer offers its own values,
+ * and the `hint` on each option is read out of that theme too — which is the
+ * only thing that makes `h4.fontSize` legible to an author.
+ */
+/** The subset of a theme these builders read. */
+export interface ThemeScaleSource {
+    typography?: Record<string, unknown>;
+    zIndex?: Record<string, unknown>;
+    /** A created theme exposes `spacing` as a FUNCTION (`spacing(2)` →
+     * `'16px'`); raw theme options carry the bare unit number. Both are
+     * accepted because both reach these builders. */
+    spacing?: ((factor: number) => string | number) | number;
+    /** `shape.borderRadius` — the unit a bare `borderRadius` number multiplies. */
+    shape?: {
+        borderRadius?: number | string;
+    };
+    /** `theme.shadows`, MUI's 25-entry elevation ladder. */
+    shadows?: ReadonlyArray<string>;
+}
+/** Font sizes from `theme.typography`, e.g. `h4.fontSize` → `2.125rem`. */
+export declare function buildFontSizeScaleOptions(theme: ThemeScaleSource | undefined): ThemeScaleOption[];
+export declare function buildFontWeightScaleOptions(theme: ThemeScaleSource | undefined): ThemeScaleOption[];
+/**
+ * Stacking layers from `theme.zIndex`, ordered by the layer they sit on
+ * rather than alphabetically — an author picking "above the app bar" is
+ * reading the stack, not the key names.
+ *
+ * This is the one of the three where a raw number is usually the WRONG
+ * answer: typing `1300` next to a modal the theme also puts at 1300 is a
+ * coin toss, and a host that re-tunes its layers leaves that number behind.
+ */
+export declare function buildZIndexScaleOptions(theme: ThemeScaleSource | undefined): ThemeScaleOption[];
+/**
+ * One rung of the theme's spacing ladder, as the box styler offers it
+ * (AGL-2486, item 5).
+ *
+ * **`value` is a NUMBER and that is the whole point.** MUI's sx system
+ * resolves a bare number on a spacing property through `theme.spacing`, so
+ * `marginTop: 2` renders 16px under `spacing: 8` and 8px under `spacing: 4`
+ * — it keeps following the theme exactly the way `h4.fontSize` and
+ * `primary.main` do. Storing the resolved `'16px'` instead would be wrong
+ * for the same reason a flattened colour is wrong: it stops tracking the
+ * theme the moment anyone retunes it.
+ *
+ * The numeric form is also the ONLY one that works. MUI multiplies numbers
+ * and passes strings through untouched, so the string `'2'` would reach the
+ * browser as `margin-top: 2` and be dropped by the CSS parser.
+ */
+export interface SpacingScaleOption {
+    /** The theme spacing STEP, stored as a number so MUI resolves it. */
+    value: number;
+    /** The author's name for it (`Medium`) — no CSS vocabulary required. */
+    label: string;
+    /** What it resolves to in this theme today (`16px`). */
+    hint: string;
+}
+/**
+ * The spacing ladder read off the SITE theme, so a host that set
+ * `spacing: 4` offers its own eight-step ladder rather than Aglyn's.
+ *
+ * A theme with no usable `spacing` yields an empty list, which leaves the
+ * styler on custom amounts only — never a ladder of numbers that resolve to
+ * nothing.
+ */
+export declare function buildSpacingScaleOptions(theme: ThemeScaleSource | undefined): SpacingScaleOption[];
+/** Every theme scale the style field groups need, built once per theme. */
+export interface StyleThemeScales {
+    fontSize: ThemeScaleOption[];
+    fontWeight: ThemeScaleOption[];
+    zIndex: ThemeScaleOption[];
+    /** The box styler's spacing ladder (AGL-2486, item 5). */
+    spacing: SpacingScaleOption[];
+    /** Corner-radius presets on the theme's shape scale (AGL-2486). */
+    cornerRadius: PresetChoiceOption[];
+    /** Drop-shadow presets named by what they look like (AGL-2486). */
+    shadow: PresetChoiceOption[];
+    /** The theme's own faces, then web-safe stacks (AGL-2486). */
+    fontFamily: PresetChoiceOption[];
+    /** Whole typography variants — `typography: 'h2'` (AGL-2486). */
+    typographyVariant: PresetChoiceOption[];
+    /** Grid/flex gaps on the theme's spacing ladder (AGL-2486). */
+    gap: PresetChoiceOption[];
+}
+export declare function buildStyleThemeScales(theme: ThemeScaleSource | undefined): StyleThemeScales;
+/** Corner-radius presets, with what each resolves to in THIS theme. */
+export declare function buildCornerRadiusChoices(theme: ThemeScaleSource | undefined): PresetChoiceOption[];
+export declare function buildShadowChoices(theme?: ThemeScaleSource | undefined): PresetChoiceOption[];
+/**
+ * Font-family choices: the SITE THEME's own faces first, then web-safe
+ *
+ * The old field was free text carrying the advice *"Prefer theme typography
+ * when possible"* — advice with no way to act on it. Leading with the
+ * theme's faces makes the recommended answer the first one in reach, and
+ * every row renders its own label in its own face so the choice can be made
+ * by looking.
+ *
+ * A theme face is stored as the resolved STACK rather than as a token path,
+ * because MUI declares `fontFamily` with `themeKey: 'typography'` and
+ * `typography.fontFamily` is the only path that resolves — `h1.fontFamily`
+ * does not. Duplicates are collapsed so a theme using one face everywhere
+ * offers it once.
+ */
+export declare function buildFontFamilyChoices(theme: ThemeScaleSource | undefined): PresetChoiceOption[];
+/**
+ * Whole text styles from `theme.typography` (AGL-2486).
+ *
+ * Every other control in this group sets ONE property, so matching a heading
+ * to the theme takes five correct picks in a row — face, size, weight, line
+ * height, letter spacing — and getting any of them wrong leaves text that
+ * looks almost right. `typography: 'h2'` is a single sx key that applies all
+ * of them at once, and it is the key MUI itself reaches for.
+ *
+ * Without this control a page can carry eleven headings at MUI's default `h2`
+ * — Light 300 at 60px — while every panel in the besigner reports nothing
+ * wrong: no field says "this is a Heading 2", only fields that say "this is
+ * 60px" once somebody types it.
+ *
+ * The hint names what the variant resolves to in THIS theme rather than in
+ * the abstract, because "Heading 2" means nothing until you know the host
+ * made it 40px semibold.
+ */
+export declare function buildTypographyVariantChoices(theme: ThemeScaleSource | undefined): PresetChoiceOption[];
+/**
+ * Grid and flex gaps on the theme's spacing ladder (AGL-2486).
+ *
+ * A free-text box for `gap`, `rowGap` or `columnGap` reads as a CSS length
+ * question and gets answered with one — but MUI runs all three through
+ * `createUnaryUnit(theme, 'spacing', …)`, exactly like margin and padding. So
+ * `gap: 2` is a theme multiple that follows a host retuning its unit, and
+ * `gap: '16px'` is a bespoke value that does not.
+ *
+ * These are the same rungs and the same labels the box styler offers for
+ * margin and padding, so the two controls agree; gaps only sit apart because
+ * they live in the Grid and Flex groups.
+ *
+ * A `PresetChoiceOption` rather than a `ThemeScaleOption` because the value
+ * STORED is a number and that interface is string-only — the same reason
+ * Corner Radius is a preset.
+ */
+export declare function buildGapChoices(theme: ThemeScaleSource | undefined): PresetChoiceOption[];