AgentSkillsCN

implementing-drag-drop

利用React/TypeScript实现拖拽与可排序界面，包括看板、可排序列表、文件上传，以及可重新排序的网格。适用于构建需要直接操作、空间组织，或支持触控友好重新排序的交互式UI时使用。

SKILL.md
--- frontmatter
name: implementing-drag-drop
description: Implements drag-and-drop and sortable interfaces with React/TypeScript including kanban boards, sortable lists, file uploads, and reorderable grids. Use when building interactive UIs requiring direct manipulation, spatial organization, or touch-friendly reordering.

Drag-and-Drop & Sortable Interfaces

Purpose

This skill helps implement drag-and-drop interactions and sortable interfaces using modern React/TypeScript libraries. It covers accessibility-first approaches, touch support, and performance optimization for creating intuitive direct manipulation UIs.

When to Use

Invoke this skill when:

  • •Building Trello-style kanban boards with draggable cards between columns
  • •Creating sortable lists with drag handles for priority ordering
  • •Implementing file upload zones with visual drag-and-drop feedback
  • •Building reorderable grids for dashboard widgets or galleries
  • •Creating visual builders with node-based interfaces
  • •Implementing any UI requiring spatial reorganization through direct manipulation

Core Patterns

Sortable Lists

Reference references/dnd-patterns.md for:

  • •Vertical lists with drag handles
  • •Horizontal lists for tab/carousel reordering
  • •Grid layouts with 2D dragging
  • •Auto-scrolling near edges

Kanban Boards

Reference references/kanban-implementation.md for:

  • •Multi-column boards with cards
  • •WIP limits and swimlanes
  • •Card preview on hover
  • •Column management (add/remove/collapse)

File Upload Zones

Reference references/file-dropzone.md for:

  • •Visual feedback states
  • •File type validation
  • •Multi-file handling
  • •Progress indicators

Accessibility

Reference references/accessibility-dnd.md for:

  • •Keyboard navigation patterns
  • •Screen reader announcements
  • •Alternative UI approaches
  • •ARIA attributes

Library Selection

Primary: dnd-kit

Modern, accessible, and performant drag-and-drop for React.

Reference references/library-guide.md for:

  • •Library comparison (dnd-kit vs alternatives)
  • •Installation and setup
  • •Core concepts and API
  • •Migration from react-beautiful-dnd

Key Features

  • •Built-in accessibility support
  • •Touch, mouse, and keyboard input
  • •Zero dependencies (~10KB core)
  • •Highly customizable
  • •TypeScript native

Implementation Workflow

Step 1: Analyze Requirements

Determine the drag-and-drop pattern needed:

  • •Simple list reordering → Sortable list pattern
  • •Multi-container movement → Kanban pattern
  • •File handling → Dropzone pattern
  • •Complex interactions → Visual builder pattern

Step 2: Set Up Library

Install required packages:

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

Step 3: Implement Core Functionality

Use examples as starting points:

  • •examples/sortable-list.tsx for basic lists
  • •examples/kanban-board.tsx for multi-column boards
  • •examples/file-dropzone.tsx for file uploads
  • •examples/grid-reorder.tsx for grid layouts

Step 4: Add Accessibility

Reference references/accessibility-dnd.md to:

  • •Implement keyboard navigation
  • •Add screen reader announcements
  • •Provide alternative controls
  • •Test with assistive technologies

Run scripts/validate_accessibility.js to check implementation.

Step 5: Optimize Performance

For lists with >100 items:

  • •Reference references/performance-optimization.md
  • •Implement virtual scrolling
  • •Use scripts/calculate_drop_position.js for efficient calculations

Step 6: Style with Design Tokens

Apply theming using the design-tokens skill:

  • •Reference design token variables
  • •Implement drag states (hovering, dragging, dropping)
  • •Add visual feedback and animations

Mobile & Touch Support

Reference references/touch-support.md for:

  • •Long press to initiate drag
  • •Preventing scroll during drag
  • •Touch-friendly hit areas (44px minimum)
  • •Gesture conflict resolution

State Management

Reference references/state-management.md for:

  • •Managing drag state in React
  • •Optimistic updates
  • •Undo/redo functionality
  • •Persisting order changes

Scripts

Calculate Drop Position

Run scripts/calculate_drop_position.js to:

  • •Determine valid drop zones
  • •Calculate insertion indices
  • •Handle edge cases

Generate Configuration

Run scripts/generate_dnd_config.js to:

  • •Create dnd-kit configuration
  • •Set up sensors and modifiers
  • •Configure animations

Validate Accessibility

Run scripts/validate_accessibility.js to:

  • •Check keyboard navigation
  • •Verify ARIA attributes
  • •Test screen reader compatibility

Examples

Each example includes complete TypeScript code with accessibility:

Sortable List

examples/sortable-list.tsx

  • •Vertical list with drag handles
  • •Keyboard navigation (Space/Enter to grab, arrows to move)
  • •Screen reader announcements

Kanban Board

examples/kanban-board.tsx

  • •Multiple columns with draggable cards
  • •Card movement between columns
  • •Column management features
  • •WIP limits

File Dropzone

examples/file-dropzone.tsx

  • •Drag files to upload
  • •Visual feedback states
  • •File type validation
  • •Upload progress

Grid Reorder

examples/grid-reorder.tsx

  • •2D grid dragging
  • •Auto-layout on drop
  • •Responsive breakpoints

Assets

TypeScript Types

assets/drag-state-types.ts provides:

  • •Type definitions for drag state
  • •Event handler types
  • •Configuration interfaces

Configuration Schema

assets/dnd-config-schema.json defines:

  • •Valid configuration options
  • •Sensor settings
  • •Animation parameters

Best Practices

Visual Feedback

  • •Show drag handles (⋮⋮) to indicate draggability
  • •Change cursor (grab → grabbing)
  • •Display drop zone placeholders
  • •Make dragged items semi-transparent
  • •Highlight valid drop targets

Performance

  • •Use CSS transforms, not position properties
  • •Apply will-change: transform for animations
  • •Throttle drag events for large lists
  • •Implement virtual scrolling when needed

Accessibility First

  • •Always provide keyboard alternatives
  • •Include screen reader announcements
  • •Test with NVDA/JAWS/VoiceOver
  • •Provide non-drag alternatives (buttons/forms)

Error Handling

  • •Show invalid drop feedback
  • •Implement undo functionality
  • •Auto-save after successful drops
  • •Handle network failures gracefully

Common Pitfalls

Avoid These Issues

  • •Forgetting keyboard navigation
  • •Missing touch support
  • •Not preventing scroll during drag
  • •Ignoring accessibility
  • •Poor performance with large lists

Solutions

Reference the appropriate guide for each issue:

  • •Accessibility → references/accessibility-dnd.md
  • •Touch → references/touch-support.md
  • •Performance → references/performance-optimization.md
  • •State → references/state-management.md

Testing Checklist

Before deployment, verify:

  • • Keyboard navigation works completely
  • • Screen readers announce all actions
  • • Touch devices can drag smoothly
  • • Performance acceptable with expected data volume
  • • Visual feedback clear and responsive
  • • Undo/redo functionality works
  • • Alternative UI provided for accessibility
  • • Works across all target browsers

Next Steps

After implementing basic drag-and-drop:

  1. •Add advanced features (auto-scroll, multi-select)
  2. •Implement gesture support for mobile
  3. •Add animation polish with Framer Motion
  4. •Create custom drag preview components
  5. •Build complex interactions (nested dragging)