exsorted-react 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ink01101011
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# exsorted-react
+
+TypeScript-first React sorting hook powered by [exsorted](https://www.npmjs.com/package/exsorted).
+
+- React support: 18 and 19
+- Public API: useSortedList, singleKeyAccessors, and related public types
+- Exsorted resolution: uses peer version when available, otherwise falls back to bundled dependency
+
+## API Surface
+
+```ts
+import { singleKeyAccessors, useSortedList } from "exsorted-react";
+```
+
+## singleKeyAccessors
+
+Minimal helper for one-field sorting while keeping accessors required.
+
+```ts
+const sorted = useSortedList(products, {
+  accessors: singleKeyAccessors("price", (item: Product) => item.price),
+  initialKey: "price",
+});
+```
+
+## useSortedList
+
+```ts
+const result = useSortedList(items, options);
+```
+
+### Next.js SSR / RSC
+
+`useSortedList` is a client hook. In Next.js App Router, call it only in Client Components.
+
+```tsx
+"use client";
+
+import { useSortedList } from "exsorted-react";
+```
+
+`singleKeyAccessors` is a pure helper and can be called in server code, but it does not make
+`useSortedList` callable in Server Components.
+
+If external read-only state provides a key that is not present in `accessors`, the hook safely falls
+back to the first accessor key to avoid error-triggered re-render loops.
+
+### Modes
+
+- Standalone mode: pass accessors with optional initialKey and initialDirection
+- Controlled mode: pass sort controller object
+- Read-only state mode: pass state object
+
+### Options
+
+- accessors (required): map of key to value accessor
+- comparator (optional): comparator used for sorting
+- sorter (optional): custom compare-based exsorted sorter, default is mergeSort
+- initialKey and initialDirection (standalone mode only)
+- sort (controlled mode only)
+- state (read-only state mode only)
+
+### Sorter Compatibility
+
+sorter must match compare-based signature:
+
+```ts
+(arr, compareFn?) => arr;
+```
+
+Not supported because function interfaces differ:
+
+- exsorted/non-compare: countingSort, radixSort, bucketSort, pigeonholeSort
+- exsorted/standard: introSort
+
+### Return Value
+
+- items: visible items (sorted or original depending on mode/actions)
+- previousItems: previous visible snapshot
+- originalItems: input source reference
+- isSorting: transition pending state
+- isSorted: true when sorted view is active and not pending
+- sort, sortKey, direction: effective sort state
+- setSortKey, setDirection, toggleDirection, setSort, reset: sort controls
+- restoreOriginal, restoreSorted: view-mode controls
+
+## Examples
+
+### Standalone Mode
+
+```ts
+import { useSortedList } from "exsorted-react";
+import { quickSort } from "exsorted";
+
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  rating: number;
+};
+
+const sorted = useSortedList(products, {
+  accessors: {
+    name: (item: Product) => item.name,
+    price: (item: Product) => item.price,
+    rating: (item: Product) => item.rating,
+  },
+  sorter: quickSort,
+  initialKey: "price",
+});
+
+sorted.setSortKey("name");
+sorted.toggleDirection();
+```
+
+### Single-key Minimal Mode
+
+```ts
+import { singleKeyAccessors, useSortedList } from "exsorted-react";
+
+const sorted = useSortedList(products, {
+  accessors: singleKeyAccessors("price", (item: Product) => item.price),
+  initialKey: "price",
+});
+```
+
+### Controlled Mode
+
+```ts
+import { useState } from "react";
+import { useSortedList } from "exsorted-react";
+
+const [sort, setSort] = useState({ key: "name" as const, direction: "asc" as const });
+
+const sorted = useSortedList(products, {
+  accessors: {
+    name: (item: Product) => item.name,
+    price: (item: Product) => item.price,
+  },
+  sort: {
+    sort,
+    setSort,
+    reset: () => setSort({ key: "name", direction: "asc" }),
+  },
+});
+```
+
+### Read-only State Mode
+
+```ts
+const sorted = useSortedList(products, {
+  accessors: {
+    name: (item: Product) => item.name,
+    price: (item: Product) => item.price,
+  },
+  state: { key: "price", direction: "desc" },
+});
+```
+
+### Custom Comparator
+
+```ts
+const sorted = useSortedList(products, {
+  accessors: {
+    name: (item: Product) => item.name,
+    price: (item: Product) => item.price,
+  },
+  initialKey: "name",
+  comparator: (a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }),
+});
+```
+
+Tree-shaking note: import and pass only the sorter algorithm you need.

package/dist/index.cjs

@@ -0,0 +1,286 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  singleKeyAccessors: () => singleKeyAccessors,
+  useSortedList: () => useSortedList
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/useSortedList.ts
+var import_react2 = require("react");
+
+// src/hooks/useSortState.ts
+var import_react = require("react");
+var defaultGetNextDirection = (current) => current === "asc" ? "desc" : "asc";
+var resolveInitialKey = (options) => {
+  if ("keys" in options) {
+    if (options.initialKey !== void 0) {
+      return options.initialKey;
+    }
+    const firstKey = options.keys[0];
+    if (firstKey === void 0) {
+      throw new Error(
+        "useSortState expected at least one key in options.keys when initialKey is omitted."
+      );
+    }
+    return firstKey;
+  }
+  return options.initialKey;
+};
+function useSortState(options) {
+  const initialDirection = options.initialDirection ?? "asc";
+  const initialKey = (0, import_react.useMemo)(() => resolveInitialKey(options), [options]);
+  const initialSort = (0, import_react.useMemo)(
+    () => ({ key: initialKey, direction: initialDirection }),
+    [initialDirection, initialKey]
+  );
+  const [sort, setSort] = (0, import_react.useState)(initialSort);
+  const setSortKey = (0, import_react.useCallback)((nextKey) => {
+    setSort((previous) => ({ ...previous, key: nextKey }));
+  }, []);
+  const setDirection = (0, import_react.useCallback)((nextDirection) => {
+    setSort((previous) => ({ ...previous, direction: nextDirection }));
+  }, []);
+  const toggleDirection = (0, import_react.useCallback)(() => {
+    const getNextDirection = options.getNextDirection ?? defaultGetNextDirection;
+    setSort((previous) => ({
+      ...previous,
+      direction: getNextDirection(previous.direction)
+    }));
+  }, [options]);
+  const reset = (0, import_react.useCallback)(() => {
+    setSort(initialSort);
+  }, [initialSort]);
+  return {
+    sort,
+    sortKey: sort.key,
+    direction: sort.direction,
+    setSortKey,
+    setDirection,
+    toggleDirection,
+    setSort,
+    reset
+  };
+}
+
+// src/utils/useSortedList.utils.ts
+var import_merge = require("exsorted/merge");
+var collator = new Intl.Collator(void 0, {
+  numeric: true,
+  sensitivity: "base"
+});
+var comparePrimitiveValues = (left, right) => {
+  if (left === right) {
+    return 0;
+  }
+  if (left == null) {
+    return 1;
+  }
+  if (right == null) {
+    return -1;
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() - right.getTime();
+  }
+  if (typeof left === "boolean" && typeof right === "boolean") {
+    return Number(left) - Number(right);
+  }
+  if (typeof left === "number" && typeof right === "number") {
+    return left - right;
+  }
+  return collator.compare(String(left), String(right));
+};
+var withDirection = (comparison, direction) => direction === "asc" ? comparison : -comparison;
+var singleKeyAccessors = (key, accessor) => ({ [key]: accessor });
+var toggleSortDirection = (direction) => direction === "asc" ? "desc" : "asc";
+var buildComparator = (accessor, state, customComparator) => {
+  const compareBase = customComparator ?? ((left, right) => comparePrimitiveValues(accessor(left), accessor(right)));
+  return (left, right) => withDirection(compareBase(left, right), state.direction);
+};
+var sortList = (items, state, accessor, comparator, sorter) => {
+  if (!accessor) {
+    return [...items];
+  }
+  const selectedSorter = sorter ?? import_merge.mergeSort;
+  const directionalComparator = buildComparator(accessor, state, comparator);
+  return selectedSorter([...items], directionalComparator);
+};
+var resolveDefaultKey = (accessors) => {
+  const firstKey = Object.keys(accessors)[0];
+  if (firstKey === void 0) {
+    throw new Error("useSortedList expected at least one accessor key.");
+  }
+  return firstKey;
+};
+var resolveStandaloneInitialDirection = (options) => {
+  if ("initialDirection" in options && options.initialDirection !== void 0) {
+    return options.initialDirection;
+  }
+  return "asc";
+};
+var resolveStandaloneInitialKey = (options, fallbackKey) => {
+  if ("initialKey" in options && options.initialKey !== void 0) {
+    return options.initialKey;
+  }
+  return fallbackKey;
+};
+var resolveAccessorWithFallback = (accessors, key, fallbackKey) => {
+  const directAccessor = accessors[key];
+  if (directAccessor !== void 0) {
+    return { accessor: directAccessor, resolvedKey: key };
+  }
+  return { accessor: accessors[fallbackKey], resolvedKey: fallbackKey };
+};
+var resolveExternalController = (options) => "sort" in options ? options.sort : void 0;
+var resolveExternalState = (options) => "state" in options ? options.state : void 0;
+var areArraysShallowEqual = (left, right) => {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (!Object.is(left[index], right[index])) {
+      return false;
+    }
+  }
+  return true;
+};
+var resolveVisibleItems = (params) => {
+  const { isOriginalMode, sourceItems, isPending, previousItems, sortedItems } = params;
+  if (isOriginalMode) {
+    return [...sourceItems];
+  }
+  if (isPending) {
+    return previousItems;
+  }
+  return sortedItems;
+};
+
+// src/hooks/useSortedList.ts
+function useSortedList(items, options) {
+  const { accessors, comparator, sorter } = options;
+  const [isPending, startTransition] = (0, import_react2.useTransition)();
+  const defaultKey = (0, import_react2.useMemo)(() => resolveDefaultKey(accessors), [accessors]);
+  const externalSortController = resolveExternalController(options);
+  const externalState = resolveExternalState(options);
+  const standaloneInitialDirection = resolveStandaloneInitialDirection(options);
+  const standaloneInitialKey = resolveStandaloneInitialKey(options, defaultKey);
+  const localSortController = useSortState({
+    initialKey: standaloneInitialKey,
+    initialDirection: standaloneInitialDirection
+  });
+  const activeSortController = externalSortController ?? (externalState === void 0 ? localSortController : void 0);
+  const activeSort = externalState ?? activeSortController?.sort ?? localSortController.sort;
+  const setSort = (0, import_react2.useCallback)(
+    (next) => {
+      activeSortController?.setSort(next);
+    },
+    [activeSortController]
+  );
+  const setSortKey = (0, import_react2.useCallback)(
+    (nextKey) => {
+      setSort((previous) => ({ ...previous, key: nextKey }));
+    },
+    [setSort]
+  );
+  const setDirection = (0, import_react2.useCallback)(
+    (nextDirection) => {
+      setSort((previous) => ({ ...previous, direction: nextDirection }));
+    },
+    [setSort]
+  );
+  const toggleDirection = (0, import_react2.useCallback)(() => {
+    setSort((previous) => ({
+      ...previous,
+      direction: toggleSortDirection(previous.direction)
+    }));
+  }, [setSort]);
+  const reset = (0, import_react2.useCallback)(() => {
+    activeSortController?.reset();
+  }, [activeSortController]);
+  const deferredItems = (0, import_react2.useDeferredValue)(items);
+  const deferredState = (0, import_react2.useDeferredValue)(activeSort);
+  const effectiveItems = deferredItems;
+  const effectiveState = deferredState;
+  const effectiveComparator = comparator;
+  const { accessor, resolvedKey } = resolveAccessorWithFallback(
+    accessors,
+    effectiveState.key,
+    defaultKey
+  );
+  const effectiveSort = resolvedKey === effectiveState.key ? effectiveState : { ...effectiveState, key: resolvedKey };
+  const nextSorted = (0, import_react2.useMemo)(
+    () => sortList(effectiveItems, effectiveSort, accessor, effectiveComparator, sorter),
+    [accessor, effectiveComparator, effectiveItems, effectiveSort, sorter]
+  );
+  const [sorted, setSorted] = (0, import_react2.useState)(nextSorted);
+  const [isOriginalMode, setIsOriginalMode] = (0, import_react2.useState)(false);
+  const previousItemsRef = (0, import_react2.useRef)(nextSorted);
+  const restoreOriginal = (0, import_react2.useCallback)(() => {
+    setIsOriginalMode(true);
+  }, []);
+  const restoreSorted = (0, import_react2.useCallback)(() => {
+    setIsOriginalMode(false);
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    if (areArraysShallowEqual(sorted, nextSorted)) {
+      return;
+    }
+    startTransition(() => {
+      setSorted((current) => {
+        if (areArraysShallowEqual(current, nextSorted)) {
+          return current;
+        }
+        previousItemsRef.current = current;
+        return nextSorted;
+      });
+    });
+  }, [nextSorted, sorted, startTransition]);
+  const visibleItems = resolveVisibleItems({
+    isOriginalMode,
+    sourceItems: items,
+    isPending,
+    previousItems: previousItemsRef.current,
+    sortedItems: sorted
+  });
+  return {
+    items: visibleItems,
+    previousItems: previousItemsRef.current,
+    originalItems: items,
+    isSorting: isPending,
+    isSorted: !isPending && !isOriginalMode,
+    sort: activeSort,
+    sortKey: activeSort.key,
+    direction: activeSort.direction,
+    setSortKey,
+    setDirection,
+    toggleDirection,
+    setSort,
+    reset,
+    restoreOriginal,
+    restoreSorted
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  singleKeyAccessors,
+  useSortedList
+});

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+import { CompareFn } from 'exsorted/types';
+
+/**
+ * Direction used when applying a sort operation.
+ */
+type SortDirection = "asc" | "desc";
+/**
+ * Primitive values supported by the default comparator.
+ */
+type SortPrimitive$1 = string | number | boolean | Date | null | undefined;
+/**
+ * Current sort state containing the active key and direction.
+ *
+ * @template TKey key union for sortable fields
+ */
+interface SortState<TKey extends PropertyKey = string> {
+    key: TKey;
+    direction: SortDirection;
+}
+/**
+ * Map of sort keys to accessor functions.
+ *
+ * Each accessor extracts a comparable primitive from an item.
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+type SortAccessors<TItem, TKey extends PropertyKey> = Record<TKey, (item: TItem) => SortPrimitive$1>;
+/**
+ * External controller contract for controlled sorting mode.
+ *
+ * @template TKey key union for sortable fields
+ */
+interface SortController<TKey extends PropertyKey> {
+    sort: SortState<TKey>;
+    setSort: (next: SortState<TKey> | ((previous: SortState<TKey>) => SortState<TKey>)) => void;
+    reset: () => void;
+}
+/**
+ * Exsorted-compatible sorting function signature.
+ *
+ * Accepts only strict comparator-based sorters.
+ *
+ * Excluded intentionally:
+ * - non-compare family from `exsorted/non-compare`:
+ *   `countingSort`, `radixSort`, `bucketSort`, `pigeonholeSort`
+ * - `introSort` from `exsorted/standard` (overload includes threshold variants)
+ *
+ * The trailing `...extra: never[]` prevents passing sorters with additional
+ * non-compatible parameters.
+ */
+type ExsortedSorter<TItem> = (arr: TItem[], compareFn?: CompareFn<TItem>, ...extra: never[]) => TItem[];
+/**
+ * Configuration object for useSortedList.
+ *
+ * Supports three modes:
+ * - standalone mode: no external state/controller, optional initialKey/initialDirection
+ * - controller mode: provide `sort` to fully control state and actions
+ * - state mode: provide `state` for read-only external state observation
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+type UseSortedListOptions<TItem, TKey extends PropertyKey> = {
+    /**
+     * Accessors used to derive sortable values from each item.
+     */
+    accessors: SortAccessors<TItem, TKey>;
+    /**
+     * Custom comparator used for all sort keys.
+     */
+    comparator?: CompareFn<TItem>;
+    /**
+     * Custom Exsorted sorter (defaults to mergeSort in the hook).
+     */
+    sorter?: ExsortedSorter<TItem>;
+} & ({
+    /**
+     * Controlled mode: external controller with state + mutators.
+     */
+    sort: SortController<TKey>;
+    state?: never;
+    initialKey?: never;
+    initialDirection?: never;
+} | {
+    /**
+     * Read-only external state mode.
+     */
+    state: SortState<TKey>;
+    sort?: never;
+    initialKey?: never;
+    initialDirection?: never;
+} | {
+    sort?: never;
+    state?: never;
+    /**
+     * Standalone mode initial key.
+     *
+     * If omitted, the first accessor key is used.
+     */
+    initialKey?: TKey;
+    /**
+     * Standalone mode initial direction.
+     *
+     * Defaults to `asc`.
+     */
+    initialDirection?: SortDirection;
+});
+/**
+ * Return shape for useSortedList.
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+interface UseSortedListResult<TItem, TKey extends PropertyKey = string> {
+    /**
+     * Current visible list, which may be sorted or original depending on mode/actions.
+     */
+    items: TItem[];
+    /**
+     * Last visible list snapshot prior to the most recent sorted update.
+     */
+    previousItems: TItem[];
+    /**
+     * Original source list reference from hook input.
+     */
+    originalItems: readonly TItem[];
+    /**
+     * True while a deferred transition is applying a new sorted result.
+     */
+    isSorting: boolean;
+    /**
+     * True when sorted view is active and no transition is pending.
+     */
+    isSorted: boolean;
+    /**
+     * Current effective sort state.
+     */
+    sort: SortState<TKey>;
+    /**
+     * Shortcut to `sort.key`.
+     */
+    sortKey: TKey;
+    /**
+     * Shortcut to `sort.direction`.
+     */
+    direction: SortDirection;
+    /**
+     * Updates only the active sort key.
+     */
+    setSortKey: (nextKey: TKey) => void;
+    /**
+     * Updates only the active sort direction.
+     */
+    setDirection: (nextDirection: SortDirection) => void;
+    /**
+     * Toggles direction between `asc` and `desc`.
+     */
+    toggleDirection: () => void;
+    /**
+     * Replaces sort state directly or via an updater callback.
+     */
+    setSort: (next: SortState<TKey> | ((previous: SortState<TKey>) => SortState<TKey>)) => void;
+    /**
+     * Resets sorting state to the initial standalone/controller state.
+     */
+    reset: () => void;
+    /**
+     * Shows original input order in `items`.
+     */
+    restoreOriginal: () => void;
+    /**
+     * Switches back to sorted view in `items`.
+     */
+    restoreSorted: () => void;
+}
+
+/**
+ * Internal primitive union used by accessor and comparator helpers.
+ */
+type SortPrimitive = string | number | boolean | Date | null | undefined;
+/**
+ * Internal accessor map used to infer key unions for hook APIs.
+ */
+type SortAccessorRecord<TItem> = Record<string, (item: TItem) => SortPrimitive>;
+/**
+ * Extracts string keys from accessor maps for stable public API typing.
+ */
+type SortKey<TAccessors extends Record<string, (...args: any[]) => unknown>> = Extract<keyof TAccessors, string>;
+
+/**
+ * Sorts a readonly list using Exsorted with stable, non-mutating behavior.
+ *
+ * Supports 3 modes:
+ * - standalone mode: pass initialKey/initialDirection (or neither) and the hook owns sort state
+ * - controller mode: pass sort controller from outside for fully controlled state/actions
+ * - state mode: pass state only for read-only external state (actions become no-ops)
+ *
+ * @template TItem item type in the source list
+ * @template TAccessors accessor map used for sort keys and inferred key union
+ * @param items source list (never mutated)
+ * @param options sorting config, accessors, and state mode controls
+ * @returns visible items, previous/original snapshots, status flags, and sort actions
+ * @example
+ * const sorted = useSortedList(products, {
+ *   accessors: {
+ *     name: (item) => item.name,
+ *     price: (item) => item.price,
+ *   },
+ *   initialKey: "price",
+ * });
+ */
+declare function useSortedList<TItem, const TAccessors extends SortAccessorRecord<TItem>>(items: readonly TItem[], options: UseSortedListOptions<TItem, SortKey<TAccessors>> & {
+    accessors: TAccessors;
+}): UseSortedListResult<TItem, SortKey<TAccessors>>;
+
+/**
+ * Builds a single-key accessor map for simpler one-field sorting cases.
+ */
+declare const singleKeyAccessors: <TItem, const TKey extends string>(key: TKey, accessor: (item: TItem) => SortPrimitive$1) => Record<TKey, (item: TItem) => SortPrimitive$1>;
+
+export { type ExsortedSorter, type SortAccessors, type SortController, type SortDirection, type SortPrimitive$1 as SortPrimitive, type SortState, type UseSortedListOptions, type UseSortedListResult, singleKeyAccessors, useSortedList };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { CompareFn } from 'exsorted/types';
+
+/**
+ * Direction used when applying a sort operation.
+ */
+type SortDirection = "asc" | "desc";
+/**
+ * Primitive values supported by the default comparator.
+ */
+type SortPrimitive$1 = string | number | boolean | Date | null | undefined;
+/**
+ * Current sort state containing the active key and direction.
+ *
+ * @template TKey key union for sortable fields
+ */
+interface SortState<TKey extends PropertyKey = string> {
+    key: TKey;
+    direction: SortDirection;
+}
+/**
+ * Map of sort keys to accessor functions.
+ *
+ * Each accessor extracts a comparable primitive from an item.
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+type SortAccessors<TItem, TKey extends PropertyKey> = Record<TKey, (item: TItem) => SortPrimitive$1>;
+/**
+ * External controller contract for controlled sorting mode.
+ *
+ * @template TKey key union for sortable fields
+ */
+interface SortController<TKey extends PropertyKey> {
+    sort: SortState<TKey>;
+    setSort: (next: SortState<TKey> | ((previous: SortState<TKey>) => SortState<TKey>)) => void;
+    reset: () => void;
+}
+/**
+ * Exsorted-compatible sorting function signature.
+ *
+ * Accepts only strict comparator-based sorters.
+ *
+ * Excluded intentionally:
+ * - non-compare family from `exsorted/non-compare`:
+ *   `countingSort`, `radixSort`, `bucketSort`, `pigeonholeSort`
+ * - `introSort` from `exsorted/standard` (overload includes threshold variants)
+ *
+ * The trailing `...extra: never[]` prevents passing sorters with additional
+ * non-compatible parameters.
+ */
+type ExsortedSorter<TItem> = (arr: TItem[], compareFn?: CompareFn<TItem>, ...extra: never[]) => TItem[];
+/**
+ * Configuration object for useSortedList.
+ *
+ * Supports three modes:
+ * - standalone mode: no external state/controller, optional initialKey/initialDirection
+ * - controller mode: provide `sort` to fully control state and actions
+ * - state mode: provide `state` for read-only external state observation
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+type UseSortedListOptions<TItem, TKey extends PropertyKey> = {
+    /**
+     * Accessors used to derive sortable values from each item.
+     */
+    accessors: SortAccessors<TItem, TKey>;
+    /**
+     * Custom comparator used for all sort keys.
+     */
+    comparator?: CompareFn<TItem>;
+    /**
+     * Custom Exsorted sorter (defaults to mergeSort in the hook).
+     */
+    sorter?: ExsortedSorter<TItem>;
+} & ({
+    /**
+     * Controlled mode: external controller with state + mutators.
+     */
+    sort: SortController<TKey>;
+    state?: never;
+    initialKey?: never;
+    initialDirection?: never;
+} | {
+    /**
+     * Read-only external state mode.
+     */
+    state: SortState<TKey>;
+    sort?: never;
+    initialKey?: never;
+    initialDirection?: never;
+} | {
+    sort?: never;
+    state?: never;
+    /**
+     * Standalone mode initial key.
+     *
+     * If omitted, the first accessor key is used.
+     */
+    initialKey?: TKey;
+    /**
+     * Standalone mode initial direction.
+     *
+     * Defaults to `asc`.
+     */
+    initialDirection?: SortDirection;
+});
+/**
+ * Return shape for useSortedList.
+ *
+ * @template TItem item type in the source list
+ * @template TKey union of valid sort keys
+ */
+interface UseSortedListResult<TItem, TKey extends PropertyKey = string> {
+    /**
+     * Current visible list, which may be sorted or original depending on mode/actions.
+     */
+    items: TItem[];
+    /**
+     * Last visible list snapshot prior to the most recent sorted update.
+     */
+    previousItems: TItem[];
+    /**
+     * Original source list reference from hook input.
+     */
+    originalItems: readonly TItem[];
+    /**
+     * True while a deferred transition is applying a new sorted result.
+     */
+    isSorting: boolean;
+    /**
+     * True when sorted view is active and no transition is pending.
+     */
+    isSorted: boolean;
+    /**
+     * Current effective sort state.
+     */
+    sort: SortState<TKey>;
+    /**
+     * Shortcut to `sort.key`.
+     */
+    sortKey: TKey;
+    /**
+     * Shortcut to `sort.direction`.
+     */
+    direction: SortDirection;
+    /**
+     * Updates only the active sort key.
+     */
+    setSortKey: (nextKey: TKey) => void;
+    /**
+     * Updates only the active sort direction.
+     */
+    setDirection: (nextDirection: SortDirection) => void;
+    /**
+     * Toggles direction between `asc` and `desc`.
+     */
+    toggleDirection: () => void;
+    /**
+     * Replaces sort state directly or via an updater callback.
+     */
+    setSort: (next: SortState<TKey> | ((previous: SortState<TKey>) => SortState<TKey>)) => void;
+    /**
+     * Resets sorting state to the initial standalone/controller state.
+     */
+    reset: () => void;
+    /**
+     * Shows original input order in `items`.
+     */
+    restoreOriginal: () => void;
+    /**
+     * Switches back to sorted view in `items`.
+     */
+    restoreSorted: () => void;
+}
+
+/**
+ * Internal primitive union used by accessor and comparator helpers.
+ */
+type SortPrimitive = string | number | boolean | Date | null | undefined;
+/**
+ * Internal accessor map used to infer key unions for hook APIs.
+ */
+type SortAccessorRecord<TItem> = Record<string, (item: TItem) => SortPrimitive>;
+/**
+ * Extracts string keys from accessor maps for stable public API typing.
+ */
+type SortKey<TAccessors extends Record<string, (...args: any[]) => unknown>> = Extract<keyof TAccessors, string>;
+
+/**
+ * Sorts a readonly list using Exsorted with stable, non-mutating behavior.
+ *
+ * Supports 3 modes:
+ * - standalone mode: pass initialKey/initialDirection (or neither) and the hook owns sort state
+ * - controller mode: pass sort controller from outside for fully controlled state/actions
+ * - state mode: pass state only for read-only external state (actions become no-ops)
+ *
+ * @template TItem item type in the source list
+ * @template TAccessors accessor map used for sort keys and inferred key union
+ * @param items source list (never mutated)
+ * @param options sorting config, accessors, and state mode controls
+ * @returns visible items, previous/original snapshots, status flags, and sort actions
+ * @example
+ * const sorted = useSortedList(products, {
+ *   accessors: {
+ *     name: (item) => item.name,
+ *     price: (item) => item.price,
+ *   },
+ *   initialKey: "price",
+ * });
+ */
+declare function useSortedList<TItem, const TAccessors extends SortAccessorRecord<TItem>>(items: readonly TItem[], options: UseSortedListOptions<TItem, SortKey<TAccessors>> & {
+    accessors: TAccessors;
+}): UseSortedListResult<TItem, SortKey<TAccessors>>;
+
+/**
+ * Builds a single-key accessor map for simpler one-field sorting cases.
+ */
+declare const singleKeyAccessors: <TItem, const TKey extends string>(key: TKey, accessor: (item: TItem) => SortPrimitive$1) => Record<TKey, (item: TItem) => SortPrimitive$1>;
+
+export { type ExsortedSorter, type SortAccessors, type SortController, type SortDirection, type SortPrimitive$1 as SortPrimitive, type SortState, type UseSortedListOptions, type UseSortedListResult, singleKeyAccessors, useSortedList };

package/dist/index.js

@@ -0,0 +1,266 @@
+// src/hooks/useSortedList.ts
+import {
+  useCallback as useCallback2,
+  useDeferredValue,
+  useEffect,
+  useMemo as useMemo2,
+  useRef,
+  useState as useState2,
+  useTransition
+} from "react";
+
+// src/hooks/useSortState.ts
+import { useCallback, useMemo, useState } from "react";
+var defaultGetNextDirection = (current) => current === "asc" ? "desc" : "asc";
+var resolveInitialKey = (options) => {
+  if ("keys" in options) {
+    if (options.initialKey !== void 0) {
+      return options.initialKey;
+    }
+    const firstKey = options.keys[0];
+    if (firstKey === void 0) {
+      throw new Error(
+        "useSortState expected at least one key in options.keys when initialKey is omitted."
+      );
+    }
+    return firstKey;
+  }
+  return options.initialKey;
+};
+function useSortState(options) {
+  const initialDirection = options.initialDirection ?? "asc";
+  const initialKey = useMemo(() => resolveInitialKey(options), [options]);
+  const initialSort = useMemo(
+    () => ({ key: initialKey, direction: initialDirection }),
+    [initialDirection, initialKey]
+  );
+  const [sort, setSort] = useState(initialSort);
+  const setSortKey = useCallback((nextKey) => {
+    setSort((previous) => ({ ...previous, key: nextKey }));
+  }, []);
+  const setDirection = useCallback((nextDirection) => {
+    setSort((previous) => ({ ...previous, direction: nextDirection }));
+  }, []);
+  const toggleDirection = useCallback(() => {
+    const getNextDirection = options.getNextDirection ?? defaultGetNextDirection;
+    setSort((previous) => ({
+      ...previous,
+      direction: getNextDirection(previous.direction)
+    }));
+  }, [options]);
+  const reset = useCallback(() => {
+    setSort(initialSort);
+  }, [initialSort]);
+  return {
+    sort,
+    sortKey: sort.key,
+    direction: sort.direction,
+    setSortKey,
+    setDirection,
+    toggleDirection,
+    setSort,
+    reset
+  };
+}
+
+// src/utils/useSortedList.utils.ts
+import { mergeSort } from "exsorted/merge";
+var collator = new Intl.Collator(void 0, {
+  numeric: true,
+  sensitivity: "base"
+});
+var comparePrimitiveValues = (left, right) => {
+  if (left === right) {
+    return 0;
+  }
+  if (left == null) {
+    return 1;
+  }
+  if (right == null) {
+    return -1;
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() - right.getTime();
+  }
+  if (typeof left === "boolean" && typeof right === "boolean") {
+    return Number(left) - Number(right);
+  }
+  if (typeof left === "number" && typeof right === "number") {
+    return left - right;
+  }
+  return collator.compare(String(left), String(right));
+};
+var withDirection = (comparison, direction) => direction === "asc" ? comparison : -comparison;
+var singleKeyAccessors = (key, accessor) => ({ [key]: accessor });
+var toggleSortDirection = (direction) => direction === "asc" ? "desc" : "asc";
+var buildComparator = (accessor, state, customComparator) => {
+  const compareBase = customComparator ?? ((left, right) => comparePrimitiveValues(accessor(left), accessor(right)));
+  return (left, right) => withDirection(compareBase(left, right), state.direction);
+};
+var sortList = (items, state, accessor, comparator, sorter) => {
+  if (!accessor) {
+    return [...items];
+  }
+  const selectedSorter = sorter ?? mergeSort;
+  const directionalComparator = buildComparator(accessor, state, comparator);
+  return selectedSorter([...items], directionalComparator);
+};
+var resolveDefaultKey = (accessors) => {
+  const firstKey = Object.keys(accessors)[0];
+  if (firstKey === void 0) {
+    throw new Error("useSortedList expected at least one accessor key.");
+  }
+  return firstKey;
+};
+var resolveStandaloneInitialDirection = (options) => {
+  if ("initialDirection" in options && options.initialDirection !== void 0) {
+    return options.initialDirection;
+  }
+  return "asc";
+};
+var resolveStandaloneInitialKey = (options, fallbackKey) => {
+  if ("initialKey" in options && options.initialKey !== void 0) {
+    return options.initialKey;
+  }
+  return fallbackKey;
+};
+var resolveAccessorWithFallback = (accessors, key, fallbackKey) => {
+  const directAccessor = accessors[key];
+  if (directAccessor !== void 0) {
+    return { accessor: directAccessor, resolvedKey: key };
+  }
+  return { accessor: accessors[fallbackKey], resolvedKey: fallbackKey };
+};
+var resolveExternalController = (options) => "sort" in options ? options.sort : void 0;
+var resolveExternalState = (options) => "state" in options ? options.state : void 0;
+var areArraysShallowEqual = (left, right) => {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (!Object.is(left[index], right[index])) {
+      return false;
+    }
+  }
+  return true;
+};
+var resolveVisibleItems = (params) => {
+  const { isOriginalMode, sourceItems, isPending, previousItems, sortedItems } = params;
+  if (isOriginalMode) {
+    return [...sourceItems];
+  }
+  if (isPending) {
+    return previousItems;
+  }
+  return sortedItems;
+};
+
+// src/hooks/useSortedList.ts
+function useSortedList(items, options) {
+  const { accessors, comparator, sorter } = options;
+  const [isPending, startTransition] = useTransition();
+  const defaultKey = useMemo2(() => resolveDefaultKey(accessors), [accessors]);
+  const externalSortController = resolveExternalController(options);
+  const externalState = resolveExternalState(options);
+  const standaloneInitialDirection = resolveStandaloneInitialDirection(options);
+  const standaloneInitialKey = resolveStandaloneInitialKey(options, defaultKey);
+  const localSortController = useSortState({
+    initialKey: standaloneInitialKey,
+    initialDirection: standaloneInitialDirection
+  });
+  const activeSortController = externalSortController ?? (externalState === void 0 ? localSortController : void 0);
+  const activeSort = externalState ?? activeSortController?.sort ?? localSortController.sort;
+  const setSort = useCallback2(
+    (next) => {
+      activeSortController?.setSort(next);
+    },
+    [activeSortController]
+  );
+  const setSortKey = useCallback2(
+    (nextKey) => {
+      setSort((previous) => ({ ...previous, key: nextKey }));
+    },
+    [setSort]
+  );
+  const setDirection = useCallback2(
+    (nextDirection) => {
+      setSort((previous) => ({ ...previous, direction: nextDirection }));
+    },
+    [setSort]
+  );
+  const toggleDirection = useCallback2(() => {
+    setSort((previous) => ({
+      ...previous,
+      direction: toggleSortDirection(previous.direction)
+    }));
+  }, [setSort]);
+  const reset = useCallback2(() => {
+    activeSortController?.reset();
+  }, [activeSortController]);
+  const deferredItems = useDeferredValue(items);
+  const deferredState = useDeferredValue(activeSort);
+  const effectiveItems = deferredItems;
+  const effectiveState = deferredState;
+  const effectiveComparator = comparator;
+  const { accessor, resolvedKey } = resolveAccessorWithFallback(
+    accessors,
+    effectiveState.key,
+    defaultKey
+  );
+  const effectiveSort = resolvedKey === effectiveState.key ? effectiveState : { ...effectiveState, key: resolvedKey };
+  const nextSorted = useMemo2(
+    () => sortList(effectiveItems, effectiveSort, accessor, effectiveComparator, sorter),
+    [accessor, effectiveComparator, effectiveItems, effectiveSort, sorter]
+  );
+  const [sorted, setSorted] = useState2(nextSorted);
+  const [isOriginalMode, setIsOriginalMode] = useState2(false);
+  const previousItemsRef = useRef(nextSorted);
+  const restoreOriginal = useCallback2(() => {
+    setIsOriginalMode(true);
+  }, []);
+  const restoreSorted = useCallback2(() => {
+    setIsOriginalMode(false);
+  }, []);
+  useEffect(() => {
+    if (areArraysShallowEqual(sorted, nextSorted)) {
+      return;
+    }
+    startTransition(() => {
+      setSorted((current) => {
+        if (areArraysShallowEqual(current, nextSorted)) {
+          return current;
+        }
+        previousItemsRef.current = current;
+        return nextSorted;
+      });
+    });
+  }, [nextSorted, sorted, startTransition]);
+  const visibleItems = resolveVisibleItems({
+    isOriginalMode,
+    sourceItems: items,
+    isPending,
+    previousItems: previousItemsRef.current,
+    sortedItems: sorted
+  });
+  return {
+    items: visibleItems,
+    previousItems: previousItemsRef.current,
+    originalItems: items,
+    isSorting: isPending,
+    isSorted: !isPending && !isOriginalMode,
+    sort: activeSort,
+    sortKey: activeSort.key,
+    direction: activeSort.direction,
+    setSortKey,
+    setDirection,
+    toggleDirection,
+    setSort,
+    reset,
+    restoreOriginal,
+    restoreSorted
+  };
+}
+export {
+  singleKeyAccessors,
+  useSortedList
+};

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "exsorted-react",
+  "version": "1.0.3",
+  "description": "React hooks for sorting with Exsorted and TypeScript-first inference",
+  "keywords": [
+    "custom-hook",
+    "exsorted",
+    "react",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Ink01101011/exsorted-react#readme",
+  "bugs": {
+    "url": "https://github.com/Ink01101011/exsorted-react/issues"
+  },
+  "license": "MIT",
+  "author": "Ink01101011",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ink01101011/exsorted-react.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "lint": "pnpm dlx oxlint@latest .",
+    "lint:fix": "pnpm dlx oxlint@latest --fix .",
+    "format": "pnpm dlx oxfmt@latest --write .",
+    "format:check": "pnpm dlx oxfmt@latest --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --runInBand",
+    "test:watch": "jest --watch",
+    "size": "node ./scripts/check-bundle-size.mjs",
+    "audit:cve": "pnpm audit --audit-level=high",
+    "check": "pnpm run lint && pnpm run format:check && pnpm run typecheck && pnpm run build && pnpm run size",
+    "prepare": "husky",
+    "precommit:check": "pnpm run lint && pnpm run format:check && pnpm run typecheck",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "exsorted": "^1.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.2.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^18.0.0 || ^19.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "ts-jest": "^29.2.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "peerDependencies": {
+    "exsorted": "^1.1.0",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "exsorted": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}