@react-hive/honey-utils 3.12.0 → 3.13.1

package/dist/dom.d.ts

@@ -1,343 +0,0 @@
-import type { Nullable } from './types';
-export declare const FOCUSABLE_HTML_TAGS: string[];
-interface HTMLElementTransformationValues {
-    translateX: number;
-    translateY: number;
-    scaleX: number;
-    scaleY: number;
-    skewX: number;
-    skewY: number;
-}
-/**
- * Extracts transformation values (translate, scale, skew) from the 2D transformation matrix of a given HTML element.
- *
- * Only works with 2D transforms (i.e., `matrix(a, b, c, d, e, f)`).
- *
- * @param element - The element with a CSS transform applied.
- * @returns An object with parsed transformation values.
- *
- * @example
- * ```ts
- * const values = parse2DMatrix(myElement);
- * console.log(values.translateX);
- * console.log(values.scaleX);
- * ```
- */
-export declare const parse2DMatrix: (element: HTMLElement) => HTMLElementTransformationValues;
-/**
- * Creates a clone of a Blob object.
- *
- * @param blob - The Blob object to clone.
- *
- * @returns A new Blob with the same content and type as the original.
- */
-export declare const cloneBlob: (blob: Blob) => Blob;
-/**
- * Calculates the intersection ratio between two DOM rectangles.
- *
- * The ratio represents the proportion of the `targetRect` that is covered by `sourceRect`.
- * A value of `1` means `sourceRect` completely covers `targetRect`, and `0` means no overlap.
- *
- * @param sourceRect - The rectangle used to measure overlap against the target.
- * @param targetRect - The rectangle whose covered area is measured.
- *
- * @returns A number between `0` and `1` representing the intersection ratio.
- */
-export declare const getDOMRectIntersectionRatio: (sourceRect: DOMRect, targetRect: DOMRect) => number;
-/**
- * Returns the bounding DOMRect of an element based on offset and client dimensions.
- *
- * This utility is useful when you need a stable, layout-based rect
- * without triggering a reflow via `getBoundingClientRect()`.
- *
- * @param element - The target HTML element.
- * @returns A `DOMRect` representing the element’s offset position and size.
- */
-export declare const getElementOffsetRect: (element: HTMLElement) => DOMRect;
-/**
- * Determines whether the given HTMLElement is an HTMLAnchorElement.
- *
- * Acts as a type guard so that TypeScript narrows `element` to
- * `HTMLAnchorElement` when the function returns `true`.
- *
- * An element qualifies as an anchor by having a tag name of `"A"`.
- *
- * @param element - The element to test.
- *
- * @returns Whether the element is an anchor element.
- */
-export declare const isAnchorHtmlElement: (element: HTMLElement) => element is HTMLAnchorElement;
-/**
- * Checks whether an element is explicitly marked as contenteditable.
- *
- * Browsers treat elements with `contenteditable="true"` as focusable,
- * even if they are not normally keyboard-focusable.
- *
- * @param element - The element to inspect.
- *
- * @returns True if `contenteditable="true"` is set.
- */
-export declare const isContentEditableHtmlElement: (element: HTMLElement) => boolean;
-/**
- * Determines whether an HTMLElement is focusable under standard browser rules.
- *
- * The function checks a combination of factors:
- * - The element must be rendered (not `display: none` or `visibility: hidden`).
- * - Disabled form controls are never focusable.
- * - Elements with `tabindex="-1"` are intentionally removed from the focus order.
- * - Certain native HTML elements are inherently focusable (e.g. inputs, buttons, anchors with `href`).
- * - Elements with `contenteditable="true"` are treated as focusable.
- * - Any element with a valid `tabindex` (not null) is considered focusable.
- *
- * This logic approximates how browsers and the accessibility tree
- * determine real-world focusability—not just tabindex presence.
- *
- * @param element - The element to test. `null` or `undefined` will return `false`.
- *
- * @returns Whether the element is focusable.
- */
-export declare const isHtmlElementFocusable: (element: Nullable<HTMLElement>) => boolean;
-/**
- * Collects all focusable descendant elements within a container.
- *
- * The function queries *all* elements under the container and filters them
- * using `isHtmlElementFocusable`, producing a reliable list of elements
- * that can receive keyboard focus in real-world browser conditions.
- *
- * @param container - The root container whose focusable children will be found.
- *
- * @returns An array of focusable HTMLElements in DOM order.
- */
-export declare const getFocusableHtmlElements: (container: HTMLElement) => HTMLElement[];
-export type FocusMoveDirection = 'next' | 'previous';
-export interface MoveFocusWithinContainerOptions {
-    /**
-     * Whether focus navigation should wrap around when reaching
-     * the beginning or end of the focusable elements list.
-     *
-     * When enabled, moving past the last element focuses the first,
-     * and moving before the first focuses the last.
-     *
-     * @default true
-     */
-    wrap?: boolean;
-    /**
-     * Custom resolver for determining the next focus index.
-     *
-     * When provided, this function overrides the default navigation logic
-     * and receives full control over how the focus moves.
-     *
-     * @param currentIndex - Index of the currently focused element.
-     * @param direction - Direction in which focus is moving.
-     * @param elements - Ordered list of focusable elements within the container.
-     *
-     * @returns The index of the element to focus next, or `null` to prevent focus movement.
-     */
-    getNextIndex?: (currentIndex: number, direction: FocusMoveDirection, elements: HTMLElement[]) => Nullable<number>;
-}
-/**
- * Moves focus to the next or previous focusable element within a container.
- *
- * This utility is commonly used to implement accessible keyboard navigation patterns such as:
- * - roving tabindex
- * - custom dropdowns
- * - tablists
- * - menus
- * - horizontal or vertical navigation groups
- *
- * Focus movement is scoped to a container and operates on the list of
- * focusable descendants returned by `getFocusableHtmlElements`.
- *
- * @param direction - Direction in which focus should move (`'next'` or `'previous'`).
- * @param container - Optional container that defines the focus scope.
- *  If omitted, the parent element of the currently focused element is used.
- * @param options - Optional configuration controlling wrapping behavior and custom index resolution.
- *
- * @remarks
- * - This function reads from and mutates the document's focus state.
- * - If no active element exists, no container can be resolved,
- *   or the active element is not part of the focusable set, no action is taken.
- * - When `getNextIndex` is provided, it fully overrides the default wrapping and directional logic.
- */
-export declare const moveFocusWithinContainer: (direction: FocusMoveDirection, container?: Nullable<HTMLElement>, { wrap, getNextIndex }?: MoveFocusWithinContainerOptions) => void;
-/**
- * Checks whether an element has horizontal overflow.
- *
- * @param element - The element to check.
- *
- * @returns `true` if the content overflows horizontally.
- */
-export declare const hasXOverflow: (element: HTMLElement) => boolean;
-/**
- * Calculates the horizontal overflow width of an element.
- *
- * The overflow width represents how much wider the content is compared
- * to the visible container area.
- *
- * @param element - The scrollable container element.
- *
- * @returns The overflow width in pixels. Returns `0` when the content does not overflow horizontally.
- */
-export declare const getXOverflowWidth: (element: HTMLElement) => number;
-/**
- * Checks whether an element has vertical overflow.
- *
- * @param element - The element to check.
- *
- * @returns `true` if the content overflows vertically.
- */
-export declare const hasYOverflow: (element: HTMLElement) => boolean;
-/**
- * Calculates the vertical overflow height of an element.
- *
- * The overflow height represents how much taller the content is compared
- * to the visible container area.
- *
- * @param element - The scrollable container element.
- *
- * @returns The overflow height in pixels. Returns `0` when the content does not overflow vertically.
- */
-export declare const getYOverflowHeight: (element: HTMLElement) => number;
-export interface CalculateCenterOffsetOptions {
-    /**
-     * Total overflow size for the axis.
-     *
-     * Represents how much larger the content is compared to the visible
-     * container size (e.g. scroll width minus client width).
-     */
-    overflowSize: number;
-    /**
-     * Visible size of the container along the axis.
-     *
-     * Typically, `clientWidth` for the X axis or `clientHeight` for the Y axis.
-     */
-    containerSize: number;
-    /**
-     * Offset of the target element from the start of the container along the axis.
-     *
-     * Typically, `offsetLeft` (X axis) or `offsetTop` (Y axis).
-     */
-    elementOffset: number;
-    /**
-     * Size of the target element along the axis.
-     *
-     * Typically, `clientWidth` (X axis) or `clientHeight` (Y axis).
-     */
-    elementSize: number;
-}
-/**
- * Calculates the offset required to center an element within a container along a single axis.
- *
- * The returned value is clamped so that the resulting translation does not
- * exceed the container's scrollable bounds.
- *
- * This function performs pure math only and does not access the DOM.
- *
- * @returns A negative offset value suitable for use in a CSS `translate`
- * transform, or `0` when no overflow exists on the axis.
- */
-export declare const calculateCenterOffset: ({ overflowSize, containerSize, elementOffset, elementSize, }: CalculateCenterOffsetOptions) => number;
-type Axis = 'x' | 'y' | 'both';
-export interface CenterElementInContainerOptions {
-    /**
-     * Axis (or axes) along which centering is applied.
-     *
-     * @default 'both'
-     */
-    axis?: Axis;
-}
-/**
- * Translates a container so that a target element is visually centered within its visible bounds.
- *
- * Centering is achieved by applying a CSS `transform: translate(...)` to the
- * container element rather than using native scrolling.
- *
- * ### Behavior
- * - Centering is calculated independently for each enabled axis.
- * - Translation is applied only when the container content overflows on that axis.
- * - When no overflow exists, the container remains untransformed for that axis.
- *
- * ### Notes
- * - This function performs immediate DOM reads and writes.
- * - The resulting transform is clamped to valid scrollable bounds.
- *
- * @param containerElement - The container whose content is translated.
- * @param elementToCenter - The descendant element to align to the container’s center.
- * @param options - Optional configuration controlling which axis or axes are centered.
- */
-export declare const centerElementInContainer: (containerElement: HTMLElement, elementToCenter: HTMLElement, { axis }?: CenterElementInContainerOptions) => void;
-/**
- * Determines whether the browser environment allows safe read access to
- * `localStorage`. Some platforms (e.g., Safari Private Mode, sandboxed iframes)
- * expose `localStorage` but still throw when accessed.
- *
- * This function **only tests read access**, making it safe even when write
- * operations would fail due to `QuotaExceededError` or storage restrictions.
- *
- * @returns `true` if `localStorage` exists and calling `getItem()` does not
- *          throw; otherwise `false`.
- */
-export declare const isLocalStorageReadable: () => boolean;
-interface LocalStorageCapabilities {
-    readable: boolean;
-    writable: boolean;
-}
-interface LocalStorageCapabilities {
-    readable: boolean;
-    writable: boolean;
-}
-/**
- * Determines whether the browser's `localStorage` supports safe read and write operations.
- * This function performs two independent checks:
- *
- * **1. Readability**
- * - Verified by calling `localStorage.getItem()` inside a `try` block.
- * - Fails in environments where storage access throws immediately (e.g., disabled storage,
- *   sandboxed iframes, strict privacy modes, SSR).
- *
- * **2. Writeability**
- * - Verified by attempting to `setItem()` and then `removeItem()` using a temporary key.
- * - Can fail due to:
- *   - `QuotaExceededError` when storage is full.
- *   - Disabled write access (e.g., Safari Private Mode).
- *   - Security-restricted contexts (third-party frames, hardened privacy settings)
- *
- * @returns An object describing the detected `localStorage` capabilities.
- */
-export declare const getLocalStorageCapabilities: () => LocalStorageCapabilities;
-export type Downloadable = Blob | MediaSource | string;
-export interface DownloadFileOptions {
-    /**
-     * Suggested filename for the downloaded file.
-     *
-     * When provided, the browser will attempt to save the file using this name.
-     * If omitted and the source is a URL string, the browser may infer the name
-     * from the URL.
-     */
-    fileName?: string;
-    /**
-     * Target browsing context for the download link.
-     */
-    target?: '_self' | '_blank';
-}
-/**
- * Initiates a file download in a browser environment.
- *
- * This utility supports downloading from:
- * - a URL string
- * - a `Blob`
- * - a `MediaSource`
- *
- * For non-string inputs, an object URL is created temporarily and
- * automatically revoked after the download is triggered.
- *
- * @remarks
- * - This function performs direct DOM manipulation and must be executed  in a browser environment.
- * - In non-DOM contexts (e.g. SSR), the function exits without side effects.
- * - Object URLs are revoked asynchronously to avoid Safari-related issues.
- *
- * @param file - The file source to download (URL string or binary object).
- * @param options - Optional configuration controlling filename and link target.
- */
-export declare const downloadFile: (file: Downloadable, { fileName, target }?: DownloadFileOptions) => void;
-export {};