@wcstack/router 1.31.0 → 1.32.0

package/dist/index.d.ts

@@ -121,6 +121,8 @@ interface IRoute extends IRouteChildContainer {
     readonly absoluteSegmentCount: number;
     readonly segmentInfos: ISegmentInfo[];
     readonly absoluteSegmentInfos: ISegmentInfo[];
+    /** guard 属性の有無。SSR の guard バリア判定に使う（docs/ssr-router-design.md §2-4） */
+    readonly hasGuard: boolean;
     guardHandler: GuardHandler;
     shouldChange(newParams: Record<string, string>): boolean;
     guardCheck(matchResult: IRouteMatchResult): Promise<void>;
@@ -129,6 +131,23 @@ interface IRoute extends IRouteChildContainer {
     setParams(params: Record<string, string>, typedParams: Record<string, any>): void;
     clearParams(): void;
     notifyGuardHandlerLoadFailed(): void;
+    /**
+     * SSR ハイドレーションの採用: サーバー描画済みノード列を内容として引き取る
+     * （docs/ssr-router-design.md §4）
+     */
+    adoptChildNodes(nodes: Node[]): void;
+}
+/**
+ * Router 観測面のコミット 1 回分（docs/router-state-contract-design.md §3.4）。
+ */
+interface IRouterCommit {
+    params: Record<string, string>;
+    typedParams: Record<string, any>;
+    routeName: string;
+    /** "?k=v" 形式または ""。パースは commit 側（Router）が行う */
+    search: string;
+    /** basename スライス後の path */
+    path: string;
 }
 interface IRouter extends IRouteChildContainer {
     readonly basename: string;
@@ -136,7 +155,33 @@ interface IRouter extends IRouteChildContainer {
     readonly template: HTMLTemplateElement;
     fallbackRoute: IRoute | null;
     path: string;
+    /** 現在マッチのマージ済み param（文字列・frozen）。fallback・初期化前は {} */
+    readonly params: Record<string, string>;
+    /** 同上の型変換済み値（frozen） */
+    readonly typedParams: Record<string, any>;
+    /** 現在 URL のクエリ（Record・last-wins・frozen）。クエリ無しは {} */
+    readonly searchParams: Record<string, string>;
+    /** 最深マッチルートの name 属性値。fallback 時は fallback ルートの name */
+    readonly routeName: string;
     navigate(path: string): Promise<void>;
+    /** navigateUrl（push）の対になる replace 遷移（§4.2） */
+    replace(path: string): Promise<void>;
+    /**
+     * same-match 判定（§4.4）。比較は basename スライス後の path 同士。
+     * 最初の成功 commit より前は常に false（初回ガード）。
+     */
+    isSameMatch(path: string): boolean;
+    /**
+     * 観測面のコミットと発火（§3.4）。全内部値を先にコミットし、その後で
+     * params → route-name → search → path の順に変化したものだけ発火する。
+     */
+    commitNavigation(commit: IRouterCommit): void;
+    /** `announce=` 用 live region。未生成なら null（docs/a11y-design.md §3-4） */
+    readonly a11yRegion: HTMLElement | null;
+    /** `<wcs-router focus=...>` の属性値（無ければ null） */
+    readonly focusPolicy: string | null;
+    /** `<wcs-router announce=...>` の属性値（無ければ null） */
+    readonly announcePolicy: string | null;
 }
 interface IOutlet {
     routesNode: IRouter;
@@ -150,6 +195,12 @@ interface IOutlet {
  * Container element that manages route definitions and navigation.
  */
 declare class Router extends HTMLElement implements IRouter {
+    /**
+     * @wcstack/server の待機プロトコル（docs/ssr-router-design.md §3.2）。
+     * renderToString はこのフラグを持つ要素の connectedCallbackPromise を待って
+     * からシリアライズする — 初期ルート適用の完了がサーバー出力に反映される。
+     */
+    static hasConnectedCallbackPromise: boolean;
     static wcBindable: IWcBindable;
     private _outlet;
     private _template;
@@ -161,9 +212,35 @@ declare class Router extends HTMLElement implements IRouter {
     private _listeningPopState;
     private _listeningNavigate;
     private _navigateUrl;
+    private _replaceUrl;
     private _disconnectedDuringInit;
     private _initializing;
+    private _a11yRegion;
+    private _params;
+    private _typedParams;
+    private _searchParams;
+    private _routeName;
+    /** 最初の成功 commit を通過したか（§4.4 の初回ガード） */
+    private _hasCommitted;
+    private _connectedCallbackPromise;
+    private _resolveConnectedCallback;
+    private _rejectConnectedCallback;
     constructor();
+    get connectedCallbackPromise(): Promise<void>;
+    get a11yRegion(): HTMLElement | null;
+    get focusPolicy(): string | null;
+    get announcePolicy(): string | null;
+    /**
+     * `announce=` 用 live region を <wcs-router> 直下に空のまま用意する
+     * （docs/a11y-design.md §3-4）。
+     * - 告知より**前**から DOM に居ないと SR に読まれないため、announce 時の
+     *   遅延生成はできない。
+     * - outlet 配下はナビゲーションごとに破棄され、オプトインで shadow root にも
+     *   なる。document.body 直下は router の寿命を超えて漏れ、マルチ router で
+     *   競合する。よって配置は <wcs-router> 直下の一択。
+     * - display:none は live region を殺すため、sr-only クリップで隠す。
+     */
+    private _ensureA11yRegion;
     /**
      * Normalize a URL pathname to a route path.
      * 共通実装は normalizePathname.ts を参照（Link との挙動整合のため）。
@@ -188,6 +265,32 @@ declare class Router extends HTMLElement implements IRouter {
      * applyRoute 内で設定される値です。
      */
     set path(value: string);
+    get params(): Record<string, string>;
+    get typedParams(): Record<string, any>;
+    get searchParams(): Record<string, string>;
+    get routeName(): string;
+    /**
+     * same-match 判定（docs/router-state-contract-design.md §4.4）。
+     *
+     * 比較は **basename スライス後の path 同士**（`_path` はスライス後で保存済み）。
+     * 判定が必要な地点は 2 箇所 — `_onNavigateFunc` の intercept オプション決定時と
+     * `applyRoute` の入口分岐 — で、両方がこの単一実装を呼ぶ。
+     *
+     * 初回ガード: 最初の成功 commit より前には適用しない。初期 `_path = ""` が
+     * 正規化後パス（常に `/` 始まり）と一致しないため偶然安全だが、
+     * normalizePathname の実装詳細に依存させず規範として明示する。
+     */
+    isSameMatch(path: string): boolean;
+    /**
+     * 観測面のコミットと発火（docs/router-state-contract-design.md §3.4）。
+     *
+     * 全内部値を先にコミットし、その後で初めてイベントを発火する — どのイベントの
+     * リスナーから要素プロパティを読んでも、遷移後スナップショットの一貫した値が
+     * 見える。発火順序は params → route-name → search → path。`path` を最後に
+     * 置くのは、既存例で `path` が「ナビゲーション完了」の信号として使われている
+     * ため。各イベントは変化した commit のみ発火する。
+     */
+    commitNavigation(commit: IRouterCommit): void;
     get fallbackRoute(): IRoute | null;
     /**
      * Routeのfallback属性がある場合にそのルートを設定します。
@@ -195,7 +298,21 @@ declare class Router extends HTMLElement implements IRouter {
     set fallbackRoute(value: IRoute | null);
     get navigateUrl(): string | null;
     set navigateUrl(value: string | null);
+    get replaceUrl(): string | null;
+    /**
+     * navigateUrl と完全同型の null-idle transient（docs/router-state-contract-design.md §4.2）。
+     * null は待機・書き込みで replace() を起動・完了で自己リセットして
+     * `wcs-router:replace-url-changed`（detail: null）を発火する。
+     */
+    set replaceUrl(value: string | null);
     navigate(path: string): Promise<void>;
+    /**
+     * navigateUrl（push）の対になる replace 遷移（docs/router-state-contract-design.md §4.2）。
+     * Navigation API では `navigation.navigate(url, { history: "replace" })`、
+     * フォールバックでは `history.replaceState` + applyRoute + 通知。
+     */
+    replace(path: string): Promise<void>;
+    private _performNavigation;
     /**
      * basename 配下の URL かどうかを判定する。
      * basename が空の場合はすべての URL にマッチする。
@@ -205,12 +322,38 @@ declare class Router extends HTMLElement implements IRouter {
     private _onNavigate;
     private _onPopState;
     private _initialize;
+    /**
+     * サーバー描画済み outlet の採用（docs/ssr-router-design.md §4）。
+     *
+     * 検証（一意な absolutePath・マーカーの整合・現在 URL のマッチとの一致）を
+     * **すべて DOM 変更の前に**行い、途中で断念しても半採用状態を残さない。
+     * 成立すれば DOM 変更ゼロで「すでにナビゲート済み」の状態を確立する —
+     * state がハイドレートしたバインディングは採用ノード上で生きたままになる。
+     *
+     * @returns 採用が成立した場合 true。false は呼び出し側（_initialize）が
+     *          サーバー DOM を破棄して従来描画にフォールバックする。
+     */
+    private _hydrateFromSsr;
+    /**
+     * SSR モードの初期ルート描画（docs/ssr-router-design.md §3.2）。
+     * 初回描画は transition arbiter に渡らない既存規則（showRouteContent）により
+     * 常に同期適用される。navigate / popstate リスナ・a11y region・
+     * `wcs:navigate` 通知はサーバーでは不要（connectedCallback 側で登録しない）。
+     */
+    private _renderForSsr;
+    /**
+     * 初期表示ルートの内容を binder プロトコルへ差し出す。SSR 描画（_renderForSsr）と
+     * ハイドレーション不能時の描き直し（state が先にハイドレートを終えている可能性が
+     * ある）の両方から呼ぶ。bind() は冪等なので余分に差し出しても壊れない。
+     */
+    private _offerInitialContentToBinder;
+    /** ルートツリー全体（ネスト含む）への走査 */
+    private _forEachRoute;
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
 }
 
 declare class Route extends HTMLElement implements IRoute {
-    static wcBindable: IWcBindable;
     private _core;
     private _routeParentNode;
     private _routeChildNodes;
@@ -228,6 +371,13 @@ declare class Route extends HTMLElement implements IRoute {
     get uuid(): string;
     get placeHolder(): Comment;
     get childNodeArray(): Node[];
+    /**
+     * SSR ハイドレーションの採用（docs/ssr-router-design.md §4）。
+     * サーバー描画済みの DOM ノード列をこのルートの内容として引き取る。
+     * 以後の hideRoute / showRoute は採用ノードに対して従来どおり動く。
+     * template 由来の fresh クローン（自身の childNodes）は不要になるため破棄する。
+     */
+    adoptChildNodes(nodes: Node[]): void;
     get routes(): IRoute[];
     get childIndex(): number;
     get path(): string;
@@ -245,6 +395,7 @@ declare class Route extends HTMLElement implements IRoute {
     get segmentCount(): number;
     get absoluteSegmentCount(): number;
     get fullpath(): string;
+    get hasGuard(): boolean;
     get guardHandler(): GuardHandler;
     set guardHandler(value: GuardHandler);
     setParams(params: Record<string, string>, typedParams: Record<string, any>): void;
@@ -271,8 +422,21 @@ interface RouteParseOptions {
     guardFallback?: string | null;
     name?: string;
 }
+/**
+ * NOTE: RouteCore / Route は `static wcBindable` を**宣言しない**
+ * （docs/router-state-contract-design.md §5.1 / D2）。
+ *
+ * `<wcs-route>` は parse 時に clone された detached コントローラであり、live DOM に
+ * 入るのは placeholder コメントとスタンプされた子ノードだけ。data-wcs は live DOM
+ * 上の属性走査で結線する仕組みなので、宣言しても構造的に到達不能な「果たせない
+ * 約束」になる。params / typedParams / routeName の観測面は live DOM に居る
+ * `<wcs-router>` に集約した（Router.wcBindable）。
+ *
+ * `wcs-route:params-changed` / `wcs-route:active-changed` の dispatch は存置する —
+ * RouteCore は EventTarget であり、Core 直接消費（signals の正式推奨形）と
+ * ユニットテストの観測面として生きている。
+ */
 declare class RouteCore extends EventTarget {
-    static wcBindable: IWcBindable;
     private _target;
     private _parentCore;
     private _path;
@@ -318,6 +482,12 @@ declare class RouteCore extends EventTarget {
     setParams(params: Record<string, string>, typedParams: Record<string, any>): void;
     clearParams(): void;
     shouldChange(newParams: Record<string, string>): boolean;
+    /**
+     * guard 属性の有無（parsePath の options.hasGuard）。SSR の guard バリア
+     * — guard 付きルートはサーバーで描かない（docs/ssr-router-design.md §2-4）—
+     * がハンドラのロードを待たずに判定するために使う。
+     */
+    get hasGuard(): boolean;
     get guardHandler(): GuardHandler;
     set guardHandler(value: GuardHandler);
     /**