@emkodev/emroute 1.6.6-beta.2 → 1.6.6-beta.4

package/src/renderer/spa/hash.renderer.ts

@@ -1,238 +0,0 @@
-/**
- * Hash Router
- *
- * Lightweight client-side router for leaf mode mini-apps.
- * Uses hashchange events + RouteCore pattern matching.
- *
- * Routes are defined inline by the consumer, not from the main manifest.
- * Coexists with SpaHtmlRouter in root mode (SPA router skips hash changes).
- */
-
-import type { RouteNode } from '../../type/route-tree.type.ts';
-import type { ContextProvider } from '../../component/abstract.component.ts';
-import type { RouteResolver } from '../../route/route.resolver.ts';
-import { RouteCore } from '../../route/route.core.ts';
-import { RouteTrie } from '../../route/route.trie.ts';
-import { escapeHtml } from '../../util/html.util.ts';
-import { logger } from '../../util/logger.util.ts';
-import { BaseRenderer } from './base.renderer.ts';
-
-/**
- * A single hash route definition with a lazy module loader.
- * @experimental
- */
-export interface HashRouteConfig {
-  /** URLPattern pathname pattern (e.g. '/settings', '/users/:id'). */
-  pattern: string;
-  /** Lazy loader returning a module with a default PageComponent export. */
-  loader: () => Promise<unknown>;
-}
-
-/**
- * Options for creating a HashRouter.
- * @experimental
- */
-export interface HashRouterOptions {
-  /** Inline route definitions. */
-  routes: HashRouteConfig[];
-  /** CSS selector or element to render into. Defaults to 'hash-slot'. */
-  slot?: string | Element;
-  /** Enriches every ComponentContext with app-level services. */
-  extendContext?: ContextProvider;
-}
-
-/**
- * Build a RouteNode tree and module loaders from inline hash route definitions.
- * Each route's pattern is used as the moduleLoaders key so RouteCore.loadModule works.
- */
-function buildRouteTree(routes: HashRouteConfig[]): {
-  resolver: RouteResolver;
-  moduleLoaders: Record<string, () => Promise<unknown>>;
-} {
-  const root: RouteNode = {};
-  const moduleLoaders: Record<string, () => Promise<unknown>> = {};
-
-  for (const r of routes) {
-    const segments = r.pattern.split('/').filter(Boolean);
-    let node = root;
-
-    for (const segment of segments) {
-      if (segment.startsWith(':')) {
-        const param = segment.endsWith('*') ? segment.slice(1, -1) : segment.slice(1);
-        if (segment.endsWith('*')) {
-          node.wildcard ??= { param, child: {} };
-          node = node.wildcard.child;
-        } else {
-          node.dynamic ??= { param, child: {} };
-          node = node.dynamic.child;
-        }
-      } else {
-        node.children ??= {};
-        node.children[segment] ??= {};
-        node = node.children[segment];
-      }
-    }
-
-    node.files = { ts: r.pattern };
-    moduleLoaders[r.pattern] = r.loader;
-  }
-
-  return { resolver: new RouteTrie(root), moduleLoaders };
-}
-
-/**
- * Hash-based mini-app router for leaf mode pages.
- *
- * Listens to `hashchange`, maps `#/path` → pattern match via RouteCore,
- * renders matched PageComponent into a slot element.
- *
- * @experimental
- */
-export class HashRouter extends BaseRenderer {
-  private boundHandler: (() => void) | null = null;
-
-  constructor(resolver: RouteResolver, options?: { extendContext?: ContextProvider; moduleLoaders?: Record<string, () => Promise<unknown>> }) {
-    const core = new RouteCore(resolver, {
-      extendContext: options?.extendContext,
-      moduleLoaders: options?.moduleLoaders,
-    });
-    super(core);
-  }
-
-  /**
-   * Initialize: find slot, attach hashchange listener, render initial hash.
-   */
-  async initialize(slot: string | Element = 'hash-slot'): Promise<void> {
-    this.slot = typeof slot === 'string' ? document.querySelector(slot) : slot;
-
-    if (!this.slot) {
-      console.error(`[HashRouter] Slot not found: ${slot}`);
-      return;
-    }
-
-    this.boundHandler = () => {
-      this.handleHashChange();
-    };
-    globalThis.addEventListener('hashchange', this.boundHandler);
-
-    // Render initial hash if present
-    if (location.hash.length > 1) {
-      await this.handleHashChange();
-    }
-  }
-
-  /**
-   * Navigate to a hash path. Triggers hashchange → render.
-   */
-  navigate(hash: string): void {
-    location.hash = hash.startsWith('#') ? hash : '#' + hash;
-  }
-
-  /**
-   * Add event listener for router events.
-   */
-  addEventListener(
-    listener: Parameters<RouteCore['addEventListener']>[0],
-  ): () => void {
-    return this.core.addEventListener(listener);
-  }
-
-  /**
-   * Remove event listeners and release references.
-   */
-  dispose(): void {
-    if (this.boundHandler) {
-      globalThis.removeEventListener('hashchange', this.boundHandler);
-      this.boundHandler = null;
-    }
-    this.slot = null;
-  }
-
-  /**
-   * Handle a hashchange event: parse hash, match, render.
-   */
-  private async handleHashChange(): Promise<void> {
-    const path = location.hash.slice(1) || '/';
-    const matchUrl = new URL(path, location.origin);
-
-    logger.nav('hash', path, path);
-
-    const controller = new AbortController();
-    const { signal } = controller;
-
-    try {
-      const matched = this.core.match(matchUrl);
-
-      if (!matched) {
-        logger.nav('hash-not-found', path, path);
-        if (this.slot) {
-          this.slot.setHTMLUnsafe(`
-            <h1>Not Found</h1>
-            <p>Path: ${escapeHtml(path)}</p>
-          `);
-        }
-        return;
-      }
-
-      logger.nav('hash-matched', path, matched.route.pattern, { params: matched.params });
-
-      this.core.currentRoute = matched;
-      const routeInfo = this.core.toRouteInfo(matched, path);
-
-      await this.renderPage(routeInfo, matched, signal);
-
-      if (signal.aborted) return;
-
-      this.core.emit({
-        type: 'navigate',
-        pathname: path,
-        params: matched.params,
-      });
-    } catch (error) {
-      if (signal.aborted) return;
-      console.error('[HashRouter] Render error:', error);
-
-      this.core.emit({
-        type: 'error',
-        pathname: path,
-        params: {},
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-
-      if (this.slot) {
-        const message = error instanceof Error ? error.message : String(error);
-        this.slot.setHTMLUnsafe(`
-          <h1>Error</h1>
-          <p>${escapeHtml(message)}</p>
-        `);
-      }
-    }
-  }
-}
-
-/**
- * Create and initialize a hash router for a leaf-mode mini-app.
- *
- * The router instance is stored on `globalThis.__emroute_hash_router` for
- * programmatic access. Calling twice returns the existing router with a warning.
- *
- * @experimental
- */
-export async function createHashRouter(
-  options: HashRouterOptions,
-): Promise<HashRouter> {
-  const g = globalThis as Record<string, unknown>;
-  if (g.__emroute_hash_router) {
-    console.warn('eMroute: Hash router already initialized.');
-    return g.__emroute_hash_router as HashRouter;
-  }
-
-  const { resolver, moduleLoaders } = buildRouteTree(options.routes);
-  const router = new HashRouter(resolver, {
-    extendContext: options.extendContext,
-    moduleLoaders,
-  });
-  await router.initialize(options.slot ?? 'hash-slot');
-  g.__emroute_hash_router = router;
-  return router;
-}

package/src/renderer/spa/html.renderer.ts

@@ -1,399 +0,0 @@
-/// <reference path="../../type/navigation-api.d.ts" />
-
-/**
- * SPA HTML Renderer
- *
- * Browser-based Single Page Application renderer.
- * Handles:
- * - DOM manipulation (slot.innerHTML)
- * - Navigation API (navigate event, intercept, scroll restoration)
- * - Document title via component.getTitle()
- * - View transitions
- */
-
-import type {
-  MatchedRoute,
-  NavigateOptions,
-  RedirectConfig,
-  RouteParams,
-  RouterState,
-} from '../../type/route.type.ts';
-import type { ContextProvider } from '../../component/abstract.component.ts';
-import type { PageComponent } from '../../component/page.component.ts';
-import type { RouteResolver } from '../../route/route.resolver.ts';
-import { ComponentElement } from '../../element/component.element.ts';
-import {
-  assertSafeRedirect,
-  type BasePath,
-  DEFAULT_BASE_PATH,
-  RouteCore,
-} from '../../route/route.core.ts';
-import { escapeHtml, STATUS_MESSAGES } from '../../util/html.util.ts';
-import { logger } from '../../util/logger.util.ts';
-import { BaseRenderer } from './base.renderer.ts';
-import type { RouteInfo } from '../../type/route.type.ts';
-import defaultPageComponent from '../../component/page.component.ts';
-
-/** Options for SPA HTML Router */
-export interface SpaHtmlRouterOptions {
-  /** Enriches every ComponentContext with app-level services before it reaches components. */
-  extendContext?: ContextProvider;
-  /** Base paths for SSR endpoints. SPA uses html basePath for routing, md for passthrough. */
-  basePath?: BasePath;
-  /** Pre-bundled module loaders keyed by file path. Bridges JSON route tree → bundled code in the browser. */
-  moduleLoaders?: Record<string, () => Promise<unknown>>;
-}
-
-/**
- * SPA Router for browser-based HTML rendering.
- */
-export class SpaHtmlRouter extends BaseRenderer {
-  private abortController: AbortController | null = null;
-  /** Base paths for SSR endpoints. */
-  private htmlBase: string;
-  private mdBase: string;
-
-  constructor(resolver: RouteResolver, options?: SpaHtmlRouterOptions) {
-    const bp = options?.basePath ?? DEFAULT_BASE_PATH;
-    const core = new RouteCore(resolver, {
-      extendContext: options?.extendContext,
-      basePath: bp.html,
-      moduleLoaders: options?.moduleLoaders,
-    });
-    super(core);
-    this.htmlBase = bp.html;
-    this.mdBase = bp.md;
-    if (options?.extendContext) {
-      ComponentElement.setContextProvider(options.extendContext);
-    }
-  }
-
-  /**
-   * Initialize router with slot element.
-   * Sets up Navigation API listener and performs initial navigation.
-   */
-  async initialize(slotSelector = 'router-slot'): Promise<void> {
-    this.slot = document.querySelector(slotSelector);
-
-    if (!this.slot) {
-      console.error(`[Router] Slot not found: ${slotSelector}`);
-      return;
-    }
-
-    // Navigation API required for SPA routing — SSR handles browsers without it
-    if (!('navigation' in globalThis)) {
-      logger.info('init', 'Navigation API not available — using SSR full-page navigation');
-      return;
-    }
-
-    this.abortController = new AbortController();
-    const { signal } = this.abortController;
-
-    // Single handler for ALL navigations: link clicks, back/forward,
-    // navigate() calls, form submissions. Replaces popstate + click listeners.
-    navigation.addEventListener('navigate', (event) => {
-      if (!event.canIntercept) return;
-      if (event.hashChange) return;
-      if (event.downloadRequest !== null) return;
-
-      const url = new URL(event.destination.url);
-
-      // /md/ paths pass through to server for full page load
-      if (url.pathname.startsWith(this.mdBase + '/') || url.pathname === this.mdBase) {
-        return;
-      }
-
-      event.intercept({
-        scroll: 'manual',
-        handler: async () => {
-          await this.handleNavigation(
-            url.pathname + url.search + url.hash,
-            event.signal,
-          );
-          event.scroll();
-        },
-      });
-    }, { signal });
-
-    // Check for SSR content — skip initial render if route matches.
-    // data-ssr-route stores the full path including basePath (e.g. /html/about).
-    const ssrRoute = this.slot.getAttribute('data-ssr-route');
-    if (ssrRoute) {
-      const currentPath = location.pathname;
-      logger.ssr('check-adoption', `SSR route=${ssrRoute}, current=${currentPath}`);
-
-      if (currentPath === ssrRoute || currentPath === ssrRoute + '/') {
-        // Adopt SSR content — strip basePath before matching unprefixed trie
-        const matched = this.core.match(new URL(this.stripBase(ssrRoute), location.origin));
-        if (matched) {
-          logger.ssr('adopt', ssrRoute);
-          this.core.currentRoute = matched;
-          navigation.updateCurrentEntry({
-            state: { pathname: ssrRoute, params: matched.params } as RouterState,
-          });
-        }
-        this.slot.removeAttribute('data-ssr-route');
-        return;
-      } else {
-        logger.ssr('mismatch', `Expected ${ssrRoute}, got ${currentPath}`);
-      }
-    }
-
-    // No SSR content or route mismatch — full client-side render
-    logger.info('init', `Initial navigation to ${location.pathname}`);
-    await this.handleNavigation(
-      location.pathname + location.search + location.hash,
-      this.abortController.signal,
-    );
-  }
-
-  /**
-   * Remove event listeners and release references.
-   */
-  dispose(): void {
-    this.abortController?.abort();
-    this.abortController = null;
-    this.slot = null;
-    ComponentElement.setContextProvider(undefined);
-  }
-
-  /**
-   * Navigate to a new URL.
-   */
-  async navigate(url: string, options: NavigateOptions = {}): Promise<void> {
-    const normalizedUrl = this.core.normalizeUrl(url);
-    try {
-      const { finished } = navigation.navigate(normalizedUrl, {
-        state: options.state,
-        history: options.replace ? 'replace' : 'auto',
-      });
-      await finished;
-    } catch (e) {
-      // Navigation interrupted (e.g. by a redirect) — not an error
-      if (e instanceof DOMException && e.name === 'AbortError') return;
-      throw e;
-    }
-  }
-
-  /**
-   * Add event listener for router events.
-   */
-  addEventListener(
-    listener: Parameters<RouteCore['addEventListener']>[0],
-  ): () => void {
-    return this.core.addEventListener(listener);
-  }
-
-  /**
-   * Get current route parameters.
-   */
-  getParams(): RouteParams {
-    return this.core.getParams();
-  }
-
-  /**
-   * Get current matched route.
-   */
-  getCurrentRoute(): MatchedRoute | null {
-    return this.core.currentRoute;
-  }
-
-  /**
-   * Strip the HTML basePath prefix from a browser pathname.
-   * Browser URLs include the prefix (e.g. /html/about) but trie patterns don't.
-   */
-  private stripBase(pathname: string): string {
-    if (this.htmlBase && (pathname.startsWith(this.htmlBase + '/') || pathname === this.htmlBase)) {
-      return pathname === this.htmlBase ? '/' : pathname.slice(this.htmlBase.length);
-    }
-    return pathname;
-  }
-
-  /**
-   * Handle navigation to a URL.
-   *
-   * Pure render function — URL updates and scroll restoration are handled
-   * by the Navigation API. Abort is signalled via the navigate event's signal.
-   */
-  private async handleNavigation(
-    url: string,
-    signal: AbortSignal,
-  ): Promise<void> {
-    const urlObj = new URL(url, location.origin);
-    const pathname = urlObj.pathname;
-
-    logger.nav('start', location.pathname, pathname);
-
-    // /md/ paths are handled server-side (initial load only — navigate handler filters these)
-    if (pathname.startsWith(this.mdBase + '/') || pathname === this.mdBase) {
-      logger.nav('redirect-md', pathname, pathname, { reason: 'server-side markdown' });
-      globalThis.location.href = url;
-      return;
-    }
-
-    // Strip basePath prefix — trie holds unprefixed patterns
-    const routePath = this.stripBase(pathname);
-
-    try {
-      const matched = this.core.match(new URL(routePath, location.origin));
-
-      if (!matched) {
-        logger.nav('not-found', pathname, pathname);
-        await this.renderStatusPage(404, pathname);
-        return;
-      }
-
-      logger.nav('matched', pathname, matched.route.pattern, { params: matched.params });
-
-      // Handle redirect — starts a new navigation, aborting this one
-      if (matched.route.type === 'redirect') {
-        const module = await this.core.loadModule<{ default: RedirectConfig }>(
-          matched.route.modulePath,
-        );
-        if (signal.aborted) return;
-        assertSafeRedirect(module.default.to);
-        navigation.navigate(module.default.to, { history: 'replace' });
-        return;
-      }
-
-      // Render page
-      this.core.currentRoute = matched;
-      const routeInfo = this.core.toRouteInfo(matched, pathname);
-
-      if (document.startViewTransition) {
-        const transition = document.startViewTransition(async () => {
-          await this.renderPage(routeInfo, matched, signal);
-        });
-        signal.addEventListener('abort', () => transition.skipTransition(), { once: true });
-        await transition.updateCallbackDone;
-      } else {
-        await this.renderPage(routeInfo, matched, signal);
-      }
-
-      if (signal.aborted) return;
-
-      // Emit navigate event
-      this.core.emit({
-        type: 'navigate',
-        pathname,
-        params: matched.params,
-      });
-    } catch (error) {
-      if (signal.aborted) return;
-      if (error instanceof Response) {
-        await this.renderStatusPage(error.status, pathname);
-        return;
-      }
-      await this.handleError(error, routePath);
-    }
-  }
-
-  /**
-   * Render a status-specific page.
-   */
-  private async renderStatusPage(
-    status: number,
-    pathname: string,
-  ): Promise<void> {
-    if (!this.slot) return;
-
-    const statusPage = this.core.getStatusPage(status);
-
-    if (statusPage) {
-      try {
-        const component: PageComponent = statusPage.files?.ts
-          ? (await this.core.loadModule<{ default: PageComponent }>(statusPage.files.ts)).default
-          : defaultPageComponent;
-        const ri: RouteInfo = {
-          pathname,
-          pattern: statusPage.pattern,
-          params: {},
-          searchParams: new URLSearchParams(),
-        };
-        const context = await this.core.buildComponentContext(ri, statusPage);
-        const data = await component.getData({ params: {}, context });
-        this.slot.setHTMLUnsafe(component.renderHTML({ data, params: {}, context }));
-        this.updateTitle();
-        return;
-      } catch (e) {
-        console.error(`[Router] Failed to render ${status} page:`, e);
-      }
-    }
-
-    this.slot.setHTMLUnsafe(`
-      <h1>${STATUS_MESSAGES[status] ?? 'Error'}</h1>
-      <p>Path: ${escapeHtml(pathname)}</p>
-    `);
-    this.updateTitle();
-  }
-
-  /** Try to load and render an error boundary or handler module into the slot. */
-  private async tryRenderErrorModule(modulePath: string): Promise<boolean> {
-    try {
-      const module = await this.core.loadModule<{ default: PageComponent }>(modulePath);
-      const component = module.default;
-      const minCtx = { pathname: '', pattern: '', params: {}, searchParams: new URLSearchParams() };
-      const data = await component.getData({ params: {}, context: minCtx });
-      const html = component.renderHTML({ data, params: {}, context: minCtx });
-      if (this.slot) {
-        this.slot.setHTMLUnsafe(html);
-        this.updateTitle();
-      }
-      return true;
-    } catch (e) {
-      console.error('[Router] Error module failed:', e);
-      return false;
-    }
-  }
-
-  /**
-   * Handle errors during navigation/rendering.
-   */
-  private async handleError(error: unknown, pathname: string): Promise<void> {
-    console.error('[Router] Navigation error:', error);
-
-    this.core.emit({
-      type: 'error',
-      pathname,
-      params: {},
-      error: error instanceof Error ? error : new Error(String(error)),
-    });
-
-    const boundary = this.core.findErrorBoundary(pathname);
-    if (boundary && await this.tryRenderErrorModule(boundary.modulePath)) return;
-
-    const errorHandler = this.core.getErrorHandler();
-    if (errorHandler && await this.tryRenderErrorModule(errorHandler.modulePath)) return;
-
-    if (this.slot) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.slot.setHTMLUnsafe(`
-        <h1>Error</h1>
-        <p>${escapeHtml(message)}</p>
-      `);
-      this.updateTitle();
-    }
-  }
-}
-
-/**
- * Create and initialize SPA HTML router.
- *
- * The router instance is stored on `globalThis.__emroute_router` for
- * programmatic access from consumer scripts (navigate, getParams, etc.).
- * Calling this function twice returns the existing router with a warning.
- */
-export async function createSpaHtmlRouter(
-  resolver: RouteResolver,
-  options?: SpaHtmlRouterOptions,
-): Promise<SpaHtmlRouter> {
-  const g = globalThis as Record<string, unknown>;
-  if (g.__emroute_router) {
-    console.warn('eMroute: SPA router already initialized. Remove duplicate <script> tags.');
-    return g.__emroute_router as SpaHtmlRouter;
-  }
-  const router = new SpaHtmlRouter(resolver, options);
-  await router.initialize();
-  g.__emroute_router = router;
-  return router;
-}