@witchcraft/layout 0.4.3 → 0.5.0

package/src/runtime/types/index.ts

@@ -246,18 +246,18 @@ const zCloseDeco = zBaseDeco.extend({
 export type CloseDeco = z.infer<typeof zCloseDeco>
 
 
-const zFrameDragDeco = zBaseDeco.extend({
+const zFrameDeco = zBaseDeco.extend({
 	id: z.uuid(),
 	type: z.literal("drop"),
 	position: zSide.or(z.enum(["center"]))
 })
 
-export type FrameDragDeco = z.infer<typeof zFrameDragDeco>
+export type FrameDeco = z.infer<typeof zFrameDeco>
 
 export const zDeco = z.union([
 	zSplitDeco,
 	zCloseDeco,
-	zFrameDragDeco
+	zFrameDeco
 ])
 
 export type Deco = z.infer<typeof zDeco>
@@ -287,7 +287,8 @@ export const LAYOUT_ERROR = enumFromArray([
 	"CANT_COLLAPSE_NOT_DOCKED",
 	"CANT_UNCOLLAPSE_NOT_COLLAPSED",
 	"NO_FILL_CANDIDATES",
-	"CANT_RESIZE_COLLAPSED_FRAME"
+	"CANT_RESIZE_COLLAPSED_FRAME",
+	"CANT_RESIZE_SINGLE_FRAME"
 ])
 
 export type LayoutError = EnumLike<typeof LAYOUT_ERROR>
@@ -330,19 +331,19 @@ export type LayoutErrorsInfo = {
 		frame: LayoutFrame
 	}
 	[LAYOUT_ERROR.CANT_REARRANGE_TO_SAME_RELATIVE_POSITION]: {
-		draggingFrameId: string
+		movingFrameId: string
 		hoveredFrameId: string
-		zoneSide: DragZone["side"]
+		zoneSide: Zone["side"]
 	}
 	[LAYOUT_ERROR.CANT_REARRANGE_WITH_DOCKED_EDGES]: {
-		draggingFrameId: string
+		movingFrameId: string
 		hoveredFrameId: string
-		zoneSide: DragZone["side"]
+		zoneSide: Zone["side"]
 	}
 	[LAYOUT_ERROR.CANT_REARRANGE_DOCKED_WITH_NON_DOCKED]: {
-		draggingFrameId: string
+		movingFrameId: string
 		hoveredFrameId: string
-		zoneSide: DragZone["side"]
+		zoneSide: Zone["side"]
 	}
 	[LAYOUT_ERROR.CANT_SPLIT_DOCKED_FRAME]: {
 		frame: LayoutFrame
@@ -376,6 +377,9 @@ export type LayoutErrorsInfo = {
 	[LAYOUT_ERROR.CANT_RESIZE_COLLAPSED_FRAME]: {
 		frame: LayoutFrame
 	}
+	[LAYOUT_ERROR.CANT_RESIZE_SINGLE_FRAME]: {
+		frame: LayoutFrame
+	}
 	[LAYOUT_ERROR.REDISTRIBUTE_WOULD_RESULT_IN_INVALID_FRAMES]: {
 		problemEdgeCoordinates: number[]
 	}
@@ -385,7 +389,7 @@ export type LayoutErrorsInfo = {
 export type HasOpposite = Direction | EdgeSide | ExtendedDirection | ExtendedEdgeSide | keyof Point | keyof Size
 
 
-export type BaseDragZone = {
+export type BaseZone = {
 	x: number
 	y: number
 	width: number
@@ -394,17 +398,17 @@ export type BaseDragZone = {
 	pxHeight: number
 }
 
-export type FrameDragZone = BaseDragZone & {
+export type FrameZone = BaseZone & {
 	type: "frame"
 	side: EdgeSide | "center"
 }
 
-export type WindowEdgeZone = BaseDragZone & {
+export type WindowEdgeZone = BaseZone & {
 	type: "window"
 	side: EdgeSide
 }
 
-export type DragZone = FrameDragZone | WindowEdgeZone
+export type Zone = FrameZone | WindowEdgeZone
 
 export const zWindowCreate = zLayoutWindowLoose
 	.partial({ id: true, pxWidth: true, pxHeight: true, pxX: true, pxY: true })
@@ -437,33 +441,33 @@ export type LayoutChange<TInfo = never> = {
 	window?: Partial<LayoutWindow>
 	info?: TInfo
 }
-export type DragState = {
+export type MoveState = {
 	/** The current directions in the corresponding orientations that the user is dragging in. */
-	dragDirections: Record<Orientation, Direction | undefined>
+	moveDirections: Record<Orientation, Direction | undefined>
 	/** The curren point (in scaled window coordinates) the user is dragging at. */
-	dragPoint?: Point
+	movePoint?: Point
 	/** Cumulative pixel distance the user has dragged from the initial click point. 0 on start, increases on each move. */
-	dragDistance: number
+	moveDistance: number
 	/** Whether the user is currently dragging and what type of drag. Is truthy string during all drag events. */
-	isDragging: boolean | "frame" | "edge"
+	isMoving: boolean | "frame" | "edge"
 	/** Whether to show the moved frames while dragging. */
-	showDragging: boolean
-	/** The frame being dragged during a frame drag. Only set when isDragging is "frame". */
-	draggingFrameId?: FrameId
+	showMoving: boolean
+	/** The frame being dragged during a frame drag. Only set when isMoving is "frame". */
+	movingFrameId?: FrameId
 	/**
 	 * The edges that are currently being dragged. There are multiple edges if they drag an intersection since what's actually happening is we're just dragging the closest horizontal and vertical edges.
 	 */
-	draggingEdges: Edge[]
+	movingEdges: Edge[]
 	/**
 	 * The intersection that is currently being dragged.
 	 */
-	draggingIntersection?: IntersectionEntry
+	movingIntersection?: IntersectionEntry
 	/** The "visual" edges that can be displayed for dragging. See {@link getVisualEdges} */
 	visualEdges: Edge[]
 	/**
 	 * The frames touching the currently dragged edges. Each entry corresponds to the frames touching the corresponding dragging edge.
 	 *
-	 * So you can use the index in draggingEdges to get the corresponding frames.
+	 * So you can use the index in movingEdges to get the corresponding frames.
 	 */
 	touchingFrames: Record<string, LayoutFrame>[]
 	/**
@@ -471,13 +475,13 @@ export type DragState = {
 	 */
 	touchingFramesArrays: LayoutFrame[][]
 	/**
-	 * All the frames, with/without the currently dragged frames depending on if `showDragging` is true.
+	 * All the frames, with/without the currently dragged frames depending on if `showMoving` is true.
 	 */
 	frames: Record<string, LayoutFrame>
 	/**
-	 * The frame that is currently being hovered over (according to whether `dragPoint` in in the frame or not).
+	 * The frame that is currently being hovered over (according to whether `movePoint` in in the frame or not).
 	 */
-	dragHoveredFrame: LayoutFrame | undefined
+	moveHoveredFrame: LayoutFrame | undefined
 	/**
 	 * A list of corner intersections. Frames can also be dragged by these.
 	 */
@@ -485,20 +489,22 @@ export type DragState = {
 	/**
 	 * Whether the drag was initiated from a point along the window edge.
 	 */
-	isDraggingFromWindowEdge: boolean
+	isMovingFromWindowEdge: boolean
+	/** Custom context passed to moveStart, available to action handlers via state.eventContext. */
+	eventContext?: Record<string, unknown>
 	win: LayoutWindow
 }
 
 
-export interface ActionDragChangeResult {
+export interface ActionChangeResult {
 	/** Whether the drag should update the edges. Defaults to false. */
 	updateEdges?: boolean
 	/** Deco shapes produced by this action during this drag step. */
 	shapes: LayoutShape[]
 	/** Whether to show the moved edges while dragging. Defaults to true. */
-	showDragging?: boolean
+	showMoving?: boolean
 }
-export type DragChangeResult = Omit<ActionDragChangeResult, "shapes">
+export type MoveChangeResult = Omit<ActionChangeResult, "shapes">
 
 /**
  * Called when the drag coordinates change (during any event).
@@ -506,14 +512,21 @@ export type DragChangeResult = Omit<ActionDragChangeResult, "shapes">
  * Should return `{ allowed: true/false, shapes: LayoutShape[] }` to control whether the action is allowed and edges update and what deco shapes to render.
  *
  * Note that the allowed return type only affect the `move` event but is also typed as `boolean` for other events for ease of use.
+ *
+ * Use also to cleanup your action when type is "end".
+ *
+ * See also {@link ActionHandler.onMoveChange} to understand it's lifecycle as it is the extended version of.
  */
-export type DragChangeHandler = <T extends "start" | "move" | "end">(
+export type MoveChangeHandler = <T extends "start" | "move" | "end">(
 	type: T,
 	e: T extends "end" ? PointerEvent | undefined : PointerEvent,
-	state: DragState,
+	state: MoveState,
 	forceRecalculateEdges: () => void,
-	cancel: (e: PointerEvent | KeyboardEvent | undefined, state: DragState) => void
-) => ActionDragChangeResult
+	/** Calls moveEnd with apply: false */
+	cancel: T extends "end" ? undefined : (e: PointerEvent | KeyboardEvent | undefined, state: MoveState) => void,
+	/** Saves result to resolve moveStart promise with then calls moveEnd with given apply. */
+	resolve: T extends "end" ? undefined : ({ apply, result }: { apply: boolean, result: any }) => void
+) => ActionChangeResult
 
 /**
  * A drag action describes when and how to handle a drag event.
@@ -523,19 +536,21 @@ export type DragChangeHandler = <T extends "start" | "move" | "end">(
  * Each action should handle it's configuration and saving/caching any state it needs. See {@link SplitAction} and {@link CloseAction} for examples.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
-export interface IDragAction {
+export interface IAction {
 	/** A unique name for your action. */
 	name: string
-	onDragChange: DragChangeHandler
+	onMoveChange: MoveChangeHandler
 	/**
 	 *
-	 * Is called after `onDragChange("end")` with the same event. Might not be called if the request was cancelled.
+	 * Is called before `onMoveChange("end")` with the same event. Might not be called if the request was cancelled.
 	 *
 	 * You should apply your action if possible and return whether it was applied.
 	 *
-	 * This is also a good place to reset your state.
+	 * Do not reset state here, use onMoveChange ("end").
+	 *
+	 * See also {@link ActionHandler.onMoveApply} which this is the extended version of.
 	 */
-	onDragApply: (state: DragState, forceRecalculateEdges: () => void) => boolean
+	onMoveApply: (state: MoveState, forceRecalculateEdges: () => void) => boolean
 	/**
 	 * Should return true if it should handle the "request"/event (e.g. some modifier is being pressed => user is requesting x action).
 	 *
@@ -545,22 +560,16 @@ export interface IDragAction {
 	 */
 	canHandleRequest(
 		e: KeyboardEvent | PointerEvent,
-		state: DragState,
+		state: MoveState,
 		forceRecalculateEdges: () => void
 	): boolean
 	/**
-	 * Called when a user cancels the drag action.
-	 *
-	 * You should reset your state here.
-	 */
-	cancel(e: PointerEvent | KeyboardEvent | undefined, state: DragState): void
-	/**
-	 * Plugins should implement some basic debug logs by calling {@link DragActionHandler.debugState } at least before and after applying actions in onDragApply. Debug can be a string because it can be an object key to filter on (see the debugState function).
+	 * Plugins should implement some basic debug logs by calling {@link ActionHandler.debugState } at least before and after applying actions in onMoveApply. Debug can be a string because it can be an object key to filter on (see the debugState function).
 	 *
 	 *
 	 * Calls look like this usually, where this.state is the plugin state:
 	 * ```ts
-	 * DragActionHandler.debugState(this.name, "before", state, this.state, this.debug)
+	 * ActionHandler.debugState(this.name, "before", state, this.state, this.debug)
 	 * ```
 	 */
 	debug: boolean | string
@@ -599,13 +608,53 @@ export interface IDragAction {
 	 */
 	annotateEdge?(edge: Edge, frames: LayoutFrame[]): void
 }
-export type EdgeDragStartData = { edge?: Edge, intersection?: IntersectionEntry }
-export type FrameDragStartData = { frameId: FrameId }
+export type EdgeMoveStartData = { edge?: Edge, intersection?: IntersectionEntry }
+export type FrameMoveStartData = { frameId: FrameId }
+
+export type ActionHandlerApplyResult = {
+	/** Whether to apply the regular drag end changes. Return false to reset to the position before dragging. */
+	apply: boolean
+	/** Value to resolve the drag promise with. Ignored if `apply` is false. */
+	result: any
+}
+
+/**
+ * Handler interface for drag actions.
+ */
+export interface ActionHandler {
+	eventHandler: (e: KeyboardEvent, state: MoveState, forceRecalculateEdges: () => void) => void
+	/**
+	 * Called when the drag coordinates change (during any event). Should return true to allow the edges to be updated/moved, or false to prevent it. Note that the return only affects the move event but it's typed like this for ease of use. See also {@link MoveChangeHandler}.
+	 *
+	 * Can be used to save some context/info to later apply safely during onMoveApply.
+	 *
+	 * The call order is:
+	 * - onMoveChange("start", ...)
+	 * - onMoveChange("move", ...)
+	 * - onMoveApply(...) (IF moveEnd was called with apply: true, otherwise this is skipped)
+	 * - onMoveChange("end", ...) // always called last, do cleanup here
+	 */
+	onMoveChange: (...args: Parameters<MoveChangeHandler>) => MoveChangeResult
+	/**
+	 * Called when drag will be applied. If moveEnd was called with apply false, it will not be called.
+	 * Return false to not apply the regular drag end changes (i.e. return false to reset to the position before dragging).
+	 *
+	 * Do not use for resetting handler state, use onMoveChange("end", ...) for that.
+	 */
+	onMoveApply: (
+		state: MoveState,
+		forceRecalculateEdges: () => void
+	) => ActionHandlerApplyResult
+	/**
+	 * Called after visual edges are recalculated. Action handlers can annotate edges with error info.
+	 */
+	annotateEdges?: (edges: Edge[], frames: LayoutFrame[]) => void
+}
 
 // drag start overloads for triggering dragsj
-export type DragStartFn = {
-	(e: PointerEvent, type: "edge", data: EdgeDragStartData): void
-	(e: PointerEvent, type: "frame", data: FrameDragStartData): void
+export type MoveStartFn = {
+	(e: PointerEvent, type: "edge", data: EdgeMoveStartData): void
+	(e: PointerEvent, type: "frame", data: FrameMoveStartData): void
 }
 
 export type * from "./vue.js"

package/src/runtime/types/vue.ts

@@ -1,10 +1,11 @@
 import type { ComputedRef, InjectionKey, Ref } from "vue"
 
 // eslint-disable-next-line no-restricted-imports
-import type { Direction, DragState, Edge, FrameId, IntersectionEntry, LayoutFrame, LayoutShape, LayoutWindow, Orientation, Point } from "./index.js"
+import type { ActionHandler, ActionHandlerApplyResult, Direction, Edge, FrameId, IntersectionEntry, LayoutFrame, LayoutShape, LayoutWindow, MoveState, Orientation, Point } from "./index.js"
 
 export type LayoutContext = ComputedRef<
 	& {
+
 		/** The owning window, needed so we can correctly scale coordinates. */
 		win: LayoutWindow
 		onFocus: (frameId: string) => void
@@ -14,28 +15,29 @@ export type LayoutContext = ComputedRef<
 export const layoutContextInjectionKey = Symbol.for("@witchcraft/layout:context") as InjectionKey<LayoutContext>
 
 export interface UseFramesContext {
-	dragStart: {
-		(e: PointerEvent, type: "edge", data: { edge?: Edge, intersection?: IntersectionEntry }): void
-		(e: PointerEvent, type: "frame", data: { frameId: FrameId }): void
+	actionHandler: ActionHandler
+	moveStart: {
+		(e: PointerEvent, type: "edge", data: { edge?: Edge, intersection?: IntersectionEntry }, opts?: { moveEvent?: string, endEvent?: string, context?: Record<string, unknown> }): Promise<any>
+		(e: PointerEvent, type: "frame", data: { frameId: FrameId }, opts?: { moveEvent?: string, endEvent?: string, context?: Record<string, unknown> }): Promise<any>
 	}
-	dragMove: (e: PointerEvent) => void
-	dragEnd: (e?: PointerEvent, options?: { apply?: boolean }) => void
+	onMove: (e: PointerEvent) => void
+	moveEnd: (e?: PointerEvent, options?: Partial<Pick<ActionHandlerApplyResult, "apply">>) => void
 	cancel: () => void
-	dragDirections: Ref<Record<Orientation, Direction | undefined>>
-	dragPoint: Ref<Point | undefined>
-	isDragging: Ref<false | "frame" | "edge">
-	draggingEdges: Ref<Edge[]>
-	draggingIntersection: Ref<IntersectionEntry | undefined>
+	moveDirections: Ref<Record<Orientation, Direction | undefined>>
+	movePoint: Ref<Point | undefined>
+	isMoving: Ref<false | "frame" | "edge">
+	movingEdges: Ref<Edge[]>
+	movingIntersection: Ref<IntersectionEntry | undefined>
 	visualEdges: Ref<Edge[]>
 	touchingFrames: Ref<Record<string, LayoutFrame>[]>
 	touchingFramesArrays: Ref<LayoutFrame[][]>
 	frames: ComputedRef<Record<string, LayoutFrame>>
-	dragHoveredFrame: ComputedRef<LayoutFrame | undefined>
+	moveHoveredFrame: ComputedRef<LayoutFrame | undefined>
 	intersections: ComputedRef<IntersectionEntry[]>
-	isDraggingFromWindowEdge: Ref<boolean>
+	isMovingFromWindowEdge: Ref<boolean>
 	forceRecalculateEdges: () => void
-	state: ComputedRef<DragState>
-	frameDragFrameId: Ref<FrameId | undefined>
+	state: ComputedRef<MoveState>
+	movingFrameId: Ref<FrameId | undefined>
 }
 
-export const dragContextInjectionKey = Symbol.for("@witchcraft/layout:dragContext") as InjectionKey<UseFramesContext>
+export const moveContextInjectionKey = Symbol.for("@witchcraft/layout:moveContext") as InjectionKey<UseFramesContext>

package/dist/runtime/drag/defaultDragActions.d.ts

@@ -1,9 +0,0 @@
-import type { IDragAction } from "../types/index.js";
-/**
- * Creates the default drag actions (Split, Close, FrameDrag).
- */
-export declare function createDefaultHandlers(config: {
-    debugSplit?: boolean;
-    debugClose?: boolean;
-    debugFrameDrag?: boolean;
-}): IDragAction[];

package/dist/runtime/drag/defaultDragActions.js

@@ -1,10 +0,0 @@
-import { CloseAction } from "./CloseAction.js";
-import { FrameDragAction } from "./FrameDragAction.js";
-import { SplitAction } from "./SplitAction.js";
-export function createDefaultHandlers(config) {
-  return [
-    new SplitAction(void 0, void 0, void 0, { debug: config.debugSplit }),
-    new CloseAction(void 0, void 0, void 0, { debug: config.debugClose }),
-    new FrameDragAction(void 0, void 0, void 0, { debug: config.debugFrameDrag })
-  ];
-}

package/dist/runtime/layout/getDragZones.d.ts

@@ -1,8 +0,0 @@
-import type { DragState, DragZone } from "../types/index.js";
-/**
- * Find the drag zone under the drag point.
- */
-export declare function getDragZones(state: Pick<DragState, "dragPoint" | "dragHoveredFrame" | "frames" | "win">, { frameEdgePx, windowEdgePx }: {
-    frameEdgePx: number;
-    windowEdgePx: number;
-}): DragZone | undefined;

package/dist/runtime/layout/getDragZones.js

@@ -1,32 +0,0 @@
-import { getFrameDragZones } from "./getFrameDragZones.js";
-import { getWindowDragZones } from "./getWindowDragZones.js";
-import { isPointInRect } from "./isPointInRect.js";
-export function getDragZones(state, { frameEdgePx, windowEdgePx }) {
-  const { dragPoint, win } = state;
-  const frameId = state.dragHoveredFrame?.id;
-  if (!frameId) return;
-  const frame = state.frames[frameId];
-  if (!frame || !dragPoint) return;
-  const frameZones = getFrameDragZones(frame, frameEdgePx, win.pxWidth, win.pxHeight);
-  const windowZones = getWindowDragZones(win, windowEdgePx);
-  let matchedZone;
-  for (const zone of windowZones) {
-    if (isPointInRect(zone, dragPoint)) {
-      matchedZone = {
-        ...zone,
-        type: "window"
-      };
-      break;
-    }
-  }
-  if (!matchedZone) {
-    for (const zone of frameZones) {
-      if (isPointInRect(zone, dragPoint)) {
-        matchedZone = zone;
-        break;
-      }
-    }
-  }
-  if (!matchedZone) return void 0;
-  return matchedZone;
-}

package/src/runtime/drag/createDefaultHandlers.ts

@@ -1,20 +0,0 @@
-import { CloseAction } from "./CloseAction"
-import { FrameDragAction } from "./FrameDragAction.js"
-import { SplitAction } from "./SplitAction.js"
-
-import type { IDragAction } from "../types/index.js"
-
-/**
- * Creates the default drag actions (Split, Close, FrameDrag).
- */
-export function createDefaultHandlers(config: {
-	debugSplit?: boolean
-	debugClose?: boolean
-	debugFrameDrag?: boolean
-} = {}): IDragAction[] {
-	return [
-		new SplitAction(undefined, undefined, undefined, { debug: config.debugSplit }),
-		new CloseAction(undefined, undefined, undefined, { debug: config.debugClose }),
-		new FrameDragAction(undefined, undefined, undefined, { debug: config.debugFrameDrag })
-	]
-}

package/src/runtime/layout/getDragZones.ts

@@ -1,48 +0,0 @@
-import { getFrameDragZones } from "./getFrameDragZones.js"
-import { getWindowDragZones } from "./getWindowDragZones.js"
-import { isPointInRect } from "./isPointInRect.js"
-
-import type { DragState, DragZone, WindowEdgeZone } from "../types/index.js"
-
-/**
- * Find the drag zone under the drag point.
- */
-export function getDragZones(
-	state: Pick<DragState, "dragPoint" | "dragHoveredFrame" | "frames" | "win">,
-	{ frameEdgePx, windowEdgePx }: { frameEdgePx: number, windowEdgePx: number }
-): DragZone | undefined {
-	const { dragPoint, win } = state
-	const frameId = state.dragHoveredFrame?.id
-	if (!frameId) return
-
-	const frame = state.frames[frameId]
-	if (!frame || !dragPoint) return
-
-	const frameZones = getFrameDragZones(frame, frameEdgePx, win.pxWidth, win.pxHeight)
-
-	const windowZones = getWindowDragZones(win, windowEdgePx)
-
-	let matchedZone: DragZone | undefined
-	for (const zone of windowZones) {
-		if (isPointInRect(zone, dragPoint)) {
-			matchedZone = {
-				...zone,
-				type: "window"
-			} as WindowEdgeZone
-			break
-		}
-	}
-
-	if (!matchedZone) {
-		for (const zone of frameZones) {
-			if (isPointInRect(zone, dragPoint)) {
-				matchedZone = zone
-				break
-			}
-		}
-	}
-
-	if (!matchedZone) return undefined
-
-	return matchedZone
-}