@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/utils/author-html-label.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 { ReactNode } from 'react';
+/**
+ * The formatted label of a CONTROL — a Button, a Screen Link, an Accordion
+ * Summary (AGL-2557).
+ *
+ * ## The three parts that have to travel together
+ *
+ * The inline editor's rich mode commits sanitized markup into an `html` prop
+ * and keeps `children` as the plain-text fallback. Until this existed,
+ * `typography.tsx` was the only component that read `html` back, so setting
+ * the editor's flag anywhere else would have shipped a toolbar whose output
+ * was discarded: bold while typing, plain the moment it committed. A
+ * component earns the flag by declaring the prop, rendering it through here,
+ * and only then turning the flag on.
+ *
+ * ## Sanitized on EVERY render (AGL-497)
+ *
+ * The editor sanitizes at commit, and that is not where the guarantee comes
+ * from. Screen node props are written straight through the Firebase client
+ * SDK, so a host editor can plant arbitrary `html` on a node without the
+ * editor ever seeing it — and it would then execute on the published site
+ * AND on the besigner canvas at app.aglyn.com. `sanitizeAuthorHtml` is pure
+ * and needs no DOM (AGL-1901), so the server and the first client render
+ * compute the same bytes and hydration is clean by construction.
+ *
+ * ## Why the narrowed allowlist
+ *
+ * A control's content model is phrasing content with no interactive
+ * descendant, so this passes {@link Aglyn.INLINE_AUTHOR_HTML_ELEMENTS}: no
+ * lists, no blocks, no nested anchor. That is a rendering requirement, not a
+ * tidiness one — the parser closes a `<button>` on a `<div>` start tag and
+ * promotes the rest to a sibling, which is a React hydration mismatch on the
+ * tenant. The toolbar declines to OFFER those commands for these components
+ * (`richTextCommands`), and this is what holds the line for markup that
+ * arrived some other way.
+ *
+ * ## Why `<aglyn-text>` and not a `<span>`
+ *
+ * The canvas edits a leaf's own `<aglyn-text>` when it renders one, and
+ * falls back to the leaf root otherwise (AGL-2556). For a composite like
+ * Accordion Summary the root is the `<button>`, and in-place editing EMPTIES
+ * whatever it is handed — which would take MUI's content wrapper, and its
+ * `textAlign: 'start'`, with it for the length of the edit. Rendering the
+ * formatted label into the same element the plain label uses keeps one edit
+ * target for both modes.
+ */
+export declare function authorHtmlLabel(html: unknown): ReactNode | null;
+/**
+ * `props` with the formatted label substituted for its children, or `props`
+ * itself when the node carries no `html`.
+ *
+ * Returned BY IDENTITY in the unformatted case, which is the overwhelmingly
+ * common one — a Screen Link is the busiest element on a published page at
+ * 70–77 nodes — so an element nobody has formatted allocates nothing and
+ * renders the tree it always did.
+ */
+export declare function withAuthorHtmlLabel<P extends object>(props: P, html: unknown): P;

package/src/lib/utils/author-html-label.js

@@ -0,0 +1,89 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import * as Aglyn from "@aglyn/aglyn";
+import { AglynText } from "@aglyn/shared-ui-jsx";
+/**
+ * The formatted label of a CONTROL — a Button, a Screen Link, an Accordion
+ * Summary (AGL-2557).
+ *
+ * ## The three parts that have to travel together
+ *
+ * The inline editor's rich mode commits sanitized markup into an `html` prop
+ * and keeps `children` as the plain-text fallback. Until this existed,
+ * `typography.tsx` was the only component that read `html` back, so setting
+ * the editor's flag anywhere else would have shipped a toolbar whose output
+ * was discarded: bold while typing, plain the moment it committed. A
+ * component earns the flag by declaring the prop, rendering it through here,
+ * and only then turning the flag on.
+ *
+ * ## Sanitized on EVERY render (AGL-497)
+ *
+ * The editor sanitizes at commit, and that is not where the guarantee comes
+ * from. Screen node props are written straight through the Firebase client
+ * SDK, so a host editor can plant arbitrary `html` on a node without the
+ * editor ever seeing it — and it would then execute on the published site
+ * AND on the besigner canvas at app.aglyn.com. `sanitizeAuthorHtml` is pure
+ * and needs no DOM (AGL-1901), so the server and the first client render
+ * compute the same bytes and hydration is clean by construction.
+ *
+ * ## Why the narrowed allowlist
+ *
+ * A control's content model is phrasing content with no interactive
+ * descendant, so this passes {@link Aglyn.INLINE_AUTHOR_HTML_ELEMENTS}: no
+ * lists, no blocks, no nested anchor. That is a rendering requirement, not a
+ * tidiness one — the parser closes a `<button>` on a `<div>` start tag and
+ * promotes the rest to a sibling, which is a React hydration mismatch on the
+ * tenant. The toolbar declines to OFFER those commands for these components
+ * (`richTextCommands`), and this is what holds the line for markup that
+ * arrived some other way.
+ *
+ * ## Why `<aglyn-text>` and not a `<span>`
+ *
+ * The canvas edits a leaf's own `<aglyn-text>` when it renders one, and
+ * falls back to the leaf root otherwise (AGL-2556). For a composite like
+ * Accordion Summary the root is the `<button>`, and in-place editing EMPTIES
+ * whatever it is handed — which would take MUI's content wrapper, and its
+ * `textAlign: 'start'`, with it for the length of the edit. Rendering the
+ * formatted label into the same element the plain label uses keeps one edit
+ * target for both modes.
+ */ export function authorHtmlLabel(html) {
+    if (typeof html !== 'string' || !html) return null;
+    return /*#__PURE__*/ _jsx(AglynText, {
+        dangerouslySetInnerHTML: {
+            __html: Aglyn.sanitizeAuthorHtml(html, undefined, {
+                allowedElements: Aglyn.INLINE_AUTHOR_HTML_ELEMENTS
+            })
+        }
+    });
+}
+/**
+ * `props` with the formatted label substituted for its children, or `props`
+ * itself when the node carries no `html`.
+ *
+ * Returned BY IDENTITY in the unformatted case, which is the overwhelmingly
+ * common one — a Screen Link is the busiest element on a published page at
+ * 70–77 nodes — so an element nobody has formatted allocates nothing and
+ * renders the tree it always did.
+ */ export function withAuthorHtmlLabel(props, html) {
+    const label = authorHtmlLabel(html);
+    return label ? _extends({}, props, {
+        children: label
+    }) : props;
+}
+
+//# sourceMappingURL=author-html-label.js.map

package/src/lib/utils/author-html-label.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/utils/author-html-label.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport * as Aglyn from '@aglyn/aglyn'\nimport { AglynText } from '@aglyn/shared-ui-jsx'\nimport type { ReactNode } from 'react'\n\n/**\n * The formatted label of a CONTROL — a Button, a Screen Link, an Accordion\n * Summary (AGL-2557).\n *\n * ## The three parts that have to travel together\n *\n * The inline editor's rich mode commits sanitized markup into an `html` prop\n * and keeps `children` as the plain-text fallback. Until this existed,\n * `typography.tsx` was the only component that read `html` back, so setting\n * the editor's flag anywhere else would have shipped a toolbar whose output\n * was discarded: bold while typing, plain the moment it committed. A\n * component earns the flag by declaring the prop, rendering it through here,\n * and only then turning the flag on.\n *\n * ## Sanitized on EVERY render (AGL-497)\n *\n * The editor sanitizes at commit, and that is not where the guarantee comes\n * from. Screen node props are written straight through the Firebase client\n * SDK, so a host editor can plant arbitrary `html` on a node without the\n * editor ever seeing it — and it would then execute on the published site\n * AND on the besigner canvas at app.aglyn.com. `sanitizeAuthorHtml` is pure\n * and needs no DOM (AGL-1901), so the server and the first client render\n * compute the same bytes and hydration is clean by construction.\n *\n * ## Why the narrowed allowlist\n *\n * A control's content model is phrasing content with no interactive\n * descendant, so this passes {@link Aglyn.INLINE_AUTHOR_HTML_ELEMENTS}: no\n * lists, no blocks, no nested anchor. That is a rendering requirement, not a\n * tidiness one — the parser closes a `<button>` on a `<div>` start tag and\n * promotes the rest to a sibling, which is a React hydration mismatch on the\n * tenant. The toolbar declines to OFFER those commands for these components\n * (`richTextCommands`), and this is what holds the line for markup that\n * arrived some other way.\n *\n * ## Why `<aglyn-text>` and not a `<span>`\n *\n * The canvas edits a leaf's own `<aglyn-text>` when it renders one, and\n * falls back to the leaf root otherwise (AGL-2556). For a composite like\n * Accordion Summary the root is the `<button>`, and in-place editing EMPTIES\n * whatever it is handed — which would take MUI's content wrapper, and its\n * `textAlign: 'start'`, with it for the length of the edit. Rendering the\n * formatted label into the same element the plain label uses keeps one edit\n * target for both modes.\n */\nexport function authorHtmlLabel(html: unknown): ReactNode | null {\n  if (typeof html !== 'string' || !html) return null\n  return (\n    <AglynText\n      dangerouslySetInnerHTML={{\n        __html: Aglyn.sanitizeAuthorHtml(html, undefined, {\n          allowedElements: Aglyn.INLINE_AUTHOR_HTML_ELEMENTS,\n        }),\n      }}\n    />\n  )\n}\n\n/**\n * `props` with the formatted label substituted for its children, or `props`\n * itself when the node carries no `html`.\n *\n * Returned BY IDENTITY in the unformatted case, which is the overwhelmingly\n * common one — a Screen Link is the busiest element on a published page at\n * 70–77 nodes — so an element nobody has formatted allocates nothing and\n * renders the tree it always did.\n */\nexport function withAuthorHtmlLabel<P extends object>(\n  props: P,\n  html: unknown,\n): P {\n  const label = authorHtmlLabel(html)\n  return label ? ({ ...props, children: label } as P) : props\n}\n"],"names":["Aglyn","AglynText","authorHtmlLabel","html","dangerouslySetInnerHTML","__html","sanitizeAuthorHtml","undefined","allowedElements","INLINE_AUTHOR_HTML_ELEMENTS","withAuthorHtmlLabel","props","label","children"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,YAAYA,WAAW,eAAc;AACrC,SAASC,SAAS,QAAQ,uBAAsB;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GACD,OAAO,SAASC,gBAAgBC,IAAa;IAC3C,IAAI,OAAOA,SAAS,YAAY,CAACA,MAAM,OAAO;IAC9C,qBACE,KAACF;QACCG,yBAAyB;YACvBC,QAAQL,MAAMM,kBAAkB,CAACH,MAAMI,WAAW;gBAChDC,iBAAiBR,MAAMS,2BAA2B;YACpD;QACF;;AAGN;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC,oBACdC,KAAQ,EACRR,IAAa;IAEb,MAAMS,QAAQV,gBAAgBC;IAC9B,OAAOS,QAAS,aAAKD;QAAOE,UAAUD;SAAgBD;AACxD"}

package/src/lib/utils/drop-cleared-props.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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.
+ */
+export declare function dropClearedProps<T extends Record<string, any>>(props: T): T;
+export default dropClearedProps;

package/src/lib/utils/drop-cleared-props.js

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */ /**
+ * Drops props an author CLEARED, so MUI's own defaults apply (AGL-1226).
+ *
+ * The besigner persists a cleared attribute as `null` (or `''`), and React
+ * only falls back to a default for `undefined` — an explicit `null` is a
+ * value. So `<Button color={null}>` does NOT become `color="primary"`; the
+ * null travels all the way into MUI, which builds its class names with
+ * `` `color${capitalize(color)}` `` and throws:
+ *
+ *     Minified MUI error #7 — capitalize(string) expects a string argument
+ *
+ * That is a SERVER-SIDE THROW during render, so the whole page 500s. It took
+ * down every `/product/*` page on the public marketing site, uncached
+ * (`x-vercel-cache: MISS` every time), for as long as one button carried a
+ * cleared colour.
+ *
+ * Stripping the key instead is what the author meant by clearing it: fall
+ * back to the component's default. Applied at the wrapper boundary rather
+ * than fixing the two offending documents, because a data fix leaves every
+ * other site one cleared dropdown away from the same 500.
+ *
+ * `0` and `false` are kept — those are real values an author can mean.
+ *
+ * `data-*` and `aria-*` are kept whatever their value. Only an authored
+ * ATTRIBUTE can be cleared, and neither of those is one: they are stamped by
+ * the renderer, and the canvas writes its flags PRESENCE-BASED — `''` for on,
+ * `undefined` for off — which is the same empty string a cleared select
+ * persists as. Dropping them took out every presence flag on every component
+ * that funnels through here: `data-aglyn-revealed`, so a panel carrying the
+ * hidden class could never be shown for designing; `data-aglyn-selected-within`,
+ * which is how a nav menu and a drawer know to open while they are being
+ * authored; and `data-aglyn-bound`, the outline on an element whose props
+ * carry bindings. They are also incapable of the crash above — both go
+ * straight to the DOM, where an empty attribute is ordinary HTML and nothing
+ * calls `capitalize()` on the value.
+ */ function isRendererAttribute(key) {
+    return key.startsWith('data-') || key.startsWith('aria-');
+}
+export function dropClearedProps(props) {
+    let cleared = false;
+    for(const key in props){
+        const value = props[key];
+        if ((value === null || value === '') && !isRendererAttribute(key)) {
+            cleared = true;
+            break;
+        }
+    }
+    if (!cleared) return props;
+    const next = {};
+    for(const key in props){
+        const value = props[key];
+        if ((value === null || value === '') && !isRendererAttribute(key)) continue;
+        next[key] = value;
+    }
+    return next;
+}
+export default dropClearedProps;
+
+//# sourceMappingURL=drop-cleared-props.js.map

package/src/lib/utils/drop-cleared-props.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/utils/drop-cleared-props.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 * Drops props an author CLEARED, so MUI's own defaults apply (AGL-1226).\n *\n * The besigner persists a cleared attribute as `null` (or `''`), and React\n * only falls back to a default for `undefined` — an explicit `null` is a\n * value. So `<Button color={null}>` does NOT become `color=\"primary\"`; the\n * null travels all the way into MUI, which builds its class names with\n * `` `color${capitalize(color)}` `` and throws:\n *\n *     Minified MUI error #7 — capitalize(string) expects a string argument\n *\n * That is a SERVER-SIDE THROW during render, so the whole page 500s. It took\n * down every `/product/*` page on the public marketing site, uncached\n * (`x-vercel-cache: MISS` every time), for as long as one button carried a\n * cleared colour.\n *\n * Stripping the key instead is what the author meant by clearing it: fall\n * back to the component's default. Applied at the wrapper boundary rather\n * than fixing the two offending documents, because a data fix leaves every\n * other site one cleared dropdown away from the same 500.\n *\n * `0` and `false` are kept — those are real values an author can mean.\n *\n * `data-*` and `aria-*` are kept whatever their value. Only an authored\n * ATTRIBUTE can be cleared, and neither of those is one: they are stamped by\n * the renderer, and the canvas writes its flags PRESENCE-BASED — `''` for on,\n * `undefined` for off — which is the same empty string a cleared select\n * persists as. Dropping them took out every presence flag on every component\n * that funnels through here: `data-aglyn-revealed`, so a panel carrying the\n * hidden class could never be shown for designing; `data-aglyn-selected-within`,\n * which is how a nav menu and a drawer know to open while they are being\n * authored; and `data-aglyn-bound`, the outline on an element whose props\n * carry bindings. They are also incapable of the crash above — both go\n * straight to the DOM, where an empty attribute is ordinary HTML and nothing\n * calls `capitalize()` on the value.\n */\nfunction isRendererAttribute(key: string): boolean {\n  return key.startsWith('data-') || key.startsWith('aria-')\n}\n\nexport function dropClearedProps<T extends Record<string, any>>(props: T): T {\n  let cleared = false\n  for (const key in props) {\n    const value = props[key]\n    if ((value === null || value === '') && !isRendererAttribute(key)) {\n      cleared = true\n      break\n    }\n  }\n  if (!cleared) return props\n  const next: Record<string, any> = {}\n  for (const key in props) {\n    const value = props[key]\n    if ((value === null || value === '') && !isRendererAttribute(key)) continue\n    next[key] = value\n  }\n  return next as T\n}\n\nexport default dropClearedProps\n"],"names":["isRendererAttribute","key","startsWith","dropClearedProps","props","cleared","value","next"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCC,GACD,SAASA,oBAAoBC,GAAW;IACtC,OAAOA,IAAIC,UAAU,CAAC,YAAYD,IAAIC,UAAU,CAAC;AACnD;AAEA,OAAO,SAASC,iBAAgDC,KAAQ;IACtE,IAAIC,UAAU;IACd,IAAK,MAAMJ,OAAOG,MAAO;QACvB,MAAME,QAAQF,KAAK,CAACH,IAAI;QACxB,IAAI,AAACK,CAAAA,UAAU,QAAQA,UAAU,EAAC,KAAM,CAACN,oBAAoBC,MAAM;YACjEI,UAAU;YACV;QACF;IACF;IACA,IAAI,CAACA,SAAS,OAAOD;IACrB,MAAMG,OAA4B,CAAC;IACnC,IAAK,MAAMN,OAAOG,MAAO;QACvB,MAAME,QAAQF,KAAK,CAACH,IAAI;QACxB,IAAI,AAACK,CAAAA,UAAU,QAAQA,UAAU,EAAC,KAAM,CAACN,oBAAoBC,MAAM;QACnEM,IAAI,CAACN,IAAI,GAAGK;IACd;IACA,OAAOC;AACT;AAEA,eAAeJ,iBAAgB"}

package/src/lib/utils/element-picker.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @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 Aglyn from '@aglyn/aglyn';
+/**
+ * THE ELEMENT PICKER EVERY CONTAINER GETS (AGL-2525).
+ *
+ * Section owned the semantic elements alone, so an author who wanted their nav
+ * row to BE the `nav` had to wrap it in a second element to say so — and on
+ * `aglyn.com` nobody did, which is why the published page had no navigation
+ * landmark at all. Wrapping to name a thing is the same shape of
+ * element-nobody-authored that AGL-2521 removed from component placements,
+ * arriving by a different route.
+ *
+ * ⛔ `main` IS NOT ON THIS LIST. A page carries exactly one, placed by
+ * `stampDocumentLandmark` on the Document layer or the Layout Slot — the two
+ * nodes that appear at most once per document. Everything using this picker can
+ * be placed any number of times, so an author-selected `main` here could only
+ * ever be the second one.
+ *
+ * An allow-list rather than free text: the value is persisted and rendered
+ * verbatim, so a typed one would put `script` into every visitor's page.
+ */
+export declare const SEMANTIC_ELEMENTS: readonly ["div", "section", "article", "aside", "nav", "header", "footer"];
+export type SemanticElement = (typeof SEMANTIC_ELEMENTS)[number];
+/**
+ * The element to render, or `undefined` to leave the component's own default
+ * alone.
+ *
+ * Returning `undefined` rather than `'div'` is what lets this be added to a
+ * component that does NOT default to a div — App Bar renders `header` unless
+ * told otherwise, and a resolver that answered `'div'` for "unset" would have
+ * silently stripped the banner landmark off every site's chrome the moment the
+ * picker appeared.
+ */
+export declare function resolveSemanticElement(value: unknown): SemanticElement | undefined;
+/**
+ * The elements that BECOME a landmark, and so want a name (AGL-2525).
+ *
+ * `div` is the odd one out: it has no role, so an `aria-label` on it names
+ * nothing. Everything else is announced as a region, and a page with two of
+ * the same kind — a header nav and a footer nav, say — is a page where
+ * "navigation, navigation" is all a screen-reader user hears without one.
+ */
+export declare const LANDMARK_ELEMENTS: ("article" | "aside" | "footer" | "header" | "nav" | "section")[];
+/**
+ * Consume the picker's props and return what the underlying MUI component
+ * should receive.
+ *
+ * Takes the whole props bag rather than one value because both keys have to
+ * be REMOVED as well as translated: `ariaLabel` spread onto a DOM element is
+ * an unknown React prop, warned about on the canvas and serialized onto the
+ * published page, which is the shape of the `propValues` leak in AGL-2486.
+ */
+export declare function applySemanticElement<P extends Record<string, unknown>>(props: P): Omit<P, 'component' | 'ariaLabel'> & {
+    component?: SemanticElement;
+    'aria-label'?: string;
+};
+/**
+ * Spreadable `component` prop: present only when the author chose one, so an
+ * unset picker is indistinguishable from never having had one.
+ */
+export declare function semanticElementProp(value: unknown): {
+    component?: SemanticElement;
+};
+/**
+ * The attribute schema. `subject` names what renders, e.g. "this stack".
+ *
+ * Labelled `Component`, the name Box, Typography, the Document layer and the
+ * Layout Slot already use — Section and Inline text keep `element` as their
+ * stored KEY because their values are persisted in published screens, but the
+ * panel says one thing everywhere (AGL-2514).
+ */
+export declare function semanticElementAttribute(subject: string): Aglyn.AglynAttributeSchema;
+/**
+ * The name for the landmark the picker just made, shown only once one exists.
+ *
+ * Gated on the element rather than always visible because on a `div` — the
+ * default, and what most of these elements stay — the field would do nothing
+ * at all, and a control that silently does nothing is worse than no control.
+ *
+ * This is the half Section already had and the picker did not. Naming stops
+ * being optional the moment a page has two landmarks of a kind: a site nav and
+ * a footer nav both announce as "navigation" until one of them says which.
+ */
+export declare function semanticElementLabelAttribute(): Aglyn.AglynAttributeSchema;

package/src/lib/utils/element-picker.js

@@ -0,0 +1,140 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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 Aglyn from "@aglyn/aglyn";
+/**
+ * THE ELEMENT PICKER EVERY CONTAINER GETS (AGL-2525).
+ *
+ * Section owned the semantic elements alone, so an author who wanted their nav
+ * row to BE the `nav` had to wrap it in a second element to say so — and on
+ * `aglyn.com` nobody did, which is why the published page had no navigation
+ * landmark at all. Wrapping to name a thing is the same shape of
+ * element-nobody-authored that AGL-2521 removed from component placements,
+ * arriving by a different route.
+ *
+ * ⛔ `main` IS NOT ON THIS LIST. A page carries exactly one, placed by
+ * `stampDocumentLandmark` on the Document layer or the Layout Slot — the two
+ * nodes that appear at most once per document. Everything using this picker can
+ * be placed any number of times, so an author-selected `main` here could only
+ * ever be the second one.
+ *
+ * An allow-list rather than free text: the value is persisted and rendered
+ * verbatim, so a typed one would put `script` into every visitor's page.
+ */ export const SEMANTIC_ELEMENTS = [
+    'div',
+    'section',
+    'article',
+    'aside',
+    'nav',
+    'header',
+    'footer'
+];
+/**
+ * The element to render, or `undefined` to leave the component's own default
+ * alone.
+ *
+ * Returning `undefined` rather than `'div'` is what lets this be added to a
+ * component that does NOT default to a div — App Bar renders `header` unless
+ * told otherwise, and a resolver that answered `'div'` for "unset" would have
+ * silently stripped the banner landmark off every site's chrome the moment the
+ * picker appeared.
+ */ export function resolveSemanticElement(value) {
+    return SEMANTIC_ELEMENTS.includes(String(value != null ? value : '')) ? value : undefined;
+}
+/**
+ * The elements that BECOME a landmark, and so want a name (AGL-2525).
+ *
+ * `div` is the odd one out: it has no role, so an `aria-label` on it names
+ * nothing. Everything else is announced as a region, and a page with two of
+ * the same kind — a header nav and a footer nav, say — is a page where
+ * "navigation, navigation" is all a screen-reader user hears without one.
+ */ export const LANDMARK_ELEMENTS = SEMANTIC_ELEMENTS.filter((element)=>element !== 'div');
+/**
+ * Consume the picker's props and return what the underlying MUI component
+ * should receive.
+ *
+ * Takes the whole props bag rather than one value because both keys have to
+ * be REMOVED as well as translated: `ariaLabel` spread onto a DOM element is
+ * an unknown React prop, warned about on the canvas and serialized onto the
+ * published page, which is the shape of the `propValues` leak in AGL-2486.
+ */ export function applySemanticElement(props) {
+    const { component, ariaLabel } = props, rest = _object_without_properties_loose(props, [
+        "component",
+        "ariaLabel"
+    ]);
+    const element = resolveSemanticElement(component);
+    const label = typeof ariaLabel === 'string' ? ariaLabel.trim() : '';
+    return _extends({}, rest, element ? {
+        component: element
+    } : {}, element && element !== 'div' && label ? {
+        'aria-label': label
+    } : {});
+}
+/**
+ * Spreadable `component` prop: present only when the author chose one, so an
+ * unset picker is indistinguishable from never having had one.
+ */ export function semanticElementProp(value) {
+    const element = resolveSemanticElement(value);
+    return element ? {
+        component: element
+    } : {};
+}
+/**
+ * The attribute schema. `subject` names what renders, e.g. "this stack".
+ *
+ * Labelled `Component`, the name Box, Typography, the Document layer and the
+ * Layout Slot already use — Section and Inline text keep `element` as their
+ * stored KEY because their values are persisted in published screens, but the
+ * panel says one thing everywhere (AGL-2514).
+ */ export function semanticElementAttribute(subject) {
+    return {
+        name: 'component',
+        label: 'Component',
+        description: `The DOM element ${subject} renders as. Use section/article/aside/nav/` + 'header/footer to give the region meaning for assistive tech and search ' + 'engines; div for purely visual grouping. "main" is not offered — the ' + 'page’s content region carries that one.',
+        component: Aglyn.FieldComponentType.SELECT,
+        options: SEMANTIC_ELEMENTS.map((value)=>({
+                value,
+                label: value
+            }))
+    };
+}
+/**
+ * The name for the landmark the picker just made, shown only once one exists.
+ *
+ * Gated on the element rather than always visible because on a `div` — the
+ * default, and what most of these elements stay — the field would do nothing
+ * at all, and a control that silently does nothing is worse than no control.
+ *
+ * This is the half Section already had and the picker did not. Naming stops
+ * being optional the moment a page has two landmarks of a kind: a site nav and
+ * a footer nav both announce as "navigation" until one of them says which.
+ */ export function semanticElementLabelAttribute() {
+    return {
+        name: 'ariaLabel',
+        label: 'Accessible label',
+        description: 'Names this region for screen readers. Required in practice once a ' + 'page has two landmarks of the same kind — a site nav and a footer ' + 'nav are both announced as "navigation" until one of them says which.',
+        component: Aglyn.FieldComponentType.TEXT_FIELD,
+        condition: {
+            when: 'component',
+            is: [
+                ...LANDMARK_ELEMENTS
+            ]
+        }
+    };
+}
+
+//# sourceMappingURL=element-picker.js.map

package/src/lib/utils/element-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/utils/element-picker.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 * as Aglyn from '@aglyn/aglyn'\n\n/**\n * THE ELEMENT PICKER EVERY CONTAINER GETS (AGL-2525).\n *\n * Section owned the semantic elements alone, so an author who wanted their nav\n * row to BE the `nav` had to wrap it in a second element to say so — and on\n * `aglyn.com` nobody did, which is why the published page had no navigation\n * landmark at all. Wrapping to name a thing is the same shape of\n * element-nobody-authored that AGL-2521 removed from component placements,\n * arriving by a different route.\n *\n * ⛔ `main` IS NOT ON THIS LIST. A page carries exactly one, placed by\n * `stampDocumentLandmark` on the Document layer or the Layout Slot — the two\n * nodes that appear at most once per document. Everything using this picker can\n * be placed any number of times, so an author-selected `main` here could only\n * ever be the second one.\n *\n * An allow-list rather than free text: the value is persisted and rendered\n * verbatim, so a typed one would put `script` into every visitor's page.\n */\nexport const SEMANTIC_ELEMENTS = [\n  'div',\n  'section',\n  'article',\n  'aside',\n  'nav',\n  'header',\n  'footer',\n] as const\nexport type SemanticElement = (typeof SEMANTIC_ELEMENTS)[number]\n\n/**\n * The element to render, or `undefined` to leave the component's own default\n * alone.\n *\n * Returning `undefined` rather than `'div'` is what lets this be added to a\n * component that does NOT default to a div — App Bar renders `header` unless\n * told otherwise, and a resolver that answered `'div'` for \"unset\" would have\n * silently stripped the banner landmark off every site's chrome the moment the\n * picker appeared.\n */\nexport function resolveSemanticElement(value: unknown): SemanticElement | undefined {\n  return (SEMANTIC_ELEMENTS as readonly string[]).includes(String(value ?? ''))\n    ? (value as SemanticElement)\n    : undefined\n}\n\n/**\n * The elements that BECOME a landmark, and so want a name (AGL-2525).\n *\n * `div` is the odd one out: it has no role, so an `aria-label` on it names\n * nothing. Everything else is announced as a region, and a page with two of\n * the same kind — a header nav and a footer nav, say — is a page where\n * \"navigation, navigation\" is all a screen-reader user hears without one.\n */\nexport const LANDMARK_ELEMENTS = SEMANTIC_ELEMENTS.filter(\n  (element) => element !== 'div',\n)\n\n/**\n * Consume the picker's props and return what the underlying MUI component\n * should receive.\n *\n * Takes the whole props bag rather than one value because both keys have to\n * be REMOVED as well as translated: `ariaLabel` spread onto a DOM element is\n * an unknown React prop, warned about on the canvas and serialized onto the\n * published page, which is the shape of the `propValues` leak in AGL-2486.\n */\nexport function applySemanticElement<P extends Record<string, unknown>>(\n  props: P,\n): Omit<P, 'component' | 'ariaLabel'> & {\n  component?: SemanticElement\n  'aria-label'?: string\n} {\n  const { component, ariaLabel, ...rest } = props as P & {\n    component?: unknown\n    ariaLabel?: unknown\n  }\n  const element = resolveSemanticElement(component)\n  const label = typeof ariaLabel === 'string' ? ariaLabel.trim() : ''\n  return {\n    ...(rest as Omit<P, 'component' | 'ariaLabel'>),\n    ...(element ? { component: element } : {}),\n    // Only on a landmark: a name on a role-less `div` is announced by\n    // nothing and is one more attribute in every visitor's markup.\n    ...(element && element !== 'div' && label ? { 'aria-label': label } : {}),\n  }\n}\n\n/**\n * Spreadable `component` prop: present only when the author chose one, so an\n * unset picker is indistinguishable from never having had one.\n */\nexport function semanticElementProp(\n  value: unknown,\n): { component?: SemanticElement } {\n  const element = resolveSemanticElement(value)\n  return element ? { component: element } : {}\n}\n\n/**\n * The attribute schema. `subject` names what renders, e.g. \"this stack\".\n *\n * Labelled `Component`, the name Box, Typography, the Document layer and the\n * Layout Slot already use — Section and Inline text keep `element` as their\n * stored KEY because their values are persisted in published screens, but the\n * panel says one thing everywhere (AGL-2514).\n */\nexport function semanticElementAttribute(\n  subject: string,\n): Aglyn.AglynAttributeSchema {\n  return {\n    name: 'component',\n    label: 'Component',\n    description:\n      `The DOM element ${subject} renders as. Use section/article/aside/nav/` +\n      'header/footer to give the region meaning for assistive tech and search ' +\n      'engines; div for purely visual grouping. \"main\" is not offered — the ' +\n      'page’s content region carries that one.',\n    component: Aglyn.FieldComponentType.SELECT,\n    options: SEMANTIC_ELEMENTS.map((value) => ({ value, label: value })),\n  } as Aglyn.AglynAttributeSchema\n}\n\n/**\n * The name for the landmark the picker just made, shown only once one exists.\n *\n * Gated on the element rather than always visible because on a `div` — the\n * default, and what most of these elements stay — the field would do nothing\n * at all, and a control that silently does nothing is worse than no control.\n *\n * This is the half Section already had and the picker did not. Naming stops\n * being optional the moment a page has two landmarks of a kind: a site nav and\n * a footer nav both announce as \"navigation\" until one of them says which.\n */\nexport function semanticElementLabelAttribute(): Aglyn.AglynAttributeSchema {\n  return {\n    name: 'ariaLabel',\n    label: 'Accessible label',\n    description:\n      'Names this region for screen readers. Required in practice once a ' +\n      'page has two landmarks of the same kind — a site nav and a footer ' +\n      'nav are both announced as \"navigation\" until one of them says which.',\n    component: Aglyn.FieldComponentType.TEXT_FIELD,\n    condition: { when: 'component', is: [...LANDMARK_ELEMENTS] },\n  } as Aglyn.AglynAttributeSchema\n}\n"],"names":["Aglyn","SEMANTIC_ELEMENTS","resolveSemanticElement","value","includes","String","undefined","LANDMARK_ELEMENTS","filter","element","applySemanticElement","props","component","ariaLabel","rest","label","trim","semanticElementProp","semanticElementAttribute","subject","name","description","FieldComponentType","SELECT","options","map","semanticElementLabelAttribute","TEXT_FIELD","condition","when","is"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,YAAYA,WAAW,eAAc;AAErC;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,MAAMC,oBAAoB;IAC/B;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAS;AAGV;;;;;;;;;CASC,GACD,OAAO,SAASC,uBAAuBC,KAAc;IACnD,OAAO,AAACF,kBAAwCG,QAAQ,CAACC,OAAOF,gBAAAA,QAAS,OACpEA,QACDG;AACN;AAEA;;;;;;;CAOC,GACD,OAAO,MAAMC,oBAAoBN,kBAAkBO,MAAM,CACvD,CAACC,UAAYA,YAAY,OAC1B;AAED;;;;;;;;CAQC,GACD,OAAO,SAASC,qBACdC,KAAQ;IAKR,MAAM,EAAEC,SAAS,EAAEC,SAAS,EAAW,GAAGF,OAATG,wCAASH;;;;IAI1C,MAAMF,UAAUP,uBAAuBU;IACvC,MAAMG,QAAQ,OAAOF,cAAc,WAAWA,UAAUG,IAAI,KAAK;IACjE,OAAO,aACDF,MACAL,UAAU;QAAEG,WAAWH;IAAQ,IAAI,CAAC,GAGpCA,WAAWA,YAAY,SAASM,QAAQ;QAAE,cAAcA;IAAM,IAAI,CAAC;AAE3E;AAEA;;;CAGC,GACD,OAAO,SAASE,oBACdd,KAAc;IAEd,MAAMM,UAAUP,uBAAuBC;IACvC,OAAOM,UAAU;QAAEG,WAAWH;IAAQ,IAAI,CAAC;AAC7C;AAEA;;;;;;;CAOC,GACD,OAAO,SAASS,yBACdC,OAAe;IAEf,OAAO;QACLC,MAAM;QACNL,OAAO;QACPM,aACE,CAAC,gBAAgB,EAAEF,QAAQ,2CAA2C,CAAC,GACvE,4EACA,0EACA;QACFP,WAAWZ,MAAMsB,kBAAkB,CAACC,MAAM;QAC1CC,SAASvB,kBAAkBwB,GAAG,CAAC,CAACtB,QAAW,CAAA;gBAAEA;gBAAOY,OAAOZ;YAAM,CAAA;IACnE;AACF;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASuB;IACd,OAAO;QACLN,MAAM;QACNL,OAAO;QACPM,aACE,uEACA,uEACA;QACFT,WAAWZ,MAAMsB,kBAAkB,CAACK,UAAU;QAC9CC,WAAW;YAAEC,MAAM;YAAaC,IAAI;mBAAIvB;aAAkB;QAAC;IAC7D;AACF"}

package/src/lib/utils/generate-preset-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2022 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 { ComponentId } from '@aglyn/aglyn';
+export declare const generatePresetId: (componentId: ComponentId, ...other: string[]) => ComponentId;
+export default generatePresetId;

package/src/lib/utils/generate-preset-id.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022 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 { BUNDLE_ID } from "../constants/bundle-common.js";
+export const generatePresetId = (componentId, ...other)=>{
+    return `${BUNDLE_ID}:${[
+        componentId,
+        ...other
+    ].join('.')}`;
+};
+export default generatePresetId;
+
+//# sourceMappingURL=generate-preset-id.js.map

package/src/lib/utils/generate-preset-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/utils/generate-preset-id.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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 { ComponentId } from '@aglyn/aglyn'\nimport { BUNDLE_ID } from '../constants/bundle-common'\n\nexport const generatePresetId = (\n  componentId: ComponentId,\n  ...other: string[]\n): ComponentId => {\n  return `${BUNDLE_ID}:${[componentId, ...other].join('.')}`\n}\n\nexport default generatePresetId\n"],"names":["BUNDLE_ID","generatePresetId","componentId","other","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,SAAS,QAAQ,gCAA4B;AAEtD,OAAO,MAAMC,mBAAmB,CAC9BC,aACA,GAAGC;IAEH,OAAO,GAAGH,UAAU,CAAC,EAAE;QAACE;WAAgBC;KAAM,CAACC,IAAI,CAAC,MAAM;AAC5D,EAAC;AAED,eAAeH,iBAAgB"}

package/src/lib/utils/link-target-props.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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.
+ */
+/**
+ * Where a link opens, as authored. Persisted in screen documents; never
+ * rename a value.
+ *
+ * - `'_self'` (or unset) — stays in the current tab, the browser default.
+ * - `'_blank'` — a new tab.
+ * - `'custom'` — a NAMED window, read from the companion `targetName` prop.
+ *   Not an anchor value itself; it is the sentinel that reveals the name
+ *   field, and never reaches the DOM.
+ */
+export type LinkTargetChoice = '_self' | '_blank' | 'custom';
+/** The anchor attributes a {@link LinkTargetChoice} resolves to. */
+export interface LinkTargetProps {
+    target?: string;
+    rel?: string;
+}
+/**
+ * Resolves the authored target pair to the attributes an anchor should carry.
+ *
+ * Returns NOTHING for the default choice rather than an explicit
+ * `target="_self"`: the two behave identically, and an absent attribute is
+ * what every link authored before this existed already renders — so adding
+ * the control moves no published markup.
+ *
+ * `rel` rides along because a target that opens elsewhere hands the new
+ * context a live `window.opener` handle back into this page. `noreferrer` is
+ * added only when the destination leaves the site: stripping the referrer
+ * from a link to one of the site's own screens would make the landing page
+ * read as direct traffic in its own analytics, which is a reporting defect,
+ * not a safety win.
+ *
+ * A cleared attribute persists as `null` or `''`, and a custom choice with
+ * an empty name is an author mid-edit — both fall back to the default rather
+ * than stamping an empty `target` on the anchor.
+ */
+export declare function linkTargetProps(target: LinkTargetChoice | string | null | undefined, targetName: string | null | undefined, leavesSite: boolean): LinkTargetProps;
+export default linkTargetProps;