@himanshu-sorathiya/react-kit 1.0.32 → 1.0.33

package/dist/index.d.ts

@@ -2844,30 +2844,238 @@ export declare function useGrouping<T = unknown>(options?: {
 	initialGroupBy?: string;
 }): UseGroupingReturn<T>;
 export type SelectionId = string | number;
-export interface UseMultipleSelectionReturn<T> {
-	selectedIds: SelectionId[];
+export type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+export type PathImpl<K extends string | number, V> = V extends Primitive ? `${K}` : V extends readonly unknown[] ? `${K}` | `${K}.${number}` | (V[number] extends Primitive ? never : `${K}.${number}.${Path<V[number]>}`) : `${K}` | `${K}.${Path<V>}`;
+export type Path<T> = T extends object ? {
+	[K in keyof T & (string | number)]: PathImpl<K, T[K]>;
+}[keyof T & (string | number)] : never;
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : unknown : P extends keyof T ? T[P] : unknown;
+/**
+ * All dot-notation paths of `T` whose resolved value is assignable to `TId`.
+ *
+ * @remarks
+ * This is what makes `field` type-safe: a path pointing at a boolean, an
+ * object, or a non-existent property simply isn't a member of this type, so
+ * passing it is a compile-time error rather than a silent `undefined` at
+ * runtime. Built on top of the `Path`/`PathValue` machinery already exported
+ * by `getValue`'s module.
+ *
+ * @template T The item shape.
+ * @template TId The id type the resolved value must be assignable to.
+ */
+export type SelectionIdPath<T, TId extends SelectionId> = {
+	[P in Path<T> & string]: PathValue<T, P> extends TId ? P : never;
+}[Path<T> & string];
+/**
+ * The options every {@link useMultipleSelection} call accepts regardless of
+ * whether `T` is a raw id type or an object type.
+ *
+ * @typeParam T - The item shape (or `TId` itself, for id-only mode).
+ * @typeParam TId - The id type used internally for `Set`/comparison purposes.
+ */
+export interface UseMultipleSelectionBaseOptions<T, TId extends SelectionId> {
+	/**
+	 * The items this selection is over. Determines `selectedItems`, and is
+	 * what `selectAll`/`toggleAll`/`invertSelection` operate against.
+	 *
+	 * @remarks
+	 * Pass a stable/memoized array. An inline `items={data.filter(...)}` gets
+	 * a new reference every render, which cascades into every memoized value
+	 * derived from `items` recomputing every render too — this hook can't
+	 * cheaply detect "same contents, different reference" for you.
+	 */
+	items?: readonly T[];
+	/**
+	 * The ids selected on mount, and what {@link UseMultipleSelectionReturn.reset}
+	 * returns the selection to.
+	 *
+	 * @remarks
+	 * Only the value present on the **first render** seeds state (standard
+	 * `useState` initializer semantics). `reset()` always reads the **latest**
+	 * `defaultSelectedIds` at call time, so if this changes across renders,
+	 * `reset()` restores to the newest default, not the original mount-time one.
+	 */
+	defaultSelectedIds?: readonly TId[];
+	/**
+	 * Predicate that marks certain ids as non-selectable.
+	 *
+	 * @remarks
+	 * Enforced on every operation that **adds** to the selection (`select`,
+	 * `toggle`'s select-direction, `selectMultiple`, `selectAll`, `toggleAll`,
+	 * `invertSelection`, `replaceSelection`). It never blocks **removal**
+	 * (`deselect`, `deselectMultiple`, `retainOnly`, `toggle`'s deselect-direction,
+	 * `deselectAll`) — if an already-selected id becomes disabled later, you can
+	 * always deselect it, just not re-select it.
+	 *
+	 * @param id - The id being checked.
+	 * @returns `true` if the id must not be added to the selection.
+	 */
+	isDisabled?: (id: TId) => boolean;
+}
+/**
+ * The `field` requirement, resolved conditionally on whether `T` is already
+ * an id (`[T] extends [TId]`) or a full object.
+ *
+ * @remarks
+ * - id-only mode (`T` is assignable to `TId`, e.g. the default `T = SelectionId`):
+ *   `field` is forbidden — there's nothing to extract a path from.
+ * - object mode: `field` is **required**, and restricted to
+ *   {@link SelectionIdPath} — a path that doesn't exist on `T`, or whose
+ *   resolved value isn't assignable to `TId`, is a compile-time error rather
+ *   than a silent `undefined` id at runtime.
+ */
+export type UseMultipleSelectionFieldOptions<T, TId extends SelectionId> = [
+	T
+] extends [
+	TId
+] ? {
+	field?: never;
+} : {
+	field: SelectionIdPath<T, TId>;
+};
+/**
+ * Combined options for {@link useMultipleSelection}. See
+ * {@link UseMultipleSelectionBaseOptions} and {@link UseMultipleSelectionFieldOptions}.
+ *
+ * @typeParam T - The item shape. Defaults to `SelectionId` (id-only mode: pass
+ * raw ids as "items", no `field` needed).
+ * @typeParam TId - The id type. Defaults to `SelectionId`; narrow it (e.g. to a
+ * branded `UserId`) for stronger inference.
+ */
+export type UseMultipleSelectionOptions<T = SelectionId, TId extends SelectionId = SelectionId> = UseMultipleSelectionBaseOptions<T, TId> & UseMultipleSelectionFieldOptions<T, TId>;
+/**
+ * Return shape of {@link useMultipleSelection}.
+ *
+ * @typeParam T - The item shape.
+ * @typeParam TId - The id type.
+ */
+export interface UseMultipleSelectionReturn<T = SelectionId, TId extends SelectionId = SelectionId> {
+	/**
+	 * The currently selected ids.
+	 *
+	 * @remarks
+	 * Ordered to match `items`' order whenever every selected id is present in
+	 * `items`. If some selected ids aren't in the current `items` array (e.g.
+	 * a previously-selected item that's since been filtered out, or an id
+	 * selected directly without ever appearing in `items`), those "orphaned"
+	 * ids are preserved and appended at the end, rather than silently dropped —
+	 * this hook never discards selection state you didn't ask it to discard.
+	 */
+	selectedIds: readonly TId[];
+	/** The number of currently selected ids (including any orphaned ones — see {@link UseMultipleSelectionReturn.selectedIds}). */
 	selectedCount: number;
-	selectedItems: T[];
+	/** The subset of `items` that are currently selected, in `items`' order. */
+	selectedItems: readonly T[];
+	/** Whether nothing at all is selected. */
 	isEmpty: boolean;
-	select: (item: SelectionId | T) => void;
-	deselect: (item: SelectionId | T) => void;
-	toggle: (item: SelectionId | T) => void;
-	isSelected: (item: SelectionId | T) => boolean;
-	resetSelection: () => void;
-	replaceSelection: (newSelectedItems: SelectionId[] | T[]) => void;
+	/**
+	 * Whether every *selectable* (non-disabled) item in `items` is currently
+	 * selected. `false` when `items` is empty. Intended for a "select all"
+	 * checkbox's checked state.
+	 */
+	isAllSelected: boolean;
+	/**
+	 * Whether some, but not all, selectable items in `items` are selected.
+	 * Intended for a "select all" checkbox's indeterminate state.
+	 */
+	isPartiallySelected: boolean;
+	/**
+	 * Adds `item` to the selection.
+	 * @remarks No-ops if `item` resolves to a disabled id.
+	 * @param item - A raw id, or a full item (requires `field` to have been configured).
+	 */
+	select: (item: TId | T) => void;
+	/**
+	 * Removes `item` from the selection. Always allowed, even for disabled ids.
+	 * @param item - A raw id, or a full item.
+	 */
+	deselect: (item: TId | T) => void;
+	/**
+	 * Adds `item` if not selected, removes it if selected.
+	 * @remarks The add-direction is blocked for disabled ids; the remove-direction never is.
+	 * @param item - A raw id, or a full item.
+	 */
+	toggle: (item: TId | T) => void;
+	/**
+	 * Checks whether `item` is currently selected.
+	 * @param item - A raw id, or a full item.
+	 * @returns `true` if currently selected.
+	 */
+	isSelected: (item: TId | T) => boolean;
+	/** Restores the selection to the current `defaultSelectedIds` (or empty, if none was provided). */
+	reset: () => void;
+	/**
+	 * Replaces the entire selection with exactly these ids/items.
+	 * @remarks Disabled ids are filtered out of the replacement set.
+	 */
+	replaceSelection: (newSelectedItems: readonly TId[] | readonly T[]) => void;
+	/** Selects every selectable (non-disabled) item in `items`. */
 	selectAll: () => void;
+	/** Clears the entire selection, including any disabled-but-selected or orphaned ids. */
 	deselectAll: () => void;
+	/**
+	 * If every selectable item in `items` is currently selected, clears the
+	 * whole selection; otherwise selects every selectable item in `items`.
+	 *
+	 * @remarks
+	 * Determined by actual set membership against every selectable item, not
+	 * a size comparison — this stays correct even if `items` contains duplicate
+	 * resolved ids, or the current selection contains ids no longer present in
+	 * `items` (both of which would silently misfire a naive `prev.size === items.length` check).
+	 */
 	toggleAll: () => void;
+	/** Selects every currently-unselected selectable item, and deselects everything else. */
 	invertSelection: () => void;
-	selectMultiple: (newItems: SelectionId[] | T[]) => void;
-	deselectMultiple: (itemsToRemove: SelectionId[] | T[]) => void;
-	retainOnly: (itemsToRetain: SelectionId[] | T[]) => void;
+	/**
+	 * Adds multiple ids/items to the selection at once.
+	 * @remarks Disabled ids are filtered out.
+	 */
+	selectMultiple: (newItems: readonly TId[] | readonly T[]) => void;
+	/** Removes multiple ids/items from the selection at once. Always allowed. */
+	deselectMultiple: (itemsToRemove: readonly TId[] | readonly T[]) => void;
+	/** Keeps only the ids/items in `itemsToRetain` that are already selected (an intersection); never adds anything new. */
+	retainOnly: (itemsToRetain: readonly TId[] | readonly T[]) => void;
 }
-export declare function useMultipleSelection<T = unknown>(options?: {
-	items?: T[];
-	field?: string;
-	initialSelectedIds?: SelectionId[];
-}): UseMultipleSelectionReturn<T>;
+/**
+ * Manages multi-item selection state (e.g. checkboxes in a table, a
+ * multi-select list, bulk-action UI).
+ *
+ * @remarks
+ * - Uncontrolled only for now — controlled mode is planned separately and
+ *   will be added without breaking this signature.
+ * - SSR-safe: no DOM/window access; `defaultSelectedIds` must be deterministic
+ *   between server and client renders to avoid hydration mismatches.
+ * - All returned callbacks are manually memoized with `useCallback`/`useMemo`
+ *   so this hook is safe to use even in codebases **without** the React Compiler.
+ * - Works in two modes, picked by whether `T` is assignable to `TId`:
+ *   - **id-only mode** (default): `useMultipleSelection()` — "items" are raw
+ *     ids, no `field` needed.
+ *   - **object mode**: `useMultipleSelection<Item, string>({ items, field: "id" })` —
+ *     `field` is a type-checked dot-path into `Item` and is required.
+ *
+ * @typeParam T - The item shape (or `TId` itself, for id-only mode).
+ * @typeParam TId - The id type. Defaults to `SelectionId`; narrow it for branded-id inference.
+ * @param options - See {@link UseMultipleSelectionOptions}.
+ * @returns The current selection state and the actions to mutate it. See {@link UseMultipleSelectionReturn}.
+ *
+ * @example
+ * ```tsx
+ * // id-only mode
+ * const { selectedIds, toggle } = useMultipleSelection({ defaultSelectedIds: ["a"] });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // object mode, with a nested field path and disabled rows
+ * interface Row { id: string; locked: boolean }
+ * const { selectedItems, toggleAll, isAllSelected, isPartiallySelected } = useMultipleSelection<Row, string>({
+ *   items: rows,
+ *   field: "id",
+ *   isDisabled: (id) => rows.find((r) => r.id === id)?.locked ?? false,
+ * });
+ * ```
+ */
+export declare function useMultipleSelection<T = SelectionId, TId extends SelectionId = SelectionId>(options?: UseMultipleSelectionOptions<T, TId>): UseMultipleSelectionReturn<T, TId>;
 export interface UseOrderReturn<T> {
 	orderedItems: T[];
 	moveUp: (index: number) => void;
@@ -2900,16 +3108,112 @@ export interface UsePaginationReturn<T> {
 	resetPagination: () => void;
 }
 export declare function usePagination<T>(data: T[] | undefined, initialPageSize: number, initialPageIndex?: number): UsePaginationReturn<T>;
-export interface UseSingleSelectionReturn {
-	selectedId: SelectionId | undefined;
+/**
+ * Configuration options for {@link useSingleSelection}.
+ *
+ * @typeParam TId - The concrete id type used by this selection instance.
+ * Must be assignable to {@link SelectionId} (`string | number`), but can be
+ * a narrower/branded type (e.g. `UserId`) for stronger inference at call sites.
+ */
+export interface UseSingleSelectionOptions<TId extends SelectionId = SelectionId> {
+	/**
+	 * The id that is selected on mount, and the id that {@link UseSingleSelectionReturn.reset}
+	 * returns the selection to.
+	 *
+	 * @remarks
+	 * Only the value present on the **first render** is used to seed state
+	 * (standard `useState` initializer semantics — later changes to this value
+	 * do not retroactively change the current selection). However, `reset()`
+	 * always reads the **latest** `defaultSelectedId` at the time it's called,
+	 * so if this value changes across renders, `reset()` will restore to the
+	 * newest default, not the original mount-time one.
+	 */
+	defaultSelectedId?: TId;
+	/**
+	 * Predicate that marks certain ids as non-selectable.
+	 *
+	 * @remarks
+	 * This guard is only enforced inside {@link UseSingleSelectionReturn.select}
+	 * and {@link UseSingleSelectionReturn.toggle}. It does **not** retroactively
+	 * clear a selection if an already-selected id later becomes disabled — the
+	 * hook has no way to know `isDisabled`'s result changed unless you call
+	 * `select`/`toggle` again. Reconcile that case yourself (e.g. via an effect)
+	 * if it matters for your use case.
+	 *
+	 * @param id - The id being checked before selection.
+	 * @returns `true` if the id must not be selectable.
+	 */
+	isDisabled?: (id: TId) => boolean;
+}
+/**
+ * Return shape of {@link useSingleSelection}.
+ *
+ * @typeParam TId - The concrete id type used by this selection instance.
+ */
+export interface UseSingleSelectionReturn<TId extends SelectionId = SelectionId> {
+	/** The currently selected id, or `undefined` if nothing is selected. */
+	selectedId: TId | undefined;
+	/**
+	 * Whether any id is currently selected.
+	 *
+	 * @remarks
+	 * Correctly distinguishes "nothing selected" from a falsy-but-valid id
+	 * such as `0` or `""` — this is `selectedId !== undefined`, not `!!selectedId`.
+	 */
 	hasSelection: boolean;
-	select: (id: SelectionId) => void;
+	/**
+	 * Selects the given id, replacing any current selection.
+	 *
+	 * @remarks No-ops if `id` is disabled per `isDisabled`.
+	 * @param id - The id to select.
+	 */
+	select: (id: TId) => void;
+	/** Clears the current selection (sets it to `undefined`). */
 	deselect: () => void;
-	toggle: (id: SelectionId) => void;
-	isSelected: (id: SelectionId) => boolean;
-	resetSelection: () => void;
+	/**
+	 * Selects `id` if it isn't already selected; deselects it if it is.
+	 *
+	 * @remarks No-ops if `id` is disabled per `isDisabled`.
+	 * @param id - The id to toggle.
+	 */
+	toggle: (id: TId) => void;
+	/**
+	 * Checks whether the given id is the currently selected one.
+	 *
+	 * @param id - The id to check.
+	 * @returns `true` if `id` is currently selected.
+	 */
+	isSelected: (id: TId) => boolean;
+	/**
+	 * Restores the selection to the current `defaultSelectedId`
+	 * (or `undefined` if none was provided).
+	 */
+	reset: () => void;
 }
-export declare function useSingleSelection(initialSelectedId?: SelectionId): UseSingleSelectionReturn;
+/**
+ * Manages single-item selection state (e.g. a radio group, a single-select
+ * list, an active tab/row).
+ *
+ * @remarks
+ * - Uncontrolled only for now — controlled mode (`selectedId` + `onSelectionChange`)
+ *   is planned separately and will be added without breaking this signature.
+ * - SSR-safe: performs no DOM/window access; `defaultSelectedId` must be
+ *   deterministic between server and client renders to avoid hydration mismatches.
+ * - All returned callbacks are manually memoized with `useCallback` so this
+ *   hook is safe to use even in codebases **without** the React Compiler.
+ *
+ * @typeParam TId - The concrete id type used by this selection instance.
+ * @param options - Optional configuration. See {@link UseSingleSelectionOptions}.
+ * @returns The current selection state and the actions to mutate it. See {@link UseSingleSelectionReturn}.
+ *
+ * @example
+ * ```tsx
+ * const { selectedId, select, isSelected } = useSingleSelection<string>({
+ *   defaultSelectedId: "row-1",
+ * });
+ * ```
+ */
+export declare function useSingleSelection<TId extends SelectionId = SelectionId>(options?: UseSingleSelectionOptions<TId>): UseSingleSelectionReturn<TId>;
 export type SortType = "numeric" | "alphabetical" | "alphanumeric" | "boolean" | "date" | "basic" | "custom";
 export interface BaseSortOptions {
 	desc?: boolean;
@@ -2951,6 +3255,235 @@ export interface UseSortReturn<T> {
 	getSortIndex: (id: string) => number | undefined;
 }
 export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+/**
+ * Restricts `field` to a **top-level** key of `T` whose value is assignable to `TId`.
+ *
+ * @remarks
+ * Deliberately not the recursive dot-path style used by `useMultipleSelection`'s
+ * `SelectionIdPath<T, TId>`. Tree nodes are self-referential (a `children` property
+ * whose value is `T[]`, pointing back to `T`), and running the recursive `Path<T>`
+ * machinery over a self-referential type produces a genuine TypeScript circular-reference
+ * error. A tree node's id is virtually always a direct top-level property anyway — a
+ * dot-path id nested inside a tree node would be an unusual shape — so this simpler,
+ * non-recursive key filter is both the fix and the more correct constraint. The function
+ * form below remains available for anything this doesn't cover.
+ */
+export type FieldKey<T, TId extends SelectionId> = {
+	[K in keyof T]: T[K] extends TId ? K : never;
+}[keyof T] & string;
+/** Restricts `childrenField` to a top-level key of `T` whose value is `T[]` (or `undefined`). */
+export type ChildrenKey<T> = {
+	[K in keyof T]: T[K] extends readonly T[] | undefined ? K : never;
+}[keyof T] & string;
+/** Either a type-checked property key, or a function, for extracting a node's id. */
+export type FieldAccessor<T, TId extends SelectionId> = FieldKey<T, TId> | ((item: T) => TId);
+/** Either a type-checked property key, or a function, for extracting a node's children. */
+export type ChildrenAccessor<T> = ChildrenKey<T> | ((item: T) => readonly T[] | undefined);
+/** The three states a tree node can be in with respect to the current selection. */
+export type TreeNodeState = "selected" | "indeterminate" | "unselected";
+/** One flattened tree entry, produced by {@link flattenForest}. */
+export interface FlatTreeEntry<T, TId extends SelectionId> {
+	item: T;
+	id: TId;
+	parentId: TId | undefined;
+	depth: number;
+}
+/** The precomputed structures every tree-selection operation is built on. */
+export interface FlattenedForest<T, TId extends SelectionId> {
+	/** Every node in the forest, in DFS pre-order. */
+	entries: readonly FlatTreeEntry<T, TId>[];
+	/** O(1) lookup from id to its flattened entry. */
+	entryById: ReadonlyMap<TId, FlatTreeEntry<T, TId>>;
+	/** O(1) lookup from a node's id to its direct children's ids. Roots are keyed under `undefined`. */
+	childIdsByParentId: ReadonlyMap<TId | undefined, readonly TId[]>;
+}
+export interface UseTreeSelectionOptions<T, TId extends SelectionId> {
+	/** The forest — an array of root nodes. Each node's children are found via `childrenField`. */
+	items: readonly T[];
+	/** How to extract a node's id. A type-checked top-level key, or a function. */
+	field: FieldAccessor<T, TId>;
+	/** How to extract a node's children. A type-checked top-level key, or a function. */
+	childrenField: ChildrenAccessor<T>;
+	/**
+	 * The ids selected on mount, and what {@link UseTreeSelectionReturn.reset} returns to.
+	 *
+	 * @remarks
+	 * Not trusted as already cascade-consistent — always run through the same
+	 * full bottom-up normalization used by `reset`/`selectAll`/etc, so passing
+	 * e.g. only a leaf (without its ancestors) still produces correct indeterminate
+	 * ancestor state from the start.
+	 */
+	defaultSelectedIds?: readonly TId[];
+	/**
+	 * Predicate marking certain ids as non-selectable.
+	 *
+	 * @remarks
+	 * A disabled node is skipped during cascade (never force-toggled) and excluded
+	 * from every "are all children selected" computation, but disabling a node does
+	 * **not** auto-disable its descendants, and does not retroactively clear it if
+	 * it was already selected before becoming disabled — same philosophy as the
+	 * flat selection hooks.
+	 */
+	isDisabled?: (id: TId) => boolean;
+	/**
+	 * Independently controls whether selecting a node propagates to its descendants
+	 * (`down`) and/or its ancestors (`up`). Both default to `true`.
+	 *
+	 * @remarks
+	 * `{ down: false, up: false }` degenerates into flat, non-hierarchical
+	 * selection over tree-rendered nodes (no relationship between a node's
+	 * selection and its parent/children) — the same shape react-arborist/MUI's
+	 * default tree multi-select uses, as opposed to checkbox-tree cascading.
+	 */
+	cascade?: {
+		down?: boolean;
+		up?: boolean;
+	};
+	/**
+	 * When `true`, {@link UseTreeSelectionReturn.selectedIds} and
+	 * {@link UseTreeSelectionReturn.selectedItems} only include leaf nodes,
+	 * even if a fully-covered branch is internally tracked as selected.
+	 *
+	 * @remarks
+	 * This does not change `select`/`toggle`/cascade behavior at all — you can
+	 * still call `select` on a branch and it cascades normally, and
+	 * {@link UseTreeSelectionReturn.getNodeState} still reports branches correctly
+	 * as `"selected"`/`"indeterminate"` for display regardless of this option. It
+	 * only changes what the flat `selectedIds`/`selectedItems` arrays report — useful
+	 * when branches are just a UI grouping and the "real" selected resources are
+	 * always the leaves (e.g. sending a set of leaf resource ids to a backend).
+	 * {@link UseTreeSelectionReturn.selectedLeafIds} gives you the leaf subset
+	 * regardless of this option, if you want both views at once.
+	 */
+	leafOnly?: boolean;
+}
+export interface UseTreeSelectionReturn<T, TId extends SelectionId> {
+	/**
+	 * Every fully-selected node's id, in forest (DFS pre-order) order.
+	 * @remarks Includes branch ids too, unless `leafOnly` is set. See {@link UseTreeSelectionOptions.leafOnly}.
+	 */
+	selectedIds: readonly TId[];
+	/** Just the leaf ids among the current selection, regardless of `leafOnly`. */
+	selectedLeafIds: readonly TId[];
+	/** Every node currently in a partial (some-but-not-all-descendants-selected) state. */
+	indeterminateIds: readonly TId[];
+	/** The item objects corresponding to {@link UseTreeSelectionReturn.selectedIds}. */
+	selectedItems: readonly T[];
+	/** `selectedIds.length`. */
+	selectedCount: number;
+	/** Whether nothing at all is selected (not even indeterminate). */
+	isEmpty: boolean;
+	/** Whether every selectable root (and by construction, everything under it) is selected. */
+	isAllSelected: boolean;
+	/** Whether some, but not all, of the forest is selected or indeterminate. */
+	isPartiallySelected: boolean;
+	/**
+	 * The full tri-state read for a node — the primitive the rest of the boolean
+	 * getters below are built from.
+	 * @param item - A raw id, or a full item.
+	 */
+	getNodeState: (item: TId | T) => TreeNodeState;
+	/** `getNodeState(item) === "selected"`. */
+	isSelected: (item: TId | T) => boolean;
+	/** `getNodeState(item) === "indeterminate"`. */
+	isIndeterminate: (item: TId | T) => boolean;
+	/**
+	 * Selects `item`, cascading per the `cascade` option.
+	 * @remarks No-ops if `item` itself resolves to a disabled id.
+	 */
+	select: (item: TId | T) => void;
+	/** Deselects `item`, cascading per the `cascade` option. Always allowed, even for disabled ids. */
+	deselect: (item: TId | T) => void;
+	/**
+	 * Selects `item` if not selected, deselects it if selected, cascading per the `cascade` option.
+	 * @remarks The select-direction is blocked for disabled ids; the deselect-direction never is.
+	 */
+	toggle: (item: TId | T) => void;
+	/** Restores the selection to the current `defaultSelectedIds` (normalized), or empty if none was given. */
+	reset: () => void;
+	/** Replaces the entire selection with exactly these ids/items (normalized — always internally consistent afterward). */
+	replaceSelection: (newSelectedItems: readonly TId[] | readonly T[]) => void;
+	/** Selects every selectable node in the forest. */
+	selectAll: () => void;
+	/** Clears the entire selection. */
+	deselectAll: () => void;
+	/** If everything selectable is currently selected, clears the selection; otherwise selects everything selectable. */
+	toggleAll: () => void;
+	/**
+	 * Selects multiple ids/items at once, cascading each per the `cascade` option.
+	 *
+	 * @remarks
+	 * More efficient than calling {@link UseTreeSelectionReturn.select} in a loop:
+	 * shared ancestors of multiple targets are only recomputed once each, not once
+	 * per target that shares them.
+	 */
+	selectMultiple: (newItems: readonly TId[] | readonly T[]) => void;
+	/** Deselects multiple ids/items at once, cascading each per the `cascade` option. Always allowed, even for disabled ids. */
+	deselectMultiple: (itemsToRemove: readonly TId[] | readonly T[]) => void;
+	/**
+	 * Keeps only the ids/items in `itemsToRetain` that are already selected (an
+	 * intersection); never adds anything new. The result is re-normalized, so
+	 * ancestor indeterminate state stays correct after the shrink.
+	 */
+	retainOnly: (itemsToRetain: readonly TId[] | readonly T[]) => void;
+	/**
+	 * Inverts the selection at the leaf level: every currently-unselected
+	 * selectable leaf becomes selected, every currently-selected one becomes
+	 * unselected. Branch/indeterminate state is re-derived from the result.
+	 * @remarks A disabled leaf that was selected before this call does not survive
+	 * it — like `useMultipleSelection`'s `invertSelection`, this is a full replace,
+	 * not a merge.
+	 */
+	invertSelection: () => void;
+	/** The id of `item`'s direct parent, or `undefined` if it's a root. */
+	getParentId: (item: TId | T) => TId | undefined;
+	/** Every ancestor id of `item`, nearest first, root last. Empty if `item` is a root. */
+	getAncestorIds: (item: TId | T) => readonly TId[];
+	/** Every descendant id of `item`. Empty if `item` is a leaf. */
+	getDescendantIds: (item: TId | T) => readonly TId[];
+}
+/**
+ * Manages hierarchical (tree/forest) selection state — checkbox trees, nested
+ * category pickers, permission trees, file explorers.
+ *
+ * @remarks
+ * - Uncontrolled only for now, SSR-safe (no DOM access), all callbacks manually
+ *   memoized — same guarantees as the other selection hooks in this library.
+ * - Expand/collapse state is explicitly **not** managed here — it's an orthogonal
+ *   view concern, not a selection concern (this hook only ever reads the full
+ *   `children` structure, regardless of what's currently expanded in the UI).
+ * - **Performance**: a single `select`/`deselect`/`toggle` call is
+ *   O(affected subtree) for the cascade-down step plus O(depth × branching factor)
+ *   for the cascade-up step — it never re-walks the whole tree. Only whole-forest
+ *   operations (`selectAll`, `toggleAll`, `reset`, `replaceSelection`, and the
+ *   initial mount) do a full O(n) pass, which is the right complexity for
+ *   something that touches every node anyway. Verified independent of selection
+ *   order (a known bug class in at least one production tree-selection library
+ *   is indeterminate state differing based on the order nodes were selected in).
+ * - If `items` (the tree **structure**) changes after mount — nodes added, removed,
+ *   or moved — the existing selection/indeterminate state is **not** automatically
+ *   re-normalized against the new shape (to avoid surprise O(n) work on every data
+ *   refresh). It stays correct for anything the change didn't touch, but the newly
+ *   changed area may need an explicit `reset()` or `replaceSelection()` to
+ *   guarantee full consistency again.
+ *
+ * @typeParam T - The tree node shape.
+ * @typeParam TId - The id type. Defaults to `SelectionId`.
+ * @param options - See {@link UseTreeSelectionOptions}.
+ * @returns The current selection state and the actions to mutate it. See {@link UseTreeSelectionReturn}.
+ *
+ * @example
+ * ```tsx
+ * interface Category { id: string; name: string; children?: Category[] }
+ *
+ * const { getNodeState, toggle, isAllSelected, toggleAll } = useTreeSelection<Category, string>({
+ *   items: categoryTree,
+ *   field: "id",
+ *   childrenField: "children",
+ * });
+ * ```
+ */
+export declare function useTreeSelection<T, TId extends SelectionId = SelectionId>(options: UseTreeSelectionOptions<T, TId>): UseTreeSelectionReturn<T, TId>;
 /**
  * Defines how a value of type `T` is converted to and from the string
  * format that `localStorage`/`sessionStorage` can actually store — the Web

package/dist/index.js

@@ -1,7 +1,7 @@
 import { t as e } from "./useEventListener.js";
 import { n as t, t as n } from "./events2.js";
 import { _ as r, a as i, c as a, d as o, f as s, g as c, h as l, i as u, l as d, m as f, n as p, o as m, p as h, r as g, s as _, t as v, u as y, v as b } from "./performance2.js";
-import { a as x, c as S, i as C, n as w, o as T, r as E, s as D, t as O } from "./state2.js";
-import { a as k, i as A, n as j, o as M, r as N, s as P, t as F } from "./storage2.js";
-import { i as I, n as L, r as R, t as z } from "./ui2.js";
-export { I as FuzzyHighlighter, N as bigIntSerializer, A as dateSerializer, k as defaultSerializer, M as mapSerializer, P as setSerializer, b as useBatcher, t as useClickOutside, c as useDebouncedCallback, l as useDebouncedState, f as useDebouncedValue, r as useDebouncer, e as useEventListener, R as useExpansion, S as useFilter, D as useFuzzySearch, T as useGrouping, i as useIntersectionObserver, n as useKey, j as useLocalStorage, x as useMultipleSelection, u as useMutationObserver, C as useOrder, E as usePagination, L as usePin, s as useRateLimitedCallback, o as useRateLimitedState, y as useRateLimitedValue, h as useRateLimiter, g as useResizeObserver, F as useSessionStorage, w as useSingleSelection, O as useSort, a as useThrottledCallback, _ as useThrottledState, m as useThrottledValue, d as useThrottler, p as useVirtualGrid, v as useVirtualList, z as useVisibility };
+import { a as x, c as S, i as C, l as w, n as T, o as E, r as D, s as O, t as k } from "./state2.js";
+import { a as A, i as j, n as M, o as N, r as P, s as F, t as I } from "./storage2.js";
+import { i as L, n as R, r as z, t as B } from "./ui2.js";
+export { L as FuzzyHighlighter, P as bigIntSerializer, j as dateSerializer, A as defaultSerializer, N as mapSerializer, F as setSerializer, b as useBatcher, t as useClickOutside, c as useDebouncedCallback, l as useDebouncedState, f as useDebouncedValue, r as useDebouncer, e as useEventListener, z as useExpansion, w as useFilter, S as useFuzzySearch, O as useGrouping, i as useIntersectionObserver, n as useKey, M as useLocalStorage, E as useMultipleSelection, u as useMutationObserver, x as useOrder, C as usePagination, R as usePin, s as useRateLimitedCallback, o as useRateLimitedState, y as useRateLimitedValue, h as useRateLimiter, g as useResizeObserver, I as useSessionStorage, D as useSingleSelection, T as useSort, a as useThrottledCallback, _ as useThrottledState, m as useThrottledValue, d as useThrottler, k as useTreeSelection, p as useVirtualGrid, v as useVirtualList, B as useVisibility };