@cero-base/react 0.0.1

package/README.md

@@ -0,0 +1,96 @@
+# @cero-base/react
+
+React hooks and providers for cero-base. Works with both `CeroBase` and `Client` (RPC) instances.
+
+## Install
+
+```bash
+npm install @cero-base/react
+```
+
+## Setup
+
+```jsx
+import { Cero, Room } from '@cero-base/react'
+
+function App() {
+  return (
+    <Cero value={db}>
+      <Room id={roomId}>
+        <Chat />
+      </Room>
+    </Cero>
+  )
+}
+```
+
+## Hooks
+
+### useCero()
+
+Access the db instance from context.
+
+```jsx
+const db = useCero()
+```
+
+### useRoom()
+
+Access the current Room from context.
+
+```jsx
+const room = useRoom()
+```
+
+### useCollection(name, query?)
+
+Subscribe to a collection. Returns live data + CRUD methods.
+
+- Local/private collections: uses `useCero()` context
+- Shared collections: requires `<Room>` provider
+
+```jsx
+const { data, put, del, get, sub } = useCollection('messages')
+```
+
+### useRooms()
+
+List all rooms. Re-fetches on update events.
+
+```jsx
+const { data: rooms } = useRooms()
+```
+
+### useMembers()
+
+Subscribe to room members. Requires `<Room>` provider.
+
+```jsx
+const { data: members } = useMembers()
+```
+
+### useProfile()
+
+Subscribe to identity profile. Returns profile data + setter.
+
+```jsx
+const { data: profile, set } = useProfile()
+await set({ name: 'Alice' })
+```
+
+## Exports
+
+| Export                | Description                          |
+| --------------------- | ------------------------------------ |
+| `Cero`                | Context provider — wraps db instance |
+| `Room`                | Context provider — wraps room by id  |
+| `useCero()`           | Access db from context               |
+| `useRoom()`           | Access room from context             |
+| `useProfile()`        | Subscribe to profile                 |
+| `useRooms()`          | Subscribe to room list               |
+| `useCollection(name)` | Subscribe to collection data         |
+| `useMembers()`        | Subscribe to room members            |
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cero-base/react",
+  "version": "0.0.1",
+  "description": "React hooks and providers for cero-base",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "brittle test/*.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@cero-base/core": "^0.0.1",
+    "@cero-base/rpc": "^0.0.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "brittle": "^3.7.0",
+    "global-jsdom": "^25.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "streamx": "^2.22.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "@simplestack/store": ">=0.7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@simplestack/store": {
+      "optional": true
+    }
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/react"
+  }
+}

package/src/CLAUDE.md

@@ -0,0 +1,3 @@
+<claude-mem-context>
+
+</claude-mem-context>

package/src/README.md

@@ -0,0 +1,89 @@
+# cero-base/react
+
+React hooks and providers for cero-base. Works with both direct Cero instances and RPC proxy clients.
+
+## Setup
+
+```jsx
+import { CeroProvider } from 'cero-base/react'
+
+const db = new Chats('./data')
+
+createRoot(root).render(
+  <CeroProvider value={db}>
+    <App />
+  </CeroProvider>
+)
+```
+
+## Hooks
+
+### useCero()
+
+Access the Cero instance from context.
+
+```jsx
+const db = useCero()
+```
+
+### useRoom()
+
+Access the current Room from context. Returns `null` if no `RoomProvider`.
+
+```jsx
+const room = useRoom()
+```
+
+### useCollection(name, query?)
+
+Subscribe to a collection. Returns live data + CRUD methods.
+
+- Local/private collections: uses `useCero()` context
+- Shared collections: requires `RoomProvider`
+
+```jsx
+const { data, loading, insert, update, remove, get } = useCollection('tasks')
+
+// With filter
+const { data: done } = useCollection('tasks', { done: true })
+```
+
+### useRooms()
+
+List all rooms. Re-fetches on 'update' events.
+
+```jsx
+const { data: rooms, loading } = useRooms()
+```
+
+### useMembers()
+
+Subscribe to room members. Requires `RoomProvider`.
+
+```jsx
+const { data: members, loading } = useMembers()
+```
+
+### useProfile()
+
+Subscribe to identity profile. Returns profile data + setter.
+
+```jsx
+const { data: profile, loading, set } = useProfile()
+await set({ name: 'Alice' })
+```
+
+## Room Context
+
+Wrap shared collection views with `RoomProvider`:
+
+```jsx
+import { RoomProvider } from 'cero-base/react'
+import { Room } from 'cero-base'
+
+const room = await Room.from(db, roomId)
+
+<RoomProvider value={room}>
+  <ChatView />  {/* useCollection('messages') works here */}
+</RoomProvider>
+```

package/src/hooks/index.js

@@ -0,0 +1,7 @@
+export * from './use-cero.js'
+export * from './use-query.js'
+export * from './use-client.jsx'
+export * from './use-profile.jsx'
+export * from './use-rooms.jsx'
+export * from './use-collection.jsx'
+export * from './use-members.jsx'

package/src/hooks/use-cero.js

@@ -0,0 +1,12 @@
+import { useContext } from 'react'
+import { CeroContext, RoomContext } from '../ui/context.js'
+
+export function useCero() {
+  const db = useContext(CeroContext)
+  if (!db) throw new Error('useCero requires <Cero> provider')
+  return db
+}
+
+export function useRoom() {
+  return useContext(RoomContext)
+}

package/src/hooks/use-client.jsx

@@ -0,0 +1,39 @@
+import { useState, useEffect, useRef } from 'react'
+import { Client, getRpc } from '@cero-base/rpc'
+
+export function useClient(setup, schema, spec) {
+  const [db, setDb] = useState(null)
+  const [ready, setReady] = useState(false)
+  const [error, setError] = useState(null)
+  const ref = useRef(null)
+
+  useEffect(() => {
+    let client = null
+
+    try {
+      const ctx = setup()
+      ref.current = ctx
+      const rpc = getRpc(ctx.pipe, spec)
+      client = new Client(rpc, schema, spec)
+
+      client
+        .ready()
+        .then(() => {
+          setDb(client)
+          setReady(true)
+        })
+        .catch((err) => setError('RPC ready failed: ' + (err.message || String(err))))
+    } catch (err) {
+      setError('Client setup failed: ' + (err.message || String(err)))
+    }
+
+    return () => {
+      try {
+        if (client) client.close()
+        if (ref.current?.destroy) ref.current.destroy()
+      } catch {}
+    }
+  }, [])
+
+  return { db, ready, error }
+}

package/src/hooks/use-collection.jsx

@@ -0,0 +1,30 @@
+import { useMemo, useCallback } from 'react'
+import { useCero, useRoom } from './use-cero.js'
+import { useQuery } from './use-query.js'
+import { SCOPE_SHARED } from '@cero-base/core/constants'
+
+export function useCollection(name, query, opts) {
+  const db = useCero()
+  const room = useRoom()
+  const scope = db.schema.getScope(name)
+
+  if (scope === SCOPE_SHARED && !room) {
+    throw new Error(`useCollection('${name}') requires <Room> provider (shared scope)`)
+  }
+
+  const owner = scope === SCOPE_SHARED ? room : db
+  const col = useMemo(() => owner.collection(name), [owner, name])
+  const queryKey = query ? JSON.stringify(query) : ''
+
+  const { data, busy, error } = useQuery(() => col.sub(query || {}, opts || {}), [col, queryKey])
+
+  return {
+    data: data || [],
+    busy,
+    error,
+    put: useCallback((doc) => col.put(doc), [col]),
+    del: useCallback((q) => col.del(q), [col]),
+    get: useCallback((q, o) => col.get(q, o), [col]),
+    sub: useCallback((q, o) => col.sub(q || {}, o || {}), [col])
+  }
+}

package/src/hooks/use-members.jsx

@@ -0,0 +1,11 @@
+import { useRoom } from './use-cero.js'
+import { useQuery } from './use-query.js'
+
+export function useMembers() {
+  const room = useRoom()
+  if (!room) throw new Error('useMembers requires <Room> provider')
+
+  const { data, busy, error } = useQuery(() => room.members.sub(), [room])
+
+  return { data: data || [], busy, error }
+}

package/src/hooks/use-profile.jsx

@@ -0,0 +1,9 @@
+import { useCallback } from 'react'
+import { useCero } from './use-cero.js'
+import { useQuery } from './use-query.js'
+
+export function useProfile() {
+  const db = useCero()
+  const { data, busy, error } = useQuery(() => db.profile.sub(), [db])
+  return { data, busy, error, set: useCallback((p) => db.profile.set(p), [db]) }
+}

package/src/hooks/use-query.js

@@ -0,0 +1,48 @@
+import { useEffect, useRef } from 'react'
+import { store } from '@simplestack/store'
+import { useStoreValue } from '@simplestack/store/react'
+
+/**
+ * useQuery — the primitive. Subscribes to a Readable stream, returns reactive data.
+ *
+ * All named hooks compose from this. Exported as escape hatch for custom subscriptions.
+ *
+ * Uses @simplestack/store as the reactive layer — signal-based, fine-grained updates.
+ * The store persists between mounts (stale-while-revalidate for free).
+ * Redundant updates are skipped via Object.is inside store.select().set().
+ *
+ * @param {Function} streamFn - Returns a Readable stream (from .sub())
+ * @param {Array} deps - Dependency array (re-subscribes when changed)
+ * @returns {{ data: any, busy: boolean, error: Error|null }}
+ */
+export function useQuery(streamFn, deps) {
+  const s = useRef(null)
+  const ref = useRef(null)
+  if (s.current === null) {
+    s.current = store({ data: null, busy: true, error: null })
+  }
+
+  useEffect(() => {
+    const st = s.current
+    st.select('busy').set(true)
+
+    const stream = streamFn()
+
+    stream.on('data', (d) => {
+      if (d === ref.current) return // skip redundant updates
+      ref.current = d
+      st.select('data').set(d)
+      st.select('busy').set(false)
+      st.select('error').set(null)
+    })
+
+    stream.on('error', (err) => {
+      st.select('error').set(err)
+      st.select('busy').set(false)
+    })
+
+    return () => stream.destroy()
+  }, deps) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return useStoreValue(s.current)
+}

package/src/hooks/use-rooms.jsx

@@ -0,0 +1,8 @@
+import { useCero } from './use-cero.js'
+import { useQuery } from './use-query.js'
+
+export function useRooms() {
+  const db = useCero()
+  const { data, busy, error } = useQuery(() => db.rooms.sub(), [db])
+  return { data: data || [], busy, error }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export * from './ui/index.js'
+export * from './hooks/index.js'

package/src/ui/cero.jsx

@@ -0,0 +1,19 @@
+import { useState, useEffect } from 'react'
+import { CeroContext } from './context.js'
+
+export function Cero({ value, children }) {
+  const [ready, setReady] = useState(value.opened)
+
+  useEffect(() => {
+    if (!value.opened)
+      value
+        .ready()
+        .then(() => setReady(true))
+        .catch(console.error)
+    else setReady(true)
+  }, [value])
+
+  if (!ready) return null
+
+  return <CeroContext.Provider value={value}>{children}</CeroContext.Provider>
+}

package/src/ui/context.js

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+
+export const CeroContext = createContext(null)
+export const RoomContext = createContext(null)

package/src/ui/index.js

@@ -0,0 +1,2 @@
+export * from './cero.jsx'
+export * from './room.jsx'

package/src/ui/room.jsx

@@ -0,0 +1,36 @@
+import { useState, useEffect, useRef } from 'react'
+import { RoomContext } from './context.js'
+import { useCero } from '../hooks/use-cero.js'
+
+export function Room({ id, children }) {
+  const db = useCero()
+  const [room, setRoom] = useState(null)
+  const roomRef = useRef(null)
+
+  useEffect(() => {
+    if (!id) return
+    let cancelled = false
+
+    db.rooms.open(id).then((r) => {
+      if (cancelled) {
+        r.close()
+        return
+      }
+      roomRef.current = r
+      setRoom(r)
+    })
+
+    return () => {
+      cancelled = true
+      if (roomRef.current) {
+        roomRef.current.close()
+        roomRef.current = null
+      }
+      setRoom(null)
+    }
+  }, [db, id])
+
+  if (!room) return null
+
+  return <RoomContext.Provider value={room}>{children}</RoomContext.Provider>
+}