State in the history entry

Hand definePageState an entry schema. The values never show in the URL: they are kept in the state the Navigation API holds for each history entry, under the definition’s key.

import { definePageState } from '@k8ordo/state';
import * as z from 'zod';

export const ordersState = definePageState('orders', {
  entry: z.object({
    expanded: z.array(z.string()).default([]),
    showNotes: z.boolean().default(false),
  }),
});

The values are kept typed, never turned into strings, so a boolean is a plain z.boolean() and a number a plain z.number().

The schema must accept its own output, though, because a written value passes the schema again as the typed value it is. A z.stringbool() or a type-changing transform lands on its default on every write.

The server has no history entry, so the server render and the hydration render show the defaults.

One definition can hold both url and entry. The state useAppState returns is the two merged flat.

export const ordersState = definePageState('orders', {
  url: z.object({
    status: z.enum(['all', 'pending', 'shipped']).default('all'),
  }),
  entry: z.object({
    expanded: z.array(z.string()).default([]),
  }),
});

const [{ status, expanded }, update] = useAppState(ordersState);

Moving a field from url to entry changes the definition and nothing at the call sites. The spelling follows the slot, though: a boolean that was z.stringbool() in url becomes z.boolean() in entry.

Declaring the same field in both is a type error, and at runtime it throws: "orders" declares in both url and entry: status.

One update() can change both url and entry. The two faces sit on the same history entry, so what changed decides how it is written.

update({ status: 'pending' }, { history: 'push' });
One navigation.navigate()

update({ expanded: ['A-102'] });
updateCurrentEntry() on the current entry

• When a url value changes: one navigation.navigate() carries the new URL and the entry state together, so a screen with only one of them changed is never seen.
• When only entry values change: navigation.updateCurrentEntry() rewrites the current entry. No navigation is involved, so it works under any router, and { history: 'push' } creates no new entry.

A write that changes the URL carries the current entry values over to the new entry, along with whatever other definitions keep in the entry’s state.

Both faces live on the browser’s history entry, not in a record the library keeps on the side, so what the browser does applies to both.

• Back and forward: the url and entry of the entry you land on come back together.
• Reload: the page loads again on the same entry, so both stay.
• Opening the URL in a new tab: only the URL travels. url has the same values, and entry starts from its defaults.
• Following a link: the new entry has no entry values yet, so they start from the defaults.
• Session restore: values an older schema wrote may come back. A value the schema rejects falls back to that field’s default alone.