react-state-custom 1.0.18 → 1.0.20

package/.github/copilot-instructions.md

@@ -0,0 +1,42 @@
+## Project Snapshot
+- `react-state-custom` is a hook-first state management library; entrypoint `src/index.ts` re-exports context factories and subscription hooks.
+- TypeScript only; consumers are expected to be React 19 apps (see `package.json` peerDependencies).
+- Library build artifacts live in `dist/`; all source utilities reside under `src/state-utils/`.
+
+## Context Core
+- `Context` (`src/state-utils/ctx.ts`) extends `EventTarget`; `data` stores the latest values and `publish` fires per-key DOM events when a loose `!=` comparison detects change.
+- `getContext` memoizes by context name; `useDataContext(name)` memoizes the lookup via React `useMemo`.
+- `useDataSource`/`useDataSourceMultiple` publish new values and register keys in `ctx.registry`; duplicate sources log via `useRegistryChecker`.
+
+## Root Contexts
+- `createRootCtx(name, useFn)` (`src/state-utils/createRootCtx.tsx`) wraps your hook (`useFn`) in a hidden `Root` component that pushes its result into a derived context namespace.
+- Context names come from `name` plus sorted prop key/value pairs; keep props serializable and stable to avoid collisions.
+- `ctxMountedCheck` blocks multiple `Root` instances for the same name; duplicates throw with the original call stack.
+- Use `useCtxStateStrict` to hard-fail when the `Root` is missing, or `useCtxState` to surface a delayed console error instead.
+
+## Auto Context Lifecycle
+- `AutoRootCtx` (`src/state-utils/createAutoCtx.tsx`) maintains a global `'auto-ctx'` context exposing `subscribe(Root, params)` and reference counts for each instance.
+- Mount `<AutoRootCtx Wrapper={YourErrorBoundary}>` once near the app root; it renders requested `Root` components inside the optional wrapper.
+- `createAutoCtx(rootCtx, unmountTime?)` returns `useCtxState(params)` that subscribes through `'auto-ctx'` and hands back `useDataContext` for the resolved name.
+- Multiple callers with identical params share a single `Root`; `unmountTime` delays teardown to absorb rapid mount/unmount cycles.
+
+## Subscription Patterns
+- `useDataSourceMultiple(ctx, ...entries)` expects stable `[key, value]` tuples; internal `useArrayHash` hashes length and reference equality only.
+- Use `useDataSubscribe(ctx, key, debounceMs)` or `useDataSubscribeMultiple(ctx, ...keys)` for keyed reads; debounce variants batch updates when values bounce.
+- `useDataSubscribeWithTransform` recomputes the transformed shape only on change; memoize the `transform` fn to avoid churn.
+- `useQuickSubscribe(ctx)` returns a proxy over `ctx.data`; destructure needed fields immediately during render and avoid storing the proxy for later use.
+
+## Utilities and Gotchas
+- Value comparisons are shallow; mutate objects before republishing or provide new references so `publish` sees changes.
+- `useArrayHash`/`useObjectHash` generate random hashes when array/object shape changes; they do not deep-compare nested content.
+- The reserved `'auto-ctx'` namespace powers `AutoRootCtx`; do not manually reuse this context name.
+
+## Build and Tooling
+- `yarn build` runs Vite with `@vitejs/plugin-react`, `vite-plugin-dts`, and `vite-bundle-analyzer`; the analyzer spins up a server after builds—stop it in CI if unused.
+- `yarn dev` starts the Vite dev server on port 3000; useful for manual inspection of bundle output.
+- Tests are stubbed (`yarn test` exits 0 after printing "No tests specified"); add coverage before depending on test gates.
+- Repo is Yarn 4 (PnP); if editors struggle with module resolution, run `./fix-vscode-yarn-pnp.sh`.
+
+## Reference Docs
+- README (`README.md`) offers narrative examples and positioning.
+- API reference (`API_DOCUMENTATION.md`) documents every export; update alongside code changes.

package/README.md

@@ -1,142 +1,320 @@
-# React State Custom - Documentation
+# React State Custom
 
-Welcome to the comprehensive documentation for the `react-state-custom` library!
+**Simple. Powerful. TypeScript-first.**
 
-## 📚 Documentation Files
-
-- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference with examples for all exported functions, hooks, and classes
-
-## 🚀 Quick Start
+A lightweight React state management library that combines the simplicity of React hooks with the power of event-driven subscriptions. No boilerplate, no complexity—just pure, performant state management.
 
 ```bash
 npm install react-state-custom
 ```
 
-## 📖 What's Inside
+## Why React State Custom?
+
+**Zero Boilerplate** • **Type-Safe** • **Selective Re-renders** • **Hook-Based** • **~10KB Bundle**
+
+React State Custom lets you write state management code that feels natural—because it **is** just React hooks. Use the same hooks you already know (`useState`, `useEffect`, etc.) to create powerful, shared state without learning new paradigms.
+
+## ⚡ Quick Example
+
+```typescript
+import { createRootCtx, createAutoCtx, useQuickSubscribe, AutoRootCtx } from 'react-state-custom';
+
+// 1. Write your state logic using familiar React hooks
+function useCounterState() {
+  const [count, setCount] = useState(0);
+  const increment = () => setCount(c => c + 1);
+  const decrement = () => setCount(c => c - 1);
+  
+  return { count, increment, decrement };
+}
+
+// 2. Create shared context (one line!)
+const { useCtxState } = createAutoCtx(createRootCtx('counter', useCounterState));
+
+// 3. Add AutoRootCtx to your app root
+function App() {
+  return (
+    <>
+      <AutoRootCtx />
+      <Counter />
+    </>
+  );
+}
+
+// 4. Use anywhere in your app
+function Counter() {
+  const ctx = useCtxState();
+  const { count, increment, decrement } = useQuickSubscribe(ctx);
+  
+  return (
+    <div>
+      <h1>{count}</h1>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  );
+}
+```
+
+**That's it!** No reducers, no actions, no providers to wrap—just hooks.
+
+## 🎯 Key Features
+
+### 1. **Just React Hooks**
+Use `useState`, `useEffect`, `useMemo`, and any other React hooks you already know. No new concepts to learn.
+
+```typescript
+function useUserState({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  
+  useEffect(() => {
+    fetchUser(userId).then(setUser).finally(() => setLoading(false));
+  }, [userId]);
+  
+  return { user, loading };
+}
+```
 
-The `react-state-custom` library provides a powerful set of tools for managing shared state in React applications:
+### 2. **Selective Re-renders**
+Components only re-render when the **specific data they subscribe to** changes—not when anything in the state changes.
 
-### Core Features
+```typescript
+// Only re-renders when 'user' changes, not when 'loading' changes
+const { user } = useDataSubscribeMultiple(ctx, 'user');
 
-- **Context System** - Type-safe context management with event-driven subscriptions
-- **Root Context Factory** - Automated context lifecycle management
-- **Auto Context System** - Self-managing context instances
-- **Utility Hooks** - Performance optimization tools
+// Or subscribe to multiple fields
+const { user, loading } = useDataSubscribeMultiple(ctx, 'user', 'loading');
+```
 
-### Key Benefits
+### 3. **Automatic Context Management**
+With `AutoRootCtx`, state contexts are automatically created and destroyed as needed. No manual provider management.
 
-- ✅ **Type Safety** - Full TypeScript support with strong typing
-- ✅ **Performance** - Only re-renders when subscribed data changes
-- ✅ **Flexibility** - Works with any data structure
-- ✅ **Developer Experience** - Rich debugging and error checking
-- ✅ **Minimal Boilerplate** - Automated context management
+### 4. **TypeScript First**
+Full type inference and type safety throughout. Your IDE knows exactly what's in your state.
 
-## 📝 Documentation Structure
+### 5. **Tiny Bundle Size**
+~10KB gzipped. No dependencies except React.
 
-The [API Documentation](./API_DOCUMENTATION.md) is organized into the following sections:
+## 🆚 Comparison with Redux & Zustand
 
-1. **Core Context System** - Basic context functionality
-2. **Data Source Hooks** - Publishing data to contexts
-3. **Data Subscription Hooks** - Subscribing to context changes
-4. **Root Context Factory** - Advanced context patterns
-5. **Auto Context System** - Automated context management
-6. **Utility Hooks** - Performance and utility functions
-7. **Usage Patterns** - Common implementation patterns
-8. **Examples** - Complete application examples
+| Feature | React State Custom | Redux | Zustand |
+|---------|-------------------|-------|---------|
+| **Bundle Size** | ~10KB | ~50KB (with toolkit) | ~1KB |
+| **Learning Curve** | ✅ Minimal (just hooks) | ❌ High (actions, reducers, middleware) | ✅ Low |
+| **Boilerplate** | ✅ None | ❌ Heavy | ✅ Minimal |
+| **Type Safety** | ✅ Full inference | ⚠️ Requires setup | ✅ Good |
+| **Selective Re-renders** | ✅ Built-in | ⚠️ Requires selectors | ✅ Built-in |
+| **DevTools** | ⚠️ Console logging | ✅ Redux DevTools | ✅ DevTools support |
+| **Async Support** | ✅ Native (hooks) | ⚠️ Requires middleware | ✅ Native |
+| **Context Composition** | ✅ Automatic | ❌ Manual | ⚠️ Manual store combination |
 
-## 🎯 Common Use Cases
+### When to Use React State Custom
 
-- **Global State Management** - Application-wide state without Redux complexity
-- **Component Communication** - Share data between distant components
-- **Performance Optimization** - Minimize unnecessary re-renders
-- **Context Composition** - Combine multiple contexts efficiently
+✅ **Choose React State Custom if you:**
+- Want to use React hooks for state management without learning new patterns
+- Need fine-grained control over component re-renders
+- Prefer minimal boilerplate and configuration
+- Want automatic context lifecycle management
+- Need multiple independent state contexts that don't interfere
 
-## 🔧 Quick Example
+❌ **Consider Redux if you:**
+- Need powerful time-travel debugging (Redux DevTools)
+- Have a very large team that benefits from strict architectural patterns
+- Already have significant Redux investment
 
-### Using createRootCtx for Advanced State Management
+❌ **Consider Zustand if you:**
+- Want the absolute smallest bundle size
+- Need a simple global store without context isolation
+- Don't need automatic context lifecycle management
 
+## 🔥 Real-World Example: User Authentication
 
-file main.tsx
 ```typescript
-import { AutoRootCtx } from 'react-state-custom';
+// authState.ts
+function useAuthState() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  
+  useEffect(() => {
+    // Check authentication on mount
+    checkAuth().then(setUser).finally(() => setLoading(false));
+  }, []);
+  
+  const login = async (email: string, password: string) => {
+    setLoading(true);
+    try {
+      const user = await authService.login(email, password);
+      setUser(user);
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  const logout = async () => {
+    await authService.logout();
+    setUser(null);
+  };
+  
+  return { user, loading, login, logout };
+}
 
-// Root Component
-function App({children}) {
+export const { useCtxState: useAuthState } = createAutoCtx(
+  createRootCtx('auth', useAuthState)
+);
+
+// App.tsx
+function App() {
   return (
     <>
       <AutoRootCtx />
-      {children}
+      <Router>
+        <Header />
+        <Routes />
+      </Router>
     </>
   );
 }
 
-```
-file userState.ts
-```typescript
-import { createRootCtx, createAutoCtx,  } from 'react-state-custom';
-
-interface UserState {
-  user: User | null;
-  loading: boolean;
-  error: string | null;
+// Header.tsx - Only re-renders when user changes
+function Header() {
+  const ctx = useAuthState();
+  const { user, logout } = useQuickSubscribe(ctx);
+  
+  return (
+    <header>
+      {user ? (
+        <>
+          <span>Welcome, {user.name}</span>
+          <button onClick={logout}>Logout</button>
+        </>
+      ) : (
+        <Link to="/login">Login</Link>
+      )}
+    </header>
+  );
 }
 
-// Create a state hook
-function useUserState(props: { userId: string }) {
-  const [user, setUser] = useState<User | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+// ProtectedRoute.tsx - Only re-renders when loading or user changes
+function ProtectedRoute({ children }) {
+  const ctx = useAuthState();
+  const { user, loading } = useDataSubscribeMultiple(ctx, 'user', 'loading');
   
-  useEffect(() => {
-    fetchUser(props.userId).then(setUser).catch(setError).finally(() => setLoading(false));
-  }, [props.userId]);
+  if (loading) return <Spinner />;
+  if (!user) return <Navigate to="/login" />;
   
-  return { user, loading, error };
+  return children;
 }
+```
+
+**Compare with Redux:**
+```typescript
+// Redux requires: action types, action creators, reducers, thunks/sagas
+// React State Custom: just write a hook! ✨
+```
+
+## 📚 Core Concepts
 
-// Register State hook
-const { useCtxState: useUserCtxState } = createAutoCtx(createRootCtx(
-  'user-state',
-  useUserState
-));
+### 1. **Context** - Event-driven state container
+```typescript
+const ctx = useDataContext<MyState>('my-state');
+```
+
+### 2. **Data Source** - Publish values to context
+```typescript
+useDataSource(ctx, 'count', count);
+```
 
-export { useUserCtxState }
+### 3. **Data Subscription** - Subscribe to specific values
+```typescript
+const count = useDataSubscribe(ctx, 'count');
+const { count, name } = useDataSubscribeMultiple(ctx, 'count', 'name');
+```
 
+### 4. **Root Context** - Lifecycle-managed context
+```typescript
+const { Root, useCtxState } = createRootCtx('my-state', useMyState);
 ```
 
-file UserProfile.tsx
+### 5. **Auto Context** - Automatic instance management
 ```typescript
-import { useDataSubscribeMultiple, useQuickSubscribe } from 'react-state-custom';
-import { useUserCtxState } from "./userState.ts"
+const { useCtxState } = createAutoCtx(rootContext);
+```
 
-// Consumer component using useDataSubscribeMultiple
-function UserProfile({ userId }: { userId: string }) {
-  const ctx = useUserCtxState({ userId });
-  const { user, loading, error } = useDataSubscribeMultiple(ctx, 'user', 'loading', 'error');
-  
-  if (loading) return <div>Loading user...</div>;
-  if (error) return <div>Error: {error}</div>;
-  
-  return <div>Welcome, {user?.name}!</div>;
+## 🚀 Advanced Features
+
+### Parameterized Contexts
+Create multiple instances of the same state with different parameters:
+
+```typescript
+function useUserState({ userId }: { userId: string }) {
+  // State logic here
 }
 
-// Or using useQuickSubscribe  for Simplified Access
+const { useCtxState: useUserState } = createAutoCtx(
+  createRootCtx('user', useUserState)
+);
 
-function UserProfileV2({ userId }: { userId: string }) {
-  const ctx = useUserCtxState({ userId });
-  const { user, loading, error } = useQuickSubscribe(ctx);
-  
-  if (loading) return <div>Loading user...</div>;
-  if (error) return <div>Error: {error}</div>;
-  
-  return <div>Welcome, {user?.name}!</div>;
+// Different instances for different users
+function UserProfile({ userId }) {
+  const ctx = useUserState({ userId }); // Automatic instance per userId
+  const { user } = useQuickSubscribe(ctx);
+  return <div>{user?.name}</div>;
 }
 ```
 
+### Debounced Subscriptions
+Optimize performance for frequently changing values:
+
+```typescript
+// Re-render at most once per 300ms
+const searchQuery = useDataSubscribe(ctx, 'searchQuery', 300);
+```
+
+### Transformed Subscriptions
+Transform data before using it:
+
+```typescript
+const userStats = useDataSubscribeWithTransform(
+  ctx,
+  'user',
+  (user) => ({
+    fullName: `${user?.firstName} ${user?.lastName}`,
+    isAdmin: user?.role === 'admin'
+  })
+);
+```
+
+## 📖 Documentation
+
+For complete API documentation, examples, and advanced patterns, see:
+- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference
+
+## 🎓 Learning Path
+
+1. **Start Simple** - Use `createRootCtx` + `createAutoCtx` for basic state
+2. **Add Subscriptions** - Use `useDataSubscribeMultiple` for selective re-renders
+3. **Optimize** - Add debouncing and transformations as needed
+4. **Scale** - Create parameterized contexts for dynamic instances
+
+## 📦 Installation
+
+```bash
+npm install react-state-custom
+# or
+yarn add react-state-custom
+# or
+pnpm add react-state-custom
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
 ## 📄 License
 
-MIT License - see the main repository for details.
+MIT License - feel free to use in any project.
 
 ---
 
-For the complete API reference with detailed examples, see [API_DOCUMENTATION.md](./API_DOCUMENTATION.md).
+**Made with ❤️ for developers who love React hooks**

package/dist/DevTool.d.ts

@@ -0,0 +1,4 @@
+export declare const DevToolContainer: ({ toggleButton, ...props }: {
+    [x: string]: any;
+    toggleButton?: string | undefined;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/DevToolState.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export declare const DevToolState: ({}: {}) => import("react/jsx-runtime").JSX.Element;
+export declare const StateView: React.FC<{
+    dataKey: string;
+}>;
+export declare const JSONView: React.FC<{
+    value: any;
+    name?: string;
+    style?: any;
+    expandLevel?: number | boolean;
+}>;

package/dist/Test.d.ts

@@ -0,0 +1 @@
+export declare const Test: ({}: {}) => import("react/jsx-runtime").JSX.Element;

package/dist/dev.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { createRootCtx } from './state-utils/createRootCtx';
 export { AutoRootCtx, createAutoCtx } from './state-utils/createAutoCtx';
 export { useArrayHash } from './state-utils/useArrayHash';
 export { useQuickSubscribe } from './state-utils/useQuickSubscribe';
+export { DevToolContainer } from './DevTool';