apprun 3.38.0 → 6.0.0-rc.0

package/src/router.ts

@@ -1,311 +0,0 @@
-/**
- * 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 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
- * // 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  
- * 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);
-}
-
-import { Router } from './types';
-
-export const ROUTER_EVENT: string = '//';
-export const ROUTER_404_EVENT: string = '///';
-export const route: Router = (url: string) => {
-  if (app['lastUrl'] === url) return; // Prevent duplicate routing
-  app['lastUrl'] = url;
-
-  // Use hierarchical routing logic
-  routeWithHierarchy(url);
-}
-export default route;

package/src/shadow.tsx

@@ -1,8 +0,0 @@
-import app from './apprun';
-
-export default (_, children) => {
-  const el = document.createElement('section');
-  el.attachShadow({ mode: 'open' });
-  app.render(el.shadowRoot, children);
-  return <>{el}</>;
-};

package/src/tsconfig.json

@@ -1,16 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "es2020",
-		"module": "esnext",
-		"moduleResolution": "node",
-		"jsx": "react",
-		"jsxFactory": "app.h",
-		"jsxFragmentFactory": "app.Fragment",
-		"lib": ["esnext","dom"],
-		"experimentalDecorators": true,
-		"esModuleInterop": true,
-		"outDir": "../esm",
-		"sourceMap": true,
-		"skipLibCheck": true
-	}
-}

package/src/type-utils.ts

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,151 +0,0 @@
-/**
- * Core TypeScript Type Definitions
- * 
- * This file defines the fundamental types used across AppRun:
- * 1. Component Types
- *    - View: Function that renders state to VDOM
- *    - Action: Function that updates state (sync/async/generator)
- *    - Update: Collection of actions (array or object format)
- *    - ActionDef: Tuple definition for action arrays
- * 
- * 2. Virtual DOM Types
- *    - 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, 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
- * - Added support for async generator and generator functions in Action types
- *
- * Usage:
- * ```ts
- * class MyComponent extends Component<State, Events> {
- *   view: View<State>;
- *   update: Update<State, Events>;
- * }
- * 
- * // Type-safe action definitions with async generators
- * const update: Update<State> = {
- *   'event': (state: State, ...args) => newState,
- *   'stream-event': async function* (state: State, ...args) {
- *     yield { ...state, loading: true };
- *     const data = await fetchData();
- *     yield { ...state, data, loading: false };
- *   }
- * };
- * ```
- */
-
-import { TemplateResult } from 'lit-html';
-export type Element = HTMLElement | string;
-export type State<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
-export type VNode = {
-  tag: string | Function,
-  props: {},
-  children: Array<VNode | string>
-}
-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 | AsyncGenerator<T> | Generator<T>;
-export type ActionDef<T, E> = (readonly [E, Action<T>, {}?]);
-export type Update<T, E = unknown> = ActionDef<T, E>[] | { [name: string]: Action<T> | {}[] } | (E | Action<T> | {})[];
-export type ActionOptions = {
-  render?: boolean, history?, global?: boolean;
-  callback?: (state: any) => void;
-};
-export type EventOptions = {
-  once?: boolean;
-  transition?: boolean;
-  delay?: number;
-} | any;
-export type MountOptions = {
-  render?: boolean, history?, global_event?: boolean, route?: string;
-  transition?: boolean;
-};
-
-export type AppStartOptions<T> = {
-  render?: boolean;
-  history?;
-  transition?: boolean;
-  route?: string;
-  rendered?: (state: T) => void
-  mounted?: (props: any, children: any, state: T) => T
-};
-export type Router = (url: string, ...args: any[]) => any;
-
-export type CustomElementOptions = {
-  render?: boolean;
-  shadow?: boolean;
-  history?: boolean;
-  global_event?: boolean;
-  observedAttributes?: string[];
-};
-
-export interface IApp {
-  // Event system methods
-  on(name: string, fn: (...args: any[]) => any, options?: EventOptions): void;
-  off(name: string, fn: (...args: any[]) => any): void;
-  run(name: string, ...args: any[]): number;
-  runAsync(name: string, ...args: any[]): Promise<any[]>;
-  once(name: string, fn: (...args: any[]) => any, options?: EventOptions): void;
-  find(name: string): any;
-
-  /** @deprecated Use runAsync() instead */
-  query(name: string, ...args: any[]): Promise<any[]>;
-
-  start<T, E = unknown>(element?: Element | string, model?: T, view?: View<T>, update?: Update<T, E>,
-    options?: AppStartOptions<T>): any;
-
-  h(tag: string | Function, props?: any, ...children: any[]): VNode | VNode[];
-  createElement(tag: string | Function, props?: any, ...children: any[]): VNode | VNode[];
-  render(element: Element | ShadowRoot, node: VNode, component?: {}): void;
-  Fragment(props: any, ...children: any[]): any[];
-  route: Router;
-  webComponent(name: string, componentClass: any, options?: CustomElementOptions): void;
-  safeHTML(html: string): any[];
-  use_render(render: any, mode?: 0 | 1): void;
-  use_react(React: any, ReactDOM: any): void;
-  version: string;
-  basePath?: string;
-  addComponents: (element: Element | string, components: ComponentRoute) => void;
-}
-
-// Define what constitutes a mountable component
-interface ComponentLike {
-  mount(element?: Element | string, options?: any): any;
-}
-
-// Define component constructor type
-type ComponentConstructor<T = unknown> = new (
-  state?: T,
-  view?: any,
-  update?: any,
-  options?: any
-) => ComponentLike;
-
-// Enhanced ComponentRoute type with clear distinctions
-export type ComponentRoute = {
-  [route: string]:
-  | ComponentLike                                    // Component instance
-  | ComponentConstructor                             // Component class constructor
-  | (() => ComponentLike | ComponentConstructor | Promise<ComponentLike | ComponentConstructor>) // Factory function
-  | ((...args: any[]) => any)                       // Event handler function
-};

package/src/vdom-html.ts_

@@ -1,20 +0,0 @@
-import { createElement, updateElement, Fragment } from './vdom-my';
-import morphdom from 'morphdom';
-
-export function render(element, html, parent?) {
-  if (!element) return;
-  if (typeof html === 'string') {
-    html = html.trim();
-    if (element.firstChild) {
-      const el = element.cloneNode(false);
-      el.innerHTML = html;
-      morphdom(element, el);
-    } else {
-      element.innerHTML = html;
-    }
-  } else {
-    updateElement(element, html, parent);
-  }
-}
-export { createElement, Fragment };
-

package/src/vdom-lit-html.ts

@@ -1,67 +0,0 @@
-import { createElement, updateElement, Fragment } from './vdom-my';
-
-
-import { render, svg, html, noChange, nothing } from 'lit';
-import { directive, Directive, PartInfo, ElementPart, DirectiveResult, EventPart, PartType } from 'lit/directive.js';
-import { unsafeHTML } from 'lit/directives/unsafe-html.js';
-import app from './apprun';
-
-function _render(element, vdom, parent?) {
-  if (!vdom) return;
-  if (typeof vdom === 'string') {
-    if (!element['_$litPart$']) element.replaceChildren();
-    render(html`${unsafeHTML(vdom)}`, element);
-  } else if (vdom['_$litType$']) {
-    if (!element['_$litPart$']) element.replaceChildren();
-    render(vdom, element);
-  } else {
-    updateElement(element, vdom, parent);
-    element['_$litPart$'] = undefined;
-  }
-}
-
-export class RunDirective extends Directive {
-  // State stored in class field
-  value: number | undefined;
-  constructor(partInfo: PartInfo) {
-    super(partInfo);
-    // When necessary, validate part in constructor using `part.type`
-    if (partInfo.type !== PartType.EVENT) { // In lit v3, use PartType.EVENT
-      throw new Error('run() can only be used in event handlers');
-    }
-  }
-  // Override update to perform any direct DOM manipulation
-  update(part: EventPart, props: Array<any>): DirectiveResult {
-    /* Any imperative updates to DOM/parts would go here */
-    const element = part.element;
-    const name = part.name;
-    const [eventOrFn, ...args] = props;
-    
-    const getComponent = () => {
-      let el = element;
-      let component = el['_component'];
-      while (!component && el) {
-        el = el.parentElement;
-        component = el && el['_component'];
-      }
-      console.assert(!!component, 'Component not found.');
-      return component;
-    }
-
-    if (typeof eventOrFn === 'string') {
-      element[`on${name}`] = e => {
-        const component = getComponent();
-        component ? component.run(eventOrFn, ...args, e) : app.run(eventOrFn, ...args, e)
-      }
-    } else if (typeof eventOrFn === 'function') {
-      element[`on${name}`] = e => getComponent().setState(eventOrFn(getComponent().state, ...args, e));
-    }
-    return this.render();
-  }
-  render() {
-    return noChange;
-  }
-}
-
-const run = directive(RunDirective) as any;
-export { createElement, Fragment, html, svg, _render as render, run };