履歴エントリに状態を置く

definePageStateにentryのスキーマを渡します。値はURLには出ず、Navigation APIが履歴エントリごとに持つ状態の中に、定義のキーを名前空間にして保存されます。

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),
  }),
});

値は文字列にされず、型の付いたまま保存されます。そのため、真偽値はz.boolean()で、数はz.number()で、書いたとおりの型のまま受けます。

ただし、スキーマは自分が出した値をもう一度受け付けなければなりません。書いた値は、型の付いたままスキーマを通り直すからです。z.stringbool()や型を変える変換は、書くたびに既定値へ戻ってしまいます。

サーバーには履歴エントリが無いので、サーバーの描画とハイドレーションの描画は既定値で行われます。

1つの定義に、urlとentryの両方を書けます。useAppStateが返す状態は、2つを平らにまとめたものです。

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);

フィールドをurlからentryへ移しても、変わるのは定義だけで、呼び出す側のコードはそのまま動きます。ただし綴りはフィールドについて回ります。urlでz.stringbool()だった真偽値は、entryではz.boolean()に書き換えます。

同じ名前のフィールドを両方に書くと、型エラーになります。実行時にも、"orders" declares in both url and entry: statusのように投げます。

1回のupdate()で、urlとentryの両方を変えられます。2つの面は同じ履歴エントリにあるので、何が変わったかで書き込み方が決まります。

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

update({ expanded: ['A-102'] });
updateCurrentEntry()で今のエントリを書き換える

• urlの値が変わるとき：navigation.navigate()を1回呼び、新しいURLとエントリの状態を一緒に渡します。片方だけが変わった画面が見えることはありません。
• entryの値だけが変わるとき：navigation.updateCurrentEntry()で今のエントリを書き換えます。遷移を伴わないので、どのルーターの下でも動きます。{ history: 'push' }を付けても、新しいエントリは作られません。

URLを変える書き込みは、今のentryの値を新しいエントリへ持ち越します。エントリの状態にほかの定義の名前空間があれば、それもそのまま残ります。

2つの面は、どちらもブラウザの履歴エントリに載っています。ライブラリが別に記録を取っているわけではないので、ブラウザの操作がそのまま両方に効きます。

• 戻る/進む：移った先のエントリにあったurlとentryが、一緒に戻ります。
• 再読み込み：同じエントリのまま読み込み直すので、どちらも残ります。
• URLを新しいタブで開く：渡るのはURLだけです。urlは同じ値になり、entryは既定値から始まります。
• リンクのクリック：新しいエントリにはentryの値がまだ無いので、既定値から始まります。
• セッションの復元：古いスキーマが書いた値が戻ってくることもあります。スキーマに合わない値は、そのフィールドだけが既定値に戻ります。