@connextar/house 0.1.1 → 0.3.0

package/dist/ux/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one thing an optimistic commit has to be able to say: "that didn't work,
+ * and here is what to tell the person".
+ *
+ * The hooks in this folder take a commit function that throws on failure —
+ * the only failure contract every transport already has. An app whose client
+ * returns a result object instead of throwing wraps it once (see
+ * `commitApi` in `lib/api.ts`) rather than teaching this layer its envelope.
+ */
+export declare class ActionError extends Error {
+    /** HTTP status, where the transport had one. */
+    readonly status?: number;
+    /**
+     * Whatever the refusal carried. A conflict usually carries the record as it
+     * now is, which is what a caller merges into rather than rolling back to.
+     */
+    readonly data?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** The wording to show for a thrown value, whatever it turned out to be. */
+export declare function errorMessage(error: unknown, fallback?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/ux/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ux/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMhG;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAyB,GAAG,MAAM,CAItF"}

package/dist/ux/errors.js

@@ -0,0 +1,33 @@
+/**
+ * The one thing an optimistic commit has to be able to say: "that didn't work,
+ * and here is what to tell the person".
+ *
+ * The hooks in this folder take a commit function that throws on failure —
+ * the only failure contract every transport already has. An app whose client
+ * returns a result object instead of throwing wraps it once (see
+ * `commitApi` in `lib/api.ts`) rather than teaching this layer its envelope.
+ */
+export class ActionError extends Error {
+    /** HTTP status, where the transport had one. */
+    status;
+    /**
+     * Whatever the refusal carried. A conflict usually carries the record as it
+     * now is, which is what a caller merges into rather than rolling back to.
+     */
+    data;
+    constructor(message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "ActionError";
+        this.status = options.status;
+        this.data = options.data;
+    }
+}
+/** The wording to show for a thrown value, whatever it turned out to be. */
+export function errorMessage(error, fallback = "Something went wrong") {
+    if (error instanceof Error && error.message)
+        return error.message;
+    if (typeof error === "string" && error)
+        return error;
+    return fallback;
+}
+//# sourceMappingURL=errors.js.map

package/dist/ux/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ux/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,gDAAgD;IACvC,MAAM,CAAU;IACzB;;;OAGG;IACM,IAAI,CAAW;IAExB,YAAY,OAAe,EAAE,UAAgE,EAAE;QAC7F,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,QAAQ,GAAG,sBAAsB;IAC5E,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/ux/feedback.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+/**
+ * How this layer tells someone what happened, without knowing what the app
+ * uses to tell them.
+ *
+ * A toast library is a design decision, and the whole point of these hooks is
+ * that they can be lifted into a shared package. So the hooks report an event
+ * and the app decides what an event looks like — one provider at the root,
+ * wired to whatever that app already has.
+ */
+export interface ActionFeedback {
+    tone: "success" | "error";
+    title: string;
+    description?: string;
+}
+export type ActionReporter = (feedback: ActionFeedback) => void;
+export declare function ActionFeedbackProvider({ report, children }: {
+    report: ActionReporter;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The app's reporter, or the console fallback. Stable across renders. */
+export declare function useActionReporter(): ActionReporter;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/ux/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/ux/feedback.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;AAchE,wBAAgB,sBAAsB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,qBAEjH;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/ux/feedback.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+const ReporterContext = React.createContext(null);
+/**
+ * Without a provider a failure still has to go somewhere: swallowing it is how
+ * an optimistic update becomes a lie. The console is a poor place to tell
+ * someone something, but it is not silence, and it shows up in a test.
+ */
+const fallbackReporter = (feedback) => {
+    if (feedback.tone !== "error")
+        return;
+    console.error(`[action] ${feedback.title}${feedback.description ? `: ${feedback.description}` : ""}`);
+};
+export function ActionFeedbackProvider({ report, children }) {
+    return _jsx(ReporterContext.Provider, { value: report, children: children });
+}
+/** The app's reporter, or the console fallback. Stable across renders. */
+export function useActionReporter() {
+    return React.useContext(ReporterContext) ?? fallbackReporter;
+}
+//# sourceMappingURL=feedback.js.map

package/dist/ux/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../src/ux/feedback.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmB/B,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,CAAwB,IAAI,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,gBAAgB,GAAmB,CAAC,QAAQ,EAAE,EAAE;IACpD,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO;IACtC,OAAO,CAAC,KAAK,CAAC,YAAY,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxG,CAAC,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAyD;IAChH,OAAO,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YAAG,QAAQ,GAA4B,CAAC;AACxF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,KAAK,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,gBAAgB,CAAC;AAC/D,CAAC"}

package/dist/ux/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@connextar/house/ux` — the interface answers the click.
+ *
+ * Optimistic updates and pending state, with no framework in them: React, and
+ * nothing else. The half that needs Next — the navigation bar and the spinner
+ * on the link you clicked — is `@connextar/house/ux/navigation`, kept apart so
+ * that `next` stays the optional peer dependency it is declared to be. A
+ * barrel that re-exported both made it mandatory for anyone importing so much
+ * as the pure patch engine, which a smoke test caught before 0.3.0 shipped.
+ *
+ * What this module needs from the host arrives as a function (`commit`), a
+ * provider (`ActionFeedbackProvider`) or a class name — never as an import.
+ */
+export { ActionError, errorMessage } from "./errors.js";
+export { ActionFeedbackProvider, useActionReporter, type ActionFeedback, type ActionReporter } from "./feedback.js";
+export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, type Patch, type PatchKind, type RowKey, } from "./optimistic.js";
+export { useAction, useKeyedAction, type Action, type ActionOptions, type KeyedAction } from "./use-action.js";
+export { useOptimisticList, type OptimisticList, type OptimisticListOptions, type WriteOptions, } from "./use-optimistic-list.js";
+export { useOptimisticValue, type OptimisticValue, type OptimisticValueOptions } from "./use-optimistic-value.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ux/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,MAAM,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/ux/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@connextar/house/ux` — the interface answers the click.
+ *
+ * Optimistic updates and pending state, with no framework in them: React, and
+ * nothing else. The half that needs Next — the navigation bar and the spinner
+ * on the link you clicked — is `@connextar/house/ux/navigation`, kept apart so
+ * that `next` stays the optional peer dependency it is declared to be. A
+ * barrel that re-exported both made it mandatory for anyone importing so much
+ * as the pure patch engine, which a smoke test caught before 0.3.0 shipped.
+ *
+ * What this module needs from the host arrives as a function (`commit`), a
+ * provider (`ActionFeedbackProvider`) or a class name — never as an import.
+ */
+export { ActionError, errorMessage } from "./errors.js";
+export { ActionFeedbackProvider, useActionReporter } from "./feedback.js";
+export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, } from "./optimistic.js";
+export { useAction, useKeyedAction } from "./use-action.js";
+export { useOptimisticList, } from "./use-optimistic-list.js";
+export { useOptimisticValue } from "./use-optimistic-value.js";
+//# sourceMappingURL=index.js.map

package/dist/ux/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,GAIR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAqD,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,GAIlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAqD,MAAM,2BAA2B,CAAC"}

package/dist/ux/navigation-index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@connextar/house/ux/navigation` — feedback for moving between screens.
+ *
+ * Its own entry point because it is the only part of `ux` that imports `next`,
+ * which is an optional peer dependency: an app on another framework (or any
+ * app's Vitest suite running under plain Node) can still have the optimistic
+ * hooks from `@connextar/house/ux` without Next installed.
+ */
+export { BUSY_ATTRIBUTE, NavigationProgress, startNavigation, startRouteProgress, useAppRouter, useNavigate, } from "./navigation-progress.js";
+//# sourceMappingURL=navigation-index.d.ts.map

package/dist/ux/navigation-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-index.d.ts","sourceRoot":"","sources":["../../src/ux/navigation-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/ux/navigation-index.js

@@ -0,0 +1,10 @@
+/**
+ * `@connextar/house/ux/navigation` — feedback for moving between screens.
+ *
+ * Its own entry point because it is the only part of `ux` that imports `next`,
+ * which is an optional peer dependency: an app on another framework (or any
+ * app's Vitest suite running under plain Node) can still have the optimistic
+ * hooks from `@connextar/house/ux` without Next installed.
+ */
+export { BUSY_ATTRIBUTE, NavigationProgress, startNavigation, startRouteProgress, useAppRouter, useNavigate, } from "./navigation-progress.js";
+//# sourceMappingURL=navigation-index.js.map

package/dist/ux/navigation-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-index.js","sourceRoot":"","sources":["../../src/ux/navigation-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/ux/navigation-progress.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+/** The attribute every busy control carries, action or navigation alike. */
+export declare const BUSY_ATTRIBUTE = "data-busy";
+/**
+ * Show the navigation feedback for something this module cannot see on its
+ * own — a programmatic `router.push`. Pass the control that caused it and it
+ * gets the spinner too.
+ */
+export declare function startNavigation(element?: Element | null): void;
+/** Backwards-compatible alias for the original name. */
+export declare const startRouteProgress: typeof startNavigation;
+/**
+ * `useRouter`, with the navigation feedback attached to `push` and `replace`.
+ *
+ * A click that runs `router.push(href)` is invisible to the watcher above —
+ * there is no anchor and no popstate — so those navigations were the ones with
+ * no feedback at all. The worst case is the one right after a save: the
+ * button's own spinner stops when the write lands, and then nothing happens
+ * for as long as the next screen takes to render.
+ *
+ * Swapping the import is the whole change; no call site moves. `refresh`,
+ * `back`, `forward` and `prefetch` pass straight through — a refresh re-renders
+ * the screen you are already on, which needs no bar.
+ */
+export declare function useAppRouter(): {
+    push: (href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions | undefined) => void;
+    replace: (href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions | undefined) => void;
+    back(): void;
+    forward(): void;
+    refresh(): void;
+    prefetch(href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").PrefetchOptions): void;
+    experimental_gesturePush?(href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions): void;
+    bfcacheId: string;
+};
+/**
+ * `router.push` with the feedback attached, and the control that caused it
+ * marked as busy. For a button that navigates rather than saves.
+ */
+export declare function useNavigate(): (href: string, options?: {
+    replace?: boolean;
+    element?: Element | null;
+}) => void;
+/**
+ * Mount once, above everything else — including anything that suspends, or the
+ * bar disappears for exactly the navigations it is there for.
+ *
+ * `className` styles the filled part of the bar, so the host app picks its own
+ * colour without this module knowing any of its tokens.
+ */
+export declare function NavigationProgress({ className }: {
+    className?: string;
+}): React.JSX.Element;
+//# sourceMappingURL=navigation-progress.d.ts.map

package/dist/ux/navigation-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-progress.d.ts","sourceRoot":"","sources":["../../src/ux/navigation-progress.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAgC/B,4EAA4E;AAC5E,eAAO,MAAM,cAAc,cAAc,CAAC;AAqB1C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAI9D;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,wBAAkB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY;;;;;;;;;EAkB3B;AAED;;;GAGG;AACH,wBAAgB,WAAW,WAGhB,MAAM,YAAY;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,UAO3E;AA0ID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,qBAMvE"}

package/dist/ux/navigation-progress.js

@@ -0,0 +1,245 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePathname, useRouter, useSearchParams } from "next/navigation.js";
+import * as React from "react";
+/**
+ * Feedback for the other half of "nothing answers my click": moving between
+ * screens.
+ *
+ * Two signals, because they answer two different questions:
+ *
+ * - **A bar across the top of the page** — "something is happening". It waits
+ *   a moment before appearing so a fast navigation does not flash it.
+ * - **A spinner on the thing that was clicked** — "*that* is what is
+ *   happening". Without it, a slow route on a page full of links gives no clue
+ *   which one took, which is when people click a second one.
+ *
+ * The second is set on the DOM node directly rather than through React state.
+ * The click can land on any link anywhere in the tree, including ones rendered
+ * by pages this component knows nothing about, and an attribute is the only
+ * thing they all have in common. `data-busy` is the same attribute the button
+ * primitive sets for an action, so one rule in the stylesheet covers both.
+ */
+/** Delay before the bar appears, so fast navigations do not flash it. */
+const START_DELAY_MS = 140;
+/** Cadence of the trickle that creeps the bar towards 90%. */
+const TRICKLE_MS = 220;
+/** Safety net: never leave the bar running forever if a navigation never commits. */
+const MAX_PENDING_MS = 20_000;
+/** How long the completed bar stays at 100% before fading out. */
+const COMPLETE_MS = 260;
+const START_EVENT = "cx:navigation-start";
+/** The attribute every busy control carries, action or navigation alike. */
+export const BUSY_ATTRIBUTE = "data-busy";
+/** The control currently marked as the reason for a navigation. */
+let marked = null;
+function unmark() {
+    if (!marked)
+        return;
+    marked.removeAttribute(BUSY_ATTRIBUTE);
+    marked.removeAttribute("aria-busy");
+    marked = null;
+}
+function mark(element) {
+    if (marked === element)
+        return;
+    unmark();
+    if (!element)
+        return;
+    marked = element;
+    element.setAttribute(BUSY_ATTRIBUTE, "true");
+    element.setAttribute("aria-busy", "true");
+}
+/**
+ * Show the navigation feedback for something this module cannot see on its
+ * own — a programmatic `router.push`. Pass the control that caused it and it
+ * gets the spinner too.
+ */
+export function startNavigation(element) {
+    if (typeof window === "undefined")
+        return;
+    mark(element ?? null);
+    window.dispatchEvent(new Event(START_EVENT));
+}
+/** Backwards-compatible alias for the original name. */
+export const startRouteProgress = startNavigation;
+/**
+ * `useRouter`, with the navigation feedback attached to `push` and `replace`.
+ *
+ * A click that runs `router.push(href)` is invisible to the watcher above —
+ * there is no anchor and no popstate — so those navigations were the ones with
+ * no feedback at all. The worst case is the one right after a save: the
+ * button's own spinner stops when the write lands, and then nothing happens
+ * for as long as the next screen takes to render.
+ *
+ * Swapping the import is the whole change; no call site moves. `refresh`,
+ * `back`, `forward` and `prefetch` pass straight through — a refresh re-renders
+ * the screen you are already on, which needs no bar.
+ */
+export function useAppRouter() {
+    const router = useRouter();
+    return React.useMemo(() => ({
+        ...router,
+        // Forwarded by spread, not by naming the options: passing an explicit
+        // `undefined` is a different call from passing nothing.
+        push: (...args) => {
+            startNavigation();
+            router.push(...args);
+        },
+        replace: (...args) => {
+            startNavigation();
+            router.replace(...args);
+        },
+    }), [router]);
+}
+/**
+ * `router.push` with the feedback attached, and the control that caused it
+ * marked as busy. For a button that navigates rather than saves.
+ */
+export function useNavigate() {
+    const router = useRouter();
+    return React.useCallback((href, options) => {
+        startNavigation(options?.element ?? null);
+        if (options?.replace)
+            router.replace(href);
+        else
+            router.push(href);
+    }, [router]);
+}
+/**
+ * A click that means "take me there", rather than one the browser will handle
+ * itself — a new tab, a download, a context menu.
+ *
+ * Deliberately *not* a `defaultPrevented` check. This runs in the capture
+ * phase, and the reason is the whole point of this listener: Next's `Link`
+ * calls `preventDefault()` on its way to a client-side navigation, so by the
+ * time a bubble-phase listener sees the click, every in-app link looks
+ * cancelled. Guarding on `defaultPrevented` there means the bar fires for
+ * exactly the navigations that do not need it and stays silent for all the
+ * ones that do — which is what was happening here until this was measured in
+ * the browser.
+ */
+function isPlainLeftClick(event) {
+    return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+}
+function navigatesElsewhere(url) {
+    if (url.origin !== window.location.origin)
+        return false;
+    // API routes are downloads/exports, not page navigations.
+    if (url.pathname.startsWith("/api/"))
+        return false;
+    return url.pathname !== window.location.pathname || url.search !== window.location.search;
+}
+function NavigationProgressBar({ className }) {
+    const pathname = usePathname();
+    const search = useSearchParams().toString();
+    const [progress, setProgress] = React.useState(null);
+    const timers = React.useRef([]);
+    const active = React.useRef(false);
+    const clearTimers = React.useCallback(() => {
+        timers.current.forEach((id) => window.clearTimeout(id));
+        timers.current = [];
+    }, []);
+    const stop = React.useCallback(() => {
+        clearTimers();
+        active.current = false;
+        delete document.body.dataset.routePending;
+        unmark();
+        setProgress((value) => (value === null ? null : 100));
+        window.setTimeout(() => {
+            // A new navigation may have started in the meantime; leave its bar alone.
+            if (!active.current)
+                setProgress(null);
+        }, COMPLETE_MS);
+    }, [clearTimers]);
+    const start = React.useCallback(() => {
+        if (active.current)
+            return;
+        active.current = true;
+        document.body.dataset.routePending = "true";
+        const trickle = () => {
+            setProgress((value) => (value === null ? value : Math.min(value + Math.max(1, (90 - value) * 0.16), 90)));
+            timers.current.push(window.setTimeout(trickle, TRICKLE_MS));
+        };
+        timers.current.push(window.setTimeout(() => {
+            setProgress(8);
+            trickle();
+        }, START_DELAY_MS));
+        timers.current.push(window.setTimeout(stop, MAX_PENDING_MS));
+    }, [stop]);
+    // The navigation committed once the URL the router reports has changed.
+    const initialRender = React.useRef(true);
+    React.useEffect(() => {
+        if (initialRender.current) {
+            initialRender.current = false;
+            return;
+        }
+        stop();
+    }, [pathname, search, stop]);
+    React.useEffect(() => {
+        const onClick = (event) => {
+            if (!isPlainLeftClick(event))
+                return;
+            const target = event.target;
+            if (!(target instanceof Element))
+                return;
+            const anchor = target.closest("a");
+            if (!anchor?.href || anchor.hasAttribute("download"))
+                return;
+            if (anchor.target && anchor.target !== "_self")
+                return;
+            if (!navigatesElsewhere(new URL(anchor.href)))
+                return;
+            // Mark before `start`, which returns early when a navigation is already
+            // running: a second click during a slow load should still move the
+            // spinner to the link that was actually clicked.
+            mark(anchor);
+            start();
+        };
+        const onSubmit = (event) => {
+            if (event.defaultPrevented)
+                return;
+            const form = event.target;
+            if (!(form instanceof HTMLFormElement))
+                return;
+            if (form.method.toLowerCase() !== "get" || !form.action)
+                return;
+            if (new URL(form.action).origin !== window.location.origin)
+                return;
+            if (event.submitter)
+                mark(event.submitter);
+            start();
+        };
+        // Capture, so this runs before `Link` cancels the click (see above). The
+        // submit listener stays in the bubble phase on purpose: a form with an
+        // `onSubmit` that saves rather than navigates is the common case here, and
+        // `defaultPrevented` is exactly how to tell those apart.
+        document.addEventListener("click", onClick, true);
+        document.addEventListener("submit", onSubmit);
+        window.addEventListener("popstate", start);
+        window.addEventListener(START_EVENT, start);
+        return () => {
+            document.removeEventListener("click", onClick, true);
+            document.removeEventListener("submit", onSubmit);
+            window.removeEventListener("popstate", start);
+            window.removeEventListener(START_EVENT, start);
+            clearTimers();
+            unmark();
+            delete document.body.dataset.routePending;
+        };
+    }, [clearTimers, start]);
+    if (progress === null)
+        return null;
+    return (_jsx("div", { className: "pointer-events-none fixed inset-x-0 top-0 z-[100] h-0.5", role: "progressbar", "aria-label": "Loading page", "aria-busy": "true", children: _jsx("div", { className: className, style: { width: `${progress}%`, opacity: progress === 100 ? 0 : 1 } }) }));
+}
+/**
+ * Mount once, above everything else — including anything that suspends, or the
+ * bar disappears for exactly the navigations it is there for.
+ *
+ * `className` styles the filled part of the bar, so the host app picks its own
+ * colour without this module knowing any of its tokens.
+ */
+export function NavigationProgress({ className }) {
+    return (_jsx(React.Suspense, { fallback: null, children: _jsx(NavigationProgressBar, { className: className }) }));
+}
+//# sourceMappingURL=navigation-progress.js.map

package/dist/ux/navigation-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-progress.js","sourceRoot":"","sources":["../../src/ux/navigation-progress.tsx"],"names":[],"mappings":"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"}