soseki 0.0.8 → 0.0.10

package/dist/src/components/browser-router.d.ts

@@ -1,4 +1,4 @@
-import type { RouteDefinition } from "../core/route.types.js";
+import { type RouterRouteDefinition } from "./router.jsx";
 /**
  * `BrowserRouter` コンポーネントに引き渡すプロパティーの型定義です。
  */
@@ -6,7 +6,7 @@ export type BrowserRouterProps = {
     /**
      * アプリケーション全体の画面構造を定義したルート定義の配列です。
      */
-    routes: readonly RouteDefinition[];
+    routes: readonly RouterRouteDefinition[];
 };
 /**
  * ブラウザー環境における SPA ルーティングを開始するための、最上位エントリーポイントコンポーネントです。

package/dist/src/components/browser-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-router.d.ts","sourceRoot":"","sources":["../../../src/components/browser-router.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAKnF"}
+{"version":3,"file":"browser-router.d.ts","sourceRoot":"","sources":["../../../src/components/browser-router.tsx"],"names":[],"mappings":"AAEA,OAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC1C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAKnF"}

package/dist/src/components/router.d.ts

@@ -1,6 +1,36 @@
 import * as React from "react";
-import type { RouteDefinition } from "../core/route.types.js";
 import type { IEngine } from "../engines/engine.types.js";
+export type RouterRouteDefinitionObject = {
+    readonly path: string;
+    readonly index?: boolean | undefined;
+    readonly action?: {
+        (args: any): unknown;
+    } | undefined;
+    readonly shouldReload?: {
+        (args: any): boolean;
+    } | undefined;
+    readonly loader?: {
+        (args: any): unknown;
+    } | undefined;
+    readonly component?: React.ComponentType<{}> | undefined;
+};
+export type RouterRouteDefinitionModule = {
+    readonly path: string;
+    readonly index?: boolean | undefined;
+    readonly action?: {
+        (args: any): unknown;
+    } | undefined;
+    readonly shouldReload?: {
+        (args: any): boolean;
+    } | undefined;
+    readonly loader?: {
+        (args: any): unknown;
+    } | undefined;
+    readonly component?: React.ComponentType<{}> | undefined;
+    readonly default?: React.ComponentType<{}> | undefined;
+    get [Symbol.toStringTag](): string;
+};
+export type RouterRouteDefinition = RouterRouteDefinitionObject | RouterRouteDefinitionModule;
 /**
  * `Router` コンポーネントに渡されるルートプロパティーの型定義です。
  */
@@ -12,7 +42,7 @@ export type RouterProps = {
     /**
      * ユーザーがアプリケーションに定義したルート定義の配列です。
      */
-    routes: readonly RouteDefinition[];
+    routes: readonly RouterRouteDefinition[];
 };
 /**
  * 宣言的なルート定義と、命令的なルーティング実行エンジンを仲介・統合し、アプリケーションの最上位でルーティングのライフサイクルと状態管理を司るプロバイダーコンポーネントです。

package/dist/src/components/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/components/router.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,4BAA4B,CAAC;AAkEvE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,KAAK,EAAE,WAAW,4BAkIhD"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/components/router.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAY/B,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,4BAA4B,CAAC;AAkEvE,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,GAAG,2BAA2B,CAAC;AAE9F;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,KAAK,EAAE,WAAW,4BAkIhD"}

package/dist/src/core/match-route-path.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ルーティングの照合対象となる URL 情報を表すインターフェースです。
+ */
+export interface MatchRoutePathTargetURL {
+    /**
+     * 照合対象のパス名です。
+     */
+    readonly pathname: string;
+}
+/**
+ * `matchRoutePath` 関数の動作を設定するための型定義です。
+ */
+export type MatchRoutePathOptions = {
+    /**
+     * 照合の基準となるルーティングのパターン文字列です。
+     */
+    readonly pattern: string;
+    /**
+     * 照合対象とする文字列または URL オブジェクトです。
+     */
+    readonly target: string | MatchRoutePathTargetURL;
+    /**
+     * 子ディレクトリーへの前方一致を許可するかどうかを制御するフラグです。
+     *
+     * @default false
+     */
+    readonly allowChild?: boolean | undefined;
+};
+/**
+ * 指定されたパターンと対象のパス名が一致するかどうかを判定します。
+ *
+ * @param options パターン、対象、および一致条件を含む設定オブジェクトです。
+ * @returns パターンに一致した場合は `true` を、一致しない場合は `false` を返します。
+ */
+declare function matchRoutePath(options: MatchRoutePathOptions): boolean;
+/**
+ * 指定されたパターンと対象のパス名が一致するかどうかを判定します。
+ *
+ * @param pattern 照合の基準となるルーティングのパターン文字列です。
+ * @param target 照合対象とする文字列または URL オブジェクトです。
+ * @param options オプションです。
+ * @returns パターンに一致した場合は `true` を、一致しない場合は `false` を返します。
+ */
+declare function matchRoutePath(pattern: MatchRoutePathOptions["pattern"], target: MatchRoutePathOptions["target"], options?: Omit<MatchRoutePathOptions, "pattern" | "target">): boolean;
+export default matchRoutePath;
+//# sourceMappingURL=match-route-path.d.ts.map

package/dist/src/core/match-route-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-route-path.d.ts","sourceRoot":"","sources":["../../../src/core/match-route-path.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF;;;;;GAKG;AACH,iBAAS,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC;AAEjE;;;;;;;GAOG;AACH,iBAAS,cAAc,CACrB,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,EACzC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACvC,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,QAAQ,CAAC,GAC1D,OAAO,CAAC;AAqBX,eAAe,cAAc,CAAC"}

package/dist/src/core/match-route-path.js

@@ -0,0 +1,16 @@
+import { parse } from "regexparam";
+import RoutePath from "./route-path.js";
+function matchRoutePath(...args) {
+    const { target, pattern, allowChild = false, } = typeof args[0] !== "string"
+        ? args[0]
+        : {
+            ...args[2],
+            target: args[1],
+            pattern: args[0],
+        };
+    const patternPathname = new RoutePath(pattern).pathname;
+    const targetPathname = typeof target === "string" ? target : target.pathname;
+    const patternRegex = parse(patternPathname, allowChild).pattern;
+    return patternRegex.test(targetPathname);
+}
+export default matchRoutePath;

package/dist/src/core/route-path.d.ts

@@ -1,10 +1,48 @@
-import type { ReadonlyURL } from "./readonly-url.types.js";
+import type { ReadonlyURL, ReadonlyURLSearchParams } from "./readonly-url.types.js";
 /**
  * アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのクラスです。
  *
  * 内包するホストやプロトコルといった余分な情報を排除し、パス、クエリー、ハッシュのみを一貫した規則で管理します。
  */
-export default class RoutePath {
+export interface ReadonlyRoutePath {
+    /**
+     * 正規化されたパス部分の文字列です。
+     */
+    readonly pathname: string;
+    /**
+     * 先頭に `?` を含むクエリー文字列です。
+     *
+     * 常にソートされます。
+     */
+    readonly search: string;
+    /**
+     * 内部の `URL` インスタンスが保持する、クエリーパラメーターを操作するための `URLSearchParams` オブジェクトを取得します。
+     */
+    readonly searchParams: ReadonlyURLSearchParams;
+    /**
+     * 先頭に `#` を含むハッシュ文字列を取得します。
+     */
+    readonly hash: string;
+    /**
+     * 現在保持しているすべてのコンポーネントを結合し、ルーティング用のパス文字列として出力します。
+     *
+     * @returns ソート済みのクエリーおよびハッシュを含んだ、正規化されたパス全体の文字列を返します。
+     */
+    toString(): string;
+    /**
+     * このインスタンスを複製し、上書き可能な形式で取得します。
+     *
+     * @returns 上書き可能な {@link RoutePath|`RoutePath`} インスタンスです。
+     */
+    clone(): RoutePath;
+}
+/**
+ * アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのクラスです。
+ *
+ * 内包するホストやプロトコルといった余分な情報を排除し、パス、クエリー、ハッシュのみを一貫した規則で管理します。
+ */
+export default class RoutePath implements ReadonlyRoutePath {
+    #private;
     /**
      * 与えられた文字列または URL オブジェクトから、正規化されたパス文字列を即座に生成する静的メソッドです。
      *
@@ -12,12 +50,6 @@ export default class RoutePath {
      * @returns 冗長なスラッシュや末尾のスラッシュが取り除かれた、結合済みのパス文字列を返します。
      */
     static encode(path: string | Pick<ReadonlyURL, "pathname" | "search" | "hash">): string;
-    /**
-     * 内部でパスコンポーネントの解析と検証を委譲するために保持する、組み込みの `URL` インスタンスです。
-     *
-     * 基底となる仮想的なオリジンと結合して管理されます。
-     */
-    private url;
     /**
      * 新しい `RoutePath` インスタンスを初期化します。
      *
@@ -53,5 +85,11 @@ export default class RoutePath {
      * @returns ソート済みのクエリーおよびハッシュを含んだ、正規化されたパス全体の文字列を返します。
      */
     toString(): string;
+    /**
+     * このインスタンスを複製し、上書き可能な形式で取得します。
+     *
+     * @returns 上書き可能な {@link RoutePath|`RoutePath`} インスタンスです。
+     */
+    clone(): RoutePath;
 }
 //# sourceMappingURL=route-path.d.ts.map

package/dist/src/core/route-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-path.d.ts","sourceRoot":"","sources":["../../../src/core/route-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAO3D;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B;;;;;OAKG;WACW,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,MAAM;IAI9F;;;;OAIG;IACH,OAAO,CAAC,GAAG,CAAM;IAEjB;;;;;;OAMG;gBACgB,IAAI,GAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAM;IAkBxF;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,QAAQ,CAAC,KAAK,EAAE,MAAM,EAQhC;IAED;;;;OAIG;IACH,IAAW,MAAM,IAAI,MAAM,CAG1B;IAED,IAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAE9B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,eAAe,CAEzC;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,EAE5B;IAED;;;;OAIG;IACI,QAAQ,IAAI,MAAM;CAI1B"}
+{"version":3,"file":"route-path.d.ts","sourceRoot":"","sources":["../../../src/core/route-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAOpF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,IAAI,MAAM,CAAC;IAEnB;;;;OAIG;IACH,KAAK,IAAI,SAAS,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,SAAU,YAAW,iBAAiB;;IACzD;;;;;OAKG;WACW,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,MAAM;IAW9F;;;;;;OAMG;gBACgB,IAAI,GAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAM;IAkBxF;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,QAAQ,CAAC,KAAK,EAAE,MAAM,EAQhC;IAED;;;;OAIG;IACH,IAAW,MAAM,IAAI,MAAM,CAG1B;IAED,IAAW,MAAM,CAAC,KAAK,EAAE,MAAM,EAE9B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,eAAe,CAEzC;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,EAE5B;IAED;;;;OAIG;IACI,QAAQ,IAAI,MAAM;IAKzB;;;;OAIG;IACI,KAAK,IAAI,SAAS;CAG1B"}

package/dist/src/core/route-path.js

@@ -1,3 +1,15 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _RoutePath_url;
 /**
  * 連続する複数のスラッシュを検出するための正規表現です。
  */
@@ -7,7 +19,7 @@ const MULTI_SLASH = /\/\/+/gu;
  *
  * 内包するホストやプロトコルといった余分な情報を排除し、パス、クエリー、ハッシュのみを一貫した規則で管理します。
  */
-export default class RoutePath {
+class RoutePath {
     /**
      * 与えられた文字列または URL オブジェクトから、正規化されたパス文字列を即座に生成する静的メソッドです。
      *
@@ -25,6 +37,12 @@ export default class RoutePath {
      * @param path 初期化に使用するパス文字列、または `ReadonlyURL` の一部のプロパティーを持つオブジェクトです。既定値は空文字列です。
      */
     constructor(path = "") {
+        /**
+         * 内部でパスコンポーネントの解析と検証を委譲するために保持する、組み込みの `URL` インスタンスです。
+         *
+         * 基底となる仮想的なオリジンと結合して管理されます。
+         */
+        _RoutePath_url.set(this, void 0);
         if (typeof path === "string") {
             path = ("/" + path).replace(MULTI_SLASH, "/");
         }
@@ -33,25 +51,25 @@ export default class RoutePath {
             path = ("/" + pathname).replace(MULTI_SLASH, "/") + search + hash;
         }
         // 組み込みの URL クラスによる厳密な解析機能を利用するため、仮想のプロトコルとホストを前置きして初期化します。
-        this.url = new URL("x://y" + path);
+        __classPrivateFieldSet(this, _RoutePath_url, new URL("x://y" + path), "f");
         // ルートパス（/）単体である場合を除き、末尾に存在する不要なスラッシュを削除して一貫性を保ちます。
-        const { pathname } = this.url;
+        const { pathname } = __classPrivateFieldGet(this, _RoutePath_url, "f");
         if (pathname !== "/" && pathname.endsWith("/")) {
-            this.url.pathname = pathname.substring(0, pathname.length - 1);
+            __classPrivateFieldGet(this, _RoutePath_url, "f").pathname = pathname.substring(0, pathname.length - 1);
         }
     }
     /**
      * 正規化されたパス部分の文字列です。
      */
     get pathname() {
-        return this.url.pathname;
+        return __classPrivateFieldGet(this, _RoutePath_url, "f").pathname;
     }
     set pathname(value) {
-        this.url.pathname = value;
+        __classPrivateFieldGet(this, _RoutePath_url, "f").pathname = value;
         // ルートパス（/）単体である場合を除き、末尾に存在する不要なスラッシュを削除して一貫性を保ちます。
-        const pathname = ("/" + this.url.pathname).replace(MULTI_SLASH, "/");
+        const pathname = ("/" + __classPrivateFieldGet(this, _RoutePath_url, "f").pathname).replace(MULTI_SLASH, "/");
         if (pathname !== "/" && pathname.endsWith("/")) {
-            this.url.pathname = pathname.substring(0, pathname.length - 1);
+            __classPrivateFieldGet(this, _RoutePath_url, "f").pathname = pathname.substring(0, pathname.length - 1);
         }
     }
     /**
@@ -60,26 +78,26 @@ export default class RoutePath {
      * 常にソートされます。
      */
     get search() {
-        this.url.searchParams.sort();
-        return this.url.search;
+        __classPrivateFieldGet(this, _RoutePath_url, "f").searchParams.sort();
+        return __classPrivateFieldGet(this, _RoutePath_url, "f").search;
     }
     set search(value) {
-        this.url.search = value;
+        __classPrivateFieldGet(this, _RoutePath_url, "f").search = value;
     }
     /**
      * 内部の `URL` インスタンスが保持する、クエリーパラメーターを操作するための `URLSearchParams` オブジェクトを取得します。
      */
     get searchParams() {
-        return this.url.searchParams;
+        return __classPrivateFieldGet(this, _RoutePath_url, "f").searchParams;
     }
     /**
      * 先頭に `#` を含むハッシュ文字列を取得します。
      */
     get hash() {
-        return this.url.hash;
+        return __classPrivateFieldGet(this, _RoutePath_url, "f").hash;
     }
     set hash(value) {
-        this.url.hash = value;
+        __classPrivateFieldGet(this, _RoutePath_url, "f").hash = value;
     }
     /**
      * 現在保持しているすべてのコンポーネントを結合し、ルーティング用のパス文字列として出力します。
@@ -90,4 +108,14 @@ export default class RoutePath {
         const { hash, search, pathname } = this;
         return pathname + search + hash;
     }
+    /**
+     * このインスタンスを複製し、上書き可能な形式で取得します。
+     *
+     * @returns 上書き可能な {@link RoutePath|`RoutePath`} インスタンスです。
+     */
+    clone() {
+        return new RoutePath(this.toString());
+    }
 }
+_RoutePath_url = new WeakMap();
+export default RoutePath;

package/dist/src/core.d.ts

@@ -22,4 +22,9 @@ export type * from "./core/start-action.js";
 export { default as startAction } from "./core/start-action.js";
 export type * from "./core/start-loaders.js";
 export { default as startLoaders } from "./core/start-loaders.js";
+/**************************************************************************************************/
+export type * from "./hooks/use-route-context.js";
+export { default as useRouteContext } from "./hooks/use-route-context.js";
+export type * from "./hooks/use-router-context.js";
+export { default as useRouterContext } from "./hooks/use-router-context.js";
 //# sourceMappingURL=core.d.ts.map

package/dist/src/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oGAAoG;AAEpG,mBAAmB,6BAA6B,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEtE,mBAAmB,8BAA8B,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAExE,oGAAoG;AAEpG,mBAAmB,gCAAgC,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAE/E,mBAAmB,mCAAmC,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEpF,mBAAmB,oCAAoC,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEtF,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oGAAoG;AAEpG,mBAAmB,6BAA6B,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEtE,mBAAmB,8BAA8B,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAExE,oGAAoG;AAEpG,mBAAmB,gCAAgC,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAE/E,mBAAmB,mCAAmC,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEpF,mBAAmB,oCAAoC,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEtF,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEhE,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAElE,oGAAoG;AAEpG,mBAAmB,8BAA8B,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE1E,mBAAmB,+BAA+B,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/src/core.js

@@ -9,3 +9,5 @@ export { default as matchRoutes } from "./core/match-routes.js";
 export { default as RoutePath } from "./core/route-path.js";
 export { default as startAction } from "./core/start-action.js";
 export { default as startLoaders } from "./core/start-loaders.js";
+export { default as useRouteContext } from "./hooks/use-route-context.js";
+export { default as useRouterContext } from "./hooks/use-router-context.js";

package/dist/src/engines/engine.types.d.ts

@@ -1,4 +1,5 @@
 import type { NinjaPromise } from "ninja-promise";
+import type { RoutePath } from "../core.js";
 import type { HistoryEntry } from "../core/expect-history-entry.js";
 import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
 import type { MatchedRoute } from "../core/match-routes.js";
@@ -151,28 +152,22 @@ export declare namespace IEngine {
             /**
              * URL パスで前方移動する形式です。
              */
-            type: "PATH";
+            type: "STATIC";
             /**
              * URL パスです。
              */
             path: string;
         } | {
             /**
-             * URL の各コンポーネントを個別に指定する形式です。
+             * URL の各コンポーネントを関数形式で個別に指定する形式です。
              */
-            type: "PARTIAL";
+            type: "DYNAMIC";
             /**
-             * 最初のスラッシュ `/` から始まる URL のパス部分です。
-             */
-            pathname?: string | undefined;
-            /**
-             * 先頭のクエスチョンマーク `?` を含む URL のクエリー文字列です。
-             */
-            search?: string | undefined;
-            /**
-             * URL のハッシュ（シャープ記号 `#` を含むフラグメント識別子）です。
+             * 動的にパッチを適用する関数です。
+             *
+             * @param path アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのオブジェクトです。
              */
-            hash?: string | undefined;
+            patch(path: RoutePath): void;
         };
         /**
          * 履歴スタックへの追加方法を指定します。

package/dist/src/engines/engine.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.types.d.ts","sourceRoot":"","sources":["../../../src/engines/engine.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.types.d.ts","sourceRoot":"","sources":["../../../src/engines/engine.types.ts"],"names":[],"mappings":"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"}

package/dist/src/engines/navigation-api-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-api-engine.d.ts","sourceRoot":"","sources":["../../../src/engines/navigation-api-engine.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,YAAW,OAAO;IACzD;;OAEG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAAsB;IAEhD;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;;OAIG;;IAwBH;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,UAAU;IA2BhD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,WAAW;IAgSnD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,GAAG,IAAI;IAkCtC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,GAAG,IAAI;CAwE3C"}
+{"version":3,"file":"navigation-api-engine.d.ts","sourceRoot":"","sources":["../../../src/engines/navigation-api-engine.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,YAAW,OAAO;IACzD;;OAEG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAAsB;IAEhD;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;;OAIG;;IAwBH;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,UAAU;IA2BhD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,WAAW;IA8RnD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,GAAG,IAAI;IAkCtC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,GAAG,IAAI;CAgE3C"}

package/dist/src/engines/navigation-api-engine.js

@@ -78,8 +78,7 @@ export default class NavigationApiEngine {
          * ユーザーのアクションによって発生したすべての遷移要求をインターセプトして処理する、ルーティングの中枢ハンドラーです。
          */
         const handleNavigate = (event) => {
-            // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、
-            // 標準の挙動を妨げないようにインターセプトせず即座にスルーします。
+            // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、標準の挙動を妨げないようにインターセプトせず即座にスルーします。
             // 参照: https://developer.mozilla.org/docs/Web/API/Navigation_API#handling_a_navigation_using_intercept
             if (!event.isTrusted ||
                 !event.canIntercept ||
@@ -146,19 +145,18 @@ export default class NavigationApiEngine {
                     switch (action.data.status) {
                         case "rejected": {
                             // アクションがエラーで失敗した場合は、URL を変更せず現在の元のページに強制リダイレクトさせます。
-                            const { pathname, search, hash } = currentEntry.url;
-                            controller.redirect(pathname + search + hash);
+                            controller.redirect(RoutePath.encode(currentEntry.url));
                             break;
                         }
                         case "fulfilled": {
                             // アクションが正常終了した場合、返り値にリダイレクト指示が含まれていればその目的地へ遷移させます。
                             // リダイレクトがなければそのまま本来の目的地へとブラウザーのコミット先を書き換えます。
                             const { redirectTo = currentEntry.url } = actionResponse;
-                            const { pathname, search, hash } = redirectTo;
-                            controller.redirect(pathname + search + hash);
-                            redirectUrl.pathname = pathname;
-                            redirectUrl.search = search;
-                            redirectUrl.hash = hash;
+                            const redirectPath = new RoutePath(redirectTo);
+                            controller.redirect(redirectPath.toString());
+                            redirectUrl.pathname = redirectPath.pathname;
+                            redirectUrl.search = redirectPath.search;
+                            redirectUrl.hash = redirectPath.hash;
                             break;
                         }
                         default:
@@ -356,28 +354,21 @@ export default class NavigationApiEngine {
             case "LINK": {
                 const { to, history } = args;
                 switch (to.type) {
-                    case "PATH": {
+                    case "STATIC": {
                         // 完全なパス文字列の余分なスラッシュなどをエンコードして直接遷移します。
                         const path = RoutePath.encode(to.path);
                         this.navigation.navigate(path, { history });
                         break;
                     }
-                    case "PARTIAL": {
-                        // 現在のロケーション情報をベースに、指定されたパーツ（パス名、クエリー、ハッシュのみなど）を部分的にパッチ（上書き）したマージ URL を算出します。
+                    case "DYNAMIC": {
+                        // 現在のロケーション情報をベースに、指定されたパーツ（パス名、クエリー、ハッシュのみなど）を部分的に上書きしたマージ URL を算出します。
                         const currentPath = new RoutePath(window.location);
-                        const nextPath = new RoutePath(window.location);
-                        if (typeof to.pathname === "string") {
-                            nextPath.pathname = to.pathname;
-                        }
-                        if (typeof to.search === "string") {
-                            nextPath.search = to.search;
-                        }
-                        if (typeof to.hash === "string") {
-                            nextPath.hash = to.hash;
-                        }
+                        const currentPathString = currentPath.toString();
+                        const nextPath = currentPath;
+                        to.patch(nextPath);
                         const nextPathString = nextPath.toString();
                         // 無駄な遷移履歴を作らないように、URL に実際の変化がある場合のみ navigate を実行します。
-                        if (nextPathString !== currentPath.toString()) {
+                        if (nextPathString !== currentPathString) {
                             this.navigation.navigate(nextPathString, { history });
                         }
                         break;

package/dist/src/hooks/use-navigate.d.ts

@@ -1,3 +1,4 @@
+import type { RoutePath } from "../core.js";
 /**
  * 遷移先のアドレスを指定するための表現型です。
  *
@@ -16,6 +17,13 @@ export type NavigateTo = string | {
      * 遷移先に付与するハッシュフラグメント（例: `"#profile"`）です。
      */
     readonly hash?: string | undefined;
+} | {
+    /**
+     * 動的にパッチを適用します。
+     *
+     * @param path アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのオブジェクトです。
+     */
+    (route: RoutePath): void;
 };
 /**
  * 画面遷移の挙動をカスタマイズするためのオプション型です。

package/dist/src/hooks/use-navigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-navigate.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-navigate.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN;IACE;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAElD;;;;OAIG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,IAAI,gBAAgB,CAwCtD"}
+{"version":3,"file":"use-navigate.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-navigate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN;IACE;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,GACD;IACE;;;;OAIG;IACH,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAElD;;;;OAIG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,IAAI,gBAAgB,CA6DtD"}

package/dist/src/hooks/use-navigate.js

@@ -23,7 +23,27 @@ export default function useNavigate() {
             return routerNavigate({
                 to: {
                     path: to,
-                    type: "PATH",
+                    type: "STATIC",
+                },
+                type: "LINK",
+                history,
+            });
+        }
+        else if (typeof to === "object") {
+            return routerNavigate({
+                to: {
+                    type: "DYNAMIC",
+                    patch(path) {
+                        if (typeof to.pathname === "string") {
+                            path.pathname = to.pathname;
+                        }
+                        if (typeof to.search === "string") {
+                            path.search = to.search;
+                        }
+                        if (typeof to.hash === "string") {
+                            path.hash = to.hash;
+                        }
+                    },
                 },
                 type: "LINK",
                 history,
@@ -32,8 +52,10 @@ export default function useNavigate() {
         else {
             return routerNavigate({
                 to: {
-                    ...to,
-                    type: "PARTIAL",
+                    type: "DYNAMIC",
+                    patch(path) {
+                        to(path);
+                    },
                 },
                 type: "LINK",
                 history,

package/dist/src/hooks/use-route-path.d.ts

@@ -0,0 +1,3 @@
+import { type ReadonlyRoutePath } from "../core/route-path.js";
+export default function useRoutePath(): ReadonlyRoutePath;
+//# sourceMappingURL=use-route-path.d.ts.map

package/dist/src/hooks/use-route-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-route-path.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-route-path.ts"],"names":[],"mappings":"AAEA,OAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1E,MAAM,CAAC,OAAO,UAAU,YAAY,IAAI,iBAAiB,CAKxD"}

package/dist/src/hooks/use-route-path.js

@@ -0,0 +1,8 @@
+import * as React from "react";
+import RoutePath from "../core/route-path.js";
+import useRouterContext from "./use-router-context.js";
+export default function useRoutePath() {
+    const url = useRouterContext((router) => router.currentEntry.url);
+    const path = React.useMemo(() => new RoutePath(url), [url]);
+    return path;
+}

package/dist/src/soseki.d.ts

@@ -5,6 +5,8 @@ export { default as Outlet } from "./components/outlet.jsx";
 /**************************************************************************************************/
 export type { Issue, UnreachableErrorArgs, UnreachableErrorMeta, LoaderConditionErrorArgs, LoaderConditionErrorMeta, LoaderDataNotFoundErrorArgs, LoaderDataNotFoundErrorMeta, UnexpectedValidationErrorArgs, UnexpectedValidationErrorMeta, } from "./core/errors.js";
 export { ErrorBase, setErrorMessage, UnreachableError, ValidationErrorBase, LoaderConditionError, LoaderDataNotFoundError, RouteContextMissingError, RouterContextMissingError, UnexpectedValidationError, NavigationApiNotSupportedError, } from "./core/errors.js";
+export type * from "./core/match-route-path.js";
+export { default as matchRoutePath } from "./core/match-route-path.js";
 export type * from "./core/readonly-form-data.types.js";
 export type * from "./core/readonly-url.types.js";
 export type * from "./core/redirect-response.js";
@@ -23,6 +25,8 @@ export type * from "./hooks/use-navigate.js";
 export { default as useNavigate } from "./hooks/use-navigate.js";
 export type * from "./hooks/use-params.js";
 export { default as useParams } from "./hooks/use-params.js";
+export type * from "./hooks/use-route-path.js";
+export { default as useRoutePath } from "./hooks/use-route-path.js";
 export type * from "./hooks/use-submit.js";
 export { default as useSubmit } from "./hooks/use-submit.js";
 /**************************************************************************************************/

package/dist/src/soseki.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"soseki.d.ts","sourceRoot":"","sources":["../../src/soseki.ts"],"names":[],"mappings":"AAAA,mBAAmB,iCAAiC,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAE3E,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oGAAoG;AAEpG,YAAY,EACV,KAAK,EACL,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,mBAAmB,oCAAoC,CAAC;AAExD,mBAAmB,8BAA8B,CAAC;AAElD,mBAAmB,6BAA6B,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAElE,mBAAmB,uBAAuB,CAAC;AAE3C,oGAAoG;AAEpG,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEjE,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE7D,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE7D,oGAAoG;AAEpG,mBAAmB,qBAAqB,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"soseki.d.ts","sourceRoot":"","sources":["../../src/soseki.ts"],"names":[],"mappings":"AAAA,mBAAmB,iCAAiC,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAE3E,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oGAAoG;AAEpG,YAAY,EACV,KAAK,EACL,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEvE,mBAAmB,oCAAoC,CAAC;AAExD,mBAAmB,8BAA8B,CAAC;AAElD,mBAAmB,6BAA6B,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAElE,mBAAmB,uBAAuB,CAAC;AAE3C,oGAAoG;AAEpG,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,4BAA4B,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,yBAAyB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEjE,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE7D,mBAAmB,2BAA2B,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEpE,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE7D,oGAAoG;AAEpG,mBAAmB,qBAAqB,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/soseki.js

@@ -1,6 +1,7 @@
 export { default as BrowserRouter } from "./components/browser-router.jsx";
 export { default as Outlet } from "./components/outlet.jsx";
 export { ErrorBase, setErrorMessage, UnreachableError, ValidationErrorBase, LoaderConditionError, LoaderDataNotFoundError, RouteContextMissingError, RouterContextMissingError, UnexpectedValidationError, NavigationApiNotSupportedError, } from "./core/errors.js";
+export { default as matchRoutePath } from "./core/match-route-path.js";
 export { default as RedirectResponse } from "./core/redirect-response.js";
 export { default as RouteRequest } from "./core/route-request.js";
 export { default as useActionData } from "./hooks/use-action-data.js";
@@ -8,5 +9,6 @@ export { default as useFormAction } from "./hooks/use-form-action.js";
 export { default as useLoaderData } from "./hooks/use-loader-data.js";
 export { default as useNavigate } from "./hooks/use-navigate.js";
 export { default as useParams } from "./hooks/use-params.js";
+export { default as useRoutePath } from "./hooks/use-route-path.js";
 export { default as useSubmit } from "./hooks/use-submit.js";
 export { default as redirect } from "./utils/redirect.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soseki",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "",
   "homepage": "https://github.com/tai-kun/soseki.js",
   "license": "MIT",

package/src/components/browser-router.tsx

@@ -1,7 +1,6 @@
-import type { RouteDefinition } from "../core/route.types.js";
 import NavigationApiEngine from "../engines/navigation-api-engine.js";
 import useSingleton from "../hooks/_use-singleton.js";
-import Router from "./router.jsx";
+import Router, { type RouterRouteDefinition } from "./router.jsx";
 
 /**
  * `BrowserRouter` コンポーネントに引き渡すプロパティーの型定義です。
@@ -10,7 +9,7 @@ export type BrowserRouterProps = {
   /**
    * アプリケーション全体の画面構造を定義したルート定義の配列です。
    */
-  routes: readonly RouteDefinition[];
+  routes: readonly RouterRouteDefinition[];
 };
 
 /**

package/src/components/router.tsx

@@ -10,7 +10,7 @@ import processRoutes from "../core/_process-routes.js";
 import type { HistoryEntry } from "../core/expect-history-entry.js";
 import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
 import type { MatchedRoute } from "../core/match-routes.js";
-import type { ActionFunction, LoaderFunction, RouteDefinition } from "../core/route.types.js";
+import type { ActionFunction, LoaderFunction } from "../core/route.types.js";
 import type { IEngine, RouterState } from "../engines/engine.types.js";
 
 /**
@@ -77,6 +77,28 @@ function RouteRenderer(props: RouteRendererProps): React.ReactElement {
   return <ComponentRenderer route={route} outlet={outlet} />;
 }
 
+export type RouterRouteDefinitionObject = {
+  readonly path: string;
+  readonly index?: boolean | undefined;
+  readonly action?: { (args: any): unknown } | undefined;
+  readonly shouldReload?: { (args: any): boolean } | undefined;
+  readonly loader?: { (args: any): unknown } | undefined;
+  readonly component?: React.ComponentType<{}> | undefined;
+};
+
+export type RouterRouteDefinitionModule = {
+  readonly path: string;
+  readonly index?: boolean | undefined;
+  readonly action?: { (args: any): unknown } | undefined;
+  readonly shouldReload?: { (args: any): boolean } | undefined;
+  readonly loader?: { (args: any): unknown } | undefined;
+  readonly component?: React.ComponentType<{}> | undefined;
+  readonly default?: React.ComponentType<{}> | undefined;
+  get [Symbol.toStringTag](): string;
+};
+
+export type RouterRouteDefinition = RouterRouteDefinitionObject | RouterRouteDefinitionModule;
+
 /**
  * `Router` コンポーネントに渡されるルートプロパティーの型定義です。
  */
@@ -89,7 +111,7 @@ export type RouterProps = {
   /**
    * ユーザーがアプリケーションに定義したルート定義の配列です。
    */
-  routes: readonly RouteDefinition[];
+  routes: readonly RouterRouteDefinition[];
 };
 
 /**

package/src/core/match-route-path.ts

@@ -0,0 +1,78 @@
+import { parse } from "regexparam";
+
+import RoutePath from "./route-path.js";
+
+/**
+ * ルーティングの照合対象となる URL 情報を表すインターフェースです。
+ */
+export interface MatchRoutePathTargetURL {
+  /**
+   * 照合対象のパス名です。
+   */
+  readonly pathname: string;
+}
+
+/**
+ * `matchRoutePath` 関数の動作を設定するための型定義です。
+ */
+export type MatchRoutePathOptions = {
+  /**
+   * 照合の基準となるルーティングのパターン文字列です。
+   */
+  readonly pattern: string;
+
+  /**
+   * 照合対象とする文字列または URL オブジェクトです。
+   */
+  readonly target: string | MatchRoutePathTargetURL;
+
+  /**
+   * 子ディレクトリーへの前方一致を許可するかどうかを制御するフラグです。
+   *
+   * @default false
+   */
+  readonly allowChild?: boolean | undefined;
+};
+
+/**
+ * 指定されたパターンと対象のパス名が一致するかどうかを判定します。
+ *
+ * @param options パターン、対象、および一致条件を含む設定オブジェクトです。
+ * @returns パターンに一致した場合は `true` を、一致しない場合は `false` を返します。
+ */
+function matchRoutePath(options: MatchRoutePathOptions): boolean;
+
+/**
+ * 指定されたパターンと対象のパス名が一致するかどうかを判定します。
+ *
+ * @param pattern 照合の基準となるルーティングのパターン文字列です。
+ * @param target 照合対象とする文字列または URL オブジェクトです。
+ * @param options オプションです。
+ * @returns パターンに一致した場合は `true` を、一致しない場合は `false` を返します。
+ */
+function matchRoutePath(
+  pattern: MatchRoutePathOptions["pattern"],
+  target: MatchRoutePathOptions["target"],
+  options?: Omit<MatchRoutePathOptions, "pattern" | "target">,
+): boolean;
+
+function matchRoutePath(...args: any): boolean {
+  const {
+    target,
+    pattern,
+    allowChild = false,
+  }: MatchRoutePathOptions = typeof args[0] !== "string"
+    ? args[0]
+    : {
+        ...args[2],
+        target: args[1],
+        pattern: args[0],
+      };
+  const patternPathname = new RoutePath(pattern).pathname;
+  const targetPathname = typeof target === "string" ? target : target.pathname;
+  const patternRegex = parse(patternPathname, allowChild).pattern;
+
+  return patternRegex.test(targetPathname);
+}
+
+export default matchRoutePath;

package/src/core/route-path.ts

@@ -1,4 +1,4 @@
-import type { ReadonlyURL } from "./readonly-url.types.js";
+import type { ReadonlyURL, ReadonlyURLSearchParams } from "./readonly-url.types.js";
 
 /**
  * 連続する複数のスラッシュを検出するための正規表現です。
@@ -10,7 +10,50 @@ const MULTI_SLASH = /\/\/+/gu;
  *
  * 内包するホストやプロトコルといった余分な情報を排除し、パス、クエリー、ハッシュのみを一貫した規則で管理します。
  */
-export default class RoutePath {
+export interface ReadonlyRoutePath {
+  /**
+   * 正規化されたパス部分の文字列です。
+   */
+  readonly pathname: string;
+
+  /**
+   * 先頭に `?` を含むクエリー文字列です。
+   *
+   * 常にソートされます。
+   */
+  readonly search: string;
+
+  /**
+   * 内部の `URL` インスタンスが保持する、クエリーパラメーターを操作するための `URLSearchParams` オブジェクトを取得します。
+   */
+  readonly searchParams: ReadonlyURLSearchParams;
+
+  /**
+   * 先頭に `#` を含むハッシュ文字列を取得します。
+   */
+  readonly hash: string;
+
+  /**
+   * 現在保持しているすべてのコンポーネントを結合し、ルーティング用のパス文字列として出力します。
+   *
+   * @returns ソート済みのクエリーおよびハッシュを含んだ、正規化されたパス全体の文字列を返します。
+   */
+  toString(): string;
+
+  /**
+   * このインスタンスを複製し、上書き可能な形式で取得します。
+   *
+   * @returns 上書き可能な {@link RoutePath|`RoutePath`} インスタンスです。
+   */
+  clone(): RoutePath;
+}
+
+/**
+ * アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのクラスです。
+ *
+ * 内包するホストやプロトコルといった余分な情報を排除し、パス、クエリー、ハッシュのみを一貫した規則で管理します。
+ */
+export default class RoutePath implements ReadonlyRoutePath {
   /**
    * 与えられた文字列または URL オブジェクトから、正規化されたパス文字列を即座に生成する静的メソッドです。
    *
@@ -26,7 +69,7 @@ export default class RoutePath {
    *
    * 基底となる仮想的なオリジンと結合して管理されます。
    */
-  private url: URL;
+  readonly #url: URL;
 
   /**
    * 新しい `RoutePath` インスタンスを初期化します。
@@ -44,12 +87,12 @@ export default class RoutePath {
     }
 
     // 組み込みの URL クラスによる厳密な解析機能を利用するため、仮想のプロトコルとホストを前置きして初期化します。
-    this.url = new URL("x://y" + path);
+    this.#url = new URL("x://y" + path);
 
     // ルートパス（/）単体である場合を除き、末尾に存在する不要なスラッシュを削除して一貫性を保ちます。
-    const { pathname } = this.url;
+    const { pathname } = this.#url;
     if (pathname !== "/" && pathname.endsWith("/")) {
-      this.url.pathname = pathname.substring(0, pathname.length - 1);
+      this.#url.pathname = pathname.substring(0, pathname.length - 1);
     }
   }
 
@@ -57,16 +100,16 @@ export default class RoutePath {
    * 正規化されたパス部分の文字列です。
    */
   public get pathname(): string {
-    return this.url.pathname;
+    return this.#url.pathname;
   }
 
   public set pathname(value: string) {
-    this.url.pathname = value;
+    this.#url.pathname = value;
 
     // ルートパス（/）単体である場合を除き、末尾に存在する不要なスラッシュを削除して一貫性を保ちます。
-    const pathname = ("/" + this.url.pathname).replace(MULTI_SLASH, "/");
+    const pathname = ("/" + this.#url.pathname).replace(MULTI_SLASH, "/");
     if (pathname !== "/" && pathname.endsWith("/")) {
-      this.url.pathname = pathname.substring(0, pathname.length - 1);
+      this.#url.pathname = pathname.substring(0, pathname.length - 1);
     }
   }
 
@@ -76,30 +119,30 @@ export default class RoutePath {
    * 常にソートされます。
    */
   public get search(): string {
-    this.url.searchParams.sort();
-    return this.url.search;
+    this.#url.searchParams.sort();
+    return this.#url.search;
   }
 
   public set search(value: string) {
-    this.url.search = value;
+    this.#url.search = value;
   }
 
   /**
    * 内部の `URL` インスタンスが保持する、クエリーパラメーターを操作するための `URLSearchParams` オブジェクトを取得します。
    */
   public get searchParams(): URLSearchParams {
-    return this.url.searchParams;
+    return this.#url.searchParams;
   }
 
   /**
    * 先頭に `#` を含むハッシュ文字列を取得します。
    */
   public get hash(): string {
-    return this.url.hash;
+    return this.#url.hash;
   }
 
   public set hash(value: string) {
-    this.url.hash = value;
+    this.#url.hash = value;
   }
 
   /**
@@ -111,4 +154,13 @@ export default class RoutePath {
     const { hash, search, pathname } = this;
     return pathname + search + hash;
   }
+
+  /**
+   * このインスタンスを複製し、上書き可能な形式で取得します。
+   *
+   * @returns 上書き可能な {@link RoutePath|`RoutePath`} インスタンスです。
+   */
+  public clone(): RoutePath {
+    return new RoutePath(this.toString());
+  }
 }

package/src/core.ts

@@ -34,3 +34,11 @@ export { default as startAction } from "./core/start-action.js";
 
 export type * from "./core/start-loaders.js";
 export { default as startLoaders } from "./core/start-loaders.js";
+
+/**************************************************************************************************/
+
+export type * from "./hooks/use-route-context.js";
+export { default as useRouteContext } from "./hooks/use-route-context.js";
+
+export type * from "./hooks/use-router-context.js";
+export { default as useRouterContext } from "./hooks/use-router-context.js";

package/src/engines/engine.types.ts

@@ -1,5 +1,6 @@
 import type { NinjaPromise } from "ninja-promise";
 
+import type { RoutePath } from "../core.js";
 import type { HistoryEntry } from "../core/expect-history-entry.js";
 import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
 import type { MatchedRoute } from "../core/match-routes.js";
@@ -178,7 +179,7 @@ export namespace IEngine {
               /**
                * URL パスで前方移動する形式です。
                */
-              type: "PATH";
+              type: "STATIC";
 
               /**
                * URL パスです。
@@ -187,24 +188,16 @@ export namespace IEngine {
             }
           | {
               /**
-               * URL の各コンポーネントを個別に指定する形式です。
+               * URL の各コンポーネントを関数形式で個別に指定する形式です。
                */
-              type: "PARTIAL";
+              type: "DYNAMIC";
 
               /**
-               * 最初のスラッシュ `/` から始まる URL のパス部分です。
+               * 動的にパッチを適用する関数です。
+               *
+               * @param path アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのオブジェクトです。
                */
-              pathname?: string | undefined;
-
-              /**
-               * 先頭のクエスチョンマーク `?` を含む URL のクエリー文字列です。
-               */
-              search?: string | undefined;
-
-              /**
-               * URL のハッシュ（シャープ記号 `#` を含むフラグメント識別子）です。
-               */
-              hash?: string | undefined;
+              patch(path: RoutePath): void;
             };
 
         /**

package/src/engines/navigation-api-engine.ts

@@ -105,8 +105,7 @@ export default class NavigationApiEngine implements IEngine {
      * ユーザーのアクションによって発生したすべての遷移要求をインターセプトして処理する、ルーティングの中枢ハンドラーです。
      */
     const handleNavigate = (event: NavigateEvent): void => {
-      // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、
-      // 標準の挙動を妨げないようにインターセプトせず即座にスルーします。
+      // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、標準の挙動を妨げないようにインターセプトせず即座にスルーします。
       // 参照: https://developer.mozilla.org/docs/Web/API/Navigation_API#handling_a_navigation_using_intercept
       if (
         !event.isTrusted ||
@@ -187,8 +186,7 @@ export default class NavigationApiEngine implements IEngine {
           switch (action.data.status) {
             case "rejected": {
               // アクションがエラーで失敗した場合は、URL を変更せず現在の元のページに強制リダイレクトさせます。
-              const { pathname, search, hash } = currentEntry.url;
-              controller.redirect(pathname + search + hash);
+              controller.redirect(RoutePath.encode(currentEntry.url));
 
               break;
             }
@@ -197,12 +195,12 @@ export default class NavigationApiEngine implements IEngine {
               // アクションが正常終了した場合、返り値にリダイレクト指示が含まれていればその目的地へ遷移させます。
               // リダイレクトがなければそのまま本来の目的地へとブラウザーのコミット先を書き換えます。
               const { redirectTo = currentEntry.url } = actionResponse;
-              const { pathname, search, hash } = redirectTo;
-              controller.redirect(pathname + search + hash);
+              const redirectPath = new RoutePath(redirectTo);
+              controller.redirect(redirectPath.toString());
 
-              redirectUrl.pathname = pathname;
-              redirectUrl.search = search;
-              redirectUrl.hash = hash;
+              redirectUrl.pathname = redirectPath.pathname;
+              redirectUrl.search = redirectPath.search;
+              redirectUrl.hash = redirectPath.hash;
 
               break;
             }
@@ -435,7 +433,7 @@ export default class NavigationApiEngine implements IEngine {
       case "LINK": {
         const { to, history } = args;
         switch (to.type) {
-          case "PATH": {
+          case "STATIC": {
             // 完全なパス文字列の余分なスラッシュなどをエンコードして直接遷移します。
 
             const path = RoutePath.encode(to.path);
@@ -444,25 +442,17 @@ export default class NavigationApiEngine implements IEngine {
             break;
           }
 
-          case "PARTIAL": {
-            // 現在のロケーション情報をベースに、指定されたパーツ（パス名、クエリー、ハッシュのみなど）を部分的にパッチ（上書き）したマージ URL を算出します。
+          case "DYNAMIC": {
+            // 現在のロケーション情報をベースに、指定されたパーツ（パス名、クエリー、ハッシュのみなど）を部分的に上書きしたマージ URL を算出します。
 
             const currentPath = new RoutePath(window.location);
-            const nextPath = new RoutePath(window.location);
-            if (typeof to.pathname === "string") {
-              nextPath.pathname = to.pathname;
-            }
-            if (typeof to.search === "string") {
-              nextPath.search = to.search;
-            }
-            if (typeof to.hash === "string") {
-              nextPath.hash = to.hash;
-            }
-
+            const currentPathString = currentPath.toString();
+            const nextPath = currentPath;
+            to.patch(nextPath);
             const nextPathString = nextPath.toString();
 
             // 無駄な遷移履歴を作らないように、URL に実際の変化がある場合のみ navigate を実行します。
-            if (nextPathString !== currentPath.toString()) {
+            if (nextPathString !== currentPathString) {
               this.navigation.navigate(nextPathString, { history });
             }
 

package/src/hooks/use-navigate.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
 
-import type {} from "../engines/engine.types.js";
+import type { RoutePath } from "../core.js";
 import useRouterContext from "./use-router-context.js";
 
 /**
@@ -25,6 +25,14 @@ export type NavigateTo =
        * 遷移先に付与するハッシュフラグメント（例: `"#profile"`）です。
        */
       readonly hash?: string | undefined;
+    }
+  | {
+      /**
+       * 動的にパッチを適用します。
+       *
+       * @param path アプリケーション内のルーティングにおけるパスを安全に構築・解析・操作するためのオブジェクトです。
+       */
+      (route: RoutePath): void;
     };
 
 /**
@@ -84,7 +92,26 @@ export default function useNavigate(): NavigateFunction {
         return routerNavigate({
           to: {
             path: to,
-            type: "PATH",
+            type: "STATIC",
+          },
+          type: "LINK",
+          history,
+        });
+      } else if (typeof to === "object") {
+        return routerNavigate({
+          to: {
+            type: "DYNAMIC",
+            patch(path) {
+              if (typeof to.pathname === "string") {
+                path.pathname = to.pathname;
+              }
+              if (typeof to.search === "string") {
+                path.search = to.search;
+              }
+              if (typeof to.hash === "string") {
+                path.hash = to.hash;
+              }
+            },
           },
           type: "LINK",
           history,
@@ -92,8 +119,10 @@ export default function useNavigate(): NavigateFunction {
       } else {
         return routerNavigate({
           to: {
-            ...to,
-            type: "PARTIAL",
+            type: "DYNAMIC",
+            patch(path) {
+              to(path);
+            },
           },
           type: "LINK",
           history,

package/src/hooks/use-route-path.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+
+import RoutePath, { type ReadonlyRoutePath } from "../core/route-path.js";
+import useRouterContext from "./use-router-context.js";
+
+export default function useRoutePath(): ReadonlyRoutePath {
+  const url = useRouterContext((router) => router.currentEntry.url);
+  const path = React.useMemo(() => new RoutePath(url), [url]);
+
+  return path;
+}

package/src/soseki.ts

@@ -30,6 +30,9 @@ export {
   NavigationApiNotSupportedError,
 } from "./core/errors.js";
 
+export type * from "./core/match-route-path.js";
+export { default as matchRoutePath } from "./core/match-route-path.js";
+
 export type * from "./core/readonly-form-data.types.js";
 
 export type * from "./core/readonly-url.types.js";
@@ -59,6 +62,9 @@ export { default as useNavigate } from "./hooks/use-navigate.js";
 export type * from "./hooks/use-params.js";
 export { default as useParams } from "./hooks/use-params.js";
 
+export type * from "./hooks/use-route-path.js";
+export { default as useRoutePath } from "./hooks/use-route-path.js";
+
 export type * from "./hooks/use-submit.js";
 export { default as useSubmit } from "./hooks/use-submit.js";