Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · dragAndDrop

Published foldkit-ui API declarations for dragAndDrop.

./dragAndDrop

@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit-ui/dragAndDrop'

Exported declarations

draggable

Returns attributes the parent attaches to a draggable element. Handles pointer-down, keyboard activation, and ARIA.

draggable: <ParentMessage>(config: DraggableConfig<ParentMessage>, h: HtmlBuilder<ParentMessage>) => ReadonlyArray<Attribute<ParentMessage>>

DraggableConfig

Configuration for creating draggable attributes with `draggable`.

export type DraggableConfig<ParentMessage> = Readonly<{
    model: Model;
    toParentMessage: (message: DraggableMessage) => ParentMessage;
    itemId: string;
    containerId: string;
    index: number;
}>;

DraggableMessage

Messages the draggable view helper can dispatch.

export type DraggableMessage = typeof Message.PressedDraggable.Type | typeof Message.ActivatedKeyboardDrag.Type;

DragState

Schema for the current pointer or keyboard drag phase.

DragState: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
    readonly Idle: {};
    readonly Pending: {
        itemId: Schema.String;
        containerId: Schema.String;
        index: Schema.Number;
        origin: Schema.Struct<{
            readonly screenX: Schema.Number;
            readonly screenY: Schema.Number;
        }>;
    };
    readonly Dragging: {
        itemId: Schema.String;
        sourceContainerId: Schema.String;
        sourceIndex: Schema.Number;
        origin: Schema.Struct<{
            readonly screenX: Schema.Number;
            readonly screenY: Schema.Number;
        }>;
        current: Schema.Struct<{
            readonly clientX: Schema.Number;
            readonly clientY: Schema.Number;
        }>;
        maybeDropTarget: Schema.Option<Schema.Struct<{
            readonly containerId: Schema.String;
            readonly index: Schema.Number;
        }>>;
    };
    readonly KeyboardDragging: {
        itemId: Schema.String;
        sourceContainerId: Schema.String;
        sourceIndex: Schema.Number;
        targetContainerId: Schema.String;
        targetIndex: Schema.Number;
    };
}>

DragState

Current pointer or keyboard drag phase.

export type DragState = typeof DragState.Type;

droppable

Returns attributes the parent attaches to a droppable container element. Handler-free, so the bundle is built with `inertHtml` and spreads into any Message universe's attribute array.

droppable: (containerId: string, label?: string) => ReadonlyArray<Attribute<never>>

FocusItem

Focuses a draggable item by ID after a keyboard move, drop, or cancel.

FocusItem: Command.CommandDefinitionWithArgs<"FocusItem", {
    itemId: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedFocusItem";
}, never, never>>

ghostStyle

Returns positioning styles for the ghost element, or None when not dragging with a pointer.

ghostStyle: (model: Model) => Option.Option<Record<string, string>>

init

Creates an initial drag-and-drop model. Starts idle with Vertical orientation and a 5px activation threshold by default.

init: (config: InitConfig) => Model

InitConfig

export type InitConfig = Readonly<{
    id: string;
    orientation?: 'Horizontal' | 'Vertical';
    activationThreshold?: number;
}>;

isDragging

Returns true when the component is actively dragging (pointer or keyboard).

isDragging: ({ dragState: { _tag } }: Model) => boolean

maybeDraggedItemId

Returns the ID of the item currently being dragged or pending, if any.

maybeDraggedItemId: (model: Model) => Option.Option<string>

maybeDropTarget

Returns the current drop target, if any. Populated during pointer drag (from collision detection) and keyboard drag (from resolved position).

maybeDropTarget: (model: Model) => Option.Option<typeof DropTarget.Type>

Message

export type Message = typeof Message.Type;

Message

Union of all messages the drag-and-drop component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly PressedDraggable: {
        itemId: Schema.String;
        containerId: Schema.String;
        index: Schema.Number;
        screenX: Schema.Number;
        screenY: Schema.Number;
    };
    readonly MovedPointer: {
        screenX: Schema.Number;
        screenY: Schema.Number;
        clientX: Schema.Number;
        clientY: Schema.Number;
        maybeDropTarget: Schema.Option<Schema.Struct<{
            readonly containerId: Schema.String;
            readonly index: Schema.Number;
        }>>;
    };
    readonly ReleasedPointer: {};
    readonly CancelledDrag: {};
    readonly ActivatedKeyboardDrag: {
        itemId: Schema.String;
        containerId: Schema.String;
        index: Schema.Number;
    };
    readonly CompletedResolveKeyboardMove: {
        targetContainerId: Schema.String;
        targetIndex: Schema.Number;
    };
    readonly ConfirmedKeyboardDrop: {};
    readonly PressedArrowKey: {
        direction: Schema.Literals<readonly ["Up", "Down", "Left", "Right", "NextContainer", "PreviousContainer"]>;
    };
    readonly AdvancedAutoScrollFrame: {};
    readonly CompletedFocusItem: {};
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the drag-and-drop component's state, tracking its unique ID, orientation, and current drag phase.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly orientation: Schema.Literals<readonly ["Horizontal", "Vertical"]>;
    readonly activationThreshold: Schema.Number;
    readonly dragState: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Idle: {};
        readonly Pending: {
            itemId: Schema.String;
            containerId: Schema.String;
            index: Schema.Number;
            origin: Schema.Struct<{
                readonly screenX: Schema.Number;
                readonly screenY: Schema.Number;
            }>;
        };
        readonly Dragging: {
            itemId: Schema.String;
            sourceContainerId: Schema.String;
            sourceIndex: Schema.Number;
            origin: Schema.Struct<{
                readonly screenX: Schema.Number;
                readonly screenY: Schema.Number;
            }>;
            current: Schema.Struct<{
                readonly clientX: Schema.Number;
                readonly clientY: Schema.Number;
            }>;
            maybeDropTarget: Schema.Option<Schema.Struct<{
                readonly containerId: Schema.String;
                readonly index: Schema.Number;
            }>>;
        };
        readonly KeyboardDragging: {
            itemId: Schema.String;
            sourceContainerId: Schema.String;
            sourceIndex: Schema.Number;
            targetContainerId: Schema.String;
            targetIndex: Schema.Number;
        };
    }>;
}>

OutMessage

export type OutMessage = typeof OutMessage.Type;

OutMessage

Union of all out-messages the drag-and-drop component can emit to its parent.

OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Reordered: {
        itemId: Schema.String;
        fromContainerId: Schema.String;
        fromIndex: Schema.Number;
        toContainerId: Schema.String;
        toIndex: Schema.Number;
    };
    readonly Cancelled: {};
}>

ResolveKeyboardMove

Resolves the next keyboard drag position by querying the DOM for adjacent sortable items and containers.

ResolveKeyboardMove: Command.CommandDefinitionWithArgs<"ResolveKeyboardMove", {
    itemId: Schema.String;
    currentContainerId: Schema.String;
    currentIndex: Schema.Number;
    direction: Schema.Literals<readonly ["Up", "Down", "Left", "Right", "NextContainer", "PreviousContainer"]>;
}, Effect.Effect<{
    readonly _tag: "CompletedResolveKeyboardMove";
    readonly targetContainerId: string;
    readonly targetIndex: number;
}, never, never>>

sortable

Returns attributes the parent attaches to a sortable item element. Typically combined with `draggable`. Handler-free, so the bundle is built with `inertHtml` and spreads into any Message universe's attribute array.

sortable: (itemId: string) => ReadonlyArray<Attribute<never>>

subscriptions

Document-level subscriptions for pointer and keyboard events during drag operations.

subscriptions: {
    readonly documentPointer: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly orientation: "Horizontal" | "Vertical";
        readonly activationThreshold: number;
        readonly dragState: {
            readonly _tag: "Dragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
            readonly current: {
                readonly clientX: number;
                readonly clientY: number;
            };
            readonly maybeDropTarget: Option.Option<{
                readonly containerId: string;
                readonly index: number;
            }>;
        } | {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "KeyboardDragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly targetContainerId: string;
            readonly targetIndex: number;
        } | {
            readonly _tag: "Pending";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
        };
    }, {
        readonly _tag: "ActivatedKeyboardDrag";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
    } | {
        readonly _tag: "AdvancedAutoScrollFrame";
    } | {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "CompletedFocusItem";
    } | {
        readonly _tag: "CompletedResolveKeyboardMove";
        readonly targetContainerId: string;
        readonly targetIndex: number;
    } | {
        readonly _tag: "ConfirmedKeyboardDrop";
    } | {
        readonly _tag: "MovedPointer";
        readonly screenX: number;
        readonly screenY: number;
        readonly clientX: number;
        readonly clientY: number;
        readonly maybeDropTarget: Option.Option<{
            readonly containerId: string;
            readonly index: number;
        }>;
    } | {
        readonly _tag: "PressedArrowKey";
        readonly direction: "Down" | "Left" | "NextContainer" | "PreviousContainer" | "Right" | "Up";
    } | {
        readonly _tag: "PressedDraggable";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
        readonly screenX: number;
        readonly screenY: number;
    } | {
        readonly _tag: "ReleasedPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
        readonly orientation: "Horizontal" | "Vertical";
    }, never> & {
        readonly __subscription: never;
    };
    readonly documentEscape: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly orientation: "Horizontal" | "Vertical";
        readonly activationThreshold: number;
        readonly dragState: {
            readonly _tag: "Dragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
            readonly current: {
                readonly clientX: number;
                readonly clientY: number;
            };
            readonly maybeDropTarget: Option.Option<{
                readonly containerId: string;
                readonly index: number;
            }>;
        } | {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "KeyboardDragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly targetContainerId: string;
            readonly targetIndex: number;
        } | {
            readonly _tag: "Pending";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
        };
    }, {
        readonly _tag: "ActivatedKeyboardDrag";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
    } | {
        readonly _tag: "AdvancedAutoScrollFrame";
    } | {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "CompletedFocusItem";
    } | {
        readonly _tag: "CompletedResolveKeyboardMove";
        readonly targetContainerId: string;
        readonly targetIndex: number;
    } | {
        readonly _tag: "ConfirmedKeyboardDrop";
    } | {
        readonly _tag: "MovedPointer";
        readonly screenX: number;
        readonly screenY: number;
        readonly clientX: number;
        readonly clientY: number;
        readonly maybeDropTarget: Option.Option<{
            readonly containerId: string;
            readonly index: number;
        }>;
    } | {
        readonly _tag: "PressedArrowKey";
        readonly direction: "Down" | "Left" | "NextContainer" | "PreviousContainer" | "Right" | "Up";
    } | {
        readonly _tag: "PressedDraggable";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
        readonly screenX: number;
        readonly screenY: number;
    } | {
        readonly _tag: "ReleasedPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
    }, never> & {
        readonly __subscription: never;
    };
    readonly documentKeyboard: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly orientation: "Horizontal" | "Vertical";
        readonly activationThreshold: number;
        readonly dragState: {
            readonly _tag: "Dragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
            readonly current: {
                readonly clientX: number;
                readonly clientY: number;
            };
            readonly maybeDropTarget: Option.Option<{
                readonly containerId: string;
                readonly index: number;
            }>;
        } | {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "KeyboardDragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly targetContainerId: string;
            readonly targetIndex: number;
        } | {
            readonly _tag: "Pending";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
        };
    }, {
        readonly _tag: "ActivatedKeyboardDrag";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
    } | {
        readonly _tag: "AdvancedAutoScrollFrame";
    } | {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "CompletedFocusItem";
    } | {
        readonly _tag: "CompletedResolveKeyboardMove";
        readonly targetContainerId: string;
        readonly targetIndex: number;
    } | {
        readonly _tag: "ConfirmedKeyboardDrop";
    } | {
        readonly _tag: "MovedPointer";
        readonly screenX: number;
        readonly screenY: number;
        readonly clientX: number;
        readonly clientY: number;
        readonly maybeDropTarget: Option.Option<{
            readonly containerId: string;
            readonly index: number;
        }>;
    } | {
        readonly _tag: "PressedArrowKey";
        readonly direction: "Down" | "Left" | "NextContainer" | "PreviousContainer" | "Right" | "Up";
    } | {
        readonly _tag: "PressedDraggable";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
        readonly screenX: number;
        readonly screenY: number;
    } | {
        readonly _tag: "ReleasedPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
    }, never> & {
        readonly __subscription: never;
    };
    readonly autoScroll: {
        readonly dependenciesSchema: Schema.Schema<{
            readonly isDragging: boolean;
            readonly clientY: number;
        }> & {
            readonly fields: Schema.Struct.Fields;
        };
        readonly modelToDependencies: (model: {
            readonly id: string;
            readonly orientation: "Horizontal" | "Vertical";
            readonly activationThreshold: number;
            readonly dragState: {
                readonly _tag: "Dragging";
                readonly itemId: string;
                readonly sourceContainerId: string;
                readonly sourceIndex: number;
                readonly origin: {
                    readonly screenX: number;
                    readonly screenY: number;
                };
                readonly current: {
                    readonly clientX: number;
                    readonly clientY: number;
                };
                readonly maybeDropTarget: Option.Option<{
                    readonly containerId: string;
                    readonly index: number;
                }>;
            } | {
                readonly _tag: "Idle";
            } | {
                readonly _tag: "KeyboardDragging";
                readonly itemId: string;
                readonly sourceContainerId: string;
                readonly sourceIndex: number;
                readonly targetContainerId: string;
                readonly targetIndex: number;
            } | {
                readonly _tag: "Pending";
                readonly itemId: string;
                readonly containerId: string;
                readonly index: number;
                readonly origin: {
                    readonly screenX: number;
                    readonly screenY: number;
                };
            };
        }) => {
            readonly isDragging: boolean;
            readonly clientY: number;
        };
        readonly keepAliveEquivalence: Equivalence.Equivalence<{
            readonly isDragging: boolean;
            readonly clientY: number;
        }>;
        readonly dependenciesToStream: (dependencies: {
            readonly isDragging: boolean;
            readonly clientY: number;
        }, readDependencies: () => {
            readonly isDragging: boolean;
            readonly clientY: number;
        }) => Stream.Stream<{
            readonly _tag: "ActivatedKeyboardDrag";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
        } | {
            readonly _tag: "AdvancedAutoScrollFrame";
        } | {
            readonly _tag: "CancelledDrag";
        } | {
            readonly _tag: "CompletedFocusItem";
        } | {
            readonly _tag: "CompletedResolveKeyboardMove";
            readonly targetContainerId: string;
            readonly targetIndex: number;
        } | {
            readonly _tag: "ConfirmedKeyboardDrop";
        } | {
            readonly _tag: "MovedPointer";
            readonly screenX: number;
            readonly screenY: number;
            readonly clientX: number;
            readonly clientY: number;
            readonly maybeDropTarget: Option.Option<{
                readonly containerId: string;
                readonly index: number;
            }>;
        } | {
            readonly _tag: "PressedArrowKey";
            readonly direction: "Down" | "Left" | "NextContainer" | "PreviousContainer" | "Right" | "Up";
        } | {
            readonly _tag: "PressedDraggable";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
            readonly screenX: number;
            readonly screenY: number;
        } | {
            readonly _tag: "ReleasedPointer";
        }, never, never>;
    } & {
        readonly __subscription: never;
    };
}

update

Processes a drag-and-drop Message and returns the next Model, optional Commands, and an optional OutMessage for the parent.

update: (model: Model, message: Message) => Readonly<{
    model: {
        readonly id: string;
        readonly orientation: "Horizontal" | "Vertical";
        readonly activationThreshold: number;
        readonly dragState: {
            readonly _tag: "Dragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
            readonly current: {
                readonly clientX: number;
                readonly clientY: number;
            };
            readonly maybeDropTarget: Option.Option<{
                readonly containerId: string;
                readonly index: number;
            }>;
        } | {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "KeyboardDragging";
            readonly itemId: string;
            readonly sourceContainerId: string;
            readonly sourceIndex: number;
            readonly targetContainerId: string;
            readonly targetIndex: number;
        } | {
            readonly _tag: "Pending";
            readonly itemId: string;
            readonly containerId: string;
            readonly index: number;
            readonly origin: {
                readonly screenX: number;
                readonly screenY: number;
            };
        };
    };
    commands?: Update.Commands<{
        readonly _tag: "ActivatedKeyboardDrag";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
    } | {
        readonly _tag: "AdvancedAutoScrollFrame";
    } | {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "CompletedFocusItem";
    } | {
        readonly _tag: "CompletedResolveKeyboardMove";
        readonly targetContainerId: string;
        readonly targetIndex: number;
    } | {
        readonly _tag: "ConfirmedKeyboardDrop";
    } | {
        readonly _tag: "MovedPointer";
        readonly screenX: number;
        readonly screenY: number;
        readonly clientX: number;
        readonly clientY: number;
        readonly maybeDropTarget: Option.Option<{
            readonly containerId: string;
            readonly index: number;
        }>;
    } | {
        readonly _tag: "PressedArrowKey";
        readonly direction: "Down" | "Left" | "NextContainer" | "PreviousContainer" | "Right" | "Up";
    } | {
        readonly _tag: "PressedDraggable";
        readonly itemId: string;
        readonly containerId: string;
        readonly index: number;
        readonly screenX: number;
        readonly screenY: number;
    } | {
        readonly _tag: "ReleasedPointer";
    }, never>;
    outMessage?: {
        readonly _tag: "Cancelled";
    } | {
        readonly _tag: "Reordered";
        readonly itemId: string;
        readonly fromContainerId: string;
        readonly fromIndex: number;
        readonly toContainerId: string;
        readonly toIndex: number;
    };
}>