Drag handle

UsageCopy Anchor Link

import { DragHandle } from '@commenda/pathfinder/drag-handle';

<DragHandle
  ref={setActivatorNodeRef}
  {...attributes}
  {...listeners}
  label={`Reorder ${item.label}`}
  dragging={isDragging}
  disabled={item.pinned}
  disabledReason="Pinned items cannot move"
/>;

InstallationCopy Anchor Link

pnpm --filter your-app add "@commenda/pathfinder@workspace:*"

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

API referenceCopy Anchor Link

The handle is an activator; it does not reorder data by itself. The playground uses dnd-kit as a documentation-only dependency, not a runtime dependency of the exported component. Application code owns stable IDs, ordering, sensors, movement, drop feedback, announcements and cancellation. Copy the integration pattern from the playground when connecting your sortable owner.

DRAG-ALTERNATIVES-01: Space/Enter picks up and drops, arrows move, Escape restores original order. Announce pickup, positions, drop and cancellation. Provide Move up, Move down and Move to top alternatives. Touch uses 250ms long press with a movement tolerance; ordinary page scroll remains possible before activation.

DRAG-GEOMETRY-01: Keep the handle inside the row at its leading edge. Reserve its space while hidden; reveal on hover and focus-within. On touch always show it with a 44px target. Desktop is a 16px glyph in a 16×24 area. Rest/hover/pressed use soft-pearl 700/800/900; disabled uses 400. Pinned items require an explanation. Do not apply handles to tabs or palette cards that drag by the whole item. Never use deprecated aria-grabbed.

ResizeHandle is separate future work despite sharing the Figma sheet; DragHandle has no resize mode. Do not claim the activator alone implements these integration behaviors.

Import @commenda/pathfinder/styles.css once at the app root. Event handlers require a client component in Next.js App Router.

Design rulesCopy Anchor Link

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

ReorderingCopy Anchor Link

• DRAG-ALTERNATIVES-01 — Figma integration requirement: focus handle, Space/Enter pickup/drop, arrows move immediately, Escape cancels. Announce each move with position and count. Supply Move up/down/to top alternatives. A 250ms long press starts touch dragging; scrolling stops during active dragging. Handle alone cannot implement ordering; application/sortable owner supplies behavior.

• DRAG-GEOMETRY-01 — Figma: leading inside the row, never hanging outside. Reserve space while hidden; reveal on hover/focus, always on touch. Desktop 16px glyph in 16×24 area; touch target 44px. Soft-pearl 700 rest, 800 hover, 900 pressed, 400 disabled. Input-style focus ring. Pinned items have a reason. Whole-item draggable tabs/palette cards do not get a handle.

• DRAG-FUTURE-01 — ResizeHandle is separate future work. Source specifies arrows 16, Shift 64, Home/End limits, Enter or double-click reset. Do not add resize semantics to DragHandle.