@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.4

package/README.md

@@ -0,0 +1,112 @@
+# @mmapp/react
+
+React hooks, components, and runtime bridge for building MindMatrix workflow applications.
+
+Published on npm as `@mmapp/react` (internal workspace name: `@mindmatrix/react`).
+
+## Installation
+
+```bash
+npm install @mmapp/react @mmapp/player-core
+```
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useQuery(slug)` | Fetch workflow instances by slug |
+| `useMutation(slug)` | Create, update, transition workflow instances |
+| `usePlayer(definition)` | Run a state machine in the browser |
+| `useRouter()` | Blueprint-aware navigation |
+| `useAuth()` | Authentication state |
+| `useToast()` | Toast notifications |
+| `useForm(fields)` | Form state management with validation |
+| `useChannel(name)` | Real-time WebSocket channels |
+| `useRole(slug)` | Role-based access control |
+| `useComputed(expr)` | Computed field evaluation |
+| `useModel(definition)` | Type-safe model access |
+| `useModule(slug)` | Module configuration |
+| `useServerAction(name)` | Server-side action execution |
+| `useServerState(slug)` | Server-synced state |
+
+## Configuration
+
+### defineBlueprint
+
+```typescript
+import { defineBlueprint } from '@mmapp/react';
+
+export default defineBlueprint({
+  slug: 'my-app',
+  name: 'My App',
+  version: '1.0.0',
+  models: [employeeModel, departmentModel],
+  views: {
+    '/': HomePage,
+    '/employees': EmployeeList,
+    '/employees/:id': EmployeeDetail,
+  },
+});
+```
+
+### defineModel
+
+```typescript
+import { defineModel } from '@mmapp/react';
+
+export default defineModel({
+  slug: 'employee',
+  fields: {
+    name: { type: 'string', required: true },
+    salary: { type: 'number', default: 0 },
+    department: { type: 'string' },
+  },
+  states: {
+    active: { type: 'initial' },
+    terminated: { type: 'terminal' },
+  },
+  transitions: {
+    terminate: { from: ['active'], to: 'terminated' },
+  },
+});
+```
+
+## Atoms
+
+Pre-built UI components available via `@mmapp/react/atoms`:
+
+```typescript
+import { Box, Text, Button, Input, Select, Modal, Card } from '@mmapp/react/atoms';
+```
+
+## npm Publishing
+
+This package is published to npm under the `@mmapp` scope.
+
+| npm name | workspace name | current version |
+|----------|---------------|-----------------|
+| `@mmapp/react` | `@mindmatrix/react` | 0.1.0-alpha.1 |
+
+### Publishing a new version
+
+Use the publish script from the monorepo root:
+
+```bash
+# Publish all 3 packages (player-core, react, react-compiler)
+./scripts/publish-npm.sh patch   # 0.1.0-alpha.1 → 0.1.0-alpha.2
+./scripts/publish-npm.sh minor   # 0.1.0-alpha.1 → 0.2.0-alpha.1
+./scripts/publish-npm.sh 0.2.0-beta.1  # explicit version
+```
+
+Or publish just this package:
+
+```bash
+cd packages/react
+pnpm run publish:alpha          # auto-increments alpha version
+```
+
+### Version strategy
+
+- `0.1.0-alpha.X` — internal development (current)
+- `0.1.0-beta.X` — user testing
+- `1.0.0` — production launch