regular-layout 0.0.2 → 0.1.0

package/dist/regular-layout-frame.d.ts

@@ -31,12 +31,15 @@ export declare class RegularLayoutFrame extends HTMLElement {
     private _drag_state;
     private _drag_moved;
     private _tab_to_index_map;
+    private _tab_panel_state;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private drawTabs;
     private onPointerDown;
     private onPointerMove;
     private onPointerUp;
     private onPointerLost;
+    private drawTabs;
+    private createTab;
+    private onTabClick;
 }

package/dist/regular-layout.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutPath, Layout, TabLayout } from "./common/layout_config.ts";
+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.
@@ -48,46 +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;
-    getPanel(name: string, layout?: Layout): TabLayout | null;
+    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;
-    clear(): void;
+    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.
      *
@@ -100,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`.
      *
@@ -113,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.2",
+	"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

@@ -86,6 +86,7 @@ function calculate_intersection_recursive(
 		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);
@@ -98,6 +99,8 @@ function calculate_intersection_recursive(
 			path: path,
 			view_window: view_window,
 			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;
 	}
 

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 {

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

@@ -77,6 +77,7 @@ export function insert_child(
 	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;
 		}
 

package/src/common/layout_config.ts

@@ -9,34 +9,10 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-/**
- * 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";
-
 /**
  * The overlay behavior type.
  */
-export type OverlayMode = "grid" | "absolute" | "interactive";
+export type OverlayMode = "grid" | "absolute";
 
 /**
  * The representation of a CSS grid, in JSON form.
@@ -105,6 +81,8 @@ export interface LayoutPath<T = undefined> {
 	panel: TabLayout;
 	path: number[];
 	view_window: ViewWindow;
+	column: number;
+	row: number;
 	column_offset: number;
 	row_offset: number;
 	orientation: Orientation;
@@ -125,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.

package/src/common/remove_child.ts

@@ -36,6 +36,7 @@ export function remove_child(panel: Layout, child: string): Layout {
 				child: newChild,
 			};
 		}
+
 		return structuredClone(panel);
 	}
 

package/src/extensions.ts

@@ -11,7 +11,7 @@
 
 import { RegularLayout } from "./regular-layout.ts";
 import { RegularLayoutFrame } from "./regular-layout-frame.ts";
-import { Layout } from "./common/layout_config.ts";
+import type { Layout } from "./common/layout_config.ts";
 
 customElements.define("regular-layout", RegularLayout);
 customElements.define("regular-layout-frame", RegularLayoutFrame);
@@ -45,20 +45,24 @@ declare global {
 			options?: { signal: AbortSignal },
 		): void;
 
-		removeEventListener(name: "regular-layout-update", cb: any): void;
+		addEventListener(
+			name: "regular-layout-before-update",
+			cb: (e: RegularLayoutEvent) => void,
+			options?: { signal: AbortSignal },
+		): void;
+
+		removeEventListener(
+			name: "regular-layout-update",
+			cb: (e: RegularLayoutEvent) => void,
+		): void;
+
+		removeEventListener(
+			name: "regular-layout-before-update",
+			cb: (e: RegularLayoutEvent) => void,
+		): void;
 	}
 }
 
 export interface RegularLayoutEvent extends CustomEvent {
 	detail: Layout;
 }
-
-export interface PerspectiveViewerElementExt {
-	addEventListener(
-		name: "regular-layout-update",
-		cb: (e: RegularLayoutEvent) => void,
-		options?: { signal: AbortSignal },
-	): void;
-
-	removeEventListener(name: "regular-layout-update", cb: any): void;
-}