state-in-url 4.1.10 → 4.1.11

package/README.CN.md

@@ -1,74 +1,125 @@
 [English](./README.md) | [한국어](./README.KO.md) | 简体中文
 
 <div align="center">
-  <img src="/assets/Logo_big.png?raw=true" alt="state-in-url logo"/>
+  <img src="/packages/example-nextjs14/public/Logo_symbol.png" alt="state-in-url logo" width="120px" />
 
-  <div>轻松在不相关的React组件之间共享状态，具有IDE自动完成和TS验证功能。无需任何麻烦或样板代码。</div>
+  # State in url
+</div>
+
+<div align="center">
 </div>
 
 <div align="center">
-<hr />
 
 [![npm](https://img.shields.io/npm/v/state-in-url.svg)](https://www.npmjs.com/package/state-in-url)
-![Tests](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml/badge.svg?branch=master)
+![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/73be54068b7f41b0b74a252579ac09ec)](https://app.codacy.com/gh/asmyshlyaev177/state-in-url/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+
+![Tests](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml/badge.svg?branch=master)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/73be54068b7f41b0b74a252579ac09ec)](https://app.codacy.com/gh/asmyshlyaev177/state-in-url/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/asmyshlyaev177/state-in-url/)
-![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)]([https://github.com/semantic-release/semantic-release](https://github.com/asmyshlyaev177/state-in-url))
+
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/asmyshlyaev177/state-in-url/badge)](https://scorecard.dev/viewer/?uri=github.com/asmyshlyaev177/state-in-url)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9679/badge)](https://www.bestpractices.dev/projects/9679)
+[![license](https://img.shields.io/github/license/asmyshlyaev177/state-in-url.svg?style=flat-square)](https://github.com/asmyshlyaev177/state-in-url/blob/master/LICENSE)
+<!-- or by embedding this in your HTML:
+<a href="https://www.bestpractices.dev/projects/9679"><img src="https://www.bestpractices.dev/projects/9679/badge"></a>  -->
+
 </div>
 
 <div align="center">
 
-<h4 align="center">如果发现bug，请随时提出issue</h4>
+<h4 align="center">如果您发现漏洞或有功能需求，请随时提交issue</h4>
 
-![演示-gif](https://github.com/asmyshlyaev177/state-in-url/assets/19854148/c9802601-4d42-4362-b3e4-37ff87c3b97f)
+![Demo-gif](https://github.com/asmyshlyaev177/state-in-url/blob/master/assets/Demo-gif.gif)
 
-<a href="https://state-in-url.dev/" target="_blank">演示</a> |
-<a href="https://state-in-url.netlify.app/" target="_blank">DEMO2</a> |
+# 演示页面
 
-<hr />
+<a href="https://state-in-url.dev" target="_blank">演示页面</a> |
+<a href="https://state-in-url.netlify.app/" target="_blank">镜像链接</a>
 
-添加⭐️来支持项目！
+<a href="https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md"  target="_blank">URI 长度限制： <b>安全上限为 12KB</b> </a>
 
 <hr />
 
-</div>
+点个 <a href="#"><img src="https://raw.githubusercontent.com/acervenky/animated-github-badges/master/assets/starbadge.gif" width="25" height="25"></a>  并且 <a href="https://github.com/asmyshlyaev177" target="_blank">关注我</a> 来支持这个项目!
+
+非常感激在[discussions](https://github.com/asmyshlyaev177/state-in-url/discussions/1)上提交你的反馈或意见
+
+如果觉得有用，就分享一下吧。
+[X.com](https://twitter.com/intent/tweet?&url=https://github.com/asmyshlyaev177/state-in-url)
+[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/asmyshlyaev177/state-in-url)
+[FB](https://www.facebook.com/sharer.php?u=https://github.com/asmyshlyaev177/state-in-url)
+[VK](http://vk.com/share.php?url=https://github.com/asmyshlyaev177/state-in-url)
 
-## 为什么使用state-in-url？
+  <hr />
 
-`state-in-url`是一个简单的状态管理工具，可以与URL同步。在不相关的React组件之间共享复杂状态，将状态同步到URL，对TS友好，兼容NextJS。
+  </div>
 
-# 使用场景
+[直接给我看代码!](#useurlstate)
 
-- 🙃 在不改变URL的情况下，在不同组件之间共享状态，是信号和其他状态管理工具的良好替代方案
-- 🔗 包含完整应用程序状态的可共享URL
-- 🔄 在页面重新加载之间轻松持久化状态
-- 🧠 在不相关的客户端组件之间同步数据
-- 🧮 在URL中存储未保存的用户表单
+## 为什么使用 `state-in-url`?
 
-# 特性
+将任何用户状态存储在查询参数中；想象一下在浏览器 URL 中嵌入 JSON 数据，同时保持数据的类型和结构。例如数字会被解码为数字而不是字符串，日期会被解码为日期，支持对象和数组等复杂结构。
+简单、快速，并且支持静态 TypeScript 验证。深度链接（即 URL 同步）变得轻而易举。
 
-- 🧩 **简单**：无需提供者、reducers、样板代码或新概念
-- 📘 **TypeScript支持和类型安全**：保留数据类型和结构，通过IDE建议、强类型和JSDoc注释增强开发体验
-- ⚛️ **框架灵活性**：为Next.js和React.js应用程序提供单独的钩子，以及用于纯JS的函数
-- ⚙ **经过充分测试**：单元测试和Playwright测试
-- ⚡ **快速**：最少的重新渲染
-- 🪶 **轻量级**：零依赖，占用空间小
+提供了适用于 Next.js 和 react-router 的 `useUrlState` 钩子，以及适用于其他 JavaScript 场景的辅助工具。
+由于现代浏览器支持超长的 URL，而用户并不关心查询字符串（通常的操作是全选、复制和粘贴）。
+
+是时候将查询字符串用于状态管理了，正如它最初的设计初衷。
+这个库为你处理了所有繁琐的工作。
+
+这个库是 NUQS 的一个很好的替代品。
+
+### 使用场景
+
+- 将未保存的用户表单或页面筛选条件存储在 URL 中
+- 将 URL 与 React 状态同步
+- 在不修改 URI 的情况下，直接在无关的客户端组件之间同步数据
+- 支持共享包含应用状态的 URL（深度链接，URL 状态同步）
+- 轻松实现页面刷新后的状态持久化
+
+### 特性
+
+- 🧩 **简单易用**：无需提供者（providers）、reducers 或样板代码，API 类似 `React.useState`，几乎没有学习成本。
+- 📘 **TypeScript 验证/自动补全**：状态是一个对象，根据 TypeScript 定义，IDE 和测试中会自动进行静态验证。
+- ✨ **支持复杂数据**：嵌套对象、日期和数组，像 JSON 一样工作，但存储在 URL 中。
+- ☂ **默认值支持**：如果 URL 中没有参数，会自动使用默认值。
+- ⌨ **结构化定义**：所有可能的值在开始时定义，避免访问不存在的键。
+- **兼容性**：保留第三方查询参数不变。
+- **灵活性**：同一页面可以使用多个状态对象，只需使用不同的键。
+- **快速**：最小化重新渲染，编码和解码大对象仅需约 [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185)。
+- **服务端渲染支持**：可在 Server Components 中使用，支持 Next.js 14 和 15。
+- **轻量级**：零依赖，库大小小于 2KB。
+- **开发者体验优化**：提供良好的文档、JSDoc 注释和示例。
+- **框架灵活性**：提供 `Next.js` 和 `react-router` 的钩子，以及适用于其他框架或纯 JavaScript 的辅助工具。
+- **全面测试**：包含单元测试和针对 Chrome/Firefox/Safari 的 Playwright 测试（[测试详情](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)）。
+- **宽松的许可证**：MIT 许可证，可自由使用。
 
 ## 目录
 
-- [安装](#安装)
-- [Next.js的`useUrlState`](#nextjs的useurlstate钩子)
-- [React.js的`useSharedState`](#reactjs的usesharedstate钩子)
-- [React.js的`useUrlEncode`](#reactjs的useurlencode钩子)
-- [纯JS使用的`encodeState`和`decodeState`](#纯js使用的encodestate和decodestate辅助函数)
-- [自动同步状态到URL](#自动同步状态)
-- [低级`encode`和`decode`函数](#encode和decode辅助函数)
-- [最佳实践](#最佳实践)
-- [注意事项](#注意事项)
-- [联系与支持](#联系与支持)
-- [更新日志](#更新日志)
-- [许可证](#许可证)
-- [灵感来源](#灵感来源)
+- [安装](#安装)  
+- [`useUrlState` 钩子](#useurlstate)  
+  - [Next.js 专用](#nextjs-专用的-useUrlState-钩子)  
+  - [React-Router 专用](#React-Router-专用的-useUrlState-钩子)  
+- [其他辅助工具](#其他钩子和辅助工具)  
+  - [其他路由器的 `useUrlStateBase` 钩子](#其他路由器的-useUrlStateBase-钩子)  
+  - [React.js/Next.js 的 `useSharedState` 钩子](#reactjs-的-useSharedState-钩子)  
+  - [React.js 的 `useUrlEncode` 钩子](#reactjs-的-useUrlEncode-钩子)  
+  - [纯 JS 使用的 `encodeState` 和 `decodeState` 辅助函数](#encodeState-和-decodeState-辅助函数)  
+  - [底层 `encode` 和 `decode` 函数](#encode-和-decode-辅助函数)  
+- [最佳实践](#最佳实践)  
+  - [注意事项](#注意事项)  
+- [其他](#其他)  
+  - [路线图](#路线图)  
+  - [贡献指南](#贡献指南与本地运行说明)  
+  - [联系与支持](#联系与支持)  
+  - [更新日志](#更新日志)  
+  - [许可证](#许可证)  
+  - [灵感来源](#灵感来源)  
+
+---
 
 ## 安装
 
@@ -83,29 +134,38 @@ yarn add state-in-url
 pnpm add state-in-url
 ```
 
-### 2. 编辑tsconfig.json
+### 2. 编辑 `tsconfig.json`
+
+在 `tsconfig.json` 的 `compilerOptions` 中设置 `"moduleResolution": "Bundler"`，或 `"moduleResolution": "Node16"`，或 `"moduleResolution": "NodeNext"`。  
+可能还需要设置 `"module": "ES2022"` 或 `"module": "ESNext"`。
+
+---
 
-在`tsconfig.json`的`compilerOptions`中设置`"moduleResolution": "Node16"`或`"moduleResolution": "NodeNext"`
+## `useUrlState`
 
-## Next.js的useUrlState钩子
+主钩子，接收初始状态作为参数，返回状态对象、更新 URL 的回调函数以及仅更新状态的回调函数。  
+所有使用相同 `state` 对象的组件会自动同步。
 
-[文档](packages/urlstate/next/useUrlState)
+### Next.js 专用的 `useUrlState` 钩子
 
-`useUrlState`是一个为Next.js应用程序设计的自定义React钩子，使客户端组件之间的通信变得简单。它允许你共享任何复杂的状态并将其与URL搜索参数同步，提供了一种在页面重新加载之间持久化状态并通过URL共享应用程序状态的方法。
+[完整 API 文档](packages/urlstate/next/useUrlState)
 
-### 使用示例
+[React-Router 示例](#React-Router-专用的-useUrlState-钩子)
 
-#### 基本用法
+#### 使用示例
 
-1. 定义状态形状
+##### 基础用法
 
-   ```typescript
-   // countState.ts
-   // 状态形状应该存储在一个常量中，不要直接传递对象
-   export const countState: CountState = { count: 0 }
+1. 定义状态结构及默认值
 
-   type CountState = { count: number }
-   ```
+ ```typescript
+ // userState.ts
+ // 只有与默认值不同的参数会被放入 URL。
+ export const userState: UserState = { name: '', age: 0 }
+
+ // 使用 `Type` 而非 `Interface`！
+ type UserState = { name: string, age: number }
+ ```
 
 2. 导入并使用
 
@@ -113,136 +173,206 @@ pnpm add state-in-url
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { countState } from './countState';
+import { userState } from './userState';
 
 function MyComponent() {
-  // 用于从服务器组件使用searchParams
-  // 例如 export default async function Home({ searchParams }: { searchParams: object }) {
-  // const { state, updateState, updateUrl } = useUrlState(countState, searchParams);
-  const { state, updateState, updateUrl } = useUrlState(countState);
-
-  // 不允许你意外地直接修改状态，需要TS
-  // state.count = 2 // <- 错误
+  // 可以传递 `replace` 参数，控制 `setUrl` 使用 `router.push` 还是 `router.replace`，默认为 replace=true
+  // 可以传递 `searchParams` 从服务端组件传入，如果需要从服务端组件获取数据，传递 `useHistory: false`
+  const { urlState, setUrl, setState, reset } = useUrlState(userState);
 
   return (
     <div>
-      <p>计数：{state.count}</p>
-
-      <button onClick={() => updateUrl({ count: state.count + 1 }), { replace: true }}>
-        增加（更新URL）
-      </button>
-
-      // 与React.useState相同的API
-      <button onClick={() => updateState(currState => ({...currState, count: currState.count + 1 }) )}>
-        增加（仅本地）
-      </button>
-      <button onClick={() => updateUrl()}>
-        同步更改到URL
-        // 或者不同步，只共享状态
-      </button>
-
-      <button onClick={() => updateUrl(state)}>
+      // 如果 URL 为空，urlState.name 将返回 `userState` 的默认值
+      <input value={urlState.name}
+        // 与 React.useState 相同的 API，例如 setUrl(currVal => currVal + 1)
+        onChange={(ev) => setUrl({ name: ev.target.value }) }
+      />
+      <input value={urlState.age}
+        onChange={(ev) => setUrl({ age: +ev.target.value }) }
+      />
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 可以立即更新状态，但根据需要同步到 URL
+        onBlur={() => setUrl()}
+      />
+
+      <button onClick={reset}>
         重置
       </button>
+
     </div>
   )
 }
 ```
 
-#### 复杂状态形状示例
+##### 自定义钩子以方便处理状态片段
+<details>
+  <Summary>示例</Summary>
 
-```typescript
-interface UserSettings {
-  theme: 'light' | 'dark';
-  fontSize: number;
-  notifications: boolean;
-}
+  ```typescript
+'use client';
 
-export const userSettings: UserSettings {
-  theme: 'light',
-  fontSize: 16,
-  notifications: true,
-}
+import React from 'react';
+import { useUrlState } from 'state-in-url/next';
+
+const form: Form = {
+    name: '',
+    age: undefined,
+    agree_to_terms: false,
+    tags: [],
+};
+
+type Form = {
+    name: string;
+    age?: number;
+    agree_to_terms: boolean;
+    tags: {id: string; value: {text: string; time: Date } }[];
+};
+
+export const useFormState = ({ searchParams }: { searchParams?: object }) => {
+    const { urlState, setUrl: setUrlBase, reset } = useUrlState(form, {
+      searchParams,
+    });
+
+    // 第一次导航会推送新的历史记录
+    // 后续导航将替换该记录
+    // 这样历史记录中只有两个条目 - ['/url', '/url?key=param']
+
+    const replace = React.useRef(false);
+    const setUrl = React.useCallback((
+        state: Parameters<typeof setUrlBase>[0],
+        opts?: Parameters<typeof setUrlBase>[1]
+      ) => {
+        setUrlBase(state, { replace: replace.current, ...opts });
+        replace.current = true;
+    }, [setUrlBase]);
+
+    return { urlState, setUrl, resetUrl: reset };
+};
+  ```
+</details>
+
+<hr />
+
+##### 复杂状态结构
+
+<details>
+  <Summary>示例</Summary>
+
+```typescript
+export const form: Form = {
+  name: '',
+  age: undefined,
+  agree_to_terms: false,
+  tags: [],
+};
+
+type Form = {
+  name: string;
+  age?: number;
+  agree_to_terms: boolean;
+  tags: { id: string; value: { text: string; time: Date } }[];
+};
 ```
 
 ```typescript
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { userSettings } from './userSettings';
-
-function SettingsComponent() {
-  // `state` 将从UserSettings类型推断！
-  const { state, updateUrl } = useUrlState(userSettings);
-
-  const toggleTheme = () => {
-    updateUrl(current => ({
-      ...current,
-      theme: current.theme === 'light' ? 'dark' : 'light',
-    }));
-  };
-
-  // 空闲时同步状态到URL
-  const timer = React.useRef(0 as unknown as NodeJS.Timeout);
-  React.useEffect(() => {
-    clearTimeout(timer.current);
-    timer.current = setTimeout(() => {
-      // 将通过内容而不是引用比较状态，只为新值触发更新
-      updateUrl(state);
-    }, 500);
+import { form } from './form';
 
-    return () => {
-      clearTimeout(timer.current);
-    };
-  }, [state, updateUrl]);
+function TagsComponent() {
+  // `urlState` 会从 Form 类型推断！
+  const { urlState, setUrl } = useUrlState(form);
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
 
   return (
     <div>
-      <h2>用户设置</h2>
-      <p>主题：{state.theme}</p>
-      <p>字体大小：{state.fontSize}px</p>
-      <button onClick={toggleTheme}>切换主题</button>
-      {/* 其他UI元素用于更新其他设置 */}
+      <Field text="标签">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <Tag
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
+              text={tag.value.text}
+              onClick={() => onChangeTags(tag)}
+              key={tag.id}
+            />
+          ))}
+        </div>
+      </Field>
     </div>
   );
 }
-...
-
-// 其他组件
-function Component() {
-  const { state } = useUrlState(defaultSettings);
 
-  return (
-    <div>
-      <p>通知 {state.notifications ? '开启' : '关闭'}</p>
-    </div>
-  )
-}
+const tags = [
+  {
+    id: '1',
+    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
+  },
+  {
+    id: '2',
+    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
+  },
+  {
+    id: '3',
+    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
+  },
+];
 ```
 
-#### 自动同步状态
+[示例页面代码](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-nextjs14/src/app/Form.tsx)
+</details>
+
+##### 仅更新状态并手动同步到 URL
+
+<details>
+  <Summary>示例</Summary>
+
+  ```typescript
 
-```typescript
   const timer = React.useRef(0 as unknown as NodeJS.Timeout);
   React.useEffect(() => {
     clearTimeout(timer.current);
     timer.current = setTimeout(() => {
-      // 将通过内容而不是引用比较状态，只为新值触发更新
-      updateUrl(state);
+      // 会比较状态内容而非引用，仅对新值触发更新
+      setUrl(urlState);
     }, 500);
 
     return () => {
       clearTimeout(timer.current);
     };
-  }, [state, updateUrl]);
+  }, [urlState, setUrl]);
 ```
 
-#### 服务器端渲染示例
+在 `onBlur` 时同步状态更符合实际使用场景。
+
+```typescript
+<input onBlur={() => updateUrl()} .../>
+```
+
+</details>
+
+##### 服务端渲染
+
+<details>
+  <Summary>示例</Summary>
 
 ```typescript
 export default async function Home({ searchParams }: { searchParams: object }) {
   return (
-    <Form sp={searchParams} />
+    <Form searchParams={searchParams} />
   )
 }
 
@@ -252,17 +382,21 @@ import React from 'react';
 import { useUrlState } from 'state-in-url/next';
 import { form } from './form';
 
-const Form = ({ sp }: { sp: object }) => {
-  const { state, updateState, updateUrl } = useUrlState(form, sp);
+const Form = ({ searchParams }: { searchParams: object }) => {
+  const { urlState, setState, setUrl } = useUrlState(form, { searchParams });
 }
 ```
 
-#### 在`layout`组件中使用钩子
+</details>
+
+##### 在 `layout` 组件中使用钩子
 
-这是一个棘手的部分，因为使用app router的nextjs不允许从服务器端访问searchParams。有一个使用中间件的解决方法，但它并不漂亮，而且可能在nextjs更新后停止工作。
+<details>
+  <Summary>示例</Summary>
+  这是一个棘手的部分，因为 Next.js 的 app router 不允许从服务端访问 searchParams。可以使用中间件解决，但不够优雅，且可能在 Next.js 更新后失效。
 
 ```typescript
-// 添加到适当的`layout.tsc`
+// 添加到适当的 `layout.tsc`
 export const runtime = 'edge';
 
 // middleware.ts
@@ -282,7 +416,7 @@ export function middleware(request: NextRequest) {
   return response;
 }
 
-// 目标layout组件
+// 目标布局组件
 import { headers } from 'next/headers';
 import { decodeState } from 'state-in-url/encodeState';
 
@@ -300,9 +434,16 @@ export default async function Layout({
     </div>
   );
 }
+
+
 ```
 
-#### 任意状态形状示例（不推荐）
+</details>
+
+##### 任意状态结构（不推荐）
+
+<details>
+  <Summary>示例</Summary>
 
 ```typescript
 'use client'
@@ -311,12 +452,112 @@ import { useUrlState } from 'state-in-url/next';
 const someObj = {};
 
 function SettingsComponent() {
-  const { state, updateUrl, updateState } = useUrlState<object>(someObj);
+  const { urlState, setUrl, setState } = useUrlState<object>(someObj);
+}
+```
+
+</details>
+
+### React-Router 专用的 `useUrlState` 钩子
+
+API 与 Next.js 版本相同，只是可以传递 [NavigateOptions](https://github.com/remix-run/react-router/blob/bc693ed9f39170bda13b9e1b282fb8e9d5925f66/packages/react-router/lib/context.ts#L99) 类型的选项。
+
+[API 文档](packages/urlstate/react-router/useUrlState)
+
+#### 示例
+
+```typescript
+export const form: Form = {
+  name: '',
+  age: undefined,
+  agree_to_terms: false,
+  tags: [],
+};
+
+type Form = {
+  name: string;
+  age?: number;
+  agree_to_terms: boolean;
+  tags: { id: string; value: { text: string; time: Date } }[];
+};
+
+```
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router';
+
+import { form } from './form';
+
+function TagsComponent() {
+  const { urlState, setUrl, setState } = useUrlState(form);
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
+
+  return (
+    <div>
+      <Field text="标签">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <Tag
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
+              text={tag.value.text}
+              onClick={() => onChangeTags(tag)}
+              key={tag.id}
+            />
+          ))}
+        </div>
+      </Field>
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 可以立即更新状态，但根据需要同步到 URL
+        onBlur={() => setUrl()}
+      />
+    </div>
+  );
 }
+
+const tags = [
+  {
+    id: '1',
+    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
+  },
+  {
+    id: '2',
+    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
+  },
+  {
+    id: '3',
+    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
+  },
+];
 ```
 
-## React.js的`useSharedState`钩子
-用于在任何React组件之间共享状态的钩子，已在Next.js和Vite中测试。
+[示例代码](packages/example-react-router6/src/Form-for-test.tsx)
+
+---
+
+## 其他钩子和辅助工具
+
+### 其他路由器的 `useUrlStateBase` 钩子
+
+用于创建与其他路由器（如 react-router 或 tanstack router）兼容的 `useUrlState` 钩子。
+
+[API 文档](packages/urlstate/useUrlStateBase)
+
+### React.js 的 `useSharedState` 钩子
+
+用于在任何 React 组件之间共享状态的钩子，已在 Next.js 和 Vite 中测试。
 
 ```typescript
 'use client'
@@ -329,59 +570,96 @@ function SettingsComponent() {
 }
 ```
 
-[文档](packages/urlstate/useSharedState/README.md)
+[API 文档](packages/urlstate/useSharedState/README.md)
 
-## React.js的`useUrlEncode`钩子
+### React.js 的 `useUrlEncode` 钩子
 
-[文档](packages/urlstate/useUrlEncode/README.md)
+[API 文档](packages/urlstate/useUrlEncode/README.md)
 
-## 纯JS使用的`encodeState`和`decodeState`辅助函数
+### `encodeState` 和 `decodeState` 辅助函数
 
-[文档](packages/urlstate/encodeState/README.md)
+[API 文档](packages/urlstate/encodeState/README.md)
 
-## `encode`和`decode`辅助函数
+### `encode` 和 `decode` 辅助函数
 
-[文档](packages/urlstate/encoder/README.md)
+[API 文档](packages/urlstate/encoder/README.md)
+
+---
 
 ## 最佳实践
 
-- 将您的状态形状定义为常量，以确保一致性
-- 使用TypeScript以增强类型安全性和自动完成功能
-- 避免在URL参数中存储敏感信息
-- 使用`updateState`进行频繁更新，使用`updateUrl`同步更改到URL
-- 在Next.js中使用`Suspence`包装客户端组件
-- 使用这个[扩展](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors)以获得可读的TS错误
+- 将状态结构定义为常量
+- 使用 TypeScript 增强类型安全和自动补全
+- 避免在 URL 参数中存储敏感信息（如 SSN、API 密钥等）
+- 使用此 [扩展](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) 以获得可读的 TS 错误提示
+
+可以为状态片段创建状态钩子，并在应用程序中重复使用。例如：
+```Typescript
+type UserState = {
+  name: string;
+  age: number;
+  other: { id: string, value: number }[]
+};
+const userState = {
+  name: '',
+  age: 0,
+  other: [],
+};
+
+export const useUserState = () => {
+  const { urlState, setUrl, reset } = useUrlState(userState);
+
+  // 其他逻辑
+
+  // 导航到其他页面时重置查询参数
+  React.useEffect(() => {
+    return reset
+  }, [])
+
+  return { userState: urlState, setUserState: setUrl };;
+}
+
+```
 
 ## 注意事项
 
-1. 只能传递可序列化的值，`Function`、`BigInt`或`Symbol`不会工作，可能类似`ArrayBuffer`的东西也不行。
-2. Vercel服务器限制头部（查询字符串和其他内容）的大小为**14KB**，所以保持您的URL状态在~5000个单词以下。https://vercel.com/docs/errors/URL_TOO_LONG
-3. 已在使用app router的`next.js` 14中测试，不计划支持pages。
+1. 只能传递可序列化的值，`Function`、`BigInt` 或 `Symbol` 无法使用，`ArrayBuffer` 等也可能无法使用。任何可以序列化为 JSON 的内容都可以使用。
+2. Vercel 服务器限制标头大小（查询字符串和其他内容）为 **14KB**，因此请将 URL 状态保持在约 5000 字以内。<https://vercel.com/docs/errors/URL_TOO_LONG>
+3. 已在 `next.js` 14/15 的 app router 中测试，暂无支持 pages 的计划。
 
-## 本地运行
+---
 
-克隆此仓库，运行`npm install`然后
+## 其他
 
-```sh
-npm run dev
-```
+### 贡献指南与本地运行说明
 
-转到[localhost:3000](http://localhost:3000)
+参见 [贡献文档](CONTRIBUTING.md)
+
+## 路线图
+
+- [x] `Next.js` 钩子
+- [x] `react-router` 钩子
+- [ ] `remix` 钩子
+- [ ] `svelte` 钩子
+- [ ] `astro` 钩子
+- [ ] 在 hash 中存储状态的钩子？
 
 ## 联系与支持
 
-- 创建[GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues)报告bug、提出功能请求或提问
+- 创建 [GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues) 以报告错误、请求功能或提出问题
 
-## [更新日志](https://github.com/asmyshlyaev177/state-in-url/blob/master/CHANGELOG.md)
+## [更新日志](CHANGELOG.md)
 
 ## 许可证
 
-本项目采用[MIT许可证](https://github.com/asmyshlyaev177/state-in-url/blob/master/LICENSE)。
+本项目采用 [MIT 许可证](LICENSE)。
 
 ## 灵感来源
 
-[在Vue中使用URL存储状态](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
+[NUQS](https://github.com/47ng/nuqs)
+
+[在 Vue 中使用 URL 存储状态](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
 
-[在URL中存储状态](https://antonz.org/storing-state/)
+[在 URL 中存储状态](https://antonz.org/storing-state/)
 
-[NextJS useSearchParams](https://nextjs.org/docs/app/api-reference/functions/use-search-params)
+[NextJS useSearchParams](https://nextjs.org/docs/app/api-reference/functions/use-search-params)

package/README.md

@@ -57,6 +57,8 @@ Share if it useful for you.
 
   </div>
 
+[Just Show Me Code!](#useurlstate)
+
 ## Why use `state-in-url`?
 
 Store any user state in query parameters; imagine JSON in a browser URL. All of it with keeping types and structure of data, e.g. numbers will be decoded as numbers not strings, dates as dates, etc, objects and arrays supported.

package/dist/encodeState/encodeState.mjs

@@ -1 +1 @@
-import{encode as f,decode as a}from"../encoder/encoder.mjs";import{getParams as i}from"../utils.mjs";function m(o,e,n){const r=i(n);return Object.entries(o||{}).forEach(([t,c])=>{const s=e?.[t];JSON.stringify(c)!==JSON.stringify(s)&&r.set(t,f(c))}),r.toString()}function d(o,e){return{...e||{},...Object.fromEntries([...i(o).entries()].map(([n,r])=>{const t=e?.[n];return[n,a(r,t)??t]}))}}export{d as decodeState,m as encodeState};
+import{encode as f,decode as m}from"../encoder/encoder.mjs";import{getParams as c}from"../utils.mjs";function a(r,e,n){const o=c(n);for(const[t,i]of Object.entries(r||{})){const s=e?.[t];JSON.stringify(i)!==JSON.stringify(s)&&o.set(t,f(i))}return o.toString()}function d(r,e){return{...e||{},...Object.fromEntries([...c(r).entries()].map(([n,o])=>{const t=e?.[n];return[n,m(o,t)??t]}))}}export{d as decodeState,a as encodeState};

package/dist/encoder/encoder.mjs

@@ -1 +1 @@
-import{SYMBOLS as r}from"../constants/constants.mjs";import{typeOf as u}from"../utils.mjs";function p(e){return typeof e=="function"||typeof e=="symbol"?"":l(e)?e:JSON.stringify(structuredClone(e),i).replace(/'/g,"%27").replace(/"/g,"'")}function i(e,t){const c=u(t);if(c!=="object"&&c!=="array")return a(t);if(c==="object"){const n=t;return Object.keys(n).forEach(o=>{n[o]=i(e,n[o])}),n}return c==="array"?t.map(n=>i(e,n)):t}const a=e=>{switch(u(e)){case"date":return r.date+new Date(e).toISOString();case"undefined":return r.undefined;default:return e}};function y(e,t){return f(e.replace(/'/g,'"').replace(/%27/g,"'"),t)}function f(e,t){try{return JSON.parse(e,d)}catch{return t}}function d(e,t){return typeof t=="string"?s(t):t}const s=e=>{if(e!==r.undefined)return e?.startsWith?.(r.date)?new Date(e.slice(1)):e},g=new RegExp(`^(${r.undefined}|${r.date})`),l=e=>g.test(String(e));export{y as decode,s as decodePrimitive,p as encode,a as encodePrimitive,f as parseJSON,d as reviver};
+import{SYMBOLS as n}from"../constants/constants.mjs";import{typeOf as u}from"../utils.mjs";function p(e){return typeof e=="function"||typeof e=="symbol"?"":l(e)?e:JSON.stringify(structuredClone(e),c).replace(/'/g,"%27").replace(/"/g,"'")}function c(e,r){const o=u(r);if(o!=="object"&&o!=="array")return f(r);if(o==="object"){const t=r;for(const i of Object.keys(t))t[i]=c(e,t[i]);return t}return o==="array"?r.map(t=>c(e,t)):r}const f=e=>{switch(u(e)){case"date":return n.date+new Date(e).toISOString();case"undefined":return n.undefined;default:return e}};function y(e,r){return a(e.replace(/'/g,'"').replace(/%27/g,"'"),r)}function a(e,r){try{return JSON.parse(e,s)}catch{return r}}function s(e,r){return typeof r=="string"?d(r):r}const d=e=>{if(e!==n.undefined)return e?.startsWith?.(n.date)?new Date(e.slice(1)):e},g=new RegExp(`^(${n.undefined}|${n.date})`),l=e=>g.test(String(e));export{y as decode,d as decodePrimitive,p as encode,f as encodePrimitive,a as parseJSON,s as reviver};

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-import i from"react";import{TIMEOUT as R}from"../constants/constants.mjs";import{useInsertionEffect as T}from"../useInsertionEffect.mjs";import{useSharedState as v}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as L}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as P}from"../utils.mjs";function b(t,a,u){const{parse:s,stringify:o}=L(t),{state:l,getState:r,setState:n}=v(t,()=>u?.({parse:s})||t),m=i.useRef(void 0);T(()=>{const e=()=>{const w=s(P(t));n(w)};return window.addEventListener(U,e),()=>{window.removeEventListener(U,e),clearTimeout(m.current)}},[n]);const c=i.useRef([]),p=i.useCallback((e,w)=>{const d=typeof e=="function"?e(r()):{...r(),...e},h=o(d,y(t)),S=`${window.location.pathname}${h.length?"?":""}${h}${window.location.hash}`,$=`${window.location.pathname}${window.location.search}${window.location.hash}`;if(S===$)return;n(d);const{replace:g,...k}=w||{};c.current.push([g?"replace":"push",S,k]),clearTimeout(m.current),queueMicrotask(()=>{c.current.length&&(m.current=setTimeout(()=>{const f=c.current.at(-1);c.current=[],a[f[0]](f[1],f[2])},R))})},[a,o,r]),E=i.useCallback(e=>{n(t),p(t,e)},[p,n]);return{updateState:n,updateUrl:p,state:l,reset:E,getState:r}}function y(t){const a=Object.keys(t),u=window.location.search,s=new URLSearchParams(u),o=new URLSearchParams;return s.forEach((l,r)=>!a.includes(r)&&o.set(r,l)),o}const U="popstate";export{b as useUrlStateBase};
+import u from"react";import{TIMEOUT as L}from"../constants/constants.mjs";import{useInsertionEffect as T}from"../useInsertionEffect.mjs";import{useSharedState as v}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as y}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as R}from"../utils.mjs";function b(t,a,l){const{parse:s,stringify:o}=y(t),{state:c,getState:n,setState:r}=v(t,()=>l?.({parse:s})||t),m=u.useRef(void 0);T(()=>{const e=()=>{const f=s(R(t));r(f)};return window.addEventListener(U,e),()=>{window.removeEventListener(U,e),clearTimeout(m.current)}},[r]);const i=u.useRef([]),p=u.useCallback((e,f)=>{const d=typeof e=="function"?e(n()):{...n(),...e},h=o(d,C(t)),S=`${window.location.pathname}${h.length?"?":""}${h}${window.location.hash}`,g=`${window.location.pathname}${window.location.search}${window.location.hash}`;if(S===g)return;r(d);const{replace:k,...E}=f||{};i.current.push([k?"replace":"push",S,E]),clearTimeout(m.current),queueMicrotask(()=>{i.current.length&&(m.current=setTimeout(()=>{const w=i.current.at(-1);i.current=[],a[w[0]](w[1],w[2])},L))})},[a,o,n]),$=u.useCallback(e=>{r(t),p(t,e)},[p,r]);return{updateState:r,updateUrl:p,state:c,reset:$,getState:n}}function C(t){const a=Object.keys(t),l=window.location.search,s=new URLSearchParams(l),o=new URLSearchParams;for(const[c,n]of s)!a.includes(c)&&o.set(c,n);return o}const U="popstate";export{b as useUrlStateBase};

package/dist/utils.mjs

@@ -1 +1 @@
-const c=n=>{const t=typeof n,r=n===null,o=Array.isArray(n),e=n instanceof Date;return r&&"null"||e&&"date"||o&&"array"||!r&&!e&&!o&&t==="object"&&"object"||t},i=typeof window>"u",l=n=>new URLSearchParams(typeof n=="string"?u(n):n?.toString?.()||""),u=n=>n.split("?")?.[1]||n||"",f=(n,t)=>JSON.stringify(n)===JSON.stringify(t);function w(n){const t=new URLSearchParams;return s(n,[...new URLSearchParams(window.location.search).entries()]).forEach(([r,o])=>t.set(r,o)),t.toString()}function p(n,t){return Object.fromEntries(s(n,Object.entries(t||{})))}function s(n,t){const r=Object.keys(n),o=[];for(let e=0;e<t.length;e++)r.includes(t[e]?.[0])&&o.push([t[e][0].replace(/\+/g," "),t[e][1]]);return o}function y(n,t){const r=Object.assign({},n);return Object.entries(n).forEach(([o])=>{const e=o,a=t[e]!==void 0;r[e]=a?t[e]:n[e]}),r}const g={push:n=>{window&&window.history.pushState(null,"",n)},replace:n=>{window&&window.history.replaceState(null,"",n)}},h=/apple/i.test(!i&&navigator?.userAgent||"");export{y as assignValue,s as filterUnknown,p as filterUnknownParams,w as filterUnknownParamsClient,l as getParams,f as isEqual,i as isSSR,h as isSafari,g as routerHistory,c as typeOf};
+const c=n=>{const t=typeof n,e=n===null,o=Array.isArray(n),r=n instanceof Date;return e&&"null"||r&&"date"||o&&"array"||!e&&!r&&!o&&t==="object"&&"object"||t},i=typeof window>"u",l=n=>new URLSearchParams(typeof n=="string"?u(n):n?.toString?.()||""),u=n=>n.split("?")?.[1]||n||"",f=(n,t)=>JSON.stringify(n)===JSON.stringify(t);function w(n){const t=new URLSearchParams,e=s(n,[...new URLSearchParams(window.location.search).entries()]);for(const[o,r]of e)t.set(o,r);return t.toString()}function p(n,t){return Object.fromEntries(s(n,Object.entries(t||{})))}function s(n,t){const e=Object.keys(n),o=[];for(let r=0;r<t.length;r++)e.includes(t[r]?.[0])&&o.push([t[r][0].replace(/\+/g," "),t[r][1]]);return o}function y(n,t){const e=Object.assign({},n);for(const[o]of Object.entries(n)){const r=o,a=t[r]!==void 0;e[r]=a?t[r]:n[r]}return e}const g={push:n=>{window&&window.history.pushState(null,"",n)},replace:n=>{window&&window.history.replaceState(null,"",n)}},S=/apple/i.test(!i&&navigator?.userAgent||"");export{y as assignValue,s as filterUnknown,p as filterUnknownParams,w as filterUnknownParamsClient,l as getParams,f as isEqual,i as isSSR,S as isSafari,g as routerHistory,c as typeOf};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "4.1.10",
+  "version": "4.1.11",
   "description": "Store state in URL as in object, types and structure are preserved, with TS validation. Same API as React.useState, wthout any hasssle or boilerplate. Next.js@14-15 and react-router@6-7.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -355,6 +355,7 @@
     "babel-plugin-module-resolver": "^5.0.2",
     "chokidar": "^4.0.1",
     "commitizen": "^4.3.0",
+    "commitlint": "^19.8.0",
     "conventional-recommended-bump": "^10.0.0",
     "cross-env": "^7.0.3",
     "cz": "^1.8.2",