displaying-timelines

タイムラインとアクティビティコンポーネントの表示

目的

このスキルを使うと、シンプルな縦型タイムラインから複雑なインタラクティブなガントチャートまで、タイムラインとアクティビティコンポーネントを体系的に作成できます。ユースケースとデータの特性に基づいた明確な判断基準により、パフォーマンス、リアルタイム更新、アクセシブルな実装を最適化できます。

使用するタイミング

次のような場合にこのスキルを有効にします：

• アクティビティフィード（ソーシャル、通知、監査ログ）を作成する
• タイムライン（縦型、横型、インタラクティブ）を表示する
• ガントチャートやプロジェクトスケジュールを作成する
• カレンダーインターフェース（月、週、日表示）を実装する
• 時系列のイベントや履歴データを表示する
• リアルタイムのアクティビティ更新を処理する
• タイムスタンプのフォーマット（相対、絶対）が必要である
• タイムラインのアクセシビリティやレスポンシブな動作を確保する

クイック判断フレームワーク

ユースケースに基づいてコンポーネントの種類を選択します：

Social Activity        → Activity Feed (infinite scroll, reactions)
System Events          → Audit Log (searchable, exportable, precise timestamps)
User Notifications     → Notification Feed (read/unread, grouped by date)
Historical Events      → Vertical Timeline (milestones, alternating sides)
Project Planning       → Gantt Chart (dependencies, drag-to-reschedule)
Scheduling             → Calendar Interface (month/week/day views)
Interactive Roadmap    → Horizontal Timeline (zoom, pan, filter)

詳細な選定基準については、references/component-selection.mdを参照してください。

主な実装パターン

アクティビティフィード

ソーシャルフィードのパターン：

• ユーザーのアバター＋名前＋アクションの説明
• 相対タイムスタンプ（「2時間前」）
• リアクションとコメント
• ページネーション付きの無限スクロール
• WebSocket によるリアルタイム更新
• references/activity-feeds.mdを参照

通知フィードのパターン：

• 日付ごとのセクションにグループ化
• インジケーター付きの既読／未読状態
• すべて既読にする機能
• 通知の種類でフィルター
• アクションボタン（表示、非表示）
• references/notification-feeds.mdを参照

監査ログのパターン：

• 正確なタイムスタンプ付きのシステムイベント
• ユーザーアクションの追跡
• 高度なフィルターを使った検索
• エクスポート可能（CSV、JSON）
• セキュリティを重視した表示
• references/audit-logs.mdを参照

例：examples/social-activity-feed.tsx

タイムラインの可視化

縦型タイムライン：

• イベントを時系列順に積み重ねる
• マーカードット付きの接続線
• 日付マーカーとイベントカード
• 左右交互の配置も可能
• 最適な用途：履歴イベント、プロジェクトのマイルストーン
• references/vertical-timelines.mdを参照

横型タイムライン：

• イベントを水平軸に沿って配置
• スクロールまたはズームで移動
• ズームレベルによって密度が変化
• 最適な用途：プロジェクトのタイムライン、ロードマップ
• references/horizontal-timelines.mdを参照

インタラクティブなタイムライン：

• イベントをクリックして詳細を表示
• カテゴリー／種類でフィルター
• ズームイン／ズームアウトのコントロール
• パンとスクロールによる移動
• 最適な用途：データ探索、高度なインタラクティブ操作
• references/interactive-timelines.mdを参照

例：examples/milestone-timeline.tsx

ガントチャート

プロジェクト計画機能：

• タスクを横棒として表示
• 矢印で依存関係を表示
• クリティカルパスを強調表示
• ドラッグしてスケジュールを変更
• 進捗インジケーター
• マイルストーンマーカー（ひし形）
• リソースの割り当て
• 今日を示す線
• ズームレベル（日／週／月／年）

ガントチャートのデータを生成するには：

python scripts/generate_gantt_data.py --tasks 50 --dependencies auto

実装の詳細はreferences/gantt-patterns.mdを参照してください。

例：examples/project-gantt.tsx

カレンダーインターフェース

月表示：

• 従来型のカレンダーグリッド
• 日付セル内にイベントを表示
• クリックして作成／編集
• カテゴリーを色分け
• 複数のカレンダーを重ねて表示

週表示：

• 時間枠（毎時）
• ドラッグ可能なブロックとしてイベントを表示
• サイズ変更で時間を変更
• 複数のカレンダーを重ねて表示

日表示／アジェンダ表示：

• 詳細な1日のスケジュール
• 時間と所要時間を含むリスト形式
• 場所と参加者
• スクロール可能なタイムライン

すべての表示形式についてはreferences/calendar-patterns.mdを参照してください。

例：examples/calendar-scheduler.tsx

タイムスタンプの書式設定

基本的なタイムスタンプのパターン：

相対表示（最近のイベント）：

• 「たった今」（1分未満）
• 「5分前」
• 「3時間前」
• 「昨日の午後3:42」

絶対表示（古いイベント）：

• 「2025年1月15日」
• 「2025年1月15日 午後3:42」
• API には ISO 8601 を使用

実装時の考慮事項：

• タイムゾーンの処理（ユーザーの現地時刻を表示）
• ロケールに応じた書式設定
• ホバー時に正確なタイムスタンプを表示
• 相対時刻を自動更新

タイムスタンプの書式を統一するには：

node scripts/format_timestamps.js --locale en-US --timezone auto

完全なパターンについては、references/timestamp-formatting.md を参照してください。

リアルタイム更新

ライブアクティビティフィード：

• 新しいイベントには WebSocket または SSE を使用
• 滑らかな挿入アニメーション
• 「新しいアイテムが X 件あります」という通知バナー
• クリックして新しいアイテムを読み込む
• ユーザー操作に対する楽観的更新

実装パターン：

1. ユーザーの操作をすぐに表示する
2. タイムスタンプを「たった今」に更新する
3. バックグラウンドでサーバーに送信する
4. エラーが発生した場合はロールバックする

WebSocket のパターンについては、references/real-time-updates.md を参照してください。

例：examples/realtime-activity.tsx

パフォーマンスの最適化

重要なパフォーマンスのしきい値：

<100 events       → Client-side rendering, no virtualization
100-1,000 events  → Virtual scrolling recommended
1,000+ events     → Virtual scrolling + server pagination
Real-time         → Debounce updates, batch insertions

最適化の戦略：

• タイムラインアイテムのコンポーネントをメモ化する
• イベントの詳細を遅延読み込みする
• 長いタイムラインには仮想スクロールを使用する
• リアルタイム更新をデバウンスする（500ms ごとにバッチ処理）
• タイムスタンプの計算を最適化する

パフォーマンスをベンチマークするには：

node scripts/benchmark_timeline.js --events 10000

詳細については、references/performance-optimization.md を参照してください。

アクセシビリティ要件

WCAG 準拠に必要な項目：

セマンティック HTML：

• タイムラインには <ol> または <ul> を使用する
• 見出し階層を適切に設定する
• セマンティックな time 要素を使用する

ARIA パターン：

• アクティビティフィードには role="feed" を使用する
• タイムラインアイテムには role="article" を使用する
• タイムスタンプには aria-label を使用する
• 読み込み中は aria-busy を使用する

キーボード操作：

• Tab キーでインタラクティブなアイテム間を移動する
• 矢印キーでタイムラインを移動する
• Enter キーまたは Space キーでアイテムを展開する
• 最新／最古の項目にスキップするコントロールを用意する

スクリーンリーダーのサポート：

• フィード内の新しいアイテムを読み上げる
• タイムスタンプに説明的なラベルを付ける
• ガントチャートの進捗状況を通知する

アクセシビリティを検証するには：

node scripts/validate_timeline_accessibility.js

完全な要件については、references/accessibility-patterns.md を参照してください。

レスポンシブデザイン

実績のある3つの戦略：

1. 縦方向に並べる（モバイル）

• 横方向のレイアウトを縦方向に変更する
• 時系列順を維持する
• 余白とフォントサイズを調整する

2. 表示をシンプルにする

• 必要な情報だけを表示する
• 詳細は展開して表示する
• 視覚的な複雑さを軽減する

3. 横方向にスクロールする

• レイアウトをそのまま維持する
• タッチスクロールを有効にする
• スクロールインジケーターを追加する

実装例については、references/responsive-strategies.md を参照してください。

例：examples/responsive-timeline.tsx

ライブラリの推奨

タイムライン：react-chrono（柔軟）

リッチコンテンツを含むタイムラインの可視化に最適です：

• 横方向、縦方向、交互のレイアウト
• 画像と動画のサポート
• アイテムのカスタムレンダリング
• TypeScript のサポート
• 標準でレスポンシブ対応

npm install react-chrono

セットアップについては、examples/react-chrono-timeline.tsx を参照してください。

代替：react-vertical-timeline-component

• シンプルですっきりした縦型タイムライン
• 軽量（約10KB）
• アイコンのサポート
• 基本的なタイムラインに適しています

ガントチャート：SVAR React Gantt

プロジェクト管理に最適です：

• モダンで依存関係なし
• タスクのドラッグ＆ドロップ
• 依存関係とマイルストーン
• 外観をカスタマイズ可能
• TypeScript に対応

npm install @svar/gantt

エンタープライズ向けの代替：Bryntum Gantt

• 機能が充実したソリューション
• 商用ライセンスが必要
• 複雑なプロジェクトに対応
• 高度なリソース管理

カレンダー：react-big-calendar

スケジュール管理インターフェースに最適です：

• 月、週、日、予定リストの各表示
• イベントのドラッグ＆ドロップ
• スタイルをカスタマイズ可能
• 大規模なコミュニティによるサポート

npm install react-big-calendar

代替：FullCalendar

• プレミアム機能を利用可能
• 優れたドキュメント
• 複数のフレームワークをサポート

詳細な比較については、references/library-comparison.md を参照してください。

デザイントークンの統合

タイムラインでは、テーマ設定の一貫性を保つためにデザイントークンのスキルを使用します。

タイムライン固有のトークン：

• --timeline-line-color - 接続線の色
• --timeline-dot-color - イベントマーカーの色
• --timeline-dot-active-color - 現在のイベント／アクティブなイベント
• --event-card-bg - イベントカードの背景
• --timestamp-color - タイムスタンプのテキスト

標準のトークンカテゴリ：

• 背景と状態のカラー トークン
• 間隔とパディングのスペーシングトークン
• テキストの階層構造のためのタイポグラフィトークン
• カードの浮き上がり表現のためのシャドウトークン
• アニメーションのためのモーショントークン

ライト、ダーク、ハイコントラスト、カスタムのテーマに対応しています。 テーマの切り替えについては、design-tokens スキルを参照してください。

実際に動作するサンプル

要件に合ったサンプルから始めてください。

social-activity-feed.tsx       # Social feed with reactions
notification-center.tsx        # Notification system with filters
audit-log-viewer.tsx           # System audit log
milestone-timeline.tsx         # Vertical timeline with milestones
project-gantt.tsx              # Gantt chart with dependencies
calendar-scheduler.tsx         # Full calendar with all views
realtime-activity.tsx          # Live updates via WebSocket
responsive-timeline.tsx        # Mobile-optimized timeline

テストツール

モックのタイムラインデータを生成します：

python scripts/generate_timeline_data.py --events 500 --realtime

リアルタイム更新をテストします：

node scripts/simulate_realtime.js --rate 5/sec --duration 60s

アクセシビリティを検証します：

node scripts/validate_timeline_accessibility.js

パフォーマンスをベンチマークします：

node scripts/benchmark_timeline.js --events 10000 --virtual

次のステップ

1. タイムラインのユースケース（アクティビティ、イベント、スケジュール）を特定する
2. 適切なコンポーネントタイプを選択する
3. ライブラリを選ぶか、トークンを使ってカスタムで構築する
4. 該当するサンプルファイルから始める
5. コア機能を実装する
6. 必要に応じてリアルタイム更新を追加する
7. 大規模なデータセットでパフォーマンスをテストする
8. アクセシビリティへの準拠を検証する
9. モバイル向けのレスポンシブ戦略を適用する