@reshaped/utilities 3.9.1-canary.3 → 3.10.0-canary.5

package/README.md

@@ -0,0 +1,232 @@
+# @reshaped/utilities
+
+`@reshaped/utilities` is a standalone package that provides common utilities for building components and web applications with any framework. These utilities handle common patterns like focus management, scroll locking, DOM manipulation, and more.
+
+Reshaped uses this package internally to power its component library, and you can use the same utilities in your own projects to build consistent, accessible experiences. In case you're using React, check `@reshaped/headless` instead as it covers more APIs and provides a better built-in integration with React.
+
+```
+npm install @reshaped/utilities
+```
+
+## API overview
+
+### Flyout
+
+```ts
+import { Flyout } from "@reshaped/utilities";
+
+const flyout = new Flyout({
+	content: contentElement,
+	trigger: triggerElement,
+	position: "bottom-start",
+});
+
+// Position the flyout content based on the trigger element
+flyout.activate();
+
+// Clean-up the flyout behavior on closing the content
+flyout.deactivate();
+
+// Update flyout position based on updated options and the current viewport position
+flyout.update(options);
+```
+
+When you need to position floating elements like dropdowns, popovers, or tooltips, create a new Flyout instance and pass the content and trigger elements. The class handles complex positioning logic, collision detection, and automatic position adjustments to ensure your floating content is always visible and properly aligned.
+
+Flyout support multiple options to tailor its behavior for your use case. These options can be pass when creating a flyout instance or when using the `update` method.
+
+```ts
+export type Options = {
+	// Element that has to be positioned against the trigger. It has to be rendered at the moment of calling `new Flyout`
+	content: HTMLElement;
+
+	// Trigger element to position the content against
+	trigger?: HTMLElement | null;
+
+	// In case there is no trigger on the page, pass the x, y coordinates instead. This is useful for building components like context menus
+	triggerCoordinates?: { x: number; y: number } | null;
+
+	// Specify a container to position the content within instead of using the viewport boundaries
+	container?: HTMLElement | null;
+
+	// Default position to render the content, relative to the trigger
+	position:
+		| `top`
+		| `top-start`
+		| `top-end`
+		| `bottom`
+		| `bottom-start`
+		| `bottom-end`
+		| `start`
+		| `start-top`
+		| `start-bottom`
+		| `end`
+		| `end-top`
+		| `end-bottom`;
+
+	// Define which positions are used as fallbacks when default position doesn't fit into the viewport
+	// Passing an empty array would always keep the content in the same position
+	fallbackPositions?: Position[];
+
+	// Custom content width instead of using the width based on the content children
+	width?: Width;
+
+	// Try shifting and resizing the content if it doesn't fit into the viewport first instead of immediately changing the position
+	fallbackAdjustLayout?: boolean;
+
+	// Minimal height value for the content when using `fallbackAdjustLayout`
+	fallbackMinHeight?: string;
+
+	// Add an additional gap between the trigger and the content
+	contentGap?: number;
+	// Shift the content alongside the trigger
+	contentShift?: number;
+
+	// Handler for the cases when flyout deactivates itself internally based on the event handling
+	// For example, it might deactivate itself after scrolling the trigger outside the viewport
+	onDeactivate: () => void;
+};
+```
+
+### TrapFocus
+
+```ts
+import { TrapFocus } from "@reshaped/utilities";
+
+class Modal {
+	trapFocus;
+
+	constructor() {
+		this.trapFocus = new TrapFocus();
+	}
+
+	open() {
+		this.trapFocus.trap(targetRef.current);
+	}
+
+	close() {
+		this.trapFocus.release();
+	}
+}
+```
+
+When `TrapFocus` is activated, it traps keyboard and screen reader navigation within the given element until focus is released. Since TrapFocus is a class, you can create a new instance and pass the target element to initialize it. This is useful when an element (like a modal or popup) appears on screen. When the element is dismissed, call the release method to restore normal focus behavior.
+
+There are multiple options you can pass to the trapFocus methods to customize its behavior:
+
+```ts
+trapFocus.trap(
+  // element to trap the focus within
+  rootElement,
+  {
+    // keep the focus on the trigger and include it in the focus sequence
+    includeTrigger: boolean,
+
+    // element to move to the focus to after the initialization
+    initialFocusEl: HTMLElement
+
+    // keyboard navigation mode
+    // `dialog` - handles Tab and Shift + Tab, looping focus within the element
+    // `action-menu` - allows focus navigation with the ArrowUp and ArrowDown keys. Pressing Tab moves focus to the next element after the original trigger and automatically releases the focus trap. You can use the `onRelease` option to dismiss the content when that happens.
+    // `action-bar` - works like `action-menu`, but uses the ArrowLeft and ArrowRight keys to move focus instead.
+    // `content-menu` - keeps the navigation flow natural by including all focusable elements in the trapped area after the trigger element.
+    // Focus navigation uses the Tab key, but pressing Tab on the last element moves focus to the next element after the original trigger.
+    // This releases the focus trap, and you can respond to it using the `onRelease` handler.
+    mode: 'dialog' | 'action-menu' | 'action-bar' | 'content-menu';
+
+    // callback to run when the focus trap is released internally
+    // for example, when Tab is pressed in the action-menu mode
+    onRelease?: () => void;
+  }
+);
+
+trapFocus.release({
+  // By default, releasing the focus trap returns focus to the original trigger element.
+  // Use the withoutFocusReturn option to disable this behavior.
+  // This is useful when closing the element with an outside click and you want to avoid the page scrolling back to the trigger.
+  withoutFocusReturn: boolean
+})
+```
+
+### classNames
+
+The `classNames` utility is a lightweight function for combining multiple class names into a single string. It's similar to the popular classnames library but is included directly in Reshaped, eliminating the need for an additional dependency.
+
+Use this utility when building custom components that need to conditionally apply CSS classes based on props, state, or other conditions. It handles various input types including strings, booleans, null, and undefined values, making it easy to compose dynamic class names.
+
+```tsx
+import { classNames } from "@reshaped/utilities";
+import styles from "./Button.module.css";
+
+const Button = ({ variant, disabled, className }) => {
+	const buttonClassNames = classNames(
+		styles.root,
+		variant && styles[`variant-${variant}`],
+		disabled && styles.disabled,
+		className
+	);
+
+	return <button className={buttonClassNames}>Click me</button>;
+};
+```
+
+You can also pass arrays of class names, which is useful when dealing with responsive class names or more complex scenarios:
+
+```tsx
+const containerClassNames = classNames(
+	styles.container,
+	[responsive && styles.responsive, styles.flex],
+	padding && [styles.paddingTop, styles.paddingBottom]
+);
+```
+
+### lockScroll
+
+```ts
+import { lockScroll } from "@reshaped/utilities";
+
+class Modal {
+	unlock;
+
+	constructor() {}
+
+	open() {
+		this.unlock = lockScroll();
+	}
+
+	close() {
+		this.unlock?.();
+	}
+}
+```
+
+By default, `lockScroll` will lock the scrolling of the document body and there are a few additional options you can pass to customize the behavior. Calling the returned `unlockScroll` function will unlock the scrolling based on the originally passed options.
+
+`lockScroll` options:
+
+```ts
+const unlock = lockScroll({
+	// lock the scrolling of a specific element
+	containerEl,
+	// specify an element that triggered the scroll lock
+	// specifying it will automatically find the closest scrollable parent to lock its scrolling instead of locking the whole document
+	originEl,
+	// callback triggered when the scroll gets locked
+	// in case it was already locked before when triggered, the callback won't run
+	callback,
+});
+
+unlock({
+	// callback triggered when the scroll gets unlocked
+	callback,
+});
+```
+
+### isRTL
+
+```ts
+import { isRTL } from "@reshaped/utilities";
+
+// Call anywhere in your code
+const rtl = isRTL();
+```

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[];
+};