@react-hive/honey-utils 4.2.0 → 5.0.0

package/README.md

@@ -99,7 +99,7 @@ splitStringIntoWords('hello world');
  * Generate a hash from a string
  */
 const hash = hashString('background-color: red;');
-// ➜ 'e4k1z0x'
+// ➜ '1s0s409'
 ```
 
 ### Encoding Utilities
@@ -188,6 +188,36 @@ parseJson('{name:"Mike"}');
 // ➜ null
 ```
 
+### Storage Utilities
+
+```ts
+import { readLocalStorageJson, writeLocalStorageJson } from '@react-hive/honey-utils';
+
+/**
+ * Store a value in localStorage as JSON
+ */
+writeLocalStorageJson('basket', [{ productId: 'p1', quantity: 2 }]);
+// ➜ true
+
+/**
+ * Read it back
+ */
+readLocalStorageJson<{ productId: string; quantity: number }[]>('basket');
+// ➜ [{ productId: 'p1', quantity: 2 }]
+
+/**
+ * Nothing stored, invalid JSON, or storage that cannot be read returns null
+ */
+readLocalStorageJson('missing');
+// ➜ null
+
+/**
+ * A write that fails (storage full, private mode, a circular value) returns false rather than throwing
+ */
+writeLocalStorageJson('basket', circularValue);
+// ➜ false
+```
+
 ### Array Utilities
 
 ```ts
@@ -200,6 +230,7 @@ import {
     intersection,
     difference,
     toggleArrayItem,
+    toMapBy,
     pipe,
     compose,
 } from '@react-hive/honey-utils';
@@ -260,6 +291,16 @@ toggleArrayItem(['a', 'b'], 'b', false);
 toggleArrayItem(['a', 'b'], 'a');
 // ➜ ['b']
 
+/**
+ * Index an array by a key
+ */
+const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+
+toMapBy(users, user => user.id);
+// ➜ Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+toMapBy(users, user => user.id, user => user.name);
+// ➜ Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+
 /**
  * Compose functions from left to right
  */
@@ -679,7 +720,7 @@ function divide(a: number, b: number): number {
 ---
 
 - `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.
+- `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.
 - `camelToDashCase(input: string): string` - Converts camelCase to dash-case.
 - `splitStringIntoWords(input: string): string[]` - Splits a string into an array of words.
@@ -714,7 +755,7 @@ function divide(a: number, b: number): number {
 
 ---
 
-- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
+- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`, symbol-keyed ones included. A key that may be `undefined` comes out optional.
 
 ### Array Utilities
 
@@ -724,8 +765,9 @@ function divide(a: number, b: number): number {
 - `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`.
 - `unique<T>(array: T[]): T[]` - Returns a new array with all duplicate elements removed. Keeps only the first occurrence of each value.
-- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size.
-- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays.
+- `toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue?: (item: Item, index: number) => Value): Map<Key, Item | Value>` - Indexes an array by a key: a `Map` from each item's key to the item, or to what `getValue` returns for it. Where two items share a key, the later one wins.
+- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size. Throws unless `size` is a positive whole number.
+- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays, each once, in the order of the first array.
 - `difference<T>(array: T[], exclude: T[]): T[]` - Returns a new array that contains items from `array` that are not present in `exclude`.
 - `pipe(...fns: Function[]): Function` - Composes unary functions left-to-right. Returns a new function that applies all given functions in a sequence.
 - `compose(...fns: Function[]): Function` - Composes unary functions **right-to-left**. Same as `pipe`, but applies functions in reverse order.
@@ -740,7 +782,7 @@ function divide(a: number, b: number): number {
 - `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`.
 - `invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result` - Invokes the input if it's a function, otherwise returns it as-is.
-- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls. Preserves both the original function’s parameter types and `this` binding.
+- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls; if it throws, every call throws that same error. Preserves both the original function’s parameter types and `this` binding.
 
 ### Type Guards
 
@@ -749,9 +791,9 @@ function divide(a: number, b: number): number {
 - `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`.
-- `isObject(value: unknown): value is object` - Checks if a value is an `object`.
+- `isObject(value: unknown): value is object` - Checks if a value is an `object`, `null` excluded.
 - `isNil(value: unknown): value is null | undefined` - Checks if a value is `null` or `undefined`.
-- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object.
+- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object - no own enumerable properties, symbol-keyed ones included.
 - `isNull(value: unknown): value is null` - Checks if a value is `null`.
 - `isUndefined(value: unknown): value is undefined` - Checks if a value is `undefined`.
 - `isDefined<T>(value: T): value is NonNullable<T>` - Checks if a value is neither `null` nor `undefined`.
@@ -786,6 +828,8 @@ function divide(a: number, b: number): number {
 
 - `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()`.
+- `readLocalStorageJson<Value>(key: string): Nullable<Value>` - Reads the value stored as JSON under a key in `localStorage`. Returns `null` when nothing is stored, the stored value is not valid JSON, or storage cannot be read (SSR, disabled storage, sandboxed iframes). Never throws. The value is cast to `Value`, not validated.
+- `writeLocalStorageJson(key: string, value: unknown): boolean` - Stores a value under a key in `localStorage` as JSON. Returns `true` once stored, or `false` when storage cannot be written (`QuotaExceededError`, private mode, restricted contexts, SSR) or the value cannot be serialised. Never throws.
 
 ### Geometry
 
@@ -806,7 +850,7 @@ function divide(a: number, b: number): number {
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
 - `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.
+- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element's `contenteditable` is `""`, `"true"` or `"plaintext-only"` (in any case), making it user-editable and implicitly focusable.
 
 #### File
 
@@ -858,8 +902,8 @@ 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.
 - `delay(delayMs: number): Promise<void>` - Creates a promise that resolves after the specified delay in milliseconds.
-- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error.
-- `retry<Task, TaskResult>(task: Task, options?: RetryOptions): Function` - Wraps an asynchronous function with retry logic, with configurable max attempts, delay between retries, exponential backoff, and retry callbacks.
+- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error. Its timer is cleared however the race ends.
+- `retry<Args, TaskResult>(task: (...args: Args) => Promise<TaskResult>, options?: RetryOptions): (...args: Args) => Promise<TaskResult>` - Wraps an asynchronous function with retry logic, with configurable max attempts (at least one), delay between retries, exponential backoff, and retry callbacks.
 
 ### Intersection Utilities
 
@@ -874,7 +918,7 @@ function divide(a: number, b: number): number {
 
 #### 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`.
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display` (an ancestor's too), `:disabled` (a disabled `<fieldset>`'s controls too), a valid `tabindex` (negative removes it, non-negative makes any element focusable), native focusable tags, and `contenteditable`.
 - `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).
 

package/dist/README.md

@@ -99,7 +99,7 @@ splitStringIntoWords('hello world');
  * Generate a hash from a string
  */
 const hash = hashString('background-color: red;');
-// ➜ 'e4k1z0x'
+// ➜ '1s0s409'
 ```
 
 ### Encoding Utilities
@@ -188,6 +188,36 @@ parseJson('{name:"Mike"}');
 // ➜ null
 ```
 
+### Storage Utilities
+
+```ts
+import { readLocalStorageJson, writeLocalStorageJson } from '@react-hive/honey-utils';
+
+/**
+ * Store a value in localStorage as JSON
+ */
+writeLocalStorageJson('basket', [{ productId: 'p1', quantity: 2 }]);
+// ➜ true
+
+/**
+ * Read it back
+ */
+readLocalStorageJson<{ productId: string; quantity: number }[]>('basket');
+// ➜ [{ productId: 'p1', quantity: 2 }]
+
+/**
+ * Nothing stored, invalid JSON, or storage that cannot be read returns null
+ */
+readLocalStorageJson('missing');
+// ➜ null
+
+/**
+ * A write that fails (storage full, private mode, a circular value) returns false rather than throwing
+ */
+writeLocalStorageJson('basket', circularValue);
+// ➜ false
+```
+
 ### Array Utilities
 
 ```ts
@@ -200,6 +230,7 @@ import {
     intersection,
     difference,
     toggleArrayItem,
+    toMapBy,
     pipe,
     compose,
 } from '@react-hive/honey-utils';
@@ -260,6 +291,16 @@ toggleArrayItem(['a', 'b'], 'b', false);
 toggleArrayItem(['a', 'b'], 'a');
 // ➜ ['b']
 
+/**
+ * Index an array by a key
+ */
+const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+
+toMapBy(users, user => user.id);
+// ➜ Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+toMapBy(users, user => user.id, user => user.name);
+// ➜ Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+
 /**
  * Compose functions from left to right
  */
@@ -679,7 +720,7 @@ function divide(a: number, b: number): number {
 ---
 
 - `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.
+- `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.
 - `camelToDashCase(input: string): string` - Converts camelCase to dash-case.
 - `splitStringIntoWords(input: string): string[]` - Splits a string into an array of words.
@@ -714,7 +755,7 @@ function divide(a: number, b: number): number {
 
 ---
 
-- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
+- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`, symbol-keyed ones included. A key that may be `undefined` comes out optional.
 
 ### Array Utilities
 
@@ -724,8 +765,9 @@ function divide(a: number, b: number): number {
 - `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`.
 - `unique<T>(array: T[]): T[]` - Returns a new array with all duplicate elements removed. Keeps only the first occurrence of each value.
-- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size.
-- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays.
+- `toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue?: (item: Item, index: number) => Value): Map<Key, Item | Value>` - Indexes an array by a key: a `Map` from each item's key to the item, or to what `getValue` returns for it. Where two items share a key, the later one wins.
+- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size. Throws unless `size` is a positive whole number.
+- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays, each once, in the order of the first array.
 - `difference<T>(array: T[], exclude: T[]): T[]` - Returns a new array that contains items from `array` that are not present in `exclude`.
 - `pipe(...fns: Function[]): Function` - Composes unary functions left-to-right. Returns a new function that applies all given functions in a sequence.
 - `compose(...fns: Function[]): Function` - Composes unary functions **right-to-left**. Same as `pipe`, but applies functions in reverse order.
@@ -740,7 +782,7 @@ function divide(a: number, b: number): number {
 - `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`.
 - `invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result` - Invokes the input if it's a function, otherwise returns it as-is.
-- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls. Preserves both the original function’s parameter types and `this` binding.
+- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls; if it throws, every call throws that same error. Preserves both the original function’s parameter types and `this` binding.
 
 ### Type Guards
 
@@ -749,9 +791,9 @@ function divide(a: number, b: number): number {
 - `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`.
-- `isObject(value: unknown): value is object` - Checks if a value is an `object`.
+- `isObject(value: unknown): value is object` - Checks if a value is an `object`, `null` excluded.
 - `isNil(value: unknown): value is null | undefined` - Checks if a value is `null` or `undefined`.
-- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object.
+- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object - no own enumerable properties, symbol-keyed ones included.
 - `isNull(value: unknown): value is null` - Checks if a value is `null`.
 - `isUndefined(value: unknown): value is undefined` - Checks if a value is `undefined`.
 - `isDefined<T>(value: T): value is NonNullable<T>` - Checks if a value is neither `null` nor `undefined`.
@@ -786,6 +828,8 @@ function divide(a: number, b: number): number {
 
 - `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()`.
+- `readLocalStorageJson<Value>(key: string): Nullable<Value>` - Reads the value stored as JSON under a key in `localStorage`. Returns `null` when nothing is stored, the stored value is not valid JSON, or storage cannot be read (SSR, disabled storage, sandboxed iframes). Never throws. The value is cast to `Value`, not validated.
+- `writeLocalStorageJson(key: string, value: unknown): boolean` - Stores a value under a key in `localStorage` as JSON. Returns `true` once stored, or `false` when storage cannot be written (`QuotaExceededError`, private mode, restricted contexts, SSR) or the value cannot be serialised. Never throws.
 
 ### Geometry
 
@@ -806,7 +850,7 @@ function divide(a: number, b: number): number {
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
 - `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.
+- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element's `contenteditable` is `""`, `"true"` or `"plaintext-only"` (in any case), making it user-editable and implicitly focusable.
 
 #### File
 
@@ -858,8 +902,8 @@ 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.
 - `delay(delayMs: number): Promise<void>` - Creates a promise that resolves after the specified delay in milliseconds.
-- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error.
-- `retry<Task, TaskResult>(task: Task, options?: RetryOptions): Function` - Wraps an asynchronous function with retry logic, with configurable max attempts, delay between retries, exponential backoff, and retry callbacks.
+- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error. Its timer is cleared however the race ends.
+- `retry<Args, TaskResult>(task: (...args: Args) => Promise<TaskResult>, options?: RetryOptions): (...args: Args) => Promise<TaskResult>` - Wraps an asynchronous function with retry logic, with configurable max attempts (at least one), delay between retries, exponential backoff, and retry callbacks.
 
 ### Intersection Utilities
 
@@ -874,7 +918,7 @@ function divide(a: number, b: number): number {
 
 #### 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`.
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display` (an ancestor's too), `:disabled` (a disabled `<fieldset>`'s controls too), a valid `tabindex` (negative removes it, non-negative makes any element focusable), native focusable tags, and `contenteditable`.
 - `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).
 

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

@@ -1,15 +1,17 @@
-import type { Nullable } from '~/types';
+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.
+ * - The element must be rendered: neither it nor an ancestor has `display: none`, and it is not
+ *   `visibility: hidden`.
+ * - Disabled form controls are never focusable - including those inside a disabled `<fieldset>`.
+ * - Elements with a negative `tabindex` are intentionally removed from the focus order.
+ * - Any element with a valid, non-negative `tabindex` is focusable. A `tabindex` that is not an
+ *   integer is ignored, as browsers ignore it.
  * - 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.
+ * - Editable elements (`contenteditable`) are treated as focusable.
  *
  * This logic approximates how browsers and the accessibility tree
  * determine real-world focusability—not just tabindex presence.

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

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../../types';
 export type FocusMoveDirection = 'next' | 'previous';
 export interface MoveFocusWithinContainerOptions {
     /**

package/dist/array/chunk.d.ts

@@ -6,11 +6,14 @@
  * @template T - The type of the items in the array.
  *
  * @param array - The input array to be chunked.
- * @param size - The size of each chunk. Must be greater than 0.
+ * @param size - The size of each chunk. Must be a positive whole number.
  *
  * @returns An array of chunks, where each chunk is an array of the specified size
  *          (except possibly the last chunk, which may be smaller).
  *
+ * @throws {Error} When `size` is not a positive whole number - a fractional size would give
+ *         chunks of other sizes, and `Infinity` none at all.
+ *
  * @example
  * ```ts
  * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]

package/dist/array/compose.d.ts

@@ -1,17 +1,21 @@
-type ComposeFn = (arg: unknown) => unknown;
+/**
+ * Any unary function: one taking a typed argument is assignable here, where it is not to
+ * `ComposeFn`.
+ */
+type AnyUnaryFn = (arg: never) => unknown;
 type Compose = {
     <A, R>(fn1: (a: A) => R): (a: A) => R;
     <A, B, R>(fn1: (b: B) => R, fn2: (a: A) => B): (a: A) => R;
     <A, B, C, R>(fn1: (c: C) => R, fn2: (b: B) => C, fn3: (a: A) => B): (a: A) => R;
     <A, B, C, D, R>(fn1: (d: D) => R, fn2: (c: C) => D, fn3: (b: B) => C, fn4: (a: A) => B): (a: A) => R;
     <A, B, C, D, E, R>(fn1: (e: E) => R, fn2: (d: D) => E, fn3: (c: C) => D, fn4: (b: B) => C, fn5: (a: A) => B): (a: A) => R;
-    (...fns: ComposeFn[]): (arg: unknown) => unknown;
+    (...fns: AnyUnaryFn[]): (arg: unknown) => unknown;
 };
 /**
  * Composes multiple unary functions into a single function, applying them from **right to left**.
  *
  * Often used for building functional pipelines where the innermost function runs first.
- * Types are inferred up to 5 chained functions for full type safety.
+ * Types are inferred up to 5 chained functions for full type safety. Beyond that, it falls back to the unknown.
  *
  * @param fns - A list of unary functions to compose.
  *

package/dist/array/get-adjacent-items.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 export interface AdjacentItems<T> {
     previousItem: Nullable<T>;
     currentItem: Nullable<T>;

package/dist/array/index.d.ts

@@ -9,3 +9,4 @@ export * from './is-array';
 export * from './is-empty-array';
 export * from './get-adjacent-items';
 export * from './toggle-array-item';
+export * from './to-map-by';

package/dist/array/intersection.d.ts

@@ -5,7 +5,8 @@
  *
  * @param arrays - Two or more arrays to find common elements from.
  *
- * @returns A new array containing only the elements that exist in all input arrays.
+ * @returns A new array containing only the elements that exist in all input arrays, each once, in
+ *          the order of the first array.
  *
  * @example
  * ```ts

package/dist/array/is-array.d.ts

@@ -4,5 +4,11 @@
  * @param value - The value to check.
  *
  * @returns `true` if the value is an array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isArray([1, 2]); // true
+ * isArray('12'); // false
+ * ```
  */
 export declare const isArray: (value: unknown) => value is unknown[];

package/dist/array/is-empty-array.d.ts

@@ -4,5 +4,12 @@
  * @param value - The value to check.
  *
  * @returns `true` if the value is an empty array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isEmptyArray([]); // true
+ * isEmptyArray([1]); // false
+ * isEmptyArray({}); // false
+ * ```
  */
 export declare const isEmptyArray: (value: unknown) => value is [];

package/dist/array/pipe.d.ts

@@ -1,11 +1,14 @@
-type PipeFn = (arg: unknown) => unknown;
+/**
+ * Any unary function: one taking a typed argument is assignable here, where it is not to `PipeFn`.
+ */
+type AnyUnaryFn = (arg: never) => unknown;
 type Pipe = {
     <A, B>(fn1: (a: A) => B): (a: A) => B;
     <A, B, C>(fn1: (a: A) => B, fn2: (b: B) => C): (a: A) => C;
     <A, B, C, D>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): (a: A) => D;
     <A, B, C, D, E>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D, fn4: (d: D) => E): (a: A) => E;
     <A, B, C, D, E, F>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D, fn4: (d: D) => E, fn5: (e: E) => F): (a: A) => F;
-    (...fns: PipeFn[]): (arg: unknown) => unknown;
+    (...fns: AnyUnaryFn[]): (arg: unknown) => unknown;
 };
 /**
  * Composes multiple unary functions into a single function, applying them from left to right.

package/dist/array/to-map-by.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Indexes an array by a key: a `Map` from each item's key to the item itself.
+ *
+ * Items are added in order, so where two share a key the later one wins, as with
+ * `new Map(entries)`.
+ *
+ * @template Item - The type of the items in the array.
+ * @template Key - The type of the keys.
+ *
+ * @param items - The items to index.
+ * @param getKey - Returns the key an item is stored under.
+ *
+ * @returns A new `Map` from each key to its item.
+ *
+ * @example
+ * ```ts
+ * const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+ *
+ * toMapBy(users, user => user.id);
+ * // Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+ * ```
+ */
+export declare function toMapBy<Item, Key>(items: readonly Item[], getKey: (item: Item, index: number) => Key): Map<Key, Item>;
+/**
+ * Indexes an array by a key: a `Map` from each item's key to what `getValue` returns for the item.
+ *
+ * Items are added in order, so where two share a key the later one wins, as with
+ * `new Map(entries)`.
+ *
+ * @template Item - The type of the items in the array.
+ * @template Key - The type of the keys.
+ * @template Value - The type of the values.
+ *
+ * @param items - The items to index.
+ * @param getKey - Returns the key an item is stored under.
+ * @param getValue - Returns the value stored for an item.
+ *
+ * @returns A new `Map` from each key to its value.
+ *
+ * @example
+ * ```ts
+ * const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+ *
+ * toMapBy(users, user => user.id, user => user.name);
+ * // Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+ * ```
+ */
+export declare function toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue: (item: Item, index: number) => Value): Map<Key, Value>;

package/dist/async/async.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 /**
  * Checks if a value is a Promise.
  *
@@ -109,6 +109,9 @@ export declare const filterParallel: <Item>(array: Item[], predicate: (item: Ite
 /**
  * Asynchronously checks if at least one element in the array satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that satisfies it - as
+ * `Array.prototype.some` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -118,6 +121,9 @@ export declare const someAsync: <Item>(array: Item[], predicate: (item: Item, in
 /**
  * Asynchronously checks if all elements in the array satisfy the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that fails it - as
+ * `Array.prototype.every` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -140,6 +146,9 @@ export declare const reduceAsync: <Item, Accumulator>(array: Item[], fn: (accumu
 /**
  * Asynchronously finds the first element that satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first match - as `Array.prototype.find`
+ * does.
+ *
  * @param array - The array of items to search.
  * @param predicate - An async function that returns a boolean.
  *

package/dist/async/retry.d.ts

@@ -1,6 +1,7 @@
 interface RetryOptions {
     /**
-     * Maximum number of retry attempts before failing.
+     * The total number of attempts, the first one included, before the last error is thrown. Taken
+     * as at least 1.
      *
      * @default 3
      */
@@ -35,7 +36,7 @@ interface RetryOptions {
  *
  * Useful for operations that may fail intermittently, such as network requests.
  *
- * @template Task - The type of the async function to wrap.
+ * @template Args - The arguments the async function takes.
  * @template TaskResult - The result type of the async function.
  *
  * @param task - The async function to wrap with retry logic.
@@ -68,5 +69,5 @@ interface RetryOptions {
  *   .catch(error => console.error('Failed after retries:', error));
  * ```
  */
-export declare const retry: <Task extends (...args: unknown[]) => Promise<TaskResult>, TaskResult>(task: Task, { maxAttempts, delayMs, backoff, onRetry }?: RetryOptions) => ((...args: Parameters<Task>) => Promise<TaskResult>);
+export declare const retry: <Args extends unknown[], TaskResult>(task: (...args: Args) => Promise<TaskResult>, { maxAttempts, delayMs, backoff, onRetry }?: RetryOptions) => ((...args: Args) => Promise<TaskResult>);
 export {};

package/dist/dom/data-transfer.d.ts

@@ -1,19 +1,37 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 export declare const DATA_TRANSFER_JSON_MIME = "application/json";
 /**
  * Serializes and stores JSON data in a DataTransfer object.
  *
  * Useful for drag-and-drop communication between elements.
  *
- * @param dataTransfer DataTransfer instance from a drag event.
- * @param data Data to serialize.
+ * @template T - The type of the data.
+ *
+ * @param dataTransfer - DataTransfer instance from a drag event.
+ * @param data - Data to serialize.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('dragstart', event => {
+ *   setDataTransferJson(event.dataTransfer, { id: 'card-1' });
+ * });
+ * ```
  */
 export declare const setDataTransferJson: <T>(dataTransfer: DataTransfer, data: T) => void;
 /**
  * Retrieves and parses JSON data from a DataTransfer object.
  *
- * @param dataTransfer DataTransfer instance from a drop event.
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param dataTransfer - DataTransfer instance from a drop event.
  *
  * @returns Parsed JSON value or null if not present or invalid.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('drop', event => {
+ *   const card = getDataTransferJson<{ id: string }>(event.dataTransfer);
+ * });
+ * ```
  */
 export declare const getDataTransferJson: <Value>(dataTransfer: DataTransfer) => Nullable<Value>;