regular-layout 0.2.0 → 0.2.2

package/src/layout/constants.ts

@@ -12,52 +12,108 @@
 import type { OverlayMode } from "./types";
 
 /**
- * The prefix to use for `CustomEvent`s generated by `regular-layout`, e.g.
- * `"regular-layout-before-update"`.
+ * Instance-specific constants which define the behavior and rendering details
+ * of a `<regular-layout>`.
  */
-export const CUSTOM_EVENT_NAME_PREFIX = "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 minimum number of pixels the mouse must move to be considered a drag.
- */
-export const MIN_DRAG_DISTANCE = 10;
+	/**
+	 * The attribute name to use for matching child `Element`s to grid
+	 * positions.
+	 */
+	CHILD_ATTRIBUTE_NAME: string;
 
-/**
- * Class name to use for child elements in overlay position (dragging).
- */
-export const OVERLAY_CLASSNAME = "overlay";
+	/**
+	 * The minimum number of pixels the mouse must move to be considered a drag.
+	 */
+	MIN_DRAG_DISTANCE: number;
 
-/**
- * The percentage of the maximum resize distance that will be clamped.
- *
- */
-export const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
+	/**
+	 * Should floating point pixel calculations be rounded. Useful for testing.
+	 */
+	SHOULD_ROUND: boolean;
 
-/**
- * Threshold from panel edge that is considered a split vs drop action.
- */
-export const SPLIT_EDGE_TOLERANCE = 0.25;
+	/**
+	 * Class name to use for child elements in overlay position (dragging).
+	 */
+	OVERLAY_CLASSNAME: string;
 
-/**
- * Threshold from _container_ edge that is considered a split action on the root
- * node.
- */
-export const SPLIT_ROOT_EDGE_TOLERANCE = 0.01;
+	/**
+	 * The percentage of the maximum resize distance that will be clamped.
+	 */
+	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD: 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.
- */
-export const GRID_TRACK_COLLAPSE_TOLERANCE = 0.001;
+	/**
+	 * Threshold from panel edge that is considered a split vs drop action.
+	 */
+	SPLIT_EDGE_TOLERANCE: number;
 
-/**
- * The overlay default behavior.
- */
-export const OVERLAY_DEFAULT: OverlayMode = "absolute";
+	/**
+	 * 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;
+}
 
 /**
- * Width of split panel dividers in pixels (for hit-test purposes).
+ * Like `GlobalPhysics`, but suitable for partial definition for incremental
+ * updates.
  */
-export const GRID_DIVIDER_SIZE = 6;
+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/layout/generate_grid.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { GRID_TRACK_COLLAPSE_TOLERANCE } from "./constants.ts";
+import { DEFAULT_PHYSICS, type Physics } from "./constants.ts";
 import type { Layout } from "./types.ts";
 
 interface GridCell {
@@ -20,10 +20,11 @@ interface GridCell {
 	rowEnd: number;
 }
 
-function dedupe_sort(result: number[], pos: number) {
+function dedupe_sort(physics: Physics, result: number[], pos: number) {
 	if (
 		result.length === 0 ||
-		Math.abs(pos - result[result.length - 1]) > GRID_TRACK_COLLAPSE_TOLERANCE
+		Math.abs(pos - result[result.length - 1]) >
+			physics.GRID_TRACK_COLLAPSE_TOLERANCE
 	) {
 		result.push(pos);
 	}
@@ -31,9 +32,9 @@ function dedupe_sort(result: number[], pos: number) {
 	return result;
 }
 
-function dedupe_positions(positions: number[]): number[] {
+function dedupe_positions(physics: Physics, positions: number[]): number[] {
 	const sorted = positions.sort((a, b) => a - b);
-	return sorted.reduce(dedupe_sort, []);
+	return sorted.reduce(dedupe_sort.bind(undefined, physics), []);
 }
 
 function collect_track_positions(
@@ -41,6 +42,7 @@ function collect_track_positions(
 	orientation: "horizontal" | "vertical",
 	start: number,
 	end: number,
+	physics: Physics,
 ): number[] {
 	if (panel.type === "child-panel") {
 		return [start, end];
@@ -59,6 +61,7 @@ function collect_track_positions(
 					orientation,
 					current,
 					next,
+					physics,
 				),
 			);
 
@@ -67,17 +70,21 @@ function collect_track_positions(
 	} else {
 		for (const child of panel.children) {
 			positions.push(
-				...collect_track_positions(child, orientation, start, end),
+				...collect_track_positions(child, orientation, start, end, physics),
 			);
 		}
 	}
 
-	return dedupe_positions(positions);
+	return dedupe_positions(physics, positions);
 }
 
-function find_track_index(positions: number[], value: number): number {
+function find_track_index(
+	physics: Physics,
+	positions: number[],
+	value: number,
+): number {
 	const index = positions.findIndex(
-		(pos) => Math.abs(pos - value) < GRID_TRACK_COLLAPSE_TOLERANCE,
+		(pos) => Math.abs(pos - value) < physics.GRID_TRACK_COLLAPSE_TOLERANCE,
 	);
 
 	return index === -1 ? 0 : index;
@@ -91,16 +98,17 @@ function build_cells(
 	colEnd: number,
 	rowStart: number,
 	rowEnd: number,
+	physics: Physics,
 ): GridCell[] {
 	if (panel.type === "child-panel") {
 		const selected = panel.selected ?? 0;
 		return [
 			{
-				child: panel.child[selected],
-				colStart: find_track_index(colPositions, colStart),
-				colEnd: find_track_index(colPositions, colEnd),
-				rowStart: find_track_index(rowPositions, rowStart),
-				rowEnd: find_track_index(rowPositions, rowEnd),
+				child: panel.tabs[selected],
+				colStart: find_track_index(physics, colPositions, colStart),
+				colEnd: find_track_index(physics, colPositions, colEnd),
+				rowStart: find_track_index(physics, rowPositions, rowStart),
+				rowEnd: find_track_index(physics, rowPositions, rowEnd),
 			},
 		];
 	}
@@ -122,6 +130,7 @@ function build_cells(
 					next,
 					rowStart,
 					rowEnd,
+					physics,
 				),
 			);
 		} else {
@@ -134,6 +143,7 @@ function build_cells(
 					colEnd,
 					current,
 					next,
+					physics,
 				),
 			);
 		}
@@ -147,8 +157,13 @@ function build_cells(
 const host_template = (rowTemplate: string, colTemplate: string) =>
 	`:host ::slotted(*){display:none}:host{display:grid;grid-template-rows:${rowTemplate};grid-template-columns:${colTemplate}}`;
 
-const child_template = (slot: string, rowPart: string, colPart: string) =>
-	`:host ::slotted([name="${slot}"]){display:flex;grid-column:${colPart};grid-row:${rowPart}}`;
+const child_template = (
+	physics: Physics,
+	slot: string,
+	rowPart: string,
+	colPart: string,
+) =>
+	`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){display:flex;grid-column:${colPart};grid-row:${rowPart}}`;
 
 /**
  * Generates CSS Grid styles to render a layout tree.
@@ -167,8 +182,8 @@ const child_template = (slot: string, rowPart: string, colPart: string) =>
  *   type: "split-panel",
  *   orientation: "horizontal",
  *   children: [
- *     { type: "child-panel", child: "sidebar" },
- *     { type: "child-panel", child: "main" }
+ *     { type: "child-panel", tabs: "sidebar" },
+ *     { type: "child-panel", tabs: "main" }
  *   ],
  *   sizes: [0.25, 0.75]
  * };
@@ -182,12 +197,15 @@ const child_template = (slot: string, rowPart: string, colPart: string) =>
  */
 export function create_css_grid_layout(
 	layout: Layout,
-	round: boolean = false,
 	overlay?: [string, string],
+	physics: Physics = DEFAULT_PHYSICS,
 ): string {
 	if (layout.type === "child-panel") {
 		const selected = layout.selected ?? 0;
-		return `${host_template("100%", "100%")}\n${child_template(layout.child[selected], "1", "1")}`;
+		return [
+			host_template("100%", "100%"),
+			child_template(physics, layout.tabs[selected], "1", "1"),
+		].join("\n");
 	}
 
 	const createTemplate = (positions: number[]) => {
@@ -195,26 +213,52 @@ export function create_css_grid_layout(
 			.slice(0, -1)
 			.map((pos, i) => positions[i + 1] - pos);
 		return sizes
-			.map((s) => `${round ? Math.round(s * 100) : s * 100}fr`)
+			.map((s) => `${physics.SHOULD_ROUND ? Math.round(s * 100) : s * 100}fr`)
 			.join(" ");
 	};
 
-	const colPositions = collect_track_positions(layout, "horizontal", 0, 1);
+	const colPositions = collect_track_positions(
+		layout,
+		"horizontal",
+		0,
+		1,
+		physics,
+	);
+
 	const colTemplate = createTemplate(colPositions);
-	const rowPositions = collect_track_positions(layout, "vertical", 0, 1);
+	const rowPositions = collect_track_positions(
+		layout,
+		"vertical",
+		0,
+		1,
+		physics,
+	);
+
 	const rowTemplate = createTemplate(rowPositions);
 	const formatGridLine = (start: number, end: number) =>
 		end - start === 1 ? `${start + 1}` : `${start + 1} / ${end + 1}`;
 
-	const cells = build_cells(layout, colPositions, rowPositions, 0, 1, 0, 1);
+	const cells = build_cells(
+		layout,
+		colPositions,
+		rowPositions,
+		0,
+		1,
+		0,
+		1,
+		physics,
+	);
+
 	const css = [host_template(rowTemplate, colTemplate)];
 	for (const cell of cells) {
 		const colPart = formatGridLine(cell.colStart, cell.colEnd);
 		const rowPart = formatGridLine(cell.rowStart, cell.rowEnd);
-		css.push(child_template(cell.child, rowPart, colPart));
+		css.push(child_template(physics, cell.child, rowPart, colPart));
 		if (cell.child === overlay?.[1]) {
-			css.push(child_template(overlay[0], rowPart, colPart));
-			css.push(`:host ::slotted([name=${overlay[0]}]){z-index:1}`);
+			css.push(child_template(physics, overlay[0], rowPart, colPart));
+			css.push(
+				`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}=${overlay[0]}]){z-index:1}`,
+			);
 		}
 	}
 

package/src/layout/generate_overlay.ts

@@ -9,16 +9,18 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import { DEFAULT_PHYSICS } from "./constants";
 import type { LayoutPath } from "./types";
 
 export function updateOverlaySheet(
 	slot: string,
 	box: DOMRect,
 	style: CSSStyleDeclaration,
-	drag_target: LayoutPath<undefined> | null,
+	drag_target: LayoutPath | null,
+	physics = DEFAULT_PHYSICS,
 ) {
 	if (!drag_target) {
-		return `:host ::slotted([name="${slot}"]){display:none;}`;
+		return `:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){display:none;}`;
 	}
 
 	const {
@@ -36,5 +38,5 @@ export function updateOverlaySheet(
 	const height = (row_end - row_start) * box_height;
 	const width = (col_end - col_start) * box_width;
 	const css = `display:flex;position:absolute!important;z-index:1;top:${top}px;left:${left}px;height:${height}px;width:${width}px;`;
-	return `::slotted([name="${slot}"]){${css}}`;
+	return `::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){${css}}`;
 }

package/src/layout/insert_child.ts

@@ -33,7 +33,7 @@ export function insert_child(
 ): Layout {
 	const createChildPanel = (childId: string): Layout => ({
 		type: "child-panel",
-		child: [childId],
+		tabs: [childId],
 	});
 
 	if (path.length === 0) {
@@ -42,7 +42,7 @@ export function insert_child(
 			// Add to existing child-panel as a tab
 			return {
 				type: "child-panel",
-				child: [child, ...panel.child],
+				tabs: [child, ...panel.tabs],
 			};
 		} else if (orientation) {
 			// When inserting at edge of root, wrap the entire panel in a new split
@@ -105,13 +105,13 @@ export function insert_child(
 			restPath.length === 0 &&
 			orientation === undefined &&
 			index >= 0 &&
-			index <= panel.child.length
+			index <= panel.tabs.length
 		) {
-			const newChild = [...panel.child];
+			const newChild = [...panel.tabs];
 			newChild.splice(index, 0, child);
 			return {
 				...panel,
-				child: newChild,
+				tabs: newChild,
 			};
 		}
 

package/src/layout/redistribute_panel_sizes.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD } from "./constants.ts";
+import { DEFAULT_PHYSICS } from "./constants.ts";
 import type { Layout } from "./types.ts";
 
 /**
@@ -32,7 +32,8 @@ import type { Layout } from "./types.ts";
 export function redistribute_panel_sizes(
 	panel: Layout,
 	path: number[],
-	delta: number,
+	delta: number | undefined,
+	physics = DEFAULT_PHYSICS,
 ): Layout {
 	// Clone the entire panel structure
 	const result = structuredClone(panel);
@@ -40,7 +41,7 @@ export function redistribute_panel_sizes(
 	// 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 };
+	const deltas = { horizontal: delta || 0, vertical: delta || 0 };
 	for (let i = 0; i < path.length - 1; i++) {
 		if (current.type === "split-panel") {
 			deltas[current.orientation] /= current.sizes[path[i]];
@@ -50,12 +51,21 @@ export function redistribute_panel_sizes(
 
 	// Apply the redistribution at the final path index
 	if (current.type === "split-panel") {
-		const delta = deltas[current.orientation];
-		const index = path[path.length - 1];
+		if (delta === undefined) {
+			current.sizes = current.sizes.map((_) => 1 / current.sizes.length);
+		} else {
+			const delta = deltas[current.orientation];
+			const index = path[path.length - 1];
 
-		// It would be fun to remove this condition.
-		if (index < current.sizes.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(
+					physics,
+					current.sizes,
+					index,
+					delta,
+				);
+			}
 		}
 	}
 
@@ -63,6 +73,7 @@ export function redistribute_panel_sizes(
 }
 
 function add_and_redistribute(
+	physics: typeof DEFAULT_PHYSICS,
 	arr: number[],
 	index: number,
 	delta: number,
@@ -83,7 +94,7 @@ function add_and_redistribute(
 		Math.sign(delta) *
 		Math.min(
 			Math.abs(delta),
-			(1 - MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD) *
+			(1 - physics.MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD) *
 				(delta > 0 ? before_total : after_total),
 		);
 

package/src/layout/remove_child.ts

@@ -26,14 +26,14 @@ import { EMPTY_PANEL } from "./types.ts";
 export function remove_child(panel: Layout, child: string): Layout {
 	// If this is a child panel, handle tab removal
 	if (panel.type === "child-panel") {
-		if (panel.child.includes(child)) {
-			const newChild = panel.child.filter((c) => c !== child);
+		if (panel.tabs.includes(child)) {
+			const newChild = panel.tabs.filter((c) => c !== child);
 			if (newChild.length === 0) {
 				return structuredClone(EMPTY_PANEL);
 			}
 			return {
 				type: "child-panel",
-				child: newChild,
+				tabs: newChild,
 			};
 		}
 
@@ -46,7 +46,7 @@ export function remove_child(panel: Layout, child: string): Layout {
 	// 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.includes(child);
+			return p.tabs.includes(child);
 		}
 
 		return false;
@@ -54,7 +54,7 @@ export function remove_child(panel: Layout, child: string): Layout {
 
 	if (index !== -1) {
 		const tab_layout = result.children[index] as TabLayout;
-		if (tab_layout.child.length === 1) {
+		if (tab_layout.tabs.length === 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);
@@ -67,10 +67,10 @@ export function remove_child(panel: Layout, child: string): Layout {
 			result.children = newChildren;
 			result.sizes = newSizes;
 		} else {
-			tab_layout.child.splice(tab_layout.child.indexOf(child), 1);
+			tab_layout.tabs.splice(tab_layout.tabs.indexOf(child), 1);
 			if (
 				tab_layout.selected &&
-				tab_layout.selected >= tab_layout.child.length
+				tab_layout.selected >= tab_layout.tabs.length
 			) {
 				tab_layout.selected--;
 			}

package/src/layout/types.ts

@@ -58,7 +58,7 @@ export interface SplitLayout {
  */
 export interface TabLayout {
 	type: "child-panel";
-	child: string[];
+	tabs: string[];
 	selected?: number;
 }
 
@@ -75,12 +75,8 @@ export interface LayoutDivider {
 
 /**
  * Represents a panel location result from hit detection.
- *
- * Contains both the panel identifier and its grid position in relative units.
- * The generic parameter `T` allows DOM-only properties (e.g. `DOMRect`) to be
- * shared in this cross-platform module.
  */
-export interface LayoutPath<T = undefined> {
+export interface LayoutPath {
 	type: "layout-path";
 	slot: string;
 	path: number[];
@@ -91,7 +87,7 @@ export interface LayoutPath<T = undefined> {
 	row_offset: number;
 	orientation: Orientation;
 	is_edge: boolean;
-	layout: T;
+	layout: Layout;
 }
 
 /**