@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/responsive-typography-sx.js

@@ -0,0 +1,122 @@
+/**
+ * @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.
+ */ /**
+ * A Styles-panel font size must beat the theme's responsive type ramp.
+ *
+ * `createResponsiveTheme` finishes with MUI's `responsiveFontSizes`, which
+ * bakes a per-breakpoint `fontSize` into each ramped typography VARIANT as
+ * literal `@media (min-width:…px)` keys. Emotion serialises a style object's
+ * plain properties before its at-rules, and the variant is serialised before
+ * the `sx` prop, so the emitted rule for one element reads:
+ *
+ * ```css
+ * .css-x { font-size: 1.5625rem;  ……  font-size: 44px; }   ← variant, then sx
+ * @media (min-width:1536px) { .css-x { font-size: 2.125rem; } }  ← variant ramp
+ * ```
+ *
+ * Both declarations sit on the same class, so the LAST one wins — and the
+ * variant's ramp is last. An author who typed 44 into Font Size at "all
+ * screen sizes" got 34px on a desktop viewport, with nothing in the panel
+ * to explain it. The value was stored correctly and reported correctly; only
+ * the cascade disagreed.
+ *
+ * The canvas never showed the bug, which is why it survived: the besigner
+ * renders through `createDevicePinnedTheme`, which flattens every variant's
+ * media keys at the artboard width before the leaf mounts. So the ramp was
+ * already gone there and the author's value won — the editor and the
+ * published page genuinely disagreed.
+ *
+ * The fix is one line of cascade position, not a new precedence rule: a
+ * scalar `fontSize` is re-expressed as `{ xs: value }`. `xs` is `min-width:0`
+ * and therefore always matches, so the RESOLVED value is unchanged for every
+ * viewport; it simply moves the declaration out of the base block and into an
+ * at-rule that Emotion emits after the variant's, restoring "the author's
+ * explicit choice wins". A `fontSize` the author already scoped per
+ * breakpoint is left exactly as written — those breakpoints are a deliberate
+ * ramp of their own and already sort after the variant.
+ *
+ * Scoped to the sx object's TOP level — the element's own styles, which are
+ * the only ones competing with the element's own variant. A `fontSize` nested
+ * under a descendant selector (`'& .price': { fontSize: 12 }`) is left alone:
+ * it is not in that contest, and rewriting it would grow the stylesheet for
+ * nothing.
+ */ /**
+ * Typography properties `responsiveFontSizes` ramps, and therefore the ones
+ * whose author value can lose to a variant at-rule.
+ *
+ * `fontSize` alone: MUI's ramp only rewrites `fontSize`, and only aligns
+ * `lineHeight` when `disableAlign` is off AND the variant's line height is a
+ * unitless number — the console theme's ramped variants (h1–h3) all carry
+ * unitless line heights, and the emitted CSS carries no `line-height` inside
+ * the ramp's media queries. Adding properties here that the theme does not
+ * ramp would emit at-rules that change nothing.
+ */ export const RAMPED_TYPOGRAPHY_PROPERTIES = [
+    'fontSize'
+];
+/** MUI breakpoint keys, smallest first; `xs` is the always-matching base. */ const BREAKPOINT_KEYS = [
+    'xs',
+    'sm',
+    'md',
+    'lg',
+    'xl'
+];
+const isPlainObject = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is already an sx responsive object (`{ xs, md, … }`).
+ * Such a value is the author's own breakpoint ramp and is never rewritten.
+ */ const isResponsiveValue = (value)=>isPlainObject(value) && Object.keys(value).length > 0 && Object.keys(value).every((key)=>BREAKPOINT_KEYS.includes(key));
+/**
+ * Pins scalar ramped-typography values into the `xs` slice so they sort
+ * after the theme's variant ramp. Identity-preserving: an sx carrying no
+ * scalar `fontSize` comes back as the very same object, so the hot render
+ * path allocates nothing in the overwhelmingly common case.
+ */ export function pinRampedTypographySx(sx) {
+    if (Array.isArray(sx)) {
+        let changed = false;
+        const next = sx.map((entry)=>{
+            const pinned = pinRampedTypographySx(entry);
+            if (pinned !== entry) changed = true;
+            return pinned;
+        });
+        return changed ? next : sx;
+    }
+    // An sx callback is resolved by MUI with the theme; wrap it so its RESULT
+    // gets the same treatment the object form does.
+    if (typeof sx === 'function') {
+        const callback = sx;
+        return (...args)=>pinRampedTypographySx(callback(...args));
+    }
+    if (!isPlainObject(sx)) return sx;
+    let changed = false;
+    const out = {};
+    for (const [key, value] of Object.entries(sx)){
+        const ramped = RAMPED_TYPOGRAPHY_PROPERTIES.includes(key);
+        // Only a SCALAR needs moving. `null`/`undefined` are the panel's cleared
+        // state and must stay scalar so they keep meaning "let the theme decide".
+        if (ramped && value != null && !isPlainObject(value) && !Array.isArray(value) && typeof value !== 'function' && !isResponsiveValue(value)) {
+            out[key] = {
+                xs: value
+            };
+            changed = true;
+            continue;
+        }
+        out[key] = value;
+    }
+    return changed ? out : sx;
+}
+export default pinRampedTypographySx;
+
+//# sourceMappingURL=responsive-typography-sx.js.map

package/src/lib/app-utils/responsive-typography-sx.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/responsive-typography-sx.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\n/**\n * A Styles-panel font size must beat the theme's responsive type ramp.\n *\n * `createResponsiveTheme` finishes with MUI's `responsiveFontSizes`, which\n * bakes a per-breakpoint `fontSize` into each ramped typography VARIANT as\n * literal `@media (min-width:…px)` keys. Emotion serialises a style object's\n * plain properties before its at-rules, and the variant is serialised before\n * the `sx` prop, so the emitted rule for one element reads:\n *\n * ```css\n * .css-x { font-size: 1.5625rem;  ……  font-size: 44px; }   ← variant, then sx\n * @media (min-width:1536px) { .css-x { font-size: 2.125rem; } }  ← variant ramp\n * ```\n *\n * Both declarations sit on the same class, so the LAST one wins — and the\n * variant's ramp is last. An author who typed 44 into Font Size at \"all\n * screen sizes\" got 34px on a desktop viewport, with nothing in the panel\n * to explain it. The value was stored correctly and reported correctly; only\n * the cascade disagreed.\n *\n * The canvas never showed the bug, which is why it survived: the besigner\n * renders through `createDevicePinnedTheme`, which flattens every variant's\n * media keys at the artboard width before the leaf mounts. So the ramp was\n * already gone there and the author's value won — the editor and the\n * published page genuinely disagreed.\n *\n * The fix is one line of cascade position, not a new precedence rule: a\n * scalar `fontSize` is re-expressed as `{ xs: value }`. `xs` is `min-width:0`\n * and therefore always matches, so the RESOLVED value is unchanged for every\n * viewport; it simply moves the declaration out of the base block and into an\n * at-rule that Emotion emits after the variant's, restoring \"the author's\n * explicit choice wins\". A `fontSize` the author already scoped per\n * breakpoint is left exactly as written — those breakpoints are a deliberate\n * ramp of their own and already sort after the variant.\n *\n * Scoped to the sx object's TOP level — the element's own styles, which are\n * the only ones competing with the element's own variant. A `fontSize` nested\n * under a descendant selector (`'& .price': { fontSize: 12 }`) is left alone:\n * it is not in that contest, and rewriting it would grow the stylesheet for\n * nothing.\n */\n\n/**\n * Typography properties `responsiveFontSizes` ramps, and therefore the ones\n * whose author value can lose to a variant at-rule.\n *\n * `fontSize` alone: MUI's ramp only rewrites `fontSize`, and only aligns\n * `lineHeight` when `disableAlign` is off AND the variant's line height is a\n * unitless number — the console theme's ramped variants (h1–h3) all carry\n * unitless line heights, and the emitted CSS carries no `line-height` inside\n * the ramp's media queries. Adding properties here that the theme does not\n * ramp would emit at-rules that change nothing.\n */\nexport const RAMPED_TYPOGRAPHY_PROPERTIES = ['fontSize'] as const\n\n/** MUI breakpoint keys, smallest first; `xs` is the always-matching base. */\nconst BREAKPOINT_KEYS = ['xs', 'sm', 'md', 'lg', 'xl'] as const\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Whether a value is already an sx responsive object (`{ xs, md, … }`).\n * Such a value is the author's own breakpoint ramp and is never rewritten.\n */\nconst isResponsiveValue = (value: unknown): boolean =>\n  isPlainObject(value) &&\n  Object.keys(value).length > 0 &&\n  Object.keys(value).every((key) =>\n    (BREAKPOINT_KEYS as readonly string[]).includes(key),\n  )\n\n/**\n * Pins scalar ramped-typography values into the `xs` slice so they sort\n * after the theme's variant ramp. Identity-preserving: an sx carrying no\n * scalar `fontSize` comes back as the very same object, so the hot render\n * path allocates nothing in the overwhelmingly common case.\n */\nexport function pinRampedTypographySx<T>(sx: T): T {\n  if (Array.isArray(sx)) {\n    let changed = false\n    const next = sx.map((entry) => {\n      const pinned = pinRampedTypographySx(entry)\n      if (pinned !== entry) changed = true\n      return pinned\n    })\n    return (changed ? next : sx) as T\n  }\n  // An sx callback is resolved by MUI with the theme; wrap it so its RESULT\n  // gets the same treatment the object form does.\n  if (typeof sx === 'function') {\n    const callback = sx as (...args: unknown[]) => unknown\n    return ((...args: unknown[]) =>\n      pinRampedTypographySx(callback(...args))) as T\n  }\n  if (!isPlainObject(sx)) return sx\n\n  let changed = false\n  const out: Record<string, unknown> = {}\n  for (const [key, value] of Object.entries(sx)) {\n    const ramped = (\n      RAMPED_TYPOGRAPHY_PROPERTIES as readonly string[]\n    ).includes(key)\n    // Only a SCALAR needs moving. `null`/`undefined` are the panel's cleared\n    // state and must stay scalar so they keep meaning \"let the theme decide\".\n    if (\n      ramped &&\n      value != null &&\n      !isPlainObject(value) &&\n      !Array.isArray(value) &&\n      typeof value !== 'function' &&\n      !isResponsiveValue(value)\n    ) {\n      out[key] = { xs: value }\n      changed = true\n      continue\n    }\n    out[key] = value\n  }\n  return (changed ? out : sx) as T\n}\n\nexport default pinRampedTypographySx\n"],"names":["RAMPED_TYPOGRAPHY_PROPERTIES","BREAKPOINT_KEYS","isPlainObject","value","Array","isArray","isResponsiveValue","Object","keys","length","every","key","includes","pinRampedTypographySx","sx","changed","next","map","entry","pinned","callback","args","out","entries","ramped","xs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCC,GAED;;;;;;;;;;CAUC,GACD,OAAO,MAAMA,+BAA+B;IAAC;CAAW,CAAS;AAEjE,2EAA2E,GAC3E,MAAMC,kBAAkB;IAAC;IAAM;IAAM;IAAM;IAAM;CAAK;AAEtD,MAAMC,gBAAgB,CAACC,QACrB,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACC,MAAMC,OAAO,CAACF;AAEhE;;;CAGC,GACD,MAAMG,oBAAoB,CAACH,QACzBD,cAAcC,UACdI,OAAOC,IAAI,CAACL,OAAOM,MAAM,GAAG,KAC5BF,OAAOC,IAAI,CAACL,OAAOO,KAAK,CAAC,CAACC,MACxB,AAACV,gBAAsCW,QAAQ,CAACD;AAGpD;;;;;CAKC,GACD,OAAO,SAASE,sBAAyBC,EAAK;IAC5C,IAAIV,MAAMC,OAAO,CAACS,KAAK;QACrB,IAAIC,UAAU;QACd,MAAMC,OAAOF,GAAGG,GAAG,CAAC,CAACC;YACnB,MAAMC,SAASN,sBAAsBK;YACrC,IAAIC,WAAWD,OAAOH,UAAU;YAChC,OAAOI;QACT;QACA,OAAQJ,UAAUC,OAAOF;IAC3B;IACA,0EAA0E;IAC1E,gDAAgD;IAChD,IAAI,OAAOA,OAAO,YAAY;QAC5B,MAAMM,WAAWN;QACjB,OAAQ,CAAC,GAAGO,OACVR,sBAAsBO,YAAYC;IACtC;IACA,IAAI,CAACnB,cAAcY,KAAK,OAAOA;IAE/B,IAAIC,UAAU;IACd,MAAMO,MAA+B,CAAC;IACtC,KAAK,MAAM,CAACX,KAAKR,MAAM,IAAII,OAAOgB,OAAO,CAACT,IAAK;QAC7C,MAAMU,SAAS,AACbxB,6BACAY,QAAQ,CAACD;QACX,yEAAyE;QACzE,0EAA0E;QAC1E,IACEa,UACArB,SAAS,QACT,CAACD,cAAcC,UACf,CAACC,MAAMC,OAAO,CAACF,UACf,OAAOA,UAAU,cACjB,CAACG,kBAAkBH,QACnB;YACAmB,GAAG,CAACX,IAAI,GAAG;gBAAEc,IAAItB;YAAM;YACvBY,UAAU;YACV;QACF;QACAO,GAAG,CAACX,IAAI,GAAGR;IACb;IACA,OAAQY,UAAUO,MAAMR;AAC1B;AAEA,eAAeD,sBAAqB"}

package/src/lib/app-utils/reusable-component-keys.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @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.
+ */
+/**
+ * The persisted keys, id prefixes and prop names of a reusable-component
+ * instance.
+ *
+ * A separate module from the graft that reads them because these are the part
+ * every OTHER surface needs: the renderer reads the two visibility directives,
+ * the element-id helpers read the graft prefix, and the canvas reads the
+ * instance component id. `compose-reusable-components.ts` beside it is the
+ * composition itself — the graft, the prune, detach, and the reference walk —
+ * which only an authoring surface and the server-side compose ever run, and
+ * which a bundler cannot drop around a named import of one constant.
+ *
+ * Every value here is persisted in screen or component documents. Never
+ * rename one.
+ */
+/**
+ * Persisted component id of a reusable-component instance node. Persisted in
+ * screen documents — never rename (cf. `layoutSlot`, legacy `muiXxx` ids).
+ */
+export declare const REUSABLE_INSTANCE_COMPONENT_ID = "reusableInstance";
+/**
+ * Prop key on an instance node holding its per-instance prop values, keyed
+ * by declared prop name (AGL-1247).
+ *
+ * Nested under one key rather than spread across the instance's own props
+ * so a prop named `refId` or `name` cannot shadow the reference itself, and
+ * so the string-prop walkers (`resolveNodesBindings`, the sanitizers) skip
+ * the whole object — values reach a page only through the graft below.
+ */
+export declare const REUSABLE_INSTANCE_PROP_VALUES_KEY = "propValues";
+/**
+ * `styleOverrides` key addressing the component ROOT (AGL-1306). Persisted
+ * in screen documents — never rename. Component-internal node ids key the
+ * per-leaf overrides beside it (AGL-1332); the definition root is addressed
+ * by this constant rather than its id so the same override survives a
+ * republish that reroots the definition.
+ */
+export declare const STYLE_OVERRIDES_ROOT_KEY = "root";
+/**
+ * Node-level fields that ride from the instance onto the definition's root
+ * when the two collapse into one element (AGL-2521).
+ *
+ * These sit beside `sx` on the node, not in `props`, so no renderer spreads
+ * them at an element and carrying them costs nothing in the DOM. They are
+ * document state the author set on THIS placement: dropping them would make a
+ * composed map that is saved back lose every per-instance override.
+ */
+export declare const INSTANCE_CARRIED_NODE_FIELDS: readonly string[];
+/**
+ * Token namespace a definition uses to reference its own declared props:
+ * `{{prop.headline}}`. Mirrors `{{entry.*}}` and `{{host.*}}` so authors
+ * meet one token syntax, not a second one invented for components.
+ */
+export declare const COMPONENT_PROP_TOKEN_PREFIX = "prop.";
+/**
+ * Declared prop names must be plain identifiers (AGL-1247).
+ *
+ * Load-bearing rather than cosmetic, which is why it lives beside the
+ * storage contract instead of in whichever form happens to edit it: the
+ * Attributes panel names its field for the nested path
+ * `propValues.<name>`, and final-form splits that on dots — so a prop
+ * called `hero.title` would address a level that does not exist and its
+ * value would silently never reach the node. The editor that declares
+ * props and the panel that fills them in must agree on this, so they read
+ * the same constant.
+ */
+export declare const COMPONENT_PROP_NAME_PATTERN: RegExp;
+/**
+ * Prefix namespacing a grafted definition's node ids per instance, so the
+ * same definition can appear many times in one tree without id collisions.
+ */
+export declare const COMPONENT_NODE_ID_PREFIX = "cmp__";
+/**
+ * Node prop a definition sets to drop part of itself when a value is
+ * TRUTHY (AGL-1314) — the "hide the mockup" toggle: the hero's media
+ * column carries `hideIf: '{{prop.hideMedia}}'`, and a page that wants no
+ * illustration ticks one checkbox.
+ *
+ * Persisted in component documents — never rename.
+ */
+export declare const NODE_HIDE_IF_PROP = "hideIf";
+/**
+ * The other polarity (AGL-1314): drop the node when the value is FALSY.
+ *
+ * This is what keeps an unfinished CTA from shipping as a dead control. A
+ * button whose link is unset renders as a labelled thing you can tab to
+ * that goes nowhere — seven of them nearly shipped in the footer
+ * (AGL-1348). Binding `hideUnless: '{{prop.secondaryCtaLink}}'` on the
+ * button means "no destination, no button": the node is gone before any
+ * renderer sees it, so there is no anchor, no `<button>`, and no keyboard
+ * stop.
+ *
+ * Note what it is bound to: the AUTHORED prop value, never whether a
+ * screen id RESOLVES. Resolution happens later (`useLinkTarget`) against
+ * the screens map, and the map behind an ISR render is not the map behind
+ * the hydration that follows it — pruning on resolution would be the
+ * element-switch hazard AGL-1357 lints for, one level up the pipeline.
+ * Prop values ride in the page document, so server and client prune
+ * identically.
+ *
+ * Persisted in component documents — never rename.
+ */
+export declare const NODE_HIDE_UNLESS_PROP = "hideUnless";
+/**
+ * Instance props that move onto the definition's root when the two collapse
+ * into one element (AGL-2521).
+ *
+ * The universal directives, and only those: they are authored against "this
+ * placement", which after the collapse IS the root. Everything else an
+ * instance carries — `refId`, `name`, {@link REUSABLE_INSTANCE_PROP_VALUES_KEY},
+ * the override slices — is bookkeeping the graft has already consumed, and
+ * spreading it onto a real element is how `propvalues="[object Object]"`
+ * reached a published page once before (AGL-2486).
+ *
+ * Listed rather than derived by exclusion: a new instance-only prop must not
+ * start leaking onto every component's root because nobody remembered to add
+ * it to a deny-list.
+ */
+export declare const INSTANCE_CARRIED_PROPS: readonly string[];

package/src/lib/app-utils/reusable-component-keys.js

@@ -0,0 +1,140 @@
+/**
+ * @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 { NODE_ANIMATION_DELAY_PROP, NODE_ANIMATION_DURATION_PROP, NODE_ANIMATION_EASE_PROP, NODE_ANIMATION_PROP, NODE_ANIMATION_REPEAT_PROP, NODE_ANIMATION_STAGGER_PROP, NODE_ANIMATION_STAGGER_STEP_PROP, NODE_ANIMATION_TRIGGER_PROP } from "./element-animation.js";
+/**
+ * The persisted keys, id prefixes and prop names of a reusable-component
+ * instance.
+ *
+ * A separate module from the graft that reads them because these are the part
+ * every OTHER surface needs: the renderer reads the two visibility directives,
+ * the element-id helpers read the graft prefix, and the canvas reads the
+ * instance component id. `compose-reusable-components.ts` beside it is the
+ * composition itself — the graft, the prune, detach, and the reference walk —
+ * which only an authoring surface and the server-side compose ever run, and
+ * which a bundler cannot drop around a named import of one constant.
+ *
+ * Every value here is persisted in screen or component documents. Never
+ * rename one.
+ */ /**
+ * Persisted component id of a reusable-component instance node. Persisted in
+ * screen documents — never rename (cf. `layoutSlot`, legacy `muiXxx` ids).
+ */ export const REUSABLE_INSTANCE_COMPONENT_ID = 'reusableInstance';
+/**
+ * Prop key on an instance node holding its per-instance prop values, keyed
+ * by declared prop name (AGL-1247).
+ *
+ * Nested under one key rather than spread across the instance's own props
+ * so a prop named `refId` or `name` cannot shadow the reference itself, and
+ * so the string-prop walkers (`resolveNodesBindings`, the sanitizers) skip
+ * the whole object — values reach a page only through the graft below.
+ */ export const REUSABLE_INSTANCE_PROP_VALUES_KEY = 'propValues';
+/**
+ * `styleOverrides` key addressing the component ROOT (AGL-1306). Persisted
+ * in screen documents — never rename. Component-internal node ids key the
+ * per-leaf overrides beside it (AGL-1332); the definition root is addressed
+ * by this constant rather than its id so the same override survives a
+ * republish that reroots the definition.
+ */ export const STYLE_OVERRIDES_ROOT_KEY = 'root';
+/**
+ * Node-level fields that ride from the instance onto the definition's root
+ * when the two collapse into one element (AGL-2521).
+ *
+ * These sit beside `sx` on the node, not in `props`, so no renderer spreads
+ * them at an element and carrying them costs nothing in the DOM. They are
+ * document state the author set on THIS placement: dropping them would make a
+ * composed map that is saved back lose every per-instance override.
+ */ export const INSTANCE_CARRIED_NODE_FIELDS = [
+    'styleOverrides',
+    'attrOverrides'
+];
+/**
+ * Token namespace a definition uses to reference its own declared props:
+ * `{{prop.headline}}`. Mirrors `{{entry.*}}` and `{{host.*}}` so authors
+ * meet one token syntax, not a second one invented for components.
+ */ export const COMPONENT_PROP_TOKEN_PREFIX = 'prop.';
+/**
+ * Declared prop names must be plain identifiers (AGL-1247).
+ *
+ * Load-bearing rather than cosmetic, which is why it lives beside the
+ * storage contract instead of in whichever form happens to edit it: the
+ * Attributes panel names its field for the nested path
+ * `propValues.<name>`, and final-form splits that on dots — so a prop
+ * called `hero.title` would address a level that does not exist and its
+ * value would silently never reach the node. The editor that declares
+ * props and the panel that fills them in must agree on this, so they read
+ * the same constant.
+ */ export const COMPONENT_PROP_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Prefix namespacing a grafted definition's node ids per instance, so the
+ * same definition can appear many times in one tree without id collisions.
+ */ export const COMPONENT_NODE_ID_PREFIX = 'cmp__';
+/**
+ * Node prop a definition sets to drop part of itself when a value is
+ * TRUTHY (AGL-1314) — the "hide the mockup" toggle: the hero's media
+ * column carries `hideIf: '{{prop.hideMedia}}'`, and a page that wants no
+ * illustration ticks one checkbox.
+ *
+ * Persisted in component documents — never rename.
+ */ export const NODE_HIDE_IF_PROP = 'hideIf';
+/**
+ * The other polarity (AGL-1314): drop the node when the value is FALSY.
+ *
+ * This is what keeps an unfinished CTA from shipping as a dead control. A
+ * button whose link is unset renders as a labelled thing you can tab to
+ * that goes nowhere — seven of them nearly shipped in the footer
+ * (AGL-1348). Binding `hideUnless: '{{prop.secondaryCtaLink}}'` on the
+ * button means "no destination, no button": the node is gone before any
+ * renderer sees it, so there is no anchor, no `<button>`, and no keyboard
+ * stop.
+ *
+ * Note what it is bound to: the AUTHORED prop value, never whether a
+ * screen id RESOLVES. Resolution happens later (`useLinkTarget`) against
+ * the screens map, and the map behind an ISR render is not the map behind
+ * the hydration that follows it — pruning on resolution would be the
+ * element-switch hazard AGL-1357 lints for, one level up the pipeline.
+ * Prop values ride in the page document, so server and client prune
+ * identically.
+ *
+ * Persisted in component documents — never rename.
+ */ export const NODE_HIDE_UNLESS_PROP = 'hideUnless';
+/**
+ * Instance props that move onto the definition's root when the two collapse
+ * into one element (AGL-2521).
+ *
+ * The universal directives, and only those: they are authored against "this
+ * placement", which after the collapse IS the root. Everything else an
+ * instance carries — `refId`, `name`, {@link REUSABLE_INSTANCE_PROP_VALUES_KEY},
+ * the override slices — is bookkeeping the graft has already consumed, and
+ * spreading it onto a real element is how `propvalues="[object Object]"`
+ * reached a published page once before (AGL-2486).
+ *
+ * Listed rather than derived by exclusion: a new instance-only prop must not
+ * start leaking onto every component's root because nobody remembered to add
+ * it to a deny-list.
+ */ export const INSTANCE_CARRIED_PROPS = [
+    NODE_HIDE_IF_PROP,
+    NODE_HIDE_UNLESS_PROP,
+    NODE_ANIMATION_PROP,
+    NODE_ANIMATION_TRIGGER_PROP,
+    NODE_ANIMATION_DURATION_PROP,
+    NODE_ANIMATION_DELAY_PROP,
+    NODE_ANIMATION_REPEAT_PROP,
+    NODE_ANIMATION_EASE_PROP,
+    NODE_ANIMATION_STAGGER_PROP,
+    NODE_ANIMATION_STAGGER_STEP_PROP
+];
+
+//# sourceMappingURL=reusable-component-keys.js.map

package/src/lib/app-utils/reusable-component-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/reusable-component-keys.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 {\n  NODE_ANIMATION_DELAY_PROP,\n  NODE_ANIMATION_DURATION_PROP,\n  NODE_ANIMATION_EASE_PROP,\n  NODE_ANIMATION_PROP,\n  NODE_ANIMATION_REPEAT_PROP,\n  NODE_ANIMATION_STAGGER_PROP,\n  NODE_ANIMATION_STAGGER_STEP_PROP,\n  NODE_ANIMATION_TRIGGER_PROP,\n} from './element-animation'\n\n/**\n * The persisted keys, id prefixes and prop names of a reusable-component\n * instance.\n *\n * A separate module from the graft that reads them because these are the part\n * every OTHER surface needs: the renderer reads the two visibility directives,\n * the element-id helpers read the graft prefix, and the canvas reads the\n * instance component id. `compose-reusable-components.ts` beside it is the\n * composition itself — the graft, the prune, detach, and the reference walk —\n * which only an authoring surface and the server-side compose ever run, and\n * which a bundler cannot drop around a named import of one constant.\n *\n * Every value here is persisted in screen or component documents. Never\n * rename one.\n */\n\n/**\n * Persisted component id of a reusable-component instance node. Persisted in\n * screen documents — never rename (cf. `layoutSlot`, legacy `muiXxx` ids).\n */\nexport const REUSABLE_INSTANCE_COMPONENT_ID = 'reusableInstance'\n\n/**\n * Prop key on an instance node holding its per-instance prop values, keyed\n * by declared prop name (AGL-1247).\n *\n * Nested under one key rather than spread across the instance's own props\n * so a prop named `refId` or `name` cannot shadow the reference itself, and\n * so the string-prop walkers (`resolveNodesBindings`, the sanitizers) skip\n * the whole object — values reach a page only through the graft below.\n */\nexport const REUSABLE_INSTANCE_PROP_VALUES_KEY = 'propValues'\n\n/**\n * `styleOverrides` key addressing the component ROOT (AGL-1306). Persisted\n * in screen documents — never rename. Component-internal node ids key the\n * per-leaf overrides beside it (AGL-1332); the definition root is addressed\n * by this constant rather than its id so the same override survives a\n * republish that reroots the definition.\n */\nexport const STYLE_OVERRIDES_ROOT_KEY = 'root'\n\n/**\n * Node-level fields that ride from the instance onto the definition's root\n * when the two collapse into one element (AGL-2521).\n *\n * These sit beside `sx` on the node, not in `props`, so no renderer spreads\n * them at an element and carrying them costs nothing in the DOM. They are\n * document state the author set on THIS placement: dropping them would make a\n * composed map that is saved back lose every per-instance override.\n */\nexport const INSTANCE_CARRIED_NODE_FIELDS: readonly string[] = [\n  'styleOverrides',\n  'attrOverrides',\n]\n\n/**\n * Token namespace a definition uses to reference its own declared props:\n * `{{prop.headline}}`. Mirrors `{{entry.*}}` and `{{host.*}}` so authors\n * meet one token syntax, not a second one invented for components.\n */\nexport const COMPONENT_PROP_TOKEN_PREFIX = 'prop.'\n\n/**\n * Declared prop names must be plain identifiers (AGL-1247).\n *\n * Load-bearing rather than cosmetic, which is why it lives beside the\n * storage contract instead of in whichever form happens to edit it: the\n * Attributes panel names its field for the nested path\n * `propValues.<name>`, and final-form splits that on dots — so a prop\n * called `hero.title` would address a level that does not exist and its\n * value would silently never reach the node. The editor that declares\n * props and the panel that fills them in must agree on this, so they read\n * the same constant.\n */\nexport const COMPONENT_PROP_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/\n\n/**\n * Prefix namespacing a grafted definition's node ids per instance, so the\n * same definition can appear many times in one tree without id collisions.\n */\nexport const COMPONENT_NODE_ID_PREFIX = 'cmp__'\n\n/**\n * Node prop a definition sets to drop part of itself when a value is\n * TRUTHY (AGL-1314) — the \"hide the mockup\" toggle: the hero's media\n * column carries `hideIf: '{{prop.hideMedia}}'`, and a page that wants no\n * illustration ticks one checkbox.\n *\n * Persisted in component documents — never rename.\n */\nexport const NODE_HIDE_IF_PROP = 'hideIf'\n\n/**\n * The other polarity (AGL-1314): drop the node when the value is FALSY.\n *\n * This is what keeps an unfinished CTA from shipping as a dead control. A\n * button whose link is unset renders as a labelled thing you can tab to\n * that goes nowhere — seven of them nearly shipped in the footer\n * (AGL-1348). Binding `hideUnless: '{{prop.secondaryCtaLink}}'` on the\n * button means \"no destination, no button\": the node is gone before any\n * renderer sees it, so there is no anchor, no `<button>`, and no keyboard\n * stop.\n *\n * Note what it is bound to: the AUTHORED prop value, never whether a\n * screen id RESOLVES. Resolution happens later (`useLinkTarget`) against\n * the screens map, and the map behind an ISR render is not the map behind\n * the hydration that follows it — pruning on resolution would be the\n * element-switch hazard AGL-1357 lints for, one level up the pipeline.\n * Prop values ride in the page document, so server and client prune\n * identically.\n *\n * Persisted in component documents — never rename.\n */\nexport const NODE_HIDE_UNLESS_PROP = 'hideUnless'\n\n/**\n * Instance props that move onto the definition's root when the two collapse\n * into one element (AGL-2521).\n *\n * The universal directives, and only those: they are authored against \"this\n * placement\", which after the collapse IS the root. Everything else an\n * instance carries — `refId`, `name`, {@link REUSABLE_INSTANCE_PROP_VALUES_KEY},\n * the override slices — is bookkeeping the graft has already consumed, and\n * spreading it onto a real element is how `propvalues=\"[object Object]\"`\n * reached a published page once before (AGL-2486).\n *\n * Listed rather than derived by exclusion: a new instance-only prop must not\n * start leaking onto every component's root because nobody remembered to add\n * it to a deny-list.\n */\nexport const INSTANCE_CARRIED_PROPS: readonly string[] = [\n  NODE_HIDE_IF_PROP,\n  NODE_HIDE_UNLESS_PROP,\n  NODE_ANIMATION_PROP,\n  NODE_ANIMATION_TRIGGER_PROP,\n  NODE_ANIMATION_DURATION_PROP,\n  NODE_ANIMATION_DELAY_PROP,\n  NODE_ANIMATION_REPEAT_PROP,\n  NODE_ANIMATION_EASE_PROP,\n  NODE_ANIMATION_STAGGER_PROP,\n  NODE_ANIMATION_STAGGER_STEP_PROP,\n]\n"],"names":["NODE_ANIMATION_DELAY_PROP","NODE_ANIMATION_DURATION_PROP","NODE_ANIMATION_EASE_PROP","NODE_ANIMATION_PROP","NODE_ANIMATION_REPEAT_PROP","NODE_ANIMATION_STAGGER_PROP","NODE_ANIMATION_STAGGER_STEP_PROP","NODE_ANIMATION_TRIGGER_PROP","REUSABLE_INSTANCE_COMPONENT_ID","REUSABLE_INSTANCE_PROP_VALUES_KEY","STYLE_OVERRIDES_ROOT_KEY","INSTANCE_CARRIED_NODE_FIELDS","COMPONENT_PROP_TOKEN_PREFIX","COMPONENT_PROP_NAME_PATTERN","COMPONENT_NODE_ID_PREFIX","NODE_HIDE_IF_PROP","NODE_HIDE_UNLESS_PROP","INSTANCE_CARRIED_PROPS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,yBAAyB,EACzBC,4BAA4B,EAC5BC,wBAAwB,EACxBC,mBAAmB,EACnBC,0BAA0B,EAC1BC,2BAA2B,EAC3BC,gCAAgC,EAChCC,2BAA2B,QACtB,yBAAqB;AAE5B;;;;;;;;;;;;;;CAcC,GAED;;;CAGC,GACD,OAAO,MAAMC,iCAAiC,mBAAkB;AAEhE;;;;;;;;CAQC,GACD,OAAO,MAAMC,oCAAoC,aAAY;AAE7D;;;;;;CAMC,GACD,OAAO,MAAMC,2BAA2B,OAAM;AAE9C;;;;;;;;CAQC,GACD,OAAO,MAAMC,+BAAkD;IAC7D;IACA;CACD,CAAA;AAED;;;;CAIC,GACD,OAAO,MAAMC,8BAA8B,QAAO;AAElD;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,8BAA8B,2BAA0B;AAErE;;;CAGC,GACD,OAAO,MAAMC,2BAA2B,QAAO;AAE/C;;;;;;;CAOC,GACD,OAAO,MAAMC,oBAAoB,SAAQ;AAEzC;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAMC,wBAAwB,aAAY;AAEjD;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMC,yBAA4C;IACvDF;IACAC;IACAb;IACAI;IACAN;IACAD;IACAI;IACAF;IACAG;IACAC;CACD,CAAA"}

package/src/lib/app-utils/reusable-prop-values.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @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 { ReusableComponentIcon, ReusableComponentProp, ReusableComponentPropCondition, ReusableComponentPropRule } from '../foundation/definitions/platform.types';
+/**
+ * Whether a value says yes, no, or nothing at all.
+ *
+ * The spellings a visibility directive accepts, because the value travels the
+ * same textual path to get here: `false`, `'false'`, `'0'`, `'off'`, `'no'` and
+ * `''` all read as no. `undefined` means there is nothing to read — the value
+ * is absent, or is still an unsubstituted token.
+ *
+ * The unresolved-token case is deliberately "no opinion": a definition binding
+ * a prop nobody declared leaves `{{prop.ghost}}` in place verbatim (only
+ * declared names are substituted), and the literal string is neither obviously
+ * true nor obviously false. Treating it as either would let one typo blank a
+ * section of a live page.
+ */
+export declare function readYesNoValue(value: unknown): boolean | undefined;
+/**
+ * The icon an instance picked for an `icon` prop, or `undefined` when it
+ * picked none.
+ *
+ * Stored as a whole {@link ReusableComponentIcon} so the path travels with the
+ * id. A bare id — written by anything other than the Attributes panel — still
+ * counts as a pick; it simply arrives with no path to draw on a published
+ * page.
+ */
+export declare function readInstanceIconValue(value: unknown): ReusableComponentIcon | undefined;
+type DeclaredProp = Pick<ReusableComponentProp, 'name' | 'type' | 'options' | 'settings' | 'defaultValue' | 'defaultIconPath' | 'condition'>;
+/**
+ * What a stored value counts as for its property, or `undefined` where it set
+ * nothing.
+ *
+ * `''` is unset, so clearing a field hands the page back to the default. An
+ * icon pick is read whole. A list is a value only for a property that takes
+ * several, where a single stored answer counts as a list of one; any other
+ * object is unset too — the only object a property value is ever written as is
+ * an icon or a list, so one anywhere else is a value left behind when the
+ * property's type changed, and stringifying it would put `[object Object]` on
+ * the page.
+ */
+export declare function readReusablePropValue(value: unknown, prop: Pick<ReusableComponentProp, 'type' | 'options' | 'settings'> | null | undefined): unknown;
+/**
+ * What a property is worth where a page set nothing: its declared default,
+ * read the way a page's own value is read — an Icon's default as the pick it
+ * stands for, id and path together.
+ */
+export declare function reusablePropDefaultValue(prop: DeclaredProp | null | undefined): unknown;
+/**
+ * The value a property's condition rules compare, given what it is worth: a
+ * Yes / no as a real boolean, a number as a number, an icon as its id, and
+ * everything else as stored — so a rule written against the value a control
+ * shows matches the value the page stored, whatever spelling it was stored in.
+ */
+export declare function reusablePropConditionValue(prop: Pick<ReusableComponentProp, 'type' | 'options' | 'settings'> | null | undefined, value: unknown): unknown;
+/**
+ * The longest pattern a property condition may carry (AGL-2893) — the bound a
+ * marketplace declaration has always been held to.
+ */
+export declare const REUSABLE_PROP_PATTERN_MAX_LENGTH = 500;
+/**
+ * The longest value a condition's pattern is matched against (AGL-2893). The
+ * match is linear in the value, and this keeps the most a page can be made to
+ * spend on one rule to a few milliseconds; a longer value holds no pattern
+ * rule, the way a pattern that cannot be matched holds none.
+ */
+export declare const REUSABLE_PROP_PATTERN_INPUT_MAX_LENGTH = 2000;
+/**
+ * Why a condition's pattern cannot be matched on a page, or `undefined` when
+ * it can (AGL-2893).
+ *
+ * A condition is written by whoever declared the property — a marketplace
+ * publisher, a template, a document written without the Properties dialog —
+ * and matched on every page that places the component and in the console of
+ * everyone editing one. So a pattern is matched by a linear-time engine
+ * (`compileLinearTest`), never by `RegExp`: a backtracking matcher takes
+ * seconds on `^(a+)+$` against a 28-character value, and the time doubles
+ * with each character. No check of a pattern's shape can make `RegExp` safe —
+ * `^a*a*a*a*a*a*a*a*$` nests no quantifier and takes a minute on 61
+ * characters — so the engine is the bound, not a heuristic.
+ *
+ * What it names: a pattern that is not text or is longer than
+ * {@link REUSABLE_PROP_PATTERN_MAX_LENGTH}; flags `RegExp` would refuse or the
+ * engine does not implement (`u`, `v`); syntax outside the engine's subset
+ * (lookaround, backreferences, named groups); and anything
+ * `RegExp` itself refuses. One answer for the Properties dialog, every
+ * server-side write of a declaration, and the evaluator below.
+ */
+export declare function reusablePropPatternProblem(pattern: unknown, flags?: unknown): string | undefined;
+/**
+ * Whether a value matches a condition's pattern — what
+ * `new RegExp(pattern, flags).test(value)` answers — or `undefined` when the
+ * pattern cannot be matched safely (see {@link reusablePropPatternProblem}) or
+ * the value is longer than {@link REUSABLE_PROP_PATTERN_INPUT_MAX_LENGTH}.
+ * Never throws.
+ */
+export declare function matchReusablePropPattern(pattern: unknown, flags: unknown, value: unknown): boolean | undefined;
+/**
+ * One rule against the value it names, with data-driven-forms' own precedence
+ * — the same order `parseCondition` applies, which a spec runs both against so
+ * the Attributes panel and a published page can never disagree.
+ *
+ * A pattern rule whose pattern cannot be matched safely, or whose value is too
+ * long to match, holds nothing — whichever way it reads the pattern — so the
+ * property renders as one whose condition is unmet (AGL-2893). A throw here
+ * used to reach the tenant loader's catch and turn every page placing the
+ * component into a 404.
+ */
+export declare function evaluateReusablePropRule(rule: Omit<ReusableComponentPropRule, 'when'>, value: unknown): boolean;
+/**
+ * Whether a condition holds against the values its rules name.
+ *
+ * A list must all hold, `and` must all hold, `or` needs one, `not` negates —
+ * data-driven-forms' `parseCondition`, minus what a stored document cannot
+ * carry. A shape it does not recognize holds nothing, which is also what
+ * `parseCondition` answers for a rule with no `when`.
+ */
+export declare function evaluateReusablePropCondition(condition: ReusableComponentPropCondition | ReusableComponentPropCondition[] | null | undefined, values: Readonly<Record<string, unknown>>): boolean;
+/**
+ * Declared properties as a server-side write stores them: each condition
+ * without the rules whose pattern cannot be matched, and a property whose
+ * condition is left with nothing stored with none (AGL-2893). Anything that is
+ * not a list of declarations comes back as it was, as does a list with nothing
+ * to remove.
+ *
+ * The page never needs this — a rule it cannot match holds nothing there — but
+ * a stored declaration is read by the Properties dialog, copied by templates
+ * and published to the marketplace, and a pattern that can never be matched
+ * should stop there rather than travel.
+ */
+export declare function withMatchableConditions<T>(props: T): T;
+/** Every property's value for one page, in the three forms the graft reads. */
+export interface ResolvedReusablePropValues {
+    /** `prop.<name>` → the text each `{{prop.<name>}}` substitutes as. */
+    tokens: Record<string, string>;
+    /**
+     * Name → what a field bound to exactly that token receives, before its kind
+     * finishes it; absent where the property has nothing to give.
+     */
+    values: Record<string, unknown>;
+    /** Name → the SVG path an Icon property's pick or default draws with. */
+    iconPaths: Record<string, string>;
+    /** The names whose condition does not hold on this page. */
+    off: Set<string>;
+}
+/**
+ * What each declared property is worth on one page.
+ *
+ * `values` is the page's own map — an instance's `propValues`, or a screen's
+ * values for its layout — and a property it leaves unset takes its default.
+ * A property whose condition does not hold renders as one with no value and no
+ * default. Conditions compare what each property is worth before any condition
+ * applies, which is what the Attributes panel compares too, so a field and the
+ * page it sets agree.
+ *
+ * `defaultsOnly` is the editor's view of its own definition: a property with no
+ * default keeps its token, so a slot nothing fills stays visible.
+ */
+export declare function resolveReusablePropValues(declared: readonly DeclaredProp[] | null | undefined, values?: Readonly<Record<string, unknown>> | null, options?: {
+    defaultsOnly?: boolean;
+}): ResolvedReusablePropValues;
+/**
+ * Token map of a definition's OWN defaults, with no instance in the picture.
+ *
+ * What the component editor draws with (AGL-2870). A page substitutes an unset
+ * prop as `''`, which is right there — an unset prop renders nothing — and
+ * wrong here, where a prop with no default has nothing to preview and should
+ * keep showing its raw token so the author can see at a glance which slots are
+ * still unfilled.
+ *
+ * `false` and `0` are real defaults and survive; only `null`, `undefined` and
+ * `''` are treated as "no default set".
+ */
+export declare function buildComponentDefaultTokens(declared: readonly DeclaredProp[] | null | undefined): Record<string, string>;
+/**
+ * The icon paths a definition's OWN defaults draw with — what the component
+ * editor shows beside {@link buildComponentDefaultTokens}.
+ */
+export declare function buildComponentDefaultIconPaths(declared: readonly DeclaredProp[] | null | undefined): Record<string, string>;
+/**
+ * The values a definition's OWN defaults hand their bound fields — what the
+ * component editor draws with beside {@link buildComponentDefaultTokens}.
+ */
+export declare function buildComponentDefaultValues(declared: readonly DeclaredProp[] | null | undefined): Record<string, unknown>;
+export {};