apprun 3.37.3 → 3.38.0

package/ai/apprun.prompt.md

@@ -1,166 +1,602 @@
----
-mode: agent
----
 # AppRun Component Creation Guide
 
-## Core Concepts
+## Core Architecture Patterns
 
-AppRun follows the State-View-Update architecture pattern with TypeScript support for type-safe component development.
+AppRun follows the State-View-Update architecture with TypeScript support. Choose the appropriate component pattern based on your needs:
 
-## Step 1: Define State Interface
+### **Stateful Class Components (Self-Contained)**
+Use for components that manage their own state internally, handle side effects, and coordinate with parents via global events. Modern pattern using `mounted` lifecycle.
 
-### **State Management**
-1. Define typed state interface with all required properties
-2. Initialize with sensible defaults including loading/error states
-3. Plan for immutable updates using spread operator
-4. Include states for: loading, error, data, UI state
+### **Container Class Components (Legacy)**
+Use for components that manage state, handle side effects, and coordinate data flow using traditional state initialization.
 
+### **Functional Components (Presentation/Dumb Components)**
+Use for components that only render UI based on props with minimal logic.
+
+## Component Patterns
+
+### **Pattern 1: Stateful Class Component (Modern - Recommended)**
+
+Use `mounted` lifecycle to receive props and convert to initial state. Functions defined at module level for better testing.
+
+#### **Module-Level Functions (separate file)**
 ```typescript
-interface ComponentState {
-  data: DataType[];
-  currentIndex: number;
+// component-functions.ts
+export interface ComponentState {
+  mode: 'create' | 'edit' | 'delete';
+  formData: FormType;
   loading: boolean;
   error: string | null;
+  successMessage: string | null;
 }
-```
 
-## Step 2: Create Component Structure
+export interface ComponentProps {
+  mode?: string;
+  initialData?: FormType;
+}
 
-### **Component-Based Architecture**
-- Extend `Component<StateType>` class
-- Initialize state with async function for API data loading
-- Plan MVU (Model-View-Update) separation
-- Use functional design principles
+export const initializeState = (props: ComponentProps): ComponentState => ({
+  mode: props.mode || 'create',
+  formData: props.initialData || getDefaultFormData(),
+  loading: false,
+  error: null,
+  successMessage: null
+});
+
+export const saveData = async function* (state: ComponentState): AsyncGenerator<ComponentState> {
+  yield { ...state, loading: true, error: null };
+  try {
+    await performSave(state.formData);
+    yield { 
+      ...state, 
+      loading: false, 
+      successMessage: 'Data saved successfully!' 
+    };
+    setTimeout(() => app.run('data-saved'), 2000);
+  } catch (error) {
+    yield { ...state, loading: false, error: error.message };
+  }
+};
+
+export const closeModal = (): void => {
+  app.run('close-modal');
+};
+```
 
+#### **Component Structure**
 ```typescript
+// component.tsx
+import { initializeState, saveData, closeModal, type ComponentState, type ComponentProps } from './component-functions';
+
 export default class MyComponent extends Component<ComponentState> {
-  state = async () => {
-    const data = await getData();
-    return {
-      data,
-      currentIndex: 0,
-      loading: false,
-      error: null
-    };
-  }
+  declare props: Readonly<ComponentProps>;
+  mounted = (props: ComponentProps): ComponentState => initializeState(props);
+
+  view = (state: ComponentState) => {
+    // Guard clauses
+    if (state.successMessage) {
+      return (
+        <div className="modal-backdrop" $onclick={[closeModal]}>
+          <div className="success-message">
+            <p>{state.successMessage}</p>
+          </div>
+        </div>
+      );
+    }
+
+    return (
+      <div className="modal-backdrop" $onclick={[closeModal]}>
+        <form>
+          <input
+            value={state.formData.name}
+            $bind="formData.name"
+            disabled={state.loading}
+          />
+          <button 
+            $onclick={[saveData]} 
+            disabled={state.loading}
+          >
+            {state.loading ? 'Saving...' : 'Save'}
+          </button>
+          <button $onclick={[closeModal]}>Cancel</button>
+        </form>
+      </div>
+    );
+  };
 }
 ```
 
-## Step 3: Design View Function
+### **Pattern 2: Legacy Container Component**
 
-### **View Structure**
+Traditional pattern with state initialization function.
+
+#### **Component Structure**
 ```typescript
-view = (state: State) => {
-  // Guard clauses first (early returns)
-  if (state.loading) return loadingView;
-  if (state.error) return errorView;
-  if (state.empty) return emptyView;
-  
-  // Main content last
-  return mainView;
+export default class MyComponent extends Component<ComponentState> {
+  state = async (): Promise<ComponentState> => {
+    // Initial state with async data loading
+    try {
+      const data = await loadData();
+      return {
+        data,
+        loading: false,
+        error: null,
+        selectedItem: null,
+        isEditing: false
+      };
+    } catch (error) {
+      return {
+        data: [],
+        loading: false,
+        error: error.message,
+        selectedItem: null,
+        isEditing: false
+      };
+    }
+  };
+
+  view = (state: ComponentState) => {
+    // Guard clauses for early returns
+    if (state.loading) return <div>Loading...</div>;
+    if (state.error) return <div>Error: {state.error}</div>;
+    if (state.data.length === 0) return <div>No data</div>;
+    
+    // Main content
+    return (
+      <div>
+        {/* Render main UI */}
+        <PresentationComponent
+          data={state.data}
+          selectedItem={state.selectedItem}
+          onSelect={(item) => this.run('select-item', item)}
+        />
+      </div>
+    );
+  };
+
+  update = {
+    'select-item': (state: ComponentState, item: DataType): ComponentState => ({
+      ...state,
+      selectedItem: item
+    }),
+
+    'async-action': async function* (state: ComponentState): AsyncGenerator<ComponentState> {
+      try {
+        yield { ...state, loading: true, error: null };
+        const result = await performAsyncAction();
+        yield { ...state, loading: false, data: result };
+      } catch (error) {
+        yield { ...state, loading: false, error: error.message };
+      }
+    },
+
+    'side-effect-action': (state: ComponentState): void => {
+      // No return value = no re-render
+      window.location.href = '/new-page';
+    }
+  };
 }
 ```
 
-### **Multi-State Rendering**
-- State-driven conditional rendering with guard clauses
-- Early returns for cleaner code flow
-- Dedicated views for each state (loading, error, empty, main)
+### **Pattern 3: Functional Presentation Component**
 
-### **Accessibility & Responsive Design**
-1. Use semantic HTML elements
-2. Add `title` attributes for tooltips
-3. Proper button usage over div+click
-4. Use conditional rendering based on data size
-5. Implement adaptive visibility logic
-6. Mobile-first button sizing
+```typescript
+interface ComponentProps {
+  data: DataType[];
+  selectedItem: DataType | null;
+  loading?: boolean;
+  error?: string | null;
+  // Event handlers
+  onSelect?: (item: DataType) => void;
+  onDelete?: (id: string) => void;
+}
 
-## Step 4: Implement Event Handling
+export default function MyPresentationComponent(props: ComponentProps) {
+  const {
+    data,
+    selectedItem,
+    loading = false,
+    error = null,
+    onSelect,
+    onDelete
+  } = props;
+
+  // Guard clauses
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (data.length === 0) return <div>No data</div>;
+
+  return (
+    <div>
+      {data.map(item => (
+        <div 
+          key={item.id}
+          $onclick={['select-item', item]}
+          className={selectedItem?.id === item.id ? 'selected' : ''}
+        >
+          {item.name}
+          <button $onclick={['delete-item', item.id]}>Delete</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Event Handling Rules
 
-### **$onclick Usage Rules**
+### **✅ DO: Use $on Directives for State Updates**
 
-#### Action Pattern
 ```typescript
-// String actions for simple state updates
-$onclick='action-name'
+// String actions (handled in parent's update object)
+$onclick="action-name"
+$oninput="update-field"
 
-// Tuple actions for data passing
+// Tuple actions (pass data to handler)
 $onclick={['action-name', data]}
+$oninput={['update-field', 'fieldName']}
+$onchange={['update-dropdown', 'provider']}
+
+// Direct function references (modern pattern - recommended)
+$onclick={[saveFunction]}
+$onclick={[deleteFunction]}
+$onclick={[closeModal]}
 ```
 
-#### Event Handling Best Practices
-1. Use `$onclick` for all click events
-2. Simple actions: string literals
-3. Data passing: tuple format `[action, data]`
-4. Conditional actions: ternary in JSX
+### **✅ DO: Use $bind for Two-Way Data Binding**
 
-#### Action Naming Convention
-- Use kebab-case: `'prev-item'`, `'next-item'`
-- Be descriptive: `'select-item'`, `'enter-item'`
-- Match business logic, not UI elements
+```typescript
+// Automatic form field binding (modern pattern)
+<input 
+  value={state.formData.name}
+  $bind="formData.name"
+/>
+
+<textarea 
+  value={state.formData.description}
+  $bind="formData.description"
+/>
+
+<select 
+  value={state.formData.provider}
+  $bind="formData.provider"
+>
+  <option value="openai">OpenAI</option>
+  <option value="anthropic">Anthropic</option>
+</select>
+```
 
-## Step 5: Create Update Functions
+### **✅ DO: Use Regular Properties for Non-State Actions**
 
-### **Update Function Signatures**
 ```typescript
-update = {
-  // State update (returns new state)
-  'action-name': (state: State, payload?: any): State => ({ ...state, changes }),
+// DOM manipulation only
+onclick={(e) => e.stopPropagation()}
+onmouseenter={(e) => e.target.focus()}
 
-  // Side effect (no return, no re-render)
-  'action-name': (state: State, payload?: any): void => { /* side effects */ },
+// Side effects (functions that call app.run() or navigate)
+onclick={handleSideEffect}  // function calls app.run() internally
+onclick={() => window.open('/new-page')}
 
-  // Async operations (generators for progressive updates)
-  'action-name': async function* (state: State): AsyncGenerator<State> { /* async logic */ }
-}
+// Event prevention
+onsubmit={(e) => e.preventDefault()}
 ```
 
-### **State Management Pattern**
-- Use immutable state updates with spread operator
-- Single source of truth for component state
-- Handle all state transitions explicitly
+### **❌ DON'T: Mix Patterns Incorrectly**
+
+```typescript
+// ❌ Don't use $on with app.run() calls
+$onclick={() => app.run('action')}
+$onclick={(e) => this.run('action', e.target.value)}
+
+// ❌ Don't use regular props for state updates
+onclick="action-name"  // Use $onclick for state updates
+
+// ❌ Don't use arrow functions for simple state updates
+$onclick={(e) => ({ ...state, field: e.target.value })}
 
-## Step 6: Handle Data Loading
+// ❌ Don't use manual form handlers when $bind is available
+$oninput={(e) => updateField('name', e)}  // Use $bind="formData.name" instead
+```
 
-### **Data Loading Patterns**
-- Use async state function for initial data loading
-- Async generator pattern for progressive updates during user interactions
-- Graceful handling of loading transitions
+## Update Function Patterns
 
+### **Module-Level State Update Functions (Modern - Recommended)**
 ```typescript
-// Progressive updates for user interactions
-update = {
-  'refresh-data': async function* (state: State): AsyncGenerator<State> {
-    try {
-      yield { ...state, loading: true, error: null };
-      const data = await fetchData();
-      yield { ...state, data, loading: false, error: null };
-    } catch (error: any) {
-      yield { ...state, loading: false, error: error.message };
+// Export functions for direct references in $on directives
+export const saveData = async function* (state: State): AsyncGenerator<State> {
+  yield { ...state, loading: true, error: null };
+  try {
+    await performSave(state.formData);
+    yield { 
+      ...state, 
+      loading: false, 
+      successMessage: 'Data saved successfully!' 
+    };
+    // Global event for parent coordination
+    setTimeout(() => app.run('data-saved'), 2000);
+  } catch (error) {
+    yield { ...state, loading: false, error: error.message };
+  }
+};
+
+export const deleteData = async function* (state: State): AsyncGenerator<State> {
+  yield { ...state, loading: true, error: null };
+  try {
+    await performDelete(state.formData.id);
+    yield { 
+      ...state, 
+      loading: false, 
+      successMessage: 'Data deleted successfully!' 
+    };
+    setTimeout(() => app.run('data-deleted'), 2000);
+  } catch (error) {
+    yield { ...state, loading: false, error: error.message };
+  }
+};
+
+export const closeModal = (): void => {
+  app.run('close-modal');  // Global event for parent
+};
+```
+
+### **Legacy Update Functions (Traditional Pattern)**
+```typescript
+// Synchronous state update
+'action-name': (state: State, payload?: any): State => ({
+  ...state,
+  // immutable updates
+  field: newValue
+}),
+
+// Async progressive updates
+'async-action': async function* (state: State, payload?: any): AsyncGenerator<State> {
+  try {
+    yield { ...state, loading: true, error: null };
+    const result = await asyncOperation(payload);
+    yield { ...state, loading: false, data: result };
+  } catch (error) {
+    yield { ...state, loading: false, error: error.message };
+  }
+},
+
+// Side effect (no re-render)
+'navigate-action': (state: State, path: string): void => {
+  window.location.href = path;
+},
+
+// Form field updates (common pattern)
+'update-form-field': (state: State, field: string, event: Event): State => {
+  const target = event.target as HTMLInputElement;
+  const value = target.type === 'number' ? parseFloat(target.value) || 0 : target.value;
+  
+  return {
+    ...state,
+    formData: {
+      ...state.formData,
+      [field]: value
     }
+  };
+}
+```
+
+## Component Composition Patterns
+
+### **Parent-Child with Global Events (Modern - Recommended)**
+```typescript
+// Parent Component (simplified state)
+export default class WorldComponent extends Component<WorldState> {
+  view = (state: WorldState) => (
+    <div>
+      {/* Core world UI */}
+      <div className="world-content">
+        {state.agents.map(agent => (
+          <div key={agent.id} $onclick={['open-agent-edit', agent]}>
+            {agent.name}
+          </div>
+        ))}
+      </div>
+
+      {/* Conditional modal rendering */}
+      {state.showAgentEdit && 
+        <AgentEdit 
+          agent={state.selectedAgent} 
+          mode={state.editMode}
+          worldName={state.worldName}
+        />
+      }
+    </div>
+  );
+
+  update = {
+    'open-agent-edit': (state, agent) => ({
+      ...state,
+      showAgentEdit: true,
+      editMode: 'edit',
+      selectedAgent: agent
+    }),
+
+    'close-agent-edit': (state) => ({
+      ...state,
+      showAgentEdit: false
+    }),
+
+    // Global events from child components
+    'agent-saved': async (state) => {
+      const agents = await getAgents(state.worldName);
+      return { ...state, agents, showAgentEdit: false };
+    },
+
+    'agent-deleted': async (state) => {
+      const agents = await getAgents(state.worldName);
+      return { ...state, agents, showAgentEdit: false };
+    }
+  };
+}
+
+// Self-contained child component
+export default class AgentEdit extends Component<AgentEditState> {
+  mounted = (props) => initializeState(props);
+
+  view = (state) => (
+    <div className="modal-backdrop" $onclick={[closeModal]}>
+      <form>
+        <input $bind="formData.name" />
+        <button $onclick={[saveAgent]}>Save</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### **Container + Presentation Pattern (Legacy)**
+```typescript
+// Container Component (manages state)
+export default class WorldComponent extends Component<WorldState> {
+  view = (state: WorldState) => (
+    <div>
+      <WorldChat
+        messages={state.messages}
+        userInput={state.userInput}
+        onSendMessage={(text) => this.run('send-message', text)}
+      />
+      <WorldSettings
+        world={state.world}
+        selectedAgent={state.selectedAgent}
+        onEditAgent={(agent) => this.run('edit-agent', agent)}
+      />
+    </div>
+  );
+}
+
+// Presentation Components (stateless)
+function WorldChat(props: WorldChatProps) { /* render only */ }
+function WorldSettings(props: WorldSettingsProps) { /* render only */ }
+```
+
+## State Management Rules
+
+### **✅ DO: Immutable Updates**
+```typescript
+// Spread operator for updates
+{ ...state, field: newValue }
+
+// Nested object updates
+{
+  ...state,
+  nested: {
+    ...state.nested,
+    field: newValue
   }
 }
+
+// Array updates
+{
+  ...state,
+  items: [...state.items, newItem],
+  filteredItems: state.items.filter(item => item.id !== deletedId)
+}
 ```
 
-## Step 7: Error Handling
+### **✅ DO: Defensive Programming**
+```typescript
+// Safe array operations
+messages: state.messages || []
+count: (state.items || []).length
 
-### **Error Handling Strategy**
-1. Wrap async operations in try-catch
-2. Yield error states in generators
-3. Provide user-friendly error messages
-4. Include retry mechanisms
-5. Defensive programming with null checks
+// Safe object access
+selectedItem: state.selectedItem?.name || 'None'
 
-## Step 8: Navigation & Side Effects
+// Default props in functional components
+const { data = [], loading = false } = props;
+```
 
-### **Navigation & Side-Effect Actions**
-1. Use void actions for navigation (no re-render)
-2. Direct `window.location.href` for page changes
-3. Use anchor tags `<a href>` for static links
-4. Actions with void return indicate no re-render needed
+### **❌ DON'T: Mutate State**
+```typescript
+// ❌ Don't mutate existing state
+state.field = newValue;
+state.items.push(newItem);
+state.nested.field = value;
+
+// ❌ Don't use non-immutable array methods
+state.items.sort();
+state.items.reverse();
+```
+
+## Error Handling Patterns
 
+### **Component Error States**
 ```typescript
-'navigate-action': (state: State, data: any): void => {
-  window.location.href = '/path/' + data.id;
+// State interface includes error
+interface State {
+  data: DataType[];
+  loading: boolean;
+  error: string | null;
+}
+
+// View handles error states
+view = (state: State) => {
+  if (state.error) {
+    return (
+      <div className="error-state">
+        <p>Error: {state.error}</p>
+        <button $onclick="retry-action">Retry</button>
+      </div>
+    );
+  }
+  // ... rest of view
+};
+
+// Update functions handle errors
+'load-data': async function* (state: State): AsyncGenerator<State> {
+  try {
+    yield { ...state, loading: true, error: null };
+    const data = await fetchData();
+    yield { ...state, loading: false, data, error: null };
+  } catch (error: any) {
+    yield { ...state, loading: false, error: error.message || 'Unknown error' };
+  }
 }
 ```
 
+## Best Practices Summary
+
+### **Component Design (Modern Patterns)**
+- **Prefer stateful class components** with `mounted` lifecycle for self-contained components
+- **Use module-level functions** for state updates to enable easy testing
+- **Use $bind for form fields** instead of manual event handlers
+- **Use direct function references** in $on directives: `$onclick={[saveFunction]}`
+- **Use global events** for parent-child coordination
+- Implement guard clauses for loading/error/empty states
+- Follow single responsibility principle
+
+### **Event Handling (Updated Rules)**
+- **$bind for two-way data binding**: `$bind="formData.fieldName"`
+- **$on directives with direct function references**: `$onclick={[functionRef]}`
+- **String/tuple actions for legacy patterns**: `$onclick="action-name"` or `$onclick={['action', data]}`
+- **Regular properties for DOM manipulation**: `onclick={(e) => e.stopPropagation()}`
+- **Global events for coordination**: `app.run('component-saved')`
+
+### **State Management (Enhanced)**
+- **Module-level functions** return new state or use async generators
+- **$bind automatically handles** form field updates
+- **Global events coordinate** between parent and child components
+- Always use immutable updates with spread operator
+- Include loading, error, and success message states
+- Use async generators for progressive updates
+- Implement defensive programming with null checks
+
+### **Architecture Patterns**
+- **Self-contained components** manage their own form state using `mounted`
+- **Parent components** use simple boolean flags for conditional rendering
+- **Module-level functions** enable easy unit testing
+- **Global events** provide loose coupling between components
+- **Success messages** with auto-close functionality
+- **Modal patterns** with backdrop click to close
+
+### **Type Safety**
+- Define comprehensive state interfaces with success message states
+- Use proper TypeScript types for all module-level functions
+- Type component props correctly for mounted pattern
+- Provide default values for optional props
+
+This guide covers modern AppRun patterns with emphasis on stateful components, module-level functions, $bind for forms, and global event coordination.