state-in-url 6.4.1 → 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=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=es source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@ Comparte si te resulta útil.
 Guarda cualquier estado de usuario en los parámetros de consulta; imagina JSON en la URL de un navegador. Todo ello manteniendo los tipos y la estructura de los datos: por ejemplo, los números se decodificarán como números y no como cadenas, las fechas como fechas, etc.; se admiten objetos y matrices.
 Simple a más no poder, rápido y con validación estática de TypeScript. Los enlaces profundos, es decir, la sincronización de URL, se vuelven fáciles.
 
-Incluye el hook `useUrlState` para Next.js y react-router, y helpers para cualquier otra cosa en JS.
+Incluye el hook `useUrlState` para Next.js, react-router, Remix y Astro, y helpers para cualquier otra cosa en JS.
 Como los navegadores modernos soportan URLs enormes y a los usuarios no les importan las cadenas de consulta (es un flujo de seleccionar todo y copiar/pegar).
 
 Es hora de usar la cadena de consulta para gestionar el estado, como se pensó originalmente.
@@ -98,10 +98,32 @@ Esta biblioteca es una buena alternativa a NUQS.
 - **Renderizado en el servidor**: Se puede usar en componentes de servidor, se soportan Next.js 14, 15 y 16
 - **Ligero**: Cero dependencias, biblioteca de menos de 2KB
 - **DX**: Buena experiencia de desarrollo, documentación, comentarios JSDoc y ejemplos
-- **Flexibilidad de frameworks**: Hooks para `Next.js` y `react-router`, helpers para usarla con otros frameworks o JS puro
+- **Flexibilidad de frameworks**: Hooks para `Next.js`, `react-router`, `Remix` y `Astro`, helpers para usarla con otros frameworks o JS puro
 - **Bien probada**: [Pruebas unitarias y pruebas de Playwright para Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Licencia permisiva**: MIT
 
+### Comparación con nuqs
+
+¿Buscas una alternativa a [nuqs](https://github.com/47ng/nuqs)? Ambas guardan estado tipado en la query string; difieren en cuánto hay que configurar y en qué puede ser un valor.
+
+| Qué | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Configuración | Ninguna — importa el hook y listo | Un componente adaptador envuelve la app |
+| Forma del estado | Un objeto tipado, como `React.useState` | Valores por clave, con un parser declarado para cada una |
+| Reutilización entre componentes | Envuelve el hook una vez — cada componente comparte el estado, sin props | Extraes tu propio hook alrededor del mapa de parsers |
+| Objetos y arrays anidados | Integrado — estructura y tipos se conservan | Parser JSON más tu propio validador |
+| Fechas | Se conservan automáticamente | Parser integrado, declarado por clave |
+| Tamaño, import completo | ~2,9 KB gzip | ~6,7 KB gzip |
+| Dependencias en runtime | Ninguna | Una |
+| Routers | Next.js, React Router v6/v7, Remix, Astro, helpers para JS puro | Next.js, React Router, Remix, TanStack Router, React puro |
+
+Tamaños: import de toda la librería, esbuild minify + gzip, medido en agosto de 2026 contra nuqs 2.10.1.
+
+nuqs es una buena librería: elígela si quieres cada valor como su propio query param legible o usas TanStack Router. Elige state-in-url cuando quieras un objeto tipado completo en la URL sin configuración.
+
+
+La comparación completa — la misma feature en ambas, otras alternativas (TanStack Router, use-query-params) y notas de migración — está en <https://state-in-url.dev/vs/nuqs>.
+
 ## Tabla de contenido
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Esta biblioteca es una buena alternativa a NUQS.
   - [¿Por qué usar `state-in-url`?](#por-qué-usar-state-in-url)
     - [Casos de uso](#casos-de-uso)
     - [Características](#características)
+    - [Comparación con nuqs](#comparación-con-nuqs)
   - [Tabla de contenido](#tabla-de-contenido)
   - [Instalación](#instalación)
     - [1. Instalar el paquete](#1-instalar-el-paquete)
@@ -127,12 +150,16 @@ Esta biblioteca es una buena alternativa a NUQS.
       - [Ejemplo](#ejemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Ejemplo](#ejemplo-1)
+    - [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)
@@ -515,6 +542,156 @@ 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.
+
+[Documentación de la API](packages/urlstate/astro/useUrlState)
+
+#### Ejemplo
+
+```typescript
+// src/state.ts
+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 } }[];
+};
+```
+
+La página debe renderizarse bajo demanda (`output: 'server'`, o `export const prerender = false` en la página, con un adaptador): una página prerenderizada no tiene petición, así que la isla recibe `{}` y lee la URL después de la hidratación.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// El renderizado en el servidor coincide con la URL, así que la hidratación no tiene nada que corregir.
+// Un objeto plano: las props de las islas se serializan, URLSearchParams no.
+const searchParams = Object.fromEntries(Astro.url.searchParams);
+---
+
+<Form client:load searchParams={searchParams} />
+<Status client:load searchParams={searchParams} />
+```
+
+```typescript
+// src/components/Form.tsx
+import React from 'react';
+import { useUrlState } from 'state-in-url/astro';
+
+import { form } from '../state';
+
+export function Form({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState, setUrl, setState } = useUrlState(form, { searchParams });
+
+  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>
+      {tags.map((tag) => (
+        <Tag
+          active={!!urlState.tags.find((t) => t.id === tag.id)}
+          text={tag.value.text}
+          onClick={() => onChangeTags(tag)}
+          key={tag.id}
+        />
+      ))}
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // Puede actualizar el estado inmediatamente pero sincronizar el cambio con la url según sea necesario
+        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') } },
+];
+
+// Status.tsx, una segunda isla, lee el mismo estado
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Las islas de Preact funcionan igual: con `@astrojs/preact` y `compat: true`, `react` se resuelve a `preact/compat` tanto en la compilación del servidor como en la del cliente, y el import de arriba no cambia.
+
+Sin islas, en una página sin ningún framework de cliente, el mismo estado vive en el frontmatter a través de [`decodeState` y `encodeState`](#helpers-encodestate-y-decodestate):
+
+```astro
+---
+import { decodeState, encodeState } from 'state-in-url/encodeState';
+
+import { form } from '../state';
+
+const state = decodeState(Astro.url.searchParams, form);
+const withName = encodeState({ ...state, name: 'Alice' }, form, Astro.url.searchParams);
+---
+
+<pre>{JSON.stringify(state)}</pre>
+<a href={`?${withName}`}>Alice</a>
+```
+
+[Ejemplo de código](packages/example-astro/src/components/Form-for-test.tsx), [página en Astro puro](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Recetas
 ##### Hook personalizado para trabajar cómodamente con una porción del estado
 <details>
@@ -676,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)
 
@@ -787,7 +994,7 @@ Consulta el [documento de contribución](CONTRIBUTING.md)
 - [x] hook para `react-router`
 - [x] hook para `remix`
 - [ ] hook para `svelte`
-- [ ] hook para `astro`
+- [x] hook para `astro`
 - [ ] hook para guardar el estado en el hash ?
 
 ## Contacto y soporte

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=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=fr source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@ Partagez si cela vous est utile.
 Stockez n'importe quel état utilisateur dans les paramètres de requête ; imaginez du JSON dans une URL de navigateur. Tout cela en conservant les types et la structure des données : par exemple, les nombres seront décodés comme des nombres et non comme des chaînes, les dates comme des dates, etc., les objets et les tableaux sont pris en charge.
 Extrêmement simple, rapide et avec une validation TypeScript statique. Les liens profonds, autrement dit la synchronisation d'URL, deviennent faciles.
 
-Contient le hook `useUrlState` pour Next.js et react-router, ainsi que des helpers pour tout le reste en JS.
+Contient le hook `useUrlState` pour Next.js, react-router, Remix et Astro, ainsi que des helpers pour tout le reste en JS.
 Comme les navigateurs modernes prennent en charge d'énormes URL et que les utilisateurs ne se soucient pas des chaînes de requête (c'est un flux de travail « tout sélectionner et copier/coller »).
 
 Il est temps d'utiliser la chaîne de requête pour la gestion d'état, comme cela était prévu à l'origine.
@@ -98,10 +98,32 @@ Cette bibliothèque est une bonne alternative à NUQS.
 - **Rendu côté serveur** : Utilisable dans les composants serveur, Next.js 14, 15 et 16 sont pris en charge
 - **Léger** : Zéro dépendance, bibliothèque de moins de 2KB
 - **DX** : Bonne expérience de développement, documentation, commentaires JSDoc et exemples
-- **Flexibilité de frameworks** : Hooks pour `Next.js` et `react-router`, helpers pour l'utiliser avec d'autres frameworks ou du JS pur
+- **Flexibilité de frameworks** : Hooks pour `Next.js`, `react-router`, `Remix` et `Astro`, helpers pour l'utiliser avec d'autres frameworks ou du JS pur
 - **Bien testée** : [Tests unitaires et tests Playwright pour Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Licence permissive** : MIT
 
+### Comparaison avec nuqs
+
+Vous cherchez une alternative à [nuqs](https://github.com/47ng/nuqs) ? Les deux gardent un état typé dans la query string ; elles diffèrent par la configuration requise et par ce qu’une valeur peut être.
+
+| Quoi | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Mise en place | Aucune — importez le hook et c’est parti | Un composant adaptateur enveloppe l’application |
+| Forme de l’état | Un objet typé, comme `React.useState` | Valeurs par clé, un parseur déclaré pour chacune |
+| Réutilisation entre composants | Enveloppez le hook une fois — chaque composant partage l’état, sans props | Vous extrayez votre propre hook autour de la table de parseurs |
+| Objets et tableaux imbriqués | Intégré — structure et types préservés | Parseur JSON plus votre propre validateur |
+| Dates | Préservées automatiquement | Parseur intégré, déclaré par clé |
+| Taille, import complet | ~2,9 Ko gzip | ~6,7 Ko gzip |
+| Dépendances au runtime | Aucune | Une |
+| Routeurs | Next.js, React Router v6/v7, Remix, Astro, helpers pour JS pur | Next.js, React Router, Remix, TanStack Router, React pur |
+
+Tailles : import de la bibliothèque entière, esbuild minify + gzip, mesuré en août 2026 face à nuqs 2.10.1.
+
+nuqs est une bonne bibliothèque — choisissez-la pour un query param lisible par valeur, ou si vous êtes sur TanStack Router. Choisissez state-in-url pour un objet typé complet dans l’URL, sans configuration.
+
+
+La comparaison complète — la même fonctionnalité dans les deux, d’autres alternatives (TanStack Router, use-query-params) et des notes de migration — se trouve sur <https://state-in-url.dev/vs/nuqs>.
+
 ## Table des matières
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Cette bibliothèque est une bonne alternative à NUQS.
   - [Pourquoi utiliser `state-in-url` ?](#pourquoi-utiliser-state-in-url-)
     - [Cas d'utilisation](#cas-dutilisation)
     - [Fonctionnalités](#fonctionnalités)
+    - [Comparaison avec nuqs](#comparaison-avec-nuqs)
   - [Table des matières](#table-des-matières)
   - [Installation](#installation)
     - [1. Installer le paquet](#1-installer-le-paquet)
@@ -127,12 +150,16 @@ Cette bibliothèque est une bonne alternative à NUQS.
       - [Exemple](#exemple)
     - [Hook useUrlState pour React-Router](#hook-useurlstate-pour-react-router)
       - [Exemple](#exemple-1)
+    - [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)
@@ -515,6 +542,156 @@ 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.
+
+[Documentation de l'API](packages/urlstate/astro/useUrlState)
+
+#### Exemple
+
+```typescript
+// src/state.ts
+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 } }[];
+};
+```
+
+La page doit être rendue à la demande (`output: 'server'`, ou `export const prerender = false` sur la page, avec un adaptateur) : une page prérendue n'a pas de requête, donc l'îlot reçoit `{}` et lit l'URL après l'hydratation.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// Le rendu serveur correspond à l'URL, donc l'hydratation n'a rien à corriger.
+// Un objet simple : les props d'îlot sont sérialisées, URLSearchParams ne l'est pas.
+const searchParams = Object.fromEntries(Astro.url.searchParams);
+---
+
+<Form client:load searchParams={searchParams} />
+<Status client:load searchParams={searchParams} />
+```
+
+```typescript
+// src/components/Form.tsx
+import React from 'react';
+import { useUrlState } from 'state-in-url/astro';
+
+import { form } from '../state';
+
+export function Form({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState, setUrl, setState } = useUrlState(form, { searchParams });
+
+  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>
+      {tags.map((tag) => (
+        <Tag
+          active={!!urlState.tags.find((t) => t.id === tag.id)}
+          text={tag.value.text}
+          onClick={() => onChangeTags(tag)}
+          key={tag.id}
+        />
+      ))}
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // Peut mettre à jour l'état immédiatement mais synchroniser le changement avec l'url selon les besoins
+        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') } },
+];
+
+// Status.tsx, un second îlot, lit le même état
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Les îlots Preact fonctionnent de la même manière : avec `@astrojs/preact` et `compat: true`, `react` est résolu vers `preact/compat` aussi bien dans le build serveur que dans le build client, et l'import ci-dessus reste inchangé.
+
+Sans îlots, sur une page sans aucun framework client, le même état vit dans le frontmatter via [`decodeState` et `encodeState`](#helpers-encodestate-et-decodestate) :
+
+```astro
+---
+import { decodeState, encodeState } from 'state-in-url/encodeState';
+
+import { form } from '../state';
+
+const state = decodeState(Astro.url.searchParams, form);
+const withName = encodeState({ ...state, name: 'Alice' }, form, Astro.url.searchParams);
+---
+
+<pre>{JSON.stringify(state)}</pre>
+<a href={`?${withName}`}>Alice</a>
+```
+
+[Exemple de code](packages/example-astro/src/components/Form-for-test.tsx), [page Astro pure](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Recettes
 ##### Hook personnalisé pour travailler confortablement avec une tranche d'état
 <details>
@@ -676,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)
 
@@ -787,7 +994,7 @@ Voir le [document de contribution](CONTRIBUTING.md)
 - [x] hook pour `react-router`
 - [x] hook pour `remix`
 - [ ] hook pour `svelte`
-- [ ] hook pour `astro`
+- [x] hook pour `astro`
 - [ ] hook pour stocker l'état dans le hash ?
 
 ## Contact et support