@real-router/solid 0.3.0 → 0.4.0

package/README.md

@@ -90,6 +90,17 @@ function UserProfile() {
 
 Signal-based hooks (`useRoute`, `useRouteNode`) remain available for simpler use cases.
 
+### Primitives
+
+Two low-level bridges convert `@real-router/sources` `RouterSource<T>` instances into Solid reactive primitives. Use them when you build custom hooks on top of `@real-router/sources`:
+
+| Primitive                | Returns            | Description                                                   |
+| ------------------------ | ------------------ | ------------------------------------------------------------- |
+| `createSignalFromSource` | `Accessor<T>`      | Bridges a source to a Solid signal. Calls `onCleanup`.        |
+| `createStoreFromSource`  | `T` (Solid store)  | Bridges a source to a Solid store via `createStore + reconcile`. |
+
+Both must be called inside a reactive owner (component body or `createRoot`).
+
 ```tsx
 // useRouteNode — updates only when "users.*" changes
 function UsersLayout() {

package/dist/cjs/index.js

@@ -8,8 +8,10 @@ var routeUtils = require('@real-router/route-utils');
 var store = require('solid-js/store');
 var core = require('@real-router/core');
 
-const MATCH_MARKER = Symbol.for("RouteView.Match");
-const NOT_FOUND_MARKER = Symbol.for("RouteView.NotFound");
+// Local (non-global) Symbols — Symbol.for() would expose markers to spoofing
+// via the global Symbol registry. See Gotchas section "RouteView Marker Objects".
+const MATCH_MARKER = Symbol("RouteView.Match");
+const NOT_FOUND_MARKER = Symbol("RouteView.NotFound");
 function Match(props) {
   const result = {
     $$type: MATCH_MARKER,
@@ -20,6 +22,10 @@ function Match(props) {
       return props.children;
     }
   };
+
+  // Marker object is identified by $$type Symbol in RouteView/helpers.tsx,
+  // not rendered as JSX. Cast required because JSX.Element does not include
+  // arbitrary marker shapes.
   return result;
 }
 Match.displayName = "RouteView.Match";
@@ -30,6 +36,8 @@ function NotFound(props) {
       return props.children;
     }
   };
+
+  // See Match for the marker-pattern rationale.
   return result;
 }
 NotFound.displayName = "RouteView.NotFound";
@@ -69,43 +77,65 @@ function buildRenderList(elements, routeName, nodeName) {
       notFoundChildren = child.children;
       continue;
     }
+    if (activeMatchFound) {
+      continue;
+    }
     const {
       segment,
       exact,
       fallback
     } = child;
     const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-    const isActive = !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
-    if (isActive) {
-      activeMatchFound = true;
-      const matchContent = child.children;
-      const content = fallback === undefined ? matchContent : web.createComponent(solidJs.Suspense, {
-        fallback: fallback,
-        children: matchContent
-      });
-      rendered.push(content);
+    if (!isSegmentMatch(routeName, fullSegmentName, exact)) {
+      continue;
     }
+    activeMatchFound = true;
+    rendered.push(fallback === undefined ? child.children : web.createComponent(solidJs.Suspense, {
+      fallback: fallback,
+      get children() {
+        return child.children;
+      }
+    }));
   }
   if (!activeMatchFound && routeName === core.UNKNOWN_ROUTE && notFoundChildren !== null) {
     rendered.push(notFoundChildren);
   }
-  return {
-    rendered,
-    activeMatchFound
-  };
+  return rendered;
 }
 
 function createSignalFromSource(source) {
   const [value, setValue] = solidJs.createSignal(source.getSnapshot());
+  const sync = () => source.getSnapshot();
   const unsubscribe = source.subscribe(() => {
-    setValue(() => source.getSnapshot());
+    setValue(sync);
   });
+
+  // Re-read after subscribe: lazy sources reconcile their snapshot in
+  // onFirstSubscribe (when reused after disconnect via cache). Listener is not
+  // notified for that internal update, so we must sync the signal manually.
+  // No-op when snapshot is unchanged (signal equality check).
+  setValue(sync);
   solidJs.onCleanup(() => {
     unsubscribe();
   });
   return value;
 }
 
+const cache$2 = new WeakMap();
+function getOrCreateNodeSource(router, nodeName) {
+  let perRouter = cache$2.get(router);
+  if (!perRouter) {
+    perRouter = new Map();
+    cache$2.set(router, perRouter);
+  }
+  let source = perRouter.get(nodeName);
+  if (!source) {
+    source = sources.createRouteNodeSource(router, nodeName);
+    perRouter.set(nodeName, source);
+  }
+  return source;
+}
+
 const RouterContext = solidJs.createContext(null);
 const RouteContext = solidJs.createContext(null);
 
@@ -119,27 +149,24 @@ const useRouter = () => {
 
 function useRouteNode(nodeName) {
   const router = useRouter();
-  const store = sources.createRouteNodeSource(router, nodeName);
-  return createSignalFromSource(store);
+  return createSignalFromSource(getOrCreateNodeSource(router, nodeName));
 }
 
 function RouteViewRoot(props) {
   const routeState = useRouteNode(props.nodeName);
   const resolved = solidJs.children(() => props.children);
+  const elements = solidJs.createMemo(() => {
+    const arr = [];
+    collectElements(resolved(), arr);
+    return arr;
+  });
   return web.memo(() => {
     const state = routeState();
     if (!state.route) {
       return null;
     }
-    const elements = [];
-    collectElements(resolved(), elements);
-    const {
-      rendered
-    } = buildRenderList(elements, state.route.name, props.nodeName);
-    if (rendered.length > 0) {
-      return rendered;
-    }
-    return null;
+    const rendered = buildRenderList(elements(), state.route.name, props.nodeName);
+    return rendered.length > 0 ? rendered : null;
   });
 }
 RouteViewRoot.displayName = "RouteView";
@@ -165,14 +192,36 @@ const INTERNAL_ROUTE_PREFIX = "@@";
 const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0";
 function createRouteAnnouncer(router, options) {
   const prefix = "Navigated to ";
+  const getCustomText = options?.getAnnouncementText;
   let isInitialNavigation = true;
   let isReady = false;
   let isDestroyed = false;
   let lastAnnouncedText = "";
+  let pendingText = null;
   let clearTimeoutId;
   const announcer = getOrCreateAnnouncer();
+  const doAnnounce = (text, h1) => {
+    lastAnnouncedText = text;
+    clearTimeout(clearTimeoutId);
+    announcer.textContent = text;
+    clearTimeoutId = setTimeout(() => {
+      announcer.textContent = "";
+      lastAnnouncedText = "";
+    }, CLEAR_DELAY);
+    manageFocus(h1);
+  };
+
+  // Safari-ready delay: announcing before VoiceOver wires up the aria-live region
+  // causes the first announcement to be silently dropped. Wait SAFARI_READY_DELAY ms
+  // before marking the announcer "ready" — any navigation during that window is
+  // buffered in pendingText and flushed once the delay expires.
   const safariTimeoutId = setTimeout(() => {
     isReady = true;
+    if (pendingText !== null && !isDestroyed) {
+      const text = pendingText;
+      pendingText = null;
+      doAnnounce(text, document.querySelector("h1"));
+    }
   }, SAFARI_READY_DELAY);
   const unsubscribe = router.subscribe(({
     route
@@ -181,22 +230,28 @@ function createRouteAnnouncer(router, options) {
       isInitialNavigation = false;
       return;
     }
+
+    // Double rAF: waits for two paint frames so the incoming route's DOM
+    // (including the new <h1>) is fully rendered before resolveText reads it.
+    // Single rAF fires before the new route's template has been attached,
+    // which would cause resolveText to pick up the OLD h1 or fall back to
+    // document.title / route.name prematurely.
     requestAnimationFrame(() => {
       requestAnimationFrame(() => {
         if (isDestroyed) {
           return;
         }
-        const text = resolveText(route, prefix);
-        if (text && text !== lastAnnouncedText && isReady) {
-          lastAnnouncedText = text;
-          clearTimeout(clearTimeoutId);
-          announcer.textContent = text;
-          clearTimeoutId = setTimeout(() => {
-            announcer.textContent = "";
-            lastAnnouncedText = "";
-          }, CLEAR_DELAY);
-          manageFocus();
+        const h1 = document.querySelector("h1");
+        const text = resolveText(route, prefix, getCustomText, h1);
+        if (!text || text === lastAnnouncedText) {
+          return;
+        }
+        if (!isReady) {
+          // Defer announcement until Safari-ready window elapses (see safariTimeoutId).
+          pendingText = text;
+          return;
         }
+        doAnnounce(text, h1);
       });
     });
   });
@@ -226,15 +281,13 @@ function getOrCreateAnnouncer() {
 function removeAnnouncer() {
   document.querySelector(`[${ANNOUNCER_ATTR}]`)?.remove();
 }
-function resolveText(route, prefix, getCustomText) {
-  const h1 = document.querySelector("h1");
+function resolveText(route, prefix, getCustomText, h1) {
   const h1Text = h1?.textContent.trim() ?? "";
   const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX) ? "" : route.name;
   const rawText = h1Text || document.title || routeName || globalThis.location.pathname;
   return `${prefix}${rawText}`;
 }
-function manageFocus() {
-  const h1 = document.querySelector("h1");
+function manageFocus(h1) {
   if (!h1) {
     return;
   }
@@ -253,7 +306,10 @@ function buildHref(router, routeName, routeParams) {
   try {
     const buildUrl = router.buildUrl;
     if (buildUrl) {
-      return buildUrl(routeName, routeParams);
+      const url = buildUrl(routeName, routeParams);
+      if (url !== undefined) {
+        return url;
+      }
     }
     return router.buildPath(routeName, routeParams);
   } catch {
@@ -261,25 +317,67 @@ function buildHref(router, routeName, routeParams) {
     return undefined;
   }
 }
+function parseTokens(value) {
+  return value ? value.match(/\S+/g) ?? [] : [];
+}
 function buildActiveClassName(isActive, activeClassName, baseClassName) {
   if (isActive && activeClassName) {
-    return baseClassName ? `${baseClassName} ${activeClassName}`.trim() : activeClassName;
+    const activeTokens = parseTokens(activeClassName);
+    if (activeTokens.length === 0) {
+      return baseClassName ?? undefined;
+    }
+    if (!baseClassName) {
+      return activeTokens.join(" ");
+    }
+    const baseTokens = parseTokens(baseClassName);
+    const seen = new Set(baseTokens);
+    for (const token of activeTokens) {
+      if (!seen.has(token)) {
+        seen.add(token);
+        baseTokens.push(token);
+      }
+    }
+    return baseTokens.join(" ");
   }
   return baseClassName ?? undefined;
 }
 function applyLinkA11y(element) {
+  if (!element) {
+    return;
+  }
   if (element instanceof HTMLAnchorElement || element instanceof HTMLButtonElement) {
     return;
   }
-  if (!element.getAttribute("role")) {
+  if (!element.hasAttribute("role")) {
     element.setAttribute("role", "link");
   }
-  if (!element.getAttribute("tabindex")) {
+  if (!element.hasAttribute("tabindex")) {
     element.setAttribute("tabindex", "0");
   }
 }
 
 var _tmpl$ = /*#__PURE__*/web.template(`<a>`);
+// Slow-path source cache: shared per-router, keyed by routeName + params + flags.
+// Captured slow-path values are stable per Link (props captured at init), so the
+// cache key is guaranteed stable for the lifetime of any consumer.
+const activeSourceCache = new WeakMap();
+function getOrCreateActiveSource(router, routeName, routeParams, activeStrict, ignoreQueryParams) {
+  let perRouter = activeSourceCache.get(router);
+  if (!perRouter) {
+    perRouter = new Map();
+    activeSourceCache.set(router, perRouter);
+  }
+  const key = `${routeName}|${JSON.stringify(routeParams)}|${activeStrict}|${ignoreQueryParams}`;
+  let source = perRouter.get(key);
+  if (!source) {
+    source = sources.createActiveRouteSource(router, routeName, routeParams, {
+      strict: activeStrict,
+      ignoreQueryParams
+    });
+    perRouter.set(key, source);
+  }
+  return source;
+}
 function Link(props) {
   const merged = solidJs.mergeProps({
     routeParams: EMPTY_PARAMS,
@@ -289,13 +387,13 @@ function Link(props) {
     ignoreQueryParams: true
   }, props);
   const [local, rest] = solidJs.splitProps(merged, ["routeName", "routeParams", "routeOptions", "activeClassName", "activeStrict", "ignoreQueryParams", "onClick", "target", "class", "children"]);
-  const router = useRouter();
   const ctx = solidJs.useContext(RouterContext);
-  const useFastPath = ctx?.routeSelector && !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
-  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(sources.createActiveRouteSource(router, local.routeName, local.routeParams, {
-    strict: local.activeStrict,
-    ignoreQueryParams: local.ignoreQueryParams
-  }));
+  if (!ctx) {
+    throw new Error("Link must be used within a RouterProvider");
+  }
+  const router = ctx.router;
+  const useFastPath = !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
+  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(getOrCreateActiveSource(router, local.routeName, local.routeParams, local.activeStrict, local.ignoreQueryParams));
   const href = solidJs.createMemo(() => buildHref(router, local.routeName, local.routeParams));
   const handleClick = evt => {
     if (local.onClick) {
@@ -327,13 +425,13 @@ function Link(props) {
   })();
 }
 
-const cache = new WeakMap();
+const cache$1 = new WeakMap();
 function useRouterError() {
   const router = useRouter();
-  let source = cache.get(router);
+  let source = cache$1.get(router);
   if (!source) {
     source = sources.createErrorSource(router);
-    cache.set(router, source);
+    cache$1.set(router, source);
   }
   return createSignalFromSource(source);
 }
@@ -352,9 +450,11 @@ function RouterErrorBoundary(props) {
     return snap.version > dismissedVersion() ? snap.error : null;
   });
   const resetError = () => setDismissedVersion(snapshot().version);
-  return [web.memo(() => props.children), web.memo(() => {
-    const error = visibleError();
-    return error ? props.fallback(error, resetError) : null;
+  return [web.memo(() => props.children), web.createComponent(solidJs.Show, {
+    get when() {
+      return visibleError();
+    },
+    children: error => props.fallback(error(), resetError)
   })];
 }
 
@@ -424,7 +524,9 @@ const useRoute = () => {
 };
 
 function createStoreFromSource(source) {
-  const [state, setState] = store.createStore(structuredClone(source.getSnapshot()));
+  const [state, setState] = store.createStore({
+    ...source.getSnapshot()
+  });
   const unsubscribe = source.subscribe(() => {
     setState(store.reconcile(source.getSnapshot()));
   });
@@ -433,23 +535,24 @@ function createStoreFromSource(source) {
 }
 
 function useRouteStore() {
-  const ctx = solidJs.useContext(RouteContext);
-  if (!ctx) {
-    throw new Error("useRouteStore must be used within a RouterProvider");
-  }
   const router = useRouter();
   return createStoreFromSource(sources.createRouteSource(router));
 }
 
 function useRouteNodeStore(nodeName) {
   const router = useRouter();
-  return createStoreFromSource(sources.createRouteNodeSource(router, nodeName));
+  return createStoreFromSource(getOrCreateNodeSource(router, nodeName));
 }
 
+const cache = new WeakMap();
 function useRouterTransition() {
   const router = useRouter();
-  const store = sources.createTransitionSource(router);
-  return createSignalFromSource(store);
+  let source = cache.get(router);
+  if (!source) {
+    source = sources.createTransitionSource(router);
+    cache.set(router, source);
+  }
+  return createSignalFromSource(source);
 }
 
 function isRouteActive(linkRouteName, currentRouteName) {