@react-hive/honey-utils 3.11.0 → 3.13.0

package/README.md

@@ -546,6 +546,8 @@ function divide(a: number, b: number): number {
 
 ### String Utilities
 
+---
+
 - `isString(value: unknown): value is string` - Checks if a value is a `string`.
 - `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is `null`, `undefined`, or an empty string.
 - `toKebabCase(input: string): string` - Converts a string to kebab-case.
@@ -555,10 +557,14 @@ function divide(a: number, b: number): number {
 
 ### Object Utilities
 
+---
+
 - `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
 
 ### Array Utilities
 
+---
+
 - `isArray(value: unknown): value is unknown[]` - Checks if a value is an array.
 - `isEmptyArray(value: unknown): value is []` - Checks if a value is an empty array.
 - `compact<T>(array: (T | Falsy)[]): T[]` – Returns a new array with all falsy values (false, null, undefined, 0, '', NaN) removed, preserving only truthy items of type `T`.
@@ -571,6 +577,8 @@ function divide(a: number, b: number): number {
 
 ### Function Utilities
 
+---
+
 - `isFunction(value: unknown): value is Function` - Checks if a value is a `function`.
 - `noop(): void` - A no-operation function.
 - `not<Args extends any[]>(fn: (...args: Args) => any): (...args: Args) => boolean` - Creates a new function that negates the result of the given predicate function. Useful for logical inversions, e.g., turning `isEven` into `isOdd`.
@@ -582,6 +590,8 @@ function divide(a: number, b: number): number {
 
 ### Type Guards
 
+---
+
 - `assert(condition: any, message: string): asserts condition` - Asserts that a condition is truthy, throwing an error with the provided message if it's not.
 - `isNumber(value: unknown): value is number` - Checks if a value is a `number`.
 - `isBool(value: unknown): value is boolean` - Checks if a value is a `boolean`.
@@ -605,32 +615,58 @@ function divide(a: number, b: number): number {
 
 ### Math Utilities
 
+---
+
 - `calculateEuclideanDistance(startX: number, startY: number, endX: number, endY: number): number` - Calculates the Euclidean distance between two points.
 - `calculateMovingSpeed(distance: number, elapsedTime: number): number` - Calculates moving speed.
 - `calculatePercentage(value: number, percentage: number): number` - Calculates the specified percentage of a value.
 
+### ENV
+
+---
+
+#### Storage
+
+- `isLocalStorageReadable(): boolean` - Determines whether `localStorage` can be safely read from. This check works even when writes fail (e.g., due to `QuotaExceededError`) and ensures that calling `getItem()` does not throw in restricted environments.
+- `getLocalStorageCapabilities(): LocalStorageCapabilities` - Detects the browser's read and write capabilities for `localStorage`. Readability is determined by safe execution of `getItem()`, while writability requires successful `setItem()` and `removeItem()`.
+
+### Geometry
+
+---
+
+#### Layout
+
+- `calculateCenterOffset(options: CalculateCenterOffsetOptions): number` - Calculates a clamped offset value that centers an element within a container along a single axis. Returns a negative value suitable for use in a CSS `translate` transform, or `0` when no overflow exists.
+
 ### DOM Utilities
 
-- `parse2DMatrix(element: HTMLElement): { 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.
+---
+
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
-- `getDOMRectIntersectionRatio(sourceRect: DOMRect, targetRect: DOMRect): number` - Calculates the ratio of the `targetRect` that is overlapped by the `sourceRect`. Returns a number between `0` (no overlap) and `1` (fully covered).
 - `getElementOffsetRect(element: HTMLElement): DOMRect` - Returns a `DOMRect` representing the element's layout position using `offsetLeft`, `offsetTop`, and `clientWidth`/`clientHeight`.
 - `isAnchorHtmlElement(element: HTMLElement): element is HTMLAnchorElement` - Determines whether the provided element is an `<a>` tag. Acts as a type guard that narrows the element to `HTMLAnchorElement`.
 - `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element has `contenteditable="true"`, making it user-editable and implicitly focusable.
-- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
-- `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
-- `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
+
+#### File
+
+- `downloadFile(file: Downloadable, options?: DownloadFileOptions): void` - Initiates a file download in a browser environment from a URL string or binary source (`Blob` / `MediaSource`). Automatically creates and revokes object URLs when required and safely no-ops in non-DOM environments (e.g. SSR).
+
+#### Layout
+
 - `hasXOverflow(element: HTMLElement): boolean` - Checks whether an element has horizontal overflow. Returns `true` if the content overflows beyond the visible width.
 - `getXOverflowWidth(element: HTMLElement): number` - Calculates the horizontal overflow width of an element. Returns the number of pixels by which the content exceeds the visible width, or `0` when no horizontal overflow exists.
 - `hasYOverflow(element: HTMLElement): boolean` - Checks whether an element has vertical overflow. Returns `true` if the content overflows beyond the visible height.
 - `getYOverflowHeight(element: HTMLElement): number` - Calculates the vertical overflow height of an element. Returns the number of pixels by which the content exceeds the visible height, or `0` when no vertical overflow exists.
-- `calculateCenterOffset(options: CalculateCenterOffsetOptions): number` - Calculates a clamped offset value that centers an element within a container along a single axis. Returns a negative value suitable for use in a CSS `translate` transform, or `0` when no overflow exists.
 - `centerElementInContainer(containerElement: HTMLElement, elementToCenter: HTMLElement, options?: CenterElementInContainerOptions): void` - Translates a container so that a target element is visually centered within its visible bounds using CSS transforms. Centering is applied independently per axis and only when an overflow exists.
-- `isLocalStorageReadable(): boolean` - Determines whether `localStorage` can be safely read from. This check works even when writes fail (e.g., due to `QuotaExceededError`) and ensures that calling `getItem()` does not throw in restricted environments.
-- `getLocalStorageCapabilities(): LocalStorageCapabilities` - Detects the browser's read and write capabilities for `localStorage`. Readability is determined by safe execution of `getItem()`, while writability requires successful `setItem()` and `removeItem()`.
+
+#### Transform
+
+- `parse2DMatrix(element: HTMLElement): { 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.
 
 ### File Utilities
 
+---
+
 - `isFile(value: unknown): value is File` - Checks if a value is a `File`.
 - `parseFileName(fileName: string): [baseName: string, extension: string]` - Splits a file name into its base name and extension using the last `.` as the separator. Handles edge cases such as hidden files (`.gitignore`), multi-dot names (`archive.tar.gz`), and names ending with a dot (`"file."`). The extension is returned in lowercase.
 - `fileListToFiles(fileList: FileList | null): File[]` - Converts a `FileList` object (such as the one returned from an `<input type="file">`) into a standard array of `File` objects. Returns an empty array when the input is `null`.
@@ -640,6 +676,8 @@ function divide(a: number, b: number): number {
 
 ### Asynchronous Utilities
 
+---
+
 - `isPromise<T = unknown>(value: unknown): value is Promise<T>` - Checks if a value is a `Promise`.
 - `runSequential<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Runs asynchronous operations on each array item *sequentially* and returns the results in the original order.
 - `runParallel<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Executes an asynchronous function for each array item *in parallel* and returns a promise of all results.
@@ -650,6 +688,25 @@ function divide(a: number, b: number): number {
 - `everyAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
 - `findAsync<Item>(array: Item[], predicate): Promise<Nullable<Item>>` - Returns the first array item that passes the async predicate, or `null` if no match is found.
 
+### Intersection Utilities
+
+---
+
+- `getDOMRectIntersectionRatio(sourceRect: DOMRect, targetRect: DOMRect): number` - Calculates the ratio of the `targetRect` that is overlapped by the `sourceRect`. Returns a number between `0` (no overlap) and `1` (fully covered).
+- `resolveAxisDelta(delta: AxisDelta, axis: Axis, options: ResolveAxisDeltaOptions): AxisDelta` – Resolves a raw two-dimensional input delta into an axis-aligned delta based on the specified axis. Supports optional vertical-to-horizontal fallback (useful for mouse wheels) and optional direction inversion for synthetic scrolling.
+
+### A11y
+
+---
+
+#### Focus
+
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
+- `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
+- `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/README.md

@@ -546,6 +546,8 @@ function divide(a: number, b: number): number {
 
 ### String Utilities
 
+---
+
 - `isString(value: unknown): value is string` - Checks if a value is a `string`.
 - `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is `null`, `undefined`, or an empty string.
 - `toKebabCase(input: string): string` - Converts a string to kebab-case.
@@ -555,10 +557,14 @@ function divide(a: number, b: number): number {
 
 ### Object Utilities
 
+---
+
 - `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
 
 ### Array Utilities
 
+---
+
 - `isArray(value: unknown): value is unknown[]` - Checks if a value is an array.
 - `isEmptyArray(value: unknown): value is []` - Checks if a value is an empty array.
 - `compact<T>(array: (T | Falsy)[]): T[]` – Returns a new array with all falsy values (false, null, undefined, 0, '', NaN) removed, preserving only truthy items of type `T`.
@@ -571,6 +577,8 @@ function divide(a: number, b: number): number {
 
 ### Function Utilities
 
+---
+
 - `isFunction(value: unknown): value is Function` - Checks if a value is a `function`.
 - `noop(): void` - A no-operation function.
 - `not<Args extends any[]>(fn: (...args: Args) => any): (...args: Args) => boolean` - Creates a new function that negates the result of the given predicate function. Useful for logical inversions, e.g., turning `isEven` into `isOdd`.
@@ -582,6 +590,8 @@ function divide(a: number, b: number): number {
 
 ### Type Guards
 
+---
+
 - `assert(condition: any, message: string): asserts condition` - Asserts that a condition is truthy, throwing an error with the provided message if it's not.
 - `isNumber(value: unknown): value is number` - Checks if a value is a `number`.
 - `isBool(value: unknown): value is boolean` - Checks if a value is a `boolean`.
@@ -605,32 +615,58 @@ function divide(a: number, b: number): number {
 
 ### Math Utilities
 
+---
+
 - `calculateEuclideanDistance(startX: number, startY: number, endX: number, endY: number): number` - Calculates the Euclidean distance between two points.
 - `calculateMovingSpeed(distance: number, elapsedTime: number): number` - Calculates moving speed.
 - `calculatePercentage(value: number, percentage: number): number` - Calculates the specified percentage of a value.
 
+### ENV
+
+---
+
+#### Storage
+
+- `isLocalStorageReadable(): boolean` - Determines whether `localStorage` can be safely read from. This check works even when writes fail (e.g., due to `QuotaExceededError`) and ensures that calling `getItem()` does not throw in restricted environments.
+- `getLocalStorageCapabilities(): LocalStorageCapabilities` - Detects the browser's read and write capabilities for `localStorage`. Readability is determined by safe execution of `getItem()`, while writability requires successful `setItem()` and `removeItem()`.
+
+### Geometry
+
+---
+
+#### Layout
+
+- `calculateCenterOffset(options: CalculateCenterOffsetOptions): number` - Calculates a clamped offset value that centers an element within a container along a single axis. Returns a negative value suitable for use in a CSS `translate` transform, or `0` when no overflow exists.
+
 ### DOM Utilities
 
-- `parse2DMatrix(element: HTMLElement): { 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.
+---
+
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
-- `getDOMRectIntersectionRatio(sourceRect: DOMRect, targetRect: DOMRect): number` - Calculates the ratio of the `targetRect` that is overlapped by the `sourceRect`. Returns a number between `0` (no overlap) and `1` (fully covered).
 - `getElementOffsetRect(element: HTMLElement): DOMRect` - Returns a `DOMRect` representing the element's layout position using `offsetLeft`, `offsetTop`, and `clientWidth`/`clientHeight`.
 - `isAnchorHtmlElement(element: HTMLElement): element is HTMLAnchorElement` - Determines whether the provided element is an `<a>` tag. Acts as a type guard that narrows the element to `HTMLAnchorElement`.
 - `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element has `contenteditable="true"`, making it user-editable and implicitly focusable.
-- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
-- `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
-- `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
+
+#### File
+
+- `downloadFile(file: Downloadable, options?: DownloadFileOptions): void` - Initiates a file download in a browser environment from a URL string or binary source (`Blob` / `MediaSource`). Automatically creates and revokes object URLs when required and safely no-ops in non-DOM environments (e.g. SSR).
+
+#### Layout
+
 - `hasXOverflow(element: HTMLElement): boolean` - Checks whether an element has horizontal overflow. Returns `true` if the content overflows beyond the visible width.
 - `getXOverflowWidth(element: HTMLElement): number` - Calculates the horizontal overflow width of an element. Returns the number of pixels by which the content exceeds the visible width, or `0` when no horizontal overflow exists.
 - `hasYOverflow(element: HTMLElement): boolean` - Checks whether an element has vertical overflow. Returns `true` if the content overflows beyond the visible height.
 - `getYOverflowHeight(element: HTMLElement): number` - Calculates the vertical overflow height of an element. Returns the number of pixels by which the content exceeds the visible height, or `0` when no vertical overflow exists.
-- `calculateCenterOffset(options: CalculateCenterOffsetOptions): number` - Calculates a clamped offset value that centers an element within a container along a single axis. Returns a negative value suitable for use in a CSS `translate` transform, or `0` when no overflow exists.
 - `centerElementInContainer(containerElement: HTMLElement, elementToCenter: HTMLElement, options?: CenterElementInContainerOptions): void` - Translates a container so that a target element is visually centered within its visible bounds using CSS transforms. Centering is applied independently per axis and only when an overflow exists.
-- `isLocalStorageReadable(): boolean` - Determines whether `localStorage` can be safely read from. This check works even when writes fail (e.g., due to `QuotaExceededError`) and ensures that calling `getItem()` does not throw in restricted environments.
-- `getLocalStorageCapabilities(): LocalStorageCapabilities` - Detects the browser's read and write capabilities for `localStorage`. Readability is determined by safe execution of `getItem()`, while writability requires successful `setItem()` and `removeItem()`.
+
+#### Transform
+
+- `parse2DMatrix(element: HTMLElement): { 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.
 
 ### File Utilities
 
+---
+
 - `isFile(value: unknown): value is File` - Checks if a value is a `File`.
 - `parseFileName(fileName: string): [baseName: string, extension: string]` - Splits a file name into its base name and extension using the last `.` as the separator. Handles edge cases such as hidden files (`.gitignore`), multi-dot names (`archive.tar.gz`), and names ending with a dot (`"file."`). The extension is returned in lowercase.
 - `fileListToFiles(fileList: FileList | null): File[]` - Converts a `FileList` object (such as the one returned from an `<input type="file">`) into a standard array of `File` objects. Returns an empty array when the input is `null`.
@@ -640,6 +676,8 @@ function divide(a: number, b: number): number {
 
 ### Asynchronous Utilities
 
+---
+
 - `isPromise<T = unknown>(value: unknown): value is Promise<T>` - Checks if a value is a `Promise`.
 - `runSequential<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Runs asynchronous operations on each array item *sequentially* and returns the results in the original order.
 - `runParallel<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Executes an asynchronous function for each array item *in parallel* and returns a promise of all results.
@@ -650,6 +688,25 @@ function divide(a: number, b: number): number {
 - `everyAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
 - `findAsync<Item>(array: Item[], predicate): Promise<Nullable<Item>>` - Returns the first array item that passes the async predicate, or `null` if no match is found.
 
+### Intersection Utilities
+
+---
+
+- `getDOMRectIntersectionRatio(sourceRect: DOMRect, targetRect: DOMRect): number` - Calculates the ratio of the `targetRect` that is overlapped by the `sourceRect`. Returns a number between `0` (no overlap) and `1` (fully covered).
+- `resolveAxisDelta(delta: AxisDelta, axis: Axis, options: ResolveAxisDeltaOptions): AxisDelta` – Resolves a raw two-dimensional input delta into an axis-aligned delta based on the specified axis. Supports optional vertical-to-horizontal fallback (useful for mouse wheels) and optional direction inversion for synthetic scrolling.
+
+### A11y
+
+---
+
+#### Focus
+
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
+- `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
+- `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/a11y/focus/get-focusable-html-elements.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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[];

package/dist/a11y/focus/index.d.ts

@@ -0,0 +1,3 @@
+export * from './is-html-element-focusable';
+export * from './get-focusable-html-elements';
+export * from './move-focus-within-container';

package/dist/a11y/focus/is-html-element-focusable.d.ts

@@ -0,0 +1,21 @@
+import type { Nullable } from '../../types';
+export declare const FOCUSABLE_HTML_TAGS: string[];
+/**
+ * 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;

package/dist/a11y/focus/move-focus-within-container.d.ts

@@ -0,0 +1,52 @@
+import type { Nullable } from '../../types';
+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;

package/dist/a11y/index.d.ts

@@ -0,0 +1 @@
+export * from './focus';

package/dist/dom/dom.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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;
+/**
+ * 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;

package/dist/dom/file/download-file.d.ts

@@ -0,0 +1,35 @@
+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;

package/dist/dom/file/index.d.ts

@@ -0,0 +1 @@
+export * from './download-file';

package/dist/dom/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dom';
+export * from './file';
+export * from './layout';
+export * from './transform';

package/dist/dom/layout/center-element-in-container.d.ts

@@ -0,0 +1,30 @@
+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;
+export {};

package/dist/dom/layout/index.d.ts

@@ -0,0 +1,2 @@
+export * from './overflow';
+export * from './center-element-in-container';

package/dist/dom/layout/overflow.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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;

package/dist/dom/transform/index.d.ts

@@ -0,0 +1 @@
+export * from './parse-2d-matrix';

package/dist/dom/transform/parse-2d-matrix.d.ts

@@ -0,0 +1,25 @@
+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;
+export {};

package/dist/env/index.d.ts

@@ -0,0 +1 @@
+export * from './storage';

package/dist/env/storage/index.d.ts

@@ -0,0 +1 @@
+export * from './local-storage';

package/dist/env/storage/local-storage.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 {};

package/dist/geometry/index.d.ts

@@ -0,0 +1 @@
+export * from './layout';