@witchcraft/layout 1.0.0

package/src/runtime/drag/CloseAction.ts

@@ -0,0 +1,158 @@
+import type { DragState, IDragAction } from "./types.js"
+
+import { dirToOrientation } from "../helpers/dirToOrientation.js"
+import { getEdgeOrientation } from "../helpers/getEdgeOrientation.js"
+import { oppositeSide } from "../helpers/oppositeSide.js"
+import { closeFrames } from "../layout/closeFrames.js"
+import { findFramesTouchingEdge } from "../layout/findFramesTouchingEdge.js"
+import { getCloseFrameInfo } from "../layout/getCloseFrameInfo.js"
+import type { CloseDeco } from "../types/index.js"
+import type { KnownError } from "../utils/KnownError.js"
+
+export type CloseInfo = Exclude<ReturnType<typeof getCloseFrameInfo>, KnownError>
+
+export class CloseAction implements IDragAction {
+	name = "close" as const
+
+	state: {
+		allowed: true
+		force: boolean
+		res: CloseInfo
+		cacheKey: string | undefined
+	} | {
+		allowed: false
+		force: boolean
+		res: CloseInfo | undefined
+		cacheKey: string | undefined
+	} = {} as any // this is initialized by this.reset()
+
+	handleEvent: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean | "force"
+	updateCloseDecos: (decos: CloseDeco[]) => void
+	hooks: {
+		onStart?: (active: boolean) => void
+		onCancel?: () => void
+		onError?: (e: KnownError) => void
+	}
+
+	constructor(
+		handleEvent: CloseAction["handleEvent"],
+		updateCloseDecos: CloseAction["updateCloseDecos"],
+		hooks: CloseAction["hooks"] = {}
+	) {
+		this.handleEvent = handleEvent
+		this.updateCloseDecos = updateCloseDecos
+		this.hooks = hooks
+		this.reset()
+	}
+
+	reset(): void {
+		this.state = {
+			allowed: false,
+			force: false,
+			res: undefined,
+			cacheKey: undefined
+		}
+		this.updateCloseDecos([])
+	}
+
+	updateDecos(state: DragState): void {
+		const {
+			isDragging
+		} = state
+		if (isDragging && this.state.allowed && this.state.res) {
+			const { force } = this.state
+			const decos = this.state.res.deletedFrames.map(_ => ({ id: _.id, type: "close" as const, force }))
+			this.updateCloseDecos(decos)
+		} else {
+			this.updateCloseDecos([])
+		}
+	}
+
+	canHandleRequest(e: PointerEvent | KeyboardEvent, state: DragState): boolean {
+		const { draggingEdges } = state
+		if (draggingEdges.length !== 1) return false
+		const res = this.handleEvent(e, state)
+		if (res === "force") {
+			this.state.force = true
+		} else {
+			this.state.force = false
+		}
+		if (res) {
+			this.hooks.onStart?.(true)
+			return true
+		}
+		this.reset()
+		return false
+	}
+
+	onDragChange(
+		_type: "start" | "end" | "move",
+		_e: PointerEvent | undefined,
+		state: DragState
+	): boolean {
+		const {
+			touchingFramesArrays,
+			dragDirections,
+			isDragging,
+			draggingEdges,
+			visualEdges,
+			frames,
+			isDraggingFromWindowEdge
+		} = state
+		const oppositeOrientation = oppositeSide(getEdgeOrientation(draggingEdges[0]))
+		let ok = false
+		if (isDragging && draggingEdges.length === 1) {
+			const res = findFramesTouchingEdge(
+				draggingEdges[0],
+				touchingFramesArrays[0],
+				{
+					// referencePoint: dragPoint.value, // if force pick smallest frame?
+					searchDirections: [dragDirections[oppositeOrientation]!]
+				}
+			)
+			if (res.length > 0) {
+				const orientation = dirToOrientation(dragDirections[oppositeOrientation]!)
+				const sizeKey = orientation === "horizontal" ? "width" : "height"
+				const smallestFrameSize = Math.min(...res.map(_ => _.frame[sizeKey]))
+				const frame = res.find(_ => _.frame[sizeKey] === smallestFrameSize)!.frame!
+				const cacheKey = `${frame.id}-${dragDirections[oppositeOrientation]!}`
+				if (this.state.allowed) {
+					if (this.state.cacheKey === cacheKey) {
+						this.updateDecos(state)
+						return true
+					}
+				}
+				const closeInfo = getCloseFrameInfo(Object.values(frames), visualEdges, frame, dragDirections[oppositeOrientation]!, "dir", this.state.force)
+				if (!(closeInfo instanceof Error)) {
+					this.state.allowed = true
+					this.state.res = closeInfo
+					this.state.cacheKey = cacheKey
+					ok = true
+				} else {
+					this.hooks.onError?.(closeInfo)
+				}
+			}
+		}
+		this.updateDecos(state)
+		if (!ok) {
+			this.state.allowed = false
+		}
+		return !isDraggingFromWindowEdge
+	}
+
+	onDragApply(state: DragState): boolean {
+		if (this.state.res) {
+			const { deletedFrames, modifiedFrames } = this.state.res
+			const win = state.win
+			closeFrames(win, deletedFrames, modifiedFrames)
+			this.reset()
+			return true
+		}
+		return false
+	}
+
+	cancel(): void {
+		this.reset()
+		this.hooks.onCancel?.()
+	}
+}

package/src/runtime/drag/DragActionHandler.ts

@@ -0,0 +1,146 @@
+import type { RecordFromArray } from "@alanscodelog/utils"
+
+import type { DragChangeHandler, DragState, IDragAction } from "./types.js"
+
+/**
+ * Handles the lifecycle of a drag actions {@link IDragAction} and provides additional hooks.
+ *
+ * The first action instance that can handle the request is passed control of the event handlers until the request changes.
+ */
+export class DragActionHandler<
+	TRawDragActions extends IDragAction[],
+	TDragActions extends RecordFromArray<TRawDragActions, "name"> = RecordFromArray<TRawDragActions, "name">
+> {
+	activeAction?: keyof TDragActions
+
+	actions: TDragActions
+
+	eventCanceller: (() => void) | undefined = undefined
+
+	boundCancel: () => void
+
+	defaultOnDragChange: DragChangeHandler
+	hooks: {
+		/** Called while dragging during dragChange events. You can use this to update the dragging edges. */
+		onRecalculate?: () => void
+		/**
+		 * Called before searching for a matching action. Useful for re-initializing state.
+		 *
+		 * Is passed a `cancel` function if you want to cancel the current drag action.
+		 */
+		onEvent?: (e: PointerEvent | KeyboardEvent | undefined, cancel: () => void) => void
+		/** Called when the action requested changes. */
+		onRequestChange?: (type: keyof TDragActions | undefined) => void
+		/** Called when the drag action ends either because it was completed or cancelled. */
+		onEnd?: (context: { cancelled: boolean, applied: boolean }) => void
+	}
+
+	constructor(
+		/**
+		 * Default onDragChange handler for when no action can handle the request.
+		 *
+		 * Should return true to allow the edges to be moved, or false to prevent it.
+		 */
+		defaultOnDragChange: DragChangeHandler,
+		actions: TRawDragActions,
+		hooks: DragActionHandler<TRawDragActions, TDragActions>["hooks"] = {}
+	) {
+		this.defaultOnDragChange = defaultOnDragChange
+		this.hooks = hooks
+		this.actions = {} as any
+		for (const action of actions) {
+			(this.actions as any)[action.name] = action
+		}
+		this.boundCancel = this.cancel.bind(this)
+	}
+
+	eventHandler(
+		e: KeyboardEvent | PointerEvent,
+		state: DragState,
+		forceRecalculateEdges: () => void
+	) {
+		if (state.isDragging) {
+			e.preventDefault()
+		}
+		let cancelled = false
+		this.hooks.onEvent?.(e, () => {
+			cancelled = true
+			this.cancel()
+		})
+		if (cancelled) return
+
+		let found = false
+		const oldActiveAction = this.activeAction
+		for (const action of Object.values<TRawDragActions[number]>(this.actions)) {
+			if (action.canHandleRequest(e, state, forceRecalculateEdges)) {
+				// if (this.activeAction !== action.name) {
+				// }
+				found = true
+				this.activeAction = action.name
+				break
+			}
+		}
+
+		if (!found) {
+			this.activeAction = undefined
+		}
+
+		if (oldActiveAction !== this.activeAction) {
+			if (oldActiveAction) {
+				this.actions[oldActiveAction]!.cancel()
+			}
+			this.hooks.onRequestChange?.(this.activeAction)
+		}
+
+		if (state.isDragging) {
+			forceRecalculateEdges()
+			this.hooks.onRecalculate?.()
+		}
+		return undefined
+	}
+
+	onDragChange<T extends "start" | "move" | "end">(
+		type: T,
+		e: T extends "end" ? PointerEvent | undefined : PointerEvent,
+		state: DragState,
+		forceRecalculateEdges: () => void,
+		cancel?: () => void
+	): boolean | undefined {
+		if (type === "start") {
+			this.eventCanceller = cancel
+			state.isDragging = true
+			this.eventHandler(e!, state, forceRecalculateEdges)
+		}
+		if (type === "end") {
+			state.isDragging = false
+			this.activeAction = undefined
+		}
+
+		if (this.activeAction) {
+			return this.actions[this.activeAction]!.onDragChange(type, e, state, forceRecalculateEdges, this.boundCancel)
+		}
+		return this.defaultOnDragChange(type, e, state, forceRecalculateEdges, this.boundCancel)
+	}
+
+	onDragApply(
+		state: DragState,
+		forceRecalculateEdges: () => void
+	): boolean {
+		if (this.activeAction) {
+			const res = this.actions[this.activeAction]!.onDragApply(state, forceRecalculateEdges)
+			this.hooks.onEnd?.({ cancelled: false, applied: res })
+			return false
+		}
+		this.hooks.onEnd?.({ cancelled: false, applied: false })
+		return true
+	}
+
+	cancel(): void {
+		if (this.activeAction) {
+			this.actions[this.activeAction].cancel()
+		}
+		this.activeAction = undefined
+		this.eventCanceller?.()
+		this.hooks.onEnd?.({ cancelled: true, applied: false })
+	}
+}

package/src/runtime/drag/DragDirectionStore.ts

@@ -0,0 +1,63 @@
+import type { Direction, Orientation, Point } from "../types/index.js"
+
+export class DragDirectionStore {
+	hooks: {
+		onUpdate: (directions: Record<Orientation, Direction | undefined>) => void
+	}
+
+	constructor(
+		hooks: DragDirectionStore["hooks"]
+	) {
+		this.hooks = hooks
+	}
+
+	lastPoint: Point | undefined
+
+	dragDirection: Record<Orientation, Direction | undefined> = {} as any
+
+	lesser: { x: Direction, y: Direction } = {
+		x: "left",
+		y: "up"
+	}
+
+	greater: { x: Direction, y: Direction } = {
+		x: "right",
+		y: "down"
+	}
+
+	reset(): void {
+		this.lastPoint = undefined
+		this.dragDirection = {} as any
+	}
+
+	update(point: Point): boolean {
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		const newXDirection = this.getDragDirection("x", point)
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		const newYDirection = this.getDragDirection("y", point)
+		let changed = false
+		if (newXDirection) {
+			this.dragDirection.horizontal = newXDirection
+		}
+		if (newYDirection) {
+			this.dragDirection.vertical = newYDirection
+		}
+
+		if (this.lastPoint?.x !== point.x || this.lastPoint?.y !== point.y) {
+			this.lastPoint = point
+			changed = true
+		}
+
+		if (!changed) return false
+		this.hooks.onUpdate(this.dragDirection)
+		return true
+	}
+
+	getDragDirection(coord: "x" | "y", point: Point): Direction | false {
+		if (!this.lastPoint) return false
+		const diff = point[coord] - this.lastPoint![coord]
+		if (diff > 0) return this.greater[coord]
+		if (diff < 0) return this.lesser[coord]
+		return false
+	}
+}

package/src/runtime/drag/SplitAction.ts

@@ -0,0 +1,147 @@
+import type { DragState, IDragAction } from "./types.js"
+
+import { getEdgeOrientation } from "../helpers/getEdgeOrientation.js"
+import { oppositeSide } from "../helpers/oppositeSide.js"
+import { createSplitDecoFromDrag } from "../layout/createSplitDecoFromDrag.js"
+import { frameSplit } from "../layout/frameSplit.js"
+import { getFrameSplitInfo } from "../layout/getFrameSplitInfo.js"
+import type { SplitDeco } from "../types/index.js"
+import type { KnownError } from "../utils/KnownError.js"
+
+export type SplitInfo = Exclude<ReturnType<typeof getFrameSplitInfo>, KnownError>
+export class SplitAction implements IDragAction {
+	name = "split" as const
+
+	state: {
+		allowed: false
+		res: SplitInfo | undefined
+		cacheKey: string | undefined
+	} | {
+		allowed: true
+		res: SplitInfo
+		cacheKey: string | undefined
+	} = {} as any // this is initialized by `this.reset()`
+
+	handleEvent: (e: PointerEvent | KeyboardEvent, state: DragState) => boolean
+	updateSplitDecos: (decos: SplitDeco[]) => void
+	hooks: {
+		onStart?: () => void
+		onCancel?: () => void
+		onError?: (e: KnownError) => void
+	}
+
+	constructor(
+		handleEvent: SplitAction["handleEvent"],
+		updateSplitDecos: SplitAction["updateSplitDecos"],
+		hooks: SplitAction["hooks"] = {}
+	) {
+		this.handleEvent = handleEvent
+		this.updateSplitDecos = updateSplitDecos
+		this.hooks = hooks
+		this.reset()
+	}
+
+	reset(): void {
+		this.state = {
+			allowed: false,
+			res: undefined,
+			cacheKey: undefined
+		}
+		this.updateSplitDecos([])
+	}
+
+	updateDecos(state: DragState): void {
+		const {
+			win,
+			isDragging,
+			dragHoveredFrame,
+			dragDirections,
+			draggingEdges,
+			dragPoint
+		} = state
+		if (isDragging && this.state.allowed && dragHoveredFrame && draggingEdges.length === 1) {
+			const oppositeOrientation = oppositeSide(getEdgeOrientation(draggingEdges[0]))
+			const deco = createSplitDecoFromDrag(
+				win.frames,
+				dragHoveredFrame,
+				dragDirections[oppositeOrientation]!,
+				dragPoint!
+			)
+			this.updateSplitDecos([deco])
+		} else {
+			this.updateSplitDecos([])
+		}
+	}
+
+	canHandleRequest(e: PointerEvent | KeyboardEvent, state: DragState): boolean {
+		const { draggingEdges } = state
+		if (draggingEdges.length !== 1) return false
+		if (this.handleEvent(e, state)) {
+			this.hooks.onStart?.()
+			return true
+		}
+		this.reset()
+		return false
+	}
+
+	calculateSplitRequest(state: DragState): boolean {
+		const {
+			dragHoveredFrame,
+			dragDirections,
+			draggingEdges,
+			dragPoint
+		} = state
+		const oppositeOrientation = oppositeSide(getEdgeOrientation(draggingEdges[0]))
+		const canSplit = getFrameSplitInfo(
+			dragHoveredFrame!,
+			dragDirections[oppositeOrientation]!,
+			dragPoint!
+		)
+		if (!(canSplit instanceof Error)) {
+			this.state.allowed = true
+			this.state.res = canSplit
+			this.state.cacheKey = dragHoveredFrame?.id
+			return true
+		} else {
+			this.hooks.onError?.(canSplit)
+			return false
+		}
+	}
+
+	onDragChange(
+		_type: "start" | "end" | "move",
+		_e: PointerEvent | undefined,
+		state: DragState
+	): true {
+		const { dragHoveredFrame } = state
+		let ok = false
+		if (dragHoveredFrame) {
+			if (this.state.cacheKey === dragHoveredFrame.id) {
+				this.updateDecos(state)
+				return true
+			}
+			ok = this.calculateSplitRequest(state)
+		}
+		this.updateDecos(state)
+		if (!ok) {
+			this.state.allowed = false
+		}
+		return true
+	}
+
+	onDragApply(state: DragState): boolean {
+		if (this.state.res) {
+			// this only caches once per frame hovered over
+			// so the drag position is outdated
+			this.calculateSplitRequest(state)
+			frameSplit(state.win, this.state.res!)
+		}
+		this.reset()
+		return true
+	}
+
+	cancel(): void {
+		this.reset()
+		this.hooks.onCancel?.()
+	}
+}

package/src/runtime/drag/types.ts

@@ -0,0 +1,107 @@
+import type { Direction, Edge, IntersectionEntry, LayoutFrame, LayoutWindow, Orientation, Point } from "../types/index.js"
+
+export type DragState = {
+	/** The current directions in the corresponding orientations that the user is dragging in. */
+	dragDirections: Record<Orientation, Direction | undefined>
+	/** The curren point (in scaled window coordinates) the user is dragging at. */
+	dragPoint?: Point
+	/** Whether the user is currently dragging. Is true during all drag events. */
+	isDragging: boolean
+	/**
+	 * 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[]
+	/**
+	 * The intersection that is currently being dragged.
+	 */
+	draggingIntersection?: 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.
+	 */
+	touchingFrames: Record<string, LayoutFrame>[]
+	/**
+	 * Same as touchingFrames, but with the frames in an array.
+	 */
+	touchingFramesArrays: LayoutFrame[][]
+	/**
+	 * All the frames, with/without the currently dragged frames depending on if `showDragging` is true.
+	 */
+	frames: Record<string, LayoutFrame>
+	/**
+	 * The frame that is currently being hovered over (according to whether `dragPoint` in in the frame or not).
+	 */
+	dragHoveredFrame: LayoutFrame | undefined
+	/**
+	 * A list of corner intersections. Frames can also be dragged by these.
+	 */
+	intersections: IntersectionEntry[]
+	/**
+	 * Whether the drag was initiated from a point along the window edge.
+	 */
+	isDraggingFromWindowEdge: boolean
+	win: LayoutWindow
+}
+
+/**
+ * Note that the return type only affects the `move` event but is also typed as `boolean` for other events for ease of use.
+ */
+export interface DragChangeHandler {
+	<T extends "start" | "move" | "end">(
+		type: T,
+		e: T extends "end" ? PointerEvent | undefined : PointerEvent,
+		state: DragState,
+		forceRecalculateEdges: () => void,
+		cancel: () => void
+	): boolean | undefined
+}
+
+/**
+ * A drag action describes when and how to handle a drag event.
+ *
+ * For example, there are the default split/close actions that can be triggered in certain situations. This could be when holding down a modifier or key, or some other condition (e.g. the user is dragging a specific edge).
+ *
+ * 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 {
+	/** A unique name for your action. */
+	name: string
+	/**
+	 * Called when the drag coordinates change (during any event). Should return true to allow the edges to be moved, or false to prevent it.
+	 *
+	 * Can be used to save some context/info to later apply safely during onDragApply.
+	 */
+
+	onDragChange: DragChangeHandler
+	/**
+	 *
+	 * Is called after `onDragChange("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.
+	 */
+	onDragApply: (state: DragState, 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).
+	 *
+	 * The user is not necessarily dragging at this point, though they might also change actions mid drag. So it does not necessarily mean the event is allowed.
+	 *
+	 * Here is where you should initiate your state. Don't allow the action by default unless it can always be allowed.
+	 */
+	canHandleRequest(
+		e: KeyboardEvent | PointerEvent,
+		state: DragState,
+		forceRecalculateEdges: () => void
+	): boolean
+	/**
+	 * Called when a user cancels the drag action.
+	 *
+	 * You should reset your state here.
+	 */
+	cancel(): void
+}

package/src/runtime/helpers/addPointsToIntersection.ts

@@ -0,0 +1,9 @@
+import type { Intersections, Point } from "../types/index.js"
+
+export function addPointsToIntersection(intersections: Intersections, points: Point[]): void {
+	for (const point of points) {
+		intersections[point.x] ??= {}
+		intersections[point.x][point.y] ??= 0
+		intersections[point.x][point.y]++
+	}
+}

package/src/runtime/helpers/assertEdgeSorted.ts

@@ -0,0 +1,11 @@
+import { getEdgeOrientation } from "./getEdgeOrientation.js"
+
+import type { Edge } from "../types/index.js"
+
+export function assertEdgeSorted(edge: Edge): void {
+	const dir = getEdgeOrientation(edge)
+	if ((dir === "horizontal" && edge.startX > edge.endX)
+		|| (dir === "vertical" && edge.startY > edge.endY)) {
+		throw new Error("Edge start/end is revered.")
+	}
+}

package/src/runtime/helpers/assertItemIn.ts

@@ -0,0 +1,13 @@
+import { LAYOUT_ERROR } from "../types/index.js"
+import { KnownError } from "../utils/KnownError.js"
+
+export function assertItemIn<
+	T extends Record<string, any>
+>(entries: T, id: keyof T | string | undefined): asserts id is keyof T {
+	if (id === undefined || entries[id] === undefined) {
+		const message = id === undefined
+			? `Id cannot be undefined.`
+			: `Could not find item by that id (${id as string | undefined}).`
+		throw new KnownError(LAYOUT_ERROR.INVALID_ID, message, { id: id as string | undefined })
+	}
+}

package/src/runtime/helpers/assertItemNotIn.ts

@@ -0,0 +1,10 @@
+import { LAYOUT_ERROR } from "../types/index.js"
+import { KnownError } from "../utils/KnownError.js"
+
+// don't try to be clever with type, we don't want it to narrow to never since we still want to be able to assign a new
+
+export function assertItemNotIn(entries: Record<string, any>, id: string | undefined): void {
+	if (id !== undefined && entries[id] !== undefined) {
+		throw new KnownError(LAYOUT_ERROR.ID_ALREADY_EXISTS, `Item with id ${id as string} already exists`, { id })
+	}
+}

package/src/runtime/helpers/assertLayoutHasActiveWindow.ts

@@ -0,0 +1,9 @@
+import type { Layout } from "../types/index.js"
+import { LAYOUT_ERROR } from "../types/index.js"
+import { KnownError } from "../utils/KnownError.js"
+
+export function assertLayoutHasActiveWindow(layout: Layout): asserts layout is Omit<Layout, "activeWindow"> & { activeWindow: NonNullable<Layout["activeWindow"]> } {
+	if (layout.activeWindow === undefined) {
+		throw new KnownError(LAYOUT_ERROR.NO_ACTIVE_WINDOW, "Layout has not active window.", {})
+	}
+}

package/src/runtime/helpers/assertValidWinAndFrame.ts

@@ -0,0 +1,16 @@
+import { assertValidWinAndFrameIds } from "./assertValidWinAndFrameIds.js"
+
+import type {
+	Layout,
+	LayoutFrame,
+	LayoutWindow
+} from "../types/index.js"
+
+export function assertValidWinAndFrame(
+	layout: Layout,
+	win?: LayoutWindow,
+	frame?: LayoutFrame
+): { win: LayoutWindow, frame: LayoutFrame } {
+	assertValidWinAndFrameIds(layout.windows, win?.id, frame?.id)
+	return { win: win!, frame: frame! }
+}