@usefy/use-selection 0.19.0

package/README.md

@@ -0,0 +1,164 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-selection</h1>
+
+<p align="center">
+  <strong>Multi/single selection state for lists and tables — Set-based, checkbox-ready</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-selection"><img src="https://img.shields.io/npm/v/@usefy/use-selection.svg?style=flat-square&color=007acc" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@usefy/use-selection"><img src="https://img.shields.io/npm/dm/@usefy/use-selection.svg?style=flat-square&color=007acc" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/@usefy/use-selection"><img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-selection?style=flat-square&color=007acc" alt="bundle size" /></a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@usefy/use-selection.svg?style=flat-square&color=007acc" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-useselection--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`useSelection` is part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It manages which items from a list or table are selected, backed by a `Set` of keys, with everything a checkbox UI needs: per-row selection, a header "select all" with indeterminate state, and an optional single-selection mode.
+
+## Features
+
+- **Set-backed** — stores **keys** (via `getKey`, default identity), so a selection survives new item identities across renders
+- **Ergonomic surface** — `selected` items, `isSelected`, `toggle`, `select`, `deselect`, `selectAll`, `clear`
+- **Header-checkbox ready** — `isAllSelected` / `isPartiallySelected` / `isNoneSelected` for the indeterminate state
+- **Single-selection mode** — `multiple: false` replaces the selection on select (radio-like)
+- **Auto-reconciled** — item-facing values derive from the current `items`; removed rows drop out automatically
+- **Stable & efficient** — stable action identities; no-op `selectAll`/`clear` skip re-renders; immutable Set updates
+- **SSR-safe & StrictMode-safe** — pure state, no mutation of prior state
+- **TypeScript-first** — full type inference and exported types
+- **Tiny & tree-shakeable** — zero dependencies, published as its own package
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-selection
+
+# yarn
+yarn add @usefy/use-selection
+
+# pnpm
+pnpm add @usefy/use-selection
+```
+
+Requires React 18 or 19 (`peerDependencies: "react": "^18.0.0 || ^19.0.0"`).
+
+## Quick Start
+
+```tsx
+import { useSelection } from "@usefy/use-selection";
+
+type User = { id: number; name: string };
+
+function UserTable({ users }: { users: User[] }) {
+  const {
+    selected,
+    isSelected,
+    toggle,
+    selectAll,
+    clear,
+    isAllSelected,
+    isPartiallySelected,
+  } = useSelection(users, { getKey: (u) => u.id });
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>
+            <input
+              type="checkbox"
+              checked={isAllSelected}
+              ref={(el) => {
+                if (el) el.indeterminate = isPartiallySelected;
+              }}
+              onChange={() => (isAllSelected ? clear() : selectAll())}
+            />
+          </th>
+          <th>Name ({selected.length} selected)</th>
+        </tr>
+      </thead>
+      <tbody>
+        {users.map((user) => (
+          <tr key={user.id}>
+            <td>
+              <input
+                type="checkbox"
+                checked={isSelected(user)}
+                onChange={() => toggle(user)}
+              />
+            </td>
+            <td>{user.name}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+## API
+
+```ts
+const result = useSelection<T>(items: T[], options?: UseSelectionOptions<T>);
+```
+
+### Options — `UseSelectionOptions<T>`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `getKey` | `(item: T) => string \| number` | identity (`(item) => item`) | Derives the selection key for an item. The `Set` stores these keys, not items, so selection survives new object references. **Provide this for object items** (e.g. `(row) => row.id`); the identity default is only correct for primitive items. |
+| `multiple` | `boolean` | `true` | `true` = multi-selection; `false` = single-selection (selecting replaces the current choice, and `selectAll` is a no-op). |
+
+### Return — `UseSelectionReturn<T>`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `selected` | `T[]` | The selected items, in `items` order. Derived as `items ∩ selectedKeys` — items removed from `items` drop out automatically. |
+| `selectedKeys` | `ReadonlySet<string \| number>` | The raw set of selected keys (source of truth). May contain keys for items no longer in `items`; those are invisible in the derived values. |
+| `isSelected` | `(item: T) => boolean` | Whether an item is selected (by key). Stable. |
+| `toggle` | `(item: T) => void` | Flip an item's selection. In single mode, selecting a new item replaces the previous one. Stable. |
+| `select` | `(item: T) => void` | Select an item (idempotent). In single mode, replaces the selection. Stable. |
+| `deselect` | `(item: T) => void` | Deselect an item (idempotent). Stable. |
+| `selectAll` | `() => void` | Select every item in `items`. No-op when all are already selected, or in single mode. Stable. |
+| `clear` | `() => void` | Clear the whole selection (deselect all). No-op when already empty. Stable. |
+| `isAllSelected` | `boolean` | `true` when every item is selected. **Always `false` for an empty `items` array.** |
+| `isPartiallySelected` | `boolean` | `true` when some — but not all — items are selected (drives an indeterminate header checkbox). `false` for empty `items`. |
+| `isNoneSelected` | `boolean` | `true` when no items are selected (including when `items` is empty). |
+
+### Behavior notes
+
+- **Selection key.** The `Set` stores **keys**, never items. This is what makes a selection stable when `items` is rebuilt with fresh object references each render — as long as `getKey` maps the same logical item to the same key. For primitive `items` (`string`/`number`) the identity default just works.
+- **Items-change reconciliation.** `selectedKeys` is the source of truth; every item-facing value is **derived from the current `items`**. Removing a selected row from `items` makes it disappear from `selected` and recomputes `isAllSelected`/`isPartiallySelected` automatically — no manual pruning needed. The removed key stays in `selectedKeys` (harmless and invisible) so it re-appears if the item comes back.
+- **Empty list.** `isAllSelected` is `false` for an empty `items` array (there is nothing to have "all" selected); `isNoneSelected` is `true`.
+- **Single-selection mode.** With `multiple: false`, `select`/`toggle` of a new item replace the current selection; toggling the already-selected item deselects it. `selectAll` is a no-op (you cannot hold more than one selection).
+- **StrictMode / concurrency.** Updates are immutable (a fresh `Set` on every change) and no user callback runs inside a `setState` updater, so it is safe under StrictMode and concurrent rendering.
+
+## Testing
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-selection/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages) — **24 tests**, 100% statement coverage.
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+/**
+ * The primitive key a selection is tracked by. Items may be objects, so
+ * {@link useSelection} never stores items directly — it stores a stable
+ * key derived from each item (see {@link UseSelectionOptions.getKey}). Keys are
+ * `string | number` so they compare by value inside the backing `Set`, which is
+ * what makes a selection survive new object identities across renders.
+ */
+type SelectionKey = string | number;
+/**
+ * Options for {@link useSelection}.
+ *
+ * @template T - The item type.
+ */
+interface UseSelectionOptions<T> {
+    /**
+     * Derive the selection key for an item. The backing `Set` stores these keys,
+     * not the items themselves, so selection is stable even when the `items`
+     * array is rebuilt with new object references each render (as long as
+     * `getKey` returns the same key for the same logical item).
+     *
+     * Defaults to identity (`(item) => item`), which is correct when `items` are
+     * primitives (`string`/`number`). For object items you should provide a
+     * `getKey` such as `(row) => row.id`.
+     */
+    getKey?: (item: T) => SelectionKey;
+    /**
+     * Whether more than one item can be selected at a time.
+     *
+     * - `true` (default) — multi-selection. `select`/`toggle` add to the set.
+     * - `false` — single-selection. Selecting an item replaces the current
+     *   selection; toggling the already-selected item deselects it. `selectAll`
+     *   is a no-op in this mode (you cannot hold more than one selection).
+     *
+     * @defaultValue true
+     */
+    multiple?: boolean;
+}
+/**
+ * Return value of {@link useSelection}.
+ *
+ * The backing `Set` of keys is the source of truth, but every item-facing value
+ * (`selected`, `isAllSelected`, …) is **derived from the current `items`**. This
+ * means keys for items no longer present in `items` simply stop appearing in
+ * `selected` and stop counting toward `isAllSelected` — stale selections never
+ * linger in the item-facing surface.
+ *
+ * @template T - The item type.
+ */
+interface UseSelectionReturn<T> {
+    /**
+     * The currently selected items, in `items` order. Derived as
+     * `items` ∩ `selectedKeys`, so items removed from `items` drop out
+     * automatically. Ideal for rendering a "selected" summary.
+     *
+     * Read-only: it is a freshly derived array — use the actions to change the
+     * selection rather than mutating this in place.
+     */
+    selected: readonly T[];
+    /**
+     * The raw set of selected keys — the source of truth. Read-only: use the
+     * actions to mutate. May contain keys for items not currently in `items`
+     * (those are simply invisible in the derived, item-facing values).
+     */
+    selectedKeys: ReadonlySet<SelectionKey>;
+    /**
+     * Whether a given item is currently selected (compared by key). Stable across
+     * renders and always reflects the latest state.
+     */
+    isSelected: (item: T) => boolean;
+    /**
+     * Toggle a single item's selection. If it is selected it becomes deselected;
+     * otherwise it becomes selected. In single-selection mode, selecting a new
+     * item replaces the previous selection. Stable identity.
+     */
+    toggle: (item: T) => void;
+    /**
+     * Explicitly select an item (idempotent — selecting an already-selected item
+     * is a no-op). In single-selection mode this replaces the current selection.
+     * Stable identity.
+     */
+    select: (item: T) => void;
+    /**
+     * Explicitly deselect an item (idempotent — deselecting an item that is not
+     * selected is a no-op). Stable identity.
+     */
+    deselect: (item: T) => void;
+    /**
+     * Select every item currently in `items`. No-op when everything is already
+     * selected (no re-render). No-op in single-selection mode. Stable identity.
+     */
+    selectAll: () => void;
+    /**
+     * Clear the entire selection (a.k.a. deselect all). No-op when the selection
+     * is already empty (no re-render). Stable identity.
+     */
+    clear: () => void;
+    /**
+     * `true` when every item in `items` is selected. Always `false` for an empty
+     * `items` array (there is nothing to have "all" selected).
+     */
+    isAllSelected: boolean;
+    /**
+     * `true` when some — but not all — of the current `items` are selected. Useful
+     * to drive a header checkbox's `indeterminate` state. `false` for an empty
+     * `items` array.
+     */
+    isPartiallySelected: boolean;
+    /**
+     * `true` when none of the current `items` are selected (including when `items`
+     * is empty).
+     */
+    isNoneSelected: boolean;
+}
+
+/**
+ * Manage multi- or single-selection state for a list or table, backed by a
+ * `Set` of keys.
+ *
+ * The `Set` stores **keys** (see the `getKey` option), never the items
+ * themselves, so a selection survives new object identities across renders —
+ * rebuilding the `items` array every render will not lose the selection as long
+ * as `getKey` maps the same logical item to the same key. Every item-facing
+ * value (`selected`, `isAllSelected`, `isPartiallySelected`, …) is **derived
+ * from the current `items`**, so removing a selected row from `items` makes it
+ * disappear from `selected` and recomputes the aggregate flags automatically —
+ * no manual reconciliation needed.
+ *
+ * Features:
+ * - `Set`-backed, immutable updates (a fresh `Set` on every change)
+ * - No-op skipping — `selectAll` when all are already selected, and `clear`
+ *   when already empty, bail out without a re-render
+ * - Single-selection mode (`multiple: false`) that replaces the selection
+ * - Stable action identities (`toggle`/`select`/`deselect`/`selectAll`/`clear`
+ *   and `isSelected`) — safe as effect dependencies
+ * - `isPartiallySelected` for a header checkbox's indeterminate state
+ * - SSR-safe (pure state) and StrictMode/concurrent-safe (no mutation of prior
+ *   state, callbacks never fire from inside a `setState` updater)
+ *
+ * @template T - The item type.
+ * @param items - The current list of items the selection is scoped to.
+ * @param options - {@link UseSelectionOptions} (`getKey`, `multiple`).
+ * @returns {@link UseSelectionReturn}
+ *
+ * @example
+ * ```tsx
+ * type User = { id: number; name: string };
+ *
+ * function UserTable({ users }: { users: User[] }) {
+ *   const {
+ *     selected,
+ *     isSelected,
+ *     toggle,
+ *     selectAll,
+ *     clear,
+ *     isAllSelected,
+ *     isPartiallySelected,
+ *   } = useSelection(users, { getKey: (u) => u.id });
+ *
+ *   return (
+ *     <table>
+ *       <thead>
+ *         <tr>
+ *           <th>
+ *             <input
+ *               type="checkbox"
+ *               checked={isAllSelected}
+ *               ref={(el) => {
+ *                 if (el) el.indeterminate = isPartiallySelected;
+ *               }}
+ *               onChange={() => (isAllSelected ? clear() : selectAll())}
+ *             />
+ *           </th>
+ *           <th>Name ({selected.length} selected)</th>
+ *         </tr>
+ *       </thead>
+ *       <tbody>
+ *         {users.map((user) => (
+ *           <tr key={user.id}>
+ *             <td>
+ *               <input
+ *                 type="checkbox"
+ *                 checked={isSelected(user)}
+ *                 onChange={() => toggle(user)}
+ *               />
+ *             </td>
+ *             <td>{user.name}</td>
+ *           </tr>
+ *         ))}
+ *       </tbody>
+ *     </table>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Single-selection mode (radio-like): selecting replaces the previous choice.
+ * const { selected, isSelected, select } = useSelection(options, {
+ *   multiple: false,
+ * });
+ * ```
+ */
+declare function useSelection<T>(items: T[], options?: UseSelectionOptions<T>): UseSelectionReturn<T>;
+
+export { type SelectionKey, type UseSelectionOptions, type UseSelectionReturn, useSelection };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The primitive key a selection is tracked by. Items may be objects, so
+ * {@link useSelection} never stores items directly — it stores a stable
+ * key derived from each item (see {@link UseSelectionOptions.getKey}). Keys are
+ * `string | number` so they compare by value inside the backing `Set`, which is
+ * what makes a selection survive new object identities across renders.
+ */
+type SelectionKey = string | number;
+/**
+ * Options for {@link useSelection}.
+ *
+ * @template T - The item type.
+ */
+interface UseSelectionOptions<T> {
+    /**
+     * Derive the selection key for an item. The backing `Set` stores these keys,
+     * not the items themselves, so selection is stable even when the `items`
+     * array is rebuilt with new object references each render (as long as
+     * `getKey` returns the same key for the same logical item).
+     *
+     * Defaults to identity (`(item) => item`), which is correct when `items` are
+     * primitives (`string`/`number`). For object items you should provide a
+     * `getKey` such as `(row) => row.id`.
+     */
+    getKey?: (item: T) => SelectionKey;
+    /**
+     * Whether more than one item can be selected at a time.
+     *
+     * - `true` (default) — multi-selection. `select`/`toggle` add to the set.
+     * - `false` — single-selection. Selecting an item replaces the current
+     *   selection; toggling the already-selected item deselects it. `selectAll`
+     *   is a no-op in this mode (you cannot hold more than one selection).
+     *
+     * @defaultValue true
+     */
+    multiple?: boolean;
+}
+/**
+ * Return value of {@link useSelection}.
+ *
+ * The backing `Set` of keys is the source of truth, but every item-facing value
+ * (`selected`, `isAllSelected`, …) is **derived from the current `items`**. This
+ * means keys for items no longer present in `items` simply stop appearing in
+ * `selected` and stop counting toward `isAllSelected` — stale selections never
+ * linger in the item-facing surface.
+ *
+ * @template T - The item type.
+ */
+interface UseSelectionReturn<T> {
+    /**
+     * The currently selected items, in `items` order. Derived as
+     * `items` ∩ `selectedKeys`, so items removed from `items` drop out
+     * automatically. Ideal for rendering a "selected" summary.
+     *
+     * Read-only: it is a freshly derived array — use the actions to change the
+     * selection rather than mutating this in place.
+     */
+    selected: readonly T[];
+    /**
+     * The raw set of selected keys — the source of truth. Read-only: use the
+     * actions to mutate. May contain keys for items not currently in `items`
+     * (those are simply invisible in the derived, item-facing values).
+     */
+    selectedKeys: ReadonlySet<SelectionKey>;
+    /**
+     * Whether a given item is currently selected (compared by key). Stable across
+     * renders and always reflects the latest state.
+     */
+    isSelected: (item: T) => boolean;
+    /**
+     * Toggle a single item's selection. If it is selected it becomes deselected;
+     * otherwise it becomes selected. In single-selection mode, selecting a new
+     * item replaces the previous selection. Stable identity.
+     */
+    toggle: (item: T) => void;
+    /**
+     * Explicitly select an item (idempotent — selecting an already-selected item
+     * is a no-op). In single-selection mode this replaces the current selection.
+     * Stable identity.
+     */
+    select: (item: T) => void;
+    /**
+     * Explicitly deselect an item (idempotent — deselecting an item that is not
+     * selected is a no-op). Stable identity.
+     */
+    deselect: (item: T) => void;
+    /**
+     * Select every item currently in `items`. No-op when everything is already
+     * selected (no re-render). No-op in single-selection mode. Stable identity.
+     */
+    selectAll: () => void;
+    /**
+     * Clear the entire selection (a.k.a. deselect all). No-op when the selection
+     * is already empty (no re-render). Stable identity.
+     */
+    clear: () => void;
+    /**
+     * `true` when every item in `items` is selected. Always `false` for an empty
+     * `items` array (there is nothing to have "all" selected).
+     */
+    isAllSelected: boolean;
+    /**
+     * `true` when some — but not all — of the current `items` are selected. Useful
+     * to drive a header checkbox's `indeterminate` state. `false` for an empty
+     * `items` array.
+     */
+    isPartiallySelected: boolean;
+    /**
+     * `true` when none of the current `items` are selected (including when `items`
+     * is empty).
+     */
+    isNoneSelected: boolean;
+}
+
+/**
+ * Manage multi- or single-selection state for a list or table, backed by a
+ * `Set` of keys.
+ *
+ * The `Set` stores **keys** (see the `getKey` option), never the items
+ * themselves, so a selection survives new object identities across renders —
+ * rebuilding the `items` array every render will not lose the selection as long
+ * as `getKey` maps the same logical item to the same key. Every item-facing
+ * value (`selected`, `isAllSelected`, `isPartiallySelected`, …) is **derived
+ * from the current `items`**, so removing a selected row from `items` makes it
+ * disappear from `selected` and recomputes the aggregate flags automatically —
+ * no manual reconciliation needed.
+ *
+ * Features:
+ * - `Set`-backed, immutable updates (a fresh `Set` on every change)
+ * - No-op skipping — `selectAll` when all are already selected, and `clear`
+ *   when already empty, bail out without a re-render
+ * - Single-selection mode (`multiple: false`) that replaces the selection
+ * - Stable action identities (`toggle`/`select`/`deselect`/`selectAll`/`clear`
+ *   and `isSelected`) — safe as effect dependencies
+ * - `isPartiallySelected` for a header checkbox's indeterminate state
+ * - SSR-safe (pure state) and StrictMode/concurrent-safe (no mutation of prior
+ *   state, callbacks never fire from inside a `setState` updater)
+ *
+ * @template T - The item type.
+ * @param items - The current list of items the selection is scoped to.
+ * @param options - {@link UseSelectionOptions} (`getKey`, `multiple`).
+ * @returns {@link UseSelectionReturn}
+ *
+ * @example
+ * ```tsx
+ * type User = { id: number; name: string };
+ *
+ * function UserTable({ users }: { users: User[] }) {
+ *   const {
+ *     selected,
+ *     isSelected,
+ *     toggle,
+ *     selectAll,
+ *     clear,
+ *     isAllSelected,
+ *     isPartiallySelected,
+ *   } = useSelection(users, { getKey: (u) => u.id });
+ *
+ *   return (
+ *     <table>
+ *       <thead>
+ *         <tr>
+ *           <th>
+ *             <input
+ *               type="checkbox"
+ *               checked={isAllSelected}
+ *               ref={(el) => {
+ *                 if (el) el.indeterminate = isPartiallySelected;
+ *               }}
+ *               onChange={() => (isAllSelected ? clear() : selectAll())}
+ *             />
+ *           </th>
+ *           <th>Name ({selected.length} selected)</th>
+ *         </tr>
+ *       </thead>
+ *       <tbody>
+ *         {users.map((user) => (
+ *           <tr key={user.id}>
+ *             <td>
+ *               <input
+ *                 type="checkbox"
+ *                 checked={isSelected(user)}
+ *                 onChange={() => toggle(user)}
+ *               />
+ *             </td>
+ *             <td>{user.name}</td>
+ *           </tr>
+ *         ))}
+ *       </tbody>
+ *     </table>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Single-selection mode (radio-like): selecting replaces the previous choice.
+ * const { selected, isSelected, select } = useSelection(options, {
+ *   multiple: false,
+ * });
+ * ```
+ */
+declare function useSelection<T>(items: T[], options?: UseSelectionOptions<T>): UseSelectionReturn<T>;
+
+export { type SelectionKey, type UseSelectionOptions, type UseSelectionReturn, useSelection };

package/dist/index.js

@@ -0,0 +1,163 @@
+"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, {
+  useSelection: () => useSelection
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSelection.ts
+var import_react = require("react");
+function useSelection(items, options = {}) {
+  const { multiple = true } = options;
+  const [selectedKeys, setSelectedKeys] = (0, import_react.useState)(
+    () => /* @__PURE__ */ new Set()
+  );
+  const getKeyOptionRef = (0, import_react.useRef)(options.getKey);
+  getKeyOptionRef.current = options.getKey;
+  const itemsRef = (0, import_react.useRef)(items);
+  itemsRef.current = items;
+  const multipleRef = (0, import_react.useRef)(multiple);
+  multipleRef.current = multiple;
+  const selectedKeysRef = (0, import_react.useRef)(selectedKeys);
+  selectedKeysRef.current = selectedKeys;
+  const getKey = (0, import_react.useCallback)((item) => {
+    const fn = getKeyOptionRef.current;
+    return fn ? fn(item) : item;
+  }, []);
+  const select = (0, import_react.useCallback)(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (multipleRef.current) {
+          if (prev.has(key)) {
+            return prev;
+          }
+          const next = new Set(prev);
+          next.add(key);
+          return next;
+        }
+        if (prev.size === 1 && prev.has(key)) {
+          return prev;
+        }
+        return /* @__PURE__ */ new Set([key]);
+      });
+    },
+    [getKey]
+  );
+  const deselect = (0, import_react.useCallback)(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (!prev.has(key)) {
+          return prev;
+        }
+        const next = new Set(prev);
+        next.delete(key);
+        return next;
+      });
+    },
+    [getKey]
+  );
+  const toggle = (0, import_react.useCallback)(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (prev.has(key)) {
+          const next = new Set(prev);
+          next.delete(key);
+          return next;
+        }
+        if (multipleRef.current) {
+          const next = new Set(prev);
+          next.add(key);
+          return next;
+        }
+        return /* @__PURE__ */ new Set([key]);
+      });
+    },
+    [getKey]
+  );
+  const selectAll = (0, import_react.useCallback)(() => {
+    if (!multipleRef.current) {
+      return;
+    }
+    setSelectedKeys((prev) => {
+      const currentItems = itemsRef.current;
+      if (currentItems.length === 0) {
+        return prev;
+      }
+      let changed = false;
+      const next = new Set(prev);
+      for (const item of currentItems) {
+        const key = getKey(item);
+        if (!next.has(key)) {
+          next.add(key);
+          changed = true;
+        }
+      }
+      return changed ? next : prev;
+    });
+  }, [getKey]);
+  const clear = (0, import_react.useCallback)(() => {
+    setSelectedKeys(
+      (prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set()
+    );
+  }, []);
+  const isSelected = (0, import_react.useCallback)(
+    (item) => selectedKeysRef.current.has(getKey(item)),
+    [getKey]
+  );
+  const { selected, isAllSelected, isPartiallySelected, isNoneSelected } = (0, import_react.useMemo)(() => {
+    const sel = [];
+    for (const item of items) {
+      if (selectedKeys.has(getKey(item))) {
+        sel.push(item);
+      }
+    }
+    const count = sel.length;
+    const total = items.length;
+    return {
+      selected: sel,
+      isAllSelected: total > 0 && count === total,
+      isPartiallySelected: count > 0 && count < total,
+      isNoneSelected: count === 0
+    };
+  }, [items, selectedKeys, getKey]);
+  return {
+    selected,
+    selectedKeys,
+    isSelected,
+    toggle,
+    select,
+    deselect,
+    selectAll,
+    clear,
+    isAllSelected,
+    isPartiallySelected,
+    isNoneSelected
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useSelection
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useSelection.ts"],"sourcesContent":["export { useSelection } from \"./useSelection\";\nexport type {\n  SelectionKey,\n  UseSelectionOptions,\n  UseSelectionReturn,\n} from \"./types\";\n","import { useCallback, useMemo, useRef, useState } from \"react\";\nimport type {\n  SelectionKey,\n  UseSelectionOptions,\n  UseSelectionReturn,\n} from \"./types\";\n\n/**\n * Manage multi- or single-selection state for a list or table, backed by a\n * `Set` of keys.\n *\n * The `Set` stores **keys** (see the `getKey` option), never the items\n * themselves, so a selection survives new object identities across renders —\n * rebuilding the `items` array every render will not lose the selection as long\n * as `getKey` maps the same logical item to the same key. Every item-facing\n * value (`selected`, `isAllSelected`, `isPartiallySelected`, …) is **derived\n * from the current `items`**, so removing a selected row from `items` makes it\n * disappear from `selected` and recomputes the aggregate flags automatically —\n * no manual reconciliation needed.\n *\n * Features:\n * - `Set`-backed, immutable updates (a fresh `Set` on every change)\n * - No-op skipping — `selectAll` when all are already selected, and `clear`\n *   when already empty, bail out without a re-render\n * - Single-selection mode (`multiple: false`) that replaces the selection\n * - Stable action identities (`toggle`/`select`/`deselect`/`selectAll`/`clear`\n *   and `isSelected`) — safe as effect dependencies\n * - `isPartiallySelected` for a header checkbox's indeterminate state\n * - SSR-safe (pure state) and StrictMode/concurrent-safe (no mutation of prior\n *   state, callbacks never fire from inside a `setState` updater)\n *\n * @template T - The item type.\n * @param items - The current list of items the selection is scoped to.\n * @param options - {@link UseSelectionOptions} (`getKey`, `multiple`).\n * @returns {@link UseSelectionReturn}\n *\n * @example\n * ```tsx\n * type User = { id: number; name: string };\n *\n * function UserTable({ users }: { users: User[] }) {\n *   const {\n *     selected,\n *     isSelected,\n *     toggle,\n *     selectAll,\n *     clear,\n *     isAllSelected,\n *     isPartiallySelected,\n *   } = useSelection(users, { getKey: (u) => u.id });\n *\n *   return (\n *     <table>\n *       <thead>\n *         <tr>\n *           <th>\n *             <input\n *               type=\"checkbox\"\n *               checked={isAllSelected}\n *               ref={(el) => {\n *                 if (el) el.indeterminate = isPartiallySelected;\n *               }}\n *               onChange={() => (isAllSelected ? clear() : selectAll())}\n *             />\n *           </th>\n *           <th>Name ({selected.length} selected)</th>\n *         </tr>\n *       </thead>\n *       <tbody>\n *         {users.map((user) => (\n *           <tr key={user.id}>\n *             <td>\n *               <input\n *                 type=\"checkbox\"\n *                 checked={isSelected(user)}\n *                 onChange={() => toggle(user)}\n *               />\n *             </td>\n *             <td>{user.name}</td>\n *           </tr>\n *         ))}\n *       </tbody>\n *     </table>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Single-selection mode (radio-like): selecting replaces the previous choice.\n * const { selected, isSelected, select } = useSelection(options, {\n *   multiple: false,\n * });\n * ```\n */\nexport function useSelection<T>(\n  items: T[],\n  options: UseSelectionOptions<T> = {}\n): UseSelectionReturn<T> {\n  const { multiple = true } = options;\n\n  const [selectedKeys, setSelectedKeys] = useState<Set<SelectionKey>>(\n    () => new Set()\n  );\n\n  // Mirror the latest inputs so the stable actions can read fresh values\n  // without being recreated each render.\n  const getKeyOptionRef = useRef(options.getKey);\n  getKeyOptionRef.current = options.getKey;\n\n  const itemsRef = useRef(items);\n  itemsRef.current = items;\n\n  const multipleRef = useRef(multiple);\n  multipleRef.current = multiple;\n\n  const selectedKeysRef = useRef(selectedKeys);\n  selectedKeysRef.current = selectedKeys;\n\n  // A stable key resolver that always uses the latest `getKey`. Falls back to\n  // identity (works for primitive items) when no `getKey` is provided.\n  const getKey = useCallback((item: T): SelectionKey => {\n    const fn = getKeyOptionRef.current;\n    return fn ? fn(item) : (item as unknown as SelectionKey);\n  }, []);\n\n  const select = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (multipleRef.current) {\n          if (prev.has(key)) {\n            return prev; // already selected — no-op\n          }\n          const next = new Set(prev);\n          next.add(key);\n          return next;\n        }\n        // single-selection: replace with just this key\n        if (prev.size === 1 && prev.has(key)) {\n          return prev; // already the sole selection — no-op\n        }\n        return new Set<SelectionKey>([key]);\n      });\n    },\n    [getKey]\n  );\n\n  const deselect = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (!prev.has(key)) {\n          return prev; // not selected — no-op\n        }\n        const next = new Set(prev);\n        next.delete(key);\n        return next;\n      });\n    },\n    [getKey]\n  );\n\n  const toggle = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (prev.has(key)) {\n          const next = new Set(prev);\n          next.delete(key);\n          return next;\n        }\n        if (multipleRef.current) {\n          const next = new Set(prev);\n          next.add(key);\n          return next;\n        }\n        // single-selection: replace with just this key\n        return new Set<SelectionKey>([key]);\n      });\n    },\n    [getKey]\n  );\n\n  const selectAll = useCallback(() => {\n    // Selecting \"all\" is a multi-selection concept.\n    if (!multipleRef.current) {\n      return;\n    }\n    setSelectedKeys((prev) => {\n      const currentItems = itemsRef.current;\n      if (currentItems.length === 0) {\n        return prev; // nothing to select — no-op\n      }\n      let changed = false;\n      const next = new Set(prev);\n      for (const item of currentItems) {\n        const key = getKey(item);\n        if (!next.has(key)) {\n          next.add(key);\n          changed = true;\n        }\n      }\n      return changed ? next : prev; // no-op when all already selected\n    });\n  }, [getKey]);\n\n  const clear = useCallback(() => {\n    setSelectedKeys((prev) =>\n      prev.size === 0 ? prev : new Set<SelectionKey>()\n    );\n  }, []);\n\n  const isSelected = useCallback(\n    (item: T) => selectedKeysRef.current.has(getKey(item)),\n    [getKey]\n  );\n\n  // Derive item-facing values from the current items ∩ selected keys. This is\n  // what drops stale keys and keeps the aggregate flags in sync when `items`\n  // changes. `getKey` is stable, so this recomputes only when `items` or the\n  // selection changes.\n  const { selected, isAllSelected, isPartiallySelected, isNoneSelected } =\n    useMemo(() => {\n      const sel: T[] = [];\n      for (const item of items) {\n        if (selectedKeys.has(getKey(item))) {\n          sel.push(item);\n        }\n      }\n      const count = sel.length;\n      const total = items.length;\n      return {\n        selected: sel,\n        isAllSelected: total > 0 && count === total,\n        isPartiallySelected: count > 0 && count < total,\n        isNoneSelected: count === 0,\n      };\n    }, [items, selectedKeys, getKey]);\n\n  return {\n    selected,\n    selectedKeys,\n    isSelected,\n    toggle,\n    select,\n    deselect,\n    selectAll,\n    clear,\n    isAllSelected,\n    isPartiallySelected,\n    isNoneSelected,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,136 @@
+// src/useSelection.ts
+import { useCallback, useMemo, useRef, useState } from "react";
+function useSelection(items, options = {}) {
+  const { multiple = true } = options;
+  const [selectedKeys, setSelectedKeys] = useState(
+    () => /* @__PURE__ */ new Set()
+  );
+  const getKeyOptionRef = useRef(options.getKey);
+  getKeyOptionRef.current = options.getKey;
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+  const multipleRef = useRef(multiple);
+  multipleRef.current = multiple;
+  const selectedKeysRef = useRef(selectedKeys);
+  selectedKeysRef.current = selectedKeys;
+  const getKey = useCallback((item) => {
+    const fn = getKeyOptionRef.current;
+    return fn ? fn(item) : item;
+  }, []);
+  const select = useCallback(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (multipleRef.current) {
+          if (prev.has(key)) {
+            return prev;
+          }
+          const next = new Set(prev);
+          next.add(key);
+          return next;
+        }
+        if (prev.size === 1 && prev.has(key)) {
+          return prev;
+        }
+        return /* @__PURE__ */ new Set([key]);
+      });
+    },
+    [getKey]
+  );
+  const deselect = useCallback(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (!prev.has(key)) {
+          return prev;
+        }
+        const next = new Set(prev);
+        next.delete(key);
+        return next;
+      });
+    },
+    [getKey]
+  );
+  const toggle = useCallback(
+    (item) => {
+      const key = getKey(item);
+      setSelectedKeys((prev) => {
+        if (prev.has(key)) {
+          const next = new Set(prev);
+          next.delete(key);
+          return next;
+        }
+        if (multipleRef.current) {
+          const next = new Set(prev);
+          next.add(key);
+          return next;
+        }
+        return /* @__PURE__ */ new Set([key]);
+      });
+    },
+    [getKey]
+  );
+  const selectAll = useCallback(() => {
+    if (!multipleRef.current) {
+      return;
+    }
+    setSelectedKeys((prev) => {
+      const currentItems = itemsRef.current;
+      if (currentItems.length === 0) {
+        return prev;
+      }
+      let changed = false;
+      const next = new Set(prev);
+      for (const item of currentItems) {
+        const key = getKey(item);
+        if (!next.has(key)) {
+          next.add(key);
+          changed = true;
+        }
+      }
+      return changed ? next : prev;
+    });
+  }, [getKey]);
+  const clear = useCallback(() => {
+    setSelectedKeys(
+      (prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set()
+    );
+  }, []);
+  const isSelected = useCallback(
+    (item) => selectedKeysRef.current.has(getKey(item)),
+    [getKey]
+  );
+  const { selected, isAllSelected, isPartiallySelected, isNoneSelected } = useMemo(() => {
+    const sel = [];
+    for (const item of items) {
+      if (selectedKeys.has(getKey(item))) {
+        sel.push(item);
+      }
+    }
+    const count = sel.length;
+    const total = items.length;
+    return {
+      selected: sel,
+      isAllSelected: total > 0 && count === total,
+      isPartiallySelected: count > 0 && count < total,
+      isNoneSelected: count === 0
+    };
+  }, [items, selectedKeys, getKey]);
+  return {
+    selected,
+    selectedKeys,
+    isSelected,
+    toggle,
+    select,
+    deselect,
+    selectAll,
+    clear,
+    isAllSelected,
+    isPartiallySelected,
+    isNoneSelected
+  };
+}
+export {
+  useSelection
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useSelection.ts"],"sourcesContent":["import { useCallback, useMemo, useRef, useState } from \"react\";\nimport type {\n  SelectionKey,\n  UseSelectionOptions,\n  UseSelectionReturn,\n} from \"./types\";\n\n/**\n * Manage multi- or single-selection state for a list or table, backed by a\n * `Set` of keys.\n *\n * The `Set` stores **keys** (see the `getKey` option), never the items\n * themselves, so a selection survives new object identities across renders —\n * rebuilding the `items` array every render will not lose the selection as long\n * as `getKey` maps the same logical item to the same key. Every item-facing\n * value (`selected`, `isAllSelected`, `isPartiallySelected`, …) is **derived\n * from the current `items`**, so removing a selected row from `items` makes it\n * disappear from `selected` and recomputes the aggregate flags automatically —\n * no manual reconciliation needed.\n *\n * Features:\n * - `Set`-backed, immutable updates (a fresh `Set` on every change)\n * - No-op skipping — `selectAll` when all are already selected, and `clear`\n *   when already empty, bail out without a re-render\n * - Single-selection mode (`multiple: false`) that replaces the selection\n * - Stable action identities (`toggle`/`select`/`deselect`/`selectAll`/`clear`\n *   and `isSelected`) — safe as effect dependencies\n * - `isPartiallySelected` for a header checkbox's indeterminate state\n * - SSR-safe (pure state) and StrictMode/concurrent-safe (no mutation of prior\n *   state, callbacks never fire from inside a `setState` updater)\n *\n * @template T - The item type.\n * @param items - The current list of items the selection is scoped to.\n * @param options - {@link UseSelectionOptions} (`getKey`, `multiple`).\n * @returns {@link UseSelectionReturn}\n *\n * @example\n * ```tsx\n * type User = { id: number; name: string };\n *\n * function UserTable({ users }: { users: User[] }) {\n *   const {\n *     selected,\n *     isSelected,\n *     toggle,\n *     selectAll,\n *     clear,\n *     isAllSelected,\n *     isPartiallySelected,\n *   } = useSelection(users, { getKey: (u) => u.id });\n *\n *   return (\n *     <table>\n *       <thead>\n *         <tr>\n *           <th>\n *             <input\n *               type=\"checkbox\"\n *               checked={isAllSelected}\n *               ref={(el) => {\n *                 if (el) el.indeterminate = isPartiallySelected;\n *               }}\n *               onChange={() => (isAllSelected ? clear() : selectAll())}\n *             />\n *           </th>\n *           <th>Name ({selected.length} selected)</th>\n *         </tr>\n *       </thead>\n *       <tbody>\n *         {users.map((user) => (\n *           <tr key={user.id}>\n *             <td>\n *               <input\n *                 type=\"checkbox\"\n *                 checked={isSelected(user)}\n *                 onChange={() => toggle(user)}\n *               />\n *             </td>\n *             <td>{user.name}</td>\n *           </tr>\n *         ))}\n *       </tbody>\n *     </table>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Single-selection mode (radio-like): selecting replaces the previous choice.\n * const { selected, isSelected, select } = useSelection(options, {\n *   multiple: false,\n * });\n * ```\n */\nexport function useSelection<T>(\n  items: T[],\n  options: UseSelectionOptions<T> = {}\n): UseSelectionReturn<T> {\n  const { multiple = true } = options;\n\n  const [selectedKeys, setSelectedKeys] = useState<Set<SelectionKey>>(\n    () => new Set()\n  );\n\n  // Mirror the latest inputs so the stable actions can read fresh values\n  // without being recreated each render.\n  const getKeyOptionRef = useRef(options.getKey);\n  getKeyOptionRef.current = options.getKey;\n\n  const itemsRef = useRef(items);\n  itemsRef.current = items;\n\n  const multipleRef = useRef(multiple);\n  multipleRef.current = multiple;\n\n  const selectedKeysRef = useRef(selectedKeys);\n  selectedKeysRef.current = selectedKeys;\n\n  // A stable key resolver that always uses the latest `getKey`. Falls back to\n  // identity (works for primitive items) when no `getKey` is provided.\n  const getKey = useCallback((item: T): SelectionKey => {\n    const fn = getKeyOptionRef.current;\n    return fn ? fn(item) : (item as unknown as SelectionKey);\n  }, []);\n\n  const select = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (multipleRef.current) {\n          if (prev.has(key)) {\n            return prev; // already selected — no-op\n          }\n          const next = new Set(prev);\n          next.add(key);\n          return next;\n        }\n        // single-selection: replace with just this key\n        if (prev.size === 1 && prev.has(key)) {\n          return prev; // already the sole selection — no-op\n        }\n        return new Set<SelectionKey>([key]);\n      });\n    },\n    [getKey]\n  );\n\n  const deselect = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (!prev.has(key)) {\n          return prev; // not selected — no-op\n        }\n        const next = new Set(prev);\n        next.delete(key);\n        return next;\n      });\n    },\n    [getKey]\n  );\n\n  const toggle = useCallback(\n    (item: T) => {\n      const key = getKey(item);\n      setSelectedKeys((prev) => {\n        if (prev.has(key)) {\n          const next = new Set(prev);\n          next.delete(key);\n          return next;\n        }\n        if (multipleRef.current) {\n          const next = new Set(prev);\n          next.add(key);\n          return next;\n        }\n        // single-selection: replace with just this key\n        return new Set<SelectionKey>([key]);\n      });\n    },\n    [getKey]\n  );\n\n  const selectAll = useCallback(() => {\n    // Selecting \"all\" is a multi-selection concept.\n    if (!multipleRef.current) {\n      return;\n    }\n    setSelectedKeys((prev) => {\n      const currentItems = itemsRef.current;\n      if (currentItems.length === 0) {\n        return prev; // nothing to select — no-op\n      }\n      let changed = false;\n      const next = new Set(prev);\n      for (const item of currentItems) {\n        const key = getKey(item);\n        if (!next.has(key)) {\n          next.add(key);\n          changed = true;\n        }\n      }\n      return changed ? next : prev; // no-op when all already selected\n    });\n  }, [getKey]);\n\n  const clear = useCallback(() => {\n    setSelectedKeys((prev) =>\n      prev.size === 0 ? prev : new Set<SelectionKey>()\n    );\n  }, []);\n\n  const isSelected = useCallback(\n    (item: T) => selectedKeysRef.current.has(getKey(item)),\n    [getKey]\n  );\n\n  // Derive item-facing values from the current items ∩ selected keys. This is\n  // what drops stale keys and keeps the aggregate flags in sync when `items`\n  // changes. `getKey` is stable, so this recomputes only when `items` or the\n  // selection changes.\n  const { selected, isAllSelected, isPartiallySelected, isNoneSelected } =\n    useMemo(() => {\n      const sel: T[] = [];\n      for (const item of items) {\n        if (selectedKeys.has(getKey(item))) {\n          sel.push(item);\n        }\n      }\n      const count = sel.length;\n      const total = items.length;\n      return {\n        selected: sel,\n        isAllSelected: total > 0 && count === total,\n        isPartiallySelected: count > 0 && count < total,\n        isNoneSelected: count === 0,\n      };\n    }, [items, selectedKeys, getKey]);\n\n  return {\n    selected,\n    selectedKeys,\n    isSelected,\n    toggle,\n    select,\n    deselect,\n    selectAll,\n    clear,\n    isAllSelected,\n    isPartiallySelected,\n    isNoneSelected,\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@usefy/use-selection",
+  "version": "0.19.0",
+  "description": "A React hook for managing multi/single selection state for lists and tables, backed by a Set",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-selection"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "selection",
+    "select",
+    "multi-select",
+    "checkbox",
+    "table",
+    "list",
+    "set",
+    "state",
+    "useSelection"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}