@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/lib/design-frame/protocol.d.ts

@@ -0,0 +1,78 @@
+import { type ContrastPreference, type MotionPreference, type Theme, type UiScale } from "../preference-values";
+/**
+ * The messages a `SandboxedFrame` host and the document inside it exchange
+ * (DX-4075). One definition, imported by both sides, so they cannot drift.
+ *
+ * REACT-FREE: this module is reachable from `@50arms/ui/pure` (the framed side
+ * is a harness of any framework), so nothing here may import React.
+ *
+ * NO SECRET TRAVELS THIS CHANNEL. The host posts the four appearance values and
+ * nothing else, which is why it can post to targetOrigin "*": the frame's origin
+ * is the string "null" and cannot be named anyway.
+ */
+export declare const DESIGN_FRAME_APPEARANCE = "danx-design:appearance";
+export declare const DESIGN_FRAME_READY = "danx-design:ready";
+export declare const DESIGN_FRAME_ERROR = "danx-design:error";
+export declare const DESIGN_FRAME_HEIGHT = "danx-design:height";
+/** The most characters of a frame's error message the host will accept. */
+export declare const DESIGN_FRAME_ERROR_MAX_LENGTH = 500;
+/**
+ * The host's Appearance. A field is absent when the host document has not set
+ * that attribute (a host that never mounted the preference hooks); the frame then
+ * leaves its own default alone rather than being told a guess.
+ */
+export interface DesignFrameAppearance {
+    theme?: Theme;
+    contrast?: ContrastPreference;
+    uiScale?: UiScale;
+    motion?: MotionPreference;
+}
+/** Host -> frame, on every change of the host's Appearance. */
+export interface DesignFrameAppearanceMessage extends DesignFrameAppearance {
+    type: typeof DESIGN_FRAME_APPEARANCE;
+}
+/** Frame -> host: the design has mounted and is listening for appearance. */
+export interface DesignFrameReadyMessage {
+    type: typeof DESIGN_FRAME_READY;
+}
+/** Frame -> host: the design failed. The host caps and treats `message` as text. */
+export interface DesignFrameErrorMessage {
+    type: typeof DESIGN_FRAME_ERROR;
+    message: string;
+}
+/**
+ * The most pixels of height or viewport the host will accept from a frame (DXUI-6): a sanity bound on
+ * untrusted input, not the guard against a page that grows with its frame (`SandboxedFrame` decides that
+ * from the reported viewport).
+ */
+export declare const DESIGN_FRAME_HEIGHT_MAX = 100000;
+/**
+ * Frame -> host: the height of the framed document and the height of the frame's own viewport
+ * (`window.innerHeight`) when it was measured, in CSS pixels, and the id of the document that sent it (`doc`, the
+ * id the host injected into that document's script). Used by `fit="content"`.
+ */
+export interface DesignFrameHeightMessage {
+    type: typeof DESIGN_FRAME_HEIGHT;
+    height: number;
+    viewport: number;
+    doc: string;
+}
+export type DesignFrameInboundMessage = DesignFrameReadyMessage | DesignFrameErrorMessage | DesignFrameHeightMessage;
+/**
+ * The four `<html data-*>` attributes that carry Appearance, by field. The names
+ * and value domains are the library's own (`preference-values.ts`).
+ */
+export declare const APPEARANCE_ATTRIBUTES: {
+    readonly theme: "theme";
+    readonly contrast: "contrast";
+    readonly uiScale: "ui-scale";
+    readonly motion: "motion";
+};
+/** Reads the Appearance off an element's `data-*` attributes; an unset or foreign value is left out. */
+export declare function readAppearance(root: Element): DesignFrameAppearance;
+/** The longest document id the host accepts in a height message. */
+export declare const DESIGN_FRAME_DOC_ID_MAX_LENGTH = 64;
+/** Narrows an untrusted `event.data` to an appearance message; a value outside its domain is refused. */
+export declare function parseAppearanceMessage(data: unknown): DesignFrameAppearanceMessage | null;
+/** Narrows an untrusted `event.data` to a ready, error or height message. */
+export declare function parseInboundMessage(data: unknown): DesignFrameInboundMessage | null;

package/dist/types/lib/dev-warn.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Say something once, in development, about a misconfiguration that would
+ * otherwise be silent.
+ *
+ * @param component the component that noticed, so the message is greppable
+ * @param message   what is wrong and what to do about it
+ */
+export declare function devWarn(component: string, message: string): void;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetDevWarnings(): void;

package/dist/types/lib/dnd/announce.d.ts

@@ -0,0 +1,124 @@
+import type { DragSession } from "./session";
+import type { ContainerId, DragId } from "./types";
+/** Everything a message may name. Assembled once per announcement. */
+export interface DragAnnouncementContext {
+    id: DragId;
+    /** `labelOf(id)` if supplied, otherwise the id — which is at least speakable. */
+    label: string;
+    container: ContainerId;
+    /**
+     * DX-4583: the container the card was picked up from. A message whose
+     * `container` differs from it describes a card in another container, which is
+     * the case where a consumer may mean "this lane" and no position at all.
+     */
+    from: ContainerId;
+    containerLabel: string;
+    /** 1-based, as spoken, in the WHOLE container — a windowed container reports its real offset and length (DX-4540). */
+    position: number;
+    /** `position` written the way the active locale writes numbers (DX-4740): what a message prints. */
+    positionText: string;
+    /**
+     * The list length WITH the carried item counted in it, so `position` is never
+     * "4 of 3". The session's own indices exclude the carried item — see the
+     * `DropTarget.index` contract — and reporting that raw count would tell the
+     * user a list is one shorter than the one they are looking at.
+     */
+    total: number;
+    /** `total` written the way the active locale writes numbers (DX-4740): what a message prints. */
+    totalText: string;
+}
+export interface DragAnnouncementOptions {
+    /** Human name for an item. Falls back to the id. */
+    labelOf?: (id: DragId) => string;
+    /** Human name for a container. Falls back to the id. */
+    containerLabelOf?: (id: ContainerId) => string;
+}
+/**
+ * One id for the whole page, deliberately not `useId()`.
+ *
+ * `<DragInstructions>` takes no required props and the hook hands the id to
+ * every handle, so the two can only agree on a CONSTANT — a generated id would
+ * differ per hook instance and every `aria-describedby` would point at nothing,
+ * which reads as "no instructions" and is invisible to every automated check.
+ * The cost: render `<DragInstructions>` once per page, not once per board.
+ */
+export declare const DRAG_INSTRUCTIONS_ID = "danxbot-dnd-instructions";
+export interface DragAnnouncements {
+    /** The current live-region text. `""` until the first pickup. */
+    message: string;
+    /** Put this on every handle's `aria-describedby`. */
+    instructionsId: string;
+}
+/**
+ * Subscribe to the session and turn it into speech.
+ *
+ * AN OBSERVER, NOT A STATE SUBSCRIPTION. The messages are derived from
+ * TRANSITIONS, not from state, and the two that matter most are indistinguishable
+ * in state: a drop and a cancel both end at the same idle value, so a subscriber
+ * sees one identical transition for two endings that need opposite messages — a
+ * drop reports where the item LANDED, a cancel where it went BACK to.
+ *
+ * `session.addObserver` exists for exactly this. It was added after the first
+ * version of this file inferred the ending from whichever DOM event was
+ * mid-dispatch, because the session's callbacks were a single slot the board
+ * already owned. That worked, and was ninety lines, and was defeated once by the
+ * microtask checkpoint the HTML spec runs BETWEEN listeners of the same event —
+ * so every cancel announced itself as a drop, in a real browser only. Nothing
+ * that reads the session should have to guess what the session just did.
+ *
+ * The context for a message is captured WHILE THE DRAG IS LIVE, never at the
+ * end. "Position 3 of 7" needs the carried item excluded from its own total, and
+ * by the time the drag has ended the session no longer knows which item that
+ * was — the number would quietly gain one.
+ */
+export declare function useDragAnnouncements(session: DragSession, options?: DragAnnouncementOptions): DragAnnouncements;
+export type DragLiveRegionProps = {
+    session: DragSession;
+} & DragAnnouncementOptions;
+/**
+ * The live region. Render it ONCE, unconditionally, for the whole board.
+ *
+ * UNCONDITIONALLY IS THE LOAD-BEARING WORD. A live region that is inserted and
+ * populated in the same frame — `{dragging && <DragLiveRegion/>}` — frequently
+ * announces nothing at all: the accessibility tree has to observe the region
+ * BEFORE its content changes to know a change happened. It renders empty here
+ * and stays mounted, which is also why the message lives in state rather than
+ * being derived from `session.getState()` during render.
+ *
+ * ASSERTIVE, NOT POLITE. Polite queues behind whatever is currently being
+ * spoken, and a drag generates positions faster than speech consumes them — so
+ * the user hears "position 2 of 7" while the card sits at 6, which is a wrong
+ * answer rather than a late one. Assertive interrupts, so the newest position
+ * always wins. The usual argument against it — that it talks over the user —
+ * does not apply to a gesture that is modal by construction: nothing else is
+ * happening, and the drag's own output is the only thing being interrupted.
+ *
+ * `sr-only` — NOT `display:none`, NOT `visibility:hidden`, NOT `hidden`. All
+ * three remove the element from the accessibility tree entirely, and a live
+ * region outside the accessibility tree is silent while looking exactly right
+ * in the markup.
+ */
+export declare function DragLiveRegion({ session, ...options }: DragLiveRegionProps): import("react").JSX.Element;
+export interface DragInstructionsProps {
+    /**
+     * The element id each handle's `aria-describedby` points at.
+     *
+     * Defaults to the module constant, which is what makes a prop-less
+     * `<DragInstructions>` and `useDragAnnouncements` agree without wiring. A
+     * component layer that generates its own id with `useId()` — so that two
+     * boards on one page do not emit a duplicate id — passes it here. Without
+     * this prop that layer has to re-implement the paragraph to change one
+     * attribute, which is how the instruction text ends up existing twice and
+     * drifting.
+     */
+    id?: string;
+}
+/**
+ * The instruction text every handle points at with `aria-describedby`.
+ *
+ * A keyboard drag is unusable without it: nothing about a focused handle says
+ * that Space starts a mode, and a user who does not know that never reaches any
+ * of the rest of this file. Visually hidden because the same information is
+ * carried for sighted users by the cursor and the moving card.
+ */
+export declare function DragInstructions({ id }?: DragInstructionsProps): import("react").JSX.Element;

package/dist/types/lib/dnd/autoscroll.d.ts

@@ -0,0 +1,88 @@
+import type { DragSession } from "./session";
+import type { Point } from "./types";
+/**
+ * Edge auto-scroll: while a card is being carried, a pointer near the edge of
+ * the nearest scrollable ancestor scrolls it.
+ *
+ * WHY IT IS NOT OPTIONAL. Without it a list is only reorderable within one
+ * screenful. The target you want is off-screen, the gesture is already in
+ * flight, and there is no way to scroll with the hand that is holding the card
+ * — so the drag has to be abandoned, the list scrolled, and the drag restarted
+ * from a position that may itself now be off-screen.
+ *
+ * THREE THINGS THAT MAKE IT WORK RATHER THAN MERELY EXIST:
+ *
+ *   1. SPEED RAMPS with proximity. A single speed is unusable at both ends: fast
+ *      enough to cross a long column overshoots the moment you approach the
+ *      edge, slow enough to be controllable never gets anywhere. The ramp is
+ *      quadratic, so the outer half of the zone crawls and the last few pixels
+ *      are quick.
+ *   2. IT RE-MEASURES. Every rect in the snapshot moves when the container
+ *      scrolls. Without a remeasure the insertion point keeps pointing at where
+ *      the items USED to be, so the marker sits still while the list slides past
+ *      it and the card lands somewhere the user never indicated.
+ *   3. IT RE-RESOLVES THE TARGET. Re-measuring alone updates the boxes but not
+ *      the answer: the pointer has not moved, so nothing recomputes `over`, and
+ *      the marker stays frozen on the old index against fresh rects. Feeding the
+ *      unchanged point back through `moveTo` is what makes the insertion point
+ *      track the content moving beneath a stationary finger.
+ *
+ * The window `scroll` listener in `sensors/pointer.ts` also remeasures, and is
+ * NOT a substitute: scroll events are coalesced and delivered after the frame
+ * has been composited, so the hit-test for the frame we just scrolled would
+ * still read the pre-scroll snapshot. This loop does it inline, before the next
+ * frame is resolved.
+ */
+export interface AutoScrollOptions {
+    /** Distance from an edge, in px, at which scrolling begins. */
+    threshold?: number;
+    /** Speed in px/second at the very edge, at full motion. */
+    maxSpeed?: number;
+    /** Speed in px/second at the very edge under reduced motion. See D-18. */
+    reducedMaxSpeed?: number;
+}
+/**
+ * Speed at a given distance from the edge. Exported because it is the whole
+ * behaviour and it is the one part testable without a browser.
+ *
+ * Zero outside the zone, `maxSpeed` at the edge, quadratic in between.
+ */
+export declare function scrollVelocity(distanceFromEdge: number, threshold: number, maxSpeed: number): number;
+/**
+ * Start auto-scrolling for the lifetime of every drag on this session.
+ * Returns the teardown.
+ *
+ * Framework-free on purpose, like the rest of the core — a React consumer wraps
+ * it in one `useEffect`, and the tests do not need a renderer to drive it.
+ */
+/**
+ * What the loop needs from whoever is dragging.
+ *
+ * EXTRACTED SO THE CALENDAR CAN USE IT UNCHANGED. Every hard-won detail below —
+ * the carried sub-pixel remainder, the clamped frame delta, the per-scroller
+ * reset, the reduced-motion cap — is about SCROLLING, not about lists, and a
+ * second copy of it in the calendar would be a second copy of the one thing
+ * whose failures are invisible (a ramp that silently loses its outer half is
+ * not something anyone notices; it just feels bad).
+ */
+export interface AutoScrollDriver {
+    /** The pointer, or null when the gesture has no pointer (a keyboard drag). */
+    getPoint: () => Point | null;
+    /**
+     * The content moved under a pointer that did not.
+     *
+     * RE-FEEDING THE POINT IS THE WHOLE REASON THIS CALLBACK EXISTS. Remeasuring
+     * alone updates the boxes and not the ANSWER: the pointer has not moved, so
+     * nothing recomputes what it is over, and the drag freezes mid-scroll.
+     * FullCalendar solves the same problem by re-emitting a synthetic
+     * `pointermove` on scroll — the same fix arrived at from the other side.
+     */
+    onScrolled: (point: Point) => void;
+}
+/** The loop, driven by anything that can answer those two questions. */
+export declare function attachEdgeAutoScroll(driver: AutoScrollDriver, options?: AutoScrollOptions): () => void;
+/**
+ * The list engine's adapter: drive the edge loop from a `DragSession`, and add
+ * the keyboard-only behaviour the pointer ramp cannot reach.
+ */
+export declare function attachAutoScroll(session: DragSession, options?: AutoScrollOptions): () => void;

package/dist/types/lib/dnd/cross-drop.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DX-4583: the one place that says what "a card dropped on another lane" means,
+ * so the drop, the highlight, the banner, the gap and the keyboard cannot drift
+ * into four spellings of the same predicate.
+ */
+import type { ContainerId, CrossDrop, DragState } from "./types";
+/**
+ * True when a card carried from `from` into `to` lands there as a whole: the
+ * destination takes a lane drop and it is not the card's own container. A card
+ * carried inside its own container is always positional.
+ */
+export declare function isLaneDrop(crossDrop: CrossDrop | undefined, from: ContainerId | null | undefined, to: ContainerId | null | undefined): boolean;
+/**
+ * Whose card is held over `container` right now: `"own"` when it was picked up
+ * from there, `"other"` when it came from another container, `null` when no card
+ * is held over it.
+ */
+export declare function heldOver(state: DragState, container: ContainerId): "own" | "other" | null;

package/dist/types/lib/dnd/geometry.d.ts

@@ -0,0 +1,126 @@
+import type { ContainerRect, ContainerRegistration, DragId, DropTarget, GroupRegistration, ItemRect, ItemRegistration, LayoutSnapshot, Point } from "./types";
+/**
+ * Measuring and hit-testing. Pure functions over a snapshot — no DOM reads
+ * except in `measure`, and no state at all, so every rule here is testable
+ * against hand-written rectangles rather than a browser.
+ */
+/**
+ * Take every box at once.
+ *
+ * Items are emitted in container-then-index order so `resolveTarget` can walk
+ * them without re-sorting on every move. Registration order is whatever React
+ * mounted in, which is not the reading order once a list re-renders.
+ */
+export declare function measure(items: Iterable<ItemRegistration>, containers: Iterable<ContainerRegistration>, groups?: Iterable<GroupRegistration>): LayoutSnapshot;
+/**
+ * The container under the pointer.
+ *
+ * SMALLEST AREA WINS, because containers nest: a board is a horizontal
+ * container of columns, and each column is a vertical container of cards. The
+ * pointer is inside both at all times, and the answer that is useful is always
+ * the innermost one.
+ */
+export declare function containerAt(snapshot: LayoutSnapshot, point: Point): ContainerRect | null;
+/**
+ * The container CLOSEST to the pointer, for a pointer that is inside none of
+ * them.
+ *
+ * THE DEAD ZONE IS THE BUG THIS EXISTS FOR, AND IT IS MOST OF A BOARD. The
+ * registered container is the SCROLLER — it has to be, so auto-scroll can find
+ * its edges — and on a kanban lane the scroller is only the card list. The lane
+ * header above it, the lane's own border, the gutter between two lanes and the
+ * board's bottom padding are all outside every registered rect, so a pointer
+ * there is "over no container" while being unmistakably over a lane to the
+ * person holding the card.
+ *
+ * What used to happen there was `resolveTarget` returning null and the session
+ * keeping the PREVIOUS target — so a card dragged from lane 1 and released on
+ * lane 3's header landed in lane 2, the lane the pointer had last crossed on
+ * its way. Measured in the demo before this change: released at (1022, 419),
+ * visually the middle of "Review" whose lane box is 878–1166 × 407–939, the
+ * card landed in "Building". Not an edge case — the header is 60px of every
+ * lane's top, and a person aiming at an empty lane aims at its label.
+ *
+ * SCOPED, so "nearest" cannot mean "somewhere else entirely": the snapshot
+ * holds one `DragDrop` root's own containers and nothing else — every root
+ * builds its own `DragSession` (`use-drag.ts`) with its own registry. The
+ * nearest container to a point over the sidebar is still a lane of the board
+ * being dragged, which is the only answer a release can sensibly have.
+ *
+ * TIES GO TO THE SMALLER BOX, matching `containerAt` — a point in the gutter
+ * between two lanes is equidistant from both, and a nested container is the
+ * more specific answer for the same reason it is there.
+ */
+export declare function nearestContainer(snapshot: LayoutSnapshot, point: Point): ContainerRect | null;
+/** A container's items in reading order, excluding the one being carried. */
+export declare function remainingItems(snapshot: LayoutSnapshot, container: string, dragged: DragId | null): ItemRect[];
+/**
+ * Insertion index for a point within one container.
+ *
+ * THE MIDPOINT RULE: insert before the first remaining item whose centre lies
+ * beyond the pointer on the container's axis; after all of them otherwise. This
+ * is the rule the dashboard's implementation already uses and it is the right
+ * one for lists — the insertion point tracks the cursor rather than the item's
+ * leading edge, so a card released halfway over a neighbour lands on the side
+ * the user is actually pointing at.
+ *
+ * The returned index counts the list WITHOUT the dragged item, which is what
+ * makes same-container and cross-container drops identical arithmetic. See the
+ * header of `types.ts`.
+ */
+export declare function indexAt(snapshot: LayoutSnapshot, container: ContainerRect, point: Point, dragged: DragId | null): number;
+/**
+ * Where the dragged item would land if released at `point`.
+ *
+ * THE POINTER IS OVER THE CONTAINER IT IS NEAREST TO, not only the one whose
+ * rectangle happens to hold it. Both halves of that matter and the second one
+ * is the fix:
+ *
+ * The goal has always been that dragging a card briefly outside the board must
+ * not make the insertion marker vanish, and that a release outside every
+ * container still lands somewhere rather than reading as a silently failed
+ * drag. That was served by returning null here and having the session keep the
+ * PREVIOUS target — which achieves "the marker does not blink out" and gets
+ * "lands where you are pointing" exactly backwards. The gap between two lanes,
+ * a lane's header, a lane's border and the board's own bottom padding are all
+ * outside every registered rect; a release in any of them landed the card in
+ * the last lane the pointer had crossed, which for a drag from lane 1 to lane 3
+ * is lane 2. See `nearestContainer` for the measurement.
+ *
+ * Nearest keeps the marker alive for the same reason last-target did, and puts
+ * it where the person is aiming rather than where they have been.
+ *
+ * STILL NULL FOR A BOARD WITH NO CONTAINERS AT ALL — there is no nearest one,
+ * and the session's `?? s.over` remains the guard for that.
+ *
+ * The index then falls out of `indexAt` without a special case: a point above a
+ * lane is before every card in it, a point below is after all of them.
+ */
+export declare function resolveTarget(snapshot: LayoutSnapshot, point: Point, dragged: DragId | null): DropTarget | null;
+/** Value equality — targets are recreated on every move, so `===` is useless. */
+export declare function sameTarget(a: DropTarget | null, b: DropTarget | null): boolean;
+/**
+ * Would releasing at `to` leave the item exactly where it started?
+ *
+ * Worth stating rather than inlining, because the two indices are counted
+ * against DIFFERENT lists: `from.index` is the item's position with itself
+ * present, `to.index` an insertion point with itself removed. They coincide at
+ * exactly one value. For `[A, B, C, D]` carrying `C` (`from.index` 2), the
+ * remaining list is `[A, B, D]` and inserting at 2 rebuilds `[A, B, C, D]` —
+ * so equality of the two numbers IS the no-op, and every other pair moves
+ * something.
+ *
+ * A consumer that skips this writes on every release, including the ones that
+ * change nothing. That is not free: the dashboard's board reordered by writing
+ * a priority decimal, so a no-op release still cost a request, a re-render and
+ * a row in the audit log.
+ */
+export declare function isNoOp(from: DropTarget, to: DropTarget): boolean;
+/**
+ * Convert a `DropTarget` into the array operation a consumer performs.
+ *
+ * Exported because every consumer needs it and each one getting it subtly wrong
+ * is the entire off-by-one bug class this module exists to remove. Returns a
+ * NEW array; the input is untouched.
+ */
+export declare function applyMove<T>(list: readonly T[], fromIndex: number, toIndex: number): T[];

package/dist/types/lib/dnd/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Drag-and-drop engine. Framework-agnostic core plus a React binding.
+ *
+ * Exported as VALUES from one place — never `import "./x"` for a side effect.
+ * `sideEffects: ["*.css"]` tells every bundler such an import is safe to
+ * delete, and esbuild does; that is exactly how this project once shipped an
+ * empty icon registry (CAV-11).
+ */
+export type { ContainerId, ContainerRect, ContainerRegistration, CrossDrop, DragAxis, DragCancelEvent, DragEndEvent, DragId, DragMode, DragPhase, DragSessionCallbacks, DragStartEvent, DragState, DropTarget, GroupId, GroupRect, GroupRegistration, ItemRect, ItemRegistration, LayoutSnapshot, PieceId, Point, } from "./types";
+export { applyMove, containerAt, indexAt, isNoOp, measure, nearestContainer, remainingItems, resolveTarget, sameTarget, } from "./geometry";
+export { heldOver, isLaneDrop } from "./cross-drop";
+export { DragSession, type StartArgs } from "./session";
+export { attachPointerSensor, attachSessionWindowListeners, type PointerActivation, type PointerSensorOptions, } from "./sensors/pointer";
+export { attachKeyboardSensor, type KeyboardSensorOptions, } from "./sensors/keyboard";
+export { attachAutoScroll, scrollVelocity, type AutoScrollOptions, } from "./autoscroll";
+export { DragSessionProvider, useCreateDragSession, useDragSession, useDragState, useDragLive, useDraggable, useDropContainer, useGroupBox, type UseDraggableOptions, type UseDraggableResult, type UseDropContainerOptions, type UseDropContainerResult, } from "./use-drag";
+export { DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, useDragAnnouncements, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, } from "./announce";

package/dist/types/lib/dnd/sensors/gesture.d.ts

@@ -0,0 +1,37 @@
+import type { Point } from "../types";
+export interface PointerActivation {
+    /** Mouse and pen: travel in px before the drag starts. */
+    distance?: number;
+    /** Touch: press duration in ms before the drag starts. */
+    delay?: number;
+    /** Touch: travel in px that abandons the press as a scroll instead. */
+    tolerance?: number;
+}
+export declare const ACTIVATION_DEFAULTS: Required<PointerActivation>;
+export interface GestureHandlers {
+    /**
+     * The pointer went down. Return false to refuse the gesture outright — a
+     * disabled row, a click on a button inside the card.
+     */
+    onPress?: (point: Point, event: PointerEvent) => boolean | void;
+    /** The activation constraint was satisfied. The drag is now live. */
+    onActivate: (point: Point) => void;
+    /** Only ever called between `onActivate` and one of the two enders. */
+    onMove: (point: Point) => void;
+    /** Released. `activated` distinguishes a drop from a plain click. */
+    onRelease: (point: Point, activated: boolean) => void;
+    /** The gesture was abandoned — a `pointercancel`, or a touch that scrolled. */
+    onCancel: () => void;
+}
+export interface GestureOptions {
+    activation?: PointerActivation;
+}
+/**
+ * Wire an element as a drag handle. Returns the teardown.
+ *
+ * The listeners live on the ELEMENT, not the document, and the element takes
+ * pointer capture at `pointerdown` — so every subsequent move and the release
+ * are delivered here even when the pointer leaves the element, which it does
+ * immediately and for the entire gesture.
+ */
+export declare function attachPointerGesture(element: HTMLElement, handlers: GestureHandlers, options?: GestureOptions): () => void;

package/dist/types/lib/dnd/sensors/keyboard.d.ts

@@ -0,0 +1,54 @@
+import type { DragSession } from "../session";
+import type { DragAxis, DragId } from "../types";
+/**
+ * The keyboard sensor. Drives the SAME session the pointer does.
+ *
+ * WHY A SENSOR AND NOT A KEYBOARD IMPLEMENTATION. The usual shape is a pointer
+ * drag with keyboard "support" bolted on, which is two codebases computing the
+ * same answer — and the accessible one is the one nobody looks at, so it is the
+ * one that rots. Here the keyboard can only `start`, `moveIndex`,
+ * `moveContainer`, `commit` and `cancel`, exactly like the pointer, so the two
+ * cannot disagree about where a card lands. `dnd-sensors.test.ts` asserts they
+ * reach an identical target for the same intent.
+ *
+ * THE KEY MAP IS FIXED BY THE PROJECT CONTRACT, not by this file:
+ *
+ *   Space          pick up; drop when already carrying
+ *   Enter          the same, but ONLY when the drag source is itself the
+ *                  focused control. On a whole-card source the key arrives by
+ *                  bubbling from the card's own button, and Enter is that
+ *                  button's — see the note at the check.
+ *   Escape         cancel — handled by `attachSessionWindowListeners`, NOT here
+ *   Along the axis step the insertion point inside the current container
+ *   Across it      move to the previous / next container
+ *
+ * "Along" and "across" swap with the container's axis: a vertical list steps
+ * with Up/Down and changes column with Left/Right; a horizontal one is the
+ * mirror. Hard-coding Up/Down as "within" makes a horizontal list unusable in
+ * the one input mode that has no alternative.
+ *
+ * NO `aria-grabbed`, NO `aria-dropeffect`. They are the attributes the name
+ * suggests and they were removed in ARIA 1.2 because assistive-technology
+ * support never arrived — an implementation using them announces nothing at
+ * all. Ordinary focus, an `aria-describedby` instruction and a live region are
+ * the working pattern; the live region is `announce.tsx`'s.
+ */
+export interface KeyboardSensorOptions {
+    id: DragId;
+    /**
+     * The reorder axis of the container this item currently lives in. Decides
+     * which arrow pair steps within the container and which moves between them.
+     */
+    axis?: DragAxis;
+    /** Return false to refuse pickup — a disabled row. Mirrors the pointer sensor. */
+    canStart?: (e: KeyboardEvent) => boolean;
+}
+/**
+ * Wire an element as a keyboard drag handle. Returns the teardown.
+ *
+ * The element must be focusable and reachable — `tabIndex={0}` and
+ * `role="button"` — or none of this is ever delivered. A handle that is a
+ * `<span>` with a listener is invisible to the keyboard and to every screen
+ * reader, and looks completely correct on a desktop.
+ */
+export declare function attachKeyboardSensor(session: DragSession, element: HTMLElement, options: KeyboardSensorOptions): () => void;

package/dist/types/lib/dnd/sensors/pointer.d.ts

@@ -0,0 +1,59 @@
+import type { DragSession } from "../session";
+import type { DragId } from "../types";
+import { type PointerActivation } from "./gesture";
+/**
+ * The pointer sensor. One listener set for mouse, touch and pen.
+ *
+ * ACTIVATION IS THE WHOLE PROBLEM. Starting the drag on `pointerdown` is what
+ * makes a drag list unusable: a tap becomes a drag, and on a phone a swipe that
+ * was meant to scroll the column picks a card up instead. So a pointer is held
+ * in `pending` until it proves itself, and the proof differs by input type:
+ *
+ *   - MOUSE and PEN have a cursor, so intent is expressed by MOVING. A few
+ *     pixels of travel is unambiguous and instant, and a click never reaches it.
+ *   - TOUCH has no cursor and movement is how you scroll, so movement cannot be
+ *     the signal. Intent is expressed by DWELLING — the long press — and any
+ *     travel beyond a small tolerance before the timer fires means the finger
+ *     was scrolling and the session must be abandoned.
+ *
+ * Getting that backwards is the single most common defect in drag lists, and it
+ * only shows up on a device the author was not testing on.
+ *
+ * AND THE DWELL IS ONLY HALF OF THE TOUCH ANSWER. The activation constraint
+ * decides whether WE start a drag; it says nothing about whether the BROWSER
+ * starts a scroll, and the browser decides that from `touch-action` alone,
+ * before any of this code runs. `touch-action: none` on the handle is therefore
+ * the tempting fix and it re-creates the failure it was meant to prevent, just
+ * on a smaller target: every swipe that happens to begin on the grip is eaten,
+ * the column does not move, and the list feels stuck at random.
+ *
+ * The handle is `touch-action: pan-y` instead (`pan-x` for a horizontal list),
+ * so the browser scrolls exactly as it would on any other element, and the
+ * drag takes the gesture back at the moment it activates by cancelling
+ * `touchmove` — see `beginTouchScrollGuard`. That ordering is what makes both
+ * true on the SAME element: a swipe scrolls, a press picks up.
+ */
+export type { PointerActivation } from "./gesture";
+export interface PointerSensorOptions {
+    id: DragId;
+    activation?: PointerActivation;
+    /** Return false to refuse the gesture — a disabled row, or a click on a button inside the card. */
+    canStart?: (e: PointerEvent) => boolean;
+}
+/**
+ * Wire an element as a drag handle for a list `DragSession`.
+ *
+ * A THIN ADAPTER, deliberately. The session's four verbs map one-to-one onto
+ * the gesture's callbacks, and the only real logic left is the `pending`
+ * start — the session is told about the press immediately so it can refuse the
+ * item, and only activated once the constraint is met.
+ */
+export declare function attachPointerSensor(session: DragSession, element: HTMLElement, options: PointerSensorOptions): () => void;
+/**
+ * Esc, and the two things that move a box while a drag is in flight.
+ *
+ * Window-level because a keypress during a drag does not go to the handle — the
+ * handle has pointer capture, not focus — and because a scroll of an ancestor
+ * invalidates every rect in the snapshot at once.
+ */
+export declare function attachSessionWindowListeners(session: DragSession): () => void;