@ozsarman/clarityjs 0.6.0

package/src/pages-router.js

@@ -0,0 +1,229 @@
+/**
+ * Clarity.js — File-Based Pages Router (browser runtime + pure helpers)
+ *
+ * This is the browser-side counterpart to the Vite `scanPages` integration.
+ * The Vite plugin scans `pages/` at dev/build time and emits a virtual module
+ * (`virtual:clarity-pages`) containing a lazy route table; this module turns
+ * that table into a working, code-split router.
+ *
+ *   import { Routes } from 'virtual:clarity-pages';
+ *   import { mount } from '@ozsarman/clarityjs';
+ *   mount(Routes, document.getElementById('app'));
+ *
+ * File → route convention (Next.js / SvelteKit style):
+ *
+ *   pages/index.clarity            →  /
+ *   pages/about.clarity            →  /about
+ *   pages/blog/index.clarity       →  /blog
+ *   pages/blog/[slug].clarity      →  /blog/:slug
+ *   pages/users/[id]/edit.clarity  →  /users/:id/edit
+ *   pages/[...all].clarity         →  /*           (catch-all)
+ *
+ * The pure helpers (filePathToRoutePattern, routeScore, sortRoutes,
+ * selectRoute) have no DOM or Node dependencies and are unit-tested directly.
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { matchRoute, currentPath } from './router.js';
+import { signal, effect, _runMountHooks, _runCleanupHooks } from './runtime.js';
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Convert a page file path (relative to the pages dir) into a route pattern.
+ *
+ * @param {string} relPath  e.g. 'blog/[slug].clarity', 'index.js'
+ * @returns {string}        e.g. '/blog/:slug', '/'
+ */
+export function filePathToRoutePattern(relPath) {
+  const stripped = String(relPath)
+    .replace(/\\/g, '/')
+    .replace(/^\.?\//, '')
+    .replace(/\.(clarity|jsx?|mjs|tsx?)$/i, '');
+
+  const segments = stripped.split('/').filter(Boolean);
+  const out = [];
+
+  for (const seg of segments) {
+    // index maps onto its parent directory (no extra segment)
+    if (seg === 'index') continue;
+
+    // Catch-all: [...name]  →  *
+    const rest = seg.match(/^\[\.\.\.(.+)\]$/);
+    if (rest) { out.push('*'); continue; }
+
+    // Dynamic: [name]  →  :name
+    const dyn = seg.match(/^\[(.+)\]$/);
+    if (dyn) { out.push(':' + dyn[1]); continue; }
+
+    out.push(seg);
+  }
+
+  const pattern = '/' + out.join('/');
+  return pattern === '/' ? '/' : pattern.replace(/\/$/, '');
+}
+
+/**
+ * Specificity score for a route pattern — higher = more specific.
+ * Static segments outrank dynamic params, which outrank catch-all wildcards.
+ * Used to decide which route wins when several could match.
+ *
+ * @param {string} pattern
+ * @returns {number}
+ */
+export function routeScore(pattern) {
+  const segs = String(pattern).split('/').filter(Boolean);
+  let score = 0;
+  for (const s of segs) {
+    if (s === '*') score -= 1000;           // catch-all — always least specific,
+                                            // even below the root '/' (score 0)
+    else if (s.startsWith(':')) score += 10; // dynamic param
+    else score += 100;                      // static segment — most specific
+  }
+  return score;
+}
+
+/**
+ * Return a new array of routes sorted most-specific first.
+ * @param {Array<{pattern: string}>} routes
+ */
+export function sortRoutes(routes) {
+  return [...routes].sort((a, b) => routeScore(b.pattern) - routeScore(a.pattern));
+}
+
+/**
+ * Select the best-matching route for a path.
+ * @param {Array<{pattern: string}>} routes
+ * @param {string} path
+ * @returns {{ route: object, params: Record<string,string> } | null}
+ */
+export function selectRoute(routes, path) {
+  for (const route of sortRoutes(routes)) {
+    const params = matchRoute(route.pattern, path);
+    if (params) return { route, params };
+  }
+  return null;
+}
+
+/**
+ * Build a sorted route table from a list of page file paths.
+ * @param {string[]} files       page file paths (relative to pages dir)
+ * @param {(file: string) => any} [loaderFor]  optional: returns a lazy loader per file
+ * @returns {Array<{ pattern: string, file: string, load?: Function }>}
+ */
+export function buildRouteTable(files, loaderFor) {
+  const routes = files.map(file => {
+    const route = { pattern: filePathToRoutePattern(file), file };
+    if (typeof loaderFor === 'function') route.load = loaderFor(file);
+    return route;
+  });
+  return sortRoutes(routes);
+}
+
+// ─── Browser router component ─────────────────────────────────────────────────
+
+/** Pick the Clarity component export from a loaded page module. */
+function _pickComponent(mod) {
+  if (!mod) return null;
+  if (typeof mod.default === 'function') return mod.default;
+  // Fall back to the first function export (named component)
+  for (const v of Object.values(mod)) {
+    if (typeof v === 'function') return v;
+  }
+  return null;
+}
+
+/**
+ * Create a file-based pages router component.
+ *
+ * @param {object} options
+ * @param {Array<{ pattern, file, load }>} options.routes  route table (each `load` returns Promise<module>)
+ * @param {Function} [options.loading]   component shown while a page chunk loads
+ * @param {Function} [options.notFound]  component shown when no route matches
+ * @param {Function} [options.error]     component shown when a chunk fails to load — receives { error }
+ * @returns {Function} a Clarity component
+ */
+export function createPagesRouter(options = {}) {
+  const {
+    routes = [],
+    loading: LoadingComp = null,
+    notFound: NotFoundComp = null,
+    error: ErrorComp = null,
+  } = options;
+
+  const sorted = sortRoutes(routes);
+  const _moduleCache = new Map(); // pattern → resolved component
+
+  return function PagesRouter() {
+    const host = (typeof document !== 'undefined')
+      ? document.createElement('div')
+      : { nodeType: 1, _children: [], replaceChildren(...n) { this._children = n; }, append(...n) { this._children.push(...n); } };
+    host.setAttribute?.('data-clarity-pages', '');
+
+    // Track the currently displayed nodes so we can run their cleanup hooks
+    // (stop game loops, dispose effects) before swapping in a new page.
+    let _current = [];
+
+    // Render a node (or component result) into the host, replacing prior content.
+    const renderInto = (node) => {
+      for (const n of _current) _runCleanupHooks(n);
+      _current = [];
+
+      if (node == null) { host.replaceChildren?.(); return; }
+      const resolved = typeof node === 'function' ? node() : node;
+      const arr = Array.isArray(resolved) ? resolved : [resolved];
+      host.replaceChildren?.(...arr);
+
+      // Fire onMount across the freshly-inserted subtree (nested components too).
+      for (const n of arr) {
+        if (n && typeof n === 'object' && n.nodeType) {
+          _runMountHooks(n);
+          _current.push(n);
+        }
+      }
+    };
+
+    const showLoading = () => { if (LoadingComp) renderInto(LoadingComp); };
+    const showNotFound = (path) => { if (NotFoundComp) renderInto(() => NotFoundComp({ path })); };
+    const showError = (err) => {
+      if (ErrorComp) renderInto(() => ErrorComp({ error: err }));
+      else console.error('[Clarity pages] failed to load route chunk:', err);
+    };
+
+    // React to path changes — select + lazy-load + render the matched page.
+    effect(() => {
+      const path = currentPath.get ? currentPath.get() : currentPath();
+      const match = selectRoute(sorted, path);
+
+      if (!match) { showNotFound(path); return; }
+
+      const { route, params } = match;
+
+      // Cached component → render synchronously.
+      if (_moduleCache.has(route.pattern)) {
+        const Comp = _moduleCache.get(route.pattern);
+        renderInto(() => Comp({ params }));
+        return;
+      }
+
+      // Not loaded yet → show loading, then lazy-import the chunk.
+      showLoading();
+      const loader = typeof route.load === 'function' ? route.load : null;
+      if (!loader) { showError(new Error(`Route ${route.pattern} has no loader`)); return; }
+
+      Promise.resolve(loader())
+        .then(mod => {
+          const Comp = _pickComponent(mod);
+          if (!Comp) throw new Error(`Route ${route.pattern} module has no component export`);
+          _moduleCache.set(route.pattern, Comp);
+          // Guard against a path change while we were loading.
+          const now = currentPath.get ? currentPath.get() : currentPath();
+          if (matchRoute(route.pattern, now)) renderInto(() => Comp({ params }));
+        })
+        .catch(showError);
+    });
+
+    return host;
+  };
+}