regular-layout 0.1.0 → 0.2.1

package/src/layout/calculate_edge.ts

@@ -0,0 +1,217 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  Copyright (c) 2026, the Regular Layout Authors. This file is part  *  ┃
+// ┃  *  of the Regular Layout library, distributed under the terms of the  *  ┃
+// ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { DEFAULT_PHYSICS, type Physics } from "./constants";
+import { insert_child } from "./insert_child";
+import type { Layout, LayoutPath, Orientation, ViewWindow } from "./types";
+
+/**
+ * Calculates an insertion point (which may involve splitting a single
+ * `"child-panel"` into a new `"split-panel"`), based on the  cursor position.
+ * *
+ * @param col - The cursor column.
+ * @param row - The cursor row.
+ * @param panel - The `Layout` to insert into.
+ * @param slot - The slot identifier where the insert should occur
+ * @param drop_target - The `LayoutPath` (from `calculateIntersect`) of the
+ * panel to either insert next to, or split by.
+ * @returns A new `LayoutPath` reflecting the updated (maybe) `"split-panel"`,
+ * which is enough to draw the overlay.
+ */
+export function calculate_edge(
+	col: number,
+	row: number,
+	panel: Layout,
+	slot: string,
+	drop_target: LayoutPath,
+	box?: DOMRect,
+	physics: Physics = DEFAULT_PHYSICS,
+): LayoutPath {
+	// Check root edges first
+	if (col < physics.SPLIT_ROOT_EDGE_TOLERANCE) {
+		return insert_root_edge(panel, slot, drop_target, [0], true, "horizontal");
+	}
+
+	if (col > 1 - physics.SPLIT_ROOT_EDGE_TOLERANCE) {
+		return insert_root_edge(
+			panel,
+			slot,
+			drop_target,
+			drop_target.path.length > 0 ? drop_target.path : [1],
+			false,
+			"horizontal",
+		);
+	}
+
+	if (row < physics.SPLIT_ROOT_EDGE_TOLERANCE) {
+		return insert_root_edge(panel, slot, drop_target, [0], true, "vertical");
+	}
+
+	if (row > 1 - physics.SPLIT_ROOT_EDGE_TOLERANCE) {
+		return insert_root_edge(
+			panel,
+			slot,
+			drop_target,
+			drop_target.path.length > 0 ? drop_target.path : [1],
+			false,
+			"vertical",
+		);
+	}
+
+	// Check panel edges
+	const is_column_edge =
+		drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE ||
+		drop_target.column_offset > 1 - physics.SPLIT_EDGE_TOLERANCE;
+
+	const is_row_edge =
+		drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE ||
+		drop_target.row_offset > 1 - physics.SPLIT_EDGE_TOLERANCE;
+
+	// If both edges triggered, choose closer axis
+	if (is_column_edge && is_row_edge) {
+		const col_distance = Math.abs(drop_target.column_offset - 0.5);
+		const row_distance = Math.abs(drop_target.row_offset - 0.5);
+		const col_scale =
+			(box?.width || 1) *
+			(drop_target.view_window.col_end - drop_target.view_window.col_start);
+
+		const row_scale =
+			(box?.height || 1) *
+			(drop_target.view_window.row_end - drop_target.view_window.row_start);
+
+		const use_column = col_distance * col_scale > row_distance * row_scale;
+
+		return insert_axis(
+			panel,
+			slot,
+			drop_target,
+			use_column
+				? drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE
+				: drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE,
+			use_column ? "horizontal" : "vertical",
+		);
+	}
+
+	if (is_column_edge) {
+		return insert_axis(
+			panel,
+			slot,
+			drop_target,
+			drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE,
+			"horizontal",
+		);
+	}
+
+	if (is_row_edge) {
+		return insert_axis(
+			panel,
+			slot,
+			drop_target,
+			drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE,
+			"vertical",
+		);
+	}
+
+	// Not at an edge - insert as a tab
+	return {
+		...drop_target,
+		path: [...drop_target.path, 0],
+	};
+}
+
+function insert_root_edge(
+	panel: Layout,
+	slot: string,
+	drop_target: LayoutPath,
+	path: number[],
+	is_before: boolean,
+	orientation: Orientation,
+): LayoutPath {
+	return insert_axis(
+		panel,
+		slot,
+		{ ...drop_target, path, orientation },
+		is_before,
+		orientation,
+	);
+}
+
+function insert_axis(
+	panel: Layout,
+	slot: string,
+	drop_target: LayoutPath,
+	is_before: boolean,
+	axis_orientation: Orientation,
+): LayoutPath {
+	let result_path: number[];
+
+	if (drop_target.orientation === axis_orientation) {
+		// Same orientation - insert into existing split
+		if (drop_target.path.length === 0) {
+			result_path = [is_before ? 0 : 1];
+		} else {
+			const last_index = drop_target.path[drop_target.path.length - 1];
+			result_path = [
+				...drop_target.path.slice(0, -1),
+				is_before ? last_index : last_index + 1,
+			];
+		}
+	} else {
+		// Different orientation - split the child panel
+		result_path = [...drop_target.path, is_before ? 0 : 1];
+	}
+
+	const new_panel = insert_child(panel, slot, result_path, axis_orientation);
+	const view_window = calculate_view_window(new_panel, result_path);
+	return {
+		...drop_target,
+		path: result_path,
+		slot: drop_target.slot,
+		is_edge: true,
+		orientation: axis_orientation,
+		view_window,
+	};
+}
+
+function calculate_view_window(panel: Layout, path: number[]): ViewWindow {
+	let view_window: ViewWindow = {
+		row_start: 0,
+		row_end: 1,
+		col_start: 0,
+		col_end: 1,
+	};
+
+	let current_panel = panel;
+	for (const step of path) {
+		if (current_panel.type === "child-panel") {
+			break;
+		}
+
+		const index = Math.min(step, current_panel.children.length - 1);
+		const is_vertical = current_panel.orientation === "vertical";
+		const start_key = is_vertical ? "row_start" : "col_start";
+		const end_key = is_vertical ? "row_end" : "col_end";
+		const total_size = view_window[end_key] - view_window[start_key];
+		const offset = current_panel.sizes
+			.slice(0, index)
+			.reduce((sum, size) => sum + size * total_size, view_window[start_key]);
+
+		view_window = {
+			...view_window,
+			[start_key]: offset,
+			[end_key]: offset + total_size * current_panel.sizes[index],
+		};
+
+		current_panel = current_panel.children[index];
+	}
+
+	return view_window;
+}

package/src/{common → layout}/calculate_intersect.ts

@@ -9,24 +9,24 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type {
-	LayoutPath,
-	LayoutDivider,
-	Layout,
-	ViewWindow,
-} from "./layout_config.ts";
+import type { LayoutPath, LayoutDivider, Layout, ViewWindow } from "./types.ts";
+
+const VIEW_WINDOW = {
+	row_start: 0,
+	row_end: 1,
+	col_start: 0,
+	col_end: 1,
+};
 
 /**
  * Determines which panel or divider is located at a given position in the
  * layout.
  *
- * @param row - Vertical position as a fraction (0-1) of the container
- * height
- * @param column - Horizontal position as a fraction (0-1) of the
- * container width
+ * @param column - Horizontal position as a fraction (0-1) of the container width
+ * @param row - Vertical position as a fraction (0-1) of the container height
  * @param layout - The layout tree to search
  * @param check_dividers - Whether `LayoutDivider` intersection should be
- * checked, which oyu may not want for e.g. `drop` actions.
+ * checked, which you may not want for e.g. `drop` actions.
  * @returns The panel path if over a panel, a divider if over a resizable
  * boundary, or null if outside all panels
  */
@@ -34,44 +34,37 @@ export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers: false,
-): LayoutPath;
+	check_dividers?: null,
+): LayoutPath | null;
 
 export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers: true,
+	check_dividers?: { rect: DOMRect; size: number },
 ): LayoutPath | null | LayoutDivider;
 
 export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers?: boolean,
+	check_dividers?: { rect: DOMRect; size: number } | null,
 ): LayoutPath | null | LayoutDivider;
 
 export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers: boolean = true,
+	check_dividers: { rect: DOMRect; size: number } | null = null,
 ): LayoutPath | null | LayoutDivider {
 	return calculate_intersection_recursive(column, row, layout, check_dividers);
 }
 
-const VIEW_WINDOW = {
-	row_start: 0,
-	row_end: 1,
-	col_start: 0,
-	col_end: 1,
-};
-
 function calculate_intersection_recursive(
 	column: number,
 	row: number,
 	panel: Layout,
-	check_dividers: boolean,
+	check_dividers: { rect: DOMRect; size: number } | null,
 	parent_orientation: "horizontal" | "vertical" | null = null,
 	view_window: ViewWindow = structuredClone(VIEW_WINDOW),
 	path: number[] = [],
@@ -83,104 +76,71 @@ function calculate_intersection_recursive(
 	// Base case: if this is a child panel, return its name
 	if (panel.type === "child-panel") {
 		const selected = panel.selected ?? 0;
-		const column_offset =
-			(column - view_window.col_start) /
-			(view_window.col_end - view_window.col_start);
-
-		const row_offset =
-			(row - view_window.row_start) /
-			(view_window.row_end - view_window.row_start);
-
+		const col_width = view_window.col_end - view_window.col_start;
+		const row_height = view_window.row_end - view_window.row_start;
 		return {
 			type: "layout-path",
-			box: undefined,
+			layout: undefined,
 			slot: panel.child[selected],
-			panel: structuredClone(panel),
-			path: path,
-			view_window: view_window,
+			path,
+			view_window,
 			is_edge: false,
 			column,
 			row,
-			column_offset,
-			row_offset,
+			column_offset: (column - view_window.col_start) / col_width,
+			row_offset: (row - view_window.row_start) / row_height,
 			orientation: parent_orientation || "horizontal",
 		};
 	}
 
 	// For split panels, determine which child was hit
-	if (panel.orientation === "vertical") {
-		// Vertical orientation = rows
-		let current_row = view_window.row_start;
-		for (let i = 0; i < panel.children.length; i++) {
-			const total_size = view_window.row_end - view_window.row_start;
-			const next_row = total_size * panel.sizes[i] + current_row;
-			if (check_dividers && Math.abs(row - next_row) < 0.01) {
+	const is_vertical = panel.orientation === "vertical";
+	const position = is_vertical ? row : column;
+	const start_key = is_vertical ? "row_start" : "col_start";
+	const end_key = is_vertical ? "row_end" : "col_end";
+	const rect_dim = is_vertical
+		? check_dividers?.rect?.height
+		: check_dividers?.rect?.width;
+
+	let current_pos = view_window[start_key];
+	const total_size = view_window[end_key] - view_window[start_key];
+	for (let i = 0; i < panel.children.length; i++) {
+		const next_pos = current_pos + total_size * panel.sizes[i];
+
+		// Check if position is on a divider
+		if (check_dividers && rect_dim) {
+			const divider_threshold = check_dividers.size / rect_dim;
+			if (Math.abs(position - next_pos) < divider_threshold) {
 				return {
 					path: [...path, i],
-					type: "vertical",
+					type: panel.orientation,
 					view_window: {
 						...view_window,
-						row_start: current_row,
-						row_end: next_row,
+						[start_key]: current_pos,
+						[end_key]: next_pos,
 					},
 				};
 			}
-
-			if (row >= current_row && row < next_row) {
-				return calculate_intersection_recursive(
-					column,
-					row,
-					panel.children[i],
-					check_dividers,
-					"vertical",
-					{
-						...view_window,
-						row_start: current_row,
-						row_end: next_row,
-					},
-					[...path, i],
-				);
-			}
-
-			current_row = next_row;
 		}
-	} else {
-		// Horizontal orientation = columns
-		let current_col = view_window.col_start;
-		for (let i = 0; i < panel.children.length; i++) {
-			const total_size = view_window.col_end - view_window.col_start;
-			const next_col = current_col + total_size * panel.sizes[i];
-			if (check_dividers && Math.abs(column - next_col) < 0.01) {
-				return {
-					path: [...path, i],
-					type: "horizontal",
-					view_window: {
-						...view_window,
-						col_start: current_col,
-						col_end: next_col,
-					},
-				};
-			}
-
-			// Check if the column falls within this child's bounds.
-			if (column >= current_col && column < next_col) {
-				return calculate_intersection_recursive(
-					column,
-					row,
-					panel.children[i],
-					check_dividers,
-					"horizontal",
-					{
-						...view_window,
-						col_start: current_col,
-						col_end: next_col,
-					},
-					[...path, i],
-				);
-			}
 
-			current_col = next_col;
+		// Check if position falls within this child's bounds
+		if (position >= current_pos && position < next_pos) {
+			return calculate_intersection_recursive(
+				column,
+				row,
+				panel.children[i],
+				check_dividers,
+				panel.orientation,
+				{
+					...view_window,
+					[start_key]: current_pos,
+					[end_key]: next_pos,
+				},
+				[...path, i],
+			);
 		}
+
+		current_pos = next_pos;
 	}
 
 	// If we get here, the hit was outside all children (possibly in a gap or

package/src/layout/constants.ts

@@ -0,0 +1,119 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  Copyright (c) 2026, the Regular Layout Authors. This file is part  *  ┃
+// ┃  *  of the Regular Layout library, distributed under the terms of the  *  ┃
+// ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import type { OverlayMode } from "./types";
+
+/**
+ * Instance-specific constants which define the behavior and rendering details
+ * of a `<regular-layout>`.
+ */
+export interface Physics {
+	/**
+	 * The prefix to use for `CustomEvent`s generated by `regular-layout`, e.g.
+	 * `"regular-layout-before-update"`.
+	 */
+	CUSTOM_EVENT_NAME_PREFIX: string;
+
+	/**
+	 * The attribute name to use for matching child `Element`s to grid
+	 * positions.
+	 */
+	CHILD_ATTRIBUTE_NAME: string;
+
+	/**
+	 * The minimum number of pixels the mouse must move to be considered a drag.
+	 */
+	MIN_DRAG_DISTANCE: number;
+
+	/**
+	 * Should floating point pixel calculations be rounded. Useful for testing.
+	 */
+	SHOULD_ROUND: boolean;
+
+	/**
+	 * Class name to use for child elements in overlay position (dragging).
+	 */
+	OVERLAY_CLASSNAME: string;
+
+	/**
+	 * The percentage of the maximum resize distance that will be clamped.
+	 */
+	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD: number;
+
+	/**
+	 * Threshold from panel edge that is considered a split vs drop action.
+	 */
+	SPLIT_EDGE_TOLERANCE: number;
+
+	/**
+	 * Threshold from _container_ edge that is considered a split action on the root
+	 * node.
+	 */
+	SPLIT_ROOT_EDGE_TOLERANCE: number;
+
+	/**
+	 * Tolerance threshold for considering two grid track positions as identical.
+	 *
+	 * When collecting and deduplicating track positions, any positions closer than
+	 * this value are treated as the same position to avoid redundant grid tracks.
+	 */
+	GRID_TRACK_COLLAPSE_TOLERANCE: number;
+
+	/**
+	 * The overlay default behavior.
+	 */
+	OVERLAY_DEFAULT: OverlayMode;
+
+	/**
+	 * Width of split panel dividers in pixels (for hit-test purposes).
+	 */
+	GRID_DIVIDER_SIZE: number;
+
+	/**
+	 * Whether the grid should trigger column resize if the grid itself is not
+	 * the `event.target`.
+	 */
+	GRID_DIVIDER_CHECK_TARGET: boolean;
+}
+
+/**
+ * Like `GlobalPhysics`, but suitable for partial definition for incremental
+ * updates.
+ */
+export interface PhysicsUpdate {
+	CUSTOM_EVENT_NAME_PREFIX?: string;
+	CHILD_ATTRIBUTE_NAME?: string;
+	MIN_DRAG_DISTANCE?: number;
+	SHOULD_ROUND?: boolean;
+	OVERLAY_CLASSNAME?: string;
+	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD?: number;
+	SPLIT_EDGE_TOLERANCE?: number;
+	SPLIT_ROOT_EDGE_TOLERANCE?: number;
+	GRID_TRACK_COLLAPSE_TOLERANCE?: number;
+	OVERLAY_DEFAULT?: OverlayMode;
+	GRID_DIVIDER_SIZE?: number;
+	GRID_DIVIDER_CHECK_TARGET?: boolean;
+}
+
+export const DEFAULT_PHYSICS: Physics = Object.freeze({
+	CUSTOM_EVENT_NAME_PREFIX: "regular-layout",
+	CHILD_ATTRIBUTE_NAME: "name",
+	MIN_DRAG_DISTANCE: 10,
+	SHOULD_ROUND: false,
+	OVERLAY_CLASSNAME: "overlay",
+	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD: 0.15,
+	SPLIT_EDGE_TOLERANCE: 0.25,
+	SPLIT_ROOT_EDGE_TOLERANCE: 0.01,
+	GRID_TRACK_COLLAPSE_TOLERANCE: 0.001,
+	OVERLAY_DEFAULT: "absolute",
+	GRID_DIVIDER_SIZE: 6,
+	GRID_DIVIDER_CHECK_TARGET: true,
+});

package/src/{common → layout}/flatten.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout } from "./layout_config.ts";
+import type { Layout } from "./types.ts";
 
 /**
  * Flattens the layout tree by merging parent and child split panels that have