apprun 3.38.0 → 6.0.0-rc.0

package/ai/apprun.prompt.md

@@ -1,602 +0,0 @@
-# AppRun Component Creation Guide
-
-## Core Architecture Patterns
-
-AppRun follows the State-View-Update architecture with TypeScript support. Choose the appropriate component pattern based on your needs:
-
-### **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.
-
-### **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
-// component-functions.ts
-export interface ComponentState {
-  mode: 'create' | 'edit' | 'delete';
-  formData: FormType;
-  loading: boolean;
-  error: string | null;
-  successMessage: string | null;
-}
-
-export interface ComponentProps {
-  mode?: string;
-  initialData?: FormType;
-}
-
-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> {
-  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>
-    );
-  };
-}
-```
-
-### **Pattern 2: Legacy Container Component**
-
-Traditional pattern with state initialization function.
-
-#### **Component Structure**
-```typescript
-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';
-    }
-  };
-}
-```
-
-### **Pattern 3: Functional Presentation Component**
-
-```typescript
-interface ComponentProps {
-  data: DataType[];
-  selectedItem: DataType | null;
-  loading?: boolean;
-  error?: string | null;
-  // Event handlers
-  onSelect?: (item: DataType) => void;
-  onDelete?: (id: string) => void;
-}
-
-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
-
-### **✅ DO: Use $on Directives for State Updates**
-
-```typescript
-// String actions (handled in parent's update object)
-$onclick="action-name"
-$oninput="update-field"
-
-// 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]}
-```
-
-### **✅ DO: Use $bind for Two-Way Data Binding**
-
-```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>
-```
-
-### **✅ DO: Use Regular Properties for Non-State Actions**
-
-```typescript
-// DOM manipulation only
-onclick={(e) => e.stopPropagation()}
-onmouseenter={(e) => e.target.focus()}
-
-// Side effects (functions that call app.run() or navigate)
-onclick={handleSideEffect}  // function calls app.run() internally
-onclick={() => window.open('/new-page')}
-
-// Event prevention
-onsubmit={(e) => e.preventDefault()}
-```
-
-### **❌ 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 })}
-
-// ❌ Don't use manual form handlers when $bind is available
-$oninput={(e) => updateField('name', e)}  // Use $bind="formData.name" instead
-```
-
-## Update Function Patterns
-
-### **Module-Level State Update Functions (Modern - Recommended)**
-```typescript
-// 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)
-}
-```
-
-### **✅ DO: Defensive Programming**
-```typescript
-// Safe array operations
-messages: state.messages || []
-count: (state.items || []).length
-
-// Safe object access
-selectedItem: state.selectedItem?.name || 'None'
-
-// Default props in functional components
-const { data = [], loading = false } = props;
-```
-
-### **❌ 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
-// 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.

package/dist/apprun-dev-tools-tests.js

@@ -1 +0,0 @@
-/* -- no need to include this file */

package/dist/apprun-dev-tools.js.LICENSE.txt

@@ -1 +0,0 @@
-/*! js-yaml 4.1.0 https://github.com/nodeca/js-yaml @license MIT */