@emkodev/emroute 1.0.3 → 1.6.0

package/src/element/component.element.ts

@@ -0,0 +1,353 @@
+/**
+ * Widget Element - Browser Custom Element
+ *
+ * Renders Widget instances in the browser as `widget-{name}` elements.
+ * Handles:
+ * - SSR hydration (ssr attribute)
+ * - Client-side data fetching with AbortSignal
+ * - Companion file loading (html, md, css) with caching
+ * - Loading/error states
+ */
+
+import type {
+  Component,
+  ComponentContext,
+  ContextProvider,
+} from '../component/abstract.component.ts';
+import { HTMLElementBase, LAZY_ATTR, SSR_ATTR } from '../util/html.util.ts';
+
+type ComponentState = 'idle' | 'loading' | 'ready' | 'error';
+
+type WidgetFiles = { html?: string; md?: string; css?: string };
+
+/**
+ * Custom element that renders a Component in the browser.
+ */
+export class ComponentElement<TParams, TData> extends HTMLElementBase {
+  /** Shared file content cache — deduplicates fetches across all widget instances. */
+  private static fileCache = new Map<string, Promise<string | undefined>>();
+
+  /** App-level context provider set once during router initialization. */
+  private static extendContext: ContextProvider | undefined;
+
+  /** Register (or clear) the context provider that enriches every widget's ComponentContext. */
+  static setContextProvider(provider: ContextProvider | undefined): void {
+    ComponentElement.extendContext = provider;
+  }
+
+  private component: Component<TParams, TData>;
+  private effectiveFiles?: WidgetFiles;
+  private params: TParams | null = null;
+  private data: TData | null = null;
+  private context!: ComponentContext;
+  private state: ComponentState = 'idle';
+  private errorMessage = '';
+  private deferred: PromiseWithResolvers<void> | null = null;
+  private abortController: AbortController | null = null;
+  private intersectionObserver: IntersectionObserver | null = null;
+
+  /** Promise that resolves with fetched data (available after loadData starts) */
+  dataPromise: Promise<TData | null> | null = null;
+
+  constructor(component: Component<TParams, TData>, files?: WidgetFiles) {
+    super();
+    this.component = component;
+    this.effectiveFiles = files;
+    // Attach shadow root if not already present (Declarative Shadow DOM creates it from <template shadowrootmode="open">)
+    // This enables progressive enhancement: SSR with DSD works without JS, then hydrates when JS loads
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+    }
+  }
+
+  /**
+   * Register a widget as a custom element: `widget-{name}`.
+   * Creates a fresh widget instance per DOM element (per-element state).
+   * Optional `files` parameter provides discovered file paths without mutating
+   * the component instance.
+   */
+  static register<TP, TD>(
+    component: Component<TP, TD>,
+    files?: WidgetFiles,
+  ): void {
+    const tagName = `widget-${component.name}`;
+
+    if (!globalThis.customElements || customElements.get(tagName)) {
+      return;
+    }
+
+    const WidgetClass = component.constructor as new () => Component<TP, TD>;
+
+    const BoundElement = class extends ComponentElement<TP, TD> {
+      constructor() {
+        super(new WidgetClass(), files);
+      }
+    };
+
+    customElements.define(tagName, BoundElement);
+  }
+
+  /**
+   * Register a widget class (not instance) as a custom element: `widget-{name}`.
+   * Used for manifest-based registration where classes are loaded dynamically.
+   */
+  static registerClass<TP, TD>(
+    WidgetClass: new () => Component<TP, TD>,
+    name: string,
+    files?: WidgetFiles,
+  ): void {
+    const tagName = `widget-${name}`;
+
+    if (!globalThis.customElements || customElements.get(tagName)) {
+      return;
+    }
+
+    const BoundElement = class extends ComponentElement<TP, TD> {
+      constructor() {
+        super(new WidgetClass(), files);
+      }
+    };
+
+    customElements.define(tagName, BoundElement);
+  }
+
+  /**
+   * Promise that resolves when component is ready (data loaded and rendered).
+   * Used by router to wait for async components.
+   */
+  get ready(): Promise<void> {
+    if (this.state === 'ready') {
+      return Promise.resolve();
+    }
+    this.deferred ??= Promise.withResolvers<void>();
+    return this.deferred.promise;
+  }
+
+  async connectedCallback(): Promise<void> {
+    this.component.element = this;
+    this.style.contentVisibility = 'auto';
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+
+    // Parse params from element attributes
+    const params: Record<string, unknown> = {};
+    for (const attr of this.attributes) {
+      if (attr.name === SSR_ATTR || attr.name === LAZY_ATTR) continue;
+      const key = attr.name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      try {
+        params[key] = JSON.parse(attr.value);
+      } catch {
+        params[key] = attr.value;
+      }
+    }
+    this.params = params as TParams;
+
+    // Validate params
+    if (this.component.validateParams && this.params !== null) {
+      const error = this.component.validateParams(this.params);
+      if (error) {
+        this.setError(error);
+        return;
+      }
+    }
+
+    // Load companion files (html, md, css) if declared
+    const files = await this.loadFiles();
+    if (signal.aborted) return;
+
+    const base: ComponentContext = {
+      pathname: globalThis.location?.pathname ?? '/',
+      pattern: '',
+      params: {},
+      searchParams: new URLSearchParams(globalThis.location?.search ?? ''),
+      files: (files.html || files.md || files.css) ? files : undefined,
+    };
+    this.context = ComponentElement.extendContext ? ComponentElement.extendContext(base) : base;
+
+    // Hydrate from SSR: adopt content from Declarative Shadow DOM
+    if (this.hasAttribute(SSR_ATTR)) {
+      this.removeAttribute(SSR_ATTR);
+
+      // Read SSR data from light DOM (JSON text placed alongside shadow root)
+      const lightText = this.textContent?.trim();
+      if (lightText) {
+        try {
+          this.data = JSON.parse(lightText);
+        } catch {
+          // Not valid JSON — proceed with data: null
+        }
+      }
+      // Clear light DOM content (JSON text)
+      this.textContent = '';
+
+      this.state = 'ready';
+
+      // Call hydrate() hook to attach event listeners
+      if (this.component.hydrate) {
+        const args = { data: this.data, params: this.params!, context: this.context };
+        queueMicrotask(() => {
+          this.component.hydrate!(args);
+        });
+      }
+
+      this.signalReady();
+      return;
+    }
+
+    // Lazy: defer loadData until element is visible
+    if (this.hasAttribute(LAZY_ATTR)) {
+      this.intersectionObserver = new IntersectionObserver(([entry]) => {
+        if (entry.isIntersecting) {
+          this.intersectionObserver?.disconnect();
+          this.intersectionObserver = null;
+          this.loadData();
+        }
+      });
+      this.intersectionObserver.observe(this);
+      return;
+    }
+
+    await this.loadData();
+  }
+
+  disconnectedCallback(): void {
+    this.component.destroy?.();
+    this.component.element = undefined;
+    this.intersectionObserver?.disconnect();
+    this.intersectionObserver = null;
+    this.abortController?.abort();
+    this.abortController = null;
+    this.state = 'idle';
+    this.data = null;
+    this.context = undefined!;
+    this.dataPromise = null;
+    this.errorMessage = '';
+    this.signalReady();
+    this.deferred = null;
+  }
+
+  /**
+   * Reload component data. Aborts any in-flight request first.
+   */
+  async reload(): Promise<void> {
+    if (this.params === null) return;
+
+    // Abort previous and create fresh controller
+    this.abortController?.abort();
+    this.abortController = new AbortController();
+
+    await this.loadData();
+  }
+
+  /**
+   * Fetch a single file by path, with caching.
+   * Absolute URLs (http/https) pass through; relative paths get '/' prefix.
+   */
+  private static loadFile(path: string): Promise<string | undefined> {
+    const cached = ComponentElement.fileCache.get(path);
+    if (cached) return cached;
+
+    const url = path.startsWith('http://') || path.startsWith('https://')
+      ? path
+      : (path.startsWith('/') ? path : '/' + path);
+
+    const promise = fetch(url).then(
+      (res) => res.ok ? res.text() : undefined,
+      () => undefined,
+    );
+
+    ComponentElement.fileCache.set(path, promise);
+    return promise;
+  }
+
+  /**
+   * Load all companion files for this widget instance.
+   * Uses effectiveFiles (from registration) falling back to component.files.
+   */
+  private async loadFiles(): Promise<{ html?: string; md?: string; css?: string }> {
+    const filePaths = this.effectiveFiles ?? this.component.files;
+    if (!filePaths) return {};
+
+    const [html, md, css] = await Promise.all([
+      filePaths.html ? ComponentElement.loadFile(filePaths.html) : undefined,
+      filePaths.md ? ComponentElement.loadFile(filePaths.md) : undefined,
+      filePaths.css ? ComponentElement.loadFile(filePaths.css) : undefined,
+    ]);
+
+    return { html, md, css };
+  }
+
+  private async loadData(): Promise<void> {
+    if (this.params === null) return;
+
+    const signal = this.abortController?.signal;
+
+    this.state = 'loading';
+    this.render();
+
+    try {
+      const promise = this.component.getData({
+        params: this.params,
+        signal,
+        context: this.context,
+      });
+      this.dataPromise = promise;
+      this.data = await promise;
+
+      // Check abort after await — don't touch DOM if disconnected
+      if (signal?.aborted) return;
+
+      this.state = 'ready';
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'AbortError') return;
+      if (signal?.aborted) return;
+
+      this.setError(e instanceof Error ? e.message : String(e));
+      return;
+    }
+
+    this.render();
+    this.signalReady();
+  }
+
+  private setError(message: string): void {
+    this.state = 'error';
+    this.errorMessage = message;
+    this.render();
+    this.signalReady(); // Ready even on error (completed loading)
+  }
+
+  private signalReady(): void {
+    this.deferred?.resolve();
+    this.deferred = null;
+  }
+
+  private render(): void {
+    if (this.params === null) {
+      this.shadowRoot!.setHTMLUnsafe('');
+      return;
+    }
+
+    if (this.state === 'error') {
+      this.shadowRoot!.setHTMLUnsafe(this.component.renderError({
+        error: new Error(this.errorMessage),
+        params: this.params,
+      }));
+      return;
+    }
+
+    this.shadowRoot!.setHTMLUnsafe(this.component.renderHTML({
+      data: this.state === 'ready' ? this.data : null,
+      params: this.params,
+      context: this.context,
+    }));
+
+    // Call hydrate() after rendering to attach event listeners
+    if (this.state === 'ready' && this.component.hydrate) {
+      const args = { data: this.data, params: this.params!, context: this.context };
+      queueMicrotask(() => {
+        this.component.hydrate!(args);
+      });
+    }
+  }
+}

package/src/element/markdown.element.ts

@@ -0,0 +1,107 @@
+/**
+ * Markdown Element — <mark-down> custom element.
+ *
+ * Renders markdown content with pluggable renderer.
+ * Supports:
+ * - Inline content: <mark-down># Title</mark-down>
+ * - Source attribute: <mark-down src="/path/to.md"></mark-down>
+ */
+
+import { escapeHtml, HTMLElementBase } from '../util/html.util.ts';
+import type { MarkdownRenderer } from '../type/markdown.type.ts';
+
+export class MarkdownElement extends HTMLElementBase {
+  private static renderer: MarkdownRenderer | null = null;
+  private static rendererInitPromise: Promise<void> | null = null;
+  private abortController: AbortController | null = null;
+
+  /**
+   * Set the markdown renderer.
+   * Must be called before any <mark-down> elements are connected.
+   *
+   * @example
+   * ```ts
+   * import { createEmkoRenderer } from './emko.renderer.ts';
+   * MarkdownElement.setRenderer(await createEmkoRenderer());
+   * ```
+   */
+  static setRenderer(renderer: MarkdownRenderer): void {
+    MarkdownElement.renderer = renderer;
+    MarkdownElement.rendererInitPromise = renderer.init ? renderer.init() : null;
+  }
+
+  /**
+   * Get the current renderer, waiting for init if needed.
+   */
+  private static async getRenderer(): Promise<MarkdownRenderer> {
+    const renderer = MarkdownElement.renderer;
+    if (!renderer) {
+      throw new Error(
+        'No markdown renderer configured. Call MarkdownElement.setRenderer() before using <mark-down> elements.',
+      );
+    }
+
+    if (MarkdownElement.rendererInitPromise) {
+      await MarkdownElement.rendererInitPromise;
+    }
+
+    return renderer;
+  }
+
+  async connectedCallback(): Promise<void> {
+    this.abortController = new AbortController();
+    await this.loadContent();
+  }
+
+  disconnectedCallback(): void {
+    this.abortController?.abort();
+    this.abortController = null;
+  }
+
+  private async loadContent(): Promise<void> {
+    const src = this.getAttribute('src');
+    const inlineContent = this.textContent?.trim();
+
+    if (src) {
+      await this.loadFromSrc(src);
+    } else if (inlineContent) {
+      await this.renderContent(inlineContent);
+    } else {
+      this.innerHTML = '';
+    }
+  }
+
+  private async loadFromSrc(src: string): Promise<void> {
+    const signal = this.abortController?.signal;
+
+    try {
+      const response = await fetch(src, { signal });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${src}: ${response.status}`);
+      }
+
+      const markdown = await response.text();
+      await this.renderContent(markdown);
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        return;
+      }
+      this.showError(error);
+    }
+  }
+
+  private async renderContent(markdown: string): Promise<void> {
+    try {
+      const renderer = await MarkdownElement.getRenderer();
+      this.innerHTML = renderer.render(markdown);
+    } catch (error) {
+      this.showError(error);
+    }
+  }
+
+  private showError(error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error);
+    this.innerHTML = `<div>Markdown Error: ${escapeHtml(message)}</div>`;
+  }
+}

package/src/element/slot.element.ts

@@ -0,0 +1,31 @@
+/**
+ * Router Slot Element
+ *
+ * <router-slot> is where page content is rendered.
+ * Supports nested routes via parent page containing slot.
+ *
+ * Usage:
+ * ```html
+ * <router-slot></router-slot>
+ * ```
+ *
+ * For nested routes, parent page includes:
+ * ```typescript
+ * export default function render() {
+ *   return `
+ *     <header>...</header>
+ *     <main>
+ *       <router-slot></router-slot>
+ *     </main>
+ *   `;
+ * }
+ * ```
+ */
+
+import { HTMLElementBase } from '../util/html.util.ts';
+
+/**
+ * Router slot web component.
+ * Serves as the mounting point for page content.
+ */
+export class RouterSlot extends HTMLElementBase {}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @emkodev/emroute
+ *
+ * Public API — types, component base classes, and utilities for consumer code.
+ *
+ * For environment-specific code, use sub-exports:
+ *   @emkodev/emroute/spa        — Browser: SPA router + custom elements
+ *   @emkodev/emroute/ssr/html   — Server: SSR HTML renderer
+ *   @emkodev/emroute/ssr/md     — Server: SSR Markdown renderer
+ *   @emkodev/emroute/server     — Production server
+ *   @emkodev/emroute/runtime    — Abstract runtime + constants
+ *   @emkodev/emroute/runtime/sitemap — Sitemap generation
+ */
+
+// Types
+export type {
+  ErrorBoundary,
+  MatchedRoute,
+  NavigateOptions,
+  RedirectConfig,
+  RouteConfig,
+  RouteFiles,
+  RouteFileType,
+  RouteInfo,
+  RouteParams,
+  RouterEvent,
+  RouterEventListener,
+  RouterEventType,
+  RouterState,
+  RoutesManifest,
+} from './type/route.type.ts';
+
+export type {
+  ParsedWidgetBlock,
+  SpaMode,
+  WidgetManifestEntry,
+  WidgetsManifest,
+} from './type/widget.type.ts';
+
+export type { MarkdownRenderer } from './type/markdown.type.ts';
+export { type Logger, setLogger } from './type/logger.type.ts';
+
+// Components
+export {
+  Component,
+  type ComponentContext,
+  type ComponentManifestEntry,
+  type ContextProvider,
+  type FileContents,
+  type RenderContext,
+} from './component/abstract.component.ts';
+
+export { PageComponent } from './component/page.component.ts';
+export { WidgetComponent } from './component/widget.component.ts';
+export { WidgetRegistry } from './widget/widget.registry.ts';
+
+// Route config
+export { type BasePath, DEFAULT_BASE_PATH, prefixManifest } from './route/route.core.ts';
+
+// Utils
+export { escapeHtml, scopeWidgetCss } from './util/html.util.ts';

package/src/overlay/mod.ts

@@ -0,0 +1,10 @@
+/**
+ * Overlay Module
+ *
+ * Programmatic overlay API for modals, toasts, and popovers.
+ * For simple cases, use declarative HTML (commandfor/command + popover/dialog).
+ * dismissAll() closes both programmatic and declarative overlays.
+ */
+
+export type { ModalOptions, OverlayService, PopoverOptions, ToastOptions } from './overlay.type.ts';
+export { createOverlayService } from './overlay.service.ts';