@barefootjs/router 0.14.0

package/README.md

@@ -0,0 +1,73 @@
+# @barefootjs/router
+
+Backend-agnostic, progressively-enhanced client router for BarefootJS. It
+intercepts same-origin navigations, fetches the **ordinary full-page HTML** any
+backend already returns (no protocol header, no JSON endpoint), swaps only the
+page **region**, and disposes/re-hydrates just the islands inside it. The shell
+stays mounted; everything outside the region keeps its DOM, scroll, and state.
+
+```ts
+import { startRouter } from '@barefootjs/router'
+
+startRouter() // install once on the client
+```
+
+Mark the swappable region in your layout with `<Region>` (compiled to
+`[bf-region]`, see `spec/router.md`); the router swaps the first match.
+
+## Public API
+
+- `startRouter(options?): Router` — install once; SSR no-op. Returns
+  `{ stop, navigate, prefetch }`.
+- `navigate(href, { history? }): Promise<void>` — programmatic navigation.
+- `BF_REGION` — re-export of the `bf-region` marker for server-side helpers.
+
+### Options
+
+| option | default | purpose |
+| --- | --- | --- |
+| `region` | `[bf-region]` | selector for the swap point |
+| `rehydrate` / `dispose` | runtime fallback chain | override island lifecycle |
+| `loadModule` | `import(src)` | how island modules are loaded |
+| `shouldIntercept` | same-origin, plain click | per-anchor opt-out (`data-bf-router="false"`, `download`, `target`, `rel=external`) |
+| `prefetch` / `prefetchDelay` | `true` / `65` | hover/focus/pointerdown prefetch + `modulepreload` |
+| `cacheFreshMs` / `cacheStaleMs` / `cacheCap` | `15000` / `60000` / `30` | SWR + LRU snapshot cache |
+| `scrollToTop` | `true` | scroll to top after a swap |
+| `manageFocus` | `true` | move focus into the region + announce the route |
+| `morph` | `true` | preserve `[data-bf-permanent]` live nodes across a swap (no-op when none present); `false` forces a plain `replaceChildren` |
+
+## Correct by default
+
+The client runtime is an **optional peer**: a fully static shell ships the
+router with zero `@barefootjs/client`. When islands are present, `dispose` and
+`rehydrate` degrade through the same fallback chain
+(`window.__bf_*` seams → `@barefootjs/client/runtime`'s
+`disposeScope`/`rehydrateScope`) and never silently no-op. There is no opt-in
+setup step.
+
+## Behaviour
+
+- **Last-wins** across overlapping navigations (a newer nav aborts the older).
+- **SWR cache** stores promises (a prefetch + click share one request); aging
+  entries serve instantly and refresh in the background; failures aren't cached.
+- **Module-aware**: a response's new island modules are imported *before* the
+  re-hydration walk, and deduped across navigations.
+- **Redirect-aware**: history commits at the response's final URL.
+- **History.state preserved**: a router replace merges rather than clobbers
+  existing state (scroll-restoration libs, framework state).
+- **A11y**: focus moves into the swapped region (its first heading) and the new
+  title is announced via a polite live region.
+- **Persistence** (`data-bf-permanent`): an element marked
+  `<div data-bf-permanent="player">` keeps its *live* node across a swap — its
+  state, media playback, scroll, and hydrated scope survive — matched between
+  documents by the attribute value (or `id`). A no-op when no element is marked;
+  pass `morph: false` for a plain swap.
+
+## Scope
+
+A **single authored region** (the broadest `[bf-region]` match), correct by
+default. `searchParams()` (query-only navigation without a swap) ships in
+`@barefootjs/client` (v0.5); the router drives it via the `__bf_pushSearch`
+seam, so query-only navigations short-circuit once a consumer is present.
+`data-bf-permanent` persistence is v1. Compiler-derived **nested** regions
+(deepest-differs swap, sibling master–detail) are v2.

package/dist/a11y.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Focus management and route-change announcement on swap (spec/router.md
+ * lifecycle step 7).
+ *
+ * A client swap replaces content without a browser navigation, so the browser
+ * does none of the accessibility work a real page load does: focus is left on a
+ * now-detached node and a screen reader never hears that the route changed.
+ * After a region swap the router (a) moves focus into the new region and (b)
+ * announces the route via a polite live region, mirroring what Remix/Turbo do.
+ */
+/**
+ * Move focus into the freshly swapped region so keyboard/AT users resume there
+ * rather than at the top of a detached tree. Prefer the region's first heading
+ * (gives a screen reader the page context); fall back to the region element
+ * itself, made programmatically focusable without becoming a tab stop.
+ */
+export declare function focusRegion(region: Element): void;
+/**
+ * Announce the new route through a singleton `aria-live="polite"` region kept
+ * visually hidden. Setting its text after the swap lets a screen reader read
+ * the new page title without stealing focus.
+ */
+export declare function announceNavigation(title: string | null): void;
+//# sourceMappingURL=a11y.d.ts.map

package/dist/a11y.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../src/a11y.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAejD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAS7D"}

package/dist/cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stale-while-revalidate snapshot cache with an LRU bound.
+ *
+ * The cache stores *Promises*, so a prefetch and a near-simultaneous click for
+ * the same URL share a single in-flight request (single-flight). Three states,
+ * keyed on `now` vs the entry's `refreshAt`/`staleAt`:
+ *   - fresh  (now < refreshAt)  → serve cached, no refetch.
+ *   - aging  (refreshAt ≤ now < staleAt) → serve cached AND refresh in the
+ *     background (single-flight), so a swap is instant while the next is fresh.
+ *   - stale  (now ≥ staleAt) / miss → fetch synchronously; never serve stale.
+ */
+import type { PageSnapshot, RouterState } from './types.ts';
+export declare function fetchSnapshot(state: RouterState, url: string): Promise<PageSnapshot | null>;
+export declare function loadPage(state: RouterState, url: string): Promise<PageSnapshot | null>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI3D,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAa3F;AAuBD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAwBtF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { startRouter, navigate } from './router.ts';
+export type { RouterOptions, NavigateOptions, Router } from './types.ts';
+export { BF_REGION } from '@barefootjs/shared';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA"}