@himanshu-sorathiya/react-kit 1.0.32 → 1.0.34

package/dist/state.d.ts

@@ -1,22 +1,261 @@
 // Generated by dts-bundle-generator v9.5.1
 
+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;
+/** The id type `useExpansion` operates on by default - a raw `string` or `number`. */
+export type ExpansionId = string | number;
+/**
+ * Options for {@link useExpansion}, in either of its two modes - id-only
+ * (`T` defaults to `TId`) or object mode (`T` is a distinct item shape,
+ * `TId` its resolved id type).
+ *
+ * @remarks
+ * The conditional shape is what makes `field` required in object mode and
+ * disallowed in id-only mode, entirely at the type level - see
+ * {@link useExpansion}'s remarks for why.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export type UseExpansionOptions<T = ExpansionId, TId extends ExpansionId = ExpansionId> = T extends TId ? {
+	/** The full list of expandable items - backs `expandedItems`/`collapsedItems`, and is the default target for `expandAll` when it's called with no argument. */
+	items?: readonly T[];
+	/** Ids expanded from the start - frozen at mount, see {@link useExpansion}'s remarks. */
+	initialExpandedIds?: readonly TId[];
+	/** Whether more than one item can be expanded at once. `false` (the default) gives accordion-style behavior, where expanding one item collapses whatever was previously expanded. */
+	multiple?: boolean;
+	/**
+	 * In single (`multiple: false`) mode, whether the one expanded item
+	 * can be collapsed back down to nothing.
+	 *
+	 * @remarks
+	 * Ignored when `multiple` is `true` - "can everything be collapsed"
+	 * isn't a meaningful constraint once more than one item can be open
+	 * at a time. Mirrors Radix UI Accordion's `collapsible` prop, though
+	 * the default here is the opposite of Radix's: `true`, matching what
+	 * this hook already did before `collapsible` existed, so leaving it
+	 * unset doesn't change any existing behavior.
+	 *
+	 * @defaultValue `true`
+	 */
+	collapsible?: boolean;
+} : {
+	/** The full list of expandable items - backs `expandedItems`/`collapsedItems`, and is the default target for `expandAll` when it's called with no argument. */
+	items: readonly T[];
+	/** A dot-path into `T`, used to resolve an item's id whenever a target is given as an item rather than a raw id. */
+	field: Path<T> | (string & {});
+	/** Ids expanded from the start - frozen at mount, see {@link useExpansion}'s remarks. */
+	initialExpandedIds?: readonly TId[];
+	/** Whether more than one item can be expanded at once. `false` (the default) gives accordion-style behavior, where expanding one item collapses whatever was previously expanded. */
+	multiple?: boolean;
+	/**
+	 * In single (`multiple: false`) mode, whether the one expanded item
+	 * can be collapsed back down to nothing.
+	 *
+	 * @remarks
+	 * Ignored when `multiple` is `true` - "can everything be collapsed"
+	 * isn't a meaningful constraint once more than one item can be open
+	 * at a time. Mirrors Radix UI Accordion's `collapsible` prop, though
+	 * the default here is the opposite of Radix's: `true`, matching what
+	 * this hook already did before `collapsible` existed, so leaving it
+	 * unset doesn't change any existing behavior.
+	 *
+	 * @defaultValue `true`
+	 */
+	collapsible?: boolean;
+};
+/**
+ * Return value of {@link useExpansion}.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export interface UseExpansionReturn<T = ExpansionId, TId extends ExpansionId = ExpansionId> {
+	/** The currently expanded ids. */
+	expandedIds: readonly TId[];
+	/** The subset of `items` that are currently expanded. */
+	expandedItems: readonly T[];
+	/** The subset of `items` that are not currently expanded. */
+	collapsedItems: readonly T[];
+	/** `expandedIds.length`. */
+	expandedCount: number;
+	/** Whether anything at all is expanded. */
+	hasExpanded: boolean;
+	/** Whether `itemOrId` is currently expanded. */
+	isExpanded: (itemOrId: TId | T) => boolean;
+	/**
+	 * Expands `itemOrId`.
+	 * @remarks No-ops if it's already expanded. In single mode, also collapses whatever was previously expanded.
+	 */
+	expand: (itemOrId: TId | T) => void;
+	/**
+	 * Collapses `itemOrId`.
+	 * @remarks No-ops if it isn't currently expanded, or (in single mode) if `collapsible` is `false`.
+	 */
+	collapse: (itemOrId: TId | T) => void;
+	/**
+	 * Expands `itemOrId` if it isn't expanded, collapses it if it is.
+	 * @remarks In single mode, expanding also collapses whatever was previously expanded; collapsing is blocked when `collapsible` is `false`, same as {@link UseExpansionReturn.collapse}.
+	 */
+	toggleExpansion: (itemOrId: TId | T) => void;
+	/**
+	 * Expands every id/item given, or every item in `items` if called with
+	 * no argument. Replaces the current expanded set rather than adding to
+	 * it.
+	 * @remarks No-ops (with a dev warning) when `multiple` is `false` - expanding "all" is meaningless in a mode that only ever allows one item open.
+	 */
+	expandAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/** Collapses every id/item given, or collapses everything if called with no argument. Unlike {@link UseExpansionReturn.expandAll}, not gated by `multiple` - collapsing to nothing is always meaningful. */
+	collapseAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/** Restores the expanded set to the value `initialExpandedIds` had at mount - see {@link useExpansion}'s remarks. Re-truncated against the *current* `multiple` value, not whatever it was at mount. */
+	resetExpansion: () => void;
+	/** Replaces the entire expanded set with exactly these ids/items, truncated to just the first if `multiple` is `false` and more than one is given. */
+	replaceExpansion: (newExpandedItems: readonly TId[] | readonly T[]) => void;
+}
+/**
+ * Manages which item(s) in a list are expanded - accordions, expandable
+ * table rows, collapsible sections.
+ *
+ * @remarks
+ * - Uncontrolled only for now - controlled mode is planned separately and
+ *   will be added without breaking this signature.
+ * - SSR-safe: performs no DOM/window access; `initialExpandedIds` 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.
+ * - Two modes, picked by whether `T` is assignable to `TId`: id-only
+ *   (default) - `itemOrId` parameters only ever receive raw ids, `field`
+ *   is disallowed; or object mode - `<Row, string>` plus a required
+ *   `field`, letting `itemOrId` parameters take a full item too. See
+ *   {@link UseExpansionOptions}.
+ * - The single/multiple invariant (at most one expanded id when `multiple`
+ *   is `false`) is enforced at every entry point that can introduce more
+ *   than one id at once - the initial mount, `resetExpansion`, and
+ *   `replaceExpansion` - not just `expand`/`toggleExpansion`, which only
+ *   ever add one id at a time by construction.
+ * - `collapsible` (single mode only) specifically gates the *interactive*
+ *   collapse path - `collapse`/`toggleExpansion` closing the one expanded
+ *   item. It does not gate `collapseAll` or `replaceExpansion([])`: those
+ *   are explicit, deliberate "set state directly" calls, treated the same
+ *   as `clearPins`/`replacePins` in `usePin` not respecting `maxPins`
+ *   either - a soft interactive constraint doesn't override an explicit
+ *   caller instruction.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ * @param options - See {@link UseExpansionOptions}.
+ * @returns The current expansion state and the actions to change it. See {@link UseExpansionReturn}.
+ *
+ * @example
+ * Accordion (single, non-collapsible - always exactly one open):
+ * ```tsx
+ * const { isExpanded, toggleExpansion } = useExpansion({
+ *   multiple: false,
+ *   collapsible: false,
+ *   initialExpandedIds: ["section-1"],
+ * });
+ * ```
+ *
+ * @example
+ * Object mode, multiple expandable rows:
+ * ```tsx
+ * interface Row { id: string; label: string }
+ * const { expandedItems, expand, expandAll } = useExpansion<Row, string>({
+ *   items: rows,
+ *   field: "id",
+ *   multiple: true,
+ * });
+ * ```
+ */
+export declare function useExpansion<T = ExpansionId, TId extends ExpansionId = ExpansionId>(options?: UseExpansionOptions<T, TId>): UseExpansionReturn<T, TId>;
+/**
+ * `Omit<T, K>`, applied per union member instead of to the flattened union
+ * as a whole - plain `Omit` over a union loses the correlation between
+ * `type`/`operator` and that arm's own `value` shape, which is exactly the
+ * information {@link FilterConfigUpdate} needs to preserve.
+ */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** `Partial<T>`, applied per union member - same distributive reasoning as {@link DistributiveOmit}. */
+export type DistributivePartial<T> = T extends unknown ? Partial<T> : never;
+/** The comparison strategy for a filter - selects which operator set (`text`, `number`, etc.) applies, or `custom` for a caller-supplied predicate. */
 export type FilterType = "text" | "number" | "boolean" | "date" | "select" | "multiselect" | "custom";
+/** Operators available on a `text`-type filter. */
 export type TextOperator = "contains" | "equals" | "startsWith" | "endsWith" | "notContains";
+/** Operators available on a `number`-type filter. */
 export type NumberOperator = "equals" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual" | "between";
-export type BooleanOperator = "equals";
+/** Operators available on a `boolean`-type filter. */
+export type BooleanOperator = "equals" | "notEquals";
+/** Operators available on a `date`-type filter. */
 export type DateOperator = "equals" | "before" | "after" | "between";
-export type SelectOperator = "equals" | "notEquals";
+/** Operators available on a `select`-type filter (single value against a scalar field). */
+export type SelectOperator = "equals" | "notEquals" | "in" | "notIn";
+/** Operators available on a `multiselect`-type filter (against an array-valued field). */
 export type MultiselectOperator = "in" | "notIn" | "intersects";
+/** The sole operator for a `custom`-type filter - present for structural symmetry with the other operator unions, not because there's a real choice to make. */
 export type CustomOperator = "custom";
+/** Options shared across filter types, though not every option is meaningful for every type. */
 export interface FilterOptions<T = unknown> {
+	/**
+	 * Case sensitivity for `text` comparisons. Ignored by every other
+	 * filter type - `select` deliberately has no equivalent, since select
+	 * values are enumerated tokens (a fixed options list, an HTML
+	 * `<select>`), not free-typed input that could differ only by case.
+	 * @defaultValue `false`
+	 */
 	caseSensitive?: boolean;
+	/**
+	 * Comparison granularity for `date` filters.
+	 * `"day"` ignores time-of-day (calendar-date comparison); `"instant"`
+	 * compares exact milliseconds. Ignored by every other filter type.
+	 * @defaultValue `"day"`
+	 */
+	dateGranularity?: "day" | "instant";
+	/** Required for `type: "custom"` - the predicate deciding whether an item matches. Ignored by every other filter type. */
 	compare?: (itemValue: unknown, filterValue: unknown, item: T) => boolean;
 }
+/** Options for {@link useFilter}. */
+export interface UseFilterOptions {
+	/**
+	 * Defers the filtering recomputation (via `useDeferredValue`) so
+	 * changing `filters` doesn't block a more urgent update (e.g. the
+	 * keystroke that triggered the change). Only `filters` is deferred -
+	 * `data` is not.
+	 * @defaultValue `false`
+	 */
+	defer?: boolean;
+}
+/** Fields common to every {@link FilterConfig}, regardless of `type`/`operator`. */
 export type BaseFilterConfig<T> = FilterOptions<T> & {
+	/** Unique identifier for this filter - used for lookups (`getFilter`, `isFilterActive`, etc.) and to distinguish filters in the `filters` array. */
 	id: string;
-	field: string;
+	/** Dot-separated path into each item, e.g. `"address.city"`. Falls back to `id` when omitted - so `id` alone is often enough if it already matches the field name. */
+	field?: string;
+	/**
+	 * Whether this filter currently participates in filtering. An inactive
+	 * filter stays in the `filters` array (so its configuration - operator,
+	 * value, etc. - is preserved) but is skipped during evaluation.
+	 * @defaultValue `true`
+	 */
 	isActive?: boolean;
 };
+/**
+ * A single filter's full configuration.
+ *
+ * @remarks
+ * Each `type` has its own dedicated arm(s) - `number`/`date`/`select` each
+ * split further by operator (a `between` arm with a `{min,max}` value,
+ * separate from every other operator's scalar/array value) - rather than
+ * grouping multiple type literals under one shared arm. This is what lets
+ * TypeScript actually narrow `value`'s type based on `type`+`operator`,
+ * and what makes {@link FilterOptionsForType}-style per-type extraction
+ * (and IDE autocomplete while constructing a filter) work correctly -
+ * grouping literals under one arm silently breaks both.
+ */
 export type FilterConfig<T = unknown> = BaseFilterConfig<T> & ({
 	type: "text";
 	operator: TextOperator;
@@ -49,8 +288,12 @@ export type FilterConfig<T = unknown> = BaseFilterConfig<T> & ({
 	value: string | number | Date;
 } | {
 	type: "select";
-	operator: SelectOperator;
+	operator: Exclude<SelectOperator, "in" | "notIn">;
 	value: string | number;
+} | {
+	type: "select";
+	operator: "in" | "notIn";
+	value: (string | number)[];
 } | {
 	type: "multiselect";
 	operator: MultiselectOperator;
@@ -60,175 +303,1598 @@ export type FilterConfig<T = unknown> = BaseFilterConfig<T> & ({
 	operator: CustomOperator;
 	value: unknown;
 });
+/** All configured filters. Order has no effect on filtering (every active filter is AND-combined), only on iteration order of `filters`/`groupedRecord`-style outputs elsewhere in this library. */
 export type FilterState<T> = FilterConfig<T>[];
+/**
+ * The update payload type for `updateFilterConfig`.
+ *
+ * @remarks
+ * Best-effort compile-time guidance, not a full guarantee: a *merge* of an
+ * update into an existing filter can still land on a structurally invalid
+ * `type`/`operator`/`value` combination that the type system alone can't
+ * catch (partial updates flatten across a union in ways whole-object
+ * construction doesn't). `isValueShapeValid`, run on the merged result
+ * inside `applyFilterUpdate`, is the actual runtime backstop.
+ */
+export type FilterConfigUpdate<T> = DistributivePartial<DistributiveOmit<FilterConfig<T>, "id">>;
+/** Return value of {@link useFilter}. */
 export interface UseFilterReturn<T> {
+	/** `data`, filtered by every active entry in `filters` (AND-combined). Same reference as `data` (no copy, no filter) when there are no active filters. */
 	filteredItems: T[];
+	/** Every configured filter, active or not. */
 	filters: FilterState<T>;
+	/** Count of filters with `isActive !== false`. */
+	activeFilterCount: number;
+	/** `activeFilterCount > 0`. */
+	hasActiveFilters: boolean;
+	/** Adds a new filter, or replaces the existing one with the same `id`. */
 	upsertFilter: (filter: FilterConfig<T>) => void;
+	/** Removes one filter by `id`, or several at once by passing an array of ids. */
 	removeFilter: (id: string | string[]) => void;
+	/** Clears every filter entirely - equivalent to `replaceFilters([])`. */
 	clearFilters: () => void;
+	/** Restores `filters` to the value passed as `initialFilters` at mount. Later changes to that argument have no effect - the reset target is frozen at mount. */
 	resetFilters: () => void;
+	/** Replaces the entire `filters` array at once. */
 	replaceFilters: (filters: FilterConfig<T>[]) => void;
+	/** Flips a filter's `isActive` (defaulting to `true` if the filter doesn't exist yet, in which case it's added). Configuration (operator, value, etc.) is preserved either way. */
 	toggleFilter: (filter: FilterConfig<T>) => void;
-	updateFilterConfig: (id: string, partialConfig: Partial<Omit<FilterConfig<T>, "id">>) => void;
+	/**
+	 * Partially updates an existing filter's config by `id`.
+	 * @remarks An unknown `id`, or an update that would produce a value
+	 * incompatible with the filter's `type`/`operator`, is rejected - see
+	 * {@link isValueShapeValid}.
+	 */
+	updateFilterConfig: (id: string, partialConfig: FilterConfigUpdate<T>) => void;
+	/** Looks up a filter's full config by `id`. `undefined` if no such filter exists. */
+	getFilter: (id: string) => FilterConfig<T> | undefined;
+	/** Just a filter's `value`, by `id`. `undefined` if no such filter exists. */
 	getFilterValue: (id: string) => unknown;
+	/** Sugar for `updateFilterConfig(id, { value })` - updates only a filter's value, leaving its type/operator/other options untouched. */
 	updateFilterValue: (id: string, value: unknown) => void;
+	/** Whether a filter (by `id`) currently participates in filtering. `false` for a nonexistent `id`, same as an explicitly inactive one. */
 	isFilterActive: (id: string) => boolean;
 }
-export declare function useFilter<T>(data?: T[], initialFilters?: FilterState<T>): UseFilterReturn<T>;
-export interface FuzzySearchOptions {
-	threshold?: number;
-	caseSensitive?: boolean;
-	matchStrategy?: "any" | "all";
-	exactPhraseBonus?: boolean;
-}
-export interface IndexedToken {
-	text: string;
-	weight: number;
-}
-export interface FlatIndexedItem<T> {
-	item: T;
-	index: number;
-	tokens: IndexedToken[];
-	combinedFlatText: string;
-}
-export interface ScoredItem<T> {
-	item: T;
-	score: number;
-	index: number;
-}
-export type UseFuzzySearchFields<T> = {
-	field: Extract<keyof T, string>;
-	weight: number;
-}[];
-export type UseFuzzySearchReturn<T> = T[];
-export declare function useFuzzySearch<T>(data: T[], query: string, fields: UseFuzzySearchFields<T>, options?: FuzzySearchOptions): UseFuzzySearchReturn<T>;
+/**
+ * Filters an array against one or more configured conditions - text
+ * matching, numeric/date comparisons and ranges, boolean/select/multiselect
+ * matching, or a fully custom predicate.
+ *
+ * @remarks
+ * - **Every active filter is AND-combined** - an item must satisfy all of
+ *   them to be included. There's no built-in OR-across-filters; use a
+ *   `custom` filter for that if needed.
+ * - **Missing/incomparable data always excludes the item**, uniformly
+ *   across every built-in operator - including the "negative" ones like
+ *   `notContains`/`notEquals`/`notIn`. A row with no value for the field is
+ *   treated as "unknown," never as a confident non-match. See
+ *   `FILTER_STRATEGIES`'s file-level `@remarks` for the full reasoning.
+ * - **Validation is dev/prod-split**, same convention as this library's
+ *   other hooks: an unknown `type`/`operator` combination, or a `custom`
+ *   filter missing its `compare` function, throws immediately in
+ *   development, but is silently excluded (that filter matches nothing) in
+ *   production.
+ * - **`field` falls back to `id`** when omitted - so a filter whose `id`
+ *   already matches the data's field name doesn't need `field` set
+ *   separately.
+ * - **Id lookups are O(1)**, backed by a `Map` built once per `filters`
+ *   change, not a linear scan per call.
+ *
+ * @typeParam T - The type of each item in `data`.
+ * @param data - The items to filter. Defaults to `[]`.
+ * @param initialFilters - Filters applied at mount. Defaults to `[]` (no filtering).
+ * @param options - See {@link UseFilterOptions}.
+ * @returns The filtered items and the current filter state, plus the
+ * actions to change it. See {@link UseFilterReturn}.
+ *
+ * @example
+ * ```tsx
+ * const { filteredItems, upsertFilter } = useFilter(products, [
+ *   { id: "category", type: "select", operator: "equals", value: "Books" },
+ * ]);
+ *
+ * upsertFilter({
+ *   id: "price",
+ *   type: "number",
+ *   operator: "between",
+ *   value: { min: 10, max: 50 },
+ * });
+ * ```
+ */
+export declare function useFilter<T>(data?: T[], initialFilters?: FilterState<T>, options?: UseFilterOptions): UseFilterReturn<T>;
+/** Bucket granularity for a `date`-type group level - see {@link GroupByDateLevel.bucket}. */
+export type DateBucketGranularity = "day" | "month" | "year";
+/**
+ * Groups by a field's raw value.
+ * @remarks If the resolved value is an array (e.g. a `tags` field), the
+ * item fans out into a separate group per element instead of being
+ * String()-coerced into one combined key - see {@link useGrouping}'s
+ * `@remarks` for details.
+ */
+export type GroupByFieldLevel = {
+	type: "field";
+	/** Dot-separated path into each item, e.g. `"address.city"`. */
+	field: string;
+};
+/** Groups by a `Date`-valued field, bucketed to day/month/year rather than exact timestamp - avoids one group per unique millisecond. */
+export type GroupByDateLevel = {
+	type: "date";
+	/** Dot-separated path into each item. */
+	field: string;
+	/**
+	 * Bucket granularity.
+	 * @defaultValue `"day"`
+	 */
+	bucket?: DateBucketGranularity;
+};
+/** Groups by a caller-supplied key function - for keys that can't be expressed as a plain field path (computed buckets, merging otherwise-distinct values into one group, etc.). */
+export type GroupByCustomLevel<T> = {
+	type: "custom";
+	/** Optional; used only to identify this level in dev warnings. */
+	id?: string;
+	/**
+	 * Computes this item's group key(s).
+	 * @remarks Return an array to fan the item out into multiple groups at
+	 * this level, mirroring array-valued {@link GroupByFieldLevel}s.
+	 * `null`/`undefined` places the item in the Unknown bucket. Throwing,
+	 * or returning anything other than `string | string[] | null | undefined`,
+	 * is treated as level misconfiguration - see {@link useGrouping}'s
+	 * `@remarks`.
+	 */
+	getKey: (item: T) => string | string[] | null | undefined;
+};
+/** A single grouping level - a plain string is shorthand for `{ type: "field", field: theString }`. */
+export type GroupByLevel<T> = string | GroupByFieldLevel | GroupByDateLevel | GroupByCustomLevel<T>;
+/** Same union as {@link GroupByLevel} with the string shorthand already expanded - what {@link useGrouping} stores internally and returns via `activeGroupBy`. */
+export type NormalizedGroupByLevel<T> = GroupByFieldLevel | GroupByDateLevel | GroupByCustomLevel<T>;
+/** A single group, as produced by {@link useGrouping}'s `groupedArray`. */
 export interface Group<T> {
+	/** Stable identifier for this group - e.g. the field's stringified value, or a date bucket like `"2026-08"`. Unique among sibling groups at the same level. */
 	key: string;
+	/** Human-readable display text. Usually equal to `key`, except for date buckets (e.g. key `"2026-08"`, label `"August 2026"`). */
+	label: string;
+	/** ALL items under this group, flattened across any deeper levels. */
 	items: T[];
+	/** Present only when there's another grouping level below this one. */
+	subGroups?: Group<T>[];
+}
+/** Options for {@link useGrouping}. */
+export interface UseGroupingOptions {
+	/**
+	 * Defers the grouping recomputation (via `useDeferredValue`) so changing
+	 * `activeGroupBy` doesn't block a more urgent update, e.g. the UI
+	 * interaction that triggered the change. Only `activeGroupBy` is
+	 * deferred - `items` is not.
+	 *
+	 * @defaultValue `false`
+	 */
+	defer?: boolean;
+	/**
+	 * Display label for the synthetic bucket holding items whose value at a
+	 * given level is missing, blank, or otherwise unresolvable.
+	 *
+	 * @defaultValue `"Unknown"`
+	 */
+	unknownGroupLabel?: string;
+	/**
+	 * Display label for the single synthetic group returned when
+	 * `activeGroupBy` is empty (no grouping applied).
+	 *
+	 * @defaultValue `"Ungrouped"`
+	 */
+	ungroupedGroupLabel?: string;
 }
+/** Return value of {@link useGrouping}. */
 export interface UseGroupingReturn<T> {
-	groupedRecord: Record<string, T[]>;
+	/** All groups, hierarchically - top-level groups from `activeGroupBy[0]`, each optionally holding `subGroups` from deeper levels. Render this for anything beyond a single flat level. */
 	groupedArray: Group<T>[];
+	/** Top-level groups only, flattened -- Record<key, items>. For deeper
+	 * levels, traverse a group's `subGroups` directly. */
+	groupedRecord: Record<string, T[]>;
+	/** Top-level group keys only, in the same order as `groupedArray`. */
 	groupKeys: string[];
+	/** Count of top-level groups only - `groupKeys.length`. */
 	totalGroups: number;
-	activeGroupBy: string | undefined;
-	changeGroupBy: (newField: string) => void;
+	/** The currently-applied grouping levels, normalized (string shorthand already expanded). Empty when no grouping is applied. */
+	activeGroupBy: NormalizedGroupByLevel<T>[];
+	/** `activeGroupBy.length > 0`. */
+	hasActiveGrouping: boolean;
+	/** The actual label in use for the "missing/unresolvable value" bucket - reflects `options.unknownGroupLabel` if customized, otherwise the default. Compare a group's `key` against this rather than hardcoding `"Unknown"`. */
+	unknownGroupKey: string;
+	/** The actual label in use for the "no grouping applied" bucket - reflects `options.ungroupedGroupLabel` if customized. Compare a group's `key` against this rather than hardcoding `"Ungrouped"`. */
+	ungroupedGroupKey: string;
+	/**
+	 * Replaces `activeGroupBy` with one level or an array of levels (for
+	 * hierarchical grouping - order determines nesting, `newGroupBy[0]`
+	 * becomes the top level).
+	 * @remarks A malformed level (missing `field`, non-function `getKey`,
+	 * etc.) is rejected - see {@link useGrouping}'s `@remarks`.
+	 */
+	changeGroupBy: (newGroupBy: GroupByLevel<T> | GroupByLevel<T>[]) => void;
+	/** Clears `activeGroupBy` entirely - equivalent to `changeGroupBy([])`. */
 	clearGrouping: () => void;
+	/** Restores `activeGroupBy` to the value passed as `initialGroupBy` at mount. Later changes to that argument have no effect - the reset target is frozen at mount. */
 	resetGrouping: () => void;
+	/** Looks up a single top-level group by its `key`. `undefined` if no such group exists.
+	 * @remarks Top-level lookup only, matching `groupedRecord`'s scope - use `groupedArray`/`subGroups` directly for a nested group. */
+	getGroup: (groupKey: string) => Group<T> | undefined;
+	/** `getGroup(groupKey)?.items ?? []` - the items in a top-level group, or an empty array if it doesn't exist. */
 	getGroupItems: (groupKey: string) => T[];
 }
-export declare function useGrouping<T = unknown>(options?: {
-	items?: T[];
-	initialGroupBy?: string;
-}): UseGroupingReturn<T>;
+/**
+ * Partitions an array into groups by one or more field values, date
+ * buckets, or a custom key function - single-level or hierarchical
+ * (subgroups within groups).
+ *
+ * @remarks
+ * - **Fan-out, not partitioning.** If a level's resolved value for an item
+ *   is an array (e.g. a `tags` field, or a `custom` level's `getKey`
+ *   returning multiple keys), the item is placed in *every* matching group
+ *   at that level, not just one. Summed item counts across sibling groups
+ *   can therefore exceed the original array length - this reflects genuine
+ *   multi-group membership, not a bug.
+ * - **Two distinct synthetic buckets**, both customizable via
+ *   {@link UseGroupingOptions}: `unknownGroupLabel` (default `"Unknown"`)
+ *   for items whose value at a level is missing, blank, or otherwise
+ *   unresolvable; `ungroupedGroupLabel` (default `"Ungrouped"`) for the
+ *   single group returned when no grouping is applied at all. The actual
+ *   labels in use are returned as `unknownGroupKey`/`ungroupedGroupKey` -
+ *   compare against those rather than hardcoding the default strings, in
+ *   case they've been customized.
+ * - **Validation is dev/prod-split**, same convention as this library's
+ *   other hooks: a malformed level (missing/empty `field`, a non-function
+ *   `getKey`, an invalid `bucket`) throws immediately in development, but
+ *   is rejected silently (falling back to the previous/empty grouping) in
+ *   production. A `custom` level's `getKey` throwing, or returning
+ *   something other than `string | string[] | null | undefined`, follows
+ *   the same split - see {@link GroupByCustomLevel.getKey}.
+ * - **`groupedRecord`/`groupKeys`/`totalGroups`/`getGroup`/`getGroupItems`
+ *   are all top-level only** - for anything below the first grouping
+ *   level, traverse a `Group`'s `subGroups` directly via `groupedArray`.
+ * - Order of top-level (and each nested level's) groups follows first
+ *   appearance in `items`, not any particular sort - re-sort `groupedArray`
+ *   yourself if a specific order is needed.
+ *
+ * @typeParam T - The type of each item in `data`.
+ * @param data - The items to group. Defaults to `[]`.
+ * @param initialGroupBy - Grouping level(s) applied at mount. Omit for no
+ * initial grouping.
+ * @param options - See {@link UseGroupingOptions}.
+ * @returns The current grouping and the actions to change it. See
+ * {@link UseGroupingReturn}.
+ *
+ * @example
+ * Single-level, by a plain field:
+ * ```tsx
+ * const { groupedArray } = useGrouping(users, "department");
+ * // groupedArray: [{ key: "Engineering", items: [...] }, { key: "Sales", items: [...] }, ...]
+ * ```
+ *
+ * @example
+ * Hierarchical, by department then a date bucket:
+ * ```tsx
+ * const { groupedArray, changeGroupBy } = useGrouping(orders);
+ *
+ * changeGroupBy([
+ *   "region",
+ *   { type: "date", field: "placedAt", bucket: "month" },
+ * ]);
+ * // groupedArray: [{ key: "EMEA", items: [...], subGroups: [{ key: "2026-08", ... }] }, ...]
+ * ```
+ */
+export declare function useGrouping<T = unknown>(data?: T[], initialGroupBy?: GroupByLevel<T> | GroupByLevel<T>[], options?: UseGroupingOptions): UseGroupingReturn<T>;
 export type SelectionId = string | number;
-export interface UseMultipleSelectionReturn<T> {
-	selectedIds: SelectionId[];
+/**
+ * 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>;
-export interface UseOrderReturn<T> {
-	orderedItems: T[];
-	moveUp: (index: number) => void;
-	moveDown: (index: number) => void;
-	canMoveUp: (index: number) => boolean;
-	canMoveDown: (index: number) => boolean;
-	moveToTop: (index: number) => void;
-	moveToBottom: (index: number) => void;
-	move: (fromIndex: number, toIndex: number) => void;
-	swap: (indexA: number, indexB: number) => void;
+/**
+ * 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>;
+/**
+ * The shape of every `target` parameter across {@link UseOrderReturn}'s
+ * methods - a plain array index when no `field` is configured, or either an
+ * index *or* a full item once one is (letting callers resolve an item's
+ * current position for themselves instead of tracking indices by hand).
+ *
+ * @remarks
+ * Deliberately gated behind `WithField` rather than always allowing `T`:
+ * `useOrder`'s base (no-`field`) overload can be called with `T = number`
+ * (ordering a plain array of numbers), where allowing an item argument too
+ * would make a bare `number` genuinely ambiguous - "index `5`" or "the item
+ * `5`"? Restricting item-based targeting to the `field`-configured overload
+ * (see {@link UseOrderFieldOptions}) sidesteps that ambiguity entirely,
+ * since `field` only makes sense for object items in the first place.
+ *
+ * @typeParam T - The item shape.
+ * @typeParam WithField - Whether `field` was configured - see {@link UseOrderFieldOptions}.
+ */
+export type OrderTarget<T, WithField extends boolean> = WithField extends true ? number | T : number;
+/**
+ * Options shared by both {@link useOrder} overloads, with or without `field`
+ * configured.
+ *
+ * @typeParam T - The item shape.
+ */
+export interface UseOrderBaseOptions<T> {
+	/**
+	 * Marks an item as un-movable and un-displaceable - see
+	 * {@link UseOrderReturn} for exactly which operations this blocks, and
+	 * how.
+	 *
+	 * @param item - The item to check.
+	 * @param index - That item's current index.
+	 * @returns `true` if `item` should be locked in place.
+	 */
+	isDisabled?: (item: T, index: number) => boolean;
+}
+/**
+ * Options for the `field`-configured overload of {@link useOrder}, which
+ * additionally accepts full items (not just indices) as move targets.
+ *
+ * @typeParam T - The item shape.
+ */
+export interface UseOrderFieldOptions<T> extends UseOrderBaseOptions<T> {
+	/**
+	 * A dot-path into `T`, used to resolve an item's id whenever a target is
+	 * given as an item rather than a raw index - see {@link OrderTarget}.
+	 */
+	field: Path<T> | (string & {});
+}
+/**
+ * Return value of {@link useOrder}.
+ *
+ * @typeParam T - The item shape.
+ * @typeParam WithField - Whether `field` was configured - see {@link OrderTarget}.
+ */
+export interface UseOrderReturn<T, WithField extends boolean = false> {
+	/** The items in their current order. */
+	orderedItems: readonly T[];
+	/**
+	 * Moves the item at `target` one position earlier (toward index `0`).
+	 * @remarks No-ops at the start of the list, or if `target`'s item or the item before it is disabled.
+	 */
+	movePrevious: (target: OrderTarget<T, WithField>) => void;
+	/**
+	 * Moves the item at `target` one position later (toward the end).
+	 * @remarks No-ops at the end of the list, or if `target`'s item or the item after it is disabled.
+	 */
+	moveNext: (target: OrderTarget<T, WithField>) => void;
+	/** Whether {@link UseOrderReturn.movePrevious} would currently have an effect for `target`. */
+	canMovePrevious: (target: OrderTarget<T, WithField>) => boolean;
+	/** Whether {@link UseOrderReturn.moveNext} would currently have an effect for `target`. */
+	canMoveNext: (target: OrderTarget<T, WithField>) => boolean;
+	/**
+	 * Moves the item at `target` to the very start of the list.
+	 * @remarks No-ops if it's already first, or if it's disabled. Items it moves past are shifted by one slot but not themselves checked - see {@link useOrder}'s remarks.
+	 */
+	moveToStart: (target: OrderTarget<T, WithField>) => void;
+	/**
+	 * Moves the item at `target` to the very end of the list.
+	 * @remarks No-ops if it's already last, or if it's disabled. Items it moves past are shifted by one slot but not themselves checked - see {@link useOrder}'s remarks.
+	 */
+	moveToEnd: (target: OrderTarget<T, WithField>) => void;
+	/**
+	 * Moves the item at `from` to the position at `to`, shifting everything
+	 * in between by one slot.
+	 * @remarks No-ops if `from` and `to` resolve to the same index, or if the item at `from` is disabled. Items shifted in between are not themselves checked - see {@link useOrder}'s remarks.
+	 */
+	move: (from: OrderTarget<T, WithField>, to: OrderTarget<T, WithField>) => void;
+	/**
+	 * Exchanges the positions of the items at `a` and `b`.
+	 * @remarks No-ops if `a` and `b` resolve to the same index, or if either item is disabled.
+	 */
+	swap: (a: OrderTarget<T, WithField>, b: OrderTarget<T, WithField>) => void;
+	/** Restores the order to the value `initialItems` had at mount - see {@link useOrder}'s remarks. */
 	resetOrder: () => void;
-	replaceOrder: (newOrderedItems: T[]) => void;
+	/** Replaces the entire order with exactly these items. */
+	replaceOrder: (newOrderedItems: readonly T[]) => void;
 }
-export declare function useOrder<T>(initialItems?: T[]): UseOrderReturn<T>;
+/**
+ * Manages the order of a list of items - drag-to-reorder UIs, "move
+ * up"/"move down" controls, manual sort overrides layered on top of a base
+ * sort.
+ *
+ * @remarks
+ * - Uncontrolled only for now - controlled mode is planned separately and
+ *   will be added without breaking this signature.
+ * - SSR-safe: performs no DOM/window access; `initialItems` 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.
+ * - Two overloads, picked by whether `field` is configured: without it,
+ *   every method's `target` parameter is a plain `number` index; with it,
+ *   `target` also accepts a full item, resolved to its current index via
+ *   `field`. See {@link OrderTarget} for why this is gated behind `field`
+ *   rather than always allowed.
+ * - `isDisabled` blocks differently depending on the operation. For the
+ *   pairwise operations (`movePrevious`, `moveNext`, `swap`), *both* items
+ *   involved must be movable, since both change position. For the
+ *   repositioning operations (`moveToStart`, `moveToEnd`, `move`), only the
+ *   item being moved is checked - items it displaces shift by one slot but
+ *   are never asked to swap places, so their own `isDisabled` state isn't
+ *   consulted for the move to proceed.
+ * - `resetOrder` restores the value `initialItems` had at mount, not
+ *   whatever it is on the current render - a later change to the
+ *   `initialItems` prop doesn't retroactively change what `resetOrder`
+ *   restores to.
+ *
+ * @typeParam T - The item shape.
+ * @param initialItems - The items to manage, in their starting order.
+ * @param options - See {@link UseOrderBaseOptions} / {@link UseOrderFieldOptions}.
+ * @returns The current order and the actions to change it. See {@link UseOrderReturn}.
+ *
+ * @example
+ * Index-only:
+ * ```tsx
+ * const { orderedItems, movePrevious, moveNext } = useOrder(["a", "b", "c"]);
+ * ```
+ *
+ * @example
+ * With `field`, so items themselves can be passed as move targets:
+ * ```tsx
+ * interface Row { id: string; label: string }
+ * const { orderedItems, movePrevious } = useOrder<Row>(rows, { field: "id" });
+ * // movePrevious(rows[2]) works directly - no manual index lookup needed
+ * ```
+ */
+export declare function useOrder<T extends Record<string, unknown>>(initialItems: readonly T[] | undefined, options: UseOrderFieldOptions<T>): UseOrderReturn<T, true>;
+export declare function useOrder<T>(initialItems?: readonly T[], options?: UseOrderBaseOptions<T>): UseOrderReturn<T, false>;
+/** Return value of {@link usePagination}. */
 export interface UsePaginationReturn<T> {
+	/** The items for the current page - a slice of `data`, `pageSize` items long (fewer on the last page if `totalCount` doesn't divide evenly). */
 	pageItems: T[];
+	/**
+	 * Current page, 1-based.
+	 * @remarks Always clamped into `[1, totalPages]` for display, even if
+	 * the underlying position becomes momentarily out of range (e.g. `data`
+	 * shrinks). The clamp is display-only - see the `currentPageIndex` note
+	 * in the implementation for why the real position isn't lost.
+	 */
+	pageNumber: number;
+	/** Items per page. */
 	pageSize: number;
-	pageIndex: number;
+	/** `Math.max(1, Math.ceil(totalCount / pageSize))` - always at least `1`, even for an empty `data`. */
 	totalPages: number;
-	canPrevious: boolean;
-	canNext: boolean;
+	/** `data.length` (after the array-safety check) - the un-paginated item count. */
+	totalCount: number;
+	/** 1-based index of the first item on the current page, for a "Showing X-Y of Z" display. `0` when `totalCount` is `0`. */
+	startIndex: number;
+	/** 1-based index of the last item on the current page. `0` when `totalCount` is `0`. */
+	endIndex: number;
+	/** Whether {@link UsePaginationReturn.previousPage} would move anywhere. */
+	canPreviousPage: boolean;
+	/** Whether {@link UsePaginationReturn.nextPage} would move anywhere. */
+	canNextPage: boolean;
+	/** Moves to the next page, if any. No-op (not a warning) on the last page - this is routine UI usage, not caller error. */
 	nextPage: () => void;
+	/** Moves to the previous page, if any. No-op on the first page. */
 	previousPage: () => void;
+	/** Jumps to page `1`. */
 	goToFirstPage: () => void;
+	/** Jumps to the last page. */
 	goToLastPage: () => void;
-	goToPage: (newPageIndex: number) => void;
+	/**
+	 * Jumps to a specific page.
+	 * @remarks A well-formed but out-of-range page (e.g. `999` on a
+	 * 5-page list) is clamped to the nearest valid page, not rejected -
+	 * only a malformed value (non-integer, `< 1`, `NaN`, etc.) is treated
+	 * as caller error. See {@link isPositiveInteger}.
+	 */
+	goToPage: (newPageNumber: number) => void;
+	/**
+	 * Changes `pageSize`.
+	 * @remarks `pageNumber` is left untouched here - it re-bounds itself
+	 * automatically against the new `totalPages` on the next render.
+	 */
 	changePageSize: (newPageSize: number) => void;
-	resetPageIndex: () => void;
+	/** Restores `pageNumber` to the value passed as `initialPageNumber` at mount. Later changes to that argument have no effect - the reset target is frozen at mount, same as `pageSize`/full pagination reset below. */
+	resetPageNumber: () => void;
+	/** Restores `pageSize` to the value passed as `initialPageSize` at mount. */
 	resetPageSize: () => void;
+	/** Restores both `pageNumber` and `pageSize` to their mount-time initial values, in one update. */
 	resetPagination: () => void;
 }
-export declare function usePagination<T>(data: T[] | undefined, initialPageSize: number, initialPageIndex?: number): UsePaginationReturn<T>;
-export interface UseSingleSelectionReturn {
-	selectedId: SelectionId | undefined;
+/**
+ * Paginates an array client-side - slices `data` into pages and exposes the
+ * navigation state and actions to move between them.
+ *
+ * @remarks
+ * - **Validation is dev/prod-split**: passing a malformed page number or
+ *   page size (non-integer, `< 1`, `NaN`, etc.) to the constructor or any
+ *   mutator throws immediately in development (surfacing the bug fast), but
+ *   silently falls back to the last valid value in production, rather than
+ *   crashing a real user's session over a caller mistake. See
+ *   {@link isPositiveInteger}.
+ * - **Out-of-range is different from malformed.** `goToPage(999)` on a
+ *   5-page list isn't an error - it's clamped to the last page. Only
+ *   structurally invalid input (see above) is treated as a mistake.
+ * - **`pageNumber` is 1-based** in this public API; page count/index math
+ *   is kept 0-based internally.
+ * - **Reset targets are frozen at mount.** `resetPageNumber`/`resetPageSize`/
+ *   `resetPagination` always restore the `initialPageNumber`/`initialPageSize`
+ *   values as they were on the very first render - passing different values
+ *   to `usePagination` on a later render does not change what reset
+ *   restores to.
+ * - **No manual/server-side pagination mode** - `data` is always assumed to
+ *   be the complete, un-paginated dataset, sliced client-side.
+ *
+ * @typeParam T - The type of each item in `data`.
+ * @param data - The full, un-paginated array. Defaults to `[]`.
+ * @param initialPageSize - Items per page at mount.
+ * @defaultValue initialPageSize `10`
+ * @param initialPageNumber - Starting page (1-based) at mount.
+ * @defaultValue initialPageNumber `1`
+ * @returns The current page's items, position, and the actions to
+ * navigate/resize/reset. See {@link UsePaginationReturn}.
+ *
+ * @example
+ * ```tsx
+ * const { pageItems, pageNumber, totalPages, nextPage, previousPage } =
+ *   usePagination(rows, 20);
+ *
+ * return (
+ *   <>
+ *     {pageItems.map((row) => <Row key={row.id} {...row} />)}
+ *     <button onClick={previousPage}>Prev</button>
+ *     <span>{pageNumber} / {totalPages}</span>
+ *     <button onClick={nextPage}>Next</button>
+ *   </>
+ * );
+ * ```
+ */
+export declare function usePagination<T>(data?: T[], initialPageSize?: number, initialPageNumber?: number): UsePaginationReturn<T>;
+/** The id type `usePin` operates on by default - a raw `string` or `number`. */
+export type PinId = string | number;
+/**
+ * Options for {@link usePin}, in either of its two modes - id-only (`T`
+ * defaults to `TId`) or object mode (`T` is a distinct item shape, `TId`
+ * its resolved id type).
+ *
+ * @remarks
+ * The conditional shape is what makes `field` required in object mode and
+ * disallowed in id-only mode, entirely at the type level - see
+ * {@link usePin}'s remarks for why.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export type UsePinOptions<T = PinId, TId extends PinId = PinId> = T extends TId ? {
+	/** The full list of pinnable items - backs `pinnedItems`/`unpinnedItems`, and is the default target for `pinAll` when it's called with no argument. */
+	items?: readonly T[];
+	/** Ids pinned from the start - frozen at mount, see {@link usePin}'s remarks. */
+	initialPinnedIds?: readonly TId[];
+	/** The maximum number of ids that can be pinned at once. `undefined` means unlimited. */
+	maxPins?: number;
+} : {
+	/** The full list of pinnable items - backs `pinnedItems`/`unpinnedItems`, and is the default target for `pinAll` when it's called with no argument. */
+	items: readonly T[];
+	/** A dot-path into `T`, used to resolve an item's id whenever a target is given as an item rather than a raw id. */
+	field: Path<T> | (string & {});
+	/** Ids pinned from the start - frozen at mount, see {@link usePin}'s remarks. */
+	initialPinnedIds?: readonly TId[];
+	/** The maximum number of ids that can be pinned at once. `undefined` means unlimited. */
+	maxPins?: number;
+};
+/**
+ * Return value of {@link usePin}.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export interface UsePinReturn<T = PinId, TId extends PinId = PinId> {
+	/** The currently pinned ids. */
+	pinnedIds: readonly TId[];
+	/** The subset of `items` that are currently pinned. */
+	pinnedItems: readonly T[];
+	/** The subset of `items` that are not currently pinned. */
+	unpinnedItems: readonly T[];
+	/** `pinnedIds.length`. */
+	pinnedCount: number;
+	/** Whether anything at all is pinned. */
+	hasPins: boolean;
+	/** Whether `pinnedCount` has reached `maxPins`. */
+	isAtMaxLimit: boolean;
+	/** The current pin limit - `Number.MAX_SAFE_INTEGER` when unset/unlimited. */
+	maxPins: number;
+	/**
+	 * Pins `itemOrId`.
+	 * @remarks No-ops if it's already pinned, or if `maxPins` has been reached.
+	 */
+	pin: (itemOrId: TId | T) => void;
+	/** Unpins `itemOrId`. Always allowed, even past `maxPins` - removal never needs to check the limit. */
+	unpin: (itemOrId: TId | T) => void;
+	/**
+	 * Pins `itemOrId` if it isn't pinned, unpins it if it is.
+	 * @remarks The pin-direction is blocked once `maxPins` is reached; the unpin-direction never is.
+	 */
+	togglePin: (itemOrId: TId | T) => void;
+	/** Whether `itemOrId` is currently pinned. */
+	isPinned: (itemOrId: TId | T) => boolean;
+	/** Whether {@link UsePinReturn.pin} would currently have an effect for `itemOrId` - `true` if it's already pinned (a no-op call still "succeeds") or there's room under `maxPins`. */
+	canPin: (itemOrId: TId | T) => boolean;
+	/** Unpins everything. */
+	clearPins: () => void;
+	/** Restores the pinned set to the value `initialPinnedIds` had at mount - see {@link usePin}'s remarks. */
+	resetPins: () => void;
+	/** Replaces the entire pinned set with exactly these ids/items, truncated to the first `maxPins` if it exceeds the current limit. */
+	replacePins: (newPinnedItems: readonly TId[] | readonly T[]) => void;
+	/**
+	 * Pins every id/item given, or every item in `items` if called with no
+	 * argument.
+	 * @remarks If `maxPins` is reached partway through, whatever already fit stays pinned rather than the whole call being rejected.
+	 */
+	pinAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/** Unpins every id/item given, or unpins everything if called with no argument. */
+	unpinAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/** Changes `maxPins` to a new value. Does not retroactively unpin anything already over the new limit. */
+	changeMaxPins: (newMaxPins: number) => void;
+	/** Restores `maxPins` to the value it had at mount. */
+	resetMaxPins: () => void;
+}
+/**
+ * Manages a pinned/starred subset of a list - pinned rows in a table,
+ * favorited items, "keep at top" behavior.
+ *
+ * @remarks
+ * - Uncontrolled only for now - controlled mode is planned separately and
+ *   will be added without breaking this signature.
+ * - SSR-safe: performs no DOM/window access; `initialPinnedIds` 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.
+ * - Two modes, picked by whether `T` is assignable to `TId`: id-only
+ *   (default) - `itemOrId` parameters only ever receive raw ids, `field`
+ *   is disallowed; or object mode - `<Row, string>` plus a required
+ *   `field`, letting `itemOrId` parameters take a full item too. See
+ *   {@link UsePinOptions}.
+ * - `maxPins` truncation always keeps the *first* ids/items and warns in
+ *   dev about the rest - this applies at mount (`initialPinnedIds`),
+ *   `replacePins`, and `pinAll`.
+ * - `resetPins` and `resetMaxPins` are independent - resetting one doesn't
+ *   touch the other, and each restores exactly the value its own option
+ *   had at mount, not whatever it is on the current render.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ * @param options - See {@link UsePinOptions}.
+ * @returns The current pinned state and the actions to change it. See {@link UsePinReturn}.
+ *
+ * @example
+ * Id-only:
+ * ```tsx
+ * const { pinnedIds, pin, isPinned } = usePin({ initialPinnedIds: ["row-1"] });
+ * ```
+ *
+ * @example
+ * Object mode, with a pin limit:
+ * ```tsx
+ * interface Row { id: string; label: string }
+ * const { pinnedItems, pin, canPin } = usePin<Row, string>({
+ *   items: rows,
+ *   field: "id",
+ *   maxPins: 5,
+ * });
+ * ```
+ */
+export declare function usePin<T = PinId, TId extends PinId = PinId>(options?: UsePinOptions<T, TId>): UsePinReturn<T, TId>;
+/**
+ * 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>;
+/** The comparison strategy for a sort key - selects which built-in comparator is used, or `custom` for a caller-supplied one. */
 export type SortType = "numeric" | "alphabetical" | "alphanumeric" | "boolean" | "date" | "basic" | "custom";
+/**
+ * How a missing value (per each sort type's own definition of "missing" -
+ * e.g. non-numeric for `numeric`, unparseable for `date`) is positioned
+ * relative to present values.
+ *
+ * @remarks
+ * - `"first"`/`"last"` are **absolute positions** - they never flip with
+ *   sort direction, which is the entire reason to choose them over `-1`/`1`.
+ * - `-1`/`1` **simulate a real extreme value** (very small / very large
+ *   respectively) - unlike `"first"`/`"last"`, these DO flip with
+ *   direction, exactly as a genuine value at that extreme would.
+ *
+ * @defaultValue `"last"`
+ */
+export type SortUndefinedOption = "first" | "last" | -1 | 1;
+/** Options shared by every sort type, regardless of comparator. */
 export interface BaseSortOptions {
+	/**
+	 * Sort direction.
+	 * @defaultValue `false` (ascending)
+	 */
 	desc?: boolean;
+	/**
+	 * When set, `toggleSort` cycles asc -> desc -> asc, skipping the
+	 * "remove this sort key" step it would otherwise land on after desc.
+	 * @defaultValue `false`
+	 */
 	disableSortRemoval?: boolean;
+	/**
+	 * Flips the effective sort direction without changing `desc` itself -
+	 * useful for a column whose "natural" order is descending (e.g. a
+	 * priority field where higher should sort first by default).
+	 * @defaultValue `false`
+	 */
 	invertSorting?: boolean;
-	sortUndefined?: "first" | "last" | -1 | 1;
+	/** See {@link SortUndefinedOption}. */
+	sortUndefined?: SortUndefinedOption;
 }
+/** Fields common to every {@link SortConfig}, regardless of `type`. */
 export interface BaseSortConfig extends BaseSortOptions {
+	/** Unique identifier for this sort key - used for lookups (`getSort`, `getSortDirection`, etc.) and to distinguish sort keys in a multi-key `sorts` array. */
 	id: string;
+	/** Dot-separated path into each item, e.g. `"address.city"`. Falls back to `id` when omitted - so `id` alone is often enough if it already matches the field name. */
 	field?: string;
 }
+/**
+ * A single sort key's full configuration.
+ *
+ * @remarks
+ * Each `type` has its own dedicated union arm (rather than several type
+ * literals sharing one arm) so that {@link SortOptionsForType} - which
+ * extracts a single type's own options via `Extract<SortConfig, { type: T }>`
+ * - resolves correctly per type. Grouping literals under one arm would
+ * make that extraction silently fail for every type in the group.
+ */
 export type SortConfig = BaseSortConfig & ({
-	type: "numeric" | "boolean" | "date" | "basic";
+	type: "numeric";
+} | {
+	type: "boolean";
+} | {
+	type: "date";
+	dateGranularity?: "day" | "instant";
 } | {
-	type: "alphabetical" | "alphanumeric";
+	type: "basic";
+} | {
+	type: "alphabetical";
+	caseSensitive?: boolean;
+} | {
+	type: "alphanumeric";
 	caseSensitive?: boolean;
 } | {
 	type: "custom";
 	compare: (a: unknown, b: unknown) => number;
 });
+/** All active sort keys, in priority order - `sorts[0]` is the primary sort, later entries only break ties left by earlier ones. */
 export type SortState = SortConfig[];
+/**
+ * A single sort type's own options, with `id`/`type`/`field` (which every
+ * type shares, and which `toggleSort` already takes as separate arguments)
+ * stripped out. Used to type `toggleSort`'s `options` parameter, narrowed
+ * to only the options relevant to the specific `type` being toggled.
+ */
 export type SortOptionsForType<T extends SortType> = Omit<Extract<SortConfig, {
 	type: T;
 }>, "id" | "type" | "field">;
+/**
+ * The update payload type for `updateSortConfig`.
+ *
+ * @remarks
+ * Preserves per-type shape correlation at the type level - e.g. TypeScript
+ * will reject `{ dateGranularity: "day" }` paired with a `type` that isn't
+ * `"date"`. This is best-effort compile-time guidance, not a full
+ * guarantee: a *merge* of an update into an existing config can still land
+ * on a structurally invalid combination that the type system alone can't
+ * catch (partial updates flatten across a union in ways whole-object
+ * construction doesn't). {@link isSortConfigShapeValid}, run on the merged
+ * result inside `applySortUpdate`, is the actual runtime backstop.
+ */
+export type SortConfigUpdate = DistributivePartial<DistributiveOmit<SortConfig, "id">>;
+/** Options for {@link useSort}. */
+export interface UseSortOptions {
+	/**
+	 * Defers the sort recomputation (via `useDeferredValue`) so changing
+	 * `sorts` doesn't block a more urgent update. Only `sorts` is deferred -
+	 * `data` is not.
+	 * @defaultValue `false`
+	 */
+	defer?: boolean;
+}
+/** Return value of {@link useSort}. */
 export interface UseSortReturn<T> {
+	/** `data`, sorted by every entry in `sorts`, applied in priority order. Same reference as `data` (no copy, no sort) when `sorts` is empty. */
 	sortedItems: T[];
+	/** The currently-active sort keys, in priority order. */
 	sorts: SortState;
+	/** `sorts.length`. */
+	sortCount: number;
+	/** `sortCount > 0`. */
+	hasSorts: boolean;
+	/** Adds a new sort key, or replaces the existing one with the same `id`. */
 	upsertSorts: (sort: SortConfig) => void;
+	/** Removes one sort key by `id`, or several at once by passing an array of ids. */
 	removeSort: (id: string | string[]) => void;
+	/** Clears every sort key - equivalent to `replaceSorts([])`. */
 	clearSorts: () => void;
+	/** Restores `sorts` to the value passed as `initialSorts` at mount. Later changes to that argument have no effect - the reset target is frozen at mount. */
 	resetSorts: () => void;
+	/** Replaces the entire `sorts` array at once. */
 	replaceSorts: (sorts: SortState) => void;
+	/**
+	 * Cycles a sort key through asc -> desc -> (reset to asc, or remove
+	 * entirely) - the standard three-state table-header sort interaction.
+	 *
+	 * @remarks
+	 * - Whether the last step resets to asc or removes the sort key
+	 *   entirely depends on `disableSortRemoval` (checked on both the
+	 *   existing config and the newly-passed `options`).
+	 * - `options.multi` (`false` by default) controls whether toggling
+	 *   this key adds/updates it alongside any other active sort keys
+	 *   (`true`), or replaces the entire `sorts` array with just this one
+	 *   key (`false`) - the usual "click a column to sort by only that
+	 *   column, shift-click to add a secondary sort" pattern.
+	 * - `type` must be supplied on every call, even for an already-active
+	 *   sort key - this hook has no independent memory of a key's type
+	 *   beyond what's in `sorts` itself.
+	 */
 	toggleSort: <TType extends SortType>(id: string, type: TType, options?: SortOptionsForType<TType> & {
 		multi?: boolean;
 		field?: string;
 	}) => void;
+	/**
+	 * Partially updates an existing sort key's config by `id`.
+	 * @remarks An unknown `id`, or an update that would produce a
+	 * structurally invalid config for its `type`, is rejected - see
+	 * {@link isSortConfigShapeValid}.
+	 */
+	updateSortConfig: (id: string, partialConfig: SortConfigUpdate) => void;
+	/** Looks up a sort key's full config by `id`. `undefined` if no such key exists. */
+	getSort: (id: string) => SortConfig | undefined;
+	/** `"asc"`/`"desc"` for an active sort key, `undefined` if `id` isn't currently sorted. */
 	getSortDirection: (id: string) => "asc" | "desc" | undefined;
+	/** What `toggleSort(id, ...)` would transition `id` to next, without actually calling it - useful for rendering the right sort-direction icon before the user clicks. */
 	getNextSortingOrder: (id: string) => "asc" | "desc" | "none";
+	/** This sort key's 1-based priority among active sort keys (`1` = primary), or `undefined` if `id` isn't currently sorted. */
 	getSortIndex: (id: string) => number | undefined;
 }
-export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+/**
+ * Sorts an array by one or more keys - single-column or multi-column,
+ * priority determined by array order.
+ *
+ * @remarks
+ * - **Multi-key sort**: `sorts[0]` is the primary sort; later entries in
+ *   the array only break ties left unresolved by earlier ones - the same
+ *   convention as `Array.prototype.sort` with a compound comparator, or a
+ *   spreadsheet's "sort by, then by" dialog.
+ * - **Validation is dev/prod-split**, uniformly across every mutator that
+ *   can produce a structurally invalid config (`toggleSort`,
+ *   `updateSortConfig`), and across an unresolvable sort key encountered
+ *   during sorting itself (unknown `type`, or a `custom` sort missing its
+ *   `compare` function): throws immediately in development, but degrades
+ *   gracefully in production (an invalid mutation is rejected/no-op; an
+ *   unresolvable sort key at compute time is simply skipped, later keys
+ *   still apply).
+ * - **`sortUndefined`'s `"first"`/`"last"` are absolute positions**, never
+ *   affected by `desc`/`invertSorting`; `-1`/`1` simulate a real extreme
+ *   value and do flip with direction - see {@link SortUndefinedOption}.
+ * - **`resetSorts` is frozen at mount** - it restores `initialSorts` as it
+ *   was on the very first render, not whatever value that argument holds
+ *   on a later render.
+ * - **Id lookups are O(1)**, backed by a `Map` built once per `sorts`
+ *   change, not a linear scan per call - safe to call `getSort`/
+ *   `getSortDirection`/etc. once per rendered column header without a
+ *   performance concern.
+ *
+ * @typeParam T - The type of each item in `data`.
+ * @param data - The items to sort. Defaults to `[]`.
+ * @param initialSorts - Sort keys applied at mount. Defaults to `[]` (no sorting).
+ * @param options - See {@link UseSortOptions}.
+ * @returns The sorted items and the current sort state, plus the actions
+ * to change it. See {@link UseSortReturn}.
+ *
+ * @example
+ * Single column, via a table header click handler:
+ * ```tsx
+ * const { sortedItems, getSortDirection, toggleSort } = useSort(rows);
+ *
+ * <th onClick={() => toggleSort("name", "alphabetical")}>
+ *   Name {getSortDirection("name") === "asc" ? "▲" : "▼"}
+ * </th>
+ * ```
+ *
+ * @example
+ * Multi-key, set directly:
+ * ```tsx
+ * const { sortedItems, replaceSorts } = useSort(orders, [
+ *   { id: "status", type: "alphabetical" },
+ *   { id: "placedAt", type: "date", desc: true },
+ * ]);
+ * // sorted by status first; same-status orders sorted by placedAt, newest first
+ * ```
+ */
+export declare function useSort<T>(data?: T[], initialSorts?: SortState, options?: UseSortOptions): 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>;
+/** The id type `useVisibility` operates on by default - a raw `string` or `number`. */
+export type VisibilityId = string | number;
+/**
+ * Options for {@link useVisibility}, in either of its two modes - id-only
+ * (`T` defaults to `TId`) or object mode (`T` is a distinct item shape,
+ * `TId` its resolved id type).
+ *
+ * @remarks
+ * The conditional shape is what makes `field` required in object mode and
+ * disallowed in id-only mode, entirely at the type level - see
+ * {@link useVisibility}'s remarks for why.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export type UseVisibilityOptions<T = VisibilityId, TId extends VisibilityId = VisibilityId> = T extends TId ? {
+	/** The full list of items whose visibility is being tracked - backs `visibleItems`/`hiddenItems`, and is the default target for `showAll` when it's called with no argument. */
+	items?: readonly T[];
+	/** Ids visible from the start - frozen at mount, see {@link useVisibility}'s remarks. */
+	initialVisibleIds?: readonly TId[];
+} : {
+	/** The full list of items whose visibility is being tracked - backs `visibleItems`/`hiddenItems`, and is the default target for `showAll` when it's called with no argument. */
+	items: readonly T[];
+	/** A dot-path into `T`, used to resolve an item's id whenever a target is given as an item rather than a raw id. */
+	field: Path<T> | (string & {});
+	/** Ids visible from the start - frozen at mount, see {@link useVisibility}'s remarks. */
+	initialVisibleIds?: readonly TId[];
+};
+/**
+ * Return value of {@link useVisibility}.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ */
+export interface UseVisibilityReturn<T = VisibilityId, TId extends VisibilityId = VisibilityId> {
+	/** The currently visible ids. */
+	visibleIds: readonly TId[];
+	/** The subset of `items` that are currently visible. */
+	visibleItems: readonly T[];
+	/** The subset of `items` that are currently hidden. */
+	hiddenItems: readonly T[];
+	/** `visibleIds.length`. */
+	visibleCount: number;
+	/** `hiddenItems.length`. */
+	hiddenCount: number;
+	/** Whether anything at all is visible. */
+	hasVisible: boolean;
+	/** Whether `itemOrId` is currently visible. */
+	isVisible: (itemOrId: TId | T) => boolean;
+	/** Shows `itemOrId`. No-ops if it's already visible. */
+	show: (itemOrId: TId | T) => void;
+	/** Hides `itemOrId`. No-ops if it's already hidden. */
+	hide: (itemOrId: TId | T) => void;
+	/** Shows `itemOrId` if it's hidden, hides it if it's visible. */
+	toggleVisibility: (itemOrId: TId | T) => void;
+	/** Shows every id/item given, or every item in `items` if called with no argument. Adds to the current visible set rather than replacing it. */
+	showAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/**
+	 * Hides every id/item given, or hides everything if called with no
+	 * argument.
+	 * @remarks Unlike {@link UseVisibilityReturn.showAll}, "no argument" means a blanket clear, not "act on the hook's own `items`" - see {@link useVisibility}'s remarks.
+	 */
+	hideAll: (itemsArray?: readonly TId[] | readonly T[]) => void;
+	/** Restores the visible set to the value `initialVisibleIds` had at mount - see {@link useVisibility}'s remarks. */
+	resetVisibility: () => void;
+	/** Replaces the entire visible set with exactly these ids/items. */
+	replaceVisibility: (newVisibleItems: readonly TId[] | readonly T[]) => void;
+}
+/**
+ * Manages which item(s) in a list are visible - show/hide toggles, column
+ * visibility, filterable chip lists.
+ *
+ * @remarks
+ * - Uncontrolled only for now - controlled mode is planned separately and
+ *   will be added without breaking this signature.
+ * - SSR-safe: performs no DOM/window access; `initialVisibleIds` 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.
+ * - Two modes, picked by whether `T` is assignable to `TId`: id-only
+ *   (default) - `itemOrId` parameters only ever receive raw ids, `field`
+ *   is disallowed; or object mode - `<Row, string>` plus a required
+ *   `field`, letting `itemOrId` parameters take a full item too. See
+ *   {@link UseVisibilityOptions}.
+ * - `showAll`/`hideAll` intentionally differ in what "no argument" means:
+ *   `showAll()` acts on the hook's own `items` (additive - anything
+ *   already visible but no longer in `items` is left alone), while
+ *   `hideAll()` is a blanket clear regardless of `items` (so a
+ *   previously-visible id that's since fallen out of `items` doesn't stay
+ *   visible forever). Passing an explicit array to either scopes it to
+ *   just that subset.
+ *
+ * @typeParam T - The item shape, or `TId` itself for id-only mode.
+ * @typeParam TId - The id type.
+ * @param options - See {@link UseVisibilityOptions}.
+ * @returns The current visibility state and the actions to change it. See {@link UseVisibilityReturn}.
+ *
+ * @example
+ * Id-only:
+ * ```tsx
+ * const { isVisible, toggleVisibility } = useVisibility({
+ *   initialVisibleIds: ["col-name", "col-email"],
+ * });
+ * ```
+ *
+ * @example
+ * Object mode:
+ * ```tsx
+ * interface Column { id: string; label: string }
+ * const { visibleItems, hide, showAll } = useVisibility<Column, string>({
+ *   items: columns,
+ *   field: "id",
+ * });
+ * ```
+ */
+export declare function useVisibility<T = VisibilityId, TId extends VisibilityId = VisibilityId>(options?: UseVisibilityOptions<T, TId>): UseVisibilityReturn<T, TId>;
+export interface FuzzySearchOptions {
+	threshold?: number;
+	caseSensitive?: boolean;
+	matchStrategy?: "any" | "all";
+	exactPhraseBonus?: boolean;
+}
+export interface IndexedToken {
+	text: string;
+	weight: number;
+}
+export interface FlatIndexedItem<T> {
+	item: T;
+	index: number;
+	tokens: IndexedToken[];
+	combinedFlatText: string;
+}
+export interface ScoredItem<T> {
+	item: T;
+	score: number;
+	index: number;
+}
 
 export {};