@aiquants/daily-report 0.1.1

package/src/client/hooks/use-daily-report.ts

@@ -0,0 +1,426 @@
+/**
+ * Suspense-friendly daily report detail loader (fetch-driven).
+ * fetch ベースの日報詳細ローダー。
+ */
+import { useCallback, useEffect, useRef, useState } from "react"
+import { normalizeBusinessDateKey } from "../../shared/business-date"
+import { createLogger, LogLevel } from "../../shared/logger"
+import type { DailyReportDetail } from "../../shared/types"
+import { useDailyReportConfig } from "../config-context"
+
+const logger = createLogger(LogLevel.INFO, "use-daily-report")
+
+// --- Configuration & Constants ---
+/**
+ * Retrieve global configuration or default.
+ * グローバル設定またはデフォルト値を取得する。
+ */
+const getGlobal = (k: string, d: number): number => {
+    if (typeof window === "undefined") return d
+    const v = (window as unknown as Record<string, unknown>)[k]
+    return typeof v === "number" && !Number.isNaN(v) ? v : d
+}
+const TTL = getGlobal("__DAILY_REPORT_CACHE_TTL__", 300_000)
+const REVIVE_MS = getGlobal("__DAILY_REPORT_CACHE_REVIVE_MS__", 60_000)
+const FETCH_DEBOUNCE_MS = 120
+
+// --- Cache Store (Centralized State) ---
+type CacheEntry<T> = { data: T; expiresAt: number }
+
+const DailyReportCache = {
+    reports: new Map<number, CacheEntry<DailyReportDetail>>(),
+    lists: new Map<string, CacheEntry<DailyReportDetail[]>>(),
+    pendingLists: new Map<string, Promise<DailyReportDetail[]>>(),
+    pendingReports: new Map<number, Promise<DailyReportDetail>>(),
+    listeners: new Set<(id: number) => void>(),
+    locks: new Set<number>(),
+    lastMutations: new Map<number, number>(),
+    recentDeletes: new Map<number, number>(),
+    lastPrune: 0,
+
+    /**
+     * Prune expired entries from the cache.
+     * キャッシュから期限切れのエントリを削除する。
+     */
+    prune() {
+        const now = Date.now()
+        // Prune at most once per minute
+        if (now - this.lastPrune < 60_000) return
+        this.lastPrune = now
+
+        // SWR のために古いデータを保持する。TTL 超過後すぐには削除せず、十分に古い（例えば 1時間経過した）データのみを破棄する
+        const GC_THRESHOLD = 60 * 60 * 1000 // 1 hour
+        for (const [id, entry] of this.reports) {
+            if (now - entry.expiresAt > GC_THRESHOLD) this.reports.delete(id)
+        }
+        for (const [key, entry] of this.lists) {
+            if (now - entry.expiresAt > GC_THRESHOLD) this.lists.delete(key)
+        }
+    },
+
+    /**
+     * Check if the cache entry is still valid.
+     * キャッシュエントリがまだ有効かを確認する。
+     */
+    isValid: (ex: number) => ex > Date.now(),
+    /**
+     * Notify all listeners of a report update.
+     * レポートの更新をすべてのリスナーに通知する。
+     */
+    notify: (id: number) => {
+        DailyReportCache.listeners.forEach((l) => {
+            l(id)
+        })
+    },
+
+    /**
+     * Retrieve a cached report by ID.
+     * ID でキャッシュされたレポートを取得する。
+     */
+    getReport(id: number, ignoreExpiry = false) {
+        const e = this.reports.get(id)
+        return e && (ignoreExpiry || this.isValid(e.expiresAt)) ? e.data : null
+    },
+
+    /**
+     * Retrieve a cached list of reports by business date key.
+     * 営業日キーでレポートのキャッシュリストを取得する。
+     */
+    getList(dateKey: string | null, ignoreExpiry = false) {
+        const e = dateKey && this.lists.get(dateKey)
+        return e && (ignoreExpiry || this.isValid(e.expiresAt)) ? e.data : null
+    },
+
+    /**
+     * Set a report in the cache and optionally sync with the list cache.
+     * キャッシュにレポートを設定し、必要に応じてリストキャッシュと同期する。
+     */
+    set(report: DailyReportDetail, expiresAt: number, syncList = true) {
+        this.reports.set(report.reportHubId, { data: report, expiresAt })
+        if (syncList) {
+            const dateKey = normalizeBusinessDateKey(report.date)
+            const listEntry = dateKey ? this.lists.get(dateKey) : null
+            if (listEntry && dateKey) {
+                const exists = listEntry.data.some((r) => r.reportHubId === report.reportHubId)
+                const data = exists ? listEntry.data.map((r) => (r.reportHubId === report.reportHubId ? report : r)) : [report, ...listEntry.data]
+                this.lists.set(dateKey, { ...listEntry, data })
+            }
+        }
+        this.notify(report.reportHubId)
+    },
+
+    /**
+     * Update a cached report with partial data.
+     * 部分的なデータでキャッシュされたレポートを更新する。
+     */
+    update(id: number, updates: Partial<DailyReportDetail>, strict = true) {
+        const entry = this.reports.get(id)
+        if (!entry?.data) return
+
+        if (strict && updates.updatedAt && entry.data.updatedAt) {
+            if (new Date(updates.updatedAt).getTime() < new Date(entry.data.updatedAt).getTime()) {
+                logger.warn(`[DailyReportCache] Stale update skipped id=${id}`)
+                return
+            }
+        }
+        this.set({ ...entry.data, ...updates } as DailyReportDetail, Math.max(entry.expiresAt, Date.now() + REVIVE_MS))
+    },
+
+    /**
+     * Delete a report from the cache and update the corresponding list.
+     * キャッシュからレポートを削除し、対応するリストを更新する。
+     */
+    delete(id: number, date: string) {
+        this.reports.delete(id)
+        const dateKey = normalizeBusinessDateKey(date)
+        const list = dateKey && this.lists.get(dateKey)
+        if (list && dateKey) {
+            this.lists.set(dateKey, { ...list, data: list.data.filter((r) => r.reportHubId !== id) })
+        }
+        this.notify(id)
+    },
+
+    /**
+     * Merge server report with cached report to handle optimistic updates and zombies.
+     * サーバーレポートとキャッシュレポートをマージして、楽観的更新とゾンビコメントを処理する。
+     */
+    merge(serverReport: DailyReportDetail, cachedReport?: DailyReportDetail | null) {
+        let report = serverReport
+        // Filter zombies
+        if (report.commentItems.some((c) => this.recentDeletes.has(c.id))) {
+            report = { ...report, commentItems: report.commentItems.filter((c) => !this.recentDeletes.has(c.id)) }
+        }
+        // Restore missing "my comments"
+        if (cachedReport) {
+            const serverIds = new Set(report.commentItems.map((c) => c.id))
+            const missing = cachedReport.commentItems.filter((c) => !serverIds.has(c.id) && c.isMine && Date.now() - new Date(c.createdAt).getTime() < 10000)
+            if (missing.length > 0) {
+                report = {
+                    ...report,
+                    commentItems: [...report.commentItems, ...missing].sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()),
+                }
+            }
+        }
+        return report
+    },
+
+    /**
+     * Hydrate the cache with fetched reports, handling comment merges and locks.
+     * フェッチされたレポートでキャッシュをハイドレートし、コメントのマージとロックを処理する。
+     */
+    cacheMany(reports: DailyReportDetail[], dateKey: string | null, fetchStart = 0) {
+        if (!reports.length) return []
+        this.prune()
+        const now = Date.now(),
+            expiresAt = now + TTL
+        for (const [id, t] of this.recentDeletes) if (now - t > 10000) this.recentDeletes.delete(id)
+
+        const processed = reports.map((r) => {
+            // Original logic: If locked, return server data directly (don't update cache, don't merge)
+            // ロックされている場合はサーバーデータをそのまま返す（キャッシュ更新せず、マージもしない）
+            if (this.locks.has(r.reportHubId)) return r
+
+            // Original logic: If recently mutated locally, prefer cached data
+            // 最近ローカルで変更された場合は、キャッシュデータを優先する
+            const lastMut = this.lastMutations.get(r.reportHubId)
+            if (lastMut && fetchStart > 0 && lastMut > fetchStart) {
+                return this.reports.get(r.reportHubId)?.data ?? r
+            }
+
+            const cached = this.reports.get(r.reportHubId)?.data
+            const merged = this.merge(r, cached)
+            this.set(merged, expiresAt, false)
+            return merged
+        })
+        if (dateKey) this.lists.set(dateKey, { data: processed, expiresAt })
+        return processed
+    },
+}
+
+// --- Public API Exports ---
+/**
+ * Update the cache for a single report.
+ * 単一レポートのキャッシュを更新する。
+ */
+export const writeCache = (r: DailyReportDetail, exp: number, sync = true) => DailyReportCache.set(r, exp, sync)
+/**
+ * Get a cached report by ID.
+ * ID でキャッシュされたレポートを取得する。
+ */
+export const getCachedReport = (id: number, opts?: { ignoreExpiry?: boolean }) => DailyReportCache.getReport(id, opts?.ignoreExpiry)
+/**
+ * Update specific fields of a cached report.
+ * キャッシュされたレポートの特定のフィールドを更新する。
+ */
+export const updateDailyReportCache = (id: number, u: Partial<DailyReportDetail>) => DailyReportCache.update(id, u)
+/**
+ * Delete a report from the cache.
+ * キャッシュからレポートを削除する。
+ */
+export const deleteDailyReportCache = (id: number, d: string) => DailyReportCache.delete(id, d)
+
+export const acquireMutationLock = (id: number) => {
+    DailyReportCache.locks.add(id)
+    DailyReportCache.lastMutations.set(id, Date.now())
+}
+export const releaseMutationLock = (id: number) => {
+    DailyReportCache.locks.delete(id)
+    DailyReportCache.lastMutations.set(id, Date.now())
+}
+export const registerRecentDeletion = (cId: number) => DailyReportCache.recentDeletes.set(cId, Date.now())
+
+/**
+ * Subscribe to cache-ready events for a specific report.
+ * Returns an unsubscribe function.
+ *
+ * 特定レポートのキャッシュ書き込みを監視する。
+ * 解除関数を返す。
+ */
+export const subscribeCacheReady = (reportHubId: number, callback: () => void): (() => void) => {
+    const listener = (id: number) => {
+        if (id === reportHubId) {
+            callback()
+        }
+    }
+    DailyReportCache.listeners.add(listener)
+    return () => {
+        DailyReportCache.listeners.delete(listener)
+    }
+}
+
+export const applyDailyReportServerUpdates = (_reportHubIdd: number, report: DailyReportDetail) => {
+    DailyReportCache.prune()
+    DailyReportCache.set(report, Date.now() + TTL)
+}
+
+// --- Data Loading ---
+/**
+ * Fetch a single report by ID.
+ * ID で単一のレポートを取得する。
+ */
+const fetchReportById = async (apiBasePath: string, id: number) => {
+    // 1. Cache Check
+    const cached = DailyReportCache.getReport(id)
+    if (cached) return cached
+
+    // 2. Prevent Duplicate Requests
+    const pending = DailyReportCache.pendingReports.get(id)
+    if (pending) return pending
+
+    // 3. Fetch
+    const start = Date.now()
+    const p = fetch(`${apiBasePath}/report?reportHubId=${id}`, { cache: "no-cache" })
+        .then((res) => (res.ok ? res.json() : Promise.reject(`HTTP ${res.status}`)))
+        .then((data) => {
+            if (data.error) throw new Error(data.error.message)
+            const report = data.report as DailyReportDetail
+            // 単一レポートの取得時にキャッシュを一括更新する
+            return DailyReportCache.cacheMany([report], null, start)[0]
+        })
+        .finally(() => DailyReportCache.pendingReports.delete(id))
+    DailyReportCache.pendingReports.set(id, p)
+    return p
+}
+
+/**
+ * Fetch reports by date key.
+ * 日付キーでレポートを取得する。
+ */
+const fetchReportsByDate = async (apiBasePath: string, dateKey: string) => {
+    const list = DailyReportCache.getList(dateKey)
+    if (list) return list
+
+    const pending = DailyReportCache.pendingLists.get(dateKey)
+    if (pending) return pending
+
+    const start = Date.now()
+    const p = fetch(`${apiBasePath}/business-date?businessDate=${encodeURIComponent(dateKey)}`, { cache: "no-cache" })
+        .then((res) => (res.ok ? res.json() : Promise.reject(`HTTP ${res.status}`)))
+        .then((data) => {
+            if (data.error) throw new Error(data.error.message)
+            return DailyReportCache.cacheMany(data.reports ?? [], dateKey, start)
+        })
+        .finally(() => DailyReportCache.pendingLists.delete(dateKey))
+    DailyReportCache.pendingLists.set(dateKey, p)
+    return p
+}
+
+// --- Hooks ---
+export type DailyReportDetailResource = { report: DailyReportDetail | null; error: Error | null; isLoading: boolean; isRefetching: boolean }
+
+/**
+ * Provides a fetcher-driven daily report detail reader with business-date aware caching.
+ * 営業日キャッシュ対応の日報詳細取得フック。
+ */
+export const useDailyReportDetail = (reportHubId: number, businessDate: string | null): DailyReportDetailResource => {
+    const { apiBasePath } = useDailyReportConfig()
+    const [report, setReport] = useState<DailyReportDetail | null>(() => DailyReportCache.getReport(reportHubId))
+    const [error, setError] = useState<Error | null>(null)
+    const [isLoading, setIsLoading] = useState(false)
+    const [isRefetching, setIsRefetching] = useState(false)
+    const reqRef = useRef({ id: reportHubId, token: 0 })
+
+    // 1. Cache Subscription
+    // キャッシュの購読: グローバルな DailyReportCache が更新されたときにローカルの状態を反応的に更新する。
+    // 依存関係: [reportHubId] - 対象のレポート ID が変更されたときのみ再購読する。
+    // クリーンアップ: メモリリークを防ぐためにリスナーを解除する。
+    useEffect(() => {
+        const onUpdate = (uid: number) => {
+            if (uid === reportHubId) {
+                const r = DailyReportCache.getReport(reportHubId, true)
+                setReport(r)
+            }
+        }
+        DailyReportCache.listeners.add(onUpdate)
+        return () => {
+            DailyReportCache.listeners.delete(onUpdate)
+        }
+    }, [reportHubId])
+
+    // 2. Data Loading & Stale Check
+    // データのロードと有効期限切れチェック: データのフェッチサイクル、 stale-while-revalidate ロジック、リクエストのデバウンスを管理する。
+    // 依存関係: [reportHubId, businessDate, apiBasePath]
+    useEffect(() => {
+        const dateKey = normalizeBusinessDateKey(businessDate)
+        const token = (reqRef.current.token || 0) + 1
+        reqRef.current = { id: reportHubId, token }
+
+        if (reportHubId <= 0) {
+            setReport(null)
+            setError(reportHubId === 0 ? new Error("Invalid ID") : null)
+            setIsLoading(false)
+            setIsRefetching(false)
+            return
+        }
+
+        // Cache Check
+        let cached = DailyReportCache.getReport(reportHubId, true)
+        let isStale = false
+        if (cached) {
+            isStale = !DailyReportCache.isValid(DailyReportCache.reports.get(reportHubId)?.expiresAt ?? 0)
+        } else if (dateKey) {
+            const list = DailyReportCache.getList(dateKey, true)
+            const found = list?.find((r) => r.reportHubId === reportHubId)
+            if (found) {
+                cached = found
+                isStale = !DailyReportCache.isValid(DailyReportCache.lists.get(dateKey)?.expiresAt ?? 0)
+            }
+        }
+        setReport(cached)
+
+        // If cached and valid, we are done
+        if (cached && !isStale) {
+            setError(null)
+            setIsLoading(false)
+            setIsRefetching(false)
+            return
+        }
+
+        setIsLoading(!cached)
+        setIsRefetching(true)
+
+        const timer = setTimeout(async () => {
+            if (reqRef.current.token !== token) return
+            try {
+                let r: DailyReportDetail | null = null
+                if (dateKey) {
+                    const res = await fetchReportsByDate(apiBasePath, dateKey)
+                    r = res.find((item) => item.reportHubId === reportHubId) ?? null
+                } else {
+                    r = await fetchReportById(apiBasePath, reportHubId)
+                }
+
+                if (reqRef.current.token === token) {
+                    setReport(r)
+                    setError(null)
+                }
+            } catch (e) {
+                if (reqRef.current.token === token) setError(e instanceof Error ? e : new Error("Load failed"))
+            } finally {
+                if (reqRef.current.token === token) {
+                    setIsLoading(false)
+                    setIsRefetching(false)
+                }
+            }
+        }, FETCH_DEBOUNCE_MS)
+
+        return () => clearTimeout(timer)
+    }, [reportHubId, businessDate, apiBasePath])
+
+    return { report, error, isLoading, isRefetching }
+}
+
+/**
+ * Provides a business-date aware prefetch helper.
+ * 営業日キャッシュを活用した日報プリフェッチ補助フック。
+ */
+export const useDailyReportPrefetch = () => {
+    const { apiBasePath } = useDailyReportConfig()
+    return useCallback(
+        (date: string | null) => {
+            const k = normalizeBusinessDateKey(date)
+            if (k && !DailyReportCache.getList(k)) fetchReportsByDate(apiBasePath, k).catch((e) => logger.warn("Prefetch error", k, e))
+        },
+        [apiBasePath],
+    )
+}

package/src/client/hooks/use-dynamic-viewport-height.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared hook for calculating viewport height of virtual scroll containers.
+ * 仮想スクロールコンテナのビューポート高さを計測する共通フック。
+ */
+import { type RefObject, useCallback, useEffect, useState } from "react"
+
+type UseDynamicViewportHeightOptions = {
+    enableMutationObserver?: boolean
+    bottomGap?: number
+    minFallbackHeight?: number
+}
+
+type UseDynamicViewportHeightResult = {
+    viewportHeight: number
+    updateViewportHeight: () => void
+}
+
+/**
+ * Computes and updates the viewport height for scroll containers while reacting to layout changes.
+ * レイアウト変化に追従しながらスクロールコンテナのビューポート高さを算出して更新する関数。
+ */
+export const useDynamicViewportHeight = (containerRef: RefObject<HTMLDivElement | null>, options?: UseDynamicViewportHeightOptions): UseDynamicViewportHeightResult => {
+    const { enableMutationObserver = false, bottomGap = 4, minFallbackHeight = 240 } = options ?? {}
+    const [viewportHeight, setViewportHeight] = useState(600)
+
+    const updateViewportHeight = useCallback(() => {
+        if (typeof window === "undefined") {
+            return
+        }
+
+        const target = containerRef.current
+        if (!target) {
+            return
+        }
+
+        // 要素が非表示の場合は計測しない (display: none など)
+        if (target.offsetParent === null && window.getComputedStyle(target).position !== "fixed") {
+            return
+        }
+
+        const toNumber = (value: string) => Number.parseFloat(value) || 0
+        const { top: containerTop } = target.getBoundingClientRect()
+        const parentRect = target.parentElement?.getBoundingClientRect()
+        const rootStyle = window.getComputedStyle(document.documentElement)
+        const footerHeight = toNumber(rootStyle.getPropertyValue("--footer-height"))
+        const headerHeight = toNumber(rootStyle.getPropertyValue("--header-height"))
+        const scrollbarHeight = toNumber(rootStyle.getPropertyValue("--scrollbar-height"))
+        const containerStyle = window.getComputedStyle(target)
+        const marginBottom = toNumber(containerStyle.marginBottom)
+        const paddingBottom = toNumber(containerStyle.paddingBottom)
+        const viewportBottom = window.innerHeight - footerHeight - scrollbarHeight - bottomGap
+        const effectiveBottom = parentRect ? Math.min(parentRect.bottom, viewportBottom) : viewportBottom
+        const layoutTop = parentRect ? Math.max(parentRect.top, headerHeight) : headerHeight
+        const effectiveTop = Math.max(containerTop, layoutTop)
+        const availableHeight = effectiveBottom - effectiveTop - marginBottom - paddingBottom
+        const safeAvailableHeight = Number.isFinite(availableHeight) ? Math.floor(availableHeight) : 0
+        const clampedHeight = safeAvailableHeight > 0 ? safeAvailableHeight : minFallbackHeight
+
+        if (clampedHeight > 0 && Number.isFinite(clampedHeight)) {
+            setViewportHeight((previous) => (Math.abs(previous - clampedHeight) > 1 ? clampedHeight : previous))
+        }
+    }, [bottomGap, containerRef, minFallbackHeight])
+
+    useEffect(() => {
+        if (typeof window === "undefined") {
+            return
+        }
+
+        let frameId: number | null = null
+        let timeoutId: number | null = null
+        let resizeObserver: ResizeObserver | null = null
+        let mutationObserver: MutationObserver | null = null
+        const scheduleUpdate = () => {
+            if (frameId !== null) {
+                window.cancelAnimationFrame(frameId)
+            }
+            frameId = window.requestAnimationFrame(() => {
+                updateViewportHeight()
+            })
+        }
+
+        // 初期表示直後とわずかな遅延後に計測して安定させる
+        scheduleUpdate()
+        timeoutId = window.setTimeout(() => {
+            scheduleUpdate()
+        }, 150)
+
+        const containerElement = containerRef.current
+        if (typeof ResizeObserver !== "undefined" && containerElement) {
+            resizeObserver = new ResizeObserver(() => {
+                // コンテナと親要素のリサイズ変化に追従する
+                scheduleUpdate()
+            })
+            resizeObserver.observe(containerElement)
+            if (containerElement.parentElement) {
+                resizeObserver.observe(containerElement.parentElement)
+            }
+        }
+
+        if (enableMutationObserver && typeof MutationObserver !== "undefined") {
+            mutationObserver = new MutationObserver(() => {
+                // ルートのスタイル変更にも追従する
+                scheduleUpdate()
+            })
+            mutationObserver.observe(document.documentElement, { attributes: true, attributeFilter: ["style"] })
+        }
+
+        window.addEventListener("resize", scheduleUpdate)
+
+        return () => {
+            if (frameId !== null) {
+                window.cancelAnimationFrame(frameId)
+            }
+            if (timeoutId !== null) {
+                window.clearTimeout(timeoutId)
+            }
+            window.removeEventListener("resize", scheduleUpdate)
+            resizeObserver?.disconnect()
+            mutationObserver?.disconnect()
+        }
+    }, [enableMutationObserver, updateViewportHeight, containerRef])
+
+    return {
+        viewportHeight,
+        updateViewportHeight,
+    }
+}

package/src/client/route-helpers.ts

@@ -0,0 +1,76 @@
+/**
+ * React Router route helpers for the daily-report page (revalidation policy / client loader).
+ * 日報ページ向け React Router ルートヘルパー (再検証ポリシー / クライアントローダー)。
+ */
+import type { ShouldRevalidateFunction, ShouldRevalidateFunctionArgs } from "react-router"
+import type { DailyReportItem } from "../shared/types"
+import { defaultDailyReportClientConfig } from "./config-context"
+
+/**
+ * Prevents loader revalidation when POP navigations keep identical URL state.
+ * URL 状態が同一の POP ナビゲーション時にローダー再検証を抑止。
+ */
+export const dailyReportShouldRevalidate: ShouldRevalidateFunction = ({ actionResult, actionStatus, currentUrl, defaultShouldRevalidate, formAction, formData, formEncType, formMethod, json, nextUrl, text }: ShouldRevalidateFunctionArgs) => {
+    if (!defaultShouldRevalidate) {
+        return false
+    }
+
+    const isSameUrl = currentUrl.pathname === nextUrl.pathname && currentUrl.search === nextUrl.search && currentUrl.hash === nextUrl.hash
+    if (!isSameUrl) {
+        return defaultShouldRevalidate
+    }
+
+    if (formData) {
+        const intent = formData.get("intent")
+        if (intent === "toggleRead" || intent === "toggleStar" || intent === "addComment" || intent === "deleteComment" || intent === "create" || intent === "update" || intent === "publish" || intent === "delete") {
+            return false
+        }
+    }
+
+    const hasSubmission = actionResult !== undefined || actionStatus !== undefined || formAction !== undefined || formData !== undefined || formEncType !== undefined || formMethod !== undefined || json !== undefined || text !== undefined
+    return hasSubmission ? defaultShouldRevalidate : false
+}
+
+/**
+ * Fetches the deferred daily report id list from the API endpoint.
+ * API エンドポイントから日報 ID 一覧を遅延取得する処理。
+ */
+export const fetchDailyReportIds = (apiBasePath: string = defaultDailyReportClientConfig.apiBasePath): Promise<DailyReportItem[]> =>
+    fetch(`${apiBasePath}/ids`, {
+        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 を生成する処理。
+ *
+ * 返す関数へ `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 serverData = (await args.serverLoader()) as TServerData
+        return {
+            ...serverData,
+            dailyReportIds: idsPromise,
+        }
+    }
+    clientLoader.hydrate = true as const
+    return clientLoader
+}

package/src/client/ui/button.tsx

@@ -0,0 +1,42 @@
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react"
+import { cn } from "./cn"
+
+const buttonVariants = cva(
+    "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+    {
+        variants: {
+            variant: {
+                default: "bg-primary text-primary-foreground hover:bg-primary/90",
+                destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+                outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+                secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+                ghost: "hover:bg-accent hover:text-accent-foreground",
+                link: "text-primary underline-offset-4 hover:underline",
+            },
+            size: {
+                default: "h-10 px-4 py-2",
+                sm: "h-9 rounded-md px-3",
+                lg: "h-11 rounded-md px-8",
+                icon: "h-10 w-10",
+            },
+        },
+        defaultVariants: {
+            variant: "default",
+            size: "default",
+        },
+    },
+)
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return <Comp className={cn(buttonVariants({ variant, size, className }))} ref={ref} {...props} />
+})
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

package/src/client/ui/cn.ts

@@ -0,0 +1,14 @@
+/**
+ * Tailwind class combiner (clsx + tailwind-merge).
+ * Tailwind クラスを結合・重複解決するユーティリティ。
+ */
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+/**
+ * Combines class values and resolves Tailwind conflicts.
+ * クラス値を結合し Tailwind の衝突を解決する処理。
+ */
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}