apprun 3.37.0 → 3.37.2

package/CHANGELOG.md

@@ -1,17 +1,34 @@
 # Change Log
 
-## Releases
+## V3.37.2
+
+* Include rule / prompt files for AI Coding Agent
+* Improved type definitions for better TypeScript support
+  - Support async function and async generator in `Action<T>` that is used in `Update<T, E>`
+  - Added `State` type to allow the initial state to be a function or an async function
+* Fixed routing basePath initialization issue - not to set basePath to location.pathname by default
+
+## V3.37.1
+
+* Make `immer` and `property-information` as dependencies
+
+## V3.37.0
+
+* Introduced `createState` helper for simplified immutable state updates using Immer [create-state-immer](#docs/done/blog-create-state-immer.md)
+* Added `addComponents` function for adding components to routes [add-components](#docs/done/blog-addcomponents-feature.md)
+* Moved the component to dev-tools
+
 
 ## 3.36.1
 
 * Continue code review with AI
 * Use property-information to improve property and attribute handling
-* Performance improvements in virtual DOM handling, see [analysis reports](docs/done/framework-reordering-comparison.md)
-* New hierarchical matching behavior, see [hierarchical routing requirements](docs/requirements/req-hierarchical-routing.md)
+* Performance improvements in virtual DOM handling, see [analysis reports](#docs/done/framework-reordering-comparison.md)
+* New hierarchical matching behavior, see [hierarchical routing requirements](#docs/requirements/req-hierarchical-routing.md)
 
 ## 3.36.0
 
-* Code review by using Copilot and Claude Sonnet 4, see [plan-apprun-bugfixes.md](docs/plan/plan-apprun-bugfixes.md) for details. 
+* Code review by using Copilot and Claude Sonnet 4, see [plan-apprun-bugfixes.md](#docs/plan/plan-apprun-bugfixes.md) for details. 
 * Enhanced type definitions (apprun.d.ts) for better TypeScript support
 * Fixed minor bugs and edge cases in virtual DOM handling
 * Fixed bugs in router initialization logic

package/README.md

@@ -3,6 +3,9 @@
 [![AppRun Docs](https://img.shields.io/badge/docs-website-blue.svg)](https://apprun.js.org/docs)
 [![AppRun Playground](https://img.shields.io/badge/playground-online-green.svg)](https://apprun.js.org/#play)
 [![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][downloads-url] [![License][license-image]][license-url] [![twitter][twitter-badge]][twitter] [![Discord Chat][discord-image]][discord-invite]
+🕵️ We now have rule / prompt files that you can use with your AI Coding Agent:
+- [For Components using JSX](ai/apprun.prompt.md)
+- [For Components using HTML](ai/apprun-html.prompt.md)
 
 🚀 July 2025, We have started to improve the codebase using AI. See [whats new](#new) for details.
 

package/ai/apprun-html.prompt.md

@@ -0,0 +1,290 @@
+---
+mode: agent
+---
+
+# AppRun Component Creation Rules
+
+When creating AppRun components, follow these guidelines for consistent, maintainable code.
+
+## Core Component Architecture
+- **HTML templates**: Always use `html` tagged literals for UI rendering
+- **State management**: Handle state through event handlers that return new state objects
+- **Event handling**: Use `event-name` syntax in templates with handlers `(state, param) => newState`
+- **Local events**: Use `run()` for component-local events (no registration needed)
+- **Immutable updates**: Always return new state objects, never mutate existing state
+
+## Component Creation Patterns
+
+### 1. Functional Components (Pure UI Components)
+**When to use**: For reusable UI pieces that don't manage their own state.
+
+```js
+// Create pure function components that take props and return HTML
+export const AgentModal = (agent, onClose) => {
+  return html`
+    <div class="modal-overlay" @click=${run(onClose, false)}>
+      <div class="modal-content" @click=${(e) => e.stopPropagation()}>
+        <!-- Use conditional rendering for dynamic content -->
+        ${agent.status ? html`<h2>${agent.name}</h2>` : html`
+          <input value="${agent.name || ''}" @input=${(e) => agent.name = e.target.value}>
+        `}
+      </div>
+    </div>
+  `;
+};
+```
+
+**Rules for functional components**:
+- Export as pure functions
+- Accept props as parameters
+- Return HTML template literals
+- Handle events through callback props
+- No internal state management
+
+### 2. Stateful Page Components (Full Components)
+**When to use**: For main application views that manage state and handle complex interactions.
+
+**Step 1: Create async state initialization**
+```js
+// Always use async state function for API calls and data loading
+const state = async () => {
+  const data = await api.getData();
+  return { 
+    ...initialState, 
+    data,
+    loading: false 
+  };
+};
+```
+
+**Step 2: Define event handlers as separate functions**
+```js
+// Create specific handlers for each user interaction
+const selectWorld = async (state, worldName) => {
+  if (worldName === state.worldName) return state;
+  const agents = await api.getAgents(worldName);
+  return ({ ...state, worldName, agents });
+};
+
+const openModal = (state, item = null) => {
+  return ({
+    ...state,
+    editingItem: item || { name: 'New Item' },
+    showModal: true
+  });
+};
+```
+
+**Step 3: Create view function with proper rendering patterns**
+```js
+// View function should be pure - only render, never mutate
+const view = (state) => {
+  return html`
+    <div class="container">
+      ${state.items.map(item => html`
+        <div class="item" @click=${run(openModal, item)}>
+          ${item.name}
+        </div>
+      `)}
+      ${state.showModal ? ModalComponent(state.editingItem, closeModal) : ''}
+    </div>
+  `;
+};
+```
+
+**Step 4: Define minimal update object for routing**
+```js
+// Keep update object minimal - most events handled by run()
+const update = {
+  '/,#': state => state,
+  // Only add global events or routing here
+};
+```
+
+**Step 5: Export Component instance**
+```js
+// Create and export component instance without class syntax
+// enable global events with {global_event: true}
+export default new Component(state, view, update, {global_event: true});
+
+// Mount to DOM element
+component.start('#main'); // For visible components
+component.mount('#modal'); // For modal/hidden components
+```
+
+## Event Handling Best Practices
+
+### Using run() for Local Events
+**✅ Correct patterns**:
+```js
+// Simple event with parameter
+@click=${run(selectWorld, world.name)}
+
+// Event with callback function  
+@click=${run(closeModal, false)}
+
+// Global event
+@input=${run('updateModalAgentName')}
+```
+
+**❌ Common mistakes to avoid**:
+```js
+// DON'T wrap run() in arrow function - prevents re-rendering
+@click=${() => run(selectWorld, world.name)}
+
+// DON'T manually pass event in arrow function
+@click=${(e) => run(updateName, e)}
+```
+
+### Event Handler Function Rules
+```js
+// Event handlers automatically receive event as last parameter
+const updateModalAgentName = (state, eventParam) => {
+  const name = eventParam.target.value;
+  return ({...state, agentName: name });
+};
+
+// Handle event.stopPropagation() in handler when needed
+const openAgentModal = (state, agent, e) => {
+  e.stopPropagation();
+  return ({...state, editingAgent: agent, showModal: true });
+};
+```
+
+
+## Template Rendering Guidelines
+
+### Conditional Rendering Patterns
+```js
+// Simple boolean conditions
+${state.loading ? html`<div>Loading...</div>` : ''}
+
+// Complex conditional with nested HTML blocks
+${agent.status ? html`
+  <h2>${agent.name}</h2>
+  <p>Status: Active</p>
+` : html`
+  <input value="${agent.name || ''}" @input=${run(updateName)}>
+  <button @click=${run(saveAgent)}>Save</button>
+`}
+```
+
+### List Rendering with map()
+```js
+// Basic list rendering
+${state.items.map(item => html`
+  <div class="${item.active ? 'active' : ''}">${item.name}</div>
+`)}
+
+// Complex list items with events
+${state.agents.map(agent => html`
+  <div class="agent-card" @click=${run(selectAgent, agent.id)}>
+    <h3>${agent.name}</h3>
+    <button @click=${run(editAgent, agent)} 
+            @click=${(e) => e.stopPropagation()}>
+      Edit
+    </button>
+  </div>
+`)}
+```
+
+### Component Composition
+```js
+// Pass data and callbacks to child components
+${state.showModal ? AgentModal(state.editingAgent, closeModal) : ''}
+
+// Conditional component rendering with fallbacks
+${state.currentView === 'list' 
+  ? AgentList(state.agents, selectAgent)
+  : AgentDetail(state.selectedAgent, goBack)
+}
+```
+
+## State Management Rules
+
+### Immutable State Updates
+```js
+// ✅ Always spread existing state for updates
+return ({ ...state, newProperty: value });
+
+// ✅ Update nested objects immutably
+return ({ 
+  ...state, 
+  user: { ...state.user, name: newName },
+  items: [...state.items, newItem]
+});
+
+// ❌ Never mutate state directly
+state.newProperty = value; // Wrong!
+state.items.push(newItem); // Wrong!
+```
+
+### Async State Updates
+```js
+// Standard async handler
+const handler = async (state, param) => {
+  try {
+    const data = await api.call(param);
+    return ({ ...state, data, loading: false });
+  } catch (error) {
+    return ({ ...state, error: error.message, loading: false });
+  }
+};
+
+// Generator for progressive updates
+const handler = async function* (state, param) {
+  yield ({ ...state, loading: true });
+  try {
+    const data = await api.call(param);
+    yield ({ ...state, data, loading: false });
+  } catch (error) {
+    yield ({ ...state, error: error.message, loading: false });
+  }
+};
+```
+
+### Error Handling in Components
+```js
+// Always handle errors in async operations
+const saveData = async (state, data) => {
+  try {
+    await api.saveData(data);
+    return ({ ...state, showModal: false, saved: true });
+  } catch (error) {
+    return ({ ...state, error: `Save failed: ${error.message}` });
+  }
+};
+```
+
+## Component Creation Checklist
+
+When creating any AppRun component, ensure you follow these rules:
+
+### Essential Requirements
+- ✅ **Event handlers must return new state** - No return = no re-render
+- ✅ **View functions are pure** - Only render, never mutate state  
+- ✅ **Use `run()` for local events** - No registration needed in update object
+- ✅ **Use `app.run()` for global events** - Cross-component communication
+- ✅ **Immutable state updates** - Always spread existing state `{...state, newProp}`
+- ✅ **HTML template literals** - Use `html` tagged templates for all UI
+- ✅ **Conditional rendering** - Use ternary operators and template conditionals
+
+### Component Structure Guidelines
+- ✅ **Functional components**: Export pure functions that take props and return HTML
+- ✅ **Stateful components**: Use async state, separate handlers, Component instance
+- ✅ **Error boundaries**: Always handle async errors in try/catch blocks
+- ✅ **Component composition**: Pass data and callbacks to child components
+- ✅ **Event delegation**: Use event.stopPropagation() when needed in handlers
+
+### File Organization
+- ✅ **One component per file** - Keep components focused and reusable
+- ✅ **Named exports for functions** - `export const ComponentName = (...) => html`
+- ✅ **Default export for pages** - `export default new Component(...)`
+- ✅ **Import dependencies** - Use static imports, omit `.js`/`.ts` extensions
+
+### Performance Considerations  
+- ✅ **Minimal update object** - Only include routing and global events
+- ✅ **Efficient rendering** - Use conditional rendering to avoid unnecessary DOM updates
+- ✅ **State normalization** - Keep state flat when possible for easier updates
+- ✅ **Event handler optimization** - Define handlers outside render when possible
+

package/ai/apprun.prompt.md

@@ -0,0 +1,166 @@
+---
+mode: agent
+---
+# AppRun Component Creation Guide
+
+## Core Concepts
+
+AppRun follows the State-View-Update architecture pattern with TypeScript support for type-safe component development.
+
+## Step 1: Define State Interface
+
+### **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
+
+```typescript
+interface ComponentState {
+  data: DataType[];
+  currentIndex: number;
+  loading: boolean;
+  error: string | null;
+}
+```
+
+## Step 2: Create Component Structure
+
+### **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
+
+```typescript
+export default class MyComponent extends Component<ComponentState> {
+  state = async () => {
+    const data = await getData();
+    return {
+      data,
+      currentIndex: 0,
+      loading: false,
+      error: null
+    };
+  }
+}
+```
+
+## Step 3: Design View Function
+
+### **View 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;
+}
+```
+
+### **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)
+
+### **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
+
+## Step 4: Implement Event Handling
+
+### **$onclick Usage Rules**
+
+#### Action Pattern
+```typescript
+// String actions for simple state updates
+$onclick='action-name'
+
+// Tuple actions for data passing
+$onclick={['action-name', data]}
+```
+
+#### 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
+
+#### Action Naming Convention
+- Use kebab-case: `'prev-item'`, `'next-item'`
+- Be descriptive: `'select-item'`, `'enter-item'`
+- Match business logic, not UI elements
+
+## Step 5: Create Update Functions
+
+### **Update Function Signatures**
+```typescript
+update = {
+  // State update (returns new state)
+  'action-name': (state: State, payload?: any): State => ({ ...state, changes }),
+
+  // Side effect (no return, no re-render)
+  'action-name': (state: State, payload?: any): void => { /* side effects */ },
+
+  // Async operations (generators for progressive updates)
+  'action-name': async function* (state: State): AsyncGenerator<State> { /* async logic */ }
+}
+```
+
+### **State Management Pattern**
+- Use immutable state updates with spread operator
+- Single source of truth for component state
+- Handle all state transitions explicitly
+
+## Step 6: Handle Data Loading
+
+### **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
+
+```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 };
+    }
+  }
+}
+```
+
+## Step 7: Error Handling
+
+### **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
+
+## Step 8: Navigation & Side Effects
+
+### **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
+
+```typescript
+'navigate-action': (state: State, data: any): void => {
+  window.location.href = '/path/' + data.id;
+}
+```
+

package/apprun.d.ts

@@ -31,6 +31,7 @@
  * - Comprehensive options typing matching implementation
  * - Added proper deprecation warnings
  * - Enhanced error handling and validation
+ * - Added support for async generator and generator functions in Action types
  */
 
 import { TemplateResult } from 'lit-html';
@@ -39,6 +40,8 @@ declare module 'apprun' {
 
   export type Element = HTMLElement | string;
 
+  export type State<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
+
   export type VNode = {
     tag: string | Function,
     props: {},
@@ -47,7 +50,7 @@ declare module 'apprun' {
 
   export type VDOM = false | string | VNode | Array<VNode | string> | TemplateResult;
   export type View<T> = (state: T) => VDOM | void;
-  export type Action<T> = (state: T, ...p: any[]) => T | Promise<T> | void;
+  export type Action<T> = (state: T, ...p: any[]) => T | Promise<T> | void | AsyncGenerator<T> | Generator<T>;
   export type ActionDef<T, E> = (readonly [E, Action<T>, {}?]);
   export type Update<T, E = any> = ActionDef<T, E>[] | { [name: string]: Action<T> | {}[] } | (E | Action<T> | {})[];
   export type Router = (url: string, ...args: any[]) => any;
@@ -106,7 +109,7 @@ declare module 'apprun' {
     /** @deprecated Use runAsync() instead. query() will be removed in a future version. */
     query(name: string, ...args: any[]): Promise<any[]>;
 
-    start<T, E = any>(element?: Element | string, model?: T, view?: View<T>, update?: Update<T, E>,
+    start<T, E = any>(element?: Element | string, state?: State<T>, view?: View<T>, update?: Update<T, E>,
       options?: AppStartOptions<T>): Component<T, E>;
 
     h(tag: string | Function, props?: any, ...children: any[]): VNode | VNode[];
@@ -126,9 +129,9 @@ declare module 'apprun' {
   }
 
   export class Component<T = any, E = any> {
-    constructor(state?: T, view?: View<T>, update?: Update<T, E>, options?: any);
+    constructor(state?: State<T>, view?: View<T>, update?: Update<T, E>, options?: any);
     readonly element: Element;
-    readonly state: T;
+    protected state: State<T>;
     view?: View<T>;
     update?: Update<T, E>;