@vue-dnd-kit/core 2.4.7 → 3.0.0-beta.2

package/dist/devtools.d.ts

@@ -0,0 +1,610 @@
+import { App } from 'vue';
+
+/** What a function `accept` rule is asked with. */
+declare interface AcceptContext {
+    /** The drag. */
+    active: Active;
+    /** Every dragged item. */
+    items: DragItem[];
+    /** The types of every dragged item, together. */
+    types: string[];
+}
+
+/** `'all'`: every dragged item must match; `'some'`: at least one (the rest can be rejected in `onBeforeDrop`). */
+declare type AcceptMode = 'all' | 'some';
+
+/** `'*'` or omitted accepts everything. Untyped items fit any string rule (v2 `groups: []` parity). */
+declare type AcceptRule = '*' | string | string[] | ((context: AcceptContext) => boolean);
+
+/** The running drag: the item it started from, and every item it carries. */
+declare interface Active<T = unknown> {
+    /** Id of the item the drag started from. */
+    id: Key;
+    /** Every dragged id, the primary one first (multi-drag). */
+    ids: Key[];
+    /** Every dragged item, the primary one first. */
+    items: DragItem<T>[];
+    /** The `data` of the item the drag started from. */
+    data: unknown;
+    /** The `label` of the item the drag started from, what people call it. */
+    label?: string;
+    /** The normalized `type` of the item the drag started from; empty means it fits any drop target. */
+    type: string[];
+    /** Element the drag started from. It may get detached (virtual lists, cross-list moves). */
+    element: HTMLElement;
+    /** Layout rect of `element` at drag start. */
+    rect: Rect;
+    /** How the drag moves: `'pointer'` follows points, `'keyboard'` moves by items (`SensorActivation.type`). */
+    sensor: SensorType;
+    /**
+     * A drag from outside the page (files, a link, text, or items from another window of the
+     * app): what it carries. Its `items` are made for it (`element` is a stand-in).
+     */
+    external?: ExternalData;
+    /** The browser's own drag (`native`, or one from outside): the browser draws the dragged image, and there is no overlay. */
+    native?: boolean;
+}
+
+export declare interface ActiveSnapshot {
+    id: Key;
+    ids: Key[];
+    items: ItemSnapshot[];
+    type: string[];
+    sensor: SensorType;
+    element: Element;
+    /** Layout rect of `element` at drag start. */
+    rect: Rect;
+}
+
+/** Why a drag ended without a drop. */
+export declare type CancelReason = 
+/** Escape, `cancel()`, the provider unmounted. */
+'cancelled'
+/** An `onBeforeDrop` (a monitor's, the target's or a list's) returned `false`, or a list's `dropOutside: 'cancel'`. */
+| 'rejected'
+/** Dropped on a target whose `accept` rule refuses the items. */
+| 'refused';
+
+/**
+ * Overlay clone of the dragged element. Taken synchronously at drag start,
+ * before the placeholder re-renders, and detached from page-level side effects.
+ */
+/**
+ * Where the clone will be shown (the overlay's parent): the styles it loses there are
+ * inlined. Backgrounds aren't guessed: a source without one of its own (a list row the
+ * list paints) gives a transparent clone, styled with `[data-dnd-overlay]` in CSS.
+ */
+export declare interface CloneOptions {
+    container?: Element | null;
+}
+
+/**
+ * The overlay's clone of `source`: a copy that fills the overlay box, with the computed
+ * styles it would lose outside its list inlined (`snapshot.ts`), in a box that carries the
+ * custom properties it inherits. A table row comes in a table of its own.
+ */
+export declare const clonePreview: (source: HTMLElement, options?: CloneOptions) => HTMLElement;
+
+/**
+ * Connects the devtools (once per page; later calls return the same bridge). Providers
+ * set up from now on report to it, until `disconnect()`.
+ */
+export declare function connectDevtools(): DevtoolsBridge;
+
+/**
+ * A point or an offset, in px: a position from the viewport's top-left corner, or an offset
+ * from where the drag started (`delta`, `transform`).
+ */
+declare interface Coordinates {
+    /** Horizontal, growing to the right. */
+    x: number;
+    /** Vertical, growing downward. */
+    y: number;
+}
+
+/**
+ * A deep copy of `source` that stays out of the page's way: no ids, no `data-dnd-*` marks,
+ * hidden from assistive tech, with what `cloneNode` leaves out (form state, canvas pixels).
+ * `source` may be detached (an item Vue just removed).
+ */
+export declare const copyElement: (source: HTMLElement) => HTMLElement;
+
+export declare interface DevtoolsBridge {
+    /** Providers set up since the bridge was connected (and still mounted), in setup order. */
+    providers(): DevtoolsProvider[];
+    /** Tells `listener` about providers and their events. Returns the unsubscribe. */
+    subscribe(listener: DevtoolsListener): () => void;
+    /** Removes the hook and forgets every provider (tests, hot reload). */
+    disconnect(): void;
+}
+
+export declare type DevtoolsEvent = (OfDrag & {
+    type: 'start';
+    active: ActiveSnapshot;
+    pointer: Coordinates;
+    /** The list the items come from. */
+    source: Key | null;
+    /** `null`: started without a sensor (`manager.start`). */
+    sensor: SensorSnapshot | null;
+}) | (OfDrag & {
+    type: 'over';
+    over: OverSnapshot | null;
+    previous: Key | null;
+})
+/** The pointer moved (every frame of a drag): for live views, not for logs. */
+| (OfDrag & {
+    type: 'move';
+})
+/** Released: the `onBeforeDrop` hooks decide. */
+| (OfDrag & {
+    type: 'release';
+    over: OverSnapshot | null;
+}) | (OfDrag & {
+    type: 'drop';
+    over: OverSnapshot | null;
+    /** False when dropped outside every drop target. */
+    dropped: boolean;
+    accepted: Key[];
+    rejected: Key[];
+    /** Milliseconds the `onBeforeDrop` hooks took. */
+    waited: number;
+    sortable: SortableDropSnapshot[];
+}) | (OfDrag & {
+    type: 'cancel';
+    reason: CancelReason;
+    over: OverSnapshot | null;
+    /** Milliseconds the `onBeforeDrop` hooks took; `null` when the drag was cancelled before a drop. */
+    waited: number | null;
+    /** Drops a list prepared before it was rejected. */
+    sortable: SortableDropSnapshot[];
+}) | {
+    type: 'status';
+    status: DnDStatus;
+} | {
+    type: 'selection';
+    ids: Key[];
+} | {
+    type: 'announcement';
+    text: string;
+} | {
+    type: 'autoScroll';
+    scrolling: boolean;
+}
+/**
+* The items of a list with `animateChanges` on changed, and no drag changed them: the list
+* animates the change (its keys; a tree's visible rows).
+*/
+| {
+    type: 'change';
+    group: string;
+    list: Key;
+    added: Key[];
+    removed: Key[];
+    reordered: boolean;
+};
+
+export declare interface DevtoolsListener {
+    added?(provider: DevtoolsProvider): void;
+    /** The provider unmounted. */
+    removed?(provider: DevtoolsProvider): void;
+    /** A listener with this handler makes the bridge follow the providers (until then they are only recorded). */
+    event?(provider: DevtoolsProvider, event: DevtoolsEvent): void;
+}
+
+/**
+ * Live overrides of a provider's option values, for the devtools' editing: development
+ * only, never written to the code, gone with the provider. An override applies where the
+ * library reads the option, and what read it re-reads it.
+ *
+ * Options: the provider's props; a list's or tree's options; a plain drop target's
+ * (`disabled`, `priority`, `accept`, `acceptMode`); a draggable's or sortable item's
+ * `disabled`, `keyboard` and `activation` (overriding what it computes from its list too).
+ */
+export declare interface DevtoolsOverrides {
+    /** Overrides `option` of `target` with `value`: `false` when it can't (no such target or option, a frozen options object). */
+    set(target: OverrideTarget, option: string, value: unknown): boolean;
+    /** Removes the override of `option` of `target`, of every option of `target`, or (no target) every override. */
+    reset(target?: OverrideTarget, option?: string): void;
+    /** `option` of `target`; `undefined` when the target isn't mounted (or isn't one: a list's own drop target). */
+    read(target: OverrideTarget, option: string): OptionRead | undefined;
+    /** Every override set (its target may be unmounted: it applies again when it mounts). */
+    list(): OptionOverride[];
+}
+
+/** A provider as the devtools see it. */
+export declare interface DevtoolsProvider {
+    /** Unique on the page: `provider-1`, … in the order providers were set up. */
+    readonly id: string;
+    /** `DnDProvider` and the component that renders it. */
+    readonly label: string;
+    /** The app the provider renders in. */
+    readonly app: App | null;
+    /**
+     * The provider's handle (`useDnDContext()`): with `provideDnDContext`, a sensor runs in
+     * it from outside its components (the drags of the devtools tab).
+     */
+    readonly context: DnDContext;
+    /** Everything the provider knows, now. */
+    snapshot(): ProviderSnapshot;
+    /** Cancels the current drag (or a press that is activating, a running rubber band). */
+    cancel(): void;
+    /** Empties the selection. */
+    clearSelection(): void;
+    /** Live overrides of its options (the devtools' editing). */
+    readonly overrides: DevtoolsOverrides;
+}
+
+/**
+ * A provider as `useDnDContext()` returns it, to hand to `provideDnDContext()`: another
+ * Vue app (e.g. one mounted in a shadow root) then works with the same provider. Opaque:
+ * it has no public members, so it never changes with the library's internals.
+ */
+declare interface DnDContext {
+    readonly [dndContext]: true;
+}
+
+declare const dndContext: unique symbol;
+
+/**
+ * What the provider is doing:
+ * - `'idle'`: nothing;
+ * - `'activating'`: a press waits for its activation constraint (a distance, a long press);
+ * - `'dragging'`: a drag runs;
+ * - `'dropping'`: a drop is decided (an async `onBeforeDrop`), or an overlay still lands;
+ * - `'selecting'`: a selection area draws its band.
+ */
+declare type DnDStatus = 'idle' | 'activating' | 'dragging' | 'dropping' | 'selecting';
+
+export declare interface DraggableSnapshot {
+    id: Key;
+    /** Normalized `type`; empty fits any drop target. */
+    type: string[];
+    disabled: boolean;
+    selected: boolean;
+    /** One of the dragged items. */
+    dragging: boolean;
+    element: Element | null;
+    /** Handle element or selector; `null` when the whole element is the handle. */
+    handle: Element | string | null;
+    data: unknown;
+    /** A sortable item: the list or tree it is in (`null` while it is in none, e.g. a copy). */
+    list: Key | null;
+}
+
+/** One dragged item: the one the drag started from, or another one of a multi-drag. */
+declare interface DragItem<T = unknown> {
+    /** Id of its draggable (the key of a sortable item). */
+    id: Key;
+    /** Item object when the drag comes from a sortable list. */
+    item?: T;
+    /** Its `data` option. */
+    data: unknown;
+    /** Its `label`, what people call it. */
+    label?: string;
+    /** Normalized `type` of the draggable; empty means it fits any drop target. */
+    type: string[];
+}
+
+/**
+ * What a drop does: `'move'`, `'copy'` (the items stay, copies of them go in), `'swap'`
+ * (`behavior: 'swap'`: two items exchange places) or `'insert'` (a plain draggable goes into
+ * a list as the item its `createItem` made).
+ */
+declare type DragMode = 'move' | 'copy' | 'swap' | 'insert';
+
+/**
+ * What a drop outside every target does: `'placeholder'` keeps the items where their slot
+ * is, `'cancel'` sends them back, `'remove'` takes them out of their list.
+ */
+declare type DropOutside = 'placeholder' | 'cancel' | 'remove';
+
+export declare interface DroppableSnapshot {
+    id: Key;
+    /** The `accept` option as given (`undefined`: everything). Sortable lists accept by their group's rules. */
+    accept: AcceptRule | undefined;
+    acceptMode: AcceptMode;
+    priority: number;
+    disabled: boolean;
+    /** The drag is over it. */
+    over: boolean;
+    /** During a drag: whether it takes the dragged items. `null` while idle, or when it can't be told without side effects. */
+    accepting: boolean | null;
+    element: Element | null;
+    data: unknown;
+    /** A sortable list or tree (see `ListSnapshot`). */
+    sortable: boolean;
+}
+
+/**
+ * A drag from outside the page (`Active.external`, `DnDEvent.external`). While it is held
+ * the browser tells what it carries, not the data: the files, links and text come at the
+ * drop (`ready`).
+ */
+declare interface ExternalData {
+    /** The MIME types it offers (`Files`, `text/uri-list`, `text/plain`, an app's own). */
+    types: readonly string[];
+    /** The MIME types of its files, one per file (`''` when the browser can't tell). */
+    fileTypes: readonly string[];
+    /** At the drop: the files the target takes (folders and refused files left out). */
+    files: readonly File[];
+    /** At the drop: its links (`text/uri-list`). */
+    urls: readonly string[];
+    /** At the drop: its plain text. */
+    text: string;
+    /** At the drop: its HTML. */
+    html: string;
+    /** At the drop: the data of any type it offers (`''` before, and for a type it doesn't offer). */
+    getData(type: string): string;
+    /** It was dropped: the data above is there. */
+    ready: boolean;
+    /**
+     * Items of the library dragged in from another window of the app (`native`): the name of
+     * their sortable group. The lists of that group take them as if they came from one of
+     * their own lists; `active.items` has them.
+     */
+    group?: string;
+}
+
+export declare interface GroupSnapshot {
+    name: string;
+    lists: ListSnapshot[];
+    session: SortableSessionSnapshot | null;
+    /** Insertion line of `placeholder: 'indicator'` lists. */
+    indicator: SortableIndicator | null;
+}
+
+export declare interface ItemSnapshot {
+    id: Key;
+    type: string[];
+    data: unknown;
+    /** Item object of a sortable list. */
+    item?: unknown;
+}
+
+/** An id or a key: of a draggable, a drop target, a list, an item of a list. */
+declare type Key = string | number;
+
+export declare interface ListSnapshot {
+    id: Key;
+    kind: 'list' | 'tree';
+    /** Name of its sortable group (`sortable:<id>` for a list without `group`). */
+    group: string;
+    strategy: SortableStrategy;
+    placeholder: SortablePlaceholder;
+    behavior: SortableBehavior;
+    multiple: MultipleMode;
+    pull: boolean | 'clone';
+    /** `sort: false` keeps the order of its own items. */
+    sort: boolean;
+    dropOutside: DropOutside;
+    acceptMode: AcceptMode;
+    disabled: boolean;
+    /** `items` can't be written (a getter, a readonly ref): drops are the user's to apply. */
+    controlled: boolean;
+    /** Items in the source (visible rows of a tree). */
+    count: number;
+    /** Keys of the source, in order. */
+    keys: Key[];
+    /** Draft order during a drag; `null` while idle. */
+    draft: Key[] | null;
+    element: Element | null;
+    over: boolean;
+    /** See `DroppableSnapshot.accepting`. */
+    accepting: boolean | null;
+}
+
+/**
+ * What the other selected items do in a multi-drag:
+ * - `'group'`: they leave their places and travel with the active item as contiguous
+ *   placeholders, so while hovering the list already shows the result of the drop;
+ * - `'gaps'`: they stay in place until the drop;
+ * - `'stack'`: they collapse into the overlay.
+ *
+ * The default overlay shows the dragged items in a column along the list (`'group'`,
+ * `'gaps'`; a row in horizontal lists, a pile behind the active one in grids), or the active
+ * one with a count (`'stack'`).
+ */
+declare type MultipleMode = 'group' | 'gaps' | 'stack';
+
+declare interface OfDrag {
+    /** Drags of the provider, counted from 1: the events of one drag share it. */
+    drag: number;
+}
+
+export declare interface OptionOverride {
+    target: OverrideTarget;
+    option: string;
+    value: unknown;
+}
+
+/** An option as the library reads it, and as the code gives it. */
+export declare interface OptionRead {
+    /** The value the library uses now (an override's, else the code's, refs and getters read). */
+    value: unknown;
+    /** The option as the code gives it (a ref or a getter as given), underneath any override. */
+    code: unknown;
+    overridden: boolean;
+}
+
+/** What an option override applies to: the provider, or one of its lists (trees too), draggables or drop targets by id. */
+export declare type OverrideTarget = {
+    kind: 'provider';
+} | {
+    kind: 'list' | 'draggable' | 'droppable';
+    id: Key;
+};
+
+export declare interface OverSnapshot {
+    id: Key;
+    accepted: boolean;
+    data: unknown;
+    element: Element;
+    rect: Rect;
+}
+
+export declare interface ProviderSnapshot {
+    status: DnDStatus;
+    /** The provider's props as given (`undefined`: the default). */
+    options: Record<string, unknown>;
+    draggables: DraggableSnapshot[];
+    /** Drop targets, the droppables of sortable lists included (`sortable: true`). */
+    droppables: DroppableSnapshot[];
+    groups: GroupSnapshot[];
+    selection: Key[];
+    session: SessionSnapshot;
+}
+
+/** A box in px, in viewport coordinates, as `getBoundingClientRect()` gives it. */
+declare interface Rect {
+    /** Its top edge, from the top of the viewport. */
+    top: number;
+    /** Its left edge, from the left of the viewport. */
+    left: number;
+    /** Its width. */
+    width: number;
+    /** Its height. */
+    height: number;
+    /** Its right edge, from the left of the viewport: `left + width`. */
+    right: number;
+    /** Its bottom edge, from the top of the viewport: `top + height`. */
+    bottom: number;
+}
+
+/** The sensor that started a drag. */
+export declare interface SensorSnapshot {
+    /** Its `name` (`'pointer'`, `'keyboard'` for the built-in ones); `undefined` when it has none. */
+    name: string | undefined;
+    /** Started by touch. */
+    touch: boolean;
+}
+
+/**
+ * How a drag moves, whichever sensor drives it (`SensorActivation.type`): `'pointer'`
+ * follows points, `'keyboard'` moves by items.
+ */
+declare type SensorType = 'pointer' | 'keyboard';
+
+export declare interface SessionSnapshot {
+    status: DnDStatus;
+    active: ActiveSnapshot | null;
+    over: OverSnapshot | null;
+    /** Pointer after modifiers. */
+    pointer: Coordinates | null;
+    /** Offset of the overlay from the drag start, after modifiers. */
+    transform: Coordinates;
+    /** What a drop would do. */
+    mode: DragMode;
+    /** Key whose element the overlay lands on, when it isn't the active id (copies, created items). */
+    landingKey: Key | null;
+    /** Multi-drag: slot key → dragged id that lands there. */
+    landings: [Key, Key][];
+    /** Size of the overlay box (`overlayFit`). */
+    fitSize: Size | null;
+    /** Whether the drag has an overlay (without one the element itself moves). */
+    overlay: boolean;
+    /** The overlay box while it is shown (what the user sees dragged). */
+    overlayElement: HTMLElement | null;
+    /** Ids with a clone taken at pickup, in drop order. */
+    previews: Key[];
+    /** The drop is decided; only the overlay animation is left. */
+    settling: boolean;
+    /** What a decided drop lands on. */
+    dropTarget: OverSnapshot | null;
+    autoScrolling: boolean;
+    /** Progress of a press that is activating, 0–1. */
+    activation: number;
+    /** Last text of the live region. */
+    announcement: string;
+}
+
+/** A width and a height, in px. */
+declare interface Size {
+    /** Width in px. */
+    width: number;
+    /** Height in px. */
+    height: number;
+}
+
+/** What hovering an item does: `'sort'` makes room (the items between shift), `'swap'` exchanges the two items. */
+declare type SortableBehavior = 'sort' | 'swap';
+
+/** A drop on a sortable list or tree, as its `SortableDropEvent` told it. */
+export declare interface SortableDropSnapshot {
+    group: string;
+    keys: Key[];
+    accepted: Key[];
+    rejected: Key[];
+    from: {
+        list: Key | null;
+        index: number;
+    };
+    to: {
+        list: Key;
+        index: number;
+    };
+    sameList: boolean;
+    mode: DragMode;
+    /** `mode: 'swap'`: the exchanged item. */
+    partner?: Key;
+    /** The new items of every list the drop changes. */
+    result: ReadonlyMap<Key, unknown[]>;
+    /** `preventDefault()` was called: the drop wasn't written. */
+    defaultPrevented: boolean;
+}
+
+/** Where the drop goes with `placeholder: 'indicator'`: the list doesn't move, you draw the line. */
+declare interface SortableIndicator {
+    /** Id of the list (or tree) the drop goes into. */
+    list: Key;
+    /** Insertion position in the list as rendered. */
+    index: number;
+    /** Item the indicator is attached to; `null` in an empty list. */
+    key: Key | null;
+    /**
+     * Side of `key` the line goes on. `'inside'` (trees): the middle of a row that takes
+     * the dragged nodes is hovered, the drop goes into it as its first child. `'swap'`
+     * (`behavior: 'swap'`): `key` is the item the drop exchanges with; mark the item itself.
+     */
+    side: 'before' | 'after' | 'inside' | 'swap';
+    /** Trees: depth the dropped nodes get (roots are 0), e.g. to indent the line. */
+    depth?: number;
+    /** Trees: parent the dropped nodes get, `null` at the root level. */
+    parentKey?: Key | null;
+}
+
+/**
+ * How a drag shows where it goes: `'item'`, the dragged item's slot moves through the list;
+ * `'indicator'`, the list stays as it is and `indicator` says where the drop goes (you draw the line).
+ */
+declare type SortablePlaceholder = 'item' | 'indicator';
+
+/** A sortable group's drag session. */
+export declare interface SortableSessionSnapshot {
+    activeKey: Key;
+    /** Dragged key the slot stands for (a tree node the active one rides in). */
+    lead: Key;
+    /** Every moved key, the lead included. */
+    keys: Key[];
+    /** Where the lead started; `list` is `null` for a plain draggable from outside. */
+    origin: {
+        list: Key | null;
+        index: number;
+    };
+    /** Key holding the slot in the drafts: the lead, its copy or a created item. */
+    slot: Key;
+    /** List whose draft holds the slot. */
+    list: Key | null;
+    /** What the slot is: the dragged item (`move`), its copy or an item made for a plain draggable. */
+    kind: 'move' | 'copy' | 'insert';
+    /** Keys travelling with the slot (multi-drag `'group'`). */
+    block: Key[];
+    /** Item the active one is exchanged with (`behavior: 'swap'`). */
+    swap: Key | null;
+    /** A trash zone or `dropOutside: 'remove'` takes the items out of their lists. */
+    removed: boolean;
+}
+
+/** How a list lays out its items: a column (`'vertical'`), a row (`'horizontal'`) or a grid that wraps (`'grid'`). */
+declare type SortableStrategy = 'vertical' | 'horizontal' | 'grid';
+
+export { }