# @rythazhur/mizan (TypeScript)

React client for the mizan framework. See the [monorepo root](../README.md) for full documentation.

## Install

```bash
npm install @rythazhur/mizan@git+https://git.impactsoundworks.com/isw/mizan.git#workspace=react
```

## Usage

You don't use this package directly. You use the **generated hooks**.

### 1. Configure

```js
// django.config.mjs
export default {
    source: {
        django: {
            managePath: '../backend/manage.py',
            command: ['uv', 'run', 'python'],
        },
    },
    output: 'src/api/generated.ts',
}
```

### 2. Generate

```bash
npx mizan-generate        # once
npx mizan-generate --watch # dev mode
```

### 3. Wrap your app

```tsx
import { DjangoContext } from '@/api'

<DjangoContext>
    <App />
</DjangoContext>
```

`DjangoContext` is the only provider you need. It handles HTTP, WebSocket, CSRF, session init, context auto-fetching, and channel connections.

### 4. Use generated hooks

```tsx
import { useCurrentUser, useEcho, useContactForm, useChatChannel } from '@/api'

// Context (SSR-hydrated, auto-refreshed)
const user = useCurrentUser()

// Server function
const echo = useEcho()
const result = await echo({ text: 'hello' })

// Form (Zod + server validation)
const form = useContactForm()
form.set('email', 'test@example.com')
await form.submit()

// Channel (WebSocket)
const chat = useChatChannel({ room: 'general' })
chat.send({ text: 'hello' })
chat.messages  // typed, reactive
```

## Generated Files

| File | Contents |
|------|----------|
| `generated.django.tsx` | `DjangoContext` + typed hooks |
| `generated.mizan.ts` | Pydantic types |
| `generated.forms.ts` | Form hooks with Zod |
| `generated.channels.hooks.tsx` | Channel hooks |
| `index.ts` | Re-exports everything |

## Sub-exports

| Import | When to use |
|--------|------------|
| `@rythazhur/mizan` | Core: mizanProvider, hooks, forms, errors |
| `@rythazhur/mizan/channels` | WebSocket channels |
| `@rythazhur/mizan/jwt` | JWT token management |
| `@rythazhur/mizan/client` | HTTP clients (CSR/SSR) |
| `@rythazhur/mizan/allauth` | Allauth UI components |

These are **library internals** used by the generated code. You should import from `@/api` (your generated index), not from the library directly.

## Running Tests

```bash
# Unit tests (Vitest, jsdom)
npm test

# E2E tests (Playwright, real browser)
# Requires Docker backend running
npx playwright test
```
