@plures/praxis 0.2.0

package/src/examples/advanced-todo/README.md

@@ -0,0 +1,371 @@
+# Advanced Todo App with Praxis
+
+A comprehensive example demonstrating Praxis's Svelte 5 integration with history state pattern.
+
+## Features
+
+### Core Functionality
+- ✅ Add, complete, and remove todos
+- ✅ Filter by all, active, or completed
+- ✅ Complete all todos at once
+- ✅ Clear completed todos
+- ✅ Real-time statistics
+
+### Advanced Features
+- 🔄 **Undo/Redo**: Full history tracking with keyboard shortcuts
+- 🕰️ **Time-Travel Debugging**: Navigate through state snapshots
+- ⚡ **Svelte 5 Runes**: Modern reactive API
+- 🎨 **Beautiful UI**: Clean, intuitive interface
+- ⌨️ **Keyboard Shortcuts**: Efficient workflow
+
+## Architecture
+
+### State Management
+- **Engine**: Praxis logic engine managing todo state
+- **Rules**: Pure functions handling events
+- **Facts**: Immutable history of what happened
+- **Context**: Current application state
+
+### Svelte Integration
+- **usePraxisEngine**: Main composable with history support
+- **Reactive Derivations**: Computed values with `$:` syntax
+- **Event Dispatching**: Type-safe event handling
+- **Snapshot Navigation**: Time-travel through history
+
+## Code Structure
+
+```
+advanced-todo/
+├── index.ts      # Engine definition, rules, and logic
+├── App.svelte    # Svelte 5 component with UI
+└── README.md     # This file
+```
+
+### Engine Definition (`index.ts`)
+
+```typescript
+// Define context type
+interface TodoContext {
+  todos: TodoItem[];
+  filter: 'all' | 'active' | 'completed';
+  nextId: number;
+}
+
+// Define events
+const AddTodo = defineEvent<'ADD_TODO', { text: string }>('ADD_TODO');
+const ToggleTodo = defineEvent<'TOGGLE_TODO', { id: string }>('TOGGLE_TODO');
+// ... more events
+
+// Define rules
+const addTodoRule = defineRule<TodoContext>({
+  id: 'todo.add',
+  description: 'Add a new todo item',
+  impl: (state, events) => {
+    // Pure function: no side effects
+    // Returns facts about what happened
+  },
+});
+
+// Create engine
+export function createTodoEngine() {
+  const registry = new PraxisRegistry<TodoContext>();
+  registry.registerRule(addTodoRule);
+  // ... register more rules
+  
+  return createPraxisEngine({
+    initialContext: { todos: [], filter: 'all', nextId: 1 },
+    registry,
+  });
+}
+```
+
+### Svelte Component (`App.svelte`)
+
+```svelte
+<script lang="ts">
+  import { usePraxisEngine } from '@plures/praxis/svelte';
+  import { createTodoEngine, AddTodo } from './index';
+
+  const engine = createTodoEngine();
+  const {
+    context,      // Reactive context
+    dispatch,     // Dispatch events
+    undo,         // Undo last action
+    redo,         // Redo action
+    canUndo,      // Boolean: can undo?
+    canRedo,      // Boolean: can redo?
+    snapshots,    // History snapshots
+    historyIndex, // Current position
+    goToSnapshot, // Jump to snapshot
+  } = usePraxisEngine(engine, {
+    enableHistory: true,
+    maxHistorySize: 50,
+  });
+
+  function handleAddTodo(text: string) {
+    dispatch([AddTodo.create({ text })], 'Add Todo');
+  }
+</script>
+
+<div>
+  <p>Todos: {context.todos.length}</p>
+  <button onclick={undo} disabled={!canUndo}>Undo</button>
+  <button onclick={redo} disabled={!canRedo}>Redo</button>
+</div>
+```
+
+## Running the Example
+
+### Non-Svelte Version
+
+Run the TypeScript example directly:
+
+```bash
+cd /home/runner/work/praxis/praxis
+npm run build
+node dist/examples/advanced-todo/index.js
+```
+
+Output:
+```
+=== Advanced Todo Example ===
+
+1. Adding todos:
+   Total todos: 3
+   - Learn Praxis
+   - Build awesome app
+   - Deploy to production
+
+2. Completing first todo:
+   Active: 2, Completed: 1
+
+3. Filtering to active todos:
+   Filter: active
+   Showing 2 todos:
+   - Build awesome app
+   - Deploy to production
+
+4. Completing all todos:
+   All completed: 3/3
+
+5. Clearing completed todos:
+   Remaining todos: 0
+```
+
+### Svelte 5 Version
+
+To use the Svelte component in your app:
+
+1. Install dependencies:
+```bash
+npm install @plures/praxis svelte@^5.0.0
+```
+
+2. Import and use the component:
+```svelte
+<script>
+  import TodoApp from '@plures/praxis/examples/advanced-todo/App.svelte';
+</script>
+
+<TodoApp />
+```
+
+Or create your own component using the engine:
+
+```svelte
+<script lang="ts">
+  import { usePraxisEngine } from '@plures/praxis/svelte';
+  import { createTodoEngine, AddTodo } from '@plures/praxis/examples/advanced-todo';
+
+  const engine = createTodoEngine();
+  const { context, dispatch } = usePraxisEngine(engine);
+  
+  let text = '';
+</script>
+
+<input bind:value={text} />
+<button onclick={() => dispatch([AddTodo.create({ text })])}>
+  Add
+</button>
+
+<ul>
+  {#each context.todos as todo}
+    <li>{todo.text}</li>
+  {/each}
+</ul>
+```
+
+## Keyboard Shortcuts
+
+- **Ctrl+Z** / **Cmd+Z**: Undo
+- **Ctrl+Y** / **Cmd+Y**: Redo
+- **Ctrl+D** / **Cmd+D**: Toggle debugger
+- **Enter**: Add todo (when input is focused)
+
+## Key Concepts
+
+### 1. Immutable State Updates
+
+```typescript
+// ❌ Don't mutate directly (outside rules)
+context.todos.push(newTodo);
+
+// ✅ Do dispatch events
+dispatch([AddTodo.create({ text: 'New todo' })]);
+```
+
+### 2. Pure Rules
+
+```typescript
+const addTodoRule = defineRule({
+  id: 'todo.add',
+  impl: (state, events) => {
+    // ✅ Pure function
+    // - Deterministic
+    // - No side effects
+    // - Testable
+    const event = findEvent(events, AddTodo);
+    if (!event) return [];
+    
+    state.context.todos.push({ /* ... */ });
+    return [TodoAdded.create({ /* ... */ })];
+  },
+});
+```
+
+### 3. Facts as History
+
+```typescript
+// Facts are immutable records of what happened
+const facts = engine.getFacts();
+
+// Find specific facts
+const added = facts.filter(f => f.tag === 'TodoAdded');
+const toggled = facts.filter(f => f.tag === 'TodoToggled');
+
+// Facts enable:
+// - Audit trails
+// - Event sourcing
+// - Time-travel debugging
+```
+
+### 4. Reactive Derivations
+
+```svelte
+<script>
+  // Svelte automatically tracks dependencies
+  $: filteredTodos = getFilteredTodos(context.todos, context.filter);
+  $: stats = getStats(context.todos);
+  $: hasCompleted = stats.completed > 0;
+</script>
+```
+
+### 5. History State Pattern
+
+```typescript
+// Enable history tracking
+const { undo, redo, snapshots, goToSnapshot } = usePraxisEngine(engine, {
+  enableHistory: true,
+  maxHistorySize: 50,
+});
+
+// Navigate history
+undo();                    // Go back
+redo();                    // Go forward
+goToSnapshot(5);           // Jump to specific snapshot
+console.log(snapshots);    // View all snapshots
+```
+
+## Testing
+
+The engine can be tested independently of Svelte:
+
+```typescript
+import { createTodoEngine, AddTodo, ToggleTodo } from './index';
+
+describe('Todo Engine', () => {
+  it('should add todos', () => {
+    const engine = createTodoEngine();
+    engine.step([AddTodo.create({ text: 'Test todo' })]);
+    
+    const context = engine.getContext();
+    expect(context.todos.length).toBe(1);
+    expect(context.todos[0].text).toBe('Test todo');
+  });
+
+  it('should toggle todos', () => {
+    const engine = createTodoEngine();
+    engine.step([AddTodo.create({ text: 'Test' })]);
+    
+    const context = engine.getContext();
+    const todoId = context.todos[0].id;
+    
+    engine.step([ToggleTodo.create({ id: todoId })]);
+    expect(engine.getContext().todos[0].completed).toBe(true);
+  });
+});
+```
+
+## Performance Tips
+
+1. **Batch Events**: Dispatch multiple events at once
+   ```typescript
+   dispatch([
+     AddTodo.create({ text: 'Todo 1' }),
+     AddTodo.create({ text: 'Todo 2' }),
+     AddTodo.create({ text: 'Todo 3' }),
+   ], 'Batch Add');
+   ```
+
+2. **Limit History**: Adjust history size based on needs
+   ```typescript
+   usePraxisEngine(engine, { maxHistorySize: 20 });
+   ```
+
+3. **Selective Subscriptions**: Use derived stores for specific values
+   ```typescript
+   const count = createDerivedStore(engine, ctx => ctx.todos.length);
+   ```
+
+## Comparison with Other Libraries
+
+### vs. Redux + Redux Toolkit
+
+| Feature | Redux + RTK | Praxis |
+|---------|-------------|--------|
+| State Updates | Reducers | Rules |
+| Side Effects | Thunks/Sagas | Actors |
+| Time-Travel | DevTools | Built-in |
+| TypeScript | Good | Excellent |
+| Learning Curve | Medium | Low |
+
+### vs. XState
+
+| Feature | XState | Praxis |
+|---------|--------|--------|
+| State Machines | Native | Engine-based |
+| Svelte Integration | @xstate/svelte | @plures/praxis/svelte |
+| History States | Built-in | Pattern-based |
+| Visual Tools | Stately | State-Docs (planned) |
+| Learning Curve | High | Medium |
+
+### vs. Svelte Stores
+
+| Feature | Svelte Stores | Praxis |
+|---------|---------------|--------|
+| Simplicity | Very High | High |
+| Structure | Manual | Built-in |
+| Time-Travel | Manual | Built-in |
+| Rules/Logic | Manual | Built-in |
+| TypeScript | Good | Excellent |
+
+## Next Steps
+
+- Explore [History State Pattern Guide](../../docs/guides/history-state-pattern.md)
+- Read [Svelte Integration Guide](../../docs/guides/svelte-integration.md)
+- Check [Parallel State Pattern](../../docs/guides/parallel-state-pattern.md)
+- View [More Examples](../)
+
+## License
+
+MIT

package/src/examples/advanced-todo/index.ts

@@ -0,0 +1,309 @@
+/**
+ * Advanced Svelte 5 Integration Example
+ * 
+ * Demonstrates the new Svelte 5 runes support with history state pattern.
+ * This example shows a todo app with undo/redo and time-travel debugging.
+ */
+
+import {
+  createPraxisEngine,
+  PraxisRegistry,
+  defineFact,
+  defineEvent,
+  defineRule,
+  findEvent,
+} from '../../index.js';
+
+// ============================================================================
+// Context & Domain Types
+// ============================================================================
+
+interface TodoItem {
+  id: string;
+  text: string;
+  completed: boolean;
+  createdAt: number;
+}
+
+interface TodoContext {
+  todos: TodoItem[];
+  filter: 'all' | 'active' | 'completed';
+  nextId: number;
+}
+
+// ============================================================================
+// Facts
+// ============================================================================
+
+const TodoAdded = defineFact<'TodoAdded', { id: string; text: string }>('TodoAdded');
+const TodoToggled = defineFact<'TodoToggled', { id: string }>('TodoToggled');
+const TodoRemoved = defineFact<'TodoRemoved', { id: string }>('TodoRemoved');
+const FilterChanged = defineFact<'FilterChanged', { filter: string }>('FilterChanged');
+const AllCompleted = defineFact<'AllCompleted', {}>('AllCompleted');
+const CompletedCleared = defineFact<'CompletedCleared', {}>('CompletedCleared');
+
+// ============================================================================
+// Events
+// ============================================================================
+
+const AddTodo = defineEvent<'ADD_TODO', { text: string }>('ADD_TODO');
+const ToggleTodo = defineEvent<'TOGGLE_TODO', { id: string }>('TOGGLE_TODO');
+const RemoveTodo = defineEvent<'REMOVE_TODO', { id: string }>('REMOVE_TODO');
+const SetFilter = defineEvent<'SET_FILTER', { filter: 'all' | 'active' | 'completed' }>(
+  'SET_FILTER'
+);
+const CompleteAll = defineEvent<'COMPLETE_ALL', {}>('COMPLETE_ALL');
+const ClearCompleted = defineEvent<'CLEAR_COMPLETED', {}>('CLEAR_COMPLETED');
+
+// ============================================================================
+// Rules
+// ============================================================================
+
+const addTodoRule = defineRule<TodoContext>({
+  id: 'todo.add',
+  description: 'Add a new todo item',
+  impl: (state, events) => {
+    const event = findEvent(events, AddTodo);
+    if (!event || !event.payload.text.trim()) {
+      return [];
+    }
+
+    const id = `todo-${state.context.nextId}`;
+    const todo: TodoItem = {
+      id,
+      text: event.payload.text.trim(),
+      completed: false,
+      createdAt: Date.now(),
+    };
+
+    state.context.todos.push(todo);
+    state.context.nextId++;
+
+    return [TodoAdded.create({ id, text: todo.text })];
+  },
+});
+
+const toggleTodoRule = defineRule<TodoContext>({
+  id: 'todo.toggle',
+  description: 'Toggle todo completion status',
+  impl: (state, events) => {
+    const event = findEvent(events, ToggleTodo);
+    if (!event) {
+      return [];
+    }
+
+    const todo = state.context.todos.find((t) => t.id === event.payload.id);
+    if (todo) {
+      todo.completed = !todo.completed;
+      return [TodoToggled.create({ id: todo.id })];
+    }
+
+    return [];
+  },
+});
+
+const removeTodoRule = defineRule<TodoContext>({
+  id: 'todo.remove',
+  description: 'Remove a todo item',
+  impl: (state, events) => {
+    const event = findEvent(events, RemoveTodo);
+    if (!event) {
+      return [];
+    }
+
+    const index = state.context.todos.findIndex((t) => t.id === event.payload.id);
+    if (index !== -1) {
+      state.context.todos.splice(index, 1);
+      return [TodoRemoved.create({ id: event.payload.id })];
+    }
+
+    return [];
+  },
+});
+
+const setFilterRule = defineRule<TodoContext>({
+  id: 'todo.setFilter',
+  description: 'Change the filter',
+  impl: (state, events) => {
+    const event = findEvent(events, SetFilter);
+    if (!event) {
+      return [];
+    }
+
+    state.context.filter = event.payload.filter;
+    return [FilterChanged.create({ filter: event.payload.filter })];
+  },
+});
+
+const completeAllRule = defineRule<TodoContext>({
+  id: 'todo.completeAll',
+  description: 'Mark all todos as completed',
+  impl: (state, events) => {
+    const event = findEvent(events, CompleteAll);
+    if (!event) {
+      return [];
+    }
+
+    state.context.todos.forEach((todo) => {
+      todo.completed = true;
+    });
+
+    return [AllCompleted.create({})];
+  },
+});
+
+const clearCompletedRule = defineRule<TodoContext>({
+  id: 'todo.clearCompleted',
+  description: 'Remove all completed todos',
+  impl: (state, events) => {
+    const event = findEvent(events, ClearCompleted);
+    if (!event) {
+      return [];
+    }
+
+    const beforeCount = state.context.todos.length;
+    state.context.todos = state.context.todos.filter((t) => !t.completed);
+    const afterCount = state.context.todos.length;
+
+    if (beforeCount !== afterCount) {
+      return [CompletedCleared.create({})];
+    }
+
+    return [];
+  },
+});
+
+// ============================================================================
+// Engine Factory
+// ============================================================================
+
+export function createTodoEngine() {
+  const registry = new PraxisRegistry<TodoContext>();
+
+  registry.registerRule(addTodoRule);
+  registry.registerRule(toggleTodoRule);
+  registry.registerRule(removeTodoRule);
+  registry.registerRule(setFilterRule);
+  registry.registerRule(completeAllRule);
+  registry.registerRule(clearCompletedRule);
+
+  return createPraxisEngine<TodoContext>({
+    initialContext: {
+      todos: [],
+      filter: 'all',
+      nextId: 1,
+    },
+    registry,
+  });
+}
+
+// ============================================================================
+// Helper Functions for Svelte
+// ============================================================================
+
+export function getFilteredTodos(todos: TodoItem[], filter: string): TodoItem[] {
+  switch (filter) {
+    case 'active':
+      return todos.filter((t) => !t.completed);
+    case 'completed':
+      return todos.filter((t) => t.completed);
+    default:
+      return todos;
+  }
+}
+
+export function getStats(todos: TodoItem[]) {
+  const total = todos.length;
+  const active = todos.filter((t) => !t.completed).length;
+  const completed = todos.filter((t) => t.completed).length;
+
+  return { total, active, completed };
+}
+
+// ============================================================================
+// Example Usage (non-Svelte demonstration)
+// ============================================================================
+
+function runExample() {
+  console.log('=== Advanced Todo Example ===\n');
+
+  const engine = createTodoEngine();
+
+  // Add some todos
+  console.log('1. Adding todos:');
+  engine.step([AddTodo.create({ text: 'Learn Praxis' })]);
+  engine.step([AddTodo.create({ text: 'Build awesome app' })]);
+  engine.step([AddTodo.create({ text: 'Deploy to production' })]);
+
+  const context1 = engine.getContext();
+  console.log(`   Total todos: ${context1.todos.length}`);
+  context1.todos.forEach((todo) => {
+    console.log(`   - ${todo.text}`);
+  });
+  console.log();
+
+  // Toggle a todo
+  console.log('2. Completing first todo:');
+  const firstId = context1.todos[0].id;
+  engine.step([ToggleTodo.create({ id: firstId })]);
+
+  const context2 = engine.getContext();
+  const stats = getStats(context2.todos);
+  console.log(`   Active: ${stats.active}, Completed: ${stats.completed}`);
+  console.log();
+
+  // Change filter
+  console.log('3. Filtering to active todos:');
+  engine.step([SetFilter.create({ filter: 'active' })])
+  
+  const context3 = engine.getContext();
+  const filtered = getFilteredTodos(context3.todos, context3.filter);
+  console.log(`   Filter: ${context3.filter}`);
+  console.log(`   Showing ${filtered.length} todos:`);
+  filtered.forEach((todo) => {
+    console.log(`   - ${todo.text}`);
+  });
+  console.log();
+
+  // Complete all
+  console.log('4. Completing all todos:');
+  engine.step([CompleteAll.create({})]);
+
+  const context4 = engine.getContext();
+  const stats4 = getStats(context4.todos);
+  console.log(`   All completed: ${stats4.completed}/${stats4.total}`);
+  console.log();
+
+  // Clear completed
+  console.log('5. Clearing completed todos:');
+  engine.step([ClearCompleted.create({})]);
+
+  const context5 = engine.getContext();
+  console.log(`   Remaining todos: ${context5.todos.length}`);
+  console.log();
+}
+
+// Run example if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runExample();
+}
+
+export {
+  // Types
+  type TodoItem,
+  type TodoContext,
+  // Events
+  AddTodo,
+  ToggleTodo,
+  RemoveTodo,
+  SetFilter,
+  CompleteAll,
+  ClearCompleted,
+  // Facts
+  TodoAdded,
+  TodoToggled,
+  TodoRemoved,
+  FilterChanged,
+  AllCompleted,
+  CompletedCleared,
+};