@plures/praxis 1.0.2 → 1.1.0

package/docs/core/schema-model.md

@@ -64,12 +64,12 @@ Facts are typed propositions about your domain. They represent "what is true" af
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique identifier |
-| `tag` | string | Yes | Fact tag (used in code) |
-| `description` | string | Yes | Human-readable description |
-| `payload` | object | Yes | JSON Schema for fact payload |
+| Field         | Type   | Required | Description                  |
+| ------------- | ------ | -------- | ---------------------------- |
+| `id`          | string | Yes      | Unique identifier            |
+| `tag`         | string | Yes      | Fact tag (used in code)      |
+| `description` | string | Yes      | Human-readable description   |
+| `payload`     | object | Yes      | JSON Schema for fact payload |
 
 ### Events
 
@@ -94,12 +94,12 @@ Events are things that happen in your application that drive state changes.
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique identifier |
-| `tag` | string | Yes | Event tag (used in code) |
-| `description` | string | Yes | Human-readable description |
-| `payload` | object | Yes | JSON Schema for event payload |
+| Field         | Type   | Required | Description                   |
+| ------------- | ------ | -------- | ----------------------------- |
+| `id`          | string | Yes      | Unique identifier             |
+| `tag`         | string | Yes      | Event tag (used in code)      |
+| `description` | string | Yes      | Human-readable description    |
+| `payload`     | object | Yes      | JSON Schema for event payload |
 
 ### Rules
 
@@ -123,14 +123,14 @@ Rules are pure functions that produce facts from events and current state.
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique identifier |
-| `name` | string | Yes | Rule name |
-| `description` | string | Yes | What the rule does |
-| `triggers` | string[] | No | Events that trigger this rule |
-| `then` | object | Yes | Rule implementation |
-| `priority` | number | No | Execution priority (higher = first) |
+| Field         | Type     | Required | Description                         |
+| ------------- | -------- | -------- | ----------------------------------- |
+| `id`          | string   | Yes      | Unique identifier                   |
+| `name`        | string   | Yes      | Rule name                           |
+| `description` | string   | Yes      | What the rule does                  |
+| `triggers`    | string[] | No       | Events that trigger this rule       |
+| `then`        | object   | Yes      | Rule implementation                 |
+| `priority`    | number   | No       | Execution priority (higher = first) |
 
 ### Constraints
 
@@ -154,14 +154,14 @@ Constraints are invariants that must always hold true.
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique identifier |
-| `name` | string | Yes | Constraint name |
-| `description` | string | Yes | What the constraint ensures |
-| `check` | object | Yes | Constraint check implementation |
-| `errorMessage` | string | Yes | Error message when violated |
-| `severity` | string | Yes | `error` or `warning` |
+| Field          | Type   | Required | Description                     |
+| -------------- | ------ | -------- | ------------------------------- |
+| `id`           | string | Yes      | Unique identifier               |
+| `name`         | string | Yes      | Constraint name                 |
+| `description`  | string | Yes      | What the constraint ensures     |
+| `check`        | object | Yes      | Constraint check implementation |
+| `errorMessage` | string | Yes      | Error message when violated     |
+| `severity`     | string | Yes      | `error` or `warning`            |
 
 ### Models
 
@@ -179,11 +179,13 @@ Models define your data structures.
         { "name": "username", "type": "string", "description": "Username" },
         { "name": "email", "type": "string", "description": "Email address" },
         { "name": "createdAt", "type": "datetime", "description": "Creation time" },
-        { "name": "role", "type": { "enum": ["admin", "user", "guest"] }, "description": "User role" }
-      ],
-      "indexes": [
-        { "name": "idx_email", "fields": ["email"], "unique": true }
+        {
+          "name": "role",
+          "type": { "enum": ["admin", "user", "guest"] },
+          "description": "User role"
+        }
       ],
+      "indexes": [{ "name": "idx_email", "fields": ["email"], "unique": true }],
       "relationships": [
         { "name": "posts", "type": "one-to-many", "target": "Post", "foreignKey": "authorId" }
       ]
@@ -194,17 +196,17 @@ Models define your data structures.
 
 #### Field Types
 
-| Type | Description | Example |
-|------|-------------|---------|
-| `string` | Text value | `"Hello"` |
-| `number` | Numeric value | `42` |
-| `boolean` | True/false | `true` |
-| `uuid` | UUID string | `"550e8400-..."` |
-| `datetime` | ISO 8601 date | `"2024-01-01T00:00:00Z"` |
-| `object` | Nested object | `{ key: value }` |
-| `{ array: { type } }` | Array of type | `[1, 2, 3]` |
-| `{ enum: [...] }` | Enumeration | `"active"` |
-| `{ reference: "Model" }` | Reference to another model | Foreign key |
+| Type                     | Description                | Example                  |
+| ------------------------ | -------------------------- | ------------------------ |
+| `string`                 | Text value                 | `"Hello"`                |
+| `number`                 | Numeric value              | `42`                     |
+| `boolean`                | True/false                 | `true`                   |
+| `uuid`                   | UUID string                | `"550e8400-..."`         |
+| `datetime`               | ISO 8601 date              | `"2024-01-01T00:00:00Z"` |
+| `object`                 | Nested object              | `{ key: value }`         |
+| `{ array: { type } }`    | Array of type              | `[1, 2, 3]`              |
+| `{ enum: [...] }`        | Enumeration                | `"active"`               |
+| `{ reference: "Model" }` | Reference to another model | Foreign key              |
 
 ### Components
 
@@ -220,8 +222,18 @@ Components define UI elements generated from the schema.
       "description": "Form for creating/editing users",
       "model": "User",
       "props": [
-        { "name": "user", "type": "User", "required": false, "description": "Existing user to edit" },
-        { "name": "onSubmit", "type": "function", "required": true, "description": "Submit handler" }
+        {
+          "name": "user",
+          "type": "User",
+          "required": false,
+          "description": "Existing user to edit"
+        },
+        {
+          "name": "onSubmit",
+          "type": "function",
+          "required": true,
+          "description": "Submit handler"
+        }
       ],
       "events": [
         { "name": "submit", "payload": "User", "description": "Form submitted" },
@@ -234,13 +246,13 @@ Components define UI elements generated from the schema.
 
 #### Component Types
 
-| Type | Description | Generated Features |
-|------|-------------|-------------------|
-| `form` | Input form | Validation, submit handling |
-| `display` | Display data | Data binding, formatting |
-| `list` | List of items | Pagination, filtering |
-| `editor` | Rich editor | Editing capabilities |
-| `composite` | Composed of others | Layout, composition |
+| Type        | Description        | Generated Features          |
+| ----------- | ------------------ | --------------------------- |
+| `form`      | Input form         | Validation, submit handling |
+| `display`   | Display data       | Data binding, formatting    |
+| `list`      | List of items      | Pagination, filtering       |
+| `editor`    | Rich editor        | Editing capabilities        |
+| `composite` | Composed of others | Layout, composition         |
 
 ### Flows
 
@@ -356,6 +368,7 @@ praxis validate --schema ./schema.psf.json
 ```
 
 Common validation errors:
+
 - Missing required fields
 - Invalid type definitions
 - Duplicate IDs
@@ -401,6 +414,7 @@ praxis generate --schema ./schema.psf.json --watch
 ```
 
 Generated outputs:
+
 - `facts.ts` - Fact type definitions and creators
 - `events.ts` - Event type definitions and creators
 - `rules.ts` - Rule implementations

package/docs/core/ui-generation.md

@@ -5,6 +5,7 @@ Praxis automatically generates Svelte components from your schema definitions. T
 ## Overview
 
 From a single schema definition, Praxis generates:
+
 - Svelte 5 components with runes
 - TypeScript type definitions
 - Data binding and validation
@@ -26,6 +27,7 @@ flowchart LR
 Forms are generated from model definitions:
 
 **Schema:**
+
 ```json
 {
   "components": [
@@ -41,33 +43,34 @@ Forms are generated from model definitions:
 ```
 
 **Generated Component:**
+
 ```svelte
 <script lang="ts">
   import type { User } from '../models';
-  
+
   interface Props {
     user?: User;
     onsubmit?: (user: User) => void;
     oncancel?: () => void;
   }
-  
+
   let { user = $bindable(), onsubmit, oncancel }: Props = $props();
-  
+
   let formData = $state({
     username: user?.username ?? '',
     email: user?.email ?? '',
     role: user?.role ?? 'user',
   });
-  
+
   let errors = $state<Record<string, string>>({});
-  
+
   function validate(): boolean {
     errors = {};
     if (!formData.username) errors.username = 'Username is required';
     if (!formData.email) errors.email = 'Email is required';
     return Object.keys(errors).length === 0;
   }
-  
+
   function handleSubmit(e: Event) {
     e.preventDefault();
     if (validate()) {
@@ -82,13 +85,13 @@ Forms are generated from model definitions:
     <input id="username" bind:value={formData.username} />
     {#if errors.username}<span class="error">{errors.username}</span>{/if}
   </div>
-  
+
   <div class="field">
     <label for="email">Email</label>
     <input id="email" type="email" bind:value={formData.email} />
     {#if errors.email}<span class="error">{errors.email}</span>{/if}
   </div>
-  
+
   <div class="field">
     <label for="role">Role</label>
     <select id="role" bind:value={formData.role}>
@@ -97,7 +100,7 @@ Forms are generated from model definitions:
       <option value="guest">Guest</option>
     </select>
   </div>
-  
+
   <div class="actions">
     <button type="submit">Save</button>
     <button type="button" onclick={oncancel}>Cancel</button>
@@ -110,6 +113,7 @@ Forms are generated from model definitions:
 Display components show data in read-only format:
 
 **Schema:**
+
 ```json
 {
   "components": [
@@ -125,15 +129,16 @@ Display components show data in read-only format:
 ```
 
 **Generated Component:**
+
 ```svelte
 <script lang="ts">
   import type { User } from '../models';
-  
+
   interface Props {
     user: User;
     onclick?: (user: User) => void;
   }
-  
+
   let { user, onclick }: Props = $props();
 </script>
 
@@ -149,6 +154,7 @@ Display components show data in read-only format:
 List components display collections:
 
 **Schema:**
+
 ```json
 {
   "components": [
@@ -167,19 +173,20 @@ List components display collections:
 ```
 
 **Generated Component:**
+
 ```svelte
 <script lang="ts">
   import type { User } from '../models';
   import UserCard from './UserCard.svelte';
-  
+
   interface Props {
     users: User[];
     filter?: string;
     onselect?: (user: User) => void;
   }
-  
+
   let { users, filter = '', onselect }: Props = $props();
-  
+
   let filtered = $derived(
     filter
       ? users.filter(u => u.username.includes(filter))
@@ -191,7 +198,7 @@ List components display collections:
   {#each filtered as user (user.id)}
     <UserCard {user} onclick={onselect} />
   {/each}
-  
+
   {#if filtered.length === 0}
     <p class="empty">No users found</p>
   {/if}
@@ -203,6 +210,7 @@ List components display collections:
 Editor components provide rich editing capabilities:
 
 **Schema:**
+
 ```json
 {
   "components": [
@@ -251,9 +259,7 @@ Define events the component emits:
       "id": "comp_cart_item",
       "name": "CartItem",
       "type": "display",
-      "props": [
-        { "name": "item", "type": "CartItem", "required": true }
-      ],
+      "props": [{ "name": "item", "type": "CartItem", "required": true }],
       "events": [
         { "name": "remove", "payload": "{ itemId: string }" },
         { "name": "updateQuantity", "payload": "{ itemId: string; quantity: number }" }
@@ -272,11 +278,11 @@ Generated components can be extended without modifying them:
 <script lang="ts">
   import ProductCard from './generated/ProductCard.svelte';
   import type { Product } from './generated/models';
-  
+
   interface Props {
     product: Product;
   }
-  
+
   let { product }: Props = $props();
 </script>
 
@@ -290,22 +296,23 @@ Generated components can be extended without modifying them:
 
 Praxis maps schema field types to HTML input types:
 
-| Schema Type | HTML Input | Component |
-|-------------|------------|-----------|
-| `string` | `<input type="text">` | Text input |
-| `number` | `<input type="number">` | Number input |
-| `boolean` | `<input type="checkbox">` | Checkbox |
-| `datetime` | `<input type="datetime-local">` | Date picker |
-| `{ enum: [...] }` | `<select>` | Dropdown |
-| `{ array: {...} }` | Custom | Array editor |
-| `object` | Nested form | Fieldset |
-| `uuid` | Hidden | Auto-generated |
+| Schema Type        | HTML Input                      | Component      |
+| ------------------ | ------------------------------- | -------------- |
+| `string`           | `<input type="text">`           | Text input     |
+| `number`           | `<input type="number">`         | Number input   |
+| `boolean`          | `<input type="checkbox">`       | Checkbox       |
+| `datetime`         | `<input type="datetime-local">` | Date picker    |
+| `{ enum: [...] }`  | `<select>`                      | Dropdown       |
+| `{ array: {...} }` | Custom                          | Array editor   |
+| `object`           | Nested form                     | Fieldset       |
+| `uuid`             | Hidden                          | Auto-generated |
 
 ## Validation
 
 Generated forms include validation based on field definitions:
 
 **Schema:**
+
 ```json
 {
   "models": [
@@ -322,27 +329,28 @@ Generated forms include validation based on field definitions:
 ```
 
 **Generated Validation:**
+
 ```svelte
 <script lang="ts">
   function validate(): boolean {
     errors = {};
-    
+
     if (!isValidEmail(formData.email)) {
       errors.email = 'Invalid email format';
     }
-    
+
     if (formData.age < 0 || formData.age > 150) {
       errors.age = 'Age must be between 0 and 150';
     }
-    
+
     if (formData.username.length < 3) {
       errors.username = 'Username must be at least 3 characters';
     }
-    
+
     if (formData.username.length > 20) {
       errors.username = 'Username must be at most 20 characters';
     }
-    
+
     return Object.keys(errors).length === 0;
   }
 </script>
@@ -362,7 +370,7 @@ Component props use the `$props` rune:
     user: User;
     editable?: boolean;
   }
-  
+
   let { user, editable = false }: Props = $props();
 </script>
 ```
@@ -377,7 +385,7 @@ Local state uses the `$state` rune:
     name: '',
     email: ''
   });
-  
+
   let errors = $state<Record<string, string>>({});
 </script>
 ```
@@ -391,7 +399,7 @@ Computed values use the `$derived` rune:
   let filteredItems = $derived(
     items.filter(item => item.name.includes(searchTerm))
   );
-  
+
   let total = $derived(
     items.reduce((sum, item) => sum + item.price, 0)
   );
@@ -407,7 +415,7 @@ Two-way binding uses `$bindable`:
   interface Props {
     value?: string;
   }
-  
+
   let { value = $bindable('') }: Props = $props();
 </script>
 
@@ -423,24 +431,24 @@ Generated components integrate with the Praxis engine:
   import { usePraxisEngine } from '@plures/praxis/svelte';
   import { engine } from '../engine';
   import { AddToCart, RemoveFromCart } from '../generated/events';
-  
+
   const { context, dispatch } = usePraxisEngine(engine);
-  
+
   function handleAddToCart(productId: string) {
     dispatch([AddToCart.create({ productId, quantity: 1 })]);
   }
-  
+
   function handleRemoveFromCart(itemId: string) {
     dispatch([RemoveFromCart.create({ itemId })]);
   }
 </script>
 
-<ProductList 
-  products={context.products} 
-  onaddtocart={handleAddToCart} 
+<ProductList
+  products={context.products}
+  onaddtocart={handleAddToCart}
 />
 
-<ShoppingCart 
+<ShoppingCart
   items={context.cart.items}
   onremove={handleRemoveFromCart}
 />
@@ -457,19 +465,19 @@ Generated components include minimal default styles:
   .field {
     margin-bottom: 1rem;
   }
-  
+
   label {
     display: block;
     margin-bottom: 0.25rem;
   }
-  
+
   input, select, textarea {
     width: 100%;
     padding: 0.5rem;
     border: 1px solid #ccc;
     border-radius: 4px;
   }
-  
+
   .error {
     color: red;
     font-size: 0.875rem;