state-in-url 6.5.0 → 7.0.0

package/README.ru.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · Русский · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=ru source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=ru source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ nuqs — достойная библиотека: берите её, если х
       - [Пример](#пример)
     - [Hook useUrlState для React-Router](#hook-useurlstate-для-react-router)
       - [Пример](#пример-1)
-    - [Hook useUrlState для Astro](#hook-useurlstate-для-astro)
+    - [Hook useUrlState для React (без роутера)](#hook-useurlstate-для-react-без-роутера)
       - [Пример](#пример-2)
+    - [Hook useUrlState для Astro](#hook-useurlstate-для-astro)
+      - [Пример](#пример-3)
   - [Рецепты](#рецепты)
         - [Пользовательский hook для удобной работы со срезом состояния](#пользовательский-hook-для-удобной-работы-со-срезом-состояния)
         - [Со сложной формой состояния](#со-сложной-формой-состояния)
         - [Обновлять только состояние и синхронизировать с URL вручную](#обновлять-только-состояние-и-синхронизировать-с-url-вручную)
   - [Другие hook'и и вспомогательные функции](#другие-hookи-и-вспомогательные-функции)
-    - [Hook `useUrlStateBase` для других роутеров](#hook-useurlstatebase-для-других-роутеров)
+    - [Hook `useUrlStateBase` для другого роутера](#hook-useurlstatebase-для-другого-роутера)
     - [Hook `useSharedState` для React.js](#hook-usesharedstate-для-reactjs)
     - [Hook `useLinkProps` для React.js](#hook-uselinkprops-для-reactjs)
     - [Hook `useUrlEncode` для React.js](#hook-useurlencode-для-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [Пример кода](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState для React (без роутера)
+
+Для React-приложения без роутера — Vite, Create React App, виджет, встраиваемый в чужую страницу. Hook пишет URL через `window.history` и перечитывает его при переходах назад/вперёд и при любом другом `pushState`/`replaceState`. Все компоненты, использующие один и тот же объект состояния, разделяют его: ничего не нужно оборачивать и ничего не нужно передавать через props.
+
+[Документация по API](packages/urlstate/react/useUrlState)
+
+#### Пример
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` — это тот же hook; ниже он описан отдельно, потому что islands дополнительно принимают `searchParams` как prop.
+
 ### Hook useUrlState для Astro
 
 Для React-островов. У Astro по умолчанию нет клиентского роутера, поэтому hook записывает URL через `window.history` и считывает его обратно при переходах назад/вперёд и при любом другом `pushState`/`replaceState`, включая собственный `<ClientRouter />` Astro. Острова на странице используют общее состояние, и оборачивать их ни во что не нужно.
@@ -818,9 +853,39 @@ const tags = [
 
 ## Другие hook'и и вспомогательные функции
 
-### Hook `useUrlStateBase` для других роутеров
+### Hook `useUrlStateBase` для другого роутера
+
+Используйте его, чтобы собрать собственный `useUrlState` для роутера, для которого пакет не поставляет точку входа, например TanStack Router. Передайте любой мемоизированный объект с методами `push(url)` и `replace(url)`.
+
+Если роутера **нет вообще**, это не нужно — возьмите [`state-in-url/react`](#hook-useurlstate-для-react-без-роутера): это тот же hook, уже подключённый к `window.history`.
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+Два отличия от `useUrlState`:
+
+- Он возвращает `state`, `updateUrl`, `updateState`, а не `urlState`, `setUrl`, `setState`; при этом `updateUrl` по умолчанию делает push, а `setUrl` — replace.
+- Третий аргумент задаёт начальный state. Если его не передать, hook проигнорирует строку запроса, с которой была открыта страница, и присланная кем-то ссылка покажет значения по умолчанию.
 
-Hook'и для создания собственных hook'ов `useUrlState` с другими роутерами, например react-router или tanstack router.
+> [!NOTE]
+> `useUrlState` больше не экспортируется из корня пакета: каждый из них привязан к своему фреймворку, поэтому у каждого своя точка входа (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). В корне остаётся только то, что от фреймворка не зависит: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` и `encodeState`/`decodeState`.
 
 [Документация по API](packages/urlstate/useUrlStateBase)
 

package/README.vi.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · Tiếng Việt
-<!-- i18n:meta locale=vi source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=vi source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ Bản so sánh đầy đủ — cùng một tính năng trong cả hai, các l
       - [Ví dụ](#ví-dụ)
     - [Hook useUrlState cho React-Router](#hook-useurlstate-cho-react-router)
       - [Ví dụ](#ví-dụ-1)
-    - [Hook useUrlState cho Astro](#hook-useurlstate-cho-astro)
+    - [Hook useUrlState cho React (không có router)](#hook-useurlstate-cho-react-không-có-router)
       - [Ví dụ](#ví-dụ-2)
+    - [Hook useUrlState cho Astro](#hook-useurlstate-cho-astro)
+      - [Ví dụ](#ví-dụ-3)
   - [Công thức nấu ăn](#công-thức-nấu-ăn)
         - [Hook tùy chỉnh để làm việc thuận tiện với một phần của state](#hook-tùy-chỉnh-để-làm-việc-thuận-tiện-với-một-phần-của-state)
         - [Với hình dạng state phức tạp](#với-hình-dạng-state-phức-tạp)
         - [Chỉ cập nhật state và đồng bộ với URL thủ công](#chỉ-cập-nhật-state-và-đồng-bộ-với-url-thủ-công)
   - [Các hook và helper khác](#các-hook-và-helper-khác)
-    - [Hook `useUrlStateBase` cho các router khác](#hook-useurlstatebase-cho-các-router-khác)
+    - [Hook `useUrlStateBase` cho router khác](#hook-useurlstatebase-cho-router-khác)
     - [Hook `useSharedState` cho React.js](#hook-usesharedstate-cho-reactjs)
     - [Hook `useLinkProps` cho React.js](#hook-uselinkprops-cho-reactjs)
     - [Hook `useUrlEncode` cho React.js](#hook-useurlencode-cho-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [Ví dụ code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState cho React (không có router)
+
+Dành cho ứng dụng React không có router — Vite, Create React App, hoặc một widget được gắn vào trang mà bạn không kiểm soát. Hook ghi URL bằng `window.history` và đọc lại khi người dùng đi lui/tới cũng như khi có bất kỳ `pushState`/`replaceState` nào khác. Mọi component dùng chung một object state đều chia sẻ state đó, không cần bọc gì và không cần truyền qua props.
+
+[Tài liệu API](packages/urlstate/react/useUrlState)
+
+#### Ví dụ
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` chính là hook này; nó được nói riêng ở phần dưới vì islands còn nhận `searchParams` dưới dạng prop.
+
 ### Hook useUrlState cho Astro
 
 Dành cho React island. Astro mặc định không có router phía client, nên hook ghi URL bằng `window.history` và đọc lại nó khi back/forward cũng như khi có bất kỳ lời gọi `pushState`/`replaceState` nào khác, kể cả `<ClientRouter />` của chính Astro. Các island trên cùng một trang chia sẻ state mà không cần bọc chúng trong bất cứ thứ gì.
@@ -818,9 +853,39 @@ const tags = [
 
 ## Các hook và helper khác
 
-### Hook `useUrlStateBase` cho các router khác
+### Hook `useUrlStateBase` cho router khác
+
+Dùng nó để tự dựng `useUrlState` cho một router mà gói này không cung cấp điểm vào, ví dụ TanStack Router. Hãy truyền một object đã được ghi nhớ (memoized) có `push(url)` và `replace(url)`.
+
+Nếu **hoàn toàn không có router**, bạn không cần tới nó — hãy dùng [`state-in-url/react`](#hook-useurlstate-cho-react-không-có-router), vốn chính là hook này đã nối sẵn với `window.history`.
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+Hai điểm khác so với `useUrlState`:
+
+- Nó trả về `state`, `updateUrl`, `updateState` chứ không phải `urlState`, `setUrl`, `setState`; và `updateUrl` mặc định là push, còn `setUrl` mặc định là replace.
+- Tham số thứ ba nạp state ban đầu. Bỏ nó đi thì hook sẽ bỏ qua chuỗi truy vấn lúc trang được tải, nên một liên kết được chia sẻ sẽ mở ra với giá trị mặc định.
 
-Hook để tạo các hook `useUrlState` của riêng bạn với các router khác, ví dụ react-router hoặc tanstack router.
+> [!NOTE]
+> `useUrlState` không còn được export từ gốc của gói: mỗi `useUrlState` đều gắn với một framework, nên mỗi cái nằm ở điểm vào riêng (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). Điểm vào gốc chỉ giữ những gì không phụ thuộc framework: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` và `encodeState`/`decodeState`.
 
 [Tài liệu API](packages/urlstate/useUrlStateBase)
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · 简体中文 · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=zh-CN source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=zh-CN source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ nuqs 也是一个不错的库——如果你希望每个值都是一条可读的
       - [示例](#示例)
     - [用于 React-Router 的 useUrlState hook](#用于-react-router-的-useurlstate-hook)
       - [示例](#示例-1)
-    - [用于 Astro 的 useUrlState hook](#用于-astro-的-useurlstate-hook)
+    - [用于 React 的 useUrlState hook（无路由器）](#用于-react-的-useurlstate-hook无路由器)
       - [示例](#示例-2)
+    - [用于 Astro 的 useUrlState hook](#用于-astro-的-useurlstate-hook)
+      - [示例](#示例-3)
   - [实用技巧](#实用技巧)
         - [自定义 hook 以便捷地处理状态切片](#自定义-hook-以便捷地处理状态切片)
         - [使用复杂状态形状](#使用复杂状态形状)
         - [仅更新状态并手动同步到 URL](#仅更新状态并手动同步到-url)
   - [其他 hooks 和辅助函数](#其他-hooks-和辅助函数)
-    - [`useUrlStateBase` hook 用于其他路由器](#useurlstatebase-hook-用于其他路由器)
+    - [用于其他路由器的 `useUrlStateBase` hook](#用于其他路由器的-useurlstatebase-hook)
     - [`useSharedState` hook 用于 React.js](#usesharedstate-hook-用于-reactjs)
     - [`useLinkProps` hook 用于 React.js](#uselinkprops-hook-用于-reactjs)
     - [`useUrlEncode` hook 用于 React.js](#useurlencode-hook-用于-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [示例代码](packages/example-react-router6/src/Form-for-test.tsx)
 
+### 用于 React 的 useUrlState hook（无路由器）
+
+适用于没有路由器的 React 应用 —— Vite、Create React App，或挂载到你无法控制的页面中的小部件。该 hook 通过 `window.history` 写入 URL，并在前进/后退以及任何其他 `pushState`/`replaceState` 时读回。使用同一个 state 对象的每个组件都共享该状态，既不需要包裹组件，也不需要通过 props 传递。
+
+[API 文档](packages/urlstate/react/useUrlState)
+
+#### 示例
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` 就是这个 hook；之所以在下文单独说明，是因为 islands 还会把 `searchParams` 作为 prop 传入。
+
 ### 用于 Astro 的 useUrlState hook
 
 适用于 React 岛屿（islands）。Astro 默认没有客户端路由器，因此该 hook 通过 `window.history` 写入 URL，并在浏览器前进/后退以及任何其他 `pushState`/`replaceState` 调用时将其读回，Astro 自带的 `<ClientRouter />` 也包括在内。同一页面上的岛屿共享状态，无需用任何东西将它们包裹起来。
@@ -818,9 +853,39 @@ const tags = [
 
 ## 其他 hooks 和辅助函数
 
-### `useUrlStateBase` hook 用于其他路由器
+### 用于其他路由器的 `useUrlStateBase` hook
+
+用它为本包未提供入口的路由器（例如 TanStack Router）构建自己的 `useUrlState`。传入任意带有 `push(url)` 和 `replace(url)` 的记忆化对象即可。
+
+如果**完全没有路由器**，则不需要它 —— 请使用 [`state-in-url/react`](#用于-react-的-useurlstate-hook无路由器)，它就是已经接好 `window.history` 的这个 hook。
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+与 `useUrlState` 有两点不同：
+
+- 它返回 `state`、`updateUrl`、`updateState`，而不是 `urlState`、`setUrl`、`setState`；并且 `updateUrl` 默认为 push，而 `setUrl` 默认为 replace。
+- 第三个参数用于填充初始 state。省略它，hook 就会忽略页面加载时 URL 中的查询字符串，于是分享出去的链接打开后只显示默认值。
 
-用于使用其他路由器(例如 react-router 或 tanstack router)创建自己的 `useUrlState` hooks 的 Hooks。
+> [!NOTE]
+> `useUrlState` 不再从包的根入口导出 —— 每个 `useUrlState` 都与某个框架绑定，因此各自位于独立入口（`state-in-url/next`、`/react`、`/react-router`、`/react-router6`、`/remix`、`/astro`）。根入口只保留与框架无关的部分：`useSharedState`、`useUrlEncode`、`useUrlStateBase`、`useLinkProps`、`encode`/`decode` 和 `encodeState`/`decodeState`。
 
 [API 文档](packages/urlstate/useUrlStateBase)
 

package/dist/astro/index.js

@@ -1 +1 @@
-"use strict";var e=require("./useUrlState/useUrlState.js");exports.useUrlState=e.useUrlState;
+"use strict";var e=require("../react/useUrlState/useUrlState.js");exports.useUrlState=e.useUrlState;

package/dist/astro/index.mjs

@@ -1 +1 @@
-import{useUrlState as t}from"./useUrlState/useUrlState.mjs";export{t as useUrlState};
+import{useUrlState as t}from"../react/useUrlState/useUrlState.mjs";export{t as useUrlState};

package/dist/astro/useUrlState/index.js

@@ -1 +1 @@
-"use strict";var e=require("./useUrlState.js");exports.useUrlState=e.useUrlState;
+"use strict";var e=require("../../react/useUrlState/useUrlState.js");exports.useUrlState=e.useUrlState;

package/dist/astro/useUrlState/index.mjs

@@ -1 +1 @@
-import{useUrlState as t}from"./useUrlState.mjs";export{t as useUrlState};
+import{useUrlState as t}from"../../react/useUrlState/useUrlState.mjs";export{t as useUrlState};

package/dist/astro/useUrlState/useUrlState.d.ts

@@ -1,85 +1 @@
-import { type JSONCompatible } from '../../utils';
-/**
- * Astro hook, for React islands. Returns `urlState`, `setState`, and `setUrl` functions
- *
- * Astro has no client-side router by default, so the URL is written with
- * `window.history` and read back on back/forward, on this hook's own writes,
- * and on any other `pushState`/`replaceState`, `<ClientRouter />` included.
- * Islands on one page share the state.
- *
- * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
- * @param {Object} params - Object with other parameters
- * @param {boolean} params.replace replace URL or push, default `true`
- * @param {?object} params.searchParams `Object.fromEntries(Astro.url.searchParams)`, passed as an island prop so the server render matches the URL
- * @returns {Object} [result] State and callbacks
- * @returns {Object} [result.urlState] - current state object
- * @returns {Function} [result.setUrl] - function to update state and url
- * @returns {Function} [result.setState] - function to update state only
- * @returns {Function} [result.reset] - function to reset state and url to default
- *
- * * Example:
- * ```ts
- * export const form = { name: '', age: 0 };
- * // island: <Form client:load searchParams={Object.fromEntries(Astro.url.searchParams)} />
- * const { urlState, setState, setUrl, reset } = useUrlState(form, { searchParams });
- *
- * setState({ name: 'test' });
- * setUrl({ name: 'test' }, { replace: false });
- * setUrl(curr => ({ ...curr, name: 'test' }));
- * // RESET state and url
- * setUrl((_curr, initialState) => initialState);
- * // Or
- * reset();
- * reset({ replace: false });
- *  ```
- *
- *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/astro/useUrlState}
- */
-export declare function useUrlState<T extends JSONCompatible>(defaultState: T, params?: Params): {
-    /**
-     * State object. Don't mutate directly, use `setState` or `setUrl`
-     */
-    urlState: T;
-    /**
-     * * Example:
-     * ```ts
-     * setState({ name: 'test' });
-     * // or
-     * setState(curr => ({ ...curr, name: 'test' }) );
-     *  ```
-     *
-     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/astro/useUrlState#setstate}
-     */
-    setState: (value: Partial<T> | ((currState: T, initial: T) => T)) => void;
-    /**
-     * * Example:
-     * ```ts
-     * setUrl({ name: 'test' });
-     * // or
-     * setUrl((curr) => ({ ...curr, name: 'test' }), { replace: false } );
-     *  * Reset
-     *  setUrl((_curr, initialState) => initialState, { replace: false } );
-     *  ```
-     *
-     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/astro/useUrlState#seturl}
-     */
-    setUrl: (value?: Partial<T> | ((currState: T, initialState: T) => T), options?: Options) => void;
-    /**
-     * * Example:
-     * ```ts
-     * reset();
-     * // or
-     * reset({ replace: false })
-     *  ```
-     *
-     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/astro/useUrlState#reset}
-     */
-    reset: (options?: Options) => void;
-};
-export type Options = {
-    replace?: boolean;
-};
-export type Params = {
-    searchParams?: object;
-    replace?: boolean;
-};
+export * from '../../react/useUrlState';

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 import { decode, encode } from './encoder';
 import { decodeState, encodeState } from './encodeState';
-import { useUrlState } from './next';
 import { useLinkProps } from './useLinkProps';
 import { useSharedState } from './useSharedState';
 import { useUrlEncode } from './useUrlEncode';
 import { useUrlStateBase } from './useUrlStateBase';
 import { isSSR, type JSONCompatible, type Type, typeOf } from './utils';
-export { decode, decodeState, encode, encodeState, isSSR, typeOf, useLinkProps, useSharedState, useUrlEncode, useUrlState, useUrlStateBase, };
+export { decode, decodeState, encode, encodeState, isSSR, typeOf, useLinkProps, useSharedState, useUrlEncode, useUrlStateBase, };
 export type { JSONCompatible, Type };

package/dist/index.js

@@ -1 +1 @@
-"use strict";var e=require("./encoder/encoder.js");var r=require("./encodeState/encodeState.js");var a=require("./next/useUrlState/useUrlState.js");var s=require("./useLinkProps/useLinkProps.js");var u=require("./useSharedState/useSharedState.js");var S=require("./useUrlEncode/useUrlEncode.js");var d=require("./useUrlStateBase/useUrlStateBase.js");var t=require("./utils.js");exports.decode=e.decode;exports.encode=e.encode;exports.decodeState=r.decodeState;exports.encodeState=r.encodeState;exports.useUrlState=a.useUrlState;exports.useLinkProps=s.useLinkProps;exports.useSharedState=u.useSharedState;exports.useUrlEncode=S.useUrlEncode;exports.useUrlStateBase=d.useUrlStateBase;exports.isSSR=t.isSSR;exports.typeOf=t.typeOf;
+"use strict";var e=require("./encoder/encoder.js");var r=require("./encodeState/encodeState.js");var a=require("./useLinkProps/useLinkProps.js");var s=require("./useSharedState/useSharedState.js");var u=require("./useUrlEncode/useUrlEncode.js");var d=require("./useUrlStateBase/useUrlStateBase.js");var t=require("./utils.js");exports.decode=e.decode;exports.encode=e.encode;exports.decodeState=r.decodeState;exports.encodeState=r.encodeState;exports.useLinkProps=a.useLinkProps;exports.useSharedState=s.useSharedState;exports.useUrlEncode=u.useUrlEncode;exports.useUrlStateBase=d.useUrlStateBase;exports.isSSR=t.isSSR;exports.typeOf=t.typeOf;

package/dist/index.mjs

@@ -1 +1 @@
-import{decode as r,encode as t}from"./encoder/encoder.mjs";import{decodeState as f,encodeState as d}from"./encodeState/encodeState.mjs";import{useUrlState as s}from"./next/useUrlState/useUrlState.mjs";import{useLinkProps as S}from"./useLinkProps/useLinkProps.mjs";import{useSharedState as c}from"./useSharedState/useSharedState.mjs";import{useUrlEncode as n}from"./useUrlEncode/useUrlEncode.mjs";import{useUrlStateBase as U}from"./useUrlStateBase/useUrlStateBase.mjs";import{isSSR as h,typeOf as k}from"./utils.mjs";export{r as decode,f as decodeState,t as encode,d as encodeState,h as isSSR,k as typeOf,S as useLinkProps,c as useSharedState,n as useUrlEncode,s as useUrlState,U as useUrlStateBase};
+import{decode as r,encode as t}from"./encoder/encoder.mjs";import{decodeState as d,encodeState as f}from"./encodeState/encodeState.mjs";import{useLinkProps as s}from"./useLinkProps/useLinkProps.mjs";import{useSharedState as S}from"./useSharedState/useSharedState.mjs";import{useUrlEncode as c}from"./useUrlEncode/useUrlEncode.mjs";import{useUrlStateBase as u}from"./useUrlStateBase/useUrlStateBase.mjs";import{isSSR as l,typeOf as U}from"./utils.mjs";export{r as decode,d as decodeState,t as encode,f as encodeState,l as isSSR,U as typeOf,s as useLinkProps,S as useSharedState,c as useUrlEncode,u as useUrlStateBase};

package/dist/next/useUrlState/useUrlState.mjs

@@ -1 +1 @@
-import r from"react";import{useRouter as y}from"next/navigation";import{parseSPObj as p}from"../../parseSPObj.mjs";import{useUrlStateBase as C}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as m,filterUnknownParams as f,getParams as v,subscribeToUrl as H,isSSR as M,filterUnknownParamsClient as j,getSearch as S}from"../../utils.mjs";function w(s,t){const c=r.useMemo(()=>t?.useHistory===void 0?true:!!t?.useHistory,[]);const a=y();const U=r.useMemo(()=>({push:(...e)=>{if(c){m.push(...e)}else{a.push(...e)}},replace:(...e)=>{if(c){m.replace(...e)}else{a.replace(...e)}}}),[a]);const{state:b,updateState:u,updateUrl:n,reset:i,getState:d,pendingUrlUpdate:h}=C(s,U,({parse:e})=>{return M?p(f(s,t?.searchParams),s):e(j(s,t?.searchParams||S()))});const l=r.useCallback(()=>{if(h())return;u(f(s,p(Object.fromEntries(v(S()).entries()),s)))},[]);r.useEffect(()=>{l();return H(l)},[l]);const o=r.useMemo(()=>{const e={...E};if(t?.scroll!==void 0)e.scroll=t.scroll;if(t?.replace!==void 0)e.replace=t.replace;return e},[t?.scroll,t?.replace]);const P=r.useCallback((e,k)=>n(e,{...o,...k}),[n,o]);const g=r.useCallback(e=>{i({...o,...e})},[i,o]);return{setState:u,setUrl:P,urlState:b,reset:g,getState:d}}const E={replace:true,scroll:false};export{w as useUrlState};
+import r from"react";import{useRouter as y}from"next/navigation";import{parseSPObj as p}from"../../parseSPObj.mjs";import{useUrlStateBase as C}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as m,isSSR as v,filterUnknownParams as f,filterUnknownParamsClient as H,getSearch as S,getParams as M,subscribeToUrl as j}from"../../utils.mjs";function w(s,t){const c=r.useMemo(()=>t?.useHistory===void 0?true:!!t?.useHistory,[]);const a=y();const U=r.useMemo(()=>({push:(...e)=>{if(c){m.push(...e)}else{a.push(...e)}},replace:(...e)=>{if(c){m.replace(...e)}else{a.replace(...e)}}}),[a]);const{state:b,updateState:u,updateUrl:n,reset:i,getState:d,pendingUrlUpdate:h}=C(s,U,({parse:e})=>{return v?p(f(s,t?.searchParams),s):e(H(s,t?.searchParams||S()))});const l=r.useCallback(()=>{if(h())return;u(f(s,p(Object.fromEntries(M(S()).entries()),s)))},[]);r.useEffect(()=>{l();return j(l)},[l]);const o=r.useMemo(()=>{const e={...E};if(t?.scroll!==void 0)e.scroll=t.scroll;if(t?.replace!==void 0)e.replace=t.replace;return e},[t?.scroll,t?.replace]);const P=r.useCallback((e,k)=>n(e,{...o,...k}),[n,o]);const g=r.useCallback(e=>{i({...o,...e})},[i,o]);return{setState:u,setUrl:P,urlState:b,reset:g,getState:d}}const E={replace:true,scroll:false};export{w as useUrlState};

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "6.5.0",
+  "version": "7.0.0",
   "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-16, react-router@6-7, remix@2, and Astro.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -43,6 +43,11 @@
       "types": "./dist/next/index.d.ts",
       "default": "./dist/next/index.mjs"
     },
+    "./react": {
+      "require": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.mjs"
+    },
     "./react-router6": {
       "require": "./dist/react-router6/index.js",
       "types": "./dist/react-router6/index.d.ts",

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export { useUrlState } from './useUrlState';

package/dist/react/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("./useUrlState/useUrlState.js");exports.useUrlState=e.useUrlState;

package/dist/react/index.mjs

@@ -0,0 +1 @@
+import{useUrlState as t}from"./useUrlState/useUrlState.mjs";export{t as useUrlState};

package/dist/react/useUrlState/index.d.ts

@@ -0,0 +1 @@
+export * from './useUrlState';

package/dist/react/useUrlState/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("./useUrlState.js");exports.useUrlState=e.useUrlState;

package/dist/react/useUrlState/index.mjs

@@ -0,0 +1 @@
+import{useUrlState as t}from"./useUrlState.mjs";export{t as useUrlState};

package/dist/react/useUrlState/useUrlState.d.ts

@@ -0,0 +1,86 @@
+import { type JSONCompatible } from '../../utils';
+/**
+ * Hook for React with no router — Vite, Create React App, an Astro island.
+ * Returns `urlState`, `setState`, and `setUrl` functions
+ *
+ * The URL is written with `window.history` and read back on back/forward, on
+ * this hook's own writes, and on any other `pushState`/`replaceState`, Astro's
+ * `<ClientRouter />` included. Every component sharing the default state object
+ * shares the state, islands on one page included.
+ *
+ * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
+ * @param {Object} params - Object with other parameters
+ * @param {boolean} params.replace replace URL or push, default `true`
+ * @param {?object} params.searchParams Query params from a server render, so it matches the URL. Astro islands pass `Object.fromEntries(Astro.url.searchParams)` as a prop; a client-only app needs nothing here
+ * @returns {Object} [result] State and callbacks
+ * @returns {Object} [result.urlState] - current state object
+ * @returns {Function} [result.setUrl] - function to update state and url
+ * @returns {Function} [result.setState] - function to update state only
+ * @returns {Function} [result.reset] - function to reset state and url to default
+ *
+ * * Example:
+ * ```ts
+ * export const form = { name: '', age: 0 };
+ * // Astro island: <Form client:load searchParams={Object.fromEntries(Astro.url.searchParams)} />
+ * const { urlState, setState, setUrl, reset } = useUrlState(form, { searchParams });
+ *
+ * setState({ name: 'test' });
+ * setUrl({ name: 'test' }, { replace: false });
+ * setUrl(curr => ({ ...curr, name: 'test' }));
+ * // RESET state and url
+ * setUrl((_curr, initialState) => initialState);
+ * // Or
+ * reset();
+ * reset({ replace: false });
+ *  ```
+ *
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react/useUrlState}
+ */
+export declare function useUrlState<T extends JSONCompatible>(defaultState: T, params?: Params): {
+    /**
+     * State object. Don't mutate directly, use `setState` or `setUrl`
+     */
+    urlState: T;
+    /**
+     * * Example:
+     * ```ts
+     * setState({ name: 'test' });
+     * // or
+     * setState(curr => ({ ...curr, name: 'test' }) );
+     *  ```
+     *
+     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react/useUrlState#setstate}
+     */
+    setState: (value: Partial<T> | ((currState: T, initial: T) => T)) => void;
+    /**
+     * * Example:
+     * ```ts
+     * setUrl({ name: 'test' });
+     * // or
+     * setUrl((curr) => ({ ...curr, name: 'test' }), { replace: false } );
+     *  * Reset
+     *  setUrl((_curr, initialState) => initialState, { replace: false } );
+     *  ```
+     *
+     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react/useUrlState#seturl}
+     */
+    setUrl: (value?: Partial<T> | ((currState: T, initialState: T) => T), options?: Options) => void;
+    /**
+     * * Example:
+     * ```ts
+     * reset();
+     * // or
+     * reset({ replace: false })
+     *  ```
+     *
+     *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react/useUrlState#reset}
+     */
+    reset: (options?: Options) => void;
+};
+export type Options = {
+    replace?: boolean;
+};
+export type Params = {
+    searchParams?: object;
+    replace?: boolean;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "6.5.0",
+  "version": "7.0.0",
   "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-16, react-router@6-7, remix@2, and Astro.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -43,6 +43,11 @@
       "types": "./dist/next/index.d.ts",
       "default": "./dist/next/index.mjs"
     },
+    "./react": {
+      "require": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.mjs"
+    },
     "./react-router6": {
       "require": "./dist/react-router6/index.js",
       "types": "./dist/react-router6/index.d.ts",

package/skills/astro-setup/SKILL.md

@@ -18,7 +18,7 @@ sources:
 metadata:
   type: framework
   library: state-in-url
-  library_version: '6.5.0'
+  library_version: '7.0.0'
   framework: astro
 ---
 

package/skills/feature-state-hook/SKILL.md

@@ -16,7 +16,7 @@ sources:
 metadata:
   type: core
   library: state-in-url
-  library_version: '6.5.0'
+  library_version: '7.0.0'
 ---
 
 # state-in-url — Feature state hook

package/skills/form-library-integration/SKILL.md

@@ -15,7 +15,7 @@ sources:
 metadata:
   type: composition
   library: state-in-url
-  library_version: '6.5.0'
+  library_version: '7.0.0'
 ---
 
 This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.