@ape-egg/vibe 2.1.22 → 2.3.0

package/runtime/parse.js

@@ -22,13 +22,14 @@ const findComponentIdForElement = (element) => {
 // Called from both the root handler and recursive() so they can't drift. Any
 // element classified as a fetched component (`<component src>` or
 // `<div class="component" src>`) captures ONLY a bound src (`src="@[page.src]"`
-// — resolved by hydration before the fetch, re-mounted on change); every other
+// — resolved by hydration before the fetch, re-mounted on change) and a bound
+// key (`key="@[page.path]"` — a key change remounts the same src); every other
 // attribute is a prop owned by processComponent and must stay raw — hydrating
 // them would coerce objects to "[object Object]" or strip boolean-like attrs
-// to empty. A mounted wrapper carries the authored binding in data-vibe-src
-// (stamped by finalize — the src attribute was consumed by the fetch), so the
-// knowledge survives every wrapper replacement: reparsing the live DOM alone
-// rebuilds it.
+// to empty. A mounted wrapper carries the authored bindings in data-vibe-src /
+// data-vibe-key (stamped by finalize — the src attribute was consumed by the
+// fetch), so the knowledge survives every wrapper replacement: reparsing the
+// live DOM alone rebuilds it.
 const captureAttributeBindings = (element, aliasSet) => {
   const nodeName = element.nodeName;
   const isFetchedComponent =
@@ -37,9 +38,14 @@ const captureAttributeBindings = (element, aliasSet) => {
 
   if (isFetchedComponent) {
     const src = element.getAttribute?.('data-vibe-src') ?? element.getAttribute?.('src');
+    const key = element.getAttribute?.('data-vibe-key') ?? element.getAttribute?.('key');
+    const attributes = {};
     BINDING_REGEX.lastIndex = 0;
+    if (BINDING_REGEX.test(src)) attributes.src = src;
+    BINDING_REGEX.lastIndex = 0;
+    if (key && BINDING_REGEX.test(key)) attributes.key = key;
     return {
-      attributes: BINDING_REGEX.test(src) ? { src } : null,
+      attributes: Object.keys(attributes).length ? attributes : null,
       nameBindings: null,
     };
   }

package/spa.js

@@ -0,0 +1,143 @@
+// @ape-egg/vibe/spa
+//
+// Standalone SPA router — the tier between a handrolled router and compiler
+// SPA mode. Maintains one contract: $.page = { path, route, params, src,
+// name }, which a reactive component src (<component src="@[page.src]">)
+// turns into a route outlet.
+//
+// SOFT DEPENDENCY: nothing in Vibe's runtime imports this, it imports nothing
+// from Vibe, and deleting it leaves a working framework. The default
+// onNavigate writes to the runtime global window.$ at call time; pass a
+// custom onNavigate and the module is a pure router (parse/claim/history)
+// with no Vibe in sight.
+//
+// Route grammar (shared with the compiler's route table and route scanners):
+//   /static/path        literal segments
+//   /brawlers/:index    :param captures one segment
+//   /docs/:rest*        trailing :name* captures zero or more segments
+//   *                   declared no-match fallback — deep links and popstate
+//                       only, never claims a click
+// Tables are pre-sorted most-specific-first; first match wins.
+
+// Match one pathname against one route template. Returns the params object
+// (possibly empty) on match, null otherwise. Empty segments are dropped, so
+// trailing slashes resolve to the same route.
+const matchRoute = (path, route) => {
+  const routeSegments = route.split('/').filter(Boolean);
+  const pathSegments = path.split('/').filter(Boolean);
+  const params = {};
+  for (let i = 0; i < routeSegments.length; i++) {
+    const segment = routeSegments[i];
+    if (segment.startsWith(':') && segment.endsWith('*')) {
+      params[segment.slice(1, -1)] = pathSegments.slice(i).join('/');
+      return params;
+    }
+    if (pathSegments[i] === undefined) return null;
+    if (segment.startsWith(':')) params[segment.slice(1)] = pathSegments[i];
+    else if (segment !== pathSegments[i]) return null;
+  }
+  return pathSegments.length === routeSegments.length ? params : null;
+};
+
+// Route slug: segments joined with dashes, params flattened to their bare
+// name — '/' → 'home', '/pve/:id' → 'pve-id', '/docs/:rest*' → 'docs-rest'.
+// Stable across param values, so markup hangs page-scoped attributes and
+// active checks on it: <page @[page.name]>, page.name.startsWith('pve').
+const routeName = (route) =>
+  route
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/:(\w+)\*?/g, '$1')
+    .replace(/\//g, '-') || 'home';
+
+// Resolve a location (anything with a .pathname, or a bare path string)
+// against a route table → { path, route, params, src, name, title? } | null.
+// Pure: the compiled shell seeds initial $.page with it, unit tests drive it
+// directly. '*' is skipped during matching and applied only when nothing
+// real matched — it is a declared fallback, not a positional route.
+export const resolve = (location, routes) => {
+  const path = location.pathname ?? location;
+  for (const entry of routes) {
+    if (entry.route === '*') continue;
+    const params = matchRoute(path, entry.route);
+    if (params)
+      return {
+        path,
+        route: entry.route,
+        params,
+        src: entry.src,
+        name: routeName(entry.route),
+        title: entry.title,
+      };
+  }
+  const fallback = routes.find((entry) => entry.route === '*');
+  return fallback
+    ? { path, route: '*', params: {}, src: fallback.src, name: '*', title: fallback.title }
+    : null;
+};
+
+// Wire the router: one document-level click listener + popstate. Claiming
+// rule: same-origin, unmodified, untargeted clicks whose pathname matches a
+// REAL route — '*' never claims, so unrouted paths navigate natively (which
+// is what makes mixed MPA/SPA output work). Returns { navigate, dispose }.
+export const setupSpa = ({ routes, onNavigate }) => {
+  // Default Vibe binding: one fresh-object assignment so bindings diff
+  // cleanly, reading window.$ at call time (page scripts boot vibe before
+  // setupSpa runs). A route-supplied title swaps document.title.
+  const apply = onNavigate ?? (({ path, route, params, src, name, title }) => {
+    window.$.page = { path, route, params, src, name };
+    if (title) document.title = title;
+  });
+
+  const claim = (target) => {
+    const resolved = resolve(target, routes);
+    return resolved && resolved.route !== '*' ? resolved : null;
+  };
+
+  const push = (url, resolved) => {
+    history.pushState({}, '', url);
+    apply(resolved);
+    scrollTo(0, 0);
+  };
+
+  const onClick = (event) => {
+    const anchor = event.target.closest('a[href]');
+    if (!anchor || anchor.origin !== location.origin) return;
+    if (anchor.target || anchor.hasAttribute('download')) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button) return;
+    if (event.defaultPrevented) return;
+    // Same-page hash links keep the native anchor jump.
+    if (anchor.hash && anchor.pathname === location.pathname) return;
+    const resolved = claim(anchor);
+    if (!resolved) return;
+    event.preventDefault();
+    push(anchor.href, resolved);
+  };
+
+  // History traversal re-resolves WITH the '*' fallback — symmetric with
+  // deep-link entry, whose URL may itself be a '*' page. No scroll: the
+  // browser restores scroll position on popstate.
+  const onPopstate = () => {
+    const resolved = resolve(location, routes);
+    if (resolved) apply(resolved);
+  };
+
+  // Programmatic navigation, claiming like a link click: real route match →
+  // SPA navigation, anything else → native load (the server rewrite serves
+  // the shell, whose deep-link resolution may then mount '*').
+  const navigate = (path) => {
+    const url = new URL(path, location.origin);
+    const resolved = claim(url);
+    if (resolved) push(url, resolved);
+    else location.assign(url);
+  };
+
+  document.addEventListener('click', onClick);
+  addEventListener('popstate', onPopstate);
+
+  const dispose = () => {
+    document.removeEventListener('click', onClick);
+    removeEventListener('popstate', onPopstate);
+  };
+
+  return { navigate, dispose };
+};