state-in-url 6.5.0 → 7.0.0

package/README.es.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 · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=es source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=es source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ La comparación completa — la misma feature en ambas, otras alternativas (TanS
       - [Ejemplo](#ejemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Ejemplo](#ejemplo-1)
-    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+    - [Hook useUrlState para React (sin router)](#hook-useurlstate-para-react-sin-router)
       - [Ejemplo](#ejemplo-2)
+    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+      - [Ejemplo](#ejemplo-3)
   - [Recetas](#recetas)
         - [Hook personalizado para trabajar cómodamente con una porción del estado](#hook-personalizado-para-trabajar-cómodamente-con-una-porción-del-estado)
         - [Con una forma de estado compleja](#con-una-forma-de-estado-compleja)
         - [Actualizar solo el estado y sincronizarlo manualmente con la URL](#actualizar-solo-el-estado-y-sincronizarlo-manualmente-con-la-url)
   - [Otros hooks y helpers](#otros-hooks-y-helpers)
-    - [Hook `useUrlStateBase` para otros routers](#hook-useurlstatebase-para-otros-routers)
+    - [Hook `useUrlStateBase` para otro router](#hook-useurlstatebase-para-otro-router)
     - [Hook `useSharedState` para React.js](#hook-usesharedstate-para-reactjs)
     - [Hook `useLinkProps` para React.js](#hook-uselinkprops-para-reactjs)
     - [Hook `useUrlEncode` para React.js](#hook-useurlencode-para-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [Ejemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState para React (sin router)
+
+Para una aplicación React sin router: Vite, Create React App, o un widget que se monta en una página que no controlas. El hook escribe la URL con `window.history` y la vuelve a leer al navegar atrás y adelante y ante cualquier otro `pushState`/`replaceState`. Todos los componentes que usan el mismo objeto de estado lo comparten, sin nada que envolver y sin nada que pasar por props.
+
+[Documentación de la API](packages/urlstate/react/useUrlState)
+
+#### Ejemplo
+
+```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` es este mismo hook; se documenta aparte más abajo porque las islands además reciben `searchParams` como prop.
+
 ### Hook useUrlState para Astro
 
 Para islas de React. Astro no tiene router del lado del cliente por defecto, así que el hook escribe la URL con `window.history` y la vuelve a leer al navegar atrás/adelante y en cualquier otro `pushState`/`replaceState`, incluido el propio `<ClientRouter />` de Astro. Las islas de una página comparten el estado, sin nada que las envuelva.
@@ -818,9 +853,39 @@ Sincronizar el estado en `onBlur` estará más alineado con el uso en el mundo r
 
 ## Otros hooks y helpers
 
-### Hook `useUrlStateBase` para otros routers
+### Hook `useUrlStateBase` para otro router
+
+Úsalo para construir tu propio `useUrlState` para un router del que este paquete no publica un punto de entrada, por ejemplo TanStack Router. Pasa cualquier objeto memoizado con `push(url)` y `replace(url)`.
+
+Si **no hay router alguno** no lo necesitas: usa [`state-in-url/react`](#hook-useurlstate-para-react-sin-router), que es este mismo hook ya conectado a `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));
+}
+```
+
+Dos diferencias respecto a `useUrlState`:
+
+- Devuelve `state`, `updateUrl` y `updateState`, no `urlState`, `setUrl` ni `setState`; además `updateUrl` hace push por defecto, mientras que `setUrl` hace replace.
+- El tercer argumento define el state inicial. Si lo omites, el hook ignora la cadena de consulta con la que se cargó la página, así que un enlace compartido se abre con los valores por defecto.
 
-Hooks para crear tus propios hooks `useUrlState` con otros routers, p. ej. react-router o tanstack router.
+> [!NOTE]
+> `useUrlState` ya no se exporta desde la raíz del paquete: cada uno está atado a un framework, así que cada uno vive en su propio punto de entrada (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). La raíz solo conserva lo que es independiente del framework: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` y `encodeState`/`decodeState`.
 
 [Documentación de la API](packages/urlstate/useUrlStateBase)
 

package/README.fr.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 · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=fr source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=fr source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ La comparaison complète — la même fonctionnalité dans les deux, d’autres
       - [Exemple](#exemple)
     - [Hook useUrlState pour React-Router](#hook-useurlstate-pour-react-router)
       - [Exemple](#exemple-1)
-    - [Hook useUrlState pour Astro](#hook-useurlstate-pour-astro)
+    - [Hook useUrlState pour React (sans routeur)](#hook-useurlstate-pour-react-sans-routeur)
       - [Exemple](#exemple-2)
+    - [Hook useUrlState pour Astro](#hook-useurlstate-pour-astro)
+      - [Exemple](#exemple-3)
   - [Recettes](#recettes)
         - [Hook personnalisé pour travailler confortablement avec une tranche d'état](#hook-personnalisé-pour-travailler-confortablement-avec-une-tranche-détat)
         - [Avec une forme d'état complexe](#avec-une-forme-détat-complexe)
         - [Mettre à jour l'état seul et le synchroniser manuellement avec l'URL](#mettre-à-jour-létat-seul-et-le-synchroniser-manuellement-avec-lurl)
   - [Autres hooks et helpers](#autres-hooks-et-helpers)
-    - [Hook `useUrlStateBase` pour d'autres routeurs](#hook-useurlstatebase-pour-dautres-routeurs)
+    - [Hook `useUrlStateBase` pour un autre routeur](#hook-useurlstatebase-pour-un-autre-routeur)
     - [Hook `useSharedState` pour React.js](#hook-usesharedstate-pour-reactjs)
     - [Hook `useLinkProps` pour React.js](#hook-uselinkprops-pour-reactjs)
     - [Hook `useUrlEncode` pour React.js](#hook-useurlencode-pour-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [Exemple de code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState pour React (sans routeur)
+
+Pour une application React sans routeur : Vite, Create React App, ou un widget monté dans une page que vous ne contrôlez pas. Le hook écrit l'URL via `window.history` et la relit lors des retours et avances dans l'historique ainsi qu'à chaque autre `pushState`/`replaceState`. Tous les composants qui utilisent le même objet d'état le partagent, sans rien à englober ni rien à faire transiter par les props.
+
+[Documentation de l'API](packages/urlstate/react/useUrlState)
+
+#### Exemple
+
+```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` est ce même hook ; il est documenté séparément plus bas parce que les îlots reçoivent en plus `searchParams` sous forme de prop.
+
 ### Hook useUrlState pour Astro
 
 Pour les îlots React. Astro n'a pas de routeur côté client par défaut, donc le hook écrit l'URL avec `window.history` et la relit lors des navigations précédent/suivant et lors de tout autre `pushState`/`replaceState`, y compris le `<ClientRouter />` d'Astro. Les îlots d'une page partagent l'état, sans avoir à les envelopper dans quoi que ce soit.
@@ -818,9 +853,39 @@ Synchroniser l'état sur `onBlur` sera plus conforme à l'usage réel.
 
 ## Autres hooks et helpers
 
-### Hook `useUrlStateBase` pour d'autres routeurs
+### Hook `useUrlStateBase` pour un autre routeur
+
+Utilisez-le pour construire votre propre `useUrlState` destiné à un routeur pour lequel ce paquet ne publie pas de point d'entrée, par exemple TanStack Router. Passez n'importe quel objet mémoïsé possédant `push(url)` et `replace(url)`.
+
+S'il n'y a **aucun routeur**, vous n'en avez pas besoin : utilisez [`state-in-url/react`](#hook-useurlstate-pour-react-sans-routeur), qui est ce même hook déjà relié à `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));
+}
+```
+
+Deux différences avec `useUrlState` :
+
+- Il renvoie `state`, `updateUrl`, `updateState`, et non `urlState`, `setUrl`, `setState` ; de plus `updateUrl` fait un push par défaut, là où `setUrl` fait un replace.
+- Le troisième argument fournit le state initial. Si vous l'omettez, le hook ignore la chaîne de requête avec laquelle la page a été chargée, et un lien partagé s'ouvre donc sur les valeurs par défaut.
 
-Hooks pour créer vos propres hooks `useUrlState` avec d'autres routeurs, par exemple react-router ou tanstack router.
+> [!NOTE]
+> `useUrlState` n'est plus exporté depuis la racine du paquet : chacun est lié à un framework, et chacun vit donc derrière son propre point d'entrée (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). La racine ne conserve que ce qui est indépendant du framework : `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` et `encodeState`/`decodeState`.
 
 [Documentation de l'API](packages/urlstate/useUrlStateBase)
 

package/README.ja.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.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=ja source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=ja source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,8 +150,10 @@ nuqs も優れたライブラリです。値ごとに読みやすいクエリパ
       - [例](#例)
     - [React-Router 向け useUrlState フック](#react-router-向け-useurlstate-フック)
       - [例](#例-1)
-    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+    - [React 向け useUrlState フック（ルーターなし）](#react-向け-useurlstate-フックルーターなし)
       - [例](#例-2)
+    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+      - [例](#例-3)
   - [レシピ](#レシピ)
         - [状態の一部を便利に扱うカスタムフック](#状態の一部を便利に扱うカスタムフック)
         - [複雑な状態の形を使用](#複雑な状態の形を使用)
@@ -540,6 +542,39 @@ const tags = [
 
 [サンプルコード](packages/example-react-router6/src/Form-for-test.tsx)
 
+### React 向け useUrlState フック（ルーターなし）
+
+ルーターを持たない React アプリ向けです。Vite、Create React App、あるいは自分では管理できないページに埋め込むウィジェットなどが対象です。このフックは `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` は同じフックです。islands では `searchParams` を prop として受け取るため、下で別に説明しています。
+
 ### Astro 向け useUrlState フック
 
 React アイランド向けです。Astro にはデフォルトでクライアントサイドルーターがないため、このフックは `window.history` で URL を書き込み、戻る/進む操作時およびその他あらゆる `pushState`/`replaceState` の際（Astro 自身の `<ClientRouter />` を含む）に URL を読み戻します。ページ上のアイランドは状態を共有し、それらをラップするものは何も必要ありません。
@@ -820,7 +855,37 @@ const tags = [
 
 ### 他のルーター向け `useUrlStateBase` フック
 
-react-router や tanstack router など、他のルーターで独自の `useUrlState` フックを作成するためのフックです。
+本パッケージがエントリーポイントを用意していないルーター（例: TanStack Router）向けに、自前の `useUrlState` を作るために使います。`push(url)` と `replace(url)` を持つメモ化されたオブジェクトを渡してください。
+
+ルーターが**まったくない**場合は不要です。[`state-in-url/react`](#react-向け-useurlstate-フックルーターなし) を使ってください。こちらは同じフックを `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` との違いは 2 点です:
+
+- 返すのは `urlState`、`setUrl`、`setState` ではなく `state`、`updateUrl`、`updateState` です。また `updateUrl` の既定は push で、`setUrl` の既定は replace です。
+- 第 3 引数が初期 state を決めます。省略するとフックは読み込み時のクエリ文字列を無視するため、共有されたリンクを開いても既定値が表示されます。
+
+> [!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/README.ko.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.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=ko source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=ko source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,8 +150,10 @@ nuqs도 훌륭한 라이브러리입니다. 값마다 읽기 쉬운 쿼리 파
       - [예제](#예제)
     - [React-Router용 useUrlState 훅](#react-router용-useurlstate-훅)
       - [예제](#예제-1)
-    - [Astro용 useUrlState 훅](#astro용-useurlstate-훅)
+    - [React용 useUrlState 훅 (라우터 없음)](#react용-useurlstate-훅-라우터-없음)
       - [예제](#예제-2)
+    - [Astro용 useUrlState 훅](#astro용-useurlstate-훅)
+      - [예제](#예제-3)
   - [레시피](#레시피)
         - [상태의 일부를 편리하게 다루기 위한 커스텀 훅](#상태의-일부를-편리하게-다루기-위한-커스텀-훅)
         - [복잡한 상태 구조 사용](#복잡한-상태-구조-사용)
@@ -536,6 +538,39 @@ const tags = [
 
 [예제 코드](packages/example-react-router6/src/Form-for-test.tsx)
 
+### React용 useUrlState 훅 (라우터 없음)
+
+라우터가 없는 React 앱을 위한 것입니다. Vite, Create React App, 또는 직접 제어할 수 없는 페이지에 끼워 넣는 위젯이 여기에 해당합니다. 이 훅은 `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` 는 바로 이 훅입니다. islands 는 `searchParams` 를 prop 으로도 받기 때문에 아래에서 따로 설명합니다.
+
 ### Astro용 useUrlState 훅
 
 React 아일랜드용입니다. Astro에는 기본적으로 클라이언트 측 라우터가 없으므로, 이 훅은 `window.history`로 URL을 쓰고, 뒤로/앞으로 이동과 그 외 모든 `pushState`/`replaceState` 시점에 (Astro 자체의 `<ClientRouter />` 포함) URL을 다시 읽어 옵니다. 한 페이지의 아일랜드들은 감싸는 것 없이 상태를 공유합니다.
@@ -816,7 +851,37 @@ const tags = [
 
 ### 다른 라우터용 `useUrlStateBase` 훅
 
-다른 라우터(예: react-router 또는 tanstack router)와 함께 자체 `useUrlState` 훅을 만들기 위한 훅입니다.
+이 패키지가 진입점을 제공하지 않는 라우터(예: TanStack Router)를 위해 직접 `useUrlState` 를 만들 때 사용합니다. `push(url)` 과 `replace(url)` 을 가진 메모이즈된 객체를 넘기면 됩니다.
+
+라우터가 **전혀 없다면** 이것은 필요 없습니다. 이미 `window.history` 에 연결된 같은 훅인 [`state-in-url/react`](#react용-useurlstate-훅-라우터-없음) 를 쓰세요.
+
+```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` 와 다른 점은 두 가지입니다:
+
+- `urlState`, `setUrl`, `setState` 가 아니라 `state`, `updateUrl`, `updateState` 를 반환하며, `updateUrl` 의 기본값은 push, `setUrl` 의 기본값은 replace 입니다.
+- 세 번째 인자가 초기 state 를 채웁니다. 이를 생략하면 훅이 페이지가 로드된 시점의 쿼리 문자열을 무시하므로, 공유된 링크를 열어도 기본값만 보입니다.
+
+> [!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/README.md

@@ -149,14 +149,16 @@ The full comparison — the same feature built in both, other alternatives (TanS
       - [Example](#example)
     - [useUrlState hook for React-Router](#useurlstate-hook-for-react-router)
       - [Example](#example-1)
-    - [useUrlState hook for Astro](#useurlstate-hook-for-astro)
+    - [useUrlState hook for React (no router)](#useurlstate-hook-for-react-no-router)
       - [Example](#example-2)
+    - [useUrlState hook for Astro](#useurlstate-hook-for-astro)
+      - [Example](#example-3)
   - [Recipes](#recipes)
         - [Custom hook to work with slice of state conveniently](#custom-hook-to-work-with-slice-of-state-conveniently)
         - [With complex state shape](#with-complex-state-shape)
         - [Update state only and sync to URL manually](#update-state-only-and-sync-to-url-manually)
   - [Other hooks and helpers](#other-hooks-and-helpers)
-    - [`useUrlStateBase` hook for others routers](#useurlstatebase-hook-for-others-routers)
+    - [`useUrlStateBase` hook for another router](#useurlstatebase-hook-for-another-router)
     - [`useSharedState` hook for React.js](#usesharedstate-hook-for-reactjs)
     - [`useLinkProps` hook for React.js](#uselinkprops-hook-for-reactjs)
     - [`useUrlEncode` hook for React.js](#useurlencode-hook-for-reactjs)
@@ -539,6 +541,39 @@ const tags = [
 
 [Example code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### useUrlState hook for React (no router)
+
+For a React app with no router — Vite, Create React App, a widget mounted into a page you do not control. The hook writes the URL with `window.history` and reads it back on back/forward and on any other `pushState`/`replaceState`. Every component using the same state object shares it, with nothing to wrap them in and nothing to pass through props.
+
+[API Docs](packages/urlstate/react/useUrlState)
+
+#### Example
+
+```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` is this same hook; it is documented separately below because islands also take `searchParams` as a prop.
+
 ### useUrlState hook for Astro
 
 For React islands. Astro has no client-side router by default, so the hook writes the URL with `window.history` and reads it back on back/forward and on any other `pushState`/`replaceState`, Astro's own `<ClientRouter />` included. Islands on a page share the state, with nothing to wrap them in.
@@ -817,9 +852,39 @@ Syncing state `onBlur` will be more aligned with real world usage.
 
 ## Other hooks and helpers
 
-### `useUrlStateBase` hook for others routers
+### `useUrlStateBase` hook for another router
+
+Use this to build your own `useUrlState` for a router this package ships no entry point for, e.g. TanStack Router. Pass any memoized object with `push(url)` and `replace(url)`.
+
+With **no router at all**, you do not need this — use [`state-in-url/react`](#useurlstate-hook-for-react-no-router), which is this hook already wired to `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));
+}
+```
+
+Two differences from `useUrlState`:
+
+- It returns `state`, `updateUrl`, `updateState` — not `urlState`, `setUrl`, `setState` — and `updateUrl` defaults to push, where `setUrl` defaults to replace.
+- The third argument seeds the initial state. Leave it out and the hook ignores the query string it loaded with, so a shared link opens with defaults.
 
-Hooks to create your own `useUrlState` hooks with other routers, e.g. react-router or tanstack router.
+> [!NOTE]
+> `useUrlState` is not exported from the package root — every one of them is tied to a framework, so each lives behind its own entry point (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). The root entry carries only what is framework-agnostic: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` and `encodeState`/`decodeState`.
 
 [API Docs](packages/urlstate/useUrlStateBase)
 

package/README.pt-BR.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) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=pt-BR source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
+<!-- i18n:meta locale=pt-BR source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -150,14 +150,16 @@ A comparação completa — a mesma feature nas duas, outras alternativas (TanSt
       - [Exemplo](#exemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Exemplo](#exemplo-1)
-    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+    - [Hook useUrlState para React (sem router)](#hook-useurlstate-para-react-sem-router)
       - [Exemplo](#exemplo-2)
+    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+      - [Exemplo](#exemplo-3)
   - [Receitas](#receitas)
         - [Hook personalizado para trabalhar convenientemente com uma fatia do estado](#hook-personalizado-para-trabalhar-convenientemente-com-uma-fatia-do-estado)
         - [Com forma de estado complexa](#com-forma-de-estado-complexa)
         - [Atualizar apenas o estado e sincronizar com a URL manualmente](#atualizar-apenas-o-estado-e-sincronizar-com-a-url-manualmente)
   - [Outros hooks e helpers](#outros-hooks-e-helpers)
-    - [Hook `useUrlStateBase` para outros routers](#hook-useurlstatebase-para-outros-routers)
+    - [Hook `useUrlStateBase` para outro router](#hook-useurlstatebase-para-outro-router)
     - [Hook `useSharedState` para React.js](#hook-usesharedstate-para-reactjs)
     - [Hook `useLinkProps` para React.js](#hook-uselinkprops-para-reactjs)
     - [Hook `useUrlEncode` para React.js](#hook-useurlencode-para-reactjs)
@@ -540,6 +542,39 @@ const tags = [
 
 [Exemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState para React (sem router)
+
+Para uma aplicação React sem router: Vite, Create React App, ou um widget montado em uma página que você não controla. O hook escreve a URL com `window.history` e a lê de volta ao navegar para trás e para frente e a cada outro `pushState`/`replaceState`. Todos os componentes que usam o mesmo objeto de estado o compartilham, sem nada para envolver e sem nada para passar por props.
+
+[Documentação da API](packages/urlstate/react/useUrlState)
+
+#### Exemplo
+
+```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` é este mesmo hook; ele é documentado à parte abaixo porque as islands também recebem `searchParams` como prop.
+
 ### Hook useUrlState para Astro
 
 Para ilhas React. O Astro não tem um router no lado do cliente por padrão, então o hook escreve a URL com `window.history` e a lê de volta ao navegar para trás/para frente e em qualquer outro `pushState`/`replaceState`, incluindo o próprio `<ClientRouter />` do Astro. As ilhas de uma página compartilham o estado, sem precisar envolvê-las em nada.
@@ -818,9 +853,39 @@ Sincronizar o estado em `onBlur` estará mais alinhado com o uso no mundo real.
 
 ## Outros hooks e helpers
 
-### Hook `useUrlStateBase` para outros routers
+### Hook `useUrlStateBase` para outro router
+
+Use-o para construir seu próprio `useUrlState` para um router do qual este pacote não publica um ponto de entrada, por exemplo TanStack Router. Passe qualquer objeto memoizado com `push(url)` e `replace(url)`.
+
+Se **não houver router algum**, você não precisa disso — use [`state-in-url/react`](#hook-useurlstate-para-react-sem-router), que é este mesmo hook já ligado ao `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));
+}
+```
+
+Duas diferenças em relação ao `useUrlState`:
+
+- Ele retorna `state`, `updateUrl` e `updateState`, e não `urlState`, `setUrl` e `setState`; além disso `updateUrl` faz push por padrão, enquanto `setUrl` faz replace.
+- O terceiro argumento define o state inicial. Se você omiti-lo, o hook ignora a query string com que a página foi carregada, então um link compartilhado abre com os valores padrão.
 
-Hooks para criar seus próprios hooks `useUrlState` com outros routers, por exemplo react-router ou tanstack router.
+> [!NOTE]
+> `useUrlState` não é mais exportado da raiz do pacote: cada um está preso a um framework, então cada um fica em seu próprio ponto de entrada (`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`). A raiz mantém apenas o que independe de framework: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode` e `encodeState`/`decodeState`.
 
 [Documentação da API](packages/urlstate/useUrlStateBase)