@emkodev/emroute 1.0.3 → 1.6.0

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

@@ -0,0 +1,382 @@
+/// <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,
+  RoutesManifest,
+} from '../../type/route.type.ts';
+import type { ContextProvider } from '../../component/abstract.component.ts';
+import type { PageComponent } from '../../component/page.component.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;
+}
+
+/**
+ * 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(manifest: RoutesManifest, options?: SpaHtmlRouterOptions) {
+    const bp = options?.basePath ?? DEFAULT_BASE_PATH;
+    const core = new RouteCore(manifest, {
+      extendContext: options?.extendContext,
+      basePath: bp.html,
+    });
+    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 — patterns are prefixed, match directly
+        const matched = this.core.match(new URL(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;
+  }
+
+  /**
+   * 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;
+    }
+
+    try {
+      const matched = this.core.match(urlObj);
+
+      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, pathname);
+    }
+  }
+
+  /**
+   * Render a status-specific page.
+   */
+  private async renderStatusPage(
+    status: number,
+    pathname: string,
+  ): Promise<void> {
+    if (!this.slot) return;
+
+    const statusPage = this.core.matcher.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.matcher.findErrorBoundary(pathname);
+    if (boundary && await this.tryRenderErrorModule(boundary.modulePath)) return;
+
+    const errorHandler = this.core.matcher.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(
+  manifest: RoutesManifest,
+  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(manifest, options);
+  await router.initialize();
+  g.__emroute_router = router;
+  return router;
+}

package/src/renderer/spa/mod.ts

@@ -0,0 +1,76 @@
+/**
+ * SPA (Browser) Module
+ *
+ * Everything needed for the browser bundle:
+ * - SPA router with client-side navigation
+ * - Custom elements for rendering and hydrating SSR islands
+ * - Widget registry (built-in widgets are opt-in)
+ */
+
+import { RouterSlot } from '../../element/slot.element.ts';
+import { MarkdownElement } from '../../element/markdown.element.ts';
+import { ComponentElement } from '../../element/component.element.ts';
+import { WidgetRegistry } from '../../widget/widget.registry.ts';
+
+export { createSpaHtmlRouter, SpaHtmlRouter, type SpaHtmlRouterOptions } from './html.renderer.ts';
+export {
+  createHashRouter,
+  type HashRouteConfig,
+  HashRouter,
+  type HashRouterOptions,
+} from './hash.renderer.ts';
+export { ComponentElement, MarkdownElement, RouterSlot, WidgetRegistry };
+export type { SpaMode, WidgetsManifest } from '../../type/widget.type.ts';
+
+// Re-export base classes and types for consumer code (pages, widgets)
+export { PageComponent } from '../../component/page.component.ts';
+export { WidgetComponent } from '../../component/widget.component.ts';
+export {
+  Component,
+  type ComponentContext,
+  type ComponentManifestEntry,
+  type ContextProvider,
+  type RenderContext,
+} from '../../component/abstract.component.ts';
+export type {
+  MatchedRoute,
+  NavigateOptions,
+  RouteParams,
+  RouterEvent,
+  RouterEventListener,
+  RouterEventType,
+  RoutesManifest,
+} from '../../type/route.type.ts';
+export type { MarkdownRenderer } from '../../type/markdown.type.ts';
+export { type BasePath, DEFAULT_BASE_PATH } from '../../route/route.core.ts';
+export { escapeHtml, scopeWidgetCss } from '../../util/html.util.ts';
+export type {
+  ErrorBoundary,
+  RedirectConfig,
+  RouteConfig,
+  RouteFiles,
+  RouteFileType,
+  RouteInfo,
+  RouterState,
+} from '../../type/route.type.ts';
+export type { ParsedWidgetBlock, WidgetManifestEntry } from '../../type/widget.type.ts';
+export { type Logger, setLogger } from '../../type/logger.type.ts';
+
+// Register core custom elements in the browser
+if (globalThis.customElements) {
+  if (!customElements.get('router-slot')) customElements.define('router-slot', RouterSlot);
+  if (!customElements.get('mark-down')) customElements.define('mark-down', MarkdownElement);
+}
+
+// Overlay API (tree-shakeable - only bundled if imported)
+export { createOverlayService } from '../../overlay/overlay.service.ts';
+export type {
+  ModalOptions,
+  OverlayService,
+  PopoverOptions,
+  ToastOptions,
+} from '../../overlay/overlay.type.ts';
+
+// Optional: Built-in widgets (tree-shakeable - only bundled if imported)
+export { PageTitleWidget } from '../../widget/page-title.widget.ts';
+export { BreadcrumbWidget } from '../../widget/breadcrumb.widget.ts';

package/src/renderer/ssr/html.renderer.ts

@@ -0,0 +1,159 @@
+/**
+ * SSR HTML Renderer
+ *
+ * Server-side HTML rendering.
+ * Generates complete HTML strings without DOM manipulation.
+ * Expands <mark-down> tags server-side when a markdown renderer is provided.
+ */
+
+import type { RouteConfig, RouteInfo, RoutesManifest } from '../../type/route.type.ts';
+import type { MarkdownRenderer } from '../../type/markdown.type.ts';
+import type { PageComponent } from '../../component/page.component.ts';
+import { DEFAULT_ROOT_ROUTE } from '../../route/route.core.ts';
+import { escapeHtml, STATUS_MESSAGES, unescapeHtml } from '../../util/html.util.ts';
+import { resolveWidgetTags } from '../../util/widget-resolve.util.ts';
+import { SsrRenderer, type SsrRendererOptions } from './ssr.renderer.ts';
+
+/** Options for SSR HTML Router */
+export interface SsrHtmlRouterOptions extends SsrRendererOptions {
+  /** Markdown renderer for server-side <mark-down> expansion */
+  markdownRenderer?: MarkdownRenderer;
+}
+
+/**
+ * SSR HTML Router for server-side rendering.
+ */
+export class SsrHtmlRouter extends SsrRenderer {
+  protected override readonly label = 'SSR HTML';
+  private markdownRenderer: MarkdownRenderer | null;
+  private markdownReady: Promise<void> | null = null;
+
+  constructor(manifest: RoutesManifest, options: SsrHtmlRouterOptions = {}) {
+    super(manifest, options);
+    this.markdownRenderer = options.markdownRenderer ?? null;
+
+    if (this.markdownRenderer?.init) {
+      this.markdownReady = this.markdownRenderer.init();
+    }
+  }
+
+  protected override injectSlot(parent: string, child: string, parentPattern: string): string {
+    const escaped = parentPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return parent.replace(
+      new RegExp(`<router-slot\\b[^>]*\\bpattern="${escaped}"[^>]*></router-slot>`),
+      child,
+    );
+  }
+
+  protected override stripSlots(result: string): string {
+    return result.replace(/<router-slot[^>]*><\/router-slot>/g, '');
+  }
+
+  /**
+   * Render a single route's content.
+   */
+  protected override async renderRouteContent(
+    routeInfo: RouteInfo,
+    route: RouteConfig,
+    isLeaf?: boolean,
+  ): Promise<{ content: string; title?: string }> {
+    if (route.modulePath === DEFAULT_ROOT_ROUTE.modulePath) {
+      return { content: `<router-slot pattern="${route.pattern}"></router-slot>` };
+    }
+
+    const { content: rawContent, title } = await this.loadRouteContent(routeInfo, route, isLeaf);
+    let content = rawContent;
+
+    // Expand <mark-down> tags server-side
+    content = await this.expandMarkdown(content);
+
+    // Attribute bare <router-slot> tags with this route's pattern (before widget
+    // resolution so widget-internal slots inside <template> are not affected)
+    content = this.attributeSlots(content, route.pattern);
+
+    // Resolve <widget-*> tags: call getData() + renderHTML(), inject ssr attribute
+    if (this.widgets) {
+      content = await resolveWidgetTags(
+        content,
+        this.widgets,
+        routeInfo,
+        (name, declared) => {
+          const files = this.widgetFiles[name] ?? declared;
+          return files ? this.core.loadWidgetFiles(files) : Promise.resolve({});
+        },
+        this.core.contextProvider,
+      );
+    }
+
+    return { content, title };
+  }
+
+  protected override renderContent(
+    component: PageComponent,
+    args: PageComponent['RenderArgs'],
+  ): string {
+    return component.renderHTML(args);
+  }
+
+  protected override renderRedirect(to: string): string {
+    return `<meta http-equiv="refresh" content="0;url=${escapeHtml(to)}">`;
+  }
+
+  protected override renderStatusPage(status: number, pathname: string): string {
+    return `
+      <h1>${STATUS_MESSAGES[status] ?? 'Error'}</h1>
+      <p>Path: ${escapeHtml(pathname)}</p>
+    `;
+  }
+
+  protected override renderErrorPage(error: unknown, pathname: string): string {
+    const message = error instanceof Error ? error.message : String(error);
+    return `
+      <h1>Error</h1>
+      <p>Path: ${escapeHtml(pathname)}</p>
+      <p>${escapeHtml(message)}</p>
+    `;
+  }
+
+  /** Add pattern attribute to bare <router-slot> tags. */
+  private attributeSlots(content: string, routePattern: string): string {
+    return content.replace(
+      /<router-slot(?![^>]*\bpattern=)([^>]*)><\/router-slot>/g,
+      `<router-slot pattern="${routePattern}"$1></router-slot>`,
+    );
+  }
+
+  /**
+   * Expand <mark-down> tags by rendering markdown to HTML server-side.
+   * Leaves content unchanged if no markdown renderer is configured.
+   */
+  private async expandMarkdown(content: string): Promise<string> {
+    if (!this.markdownRenderer) return content;
+    if (!content.includes('<mark-down>')) return content;
+
+    if (this.markdownReady) {
+      await this.markdownReady;
+    }
+
+    const renderer = this.markdownRenderer;
+
+    // Match <mark-down>escaped content</mark-down>
+    const pattern = /<mark-down>([\s\S]*?)<\/mark-down>/g;
+
+    return content.replace(pattern, (_match, escaped: string) => {
+      const markdown = unescapeHtml(escaped);
+      const rendered = renderer.render(markdown);
+      return rendered;
+    });
+  }
+}
+
+/**
+ * Create SSR HTML router.
+ */
+export function createSsrHtmlRouter(
+  manifest: RoutesManifest,
+  options?: SsrHtmlRouterOptions,
+): SsrHtmlRouter {
+  return new SsrHtmlRouter(manifest, options);
+}