regular-layout 0.1.0 → 0.2.0

package/src/{common → layout}/insert_child.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";
 
 /**
  * Inserts a new child panel into the layout tree at a specified location.
@@ -22,15 +22,20 @@ import type { Layout } from "./layout_config.ts";
  * at root level.
  * @param orientation - Orientation for newly created split panels. Defaults to
  * "horizontal".
+ * @param is_edge - If true, create the split at the parent level.
  * @returns A new layout tree with the child inserted (original is not mutated).
  */
 export function insert_child(
 	panel: Layout,
 	child: string,
 	path: number[],
-	orientation: "horizontal" | "vertical" = "horizontal",
-	is_edge?: boolean,
+	orientation?: "horizontal" | "vertical",
 ): Layout {
+	const createChildPanel = (childId: string): Layout => ({
+		type: "child-panel",
+		child: [childId],
+	});
+
 	if (path.length === 0) {
 		// Insert at root level
 		if (panel.type === "child-panel") {
@@ -39,92 +44,136 @@ export function insert_child(
 				type: "child-panel",
 				child: [child, ...panel.child],
 			};
+		} else if (orientation) {
+			// When inserting at edge of root, wrap the entire panel in a new split
+			return {
+				type: "split-panel",
+				orientation: orientation,
+				children: [createChildPanel(child), panel],
+				sizes: [0.5, 0.5],
+			};
 		} else {
 			// Append to existing split-panel
-			const newChildren = [
-				...panel.children,
-				{
-					type: "child-panel",
-					child: [child],
-				} as Layout,
-			];
-
-			const numChildren = newChildren.length;
-			const newSizes = Array(numChildren).fill(1 / numChildren);
+			const newChildren = [...panel.children, createChildPanel(child)];
+			const newSizes = [...panel.sizes, 1 / (newChildren.length - 1)];
 			return {
 				...panel,
 				children: newChildren,
-				sizes: newSizes,
+				sizes: redistribute(newSizes),
 			};
 		}
 	}
 
 	// Navigate down the path
 	const [index, ...restPath] = path;
+
+	// Special case: when orientation is provided and restPath is empty, handle edge insertion
+	if (orientation && restPath.length === 0) {
+		// If panel is a split-panel with the same orientation, insert into its children
+		if (panel.type === "split-panel" && panel.orientation === orientation) {
+			const newChildren = [...panel.children];
+			newChildren.splice(index, 0, createChildPanel(child));
+			const newSizes = [...panel.sizes];
+			newSizes.splice(index, 0, 1 / (newChildren.length - 1));
+			return {
+				...panel,
+				children: newChildren,
+				sizes: redistribute(newSizes),
+			};
+		}
+
+		// Otherwise, wrap the entire panel in a new split at the edge
+		const children =
+			index === 0
+				? [createChildPanel(child), panel]
+				: [panel, createChildPanel(child)];
+
+		return {
+			type: "split-panel",
+			orientation: orientation,
+			children,
+			sizes: [0.5, 0.5],
+		};
+	}
+
 	if (panel.type === "child-panel") {
-		// This shouldn't happen if path.length > 0, but handle it gracefully
-		// We need to split this child-panel
+		// Stack into child array only when ALL of these conditions are met:
+		// 1. Path has exactly one element (restPath is empty)
+		// 2. Orientation was NOT explicitly provided (orientation is undefined)
+		// 3. Index is within the valid stacking range [0, child.length]
+		if (
+			restPath.length === 0 &&
+			orientation === undefined &&
+			index >= 0 &&
+			index <= panel.child.length
+		) {
+			const newChild = [...panel.child];
+			newChild.splice(index, 0, child);
+			return {
+				...panel,
+				child: newChild,
+			};
+		}
+
+		// Otherwise, wrap in a split panel and recurse
 		const newPanel: Layout = {
 			type: "split-panel",
-			orientation,
+			orientation: orientation || "horizontal",
 			children: [panel],
 			sizes: [1],
 		};
 
-		return insert_child(newPanel, child, path, orientation, is_edge);
+		return insert_child(newPanel, child, path, orientation);
 	}
 
 	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;
+		if (orientation && panel.children[index]) {
+			// When inserting at an edge, create a split panel with the new child and existing child
+			const newSplitPanel: Layout = {
+				type: "split-panel",
+				orientation: orientation,
+				children: [createChildPanel(child), panel.children[index]],
+				sizes: [0.5, 0.5],
+			};
+
+			const newChildren = [...panel.children];
+			newChildren[index] = newSplitPanel;
+			return {
+				...panel,
+				children: newChildren,
+				sizes: redistribute(panel.sizes),
+			};
 		}
 
 		// Insert at this level at the specified index
 		const newChildren = [...panel.children];
-		newChildren.splice(index, 0, {
-			type: "child-panel",
-			child: [child],
-		});
-
-		const numChildren = newChildren.length;
-		const newSizes = Array(numChildren).fill(1 / numChildren);
+		newChildren.splice(index, 0, createChildPanel(child));
+		const newSizes = [...panel.sizes];
+		newSizes.splice(index, 0, 1 / (newChildren.length - 1));
 		return {
 			...panel,
 			children: newChildren,
-			sizes: newSizes,
+			sizes: redistribute(newSizes),
 		};
 	}
 
 	const targetChild = panel.children[index];
-	if (targetChild.type === "child-panel" && restPath.length > 0) {
-		// Need to split this child-panel
-		const oppositeOrientation =
-			panel.orientation === "horizontal" ? "vertical" : "horizontal";
-
-		const newSplitPanel = insert_child(
-			targetChild,
-			child,
-			restPath,
-			oppositeOrientation,
-			is_edge,
-		);
 
-		const newChildren = [...panel.children];
-		newChildren[index] = newSplitPanel;
-		return {
-			...panel,
-			children: newChildren,
-		};
-	}
+	// Determine the orientation to pass down when navigating into a child-panel
+	const childOrientation =
+		targetChild.type === "child-panel" &&
+		restPath.length > 0 &&
+		orientation !== undefined
+			? panel.orientation === "horizontal"
+				? "vertical"
+				: "horizontal"
+			: orientation;
 
 	const updatedChild = insert_child(
 		targetChild,
 		child,
 		restPath,
-		orientation,
-		is_edge,
+		childOrientation,
 	);
 
 	const newChildren = [...panel.children];
@@ -134,3 +183,8 @@ export function insert_child(
 		children: newChildren,
 	};
 }
+
+function redistribute(arr: number[]): number[] {
+	const total = arr.reduce((sum, val) => sum + val, 0);
+	return arr.map((val) => val / total);
+}

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

@@ -10,7 +10,7 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 import { MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD } from "./constants.ts";
-import type { Layout } from "./layout_config.ts";
+import type { Layout } from "./types.ts";
 
 /**
  * Adjusts panel sizes during a drag operation on a divider.

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

@@ -9,8 +9,8 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout, TabLayout } from "./layout_config.ts";
-import { EMPTY_PANEL } from "./layout_config.ts";
+import type { Layout, TabLayout } from "./types.ts";
+import { EMPTY_PANEL } from "./types.ts";
 
 /**
  * Removes a child panel from the layout tree by its name.

package/src/{common/layout_config.ts → layout/types.ts}

@@ -40,6 +40,11 @@ export interface ViewWindow {
  * Child panels are arranged either horizontally (side by side) or vertically
  * (stacked), via the `orientation` property `"horizzontal"` and `"vertical"`
  * (respectively).
+ *
+ * While the type structure of `SplitLayout` allows nesting levels with the same
+ * `orientation`, calling `RegularLayout.restore` with such a `Layout` will be
+ * flattened to the equivalent layout with every child guaranteed to have the
+ * opposite `orientation` as its parent.
  */
 export interface SplitLayout {
 	type: "split-panel";
@@ -78,7 +83,6 @@ export interface LayoutDivider {
 export interface LayoutPath<T = undefined> {
 	type: "layout-path";
 	slot: string;
-	panel: TabLayout;
 	path: number[];
 	view_window: ViewWindow;
 	column: number;
@@ -87,24 +91,7 @@ export interface LayoutPath<T = undefined> {
 	row_offset: number;
 	orientation: Orientation;
 	is_edge: boolean;
-	box: T;
-}
-
-/**
- * Recursively iterates over all child panel names in the layout tree, yielding
- * panel names in depth-first order.
- *
- * @param panel - The layout tree to iterate over
- * @returns Generator yielding child panel names
- */
-export function* iter_panel_children(panel: Layout): Generator<string> {
-	if (panel.type === "split-panel") {
-		for (const child of panel.children) {
-			yield* iter_panel_children(child);
-		}
-	} else {
-		yield panel.child[panel.selected || 0];
-	}
+	layout: T;
 }
 
 /**

package/src/regular-layout-frame.ts

@@ -9,20 +9,26 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { MIN_DRAG_DISTANCE, OVERLAY_CLASSNAME } from "./common/constants.ts";
-import type { LayoutPath, TabLayout } from "./common/layout_config.ts";
+import { MIN_DRAG_DISTANCE, OVERLAY_CLASSNAME } from "./layout/constants.ts";
+import type { Layout, LayoutPath } from "./layout/types.ts";
 import type { RegularLayoutEvent } from "./extensions.ts";
 import type { RegularLayout } from "./regular-layout.ts";
-
-const CSS = (className: string) => `
-:host{--titlebar--height:24px;box-sizing:border-box}
-:host(:not(.${className})){margin-top:calc(var(--titlebar--height) + 3px)!important;}
-:host(:not(.${className}))::part(container){position:absolute;top:0;left:0;right:0;bottom:0;display:flex;flex-direction:column;background-color:inherit;border-radius:inherit}
-:host(:not(.${className}))::part(titlebar){height:var(--titlebar--height);margin-top:calc(0px - var(--titlebar--height));user-select: none;}
-:host(:not(.${className}))::part(body){flex:1 1 auto;}
+import type { RegularLayoutTab } from "./regular-layout-tab.ts";
+
+const CSS = `
+:host{box-sizing:border-box;flex-direction:column}
+:host::part(titlebar){display:flex;height:24px;user-select:none;overflow:hidden}
+:host::part(container){flex:1 1 auto}
+:host::part(title){flex:1 1 auto;pointer-events:none}
+:host::part(close){align-self:stretch}
+:host::slotted{flex:1 1 auto;}
+:host regular-layout-tab{width:0px;}
 `;
 
-const HTML_TEMPLATE = `<slot part="container"><slot part="titlebar"></slot><slot part="body"><slot></slot></slot></slot>`;
+const HTML_TEMPLATE = `
+	<div part="titlebar"></div>
+	<slot part="container"></slot>
+`;
 
 /**
  * A custom element that represents a draggable panel within a
@@ -43,7 +49,7 @@ const HTML_TEMPLATE = `<slot part="container"><slot part="titlebar"></slot><slot
  * @example
  * ```html
  * <regular-layout>
- *     <regular-layout-frame slot="panel-1">
+ *     <regular-layout-frame name="panel-1">
  *         <!-- Panel content here -->
  *     </regular-layout-frame>
  * </regular-layout>
@@ -54,14 +60,13 @@ export class RegularLayoutFrame extends HTMLElement {
 	private _container_sheet: CSSStyleSheet;
 	private _layout!: RegularLayout;
 	private _header!: HTMLElement;
-	private _drag_state: LayoutPath<DOMRect> | null = null;
+	private _drag_state: LayoutPath<Layout> | null = null;
 	private _drag_moved: boolean = false;
-	private _tab_to_index_map: WeakMap<HTMLDivElement, number> = new WeakMap();
-	private _tab_panel_state: TabLayout | null = null;
+	private _tab_to_index_map: WeakMap<RegularLayoutTab, number> = new WeakMap();
 	constructor() {
 		super();
 		this._container_sheet = new CSSStyleSheet();
-		this._container_sheet.replaceSync(CSS(OVERLAY_CLASSNAME));
+		this._container_sheet.replaceSync(CSS);
 		this._shadowRoot = this.attachShadow({ mode: "open" });
 		this._shadowRoot.adoptedStyleSheets = [this._container_sheet];
 	}
@@ -69,7 +74,7 @@ export class RegularLayoutFrame extends HTMLElement {
 	connectedCallback() {
 		this._shadowRoot.innerHTML = HTML_TEMPLATE;
 		this._layout = this.parentElement as RegularLayout;
-		this._header = this._shadowRoot.children[0].children[0] as HTMLElement;
+		this._header = this._shadowRoot.children[0] as HTMLElement;
 		this._header.addEventListener("pointerdown", this.onPointerDown);
 		this._header.addEventListener("pointermove", this.onPointerMove);
 		this._header.addEventListener("pointerup", this.onPointerUp);
@@ -94,7 +99,7 @@ export class RegularLayoutFrame extends HTMLElement {
 	}
 
 	private onPointerDown = (event: PointerEvent): void => {
-		const elem = event.target as HTMLDivElement;
+		const elem = event.target as RegularLayoutTab;
 		if (elem.part.contains("tab")) {
 			this._drag_state = this._layout.calculateIntersect(
 				event.clientX,
@@ -104,11 +109,6 @@ export class RegularLayoutFrame extends HTMLElement {
 			if (this._drag_state) {
 				this._header.setPointerCapture(event.pointerId);
 				event.preventDefault();
-				const last_index = this._drag_state.path.length - 1;
-				const selected = this._tab_to_index_map.get(elem);
-				if (selected) {
-					this._drag_state.path[last_index] = selected;
-				}
 			}
 		}
 	};
@@ -165,35 +165,30 @@ export class RegularLayoutFrame extends HTMLElement {
 	};
 
 	private drawTabs = (event: RegularLayoutEvent) => {
-		const slot = this.assignedSlot;
+		const slot = this.getAttribute("name");
 		if (!slot) {
 			return;
 		}
 
 		const new_panel = event.detail;
-		const new_tab_panel = this._layout.getPanel(slot.name, new_panel);
+		let new_tab_panel = this._layout.getPanel(slot, new_panel);
 		if (!new_tab_panel) {
-			return;
+			new_tab_panel = {
+				type: "child-panel",
+				child: [slot],
+				selected: 0,
+			};
 		}
 
 		for (let i = 0; i < new_tab_panel.child.length; i++) {
 			if (i >= this._header.children.length) {
-				const new_tab = this.createTab(new_tab_panel, i);
+				const new_tab = document.createElement("regular-layout-tab");
+				new_tab.populate(this._layout, new_tab_panel, i);
 				this._header.appendChild(new_tab);
+				this._tab_to_index_map.set(new_tab, i);
 			} else {
-				const tab_changed =
-					(i === new_tab_panel.selected) !==
-					(i === this._tab_panel_state?.selected);
-
-				const tab = this._header.children[i] as HTMLDivElement;
-				const index_changed =
-					tab_changed ||
-					this._tab_panel_state?.child[i] !== new_tab_panel.child[i];
-
-				if (index_changed) {
-					const new_tab = this.createTab(new_tab_panel, i);
-					this._header.replaceChild(new_tab, tab);
-				}
+				const tab = this._header.children[i] as RegularLayoutTab;
+				tab.populate(this._layout, new_tab_panel, i);
 			}
 		}
 
@@ -201,37 +196,5 @@ export class RegularLayoutFrame extends HTMLElement {
 		for (let j = this._header.children.length - 1; j >= last_index; j--) {
 			this._header.removeChild(this._header.children[j]);
 		}
-
-		this._tab_panel_state = new_tab_panel;
-	};
-
-	private createTab = (tab_panel: TabLayout, index: number): HTMLDivElement => {
-		const selected = tab_panel.selected || 0;
-		const tab = document.createElement("div");
-		this._tab_to_index_map.set(tab, index);
-		tab.textContent = tab_panel.child[index] || "";
-		if (index === selected) {
-			tab.setAttribute("part", "tab active-tab");
-		} else {
-			tab.setAttribute("part", "tab");
-			tab.addEventListener("pointerdown", (_) =>
-				this.onTabClick(tab_panel, index),
-			);
-		}
-
-		return tab;
-	};
-
-	private onTabClick = (tab_panel: TabLayout, index: number) => {
-		const new_layout = this._layout.save();
-		const new_tab_panel = this._layout.getPanel(
-			tab_panel.child[index],
-			new_layout,
-		);
-
-		if (new_tab_panel) {
-			new_tab_panel.selected = index;
-			this._layout.restore(new_layout);
-		}
 	};
 }

package/src/regular-layout-tab.ts

@@ -0,0 +1,103 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { TabLayout } from "./layout/types.ts";
+import type { RegularLayout } from "./regular-layout.ts";
+
+/**
+ * A custom HTML element representing an individual tab in a tab panel.
+ *
+ * This element manages the visual representation and interactions for a single tab,
+ * including selection state, close functionality, and content display.
+ */
+export class RegularLayoutTab extends HTMLElement {
+	private _layout?: RegularLayout;
+	private _tab_panel?: TabLayout;
+	private _index?: number;
+
+	/**
+	 * Populates or updates the tab with layout information.
+	 *
+	 * This method initializes the tab's content and event listeners on first call,
+	 * and efficiently updates only the changed properties on subsequent calls.
+	 *
+	 * @param layout - The parent RegularLayout instance managing this tab.
+	 * @param tab_panel - The tab panel layout containing this tab.
+	 * @param index - The index of this tab within the tab panel.
+	 */
+	populate = (layout: RegularLayout, tab_panel: TabLayout, index: number) => {
+		if (this._tab_panel) {
+			const tab_changed =
+				(index === tab_panel.selected) !==
+				(index === this._tab_panel?.selected);
+
+			const index_changed =
+				tab_changed || this._tab_panel?.child[index] !== tab_panel.child[index];
+
+			if (index_changed) {
+				const selected = tab_panel.selected === index;
+				const slot = tab_panel.child[index];
+				this.children[0].textContent = slot;
+
+				if (selected) {
+					this.children[1].part.add("active-close");
+					this.part.add("active-tab");
+				} else {
+					this.children[1].part.remove("active-close");
+					this.part.remove("active-tab");
+				}
+			}
+		} else {
+			const slot = tab_panel.child[index];
+			const selected = tab_panel.selected === index;
+			const parts = selected ? "active-close close" : "close";
+			this.innerHTML = `<div part="title"></div><button part="${parts}"></button>`;
+			if (selected) {
+				this.part.add("tab", "active-tab");
+			} else {
+				this.part.add("tab");
+			}
+
+			this.addEventListener("pointerdown", this.onTabClick);
+			this.children[0].textContent = slot;
+			this.children[1].addEventListener("pointerdown", this.onTabClose);
+		}
+
+		this._tab_panel = tab_panel;
+		this._layout = layout;
+		this._index = index;
+	};
+
+	private onTabClose = (_: Event) => {
+		if (this._tab_panel !== undefined && this._index !== undefined) {
+			this._layout?.removePanel(this._tab_panel.child[this._index]);
+		}
+	};
+
+	private onTabClick = (_: PointerEvent) => {
+		if (
+			this._tab_panel !== undefined &&
+			this._index !== undefined &&
+			this._index !== this._tab_panel.selected
+		) {
+			const new_layout = this._layout?.save();
+			const new_tab_panel = this._layout?.getPanel(
+				this._tab_panel.child[this._index],
+				new_layout,
+			);
+
+			if (new_tab_panel && new_layout) {
+				new_tab_panel.selected = this._index;
+				this._layout?.restore(new_layout);
+			}
+		}
+	};
+}