@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/typography.js

@@ -0,0 +1,433 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+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 { mdiAlphabetical, mdiFormatHeader1, mdiFormatHeader2, mdiFormatHeader3, mdiFormatHeader4, mdiFormatHeader5, mdiFormatHeader6, mdiFormatText } from "@aglyn/shared-data-mdi";
+import Typography from "@mui/material/Typography";
+import { forwardRef } from "react";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { FIELD_TEXT_CONTENT } from "../constants/field-presets.js";
+import { dropClearedProps } from "../utils/drop-cleared-props.js";
+import { generatePresetId } from "../utils/generate-preset-id.js";
+// Component ids are persisted in screen documents; keep the legacy ids.
+export const ID = 'muiTypography';
+// The brand's own rungs sit alongside MUI's. They were added to the theme
+// (AGL-1308 for the body scale, for the display rung) but never to
+// this list, so the only way to reach one was to hand-write its pixels into
+// the Styles panel — which is the very thing the tokens exist to stop.
+// Display first: the list reads largest to smallest.
+//
+// Exported because it is the theme's rung list, not this element's: any block
+// that offers a type step has to offer the SAME one, or a rung added to the
+// theme becomes reachable from the Typography element and nowhere else.
+export const typographyVariants = [
+    {
+        value: 'displayXl',
+        label: 'Display XL',
+        icon: {
+            path: mdiFormatHeader1.path
+        }
+    },
+    {
+        value: 'h1',
+        label: 'Heading 1',
+        icon: {
+            path: mdiFormatHeader1.path
+        }
+    },
+    {
+        value: 'h2',
+        label: 'Heading 2',
+        icon: {
+            path: mdiFormatHeader2.path
+        }
+    },
+    {
+        value: 'h3',
+        label: 'Heading 3',
+        icon: {
+            path: mdiFormatHeader3.path
+        }
+    },
+    {
+        value: 'h4',
+        label: 'Heading 4',
+        icon: {
+            path: mdiFormatHeader4.path
+        }
+    },
+    {
+        value: 'h5',
+        label: 'Heading 5',
+        icon: {
+            path: mdiFormatHeader5.path
+        }
+    },
+    {
+        value: 'h6',
+        label: 'Heading 6',
+        icon: {
+            path: mdiFormatHeader6.path
+        }
+    },
+    {
+        value: 'subtitle1',
+        label: 'Subtitle 1',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'subtitle2',
+        label: 'Subtitle 2',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'body1',
+        label: 'Body 1',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'body2',
+        label: 'Body 2',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'lede',
+        label: 'Lede',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'overline',
+        label: 'Overline',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'caption',
+        label: 'Caption',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'bodyCompact',
+        label: 'Body compact',
+        icon: {
+            path: mdiFormatText.path
+        }
+    },
+    {
+        value: 'micro',
+        label: 'Micro',
+        icon: {
+            path: mdiFormatText.path
+        }
+    }
+];
+export const schema = {
+    $id: ID,
+    pluginId: BUNDLE_ID,
+    displayName: 'Typography',
+    description: "A block of text in one of the theme's type styles.",
+    category: Aglyn.ComponentCategory.TEXT,
+    icon: {
+        path: mdiAlphabetical.path,
+        sx: {
+            color: '#057822'
+        }
+    },
+    flags: {
+        textEditable: Aglyn.FEATURE_FLAG.ENABLED,
+        richTextEditable: Aglyn.FEATURE_FLAG.ENABLED
+    },
+    attributes: [
+        FIELD_TEXT_CONTENT,
+        // FIELD_COLOR,
+        {
+            name: 'variant',
+            description: 'Which typography step from the site theme this text uses — h1–h6, ' + 'body, subtitle, caption, overline. It sets size, weight and line ' + 'height together; it does NOT change the HTML element, which is the ' + 'field below.',
+            component: Aglyn.FieldComponentType.SELECT,
+            label: 'Variant',
+            // "Default" deleted (AGL-1453): unpersistable, and a second name for
+            // `body1`, MUI's own default, already in `typographyVariants`.
+            options: [
+                ...typographyVariants
+            ]
+        },
+        {
+            name: 'component',
+            description: 'The html element to use.',
+            component: Aglyn.FieldComponentType.SELECT,
+            label: 'Component',
+            // "Default" deleted rather than given a sentinel (AGL-1453), and this
+            // is the prop that shows why a sentinel is not always available: MUI
+            // derives the element from `variantMapping[variant]`, so "Default"
+            // resolves to a DIFFERENT tag per variant — `h2` for a Heading 2, `p`
+            // for Body 1. No single value on this list expresses that, and picking
+            // one would pin the tag and change the document outline. Unset is the
+            // only thing that means "let the variant decide", and the field's ✕ is
+            // how an author says it.
+            options: [
+                {
+                    value: 'h1',
+                    label: 'Heading 1'
+                },
+                {
+                    value: 'h2',
+                    label: 'Heading 2'
+                },
+                {
+                    value: 'h3',
+                    label: 'Heading 3'
+                },
+                {
+                    value: 'h4',
+                    label: 'Heading 4'
+                },
+                {
+                    value: 'h5',
+                    label: 'Heading 5'
+                },
+                {
+                    value: 'h6',
+                    label: 'Heading 6'
+                },
+                {
+                    value: 'p',
+                    label: 'Paragraph'
+                },
+                {
+                    value: 'div',
+                    label: 'Div'
+                },
+                {
+                    value: 'span',
+                    label: 'Span'
+                }
+            ]
+        },
+        {
+            name: 'align',
+            description: 'The text alignment',
+            component: Aglyn.FieldComponentType.SELECT,
+            label: 'Alignment',
+            // "Default" deleted (AGL-1453): unpersistable, and a second name for
+            // `inherit`, MUI Typography's own default, already on the list.
+            options: [
+                {
+                    value: 'inherit',
+                    label: 'Inherit'
+                },
+                {
+                    value: 'left',
+                    label: 'Left'
+                },
+                {
+                    value: 'center',
+                    label: 'Center'
+                },
+                {
+                    value: 'right',
+                    label: 'Right'
+                },
+                {
+                    value: 'justify',
+                    label: 'Justified'
+                }
+            ]
+        },
+        {
+            name: 'noWrap',
+            description: 'If true, the text will not wrap/fold.',
+            component: Aglyn.FieldComponentType.SWITCH,
+            label: 'Disable wrapping?'
+        },
+        {
+            name: 'gutterBottom',
+            description: 'If true, the text will have a space beneath.',
+            component: Aglyn.FieldComponentType.SWITCH,
+            label: 'Gutter bottom?'
+        }
+    ]
+};
+export const presets = [
+    ...typographyVariants.map((item)=>({
+            $id: generatePresetId(ID, item.value),
+            type: Aglyn.NodeType.PRESET,
+            displayName: item.label,
+            pluginId: BUNDLE_ID,
+            description: `Element with ${item.label} styles`,
+            category: Aglyn.ComponentCategory.TEXT,
+            icon: _extends({
+                sx: {
+                    color: '#057822'
+                }
+            }, item.icon),
+            data: {
+                $id: null,
+                componentId: ID,
+                pluginId: BUNDLE_ID,
+                props: {
+                    variant: item.value,
+                    children: item.label
+                }
+            }
+        }))
+];
+/**
+ * Typography that renders rich text (AGL-54): when the node carries an
+ * `html` prop it renders as innerHTML; otherwise plain `children`.
+ *
+ * The `html` prop is re-sanitized on EVERY render (AGL-497). The inline
+ * editor sanitizes at commit, but screen node props are written directly via
+ * the Firebase client SDK, so a host editor can plant arbitrary `html`
+ * (bypassing the editor) that would execute on the public site AND in the
+ * besigner canvas on app.aglyn.com.
+ *
+ * The sanitizer is `Aglyn.sanitizeAuthorHtml` (AGL-1901), which needs no DOM
+ * and so runs on the server too — the DOMPurify call this replaced could
+ * not, which is why the content used to be deferred to an effect and left
+ * every rich-text body out of the server response. The allowlist it enforces
+ * is a subset of the old DOMPurify config's, pinned pair by pair in
+ * `rich-text-hydration.spec.tsx`.
+ */ function sanitizeTypographyHtml(html) {
+    return Aglyn.sanitizeAuthorHtml(html);
+}
+/**
+ * MUI's own `defaultVariantMapping`, plus its `span` fallback — the element
+ * Typography will actually render for a given variant. Copied rather than
+ * imported because MUI does not export it; `author-html-round-trip.spec.tsx`
+ * asserts this table still matches what MUI actually renders, so a MUI upgrade that
+ * changed the mapping fails there rather than silently reopening the
+ * reparenting hazard below.
+ */ /**
+ * The element each variant renders as, and the ONE place that decides
+ *.
+ *
+ * MUI's own `variantMapping` sends `subtitle1` and `subtitle2` to `<h6>`.
+ * That is a typographic choice made in a component library, and on a page
+ * builder it is a document-outline decision made by somebody who has never
+ * seen the page: a subtitle is a label, not a section, and every one on every
+ * Aglyn site was silently inserting an `<h6>` into the heading order. It is
+ * what Lighthouse's `heading-order` was reporting — a "Open source &
+ * self-hostable" card label rendering ahead of the page's own `<h1>`, from a
+ * node whose author had selected Subtitle 1 and nothing else.
+ *
+ * Subtitles render as `<p>` here. An author who wants a heading still says so
+ * with the Component field, which is the control for exactly that question
+ * and is unchanged.
+ *
+ * Passed to MUI as `variantMapping` rather than only consulted by
+ * `blockSafeComponent`, so the table cannot describe one thing while the
+ * element is another.
+ */ const VARIANT_ELEMENT = {
+    h1: 'h1',
+    h2: 'h2',
+    h3: 'h3',
+    h4: 'h4',
+    h5: 'h5',
+    h6: 'h6',
+    subtitle1: 'p',
+    subtitle2: 'p',
+    body1: 'p',
+    body2: 'p',
+    inherit: 'p'
+};
+/**
+ * The element the rich-text body is put INSIDE, which may have to be a
+ * `<div>` rather than the one the variant implies (AGL-1901).
+ *
+ * The parser closes a `<p>` on any block start tag, and a heading on any
+ * other heading. So a body with an `<h2>` in it, served inside the `<p>` MUI
+ * renders for `body1`, arrives at the browser as
+ * `<p class="MuiTypography-root"></p><h2>…</h2>` — the container emptied and
+ * the body promoted to a sibling. React then hydrates against a DOM that is
+ * not the one it described and reports a mismatch: the live React #418 shape
+ * on tenant (AGL-1926), which this change must not add to.
+ *
+ * This never mattered before because the server `<p>` was EMPTY and the body
+ * arrived through an `innerHTML` assignment, which parses in the CONTEXT of
+ * the `<p>` and so does not reparent. Serving the body is what makes the
+ * container's element type load-bearing.
+ *
+ * `authorHtmlBreaksContainer` holds the rule, next to the table of tags it
+ * depends on. Returns `'div'` to override, or `undefined` to leave MUI's
+ * choice alone; the decision is a pure function of props, so the server and
+ * the client make it identically.
+ */ function blockSafeComponent(sanitized, rest) {
+    var _ref, _rest_component, _rest_variant;
+    const element = (_ref = (_rest_component = rest.component) != null ? _rest_component : // MUI's own default variant is `body1`, which maps to `p` — the case that
+    // matters, since a Typography with no variant set is the shape nearly
+    // every rich-text node has. (`paragraph` is gone in MUI v7, so the
+    // variant mapping is the only other input.)
+    VARIANT_ELEMENT[(_rest_variant = rest.variant) != null ? _rest_variant : 'body1']) != null ? _ref : 'span';
+    return Aglyn.authorHtmlBreaksContainer(sanitized, element) ? 'div' : undefined;
+}
+const AglynTypography = /*#__PURE__*/ forwardRef(function AglynTypography(props, ref) {
+    const { html, children } = props, spread = _object_without_properties_loose(props, [
+        "html",
+        "children"
+    ]);
+    // A cleared `align` persists as null and MUI capitalizes it — an SSR throw
+    // that 500s the page (AGL-1226, same shape as the button colour).
+    const rest = dropClearedProps(spread);
+    const hasHtml = typeof html === 'string' && Boolean(html);
+    // Sanitized DURING render, on the server and in the browser alike
+    // (AGL-1901). The effect this replaced existed because DOMPurify needs a
+    // DOM: the server rendered nothing, so the first client render had to
+    // render nothing too or hydration would mismatch (AGL-1268) — the two
+    // sides agreed only by both being empty, and the body never reached a
+    // crawler. `sanitizeAuthorHtml` is a pure function of the string with no
+    // DOM dependency, so both sides now compute the same bytes from the same
+    // prop and agree on the CONTENT instead of on the absence of it.
+    const sanitized = hasHtml ? sanitizeTypographyHtml(html) : null;
+    if (sanitized !== null) {
+        // A `<p>` cannot hold the block content a rich-text body may contain —
+        // see `blockSafeComponent`. `undefined` leaves MUI's own choice alone.
+        const component = blockSafeComponent(sanitized, rest);
+        return /*#__PURE__*/ _jsx(Typography, _extends({
+            ref: ref,
+            variantMapping: VARIANT_ELEMENT
+        }, rest, component ? {
+            component
+        } : {}, {
+            dangerouslySetInnerHTML: {
+                __html: sanitized
+            }
+        }));
+    }
+    return /*#__PURE__*/ _jsx(Typography, _extends({
+        ref: ref,
+        variantMapping: VARIANT_ELEMENT
+    }, rest, {
+        children: children
+    }));
+});
+export default AglynTypography;
+
+//# sourceMappingURL=typography.js.map

package/src/lib/components/typography.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/components/typography.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 {\n  mdiAlphabetical,\n  mdiFormatHeader1,\n  mdiFormatHeader2,\n  mdiFormatHeader3,\n  mdiFormatHeader4,\n  mdiFormatHeader5,\n  mdiFormatHeader6,\n  mdiFormatText,\n} from '@aglyn/shared-data-mdi'\nimport Typography, { type TypographyProps } from '@mui/material/Typography'\nimport { forwardRef } from 'react'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { FIELD_TEXT_CONTENT } from '../constants/field-presets'\nimport { dropClearedProps } from '../utils/drop-cleared-props'\nimport { generatePresetId } from '../utils/generate-preset-id'\n\n// Component ids are persisted in screen documents; keep the legacy ids.\nexport const ID: Aglyn.ComponentId = 'muiTypography'\n// The brand's own rungs sit alongside MUI's. They were added to the theme\n// (AGL-1308 for the body scale, for the display rung) but never to\n// this list, so the only way to reach one was to hand-write its pixels into\n// the Styles panel — which is the very thing the tokens exist to stop.\n// Display first: the list reads largest to smallest.\n//\n// Exported because it is the theme's rung list, not this element's: any block\n// that offers a type step has to offer the SAME one, or a rung added to the\n// theme becomes reachable from the Typography element and nowhere else.\nexport const typographyVariants = [\n  {\n    value: 'displayXl',\n    label: 'Display XL',\n    icon: { path: mdiFormatHeader1.path },\n  },\n  { value: 'h1', label: 'Heading 1', icon: { path: mdiFormatHeader1.path } },\n  { value: 'h2', label: 'Heading 2', icon: { path: mdiFormatHeader2.path } },\n  { value: 'h3', label: 'Heading 3', icon: { path: mdiFormatHeader3.path } },\n  { value: 'h4', label: 'Heading 4', icon: { path: mdiFormatHeader4.path } },\n  { value: 'h5', label: 'Heading 5', icon: { path: mdiFormatHeader5.path } },\n  { value: 'h6', label: 'Heading 6', icon: { path: mdiFormatHeader6.path } },\n  {\n    value: 'subtitle1',\n    label: 'Subtitle 1',\n    icon: { path: mdiFormatText.path },\n  },\n  {\n    value: 'subtitle2',\n    label: 'Subtitle 2',\n    icon: { path: mdiFormatText.path },\n  },\n  { value: 'body1', label: 'Body 1', icon: { path: mdiFormatText.path } },\n  { value: 'body2', label: 'Body 2', icon: { path: mdiFormatText.path } },\n  { value: 'lede', label: 'Lede', icon: { path: mdiFormatText.path } },\n  { value: 'overline', label: 'Overline', icon: { path: mdiFormatText.path } },\n  { value: 'caption', label: 'Caption', icon: { path: mdiFormatText.path } },\n  {\n    value: 'bodyCompact',\n    label: 'Body compact',\n    icon: { path: mdiFormatText.path },\n  },\n  { value: 'micro', label: 'Micro', icon: { path: mdiFormatText.path } },\n]\n\nexport const schema: Aglyn.ComponentSchema = {\n  $id: ID,\n  pluginId: BUNDLE_ID,\n  displayName: 'Typography',\n  description: \"A block of text in one of the theme's type styles.\",\n  category: Aglyn.ComponentCategory.TEXT,\n  icon: {\n    path: mdiAlphabetical.path,\n    sx: { color: '#057822' },\n  },\n  flags: {\n    textEditable: Aglyn.FEATURE_FLAG.ENABLED,\n    richTextEditable: Aglyn.FEATURE_FLAG.ENABLED,\n  },\n  attributes: [\n    FIELD_TEXT_CONTENT,\n    // FIELD_COLOR,\n    {\n      name: 'variant',\n      description:\n        'Which typography step from the site theme this text uses — h1–h6, ' +\n        'body, subtitle, caption, overline. It sets size, weight and line ' +\n        'height together; it does NOT change the HTML element, which is the ' +\n        'field below.',\n      component: Aglyn.FieldComponentType.SELECT,\n      label: 'Variant',\n      // \"Default\" deleted (AGL-1453): unpersistable, and a second name for\n      // `body1`, MUI's own default, already in `typographyVariants`.\n      options: [...typographyVariants],\n    },\n    {\n      name: 'component',\n      description: 'The html element to use.',\n      component: Aglyn.FieldComponentType.SELECT,\n      label: 'Component',\n      // \"Default\" deleted rather than given a sentinel (AGL-1453), and this\n      // is the prop that shows why a sentinel is not always available: MUI\n      // derives the element from `variantMapping[variant]`, so \"Default\"\n      // resolves to a DIFFERENT tag per variant — `h2` for a Heading 2, `p`\n      // for Body 1. No single value on this list expresses that, and picking\n      // one would pin the tag and change the document outline. Unset is the\n      // only thing that means \"let the variant decide\", and the field's ✕ is\n      // how an author says it.\n      options: [\n        { value: 'h1', label: 'Heading 1' },\n        { value: 'h2', label: 'Heading 2' },\n        { value: 'h3', label: 'Heading 3' },\n        { value: 'h4', label: 'Heading 4' },\n        { value: 'h5', label: 'Heading 5' },\n        { value: 'h6', label: 'Heading 6' },\n        { value: 'p', label: 'Paragraph' },\n        { value: 'div', label: 'Div' },\n        { value: 'span', label: 'Span' },\n      ],\n    },\n    {\n      name: 'align',\n      description: 'The text alignment',\n      component: Aglyn.FieldComponentType.SELECT,\n      label: 'Alignment',\n      // \"Default\" deleted (AGL-1453): unpersistable, and a second name for\n      // `inherit`, MUI Typography's own default, already on the list.\n      options: [\n        { value: 'inherit', label: 'Inherit' },\n        { value: 'left', label: 'Left' },\n        { value: 'center', label: 'Center' },\n        { value: 'right', label: 'Right' },\n        { value: 'justify', label: 'Justified' },\n      ],\n    },\n    {\n      name: 'noWrap',\n      description: 'If true, the text will not wrap/fold.',\n      component: Aglyn.FieldComponentType.SWITCH,\n      label: 'Disable wrapping?',\n    },\n    {\n      name: 'gutterBottom',\n      description: 'If true, the text will have a space beneath.',\n      component: Aglyn.FieldComponentType.SWITCH,\n      label: 'Gutter bottom?',\n    },\n  ],\n}\n\nexport const presets: Aglyn.PresetSchema[] = [\n  ...typographyVariants.map((item): Aglyn.PresetSchema => ({\n    $id: generatePresetId(ID, item.value),\n    type: Aglyn.NodeType.PRESET,\n    displayName: item.label,\n    pluginId: BUNDLE_ID,\n    description: `Element with ${item.label} styles`,\n    category: Aglyn.ComponentCategory.TEXT,\n    icon: {\n      sx: { color: '#057822' },\n      ...item.icon,\n    },\n    data: {\n      $id: null,\n      componentId: ID,\n      pluginId: BUNDLE_ID,\n      props: {\n        variant: item.value,\n        children: item.label,\n      },\n    },\n  })),\n]\n\n/**\n * Typography that renders rich text (AGL-54): when the node carries an\n * `html` prop it renders as innerHTML; otherwise plain `children`.\n *\n * The `html` prop is re-sanitized on EVERY render (AGL-497). The inline\n * editor sanitizes at commit, but screen node props are written directly via\n * the Firebase client SDK, so a host editor can plant arbitrary `html`\n * (bypassing the editor) that would execute on the public site AND in the\n * besigner canvas on app.aglyn.com.\n *\n * The sanitizer is `Aglyn.sanitizeAuthorHtml` (AGL-1901), which needs no DOM\n * and so runs on the server too — the DOMPurify call this replaced could\n * not, which is why the content used to be deferred to an effect and left\n * every rich-text body out of the server response. The allowlist it enforces\n * is a subset of the old DOMPurify config's, pinned pair by pair in\n * `rich-text-hydration.spec.tsx`.\n */\nfunction sanitizeTypographyHtml(html: string): string {\n  return Aglyn.sanitizeAuthorHtml(html)\n}\n\n/**\n * MUI's own `defaultVariantMapping`, plus its `span` fallback — the element\n * Typography will actually render for a given variant. Copied rather than\n * imported because MUI does not export it; `author-html-round-trip.spec.tsx`\n * asserts this table still matches what MUI actually renders, so a MUI upgrade that\n * changed the mapping fails there rather than silently reopening the\n * reparenting hazard below.\n */\n/**\n * The element each variant renders as, and the ONE place that decides\n *.\n *\n * MUI's own `variantMapping` sends `subtitle1` and `subtitle2` to `<h6>`.\n * That is a typographic choice made in a component library, and on a page\n * builder it is a document-outline decision made by somebody who has never\n * seen the page: a subtitle is a label, not a section, and every one on every\n * Aglyn site was silently inserting an `<h6>` into the heading order. It is\n * what Lighthouse's `heading-order` was reporting — a \"Open source &\n * self-hostable\" card label rendering ahead of the page's own `<h1>`, from a\n * node whose author had selected Subtitle 1 and nothing else.\n *\n * Subtitles render as `<p>` here. An author who wants a heading still says so\n * with the Component field, which is the control for exactly that question\n * and is unchanged.\n *\n * Passed to MUI as `variantMapping` rather than only consulted by\n * `blockSafeComponent`, so the table cannot describe one thing while the\n * element is another.\n */\nconst VARIANT_ELEMENT: Record<string, string> = {\n  h1: 'h1', h2: 'h2', h3: 'h3', h4: 'h4', h5: 'h5', h6: 'h6',\n  subtitle1: 'p', subtitle2: 'p', body1: 'p', body2: 'p', inherit: 'p',\n}\n\n/**\n * The element the rich-text body is put INSIDE, which may have to be a\n * `<div>` rather than the one the variant implies (AGL-1901).\n *\n * The parser closes a `<p>` on any block start tag, and a heading on any\n * other heading. So a body with an `<h2>` in it, served inside the `<p>` MUI\n * renders for `body1`, arrives at the browser as\n * `<p class=\"MuiTypography-root\"></p><h2>…</h2>` — the container emptied and\n * the body promoted to a sibling. React then hydrates against a DOM that is\n * not the one it described and reports a mismatch: the live React #418 shape\n * on tenant (AGL-1926), which this change must not add to.\n *\n * This never mattered before because the server `<p>` was EMPTY and the body\n * arrived through an `innerHTML` assignment, which parses in the CONTEXT of\n * the `<p>` and so does not reparent. Serving the body is what makes the\n * container's element type load-bearing.\n *\n * `authorHtmlBreaksContainer` holds the rule, next to the table of tags it\n * depends on. Returns `'div'` to override, or `undefined` to leave MUI's\n * choice alone; the decision is a pure function of props, so the server and\n * the client make it identically.\n */\nfunction blockSafeComponent(\n  sanitized: string,\n  rest: TypographyProps,\n): 'div' | undefined {\n  const element =\n    (rest.component as string | undefined) ??\n    // MUI's own default variant is `body1`, which maps to `p` — the case that\n    // matters, since a Typography with no variant set is the shape nearly\n    // every rich-text node has. (`paragraph` is gone in MUI v7, so the\n    // variant mapping is the only other input.)\n    VARIANT_ELEMENT[(rest.variant as string) ?? 'body1'] ??\n    'span'\n  return Aglyn.authorHtmlBreaksContainer(sanitized, element) ? 'div' : undefined\n}\n\nconst AglynTypography = forwardRef<\n  HTMLElement,\n  TypographyProps & { html?: string }\n>(function AglynTypography(props, ref) {\n  const { html, children, ...spread } = props\n  // A cleared `align` persists as null and MUI capitalizes it — an SSR throw\n  // that 500s the page (AGL-1226, same shape as the button colour).\n  const rest = dropClearedProps(spread)\n  const hasHtml = typeof html === 'string' && Boolean(html)\n  // Sanitized DURING render, on the server and in the browser alike\n  // (AGL-1901). The effect this replaced existed because DOMPurify needs a\n  // DOM: the server rendered nothing, so the first client render had to\n  // render nothing too or hydration would mismatch (AGL-1268) — the two\n  // sides agreed only by both being empty, and the body never reached a\n  // crawler. `sanitizeAuthorHtml` is a pure function of the string with no\n  // DOM dependency, so both sides now compute the same bytes from the same\n  // prop and agree on the CONTENT instead of on the absence of it.\n  const sanitized = hasHtml ? sanitizeTypographyHtml(html as string) : null\n  if (sanitized !== null) {\n    // A `<p>` cannot hold the block content a rich-text body may contain —\n    // see `blockSafeComponent`. `undefined` leaves MUI's own choice alone.\n    const component = blockSafeComponent(sanitized, rest as TypographyProps)\n    return (\n      <Typography\n        ref={ref}\n        variantMapping={VARIANT_ELEMENT}\n        {...rest}\n        {...(component ? { component } : {})}\n        dangerouslySetInnerHTML={{ __html: sanitized }}\n      />\n    )\n  }\n  return (\n    <Typography ref={ref} variantMapping={VARIANT_ELEMENT} {...rest}>\n      {children}\n    </Typography>\n  )\n})\n\nexport default AglynTypography\n"],"names":["Aglyn","mdiAlphabetical","mdiFormatHeader1","mdiFormatHeader2","mdiFormatHeader3","mdiFormatHeader4","mdiFormatHeader5","mdiFormatHeader6","mdiFormatText","Typography","forwardRef","BUNDLE_ID","FIELD_TEXT_CONTENT","dropClearedProps","generatePresetId","ID","typographyVariants","value","label","icon","path","schema","$id","pluginId","displayName","description","category","ComponentCategory","TEXT","sx","color","flags","textEditable","FEATURE_FLAG","ENABLED","richTextEditable","attributes","name","component","FieldComponentType","SELECT","options","SWITCH","presets","map","item","type","NodeType","PRESET","data","componentId","props","variant","children","sanitizeTypographyHtml","html","sanitizeAuthorHtml","VARIANT_ELEMENT","h1","h2","h3","h4","h5","h6","subtitle1","subtitle2","body1","body2","inherit","blockSafeComponent","sanitized","rest","element","authorHtmlBreaksContainer","undefined","AglynTypography","ref","spread","hasHtml","Boolean","variantMapping","dangerouslySetInnerHTML","__html"],"mappings":"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"}

package/src/lib/components/video-lightbox-controls.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @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 Theme } from '@mui/material/styles';
+import { type KeyboardEvent, type RefObject } from 'react';
+/** One arrow press on the playhead, on the seek slider or from any other stop. */
+export declare const SEEK_STEP_SECONDS = 5;
+/** `Page Up` and `Page Down` on the seek slider, and an arrow held with `Shift`. */
+export declare const SEEK_PAGE_SECONDS = 10;
+/**
+ * A player clock: `m:ss`, or `h:mm:ss` from an hour up.
+ *
+ * A duration the browser does not know yet (`NaN`, before metadata) or cannot
+ * know (`Infinity`, a stream) reads as `0:00` rather than as `NaN:NaN`.
+ */
+export declare function formatMediaTime(seconds: number): string;
+/** What the seek slider says its value is: `1:23 of 4:10`. */
+export declare function seekValueText(position: number, duration: number): string;
+/** The two elements the controls and the keyboard act on. */
+export interface LightboxPlayerElements {
+    video: HTMLVideoElement | null;
+    /**
+     * The frame that goes full screen: the film AND these controls, so they are
+     * still on screen, and still reachable from the keyboard, once it has.
+     */
+    player: HTMLElement | null;
+}
+/**
+ * Play or pause.
+ *
+ * `play()` rejects when the browser refuses playback, and the refusal needs
+ * no handling: no `play` event fires, so the control goes on reporting a
+ * paused film, which is the truth.
+ */
+export declare function togglePlayback(video: HTMLVideoElement): void;
+/**
+ * Moves the playhead, clamped to the film, and returns where it landed.
+ * Before the duration is known there is nowhere to land, and nothing moves.
+ */
+export declare function seekPlayback(video: HTMLVideoElement, seconds: number): number | undefined;
+export declare function toggleMute(video: HTMLVideoElement): void;
+/**
+ * Whether a full-screen control would do anything here.
+ *
+ * `fullscreenEnabled` is false inside a frame whose embedder did not allow it,
+ * and there the control is left out rather than shown doing nothing. A phone
+ * with no element full screen at all still gets the video-only kind, which
+ * plays under the platform's own controls.
+ */
+export declare function fullscreenAvailable(): boolean;
+export declare function toggleFullscreen({ video, player }: LightboxPlayerElements): void;
+/**
+ * Whether the focused element uses `key` for itself, in which case no shortcut
+ * may take it: `Space` and `Enter` press a focused button, the arrows and
+ * `Home`/`End` move a focused slider, and a text field wants every key.
+ */
+export declare function keyBelongsToFocus(target: EventTarget | null, key: string): boolean;
+/**
+ * The dialog's `onKeyDown`: the player's shortcuts, from every stop inside it.
+ *
+ * Bound on the Modal root rather than on the controls, because focus is not
+ * always on a control — a click on the film leaves it on the dialog container
+ * — and a key pressed anywhere in the dialog bubbles through the root. MUI
+ * calls this before its own `Escape` handling, and nothing here touches
+ * `Escape`.
+ *
+ * A key the focused control uses for itself is left alone, and so is any key
+ * a control already claimed: MUI's Slider calls `preventDefault` on the keys
+ * it moves with, which is how an arrow on a slider stays that slider's.
+ */
+export declare function handlePlayerShortcut(event: KeyboardEvent<Element>, { video, player }: LightboxPlayerElements): void;
+/**
+ * Every button on the player, the dialog's close button included.
+ *
+ * IconButton's own hover rule reads `--IconButton-hoverBg`, `hover: none`
+ * reset and all; its default is a tint of `action.active`, which on a light
+ * site's palette is black on this black ground and never shows. The ripple is
+ * motion, so it goes for a visitor who asked for less, and it is gated in CSS
+ * as the poster's play badge is so the setting resolves in both directions.
+ */
+export declare const controlButtonSx: (theme: Theme) => {
+    color: string;
+    '--IconButton-hoverBg': string;
+    '&:focus-visible': {
+        outline: string;
+        outlineColor: string;
+        outlineOffset: number;
+    };
+    '@media (prefers-reduced-motion: reduce)': {
+        [x: string]: {
+            display: string;
+        };
+    };
+};
+export interface VideoLightboxControlsProps {
+    videoRef: RefObject<HTMLVideoElement | null>;
+    /** See {@link LightboxPlayerElements.player}. */
+    playerRef: RefObject<HTMLElement | null>;
+    /** The film carries a captions track, so a toggle for it belongs here. */
+    captions?: boolean;
+}
+/**
+ * The bar under the film: a seek slider across the top, then play, the clock,
+ * mute, volume, captions and full screen.
+ *
+ * Each control is a real `<button>` or a real range input with a name and a
+ * state: `aria-pressed` on the toggles, a spoken `1:23 of 4:10` on the seek
+ * slider, `aria-keyshortcuts` where a key does the same thing.
+ *
+ * What the controls draw is read back off the `<video>` on its own events
+ * rather than kept beside it, so a button, a shortcut, a click on the film and
+ * the platform's media keys all end in one place, and the play beacon's
+ * handlers on the element hear every one of them.
+ */
+export declare function VideoLightboxControls(props: VideoLightboxControlsProps): import("react").JSX.Element;
+export declare namespace VideoLightboxControls {
+    var displayName: string;
+}