@witchcraft/layout 1.0.0

package/src/runtime/helpers/resizeByEdge.ts

@@ -0,0 +1,45 @@
+import type {
+	Direction,
+	Edge, LayoutFrame
+} from "../types/index.js"
+
+export function resizeByEdge(
+	touchingFrames: LayoutFrame[],
+	edge: Edge,
+	dir: Direction,
+	newPos: number,
+	distance: number
+): void {
+	if (distance === 0) return
+
+	for (const frame of touchingFrames) {
+		if (dir === "up" || dir === "down") {
+			const isAbove = frame.y < edge!.startY
+
+			if (isAbove) {
+				frame.height = newPos - frame.y
+			} else {
+				// careful order
+				frame.height = (frame.y + frame.height) - newPos
+				frame.y = newPos
+			}
+		} else {
+			const isLeft = frame.x < edge!.startX
+
+			if (isLeft) {
+				frame.width = newPos - frame.x
+			} else {
+				// careful order
+				frame.width = (frame.x + frame.width) - newPos
+				frame.x = newPos
+			}
+		}
+	}
+	if (dir === "up" || dir === "down") {
+		edge!.startY = newPos
+		edge!.endY = newPos
+	} else {
+		edge!.startX = newPos
+		edge!.endX = newPos
+	}
+}

package/src/runtime/helpers/sideToDirection.ts

@@ -0,0 +1,15 @@
+import type { Direction, EdgeSide } from "../types/index.js"
+
+/** Converts a side to a direction (relative to a frame's center) */
+
+export function sideToDirection(side: EdgeSide): Direction {
+	switch (side) {
+		case "left":
+		case "right":
+			return side
+		case "top":
+			return "up"
+		case "bottom":
+			return "down"
+	}
+}

package/src/runtime/helpers/sideToOrientation.ts

@@ -0,0 +1,12 @@
+import type { EdgeSide, Orientation } from "../types/index.js"
+
+export function sideToOrientation(dir: EdgeSide): Orientation {
+	switch (dir) {
+		case "left":
+		case "right":
+			return "vertical"
+		case "top":
+		case "bottom":
+			return "horizontal"
+	}
+}

package/src/runtime/helpers/splitEdge.ts

@@ -0,0 +1,23 @@
+import { last } from "@alanscodelog/utils/last"
+
+import type { Edge, Orientation } from "../types/index.js"
+
+export function splitEdge(edge: Edge, edgeDirection: Orientation, splits: number[]): Edge[] {
+	const startKey = edgeDirection === "horizontal" ? "startX" : "startY"
+	const endKey = edgeDirection === "horizontal" ? "endX" : "endY"
+	const newEdges: Edge[] = []
+	if (splits.length === 0) throw new Error("There must be at least one split position.")
+	for (const [i, splitPos] of splits.entries()) {
+		if (i === 0) {
+			newEdges.push({ ...edge, [startKey]: edge[startKey], [endKey]: splitPos })
+		} else {
+			const prevEdge = newEdges[i - 1]
+			newEdges.push({ ...prevEdge, [startKey]: prevEdge[endKey], [endKey]: splitPos })
+		}
+	}
+	const prevEdge = last(newEdges)
+	if (prevEdge[endKey] !== edge[endKey]) {
+		newEdges.push({ ...prevEdge, [startKey]: prevEdge[endKey], [endKey]: edge[endKey] })
+	}
+	return newEdges
+}

package/src/runtime/helpers/toCoord.ts

@@ -0,0 +1,13 @@
+import type { HasOpposite } from "../types/index.js"
+
+/** Converts the given side/dir into a coordinate key (x/y) */
+export function toCoord<T extends HasOpposite>(dir: T): T extends "left" | "right" | "horizontal" ? "x" : "y" {
+	switch (dir) {
+		case "left":
+		case "right":
+		case "horizontal":
+			return "x" satisfies "x" | "y" as any
+		default:
+			return "y" satisfies "x" | "y" as any
+	}
+}

package/src/runtime/helpers/toId.ts

@@ -0,0 +1,9 @@
+import { unreachable } from "@alanscodelog/utils/unreachable"
+
+export function toId(item: { id: string } | string): string {
+	return typeof item === "string"
+		? item
+		: typeof item.id === "string"
+			? item.id
+			: unreachable()
+}

package/src/runtime/helpers/toWindowCoord.ts

@@ -0,0 +1,23 @@
+import { snapNumber } from "@alanscodelog/utils/snapNumber"
+
+import { numberToScaledPercent } from "./numberToScaledPercent.js"
+
+import { getSnapPoint } from "../settings.js"
+import type { LayoutWindow, Point } from "../types/index.js"
+
+export function toWindowCoord(
+	win: LayoutWindow,
+	e: Pick<PointerEvent, "clientX" | "clientY">,
+	snapAmount: Point = getSnapPoint()
+): Point {
+	const x = numberToScaledPercent((e.clientX - win.pxX), win.pxWidth)
+	const y = numberToScaledPercent((e.clientY - win.pxY), win.pxHeight)
+
+	if (snapAmount) {
+		return {
+			x: snapNumber(x, snapAmount.x),
+			y: snapNumber(y, snapAmount.x)
+		}
+	}
+	return { x, y }
+}

package/src/runtime/helpers/unionEdges.ts

@@ -0,0 +1,11 @@
+import { last } from "@alanscodelog/utils/last"
+
+import type { Edge, Orientation } from "../types/index.js"
+
+export function unionEdges(edges: Edge[], dir: Orientation): Edge {
+	const startKey = dir === "horizontal" ? "startX" : "startY"
+	const endKey = dir === "horizontal" ? "endX" : "endY"
+	edges.sort((a, b) => a[startKey] - b[startKey])
+	const newEdge = { ...edges[0], [startKey]: edges[0][startKey], [endKey]: last(edges)[endKey] }
+	return newEdge
+}

package/src/runtime/helpers/updateWindowSizeWithEvent.ts

@@ -0,0 +1,10 @@
+import type { LayoutWindow, PxPos, PxSize } from "../types/index.js"
+
+const props = ["pxWidth", "pxHeight", "pxX", "pxY"] as const
+export function updateWindowWithEvent(win: LayoutWindow, event: PxPos & PxSize): void {
+	for (const prop of props) {
+		if (event[prop] && win[prop] !== event[prop]) {
+			win[prop] = event[prop]
+		}
+	}
+}

package/src/runtime/index.ts

@@ -0,0 +1,5 @@
+export * from "./types/index.js"
+export * from "./layout/index.js"
+export * from "./helpers/index.js"
+export * from "./utils/KnownError.js"
+export * from "./settings.js"

package/src/runtime/layout/closeFrame.ts

@@ -0,0 +1,33 @@
+import { closeFrames } from "./closeFrames.js"
+import { getCloseFrameInfo } from "./getCloseFrameInfo.js"
+
+import { getMarginSize } from "../settings.js"
+import type { Direction, Edge, EdgeSide, LAYOUT_ERROR, LayoutFrame, LayoutWindow, Size } from "../types/index.js"
+import type { KnownError } from "../utils/KnownError.js"
+
+export function closeFrame<T extends "edge" | "dir">(
+	win: LayoutWindow,
+	visualEdges: Edge[],
+	frame: LayoutFrame,
+	/** See {@link getCloseFrameInfo} */
+	// future, support multiple dirs? return aggregate error?
+	closeDirOrSide: (T extends "dir" ? Direction : EdgeSide),
+	closeBy: T = "dir" as any as T,
+	force: boolean = false,
+	minSize: Size = getMarginSize()
+): LayoutFrame[]
+	| KnownError<
+		| typeof LAYOUT_ERROR.CANT_CLOSE_NEARBY_FRAMES_TOO_SMALL
+		| typeof LAYOUT_ERROR.CANT_CLOSE_NO_DRAG_EDGE
+		| typeof LAYOUT_ERROR.CANT_CLOSE_SINGLE_FRAME
+		| typeof LAYOUT_ERROR.CANT_CLOSE_WITHOUT_FORCE
+	> {
+	const canClose = getCloseFrameInfo(Object.values(win.frames), visualEdges, frame, closeDirOrSide, closeBy, force, minSize)
+	if ((canClose instanceof Error)) {
+		return canClose
+	}
+	const { deletedFrames, modifiedFrames } = canClose
+	closeFrames(win, deletedFrames, modifiedFrames)
+	win.activeFrame = modifiedFrames[0].id
+	return deletedFrames
+}

package/src/runtime/layout/closeFrames.ts

@@ -0,0 +1,14 @@
+import type { LayoutFrame, LayoutWindow } from "../types/index.js"
+
+export function closeFrames(
+	win: LayoutWindow,
+	deletedFrames: LayoutFrame[],
+	modifiedFrames: LayoutFrame[]
+): void {
+	for (const f of deletedFrames) {
+		delete win.frames[f.id]
+	}
+	for (const mod of modifiedFrames) {
+		win.frames[mod.id] = mod
+	}
+}

package/src/runtime/layout/createSplitDecoEdge.ts

@@ -0,0 +1,34 @@
+import { findSafeSplitEdgeAndPosition } from "./findSafeSplitEdge.js"
+
+import { getMarginSize, getSnapPoint } from "../settings.js"
+import type { LayoutFrame, Point, RawSplitDeco, Size, SplitDecoShapes } from "../types/index.js"
+
+export function createSplitDecoEdge(
+	frames: Record<string, LayoutFrame>,
+	deco: RawSplitDeco,
+	snapAmount: Point = getSnapPoint(),
+	minSize: Size = getMarginSize()
+): SplitDecoShapes {
+	const frame = frames[deco.id]
+	const { edge, position } = findSafeSplitEdgeAndPosition(frame, deco.direction, deco.position, snapAmount, minSize)
+	const newFrame = { x: frame.x, y: frame.y, width: frame.width, height: frame.height }
+
+	switch (deco.direction) {
+		case "right":
+			newFrame.x = position
+			newFrame.width = frame.x + frame.width - position
+			break
+		case "left":
+			newFrame.width = position - frame.x
+			break
+		case "down":
+			newFrame.y = position
+			newFrame.height = frame.y + frame.height - position
+			break
+		case "up":
+			newFrame.height = position - frame.y
+			break
+	}
+
+	return { edge, newFrame }
+}

package/src/runtime/layout/createSplitDecoFromDrag.ts

@@ -0,0 +1,24 @@
+import { createSplitDecoEdge } from "./createSplitDecoEdge.js"
+
+import { dirToOrientation } from "../helpers/dirToOrientation.js"
+import { getMarginSize, getSnapPoint } from "../settings.js"
+import type { Direction, LayoutFrame, Point, RawSplitDeco, Size, SplitDeco } from "../types/index.js"
+
+export function createSplitDecoFromDrag(
+	frames: Record<string, LayoutFrame>,
+	frame: LayoutFrame,
+	dragDirection: Direction,
+	dragPoint: Point,
+	snapAmount: Point = getSnapPoint(),
+	minSize: Size = getMarginSize()
+): SplitDeco {
+	const orientation = dirToOrientation(dragDirection)
+	const deco: RawSplitDeco = {
+		type: "split",
+		id: frame.id,
+		position: dragPoint[orientation === "horizontal" ? "x" : "y"],
+		direction: dragDirection
+	}
+	;(deco as SplitDeco).shapes = createSplitDecoEdge(frames, deco, snapAmount, minSize)
+	return deco as SplitDeco
+}

package/src/runtime/layout/debugFrame.ts

@@ -0,0 +1,6 @@
+import type { LayoutFrame } from "../types/index.js"
+
+export function debugFrame(frame: LayoutFrame): string {
+	const f = frame
+	return `id: ${f.id.slice(0, 4)}, x:  ${f.x}, y: ${f.y}, w: ${f.width}, h: ${f.height}`
+}

package/src/runtime/layout/findFramesTouchingEdge.ts

@@ -0,0 +1,92 @@
+import { containsEdge } from "../helpers/containsEdge.js"
+import { dirToSide } from "../helpers/dirToSide.js"
+import { frameToEdges } from "../helpers/frameToEdges.js"
+import { getEdgeOrientation } from "../helpers/getEdgeOrientation.js"
+import { inRange } from "../helpers/inRange.js"
+import { oppositeSide } from "../helpers/oppositeSide.js"
+import { toCoord } from "../helpers/toCoord.js"
+import type { Direction, Edge, EdgeSide, LayoutFrame, Point } from "../types/index.js"
+
+/**
+ * Given an edge or visualEdge (which might touch/contain several frame edges, see {@link getVisualEdges }), returns the frame edges that match the given criteria. If no criteria is given, just returns all touching frames.
+ *
+ * Useful, for implementing drag related features.
+ *
+ * A visual explanation of the options:
+ * ```
+ * frames (A,B,C,D):
+ * ┌──────────────────┐
+ * │A       ╏B        │
+ * │        ╏         │
+ * ├────────╏         │
+ * │C       ╏─────────┤
+ * │        ╏D        │
+ * │        ╏         │
+ * │      < ╏ > searchDirections
+ * │        ╏         │
+ * │     + referencePoint*
+ * │        ╏         │
+ * └──────────────────┘
+ *          ^visualEdge
+ *
+ * Note the reference point is not on the line. The coordinate used depends on the orientation of the visualEdge.
+ * ```
+ * So given the middle visual edge, the point `+` and the right search direction, would return the left edge of frame D.
+ *
+ * Given the left direction instead it would return C.
+ *
+ * Given no point, and the right direction it would return B and D.
+ */
+
+export function findFramesTouchingEdge(
+	edge: Edge,
+	frames: LayoutFrame[],
+	criteria: {
+		/**
+		 * If a position (e.g. a cursor position) is given, only edges within the corresponding horizontal/vertical range will be returned.
+		 *
+		 * For example, if the visual edge is vertical, the function will only return edges that contain the y position, ignoring the x position. See the function documentation for a visual example.
+		 */
+		referencePoint?: Point
+		/**
+		 * Several frames can lay to either side of a visual edge. This limits the directions in which to look. Otherwise we look in the directions perpendicular to the visual edge.
+		 *
+		 * See the function documentation for a visual example.
+		 */
+		searchDirections?: Direction[]
+	} = {}
+): ({ edge: Edge, frame: LayoutFrame, side: EdgeSide })[] {
+	const visualEdge = edge
+	const res: ({ edge: Edge, frame: LayoutFrame, side: EdgeSide })[] = []
+	const visualEdgeDirection = getEdgeOrientation(visualEdge)
+
+	const searchDirections = criteria.searchDirections
+		?? (visualEdgeDirection === "horizontal"
+			? ["up", "down"]
+			: ["left", "right"])
+
+	// the side opposite to the direction is the one touching the visual edge
+	const frameSearchSides = searchDirections.map(dir => oppositeSide(dirToSide(dir)))
+
+	const coord = toCoord(visualEdgeDirection)
+	const coordUpper: "X" | "Y" = coord.toUpperCase() as any
+
+	for (const frame of frames) {
+		const frameEdges = frameToEdges(frame, frameSearchSides)
+		const edges = Object.entries(frameEdges)
+
+		for (const [side, edge] of edges as [EdgeSide, Edge][]) {
+			if (containsEdge(edge, visualEdge, visualEdgeDirection)) {
+				if (criteria.referencePoint) {
+					const isInRange = inRange(criteria.referencePoint[coord], edge[`start${coordUpper}`], edge[`end${coordUpper}`])
+					if (isInRange) {
+						res.push({ edge, frame, side })
+					}
+				} else {
+					res.push({ edge, frame, side })
+				}
+			}
+		}
+	}
+	return res
+}

package/src/runtime/layout/findSafeSplitEdge.ts

@@ -0,0 +1,39 @@
+import { clampNumber, snapNumber } from "@alanscodelog/utils"
+
+import { dirToOrientation } from "../helpers/dirToOrientation.js"
+import { oppositeSide } from "../helpers/oppositeSide.js"
+import { getMarginSize, getSnapPoint } from "../settings.js"
+import type { Direction, Edge, LayoutFrame, Point, Size } from "../types/index.js"
+
+export function findSafeSplitEdgeAndPosition(
+	frame: LayoutFrame,
+	dragDirection: Direction,
+	dragPointOrPosition: Point | number,
+	snapAmount: Point = getSnapPoint(),
+	minSize: Size = getMarginSize()
+): { edge: Edge, position: number } {
+	const orientation = dirToOrientation(dragDirection)
+	const position
+		= typeof dragPointOrPosition === "number"
+			? dragPointOrPosition
+			: dragPointOrPosition[orientation === "horizontal" ? "x" : "y"]
+
+	const coordKey = orientation === "vertical" ? "y" : "x"
+	const sizeKey = orientation === "vertical" ? "height" : "width"
+	const pos = snapNumber(position, snapAmount[coordKey])
+	const lowerLimit = snapNumber(frame[coordKey] + minSize[sizeKey], snapAmount[coordKey], "floor")
+	const upperLimit = snapNumber(frame[coordKey] + frame[sizeKey] - minSize[sizeKey], snapAmount[coordKey], "floor")
+	const clampedPos = clampNumber(pos, lowerLimit, upperLimit)
+
+	const oppositeCoordKey = oppositeSide(coordKey)
+	const oppositeSizeKey = oppositeSide(sizeKey)
+	const frameStart = snapNumber(frame[oppositeCoordKey], snapAmount[oppositeCoordKey])
+	const frameEnd = snapNumber(frameStart + frame[oppositeSizeKey], snapAmount[oppositeCoordKey])
+
+	// createEdge is not needed, we can be sure edge created is sorted
+	const edge = orientation === "vertical"
+		? { startY: clampedPos, endY: clampedPos, startX: frameStart, endX: frameEnd }
+		: { startX: clampedPos, endX: clampedPos, startY: frameStart, endY: frameEnd }
+
+	return { edge, position: clampedPos }
+}

package/src/runtime/layout/findVisualEdge.ts

@@ -0,0 +1,11 @@
+import { containsEdge } from "../helpers/containsEdge.js"
+import { getEdgeOrientation } from "../helpers/getEdgeOrientation.js"
+import type { Edge } from "../types/index.js"
+
+export function findVisualEdge(visualEdges: Edge[], edge: Edge): Edge | undefined {
+	const edgeDirection = getEdgeOrientation(edge)
+	for (const visualEdge of visualEdges) {
+		if (containsEdge(visualEdge, edge, edgeDirection)) return visualEdge
+	}
+	return undefined
+}

package/src/runtime/layout/frameCreate.ts

@@ -0,0 +1,23 @@
+import { v4 as uuidv4 } from "uuid"
+
+import { getMaxInt } from "../settings.js"
+import type {
+	BaseLayoutFrame,
+	ExtendedLayoutFrame,
+	LayoutFrame
+} from "../types/index.js"
+
+/** Create a new frame. Note that it will always have a new id if it's undefined. */
+export function frameCreate(
+	opts: Partial<BaseLayoutFrame> & Omit<ExtendedLayoutFrame, keyof BaseLayoutFrame> = {}
+): LayoutFrame {
+	const maxInt = getMaxInt()
+	return {
+		width: maxInt,
+		height: maxInt,
+		x: 0,
+		y: 0,
+		...opts,
+		id: opts.id ?? uuidv4()
+	}
+}

package/src/runtime/layout/frameSplit.ts

@@ -0,0 +1,31 @@
+import { keys } from "@alanscodelog/utils/keys"
+
+import type { LayoutFrame, LayoutWindow } from "../types/index.js"
+
+/**
+ * Apply a frame split. See {@link getFrameSplitInfo}
+ * ```ts
+ * // undefined if we can't split
+ * const splitInfo = getFrameSplitInfo()
+ * if (splitInfo) {
+ * 	frameSplit(win, splitInfo)
+ *
+ * }
+ * ```
+ */
+
+export function frameSplit(
+	win: LayoutWindow,
+	{ splitFrame, newFrame }: {
+		splitFrame: LayoutFrame
+		newFrame: LayoutFrame
+	}
+): LayoutFrame | undefined {
+	const winFrame = win.frames[splitFrame.id]
+	for (const key of keys(splitFrame)) {
+		// @ts-expect-error wut
+		winFrame[key] = splitFrame[key]
+	}
+	win.frames[newFrame.id] = newFrame
+	return newFrame
+}