@allxsmith/bestax-bulma 5.59.0 → 5.61.0

package/dist/esm/helpers/useInertSiblings.js

@@ -76,16 +76,20 @@ const above = (el) => el.parentElement ?? el.getRootNode().host;
  * @param active - Whether what's beside it is inert.
  * @param wholePage - Whether that goes for the whole page rather than only
  * the element's siblings.
+ * @param except - Ref to an element beside it to leave reachable too, such
+ * as the overlay's own backdrop, which has to take the presses that close
+ * it rather than let them through to what's under it.
  */
-function useInertSiblings(ref, active, wholePage) {
+function useInertSiblings(ref, active, wholePage, except) {
     useEffect(() => {
         const el = ref.current;
         if (!active || !el)
             return undefined;
         const doc = el.ownerDocument;
+        const keep = except?.current;
         const held = [];
         for (let node = el; node && node !== doc.body; node = wholePage ? above(node) : undefined) {
-            held.push(...siblingsOf(node).filter(hold));
+            held.push(...siblingsOf(node).filter(sibling => sibling !== keep && hold(sibling)));
         }
         // Focus this takes away, to hand back later. It's looked up as `el`'s
         // tree sees it, where focus inside a nested shadow root reads as its
@@ -100,7 +104,7 @@ function useInertSiblings(ref, active, wholePage) {
             if (doc.activeElement === doc.body)
                 taken?.focus();
         };
-    }, [ref, active, wholePage]);
+    }, [ref, active, wholePage, except]);
 }
 
 export { useInertSiblings };

package/dist/esm/helpers/useInertSiblings.js.map

@@ -1 +1 @@
-{"version":3,"file":"useInertSiblings.js","sources":["../../../src/helpers/useInertSiblings.ts"],"sourcesContent":["// INTERNAL: deliberately not exported from src/index.ts.\nimport { useEffect } from 'react';\nimport type { RefObject } from 'react';\nimport { getActiveElementInTree, getDeepestActiveElement } from './shadowDom';\n\n/**\n * How many callers hold each element inert. Shared across callers, the way\n * the scroll lock's count is, so two that cover the same element don't take\n * `inert` off it while the other still needs it. An element that was inert\n * before any caller came isn't counted, so it's left as it was.\n */\nconst holds = new Map<Element, number>();\n\n/**\n * Makes `el` inert for one more caller. Returns `false`, touching nothing,\n * when it was inert already and no caller made it so.\n */\nfunction hold(el: Element): boolean {\n  const count = holds.get(el) ?? 0;\n  if (count === 0 && el.hasAttribute('inert')) return false;\n  holds.set(el, count + 1);\n  el.setAttribute('inert', '');\n  return true;\n}\n\n/** Lets go of one caller's hold, and takes `inert` off with the last one. */\nfunction release(el: Element): void {\n  const count = (holds.get(el) as number) - 1;\n  if (count > 0) {\n    holds.set(el, count);\n    return;\n  }\n  holds.delete(el);\n  el.removeAttribute('inert');\n}\n\n/** The element's siblings, in a shadow root as anywhere else. */\nfunction siblingsOf(el: Element): Element[] {\n  const siblings: Element[] = [];\n  for (let s = el.previousElementSibling; s; s = s.previousElementSibling) {\n    siblings.push(s);\n  }\n  for (let s = el.nextElementSibling; s; s = s.nextElementSibling) {\n    siblings.push(s);\n  }\n  return siblings;\n}\n\n/**\n * The element above `el` in the page: its parent, or the host of the shadow\n * root it sits at the top of. Nothing above the top of a detached tree.\n */\nconst above = (el: Element): Element | undefined =>\n  el.parentElement ?? (el.getRootNode() as Partial<ShadowRoot>).host;\n\n/**\n * Makes the elements beside `ref`'s element inert while `active` is true,\n * and takes it off again when `active` turns false or the caller unmounts.\n * With `wholePage`, it does the same beside each element above it up to\n * `<body>`, so everything on the page but `ref`'s element is inert, the way a\n * modal layer leaves it. The element itself and its own content are never\n * touched.\n *\n * It sets the `inert` attribute through the DOM in an effect, so it works the\n * same on React 18 and 19 and a server render has nothing to show for it. An\n * element that was inert already is left alone, and keeps its `inert` once\n * this lets go. It makes inert what's there when it turns on: an element that\n * mounts beside it afterwards isn't. It follows the DOM, so content a web\n * component renders around a slot this sits in, and text with no element of\n * its own, stays as it is.\n *\n * Focus on an element that turns inert is lost: the browser moves it to\n * `<body>`. So when focus was inside what this made inert, and is still on\n * `<body>` when this lets go, it goes back to the element that had it. Focus\n * this never took isn't handed anywhere, and focus the user or the app has\n * put somewhere else meanwhile stays there.\n *\n * @function useInertSiblings\n * @param ref - Ref to the element that stays reachable.\n * @param active - Whether what's beside it is inert.\n * @param wholePage - Whether that goes for the whole page rather than only\n * the element's siblings.\n */\nexport function useInertSiblings(\n  ref: RefObject<Element | null>,\n  active: boolean,\n  wholePage: boolean\n): void {\n  useEffect(() => {\n    const el = ref.current;\n    if (!active || !el) return undefined;\n    const doc = el.ownerDocument;\n\n    const held: Element[] = [];\n    for (\n      let node: Element | undefined = el;\n      node && node !== doc.body;\n      node = wholePage ? above(node) : undefined\n    ) {\n      held.push(...siblingsOf(node).filter(hold));\n    }\n\n    // Focus this takes away, to hand back later. It's looked up as `el`'s\n    // tree sees it, where focus inside a nested shadow root reads as its\n    // host, so it compares with what's held. What gets focused again is the\n    // element that really had focus, inside that shadow root.\n    const focused = getActiveElementInTree(el);\n    const taken = held.some(other => other.contains(focused))\n      ? (getDeepestActiveElement(doc) as HTMLElement | null)\n      : null;\n\n    return () => {\n      held.forEach(release);\n      if (doc.activeElement === doc.body) taken?.focus();\n    };\n  }, [ref, active, wholePage]);\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useInertSiblings.js","sources":["../../../src/helpers/useInertSiblings.ts"],"sourcesContent":["// INTERNAL: deliberately not exported from src/index.ts.\nimport { useEffect } from 'react';\nimport type { RefObject } from 'react';\nimport { getActiveElementInTree, getDeepestActiveElement } from './shadowDom';\n\n/**\n * How many callers hold each element inert. Shared across callers, the way\n * the scroll lock's count is, so two that cover the same element don't take\n * `inert` off it while the other still needs it. An element that was inert\n * before any caller came isn't counted, so it's left as it was.\n */\nconst holds = new Map<Element, number>();\n\n/**\n * Makes `el` inert for one more caller. Returns `false`, touching nothing,\n * when it was inert already and no caller made it so.\n */\nfunction hold(el: Element): boolean {\n  const count = holds.get(el) ?? 0;\n  if (count === 0 && el.hasAttribute('inert')) return false;\n  holds.set(el, count + 1);\n  el.setAttribute('inert', '');\n  return true;\n}\n\n/** Lets go of one caller's hold, and takes `inert` off with the last one. */\nfunction release(el: Element): void {\n  const count = (holds.get(el) as number) - 1;\n  if (count > 0) {\n    holds.set(el, count);\n    return;\n  }\n  holds.delete(el);\n  el.removeAttribute('inert');\n}\n\n/** The element's siblings, in a shadow root as anywhere else. */\nfunction siblingsOf(el: Element): Element[] {\n  const siblings: Element[] = [];\n  for (let s = el.previousElementSibling; s; s = s.previousElementSibling) {\n    siblings.push(s);\n  }\n  for (let s = el.nextElementSibling; s; s = s.nextElementSibling) {\n    siblings.push(s);\n  }\n  return siblings;\n}\n\n/**\n * The element above `el` in the page: its parent, or the host of the shadow\n * root it sits at the top of. Nothing above the top of a detached tree.\n */\nconst above = (el: Element): Element | undefined =>\n  el.parentElement ?? (el.getRootNode() as Partial<ShadowRoot>).host;\n\n/**\n * Makes the elements beside `ref`'s element inert while `active` is true,\n * and takes it off again when `active` turns false or the caller unmounts.\n * With `wholePage`, it does the same beside each element above it up to\n * `<body>`, so everything on the page but `ref`'s element is inert, the way a\n * modal layer leaves it. The element itself and its own content are never\n * touched.\n *\n * It sets the `inert` attribute through the DOM in an effect, so it works the\n * same on React 18 and 19 and a server render has nothing to show for it. An\n * element that was inert already is left alone, and keeps its `inert` once\n * this lets go. It makes inert what's there when it turns on: an element that\n * mounts beside it afterwards isn't. It follows the DOM, so content a web\n * component renders around a slot this sits in, and text with no element of\n * its own, stays as it is.\n *\n * Focus on an element that turns inert is lost: the browser moves it to\n * `<body>`. So when focus was inside what this made inert, and is still on\n * `<body>` when this lets go, it goes back to the element that had it. Focus\n * this never took isn't handed anywhere, and focus the user or the app has\n * put somewhere else meanwhile stays there.\n *\n * @function useInertSiblings\n * @param ref - Ref to the element that stays reachable.\n * @param active - Whether what's beside it is inert.\n * @param wholePage - Whether that goes for the whole page rather than only\n * the element's siblings.\n * @param except - Ref to an element beside it to leave reachable too, such\n * as the overlay's own backdrop, which has to take the presses that close\n * it rather than let them through to what's under it.\n */\nexport function useInertSiblings(\n  ref: RefObject<Element | null>,\n  active: boolean,\n  wholePage: boolean,\n  except?: RefObject<Element | null>\n): void {\n  useEffect(() => {\n    const el = ref.current;\n    if (!active || !el) return undefined;\n    const doc = el.ownerDocument;\n    const keep = except?.current;\n\n    const held: Element[] = [];\n    for (\n      let node: Element | undefined = el;\n      node && node !== doc.body;\n      node = wholePage ? above(node) : undefined\n    ) {\n      held.push(\n        ...siblingsOf(node).filter(sibling => sibling !== keep && hold(sibling))\n      );\n    }\n\n    // Focus this takes away, to hand back later. It's looked up as `el`'s\n    // tree sees it, where focus inside a nested shadow root reads as its\n    // host, so it compares with what's held. What gets focused again is the\n    // element that really had focus, inside that shadow root.\n    const focused = getActiveElementInTree(el);\n    const taken = held.some(other => other.contains(focused))\n      ? (getDeepestActiveElement(doc) as HTMLElement | null)\n      : null;\n\n    return () => {\n      held.forEach(release);\n      if (doc.activeElement === doc.body) taken?.focus();\n    };\n  }, [ref, active, wholePage, except]);\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/helpers/useOutsidePress.js

@@ -0,0 +1,53 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+'use client';
+import { useRef, useEffect, useCallback } from 'react';
+import { useLatestRef } from './useLatestRef.js';
+import { isEventInside } from './shadowDom.js';
+
+// INTERNAL: deliberately not exported from src/index.ts.
+/**
+ * Calls `onOutsidePress` for a `pointerdown` outside `ref`'s element while
+ * `active`, as a Popover closes on one.
+ *
+ * A press counts as inside in two ways: on the element's own path in the DOM,
+ * and anywhere in a React tree the returned handler is put on, as
+ * `onPointerDownCapture`. React's tree includes content portaled out of it,
+ * which the DOM path doesn't, and React has seen a press there by the time
+ * the document hears it.
+ *
+ * The listener is on the element's own document, an iframe's when the tree
+ * renders into one, and reads the latest `onOutsidePress` as a press
+ * arrives, so it stays put while the callback changes identity.
+ *
+ * @function useOutsidePress
+ * @param ref - Ref to the element a press inside of doesn't count.
+ * @param active - Whether to listen.
+ * @param onOutsidePress - Called with each press outside.
+ * @returns The `onPointerDownCapture` handler that marks a press in its tree
+ * as inside.
+ */
+function useOutsidePress(ref, active, onOutsidePress) {
+    // The last pointerdown React saw inside.
+    const insidePressRef = useRef(null);
+    const onOutsidePressRef = useLatestRef(onOutsidePress);
+    useEffect(() => {
+        const element = ref.current;
+        if (!active || !element)
+            return undefined;
+        const handlePointerDown = (e) => {
+            if (e === insidePressRef.current || isEventInside(e, ref.current)) {
+                return;
+            }
+            onOutsidePressRef.current(e);
+        };
+        const doc = element.ownerDocument;
+        doc.addEventListener('pointerdown', handlePointerDown);
+        return () => doc.removeEventListener('pointerdown', handlePointerDown);
+    }, [ref, active, onOutsidePressRef]);
+    return useCallback((event) => {
+        insidePressRef.current = event.nativeEvent;
+    }, []);
+}
+
+export { useOutsidePress };
+//# sourceMappingURL=useOutsidePress.js.map

package/dist/esm/helpers/useOutsidePress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOutsidePress.js","sources":["../../../src/helpers/useOutsidePress.ts"],"sourcesContent":["// INTERNAL: deliberately not exported from src/index.ts.\nimport { useCallback, useEffect, useRef } from 'react';\nimport type React from 'react';\nimport type { RefObject } from 'react';\nimport { useLatestRef } from './useLatestRef';\nimport { isEventInside } from './shadowDom';\n\n/**\n * Calls `onOutsidePress` for a `pointerdown` outside `ref`'s element while\n * `active`, as a Popover closes on one.\n *\n * A press counts as inside in two ways: on the element's own path in the DOM,\n * and anywhere in a React tree the returned handler is put on, as\n * `onPointerDownCapture`. React's tree includes content portaled out of it,\n * which the DOM path doesn't, and React has seen a press there by the time\n * the document hears it.\n *\n * The listener is on the element's own document, an iframe's when the tree\n * renders into one, and reads the latest `onOutsidePress` as a press\n * arrives, so it stays put while the callback changes identity.\n *\n * @function useOutsidePress\n * @param ref - Ref to the element a press inside of doesn't count.\n * @param active - Whether to listen.\n * @param onOutsidePress - Called with each press outside.\n * @returns The `onPointerDownCapture` handler that marks a press in its tree\n * as inside.\n */\nexport function useOutsidePress(\n  ref: RefObject<Element | null>,\n  active: boolean,\n  onOutsidePress: (event: PointerEvent) => void\n): (event: React.PointerEvent) => void {\n  // The last pointerdown React saw inside.\n  const insidePressRef = useRef<Event | null>(null);\n  const onOutsidePressRef = useLatestRef(onOutsidePress);\n\n  useEffect(() => {\n    const element = ref.current;\n    if (!active || !element) return undefined;\n    const handlePointerDown = (e: PointerEvent) => {\n      if (e === insidePressRef.current || isEventInside(e, ref.current)) {\n        return;\n      }\n      onOutsidePressRef.current(e);\n    };\n    const doc = element.ownerDocument;\n    doc.addEventListener('pointerdown', handlePointerDown);\n    return () => doc.removeEventListener('pointerdown', handlePointerDown);\n  }, [ref, active, onOutsidePressRef]);\n\n  return useCallback((event: React.PointerEvent) => {\n    insidePressRef.current = event.nativeEvent;\n  }, []);\n}\n"],"names":[],"mappings":";;;;;;AAAA;AAOA;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,eAAe,CAC7B,GAA8B,EAC9B,MAAe,EACf,cAA6C,EAAA;;AAG7C,IAAA,MAAM,cAAc,GAAG,MAAM,CAAe,IAAI,CAAC;AACjD,IAAA,MAAM,iBAAiB,GAAG,YAAY,CAAC,cAAc,CAAC;IAEtD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO;AAC3B,QAAA,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO;AAAE,YAAA,OAAO,SAAS;AACzC,QAAA,MAAM,iBAAiB,GAAG,CAAC,CAAe,KAAI;AAC5C,YAAA,IAAI,CAAC,KAAK,cAAc,CAAC,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE;gBACjE;YACF;AACA,YAAA,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9B,QAAA,CAAC;AACD,QAAA,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa;AACjC,QAAA,GAAG,CAAC,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,CAAC;QACtD,OAAO,MAAM,GAAG,CAAC,mBAAmB,CAAC,aAAa,EAAE,iBAAiB,CAAC;IACxE,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEpC,IAAA,OAAO,WAAW,CAAC,CAAC,KAAyB,KAAI;AAC/C,QAAA,cAAc,CAAC,OAAO,GAAG,KAAK,CAAC,WAAW;IAC5C,CAAC,EAAE,EAAE,CAAC;AACR;;"}

package/dist/esm/helpers/useOverlayFocus.js

@@ -0,0 +1,74 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+'use client';
+import { useRef, useEffect } from 'react';
+import { useClientLayoutEffect } from './useClientLayoutEffect.js';
+import { useLatestRef } from './useLatestRef.js';
+import { isModalOverlayOpen } from './overlayStack.js';
+import { focusTabStop } from './useFocusTrap.js';
+import { getActiveElementInTree, getDeepestActiveElement } from './shadowDom.js';
+
+// INTERNAL: deliberately not exported from src/index.ts.
+/**
+ * Moves focus into an overlay as it opens, to the first stop Tab wraps to
+ * inside `ref`'s element or the element itself, and hands it back to
+ * whatever had it as it closes, as `Modal` does. Focus goes back only while
+ * the overlay still holds it, or it's been dropped to `<body>`: closing one
+ * under another overlay mustn't pull focus out of the one on top, and focus
+ * moved out to the page stays there. The opener is found wherever it sits,
+ * inside a shadow root too, in the overlay's own document, an iframe's when
+ * it renders into one. It's read in a layout effect as the overlay opens, so
+ * before the commit's passive effects, such as one that makes the page
+ * inert. Content inside the overlay with a layout effect of its own, or an
+ * `autoFocus`, can still move focus first, and then there's no opener to go
+ * back to: focus is never handed back into the overlay that's closing.
+ *
+ * @function useOverlayFocus
+ * @param ref - Ref to the overlay's element.
+ * @param open - Whether the overlay is open.
+ * @param options - Whether it's modal, what remounts it, and whether a
+ * close hands focus back.
+ */
+function useOverlayFocus(ref, open, { modal, remountKey, restore }) {
+    const openerRef = useRef(null);
+    const restoreRef = useLatestRef(restore);
+    // The element that had focus, wherever it sits: a portaled overlay renders
+    // under `document.body` while its opener can be inside a shadow root.
+    useClientLayoutEffect(() => {
+        if (!open)
+            return;
+        const element = ref.current;
+        /* istanbul ignore if: as below, the ref is set while the overlay is open */
+        if (!element)
+            return;
+        // Focus already inside, where an `autoFocus` in the overlay puts it, has
+        // no opener to go back to.
+        openerRef.current = element.contains(getActiveElementInTree(element))
+            ? null
+            : getDeepestActiveElement(element.ownerDocument);
+    }, [open, ref]);
+    useEffect(() => {
+        if (!open)
+            return undefined;
+        const element = ref.current;
+        /* istanbul ignore if: the overlay renders whenever it's open, so its ref is set before this runs */
+        if (!element)
+            return undefined;
+        if (modal || !isModalOverlayOpen()) {
+            focusTabStop(element);
+        }
+        return () => {
+            // A removed subtree leaves focus on <body>, which still counts as held.
+            const active = getActiveElementInTree(element);
+            const held = active === element.ownerDocument.body || element.contains(active);
+            // Asked now rather than as it opened: it's about this close.
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+            if (held && (restoreRef.current?.() ?? true)) {
+                openerRef.current?.focus();
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `modal` is read as the overlay opens, on purpose
+    }, [open, remountKey, ref, restoreRef]);
+}
+
+export { useOverlayFocus };
+//# sourceMappingURL=useOverlayFocus.js.map

package/dist/esm/helpers/useOverlayFocus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverlayFocus.js","sources":["../../../src/helpers/useOverlayFocus.ts"],"sourcesContent":["// INTERNAL: deliberately not exported from src/index.ts.\nimport { useEffect, useRef } from 'react';\nimport type { RefObject } from 'react';\nimport { useClientLayoutEffect } from './useClientLayoutEffect';\nimport { useLatestRef } from './useLatestRef';\nimport { isModalOverlayOpen } from './overlayStack';\nimport { focusTabStop } from './useFocusTrap';\nimport { getActiveElementInTree, getDeepestActiveElement } from './shadowDom';\n\n/** Options for `useOverlayFocus`. */\nexport interface OverlayFocusOptions {\n  /**\n   * Whether the overlay is modal. One that isn't, opened while a modal\n   * overlay is open under it, leaves focus where it is: that overlay keeps\n   * Tab, so a Tab from this one's controls would only go back to it. It's\n   * read as the overlay opens, so a change while it's open moves nothing.\n   */\n  modal: boolean;\n  /**\n   * A value that remounts the overlay's nodes while it's open when it\n   * changes, such as a new portal target. Focus is handed back from the old\n   * nodes and moved into the new ones.\n   */\n  remountKey?: unknown;\n  /**\n   * Asked as the overlay closes, while it still holds focus: `false` leaves\n   * focus where it is, for a close that shouldn't send it back, such as one\n   * whose overlay stays on the page as something else.\n   */\n  restore?: () => boolean;\n}\n\n/**\n * Moves focus into an overlay as it opens, to the first stop Tab wraps to\n * inside `ref`'s element or the element itself, and hands it back to\n * whatever had it as it closes, as `Modal` does. Focus goes back only while\n * the overlay still holds it, or it's been dropped to `<body>`: closing one\n * under another overlay mustn't pull focus out of the one on top, and focus\n * moved out to the page stays there. The opener is found wherever it sits,\n * inside a shadow root too, in the overlay's own document, an iframe's when\n * it renders into one. It's read in a layout effect as the overlay opens, so\n * before the commit's passive effects, such as one that makes the page\n * inert. Content inside the overlay with a layout effect of its own, or an\n * `autoFocus`, can still move focus first, and then there's no opener to go\n * back to: focus is never handed back into the overlay that's closing.\n *\n * @function useOverlayFocus\n * @param ref - Ref to the overlay's element.\n * @param open - Whether the overlay is open.\n * @param options - Whether it's modal, what remounts it, and whether a\n * close hands focus back.\n */\nexport function useOverlayFocus(\n  ref: RefObject<HTMLElement | null>,\n  open: boolean,\n  { modal, remountKey, restore }: OverlayFocusOptions\n): void {\n  const openerRef = useRef<HTMLElement | null>(null);\n  const restoreRef = useLatestRef(restore);\n\n  // The element that had focus, wherever it sits: a portaled overlay renders\n  // under `document.body` while its opener can be inside a shadow root.\n  useClientLayoutEffect(() => {\n    if (!open) return;\n    const element = ref.current;\n    /* istanbul ignore if: as below, the ref is set while the overlay is open */\n    if (!element) return;\n    // Focus already inside, where an `autoFocus` in the overlay puts it, has\n    // no opener to go back to.\n    openerRef.current = element.contains(getActiveElementInTree(element))\n      ? null\n      : (getDeepestActiveElement(element.ownerDocument) as HTMLElement | null);\n  }, [open, ref]);\n\n  useEffect(() => {\n    if (!open) return undefined;\n    const element = ref.current;\n    /* istanbul ignore if: the overlay renders whenever it's open, so its ref is set before this runs */\n    if (!element) return undefined;\n\n    if (modal || !isModalOverlayOpen()) {\n      focusTabStop(element);\n    }\n\n    return () => {\n      // A removed subtree leaves focus on <body>, which still counts as held.\n      const active = getActiveElementInTree(element);\n      const held =\n        active === element.ownerDocument.body || element.contains(active);\n      // Asked now rather than as it opened: it's about this close.\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n      if (held && (restoreRef.current?.() ?? true)) {\n        openerRef.current?.focus();\n      }\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- `modal` is read as the overlay opens, on purpose\n  }, [open, remountKey, ref, restoreRef]);\n}\n"],"names":[],"mappings":";;;;;;;;;AAAA;AAgCA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,eAAe,CAC7B,GAAkC,EAClC,IAAa,EACb,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAuB,EAAA;AAEnD,IAAA,MAAM,SAAS,GAAG,MAAM,CAAqB,IAAI,CAAC;AAClD,IAAA,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC;;;IAIxC,qBAAqB,CAAC,MAAK;AACzB,QAAA,IAAI,CAAC,IAAI;YAAE;AACX,QAAA,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO;;AAE3B,QAAA,IAAI,CAAC,OAAO;YAAE;;;QAGd,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,OAAO,CAAC;AAClE,cAAE;AACF,cAAG,uBAAuB,CAAC,OAAO,CAAC,aAAa,CAAwB;AAC5E,IAAA,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEf,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,IAAI;AAAE,YAAA,OAAO,SAAS;AAC3B,QAAA,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO;;AAE3B,QAAA,IAAI,CAAC,OAAO;AAAE,YAAA,OAAO,SAAS;AAE9B,QAAA,IAAI,KAAK,IAAI,CAAC,kBAAkB,EAAE,EAAE;YAClC,YAAY,CAAC,OAAO,CAAC;QACvB;AAEA,QAAA,OAAO,MAAK;;AAEV,YAAA,MAAM,MAAM,GAAG,sBAAsB,CAAC,OAAO,CAAC;AAC9C,YAAA,MAAM,IAAI,GACR,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;;;AAGnE,YAAA,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO,IAAI,IAAI,IAAI,CAAC,EAAE;AAC5C,gBAAA,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE;YAC5B;AACF,QAAA,CAAC;;IAEH,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;AACzC;;"}

package/dist/esm/layout/AppFrame.js

@@ -0,0 +1,438 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+'use client';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React, { createContext, forwardRef, useContext, useRef, useCallback, useEffect, useState, useId, useMemo } from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { withSubComponents } from '../helpers/withSubComponents.js';
+import { flattenChildren } from '../helpers/flattenChildren.js';
+import { useLatestRef } from '../helpers/useLatestRef.js';
+import { useOverlayStack, useOverlayEscape } from '../helpers/overlayStack.js';
+import { useScrollLock } from '../helpers/scrollLock.js';
+import { useInertSiblings } from '../helpers/useInertSiblings.js';
+import { trapTab } from '../helpers/useFocusTrap.js';
+import { useOverlayFocus } from '../helpers/useOverlayFocus.js';
+import { useOutsidePress } from '../helpers/useOutsidePress.js';
+import { getActiveElementInTree } from '../helpers/shadowDom.js';
+import { useBulmaBreakpoint } from '../helpers/useBulmaViewport.js';
+import { warnOnce } from '../helpers/devWarnings.js';
+import { NavbarBurger } from '../components/Navbar.js';
+import { Delete } from '../elements/Delete.js';
+
+const FrameContext = createContext(null);
+/** A width prop as CSS: a number is pixels. */
+const cssLength = (value) => typeof value === 'number' ? `${value}px` : value;
+/**
+ * Hands `node` to a part's own ref and to the one forwarded to it. A
+ * forwarded callback that returns a cleanup, as React 19 allows, has it held
+ * in `cleanup` and run on detach in place of a call with `null`, on React 18
+ * as well.
+ */
+function setRefs(node, own, forwarded, cleanup) {
+    own.current = node;
+    if (typeof forwarded === 'function') {
+        if (node === null) {
+            const detach = cleanup.current;
+            cleanup.current = null;
+            if (detach)
+                detach();
+            else
+                forwarded(null);
+            return;
+        }
+        const returned = forwarded(node);
+        cleanup.current =
+            typeof returned === 'function' ? returned : null;
+    }
+    else if (forwarded) {
+        forwarded.current = node;
+    }
+}
+/**
+ * Warns when a part has an `id` the frame couldn't read, because it isn't a
+ * direct child, so the skip link or the burger points at the wrong one.
+ */
+function warnOnUnreadId(part, id, expected) {
+    if (id && id !== expected) {
+        warnOnce(`AppFrame:${part}-id`, `[bestax-bulma] <AppFrame.${part}> has an id <AppFrame> can't read, ` +
+            `so ${part === 'Main' ? 'the skip link' : "the burger's aria-controls"} ` +
+            `misses it. Put AppFrame.${part} directly inside AppFrame.`);
+    }
+}
+/**
+ * The top bar of an AppFrame, which sticks while the page scrolls.
+ *
+ * @function
+ * @param {AppFrameHeaderProps} props - Props for AppFrame.Header.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<header>`.
+ * @returns {JSX.Element} The rendered header.
+ */
+const AppFrameHeader = forwardRef(({ className, children, ...props }, ref) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const headerClass = usePrefixedClassNames('app-frame-header');
+    return (jsx("header", { ref: ref, className: classNames(headerClass, bulmaHelperClasses, className), ...rest, children: children }));
+});
+AppFrameHeader.displayName = 'AppFrame.Header';
+/**
+ * The navigation of an AppFrame: a column beside the page from the breakpoint up, and a drawer below it.
+ *
+ * @function
+ * @param {AppFrameNavProps} props - Props for AppFrame.Nav.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<nav>`.
+ * @returns {JSX.Element} The rendered nav, and the drawer's backdrop.
+ */
+const AppFrameNav = forwardRef(({ className, style, width, overlay = true, closeOnEscape = true, closeOnClickOutside = true, closeOnNavigate = true, onClick, onPointerDownCapture, children, ...props }, ref) => {
+    const frame = useContext(FrameContext);
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const navClass = usePrefixedClassNames('app-frame-nav');
+    const closeClass = usePrefixedClassNames('app-frame-close');
+    const backdropClass = usePrefixedClassNames('app-frame-backdrop');
+    const activeClass = usePrefixedClassNames('is-active');
+    const navRef = useRef(null);
+    const backdropRef = useRef(null);
+    const navCleanupRef = useRef(null);
+    const navRefs = useCallback((node) => setRefs(node, navRef, ref, navCleanupRef), [ref]);
+    const navId = rest.id || frame?.state.navId;
+    if (frame)
+        warnOnUnreadId('Nav', rest.id, frame.state.navId);
+    // The drawer is open only below the breakpoint. Above it the nav is a
+    // column, and none of what follows applies.
+    const isDrawer = !!frame?.state.isDrawer;
+    const open = isDrawer && !!frame?.state.navOpen;
+    // The open drawer is Bulma's active state, on the nav as on a navbar's
+    // menu, and on its backdrop.
+    const shown = { [activeClass]: !!frame?.state.navOpen };
+    const modal = open && overlay;
+    const close = () => frame?.state.setNavOpen(false);
+    // The rest of the frame goes inert: the header, the page, the aside and
+    // the footer, but not the backdrop, which takes the presses outside the
+    // drawer rather than let them through to what's under it. Not the whole
+    // page, since a Modal or a toast renders beside the frame, often into an
+    // element that's there before the drawer opens, and a Modal opened from
+    // the drawer has to stay usable. First, so that as the drawer closes it
+    // lets go before focus goes back to the burger: an inert element can't
+    // take focus.
+    useInertSiblings(navRef, modal, false, backdropRef);
+    const isTopmost = useOverlayStack(open, overlay);
+    useScrollLock(modal);
+    // Tab stays inside while the drawer is the topmost modal overlay, as in
+    // Sidebar, so a Modal opened from the drawer holds Tab until it closes.
+    useEffect(() => {
+        if (!modal)
+            return undefined;
+        return trapTab(() => navRef.current, window, () => isTopmost('modal'));
+    }, [modal, isTopmost]);
+    useOverlayEscape(open && closeOnEscape, isTopmost, close);
+    // Without an overlay there's no backdrop: a press outside the drawer
+    // closes it, as Popover's does, while it's the topmost overlay, so a
+    // press in a Modal opened over it is the Modal's. A press on a control
+    // that names the nav in its `aria-controls`, such as the burger, is left
+    // to that control, which toggles it.
+    const markInsidePress = useOutsidePress(navRef, open && !overlay && closeOnClickOutside, e => {
+        const id = navRef.current?.id;
+        const controlsNav = (node) => !!node
+            .getAttribute?.('aria-controls')
+            ?.split(/\s+/)
+            .includes(id);
+        if (!isTopmost() || e.composedPath().some(controlsNav))
+            return;
+        close();
+    });
+    // Focus moves to the drawer's first tab stop, the close button, as it
+    // opens, and back to whatever had it as it closes, unless it has left
+    // the drawer. After a press outside, the press's own mousedown then takes
+    // it wherever the press goes. When the window widened, the drawer is the
+    // column again, and focus on its links stays; the close button hides
+    // there, so focus on it, or dropped from it to <body>, goes back too.
+    const isDrawerRef = useLatestRef(isDrawer);
+    useOverlayFocus(navRef, open, {
+        modal: overlay,
+        restore: () => {
+            if (isDrawerRef.current)
+                return true;
+            const nav = navRef.current;
+            const active = getActiveElementInTree(nav);
+            return (!nav.contains(active) || !!active?.classList.contains(closeClass));
+        },
+    });
+    const handleClick = (e) => {
+        onClick?.(e);
+        if (!open ||
+            !closeOnNavigate ||
+            e.button !== 0 ||
+            e.metaKey ||
+            e.ctrlKey ||
+            e.shiftKey ||
+            e.altKey) {
+            return;
+        }
+        // Not skipped for a click whose default was prevented: a router's
+        // link prevents it to navigate without a page load. Only a link the nav
+        // holds: one in a Modal portaled from it is the Modal's.
+        const link = e.target.closest('a[href]');
+        if (!link || !navRef.current?.contains(link))
+            return;
+        if (link.hasAttribute('download'))
+            return;
+        const target = link.getAttribute('target');
+        if (target && target !== '_self')
+            return;
+        close();
+    };
+    const navStyle = width === undefined
+        ? style
+        : {
+            ...style,
+            '--bulma-app-frame-nav-width': cssLength(width),
+        };
+    return (jsxs(Fragment, { children: [jsxs("nav", { ref: navRefs, className: classNames(navClass, shown, bulmaHelperClasses, className), style: navStyle, onClick: handleClick, onPointerDownCapture: e => {
+                    onPointerDownCapture?.(e);
+                    markInsidePress(e);
+                }, ...rest, id: navId, "aria-label": rest['aria-label'] ||
+                    (rest['aria-labelledby'] ? undefined : frame?.labels.nav), children: [frame && (jsx(Delete, { className: closeClass, size: "medium", ariaLabel: frame.labels.closeNav, onClick: close })), children] }), frame && overlay && (jsx("div", { ref: backdropRef, className: classNames(backdropClass, shown), "aria-hidden": "true", onClick: closeOnClickOutside
+                    ? () => {
+                        // Not under an overlay opened over the drawer.
+                        if (isTopmost())
+                            close();
+                    }
+                    : undefined }))] }));
+});
+AppFrameNav.displayName = 'AppFrame.Nav';
+/**
+ * The page's main content in an AppFrame, which the skip link moves focus to.
+ *
+ * @function
+ * @param {AppFrameMainProps} props - Props for AppFrame.Main.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<main>`.
+ * @returns {JSX.Element} The rendered main.
+ */
+const AppFrameMain = forwardRef(({ className, children, ...props }, ref) => {
+    const frame = useContext(FrameContext);
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const mainClass = usePrefixedClassNames('app-frame-main');
+    if (frame)
+        warnOnUnreadId('Main', rest.id, frame.mainId);
+    return (jsx("main", { ref: ref, tabIndex: -1, className: classNames(mainClass, bulmaHelperClasses, className), ...rest, id: rest.id || frame?.mainId, children: children }));
+});
+AppFrameMain.displayName = 'AppFrame.Main';
+/**
+ * Content beside the page in an AppFrame, which moves under it below the breakpoint.
+ *
+ * @function
+ * @param {AppFrameAsideProps} props - Props for AppFrame.Aside.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<aside>`.
+ * @returns {JSX.Element} The rendered aside.
+ */
+const AppFrameAside = forwardRef(({ className, style, width, children, ...props }, ref) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const asideClass = usePrefixedClassNames('app-frame-aside');
+    const asideStyle = width === undefined
+        ? style
+        : {
+            ...style,
+            '--bulma-app-frame-aside-width': cssLength(width),
+        };
+    return (jsx("aside", { ref: ref, className: classNames(asideClass, bulmaHelperClasses, className), style: asideStyle, ...rest, children: children }));
+});
+AppFrameAside.displayName = 'AppFrame.Aside';
+/**
+ * The bottom of an AppFrame, under the page.
+ *
+ * @function
+ * @param {AppFrameFooterProps} props - Props for AppFrame.Footer.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<footer>`.
+ * @returns {JSX.Element} The rendered footer.
+ */
+const AppFrameFooter = forwardRef(({ className, children, ...props }, ref) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const footerClass = usePrefixedClassNames('app-frame-footer');
+    return (jsx("footer", { ref: ref, className: classNames(footerClass, bulmaHelperClasses, className), ...rest, children: children }));
+});
+AppFrameFooter.displayName = 'AppFrame.Footer';
+/**
+ * The button that opens the drawer, or collapses the column from the breakpoint up: Navbar.Burger, wired to the frame.
+ *
+ * @function
+ * @param {AppFrameBurgerProps} props - Props for AppFrame.Burger.
+ * @param {React.Ref<HTMLButtonElement>} ref - Forwarded ref to the `<button>`.
+ * @returns {JSX.Element} The rendered burger.
+ */
+const AppFrameBurger = forwardRef(({ className, onClick, ...props }, ref) => {
+    // Outside a frame it's a Navbar.Burger that controls nothing.
+    const frame = useContext(FrameContext);
+    const burgerClass = usePrefixedClassNames('app-frame-burger');
+    const state = frame?.state;
+    // Until the frame knows whether the nav is a drawer, the burger says
+    // nothing it can't stand behind: no `aria-expanded`, and its bars. It can't
+    // act before then anyway, since that's before hydration. Outside a frame
+    // it's a plain Navbar.Burger.
+    const known = !!frame?.modeKnown;
+    const expanded = known && !!state && (state.isDrawer ? state.navOpen : !state.navCollapsed);
+    return (jsx(NavbarBurger, { ref: ref, ...props, className: classNames(burgerClass, className), "aria-label": props['aria-label'] || frame?.labels.burger, active: expanded, "aria-expanded": frame && !known ? null : expanded, "aria-controls": state?.navId, onClick: e => {
+            onClick?.(e);
+            if (e.defaultPrevented || !frame)
+                return;
+            // Safari, and Firefox on a Mac, don't focus a button that's pressed.
+            // Focused, it's the element the drawer hands focus back to.
+            e.currentTarget.focus();
+            frame.state.toggleNav();
+        } }));
+});
+AppFrameBurger.displayName = 'AppFrame.Burger';
+const isMain = (child) => React.isValidElement(child) && child.type === AppFrameMain;
+const isNav = (child) => React.isValidElement(child) && child.type === AppFrameNav;
+/**
+ * The `AppFrame` component lays out an app's pages: a header across the top, a navigation column down the side, the page, and an aside and a footer, with the nav a drawer behind a burger on narrow screens.
+ *
+ * The header and the column stick while the document scrolls, and a skip
+ * link comes first. The layout is CSS, so the server renders it as the
+ * browser does. It holds two states, each yours to control: whether the
+ * drawer is open, and whether the column is collapsed. `AppFrame.Burger`
+ * and `useAppFrame()` toggle whichever applies at the current width.
+ *
+ * @function
+ * @param {AppFrameProps} props - Props for the AppFrame component.
+ * @param {React.Ref<HTMLDivElement>} ref - Forwarded ref to the root `<div>`.
+ * @returns {JSX.Element} The rendered frame.
+ *
+ * @example
+ * <AppFrame>
+ *   <AppFrame.Header>
+ *     <Navbar aria-label="Site">
+ *       <Navbar.Brand>
+ *         <Navbar.Item href="/">Acme</Navbar.Item>
+ *         <AppFrame.Burger />
+ *       </Navbar.Brand>
+ *     </Navbar>
+ *   </AppFrame.Header>
+ *   <AppFrame.Nav>
+ *     <Menu>…</Menu>
+ *   </AppFrame.Nav>
+ *   <AppFrame.Main>…</AppFrame.Main>
+ * </AppFrame>
+ */
+const AppFrameRoot = forwardRef(({ className, textColor, bgColor, breakpoint = 'desktop', navOpen: navOpenProp, defaultNavOpen = false, onNavOpenChange, navCollapsed: navCollapsedProp, defaultNavCollapsed = false, onNavCollapsedChange, skipLink = true, labels, children, ...props }, ref) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...props,
+    });
+    const rootRef = useRef(null);
+    const rootCleanupRef = useRef(null);
+    const rootRefs = useCallback((node) => setRefs(node, rootRef, ref, rootCleanupRef), [ref]);
+    const [openState, setOpenState] = useState(defaultNavOpen);
+    const [collapsedState, setCollapsedState] = useState(defaultNavCollapsed);
+    const navOpen = navOpenProp ?? openState;
+    const navCollapsed = navCollapsedProp ?? collapsedState;
+    const openControlled = navOpenProp !== undefined;
+    const collapsedControlled = navCollapsedProp !== undefined;
+    const onNavOpenChangeRef = useLatestRef(onNavOpenChange);
+    const onNavCollapsedChangeRef = useLatestRef(onNavCollapsedChange);
+    const setNavOpen = useCallback((open) => {
+        onNavOpenChangeRef.current?.(open);
+        if (!openControlled)
+            setOpenState(open);
+    }, [openControlled, onNavOpenChangeRef]);
+    const setNavCollapsed = useCallback((collapsed) => {
+        onNavCollapsedChangeRef.current?.(collapsed);
+        if (!collapsedControlled)
+            setCollapsedState(collapsed);
+    }, [collapsedControlled, onNavCollapsedChangeRef]);
+    // The layout switches in the stylesheet. The script needs the width
+    // only to know which state the burger toggles, and to close the drawer
+    // once the window is at or past the breakpoint.
+    const wide = useBulmaBreakpoint(breakpoint);
+    const isDrawer = wide === false;
+    const isWide = wide === true;
+    useEffect(() => {
+        // eslint-disable-next-line react-hooks/set-state-in-effect -- the width is known only in the browser, and the drawer closes in answer to it
+        if (isWide && navOpen)
+            setNavOpen(false);
+    }, [isWide, navOpen, setNavOpen]);
+    const toggleNav = useCallback(() => {
+        if (isDrawer)
+            setNavOpen(!navOpen);
+        else
+            setNavCollapsed(!navCollapsed);
+    }, [isDrawer, navOpen, navCollapsed, setNavOpen, setNavCollapsed]);
+    // The ids of the parts the skip link and the burger point at, read off
+    // the children so the server renders them too.
+    const baseId = useId();
+    const parts = flattenChildren(children);
+    const mainId = parts.find(isMain)?.props.id || `${baseId}-main`;
+    const navId = parts.find(isNav)?.props.id || `${baseId}-nav`;
+    const { skipLink: skipText, nav, closeNav, burger } = labels ?? {};
+    const value = useMemo(() => ({
+        state: {
+            navOpen,
+            setNavOpen,
+            navCollapsed,
+            setNavCollapsed,
+            isDrawer,
+            toggleNav,
+            navId,
+        },
+        labels: {
+            skipLink: skipText || 'Skip to main content',
+            nav: nav || 'Sections',
+            closeNav: closeNav || 'Close navigation',
+            burger: burger || undefined,
+        },
+        mainId,
+        modeKnown: wide !== null,
+    }), [
+        navOpen,
+        setNavOpen,
+        navCollapsed,
+        setNavCollapsed,
+        isDrawer,
+        toggleNav,
+        navId,
+        skipText,
+        nav,
+        closeNav,
+        burger,
+        mainId,
+        wide,
+    ]);
+    // Its header and footer are the page's banner and contentinfo only
+    // outside `main` and sectioning content, as HTML-AAM maps them.
+    useEffect(() => {
+        const host = rootRef.current?.parentElement?.closest('main, article, aside, nav, section');
+        if (host) {
+            warnOnce('AppFrame:nested', `[bestax-bulma] <AppFrame> sits inside a <${host.localName}>, where ` +
+                "its header and footer are no longer the page's banner and " +
+                'contentinfo landmarks. Put AppFrame at the top of the page.');
+        }
+    }, []);
+    const rootClass = usePrefixedClassNames('app-frame', {
+        [`is-${breakpoint}`]: true,
+        'is-nav-collapsed': navCollapsed,
+    });
+    const skipClass = usePrefixedClassNames('app-frame-skip-link');
+    return (jsxs("div", { ref: rootRefs, className: classNames(rootClass, bulmaHelperClasses, className), ...rest, children: [skipLink && (jsx("a", { className: skipClass, href: `#${mainId}`, children: value.labels.skipLink })), jsx(FrameContext.Provider, { value: value, children: children })] }));
+});
+/**
+ * The frame's state, for a control of your own inside it: whether the
+ * drawer is open and the column collapsed, setters that go through the
+ * frame's callbacks, and `toggleNav()`, which does what the burger does.
+ * Outside an AppFrame it's `null`, as the library's other context hooks
+ * are, so a control that can sit outside one renders a fallback or nothing.
+ *
+ * @function useAppFrame
+ * @returns The frame's state, or `null` outside an AppFrame.
+ */
+function useAppFrame() {
+    return useContext(FrameContext)?.state ?? null;
+}
+const AppFrame = withSubComponents(AppFrameRoot, {
+    Header: AppFrameHeader,
+    Nav: AppFrameNav,
+    Main: AppFrameMain,
+    Aside: AppFrameAside,
+    Footer: AppFrameFooter,
+    Burger: AppFrameBurger,
+}, 'AppFrame');
+
+export { AppFrame, AppFrameAside, AppFrameBurger, AppFrameFooter, AppFrameHeader, AppFrameMain, AppFrameNav, useAppFrame };
+//# sourceMappingURL=AppFrame.js.map