@aiquants/daily-report 0.6.2 → 0.8.0

package/src/client/hooks/use-animated-number.spec.ts

@@ -0,0 +1,103 @@
+/**
+ * Timing tests for the ease-out animated number hook.
+ * イーズアウト数値アニメーションフックのタイミングテスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **経過時間の基準は最初の rAF フレームのタイムスタンプ** — effect 内の
+ *   `performance.now()` 基準だと混雑時に負の進捗が生まれ 0 に張り付く
+ *   (contact-map で実測された既知の不具合の再発防止)。
+ * - **初回マウントは補間せず即時表示** (カウントアップ演出をしない)。
+ * - **中断された補間は表示中の値から次の補間を始める** (跳び戻りしない)。
+ */
+import { act, renderHook } from "@testing-library/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { useAnimatedNumber } from "./use-animated-number"
+
+/** 手動発火の rAF キュー。 */
+let rafQueue: FrameRequestCallback[] = []
+
+beforeEach(() => {
+    rafQueue = []
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+        rafQueue.push(callback)
+        return rafQueue.length
+    })
+    vi.stubGlobal("cancelAnimationFrame", vi.fn())
+})
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+})
+
+/** 保留中の rAF を 1 フレームだけ指定タイムスタンプで発火する。 */
+const fireFrame = (timestamp: number) => {
+    const frame = rafQueue.shift()
+    act(() => {
+        frame?.(timestamp)
+    })
+}
+
+describe("useAnimatedNumber", () => {
+    it("初回マウントは補間せず即時に値を表示する", () => {
+        const { result } = renderHook(() => useAnimatedNumber(42))
+        expect(result.current).toBe(42)
+        expect(rafQueue).toHaveLength(0)
+    })
+
+    it("値の変化をイーズアウト 3 次で補間する (基準は最初のフレーム時刻)", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+
+        // 最初のフレームが基準になる (進捗 0)
+        fireFrame(5_000)
+        expect(result.current).toBe(0)
+
+        // 50ms 経過 → eased = 1 - 0.5^3 = 0.875
+        fireFrame(5_050)
+        expect(result.current).toBe(88)
+
+        // 100ms 経過 → 完了
+        fireFrame(5_100)
+        expect(result.current).toBe(100)
+        expect(rafQueue).toHaveLength(0)
+    })
+
+    it("基準フレームより過去のような大きなタイムスタンプでも進捗は 0-1 にクランプされる", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+        fireFrame(5_000)
+        // 大幅超過は 1 へクランプ
+        fireFrame(99_999)
+        expect(result.current).toBe(100)
+    })
+
+    it("補間の中断は表示中の値から次の補間を開始する (跳び戻りしない)", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+        fireFrame(1_000)
+        fireFrame(1_050)
+        expect(result.current).toBe(88)
+
+        // 補間途中で目標値を更新 → 旧アニメーションは破棄され、88 を起点に 200 へ向かう
+        rafQueue.length = 0
+        rerender({ value: 200 })
+        expect(result.current).toBe(88)
+
+        // 第 2 アニメーションの基準フレーム (進捗 0 = 起点 88 のまま)
+        fireFrame(2_000)
+        expect(result.current).toBe(88)
+        // 50ms 経過 → eased 0.875 → 88 + (200 - 88) × 0.875 = 186
+        fireFrame(2_050)
+        expect(result.current).toBe(186)
+        // 完了 → 200
+        fireFrame(2_100)
+        expect(result.current).toBe(200)
+    })
+
+    it("同値への再レンダーはアニメーションを起こさない", () => {
+        const { rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 7 } })
+        rerender({ value: 7 })
+        expect(rafQueue).toHaveLength(0)
+    })
+})

package/src/client/hooks/use-animated-number.ts

@@ -0,0 +1,69 @@
+/**
+ * Ease-out animated number for streaming counters.
+ * ストリーミングカウンター向けのイーズアウト数値アニメーションフック。
+ *
+ * 経過時間の基準は「最初の rAF フレームのタイムスタンプ」にする。effect 内の
+ * `performance.now()` を基準にすると、メインスレッド混雑時に保留中フレームの
+ * vsync 時刻が基準より過去になり、負の進捗が 3 乗されて 0 に張り付く
+ * (contact-map で実測された既知の不具合)。進捗は念のため 0 でもクランプする。
+ */
+import { useEffect, useRef, useState } from "react"
+
+/**
+ * Animates numeric changes with ease-out cubic.
+ * 数値変化をイーズアウト 3 次で補間するフック。
+ *
+ * @param value Target value. 目標値。
+ * @param durationMs Animation duration. アニメーション時間 (既定 250ms)。
+ * @returns Displayed (interpolated) value. 表示用の補間値。
+ */
+export const useAnimatedNumber = (value: number, durationMs = 250): number => {
+    const [display, setDisplay] = useState(value)
+    // 表示中の値の同期ミラー (アニメーション中断時の次回開始点に使う)
+    const displayRef = useRef(value)
+    const isFirstRef = useRef(true)
+
+    /**
+     * Animation effect.
+     * アニメーション副作用。
+     *
+     * 依存配列:
+     * - value: 目標値の変化でアニメーションを開始する
+     * - durationMs: 時間変更で再スケジュール
+     * クリーンアップ:
+     * - 実行中の rAF をキャンセルする (中断時は displayRef が現在値を保持)
+     */
+    useEffect(() => {
+        // 初回は補間せず即時表示する (マウント時のカウントアップ演出は不要)
+        if (isFirstRef.current) {
+            isFirstRef.current = false
+            displayRef.current = value
+            setDisplay(value)
+            return
+        }
+        const from = displayRef.current
+        if (from === value) return
+
+        let rafId: number | null = null
+        let startTimestamp: number | null = null
+        const step = (timestamp: number) => {
+            if (startTimestamp === null) {
+                startTimestamp = timestamp
+            }
+            const progress = Math.min(1, Math.max(0, (timestamp - startTimestamp) / durationMs))
+            const eased = 1 - (1 - progress) ** 3
+            const next = Math.round(from + (value - from) * eased)
+            displayRef.current = next
+            setDisplay(next)
+            if (progress < 1) {
+                rafId = requestAnimationFrame(step)
+            }
+        }
+        rafId = requestAnimationFrame(step)
+        return () => {
+            if (rafId !== null) cancelAnimationFrame(rafId)
+        }
+    }, [value, durationMs])
+
+    return display
+}

package/src/client/hooks/use-responsive-layout.spec.ts

@@ -0,0 +1,74 @@
+/**
+ * Tests for the shared responsive-layout hooks.
+ * 共有のレスポンシブ判定フックのテスト。
+ *
+ * 閾値は 1 箇所でだけ定義する。各ビューが独自に `matchMedia` を持つと、片方だけ変更されて
+ * レイアウト分岐が食い違う。
+ *
+ * ❗ スクロール操作の可否はここで決めない (画面幅では「主入力がマウスのタッチ対応ノート」を
+ * 取りこぼす)。ドラッグはポインタ種別ごとに `pointerDragInputs` で制御する。
+ */
+import { act, renderHook } from "@testing-library/react"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { MOBILE_LAYOUT_MEDIA_QUERY, useIsMobileLayout } from "./use-responsive-layout"
+
+/** 購読中のリスナー。`change` を発火させて再評価させるために保持する。 */
+type Listener = () => void
+
+/**
+ * Installs a `matchMedia` stub whose result is driven by the given query set.
+ * 指定したクエリ集合で結果が決まる `matchMedia` スタブを差し込む処理。
+ *
+ * @param matching Queries that should report a match. 一致させるクエリ群。
+ * @returns A setter to change the matching set and re-notify. 一致集合を差し替えて再通知するための関数。
+ */
+const stubMatchMedia = (matching: string[]) => {
+    let current = new Set(matching)
+    const listeners: Listener[] = []
+
+    vi.stubGlobal("matchMedia", (query: string) => ({
+        get matches() {
+            return current.has(query)
+        },
+        media: query,
+        addEventListener: (_type: string, listener: Listener) => listeners.push(listener),
+        removeEventListener: (_type: string, listener: Listener) => {
+            const index = listeners.indexOf(listener)
+            if (index >= 0) listeners.splice(index, 1)
+        },
+    }))
+
+    return {
+        set: (next: string[]) => {
+            current = new Set(next)
+            act(() => {
+                for (const listener of [...listeners]) listener()
+            })
+        },
+        listenerCount: () => listeners.length,
+    }
+}
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+})
+
+describe("useIsMobileLayout", () => {
+    it("ビューポートが閾値以下ならモバイルレイアウトと判定する", () => {
+        stubMatchMedia([MOBILE_LAYOUT_MEDIA_QUERY])
+        expect(renderHook(() => useIsMobileLayout()).result.current).toBe(true)
+    })
+
+    it("閾値を超えるならデスクトップレイアウトと判定する", () => {
+        stubMatchMedia([])
+        expect(renderHook(() => useIsMobileLayout()).result.current).toBe(false)
+    })
+
+    it("リサイズ (change) に追随する", () => {
+        const media = stubMatchMedia([])
+        const { result } = renderHook(() => useIsMobileLayout())
+        expect(result.current).toBe(false)
+        media.set([MOBILE_LAYOUT_MEDIA_QUERY])
+        expect(result.current).toBe(true)
+    })
+})

package/src/client/hooks/use-responsive-layout.ts

@@ -0,0 +1,56 @@
+/**
+ * Responsive layout detection shared by the daily-report views.
+ * 日報ビューが共有するレスポンシブ判定。
+ *
+ * 閾値を 1 箇所に集約する。各ビューが独自に `matchMedia` を持つと、片方だけ変更されて
+ * レイアウト分岐が食い違う。
+ *
+ * ❗ **スクロール操作の可否をここで決めてはならない。** 画面幅で判定すると
+ * 「主入力がマウスのタッチ対応ノート」のような端末を取りこぼす。ドラッグスクロールは
+ * `ScrollPane` の `pointerDragInputs` で**イベントのポインタ種別ごとに**制御する
+ * (`CONTENT_DRAG_POINTER_INPUTS` 参照)。
+ */
+import { useEffect, useState } from "react"
+
+/**
+ * Viewport width at which the daily-report views switch to the mobile layout.
+ * 日報ビューがモバイルレイアウトへ切り替わるビューポート幅。
+ *
+ * Tailwind の `sm` (640px) の直下に合わせてある。リスト + サイドペインの 2 カラムを
+ * 畳んでオーバーレイ表示にする閾値であり、**この値は 1 箇所でだけ定義する**。
+ */
+export const MOBILE_LAYOUT_MEDIA_QUERY = "(max-width: 639px)"
+
+/**
+ * Reports whether the viewport is narrow enough for the mobile layout.
+ * ビューポートがモバイルレイアウトの幅かどうかを返す処理。
+ *
+ * SSR と初回描画では `false` を返し、マウント後に実環境で更新する
+ * (サーバーとクライアントで初期値を揃えてハイドレーション不一致を避ける)。
+ *
+ * @returns True on the mobile layout. モバイルレイアウトなら true。
+ */
+export const useIsMobileLayout = (): boolean => {
+    const [isMobileLayout, setIsMobileLayout] = useState(false)
+
+    /**
+     * Tracks the viewport width.
+     * ビューポート幅を追跡する副作用。
+     *
+     * 目的: 画面回転・ウィンドウリサイズに追随する。
+     * 依存関係: [] - 監視対象は固定の定数なので購読は 1 度だけ張る。
+     * クリーンアップ: リスナーを解除する。
+     */
+    useEffect(() => {
+        if (typeof window === "undefined" || typeof window.matchMedia !== "function") return
+
+        const query = window.matchMedia(MOBILE_LAYOUT_MEDIA_QUERY)
+        const sync = () => setIsMobileLayout(query.matches)
+
+        sync()
+        query.addEventListener("change", sync)
+        return () => query.removeEventListener("change", sync)
+    }, [])
+
+    return isMobileLayout
+}

package/src/client/route-helpers.spec.ts

@@ -0,0 +1,100 @@
+/**
+ * Bootstrap-ordering tests for the daily-report clientLoader factory.
+ * 日報 clientLoader 工場の起動順序テスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **prime は serverLoader の解決を待たずに先行する** (再訪の再検証前倒し)。
+ * - **ローダー時点でセッションを bootstrap する** (コールドロードの最重要最適化 —
+ *   ページマウントの effect まで生成を遅らせると、ストリーム開始がハイドレーション
+ *   完了の後ろに直列化される)。
+ * - **`hydrate = true`** (初期ハイドレーションでも実行される契約)。
+ */
+import { describe, expect, it, vi } from "vitest"
+
+const calls: string[] = []
+const bootstrapMock = vi.fn((options: { apiBasePath?: string; userKey: string | null }) => {
+    calls.push(`bootstrap:${options.userKey}`)
+})
+const primeMock = vi.fn(() => {
+    calls.push("prime")
+})
+
+vi.mock("./streaming/daily-report-ids-stream-session", () => ({
+    bootstrapDailyReportIdsStreamSession: (options: { apiBasePath?: string; userKey: string | null }) => bootstrapMock(options),
+    primeDailyReportIdsStreamSession: () => primeMock(),
+}))
+
+import { createDailyReportClientLoader, dailyReportShouldRevalidate } from "./route-helpers"
+
+describe("createDailyReportClientLoader", () => {
+    it("prime → serverLoader → bootstrap(userKey) の順で起動し、serverData を素通しする", async () => {
+        calls.length = 0
+        const clientLoader = createDailyReportClientLoader<{ userId: string | null; extra: number }>()
+        const serverLoader = vi.fn(async () => {
+            calls.push("serverLoader")
+            return { userId: "ENC8", extra: 42 }
+        })
+
+        const result = await clientLoader({ serverLoader })
+
+        expect(calls).toEqual(["prime", "serverLoader", "bootstrap:ENC8"])
+        expect(result).toEqual({ userId: "ENC8", extra: 42 })
+    })
+
+    it("userId が文字列でない serverData は userKey null で起動する", async () => {
+        bootstrapMock.mockClear()
+        const clientLoader = createDailyReportClientLoader()
+        await clientLoader({ serverLoader: async () => ({ userId: null }) })
+        expect(bootstrapMock).toHaveBeenCalledWith({ apiBasePath: undefined, userKey: null })
+
+        await clientLoader({ serverLoader: async () => ({}) })
+        expect(bootstrapMock).toHaveBeenLastCalledWith({ apiBasePath: undefined, userKey: null })
+    })
+
+    it("factory の apiBasePath オプションは bootstrap へ透過する", async () => {
+        bootstrapMock.mockClear()
+        const clientLoader = createDailyReportClientLoader({ apiBasePath: "/custom/api" })
+        await clientLoader({ serverLoader: async () => ({ userId: "ENC9" }) })
+        expect(bootstrapMock).toHaveBeenCalledWith({ apiBasePath: "/custom/api", userKey: "ENC9" })
+    })
+
+    it("hydrate フラグが立っている (初期ハイドレーションでも実行される契約)", () => {
+        const clientLoader = createDailyReportClientLoader()
+        expect(clientLoader.hydrate).toBe(true)
+    })
+})
+
+describe("dailyReportShouldRevalidate", () => {
+    /** 最小限の引数組み立て。 */
+    const makeArgs = (over: Record<string, unknown> = {}) =>
+        ({
+            defaultShouldRevalidate: true,
+            currentUrl: new URL("http://localhost/daily_report"),
+            nextUrl: new URL("http://localhost/daily_report"),
+            actionResult: undefined,
+            actionStatus: undefined,
+            formAction: undefined,
+            formData: undefined,
+            formEncType: undefined,
+            formMethod: undefined,
+            json: undefined,
+            text: undefined,
+            ...over,
+            // biome-ignore lint/suspicious/noExplicitAny: ShouldRevalidateFunctionArgs の完全構築はテストに不要
+        }) as any
+
+    it("同一 URL かつ送信シグナル無しは再検証しない", () => {
+        expect(dailyReportShouldRevalidate(makeArgs())).toBe(false)
+    })
+
+    it("URL が変われば既定に従う", () => {
+        expect(dailyReportShouldRevalidate(makeArgs({ nextUrl: new URL("http://localhost/daily_report?businessDate=2026-08-01") }))).toBe(true)
+    })
+
+    it("ミューテーション intent は再検証しない (SSE が伝搬を担う)", () => {
+        const formData = new FormData()
+        formData.set("intent", "toggleRead")
+        expect(dailyReportShouldRevalidate(makeArgs({ formData }))).toBe(false)
+    })
+})

package/src/client/route-helpers.ts

@@ -3,8 +3,7 @@
  * 日報ページ向け React Router ルートヘルパー (再検証ポリシー / クライアントローダー)。
  */
 import type { ShouldRevalidateFunction, ShouldRevalidateFunctionArgs } from "react-router"
-import type { DailyReportItem } from "../shared/types"
-import { defaultDailyReportClientConfig } from "./config-context"
+import { bootstrapDailyReportIdsStreamSession, primeDailyReportIdsStreamSession } from "./streaming/daily-report-ids-stream-session"
 
 /**
  * Prevents loader revalidation when POP navigations keep identical URL state.
@@ -32,50 +31,30 @@ export const dailyReportShouldRevalidate: ShouldRevalidateFunction = ({ actionRe
 }
 
 /**
- * Fetches the deferred daily report id list from the API endpoint.
- * API エンドポイントから日報 ID 一覧を遅延取得する処理。
- */
-export const fetchDailyReportIds = (apiBasePath: string = defaultDailyReportClientConfig.apiBasePath, forceRefresh = false): Promise<DailyReportItem[]> => {
-    const url = new URL(`${apiBasePath}/ids`, typeof window !== "undefined" ? window.location.origin : "http://localhost")
-    if (forceRefresh) {
-        url.searchParams.set("forceRefresh", "true")
-        url.searchParams.set("_t", Date.now().toString())
-    }
-    return fetch(url.toString(), {
-        method: "GET",
-        headers: { "Content-Type": "application/json" },
-        cache: "no-cache",
-    })
-        .then(async (response) => {
-            if (!response.ok) {
-                throw new Error(`Failed to fetch daily report ids: ${response.status} ${response.statusText}`)
-            }
-            return response
-        })
-        .then(async (response) => response.json())
-        .then((data) => {
-            if (!(data.ids && Array.isArray(data.ids))) {
-                throw new Error("Invalid daily report ids response")
-            }
-            return data.ids as DailyReportItem[]
-        })
-}
-
-/**
- * Creates a React Router clientLoader that merges server data with deferred report ids.
- * サーバーデータへ遅延日報 ID を合成する React Router clientLoader を生成する処理。
+ * Creates a React Router clientLoader that bootstraps the ids stream session.
+ * ID ストリームセッションを起動する React Router clientLoader を生成する処理。
+ *
+ * ID 一覧は Promise で返さず、モジュール常駐のストリームセッションが供給する
+ * (ページ側は `useDailyReportIdsStream` で購読する)。ローダー時点でセッションを
+ * 生成することが**コールドロードの最重要最適化** — ページマウントの effect まで
+ * 遅らせると、ストリームの開始が「ハイドレーション完了 + effect flush」の後ろに
+ * 直列化される。再訪 (セッション既存) は serverLoader を待たずに鮮度確認を先行させる。
+ *
+ * `config.apiBasePath` を上書きするアプリは同じ値を `options.apiBasePath` にも渡すこと
+ * (渡し忘れは初回 1 回だけ誤パス生成 → ページマウントの ensure が自己修復する)。
  *
  * 返す関数へ `hydrate = true as const` を付与済み (初期ハイドレーションでも実行される)。
  */
 export const createDailyReportClientLoader = <TServerData extends Record<string, unknown>>(options?: { apiBasePath?: string }) => {
-    const clientLoader = async (args: { serverLoader: () => Promise<unknown> }): Promise<TServerData & { dailyReportIds: Promise<DailyReportItem[]> }> => {
-        // サーバーローダーの解決を待つ間に ID 取得を並行開始する
-        const idsPromise = fetchDailyReportIds(options?.apiBasePath)
+    const clientLoader = async (args: { serverLoader: () => Promise<unknown> }): Promise<TServerData> => {
+        // 再訪の主経路: 既存セッションの鮮度確認を serverLoader より先に始める
+        primeDailyReportIdsStreamSession()
         const serverData = (await args.serverLoader()) as TServerData
-        return {
-            ...serverData,
-            dailyReportIds: idsPromise,
-        }
+        // 不在なら生成 (コールドロードでハイドレーションと並行してフェッチを開始)、
+        // 既存なら userKey 照合 (別ユーザーは描画前に破棄・再生成) + 鮮度確認
+        const rawUserId = (serverData as { userId?: unknown }).userId
+        bootstrapDailyReportIdsStreamSession({ apiBasePath: options?.apiBasePath, userKey: typeof rawUserId === "string" ? rawUserId : null })
+        return serverData
     }
     clientLoader.hydrate = true as const
     return clientLoader