react-state-custom 1.0.23 → 1.0.24

package/.github/copilot-instructions.md

@@ -2,6 +2,7 @@
 - `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/`.
+- Live demo at https://vothanhdat.github.io/react-state-custom/ showcases interactive examples.
 
 ## 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.
@@ -20,6 +21,12 @@
 - `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.
 
+## Developer Tools
+- `DevToolContainer` (`src/dev-tool/DevTool.tsx`) provides a debugging UI for inspecting all context data; mount it alongside `<AutoRootCtx />`.
+- Accepts optional `Component` prop (type `DataViewComponent`) for custom data rendering; defaults to JSON stringify.
+- Import styles with `import 'react-state-custom/dist/react-state-custom.css'` when using DevTool.
+- Used in demo (`src/dev.tsx`, `src/examples/`) with `react-obj-view` for rich object inspection.
+
 ## 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.
@@ -31,12 +38,20 @@
 - `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.
 
+## Examples
+- Five complete examples in `src/examples/`: counter, todo, form, timer, cart.
+- `Playground.tsx` uses `@codesandbox/sandpack-react` to render interactive examples with live editing.
+- Each example has `state.ts` (hook), `view.tsx` (components), `app.tsx` (root), and `index.ts` (exports).
+- Demo uses `?raw` imports to show source code in Sandpack editor.
+
 ## 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.
+- `yarn dev` starts the Vite dev server on port 3000 with demo examples; `yarn build:demo` creates GitHub Pages build.
+- `yarn preview` previews demo build locally with correct base path (`/react-state-custom/`).
 - 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`.
+- GitHub Actions workflow (`.github/workflows/deploy.yml`) auto-deploys demo to GitHub Pages on push to master.
 
 ## Reference Docs
-- README (`README.md`) offers narrative examples and positioning.
+- README (`README.md`) offers narrative examples and positioning; includes live demo link.
 - API reference (`API_DOCUMENTATION.md`) documents every export; update alongside code changes.

package/.github/workflows/deploy.yml

@@ -0,0 +1,56 @@
+name: Deploy Demo to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Build demo
+        run: yarn build:demo
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './demo-dist'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/API_DOCUMENTATION.md

@@ -2,6 +2,8 @@
 
 A powerful React library for managing shared state and context with TypeScript support, built with Vite.
 
+🎮 **[Try the Live Demo →](https://vothanhdat.github.io/react-state-custom/)**
+
 ## Table of Contents
 
 1. [Core Context System](#core-context-system)
@@ -21,11 +23,14 @@ A powerful React library for managing shared state and context with TypeScript s
 5. [Auto Context System](#auto-context-system)
    - [AutoRootCtx](#autorootctx)
    - [createAutoCtx](#createautoctx)
-6. [Utility Hooks](#utility-hooks)
+6. [Developer Tools](#developer-tools)
+   - [DevToolContainer](#devtoolcontainer)
+   - [DataViewComponent](#dataviewcomponent)
+7. [Utility Hooks](#utility-hooks)
    - [useArrayHash](#usearrayhash)
    - [useQuickSubscribe](#usequicksubscribe)
-7. [Usage Patterns](#usage-patterns)
-8. [Examples](#examples)
+8. [Usage Patterns](#usage-patterns)
+9. [Examples](#examples)
 
 ---
 
@@ -560,6 +565,105 @@ function UserProfile({ userId }: { userId: string }) {
 
 ---
 
+## Developer Tools
+
+### DevToolContainer
+
+A debugging component that displays all context data in your application. Provides a visual interface for inspecting state values across all contexts.
+
+**Type Definition:**
+```typescript
+function DevToolContainer(props: {
+  toggleButton?: string;
+  Component?: DataViewComponent;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+}): JSX.Element
+```
+
+**Parameters:**
+- `toggleButton` - Optional text for the toggle button (default: "[x]")
+- `Component` - Optional custom component for rendering data (default: `DataViewDefault`)
+- `style` - Optional inline styles for the toggle button
+- `children` - Optional custom content for the toggle button (default: "Toggle Dev Tool")
+
+**Returns:**
+- A JSX element containing the dev tool UI
+
+**Example:**
+```typescript
+import { DevToolContainer } from 'react-state-custom';
+import 'react-state-custom/dist/react-state-custom.css'; // Import styles
+
+function App() {
+  return (
+    <>
+      <AutoRootCtx />
+      <YourAppContent />
+      <DevToolContainer />
+    </>
+  );
+}
+```
+
+**With Custom Component:**
+```typescript
+import { DevToolContainer, DataViewComponent } from 'react-state-custom';
+import { ObjectView } from 'react-obj-view';
+import 'react-obj-view/dist/react-obj-view.css';
+
+const CustomDataView: DataViewComponent = ({ name, value }) => {
+  return <ObjectView name={name} value={value} expandLevel={2} />;
+};
+
+function App() {
+  return (
+    <>
+      <AutoRootCtx />
+      <YourAppContent />
+      <DevToolContainer 
+        Component={CustomDataView}
+        style={{ left: "20px", bottom: "10px" }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+### DataViewComponent
+
+Type definition for custom data view components used by `DevToolContainer`.
+
+**Type Definition:**
+```typescript
+type DataViewComponent = React.FC<{
+  value: any;
+  name: string;
+}>;
+```
+
+**Parameters:**
+- `value` - The data value to display
+- `name` - The context name
+
+**Example:**
+```typescript
+import { DataViewComponent } from 'react-state-custom';
+
+const CustomDataView: DataViewComponent = ({ name, value }) => {
+  return (
+    <div className="custom-view">
+      <h3>{name}</h3>
+      <pre>{JSON.stringify(value, null, 2)}</pre>
+    </div>
+  );
+};
+```
+
+---
+
 ## Utility Hooks
 
 ### useArrayHash
@@ -880,4 +984,29 @@ function TodoFilters() {
 }
 ```
 
+---
+
+## Live Examples
+
+For interactive examples with live editing, visit the **[Live Demo](https://vothanhdat.github.io/react-state-custom/)**.
+
+The demo includes the following examples:
+
+### Counter Example
+A simple counter demonstrating basic state management with increment, decrement, and reset operations.
+
+### Todo List Example  
+Multiple independent todo lists showing how contexts can be scoped by parameters. Each list maintains its own state.
+
+### Form Example
+Form validation example with multiple independent form instances. Shows real-time validation and error handling.
+
+### Timer Example
+Multiple independent timers with millisecond precision demonstrating side effects and cleanup patterns.
+
+### Shopping Cart Example
+Shopping cart with product selection and quantity management. Shows how to handle derived state (total, itemCount) and complex state updates.
+
+---
+
 This comprehensive documentation covers all exported APIs from the react-state-custom library with detailed descriptions, type information, and practical examples.

package/README.md

@@ -4,10 +4,16 @@
 
 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.
 
+[![Demo](https://img.shields.io/badge/Demo-Live-blue?style=flat-square)](https://vothanhdat.github.io/react-state-custom/)
+[![npm version](https://img.shields.io/npm/v/react-state-custom?style=flat-square)](https://www.npmjs.com/package/react-state-custom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
 ```bash
 npm install react-state-custom
 ```
 
+🎮 **[Try the Live Demo →](https://vothanhdat.github.io/react-state-custom/)**
+
 ## Why React State Custom?
 
 **Zero Boilerplate** • **Type-Safe** • **Selective Re-renders** • **Hook-Based** • **~10KB Bundle**
@@ -105,7 +111,7 @@ Full type inference and type safety throughout. Your IDE knows exactly what's in
 | **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 |
+| **DevTools** | ✅ Built-in UI | ✅ Redux DevTools | ✅ DevTools support |
 | **Async Support** | ✅ Native (hooks) | ⚠️ Requires middleware | ✅ Native |
 | **Context Composition** | ✅ Automatic | ❌ Manual | ⚠️ Manual store combination |
 
@@ -243,6 +249,36 @@ const { useCtxState } = createAutoCtx(rootContext);
 
 ## 🚀 Advanced Features
 
+### Developer Tools
+Visual debugging component to inspect all your context data in real-time:
+
+```typescript
+import { DevToolContainer } from 'react-state-custom';
+import 'react-state-custom/dist/react-state-custom.css';
+
+function App() {
+  return (
+    <>
+      <AutoRootCtx />
+      <YourAppContent />
+      <DevToolContainer />
+    </>
+  );
+}
+```
+
+**Custom data viewer with rich object visualization:**
+```typescript
+import { DataViewComponent } from 'react-state-custom';
+import { ObjectView } from 'react-obj-view';
+
+const CustomDataView: DataViewComponent = ({ name, value }) => {
+  return <ObjectView name={name} value={value} expandLevel={2} />;
+};
+
+<DevToolContainer Component={CustomDataView} />
+```
+
 ### Parameterized Contexts
 Create multiple instances of the same state with different parameters:
 
@@ -285,10 +321,42 @@ const userStats = useDataSubscribeWithTransform(
 );
 ```
 
+## 🎮 Live Examples
+
+Explore interactive examples in the **[Live Demo](https://vothanhdat.github.io/react-state-custom/)**:
+
+- **Counter** - Basic state management with increment, decrement, and reset
+- **Todo List** - Multiple independent lists with scoped contexts
+- **Form Validation** - Real-time validation with error handling
+- **Timer** - Side effects and cleanup with millisecond precision
+- **Shopping Cart** - Complex state with derived values (total, itemCount)
+
+Each example includes live code editing with syntax highlighting, powered by Sandpack!
+
 ## 📖 Documentation
 
 For complete API documentation, examples, and advanced patterns, see:
 - **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference
+- **[Live Demo](https://vothanhdat.github.io/react-state-custom/)** - Interactive examples
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Run dev server with examples
+yarn dev
+
+# Build library
+yarn build
+
+# Build demo site
+yarn build:demo
+
+# Preview demo locally
+yarn preview
+```
 
 ## 🎓 Learning Path
 

package/dist/dev-tool/DataViewComponent.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+export type DataViewComponent = React.FC<{
+    value: any;
+    name: string;
+}>;
+export declare const DataViewDefault: DataViewComponent;

package/dist/dev-tool/DevTool.d.ts

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

package/dist/dev-tool/DevToolState.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { DataViewComponent } from './DataViewComponent';
+export declare const DevToolState: React.FC<{
+    Component: DataViewComponent;
+}>;
+export declare const StateView: React.FC<{
+    dataKey: string;
+    Component: DataViewComponent;
+}>;

package/dist/dev-tool/StateLabelRender.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare const StateLabelRender: React.FC<any>;

package/dist/dev-tool/useHighlight.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export declare function useHighlight(filterString: string): {
+    highlight: RegExp;
+};
+export declare const HightlightWrapper: React.FC<{
+    highlight: string;
+    children: any;
+}>;
+export declare const HighlightString: React.FC<{
+    text: string;
+}>;

package/dist/dev.d.ts

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

package/dist/examples/Playground.d.ts

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

package/dist/examples/cart/app.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/examples/cart/index.d.ts

@@ -0,0 +1,3 @@
+export { CartExample, CartExample as default } from './view';
+export { useCartCtx, PRODUCTS } from './state';
+export type { CartItem } from './state';

package/dist/examples/cart/state.d.ts

@@ -0,0 +1,23 @@
+export interface CartItem {
+    id: string;
+    name: string;
+    price: number;
+    quantity: number;
+}
+export declare const PRODUCTS: {
+    id: string;
+    name: string;
+    price: number;
+}[];
+export declare const useCartCtx: (e: {
+    userId: string;
+}) => import('../../index').Context<{
+    userId: string;
+    items: CartItem[];
+    total: string;
+    itemCount: number;
+    addItem: (product: (typeof PRODUCTS)[0]) => void;
+    removeItem: (id: string) => void;
+    updateQuantity: (id: string, quantity: number) => void;
+    clear: () => void;
+}>;

package/dist/examples/cart/view.d.ts

@@ -0,0 +1,4 @@
+export declare const CartExample: ({ userId }: {
+    userId?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default CartExample;

package/dist/examples/counter/app.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/examples/counter/index.d.ts

@@ -0,0 +1,2 @@
+export { CounterExample, CounterExample as default } from './view';
+export { useCounterCtx } from './state';

package/dist/examples/counter/state.d.ts

@@ -0,0 +1,6 @@
+export declare const useCounterCtx: (e: object) => import('../../index').Context<{
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+}>;

package/dist/examples/counter/view.d.ts

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

package/dist/examples/form/app.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/examples/form/index.d.ts

@@ -0,0 +1,3 @@
+export { FormExample, FormExample as default } from './view';
+export { useFormCtx } from './state';
+export type { FormData } from './state';

package/dist/examples/form/state.d.ts

@@ -0,0 +1,16 @@
+export interface FormData {
+    name: string;
+    email: string;
+    age: string;
+}
+export declare const useFormCtx: (e: {
+    formId: string;
+}) => import('../../index').Context<{
+    formId: string;
+    data: FormData;
+    errors: Partial<FormData>;
+    submitted: boolean;
+    updateField: (field: keyof FormData, value: string) => void;
+    submit: () => void;
+    reset: () => void;
+}>;

package/dist/examples/form/view.d.ts

@@ -0,0 +1,4 @@
+export declare const FormExample: ({ formId }: {
+    formId?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default FormExample;

package/dist/examples/timer/app.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/examples/timer/index.d.ts

@@ -0,0 +1,2 @@
+export { TimerExample, TimerExample as default } from './view';
+export { useTimerCtx } from './state';

package/dist/examples/timer/state.d.ts

@@ -0,0 +1,11 @@
+export declare const useTimerCtx: (e: {
+    timerId: string;
+}) => import('../../index').Context<{
+    timerId: string;
+    milliseconds: number;
+    isRunning: boolean;
+    formattedTime: string;
+    start: () => void;
+    pause: () => void;
+    reset: () => void;
+}>;

package/dist/examples/timer/view.d.ts

@@ -0,0 +1,4 @@
+export declare const TimerExample: ({ timerId }: {
+    timerId?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default TimerExample;

package/dist/examples/todo/app.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/examples/todo/index.d.ts

@@ -0,0 +1,3 @@
+export { TodoExample, TodoExample as default } from './view';
+export { useTodoCtx } from './state';
+export type { Todo } from './state';

package/dist/examples/todo/state.d.ts

@@ -0,0 +1,17 @@
+export interface Todo {
+    id: string;
+    text: string;
+    completed: boolean;
+}
+export declare const useTodoCtx: (e: {
+    listId: string;
+}) => import('../../index').Context<{
+    listId: string;
+    todos: Todo[];
+    input: string;
+    setInput: import('react').Dispatch<import('react').SetStateAction<string>>;
+    addTodo: () => void;
+    toggleTodo: (id: string) => void;
+    removeTodo: (id: string) => void;
+    clearCompleted: () => void;
+}>;

package/dist/examples/todo/view.d.ts

@@ -0,0 +1,4 @@
+export declare const TodoExample: ({ listId }: {
+    listId?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default TodoExample;

package/dist/index.d.ts

@@ -3,4 +3,5 @@ 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';
+export { DevToolContainer } from './dev-tool/DevTool';
+export type { DataViewComponent } from './dev-tool/DataViewComponent';