@reshaped/utilities 3.9.1-canary.2 → 3.10.0-canary.4

package/dist/a11y/Chain.d.ts

@@ -0,0 +1,20 @@
+type ID = number;
+type Item<T> = {
+    previousId?: ID | null;
+    nextId?: ID | null;
+    data: T;
+};
+declare class Chain<T = unknown> {
+    chain: Record<ID, Item<T>>;
+    tailId: ID | null;
+    idCounter: ID;
+    generateId(): number;
+    getAll(): Record<number, Item<T>>;
+    get(id: ID): Item<T>;
+    isLast(id: ID): boolean;
+    isEmpty(): boolean;
+    add(data: T): number;
+    remove(id: ID): T | undefined;
+    removePreviousTill(id: ID, condition: (item: Item<T>) => boolean): T | undefined;
+}
+export default Chain;

package/dist/a11y/Chain.js

@@ -0,0 +1,60 @@
+class Chain {
+    chain = {};
+    tailId = null;
+    idCounter = 0;
+    generateId() {
+        this.idCounter += 1;
+        return this.idCounter;
+    }
+    getAll() {
+        return this.chain;
+    }
+    get(id) {
+        return this.chain[id];
+    }
+    isLast(id) {
+        return this.tailId !== null && id === this.tailId;
+    }
+    isEmpty() {
+        return typeof this.tailId !== "number";
+    }
+    add(data) {
+        const previousId = this.tailId;
+        const previousItem = previousId && this.get(previousId);
+        const id = this.generateId();
+        this.chain[id] = { previousId, data };
+        if (previousItem)
+            previousItem.nextId = id;
+        this.tailId = id;
+        return id;
+    }
+    remove(id) {
+        const target = this.chain[id];
+        if (!target)
+            return;
+        const previousId = target.previousId;
+        const previousItem = previousId && this.get(previousId);
+        const nextId = target.nextId;
+        const nextItem = nextId && this.get(nextId);
+        if (previousItem)
+            previousItem.nextId = target.nextId ?? null;
+        if (nextItem)
+            nextItem.previousId = target.previousId ?? null;
+        if (!nextId)
+            this.tailId = previousId ?? null;
+        const data = this.get(id).data;
+        delete this.chain[id];
+        return data;
+    }
+    removePreviousTill(id, condition) {
+        const target = this.get(id);
+        const data = this.remove(id);
+        if (!target || !target.previousId)
+            return data;
+        const keepIterating = !condition(target);
+        if (keepIterating)
+            return this.removePreviousTill(target.previousId, condition);
+        return data;
+    }
+}
+export default Chain;

package/dist/a11y/TrapFocus.d.ts

@@ -0,0 +1,28 @@
+import Chain from "./Chain";
+import type { FocusableElement, TrapMode } from "./types";
+type ReleaseOptions = {
+    withoutFocusReturn?: boolean;
+};
+type TrapOptions = {
+    onRelease?: () => void;
+    includeTrigger?: boolean;
+    initialFocusEl?: FocusableElement | null;
+    mode?: TrapMode;
+};
+declare class TrapFocus {
+    #private;
+    static chain: Chain<TrapFocus>;
+    trapped?: boolean;
+    constructor();
+    /**
+     * Trap the focus, add observer and keyboard event listeners
+     * and create a chain item
+     */
+    trap: (root: HTMLElement, options?: TrapOptions) => void;
+    /**
+     * Disabled the trap focus for the element,
+     * cleanup all observers/handlers and trap for the previous element in the chain
+     */
+    release: (releaseOptions?: ReleaseOptions) => void;
+}
+export default TrapFocus;

package/dist/a11y/TrapFocus.js

@@ -0,0 +1,162 @@
+var _a;
+import * as keys from "../constants/keys.js";
+import { getShadowRoot } from "../dom/index.js";
+import Chain from "./Chain.js";
+import { getActiveElement, getFocusableElements, focusElement, getFocusData } from "./focus.js";
+import { checkKeyboardMode } from "./keyboardMode.js";
+import TrapScreenReader from "./TrapScreenReader.js";
+class TrapFocus {
+    static chain = new Chain();
+    #chainId;
+    #root = null;
+    #trigger = null;
+    #options = {};
+    trapped;
+    #screenReaderTrap = null;
+    #mutationObserver = null;
+    constructor() { }
+    /**
+     * Handle keyboard navigation while focus is trapped
+     */
+    #handleKeyDown = (event) => {
+        if (event.defaultPrevented)
+            return;
+        if (_a.chain.tailId !== this.#chainId)
+            return;
+        if (!this.#root)
+            return;
+        const { mode, onRelease, pseudoFocus, includeTrigger } = this.#options;
+        let navigationMode = "tabs";
+        if (mode === "action-menu" || mode === "selection-menu" || mode === "action-bar") {
+            navigationMode = "arrows";
+        }
+        const key = event.key;
+        const isTab = key === keys.TAB;
+        const isPrevTab = isTab && event.shiftKey;
+        const isNextTab = isTab && !event.shiftKey;
+        const isArrow = [keys.LEFT, keys.RIGHT, keys.UP, keys.DOWN].includes(key);
+        const isPrevArrow = navigationMode === "arrows" && key === (mode === "action-bar" ? keys.LEFT : keys.UP);
+        const isNextArrow = navigationMode === "arrows" && key === (mode === "action-bar" ? keys.RIGHT : keys.DOWN);
+        const isPrev = (isPrevTab && navigationMode === "tabs") || isPrevArrow;
+        const isNext = (isNextTab && navigationMode === "tabs") || isNextArrow;
+        const isFocusedOnTrigger = getActiveElement(this.#root) === this.#trigger;
+        const focusData = getFocusData({
+            root: this.#root,
+            target: isPrev ? "prev" : "next",
+            options: {
+                additionalElement: includeTrigger ? this.#trigger : undefined,
+                circular: true,
+            },
+        });
+        // Release the trap when tab is used in navigation modes that support arrows
+        const hasNavigatedOutside = (isTab && navigationMode === "arrows") ||
+            (mode === "content-menu" && isTab && focusData.overflow);
+        if (hasNavigatedOutside) {
+            // Prevent shift + tab event to avoid focus moving after the trap release
+            if (isPrevTab && !isFocusedOnTrigger)
+                event.preventDefault();
+            this.release();
+            onRelease?.();
+            return;
+        }
+        if (!isPrev && !isNext) {
+            // Avoid page from scrolling with arrow keys while focus it trapped
+            if (isArrow && (mode === "action-bar" || mode === "action-menu"))
+                event.preventDefault();
+            return;
+        }
+        event.preventDefault();
+        if (!focusData.el)
+            return;
+        focusElement(focusData.el, { pseudoFocus });
+    };
+    #addListeners = () => {
+        const shadowRoot = getShadowRoot(this.#root);
+        const el = shadowRoot ?? document;
+        el.addEventListener("keydown", this.#handleKeyDown);
+    };
+    #removeListeners = () => {
+        const shadowRoot = getShadowRoot(this.#root);
+        const el = shadowRoot ?? document;
+        el.removeEventListener("keydown", this.#handleKeyDown);
+    };
+    #isLast = () => {
+        const tailItem = _a.chain.tailId && _a.chain.get(_a.chain.tailId);
+        return tailItem && tailItem.data.#root === this.#root;
+    };
+    /**
+     * Trap the focus, add observer and keyboard event listeners
+     * and create a chain item
+     */
+    trap = (root, options = {}) => {
+        const { mode = "dialog", includeTrigger, initialFocusEl } = options;
+        this.#root = root;
+        this.#screenReaderTrap = new TrapScreenReader(root);
+        const trigger = getActiveElement(this.#root);
+        const focusable = getFocusableElements(this.#root, {
+            additionalElement: includeTrigger ? trigger : undefined,
+        });
+        const pseudoFocus = mode === "selection-menu";
+        this.#options = { ...options, pseudoFocus };
+        this.#trigger = trigger;
+        this.#mutationObserver = new MutationObserver(() => {
+            if (!this.#root)
+                return;
+            if (!this.#isLast())
+                return;
+            const currentActiveElement = getActiveElement(this.#root);
+            // Focus stayed inside the wrapper, no need to refocus
+            if (this.#root.contains(currentActiveElement))
+                return;
+            const focusable = getFocusableElements(this.#root, {
+                additionalElement: includeTrigger ? trigger : undefined,
+            });
+            if (!focusable.length)
+                return;
+            focusElement(focusable[0], { pseudoFocus });
+        });
+        this.#removeListeners();
+        this.#mutationObserver.observe(this.#root, { childList: true, subtree: true });
+        // Don't trap in case there is nothing to focus inside
+        if (!focusable.length && !initialFocusEl)
+            return;
+        this.#addListeners();
+        if (mode === "dialog")
+            this.#screenReaderTrap.trap();
+        const currentActiveElement = getActiveElement(this.#root);
+        const isLastInChain = this.#isLast();
+        // Don't add back to the chain if we're traversing back
+        if (!isLastInChain) {
+            this.#chainId = _a.chain.add(this);
+            // If the focus was moved manually (e.g. with autoFocus) - keep it there
+            if (!this.#root.contains(currentActiveElement)) {
+                focusElement(initialFocusEl || focusable[0], { pseudoFocus });
+            }
+        }
+        this.trapped = true;
+    };
+    /**
+     * Disabled the trap focus for the element,
+     * cleanup all observers/handlers and trap for the previous element in the chain
+     */
+    release = (releaseOptions = {}) => {
+        const { withoutFocusReturn } = releaseOptions;
+        if (!this.trapped || !this.#chainId || !this.#root)
+            return;
+        this.trapped = false;
+        if (this.#trigger && !withoutFocusReturn) {
+            this.#trigger.focus({ preventScroll: !checkKeyboardMode() });
+        }
+        _a.chain.removePreviousTill(this.#chainId, (item) => document.body.contains(item.data.#trigger));
+        this.#mutationObserver?.disconnect();
+        this.#removeListeners();
+        this.#screenReaderTrap?.release();
+        const previousItem = _a.chain.tailId && _a.chain.get(_a.chain.tailId);
+        if (previousItem && previousItem.data.#root) {
+            const trapInstance = new _a();
+            trapInstance.trap(previousItem.data.#root, previousItem.data.#options);
+        }
+    };
+}
+_a = TrapFocus;
+export default TrapFocus;

package/dist/a11y/TrapScreenReader.d.ts

@@ -0,0 +1,15 @@
+declare class TrapScreenReader {
+    root: HTMLElement;
+    /**
+     * Elements ignored by screen reader when trap is active
+     */
+    private hiddenElements;
+    constructor(root: HTMLElement);
+    /**
+     * Apply aria-hidden to all elements except the passed
+     */
+    hideSiblingsFromScreenReader: (el: HTMLElement) => void;
+    release: () => void;
+    trap: () => void;
+}
+export default TrapScreenReader;

package/dist/a11y/TrapScreenReader.js

@@ -0,0 +1,42 @@
+class TrapScreenReader {
+    root;
+    /**
+     * Elements ignored by screen reader when trap is active
+     */
+    hiddenElements = [];
+    constructor(root) {
+        this.root = root;
+    }
+    /**
+     * Apply aria-hidden to all elements except the passed
+     */
+    hideSiblingsFromScreenReader = (el) => {
+        let sibling = el.parentNode && el.parentNode.firstChild;
+        while (sibling) {
+            const notCurrent = sibling !== el;
+            const isValid = sibling.nodeType === 1 && !sibling.hasAttribute("aria-hidden");
+            if (notCurrent && isValid) {
+                sibling.setAttribute("aria-hidden", "true");
+                this.hiddenElements.push(sibling);
+            }
+            sibling = sibling.nextSibling;
+        }
+    };
+    release = () => {
+        this.hiddenElements.forEach((el) => {
+            el.removeAttribute("aria-hidden");
+        });
+        this.hiddenElements = [];
+    };
+    trap = () => {
+        let currentEl = this.root;
+        this.release();
+        // Stop at the body level for regular pages
+        // And stop at shadow root
+        while (currentEl !== document.body && currentEl.parentElement) {
+            this.hideSiblingsFromScreenReader(currentEl);
+            currentEl = currentEl.parentElement;
+        }
+    };
+}
+export default TrapScreenReader;

package/dist/a11y/focus.d.ts

@@ -0,0 +1,38 @@
+import type { FocusableElement, FocusableOptions } from "./types";
+export declare const focusableSelector = "a,button,input:not([type=\"hidden\"]),textarea,select,details,[tabindex],[contenteditable]";
+export declare const getActiveElement: (originEl?: HTMLElement | null) => HTMLButtonElement;
+export declare const focusElement: (el: FocusableElement, options?: {
+    pseudoFocus?: boolean;
+}) => void;
+export declare const getFocusableElements: (rootEl: HTMLElement, options?: FocusableOptions) => FocusableElement[];
+export declare const getFocusData: (args: {
+    root: HTMLElement;
+    target: "next" | "prev" | "first" | "last";
+    options?: FocusableOptions & {
+        circular?: boolean;
+    };
+}) => {
+    overflow: boolean;
+    el: FocusableElement;
+    focusableElements: FocusableElement[];
+};
+export declare const focusNextElement: (root: HTMLElement, options?: {
+    circular?: boolean;
+}) => {
+    el: FocusableElement;
+    focusableElements: FocusableElement[];
+};
+export declare const focusPreviousElement: (root: HTMLElement, options?: {
+    circular?: boolean;
+}) => {
+    el: FocusableElement;
+    focusableElements: FocusableElement[];
+};
+export declare const focusFirstElement: (root: HTMLElement) => {
+    el: FocusableElement;
+    focusableElements: FocusableElement[];
+};
+export declare const focusLastElement: (root: HTMLElement) => {
+    el: FocusableElement;
+    focusableElements: FocusableElement[];
+};

package/dist/a11y/focus.js

@@ -0,0 +1,101 @@
+import { getShadowRoot } from "../dom/index.js";
+const pseudoFocusAttribute = "data-rs-focus";
+export const focusableSelector = 'a,button,input:not([type="hidden"]),textarea,select,details,[tabindex],[contenteditable]';
+export const getActiveElement = (originEl) => {
+    const shadowRoot = originEl ? getShadowRoot(originEl) : null;
+    const rootEl = shadowRoot ?? document;
+    const pseudoFocusedEl = rootEl.querySelector(`[${pseudoFocusAttribute}]`);
+    return (pseudoFocusedEl || rootEl.activeElement);
+};
+export const focusElement = (el, options) => {
+    const shadowRoot = getShadowRoot(el);
+    const rootEl = shadowRoot ?? document;
+    rootEl.querySelector(`[${pseudoFocusAttribute}]`)?.removeAttribute(pseudoFocusAttribute);
+    if (options?.pseudoFocus) {
+        el.setAttribute(pseudoFocusAttribute, "true");
+    }
+    else {
+        el.focus();
+    }
+};
+export const getFocusableElements = (rootEl, options) => {
+    const focusableElements = Array.from(rootEl.querySelectorAll(focusableSelector));
+    const filteredElements = focusableElements.filter((el) => {
+        if (el.hasAttribute("disabled"))
+            return false;
+        if (el.clientHeight === 0)
+            return false;
+        // Using getAttribute here since browser sets el.tabIndex to -1 by default
+        if (!options?.includeNegativeTabIndex && el.getAttribute("tabindex") === "-1")
+            return false;
+        if (el.type === "radio") {
+            let sameNameRadioEls;
+            if (el.form) {
+                const formInputs = el.form.elements.namedItem(el.name);
+                // Synthetic error handling for narrowing down types
+                // Radio element can't find itself in the form, so we don't need to include it in the array
+                if (!formInputs)
+                    return false;
+                const multipleElementsFound = "length" in formInputs;
+                if (!multipleElementsFound) {
+                    // Single element found is always an input radio since we're inside the condition
+                    sameNameRadioEls = [formInputs];
+                }
+                else {
+                    sameNameRadioEls = Array.from(formInputs).filter((el) => "type" in el && el.type === "radio");
+                }
+            }
+            else {
+                sameNameRadioEls = Array.from(rootEl.querySelectorAll(`[type="radio"][name="${el.name}"]`));
+            }
+            if (sameNameRadioEls?.length) {
+                const checkedEl = Array.from(sameNameRadioEls).find((el) => el.checked);
+                if (checkedEl && el !== checkedEl)
+                    return false;
+                if (!checkedEl && el !== sameNameRadioEls[0])
+                    return false;
+            }
+        }
+        return true;
+    });
+    if (options?.additionalElement && filteredElements.length) {
+        filteredElements.unshift(options.additionalElement);
+    }
+    return filteredElements;
+};
+export const getFocusData = (args) => {
+    const { root, target, options } = args;
+    const focusable = getFocusableElements(root, {
+        additionalElement: options?.additionalElement,
+        includeNegativeTabIndex: options?.includeNegativeTabIndex,
+    });
+    const focusableLimit = focusable.length - 1;
+    const currentElement = getActiveElement(root);
+    const currentIndex = focusable.indexOf(currentElement);
+    const positions = {
+        next: currentIndex + 1,
+        prev: currentIndex - 1,
+        first: 0,
+        last: focusableLimit,
+    };
+    let nextIndex = positions[target];
+    const isOverflow = nextIndex > focusableLimit || nextIndex < 0;
+    if (isOverflow) {
+        if (options?.circular) {
+            nextIndex = target === "prev" ? positions.last : positions.first;
+        }
+        else {
+            nextIndex = target === "prev" ? positions.first : positions.last;
+        }
+    }
+    return { overflow: isOverflow, el: focusable[nextIndex], focusableElements: focusable };
+};
+const focusTargetElement = (root, target, options) => {
+    const data = getFocusData({ root, target, options });
+    focusElement(data.el);
+    return { el: data.el, focusableElements: data.focusableElements };
+};
+export const focusNextElement = (root, options) => focusTargetElement(root, "next", { ...options, includeNegativeTabIndex: true });
+export const focusPreviousElement = (root, options) => focusTargetElement(root, "prev", { ...options, includeNegativeTabIndex: true });
+export const focusFirstElement = (root) => focusTargetElement(root, "first", { includeNegativeTabIndex: true });
+export const focusLastElement = (root) => focusTargetElement(root, "last", { includeNegativeTabIndex: true });

package/dist/a11y/index.d.ts

@@ -0,0 +1,4 @@
+export { focusableSelector, getActiveElement, getFocusableElements, focusNextElement, focusPreviousElement, focusFirstElement, focusLastElement, } from "./focus";
+export { activateKeyboardMode, deactivateKeyboardMode, checkKeyboardMode } from "./keyboardMode";
+export { default as TrapFocus } from "./TrapFocus";
+export type { TrapMode, FocusableElement } from "./types";

package/dist/a11y/index.js

@@ -0,0 +1,3 @@
+export { focusableSelector, getActiveElement, getFocusableElements, focusNextElement, focusPreviousElement, focusFirstElement, focusLastElement, } from "./focus.js";
+export { activateKeyboardMode, deactivateKeyboardMode, checkKeyboardMode } from "./keyboardMode.js";
+export { default as TrapFocus } from "./TrapFocus.js";

package/dist/a11y/keyboardMode.d.ts

@@ -0,0 +1,4 @@
+export declare const keyboardModeAttribute = "data-rs-keyboard";
+export declare const activateKeyboardMode: () => void;
+export declare const deactivateKeyboardMode: () => void;
+export declare const checkKeyboardMode: () => boolean;

package/dist/a11y/keyboardMode.js

@@ -0,0 +1,10 @@
+export const keyboardModeAttribute = "data-rs-keyboard";
+export const activateKeyboardMode = () => {
+    document.documentElement.setAttribute(keyboardModeAttribute, "true");
+};
+export const deactivateKeyboardMode = () => {
+    document.documentElement.removeAttribute(keyboardModeAttribute);
+};
+export const checkKeyboardMode = () => {
+    return document.documentElement.hasAttribute(keyboardModeAttribute);
+};

package/dist/a11y/tests/Chain.test.js

@@ -0,0 +1,88 @@
+import { expect, test, describe, beforeEach } from "vitest";
+import Chain from "../Chain.js";
+describe("a11y/Chain", () => {
+    let chain;
+    beforeEach(() => {
+        chain = new Chain();
+    });
+    test("initializes as empty", () => {
+        expect(chain.isEmpty()).toBe(true);
+        expect(chain.getAll()).toEqual({});
+        expect(chain.tailId).toBe(null);
+    });
+    test("adds items and maintains chain order", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        const id3 = chain.add("third");
+        expect(chain.isEmpty()).toBe(false);
+        expect(chain.get(id1)).toEqual({ previousId: null, data: "first", nextId: id2 });
+        expect(chain.get(id2)).toEqual({ previousId: id1, data: "second", nextId: id3 });
+        expect(chain.get(id3)).toEqual({ previousId: id2, data: "third" });
+        expect(chain.tailId).toBe(id3);
+    });
+    test("identifies last item correctly", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        expect(chain.isLast(id1)).toBe(false);
+        expect(chain.isLast(id2)).toBe(true);
+    });
+    test("removes middle item and reconnects chain", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        const id3 = chain.add("third");
+        const removed = chain.remove(id2);
+        expect(removed).toBe("second");
+        expect(chain.get(id1).nextId).toBe(id3);
+        expect(chain.get(id3).previousId).toBe(id1);
+        expect(chain.get(id2)).toBeUndefined();
+    });
+    test("removes last item and updates tail", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        chain.remove(id2);
+        expect(chain.tailId).toBe(id1);
+        expect(chain.get(id1).nextId).toBe(null);
+    });
+    test("removes first item", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        chain.remove(id1);
+        expect(chain.get(id2).previousId).toBe(null);
+        expect(chain.get(id1)).toBeUndefined();
+    });
+    test("removes all items leaving chain empty", () => {
+        const id1 = chain.add("only");
+        chain.remove(id1);
+        expect(chain.isEmpty()).toBe(true);
+        expect(chain.tailId).toBe(null);
+    });
+    test("handles removing non-existent item", () => {
+        chain.add("first");
+        const result = chain.remove(999);
+        expect(result).toBeUndefined();
+    });
+    test("removes previous items until condition is met", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        const id3 = chain.add("third");
+        const id4 = chain.add("fourth");
+        const result = chain.removePreviousTill(id4, (item) => item.data === "second");
+        // Last deleted id
+        expect(result).toBe("second");
+        // Keeps only the first item
+        expect(chain.get(id1)).toEqual({ previousId: null, nextId: null, data: "first" });
+        expect(chain.get(id2)).toBeUndefined();
+        expect(chain.get(id3)).toBeUndefined();
+        expect(chain.get(id4)).toBeUndefined();
+        expect(chain.tailId).toBe(id1);
+    });
+    test("removePreviousTill stops at first item when condition never met", () => {
+        const id1 = chain.add("first");
+        const id2 = chain.add("second");
+        const result = chain.removePreviousTill(id2, () => false);
+        expect(result).toBe("first");
+        expect(chain.get(id1)).toBeUndefined();
+        expect(chain.get(id2)).toBeUndefined();
+        expect(chain.isEmpty()).toBe(true);
+    });
+});

package/dist/a11y/tests/TrapFocus.test.d.ts

@@ -0,0 +1 @@
+export {};