@aiquants/daily-report 0.6.2 → 0.7.0

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/utils/constants.spec.ts

@@ -0,0 +1,96 @@
+/**
+ * Value-pinning tests for the shared scroll tuning constants.
+ * 共有スクロール調整値の値を固定するテスト。
+ *
+ * ❗ **「共有定数を参照していること」だけを見るテストでは守れない。** 参照はそのままに
+ * 値だけを是正前へ戻す変更は、ビューを描画するテストでは検出できない
+ * (どちらも同じオブジェクト参照になるため)。ここで値そのものを固定する。
+ *
+ * `TAP_SCROLL_CIRCLE_OPTIONS` の docstring は「ビューポート 800px での実測表」を
+ * 根拠として掲げている。その表をパッケージ本体の `computeTapScrollSpeed` で
+ * 実際に再現し、**文書と実装が食い違ったらテストが落ちる**ようにする。
+ */
+import { computeTapScrollSpeed, TAP_SCROLL_SPEED_DEFAULTS } from "@aiquants/virtualscroll"
+import { describe, expect, it } from "vitest"
+import { CONTENT_DRAG_POINTER_INPUTS, TAP_SCROLL_CIRCLE_OPTIONS } from "./constants"
+
+/** docstring の実測表が前提とするビューポート。 */
+const VIEWPORT_SIZE = 800
+
+/** 引き幅の基準 (パッケージの既定 `maxVisualDistance`)。 */
+const MAX_DISTANCE = TAP_SCROLL_SPEED_DEFAULTS.maxDistance
+
+/**
+ * `ScrollBar` の `minSpeedMultiplier` 既定値。
+ *
+ * ❗ `TAP_SCROLL_CIRCLE_OPTIONS` は `minSpeedMultiplier` を指定せず既定に委ねている。
+ * **値をここへ写さず、パッケージが公開している定数を読む。** 写すと、既定が変わったときに
+ * この表が「間違った値のまま緑で通り続ける」状態になる。
+ */
+const DEFAULT_MIN_SPEED_MULTIPLIER = TAP_SCROLL_SPEED_DEFAULTS.minSpeedMultiplier
+
+/** タップサークルを `ratio` (0〜1) だけ引いたときの速度 (px/s)。 */
+const speedAt = (ratio: number) =>
+    computeTapScrollSpeed({
+        distance: ratio * MAX_DISTANCE,
+        maxDistance: MAX_DISTANCE,
+        viewportSize: VIEWPORT_SIZE,
+        minSpeedMultiplier: DEFAULT_MIN_SPEED_MULTIPLIER,
+        maxSpeedMultiplier: TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedMultiplier ?? 0,
+        hasCustomMaxSpeedMultiplier: TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedMultiplier !== undefined,
+        curve: TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedCurve,
+    })
+
+describe("TAP_SCROLL_CIRCLE_OPTIONS", () => {
+    it("チューニング値が固定されている", () => {
+        expect(TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedMultiplier).toBe(8)
+        expect(TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedCurve).toEqual({ exponentialSteepness: 3, exponentialScale: 8 })
+    })
+
+    it("easedOffset を使わない (低速域の分解能を下駄で潰さない)", () => {
+        // `easedOffset` は速度レンジ全体に対する比率として引き距離 0 へ適用される。
+        // 0.18 を入れると引き距離 0 で 1,283 px/s (160px 行で毎秒 8 行) から始まってしまう
+        expect(TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedCurve?.easedOffset).toBeUndefined()
+    })
+
+    it("minSpeedMultiplier を指定せずパッケージ既定に委ねている", () => {
+        expect(TAP_SCROLL_CIRCLE_OPTIONS.minSpeedMultiplier).toBeUndefined()
+    })
+
+    it.each([
+        [0, 160],
+        [0.25, 525],
+        [0.5, 1298],
+        [1, 6400],
+    ])("docstring の実測表を再現する (引き %s → 約 %s px/s)", (ratio, expected) => {
+        expect(speedAt(ratio)).toBeCloseTo(expected, 0)
+    })
+
+    it("引き距離に対して狭義単調で、死角 (速度が変わらない区間) が無い", () => {
+        // 旧値 (steepness 7.5 / scale 14) では引き幅の 43.85% が死角だった
+        const samples = Array.from({ length: 101 }, (_, index) => speedAt(index / 100))
+        for (let index = 1; index < samples.length; index += 1) {
+            expect(samples[index], `ratio=${index / 100}`).toBeGreaterThan(samples[index - 1])
+        }
+    })
+
+    it("最高速が 1 フレームでオーバースキャン分を飛び越さない", () => {
+        // 60fps で 1 フレーム 106.7px = 160px 行の 0.67 行。オーバースキャン 15 行に対して十分小さい
+        expect(speedAt(1) / 60).toBeLessThan(160)
+    })
+})
+
+describe("CONTENT_DRAG_POINTER_INPUTS", () => {
+    it("直接操作 (指・ペン) を必ず含む", () => {
+        // ❗ ここが最重要。`ScrollPane` はネイティブのスクロール領域を持たないため、
+        // "touch" を外すとタッチ端末から一覧をスクロールする手段が完全に消える
+        expect(CONTENT_DRAG_POINTER_INPUTS).toContain("touch")
+        expect(CONTENT_DRAG_POINTER_INPUTS).toContain("pen")
+    })
+
+    it("マウスだけを除外する", () => {
+        // マウスのドラッグは行のタップ判定・テキスト選択と競合するため外す
+        expect(CONTENT_DRAG_POINTER_INPUTS).not.toContain("mouse")
+        expect([...CONTENT_DRAG_POINTER_INPUTS]).toEqual(["pen", "touch"])
+    })
+})

package/src/client/utils/constants.ts

@@ -21,9 +21,54 @@ export const WHEEL_RESET_TIMEOUT_MS = 240
 export const VIRTUAL_SCROLL_OVERSCAN_COUNT = 15
 export const SCROLL_BAR_WIDTH = 8
 export const MAX_PREVIEW_LINES = 3
+
+/**
+ * Tap-scroll circle tuning shared by every daily-report list.
+ * 日報のすべての一覧が共有するタップスクロールサークルの調整値。
+ *
+ * ❗ **List タブと DetailList タブで同じ値を使うこと。** 片方だけ独自定義にすると、
+ * 同じ指の位置でタブごとに速度が何十倍も違う (実測で最大 77 倍) という事故になる。
+ *
+ * 値の根拠 (ビューポート 800px で実測):
+ *
+ * | 引き距離 | 速度 | List (行 160px) |
+ * | --- | --- | --- |
+ * | 0 | 160 px/s | 1 行/秒 |
+ * | 1/4 | 525 px/s | 3.3 行/秒 |
+ * | 1/2 | 1,298 px/s | 8 行/秒 |
+ * | 最大 | 6,400 px/s | 40 行/秒 (0.67 行/フレーム) |
+ *
+ * - `exponentialSteepness: 3` — 引き幅の前半をゆっくりにして微速の分解能を確保する。
+ *   大きくしすぎると低速域が最小速度へ張り付いて**引いても動かない死角**になる
+ *   (旧値 7.5 では引き幅の 43.85% が死角だった)。
+ * - `exponentialScale: 8` — 最高速の上限 (ビューポート比)。`maxSpeedMultiplier` と揃えて
+ *   上限がどちらで決まるかを一意にする。1 フレームあたりの移動をオーバースキャン
+ *   (`VIRTUAL_SCROLL_OVERSCAN_COUNT`) の行数より十分小さく保つ値にすること。
+ * - `easedOffset` は使わない。最小速度 160 px/s で十分に遅く、下駄を履かせると
+ *   低速域の分解能がその分だけ失われる。
+ *
+ * 長距離の移動はタップスクロールではなくスクロールバーのつまみ (と
+ * `BusinessDayThumbOverlay` の日付表示) が担う。ここを速くして解こうとしない。
+ */
 export const TAP_SCROLL_CIRCLE_OPTIONS: ScrollBarTapCircleOptions = {
     enabled: true,
     renderVisual: tapScrollCircleSampleVisual,
-    maxSpeedCurve: { exponentialSteepness: 7.5, exponentialScale: 14, easedOffset: 0.18 },
-    maxSpeedMultiplier: 18,
+    maxSpeedCurve: { exponentialSteepness: 3, exponentialScale: 8 },
+    maxSpeedMultiplier: 8,
 }
+
+/**
+ * Pointer types allowed to drag-scroll the list content.
+ * 一覧のコンテンツ領域をドラッグしてスクロールできるポインタ種別。
+ *
+ * ❗ **`enablePointerDrag` を丸ごと切ってはならない。** `ScrollPane` はコンテンツを
+ * transform で動かしておりネイティブのスクロール領域を持たない
+ * (`.aqvs-scroll-pane-content` は `overflow: hidden`) ため、切るとタッチ端末から
+ * スクロール手段が消える (一度そうしてしまい、モバイルで一切スクロールできなくなった)。
+ *
+ * マウスのドラッグだけを外す。行のタップ判定 (`useTapClick`) ・テキスト選択と競合するため。
+ * 画面幅のメディアクエリで切り替える案は採らなかった。画面幅は入力手段を表さないので
+ * 「主入力がマウスのタッチ対応ノート」のような端末を取りこぼす。判定は**イベントの
+ * ポインタ種別**で行うため、同一端末でマウスと指を使い分けても常に正しく振る舞う。
+ */
+export const CONTENT_DRAG_POINTER_INPUTS = ["pen", "touch"] as const

package/src/client.ts

@@ -3,6 +3,8 @@
  * @aiquants/daily-report の client エントリ。React コンポーネント・フック・ルートヘルパーを公開。
  */
 export * from "./client/components/business-day-thumb-overlay"
+export * from "./client/components/daily-report-attachment-indicator"
+export * from "./client/components/daily-report-attachment-list"
 export * from "./client/components/daily-report-comment-item"
 export * from "./client/components/daily-report-comment-section"
 export * from "./client/components/daily-report-detail-list"