soseki 0.0.1

package/src/components/action-id.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import actionIdRegistry from "../core/_action-id-registry.js";
+import { ACTION_ID_FORM_DATA_NAME } from "../core/constants.js";
+import type { IAction } from "../core/route.types.js";
+import HiddenInput from "./hidden-input.jsx";
+
+/**
+ * ActionId コンポーネントのプロパティーを定義する型です。
+ */
+export type ActionIdProps = {
+  /**
+   * 実行対象となるアクション関数です。
+   */
+  action: IAction;
+};
+
+/**
+ * アクションに対応する識別子を隠しフィールドとしてレンダリングするコンポーネントです。
+ *
+ * アクション関数をレジストリーに登録し、発行された ID をフォームデータとして送信可能な状態にします。
+ */
+export default /*#__PURE__*/ React.memo(
+  function ActionId(props: ActionIdProps): React.ReactElement {
+    const { action } = props;
+    const id = actionIdRegistry.set(action);
+
+    return (
+      <HiddenInput
+        name={ACTION_ID_FORM_DATA_NAME}
+        value={id}
+      />
+    );
+  },
+  (a, b) => a.action === b.action,
+);

package/src/components/browser-router.tsx

@@ -0,0 +1,31 @@
+import useSingleton from "../core/_use-singleton.js";
+import type { RouteDefinition } from "../core/route.types.js";
+import NavigationApiEngine from "../engines/navigation-api-engine.js";
+import Router from "./router.jsx";
+
+/**
+ * BrowserRouter コンポーネントに渡されるプロパティーの型定義です。
+ */
+export type BrowserRouterProps = {
+  /**
+   * アプリケーション全体のルート定義を格納した配列です。
+   */
+  routes: readonly RouteDefinition[];
+};
+
+/**
+ * ブラウザー標準の Navigation API を使用してルーティングを行うためのコンポーネントです。
+ *
+ * `NavigationApiEngine` のインスタンスをシングルトンとして保持し、ルーターの基盤を提供します。
+ */
+export default function BrowserRouter(props: BrowserRouterProps): React.ReactElement {
+  const { routes } = props;
+  const engine = useSingleton(() => new NavigationApiEngine());
+
+  return (
+    <Router
+      engine={engine}
+      routes={routes}
+    />
+  );
+}

package/src/components/hidden-input.tsx

@@ -0,0 +1,39 @@
+import * as React from "react";
+
+/**
+ * 隠し入力フィールド（hidden input）のプロパティーを定義する型です。
+ */
+export type HiddenInputProps = {
+  /**
+   * フォーム送信時に使用される要素の名前です。
+   */
+  name: string;
+
+  /**
+   * フォーム送信時に送信される値です。
+   */
+  value: string;
+};
+
+/**
+ * フォーム内で非表示の状態を保持するための隠し入力コンポーネントです。
+ */
+export default /*#__PURE__*/ React.memo(
+  function HiddenInput(props: HiddenInputProps) {
+    const {
+      name,
+      value,
+    } = props;
+
+    return (
+      <input
+        type="hidden"
+        name={name}
+        style={{ display: "none" }}
+        value={value}
+        hidden
+      />
+    );
+  },
+  (a, b) => a.name === b.name && a.value === b.value,
+);

package/src/components/outlet.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+import RouteContext from "../contexts/route-context.js";
+import { RouteContextMissingError } from "../core/errors.js";
+
+/**
+ * 現在のルート階層における子ルート（アウトレット）を描画するためのコンポーネントです。
+ *
+ * ネストされたルーティングにおいて、親ルートのコンポーネント内で子ルートの挿入位置を指定するために使用します。
+ */
+export default function Outlet(): React.ReactElement | null {
+  const routeContext = React.use(RouteContext);
+  if (!routeContext) {
+    throw new RouteContextMissingError();
+  }
+
+  return routeContext.outlet;
+}

package/src/components/router.tsx

@@ -0,0 +1,234 @@
+import * as React from "react";
+import RouteContext from "../contexts/route-context.js";
+import RouterContext, {
+  type RouterContextValue,
+  type RouterRef,
+} from "../contexts/router-context.js";
+import processRoutes from "../core/_process-routes.js";
+import type { IDataStore } from "../core/data-store.types.js";
+import type { HistoryEntry } from "../core/expect-history-entry.js";
+import type { MatchedRoute } from "../core/match-routes.js";
+import type { IAction, ILoader, RouteDefinition } from "../core/route.types.js";
+import type { IEngine, RouterState, SubmitArgs } from "../engines/engine.types.js";
+import type { NavigateArgs } from "../engines/engine.types.js";
+
+/**
+ * ComponentRenderer コンポーネントに渡されるプロパティーの型定義です。
+ */
+type ComponentRendererProps = {
+  /**
+   * 現在のコンテキストでレンダリングされる、マッチしたルート情報です。
+   */
+  route: MatchedRoute;
+
+  /**
+   * ネストされた下位のルート要素です。存在しない場合は null を指定します。
+   */
+  outlet: React.ReactElement<RouteRendererProps, typeof RouteRenderer> | null;
+};
+
+/**
+ * 個別のルートコンポーネントをレンダリングし、ルートコンテキストを提供する内部コンポーネントです。
+ */
+function ComponentRenderer(props: ComponentRendererProps): React.JSX.Element | null {
+  const {
+    route: {
+      path,
+      index,
+      params,
+      urlPath,
+      component: Component,
+    },
+    outlet,
+  } = props;
+  const context = {
+    path,
+    index,
+    params,
+    outlet,
+    urlPath,
+  };
+
+  return (
+    <RouteContext value={context}>
+      {Component ? <Component /> : outlet}
+    </RouteContext>
+  );
+}
+
+/**
+ * マッチしたルートを再帰的にレンダリングするためのプロパティーです。
+ */
+type RouteRendererProps = {
+  /**
+   * 現在のパスにマッチしたルートの配列です。
+   */
+  routes: readonly MatchedRoute[];
+
+  /**
+   * 現在レンダリング対象となっているルートのインデックス番号です。
+   */
+  index?: number;
+};
+
+/**
+ * マッチしたルートの階層を順番にレンダリングする内部コンポーネントです。
+ */
+function RouteRenderer(props: RouteRendererProps): React.ReactElement {
+  const {
+    index = 0,
+    routes,
+  } = props;
+  const route = routes[index]!;
+  const outlet = index < routes.length - 1
+    ? <RouteRenderer routes={routes} index={index + 1} />
+    : null;
+
+  return (
+    <ComponentRenderer
+      route={route}
+      outlet={outlet}
+    />
+  );
+}
+
+/**
+ * Router コンポーネントに渡されるプロパティーの型定義です。
+ */
+export type RouterProps = {
+  /**
+   * ルーティングのロジックを制御するエンジンインスタンスです。
+   */
+  engine: IEngine;
+
+  /**
+   * アプリケーションのルート定義の配列です。
+   */
+  routes: readonly RouteDefinition[];
+};
+
+/**
+ * ルーティング機能を提供するメインのコンポーネントです。
+ *
+ * エンジンの管理、状態の同期、およびルートのレンダリングを担います。
+ */
+export default function Router(props: RouterProps) {
+  const {
+    engine,
+    routes: routesProp,
+  } = props;
+  const routerRef = React.useRef({} as {
+    submit(args: SubmitArgs): void;
+    navigate(args: NavigateArgs): void;
+    currentEntry: HistoryEntry;
+    actionDataStore: IDataStore<IAction>;
+    loaderDataStore: IDataStore<ILoader>;
+  });
+  const router = React.useMemo<{
+    start(): () => void;
+    context: RouterContextValue;
+    getRoutes(): readonly MatchedRoute[] | undefined;
+  }>(
+    () => {
+      const actionDataStore: IDataStore<IAction> = new Map();
+      const loaderDataStore: IDataStore<ILoader> = new Map();
+      const subscribers = new Set<() => void>();
+      const routes = processRoutes(routesProp);
+      let ac: AbortController | null = null;
+
+      function getAbortSignal(): AbortSignal {
+        return (ac ||= new AbortController()).signal;
+      }
+
+      const initialState = engine.init({
+        routes,
+        getSignal: getAbortSignal,
+        loaderDataStore,
+      });
+      let currentRoutes = initialState?.routes;
+
+      function updateRouter(newState?: RouterState | null) {
+        if (newState !== undefined) {
+          currentRoutes = newState?.routes;
+        }
+        if (newState) {
+          routerRef.current.currentEntry = newState.entry;
+        }
+
+        // 登録されているすべてのサブスクライバーに通知します。
+        subscribers.forEach(notify => notify());
+      }
+
+      function startRouterEngine() {
+        const stop = engine.start({
+          routes,
+          update: updateRouter,
+          getSignal: getAbortSignal,
+          actionDataStore,
+          loaderDataStore,
+        });
+
+        return function stopRouterEngine() {
+          try {
+            // エンジンの動作を停止します。
+            stop?.();
+          } finally {
+            // 進行中のすべての非同期処理を中断します。
+            try {
+              ac?.abort();
+            } catch {
+            }
+
+            // 中断後は次回の呼び出しに備えてコントローラーを破棄します。
+            ac = null;
+          }
+        };
+      }
+
+      Object.assign<RouterRef["current"], RouterRef["current"]>(routerRef.current, {
+        submit(args) {
+          return engine.submit(args);
+        },
+        navigate(args) {
+          return engine.navigate(args);
+        },
+        currentEntry: initialState?.entry!,
+        actionDataStore,
+        loaderDataStore,
+      });
+
+      return {
+        start: startRouterEngine,
+        context: {
+          routerRef,
+          subscribe(cb) {
+            subscribers.add(cb);
+            return () => {
+              subscribers.delete(cb);
+            };
+          },
+        },
+        getRoutes() {
+          return currentRoutes;
+        },
+      };
+    },
+    [
+      engine,
+      routesProp,
+    ],
+  );
+
+  React.useEffect(router.start, [router]);
+
+  const routes = React.useSyncExternalStore(router.context.subscribe, router.getRoutes);
+  if (!routes) {
+    return null;
+  }
+
+  return (
+    <RouterContext value={router.context}>
+      <RouteRenderer routes={routes.toReversed()} />
+    </RouterContext>
+  );
+}

package/src/contexts/route-context.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { MatchedRoute } from "../core/match-routes.js";
+
+/**
+ * 各ルートのコンテキストで共有される値の型定義です。
+ */
+export type RouteContextValue = Pick<MatchedRoute, "path" | "index" | "params" | "urlPath"> & {
+  /**
+   * 子ルートを描画するための React 要素です。
+   *
+   * 子ルートが存在しない場合は `null` となります。
+   */
+  readonly outlet: React.ReactElement | null;
+};
+
+/**
+ * 個別のルート情報やアウトレット（子ルートの挿入場所）を保持するための React コンテキストです。
+ */
+const RouteContext = /*#__PURE__*/ React.createContext<RouteContextValue | null>(null);
+
+export default RouteContext;

package/src/contexts/router-context.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+import type { IReadonlyDataStore } from "../core/data-store.types.js";
+import type { HistoryEntry } from "../core/expect-history-entry.js";
+import type { IAction, ILoader } from "../core/route.types.js";
+import type { NavigateArgs, SubmitArgs } from "../engines/engine.types.js";
+
+export type RouterRef = Readonly<
+  React.RefObject<{
+    /**
+     * フォームデータやクエリー パラメーターを送信します。
+     *
+     * @param args 送信内容と送信先を含む引数です。
+     */
+    readonly submit: (args: SubmitArgs) => void;
+
+    /**
+     * 指定されたパスへ遷移します。
+     *
+     * @param args 遷移先と遷移オプションを含む引数です。
+     */
+    readonly navigate: (args: NavigateArgs) => void;
+
+    /**
+     * 現在の履歴エントリー情報（ID、URL、インデックスなど）です。
+     */
+    readonly currentEntry: HistoryEntry;
+
+    /**
+     * 履歴 ID ごとに管理されているアクションデータのマップです。
+     */
+    readonly actionDataStore: IReadonlyDataStore<IAction>;
+
+    /**
+     * 履歴 ID ごとに管理されているローダーデータのマップです。
+     */
+    readonly loaderDataStore: IReadonlyDataStore<ILoader>;
+  }>
+>;
+
+/**
+ * ルーターコンテキストで共有される値の型定義です。
+ */
+export type RouterContextValue = {
+  readonly routerRef: RouterRef;
+  readonly subscribe: (onRouterChange: () => void) => () => void;
+};
+
+/**
+ * ルーターの状態や操作関数をコンポーネントツリー全体で共有するための React コンテキストです。
+ *
+ * 初期値は `null` であり、通常は Provider を介して値が提供されます。
+ */
+const RouterContext = /*#__PURE__*/ React.createContext<RouterContextValue | null>(null);
+
+export default RouterContext;

package/src/core/_action-id-registry.ts

@@ -0,0 +1,11 @@
+import WeakIdRegistry from "./_weak-id-registry.js";
+import type { IAction } from "./route.types.js";
+
+/**
+ * `IAction` 型のオブジェクトとその識別子を管理するための、弱い参照を用いたレジストリーです。
+ *
+ * ガベージコレクションを妨げずにアクションの識別子を保持するために使用されます。
+ */
+const actionIdRegistry = new WeakIdRegistry<IAction>();
+
+export default actionIdRegistry;

package/src/core/_capture-stack-trace.ts

@@ -0,0 +1,12 @@
+/**
+ * オブジェクトにスタックトレースをキャプチャーします。
+ *
+ * @param targetObject スタックトレースのプロパティーを追加する対象のオブジェクトです。
+ * @param constructorOpt スタックトレースの開始地点としてマークする関数です。
+ */
+export default function captureStackTrace(targetObject: object, constructorOpt: Function): void {
+  // 実行環境（V8 エンジンなど）が Error.captureStackTrace をサポートしているか確認します。
+  if ("captureStackTrace" in Error && typeof Error.captureStackTrace === "function") {
+    Error.captureStackTrace(targetObject, constructorOpt);
+  }
+}

package/src/core/_compare-route-paths.ts

@@ -0,0 +1,90 @@
+/**
+ * セグメントの種類に応じたスコア定数です。
+ *
+ * 数値が大きいほど優先順位（具体性）が高いです。
+ */
+const SCORE = {
+  /**
+   * 静的なパスセグメントのスコアです。
+   */
+  STATIC: 4,
+
+  /**
+   * 必須のパラメーターセグメントのスコアです。
+   */
+  PARAMETER: 3,
+
+  /**
+   * 任意のパラメーターセグメントのスコアです。
+   */
+  OPTIONAL_PARAM: 2,
+
+  /**
+   * ワイルドカードセグメントのスコアです。
+   */
+  WILDCARD: 1,
+} as const;
+
+/**
+ * 指定されたパスセグメントの文字列から、その種類に応じたスコアを計算します。
+ *
+ * @param s 解析対象のパスセグメント文字列です。
+ * @returns セグメントの種類に基づいた数値スコアを返します。
+ */
+function getSegmentScore(s: string): number {
+  if (s.includes("*")) {
+    return SCORE.WILDCARD;
+  }
+
+  if (s.startsWith(":")) {
+    if (s.endsWith("?")) {
+      return SCORE.OPTIONAL_PARAM;
+    } else {
+      return SCORE.PARAMETER;
+    }
+  }
+
+  return SCORE.STATIC;
+}
+
+/**
+ * 2 つのパスを比較し、ルーティングの優先順位に基づいたソート順を決定します。
+ *
+ * より具体的で深いパスが前方に配置されるように比較を行います。
+ *
+ * @param pathA 比較対象のパス A です。
+ * @param pathB 比較対象のパス B です。
+ * @returns 比較結果を示す数値です（負数は pathA が優先、正数は pathB が優先）。
+ */
+export default function compareRoutePaths(pathA: string, pathB: string): number {
+  const partsA = pathA.split("/").filter(Boolean);
+  const partsB = pathB.split("/").filter(Boolean);
+  const length = Math.max(partsA.length, partsB.length);
+
+  for (let i = 0; i < length; i++) {
+    const a = partsA[i];
+    // パス A のセグメントが先に終了した場合は、パス B を優先します。
+    if (a === undefined) {
+      return 1;
+    }
+
+    const b = partsB[i];
+    // パス B のセグメントが先に終了した場合は、パス A を優先します。
+    if (b === undefined) {
+      return -1;
+    }
+
+    const scoreA = getSegmentScore(a);
+    const scoreB = getSegmentScore(b);
+    // スコアが異なる場合は、スコアが高い方を優先します。
+    if (scoreA !== scoreB) {
+      return scoreB - scoreA;
+    }
+    // スコアが同じ場合は、文字列の辞書順で比較します。
+    if (a !== b) {
+      return a.localeCompare(b);
+    }
+  }
+
+  return 0;
+}

package/src/core/_create-html-form-element-form-form-data.ts

@@ -0,0 +1,32 @@
+import type { ReadonlyFormData } from "./readonly-form-data.types.js";
+
+/**
+ * ReadonlyFormData の内容から、一時的な HTMLFormElement を生成します。
+ *
+ * @param formData フォーム要素に変換する元のフォームデータです。
+ * @returns 生成された HTMLFormElement を返します。
+ */
+export default function createHtmlFormElementFormFormData(
+  formData: ReadonlyFormData,
+): HTMLFormElement {
+  const form = document.createElement("form");
+  form.style.display = "none";
+  formData.forEach((value, name) => {
+    const input = document.createElement("input");
+    if (value instanceof File) {
+      input.type = "file";
+      input.name = name;
+      const dataTransfer = new DataTransfer();
+      dataTransfer.items.add(value);
+      input.files = dataTransfer.files;
+    } else {
+      input.type = "hidden";
+      input.name = name;
+      input.value = value;
+    }
+
+    form.appendChild(input);
+  });
+
+  return form;
+}

package/src/core/_encode-pathname.ts

@@ -0,0 +1,17 @@
+/**
+ * 連続するスラッシュ（/）にマッチする正規表現です。
+ */
+const MULTI_SLASH = /\/\/+/gu;
+
+/**
+ * 与えられたパス名を URL エンコードし、正規化された形式で返します。
+ *
+ * エンコードの必要がある部分のみをエンコードします。
+ *
+ * @param pathname エンコード対象となるパス名の文字列です。
+ * @returns 正規化およびエンコードされたパス名の文字列です。
+ */
+export default function encodePathname(pathname: string): string {
+  const u = new URL("x://y" + ("/" + pathname).replace(MULTI_SLASH, "/"));
+  return u.pathname;
+}

package/src/core/_is-error.ts

@@ -0,0 +1,16 @@
+/**
+ * エラーオブジェクトのようなオブジェクトかどうか判定します。
+ *
+ * @param e 判定する値です。
+ * @returns 判定結果です。
+ */
+function isError(e: unknown): e is Error {
+  return e instanceof Error || (
+    e !== null
+    && typeof e === "object"
+    && ("name" in e && typeof e.name === "string")
+    && ("message" in e && typeof e.message === "string")
+  );
+}
+
+export default globalThis.Error.isError || isError;

package/src/core/_is-promise-like.ts

@@ -0,0 +1,14 @@
+/**
+ * 与えられた値が `PromiseLike` であるかどうかを判定します。
+ *
+ * @param value 判定対象の値です。
+ * @returns 値が `then` メソッドを持つオブジェクトである場合は `true`、それ以外は `false` を返します。
+ */
+export default function isPromiseLike<T = unknown>(value: unknown): value is PromiseLike<T> {
+  return (
+    value !== null
+    && typeof value === "object"
+    // @ts-expect-error
+    && typeof value["then"] === "function"
+  );
+}

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

@@ -0,0 +1,39 @@
+import type { PathParams, Route } from "./route.types.js";
+
+/**
+ * パスマッチングの結果を表す型定義です。
+ */
+export type MatchPathResult = {
+  /**
+   * パスから抽出されたパラメーターのキーと値のペアです。
+   */
+  params: PathParams;
+};
+
+/**
+ * 指定されたルートの正規表現パターンを使用して、パス名がマッチするかどうかを判定します。
+ *
+ * @param route 判定対象となる前処理済みのルートオブジェクトです。
+ * @param pathname マッチングを行う対象のパス名（URL のパス部分）です。
+ * @returns マッチした場合はパラメーターを含むオブジェクトを返し、マッチしない場合は `null` を返します。
+ */
+export default function matchPath(
+  route: Pick<Route, "paramKeys" | "pathPattern">,
+  pathname: string,
+): MatchPathResult | null {
+  const matches = route.pathPattern.exec(pathname);
+  if (!matches) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+  for (let i = 0, value: string | undefined; i < route.paramKeys.length; i++) {
+    value = matches[i + 1];
+    if (value !== undefined) {
+      // route.paramKeys のインデックスと matches のキャプチャーグループを対応させます。
+      params[route.paramKeys[i]!] = value;
+    }
+  }
+
+  return { params };
+}