# drag

One pointer and keyboard model for sliders, resize handles, swipe to
dismiss, drawers and sortable cards. A primary-button press on the element
(or on its `handle`) arms the drag; it starts once the pointer has moved
`threshold` px along `axis`, or after `delay` ms held within `tolerance`
px, and the callbacks get the point, the distance from the start and the
velocity.

```ts Signature
function drag(el: HTMLElement, opts: DragOptions): Drag;

type DragAxis = "x" | "y" | "both";
type DragSource = "pointer" | "keyboard";
```

## Options

| Option | Type | Default | What it does |
|---|---|---|---|
| `handle` | `string \| HTMLElement` | the element | Where a press starts the drag: a selector inside the element, or an element. |
| `axis` | `DragAxis` | `"both"` | Which movement counts. |
| `threshold` | `number` | `3` | px moved before the drag starts. `0` starts on press, as a slider does. |
| `delay` | `number` | `0` (off) | ms held before the drag starts, instead of the threshold. |
| `tolerance` | `number` | `5` | With `delay`: px the pointer may move while held. |
| `touch` | `{ threshold?, delay?, tolerance? }` | none | For touch presses only: replaces threshold, delay and tolerance, so a finger holds before it drags and a swipe still scrolls. |
| `canStart` | `(e: PointerEvent \| KeyboardEvent) => boolean` | none | Called with the pointerdown or keydown that would start a drag; `false` ignores it. |
| `keyboard` | `DragKeyboard \| false` | `{ mode: "step" }` | The keyboard model below; `false` turns keys off. |
| `disabled` | `() => boolean` | none | Returns true while dragging must not start. |
| `dir` | `"ltr" \| "rtl"` | the element's computed direction | Reading direction for step mode. |
| `onStart` | `(s: DragState) => void \| boolean` | none | The drag is starting. Return `false` to refuse it. |
| `onMove` | `(s: DragState) => void` | none | The pointer moved, or a grab-mode key moved the item. |
| `onEnd` | `(s: DragState) => void` | none | The pointer was released, or the item dropped. |
| `onCancel` | `(s: DragState) => void` | none | Escape, pointercancel, a lost capture, blur, a tab switch, a resize, or `cancel()`. |
| `onStep` | `(step: DragStep) => void` | none | Step mode: one keyboard step. |
| `label` | `() => string` | `aria-label`, else the text | Grab mode: the item's name in announcements. |
| `announcements` | `DragAnnouncements \| false` | the defaults | Grab mode: `start`, `move`, `end` and `cancel` functions of `(label, state)` returning the message, merged over the defaults ("Picked up <label>.", "<label> moved.", "<label> dropped.", "Dragging cancelled. <label> returned."); `false` turns them off. |
| `instructions` | `string \| false` | the default text | Grab mode: screen reader instructions wired with `aria-describedby`; `false` turns them off. |

`DragKeyboard`:

| Option | Type | Default | What it does |
|---|---|---|---|
| `mode` | `"step" \| "grab"` | `"step"` | Step: keys call `onStep` and no drag starts. Grab: keys pick up, move and drop the item through `onStart`, `onMove` and `onEnd`. |
| `step` | `number` | `25` | Grab mode: px per arrow press. |
| `largeStep` | `number` | `4 * step` | Grab mode: px per Shift+arrow. |
| `keyboardCodes` | `{ start?, cancel?, end? }` | start `["Space", "Enter"]`, cancel `["Escape"]`, end `["Space", "Enter", "Tab"]` | Grab mode: the `KeyboardEvent.code` values that pick up, cancel and drop. |
| `scrollIntoView` | `boolean \| (() => Element \| null)` | `true` | Grab mode: after a move, scroll the lifted element into view, another element (a placeholder in another column), or nothing. |
| `scrollBehavior` | `"instant" \| "smooth"` | `"instant"` | Grab mode: how that scroll moves. Instant is on screen before the next key. |
| `next` | `(key, point, e) => { x, y } \| undefined` | arrow math by `step` | Grab mode: computes the next point for an arrow key (move to the next column, snap to a slot); `undefined` keeps the point. |

## State

Callbacks get a `DragState`: `source` (pointer or keyboard), `pointerType`
(`"mouse"`, `"pen"`, `"touch"` or `"keyboard"`), `startX`, `startY`, the
current `x` and `y`, `dx` and `dy` from the start, `velocityX` and
`velocityY` in px per ms over the last 100ms, and the `event`. Coordinates
are viewport px. `dx` and `dy` are zero on the axis the drag ignores, and a
pointer held still before the release has no velocity, so a slow release is
never a fling.

`onStep` gets a `DragStep`: `dx` and `dy` as -1, 0 or 1 (Left and Right
follow reading direction), `large` for Shift+arrow, PageUp or PageDown,
`edge` as `"start"` for Home and `"end"` for End, the `key` and the
`event`. The template decides what a step is.

## Pointer

A move across the axis first, past the threshold, gives the gesture back to
the page: a vertical scroll is not a horizontal swipe. Once started, the
element captures the pointer, text selection is suppressed, the element
gets `data-dragging`, and the click that follows a real drag is swallowed
so a dragged card does not also open. A press that never reaches the
threshold is a plain click. Set `touch-action` in CSS on the handle (`none`,
or `pan-y` for a horizontal swipe): pointer events cannot stop touch
scrolling once it starts.

## Keyboard

The element must be focusable. A control inside it (a button, link or
field that is not the handle) keeps its own keys, so Space on a Delete
button in a card presses the button.

| Keys | Step mode | Grab mode |
|---|---|---|
| Arrows | `onStep` with a unit direction | Move by `step` px while lifted |
| Shift+arrows, PageUp, PageDown | `onStep` with `large` | Move by `largeStep` px |
| Home, End | `onStep` with `edge` | |
| Space, Enter | | Pick up; while lifted, drop (`onEnd`) |
| Tab | | Drop while lifted |
| Escape, blur | | Cancel (`onCancel`) |

While lifted the element has `aria-pressed="true"`, scrolls into view after
each move, and the pick up, move, drop and cancel are announced through
[announce](announce).

## The handle

| Member | What it does |
|---|---|
| `dragging()` | True between onStart and onEnd or onCancel. |
| `cancel()` | Cancels a drag in progress, calling onCancel. `release()` does too. |
| `release()` | Stops listening and puts back what the behavior set. |

## In a template of your own

```ehtml app/shared/templates/range/index.ehtml
import { drag, type Drag, type DragState, type DragStep } from "@elements/ui/behaviors";

interface RangeState {
  track?: HTMLElement;
  d?: Drag;
}

function clamp(n: number): number {
  return Math.round(Math.min(100, Math.max(0, n)));
}

function fromPointer(s: DragState, track: HTMLElement): number {
  let r = track.getBoundingClientRect();
  return clamp(((s.x - r.left) / r.width) * 100);
}

function fromStep(value: number, k: DragStep): number {
  if (k.edge) {
    return k.edge === "start" ? 0 : 100;
  }

  return clamp(value + k.dx * (k.large ? 10 : 1));
}

<Range (value: number = 50, private ui: RangeState = {})>
  <div class="range" oninsert={(e) => ui.track = e.target as HTMLElement}>
    <div class="range-thumb" role="slider" tabindex="0"
         aria-valuemin="0" aria-valuemax="100" aria-valuenow={value} style={`left: ${value}%`}
         oninsert={(e) => ui.d = drag(e.target as HTMLElement, {
           axis: "x",
           threshold: 0,
           onMove: (s) => value = fromPointer(s, ui.track!),
           onStep: (k) => value = fromStep(value, k),
         })}
         onremove={() => ui.d?.release()}></div>
  </div>
</Range>
```

```css app/shared/templates/range/style.css
.range { position: relative; height: var(--space-4); }
.range-thumb { position: absolute; top: 0; touch-action: none; }
```

## Writes

`data-dragging` on the element while a drag runs. In grab mode,
`aria-pressed` while lifted and `aria-describedby` pointing at one hidden
instructions node on `<body>` per distinct text.

## Used by

[Carousel](../templates/carousel), [ColorPicker](../templates/color-picker),
[DataTable](../templates/data-table), [Drawer](../templates/drawer),
[Kanban](../templates/kanban), [Resizable](../templates/resizable),
[ScrollArea](../templates/scroll-area), [Slider](../templates/slider),
[Toast](../templates/toast).