@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/element-animation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/element-animation.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 * Element animation vocabulary (AGL-2486) — the names the renderer, the\n * besigner attributes panel and the tenant's stylesheet all agree on.\n *\n * ## Why there is no animation runtime here\n *\n * Published pages ship no animation library, and that is the design, not a\n * phase one. Motion's smallest useful React surface (`LazyMotion` +\n * `domAnimation` + `m`) is ~17kB gzipped and the full `motion` import ~34kB —\n * against the 87,646 B gzipped that came OFF the published page the same week\n * this landed. What a site builder's authors actually reach for is entrance\n * and hover emphasis: fade, slide, zoom, played on load, on scroll-in or on\n * hover. Every one of those is `@keyframes` plus `transition`, which the\n * compositor runs off the main thread — including during hydration, which is\n * exactly when an entrance animation plays and exactly when a JS runtime is\n * least able to keep up. Spring physics, FLIP/layout animation and\n * gesture-driven interpolation are what a runtime would buy, and none of them\n * are authorable from a preset dropdown by the audience this is for.\n *\n * The single exception is the scroll trigger, which needs an\n * `IntersectionObserver`. That is ~700 bytes of inline script shipped in the\n * SSR HTML by `apps/tenant`, only on pages that actually carry a\n * scroll-triggered node — no module, no chunk, no extra request, and it\n * gzips with the document. See `@aglyn/tenant-runtime`'s\n * `element-animation-assets.ts` for the stylesheet and that script.\n *\n * This module is reachable from the client bundle (the renderer's `Leaf`\n * imports it), so it holds constants and two small pure functions and\n * nothing else. The stylesheet text deliberately lives in the server-only\n * module so a page that animates nothing pays literally zero bytes for it.\n */\n\n/** Preset id prop. Reserved node prop, stripped before the DOM spread. */\nexport const NODE_ANIMATION_PROP = 'aglynAnimation'\n/** Trigger prop: when the preset plays. */\nexport const NODE_ANIMATION_TRIGGER_PROP = 'aglynAnimationTrigger'\n/** Duration prop, in milliseconds. */\nexport const NODE_ANIMATION_DURATION_PROP = 'aglynAnimationDuration'\n/** Delay prop, in milliseconds. */\nexport const NODE_ANIMATION_DELAY_PROP = 'aglynAnimationDelay'\n/** Repeat prop: re-play every time the element scrolls back into view. */\nexport const NODE_ANIMATION_REPEAT_PROP = 'aglynAnimationRepeat'\n/** Easing prop: the shape of the motion curve. */\nexport const NODE_ANIMATION_EASE_PROP = 'aglynAnimationEase'\n/** Stagger prop: animate the children one after another, not the element. */\nexport const NODE_ANIMATION_STAGGER_PROP = 'aglynAnimationStagger'\n/** Stagger step prop: how much later each child starts, in milliseconds. */\nexport const NODE_ANIMATION_STAGGER_STEP_PROP = 'aglynAnimationStaggerStep'\n\n/** Every reserved animation prop, for the renderer's strip step. */\nexport const NODE_ANIMATION_PROPS = [\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] as const\n\n/**\n * The \"no animation\" value is a real string, never `''` (AGL-1451): an empty\n * value cannot persist through the attributes form, so an author who picked a\n * preset could never switch back off it.\n */\nexport const ANIMATION_NONE = 'none'\n\n/** Preset ids. Persisted in screen documents — never rename one. */\nexport const ANIMATION_PRESETS = [\n  ANIMATION_NONE,\n  'fade',\n  'slide-up',\n  'slide-down',\n  'slide-left',\n  'slide-right',\n  'zoom-in',\n  'zoom-out',\n] as const\n\nexport type AnimationPreset = (typeof ANIMATION_PRESETS)[number]\n\n/** Trigger ids. Persisted — never rename one. */\nexport const ANIMATION_TRIGGERS = ['load', 'scroll', 'hover'] as const\n\nexport type AnimationTrigger = (typeof ANIMATION_TRIGGERS)[number]\n\n/**\n * Easing ids — the SHAPE of the motion, the third dial beside duration and\n * delay. Persisted; never rename one.\n *\n * Only the ids live here. The `cubic-bezier()` curves themselves are in the\n * server-only stylesheet module, for the same reason the keyframes are: this\n * file is reachable from the client bundle and six bezier literals is ~200\n * bytes that every visitor to a still page would otherwise carry. The id\n * becomes a class, the class sets a custom property, and the curve is read\n * from the sheet that only an animating page ships.\n */\nexport const ANIMATION_EASINGS = [\n  'smooth',\n  'steady',\n  'gentle-start',\n  'gentle-end',\n  'gentle-both',\n  'overshoot',\n] as const\n\nexport type AnimationEase = (typeof ANIMATION_EASINGS)[number]\n\n/** Default when an author picks a preset but leaves the dials alone. */\nexport const ANIMATION_DEFAULT_TRIGGER: AnimationTrigger = 'scroll'\nexport const ANIMATION_DEFAULT_DURATION_MS = 600\nexport const ANIMATION_DEFAULT_DELAY_MS = 0\n/**\n * The curve every animation used before easing was authorable. Keeping it as\n * the default means every screen authored before this shipped renders byte\n * for byte the same.\n */\nexport const ANIMATION_DEFAULT_EASE: AnimationEase = 'smooth'\n/** Default gap between staggered children. */\nexport const ANIMATION_DEFAULT_STAGGER_STEP_MS = 90\n\n/** Upper bounds. A 30s entrance is an author mistake, not an intent. */\nexport const ANIMATION_MAX_DURATION_MS = 3000\nexport const ANIMATION_MAX_DELAY_MS = 3000\n/**\n * A stagger step is capped far lower than a delay, because it MULTIPLIES:\n * the last of twelve cards waits eleven steps. At the 500ms cap that is\n * already 5.5s, which is why {@link ANIMATION_STAGGER_MAX_CHILDREN} stops the\n * ladder climbing rather than letting a long list run off the end.\n */\nexport const ANIMATION_MAX_STAGGER_STEP_MS = 500\n/**\n * How many children get their own rung of the stagger ladder. Beyond this\n * every remaining child shares the last rung, so a 200-row collection cannot\n * leave its tail invisible for a minute — the tail arrives together, which is\n * the least surprising failure and the one an author can actually see.\n *\n * Also the size of the generated rule block, which is why it is a number and\n * not \"all of them\": each rung is one selector.\n */\nexport const ANIMATION_STAGGER_MAX_CHILDREN = 24\n\n/** Base class every animated element carries. */\nexport const ANIMATION_CLASS = 'aglyn-anim'\n/**\n * Base class of a STAGGER HOST — an element whose children animate one after\n * another instead of the element itself animating.\n *\n * It is a different base class rather than a modifier on {@link\n * ANIMATION_CLASS} because the two are mutually exclusive by construction: an\n * element carrying both would play its own entrance AND run its children's,\n * which is two overlapping fades on the same pixels. The preset and easing\n * modifiers are shared, and reach the children through custom-property\n * inheritance — the host sets `--aglyn-anim-name`, every child reads it, and\n * the stylesheet needs no per-preset child rule.\n */\nexport const ANIMATION_GROUP_CLASS = 'aglyn-anim-group'\n/** Per-preset modifier, e.g. `aglyn-anim--slide-up`. */\nexport const ANIMATION_PRESET_CLASS_PREFIX = 'aglyn-anim--'\n/** Per-easing modifier, e.g. `aglyn-anim-ease--overshoot`. */\nexport const ANIMATION_EASE_CLASS_PREFIX = 'aglyn-anim-ease--'\n/** Added by the scroll runtime once an element has entered the viewport. */\nexport const ANIMATION_IN_CLASS = 'aglyn-anim--in'\n/**\n * Set on `<html>` by the inline runtime. Every rule that HIDES a\n * scroll-triggered element before it plays is scoped under this class, so a\n * visitor with no JS — and every crawler — sees the un-animated, VISIBLE\n * state. Nothing is ever hidden by the server.\n */\nexport const ANIMATION_READY_CLASS = 'aglyn-anim-js'\n\n/** Trigger attribute the stylesheet and the runtime both select on. */\nexport const ANIMATION_TRIGGER_ATTR = 'data-aglyn-anim-trigger'\n/** Repeat attribute the runtime reads; `'1'` means re-play. */\nexport const ANIMATION_REPEAT_ATTR = 'data-aglyn-anim-repeat'\n\n/** Custom properties carrying the author's dials. */\nexport const ANIMATION_DURATION_VAR = '--aglyn-anim-duration'\nexport const ANIMATION_DELAY_VAR = '--aglyn-anim-delay'\n/** Set on a stagger host; every child reads it through inheritance. */\nexport const ANIMATION_STAGGER_STEP_VAR = '--aglyn-anim-step'\n/**\n * Set on each child BY the stylesheet's nth-child ladder, not by the\n * renderer — the renderer never sees a child's index, and asking it to would\n * mean the host re-rendering whenever a sibling was inserted.\n */\nexport const ANIMATION_STAGGER_OFFSET_VAR = '--aglyn-anim-stagger'\n\n/**\n * Clamp a millisecond dial. `strictNullChecks` is OFF repo-wide and `0` is a\n * legitimate delay, so this tests for a finite number rather than\n * truthiness — `if (!delay)` would silently discard a deliberate `0` and,\n * worse, treat it as \"not set\" and substitute the default.\n */\nfunction clampMs(value: unknown, fallback: number, max: number): number {\n  const n = typeof value === 'string' ? Number(value) : value\n  if (typeof n !== 'number' || !Number.isFinite(n)) return fallback\n  return Math.min(Math.max(n, 0), max)\n}\n\nexport interface ResolvedElementAnimation {\n  preset: AnimationPreset\n  trigger: AnimationTrigger\n  ease: AnimationEase\n  durationMs: number\n  delayMs: number\n  repeat: boolean\n  /** True when the CHILDREN animate in sequence rather than this element. */\n  stagger: boolean\n  staggerStepMs: number\n  /** Classes to append to the element. */\n  className: string\n  /** DOM attributes the stylesheet and runtime select on. */\n  attributes: Record<string, string>\n  /** Custom properties, merged into the element's inline style. */\n  style: Record<string, string>\n}\n\n/**\n * Reads the reserved animation props off a node's resolved props and returns\n * the class/attribute/style triple the renderer applies — or `undefined` when\n * the node does not animate, which is the overwhelmingly common case and\n * costs one property read.\n *\n * Unknown preset and trigger values resolve to \"no animation\" rather than\n * being passed through: these strings reach a `data-` attribute and a class\n * name, and a screen document authored against a future preset must degrade\n * to a static element, never to a broken selector.\n */\nexport function resolveElementAnimation(\n  props: Record<string, any> | undefined,\n): ResolvedElementAnimation | undefined {\n  const preset = props?.[NODE_ANIMATION_PROP]\n  if (typeof preset !== 'string' || preset === ANIMATION_NONE) return undefined\n  if (!(ANIMATION_PRESETS as readonly string[]).includes(preset)) return undefined\n\n  const rawTrigger = props?.[NODE_ANIMATION_TRIGGER_PROP]\n  const trigger = (\n    typeof rawTrigger === 'string' &&\n    (ANIMATION_TRIGGERS as readonly string[]).includes(rawTrigger)\n      ? rawTrigger\n      : ANIMATION_DEFAULT_TRIGGER\n  ) as AnimationTrigger\n\n  const durationMs = clampMs(\n    props?.[NODE_ANIMATION_DURATION_PROP],\n    ANIMATION_DEFAULT_DURATION_MS,\n    ANIMATION_MAX_DURATION_MS,\n  )\n  const delayMs = clampMs(\n    props?.[NODE_ANIMATION_DELAY_PROP],\n    ANIMATION_DEFAULT_DELAY_MS,\n    ANIMATION_MAX_DELAY_MS,\n  )\n  const rawEase = props?.[NODE_ANIMATION_EASE_PROP]\n  const ease = (\n    typeof rawEase === 'string' &&\n    (ANIMATION_EASINGS as readonly string[]).includes(rawEase)\n      ? rawEase\n      : ANIMATION_DEFAULT_EASE\n  ) as AnimationEase\n\n  // Repeat only means anything for the scroll trigger — `load` fires once by\n  // definition and `hover` is a transition, not a keyframe run.\n  const repeat = trigger === 'scroll' && Boolean(props?.[NODE_ANIMATION_REPEAT_PROP])\n\n  // Stagger is refused for `hover` on purpose. A hover effect is a transition\n  // that must reverse the instant the pointer leaves; a staggered one would\n  // leave half a row mid-flight, and the ladder below only ever feeds\n  // `animation-delay`, which a transition does not read.\n  const stagger =\n    trigger !== 'hover' && Boolean(props?.[NODE_ANIMATION_STAGGER_PROP])\n  const staggerStepMs = stagger\n    ? clampMs(\n        props?.[NODE_ANIMATION_STAGGER_STEP_PROP],\n        ANIMATION_DEFAULT_STAGGER_STEP_MS,\n        ANIMATION_MAX_STAGGER_STEP_MS,\n      )\n    : 0\n\n  const attributes: Record<string, string> = {\n    [ANIMATION_TRIGGER_ATTR]: trigger,\n  }\n  if (repeat) attributes[ANIMATION_REPEAT_ATTR] = '1'\n\n  const style: Record<string, string> = {\n    [ANIMATION_DURATION_VAR]: `${durationMs}ms`,\n    [ANIMATION_DELAY_VAR]: `${delayMs}ms`,\n  }\n  // Written only for a stagger host, so a plain animated element's inline\n  // style is byte for byte what it was before this shipped.\n  if (stagger) style[ANIMATION_STAGGER_STEP_VAR] = `${staggerStepMs}ms`\n\n  return {\n    preset: preset as AnimationPreset,\n    trigger,\n    ease,\n    durationMs,\n    delayMs,\n    repeat,\n    stagger,\n    staggerStepMs,\n    className: `${stagger ? ANIMATION_GROUP_CLASS : ANIMATION_CLASS} ${\n      ANIMATION_PRESET_CLASS_PREFIX\n    }${preset} ${ANIMATION_EASE_CLASS_PREFIX}${ease}`,\n    attributes,\n    style,\n  }\n}\n\n/**\n * True when a node's props ask for a real animation. Cheap enough to run over\n * every node in a screen's flat node map, which is how the tenant decides\n * whether to ship the stylesheet at all.\n */\nexport function nodePropsAnimate(props: Record<string, any> | undefined): boolean {\n  const preset = props?.[NODE_ANIMATION_PROP]\n  return (\n    typeof preset === 'string' &&\n    preset !== ANIMATION_NONE &&\n    (ANIMATION_PRESETS as readonly string[]).includes(preset)\n  )\n}\n"],"names":["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","NODE_ANIMATION_PROPS","ANIMATION_NONE","ANIMATION_PRESETS","ANIMATION_TRIGGERS","ANIMATION_EASINGS","ANIMATION_DEFAULT_TRIGGER","ANIMATION_DEFAULT_DURATION_MS","ANIMATION_DEFAULT_DELAY_MS","ANIMATION_DEFAULT_EASE","ANIMATION_DEFAULT_STAGGER_STEP_MS","ANIMATION_MAX_DURATION_MS","ANIMATION_MAX_DELAY_MS","ANIMATION_MAX_STAGGER_STEP_MS","ANIMATION_STAGGER_MAX_CHILDREN","ANIMATION_CLASS","ANIMATION_GROUP_CLASS","ANIMATION_PRESET_CLASS_PREFIX","ANIMATION_EASE_CLASS_PREFIX","ANIMATION_IN_CLASS","ANIMATION_READY_CLASS","ANIMATION_TRIGGER_ATTR","ANIMATION_REPEAT_ATTR","ANIMATION_DURATION_VAR","ANIMATION_DELAY_VAR","ANIMATION_STAGGER_STEP_VAR","ANIMATION_STAGGER_OFFSET_VAR","clampMs","value","fallback","max","n","Number","isFinite","Math","min","resolveElementAnimation","props","preset","undefined","includes","rawTrigger","trigger","durationMs","delayMs","rawEase","ease","repeat","Boolean","stagger","staggerStepMs","attributes","style","className","nodePropsAnimate"],"mappings":"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"}

package/src/lib/app-utils/element-hidden-style.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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 "start hidden" class and the one CSS rule behind it.
+ *
+ * Its own module because a published page reads only the rule text — it goes
+ * into the SSR HTML so an author-applied hidden class paints hidden from the
+ * first frame — while `element-ui.ts` around it is the authoring-time
+ * choreography contract: the visibility executor, the drawer and menu command
+ * buses, leaf-selector expansion and the responsive bands, and through
+ * `compose-layout-nodes.ts` the layout composer as well. None of that runs to
+ * paint a hidden element, and a bundler cannot drop it around a single named
+ * import.
+ */
+/**
+ * Class the show/hide steps toggle. The tenant page ships
+ * {@link ELEMENT_HIDDEN_STYLE_TEXT} in its SSR HTML so an author-applied
+ * "start hidden" class paints hidden from the first frame; the besigner
+ * canvas deliberately omits the rule so hidden elements stay editable
+ * (same posture as the AGL-557 reveal outcome).
+ */
+export declare const ELEMENT_HIDDEN_CLASS = "aglyn-hidden";
+/** Stylesheet rule backing {@link ELEMENT_HIDDEN_CLASS}. */
+export declare const ELEMENT_HIDDEN_STYLE_TEXT = ".aglyn-hidden{display:none !important}";
+/** Id of the injected fallback style tag (idempotence marker). */
+export declare const ELEMENT_HIDDEN_STYLE_ID = "aglyn-element-hidden-style";
+/**
+ * Ensures the hidden-class rule exists in the document (the tenant page
+ * renders it during SSR; this is the belt-and-braces path for other
+ * surfaces, e.g. the interaction builder's Test button).
+ */
+export declare function ensureElementHiddenStyle(doc?: Document): void;

package/src/lib/app-utils/element-hidden-style.js

@@ -0,0 +1,48 @@
+/**
+ * @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 "start hidden" class and the one CSS rule behind it.
+ *
+ * Its own module because a published page reads only the rule text — it goes
+ * into the SSR HTML so an author-applied hidden class paints hidden from the
+ * first frame — while `element-ui.ts` around it is the authoring-time
+ * choreography contract: the visibility executor, the drawer and menu command
+ * buses, leaf-selector expansion and the responsive bands, and through
+ * `compose-layout-nodes.ts` the layout composer as well. None of that runs to
+ * paint a hidden element, and a bundler cannot drop it around a single named
+ * import.
+ */ /**
+ * Class the show/hide steps toggle. The tenant page ships
+ * {@link ELEMENT_HIDDEN_STYLE_TEXT} in its SSR HTML so an author-applied
+ * "start hidden" class paints hidden from the first frame; the besigner
+ * canvas deliberately omits the rule so hidden elements stay editable
+ * (same posture as the AGL-557 reveal outcome).
+ */ export const ELEMENT_HIDDEN_CLASS = 'aglyn-hidden';
+/** Stylesheet rule backing {@link ELEMENT_HIDDEN_CLASS}. */ export const ELEMENT_HIDDEN_STYLE_TEXT = `.${ELEMENT_HIDDEN_CLASS}{display:none !important}`;
+/** Id of the injected fallback style tag (idempotence marker). */ export const ELEMENT_HIDDEN_STYLE_ID = 'aglyn-element-hidden-style';
+/**
+ * Ensures the hidden-class rule exists in the document (the tenant page
+ * renders it during SSR; this is the belt-and-braces path for other
+ * surfaces, e.g. the interaction builder's Test button).
+ */ export function ensureElementHiddenStyle(doc = document) {
+    if (doc.getElementById(ELEMENT_HIDDEN_STYLE_ID)) return;
+    const style = doc.createElement('style');
+    style.id = ELEMENT_HIDDEN_STYLE_ID;
+    style.textContent = ELEMENT_HIDDEN_STYLE_TEXT;
+    doc.head.appendChild(style);
+}
+
+//# sourceMappingURL=element-hidden-style.js.map

package/src/lib/app-utils/element-hidden-style.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/element-hidden-style.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 * The \"start hidden\" class and the one CSS rule behind it.\n *\n * Its own module because a published page reads only the rule text — it goes\n * into the SSR HTML so an author-applied hidden class paints hidden from the\n * first frame — while `element-ui.ts` around it is the authoring-time\n * choreography contract: the visibility executor, the drawer and menu command\n * buses, leaf-selector expansion and the responsive bands, and through\n * `compose-layout-nodes.ts` the layout composer as well. None of that runs to\n * paint a hidden element, and a bundler cannot drop it around a single named\n * import.\n */\n\n/**\n * Class the show/hide steps toggle. The tenant page ships\n * {@link ELEMENT_HIDDEN_STYLE_TEXT} in its SSR HTML so an author-applied\n * \"start hidden\" class paints hidden from the first frame; the besigner\n * canvas deliberately omits the rule so hidden elements stay editable\n * (same posture as the AGL-557 reveal outcome).\n */\nexport const ELEMENT_HIDDEN_CLASS = 'aglyn-hidden'\n\n/** Stylesheet rule backing {@link ELEMENT_HIDDEN_CLASS}. */\nexport const ELEMENT_HIDDEN_STYLE_TEXT = `.${ELEMENT_HIDDEN_CLASS}{display:none !important}`\n\n/** Id of the injected fallback style tag (idempotence marker). */\nexport const ELEMENT_HIDDEN_STYLE_ID = 'aglyn-element-hidden-style'\n\n/**\n * Ensures the hidden-class rule exists in the document (the tenant page\n * renders it during SSR; this is the belt-and-braces path for other\n * surfaces, e.g. the interaction builder's Test button).\n */\nexport function ensureElementHiddenStyle(doc: Document = document): void {\n  if (doc.getElementById(ELEMENT_HIDDEN_STYLE_ID)) return\n  const style = doc.createElement('style')\n  style.id = ELEMENT_HIDDEN_STYLE_ID\n  style.textContent = ELEMENT_HIDDEN_STYLE_TEXT\n  doc.head.appendChild(style)\n}\n"],"names":["ELEMENT_HIDDEN_CLASS","ELEMENT_HIDDEN_STYLE_TEXT","ELEMENT_HIDDEN_STYLE_ID","ensureElementHiddenStyle","doc","document","getElementById","style","createElement","id","textContent","head","appendChild"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;CAWC,GAED;;;;;;CAMC,GACD,OAAO,MAAMA,uBAAuB,eAAc;AAElD,0DAA0D,GAC1D,OAAO,MAAMC,4BAA4B,CAAC,CAAC,EAAED,qBAAqB,yBAAyB,CAAC,CAAA;AAE5F,gEAAgE,GAChE,OAAO,MAAME,0BAA0B,6BAA4B;AAEnE;;;;CAIC,GACD,OAAO,SAASC,yBAAyBC,MAAgBC,QAAQ;IAC/D,IAAID,IAAIE,cAAc,CAACJ,0BAA0B;IACjD,MAAMK,QAAQH,IAAII,aAAa,CAAC;IAChCD,MAAME,EAAE,GAAGP;IACXK,MAAMG,WAAW,GAAGT;IACpBG,IAAIO,IAAI,CAACC,WAAW,CAACL;AACvB"}

package/src/lib/app-utils/element-ui.d.ts

@@ -0,0 +1,243 @@
+/**
+ * @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.
+ */
+/**
+ * Element UI choreography contract (AGL-562): the shared pieces the
+ * interactions executor (marketing site runtime), the drawer element
+ * (plugins-mui), and the besigner authoring surfaces agree on —
+ * show/hide semantics, the drawer command event bus, and the responsive
+ * visibility media bands. Pure constants + DOM helpers; every function
+ * that touches `window`/`document` is only ever called client-side.
+ */
+import { type ScrollToBehavior } from './actions';
+export * from './element-hidden-style';
+export type ElementVisibilityCommand = 'show' | 'hide' | 'toggle';
+/**
+ * Applies a show/hide/toggle command to every element the selector
+ * matches. Hide adds the shared hidden class; show removes it AND any
+ * inline `display: none` so an element hidden either way reveals; toggle
+ * flips per element. Returns the number of elements touched (0 for a
+ * selector that matches nothing — steps never throw).
+ */
+export declare function applyElementVisibility(command: ElementVisibilityCommand, selector: string, root?: ParentNode): number;
+export interface ElementVisibilityOptions {
+    /** Defer the change; a later visibility step on the same selector
+     * cancels the pending one — the hover grace period. */
+    delayMs?: number;
+    /** Self-dismiss a SHOWN element on Escape / a pointerdown outside it. */
+    dismissOn?: Array<'escape' | 'outsideClick'>;
+}
+/** Tears down all pending timers and dismiss listeners (tests). */
+export declare function resetElementVisibilityChoreography(): void;
+/**
+ * Runs an element-visibility step with menu-grade choreography (AGL-589):
+ *
+ * - `delayMs` defers the change; ANY later visibility step on the same
+ *   selector cancels the pending one first. Hover menus author
+ *   hover-enter → show (immediate, cancels a pending hide) and
+ *   hover-leave → hide with a small delay — the classic grace period.
+ * - `dismissOn` arms Escape / outside-pointerdown listeners while the
+ *   element is shown (armed AFTER the change applies, so the click that
+ *   opened it can never instantly close it) and disarms them on hide.
+ *
+ * Without options this is exactly {@link applyElementVisibility}.
+ */
+export declare function runElementVisibilityStep(command: ElementVisibilityCommand, selector: string, options?: ElementVisibilityOptions, doc?: Document): void;
+/**
+ * Strips a single leading LAYOUT namespace prefix from a node/leaf id so ids
+ * authored against the raw canvas id and ids stamped on the live
+ * layout-composed DOM compare equal (AGL-573). Idempotent for an
+ * already-raw id, and only a *leading* prefix is removed, so unrelated ids
+ * can never be coerced into colliding.
+ *
+ * Deliberately does NOT try to strip a reusable-component graft — that
+ * namespace is unparseable (see {@link isComponentGraft}); `leafIdsMatch`
+ * and `expandLeafSelector` handle grafts by suffix.
+ *
+ * @example
+ * normalizeLeafId('layout___5I3TBXywa') // → '_5I3TBXywa'
+ * normalizeLeafId('_5I3TBXywa')         // → '_5I3TBXywa'
+ */
+export declare function normalizeLeafId(id: string | undefined | null): string;
+/**
+ * Whether two node ids address the same node ignoring composition
+ * namespace prefixes (AGL-573, extended to reusable-component grafts by
+ * AGL-1229) — the durable half of the fix for interactions authored on
+ * composed elements, whose stored command id is the raw canvas id while the
+ * live element's id is namespaced.
+ *
+ * Layout prefixes are stripped exactly. A component graft is matched by
+ * SUFFIX instead, because its namespace cannot be parsed off unambiguously
+ * (see {@link isComponentGraft}) — a composed id always ends in `__` plus
+ * the raw id it was built from, and a raw id is a single nanoid with no
+ * `__` boundary to spare, so the suffix cannot reach an unrelated node.
+ *
+ * Two empty ids never match (a missing id is not a wildcard).
+ */
+export declare function leafIdsMatch(a: string | undefined | null, b: string | undefined | null): boolean;
+/**
+ * Extracts the leaf id from a canonical `[data-aglyn="leaf:<id>"]`
+ * selector (the exact form the renderer and the interaction builder emit),
+ * or `undefined` for any other selector.
+ */
+export declare function leafIdFromSelector(selector: string): string | undefined;
+/**
+ * Rewrites a `[data-aglyn="leaf:<id>"]` selector so it ALSO matches the
+ * same node once composition has namespaced its live id (AGL-573, extended
+ * to reusable components by AGL-1229):
+ *
+ *   [data-aglyn="leaf:_5I3TBXywa"]
+ *     → [data-aglyn="leaf:_5I3TBXywa"],
+ *       [data-aglyn="leaf:layout___5I3TBXywa"],
+ *       [data-aglyn$="___5I3TBXywa"]
+ *
+ * The layout alternatives stay enumerated and exactly anchored. The last is
+ * a SUFFIX match, and it is the only way to reach a reusable-component
+ * graft: its namespace is `cmp__{instanceId}__`, one per placement, so
+ * there is no finite prefix list to enumerate.
+ *
+ * The suffix cannot collide. A composed id always ends in the raw id it was
+ * built from, so matching `__` + the exact raw id can only reach a
+ * composition OF THAT id — reaching an unrelated node would need that
+ * node's own raw id to end in `__` plus a full id, and raw ids are a single
+ * fixed-length nanoid with no `__` boundary to spare.
+ *
+ * Any non-leaf selector — a plain CSS selector an author typed by hand —
+ * passes through verbatim.
+ */
+export declare function expandLeafSelector(selector: string): string;
+export type DrawerCommand = 'open' | 'close' | 'toggle';
+/** Window event carrying a drawer command (AGL-562). */
+export declare const DRAWER_COMMAND_EVENT = "aglyn:drawer-command";
+export interface DrawerCommandDetail {
+    command: DrawerCommand;
+    /** Target drawer's canvas node id; absent = the page's first drawer. */
+    nodeId?: string;
+}
+/** Dispatches a drawer command onto the window event bus. */
+export declare function dispatchDrawerCommand(command: DrawerCommand, nodeId?: string): void;
+/**
+ * Subscribes to drawer commands; returns the unsubscriber. The handler
+ * receives every command — drawer instances filter by their own node id
+ * (or first-registered status for broadcasts).
+ */
+export declare function subscribeDrawerCommands(handler: (detail: DrawerCommandDetail) => void): () => void;
+export type MenuCommand = 'open' | 'close' | 'toggle';
+/**
+ * Window event carrying a nav-menu command (AGL-568): the interactions
+ * system's open/close/toggle steps address Dropdown Menu and Mega Menu
+ * elements over this bus, exactly like drawers — no bespoke "open on"
+ * attribute involved.
+ */
+export declare const MENU_COMMAND_EVENT = "aglyn:menu-command";
+export interface MenuCommandDetail {
+    command: MenuCommand;
+    /** Target menu's canvas node id; absent = the page's first menu. */
+    nodeId?: string;
+    /**
+     * Set when the command came from a hover trigger: a menu opened this
+     * way closes itself once the pointer leaves the trigger + panel
+     * surface (standard hover-menu UX), while click/command opens stay
+     * put until an explicit close, click-away, or Escape.
+     */
+    hover?: boolean;
+}
+/** Dispatches a menu command onto the window event bus. */
+export declare function dispatchMenuCommand(command: MenuCommand, nodeId?: string, options?: {
+    hover?: boolean;
+}): void;
+/**
+ * Subscribes to menu commands; returns the unsubscriber. The handler
+ * receives every command — menu instances filter by their own node id
+ * (or first-registered status for broadcasts).
+ */
+export declare function subscribeMenuCommands(handler: (detail: MenuCommandDetail) => void): () => void;
+/**
+ * The element a one-target step acts on: the first match that has a layout
+ * box, or null.
+ *
+ * Every match is read rather than only the first, because one element can
+ * legitimately appear twice — an expanded leaf selector reaches each
+ * composition of an id, and a page may carry a desktop and a mobile copy with
+ * one hidden at each breakpoint. The copy the visitor can see is the one they
+ * meant.
+ *
+ * A match with no box is never acted on. Scrolling to a `display: none`
+ * element lands at the top of the page, and pressing a hidden player starts a
+ * film nobody can see, so a target that is not on the page in the layout
+ * sense makes the step a no-op, as a missing or deleted one does.
+ */
+export declare function resolveStepTarget(selector: string, root?: ParentNode): HTMLElement | SVGElement | null;
+export interface ScrollToStepOptions {
+    /** Absent means `smooth`; reduced motion overrides either to `instant`. */
+    behavior?: ScrollToBehavior;
+    /** Pixels left above the target; clamped to 0–{@link SCROLL_TO_MAX_OFFSET_PX}. */
+    offsetPx?: number;
+}
+/**
+ * Runs a `scrollTo` step: brings the target to the top of the window, less
+ * the offset, and moves focus to it. Returns whether there was a target.
+ *
+ * The position is computed and handed to the window rather than asked of
+ * `scrollIntoView`, because the offset has nowhere to go in that call except
+ * a `scroll-margin` written onto the author's element. A target inside a box
+ * that scrolls its own content is the exception, and there the box has to be
+ * scrolled too, which `scrollIntoView` does for every such ancestor at once;
+ * the offset is for a header over the page, not for a panel's own edge.
+ *
+ * Reduced motion is read at the moment of the press, so a visitor who changes
+ * the setting mid-visit gets what they asked for on the next one.
+ */
+export declare function runScrollToStep(selector: string, options?: ScrollToStepOptions, doc?: Document): boolean;
+/**
+ * The event a Video element answers with its own poster press.
+ *
+ * Dispatched ON the element, where the drawer and menu commands go to
+ * `window`. Those buses need an address because a command with none means
+ * "the page's first drawer"; a `playVideo` step has already found its element
+ * through its selector, so the element that receives the event is the one that
+ * should answer, with no id to parse or compare.
+ */
+export declare const VIDEO_COMMAND_EVENT = "aglyn:video-command";
+export type VideoCommand = 'play';
+export interface VideoCommandDetail {
+    command: VideoCommand;
+}
+/**
+ * Sends a command to an element. Returns whether a Video element answered —
+ * a listener registered through {@link subscribeVideoCommands} cancels the
+ * event to say so — which is false for an element that is not a Video.
+ */
+export declare function dispatchVideoCommand(element: EventTarget, command: VideoCommand): boolean;
+/** Answers video commands sent to `element`; returns the unsubscriber. */
+export declare function subscribeVideoCommands(element: EventTarget, handler: (detail: VideoCommandDetail) => void): () => void;
+/**
+ * Runs a `playVideo` step: presses the poster of the Video element the
+ * selector names. Returns whether a Video answered.
+ */
+export declare function runPlayVideoStep(selector: string, doc?: Document): boolean;
+/**
+ * The three authoring-facing visibility bands and the sx media-query
+ * keys the styles panel writes `display: none` under. Range-scoped
+ * queries (not MUI's mobile-first responsive objects) so hiding one band
+ * never needs a "restore" display value on the others — the element's
+ * natural display simply keeps applying outside the hidden range.
+ * Boundaries follow the MUI defaults the device preview uses: mobile
+ * under 600, tablet 600–899, desktop 900 and up.
+ */
+export declare const VISIBILITY_BANDS: readonly ["mobile", "tablet", "desktop"];
+export type VisibilityBand = (typeof VISIBILITY_BANDS)[number];
+export declare const VISIBILITY_BAND_MEDIA: Record<VisibilityBand, string>;