@allxsmith/bestax-bulma 5.27.0 → 5.27.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrollLock.js","sources":["../../../src/helpers/scrollLock.ts"],"sourcesContent":["import { useEffect } from 'react';\n\n// Ref-counted across every caller (e.g. a Dialog rendering its own Modal)\n// so overlapping/nested locks don't fight over which one restores `overflow`.\n// Every overlay that locks body scroll — Modal, Dialog, Sidebar, Loading —\n// goes through here; a component setting `document.body.style.overflow`\n// itself would clear a lock another overlay still needs.\nlet lockCount = 0;\nlet originalOverflow = '';\n\n/**\n * Locks (and ref-counted-ly unlocks) `document.body` scrolling while `active`\n * is true. Safe to call from multiple components at once — the body scroll\n * is only restored once every active caller has released its lock.\n *\n * @function useScrollLock\n * @param active - Whether this caller wants the body scroll locked.\n */\nexport function useScrollLock(active: boolean): void {\n  useEffect(() => {\n    if (!active) return undefined;\n\n    lockCount++;\n    if (lockCount === 1) {\n      originalOverflow = document.body.style.overflow;\n      document.body.style.overflow = 'hidden';\n    }\n\n    return () => {\n      lockCount--;\n      if (lockCount === 0) {\n        document.body.style.overflow = originalOverflow;\n      }\n    };\n  }, [active]);\n}\n"],"names":[],"mappings":";;;AAEA;AACA;AACA;AACA;AACA;AACA,IAAI,SAAS,GAAG,CAAC;AACjB,IAAI,gBAAgB,GAAG,EAAE;AAEzB;;;;;;;AAOG;AACG,SAAU,aAAa,CAAC,MAAe,EAAA;IAC3C,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,MAAM;AAAE,YAAA,OAAO,SAAS;AAE7B,QAAA,SAAS,EAAE;AACX,QAAA,IAAI,SAAS,KAAK,CAAC,EAAE;YACnB,gBAAgB,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ;YAC/C,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ;QACzC;AAEA,QAAA,OAAO,MAAK;AACV,YAAA,SAAS,EAAE;AACX,YAAA,IAAI,SAAS,KAAK,CAAC,EAAE;gBACnB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,gBAAgB;YACjD;AACF,QAAA,CAAC;AACH,IAAA,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AACd;;"}

package/dist/esm/helpers/shadowDom.js

@@ -0,0 +1,71 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+/**
+ * Event and focus checks that still hold when a component renders inside a
+ * shadow root.
+ *
+ * Code outside a shadow root cannot see into it. A listener on `document`
+ * reads an event from inside one with its `target` set to the shadow host,
+ * and `document.activeElement` names the host instead of the element that has
+ * focus. A component asking either question from `document` then takes a
+ * click on its own menu for an outside click, or cannot tell which of its
+ * items is focused. A web component or a sandboxed preview puts a component
+ * in exactly that position.
+ *
+ * Focus comes in two questions, and each has its own function here. "Is focus
+ * inside me, and on which of my elements?" is `getActiveElementInTree`. "Which
+ * element has focus, wherever it is?", the one to record before moving focus
+ * away and restore to later, is `getDeepestActiveElement`.
+ */
+/**
+ * Whether `event` happened inside `node`. The event's composed path still
+ * holds the element that was really clicked, where a `document` listener
+ * reads the shadow host as the event's `target`.
+ *
+ * @param event - An event read by a listener outside `node`, usually on `document`.
+ * @param node - The component's element, or nothing while it is unmounted.
+ * @returns True when `node` is on the event's path.
+ */
+function isEventInside(event, node) {
+    return !!node && event.composedPath().includes(node);
+}
+/**
+ * The focused element as `node`'s own tree sees it: its shadow root's
+ * `activeElement` when `node` is inside one, `document.activeElement` when it
+ * is not. The result is comparable with `node` and its descendants, which
+ * live in that same tree, so use it to ask whether focus is inside `node`.
+ * Focus inside a shadow root nested within `node` reads as that root's host,
+ * which `node` contains.
+ *
+ * A shadow root with nothing focused inside reports `null`, and a detached
+ * node has no document above it. Both fall back to `document.activeElement`,
+ * so focus elsewhere on the page still reads as outside `node`.
+ *
+ * @param node - An element of the component, or nothing while it is unmounted.
+ * @returns The focused element in `node`'s tree, or the document's.
+ */
+function getActiveElementInTree(node) {
+    const root = node?.getRootNode();
+    return root?.activeElement ?? document.activeElement;
+}
+/**
+ * The element that really has focus, followed down from
+ * `document.activeElement` through every open shadow root on the way. Use it
+ * to record where focus was before moving it, so it can be restored to that
+ * element later: the tree a component renders into need not be the tree its
+ * opener sits in. A closed shadow root cannot be entered, so focus inside one
+ * reads as its host.
+ *
+ * @param doc - The document to start from: the component's own, when it may
+ * render into one other than the page's (an iframe's). Defaults to `document`.
+ * @returns The focused element, or `null` when the document has none.
+ */
+function getDeepestActiveElement(doc = document) {
+    let active = doc.activeElement;
+    while (active?.shadowRoot?.activeElement) {
+        active = active.shadowRoot.activeElement;
+    }
+    return active;
+}
+
+export { getActiveElementInTree, getDeepestActiveElement, isEventInside };
+//# sourceMappingURL=shadowDom.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shadowDom.js","sources":["../../../src/helpers/shadowDom.ts"],"sourcesContent":["/**\n * Event and focus checks that still hold when a component renders inside a\n * shadow root.\n *\n * Code outside a shadow root cannot see into it. A listener on `document`\n * reads an event from inside one with its `target` set to the shadow host,\n * and `document.activeElement` names the host instead of the element that has\n * focus. A component asking either question from `document` then takes a\n * click on its own menu for an outside click, or cannot tell which of its\n * items is focused. A web component or a sandboxed preview puts a component\n * in exactly that position.\n *\n * Focus comes in two questions, and each has its own function here. \"Is focus\n * inside me, and on which of my elements?\" is `getActiveElementInTree`. \"Which\n * element has focus, wherever it is?\", the one to record before moving focus\n * away and restore to later, is `getDeepestActiveElement`.\n */\n\n/**\n * Whether `event` happened inside `node`. The event's composed path still\n * holds the element that was really clicked, where a `document` listener\n * reads the shadow host as the event's `target`.\n *\n * @param event - An event read by a listener outside `node`, usually on `document`.\n * @param node - The component's element, or nothing while it is unmounted.\n * @returns True when `node` is on the event's path.\n */\nexport function isEventInside(\n  event: Event,\n  node: Node | null | undefined\n): boolean {\n  return !!node && event.composedPath().includes(node);\n}\n\n/**\n * The focused element as `node`'s own tree sees it: its shadow root's\n * `activeElement` when `node` is inside one, `document.activeElement` when it\n * is not. The result is comparable with `node` and its descendants, which\n * live in that same tree, so use it to ask whether focus is inside `node`.\n * Focus inside a shadow root nested within `node` reads as that root's host,\n * which `node` contains.\n *\n * A shadow root with nothing focused inside reports `null`, and a detached\n * node has no document above it. Both fall back to `document.activeElement`,\n * so focus elsewhere on the page still reads as outside `node`.\n *\n * @param node - An element of the component, or nothing while it is unmounted.\n * @returns The focused element in `node`'s tree, or the document's.\n */\nexport function getActiveElementInTree(\n  node: Node | null | undefined\n): Element | null {\n  const root = node?.getRootNode() as Partial<DocumentOrShadowRoot> | undefined;\n  return root?.activeElement ?? document.activeElement;\n}\n\n/**\n * The element that really has focus, followed down from\n * `document.activeElement` through every open shadow root on the way. Use it\n * to record where focus was before moving it, so it can be restored to that\n * element later: the tree a component renders into need not be the tree its\n * opener sits in. A closed shadow root cannot be entered, so focus inside one\n * reads as its host.\n *\n * @param doc - The document to start from: the component's own, when it may\n * render into one other than the page's (an iframe's). Defaults to `document`.\n * @returns The focused element, or `null` when the document has none.\n */\nexport function getDeepestActiveElement(\n  doc: Document = document\n): Element | null {\n  let active = doc.activeElement;\n  while (active?.shadowRoot?.activeElement) {\n    active = active.shadowRoot.activeElement;\n  }\n  return active;\n}\n"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;AAgBG;AAEH;;;;;;;;AAQG;AACG,SAAU,aAAa,CAC3B,KAAY,EACZ,IAA6B,EAAA;AAE7B,IAAA,OAAO,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;AACtD;AAEA;;;;;;;;;;;;;;AAcG;AACG,SAAU,sBAAsB,CACpC,IAA6B,EAAA;AAE7B,IAAA,MAAM,IAAI,GAAG,IAAI,EAAE,WAAW,EAA+C;AAC7E,IAAA,OAAO,IAAI,EAAE,aAAa,IAAI,QAAQ,CAAC,aAAa;AACtD;AAEA;;;;;;;;;;;AAWG;AACG,SAAU,uBAAuB,CACrC,GAAA,GAAgB,QAAQ,EAAA;AAExB,IAAA,IAAI,MAAM,GAAG,GAAG,CAAC,aAAa;AAC9B,IAAA,OAAO,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE;AACxC,QAAA,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,aAAa;IAC1C;AACA,IAAA,OAAO,MAAM;AACf;;"}

package/dist/esm/helpers/statusRegion.js

@@ -0,0 +1,282 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useState, useEffect } from 'react';
+
+/**
+ * How long after an item appears its announcement is written, in ms. The wait
+ * lets a screen reader register a region the container has only just mounted,
+ * and items shown in quick succession are written, and read out, together.
+ */
+const announceDelay = 100;
+/**
+ * How long an announcement stays in the region once written, in ms. That's
+ * long enough for a screen reader to pick it up. Clearing it after keeps a
+ * second copy of the item's text from sitting in the page, where someone
+ * reading through the page, or a test looking the text up, would find it
+ * again.
+ */
+const announcementLifetime = 1000;
+const noAnnouncements = [];
+const nothingWritten = [];
+const noAnnouncementsYet = {
+    key: 0,
+    waiting: noAnnouncements,
+    written: nothingWritten,
+};
+// Hides the region with inline styles rather than a class, so it needs no
+// stylesheet, including the helper classes a modular Bulma build can leave
+// out. Clipping it, rather than using `display` or `visibility`, keeps it in
+// the accessibility tree. The declarations match the `extras-sr-only` mixin,
+// plus `clip-path`, which replaces the deprecated `clip`. The negative margin
+// pulls the 1px box back inside the page, so it doesn't add scrollable
+// overflow. Exported for other live regions that must work without a
+// stylesheet, such as a range calendar's.
+const visuallyHidden = {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: 0,
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    clipPath: 'inset(50%)',
+    whiteSpace: 'nowrap',
+    border: 0,
+};
+/**
+ * Works out what a status region says. Each item is announced once. Its
+ * announcement is written `announceDelay` after it appears, or after the last
+ * item to join it when several appear in quick succession, alongside whatever
+ * the region still says. Once written, it stays for `announcementLifetime`,
+ * whatever is written after it and whether or not its item goes in the
+ * meantime. An item that goes before its announcement is written isn't
+ * announced.
+ *
+ * Nothing is written in the commit that mounts the region or the item. A
+ * screen reader reliably announces a polite live region whose content changes
+ * after the region is already in the page, and not always one that arrives
+ * with its content. By the time `describe` runs, an item's rendered text can
+ * be read.
+ *
+ * @function useAnnouncements
+ * @param items - The items to announce, in the order they were shown.
+ * @param describe - The text to announce for an item, or nothing to skip it.
+ *   It runs once the item is on screen, and it must keep its identity between
+ *   renders (a module-level function or a `useCallback`), or every render
+ *   re-checks the items.
+ * @returns The announcements to render, in the order they were written.
+ */
+function useAnnouncements(items, describe) {
+    // The ids of the items on screen as of the last change, every one of which
+    // has been looked at for an announcement already.
+    const onScreenIdsRef = useRef(new Set());
+    // Clears that haven't run yet. They outlive the batch that started them, so
+    // they're only stopped when the region unmounts.
+    const clearTimersRef = useRef(new Set());
+    const [announcements, setAnnouncements] = useState(noAnnouncementsYet);
+    // Runs after the commit that puts an item on screen, which is the first
+    // point its rendered text can be read.
+    useEffect(() => {
+        const announced = onScreenIdsRef.current;
+        const appeared = items.filter(item => !announced.has(item.id));
+        // Items that have gone drop out here too. Ids are never reused, so
+        // forgetting them can't bring an old item back.
+        onScreenIdsRef.current = new Set(items.map(item => item.id));
+        const next = [];
+        for (const item of appeared) {
+            const text = describe(item);
+            if (text)
+                next.push({ id: item.id, text });
+        }
+        if (next.length > 0) {
+            // eslint-disable-next-line react-hooks/set-state-in-effect -- an item's rendered text can only be read once it's on screen
+            setAnnouncements(current => ({
+                ...current,
+                key: current.key + 1,
+                // Announcements still waiting go out with the new ones. What's
+                // already written stays put.
+                waiting: [...current.waiting, ...next],
+            }));
+        }
+    }, [items, describe]);
+    // The write only touches the batch it was started for: a newer batch can
+    // be set before the render that cancels this timer. Its clear is started
+    // by the write itself, so it's timed from the write without waiting on a
+    // render, and a newer batch arriving doesn't cut short what's written.
+    const { key } = announcements;
+    useEffect(() => {
+        if (key === noAnnouncementsYet.key)
+            return undefined;
+        const clearTimers = clearTimersRef.current;
+        const write = setTimeout(() => {
+            // Whether an item is on screen is decided here, once. An item that
+            // went before its announcement was due isn't announced, and one that
+            // goes after keeps its announcement for the rest of its lifetime, when
+            // the region holds the only copy of its text rather than a second one.
+            const onScreen = onScreenIdsRef.current;
+            setAnnouncements(current => current.key === key
+                ? {
+                    ...current,
+                    waiting: noAnnouncements,
+                    written: [
+                        ...current.written,
+                        ...current.waiting
+                            .filter(announcement => onScreen.has(announcement.id))
+                            .map(announcement => ({ ...announcement, batch: key })),
+                    ],
+                }
+                : current);
+            // eslint-disable-next-line @eslint-react/web-api-no-leaked-timeout -- it has to outlive this effect when a newer batch arrives, so the unmount effect below clears it
+            const clear = setTimeout(() => {
+                clearTimers.delete(clear);
+                setAnnouncements(current => {
+                    const written = current.written.filter(announcement => announcement.batch !== key);
+                    return written.length === current.written.length
+                        ? current
+                        : { ...current, written };
+                });
+            }, announcementLifetime);
+            clearTimers.add(clear);
+        }, announceDelay);
+        return () => clearTimeout(write);
+    }, [key]);
+    useEffect(() => {
+        const clearTimers = clearTimersRef.current;
+        return () => {
+            clearTimers.forEach(clearTimeout);
+            clearTimers.clear();
+        };
+    }, []);
+    return announcements.written;
+}
+/**
+ * Reads an element out roughly the way a screen reader would: its text, with
+ * an element's `aria-label`, or an image's `alt`, standing in for what's
+ * inside it, a break between block-level elements, and parts that are
+ * `aria-hidden`, `hidden` or inline-styled `display: none` left out. It isn't
+ * the full accessible name computation, so `aria-labelledby`, CSS-generated
+ * content, content hidden by a stylesheet and other ways of naming or hiding
+ * content aren't followed.
+ *
+ * @function spokenText
+ * @param element - The element to read.
+ * @returns Its text, with runs of whitespace collapsed and the ends trimmed.
+ */
+function spokenText(element) {
+    return readAloud(element).replace(/\s+/g, ' ').trim();
+}
+// Elements a browser displays as blocks by default, and `br`. A screen reader
+// pauses between them, so their text shouldn't run into the text beside them.
+// They're known by tag rather than by computed `display`, which would depend
+// on a stylesheet and on layout.
+const blockLevelTags = new Set([
+    'ADDRESS',
+    'ARTICLE',
+    'ASIDE',
+    'BLOCKQUOTE',
+    'BR',
+    'CAPTION',
+    'DD',
+    'DETAILS',
+    'DIALOG',
+    'DIV',
+    'DL',
+    'DT',
+    'FIELDSET',
+    'FIGCAPTION',
+    'FIGURE',
+    'FOOTER',
+    'FORM',
+    'H1',
+    'H2',
+    'H3',
+    'H4',
+    'H5',
+    'H6',
+    'HEADER',
+    'HGROUP',
+    'HR',
+    'LEGEND',
+    'LI',
+    'MAIN',
+    'MENU',
+    'NAV',
+    'OL',
+    'P',
+    'PRE',
+    'SEARCH',
+    'SECTION',
+    'SUMMARY',
+    'TABLE',
+    'TBODY',
+    'TD',
+    'TFOOT',
+    'TH',
+    'THEAD',
+    'TR',
+    'UL',
+]);
+/**
+ * Whether an element is left out of what a screen reader reads.
+ *
+ * @function isHidden
+ * @param element - The element to check.
+ * @returns True for `aria-hidden="true"`, the `hidden` attribute, and an
+ *   inline `display: none`, on an HTML, SVG or any other element with an
+ *   inline style.
+ */
+const isHidden = (element) => element.getAttribute('aria-hidden') === 'true' ||
+    element.hasAttribute('hidden') ||
+    element.style?.display === 'none';
+/**
+ * The text `spokenText` reads for an element, before its whitespace is
+ * tidied.
+ *
+ * @function readAloud
+ * @param element - The element to read.
+ * @returns Its text.
+ */
+function readAloud(element) {
+    if (isHidden(element))
+        return '';
+    const name = element.getAttribute('aria-label') ||
+        (element.tagName === 'IMG' ? element.getAttribute('alt') : null);
+    const text = name ||
+        Array.from(element.childNodes, child => {
+            if (child instanceof Element)
+                return readAloud(child);
+            return child.nodeType === Node.TEXT_NODE ? child.textContent : '';
+        }).join('');
+    // A name stands in for the element's content, and a block's content stands
+    // apart from what's around it, so both are padded to keep them from running
+    // into the neighboring text. An inline run, like `<span>Up</span>` then
+    // `<span>loaded</span>`, still reads as one word.
+    return name || blockLevelTags.has(element.tagName) ? ` ${text} ` : text;
+}
+/**
+ * A visually hidden, polite `status` live region that a programmatic
+ * container announces its items through. The container renders it from the
+ * moment it mounts, whether or not it has anything to show, so the region is
+ * already in the page when an announcement is written into it.
+ *
+ * The announcements are this component's own state, so writing and clearing
+ * them re-renders the region and leaves the container's items alone. Each one
+ * is its own keyed node, so a re-render that leaves the announcements alone
+ * leaves the region's content alone too, and nothing is read out twice.
+ *
+ * @function StatusRegion
+ * @param props - The items to announce, and the text to announce for each.
+ * @returns The region.
+ */
+function StatusRegion({ items, describe, }) {
+    const announcements = useAnnouncements(items, describe);
+    // `role="status"` makes a region atomic unless it says otherwise, which
+    // reads the whole region on every change. Each announcement is its own
+    // node, and only additions are relevant by default, so with atomic off a
+    // screen reader reads just what was written, and removing one announcement
+    // doesn't read out the ones still there.
+    return (jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "false", style: visuallyHidden, children: announcements.map(announcement => (jsx("div", { children: announcement.text }, announcement.id))) }));
+}
+
+export { StatusRegion, announceDelay, announcementLifetime, spokenText, visuallyHidden };
+//# sourceMappingURL=statusRegion.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statusRegion.js","sources":["../../../src/helpers/statusRegion.tsx"],"sourcesContent":["import React, { useEffect, useRef, useState } from 'react';\n\n/**\n * What a status region says for one of a container's items.\n */\ninterface Announcement {\n  /** The id of the item it announces. */\n  id: string;\n  /** The text a screen reader reads out. */\n  text: string;\n}\n\n/**\n * An announcement in the region.\n */\ninterface WrittenAnnouncement extends Announcement {\n  /** The batch it was written with, which is what its clear removes. */\n  batch: number;\n}\n\n/**\n * How long after an item appears its announcement is written, in ms. The wait\n * lets a screen reader register a region the container has only just mounted,\n * and items shown in quick succession are written, and read out, together.\n */\nexport const announceDelay = 100;\n\n/**\n * How long an announcement stays in the region once written, in ms. That's\n * long enough for a screen reader to pick it up. Clearing it after keeps a\n * second copy of the item's text from sitting in the page, where someone\n * reading through the page, or a test looking the text up, would find it\n * again.\n */\nexport const announcementLifetime = 1000;\n\n/**\n * What the region says, and what it's about to say.\n */\ninterface Announcements {\n  /**\n   * Changes whenever announcements join the wait, which restarts it. It also\n   * names the batch they're written with.\n   */\n  key: number;\n  /** Waiting to be written, in the order their items were shown. */\n  waiting: Announcement[];\n  /** In the region, in the order they were written. */\n  written: WrittenAnnouncement[];\n}\n\nconst noAnnouncements: Announcement[] = [];\nconst nothingWritten: WrittenAnnouncement[] = [];\nconst noAnnouncementsYet: Announcements = {\n  key: 0,\n  waiting: noAnnouncements,\n  written: nothingWritten,\n};\n\n// Hides the region with inline styles rather than a class, so it needs no\n// stylesheet, including the helper classes a modular Bulma build can leave\n// out. Clipping it, rather than using `display` or `visibility`, keeps it in\n// the accessibility tree. The declarations match the `extras-sr-only` mixin,\n// plus `clip-path`, which replaces the deprecated `clip`. The negative margin\n// pulls the 1px box back inside the page, so it doesn't add scrollable\n// overflow. Exported for other live regions that must work without a\n// stylesheet, such as a range calendar's.\nexport const visuallyHidden: React.CSSProperties = {\n  position: 'absolute',\n  width: '1px',\n  height: '1px',\n  padding: 0,\n  margin: '-1px',\n  overflow: 'hidden',\n  clip: 'rect(0, 0, 0, 0)',\n  clipPath: 'inset(50%)',\n  whiteSpace: 'nowrap',\n  border: 0,\n};\n\n/**\n * Works out what a status region says. Each item is announced once. Its\n * announcement is written `announceDelay` after it appears, or after the last\n * item to join it when several appear in quick succession, alongside whatever\n * the region still says. Once written, it stays for `announcementLifetime`,\n * whatever is written after it and whether or not its item goes in the\n * meantime. An item that goes before its announcement is written isn't\n * announced.\n *\n * Nothing is written in the commit that mounts the region or the item. A\n * screen reader reliably announces a polite live region whose content changes\n * after the region is already in the page, and not always one that arrives\n * with its content. By the time `describe` runs, an item's rendered text can\n * be read.\n *\n * @function useAnnouncements\n * @param items - The items to announce, in the order they were shown.\n * @param describe - The text to announce for an item, or nothing to skip it.\n *   It runs once the item is on screen, and it must keep its identity between\n *   renders (a module-level function or a `useCallback`), or every render\n *   re-checks the items.\n * @returns The announcements to render, in the order they were written.\n */\nfunction useAnnouncements<Item extends { id: string }>(\n  items: readonly Item[],\n  describe: (item: Item) => string | null\n): WrittenAnnouncement[] {\n  // The ids of the items on screen as of the last change, every one of which\n  // has been looked at for an announcement already.\n  const onScreenIdsRef = useRef(new Set<string>());\n  // Clears that haven't run yet. They outlive the batch that started them, so\n  // they're only stopped when the region unmounts.\n  const clearTimersRef = useRef(new Set<ReturnType<typeof setTimeout>>());\n  const [announcements, setAnnouncements] = useState(noAnnouncementsYet);\n\n  // Runs after the commit that puts an item on screen, which is the first\n  // point its rendered text can be read.\n  useEffect(() => {\n    const announced = onScreenIdsRef.current;\n    const appeared = items.filter(item => !announced.has(item.id));\n    // Items that have gone drop out here too. Ids are never reused, so\n    // forgetting them can't bring an old item back.\n    onScreenIdsRef.current = new Set(items.map(item => item.id));\n\n    const next: Announcement[] = [];\n    for (const item of appeared) {\n      const text = describe(item);\n      if (text) next.push({ id: item.id, text });\n    }\n    if (next.length > 0) {\n      // eslint-disable-next-line react-hooks/set-state-in-effect -- an item's rendered text can only be read once it's on screen\n      setAnnouncements(current => ({\n        ...current,\n        key: current.key + 1,\n        // Announcements still waiting go out with the new ones. What's\n        // already written stays put.\n        waiting: [...current.waiting, ...next],\n      }));\n    }\n  }, [items, describe]);\n\n  // The write only touches the batch it was started for: a newer batch can\n  // be set before the render that cancels this timer. Its clear is started\n  // by the write itself, so it's timed from the write without waiting on a\n  // render, and a newer batch arriving doesn't cut short what's written.\n  const { key } = announcements;\n  useEffect(() => {\n    if (key === noAnnouncementsYet.key) return undefined;\n    const clearTimers = clearTimersRef.current;\n    const write = setTimeout(() => {\n      // Whether an item is on screen is decided here, once. An item that\n      // went before its announcement was due isn't announced, and one that\n      // goes after keeps its announcement for the rest of its lifetime, when\n      // the region holds the only copy of its text rather than a second one.\n      const onScreen = onScreenIdsRef.current;\n      setAnnouncements(current =>\n        current.key === key\n          ? {\n              ...current,\n              waiting: noAnnouncements,\n              written: [\n                ...current.written,\n                ...current.waiting\n                  .filter(announcement => onScreen.has(announcement.id))\n                  .map(announcement => ({ ...announcement, batch: key })),\n              ],\n            }\n          : current\n      );\n      // eslint-disable-next-line @eslint-react/web-api-no-leaked-timeout -- it has to outlive this effect when a newer batch arrives, so the unmount effect below clears it\n      const clear = setTimeout(() => {\n        clearTimers.delete(clear);\n        setAnnouncements(current => {\n          const written = current.written.filter(\n            announcement => announcement.batch !== key\n          );\n          return written.length === current.written.length\n            ? current\n            : { ...current, written };\n        });\n      }, announcementLifetime);\n      clearTimers.add(clear);\n    }, announceDelay);\n    return () => clearTimeout(write);\n  }, [key]);\n\n  useEffect(() => {\n    const clearTimers = clearTimersRef.current;\n    return () => {\n      clearTimers.forEach(clearTimeout);\n      clearTimers.clear();\n    };\n  }, []);\n\n  return announcements.written;\n}\n\n/**\n * Reads an element out roughly the way a screen reader would: its text, with\n * an element's `aria-label`, or an image's `alt`, standing in for what's\n * inside it, a break between block-level elements, and parts that are\n * `aria-hidden`, `hidden` or inline-styled `display: none` left out. It isn't\n * the full accessible name computation, so `aria-labelledby`, CSS-generated\n * content, content hidden by a stylesheet and other ways of naming or hiding\n * content aren't followed.\n *\n * @function spokenText\n * @param element - The element to read.\n * @returns Its text, with runs of whitespace collapsed and the ends trimmed.\n */\nexport function spokenText(element: Element): string {\n  return readAloud(element).replace(/\\s+/g, ' ').trim();\n}\n\n// Elements a browser displays as blocks by default, and `br`. A screen reader\n// pauses between them, so their text shouldn't run into the text beside them.\n// They're known by tag rather than by computed `display`, which would depend\n// on a stylesheet and on layout.\nconst blockLevelTags = new Set([\n  'ADDRESS',\n  'ARTICLE',\n  'ASIDE',\n  'BLOCKQUOTE',\n  'BR',\n  'CAPTION',\n  'DD',\n  'DETAILS',\n  'DIALOG',\n  'DIV',\n  'DL',\n  'DT',\n  'FIELDSET',\n  'FIGCAPTION',\n  'FIGURE',\n  'FOOTER',\n  'FORM',\n  'H1',\n  'H2',\n  'H3',\n  'H4',\n  'H5',\n  'H6',\n  'HEADER',\n  'HGROUP',\n  'HR',\n  'LEGEND',\n  'LI',\n  'MAIN',\n  'MENU',\n  'NAV',\n  'OL',\n  'P',\n  'PRE',\n  'SEARCH',\n  'SECTION',\n  'SUMMARY',\n  'TABLE',\n  'TBODY',\n  'TD',\n  'TFOOT',\n  'TH',\n  'THEAD',\n  'TR',\n  'UL',\n]);\n\n/**\n * Whether an element is left out of what a screen reader reads.\n *\n * @function isHidden\n * @param element - The element to check.\n * @returns True for `aria-hidden=\"true\"`, the `hidden` attribute, and an\n *   inline `display: none`, on an HTML, SVG or any other element with an\n *   inline style.\n */\nconst isHidden = (element: Element): boolean =>\n  element.getAttribute('aria-hidden') === 'true' ||\n  element.hasAttribute('hidden') ||\n  (element as Partial<ElementCSSInlineStyle>).style?.display === 'none';\n\n/**\n * The text `spokenText` reads for an element, before its whitespace is\n * tidied.\n *\n * @function readAloud\n * @param element - The element to read.\n * @returns Its text.\n */\nfunction readAloud(element: Element): string {\n  if (isHidden(element)) return '';\n  const name =\n    element.getAttribute('aria-label') ||\n    (element.tagName === 'IMG' ? element.getAttribute('alt') : null);\n  const text =\n    name ||\n    Array.from(element.childNodes, child => {\n      if (child instanceof Element) return readAloud(child);\n      return child.nodeType === Node.TEXT_NODE ? child.textContent : '';\n    }).join('');\n  // A name stands in for the element's content, and a block's content stands\n  // apart from what's around it, so both are padded to keep them from running\n  // into the neighboring text. An inline run, like `<span>Up</span>` then\n  // `<span>loaded</span>`, still reads as one word.\n  return name || blockLevelTags.has(element.tagName) ? ` ${text} ` : text;\n}\n\n/**\n * Props for StatusRegion.\n */\nexport interface StatusRegionProps<Item extends { id: string }> {\n  /** The items to announce politely, in the order they were shown. */\n  items: readonly Item[];\n  /**\n   * The text to announce for an item, or nothing to skip it, as\n   * `useAnnouncements` takes it.\n   */\n  describe: (item: Item) => string | null;\n}\n\n/**\n * A visually hidden, polite `status` live region that a programmatic\n * container announces its items through. The container renders it from the\n * moment it mounts, whether or not it has anything to show, so the region is\n * already in the page when an announcement is written into it.\n *\n * The announcements are this component's own state, so writing and clearing\n * them re-renders the region and leaves the container's items alone. Each one\n * is its own keyed node, so a re-render that leaves the announcements alone\n * leaves the region's content alone too, and nothing is read out twice.\n *\n * @function StatusRegion\n * @param props - The items to announce, and the text to announce for each.\n * @returns The region.\n */\nexport function StatusRegion<Item extends { id: string }>({\n  items,\n  describe,\n}: StatusRegionProps<Item>): React.ReactElement {\n  const announcements = useAnnouncements(items, describe);\n\n  // `role=\"status\"` makes a region atomic unless it says otherwise, which\n  // reads the whole region on every change. Each announcement is its own\n  // node, and only additions are relevant by default, so with atomic off a\n  // screen reader reads just what was written, and removing one announcement\n  // doesn't read out the ones still there.\n  return (\n    <div\n      role=\"status\"\n      aria-live=\"polite\"\n      aria-atomic=\"false\"\n      style={visuallyHidden}\n    >\n      {announcements.map(announcement => (\n        <div key={announcement.id}>{announcement.text}</div>\n      ))}\n    </div>\n  );\n}\n"],"names":["_jsx"],"mappings":"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"}

package/dist/esm/helpers/useAnchoredPosition.js

@@ -0,0 +1,86 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { useState } from 'react';
+import { useClientLayoutEffect } from './useClientLayoutEffect.js';
+
+// INTERNAL: deliberately not exported from src/index.ts.
+/**
+ * A `styledGap` for a panel whose stylesheet puts the gap in a margin on the
+ * side facing the anchor, negative on a portaled panel above it, so the
+ * larger magnitude is the gap. In pixels.
+ */
+function marginGap(panel) {
+    const { marginTop, marginBottom } = getComputedStyle(panel);
+    return Math.max(Math.abs(parseFloat(marginTop)) || 0, Math.abs(parseFloat(marginBottom)) || 0);
+}
+/**
+ * The corner that keeps a panel of this size in the viewport, preferring
+ * below the anchor and lined up with its left edge.
+ */
+function resolveAuto(view, rect, panelWidth, panelHeight, gap) {
+    const fitsBelow = rect.bottom + panelHeight + gap <= view.innerHeight;
+    const fitsRight = rect.left + panelWidth <= view.innerWidth;
+    if (fitsBelow)
+        return fitsRight ? 'bottom-left' : 'bottom-right';
+    return fitsRight ? 'top-left' : 'top-right';
+}
+const samePosition = (a, b) => a.position === b.position && a.top === b.top && a.left === b.left;
+/**
+ * Places a floating panel against its anchor: resolves `auto` to a corner
+ * and, for a panel fixed to the viewport, works out its coordinates. It
+ * measures again on resize and on any scroll of the anchor's window (an
+ * iframe's, when the anchor renders into one), so a fixed panel follows its
+ * anchor. A measurement that changes nothing doesn't render again.
+ *
+ * Measuring happens in a layout effect, so the panel is placed before it
+ * paints. It needs both elements on the page while `active` is on, and
+ * keeps the last placement when either is missing.
+ *
+ * @function useAnchoredPosition
+ * @param anchorRef - The element the panel opens from.
+ * @param panelRef - The floating panel.
+ * @param options - Whether to measure, the corner asked for, and how the panel is placed.
+ * @returns The corner the panel opens from, with coordinates when it is fixed.
+ */
+function useAnchoredPosition(anchorRef, panelRef, { active, position, fixed, offset = 4, styledGap }) {
+    const [resolved, setResolved] = useState({
+        position: position === 'auto' ? 'bottom-left' : position,
+    });
+    useClientLayoutEffect(() => {
+        if (!active)
+            return undefined;
+        const view = (anchorRef.current ?? panelRef.current)?.ownerDocument.defaultView ??
+            window;
+        const update = () => {
+            const anchor = anchorRef.current;
+            const panel = panelRef.current;
+            if (!anchor || !panel)
+                return;
+            const rect = anchor.getBoundingClientRect();
+            const { width, height } = panel.getBoundingClientRect();
+            const corner = position === 'auto'
+                ? resolveAuto(view, rect, width, height, offset + (styledGap?.(panel) ?? 0))
+                : position;
+            const next = fixed
+                ? {
+                    position: corner,
+                    top: corner.startsWith('bottom')
+                        ? rect.bottom + offset
+                        : rect.top - height - offset,
+                    left: corner.endsWith('left') ? rect.left : rect.right - width,
+                }
+                : { position: corner };
+            setResolved(prev => (samePosition(prev, next) ? prev : next));
+        };
+        update();
+        view.addEventListener('resize', update, { passive: true });
+        view.addEventListener('scroll', update, { passive: true, capture: true });
+        return () => {
+            view.removeEventListener('resize', update);
+            view.removeEventListener('scroll', update, { capture: true });
+        };
+    }, [active, anchorRef, panelRef, position, fixed, offset, styledGap]);
+    return resolved;
+}
+
+export { marginGap, useAnchoredPosition };
+//# sourceMappingURL=useAnchoredPosition.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAnchoredPosition.js","sources":["../../../src/helpers/useAnchoredPosition.ts"],"sourcesContent":["// INTERNAL: deliberately not exported from src/index.ts.\nimport { useState } from 'react';\nimport type { RefObject } from 'react';\nimport type { PickerPosition } from '../form/_pickerInternals/pickerTypes';\nimport { useClientLayoutEffect } from './useClientLayoutEffect';\n\n/** A corner of the anchor the panel opens from, once `auto` is resolved. */\nexport type AnchoredCorner = Exclude<PickerPosition, 'auto'>;\n\n/**\n * Where the panel goes: the corner it opens from and, when it is fixed to\n * the viewport, its coordinates there.\n */\nexport interface AnchoredPosition {\n  position: AnchoredCorner;\n  top?: number;\n  left?: number;\n}\n\n/**\n * Options for `useAnchoredPosition`.\n */\nexport interface UseAnchoredPositionOptions {\n  /** Whether the panel is on the page. Nothing is measured while it is not. */\n  active: boolean;\n  /** The corner asked for, or `auto` to pick one that keeps the panel in the viewport. */\n  position: PickerPosition;\n  /**\n   * Whether the panel is fixed to the viewport (it was portaled away from the\n   * anchor), which needs coordinates. Otherwise the panel's CSS places it\n   * against the anchor from the corner alone.\n   */\n  fixed: boolean;\n  /**\n   * The gap between the anchor and the panel, in pixels, that the hook puts\n   * there itself: added to the fixed coordinates and to the room `auto` asks\n   * for below the anchor. Popover and the pickers' popover pass `0` and take\n   * their gap from a margin in their stylesheet, read through `styledGap`, so\n   * a theme's offset moves the panel and `auto` alike. A new panel should do\n   * the same rather than rely on this default, which no stylesheet sees.\n   * @defaultValue 4\n   */\n  offset?: number;\n  /**\n   * Reads the gap the panel's own stylesheet puts between it and the anchor,\n   * in pixels, each time the panel is measured. `auto` leaves room for it as\n   * well; the coordinates don't include it, because the stylesheet applies it.\n   */\n  styledGap?: (panel: HTMLElement) => number;\n}\n\n/**\n * A `styledGap` for a panel whose stylesheet puts the gap in a margin on the\n * side facing the anchor, negative on a portaled panel above it, so the\n * larger magnitude is the gap. In pixels.\n */\nexport function marginGap(panel: HTMLElement): number {\n  const { marginTop, marginBottom } = getComputedStyle(panel);\n  return Math.max(\n    Math.abs(parseFloat(marginTop)) || 0,\n    Math.abs(parseFloat(marginBottom)) || 0\n  );\n}\n\n/**\n * The corner that keeps a panel of this size in the viewport, preferring\n * below the anchor and lined up with its left edge.\n */\nfunction resolveAuto(\n  view: Window,\n  rect: DOMRect,\n  panelWidth: number,\n  panelHeight: number,\n  gap: number\n): AnchoredCorner {\n  const fitsBelow = rect.bottom + panelHeight + gap <= view.innerHeight;\n  const fitsRight = rect.left + panelWidth <= view.innerWidth;\n  if (fitsBelow) return fitsRight ? 'bottom-left' : 'bottom-right';\n  return fitsRight ? 'top-left' : 'top-right';\n}\n\nconst samePosition = (a: AnchoredPosition, b: AnchoredPosition): boolean =>\n  a.position === b.position && a.top === b.top && a.left === b.left;\n\n/**\n * Places a floating panel against its anchor: resolves `auto` to a corner\n * and, for a panel fixed to the viewport, works out its coordinates. It\n * measures again on resize and on any scroll of the anchor's window (an\n * iframe's, when the anchor renders into one), so a fixed panel follows its\n * anchor. A measurement that changes nothing doesn't render again.\n *\n * Measuring happens in a layout effect, so the panel is placed before it\n * paints. It needs both elements on the page while `active` is on, and\n * keeps the last placement when either is missing.\n *\n * @function useAnchoredPosition\n * @param anchorRef - The element the panel opens from.\n * @param panelRef - The floating panel.\n * @param options - Whether to measure, the corner asked for, and how the panel is placed.\n * @returns The corner the panel opens from, with coordinates when it is fixed.\n */\nexport function useAnchoredPosition(\n  anchorRef: RefObject<HTMLElement | null>,\n  panelRef: RefObject<HTMLElement | null>,\n  { active, position, fixed, offset = 4, styledGap }: UseAnchoredPositionOptions\n): AnchoredPosition {\n  const [resolved, setResolved] = useState<AnchoredPosition>({\n    position: position === 'auto' ? 'bottom-left' : position,\n  });\n\n  useClientLayoutEffect(() => {\n    if (!active) return undefined;\n    const view =\n      (anchorRef.current ?? panelRef.current)?.ownerDocument.defaultView ??\n      window;\n    const update = () => {\n      const anchor = anchorRef.current;\n      const panel = panelRef.current;\n      if (!anchor || !panel) return;\n      const rect = anchor.getBoundingClientRect();\n      const { width, height } = panel.getBoundingClientRect();\n      const corner =\n        position === 'auto'\n          ? resolveAuto(\n              view,\n              rect,\n              width,\n              height,\n              offset + (styledGap?.(panel) ?? 0)\n            )\n          : position;\n      const next: AnchoredPosition = fixed\n        ? {\n            position: corner,\n            top: corner.startsWith('bottom')\n              ? rect.bottom + offset\n              : rect.top - height - offset,\n            left: corner.endsWith('left') ? rect.left : rect.right - width,\n          }\n        : { position: corner };\n      setResolved(prev => (samePosition(prev, next) ? prev : next));\n    };\n    update();\n    view.addEventListener('resize', update, { passive: true });\n    view.addEventListener('scroll', update, { passive: true, capture: true });\n    return () => {\n      view.removeEventListener('resize', update);\n      view.removeEventListener('scroll', update, { capture: true });\n    };\n  }, [active, anchorRef, panelRef, position, fixed, offset, styledGap]);\n\n  return resolved;\n}\n"],"names":[],"mappings":"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"}