@witchcraft/layout 0.4.4 → 0.5.1

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>
@@ -331,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
@@ -389,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
@@ -398,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 })
@@ -441,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>[]
 	/**
@@ -475,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.
 	 */
@@ -489,22 +489,22 @@ export type DragState = {
 	/**
 	 * Whether the drag was initiated from a point along the window edge.
 	 */
-	isDraggingFromWindowEdge: boolean
-	/** Custom context passed to dragStart, available to action handlers via state.eventContext. */
+	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).
@@ -512,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. This can technically be called from "end", it should still work. */
+	cancel: (e: PointerEvent | KeyboardEvent | undefined, state: MoveState) => void,
+	/** Saves result to resolve moveStart promise with then calls moveEnd with given apply. Not available during "end" event. It's designed for resolving from other external evente (e.g. key events). */
+	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.
@@ -529,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).
 	 *
@@ -551,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
@@ -584,6 +587,11 @@ export interface IDragAction {
 		/** Error texts/hints to display when the action produces an error. */
 		errors?: string[]
 	}
+	/**
+	 * Called when an action is cancelled. Call action specific onCancel hooks here.
+	 */
+	// note: internally this is done by the actionhandler wrapping the given cancel function for an event
+	cancel(e: PointerEvent | KeyboardEvent | undefined, state: MoveState): void
 	/**
 	 * Called after visual edges are recalculated, once per edge. Action handlers can annotate edges with error info here ({@link Edge.error}).
 	 *
@@ -605,35 +613,48 @@ 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: DragState, forceRecalculateEdges: () => void) => void
+	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.
+	 * 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. See also {@link MoveChangeHandler} for the built in action handler.
 	 *
-	 * Can return anything for the end event as it's ignored.
+	 * Can be used to save some context/info to later apply safely during onMoveApply.
 	 *
-	 * Can be used to save some context/info to later apply safely during onDragApply.
+	 * The call order is:
+	 * - onMoveChange("start", ...)
+	 * - onMoveChange("move", ...)
+	 * - onMoveChange("end", ...)
+	 * - onMoveApply(...) (IF moveEnd was called with apply: true, otherwise this is skipped)
+	 * - onMoveEnded() // do cleanup here
 	 */
-	onDragChange: (...args: Parameters<DragChangeHandler>) => DragChangeResult
+	onMoveChange: (...args: Parameters<MoveChangeHandler>) => MoveChangeResult
 	/**
-	 * Called when drag will be applied. If dragEnd was called with apply false, it will not be called.
+	 * 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 onMoveEnded for that.
 	 */
-	onDragApply: (
-		state: DragState,
+	onMoveApply: (
+		state: MoveState,
 		forceRecalculateEdges: () => void
-	) => {
-		/** 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
-	}
+	) => ActionHandlerApplyResult
+
+	/** For doing cleanup */
+	onMoveEnded: () => void
+
 	/**
 	 * Called after visual edges are recalculated. Action handlers can annotate edges with error info.
 	 */
@@ -641,9 +662,9 @@ export interface ActionHandler {
 }
 
 // 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,7 +1,7 @@
 import type { ComputedRef, InjectionKey, Ref } from "vue"
 
 // eslint-disable-next-line no-restricted-imports
-import type { ActionHandler, 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<
 	& {
@@ -16,28 +16,28 @@ export const layoutContextInjectionKey = Symbol.for("@witchcraft/layout:context"
 
 export interface UseFramesContext {
 	actionHandler: ActionHandler
-	dragStart: {
+	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/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/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
-}