implementing-drag-drop

ドラッグ＆ドロップと並べ替え可能なインターフェース

目的

このスキルは、最新の React／TypeScript ライブラリを使用して、ドラッグ＆ドロップ操作や並べ替え可能なインターフェースを実装するためのものです。直感的な直接操作型 UI を作成するための、アクセシビリティを優先したアプローチ、タッチ操作への対応、パフォーマンスの最適化について説明します。

使用する場面

次のような場合に、このスキルを利用します。

• Trello 形式のカンバンボードを作成し、列間でカードをドラッグできるようにする
• 優先順位を並べ替えるためのドラッグハンドル付きリストを作成する
• 視覚的なドラッグ＆ドロップのフィードバックがあるファイルアップロード領域を実装する
• ダッシュボードのウィジェットやギャラリー用に、順序を変更できるグリッドを作成する
• ノードベースのインターフェースを備えたビジュアルビルダーを作成する
• 直接操作による空間的な再配置が必要な UI を実装する

主なパターン

並べ替え可能なリスト

次の項目については、references/dnd-patterns.md を参照してください。

• ドラッグハンドル付きの垂直リスト
• タブ／カルーセルを並べ替えるための水平リスト
• 2D ドラッグに対応するグリッドレイアウト
• 端に近づいたときの自動スクロール

カンバンボード

次の項目については、references/kanban-implementation.md を参照してください。

• カードを含む複数列のボード
• WIP 制限とスイムレーン
• ホバー時のカードプレビュー
• 列の管理（追加／削除／折りたたみ）

ファイルアップロード領域

次の項目については、references/file-dropzone.md を参照してください。

• 視覚的なフィードバックの状態
• ファイル形式の検証
• 複数ファイルの処理
• 進行状況インジケーター

アクセシビリティ

次の項目については、references/accessibility-dnd.md を参照してください。

• キーボードナビゲーションのパターン
• スクリーンリーダー向けの通知
• 代替となる UI のアプローチ
• ARIA 属性

ライブラリの選択

第一候補：dnd-kit

React 向けの最新でアクセシブルかつ高性能なドラッグ＆ドロップライブラリです。

次の項目については、references/library-guide.md を参照してください。

• ライブラリの比較（dnd-kit と代替ライブラリ）
• インストールとセットアップ
• 基本概念と API
• react-beautiful-dnd からの移行

主な機能

• アクセシビリティを標準でサポート
• タッチ、マウス、キーボード入力に対応
• 依存関係なし（コアは約 10KB）
• 高いカスタマイズ性
• TypeScript にネイティブ対応

実装ワークフロー

手順 1：要件を分析する

必要なドラッグ＆ドロップのパターンを特定します。

• シンプルなリストの並べ替え → 並べ替え可能なリストのパターン
• 複数コンテナー間の移動 → カンバンのパターン
• ファイルの処理 → ドロップゾーンのパターン
• 複雑な操作 → ビジュアルビルダーのパターン

手順 2：ライブラリをセットアップする

必要なパッケージをインストールします。

npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

手順 3：基本機能を実装する

次のサンプルを出発点として使用します。

• 基本的なリストには examples/sortable-list.tsx
• 複数列のボードには examples/kanban-board.tsx
• ファイルアップロードには examples/file-dropzone.tsx
• グリッドレイアウトには examples/grid-reorder.tsx

手順 4：アクセシビリティを追加する

次の項目については、references/accessibility-dnd.md を参照してください。

• キーボードナビゲーションを実装する
• スクリーンリーダー向けの通知を追加する
• 代替コントロールを用意する
• 支援技術を使ってテストする

scripts/validate_accessibility.js を実行して、実装を確認します。

手順 5：パフォーマンスを最適化する

100 件を超える項目を含むリストの場合：

• references/performance-optimization.md を参照する
• 仮想スクロールを実装する
• 効率的な計算には scripts/calculate_drop_position.js を使用する

手順 6：デザイントークンでスタイルを設定する

design-tokens スキルを使用してテーマを適用します。

• デザイントークンの変数を参照する
• ドラッグ状態（ホバー中、ドラッグ中、ドロップ中）を実装する
• 視覚的なフィードバックとアニメーションを追加する

モバイルとタッチ操作への対応

次の項目については、references/touch-support.md を参照してください。

• 長押しでドラッグを開始する
• ドラッグ中のスクロールを防止する
• タッチしやすいヒット領域（最小 44px）
• ジェスチャーの競合を解決する

状態管理

次の項目については、references/state-management.md を参照してください。

• React でドラッグ状態を管理する
• 楽観的な更新
• 元に戻す／やり直す機能
• 順序の変更を永続化する

スクリプト

ドロップ位置の計算

scripts/calculate_drop_position.js を実行して、次の処理を行います。

• 有効なドロップゾーンを特定する
• 挿入インデックスを計算する
• エッジケースを処理する

設定の生成

scripts/generate_dnd_config.js を実行して、次の処理を行います。

• dnd-kit の設定を作成する
• センサーとモディファイアーをセットアップする
• アニメーションを設定する

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

scripts/validate_accessibility.js を実行して、以下を行います。

• キーボード操作を確認する
• ARIA 属性を検証する
• スクリーンリーダーとの互換性をテストする

例

各例には、アクセシビリティに配慮した TypeScript のコード一式が含まれています。

並べ替え可能なリスト

examples/sortable-list.tsx

• ドラッグハンドル付きの縦並びリスト
• キーボード操作（Space/Enter でつかみ、矢印キーで移動）
• スクリーンリーダーによるアナウンス

カンバンボード

examples/kanban-board.tsx

• ドラッグ可能なカードがある複数の列
• 列間でのカード移動
• 列の管理機能
• WIP 制限

ファイルドロップゾーン

examples/file-dropzone.tsx

• ファイルをドラッグしてアップロード
• 視覚的なフィードバック状態
• ファイル形式の検証
• アップロードの進行状況

グリッドの並べ替え

examples/grid-reorder.tsx

• 2D グリッドのドラッグ操作
• ドロップ時の自動レイアウト
• レスポンシブなブレークポイント

アセット

TypeScript 型

assets/drag-state-types.ts には以下が含まれています。

• ドラッグ状態の型定義
• イベントハンドラーの型
• 設定インターフェース

設定スキーマ

assets/dnd-config-schema.json では以下を定義します。

• 有効な設定オプション
• センサー設定
• アニメーションパラメーター

ベストプラクティス

視覚的なフィードバック

• ドラッグ可能であることを示すドラッグハンドル（⋮⋮）を表示する
• カーソルを変更する（grab → grabbing）
• ドロップゾーンのプレースホルダーを表示する
• ドラッグ中の項目を半透明にする
• ドロップ可能なターゲットを強調表示する

パフォーマンス

• position プロパティではなく、CSS transforms を使用する
• アニメーションに will-change: transform を適用する
• 大きなリストではドラッグイベントをスロットルする
• 必要に応じて仮想スクロールを実装する

アクセシビリティを最優先する

• 必ずキーボード操作の代替手段を用意する
• スクリーンリーダーによるアナウンスを含める
• NVDA/JAWS/VoiceOver でテストする
• ドラッグ以外の方法（ボタン／フォーム）を用意する

エラー処理

• ドロップが無効な場合のフィードバックを表示する
• 元に戻す機能を実装する
• ドロップ成功後に自動保存する
• ネットワーク障害を適切に処理する

よくある落とし穴

次の問題を避ける

• キーボード操作を忘れる
• タッチ操作に対応しない
• ドラッグ中のスクロールを防止しない
• アクセシビリティを無視する
• 大きなリストでパフォーマンスが低下する

解決策

各問題に応じたガイドを参照してください。

• アクセシビリティ → references/accessibility-dnd.md
• タッチ操作 → references/touch-support.md
• パフォーマンス → references/performance-optimization.md
• 状態 → references/state-management.md

テストチェックリスト

デプロイ前に、以下を確認してください。

• キーボード操作がすべて正常に機能する
• スクリーンリーダーがすべての操作をアナウンスする
• タッチデバイスでスムーズにドラッグできる
• 想定されるデータ量でパフォーマンスに問題がない
• 視覚的なフィードバックが明確で、適切に応答する
• 元に戻す／やり直す機能が動作する
• アクセシビリティのための代替 UI が用意されている
• 対象となるすべてのブラウザーで動作する

次のステップ

基本的なドラッグ＆ドロップを実装した後は、以下を行います。

1. 高度な機能（自動スクロール、複数選択）を追加する
2. モバイル向けのジェスチャー操作に対応する
3. Framer Motion でアニメーションを洗練させる
4. カスタムのドラッグプレビューコンポーネントを作成する
5. 複雑なインタラクション（入れ子のドラッグ操作）を構築する