@danxbot/ui 1.0.0

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

@@ -0,0 +1,132 @@
+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;
+    containerLabel: string;
+    /** 1-based, as spoken. */
+    position: number;
+    /**
+     * 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;
+}
+export interface DragStrings {
+    /** Rendered by `<DragInstructions>`; referenced by each handle's `aria-describedby`. */
+    instructions: string;
+    picked: (c: DragAnnouncementContext) => string;
+    moved: (c: DragAnnouncementContext) => string;
+    dropped: (c: DragAnnouncementContext) => string;
+    /** Describes the item's ORIGINAL position — cancel is a restore, not a move. */
+    cancelled: (c: DragAnnouncementContext) => string;
+}
+/**
+ * Exported as data so a consumer can read one message, override one message, or
+ * assert on the set — a grammar hidden inside the component that renders it can
+ * only be checked by rendering it.
+ */
+export declare const DEFAULT_DRAG_STRINGS: DragStrings;
+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;
+    /** Override any subset of the grammar — localisation, or a domain noun. */
+    strings?: Partial<DragStrings>;
+}
+/**
+ * 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 {
+    strings?: Partial<DragStrings>;
+    /**
+     * 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({ strings, 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/geometry.d.ts

@@ -0,0 +1,78 @@
+import type { ContainerRect, ContainerRegistration, DragId, DropTarget, 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>): 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;
+/** 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`.
+ *
+ * Returns null when the pointer is over no container at all. The session keeps
+ * the PREVIOUS target in that case rather than clearing it — dragging a card
+ * briefly outside the board should not make the insertion marker vanish, and a
+ * release outside every container should still land where the marker last
+ * showed. That is the behaviour every board people already use has, and the
+ * alternative reads as the drag having silently failed.
+ */
+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,16 @@
+/**
+ * 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, DragAxis, DragCancelEvent, DragEndEvent, DragId, DragMode, DragPhase, DragSessionCallbacks, DragStartEvent, DragState, DropTarget, ItemRect, ItemRegistration, LayoutSnapshot, Point, } from "./types";
+export { applyMove, containerAt, indexAt, isNoOp, measure, remainingItems, resolveTarget, sameTarget, } from "./geometry";
+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, useDraggable, useDropContainer, type UseDraggableOptions, type UseDraggableResult, type UseDropContainerOptions, type UseDropContainerResult, } from "./use-drag";
+export { DEFAULT_DRAG_STRINGS, DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, useDragAnnouncements, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, type DragStrings, } 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,50 @@
+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 / Enter  pick up on a focused handle; drop when already carrying
+ *   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;

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

@@ -0,0 +1,99 @@
+import type { ContainerRegistration, DragId, DragMode, DragSessionCallbacks, DragState, ItemRegistration, LayoutSnapshot, Point } from "./types";
+export interface StartArgs {
+    id: DragId;
+    mode: DragMode;
+    /** Pointer position at pickup. Omitted for keyboard sessions. */
+    point?: Point;
+    /**
+     * `true` for a pointer that is down but has not passed its activation
+     * constraint yet. The session holds `pending` until the sensor calls
+     * `activate()` — see `DragPhase` in `types.ts` for why that gap exists.
+     */
+    pending?: boolean;
+}
+export declare class DragSession {
+    private state;
+    private listeners;
+    private items;
+    private containers;
+    private layout;
+    private callbacks;
+    private observers;
+    constructor(callbacks?: DragSessionCallbacks);
+    /**
+     * The OWNING consumer's callbacks — the one that renders the board and writes
+     * the reorder. Replaced rather than passed per-call because a React consumer
+     * re-creates its handlers on every render and the session must not be rebuilt;
+     * rebuilding it mid-gesture drops the drag.
+     */
+    setCallbacks(callbacks: DragSessionCallbacks): void;
+    /**
+     * Register an ADDITIONAL listener. Returns its teardown.
+     *
+     * `setCallbacks` is a single slot owned by whoever renders the board, so a
+     * second interested party — the live-region announcer, an analytics hook, a
+     * test — could not be told anything without clobbering it. And `subscribe`
+     * is not a substitute: a drop and a cancel both end at the same idle state,
+     * so a state subscriber sees ONE identical transition for two outcomes that
+     * must be announced differently.
+     *
+     * That gap was not theoretical. The announcer worked around it by inferring
+     * the cause from whichever DOM event was mid-dispatch — about ninety lines of
+     * genuinely careful machinery, defeated once by the microtask checkpoint the
+     * HTML spec runs BETWEEN listeners of the same event, so that every cancel
+     * announced itself as a drop. Nothing that reads the session should have to
+     * guess what the session just did.
+     */
+    addObserver(callbacks: DragSessionCallbacks): () => void;
+    /**
+     * Owner first, then observers, in registration order.
+     *
+     * The owner goes first because it is the one that mutates the list, and an
+     * observer that reads the consumer's state — an announcer reporting "3 of 7"
+     * — must see the world after the write, not before.
+     */
+    private fan;
+    getState: () => DragState;
+    subscribe: (fn: () => void) => (() => void);
+    private emit;
+    registerItem(reg: ItemRegistration): () => void;
+    registerContainer(reg: ContainerRegistration): () => void;
+    /** Registered order, used by keyboard container stepping. */
+    containerIds(): string[];
+    /**
+     * Re-measure. Called at pickup, and by the sensors on scroll, resize and
+     * every auto-scroll frame — the three things that move a box while a drag is
+     * in flight without the drag having caused it.
+     */
+    remeasure(): LayoutSnapshot;
+    getLayout(): LayoutSnapshot | null;
+    start(args: StartArgs): boolean;
+    /** Promote a `pending` pointer into a real drag once its constraint is met. */
+    activate(): void;
+    /** Pointer moved. Cheap when the target has not changed, which is most frames. */
+    moveTo(point: Point): void;
+    /**
+     * Step the insertion point within the current container. The keyboard's
+     * along-axis movement.
+     *
+     * Clamped rather than wrapping: wrapping from the bottom of a list to the top
+     * is indistinguishable from a missed keypress when you cannot see the list.
+     */
+    moveIndex(delta: number): void;
+    /**
+     * Move to the previous or next container. The keyboard's cross-axis movement.
+     *
+     * Lands at the index nearest the item's current one rather than at the top,
+     * because a card carried sideways across a board should stay roughly where it
+     * was vertically — the same thing the pointer does for free.
+     */
+    moveContainer(delta: number): void;
+    /** Release. Emits `onDragEnd` even for a no-op so consumers can announce it. */
+    commit(): void;
+    /** Esc, `pointercancel`, or an unmount mid-gesture. Never writes. */
+    cancel(): void;
+    /** The container the pointer is over right now, or null. */
+    containerAtPoint(point: Point): string | null;
+    /** How many items a container holds once the carried one is taken out. */
+    slotCount(container: string): number;
+}