feat: useLinkProps hook

Author: asmyshlyaev177

.eslintignore

@@ -3,6 +3,7 @@ package.json
 playwright.config.ts
 rollup.config.*
 .eslintrc.cjs
+scripts
 *.test.ts
 *.test.tsx
 *.spec.ts

.eslintrc.cjs

@@ -64,5 +64,11 @@ module.exports = {
         '@typescript-eslint/no-unused-vars': 'warn',
       },
     },
+    {
+      // `tsconfig.json` excludes `tests`, so type-aware parsing cannot reach
+      // these — without this they are a parsing error, not a lint result.
+      files: ['tests/**/*.ts'],
+      parserOptions: { project: null },
+    },
   ],
 };

.github/workflows/tests.yml

@@ -50,7 +50,9 @@ jobs:
       #   run: npm run test:exports
 
       - name: Unit tests
-        run: pnpm exec tsc --noEmit && pnpm exec vitest --run --coverage
+        # Through wireit: the examples import `state-in-url`, so the typecheck
+        # needs a built `dist/`, and `tsc` depends on `build`.
+        run: pnpm run tsc && pnpm exec vitest --run --coverage
       - name: Run codacy-coverage-reporter
         uses: codacy/codacy-coverage-reporter-action@89d6c85cfafaec52c72b6c5e8b2878d33104c699 # v1.3.0
         continue-on-error: true

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=es source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@ Esta biblioteca es una buena alternativa a NUQS.
   - [Otros hooks y helpers](#otros-hooks-y-helpers)
     - [Hook `useUrlStateBase` para otros routers](#hook-useurlstatebase-para-otros-routers)
     - [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)
     - [Helpers `encodeState` y `decodeState`](#helpers-encodestate-y-decodestate)
     - [Helpers `encode` y `decode`](#helpers-encode-y-decode)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [Documentación de la API](packages/urlstate/useSharedState/README.es.md)
 
+### Hook `useLinkProps` para React.js
+
+Hook para llevar el estado a un enlace que apunta a otra ruta, por ejemplo un selector de idioma. `setUrl` siempre escribe en la ruta actual; este no.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+El marcado conserva el `href` tal cual, así que los rastreadores y `hreflang` ven la URL canónica; el estado se lee al hacer clic.
+
+[Documentación de la API](packages/urlstate/useLinkProps/README.es.md)
+
 ### Hook `useUrlEncode` para React.js
 
 [Documentación de la API](packages/urlstate/useUrlEncode/README.es.md)

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=fr source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@ Cette bibliothèque est une bonne alternative à NUQS.
   - [Autres hooks et helpers](#autres-hooks-et-helpers)
     - [Hook `useUrlStateBase` pour d'autres routeurs](#hook-useurlstatebase-pour-dautres-routeurs)
     - [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)
     - [Helpers `encodeState` et `decodeState`](#helpers-encodestate-et-decodestate)
     - [Helpers `encode` et `decode`](#helpers-encode-et-decode)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [Documentation de l'API](packages/urlstate/useSharedState/README.fr.md)
 
+### Hook `useLinkProps` pour React.js
+
+Hook qui emporte l'état vers un lien pointant sur une autre route, par exemple un sélecteur de langue. `setUrl` écrit toujours sur le chemin courant ; celui-ci non.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+Le balisage conserve le `href` tel quel : les robots d'indexation et `hreflang` voient donc l'URL canonique ; l'état est lu au clic.
+
+[Documentation de l'API](packages/urlstate/useLinkProps/README.fr.md)
+
 ### Hook `useUrlEncode` pour React.js
 
 [Documentation de l'API](packages/urlstate/useUrlEncode/README.fr.md)

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=ja source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@ Next.js と react-router 用の `useUrlState` フックと、その他あらゆ
   - [その他のフックとヘルパー](#その他のフックとヘルパー)
     - [他のルーター向け `useUrlStateBase` フック](#他のルーター向け-useurlstatebase-フック)
     - [React.js 向け `useSharedState` フック](#reactjs-向け-usesharedstate-フック)
+    - [React.js 向け `useLinkProps` フック](#reactjs-向け-uselinkprops-フック)
     - [React.js 向け `useUrlEncode` フック](#reactjs-向け-useurlencode-フック)
     - [`encodeState` と `decodeState` ヘルパー](#encodestate-と-decodestate-ヘルパー)
     - [`encode` と `decode` ヘルパー](#encode-と-decode-ヘルパー)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [API ドキュメント](packages/urlstate/useSharedState/README.ja.md)
 
+### React.js 向け `useLinkProps` フック
+
+別のルートを指すリンクに状態を引き継ぐためのフックです。言語切り替えなどに使います。`setUrl` は常に現在のパスに書き込みますが、こちらは違います。
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+マークアップには素の `href` が残るため、クローラーと `hreflang` は正規の URL を参照します。状態はクリック時に読み取られます。
+
+[API ドキュメント](packages/urlstate/useLinkProps/README.ja.md)
+
 ### React.js 向け `useUrlEncode` フック
 
 [API ドキュメント](packages/urlstate/useUrlEncode/README.ja.md)

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=ko source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@ Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬
   - [기타 훅과 헬퍼](#기타-훅과-헬퍼)
     - [다른 라우터용 `useUrlStateBase` 훅](#다른-라우터용-useurlstatebase-훅)
     - [React.js용 `useSharedState` 훅](#reactjs용-usesharedstate-훅)
+    - [React.js용 `useLinkProps` 훅](#reactjs용-uselinkprops-훅)
     - [React.js용 `useUrlEncode` 훅](#reactjs용-useurlencode-훅)
     - [`encodeState` 및 `decodeState` 헬퍼](#encodestate-및-decodestate-헬퍼)
     - [`encode` 및 `decode` 헬퍼](#encode-및-decode-헬퍼)
@@ -694,6 +695,29 @@ function SettingsComponent() {
 
 [API 문서](packages/urlstate/useSharedState/README.md)
 
+### React.js용 `useLinkProps` 훅
+
+다른 라우트를 가리키는 링크로 상태를 넘기는 훅입니다. 예를 들어 언어 전환기에 씁니다. `setUrl` 은 언제나 현재 경로에 쓰지만, 이 훅은 그렇지 않습니다.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+마크업에는 원래의 `href` 가 남으므로 크롤러와 `hreflang` 은 정규 URL 을 봅니다. 상태는 클릭할 때 읽습니다.
+
+[API 문서](packages/urlstate/useLinkProps/README.ko.md)
+
 ### React.js용 `useUrlEncode` 훅
 
 [API 문서](packages/urlstate/useUrlEncode/README.md)

README.md

@@ -134,6 +134,7 @@ This library is a good alternative for NUQS.
   - [Other hooks and helpers](#other-hooks-and-helpers)
     - [`useUrlStateBase` hook for others routers](#useurlstatebase-hook-for-others-routers)
     - [`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)
     - [`encodeState` and `decodeState` helpers](#encodestate-and-decodestate-helpers)
     - [`encode` and `decode` helpers](#encode-and-decode-helpers)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [API Docs](packages/urlstate/useSharedState/README.md)
 
+### `useLinkProps` hook for React.js
+
+Hook to carry the state to a link pointing at a different route, e.g. a language switcher. `setUrl` always writes to the current path; this doesn't.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+The markup keeps the plain `href`, so crawlers and `hreflang` see the canonical URL; the state is read on click.
+
+[API Docs](packages/urlstate/useLinkProps/README.md)
+
 ### `useUrlEncode` hook for React.js
 
 [API Docs](packages/urlstate/useUrlEncode/README.md)

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=pt-BR source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@ Esta biblioteca é uma boa alternativa ao NUQS.
   - [Outros hooks e helpers](#outros-hooks-e-helpers)
     - [Hook `useUrlStateBase` para outros routers](#hook-useurlstatebase-para-outros-routers)
     - [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)
     - [Helpers `encodeState` e `decodeState`](#helpers-encodestate-e-decodestate)
     - [Helpers `encode` e `decode`](#helpers-encode-e-decode)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [Documentação da API](packages/urlstate/useSharedState/README.pt-BR.md)
 
+### Hook `useLinkProps` para React.js
+
+Hook para levar o estado até um link que aponta para outra rota, por exemplo um seletor de idioma. `setUrl` sempre escreve no caminho atual; este não.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+A marcação mantém o `href` simples, então rastreadores e `hreflang` enxergam a URL canônica; o estado é lido no clique.
+
+[Documentação da API](packages/urlstate/useLinkProps/README.pt-BR.md)
+
 ### Hook `useUrlEncode` para React.js
 
 [Documentação da API](packages/urlstate/useUrlEncode/README.pt-BR.md)

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=01b5b4f72aa3c8871c185cfce21c6d696edb847b status=translated -->
+<!-- i18n:meta locale=ru source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -134,6 +134,7 @@
   - [Другие hook'и и вспомогательные функции](#другие-hookи-и-вспомогательные-функции)
     - [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)
     - [Вспомогательные функции `encodeState` и `decodeState`](#вспомогательные-функции-encodestate-и-decodestate)
     - [Вспомогательные функции `encode` и `decode`](#вспомогательные-функции-encode-и-decode)
@@ -698,6 +699,29 @@ function SettingsComponent() {
 
 [Документация по API](packages/urlstate/useSharedState/README.ru.md)
 
+### Hook `useLinkProps` для React.js
+
+Хук, переносящий состояние на ссылку, которая ведёт на другой маршрут, — например, в переключателе языка. `setUrl` всегда пишет в текущий путь, этот хук — нет.
+
+```tsx
+'use client'
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useLinkProps } from 'state-in-url/useLinkProps';
+
+export const form = { name: '' };
+
+function LanguagePicker() {
+  const linkProps = useLinkProps(form, useRouter().push);
+
+  return <Link {...linkProps('/de/pricing')}>Deutsch</Link>;
+}
+```
+
+В разметке остаётся обычный `href`, поэтому краулеры и `hreflang` видят канонический URL; состояние читается в момент клика.
+
+[Документация по API](packages/urlstate/useLinkProps/README.ru.md)
+
 ### Hook `useUrlEncode` для React.js
 
 [Документация по API](packages/urlstate/useUrlEncode/README.ru.md)