Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

4.8 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef } from 'react';
import { useBlocker } from 'react-router';

// Guards an editor's unsaved draft against BOTH exit doors (#3958):
//
//   1. In-app router navigation — a sidebar link, a ⌘K palette jump, a voice
//      `ui_navigate`, or the browser Back button. These never touch the page's
//      own controls, so a page-local handler can't see them; react-router's
//      `useBlocker` parks the navigation instead and hands back `proceed()` /
//      `reset()`.
//   2. Tab close / reload — `beforeunload`, which the browser owns.
//
// REQUIRES a data router (`createBrowserRouter` + `<RouterProvider>`, wired in
// `client/src/main.jsx`); `useBlocker` throws under a plain `<BrowserRouter>`.
// Tests rendering a page that uses this hook must mount it under
// `createMemoryRouter` + `<RouterProvider>`, not `<MemoryRouter>`.
//
// The caller renders its OWN confirm UI from `blocked` — an `InlineConfirmRow`,
// never `window.confirm` (see client/src/AGENTS.md).
//
//   const { blocked, proceed, reset } = useUnsavedChangesGuard(isDirty);
//   {blocked && <InlineConfirmRow onConfirm={discardAndProceed} onCancel={reset} … />}
//
// Discarding is the CALLER's job — only it knows how to reset its draft — so a
// discard handler resets local state and then calls `proceed()`.
// `scopePath` — the path prefix this editor OWNS, for an editor whose own
// in-page moves change the pathname. A splat route like
// `/pipeline/series/:id/manuscript/*` swaps the issue segment without leaving
// (or remounting) the editor, so the default pathname comparison would raise a
// discard confirm on every issue tab click. A navigation that stays under the
// prefix is an in-editor move and passes through unguarded; leaving it is a
// real exit and still parks. A plain string (not a predicate) so a caller can't
// re-register the blocker every render with an unmemoized inline function.
export default function useUnsavedChangesGuard(isDirty, { beforeUnload = true, scopePath } = {}) {
  // Same-location navigations (a re-click on the link you're already on, a
  // search-param tweak on the current page) don't unmount the editor, so
  // there's nothing to guard — let them through rather than raising a confirm
  // the user can't explain.
  const shouldBlock = useCallback(({ currentLocation, nextLocation }) => {
    if (!isDirty) return false;
    if (currentLocation.pathname === nextLocation.pathname) return false;
    // Segment-aware, not a bare `startsWith`: a sibling route that merely
    // shares the prefix (`/…/manuscript-export` against `/…/manuscript`) is a
    // real exit, and letting it through would discard the draft silently.
    const inScope = !!scopePath && (
      nextLocation.pathname === scopePath || nextLocation.pathname.startsWith(`${scopePath}/`)
    );
    return !inScope;
  }, [isDirty, scopePath]);
  const blocker = useBlocker(shouldBlock);
  const blocked = blocker.state === 'blocked';
  // A caller's discard handler and the clean-draft effect below can both run
  // in one commit. The effect retains the old blocker object, so its state
  // alone cannot prevent a second proceed() after React Router has moved on.
  const proceededRef = useRef(null);
  const proceed = useCallback(() => {
    if (blocker.state !== 'blocked' || proceededRef.current === blocker) return;
    proceededRef.current = blocker;
    blocker.proceed();
  }, [blocker]);

  // Once the draft settles while a navigation is parked — the user hit Save
  // with the confirm up, or typed the value back to what's stored — the
  // navigation they asked for RUNS. Dropping it would swallow the click: the
  // confirm hides and nothing ever navigates.
  useEffect(() => {
    if (!isDirty) proceed();
  }, [isDirty, proceed]);

  // Tab close / reload — the browser owns this prompt; preventDefault arms it.
  // `returnValue` is the legacy signal, still what some browsers actually read,
  // so set both or the tab can close without asking.
  useEffect(() => {
    if (!beforeUnload || !isDirty) return undefined;
    const onBeforeUnload = (e) => { e.preventDefault(); e.returnValue = ''; };
    window.addEventListener('beforeunload', onBeforeUnload);
    return () => window.removeEventListener('beforeunload', onBeforeUnload);
  }, [beforeUnload, isDirty]);

  // `proceed` / `reset` exist only while blocked — the optional call keeps a
  // stale confirm's button from throwing after the blocker went idle.
  const reset = useCallback(() => blocker.reset?.(), [blocker]);

  // Memoized: callers pass this object to `<UnsavedChangesConfirm guard>` and
  // name its members in dep arrays, so a fresh literal per render would be a
  // guaranteed miss on every editor's hot typing path.
  return useMemo(() => ({ blocked, proceed, reset }), [blocked, proceed, reset]);
}