@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/drag-drop/directives/drag.d.ts

@@ -0,0 +1,210 @@
+import { type Stream } from "../../scrolling/emitter.js";
+import { type ElementLike } from "../dom/coerce.js";
+import { type Directionality } from "../../bidi/index.js";
+import type { DragDrop, DragEnd, DragEnter, DragExit, DragMove, DragRelease, DragStart } from "../drag-events.js";
+import { type DragConstrainPosition, type DragRef, type Point, type PreviewContainer } from "../drag-ref.js";
+import type { DropListInstance } from "./drop-list.js";
+import type { DragAxis, DragDropConfig, DragStartDelay } from "./config.js";
+import { DragHandleInstance } from "./drag-handle.js";
+import { type MaybeAccessor } from "./registry.js";
+/** Inputs and outputs of a draggable (Angular `cdkDrag*` inputs / outputs, `Cdk` prefix dropped). */
+export interface DragInputs<T = any> {
+    /** Arbitrary data to attach to this drag instance. */
+    data?: MaybeAccessor<T>;
+    /** Locks the position of the dragged element along the specified axis. */
+    lockAxis?: MaybeAccessor<DragAxis | null | undefined>;
+    /**
+     * Selector that will be used to determine the root draggable element, starting from
+     * the `Drag` element and going up the DOM. Passing an alternate root element is useful
+     * when trying to enable dragging on an element that you might not have access to.
+     */
+    rootElementSelector?: MaybeAccessor<string | undefined>;
+    /**
+     * Node or selector that will be used to determine the element to which the draggable's
+     * position will be constrained. If a string is passed in, it'll be used as a selector that
+     * will be matched starting from the element's parent and going up the DOM until a match
+     * has been found.
+     */
+    boundaryElement?: MaybeAccessor<string | ElementLike | null | undefined>;
+    /**
+     * Amount of milliseconds to wait after the user has put their
+     * pointer down before starting to drag the element.
+     */
+    dragStartDelay?: MaybeAccessor<DragStartDelay | string | undefined>;
+    /**
+     * Sets the position of a `Drag` that is outside of a drop container.
+     * Can be used to restore the element's position for a returning user.
+     */
+    freeDragPosition?: MaybeAccessor<Point | undefined>;
+    /** Whether starting to drag this element is disabled. */
+    disabled?: MaybeAccessor<boolean | undefined>;
+    /**
+     * Function that can be used to customize the logic of how the position of the drag item
+     * is limited while it's being dragged. Gets called with a point containing the current position
+     * of the user's pointer on the page, a reference to the item being dragged and its dimensions.
+     * Should return a point describing where the item should be rendered.
+     */
+    constrainPosition?: DragConstrainPosition;
+    /** Class to be added to the preview element. */
+    previewClass?: MaybeAccessor<string | string[] | undefined>;
+    /**
+     * Configures the place into which the preview of the item will be inserted. Can be configured
+     * globally through `DragDropConfigContext`. Possible values:
+     * - `global` - Preview will be inserted at the bottom of the `<body>`. The advantage is that
+     * you don't have to worry about `overflow: hidden` or `z-index`, but the item won't retain
+     * its inherited styles.
+     * - `parent` - Preview will be inserted into the parent of the drag item. The advantage is that
+     * inherited styles will be preserved, but it may be clipped by `overflow: hidden` or not be
+     * visible due to `z-index`. Furthermore, the preview is going to have an effect over selectors
+     * like `:nth-child` and some flexbox configurations.
+     * - `ElementLike` - Preview will be inserted into a specific element.
+     * Same advantages and disadvantages as `parent`.
+     */
+    previewContainer?: MaybeAccessor<PreviewContainer | undefined>;
+    /**
+     * If the parent of the dragged element has a `scale` transform, it can throw off the
+     * positioning when the user starts dragging. Use this input to notify the CDK of the scale.
+     */
+    scale?: MaybeAccessor<number | string | undefined>;
+    /** Emits when the user starts dragging the item. */
+    onStarted?: (event: DragStart<T>) => void;
+    /** Emits when the user has released a drag item, before any animations have started. */
+    onReleased?: (event: DragRelease<T>) => void;
+    /** Emits when the user stops dragging an item in the container. */
+    onEnded?: (event: DragEnd<T>) => void;
+    /** Emits when the user has moved the item into a new container. */
+    onEntered?: (event: DragEnter<any, T>) => void;
+    /** Emits when the user removes the item its container by dragging it into another container. */
+    onExited?: (event: DragExit<any, T>) => void;
+    /** Emits when the user drops the item inside a container. */
+    onDropped?: (event: DragDrop<any, any, T>) => void;
+    /**
+     * Emits as the user is dragging the item. Use with caution,
+     * because this event will fire for every pixel that the user has dragged.
+     */
+    onMoved?: (event: DragMove<T>) => void;
+}
+/** Options a drag instance is created with (component props + render context). */
+export interface DragSetup<T = any> {
+    inputs?: DragInputs<T>;
+    /** `DragDropConfigContext` value where the `<Drag>` rendered. */
+    config?: DragDropConfig | null;
+    /** `DirectionalityContext` value where the `<Drag>` rendered (else the document's). */
+    dir?: Directionality | null;
+    /**
+     * Rivet: the `<Drag>` element's `ref()`. The instance is destroyed once it lets go of the element: a client unmount
+     * (`bindRef`'s cleanup) or, on a resumed page, the end of the server element's region (a row a `For` drops, a
+     * re-created region: the revived ref resets).
+     */
+    element?: () => HTMLElement | undefined;
+}
+/** Element that can be moved inside a `DropList` container (Angular `CdkDrag`). */
+export declare class DragInstance<T = any> {
+    /** The `<Drag>` element. */
+    readonly element: HTMLElement;
+    /** Droppable container that the draggable is a part of. */
+    dropContainer: DropListInstance | null;
+    /** Reference to the underlying drag instance. */
+    _dragRef: DragRef<DragInstance<T>>;
+    /**
+     * Emits as the user is dragging the item. Use with caution,
+     * because this event will fire for every pixel that the user has dragged.
+     * (Angular `cdkDragMoved` observable; the `onMoved` prop is its output binding.)
+     */
+    readonly moved: Stream<DragMove<T>>;
+    private _inputs;
+    private _config;
+    private _dir;
+    private _dragDropRegistry;
+    private _destroyed;
+    private _disposeSync;
+    private _disposeRelease;
+    private _containerBeforeStarted;
+    private _movedSubscription;
+    private _handles;
+    private _previewView;
+    private _placeholderView;
+    constructor(element: HTMLElement, setup?: DragSetup<T>);
+    /** Arbitrary data to attach to this drag instance. */
+    get data(): T;
+    /** Locks the position of the dragged element along the specified axis. */
+    get lockAxis(): DragAxis | null;
+    /** Selector of an alternate root element. */
+    get rootElementSelector(): string | undefined;
+    /** Element (or selector) the draggable's position is constrained to. */
+    get boundaryElement(): string | ElementLike | null | undefined;
+    /** Delay before dragging starts. */
+    get dragStartDelay(): DragStartDelay | string;
+    /** Position of a standalone drag item. */
+    get freeDragPosition(): Point | undefined;
+    /** Whether starting to drag this element is disabled. */
+    get disabled(): boolean;
+    private get _ownDisabled();
+    /** Position constraint function. */
+    get constrainPosition(): DragConstrainPosition | undefined;
+    /** Class to be added to the preview element. */
+    get previewClass(): string | string[] | undefined;
+    /** Place into which the preview of the item will be inserted. */
+    get previewContainer(): PreviewContainer | undefined;
+    /** Scale of the drag element's parent. */
+    get scale(): number;
+    /**
+     * Returns the element that is being used as a placeholder
+     * while the current element is being dragged.
+     */
+    getPlaceholderElement(): HTMLElement;
+    /** Returns the root draggable element. */
+    getRootElement(): HTMLElement;
+    /** Resets a standalone drag item to its initial position. */
+    reset(): void;
+    /** Resets drag item to end of boundary element. */
+    resetToBoundary(): void;
+    /**
+     * Gets the pixel coordinates of the draggable outside of a drop container.
+     */
+    getFreeDragPosition(): Readonly<Point>;
+    /**
+     * Sets the current position in pixels the draggable outside of a drop container.
+     * @param value New position to be set.
+     */
+    setFreeDragPosition(value: Point): void;
+    /** Rivet: the props of a lazily created (bare) instance arrived with its own handler. */
+    _setInputs(setup: DragSetup<T>): void;
+    /**
+     * Rivet: destroy the instance once `element` (the `<Drag>`'s `ref()`, `DragSetup.element`) stops holding this
+     * element (Angular `ngOnDestroy`). A server-rendered `<Drag>` runs no component code on a resumed page, so its lazily
+     * created instance had no destroy hook: a row a resumed `For` dropped stayed in the registry (`_dragInstances`, the
+     * document `touchmove` listener), its list's items and its sync effects. The resume runtime resets a revived ref when
+     * the region of its server element dies; client renders reset it on unmount (`bindRef`), like `drag.tsx`'s cleanup.
+     * False: destroyed (the element already left).
+     */
+    _releaseWith(element: (() => HTMLElement | undefined) | undefined): boolean;
+    /** Rivet: sync what the DOM holds (handles, container state) before the ref sees a pointer down. */
+    _beforePointerDown(): void;
+    /** Angular `ngOnDestroy`. */
+    destroy(): void;
+    private _handlesSynced;
+    /** Re-collects the handles below the element (Angular: `_handles` + `_stateChanges`). */
+    _syncHandles(): void;
+    /** The handles of the drag item (Angular `_handles`). */
+    get _handleInstances(): readonly DragHandleInstance[];
+    /** Syncs the root element with the `DragRef`. */
+    private _updateRootElement;
+    /** Gets the boundary element, based on the `boundaryElement` value. */
+    private _getBoundaryElement;
+    /** The preview / placeholder `<template>` of this drag item (the last one wins, like Angular). */
+    private _template;
+    /** Syncs the inputs of the Drag with the options of the underlying DragRef. */
+    private _syncInputs;
+    /** Handles the events from the underlying `DragRef`. */
+    private _handleEvents;
+    /** `cdkDragMoved` (only observed while there is a listener, like Angular's lazy Observable). */
+    private _subscribeMoved;
+    /** Rivet: signal inputs Angular re-syncs on change (`ngOnChanges`, the `disabled` setter). */
+    private _syncReactiveInputs;
+    /** The server-rendered `transform` of `freeDragPosition` is handed over to the ref. */
+    private _rootTransformRendered;
+    /** Host classes (Angular host bindings). */
+    _syncHostClasses(): void;
+    private _toggleClass;
+}