@thefoxieflow/signal-ctx 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,379 @@
+# signal-ctx
+
+A tiny, signal-based state utility for React that **solves the `useContext` re-render problem** using
+**`useSyncExternalStore`**.
+
+If you’ve ever had this issue:
+
+```ts
+{ count, book }
+// updating count re-renders book components 😡
+```
+
+`signal-ctx` is designed specifically to fix that.
+
+---
+
+## ✨ Why signal-ctx?
+
+### ❌ The Problem with `useContext`
+
+React Context subscribes to the **entire value**.
+
+```tsx
+const { book } = useContext(StoreCtx)
+```
+
+When **any property changes**, **every consumer re-renders** — even if they don’t use it.
+
+This is not a bug. Context has **no selector mechanism**.
+
+---
+
+### ✅ The Solution
+
+`signal-ctx`:
+
+* Moves state **outside React**
+* Uses **external subscriptions**
+* Allows **selector-based updates**
+
+So only the components that *actually use* the changed data re-render.
+
+---
+
+## ✨ Features
+
+* ⚡ Signal-style state container
+* 🎯 Selector-based subscriptions
+* 🧵 React 18 concurrent-safe
+* 🧩 Context-backed but not context-driven
+* 📦 Very small bundle size
+* 🌳 Tree-shakable
+* 🧠 Explicit and predictable
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @thefoxieflow/signal-ctx
+```
+
+> **Peer dependency:** React 18+
+
+---
+
+## 🧠 Core Idea
+
+Context **does not store state**.
+
+It stores a **stable signal reference**.
+
+```tsx
+<Provider value={store} />
+```
+
+The state lives **outside React**, and components subscribe **directly to the signal**.
+
+---
+
+## 🔹 Signal Store
+
+A signal is:
+
+* A function that returns state
+* Can be subscribed to
+* Can be updated imperatively
+
+```ts
+type Store<T> = {
+  (): T
+  subscribe(fn: () => void): () => void
+  set(action: SetStateAction<T>): void
+}
+```
+
+---
+
+## 🔹 Low-Level Hooks
+
+### `createStore(()=>{})`
+
+### `useStoreValue(store, selector?)`
+
+Subscribe to a signal.
+
+```tsx
+const count = useStoreValue(store, s => s.count)
+```
+
+* Uses `useSyncExternalStore`
+* Re-renders only when the selected value changes
+* Selector is optional
+
+---
+
+### `useSetStore(store, selector?)`
+
+Returns a setter function.
+
+```ts
+const set = useSetStore(store)
+
+set(prev => ({ ...prev, count: prev.count + 1 }))
+```
+
+Scoped update:
+
+```ts
+// book must be object for selector
+const setBook = useSetSignal(store, s => s.book)
+
+
+// put: update an object
+setBook({
+    title : "book"
+})
+
+// patch: update partially
+setBook((b)=>{
+    b.title = "book"
+})
+```
+
+⚠️ Updates are **mutation-based**. Spread manually if you want immutability.
+
+---
+
+## 🔹 Context-Based API
+
+### `createCtx(init)`
+
+Creates a **context-backed signal store hook**.
+
+```ts
+import { createCtx } from "@your-scope/signal-ctx"
+
+export const useStore = createCtx(() => ({
+  count: 0,
+  book: { title: "1984" }
+}))
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Create a Provider
+
+```tsx
+// use default initial value from useStore
+type Props = {
+  children: React.ReactNode
+}
+
+export function StoreProvider({ children }: Props) {
+  const Provider = useStore.provide()
+  return <Provider>{children}</Provider>
+}
+
+// overwrite value
+export function StoreProvider({ children }: Props) {
+  const Provider = useStore.provide({
+    value: {
+      count: 10,
+      book: { title: "Brave New World" }
+    }
+  })
+
+  return <Provider>{children}</Provider>
+}
+```
+
+```tsx
+<StoreProvider>
+  <App />
+</StoreProvider>
+```
+
+---
+
+### 2. Read only what you need
+
+```tsx
+function Count() {
+  const count = useStore(s => s.count)
+  return <div>{count}</div>
+}
+
+function Book() {
+  const book = useStore(s => s.book)
+  return <div>{book.title}</div>
+}
+```
+
+---
+
+### 3. Update state
+
+```tsx
+function Increment() {
+  const set = useStore.useSetter()
+
+  return (
+    <button onClick={() =>
+      set(s => ({ ...s, count: s.count + 1 }))
+    }>
+      +
+    </button>
+  )
+}
+```
+
+✅ Updating `count` **does NOT re-render** `Book`.
+
+---
+
+## 🧩 Why This Works
+
+* Context value never changes
+* React does not re-render on context updates
+* `useSyncExternalStore` compares selected snapshots
+* Only changed selectors trigger re-renders
+
+This is the **same model** used by:
+
+* Redux `useSelector`
+* Zustand selectors
+* React’s official external store docs
+
+---
+
+## ⚠️ Important Rule
+
+> **Never destructure the entire state.**
+> Always select the smallest possible slice.
+
+❌ Bad:
+
+```ts
+const state = useStore(s => s)
+```
+
+✅ Good:
+
+```ts
+const count = useStore(s => s.count)
+```
+
+---
+
+## 🧩 Multiple Stores
+
+You can create isolated stores using `storeName`.
+
+```tsx
+type Props = {
+  children: React.ReactNode
+  storeName: string
+  initialValue?: { count: number; book: { title: string } }
+}
+
+export function StoreProvider({ children, storeName, initialValue }: Props) {
+  const Provider = useStore.provide({
+    storeName,
+    value: initialValue || { count: 0, book: { title: "1984" } }
+  })
+
+  return <Provider>{children}</Provider>
+}
+```
+
+### Usage
+```tsx
+<StoreProvider storeName="storeA" initialValue={{ count: 1, book: { title: "A" } }}>
+  <AppA />
+  <StoreProvider storeName="storeB" initialValue={{ count: 5, book: { title: "B" } }}>
+    <AppB />
+  </StoreProvider>
+</StoreProvider>
+
+function AppB(){
+  // book from parent context; parent = "storeA" so book.title = "A"
+  const book = useStore(s => s.book)
+
+  // but i want a book from storeA; so it requires storeName
+  // book.title = "B"
+  const storeABook = useStore(s => s.book,{ storeName :"storeA" })
+
+  // same apply to setter
+  const setBookStoreA = useStore.useSetter((s)=>s.book, {storeName : "storeA"})
+
+  const handleClick = (text)=>{
+    setCountStoreA((s) => {
+       s.title = "change A to AA"
+       return s
+    })
+  }
+}
+```
+
+
+
+Each store is independent.
+
+---
+
+## 🌐 Server-Side Rendering (SSR)
+
+`signal-ctx` is SSR-safe.
+
+* Uses `useSyncExternalStore`
+* Identical snapshot logic on server & client
+* No shared global state between requests
+
+---
+
+## ⚠️ Caveats
+
+* No middleware
+* No devtools
+* No persistence
+* Mutation-based updates by design
+
+Best suited for:
+
+* UI state
+* App-level shared state
+* Lightweight global stores
+
+---
+
+## 🧪 TypeScript
+
+Fully typed with generics and inferred selectors.
+
+```ts
+const count = useStore(s => s.count) // number
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## ⭐ Philosophy
+
+`signal-ctx` is intentionally small.
+
+It favors:
+
+* Explicit ownership
+* Predictable updates
+* Minimal abstraction
+
+If you understand React, you understand `signal-ctx`.

package/dist/index.js

@@ -1,5 +1,4 @@
 "use strict";
-"use client";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/index.mjs

@@ -1,5 +1,3 @@
-"use client";
-
 // src/index.tsx
 import {
   createContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thefoxieflow/signal-ctx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight signal-based React context store",
   "main": "dist/index.cjs",
   "module": "dist/index.js",