regular-layout 0.0.1 → 0.1.0

package/dist/regular-layout.d.ts

@@ -1,5 +1,4 @@
-import type { LayoutPath, Layout } from "./common/layout_config.ts";
-export type OverlayMode = "grid" | "absolute" | "interactive";
+import type { LayoutPath, Layout, TabLayout, OverlayMode } from "./common/layout_config.ts";
 /**
  * A Web Component that provides a resizable panel layout system.
  * Panels are arranged using CSS Grid and can be resized by dragging dividers.
@@ -49,44 +48,61 @@ export declare class RegularLayout extends HTMLElement {
      *
      * @param x - X coordinate in screen pixels.
      * @param y - Y coordinate in screen pixels.
-     * @param layoutPath - Layout path containing the slot identifier.
-     * @param mode - Overlay rendering mode: "grid" highlights the target,
-     *   "absolute" positions the panel absolutely, "interactive" updates the
-     *   actual layout in real-time. Defaults to "absolute".
+     * @param dragTarget - A `LayoutPath` (presumably from `calculateIntersect`)
+     *     which points to the drag element in the current layout.
+     * @param className - The CSS class name to use for the overlay panel
+     *     (defaults to "overlay").
+     * @param mode - Overlay rendering mode: "grid" uses CSS grid to position
+     *     the target, "absolute" positions the panel absolutely. Defaults to
+     *     "absolute".
      */
-    setOverlayState<T>(x: number, y: number, { slot }: LayoutPath<T>, mode?: "grid" | "absolute" | "interactive"): void;
+    setOverlayState: (x: number, y: number, { slot }: LayoutPath<unknown>, className?: string, mode?: OverlayMode) => void;
     /**
      * Clears the overlay state and commits the panel placement.
      *
      * @param x - X coordinate in screen pixels.
      * @param y - Y coordinate in screen pixels.
-     * @param layout_path - Layout path containing the slot identifier.
+     * @param dragTarget - A `LayoutPath` (presumably from `calculateIntersect`)
+     *     which points to the drag element in the current layout.
+     * @param className - The CSS class name to use for the overlay panel
+     *     (defaults to "overlay").
      * @param mode - Overlay rendering mode that was used, must match the mode
-     *   passed to `setOverlayState`. Defaults to "absolute".
+     *     passed to `setOverlayState`. Defaults to "absolute".
      */
-    clearOverlayState<T>(x: number, y: number, drag_target: LayoutPath<T>, mode?: "grid" | "absolute" | "interactive"): void;
+    clearOverlayState: (x: number, y: number, drag_target: LayoutPath<unknown>, className?: string, mode?: OverlayMode) => void;
     /**
      * Inserts a new panel into the layout at a specified path.
      *
      * @param name - Unique identifier for the new panel.
      * @param path - Index path defining where to insert.
      */
-    insertPanel(name: string, path?: number[]): void;
+    insertPanel: (name: string, path?: number[]) => void;
     /**
      * Removes a panel from the layout by name.
      *
      * @param name - Name of the panel to remove
      */
-    removePanel(name: string): void;
+    removePanel: (name: string) => void;
+    /**
+     * Retrieves a panel by name from the layout tree.
+     *
+     * @param name - Name of the panel to find.
+     * @param layout - Optional layout tree to search in (defaults to current layout).
+     * @returns The TabLayout containing the panel if found, null otherwise.
+     */
+    getPanel: (name: string, layout?: Layout) => TabLayout | null;
     /**
      * Determines which panel is at a given screen coordinate.
-     * Useful for drag-and-drop operations or custom interactions.
      *
      * @param column - X coordinate in screen pixels.
      * @param row - Y coordinate in screen pixels.
      * @returns Panel information if a panel is at that position, null otherwise.
      */
-    calculateIntersect(x: number, y: number, check_dividers?: boolean): LayoutPath<DOMRect> | null;
+    calculateIntersect: (x: number, y: number, check_dividers?: boolean) => LayoutPath<DOMRect> | null;
+    /**
+     * Clears the entire layout, unslotting all panels.
+     */
+    clear: () => void;
     /**
      * Restores the layout from a saved state.
      *
@@ -99,7 +115,7 @@ export declare class RegularLayout extends HTMLElement {
      * layout.restore(savedState);
      * ```
      */
-    restore(layout: Layout, _is_flattened?: boolean): void;
+    restore: (layout: Layout, _is_flattened?: boolean) => void;
     /**
      * Serializes the current layout state, which can be restored via `restore`.
      *
@@ -112,8 +128,22 @@ export declare class RegularLayout extends HTMLElement {
      * localStorage.setItem('layout', JSON.stringify(state));
      * ```
      */
-    save(): Layout;
-    private relativeCoordinates;
+    save: () => Layout;
+    /**
+     * Converts screen coordinates to relative layout coordinates.
+     *
+     * Transforms absolute pixel positions into normalized coordinates (0-1 range)
+     * relative to the layout's bounding box.
+     *
+     * @param clientX - X coordinate in screen pixels (client space).
+     * @param clientY - Y coordinate in screen pixels (client space).
+     * @returns A tuple containing:
+     *   - col: Normalized X coordinate (0 = left edge, 1 = right edge)
+     *   - row: Normalized Y coordinate (0 = top edge, 1 = bottom edge)
+     *   - box: The layout element's bounding rectangle
+     */
+    relativeCoordinates: (clientX: number, clientY: number) => [number, number, DOMRect];
+    private updateSlots;
     private onPointerDown;
     private onPointerMove;
     private onPointerUp;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "regular-layout",
-	"version": "0.0.1",
+	"version": "0.1.0",
 	"description": "A regular CSS `grid` container",
 	"keywords": [],
 	"license": "Apache-2.0",
@@ -20,6 +20,7 @@
 		"clean": "rm -rf dist",
 		"test": "playwright test",
 		"example": "npx http-server . -p 8000",
+		"deploy": "node deploy.mjs",
 		"lint": "biome lint src tests",
 		"format": "biome format --write src tests",
 		"check": "biome check --write src tests"

package/src/common/calculate_edge.ts

@@ -0,0 +1,104 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { calculate_intersection } from "./calculate_intersect";
+import { SPLIT_EDGE_TOLERANCE } from "./constants";
+import { insert_child } from "./insert_child";
+import type { Layout, LayoutPath, Orientation } from "./layout_config";
+
+/**
+ * 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,
+): LayoutPath {
+	const is_column_edge =
+		drop_target.column_offset < SPLIT_EDGE_TOLERANCE ||
+		drop_target.column_offset > 1 - SPLIT_EDGE_TOLERANCE;
+
+	const is_row_edge =
+		drop_target.row_offset < SPLIT_EDGE_TOLERANCE ||
+		drop_target.row_offset > 1 - SPLIT_EDGE_TOLERANCE;
+
+	if (is_column_edge) {
+		return handle_axis(
+			col,
+			row,
+			panel,
+			slot,
+			drop_target,
+			drop_target.column_offset,
+			"horizontal",
+		);
+	} else if (is_row_edge) {
+		return handle_axis(
+			col,
+			row,
+			panel,
+			slot,
+			drop_target,
+			drop_target.row_offset,
+			"vertical",
+		);
+	}
+
+	return drop_target;
+}
+
+function handle_axis(
+	col: number,
+	row: number,
+	panel: Layout,
+	slot: string,
+	drop_target: LayoutPath,
+	axis_offset: number,
+	axis_orientation: Orientation,
+): LayoutPath {
+	const is_before = axis_offset < SPLIT_EDGE_TOLERANCE;
+	if (drop_target.orientation === axis_orientation) {
+		if (drop_target.path.length === 0) {
+			const insert_index = is_before ? 0 : 1;
+			const new_panel = insert_child(panel, slot, [insert_index]);
+			drop_target = calculate_intersection(col, row, new_panel, false);
+		} else {
+			const path_without_last = drop_target.path.slice(0, -1);
+			const last_index = drop_target.path[drop_target.path.length - 1];
+			const insert_index = is_before ? last_index : last_index + 1;
+			const new_panel = insert_child(panel, slot, [
+				...path_without_last,
+				insert_index,
+			]);
+
+			drop_target = calculate_intersection(col, row, new_panel, false);
+		}
+	} else {
+		const path = [...drop_target.path, is_before ? 0 : 1];
+		const new_panel = insert_child(panel, slot, path, axis_orientation);
+		drop_target = calculate_intersection(col, row, new_panel, false);
+	}
+
+	drop_target.is_edge = true;
+	return drop_target;
+}

package/src/common/calculate_intersect.ts

@@ -72,25 +72,38 @@ function calculate_intersection_recursive(
 	row: number,
 	panel: Layout,
 	check_dividers: boolean,
-	parent_orientation: "horizontal" | "vertical" = "horizontal",
+	parent_orientation: "horizontal" | "vertical" | null = null,
 	view_window: ViewWindow = structuredClone(VIEW_WINDOW),
 	path: number[] = [],
 ): LayoutPath | null | LayoutDivider {
+	if (column < 0 || row < 0 || column > 1 || row > 1) {
+		return null;
+	}
+
 	// 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);
+
 		return {
 			type: "layout-path",
 			box: undefined,
-			slot: panel.child,
+			slot: panel.child[selected],
+			panel: structuredClone(panel),
 			path: path,
 			view_window: view_window,
-			column_offset:
-				(column - view_window.col_start) /
-				(view_window.col_end - view_window.col_start),
-			row_offset:
-				(row - view_window.row_start) /
-				(view_window.row_end - view_window.row_start),
-			orientation: parent_orientation,
+			is_edge: false,
+			column,
+			row,
+			column_offset,
+			row_offset,
+			orientation: parent_orientation || "horizontal",
 		};
 	}
 

package/src/common/constants.ts

@@ -0,0 +1,46 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 "./layout_config";
+
+/**
+ * The minimum number of pixels the mouse must move to be considered a drag.
+ */
+export const MIN_DRAG_DISTANCE = 10;
+
+/**
+ * Class name to use for child elements in overlay position (dragging).
+ */
+export const OVERLAY_CLASSNAME = "overlay";
+
+/**
+ * The percentage of the maximum resize distance that will be clamped.
+ *
+ */
+export const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
+
+/**
+ * Threshold from panel edge that is considered a split vs drop action.
+ */
+export const SPLIT_EDGE_TOLERANCE = 0.25;
+
+/**
+ * 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.
+ */
+export const GRID_TRACK_COLLAPSE_TOLERANCE = 0.001;
+
+/**
+ * The overlay default behavior.
+ */
+export const OVERLAY_DEFAULT: OverlayMode = "absolute";

package/src/common/flatten.ts

@@ -24,6 +24,7 @@ import type { Layout } from "./layout_config.ts";
  */
 export function flatten(layout: Layout): Layout {
 	if (layout.type === "child-panel") {
+		layout.selected = layout.selected || 0;
 		return layout;
 	}
 
@@ -48,6 +49,10 @@ export function flatten(layout: Layout): Layout {
 		}
 	}
 
+	if (flattenedChildren.length === 1) {
+		return flattenedChildren[0];
+	}
+
 	return {
 		type: "split-panel",
 		orientation: layout.orientation,

package/src/common/generate_grid.ts

@@ -9,7 +9,8 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { GRID_TRACK_COLLAPSE_TOLERANCE, type Layout } from "./layout_config.ts";
+import { GRID_TRACK_COLLAPSE_TOLERANCE } from "./constants.ts";
+import type { Layout } from "./layout_config.ts";
 import { remove_child } from "./remove_child.ts";
 
 interface GridCell {
@@ -85,7 +86,7 @@ function collectTrackPositions(
 
 function findTrackIndex(positions: number[], value: number): number {
 	for (let i = 0; i < positions.length; i++) {
-		if (Math.abs(positions[i] - value) < 0.0001) {
+		if (Math.abs(positions[i] - value) < GRID_TRACK_COLLAPSE_TOLERANCE) {
 			return i;
 		}
 	}
@@ -103,9 +104,10 @@ function buildCells(
 	rowEnd: number,
 ): GridCell[] {
 	if (panel.type === "child-panel") {
+		const selected = panel.selected ?? 0;
 		return [
 			{
-				child: panel.child,
+				child: panel.child[selected],
 				colStart: findTrackIndex(colPositions, colStart),
 				colEnd: findTrackIndex(colPositions, colEnd),
 				rowStart: findTrackIndex(rowPositions, rowStart),
@@ -203,7 +205,8 @@ export function create_css_grid_layout(
 	}
 
 	if (layout.type === "child-panel") {
-		return `${host_template("100%", "100%")}\n${child_template(layout.child, "1", "1")}`;
+		const selected = layout.selected ?? 0;
+		return `${host_template("100%", "100%")}\n${child_template(layout.child[selected], "1", "1")}`;
 	}
 
 	const colPositions = collectTrackPositions(layout, "horizontal", 0, 1);

package/src/common/generate_overlay.ts

@@ -11,15 +11,18 @@
 
 import type { LayoutPath } from "./layout_config";
 
-export function updateOverlaySheet({
-	view_window: { row_start, row_end, col_start, col_end },
-	box,
-}: LayoutPath<DOMRect>) {
+export function updateOverlaySheet(
+	slot: string,
+	{
+		view_window: { row_start, row_end, col_start, col_end },
+		box,
+	}: LayoutPath<DOMRect>,
+) {
 	const margin = 0;
 	const top = row_start * box.height + margin / 2;
 	const left = col_start * box.width + margin / 2;
 	const height = (row_end - row_start) * box.height - margin;
 	const width = (col_end - col_start) * box.width - margin;
 	const css = `position:absolute!important;z-index:1;top:${top}px;left:${left}px;height:${height}px;width:${width}px;`;
-	return `::slotted(:not([slot])){${css}}`;
+	return `::slotted([slot="${slot}"]){${css}}`;
 }

package/src/common/insert_child.ts

@@ -29,22 +29,15 @@ export function insert_child(
 	child: string,
 	path: number[],
 	orientation: "horizontal" | "vertical" = "horizontal",
+	is_edge?: boolean,
 ): Layout {
 	if (path.length === 0) {
 		// Insert at root level
 		if (panel.type === "child-panel") {
-			// Convert single child-panel to split-panel with two children
+			// Add to existing child-panel as a tab
 			return {
-				type: "split-panel",
-				orientation,
-				children: [
-					panel,
-					{
-						type: "child-panel",
-						child,
-					},
-				],
-				sizes: [0.5, 0.5],
+				type: "child-panel",
+				child: [child, ...panel.child],
 			};
 		} else {
 			// Append to existing split-panel
@@ -52,7 +45,7 @@ export function insert_child(
 				...panel.children,
 				{
 					type: "child-panel",
-					child,
+					child: [child],
 				} as Layout,
 			];
 
@@ -78,15 +71,21 @@ export function insert_child(
 			sizes: [1],
 		};
 
-		return insert_child(newPanel, child, path, orientation);
+		return insert_child(newPanel, child, path, orientation, is_edge);
 	}
 
 	if (restPath.length === 0 || index === panel.children.length) {
+		if (is_edge && panel.children[index]?.type === "child-panel") {
+			panel.children[index].child.unshift(child);
+			panel.children[index].selected = 0;
+			return panel;
+		}
+
 		// Insert at this level at the specified index
 		const newChildren = [...panel.children];
 		newChildren.splice(index, 0, {
 			type: "child-panel",
-			child,
+			child: [child],
 		});
 
 		const numChildren = newChildren.length;
@@ -109,6 +108,7 @@ export function insert_child(
 			child,
 			restPath,
 			oppositeOrientation,
+			is_edge,
 		);
 
 		const newChildren = [...panel.children];
@@ -119,7 +119,14 @@ export function insert_child(
 		};
 	}
 
-	const updatedChild = insert_child(targetChild, child, restPath, orientation);
+	const updatedChild = insert_child(
+		targetChild,
+		child,
+		restPath,
+		orientation,
+		is_edge,
+	);
+
 	const newChildren = [...panel.children];
 	newChildren[index] = updatedChild;
 	return {

package/src/common/layout_config.ts

@@ -10,23 +10,9 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 /**
- * The percentage of the maximum resize distance that will be clamped.
- *
- */
-export const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
-
-/**
- * Threshold from panel edge that is considered a split vs drop action.
- */
-export const SPLIT_EDGE_TOLERANCE = 0.15;
-
-/**
- * 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.
+ * The overlay behavior type.
  */
-export const GRID_TRACK_COLLAPSE_TOLERANCE = 0.0001;
+export type OverlayMode = "grid" | "absolute";
 
 /**
  * The representation of a CSS grid, in JSON form.
@@ -67,7 +53,8 @@ export interface SplitLayout {
  */
 export interface TabLayout {
 	type: "child-panel";
-	child: string;
+	child: string[];
+	selected?: number;
 }
 
 /**
@@ -91,11 +78,15 @@ export interface LayoutDivider {
 export interface LayoutPath<T = undefined> {
 	type: "layout-path";
 	slot: string;
+	panel: TabLayout;
 	path: number[];
 	view_window: ViewWindow;
+	column: number;
+	row: number;
 	column_offset: number;
 	row_offset: number;
 	orientation: Orientation;
+	is_edge: boolean;
 	box: T;
 }
 
@@ -112,7 +103,7 @@ export function* iter_panel_children(panel: Layout): Generator<string> {
 			yield* iter_panel_children(child);
 		}
 	} else {
-		yield panel.child;
+		yield panel.child[panel.selected || 0];
 	}
 }
 

package/src/common/redistribute_panel_sizes.ts

@@ -9,10 +9,8 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import {
-	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD,
-	type Layout,
-} from "./layout_config.ts";
+import { MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD } from "./constants.ts";
+import type { Layout } from "./layout_config.ts";
 
 /**
  * Adjusts panel sizes during a drag operation on a divider.
@@ -54,7 +52,11 @@ export function redistribute_panel_sizes(
 	if (current.type === "split-panel") {
 		const delta = deltas[current.orientation];
 		const index = path[path.length - 1];
-		current.sizes = add_and_redistribute(current.sizes, index, delta);
+
+		// It would be fun to remove this condition.
+		if (index < current.sizes.length - 1) {
+			current.sizes = add_and_redistribute(current.sizes, index, delta);
+		}
 	}
 
 	return result;