@better-state/react 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Better-State Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# @better-state/react
+
+React hooks for [Better-State](https://github.com/Nathanim1919/better-state). Real-time synced state with one line of code.
+
+## Installation
+
+```bash
+npm install @better-state/client @better-state/react
+# or
+pnpm add @better-state/client @better-state/react
+```
+
+Requires React 18+ and a running [`@better-state/server`](https://www.npmjs.com/package/@better-state/server).
+
+## Quick Start
+
+```tsx
+import { BetterStateProvider, useBetterState } from '@better-state/react'
+
+function App() {
+  return (
+    <BetterStateProvider
+      url="http://localhost:3001"
+      options={{ apiKey: 'your-api-key' }}
+    >
+      <Counter />
+    </BetterStateProvider>
+  )
+}
+
+function Counter() {
+  const [count, setCount, updateCount] = useBetterState('counter', 0)
+
+  return (
+    <div>
+      <h1>{count}</h1>
+      <button onClick={() => updateCount(n => n + 1)}>+1</button>
+      <button onClick={() => updateCount(n => n - 1)}>-1</button>
+      <button onClick={() => setCount(0)}>Reset</button>
+    </div>
+  )
+}
+```
+
+Open the same page in two tabs. The counter syncs in real-time.
+
+## API
+
+### `<BetterStateProvider>`
+
+Wraps your app and creates a single Better-State client for the component tree.
+
+```tsx
+<BetterStateProvider
+  url="http://localhost:3001"
+  options={{
+    apiKey: string,       // required
+    namespace?: string,   // default: 'default'
+    debug?: boolean,      // default: false
+  }}
+>
+  {children}
+</BetterStateProvider>
+```
+
+Place it once at the root of your app (or per-feature if you need multiple servers).
+
+### `useBetterState(key, initialValue)`
+
+Synced state hook. Works like `useState`, but the value is shared across all connected clients.
+
+```tsx
+const [value, set, update] = useBetterState('my-key', initialValue)
+```
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `value` | `T` | Current value (reactive) |
+| `set` | `(value: T) => void` | Replace the value |
+| `update` | `(fn: (prev: T) => T) => void` | Transform the value |
+
+Updates are **optimistic** — the UI updates instantly, then syncs to the server in the background.
+
+```tsx
+function TodoList() {
+  const [todos, setTodos, updateTodos] = useBetterState('todos', [])
+
+  const addTodo = (text: string) => {
+    updateTodos(list => [...list, { id: crypto.randomUUID(), text, done: false }])
+  }
+
+  const toggleTodo = (id: string) => {
+    updateTodos(list =>
+      list.map(t => t.id === id ? { ...t, done: !t.done } : t)
+    )
+  }
+
+  return (
+    <ul>
+      {todos.map(t => (
+        <li key={t.id} onClick={() => toggleTodo(t.id)}>
+          {t.done ? '✓' : '○'} {t.text}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### `useConnectionStatus()`
+
+Returns the current connection status. Re-renders when it changes.
+
+```tsx
+import { useConnectionStatus } from '@better-state/react'
+
+function StatusIndicator() {
+  const status = useConnectionStatus()
+
+  return (
+    <span>
+      {status === 'connected' && 'Online'}
+      {status === 'connecting' && 'Connecting...'}
+      {status === 'disconnected' && 'Offline'}
+    </span>
+  )
+}
+```
+
+Returns: `'connecting' | 'connected' | 'disconnected'`
+
+### `useBetterStateClient()`
+
+Returns the underlying `BetterStateClient` instance for advanced use cases (disconnect, error handling, conflict listeners).
+
+```tsx
+import { useBetterStateClient } from '@better-state/react'
+
+function Settings() {
+  const client = useBetterStateClient()
+
+  useEffect(() => {
+    const unsub = client.onError(err => {
+      console.error(err.code, err.message)
+    })
+    return unsub
+  }, [client])
+
+  return <button onClick={() => client.disconnect()}>Disconnect</button>
+}
+```
+
+## Full Example
+
+```tsx
+import { BetterStateProvider, useBetterState, useConnectionStatus } from '@better-state/react'
+
+function App() {
+  return (
+    <BetterStateProvider
+      url="http://localhost:3001"
+      options={{ apiKey: 'your-api-key' }}
+    >
+      <StatusBar />
+      <Counter />
+    </BetterStateProvider>
+  )
+}
+
+function StatusBar() {
+  const status = useConnectionStatus()
+  return <div>{status === 'connected' ? 'Online' : 'Offline'}</div>
+}
+
+function Counter() {
+  const [count, , updateCount] = useBetterState('counter', 0)
+  return (
+    <div>
+      <h1>{count}</h1>
+      <button onClick={() => updateCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+
+export default App
+```
+
+## Peer Dependencies
+
+- `react` >= 18.0.0
+- `@better-state/client` >= 0.1.0
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-state/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React hooks for Better-State — real-time synced state with one line of code",
   "type": "module",
   "main": "dist/index.js",
@@ -11,8 +11,18 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
-  "keywords": ["react", "hooks", "state", "sync", "realtime", "websocket", "better-state"],
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "hooks",
+    "state",
+    "sync",
+    "realtime",
+    "websocket",
+    "better-state"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,19 +32,27 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
     "@better-state/client": ">=0.1.0",
     "react": ">=18.0.0"
   },
   "devDependencies": {
-    "@better-state/client": "workspace:*",
+    "@better-state/server": "^0.3.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.2.3",
+    "happy-dom": "^20.7.0",
     "react": "^19.0.0",
-    "typescript": "^5.7.0"
+    "react-dom": "^19.2.4",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "@better-state/client": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
   }
-}
+}