apprun 3.35.0 → 3.36.1

package/src/directive.ts

@@ -2,22 +2,38 @@
  * Component Directives Implementation
  * 
  * This file provides built-in directives for components:
- * 1. Event Binding
+ * 1. Event Binding ($on directives)
  *    - $on: Bind DOM events to component events
  *    - Supports event delegation and parameters
  *    - Handles function, string, and array event handlers
+ *    - Type-safe event target handling
  * 
- * 2. Two-way Data Binding
+ * 2. Two-way Data Binding ($bind directive)
  *    - $bind: Sync form elements with component state
- *    - Handles input types: text, checkbox, radio, select
- *    - Automatic value type conversion
+ *    - Handles input types: text, checkbox, radio, number, range
+ *    - Supports select (single/multiple) and textarea elements
+ *    - Automatic value type conversion for numbers
  *    - Support for complex property paths
  * 
  * 3. Custom Directives
- *    - Extensible directive system
+ *    - Extensible directive system via '$' events
  *    - Processes virtual DOM during rendering
  *    - Supports custom attribute directives
  * 
+ * Features:
+ * - Automatic state synchronization
+ * - Type conversion for form inputs
+ * - Event delegation support
+ * - Multiple event handler formats
+ * - Nested property binding
+ * - Custom directive extensibility
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Added null checks for event targets before type assertions
+ * - Proper typing for different HTML element types
+ * - Enhanced error handling for invalid event targets
+ * - Safer DOM element property access
+ *
  * Usage:
  * ```tsx
  * // Event binding
@@ -27,10 +43,14 @@
  * // Two-way binding
  * <input $bind="state.property" />
  * <select $bind="selected">...</select>
+ * 
+ * // Array handlers
+ * <button $onclick={['handler', param1, param2]}>Click</button>
  * ```
  */
 
 import app from './app';
+import { safeEventTarget } from './type-utils';
 
 const getStateValue = (component, name) => {
   return (name ? component['state'][name] : component['state']) || '';
@@ -72,34 +92,65 @@ const apply_directive = (key: string, props: {}, tag, component) => {
       switch (type) {
         case 'checkbox':
           props['checked'] = getStateValue(component, name);
-          props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.checked);
+          props['onclick'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.checked);
+            }
+          };
           break;
         case 'radio':
           props['checked'] = getStateValue(component, name) === props['value'];
-          props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.value);
+          props['onclick'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.value);
+            }
+          };
           break;
         case 'number':
         case 'range':
           props['value'] = getStateValue(component, name);
-          props['oninput'] = e => setStateValue(component, name || e.target.name, Number(e.target.value));
+          props['oninput'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, Number(target.value));
+            }
+          };
           break;
         default:
           props['value'] = getStateValue(component, name);
-          props['oninput'] = e => setStateValue(component, name || e.target.name, e.target.value);
+          props['oninput'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.value);
+            }
+          };
       }
     } else if (tag === 'select') {
       props['value'] = getStateValue(component, name);
       props['onchange'] = e => {
-        if (!e.target.multiple) { // multiple selection use $bind on option
-          setStateValue(component, name || e.target.name, e.target.value);
+        const target = safeEventTarget<HTMLSelectElement>(e);
+        if (target && !target.multiple) { // multiple selection use $bind on option
+          setStateValue(component, name || target.name, target.value);
         }
       }
     } else if (tag === 'option') {
       props['selected'] = getStateValue(component, name);
-      props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.selected);
+      props['onclick'] = e => {
+        const target = safeEventTarget<HTMLOptionElement>(e);
+        if (target) {
+          setStateValue(component, name || (target as any).name, target.selected);
+        }
+      };
     } else if (tag === 'textarea') {
       props['innerHTML'] = getStateValue(component, name);
-      props['oninput'] = e => setStateValue(component, name || e.target.name, e.target.value);
+      props['oninput'] = e => {
+        const target = safeEventTarget<HTMLTextAreaElement>(e);
+        if (target) {
+          setStateValue(component, name || target.name, target.value);
+        }
+      };
     }
   } else {
     app.run('$', { key, tag, props, component });

package/src/router.ts

@@ -1,30 +1,302 @@
 /**
- * AppRun Router Implementation
+ * AppRun Router Implementation with Hierarchical Matching
  * 
  * This file provides URL routing capabilities:
  * 1. Hash-based routing (#/path)
+ *    - Works with SPA mode using hash fragments
+ *    - Handles hashchange events automatically
+ *    - No server configuration required
  * 2. Path-based routing (/path) 
+ *    - Works with browser history API
+ *    - Requires server configuration for SPA routing
+ *    - Handles popstate events automatically
  * 3. Event-based navigation
+ *    - Routes trigger corresponding component events
+ *    - Automatic route parameter extraction
+ *    - Fallback to 404 handling for unknown routes
  * 
  * Features:
- * - Automatic route event firing
- * - 404 handling via ROUTER_404_EVENT
- * - History API integration
- * - Route parameter parsing
+ * - Automatic route event firing with ROUTER_EVENT
+ * - 404 handling via ROUTER_404_EVENT for unmatched routes
+ * - History API integration for seamless navigation
+ * - Route parameter parsing and injection into events
+ * - URL pattern matching with parameter support
+ * - Global and component-level route handling
+ * - **NEW: Hierarchical route matching** - progressively tries parent routes
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced route type definitions
+ * - Better parameter type inference
+ * - Improved URL validation and error handling
  * 
  * Usage:
  * ```ts
- * // Handle routes
+ * // Basic routing
  * app.on('#/home', () => // Show home page);
  * app.on('#/users/:id', (id) => // Show user profile);
+ * app.on('/api/*', (path) => // Handle API routes);
  * 
- * // Navigate programmatically
+ * // Navigate programmatically  
  * app.run('route', '#/home');
+ * route('/users/123'); // Direct routing
+ * 
+ * // Hierarchical matching examples
+ * app.on('/api', (operation, id) => // Handle /api/users/123);
+ * app.on('#users', (id, action) => // Handle #users/123/edit);
+ * 
+ * // Hierarchical Route Matching (NEW):
+ * // For URL: /api/v1/users/123
+ * // Router tries: /api/v1/users/123 → /api/v1/users → /api/v1 → /api → 404
+ * // If handler found at /api, it receives: ('v1', 'users', '123')
+ * 
+ * // Base Path Support (NEW):
+ * app.basePath = '/myapp'; // For sub-directory deployments
+ * // Links: <a href="/users/123"> (relative paths)
+ * // Navigation: /myapp/users/123 (full path)
+ * // Routing: /users/123 (base path stripped)
+ * 
+ * // Empty Path Handling (NEW):
+ * // For URL: "" (empty)
+ * // Router tries: # → / → #/ → 404 (in priority order)
+ * 
+ * // 404 Behavior (ENHANCED):
+ * // Fires only at minimal levels: /a, #a, #/a, a
+ * // Never tries root handlers: /, #, #/
  * ```
  */
 
 import app from './app';
 
+// Helper functions for hierarchical routing
+
+/**
+ * Extract clean path segments from URL
+ * @param url - The URL to parse
+ * @returns Array of path segments
+ */
+function parsePathSegments(url: string): string[] {
+  if (!url) return [];
+
+  // Handle different URL types
+  if (url.startsWith('#/')) {
+    return url.substring(2).split('/');
+  } else if (url.startsWith('#')) {
+    return url.substring(1).split('/');
+  } else if (url.startsWith('/')) {
+    return url.substring(1).split('/');
+  } else {
+    return url.split('/');
+  }
+}
+
+/**
+ * Normalize trailing slash - convert /a/ to /a
+ * @param url - The URL to normalize
+ * @returns Normalized URL
+ */
+function normalizeTrailingSlash(url: string): string {
+  if (!url || url === '/' || url === '#' || url === '#/') return url;
+  if (url.endsWith('/')) return url.slice(0, -1);
+  return url;
+}
+
+/**
+ * Validate hierarchy depth and warn if too deep
+ * @param segments - Path segments to validate
+ */
+function validateHierarchyDepth(segments: string[]): void {
+  // Count non-empty segments for depth validation
+  const nonEmptySegments = segments.filter(Boolean);
+  if (nonEmptySegments.length > 11) {
+    console.warn(`Deep route hierarchy detected: ${nonEmptySegments.join('/')} (${nonEmptySegments.length} levels)`);
+  }
+}
+
+/**
+ * Strip base path from URL
+ * @param url - The URL to process
+ * @param basePath - The base path to remove
+ * @returns URL with base path removed
+ */
+function stripBasePath(url: string, basePath: string): string {
+  if (!basePath || basePath === '/' || basePath === '') return url;
+
+  // Normalize base path
+  const normalizedBasePath = basePath.startsWith('/') ? basePath : '/' + basePath;
+
+  if (url.startsWith(normalizedBasePath)) {
+    const stripped = url.substring(normalizedBasePath.length);
+    return stripped.startsWith('/') ? stripped : '/' + stripped;
+  }
+
+  return url;
+}
+
+/**
+ * Generate hierarchy of routes to try (stops at minimal level)
+ * @param segments - Array of path segments
+ * @param routeType - Type of route (path, hash, hash-slash, non-prefixed)
+ * @returns Array of route names to try in order
+ */
+function generateRouteHierarchy(segments: string[], routeType: 'path' | 'hash' | 'hash-slash' | 'non-prefixed'): string[] {
+  const hierarchy: string[] = [];
+
+  // Build hierarchy from most specific to least specific
+  for (let i = segments.length; i > 0; i--) {
+    const currentSegments = segments.slice(0, i);
+    let routeName = '';
+
+    switch (routeType) {
+      case 'path':
+        routeName = '/' + currentSegments.join('/');
+        break;
+      case 'hash':
+        routeName = '#' + currentSegments.join('/');
+        break;
+      case 'hash-slash':
+        routeName = '#/' + currentSegments.join('/');
+        break;
+      case 'non-prefixed':
+        routeName = currentSegments.join('/');
+        break;
+    }
+
+    hierarchy.push(routeName);
+  }
+
+  return hierarchy;
+}
+
+/**
+ * Find handler in hierarchy and return handler info
+ * @param hierarchy - Array of route names to try
+ * @param originalSegments - Original path segments
+ * @returns Handler info if found, null otherwise
+ */
+function findHandlerInHierarchy(hierarchy: string[], originalSegments: string[]): { eventName: string; parameters: string[] } | null {
+  for (let i = 0; i < hierarchy.length; i++) {
+    const routeName = hierarchy[i];
+    const subscribers = app.find(routeName);
+
+    if (subscribers && subscribers.length > 0) {
+      // Found handler - calculate remaining parameters
+      const handlerDepth = hierarchy.length - i;
+      const parameters = originalSegments.slice(handlerDepth);
+
+      return {
+        eventName: routeName,
+        parameters: parameters
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Handle empty path with priority order: # → / → #/ → 404
+ */
+function handleEmptyPath(): void {
+  // Try # first
+  const hashSubscribers = app.find('#');
+  if (hashSubscribers && hashSubscribers.length > 0) {
+    app.run('#');
+    app.run(ROUTER_EVENT, '#');
+    return;
+  }
+
+  // Try / second
+  const pathSubscribers = app.find('/');
+  if (pathSubscribers && pathSubscribers.length > 0) {
+    app.run('/');
+    app.run(ROUTER_EVENT, '/');
+    return;
+  }
+
+  // Try #/ third
+  const hashSlashSubscribers = app.find('#/');
+  if (hashSlashSubscribers && hashSlashSubscribers.length > 0) {
+    app.run('#/');
+    app.run(ROUTER_EVENT, '#/');
+    return;
+  }
+
+  // Fire 404 if no handlers found
+  console.warn('No subscribers for event: ');
+  app.run(ROUTER_404_EVENT, '');
+  app.run(ROUTER_EVENT, '');
+}
+
+/**
+ * Main hierarchical routing logic
+ * @param url - The URL to route
+ */
+function routeWithHierarchy(url: string): void {
+  // Handle empty path
+  if (!url) {
+    handleEmptyPath();
+    return;
+  }
+
+  // Normalize trailing slash
+  url = normalizeTrailingSlash(url);
+
+  // Strip base path if configured
+  const basePath = app['basePath'];
+  if (basePath) {
+    url = stripBasePath(url, basePath);
+  }
+
+  // Parse segments and validate depth
+  const segments = parsePathSegments(url);
+  validateHierarchyDepth(segments);
+
+  // Determine route type
+  let routeType: 'path' | 'hash' | 'hash-slash' | 'non-prefixed';
+  if (url.startsWith('#/')) {
+    routeType = 'hash-slash';
+  } else if (url.startsWith('#')) {
+    routeType = 'hash';
+  } else if (url.startsWith('/')) {
+    routeType = 'path';
+  } else {
+    routeType = 'non-prefixed';
+  }
+
+  // Generate hierarchy
+  const hierarchy = generateRouteHierarchy(segments, routeType);
+
+  // Find handler in hierarchy
+  const handlerInfo = findHandlerInHierarchy(hierarchy, segments);
+
+  if (handlerInfo) {
+    // Found handler - publish route with parameters
+    publishRoute(handlerInfo.eventName, ...handlerInfo.parameters);
+  } else {
+    // No handler found - fire 404 with original URL
+    if (hierarchy.length > 0) {
+      const minimalRoute = hierarchy[hierarchy.length - 1];
+      console.warn(`No subscribers for event: ${minimalRoute}`);
+      app.run(ROUTER_404_EVENT, url);
+      app.run(ROUTER_EVENT, url);
+    } else {
+      handleEmptyPath();
+    }
+  }
+}
+
+const publishRoute = (name: string, ...args: any[]) => {
+  if (!name || name === ROUTER_EVENT || name === ROUTER_404_EVENT) return;
+  const subscribers = app.find(name);
+  if (!subscribers || subscribers.length === 0) {
+    console.warn(`No subscribers for event: ${name}`);
+    app.run(ROUTER_404_EVENT, name, ...args);
+  } else {
+    app.run(name, ...args);
+  }
+  app.run(ROUTER_EVENT, name, ...args);
+}
+
 export type Route = (url: string, ...args: any[]) => any;
 
 export const ROUTER_EVENT: string = '//';
@@ -32,18 +304,8 @@ export const ROUTER_404_EVENT: string = '///';
 export const route: Route = (url: string) => {
   if (app['lastUrl'] === url) return; // Prevent duplicate routing
   app['lastUrl'] = url;
-  if (!url) url = '#';
-  if (url.startsWith('#')) {
-    const [name, ...rest] = url.split('/');
-    app.run(name, ...rest) || app.run(ROUTER_404_EVENT, name, ...rest);
-    app.run(ROUTER_EVENT, name, ...rest);
-  } else if (url.startsWith('/')) {
-    const [_, name, ...rest] = url.split('/');
-    app.run('/' + name, ...rest) || app.run(ROUTER_404_EVENT, '/' + name, ...rest);
-    app.run(ROUTER_EVENT, '/' + name, ...rest);
-  } else {
-    app.run(url) || app.run(ROUTER_404_EVENT, url);
-    app.run(ROUTER_EVENT, url);
-  }
+
+  // Use hierarchical routing logic
+  routeWithHierarchy(url);
 }
 export default route;

package/src/type-utils.ts

@@ -0,0 +1,130 @@
+/**
+ * Type Safety Utilities for AppRun
+ * 
+ * This file provides utility functions and types to improve type safety
+ * across the AppRun framework, including:
+ * 1. Safe type assertions with null checks
+ * 2. Global object assignment helpers
+ * 3. Event target type guards
+ * 4. Function validation utilities
+ */
+
+/**
+ * Safely cast event target to specific HTML element type with null check
+ */
+export function safeEventTarget<T extends HTMLElement = HTMLElement>(event: Event): T | null {
+  return event?.target instanceof HTMLElement ? event.target as T : null;
+}
+
+/**
+ * Type guard to check if an object is a valid function
+ */
+export function isFunction(obj: any): obj is Function {
+  return typeof obj === 'function';
+}
+
+/**
+ * Type guard to check if an object is a valid HTML element
+ */
+export function isHTMLElement(obj: any): obj is HTMLElement {
+  return obj instanceof HTMLElement;
+}
+
+/**
+ * Safely assign properties to global object with type checking
+ */
+export function safeGlobalAssign<T extends Record<string, any>>(
+  globalObj: any,
+  assignments: T
+): void {
+  if (typeof globalObj === 'object' && globalObj !== null) {
+    Object.keys(assignments).forEach(key => {
+      globalObj[key] = assignments[key];
+    });
+  }
+}
+
+/**
+ * Safely get property from global object with fallback
+ */
+export function safeGlobalGet<T>(
+  globalObj: any,
+  property: string,
+  fallback?: T
+): T | undefined {
+  if (typeof globalObj === 'object' && globalObj !== null) {
+    return globalObj[property] ?? fallback;
+  }
+  return fallback;
+}
+
+/**
+ * Type-safe wrapper for DOM element queries
+ */
+export function safeQuerySelector<T extends Element = Element>(
+  selector: string,
+  context: Document | Element = document
+): T | null {
+  try {
+    return context.querySelector<T>(selector);
+  } catch (error) {
+    console.warn(`Invalid selector: ${selector}`, error);
+    return null;
+  }
+}
+
+/**
+ * Type-safe wrapper for DOM element by ID
+ */
+export function safeGetElementById<T extends HTMLElement = HTMLElement>(
+  id: string
+): T | null {
+  try {
+    return document.getElementById(id) as T | null;
+  } catch (error) {
+    console.warn(`Error getting element by id: ${id}`, error);
+    return null;
+  }
+}
+
+/**
+ * Validate and safely execute a function with error handling
+ */
+export function safeExecute<T extends any[], R>(
+  fn: ((...args: T) => R) | undefined | null,
+  args: T,
+  context?: any,
+  errorMessage?: string
+): R | undefined {
+  if (!isFunction(fn)) {
+    if (errorMessage) {
+      console.warn(errorMessage, fn);
+    }
+    return undefined;
+  }
+
+  try {
+    return context ? fn.apply(context, args) : fn(...args);
+  } catch (error) {
+    console.error(errorMessage || 'Error executing function:', error);
+    return undefined;
+  }
+}
+
+/**
+ * Type definitions for improved global object safety
+ */
+export interface SafeGlobalWindow {
+  Component?: any;
+  _React?: any;
+  React?: any;
+  on?: any;
+  customElement?: any;
+  safeHTML?: any;
+  html?: any;
+  svg?: any;
+  run?: any;
+  [key: string]: any;
+}
+
+export type SafeGlobalContext = SafeGlobalWindow | typeof globalThis | any;

package/src/types.ts

@@ -4,26 +4,47 @@
  * This file defines the fundamental types used across AppRun:
  * 1. Component Types
  *    - View: Function that renders state to VDOM
- *    - Action: Function that updates state
- *    - Update: Collection of actions
+ *    - Action: Function that updates state (sync/async)
+ *    - Update: Collection of actions (array or object format)
+ *    - ActionDef: Tuple definition for action arrays
  * 
  * 2. Virtual DOM Types
- *    - VNode: Virtual DOM node structure
- *    - VDOM: Union of possible VDOM types
- *    - Element: DOM element references
+ *    - VNode: Virtual DOM node structure with tag/props/children
+ *    - VDOM: Union of possible VDOM types (false, string, VNode, array)
+ *    - Element: DOM element references (HTMLElement or string selector)
+ *    - TemplateResult: Lit-html template support
  * 
  * 3. Configuration Types
- *    - EventOptions: Event handler options (once, delay, etc)
- *    - ActionOptions: Action behavior options (render, history, etc)
- *    - MountOptions: Component mounting options (global events, routing)
- *    - AppStartOptions: Application startup configuration
+ *    - EventOptions: Event handler options (once, delay, transition)
+ *    - ActionOptions: Action behavior options (render, history, global, callback)
+ *    - MountOptions: Component mounting options (global events, routing, transitions)
+ *    - AppStartOptions: Application startup configuration with lifecycle hooks
  * 
+ * Features:
+ * - Strong typing for component lifecycle
+ * - Flexible action definition formats
+ * - Comprehensive event options
+ * - Integration with external libraries (lit-html)
+ * - Type-safe component mounting
+ * - Lifecycle hook typing
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced generic constraints for better type inference
+ * - Improved union types for VDOM flexibility
+ * - Better callback typing in options
+ * - Stricter typing for lifecycle methods
+ *
  * Usage:
  * ```ts
- * class MyComponent implements Component<State> {
+ * class MyComponent extends Component<State, Events> {
  *   view: View<State>;
- *   update: Update<State>;
+ *   update: Update<State, Events>;
  * }
+ * 
+ * // Type-safe action definitions
+ * const update: Update<State> = {
+ *   'event': (state: State, ...args) => newState
+ * };
  * ```
  */
 
@@ -59,5 +80,5 @@ export type AppStartOptions<T> = {
   transition?: boolean;
   route?: string;
   rendered?: (state: T) => void
-  mounted?: (props:any, children:any, state: T) => T
+  mounted?: (props: any, children: any, state: T) => T
 };