@ape-egg/vibe 4.0.1 → 4.1.3

package/spa.js

@@ -1,31 +1,5 @@
-// @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, and deleting it
-// leaves a working framework. Its one import is the standalone template cache
-// (itself dependency-free), so navigation prefetches ride the same in-flight
-// promise the outlet's mount consumes — one request per fragment. The default
-// onNavigate writes to the runtime global window.$ at call time; pass a
-// custom onNavigate and the module stays a pure router (parse/claim/history)
-// over that cache.
-//
-// 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.
-
 import { fetchComponentTemplate } from './runtime/component-cache.js';
 
-// Captured params arrive percent-encoded from the URL bar; hand authors the
-// decoded value. A malformed escape (user-typed %zz) keeps the raw segment —
-// URLs are external input, not authored code.
 const decode = (segment) => {
   try {
     return decodeURIComponent(segment);
@@ -34,9 +8,6 @@ const decode = (segment) => {
   }
 };
 
-// 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);
@@ -54,21 +25,12 @@ const matchRoute = (path, route) => {
   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) {
@@ -85,29 +47,16 @@ export const resolve = (location, routes) => {
       };
   }
   const fallback = routes.find((entry) => entry.route === '*');
-  // 'not-found', not '*': the slug feeds name bindings (<page @[page.name]>)
-  // and setAttribute('*') throws — the fallback must be attribute-safe.
   return fallback
     ? { path, route: '*', params: {}, src: fallback.src, name: 'not-found', title: fallback.title }
     : null;
 };
 
-// Programmatic navigation without holding the setupSpa return value: app code
-// imports this and calls it like a link click. With no router active (MPA
-// output, or before setupSpa runs) it falls back to a native load, so the same
-// call site works in both output modes.
 let activeRouter = null;
 export const navigate = (path) =>
   activeRouter ? activeRouter.navigate(path) : location.assign(new URL(path, location.origin));
 
-// 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;
@@ -118,14 +67,6 @@ export const setupSpa = ({ routes, onNavigate }) => {
     return resolved && resolved.route !== '*' ? resolved : null;
   };
 
-  // Two-phase commit: the URL flips at interaction time, but route state —
-  // and with it every binding the outgoing page still renders — flips only
-  // once the incoming fragment's template is in hand. The old view never
-  // re-renders against the new route, and the prefetch IS the mount's fetch
-  // (same cache entry), so a navigation still costs one request. A failed
-  // prefetch resolves anyway: the flip proceeds and the mount path owns the
-  // error, exactly as before. The token makes rapid navigations last-wins —
-  // a superseded prefetch never applies a stale flip.
   let navigationToken = 0;
   const commit = (resolved, { scroll, hash }) => {
     const token = ++navigationToken;
@@ -135,12 +76,6 @@ export const setupSpa = ({ routes, onNavigate }) => {
     prefetch.then(() => {
       if (token !== navigationToken) return;
       apply(resolved);
-      // A cross-page hash link scrolls to its anchor once the fragment's
-      // mount settles — late ready fires exactly then. Hashless navigations
-      // start at the top. getElementById + decode, not querySelector: a URL
-      // fragment is an element id, not a CSS selector — digit-leading ids
-      // are valid HTML but invalid selectors, and fragments arrive
-      // percent-encoded.
       if (hash)
         window.$?.on?.('ready', () =>
           document.getElementById(decodeURIComponent(hash.slice(1)))?.scrollIntoView(),
@@ -160,30 +95,19 @@ export const setupSpa = ({ routes, onNavigate }) => {
     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();
-    // Same-URL click: claimed (no reload), but no duplicate history entry —
-    // Back must keep meaning "the previous page". The WHOLE url: a link to
-    // the same pathname with a different query string is a real navigation.
     if (anchor.href === location.href) return;
     push(anchor.href, resolved, anchor.hash || null);
   };
 
-  // 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. Same two-phase commit:
-  // going back re-renders the old view only when the target is ready.
   const onPopstate = () => {
     const resolved = resolve(location, routes);
     if (resolved) commit(resolved, { scroll: false });
   };
 
-  // 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);

package/vibe.css

@@ -1,46 +1,7 @@
-[vibe-fouc],
-.vibe-fouc {
-  visibility: hidden;
-}
+[vibe-fouc], .vibe-fouc { visibility: hidden }
+[vibe-staged] { display: none }
+[vibe-fouc], .vibe-fouc, [vibe-fouc] *, .vibe-fouc * { transition: none !important; animation: none !important }
 
-/* A route/key remount stages the incoming wrapper as a hidden sibling of the
- * outgoing page (which keeps its place, visible and styled) until the commit
- * swaps them in one paint. display: none keeps the staged content out of
- * layout so the two never occupy the document together. */
-[vibe-staged] {
-  display: none;
-}
+/* vibe:optional — everything below is skipped by disableVibeCss */
 
-/* Animations too, not just transitions: visibility: hidden does not pause
- * CSS animations — a covered element still animates and still fires
- * animationend, reaching inline handlers before the module chain defines
- * them. Suppressed under the cover, entrance animations instead play on
- * reveal, matching what the user actually sees. */
-[vibe-fouc],
-.vibe-fouc,
-[vibe-fouc] *,
-.vibe-fouc * {
-  transition: none !important;
-  animation: none !important;
-}
-
-/* Vibe Dehydrate - Skip Reactive Processing
- * Elements with [vibe-dehydrate] attribute or .vibe-dehydrate class are skipped during
- * Vibe's parsing and hydration. Useful for displaying literal @[variable] syntax in
- * documentation, examples, or code snippets without triggering reactivity.
- */
-[vibe-dehydrate],
-.vibe-dehydrate {
-  /* No styles applied - marker only */
-}
-
-/* Component Wrappers - Layout Transparent
- * Component wrappers (<component> or <div class="component">) use display: contents
- * to make the wrapper invisible in the layout. Children render as if the wrapper doesn't exist.
- */
-component,
-div.component,
-slot,
-div.slot {
-  display: contents;
-}
+component, div.component, slot, div.slot { display: contents }