@mdxui/do 3.0.0 → 4.0.0

package/README.md

@@ -3,33 +3,19 @@
 [![npm version](https://img.shields.io/npm/v/@mdxui/do.svg)](https://www.npmjs.com/package/@mdxui/do)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Admin interface for the .do platform - manage Durable Objects and Things with a full dashboard shell.
-
-## What is @mdxui/do?
-
-`@mdxui/do` provides a React-based admin interface for the [.do platform](https://do.md). It includes a complete dashboard shell with routing, authentication (WorkOS AuthKit), and multiple view experiences: data browser, spreadsheet-style grid, document editor, and function executor. The library uses capnweb for RPC communication and `@mdxui/admin` for UI components.
+React components and hooks for building admin interfaces for .do Durable Objects.
 
 ## Installation
 
 ```bash
-npm install @mdxui/do
-# or
 pnpm add @mdxui/do
-# or
-yarn add @mdxui/do
-```
-
-### Peer Dependencies
-
-```bash
-npm install react react-dom
 ```
 
 ## Quick Start
 
-### Complete Admin App
+### Full Admin Dashboard
 
-The easiest way to get started is with the `DOApp` component:
+Use `DOApp` for a complete admin experience with routing and authentication:
 
 ```tsx
 import { DOApp } from '@mdxui/do/app'
@@ -45,43 +31,31 @@ function App() {
           realTimeUpdates: false,
         },
         identity: {
-          clientId: 'client_xxx',
+          clientId: 'client_xxx', // WorkOS client ID
           devMode: true,
         },
-        branding: {
-          name: 'My Admin',
-        },
-        defaultNamespace: 'production',
       }}
     />
   )
 }
 ```
 
-This provides a complete admin experience with:
-- Dashboard shell with sidebar navigation
-- WorkOS AuthKit authentication
-- URL-based routing (Things, Databases, Functions, etc.)
-- Multiple view modes (browser, grid, document, function)
+### Custom UI with Provider
 
-### Using the Provider Directly
-
-For custom UIs, wrap your app with `DOProvider`:
+For custom UIs, use `DOProvider` directly:
 
 ```tsx
-import { DOProvider, useThings, useCreateThing } from '@mdxui/do'
+import { DOProvider, useThings } from '@mdxui/do'
 
 function App() {
   return (
     <DOProvider
       config={{
         apiEndpoint: 'https://api.example.do',
-        authMethod: 'jwt',
-        authToken: 'your-token',
+        authMethod: 'none',
         bindings: [],
         realTimeUpdates: false,
       }}
-      initialNamespace="default"
     >
       <TaskList />
     </DOProvider>
@@ -89,11 +63,9 @@ function App() {
 }
 
 function TaskList() {
-  const { data, isLoading, error } = useThings({ type: 'Task' })
-  const createThing = useCreateThing()
+  const { data, isLoading } = useThings({ type: 'Task' })
 
   if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
 
   return (
     <ul>
@@ -105,293 +77,126 @@ function TaskList() {
 }
 ```
 
-### Using the RPC Client Directly
-
-Access the capnweb client instance for direct RPC calls:
-
-```tsx
-import { useDO, useDOClient } from '@mdxui/do'
-
-function MyComponent() {
-  const { client, isConnected } = useDO()
-  // or just: const client = useDOClient()
-
-  const fetchData = async () => {
-    // Promise pipelining - efficient batched RPC calls
-    const [users, projects] = await Promise.all([
-      client.Thing.list({ type: 'User' }),
-      client.Thing.list({ type: 'Project' }),
-    ])
-    return { users, projects }
-  }
-}
-```
-
-## Shell Components
+## Views
 
-### DOApp
-
-Complete routed application with authentication and navigation:
+Four view components for managing Things:
 
 ```tsx
-import { DOApp } from '@mdxui/do/app'
-
-<DOApp config={shellConfig} />
+import {
+  DataBrowserView,   // Browse/search with filtering
+  DataGridView,      // Spreadsheet-style editing
+  DocumentEditorView, // Form-based editing
+  FunctionEditorView  // Execute functions
+} from '@mdxui/do/views'
 ```
 
-### DOShell
+## Hooks
 
-Dashboard shell layout for custom routing setups:
+### Data Fetching
 
 ```tsx
-import { DOShell, DOShellNav } from '@mdxui/do/app'
-
-<DOShell>
-  <YourContent />
-</DOShell>
-```
+import { useThings, useThing, useCreateThing } from '@mdxui/do'
 
-### AuthGate
+// List things
+const { data } = useThings({ type: 'Task' })
 
-Authentication guard that shows sign-in when unauthenticated:
+// Get single thing
+const { data } = useThing({ ns: 'default', type: 'Task', id: 'task-1' })
 
-```tsx
-import { AuthGate } from '@mdxui/do/app'
-
-<AuthGate>
-  <ProtectedContent />
-</AuthGate>
+// Create thing
+const create = useCreateThing()
+create.mutate({ ns: 'default', type: 'Task', name: 'New Task', data: {} })
 ```
 
-## View Modes
-
-`@mdxui/do` provides four view experiences for managing Things:
-
-| View | Component | Description |
-|------|-----------|-------------|
-| **Data Browser** | `DataBrowserView` | Browse and search Things with filtering and sorting |
-| **Data Grid** | `DataGridView` | Spreadsheet-style editing with inline cell editing |
-| **Document Editor** | `DocumentEditorView` | Form-based editing for individual Things |
-| **Function Editor** | `FunctionEditorView` | Execute code/functions against the DO |
+### Discovery
 
 ```tsx
-import { DataBrowserView, DataGridView, DocumentEditorView } from '@mdxui/do/views'
+import { useNamespaces, useTypes, useSchema } from '@mdxui/do'
 
-// Use individual views in your own layout
-function CustomAdmin() {
-  return (
-    <DOProvider config={config}>
-      <DataBrowserView />
-    </DOProvider>
-  )
-}
+const { data: namespaces } = useNamespaces()
+const { data: types } = useTypes()
+const { data: schema } = useSchema('Task')
 ```
 
-## Core Concepts
-
-### Things
+### State Management
 
-Things are semantic entities (nouns) that form the foundation of your data model:
-
-- **Namespace (`ns`)**: Tenant or domain isolation
-- **Type**: Entity classification (e.g., `"Task"`, `"User"`)
-- **ID**: Unique identifier within namespace/type
-- **Data**: JSON-LD compatible payload
+Endpoint and namespace state is managed via TanStack Query with localStorage persistence:
 
 ```tsx
-import { useThings, useThing, useCreateThing } from '@mdxui/do'
-
-// Fetch multiple Things with filtering
-const { data } = useThings({ type: 'Task', nameSearch: 'urgent' })
-
-// Fetch a single Thing
-const { data: task } = useThing('default', 'Task', 'task-123')
+import { useDOState, useEndpoint, useSetEndpoint } from '@mdxui/do'
 
-// Create a new Thing
-const createThing = useCreateThing()
-createThing.mutate({
-  ns: 'default',
-  type: 'Task',
-  name: 'New Task',
-  data: { priority: 'high' },
+// Combined hook for all state
+const { endpoint, setEndpoint, namespace, setNamespace, recentEndpoints } = useDOState({
+  endpoint: 'https://api.example.do', // Required: fallback from config
 })
-```
-
-### Schema Discovery
-
-Automatically discover available types and their schemas:
-
-```tsx
-import { useSchema, useTypes, useNamespaces } from '@mdxui/do'
 
-// Get all namespaces
-const { data: namespaces } = useNamespaces()
-
-// Get all types in a namespace
-const { data: types } = useTypes({ namespace: 'default' })
-
-// Get schema for a specific type
-const { data: schema } = useSchema('Task')
+// Or use individual hooks
+const endpoint = useEndpoint('https://api.example.do')
+const { mutate: setEndpoint } = useSetEndpoint()
 ```
 
-### Real-time Subscriptions
+State persists across sessions via localStorage and automatically invalidates data queries when the endpoint changes.
 
-Subscribe to Thing changes for real-time updates:
+## Architecture
 
-```tsx
-import { useThingSubscription, useSingleThingSubscription } from '@mdxui/do'
-
-// Subscribe to all Things of a type
-useThingSubscription({
-  type: 'Task',
-  onEvent: (event) => {
-    console.log('Thing changed:', event)
-  },
-})
+`DOApp` provides a complete admin dashboard with:
 
-// Subscribe to a single Thing
-useSingleThingSubscription({
-  ns: 'default',
-  type: 'Task',
-  id: 'task-123',
-  onEvent: (event) => {
-    console.log('Task updated:', event)
-  },
-})
-```
+- **TanStack Router** for client-side navigation
+- **WorkOS AuthKit** for authentication
+- **TanStack Query** for data fetching/caching
+- **capnweb** for WebSocket RPC to Durable Objects
 
-## Configuration
+The auth flow:
+1. User signs in via WorkOS
+2. Access token is passed to `DOProvider`
+3. RPC calls include token as `?token=` query param
+4. Backend validates JWT
 
-### DOShellConfig
+## Configuration
 
-Configuration for the complete `DOApp`:
+### DOAdminConfig (for DOProvider)
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `do` | `DOAdminConfig` | Yes | RPC and API configuration |
-| `identity` | `DOIdentity` | Yes | WorkOS AuthKit configuration |
-| `basePath` | `string` | No | Base URL path for routing |
-| `defaultNamespace` | `string` | No | Initial namespace |
-| `branding` | `{ name?, logo? }` | No | Custom branding |
-| `theme` | `{ mode? }` | No | Theme preference (light/dark/system) |
-| `routes` | `Record<string, boolean>` | No | Enable/disable specific routes |
-
-### DOAdminConfig
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `apiEndpoint` | `string` | Yes | - | Base URL for API calls |
-| `rpcUrl` | `string` | No | `${apiEndpoint}/rpc` | Explicit RPC URL for capnweb session |
-| `authMethod` | `'none' \| 'jwt' \| 'api-key' \| 'oauth'` | Yes | - | Authentication method |
-| `authToken` | `string` | No | - | JWT token or API key |
-| `bindings` | `DOBinding[]` | Yes | - | Durable Object bindings |
-| `realTimeUpdates` | `boolean` | Yes | - | Enable real-time updates via RPC subscriptions |
-| `clientType` | `'capnweb' \| 'json-rpc'` | No | `'capnweb'` | RPC client type |
-| `requestTimeout` | `number` | No | `30000` | Request timeout in ms |
-| `skipHealthCheck` | `boolean` | No | `false` | Skip health check on connection |
-| `healthCheckRetries` | `number` | No | `3` | Number of health check retries |
-
-### DOIdentity
+| `apiEndpoint` | `string` | Yes | Base URL for API |
+| `authMethod` | `'none' \| 'jwt' \| 'api-key'` | Yes | Auth method |
+| `authToken` | `string` | No | JWT or API key |
+| `bindings` | `DOBinding[]` | Yes | DO bindings |
+| `realTimeUpdates` | `boolean` | Yes | Enable subscriptions |
+| `clientType` | `'capnweb' \| 'json-rpc'` | No | RPC client type |
+
+### DOShellConfig (for DOApp)
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `clientId` | `string` | Yes | WorkOS client ID |
-| `apiHostname` | `string` | No | WorkOS API hostname |
-| `devMode` | `boolean` | No | Enable development mode |
-| `redirectUri` | `string` | No | OAuth redirect URI |
+| `do` | `DOAdminConfig` | Yes | API config |
+| `identity` | `DOIdentity` | Yes | WorkOS auth config |
+| `branding` | `{ name?, logo? }` | No | Branding |
+| `basePath` | `string` | No | URL base path |
 
-## Available Hooks
-
-### Context Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useDO()` | Access DO context (config, namespace, client, connection state) |
-| `useDOClient()` | Access the capnweb client instance directly |
-| `useDOUrls()` | Get derived URLs (rpcUrl, apiEndpoint) |
-| `useIdentity()` | Access WorkOS auth state (from AuthKit) |
-| `useDOShell()` | Access shell config and navigation state |
-
-### Things Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useThings(filter?)` | Fetch paginated Things with filtering |
-| `useThing(ns, type, id)` | Fetch a single Thing |
-| `useThingVersions(ns, type, id)` | Fetch version history for a Thing |
-| `useTypeStats(type)` | Fetch statistics for a Thing type |
-| `useCreateThing()` | Create a new Thing |
-| `useUpdateThing(ns, type, id)` | Update an existing Thing |
-| `useDeleteThing(ns, type, id)` | Delete a Thing |
-
-### Discovery Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useSchema(type)` | Get schema for a Thing type |
-| `useSchemaDefinition(type)` | Get detailed schema definition |
-| `useNamespaces()` | List available namespaces |
-| `useTypes(options?)` | List available Thing types |
-
-### Subscription Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useThingSubscription(options)` | Subscribe to Thing changes |
-| `useSingleThingSubscription(options)` | Subscribe to a single Thing |
-
-## Subpath Exports
+## Exports
 
 ```tsx
-// Full package - types, providers, hooks, components, views, app
+// Main
 import { DOProvider, useThings, DOApp } from '@mdxui/do'
 
-// App components - DOApp, DOShell, pages, routes
-import { DOApp, DOShell, DOShellNav, AuthGate } from '@mdxui/do/app'
+// App (routing, shell, auth)
+import { DOApp, DOShell, AuthGate } from '@mdxui/do/app'
 
-// Providers - DOProvider and context hooks
-import { DOProvider, useDO, useDOClient } from '@mdxui/do/providers'
+// Providers
+import { DOProvider, useDO } from '@mdxui/do/providers'
 
-// Hooks - all data fetching hooks
-import { useThings, useSchema, useNamespaces } from '@mdxui/do/hooks'
+// Hooks
+import { useThings, useCreateThing } from '@mdxui/do/hooks'
 
-// Things-specific hooks
-import { useThings, useCreateThing } from '@mdxui/do/hooks/things'
+// State (TanStack Query-based)
+import { useDOState, useEndpoint, useSetEndpoint, useNamespace } from '@mdxui/do'
 
-// Views - the 4 view experiences
+// Views
 import { DataBrowserView, DataGridView } from '@mdxui/do/views'
 
-// Components - UI components
-import { ErrorBoundary } from '@mdxui/do/components'
-
-// Types - TypeScript types
-import type { Thing, DOAdminConfig, ThingFilter } from '@mdxui/do/types'
-
-// Schemas - Zod schemas for validation
-import { ThingSchema, ThingFilterSchema } from '@mdxui/do/schemas'
-
-// Lib - utilities
-import { cn, formatDate, APIError } from '@mdxui/do/lib'
-```
-
-## Architecture
-
-```
-@mdxui/do
-├── app/           # DOApp, DOShell, pages, routes, auth
-├── providers/     # DOProvider, context hooks
-├── hooks/         # Data fetching hooks (Things, Schema, etc.)
-├── views/         # View components (Browser, Grid, Document, Function)
-├── components/    # Shared UI components
-├── types/         # TypeScript types + Zod schemas
-└── lib/           # Utilities (cn, errors, formatters)
-
-Dependencies:
-├── capnweb              # Binary RPC over HTTP
-├── @workos-inc/authkit  # Authentication
-├── @mdxui/admin         # UI components
-├── @mdxui/primitives    # Base UI primitives
-└── @tanstack/react-query # Data fetching & caching
+// Types
+import type { Thing, DOAdminConfig } from '@mdxui/do/types'
 ```
 
 ## License