Navigation Guards

lockNavigation for a hard block; onNavigationRequest for confirm-to-leave (next()-only commit).

import { atom, html, useUtils, renderApp } from 'mates';
import { ConfirmDialog } from 'mates-ui';

const EditForm = () => {
  const { onNavigationRequest, navigateTo } = useUtils();
  const dirty = atom(false);
  const confirmOpen = atom(false);
  let pendingNext = null;

  // Confirm-to-leave: with any subscriber, navigateTo waits for next().
  // Every subscriber must call next() to allow (AND). Omit next() to cancel.
  onNavigationRequest(({ next }) => {
    if (!dirty()) {
      next();
      return;
    }
    pendingNext = next;
    confirmOpen.set(true);
  });

  return () => html`
    <input type="text" @input=${(e) => dirty.set(!!e.target.value)} />
    <button @click=${() => navigateTo('/about')}>Leave</button>
    ${ConfirmDialog({
      openAtom: confirmOpen,
      title: 'Unsaved changes',
      message: 'Leave this page? Unsaved changes will be lost.',
      confirmLabel: 'Leave',
      cancelLabel: 'Stay',
      danger: true,
      onConfirm: () => {
        dirty.set(false);
        const go = pendingNext;
        pendingNext = null;
        go?.();
      },
      onCancel: () => { pendingNext = null; },
    })}
  `;
};

renderApp(EditForm, document.getElementById('app'));

Overview

Two tools cover leave guards: lockNavigation() for a silent hard block, and onNavigationRequest(fn) for confirm-to-leave. Prefer the request hook when you need a dialog.

With any onNavigationRequest subscriber, navigateTo never auto-commits. Every subscriber must call next() (AND). Prefer onNavigate for post-commit side effects.

lock vs request

API	Use when	Commit model
`lockNavigation()`	Silent hard block	`navigateTo` no-ops; `beforeunload` on tab close.
`onNavigationRequest(fn)`	Confirm dialog	Call `next()` to allow, omit to cancel.
`onNavigate`	After commit	Analytics / scroll — not a guard.

Type in the text box to mark the form dirty. navigateTo then opens a mates-ui ConfirmDialog; Leave calls next(), Stay cancels.

import { html, atom, useUtils, renderApp } from 'mates';

import { ConfirmDialog, Button, registerLayoutElements } from 'mates-ui';

registerLayoutElements();

const App = () => {

const { onNavigationRequest, navigateTo, pathAtom } = useUtils();

const dirty = atom(false);

const confirmOpen = atom(false);

let pendingNext = null;

let leaveMessage = 'Leave this page? Unsaved changes will be lost.';

onNavigationRequest(({ to, from, next }) => {

if (!dirty()) {

next();

return;

}

leaveMessage = `Leave ${from} for ${to}? Unsaved changes will be lost.`;

pendingNext = next;

confirmOpen.set(true);

});

return () => html`

<x-col spacing="2">

<p style="margin:0;opacity:.7">path=${pathAtom()} dirty=${dirty()}</p>

<input

type="text"

@input=${(e) => dirty.set(!!e.target.value)}

placeholder="Type to mark unsaved changes…"

style="box-sizing:border-box;width:100%;padding:.5rem .75rem;border-radius:8px;border:1px solid var(--md-color-border);background:var(--md-surface-section);color:var(--md-color-text);font:inherit;"

<x-row spacing="1" wrap>

${Button("navigateTo('/')", { variant: "outlined", on: { click: () => navigateTo('/') } })}

${Button("navigateTo('/about')", { variant: "outlined", on: { click: () => navigateTo('/about') } })}

${Button("Discard", { variant: "filled", on: { click: () => dirty.set(false) } })}

</x-row>

Sandbox cannot show window.confirm reliably — toggle allow to simulate next() vs cancel.

import { html, atom, useUtils, renderApp } from 'mates';

const App = () => {

const { onNavigationRequest, navigateTo, pathAtom } = useUtils();

const allow = atom(true);

const log = atom([]);

onNavigationRequest(({ to, from, next }) => {

log.update((rows) => { rows.push(from + ' → ' + to); });

if (allow()) next();

// else cancel (no next)

});

return () => html`

<p class="hint">path=${pathAtom()} allow=${allow()}</p>

<input type="checkbox" .checked=${allow()}

@change=${(e) => allow.set(e.target.checked)} />

Call next()

</label>

<button @click=${() => navigateTo('/')}>/</button>

<button @click=${() => navigateTo('/about')}>/about</button>

</div>

${log().map((line) => html`<div class="mono">${line}</div>`)}

</div>

};

renderApp(App, document.getElementById('app'));

API — Navigation lock & intercept

import { useUtils } from 'mates'

Prop / Option	Type	Default	Description
`lockNavigation()`	`void`	—	Hard block: navigateTo is a no-op (when no guards). Installs beforeunload.
`unlockNavigation()`	`void`	—	Re-enable navigation after lockNavigation().
`navigationLocked()`	`boolean`	—	Reactive atom — true while locked.
`onNavigationRequest(fn)`	`void`	—	Guard before commit. Detail: { to, from, replace, data, next }. Every subscriber must call next() (AND). Omit next() to cancel.

onNavigationRequest detail

Prop / Option	Type	Default	Description
`to / from`	`string`	—	Target and current path for the pending navigation.
`replace / data`	`boolean / unknown`	—	Original navigateTo args — preserved when you call next().
`next()`	`void`	—	Allow this navigation. Stale next() from an older attempt is ignored.

Navigation Guards

Overview

lock vs request

Unsaved text box — ConfirmDialog

onNavigationRequest confirm (simulated)