Skip to content

Latest commit

 

History

History
101 lines (72 loc) · 3.85 KB

CLAUDE.md

File metadata and controls

101 lines (72 loc) · 3.85 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

This project uses Yarn, not npm. Always use yarn for package management.

This project uses Make for builds. Key commands:

  • make build - Full build (cleans, then builds CJS and web bundles)
  • make lint - Runs Flow type checker, ESLint, and TypeScript type checking on typings
  • make test - Runs unit tests via Vitest
  • make test-browser - Runs browser tests via Puppeteer (requires build first)
  • make test-all - Runs both unit and browser tests
  • make dev - Starts webpack dev server with example page at localhost:8080

Yarn scripts:

  • yarn test - Run unit tests (jsdom environment)
  • yarn test:watch - Run unit tests in watch mode
  • yarn test -- path/to/test.jsx - Run a single test file
  • yarn test -- -t "test name" - Run tests matching a pattern
  • yarn test:browser - Build and run browser tests (Puppeteer)
  • yarn test:all - Run all tests
  • yarn test:coverage - Run tests with coverage report

Pre-commit hooks run make lint and make test automatically.

Test Architecture

Tests are split into two categories:

  1. Unit tests (test/*.test.{js,jsx}) - Run in jsdom via Vitest

    • Fast, no browser required
    • Test component logic, callbacks, prop handling
    • Some coordinate-based tests skipped (require real browser)

  2. Browser tests (test/browser/*.test.js) - Run in headless Chrome via Puppeteer

    • Test actual drag behavior with real coordinate calculations
    • Test transforms, axis constraints, bounds, scale

Test Utilities

test/testUtils.js provides helpers for simulating drag events:

  • simulateDrag(element, {from, to}) - Complete drag operation
  • startDrag(element, {x, y}) / moveDrag({x, y}) / endDrag(element, {x, y}) - Step-by-step drag
  • simulateTouchDrag(element, {from, to}) - Touch event drag

Architecture

Component Hierarchy

DraggableCore (lib/DraggableCore.js) - Low-level component that handles raw drag events

  • Maintains minimal internal state (just dragging, lastX, lastY)
  • Manages mouse/touch event binding and cleanup
  • Provides onStart, onDrag, onStop callbacks with position data
  • Use this when you need full control over positioning

Draggable (lib/Draggable.js) - High-level wrapper around DraggableCore

  • Manages position state, bounds checking, axis constraints
  • Applies CSS transforms or SVG transform attributes
  • Supports controlled (position prop) and uncontrolled (defaultPosition) modes
  • Adds dragging-related CSS classes

Key Utilities

  • lib/utils/domFns.js - DOM helpers: event binding, CSS transforms, user-select hacks
  • lib/utils/positionFns.js - Position calculations: bounds checking, grid snapping, delta computations
  • lib/utils/getPrefix.js - Browser prefix detection for CSS transforms

Build Outputs

  • build/cjs/ - CommonJS build (Babel)
  • build/web/react-draggable.min.js - UMD browser bundle (Webpack)

Type Systems

The codebase uses Flow for internal type checking (// @flow annotations) and ships TypeScript definitions in typings/index.d.ts. Both must stay in sync when modifying component props or types.

Key Patterns

nodeRef Pattern

To avoid ReactDOM.findDOMNode deprecation warnings in Strict Mode, components accept a nodeRef prop:

const nodeRef = React.useRef(null);
<Draggable nodeRef={nodeRef}>
  <div ref={nodeRef}>Content</div>
</Draggable>

Callback Return Values

Returning false from onStart, onDrag, or onStop cancels the drag operation.

CSS Transform Approach

Dragging uses CSS transforms (translate) rather than absolute positioning, allowing draggable elements to work regardless of their CSS position value.

Release Process

  • Update CHANGELOG.md
  • make release-patch, make release-minor, or make release-major
  • make publish