@emkodev/emroute 1.0.3 → 1.6.0

package/src/renderer/spa/base.renderer.ts

@@ -0,0 +1,186 @@
+/**
+ * Base Renderer
+ *
+ * Shared rendering logic for SPA and Hash routers:
+ * - Route hierarchy traversal with nested slot rendering
+ * - Component loading, data fetching, and HTML rendering
+ * - Markdown render waiting
+ * - Document title updates
+ */
+
+import type { MatchedRoute, RouteConfig, RouteInfo } from '../../type/route.type.ts';
+import defaultPageComponent, { type PageComponent } from '../../component/page.component.ts';
+import { DEFAULT_ROOT_ROUTE, RouteCore } from '../../route/route.core.ts';
+import { logger } from '../../util/logger.util.ts';
+
+const MARKDOWN_RENDER_TIMEOUT = 5000;
+
+/**
+ * Abstract base for renderers that share the page rendering pipeline.
+ * Subclasses provide navigation mechanics (Navigation API, hashchange, etc.).
+ */
+export abstract class BaseRenderer {
+  protected core: RouteCore;
+  protected slot: Element | null = null;
+
+  constructor(core: RouteCore) {
+    this.core = core;
+  }
+
+  /**
+   * Render a matched page route with nested route support.
+   */
+  protected async renderPage(
+    routeInfo: RouteInfo,
+    matched: MatchedRoute,
+    signal: AbortSignal,
+  ): Promise<void> {
+    if (!this.slot) return;
+
+    try {
+      const hierarchy = this.core.buildRouteHierarchy(routeInfo.pattern);
+      logger.render('page', routeInfo.pattern, `hierarchy: ${hierarchy.join(' > ')}`);
+
+      let currentSlot: Element = this.slot;
+      let pageTitle: string | undefined;
+
+      for (let i = 0; i < hierarchy.length; i++) {
+        if (signal.aborted) return;
+
+        const routePattern = hierarchy[i];
+        const isLeaf = i === hierarchy.length - 1;
+
+        let route = this.core.matcher.findRoute(routePattern);
+
+        if (!route && routePattern === this.core.root) {
+          route = { ...DEFAULT_ROOT_ROUTE, pattern: this.core.root };
+        }
+
+        if (!route) {
+          logger.render('skip', routePattern, 'route not found');
+          continue;
+        }
+
+        const routeType = isLeaf ? 'leaf' : 'layout';
+        logger.render(routeType, routePattern, `${route.files?.ts ?? 'default'} → slot`);
+
+        // Skip wildcard route appearing as its own parent (prevents double-render)
+        if (route === matched.route && routePattern !== matched.route.pattern) {
+          continue;
+        }
+
+        const { html, title } = await this.renderRouteContent(routeInfo, route, signal, isLeaf);
+        if (signal.aborted) return;
+
+        currentSlot.setHTMLUnsafe(html);
+
+        if (title) {
+          pageTitle = title;
+        }
+
+        // Wait for <mark-down> to finish rendering its content
+        // (must happen before attributing slots — router-slot may be inside markdown)
+        const markDown = currentSlot.querySelector<HTMLElement>('mark-down');
+        if (markDown) {
+          await this.waitForMarkdownRender(markDown);
+          if (signal.aborted) return;
+        }
+
+        // Attribute bare <router-slot> tags with this route's pattern
+        for (const slot of currentSlot.querySelectorAll('router-slot:not([pattern])')) {
+          slot.setAttribute('pattern', routePattern);
+        }
+
+        if (!isLeaf) {
+          const nestedSlot = currentSlot.querySelector(
+            `router-slot[pattern="${CSS.escape(routePattern)}"]`,
+          );
+          if (nestedSlot) {
+            currentSlot = nestedSlot;
+          } else {
+            logger.warn(
+              `Route "${routePattern}" has no <router-slot> ` +
+                `for child routes to render into. ` +
+                `Add <router-slot></router-slot> to the parent template.`,
+            );
+          }
+        }
+      }
+
+      if (signal.aborted) return;
+
+      this.updateTitle(pageTitle);
+
+      this.core.emit({
+        type: 'load',
+        pathname: routeInfo.pattern,
+        params: routeInfo.params,
+      });
+    } catch (error) {
+      if (signal.aborted) return;
+      throw error;
+    }
+  }
+
+  /**
+   * Render a single route's content.
+   */
+  protected async renderRouteContent(
+    routeInfo: RouteInfo,
+    route: RouteConfig,
+    signal: AbortSignal,
+    isLeaf?: boolean,
+  ): Promise<{ html: string; title?: string }> {
+    if (route.modulePath === DEFAULT_ROOT_ROUTE.modulePath) {
+      return { html: `<router-slot pattern="${route.pattern}"></router-slot>` };
+    }
+
+    const files = route.files ?? {};
+
+    const component: PageComponent = files.ts
+      ? (await this.core.loadModule<{ default: PageComponent }>(files.ts)).default
+      : defaultPageComponent;
+
+    const context = await this.core.buildComponentContext(routeInfo, route, signal, isLeaf);
+    const data = await component.getData({ params: routeInfo.params, signal, context });
+    const html = component.renderHTML({ data, params: routeInfo.params, context });
+    const title = component.getTitle({ data, params: routeInfo.params, context });
+    return { html, title };
+  }
+
+  /**
+   * Wait for a <mark-down> element to finish rendering.
+   */
+  protected waitForMarkdownRender(element: HTMLElement): Promise<void> {
+    return new Promise((resolve) => {
+      if (element.children.length > 0) {
+        resolve();
+        return;
+      }
+
+      const timeout = setTimeout(() => {
+        observer.disconnect();
+        resolve();
+      }, MARKDOWN_RENDER_TIMEOUT);
+
+      const observer = new MutationObserver(() => {
+        if (element.children.length > 0) {
+          clearTimeout(timeout);
+          observer.disconnect();
+          resolve();
+        }
+      });
+
+      observer.observe(element, { childList: true });
+    });
+  }
+
+  /**
+   * Update document.title from getTitle() result.
+   */
+  protected updateTitle(pageTitle?: string): void {
+    if (pageTitle) {
+      document.title = pageTitle;
+    }
+  }
+}

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

@@ -0,0 +1,215 @@
+/**
+ * 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 { RoutesManifest } from '../../type/route.type.ts';
+import type { ContextProvider } from '../../component/abstract.component.ts';
+import { RouteCore } from '../../route/route.core.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 an internal RoutesManifest from inline hash route definitions.
+ * Each route's pattern is used as the moduleLoaders key so RouteCore.loadModule works.
+ */
+function buildManifest(routes: HashRouteConfig[]): RoutesManifest {
+  return {
+    routes: routes.map((r) => ({
+      pattern: r.pattern,
+      type: 'page' as const,
+      modulePath: r.pattern,
+      files: { ts: r.pattern },
+    })),
+    errorBoundaries: [],
+    statusPages: new Map(),
+    moduleLoaders: Object.fromEntries(
+      routes.map((r) => [r.pattern, r.loader]),
+    ),
+  };
+}
+
+/**
+ * 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(manifest: RoutesManifest, options?: { extendContext?: ContextProvider }) {
+    const core = new RouteCore(manifest, {
+      extendContext: options?.extendContext,
+    });
+    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 manifest = buildManifest(options.routes);
+  const router = new HashRouter(manifest, {
+    extendContext: options.extendContext,
+  });
+  await router.initialize(options.slot ?? 'hash-slot');
+  g.__emroute_hash_router = router;
+  return router;
+}