regular-layout 0.0.1

package/src/common/redistribute_panel_sizes.ts

@@ -0,0 +1,100 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 {
+	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD,
+	type Layout,
+} from "./layout_config.ts";
+
+/**
+ * Adjusts panel sizes during a drag operation on a divider.
+ *
+ * The `delta` is distributed proportionally among affected panels, maintaining
+ * the sum:
+ *
+ * - Panels before and including the path index shrink by delta.
+ * - Panels after the path index grow by delta.
+ *
+ * @param panel - The root layout tree to modify.
+ * @param path - Path to the divider being dragged (identifies which split panel
+ * to resize).
+ * @param delta - Amount to resize, as a fraction (0-1). Positive values grow
+ * panels before the divider, negative values shrink them.
+ * @returns A new layout tree with updated sizes (original is not mutated).
+ * ```
+ */
+export function redistribute_panel_sizes(
+	panel: Layout,
+	path: number[],
+	delta: number,
+): Layout {
+	// Clone the entire panel structure
+	const result = structuredClone(panel);
+
+	// Find the orientation of the insertion panel,
+	// and scale the delta on the respective axis if aligned.
+	let current: Layout = result;
+	const deltas = { horizontal: delta, vertical: delta };
+	for (let i = 0; i < path.length - 1; i++) {
+		if (current.type === "split-panel") {
+			deltas[current.orientation] /= current.sizes[path[i]];
+			current = current.children[path[i]];
+		}
+	}
+
+	// Apply the redistribution at the final path index
+	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);
+	}
+
+	return result;
+}
+
+function add_and_redistribute(
+	arr: number[],
+	index: number,
+	delta: number,
+): number[] {
+	const result = [...arr];
+	let before_total = 0;
+	for (let i = 0; i <= index; i++) {
+		before_total += arr[i];
+	}
+
+	let after_total = 0;
+	for (let i = index + 1; i < arr.length; i++) {
+		after_total += arr[i];
+	}
+
+	// Clamp `delta` to prevent redistributing either side to 0.
+	delta =
+		Math.sign(delta) *
+		Math.min(
+			Math.abs(delta),
+			(1 - MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD) *
+				(delta > 0 ? before_total : after_total),
+		);
+
+	// Redistribute elements
+	for (let i = 0; i <= index; i++) {
+		const proportion = arr[i] / before_total;
+		result[i] = arr[i] - delta * proportion;
+	}
+
+	for (let i = index + 1; i < arr.length; i++) {
+		const proportion = arr[i] / after_total;
+		result[i] = arr[i] + delta * proportion;
+	}
+
+	return result;
+}

package/src/common/remove_child.ts

@@ -0,0 +1,102 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { Layout } from "./layout_config.ts";
+import { EMPTY_PANEL } from "./layout_config.ts";
+
+/**
+ * Removes a child panel from the layout tree by its name.
+ *
+ * Redistributes the removed panel's space proportionally among remaining
+ * siblings. Automatically collapses split panels when only one child remains.
+ *
+ * @param panel - The root layout tree to remove from.
+ * @param child - Name of the child panel to remove.
+ * @returns A new layout tree with the child removed (original is not mutated).
+ * Returns `EMPTY_PANEL` if the last panel is removed.
+ */
+export function remove_child(panel: Layout, child: string): Layout {
+	// If this is a child panel and it matches, we can't remove ourselves
+	// The caller should handle this case
+	if (panel.type === "child-panel") {
+		return structuredClone(EMPTY_PANEL);
+	}
+
+	// Clone the panel structure
+	const result = structuredClone(panel);
+
+	// Try to remove the child from this split panel's children
+	const index = result.children.findIndex((p) => {
+		if (p.type === "child-panel") {
+			return p.child === child;
+		}
+		return false;
+	});
+
+	if (index !== -1) {
+		// Found the child at this level - remove it
+		const newChildren = result.children.filter((_, i) => i !== index);
+		const newSizes = remove_and_redistribute(result.sizes, index);
+
+		// If only one child remains, collapse the split panel
+		if (newChildren.length === 1) {
+			return newChildren[0];
+		}
+
+		result.children = newChildren;
+		result.sizes = newSizes;
+		return result;
+	}
+
+	// Child not found at this level - recursively search children
+	let modified = false;
+	const newChildren = result.children.map((p) => {
+		if (p.type === "split-panel") {
+			const updated = remove_child(p, child);
+			if (updated !== p) {
+				modified = true;
+			}
+			return updated;
+		}
+		return p;
+	});
+
+	if (modified) {
+		result.children = newChildren;
+	}
+
+	return result;
+}
+
+function remove_and_redistribute(arr: number[], index: number): number[] {
+	const result = [];
+
+	// Get the size of the element being removed
+	const removed_size = arr[index];
+
+	// Calculate the total of remaining elements
+	let remaining_total = 0;
+	for (let i = 0; i < arr.length; i++) {
+		if (i !== index) {
+			remaining_total += arr[i];
+		}
+	}
+
+	// Distribute the removed size proportionally to remaining elements
+	for (let i = 0; i < arr.length; i++) {
+		if (i !== index) {
+			const proportion = arr[i] / remaining_total;
+			result.push(arr[i] + removed_size * proportion);
+		}
+	}
+
+	return result;
+}

package/src/extensions.ts

@@ -0,0 +1,40 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { RegularLayout } from "./regular-layout.ts";
+import { RegularLayoutFrame } from "./regular-layout-frame.ts";
+
+customElements.define("regular-layout-frame", RegularLayoutFrame);
+
+customElements.define("regular-layout", RegularLayout);
+
+declare global {
+	interface Document {
+		createElement(
+			tagName: "regular-layout",
+			options?: ElementCreationOptions,
+		): RegularLayout;
+
+		createElement(
+			tagName: "regular-layout-frame",
+			options?: ElementCreationOptions,
+		): RegularLayoutFrame;
+
+		querySelector<E extends Element = Element>(selectors: string): E | null;
+		querySelector(selectors: "regular-layout"): RegularLayout | null;
+		querySelector(selectors: "regular-layout-frame"): RegularLayoutFrame | null;
+	}
+
+	interface CustomElementRegistry {
+		get(tagName: "regular-layout"): typeof RegularLayout;
+		get(tagName: "regular-layout-frame"): typeof RegularLayoutFrame;
+	}
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Regular Layout - Resizable Panel Layout System
+ *
+ * A Web Component library for creating resizable, re-arrangeable layouts using
+ * CSS `grid`.
+ *
+ * ## Basic Usage
+ *
+ * ```html
+ * <regular-layout>
+ *   <regular-layout-frame slot="sidebar">Sidebar content</regular-layout-frame>
+ *   <regular-layout-frame slot="main">Main content</regular-layout-frame>
+ * </regular-layout>
+ * ```
+ *
+ * ```typescript
+ * import { RegularLayout } from 'regular-layout';
+ *
+ * const layout = document.querySelector('regular-layout');
+ *
+ * // Insert panels into the grid layout.
+ * layout.insertPanel('sidebar', [0]);
+ * layout.insertPanel('main', [1]);
+ *
+ * // Remove a panel (DOM child remains connected, but not slotted).
+ * layout.removePanel('sidebar');
+ *
+ * // Save current layout state.
+ * const state = layout.save();
+ * localStorage.setItem('layout', JSON.stringify(state));
+ *
+ * // Restore layout later.
+ * const savedState = JSON.parse(localStorage.getItem('layout'));
+ * layout.restore(savedState);
+ * ```
+ *
+ * ## Core Components
+ *
+ * - {@link RegularLayout}: The main `<regular-layout>` custom element.
+ * - {@link RegularLayoutFrame}: Optional frame component with titlebar support.
+ *
+ * ## Type Definitions
+ *
+ * - {@link Layout}: The layout tree structure for panel configuration.
+ * - {@link LayoutPath}: Information about a panel's position and viewport.
+ * - {@link LayoutDivider}: Information about a resizable divider.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+	LayoutPath,
+	Layout,
+	LayoutDivider,
+} from "./common/layout_config.ts";
+
+export { RegularLayout } from "./regular-layout.ts";
+export { RegularLayoutFrame } from "./regular-layout-frame.ts";
+
+// Side effects
+import "./extensions.ts";

package/src/regular-layout-frame.ts

@@ -0,0 +1,114 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { LayoutPath } from "./common/layout_config.ts";
+import type { RegularLayout } from "./regular-layout.ts";
+
+const CSS = `
+:host{--titlebar--height:24px;box-sizing:border-box}
+:host([slot]){margin-top:calc(var(--titlebar--height) + 3px)!important;}
+:host([slot])::part(container){position:absolute;top:0;left:0;right:0;bottom:0;display:flex;flex-direction:column;background-color:inherit;border-radius:inherit}
+:host([slot])::part(titlebar){height:var(--titlebar--height);margin-top:calc(-2px - var(--titlebar--height));user-select: none;}
+:host([slot])::part(body){flex:1 1 auto;}
+`;
+
+/**
+ * A custom element that represents a draggable panel within a
+ * `<regular-layout>`.
+ *
+ * `<regular-layout-frame>` is optional - you may also use a `<regular-layout>`
+ * with just plain `<div>` children (for example), but panels will not be
+ * moveable within the layout unless you manually call `setOverlayState` and
+ * `clearOverlayState` (or otherwise impement panel moving via the
+ * `<regular-layout>` API).
+ *
+ * `<regular-layout-frame>` simple and highly customizable implementations
+ * based on [CSS `part`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/::part)
+ * for custom styling, and symmetric
+ * [named `slot`s](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)
+ * for wholesale replacement of the underlying Shadow DOM.
+ *
+ * @example
+ * ```html
+ * <regular-layout>
+ *     <regular-layout-frame slot="panel-1">
+ *         <!-- Panel content here -->
+ *     </regular-layout-frame>
+ * </regular-layout>
+ * ```
+ */
+export class RegularLayoutFrame extends HTMLElement {
+	private _shadowRoot: ShadowRoot;
+	private _container_sheet: CSSStyleSheet;
+	private _layout!: RegularLayout;
+	private _header!: HTMLElement;
+	private _drag_state: LayoutPath<DOMRect> | null = null;
+	constructor() {
+		super();
+		this._container_sheet = new CSSStyleSheet();
+		this._container_sheet.replaceSync(CSS);
+		this._shadowRoot = this.attachShadow({ mode: "open" });
+		this._shadowRoot.adoptedStyleSheets = [this._container_sheet];
+		this._shadowRoot.innerHTML = `<slot part="container"><slot part="titlebar">header</slot><slot part="body"><slot></slot></slot></slot>`;
+		this._layout = this.parentElement as RegularLayout;
+		this._header = this._shadowRoot.children[0].children[0] as HTMLElement;
+	}
+
+	connectedCallback() {
+		this._header.addEventListener("pointerdown", this.onPointerDown);
+		this._header.addEventListener("pointermove", this.onPointerMove);
+		this._header.addEventListener("pointerup", this.onPointerUp);
+	}
+
+	disconnectedCallback() {
+		this._header.removeEventListener("pointerdown", this.onPointerDown);
+		this._header.removeEventListener("pointermove", this.onPointerMove);
+		this._header.removeEventListener("pointerup", this.onPointerUp);
+	}
+
+	private onPointerDown = (event: PointerEvent): void => {
+		this._drag_state = this._layout.calculateIntersect(
+			event.clientX,
+			event.clientY,
+		);
+
+		if (!this._drag_state) {
+			return;
+		}
+
+		this._header.setPointerCapture(event.pointerId);
+		event.preventDefault();
+		event.stopImmediatePropagation();
+	};
+
+	private onPointerMove = (event: PointerEvent): void => {
+		if (this._drag_state) {
+			this._layout.setOverlayState(
+				event.clientX,
+				event.clientY,
+				this._drag_state,
+			);
+		}
+	};
+
+	private onPointerUp = (event: PointerEvent): void => {
+		if (this._drag_state) {
+			this._layout.clearOverlayState(
+				event.clientX,
+				event.clientY,
+				this._drag_state,
+			);
+
+			this._header.releasePointerCapture(event.pointerId);
+			this._drag_state = null;
+		}
+	};
+}