DragHandle

Read as Markdown

import {
  DragHandle,
  ManipulationFrame,
  Rectangle,
  useManipulation,
  useSignal,
} from "@pibbl/core";

DragHandle starts a move interaction for its controller. Its children provide the hit areas through normal Pibbl event targeting. It adds no target of its own: empty space, gaps between children, and descendants with pointerEvents="none" do not start dragging. Shapes retain their transforms, clips, fill and stroke hit rules. Place it inside the ManipulationFrame attached to the same controller.

const box = useSignal({ left: 40, top: 32, width: 180, height: 100 });
const manipulation = useManipulation({ box, move: {} });

<ManipulationFrame {...manipulation.frameProps}>
  <DragHandle controller={manipulation} style={{ readout: true }}>
    <Rectangle
      keyboardFocusable
      style={{ width: 180, height: 100, fill: "#2563eb", cursor: "grab" }}
    />
  </DragHandle>
</ManipulationFrame>;

Position readouts display the frame’s applied left and top, default to active-only, and accept the same style.readout states, gap, and canvas containment as resize readouts. formatReadout={({ left, top }) => ...} can display custom document units. Put keyboardFocusable and cursor styling on the actual child target. Child event cancellation can reject a drag before it reaches the handle.

The position readout sits outside the top edge with a default gap of 40 CSS pixels, leaving room for the standard rotation handle and guide arc. Set style={{ readout: { gap: 48 } }} to adjust that distance. The gap follows the rotated edge; canvas containment takes priority near the canvas boundary. Readouts do not currently support independent horizontal/vertical offsets.

API details from source

Draws an interactive handle that starts translation of its manipulation target.

DragHandle: PibblPrimitiveComponent<PibblDragHandleProps, PrimitiveInput<PibblDragHandleProps, PibblDragHandleStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

Implementation guidance for agents

Read the Input, focus, and native HTML companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Own a manipulation controller: Compose a drag surface and one resize handle, inspect gesture state, and cancel explicitly. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.