@k8ordo/state

履歴エントリ

開いている行や広げたパネルのように、戻るボタンでは元に戻したい一方で、リンクでは共有したくない状態があります。こうした状態はentryに置きます。

このページの内容

entryのスキーマ

orders-state.ts
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),
  }),
});

definePageStateにentryのスキーマを渡します。値はURLには含まれません。Navigation APIが履歴エントリごとに持つ状態の、定義のキーの下に保存されます。

値は文字列にされず、型の付いたまま保存されます。真偽値はz.boolean()で、数値はz.number()で受けます。書いた値はそのままの型でもう一度スキーマで検証されます。z.stringbool()や型を変えるtransformは、書くたびに既定値に戻ります。

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

urlとentryの併用

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

1つの定義にurlとentryの両方を書けます。useAppStateは、2つを1つのオブジェクトにまとめて返します。

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

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

書き込みの振り分け

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

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

1回のupdate()で、urlとentryの両方を変えられます。urlの値が変わるかどうかで、書き込み方が決まります。

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

URLを変える書き込みは、今のentryの値を新しい履歴エントリへ持ち越します。ほかの定義が履歴エントリに保存した値も、そのまま残ります。

ブラウザ操作での復元

urlもentryも、ブラウザの履歴エントリにあります。ライブラリは別の記録を持ちません。ブラウザで戻る、進む、再読み込みをすると両方に同じように反映されます。

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

urlとentryの比較

絞り込みをurlに、開いている注文をentryに置いたdefinePageStateで、このページのURLと履歴エントリを実際に書き換えます。

絞り込み
  • 発送済み
  • 未発送
  • 未発送
url
クエリなし
entry
{ expanded: [] }

試してみる

  1. 「A-102」を開きます。entryの値は変わりますが、URLのクエリは変わりません。
  2. 絞り込みを「未発送」に切り替えます。クエリが?status=pendingになり、「A-102」は開いたまま残ります。
  3. 「A-103」も開いてから、ブラウザの戻るを押します。絞り込みが「すべて」に戻り、開いている注文も「A-102」だけに戻ります。
  4. ページを再読み込みしても、絞り込みと開いている注文はそのまま残ります。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。