@vuu-ui/grid-layout 4.0.0-alpha.1

package/src/useGridSplitterResizing.js

@@ -0,0 +1,262 @@
+import { useCallback, useEffect, useRef } from "react";
+import { classNameLayoutItem, getGridLayoutItem, getGridSplitter } from "./grid-dom-utils.js";
+import { adjustDistance, getTrackType } from "./grid-layout-utils.js";
+import { DEFAULT_MIN_GRID_ITEM_SIZE } from "./GridModel.js";
+import { queryClosest } from "@vuu-ui/vuu-utils";
+import { throwForGridCommandFailure } from "./GridCommand.js";
+const useGridSplitterResizing = ({ gridController, gridLayoutModel: layoutModel, gridModel, onClick: onClickProp, rowResizeDistribution })=>{
+    const resizingState = useRef(void 0);
+    const splitterRef = useRef(void 0);
+    const transactionRef = useRef(void 0);
+    const getResizeAllowance = useCallback((gridLayout, ids, orientation)=>{
+        const dimension = "horizontal" === orientation ? "width" : "height";
+        const minimum = "horizontal" === orientation ? "minWidth" : "minHeight";
+        return Math.min(...ids.map((id)=>{
+            const item = gridModel.getChildItem(id, true);
+            const element = gridLayout.querySelector(`#${CSS.escape(id)}`);
+            if (!element) throw Error(`[useGridSplitterResizing] GridItem #${id} not found in #${gridModel.id}`);
+            const size = element.getBoundingClientRect()[dimension];
+            return Math.max(0, size - (item[minimum] ?? DEFAULT_MIN_GRID_ITEM_SIZE));
+        }));
+    }, [
+        gridModel
+    ]);
+    const getProportionalTrackGroups = useCallback((splitter)=>{
+        const indicesFor = (ids)=>{
+            const items = ids.map((id)=>gridModel.getChildItem(id, true));
+            const start = Math.min(...items.map(({ row })=>row.start)) - 1;
+            const end = Math.max(...items.map(({ row })=>row.end)) - 1;
+            return Array.from({
+                length: end - start
+            }, (_, index)=>start + index);
+        };
+        return {
+            after: indicesFor(splitter.resizedChildItems.after),
+            before: indicesFor(splitter.resizedChildItems.before)
+        };
+    }, [
+        gridModel
+    ]);
+    const canResizeGroupsProportionally = useCallback(({ after, before })=>{
+        const allTrackIndices = before.concat(after);
+        return gridModel.childItems.every((item)=>{
+            const itemTrackIndices = Array.from({
+                length: item.row.end - item.row.start
+            }, (_, index)=>item.row.start - 1 + index);
+            const crossesBoundary = before.some((index)=>itemTrackIndices.includes(index)) && after.some((index)=>itemTrackIndices.includes(index));
+            return !crossesBoundary || allTrackIndices.every((index)=>itemTrackIndices.includes(index));
+        });
+    }, [
+        gridModel
+    ]);
+    const getProportionalTrackConstraints = useCallback((trackIndices, oppositeTrackIndices)=>{
+        gridModel.tracks.measure("row");
+        const tracks = gridModel.tracks.getTracks("row");
+        const groupTrackSet = new Set(trackIndices);
+        const firstTrack = Math.min(...trackIndices);
+        const lastTrack = Math.max(...trackIndices);
+        const constraints = [];
+        for (const item of gridModel.childItems){
+            if (item.stackId || item.row.end - 2 < firstTrack || item.row.start - 1 > lastTrack) continue;
+            const itemTrackIndices = Array.from({
+                length: item.row.end - item.row.start
+            }, (_, index)=>item.row.start - 1 + index);
+            if (trackIndices.concat(oppositeTrackIndices).every((index)=>itemTrackIndices.includes(index))) continue;
+            const overlappingTrackIndices = itemTrackIndices.filter((index)=>groupTrackSet.has(index));
+            const externalSize = itemTrackIndices.filter((index)=>!groupTrackSet.has(index)).reduce((total, index)=>total + tracks[index].numericValue, 0);
+            const requiredGroupSize = Math.max(0, (item.minHeight ?? DEFAULT_MIN_GRID_ITEM_SIZE) - externalSize);
+            if (requiredGroupSize > 0) constraints.push({
+                minimum: requiredGroupSize,
+                trackIndices: overlappingTrackIndices
+            });
+        }
+        return constraints;
+    }, [
+        gridModel
+    ]);
+    const createNewTrackForResize = useCallback((moveBy)=>{
+        const resizeOperation = moveBy < 0 ? "contract" : "expand";
+        const { current: state } = resizingState;
+        if (state) {
+            const { splitter } = state;
+            const trackType = getTrackType(splitter);
+            const [_, resizeTrackIndex] = splitter.resizedGridTracks;
+            layoutModel.addTrackForResize(trackType, Math.abs(moveBy), resizeOperation, resizeTrackIndex, state);
+            if ("contract" === resizeOperation) {
+                splitter.resizedGridTracks[1] += 1;
+                splitter.resizedGridTracks[0] += 1;
+            }
+            state.resizeTrackIsShared = false;
+        }
+    }, [
+        layoutModel
+    ]);
+    const removeTrack = useCallback((moveBy, resizeOperation)=>{
+        const { current: state } = resizingState;
+        let restoredDistance = 0;
+        if (state) {
+            const { resizeTrackIsShared, splitter } = state;
+            const [contraTrackIndex, resizeTrackIndex] = splitter.resizedGridTracks;
+            const trackType = getTrackType(splitter);
+            const targetTrack = "expand" === resizeOperation ? contraTrackIndex : resizeTrackIndex;
+            const currentTracks = gridModel.tracks.getTracks(trackType);
+            restoredDistance = currentTracks[targetTrack].numericValue;
+            const assignDirection = resizeTrackIsShared ? "expand" === resizeOperation ? "bwd" : "fwd" : "expand" === resizeOperation ? "fwd" : "bwd";
+            gridModel.removeGridTrack(trackType, targetTrack, assignDirection);
+            state.resizeTrackIsShared = true;
+            if ("expand" === resizeOperation) {
+                splitter.resizedGridTracks[1] -= 1;
+                splitter.resizedGridTracks[0] -= 1;
+            }
+            const adjustedDistance = adjustDistance(moveBy, restoredDistance);
+            if (0 !== adjustedDistance && resizeOperation) createNewTrackForResize(adjustedDistance);
+        }
+    }, [
+        gridModel,
+        createNewTrackForResize
+    ]);
+    const moveSplitter = useCallback((moveBy)=>{
+        const { current: state } = resizingState;
+        const directionOfTravel = moveBy < 0 ? "bwd" : "fwd";
+        if (state) {
+            if (state.proportionalTrackGroups) {
+                state.proportionalMoveBy = (state.proportionalMoveBy ?? 0) + moveBy;
+                gridModel.tracks.resizeGroupsProportionally("row", state.proportionalTrackGroups.before, state.proportionalTrackGroups.after, state.proportionalMoveBy, state.proportionalTrackConstraints?.before, state.proportionalTrackConstraints?.after, state.proportionalInitialTrackSizes);
+                return;
+            }
+            const { splitter } = state;
+            const [contraTrackIndex, resizeTrackIndex] = splitter.resizedGridTracks;
+            const trackType = "vertical" === splitter.orientation ? "row" : "column";
+            const tracks = gridModel.tracks.getTracks(trackType);
+            const reducedTrack = "fwd" === directionOfTravel ? tracks[contraTrackIndex] : tracks[resizeTrackIndex];
+            if (reducedTrack.isFraction) gridModel.tracks.measure(trackType);
+            if (!reducedTrack.isFraction && reducedTrack.numericValue - Math.abs(moveBy) <= 0) "fwd" === directionOfTravel ? removeTrack(moveBy, "expand") : removeTrack(moveBy, "contract");
+            else gridModel.tracks.resizeBy(trackType, resizeTrackIndex, contraTrackIndex, moveBy);
+        }
+    }, [
+        gridModel,
+        removeTrack
+    ]);
+    const mouseMove = useCallback(({ clientX, clientY })=>{
+        const { current: state } = resizingState;
+        if (state) {
+            const { mousePos, resizeTrackIsShared, splitter } = state;
+            const requestedMousePos = "vertical" === splitter.orientation ? clientY : clientX;
+            const newMousePos = Math.min(state.maxMousePos, Math.max(state.minMousePos, requestedMousePos));
+            if (newMousePos !== mousePos) {
+                const moveBy = mousePos - newMousePos;
+                state.mousePos = newMousePos;
+                if (0 !== moveBy) {
+                    if (resizeTrackIsShared) createNewTrackForResize(moveBy);
+                    moveSplitter(moveBy);
+                    const transaction = transactionRef.current;
+                    if (transaction) throwForGridCommandFailure(transaction.dispatch({
+                        type: "regenerate-placeholders"
+                    }));
+                }
+            }
+        }
+    }, [
+        createNewTrackForResize,
+        moveSplitter
+    ]);
+    const mouseUp = useCallback(()=>{
+        document.removeEventListener("mousemove", mouseMove);
+        document.removeEventListener("mouseup", mouseUp);
+        if (splitterRef.current) {
+            splitterRef.current.classList.remove("vuuGridSplitter-active");
+            splitterRef.current = void 0;
+        }
+        const transaction = transactionRef.current;
+        if (transaction) {
+            const result = transaction.commit();
+            if (!result.ok) throw Error(result.error.message);
+            transactionRef.current = void 0;
+        }
+        resizingState.current = void 0;
+    }, [
+        mouseMove
+    ]);
+    const onMouseDown = useCallback((e)=>{
+        const splitterElement = getGridSplitter(e.target);
+        if (null === splitterElement) return;
+        const gridLayout = queryClosest(splitterElement, ".vuuGridLayout", true);
+        if (gridLayout.id === gridModel.id) {
+            e.preventDefault();
+            const transactionResult = gridController.beginTransaction("resize");
+            if (!transactionResult.ok) throw Error(transactionResult.error.message);
+            transactionRef.current = transactionResult.transaction;
+            const splitter = layoutModel.getSplitterById(splitterElement.id);
+            const resizeTrackIsShared = layoutModel.isResizeTrackShared(splitter);
+            const candidateTrackGroups = "proportional" !== rowResizeDistribution || "vertical" !== splitter.orientation || resizeTrackIsShared ? void 0 : getProportionalTrackGroups(splitter);
+            const proportionalTrackGroups = candidateTrackGroups && canResizeGroupsProportionally(candidateTrackGroups) ? candidateTrackGroups : void 0;
+            const proportionalTrackConstraints = proportionalTrackGroups ? {
+                after: getProportionalTrackConstraints(proportionalTrackGroups.after, proportionalTrackGroups.before),
+                before: getProportionalTrackConstraints(proportionalTrackGroups.before, proportionalTrackGroups.after)
+            } : void 0;
+            const mousePos = "horizontal" === splitter.ariaOrientation ? e.clientY : e.clientX;
+            const beforeAllowance = proportionalTrackGroups ? gridModel.tracks.getProportionalResizeAllowance("row", proportionalTrackGroups.before, proportionalTrackConstraints?.before ?? []) : getResizeAllowance(gridLayout, splitter.resizedChildItems.before, splitter.orientation);
+            const afterAllowance = proportionalTrackGroups ? gridModel.tracks.getProportionalResizeAllowance("row", proportionalTrackGroups.after, proportionalTrackConstraints?.after ?? []) : getResizeAllowance(gridLayout, splitter.resizedChildItems.after, splitter.orientation);
+            resizingState.current = {
+                maxMousePos: mousePos + afterAllowance,
+                minMousePos: mousePos - beforeAllowance,
+                mousePos,
+                proportionalTrackConstraints,
+                proportionalTrackGroups,
+                proportionalInitialTrackSizes: proportionalTrackGroups ? gridModel.tracks.getTracks("row").map((track)=>track.numericValue) : void 0,
+                proportionalMoveBy: proportionalTrackGroups ? 0 : void 0,
+                resizeTrackIsShared,
+                splitter
+            };
+            document.addEventListener("mousemove", mouseMove);
+            document.addEventListener("mouseup", mouseUp);
+            splitterElement.classList.add("vuuGridSplitter-active");
+            splitterRef.current = splitterElement;
+        }
+    }, [
+        canResizeGroupsProportionally,
+        getProportionalTrackGroups,
+        getProportionalTrackConstraints,
+        getResizeAllowance,
+        gridController,
+        gridModel,
+        layoutModel,
+        mouseMove,
+        mouseUp,
+        rowResizeDistribution
+    ]);
+    useEffect(()=>()=>{
+            document.removeEventListener("mousemove", mouseMove);
+            document.removeEventListener("mouseup", mouseUp);
+            const transaction = transactionRef.current;
+            if (transaction) {
+                transaction.rollback();
+                transactionRef.current = void 0;
+            }
+        }, [
+        mouseMove,
+        mouseUp
+    ]);
+    const selectedRef = useRef(void 0);
+    const clickHandler = useCallback((e)=>{
+        const gridLayoutItem = getGridLayoutItem(e.target);
+        if (gridLayoutItem) {
+            const { left, top } = gridLayoutItem.getBoundingClientRect();
+            if (e.clientY < top || e.clientX < left) return;
+            if (selectedRef.current) {
+                const el = document.getElementById(selectedRef.current);
+                el.classList.remove(`${classNameLayoutItem}-active`);
+            }
+            selectedRef.current = gridLayoutItem.id;
+            gridLayoutItem.classList.add(`${classNameLayoutItem}-active`);
+        }
+        onClickProp?.(e);
+    }, [
+        onClickProp
+    ]);
+    return {
+        onClick: clickHandler,
+        onMouseDown
+    };
+};
+export { useGridSplitterResizing };

package/src/useNotDropTarget.js

@@ -0,0 +1,2 @@
+const useNotDropTarget = ()=>({});
+export { useNotDropTarget };

package/types/AddTabDialog.d.ts

@@ -0,0 +1,5 @@
+export declare const AddTabDialog: ({ open, onConfirm, onCancel, }: {
+    open?: boolean;
+    onConfirm: (value: string) => void;
+    onCancel: () => void;
+}) => import("react/jsx-runtime").JSX.Element;

package/types/GridCommand.d.ts

@@ -0,0 +1,146 @@
+import { type GridLayoutSplitDirection } from "@vuu-ui/vuu-utils";
+import { GridLayoutModel, type GridItemRemoveReason } from "./GridLayoutModel";
+import { type GridModel, type TrackSize, type TrackType } from "./GridModel";
+import type { GridItemId, GridItemResizeable, GridSpanSnapshot, StackId } from "./GridSnapshot";
+export interface GridCommandItem {
+    readonly column: GridSpanSnapshot;
+    readonly contentVisible?: boolean;
+    readonly dropTarget?: boolean | string;
+    readonly header?: boolean;
+    readonly id: GridItemId;
+    readonly minHeight?: number;
+    readonly minWidth?: number;
+    readonly resizeable?: GridItemResizeable;
+    readonly row: GridSpanSnapshot;
+    readonly title?: string;
+}
+export interface GridCommandResizeConstraint {
+    readonly minimum: number;
+    readonly trackIndices: readonly number[];
+}
+export type GridTrackResize = {
+    readonly contraTrackIndex: number;
+    readonly delta: number;
+    readonly distribution: "adjacent";
+    readonly measuredSizes?: readonly number[];
+    readonly resizedTrackIndex: number;
+    readonly track: TrackType;
+} | {
+    readonly afterConstraints?: readonly GridCommandResizeConstraint[];
+    readonly afterTrackIndices: readonly number[];
+    readonly beforeConstraints?: readonly GridCommandResizeConstraint[];
+    readonly beforeTrackIndices: readonly number[];
+    readonly delta: number;
+    readonly distribution: "proportional";
+    readonly initialSizes?: readonly number[];
+    readonly measuredSizes?: readonly number[];
+    readonly track: TrackType;
+};
+export type GridCommand = {
+    readonly item: GridCommandItem;
+    readonly type: "add-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly position: GridLayoutSplitDirection;
+    readonly targetId: GridItemId;
+    readonly type: "move-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly targetId: GridItemId;
+    readonly type: "replace-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly stackId: StackId;
+    readonly targetId: GridItemId;
+    readonly type: "replace-stack-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly reason: GridItemRemoveReason;
+    readonly type: "remove-item";
+} | {
+    readonly index: number;
+    readonly size: TrackSize;
+    readonly track: TrackType;
+    readonly type: "resize-track";
+} | ({
+    readonly type: "resize-tracks";
+} & GridTrackResize) | {
+    readonly itemId: GridItemId;
+    readonly selectedItemId?: GridItemId;
+    readonly targetId: GridItemId;
+    readonly type: "create-stack";
+} | {
+    readonly item: GridCommandItem;
+    readonly position?: "after" | "before";
+    readonly stackId: StackId;
+    readonly targetItemId?: GridItemId;
+    readonly type: "add-stack-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly stackId: StackId;
+    readonly type: "remove-stack-item";
+} | {
+    readonly fromStackId?: StackId;
+    readonly itemId: GridItemId;
+    readonly position?: "after" | "before";
+    readonly stackId: StackId;
+    readonly targetItemId?: GridItemId;
+    readonly type: "move-item-to-stack";
+} | {
+    readonly itemId: GridItemId;
+    readonly position: GridLayoutSplitDirection;
+    readonly stackId: StackId;
+    readonly targetId: GridItemId;
+    readonly type: "move-stack-item-to-grid";
+} | {
+    readonly itemId: GridItemId;
+    readonly stackId: StackId;
+    readonly type: "select-stack-item";
+} | {
+    readonly activate?: boolean;
+    readonly itemId: GridItemId;
+    readonly position: "after" | "before";
+    readonly stackId: StackId;
+    readonly targetItemId: GridItemId;
+    readonly type: "reorder-stack-item";
+} | {
+    readonly itemId: GridItemId;
+    readonly title: string;
+    readonly type: "rename-item";
+} | {
+    readonly type: "regenerate-placeholders";
+};
+export type GridCommandErrorCode = "DUPLICATE_ITEM_ID" | "INVALID_ITEM" | "INVALID_TARGET" | "ITEM_NOT_FOUND" | "MEASUREMENT_REQUIRED" | "NON_RESIZABLE" | "STACK_NOT_FOUND" | "TAB_NOT_FOUND" | "TRACK_NOT_FOUND" | "TRANSACTION_ACTIVE" | "TRANSACTION_CLOSED" | "UNSUPPORTED_ACTION";
+export interface GridCommandError {
+    readonly code: GridCommandErrorCode;
+    readonly message: string;
+}
+export type GridCommandResult = {
+    readonly command: GridCommand["type"];
+    readonly ok: true;
+} | {
+    readonly command: GridCommand["type"];
+    readonly error: GridCommandError;
+    readonly ok: false;
+};
+export declare class GridCommandExecutionError extends Error {
+    readonly code: GridCommandErrorCode;
+    constructor({ code, message }: GridCommandError);
+}
+export declare class LegacyGridCommandExecutor {
+    private readonly gridModel;
+    private readonly gridLayoutModel;
+    constructor(gridModel: GridModel, gridLayoutModel?: GridLayoutModel);
+    execute(command: GridCommand): GridCommandResult;
+    private removeItem;
+    private applyMeasurements;
+    private validateResizeCommand;
+    private requireItem;
+    private requireStack;
+    private requireTab;
+    private requireTracks;
+    private validateNewItem;
+    private validatePair;
+    private rejectStackMember;
+}
+export declare const throwForGridCommandFailure: (result: GridCommandResult) => void;

package/types/GridComponentSettings.d.ts

@@ -0,0 +1,71 @@
+import type { ReactElement } from "react";
+import type { JsonValue } from "./json-value";
+export interface GridSettingsCodecIssue {
+    readonly code: string;
+    readonly message: string;
+    readonly path: string;
+}
+export type GridSettingsCodecResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly error: GridSettingsCodecIssue;
+    readonly ok: false;
+};
+export interface GridComponentSettingsCodec<T> {
+    readonly decode: (value: JsonValue) => GridSettingsCodecResult<T>;
+    readonly encode: (settings: T) => GridSettingsCodecResult<unknown>;
+    readonly isSettings: (value: unknown) => value is T;
+    readonly migrations?: Readonly<Record<number, (value: JsonValue) => GridSettingsCodecResult<unknown>>>;
+    readonly version: number;
+}
+export interface GridComponentSettingsInput {
+    readonly id: string;
+    readonly settings: unknown;
+    readonly type: string;
+}
+export interface EncodedGridComponentSettings {
+    readonly id: string;
+    readonly settings: JsonValue;
+    readonly type: string;
+    readonly version: number;
+}
+export interface DecodedGridComponentSettings {
+    readonly id: string;
+    readonly settings: unknown;
+    readonly type: string;
+    readonly version: number;
+}
+export type GridComponentSettingsErrorCode = "COMPONENT_DECODE_FAILED" | "COMPONENT_ENCODE_FAILED" | "COMPONENT_MIGRATION_FAILED" | "INVALID_COMPONENT_SETTINGS" | "UNKNOWN_COMPONENT_TYPE" | "UNSUPPORTED_COMPONENT_VERSION";
+export interface GridComponentSettingsError {
+    readonly code: GridComponentSettingsErrorCode;
+    readonly componentId: string;
+    readonly componentType: string;
+    readonly message: string;
+    readonly path: string;
+    readonly version?: number;
+}
+export type GridComponentSettingsResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly error: GridComponentSettingsError;
+    readonly ok: false;
+};
+export declare class GridComponentSettingsRegistry {
+    #private;
+    register<T>(type: string, codec: GridComponentSettingsCodec<T>): void;
+    encode(component: GridComponentSettingsInput): GridComponentSettingsResult<EncodedGridComponentSettings>;
+    decode(component: EncodedGridComponentSettings): GridComponentSettingsResult<DecodedGridComponentSettings>;
+}
+export type GridComponentRenderer<T> = (settings: T, componentId: string) => ReactElement;
+export declare class GridComponentRendererRegistry {
+    #private;
+    register<T>(type: string, isSettings: (value: unknown) => value is T, render: GridComponentRenderer<T>): void;
+    render(component: DecodedGridComponentSettings): ReactElement;
+}
+export declare class GridLayoutContentRegistry<T> {
+    #private;
+    entries(): ReadonlyMap<string, T>;
+    replace(components: readonly DecodedGridComponentSettings[], resolve: (component: DecodedGridComponentSettings) => T): void;
+}

package/types/GridController.d.ts

@@ -0,0 +1,50 @@
+import { LegacyGridCommandExecutor, type GridCommand, type GridCommandResult } from "./GridCommand";
+import type { GridModel } from "./GridModel";
+import type { GridSnapshot } from "./GridSnapshot";
+export type GridTransactionKind = "drag" | "resize";
+export type GridControllerListener = () => void;
+export type GridControllerErrorCode = "TRANSACTION_ACTIVE" | "TRANSACTION_CLOSED";
+export interface GridControllerError {
+    readonly code: GridControllerErrorCode;
+    readonly message: string;
+}
+export type GridTransactionStartResult = {
+    readonly ok: true;
+    readonly transaction: GridTransaction;
+} | {
+    readonly error: GridControllerError;
+    readonly ok: false;
+};
+export type GridTransactionCloseResult = {
+    readonly ok: true;
+    readonly snapshot: GridSnapshot;
+} | {
+    readonly error: GridControllerError;
+    readonly ok: false;
+};
+export interface GridTransaction {
+    readonly kind: GridTransactionKind;
+    commit(): GridTransactionCloseResult;
+    dispatch(command: GridCommand): GridCommandResult;
+    establishWorkingBaseline(commands: readonly GridCommand[]): GridCommandResult;
+    replace(commands: readonly GridCommand[]): GridCommandResult;
+    rollback(): GridTransactionCloseResult;
+    validateReplacement(commands: readonly GridCommand[]): GridCommandResult;
+}
+export interface GridCommittedTransition {
+    readonly commands: readonly GridCommand[];
+    readonly kind: "dispatch" | GridTransactionKind;
+    readonly previous: GridSnapshot;
+    readonly snapshot: GridSnapshot;
+}
+export type GridCommittedTransitionListener = (transition: GridCommittedTransition) => void;
+export declare class GridController {
+    #private;
+    private readonly gridModel;
+    constructor(gridModel: GridModel, revision?: number, executor?: LegacyGridCommandExecutor);
+    getSnapshot: () => GridSnapshot;
+    subscribe: (listener: GridControllerListener) => (() => void);
+    subscribeCommitted: (listener: GridCommittedTransitionListener) => (() => void);
+    dispatch(command: GridCommand): GridCommandResult;
+    beginTransaction(kind: GridTransactionKind): GridTransactionStartResult;
+}

package/types/GridDragCoordinator.d.ts

@@ -0,0 +1,80 @@
+import type { GridCommand, GridCommandItem } from "./GridCommand";
+import type { GridController, GridControllerError } from "./GridController";
+import type { GridId, GridItemId, StackId } from "./GridSnapshot";
+export type GridDragSource = {
+    readonly itemId: GridItemId;
+    readonly kind: "existing-item";
+    readonly sourceGridId: GridId;
+} | {
+    readonly itemId: GridItemId;
+    readonly kind: "stack-member";
+    readonly selected: boolean;
+    readonly sourceGridId: GridId;
+    readonly stackId: StackId;
+} | {
+    readonly item: GridCommandItem;
+    readonly kind: "palette-template";
+    readonly templateId: string;
+};
+export type GridDropIntent = {
+    readonly kind: "replace";
+} | {
+    readonly kind: "split";
+    readonly position: "east" | "north" | "south" | "west";
+} | {
+    readonly kind: "create-stack";
+} | {
+    readonly kind: "stack";
+    readonly position?: "after" | "before";
+    readonly targetItemId?: GridItemId;
+};
+export interface GridDropTarget {
+    readonly gridId: GridId;
+    readonly intent: GridDropIntent;
+    readonly targetId: GridItemId | StackId;
+}
+export type GridDragCoordinatorState = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "dragging";
+    readonly source: GridDragSource;
+} | {
+    readonly phase: "previewing";
+    readonly plan: GridDropPlan;
+    readonly source: GridDragSource;
+    readonly target: GridDropTarget;
+} | {
+    readonly phase: "committed" | "cancelled";
+    readonly source: GridDragSource;
+};
+export type GridDropPlan = {
+    readonly commands: readonly GridCommand[];
+    readonly source: GridDragSource;
+    readonly target: GridDropTarget;
+};
+export type GridDragCoordinatorErrorCode = "CROSS_GRID_DRAG" | "INVALID_TRANSITION" | "TRANSACTION_FAILURE" | "UNSUPPORTED_DROP";
+export interface GridDragCoordinatorError {
+    readonly code: GridDragCoordinatorErrorCode;
+    readonly message: string;
+}
+export type GridDragCoordinatorResult = {
+    readonly ok: true;
+    readonly state: GridDragCoordinatorState;
+} | {
+    readonly error: GridDragCoordinatorError | GridControllerError;
+    readonly ok: false;
+};
+export declare const createGridDropPlan: (source: GridDragSource, target: GridDropTarget) => GridDropPlan | GridDragCoordinatorError;
+export declare class GridDragCoordinator {
+    #private;
+    readonly gridId: GridId;
+    private readonly controller;
+    constructor(gridId: GridId, controller: GridController);
+    get state(): GridDragCoordinatorState;
+    begin(source: GridDragSource): GridDragCoordinatorResult;
+    preview(target: GridDropTarget): GridDragCoordinatorResult;
+    commit(): GridDragCoordinatorResult;
+    clearPreview(): GridDragCoordinatorResult;
+    cancel(): GridDragCoordinatorResult;
+    dispose(): void;
+}