@zerotal/flow 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -10,6 +10,45 @@ between minor versions.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-08-10
+
+### Fixed
+
+- **`focusOnError` did nothing on a page that rendered through the runtime.** The
+  JSX runtime rewrites `-` to `.` inside a `flow:` attribute — right for a
+  hand-written `flow:loading-class`, wrong for a name the directive map already
+  spells out. `focusOnError` reached the DOM as `flow:focus.error` while the
+  bridge only ever queries `[flow\:focus-error]`, so focus-on-error worked on a
+  compiled page and silently did not on one the compiler bailed out of (a
+  branching `render()`, say). Mapped names now go out verbatim; the kebab→dot
+  rewrite still applies to attributes written by hand. `sortGroupId` was affected
+  the same way.
+
+- **`flow:navigate` now scrolls, instead of leaving you wherever the last page
+  was.** The SPA swap replaced the page under a stationary viewport and never
+  touched the scroll offset, so following a link from near the bottom of a long
+  list landed you halfway down the next page. Nothing visible changed, which
+  reads as the page having failed to load rather than as a scroll problem.
+
+  A navigation now lands at the top of the new page, or at the fragment when the
+  href names one (`/docs#install`) — which is what the same link does without the
+  SPA swap. Back and Forward restore the position the entry was left at.
+
+  The scroll happens inside the swap, after the root is replaced: the document
+  only has its new height (and its fragment targets) at that point, and inside a
+  View Transition it is also what the "after" snapshot captures, so the animation
+  ends at the right offset rather than sliding to it. It is issued with
+  `behavior: "instant"`, so a page whose CSS sets `scroll-behavior: smooth` does
+  not animate the whole way up on every visit.
+
+### Added
+
+- **`preserveScroll`** — `<Link href="…" preserveScroll>` and
+  `this.navigateCurrent({ query: …, preserveScroll: true })` leave the viewport
+  where it is. For a control partway down a page — a sort header, a filter, a tab
+  strip — going to the top loses the thing the user was just looking at. Compiles
+  to `flow:navigate.preserve` on the anchor.
+
 ## [1.3.0] — 2026-08-09
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "maturity": "experimental",
   "private": false,
@@ -45,14 +45,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.3.0",
-    "@zerotal/orm": "1.3.0",
-    "@zerotal/validator": "1.3.0",
+    "@zerotal/core": "1.4.0",
+    "@zerotal/orm": "1.4.0",
+    "@zerotal/validator": "1.4.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.3.0",
+    "@zerotal/broadcasting": "1.4.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/client/bridge.ts

@@ -865,7 +865,11 @@ function _syncUrlParams(comp: FlowComponent): void {
 
   if (newUrl !== location.pathname + location.search + location.hash) {
     if (pushed) {
-      history.pushState({ flowNavigate: true }, "", newUrl);
+      // Bank the scroll offset first: this entry is about to become a Back
+      // target, and the viewport has not moved, so where the user is now is
+      // where Back should return them.
+      _rememberScroll();
+      _pushHistoryEntry(newUrl);
     } else {
       history.replaceState(history.state, "", newUrl);
     }
@@ -2357,7 +2361,127 @@ function _takePrefetched(href: string): string | null {
   return Date.now() - cached.at < PREFETCH_TTL_MS ? cached.html : null;
 }
 
-async function _navigateTo(href: string, pushState = true): Promise<void> {
+// ── Scroll position across SPA navigations ────────────────────────────────────
+//
+// A real navigation puts you at the top of the new page, and Back puts you back
+// where you were. Swapping the DOM under a stationary viewport does neither: you
+// click a link near the bottom of a long list and land halfway down the next
+// page, which reads as the page having failed to load.
+//
+// Positions live in a map keyed by history entry rather than inside
+// `history.state`, because the entry you are *leaving* on a Back cannot be
+// stamped — by the time `popstate` fires, `history.state` is already the
+// destination's. A key per entry lets both directions be recorded.
+
+let _nextHistoryKey = 1;
+let _currentHistoryKey = 0;
+const _scrollByHistoryKey = new Map<number, [number, number]>();
+
+/**
+ * The live scroll offset, tracked passively.
+ *
+ * Read from here rather than from `window.scrollY` at navigation time: on a
+ * `popstate` the browser may already have applied its own scroll restoration
+ * before our handler runs, and by then the outgoing page's real position is gone.
+ */
+let _liveScroll: [number, number] = [0, 0];
+
+function _trackScroll(): void {
+  const update = (): void => {
+    _liveScroll = [window.scrollX, window.scrollY];
+  };
+  update();
+  window.addEventListener("scroll", update, { passive: true });
+}
+
+/** Record where the current history entry was left, so Back can return to it. */
+function _rememberScroll(): void {
+  _scrollByHistoryKey.set(_currentHistoryKey, _liveScroll);
+}
+
+/** Start a new history entry, keyed so its scroll position can be found again. */
+function _pushHistoryEntry(url: string): void {
+  _currentHistoryKey = _nextHistoryKey++;
+  history.pushState({ flowNavigate: true, flowKey: _currentHistoryKey }, "", url);
+}
+
+/** Where a navigation should leave the viewport. */
+export type ScrollIntent = "top" | "preserve" | readonly [number, number];
+
+/** The fragment of an href, without the `#`. Empty when it has none. */
+export function _hashOf(href: string): string {
+  const at = href.indexOf("#");
+  return at === -1 ? "" : href.slice(at + 1);
+}
+
+/**
+ * Resolve what a navigation should do to the viewport.
+ *
+ * A recorded position wins outright: on Back/Forward the whole point is to land
+ * where the user was, and `preserveScroll` is passed alongside it only as the
+ * fallback for an entry with nothing recorded.
+ */
+export function _scrollIntent(options: {
+  preserveScroll?: boolean;
+  restoreScroll?: readonly [number, number] | undefined;
+}): ScrollIntent {
+  return options.restoreScroll ?? (options.preserveScroll ? "preserve" : "top");
+}
+
+/** What {@link _applyScroll} will do, separated out so the decision is testable. */
+export type ScrollAction =
+  | { kind: "none" }
+  | { kind: "offset"; left: number; top: number }
+  | { kind: "fragment"; id: string };
+
+export function _scrollAction(intent: ScrollIntent, hash: string): ScrollAction {
+  if (intent === "preserve") return { kind: "none" };
+  if (intent !== "top") return { kind: "offset", left: intent[0], top: intent[1] };
+
+  // A fragment in the URL beats the top of the page — that is what the browser
+  // would have done for the same link without the SPA swap.
+  let id = hash;
+  if (id) {
+    try {
+      id = decodeURIComponent(id);
+    } catch {
+      /* malformed %-escape — take the fragment literally, as browsers do */
+    }
+  }
+  return id ? { kind: "fragment", id } : { kind: "offset", left: 0, top: 0 };
+}
+
+function _applyScroll(intent: ScrollIntent, hash: string): void {
+  const action = _scrollAction(intent, hash);
+  if (action.kind === "none") return;
+
+  // `behavior: "instant"` on purpose: a page with `scroll-behavior: smooth` in
+  // its CSS would otherwise animate the whole way up on every navigation, which
+  // on a long page is a visible scroll-back the user did not ask for.
+  if (action.kind === "offset") {
+    window.scrollTo({ left: action.left, top: action.top, behavior: "instant" });
+    return;
+  }
+
+  const target = document.getElementById(action.id);
+  // A fragment naming nothing on the page lands at the top, same as a real load.
+  if (target) target.scrollIntoView({ behavior: "instant", block: "start" });
+  else window.scrollTo({ left: 0, top: 0, behavior: "instant" });
+}
+
+/** Options for {@link _navigateTo}. */
+interface NavigateOptions {
+  /** Add a history entry. False on Back/Forward, where the entry already exists. */
+  push?: boolean;
+  /** Leave the viewport where it is instead of going to the top of the new page. */
+  preserveScroll?: boolean;
+  /** Offsets to restore, for Back/Forward. Takes precedence over `preserveScroll`. */
+  restoreScroll?: readonly [number, number] | undefined;
+}
+
+async function _navigateTo(href: string, options: NavigateOptions = {}): Promise<void> {
+  const { push = true } = options;
+  const scrollIntent = _scrollIntent(options);
   let html: string;
   const prefetched = _takePrefetched(href);
   if (prefetched !== null) {
@@ -2391,8 +2515,9 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     // document.write() here would re-inject the classic runtime <script> into the
     // *current* realm and redeclare its top-level bindings (e.g. `class
     // FlowComponent` → "already declared"). A hard navigation also re-bootstraps
-    // the client cleanly for the new layout.
-    if (pushState) window.location.assign(href);
+    // the client cleanly for the new layout — including the scroll position,
+    // which the browser owns on a real document load.
+    if (push) window.location.assign(href);
     else window.location.reload();
     return;
   }
@@ -2417,6 +2542,12 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   const incomingClone = incomingRoot.cloneNode(true) as HTMLElement;
   _carryPersisted(currentRoot, incomingClone);
 
+  // Where this page is sitting, banked before the swap. Replacing the root
+  // changes the document height, and the browser clamps the scroll offset
+  // against it — read afterwards, a position near the bottom of a long page
+  // comes back as somewhere near the bottom of the short one.
+  if (push) _rememberScroll();
+
   // Swap state script + component root. Wrapped in a View Transition when the
   // browser supports it, for a smooth cross-page animation; falls back to an
   // instant swap otherwise.
@@ -2427,6 +2558,11 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     _cleanupDisconnected();
     _scanComponents();
     _processHead(doc); // re-apply head from the incoming page (shell stylesheet + page meta)
+    // Inside the swap, not after it: the document only has its new height (and
+    // its fragment targets) once the root is in place. Inside the View
+    // Transition callback this is also what the "after" snapshot captures, so
+    // the animation ends at the right offset instead of sliding there.
+    _applyScroll(scrollIntent, _hashOf(href));
   };
   const _startVT = (document as unknown as { startViewTransition?: (cb: () => void) => unknown })
     .startViewTransition;
@@ -2435,7 +2571,7 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   if (typeof _startVT === "function" && !_reduceMotion) _startVT.call(document, _swap);
   else _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
 
-  if (pushState) history.pushState({ flowNavigate: true }, "", href);
+  if (push) _pushHistoryEntry(href);
   const incomingTitle = doc.querySelector("title");
   if (incomingTitle) document.title = incomingTitle.textContent ?? "";
   _updateCurrentLinks();
@@ -2542,14 +2678,22 @@ function _setupPrefetch(): void {
 function _setupNavigationLinks(): void {
   _updateCurrentLinks();
   _setupPrefetch();
+  _trackScroll();
 
   // Stamp the initial history entry as ours. A fresh page load has `history.state === null`,
   // so without this, pressing Back to the first page fires `popstate` with a null state — the
   // handler below ignores it and the URL changes while the page stays put. Replacing (not
-  // pushing) keeps the entry in place; it just gains the flowNavigate marker.
-  if (!(history.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
+  // pushing) keeps the entry in place; it just gains the flowNavigate marker and its scroll key.
+  const initial = history.state as { flowNavigate?: boolean; flowKey?: number } | null;
+  if (typeof initial?.flowKey === "number") {
+    // Restored from bfcache or a reload — keep the key so the entry's recorded
+    // position still matches, and mint above it so a new entry can't collide.
+    _currentHistoryKey = initial.flowKey;
+    _nextHistoryKey = Math.max(_nextHistoryKey, initial.flowKey + 1);
+  } else {
+    _currentHistoryKey = _nextHistoryKey++;
     history.replaceState(
-      { ...(history.state as object | null), flowNavigate: true },
+      { ...(initial as object | null), flowNavigate: true, flowKey: _currentHistoryKey },
       "",
       location.href,
     );
@@ -2566,13 +2710,31 @@ function _setupNavigationLinks(): void {
       return;
     }
     e.preventDefault();
-    void _navigateTo(href);
+    void _navigateTo(href, {
+      preserveScroll: anchor.hasAttribute("flow:navigate.preserve"),
+    });
   });
 
   window.addEventListener("popstate", (e) => {
-    if ((e.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
-      void _navigateTo(window.location.pathname + window.location.search, false);
-    }
+    const state = e.state as { flowNavigate?: boolean; flowKey?: number } | null;
+    if (!state?.flowNavigate) return;
+
+    // Bank the outgoing entry before the key moves on, so Forward lands correctly
+    // too — not just Back. This is the half that cannot be done from
+    // `history.state`, which by now already describes the destination.
+    _rememberScroll();
+    const destination = state.flowKey;
+    const restore = destination === undefined ? undefined : _scrollByHistoryKey.get(destination);
+    if (destination !== undefined) _currentHistoryKey = destination;
+
+    void _navigateTo(location.pathname + location.search + location.hash, {
+      push: false,
+      restoreScroll: restore,
+      // Nothing recorded for this entry — it predates the runtime, or a reload
+      // cleared the map. Leave the viewport alone rather than jumping to the
+      // top, which is not what Back does.
+      preserveScroll: restore === undefined,
+    });
   });
 }
 
@@ -2584,12 +2746,21 @@ function _setupNavigationLinks(): void {
  * Both read the live URL from window.location (kept in sync by flow:navigate).
  * Ideal for instant filters, e.g.:
  *   <select @change="$flow.navigateCurrent({ query: { status: $event.target.value || null } })">
+ *
+ * Like any navigation this lands at the top of the page. For a control sitting
+ * partway down — a filter row the user is looking at while they change it —
+ * pass `preserveScroll: true` to leave the viewport alone:
+ *   $flow.navigateCurrent({ query: { status: … }, preserveScroll: true })
  */
 function _currentUrl(options: CurrentUrlOptions = {}): string {
   return buildUrlWithQuery(window.location.href, options);
 }
-function _navigateCurrent(options: CurrentUrlOptions = {}): Promise<void> {
-  return _navigateTo(buildUrlWithQuery(window.location.href, options));
+function _navigateCurrent(
+  options: CurrentUrlOptions & { preserveScroll?: boolean } = {},
+): Promise<void> {
+  return _navigateTo(buildUrlWithQuery(window.location.href, options), {
+    preserveScroll: options.preserveScroll ?? false,
+  });
 }
 
 const _debouncedModelSend = (() => {

package/src/compiler/directives.ts

@@ -22,6 +22,7 @@ export const BOOLEAN_DIRECTIVES: Record<string, string> = {
   hideOnDirty: "flow:dirty.remove",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  navigatePreserveScroll: "flow:navigate.preserve",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
   cloak: "flow:cloak",

package/src/compiler/transform.ts

@@ -1634,6 +1634,10 @@ function _compileRenderMethod(
           emitStatic(" flow:navigate.hover");
           continue;
         }
+        if (ln === "preserveScroll" && attr.initializer === undefined) {
+          emitStatic(" flow:navigate.preserve");
+          continue;
+        }
         if (ln === "current") {
           const ci = attr.initializer;
           // current={false} → opt out of the auto active class; current={true} → default (skip).

package/src/components.ts

@@ -22,6 +22,7 @@ export interface LinkProps {
   hover?: boolean;
   current?: boolean;
   exact?: boolean;
+  preserveScroll?: boolean;
   [key: string]: unknown;
 }
 
@@ -35,18 +36,26 @@ export interface LinkProps {
  * the automatic active state to an exact path match. Any other props pass through to
  * the `<a>`.
  *
+ * Following a link lands at the top of the new page, as a full navigation would —
+ * or at the fragment, if the href names one. `preserveScroll` leaves the viewport
+ * where it is instead, which is what you want for a control the user is looking at
+ * partway down a page (a filter, a sort header, a tab strip) rather than a link
+ * that takes them somewhere else.
+ *
  * @example
  * ```tsx
  * <Link href="/posts" hover>Posts</Link>
  * <Link href="/dashboard" exact>Dashboard</Link>
+ * <Link href="/posts?sort=title" preserveScroll>Title</Link>
  * ```
  *
  * @category Navigation & data
  */
 export function Link(props: LinkProps & { children?: unknown }): HtmlNode {
-  const { href, hover, current, exact, children, ...rest } = props;
+  const { href, hover, current, exact, preserveScroll, children, ...rest } = props;
   const out: Record<string, unknown> = { ...rest, href, navigate: true, children };
   if (hover) out["navigateHover"] = true;
+  if (preserveScroll) out["navigatePreserveScroll"] = true;
   // `current` overrides the automatic URL-based active state:
   //   false → never active (flow:current.ignore)
   //   true  → always active, and stays active across SPA navigations (flow:current.force).

package/src/jsx-runtime.ts

@@ -59,6 +59,7 @@ interface FlowDirectives {
 
   navigate?: boolean;
   navigateHover?: boolean;
+  navigatePreserveScroll?: boolean;
   current?: string;
   currentExact?: boolean;
   currentStrict?: boolean;
@@ -704,6 +705,10 @@ const PULSE_PROP_MAP: Record<string, string> = {
   dirtyTarget: "flow:target",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  // One word on purpose: toFlowHtmlAttr() rewrites every `-` in a flow: attribute
+  // to a `.`, so a hyphenated modifier would reach the DOM under a different name
+  // here than the compiler emits.
+  navigatePreserveScroll: "flow:navigate.preserve",
   current: "flow:current",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
@@ -1154,8 +1159,14 @@ export function jsx(
       continue;
     }
 
-    let htmlKey = PULSE_PROP_MAP[k] || k;
-    htmlKey = toFlowHtmlAttr(htmlKey);
+    // A mapped value is the attribute name the compiler emits and the bridge queries
+    // for, so it goes out verbatim. Running it through toFlowHtmlAttr() rewrote the
+    // hyphen in `flow:focus-error` to a dot, and the runtime path then emitted an
+    // attribute nothing listens for: `focusOnError` worked on a compiled page and did
+    // nothing at all on one that fell back to the runtime, with no error either way.
+    // The kebab→dot rewrite is for hand-written `flow:*` attributes only.
+    const mapped = PULSE_PROP_MAP[k];
+    const htmlKey = mapped ?? toFlowHtmlAttr(k);
 
     // Special object formatting for `confirm={{ message, title?, confirm?, cancel?,
     // variant?, danger?, icon?, prompt? }}`. The bare {message} and {message,prompt}