@patch-kit/history 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# History Manager
+
+A self-contained undo/redo system for using the Command Pattern.
+
+---
+
+## Overview
+
+Each user action is recorded as a command with `undo()` and `redo()` functions, enabling full history traversal. The factory pattern ensures each history instance is independently scoped and fully typed.
+
+---
+
+## Setup
+
+Call `createHistory()` once at module level and export the bound pair. Both `HistoryProvider` and `useHistory` must come from the same call — they share the same context instance.
+
+```typescript
+import { createHistory } from '@patch-kit/history';
+
+export const { HistoryProvider, useHistory } = createHistory();
+```
+
+For multiple independent history stacks, each call creates its own isolated instance:
+
+```typescript
+export const { HistoryProvider: HistoryA, useHistory: useHistoryA } = createHistory();
+export const { HistoryProvider: HistoryB, useHistory: useHistoryB } = createHistory();
+```
+
+---
+
+## Basic Usage
+
+```tsx
+<HistoryProvider>
+  <App />
+</HistoryProvider>
+```
+
+```typescript
+const { addHistory, undo, redo, canUndo, canRedo } = useHistory();
+
+addHistory({
+  name: 'History Command',
+  undo() {
+    // Undoes the action (called on undo)
+  }
+  redo() {
+    // Re-applies the action (called on redo)
+  },
+});
+```
+
+### `immediate`
+
+Pass `true` as the second argument to apply the action immediately on record, instead of applying it manually beforehand:
+
+```typescript
+// without immediate — apply manually first, then record
+applyChange(next);
+addHistory({ undo: () => applyChange(prev), redo: () => applyChange(next) });
+
+// with immediate — record and apply in one call
+addHistory({ undo: () => applyChange(prev), redo: () => applyChange(next) }, true);
+```
+
+---
+
+## Typed Return Values
+
+Commands can return a value from `undo()` and `redo()`. When they do, the Provider's `onUndo`/`onRedo` callbacks receive that value — letting you centralise any shared logic that would otherwise be repeated at every call site.
+
+```typescript
+type HistoryValue = { type: string; payload: unknown };
+
+export const { HistoryProvider, useHistory } = createHistory<HistoryValue>();
+```
+
+```tsx
+<HistoryProvider
+  onUndo={(value) => { /* handle value centrally */ }}
+  onRedo={(value) => { /* handle value centrally */ }}
+>
+  <App />
+</HistoryProvider>
+```
+
+```typescript
+addHistory({
+  name: 'Update',
+  undo() { return { type: 'update', payload: previous }; },
+  redo() { return { type: 'update', payload: next }; }
+});
+```
+
+If no return value is needed, `undo()` and `redo()` can be void — `onUndo`/`onRedo` are optional and only relevant when commands return data.
+
+---
+
+## API
+
+### `createHistory<T = any>()`
+
+Factory function. Call at module level, outside any component.
+
+Returns `{ HistoryProvider, useHistory }` bound to the same context instance.
+
+### `<HistoryProvider>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `limit` | `number` | `64` | Max number of history entries |
+| `onUndo` | `(value: T) => void` | — | Called after `undo()` with its return value |
+| `onRedo` | `(value: T) => void` | — | Called after `redo()` with its return value |
+
+### `useHistory()`
+
+Must be called inside the matching `HistoryProvider`.
+
+```typescript
+const {
+  addHistory,   // (command: Command<T>, immediate?: boolean) => void
+  undo,         // () => void
+  redo,         // () => void
+  resetHistory, // () => void
+  canUndo,      // boolean
+  canRedo,      // boolean
+} = useHistory();
+```
+
+### `Command<T>`
+
+```typescript
+type Command<T = any> = {
+  name: string;
+  undo: () => T;  // return value passed to onUndo
+  redo: () => T;  // return value passed to onRedo
+}
+```
+
+---
+
+## Patterns
+
+### Capture state before mutating
+
+Always snapshot the previous state before applying the change:
+
+```typescript
+const previous = structuredClone(item);
+applyChange(next);
+
+addHistory({
+  name: 'Update',
+  undo() { applyChange(previous); },
+  redo() { applyChange(next); }
+});
+```
+
+### Batch related operations
+
+Multiple related changes should be a single history entry:
+
+```typescript
+// ✅ one entry, one undo
+addHistory({
+  name: `Move ${ids.length} items`,
+  undo() { ids.forEach(id => move(id, prevPos[id])); },
+  redo() { ids.forEach(id => move(id, nextPos[id])); }
+});
+
+// ❌ N entries, N undos
+ids.forEach(id => addHistory({ ... }));
+```
+
+### Delayed commit (drag, resize, etc.)
+
+For continuous interactions, accumulate changes and commit once on release:
+
+```typescript
+const pending = useRef({ initial: null, final: null });
+
+onDragStart(() => { pending.current.initial = getPosition(); });
+onDragMove((pos) => { pending.current.final = pos; });
+onDragEnd(() => {
+  const { initial, final } = pending.current;
+  addHistory({
+    name: 'Move',
+    undo() { setPosition(initial); },
+    redo() { setPosition(final); }
+  });
+});
+```
+
+Updating state on every move event causes re-renders that feed back into the drag — commit once at the end instead.
+
+---

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Defines an action that can be executed and reverted.
+ * Tells the action **WHAT** happends.
+ */
+type Command<T = any> = {
+    name: string;
+    /**
+     * Undo the action attached to the command.
+     */
+    undo: () => T;
+    /**
+     * Redo the action attached to the command.
+     */
+    redo: () => T;
+};
+
+interface HistoryContextType<T> {
+    addHistory: (command: Command<T>, immediate?: boolean) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    resetHistory: () => void;
+}
+interface HistoryProviderProps<T> {
+    children: React.ReactNode;
+    limit?: number;
+    onUndo?: (value: T) => void;
+    onRedo?: (value: T) => void;
+}
+/**
+ * Manages a history of commands to provide undo and redo functionality.
+ *
+ * Implements the Command design pattern's history tracking. It stores
+ * a list of executed commands in a buffer with a limit.
+ * When a new command is added after an `undo` operation, any existing `redo`
+ * history is cleared. If the history limit is exceeded, the oldest command is
+ * discarded.
+ */
+declare function createHistory<T = any>(): {
+    HistoryProvider: ({ children, limit, onUndo, onRedo, }: HistoryProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    useHistory: () => HistoryContextType<T>;
+};
+
+export { createHistory };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Defines an action that can be executed and reverted.
+ * Tells the action **WHAT** happends.
+ */
+type Command<T = any> = {
+    name: string;
+    /**
+     * Undo the action attached to the command.
+     */
+    undo: () => T;
+    /**
+     * Redo the action attached to the command.
+     */
+    redo: () => T;
+};
+
+interface HistoryContextType<T> {
+    addHistory: (command: Command<T>, immediate?: boolean) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    resetHistory: () => void;
+}
+interface HistoryProviderProps<T> {
+    children: React.ReactNode;
+    limit?: number;
+    onUndo?: (value: T) => void;
+    onRedo?: (value: T) => void;
+}
+/**
+ * Manages a history of commands to provide undo and redo functionality.
+ *
+ * Implements the Command design pattern's history tracking. It stores
+ * a list of executed commands in a buffer with a limit.
+ * When a new command is added after an `undo` operation, any existing `redo`
+ * history is cleared. If the history limit is exceeded, the oldest command is
+ * discarded.
+ */
+declare function createHistory<T = any>(): {
+    HistoryProvider: ({ children, limit, onUndo, onRedo, }: HistoryProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    useHistory: () => HistoryContextType<T>;
+};
+
+export { createHistory };

package/dist/index.js

@@ -0,0 +1,124 @@
+"use client";
+"use strict";
+"use client";
+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);
+
+// index.tsx
+var index_exports = {};
+__export(index_exports, {
+  createHistory: () => createHistory
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var initialState = {
+  commands: [],
+  step: 0
+};
+function historyReducer(state, action) {
+  switch (action.type) {
+    case "ADD": {
+      try {
+        const newHistory = state.commands.slice(0, state.step);
+        newHistory.push(action.command);
+        if (newHistory.length > action.limit) {
+          newHistory.shift();
+        }
+        return { commands: newHistory, step: newHistory.length };
+      } catch (error) {
+        console.error(`Failed to add command ${action.command.name}: ${error}`);
+        return state;
+      }
+    }
+    case "UNDO": {
+      if (state.step <= 0) return state;
+      return { ...state, step: state.step - 1 };
+    }
+    case "REDO": {
+      if (state.step >= state.commands.length) return state;
+      return { ...state, step: state.step + 1 };
+    }
+    case "RESET":
+      return initialState;
+    default:
+      return state;
+  }
+}
+function createHistory() {
+  const Context = (0, import_react.createContext)(null);
+  function HistoryProvider({
+    children,
+    limit = 64,
+    onUndo,
+    onRedo
+  }) {
+    const [state, dispatch] = (0, import_react.useReducer)(historyReducer, initialState);
+    const canUndo = state.step > 0;
+    const canRedo = state.step < state.commands.length;
+    const addHistory = (0, import_react.useCallback)(
+      (command, immediate = false) => {
+        if (immediate) command.redo();
+        dispatch({ type: "ADD", command, limit });
+      },
+      [limit]
+    );
+    const undo = (0, import_react.useCallback)(() => {
+      const { commands, step } = state;
+      if (step <= 0) return;
+      const command = commands[step - 1];
+      const value2 = command.undo();
+      onUndo?.(value2);
+      dispatch({ type: "UNDO" });
+    }, [state, onUndo]);
+    const redo = (0, import_react.useCallback)(() => {
+      const { commands, step } = state;
+      if (step >= commands.length) return;
+      const command = commands[step];
+      const value2 = command.redo();
+      onRedo?.(value2);
+      dispatch({ type: "REDO" });
+    }, [state, onRedo]);
+    const resetHistory = (0, import_react.useCallback)(() => {
+      dispatch({ type: "RESET" });
+    }, []);
+    const value = (0, import_react.useMemo)(
+      () => ({
+        addHistory,
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+        resetHistory
+      }),
+      [addHistory, undo, redo, canUndo, canRedo, resetHistory]
+    );
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Context.Provider, { value, children });
+  }
+  function useHistory() {
+    const context = (0, import_react.useContext)(Context);
+    if (!context) throw new Error("useHistory must be used within a HistoryProvider");
+    return context;
+  }
+  return { HistoryProvider, useHistory };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHistory
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.tsx"],"sourcesContent":["\"use client\";\n\nimport React, {\n  createContext,\n  useContext,\n  useReducer,\n  useCallback,\n  useMemo,\n} from \"react\";\nimport { Command } from \"./types\";\n\ninterface HistoryContextType<T> {\n  addHistory: (command: Command<T>, immediate?: boolean) => void;\n  undo: () => void;\n  redo: () => void;\n  canUndo: boolean;\n  canRedo: boolean;\n  resetHistory: () => void;\n}\n\n// State and action types for the reducer\ninterface HistoryState {\n  commands: Command<any>[];\n  step: number;\n}\n\ntype HistoryAction =\n  | { type: \"ADD\"; command: Command<any>; limit: number }\n  | { type: \"UNDO\" }\n  | { type: \"REDO\" }\n  | { type: \"RESET\" };\n\nconst initialState: HistoryState = {\n  commands: [],\n  step: 0,\n};\n\n/**\n * Pure reducer function that handles all history state transitions atomically.\n * Side effects (undo/redo) are handled outside the reducer to avoid\n * state updates during render.\n */\nfunction historyReducer(state: HistoryState, action: HistoryAction): HistoryState {\n  switch (action.type) {\n    case \"ADD\": {\n      try {\n        const newHistory = state.commands.slice(0, state.step);\n        newHistory.push(action.command);\n\n        if (newHistory.length > action.limit) {\n          newHistory.shift();\n        }\n\n        return { commands: newHistory, step: newHistory.length };\n      } catch (error) {\n        console.error(`Failed to add command ${action.command.name}: ${error}`);\n        return state;\n      }\n    }\n    case \"UNDO\": {\n      if (state.step <= 0) return state;\n      return { ...state, step: state.step - 1 };\n    }\n    case \"REDO\": {\n      if (state.step >= state.commands.length) return state;\n      return { ...state, step: state.step + 1 };\n    }\n    case \"RESET\":\n      return initialState;\n    default:\n      return state;\n  }\n}\n\ninterface HistoryProviderProps<T> {\n  children: React.ReactNode;\n  limit?: number;\n  onUndo?: (value: T) => void;\n  onRedo?: (value: T) => void;\n}\n\n/**\n * Manages a history of commands to provide undo and redo functionality.\n *\n * Implements the Command design pattern's history tracking. It stores\n * a list of executed commands in a buffer with a limit.\n * When a new command is added after an `undo` operation, any existing `redo`\n * history is cleared. If the history limit is exceeded, the oldest command is\n * discarded.\n */\nexport function createHistory<T = any>() {\n  const Context = createContext<HistoryContextType<T> | null>(null);\n\n  function HistoryProvider({\n    children,\n    limit = 64,\n    onUndo,\n    onRedo,\n  }: HistoryProviderProps<T>) {\n    const [state, dispatch] = useReducer(historyReducer, initialState);\n\n    const canUndo = state.step > 0;\n    const canRedo = state.step < state.commands.length;\n\n    const addHistory = useCallback(\n      (command: Command<T>, immediate = false) => {\n        if (immediate) command.redo();\n        dispatch({ type: \"ADD\", command, limit });\n      },\n      [limit]\n    );\n\n    const undo = useCallback(() => {\n      const { commands, step } = state;\n      if (step <= 0) return;\n\n      const command = commands[step - 1];\n      const value = command.undo();\n      onUndo?.(value as T);\n      dispatch({ type: \"UNDO\" });\n    }, [state, onUndo]);\n\n    const redo = useCallback(() => {\n      const { commands, step } = state;\n      if (step >= commands.length) return;\n\n      const command = commands[step];\n      const value = command.redo();\n      onRedo?.(value as T);\n      dispatch({ type: \"REDO\" });\n    }, [state, onRedo]);\n\n    const resetHistory = useCallback(() => {\n      dispatch({ type: \"RESET\" });\n    }, []);\n\n    const value = useMemo(\n      () => ({\n        addHistory,\n        undo,\n        redo,\n        canUndo,\n        canRedo,\n        resetHistory,\n      }),\n      [addHistory, undo, redo, canUndo, canRedo, resetHistory]\n    );\n\n    return <Context.Provider value={value}>{children}</Context.Provider>;\n  }\n\n  function useHistory() {\n    const context = useContext(Context);\n    if (!context) throw new Error(\"useHistory must be used within a HistoryProvider\");\n    return context;\n  }\n\n  return { HistoryProvider, useHistory };\n}"],"mappings":"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","names":["value"]}

package/dist/index.mjs

@@ -0,0 +1,106 @@
+"use client";
+"use client";
+
+// index.tsx
+import {
+  createContext,
+  useContext,
+  useReducer,
+  useCallback,
+  useMemo
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var initialState = {
+  commands: [],
+  step: 0
+};
+function historyReducer(state, action) {
+  switch (action.type) {
+    case "ADD": {
+      try {
+        const newHistory = state.commands.slice(0, state.step);
+        newHistory.push(action.command);
+        if (newHistory.length > action.limit) {
+          newHistory.shift();
+        }
+        return { commands: newHistory, step: newHistory.length };
+      } catch (error) {
+        console.error(`Failed to add command ${action.command.name}: ${error}`);
+        return state;
+      }
+    }
+    case "UNDO": {
+      if (state.step <= 0) return state;
+      return { ...state, step: state.step - 1 };
+    }
+    case "REDO": {
+      if (state.step >= state.commands.length) return state;
+      return { ...state, step: state.step + 1 };
+    }
+    case "RESET":
+      return initialState;
+    default:
+      return state;
+  }
+}
+function createHistory() {
+  const Context = createContext(null);
+  function HistoryProvider({
+    children,
+    limit = 64,
+    onUndo,
+    onRedo
+  }) {
+    const [state, dispatch] = useReducer(historyReducer, initialState);
+    const canUndo = state.step > 0;
+    const canRedo = state.step < state.commands.length;
+    const addHistory = useCallback(
+      (command, immediate = false) => {
+        if (immediate) command.redo();
+        dispatch({ type: "ADD", command, limit });
+      },
+      [limit]
+    );
+    const undo = useCallback(() => {
+      const { commands, step } = state;
+      if (step <= 0) return;
+      const command = commands[step - 1];
+      const value2 = command.undo();
+      onUndo?.(value2);
+      dispatch({ type: "UNDO" });
+    }, [state, onUndo]);
+    const redo = useCallback(() => {
+      const { commands, step } = state;
+      if (step >= commands.length) return;
+      const command = commands[step];
+      const value2 = command.redo();
+      onRedo?.(value2);
+      dispatch({ type: "REDO" });
+    }, [state, onRedo]);
+    const resetHistory = useCallback(() => {
+      dispatch({ type: "RESET" });
+    }, []);
+    const value = useMemo(
+      () => ({
+        addHistory,
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+        resetHistory
+      }),
+      [addHistory, undo, redo, canUndo, canRedo, resetHistory]
+    );
+    return /* @__PURE__ */ jsx(Context.Provider, { value, children });
+  }
+  function useHistory() {
+    const context = useContext(Context);
+    if (!context) throw new Error("useHistory must be used within a HistoryProvider");
+    return context;
+  }
+  return { HistoryProvider, useHistory };
+}
+export {
+  createHistory
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.tsx"],"sourcesContent":["\"use client\";\n\nimport React, {\n  createContext,\n  useContext,\n  useReducer,\n  useCallback,\n  useMemo,\n} from \"react\";\nimport { Command } from \"./types\";\n\ninterface HistoryContextType<T> {\n  addHistory: (command: Command<T>, immediate?: boolean) => void;\n  undo: () => void;\n  redo: () => void;\n  canUndo: boolean;\n  canRedo: boolean;\n  resetHistory: () => void;\n}\n\n// State and action types for the reducer\ninterface HistoryState {\n  commands: Command<any>[];\n  step: number;\n}\n\ntype HistoryAction =\n  | { type: \"ADD\"; command: Command<any>; limit: number }\n  | { type: \"UNDO\" }\n  | { type: \"REDO\" }\n  | { type: \"RESET\" };\n\nconst initialState: HistoryState = {\n  commands: [],\n  step: 0,\n};\n\n/**\n * Pure reducer function that handles all history state transitions atomically.\n * Side effects (undo/redo) are handled outside the reducer to avoid\n * state updates during render.\n */\nfunction historyReducer(state: HistoryState, action: HistoryAction): HistoryState {\n  switch (action.type) {\n    case \"ADD\": {\n      try {\n        const newHistory = state.commands.slice(0, state.step);\n        newHistory.push(action.command);\n\n        if (newHistory.length > action.limit) {\n          newHistory.shift();\n        }\n\n        return { commands: newHistory, step: newHistory.length };\n      } catch (error) {\n        console.error(`Failed to add command ${action.command.name}: ${error}`);\n        return state;\n      }\n    }\n    case \"UNDO\": {\n      if (state.step <= 0) return state;\n      return { ...state, step: state.step - 1 };\n    }\n    case \"REDO\": {\n      if (state.step >= state.commands.length) return state;\n      return { ...state, step: state.step + 1 };\n    }\n    case \"RESET\":\n      return initialState;\n    default:\n      return state;\n  }\n}\n\ninterface HistoryProviderProps<T> {\n  children: React.ReactNode;\n  limit?: number;\n  onUndo?: (value: T) => void;\n  onRedo?: (value: T) => void;\n}\n\n/**\n * Manages a history of commands to provide undo and redo functionality.\n *\n * Implements the Command design pattern's history tracking. It stores\n * a list of executed commands in a buffer with a limit.\n * When a new command is added after an `undo` operation, any existing `redo`\n * history is cleared. If the history limit is exceeded, the oldest command is\n * discarded.\n */\nexport function createHistory<T = any>() {\n  const Context = createContext<HistoryContextType<T> | null>(null);\n\n  function HistoryProvider({\n    children,\n    limit = 64,\n    onUndo,\n    onRedo,\n  }: HistoryProviderProps<T>) {\n    const [state, dispatch] = useReducer(historyReducer, initialState);\n\n    const canUndo = state.step > 0;\n    const canRedo = state.step < state.commands.length;\n\n    const addHistory = useCallback(\n      (command: Command<T>, immediate = false) => {\n        if (immediate) command.redo();\n        dispatch({ type: \"ADD\", command, limit });\n      },\n      [limit]\n    );\n\n    const undo = useCallback(() => {\n      const { commands, step } = state;\n      if (step <= 0) return;\n\n      const command = commands[step - 1];\n      const value = command.undo();\n      onUndo?.(value as T);\n      dispatch({ type: \"UNDO\" });\n    }, [state, onUndo]);\n\n    const redo = useCallback(() => {\n      const { commands, step } = state;\n      if (step >= commands.length) return;\n\n      const command = commands[step];\n      const value = command.redo();\n      onRedo?.(value as T);\n      dispatch({ type: \"REDO\" });\n    }, [state, onRedo]);\n\n    const resetHistory = useCallback(() => {\n      dispatch({ type: \"RESET\" });\n    }, []);\n\n    const value = useMemo(\n      () => ({\n        addHistory,\n        undo,\n        redo,\n        canUndo,\n        canRedo,\n        resetHistory,\n      }),\n      [addHistory, undo, redo, canUndo, canRedo, resetHistory]\n    );\n\n    return <Context.Provider value={value}>{children}</Context.Provider>;\n  }\n\n  function useHistory() {\n    const context = useContext(Context);\n    if (!context) throw new Error(\"useHistory must be used within a HistoryProvider\");\n    return context;\n  }\n\n  return { HistoryProvider, useHistory };\n}"],"mappings":"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","names":["value"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@patch-kit/history",
+  "version": "1.0.0",
+  "description": "History Manager for React",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XKeeXE/patchkit",
+    "directory": "packages/history"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.0"
+  }
+}