regular-layout 0.2.0 → 0.2.1

package/dist/layout/calculate_edge.d.ts

@@ -1,3 +1,4 @@
+import { type Physics } from "./constants";
 import type { Layout, LayoutPath } from "./types";
 /**
  * Calculates an insertion point (which may involve splitting a single
@@ -12,4 +13,4 @@ import type { Layout, LayoutPath } from "./types";
  * @returns A new `LayoutPath` reflecting the updated (maybe) `"split-panel"`,
  * which is enough to draw the overlay.
  */
-export declare function calculate_edge(col: number, row: number, panel: Layout, slot: string, drop_target: LayoutPath, box?: DOMRect): LayoutPath;
+export declare function calculate_edge(col: number, row: number, panel: Layout, slot: string, drop_target: LayoutPath, box?: DOMRect, physics?: Physics): LayoutPath;

package/dist/layout/calculate_intersect.d.ts

@@ -12,5 +12,11 @@ import type { LayoutPath, LayoutDivider, Layout } from "./types.ts";
  * boundary, or null if outside all panels
  */
 export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: null): LayoutPath | null;
-export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: DOMRect): LayoutPath | null | LayoutDivider;
-export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: DOMRect | null): LayoutPath | null | LayoutDivider;
+export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: {
+    rect: DOMRect;
+    size: number;
+}): LayoutPath | null | LayoutDivider;
+export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: {
+    rect: DOMRect;
+    size: number;
+} | null): LayoutPath | null | LayoutDivider;

package/dist/layout/constants.d.ts

@@ -1,43 +1,81 @@
 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 declare 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 attribute name to use for matching child `Element`s to grid
+     * positions.
+     */
+    CHILD_ATTRIBUTE_NAME: string;
+    /**
+     * The minimum number of pixels the mouse must move to be considered a drag.
+     */
+    MIN_DRAG_DISTANCE: number;
+    /**
+     * Should floating point pixel calculations be rounded. Useful for testing.
+     */
+    SHOULD_ROUND: boolean;
+    /**
+     * Class name to use for child elements in overlay position (dragging).
+     */
+    OVERLAY_CLASSNAME: string;
+    /**
+     * The percentage of the maximum resize distance that will be clamped.
+     */
+    MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD: number;
+    /**
+     * Threshold from panel edge that is considered a split vs drop action.
+     */
+    SPLIT_EDGE_TOLERANCE: number;
+    /**
+     * 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;
+}
 /**
- * The minimum number of pixels the mouse must move to be considered a drag.
+ * Like `GlobalPhysics`, but suitable for partial definition for incremental
+ * updates.
  */
-export declare const MIN_DRAG_DISTANCE = 10;
-/**
- * Class name to use for child elements in overlay position (dragging).
- */
-export declare const OVERLAY_CLASSNAME = "overlay";
-/**
- * The percentage of the maximum resize distance that will be clamped.
- *
- */
-export declare const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
-/**
- * Threshold from panel edge that is considered a split vs drop action.
- */
-export declare const SPLIT_EDGE_TOLERANCE = 0.25;
-/**
- * Threshold from _container_ edge that is considered a split action on the root
- * node.
- */
-export declare const SPLIT_ROOT_EDGE_TOLERANCE = 0.01;
-/**
- * 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 declare const GRID_TRACK_COLLAPSE_TOLERANCE = 0.001;
-/**
- * The overlay default behavior.
- */
-export declare const OVERLAY_DEFAULT: OverlayMode;
-/**
- * Width of split panel dividers in pixels (for hit-test purposes).
- */
-export declare 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 declare const DEFAULT_PHYSICS: Physics;

package/dist/layout/generate_grid.d.ts

@@ -1,3 +1,4 @@
+import { type Physics } from "./constants.ts";
 import type { Layout } from "./types.ts";
 /**
  * Generates CSS Grid styles to render a layout tree.
@@ -29,4 +30,4 @@ import type { Layout } from "./types.ts";
  * // :host ::slotted([name=main]) { grid-column: 2; grid-row: 1; }
  * ```
  */
-export declare function create_css_grid_layout(layout: Layout, round?: boolean, overlay?: [string, string]): string;
+export declare function create_css_grid_layout(layout: Layout, overlay?: [string, string], physics?: Physics): string;

package/dist/layout/generate_overlay.d.ts

@@ -1,2 +1,2 @@
 import type { LayoutPath } from "./types";
-export declare function updateOverlaySheet(slot: string, box: DOMRect, style: CSSStyleDeclaration, drag_target: LayoutPath<undefined> | null): string;
+export declare function updateOverlaySheet(slot: string, box: DOMRect, style: CSSStyleDeclaration, drag_target: LayoutPath<undefined> | null, physics?: import("./constants").Physics): string;

package/dist/layout/redistribute_panel_sizes.d.ts

@@ -16,4 +16,4 @@ import type { Layout } from "./types.ts";
  * @returns A new layout tree with updated sizes (original is not mutated).
  * ```
  */
-export declare function redistribute_panel_sizes(panel: Layout, path: number[], delta: number): Layout;
+export declare function redistribute_panel_sizes(panel: Layout, path: number[], delta: number, physics?: import("./constants.ts").Physics): Layout;

package/dist/regular-layout.d.ts

@@ -1,4 +1,5 @@
 import type { LayoutPath, Layout, TabLayout, OverlayMode, Orientation } from "./layout/types.ts";
+import { type PhysicsUpdate, type Physics } from "./layout/constants.ts";
 /**
  * A Web Component that provides a resizable panel layout system.
  * Panels are arranged using CSS Grid and can be resized by dragging dividers.
@@ -40,6 +41,7 @@ export declare class RegularLayout extends HTMLElement {
     private _drag_target?;
     private _cursor_override;
     private _dimensions?;
+    private _physics;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -135,6 +137,18 @@ export declare class RegularLayout extends HTMLElement {
      * ```
      */
     save: () => Layout;
+    /**
+     * Override this instance's global constants.
+     *
+     * @param physics
+     */
+    restorePhysics(physics: PhysicsUpdate): void;
+    /**
+     * Get this instance's constants.
+     *
+     * @returns The current constants
+     */
+    savePhysics(): Physics;
     /**
      * Converts screen coordinates to relative layout coordinates.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "regular-layout",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "A regular CSS `grid` container",
 	"keywords": [],
 	"license": "Apache-2.0",

package/src/layout/calculate_edge.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { SPLIT_EDGE_TOLERANCE, SPLIT_ROOT_EDGE_TOLERANCE } from "./constants";
+import { DEFAULT_PHYSICS, type Physics } from "./constants";
 import { insert_child } from "./insert_child";
 import type { Layout, LayoutPath, Orientation, ViewWindow } from "./types";
 
@@ -33,39 +33,47 @@ export function calculate_edge(
 	slot: string,
 	drop_target: LayoutPath,
 	box?: DOMRect,
+	physics: Physics = DEFAULT_PHYSICS,
 ): LayoutPath {
 	// Check root edges first
-	if (col < SPLIT_ROOT_EDGE_TOLERANCE) {
+	if (col < physics.SPLIT_ROOT_EDGE_TOLERANCE) {
 		return insert_root_edge(panel, slot, drop_target, [0], true, "horizontal");
 	}
 
-	if (col > 1 - SPLIT_ROOT_EDGE_TOLERANCE) {
+	if (col > 1 - physics.SPLIT_ROOT_EDGE_TOLERANCE) {
 		return insert_root_edge(
 			panel,
 			slot,
 			drop_target,
-			drop_target.path.length > 0 ? drop_target.path : [],
+			drop_target.path.length > 0 ? drop_target.path : [1],
 			false,
 			"horizontal",
 		);
 	}
 
-	if (row < SPLIT_ROOT_EDGE_TOLERANCE) {
+	if (row < physics.SPLIT_ROOT_EDGE_TOLERANCE) {
 		return insert_root_edge(panel, slot, drop_target, [0], true, "vertical");
 	}
 
-	if (row > 1 - SPLIT_ROOT_EDGE_TOLERANCE) {
-		return insert_root_edge(panel, slot, drop_target, [], false, "vertical");
+	if (row > 1 - physics.SPLIT_ROOT_EDGE_TOLERANCE) {
+		return insert_root_edge(
+			panel,
+			slot,
+			drop_target,
+			drop_target.path.length > 0 ? drop_target.path : [1],
+			false,
+			"vertical",
+		);
 	}
 
 	// Check panel edges
 	const is_column_edge =
-		drop_target.column_offset < SPLIT_EDGE_TOLERANCE ||
-		drop_target.column_offset > 1 - SPLIT_EDGE_TOLERANCE;
+		drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE ||
+		drop_target.column_offset > 1 - physics.SPLIT_EDGE_TOLERANCE;
 
 	const is_row_edge =
-		drop_target.row_offset < SPLIT_EDGE_TOLERANCE ||
-		drop_target.row_offset > 1 - SPLIT_EDGE_TOLERANCE;
+		drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE ||
+		drop_target.row_offset > 1 - physics.SPLIT_EDGE_TOLERANCE;
 
 	// If both edges triggered, choose closer axis
 	if (is_column_edge && is_row_edge) {
@@ -86,8 +94,8 @@ export function calculate_edge(
 			slot,
 			drop_target,
 			use_column
-				? drop_target.column_offset < SPLIT_EDGE_TOLERANCE
-				: drop_target.row_offset < SPLIT_EDGE_TOLERANCE,
+				? drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE
+				: drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE,
 			use_column ? "horizontal" : "vertical",
 		);
 	}
@@ -97,7 +105,7 @@ export function calculate_edge(
 			panel,
 			slot,
 			drop_target,
-			drop_target.column_offset < SPLIT_EDGE_TOLERANCE,
+			drop_target.column_offset < physics.SPLIT_EDGE_TOLERANCE,
 			"horizontal",
 		);
 	}
@@ -107,7 +115,7 @@ export function calculate_edge(
 			panel,
 			slot,
 			drop_target,
-			drop_target.row_offset < SPLIT_EDGE_TOLERANCE,
+			drop_target.row_offset < physics.SPLIT_EDGE_TOLERANCE,
 			"vertical",
 		);
 	}

package/src/layout/calculate_intersect.ts

@@ -9,7 +9,6 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { GRID_DIVIDER_SIZE } from "./constants.ts";
 import type { LayoutPath, LayoutDivider, Layout, ViewWindow } from "./types.ts";
 
 const VIEW_WINDOW = {
@@ -42,21 +41,21 @@ export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers?: DOMRect,
+	check_dividers?: { rect: DOMRect; size: number },
 ): LayoutPath | null | LayoutDivider;
 
 export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers?: DOMRect | null,
+	check_dividers?: { rect: DOMRect; size: number } | null,
 ): LayoutPath | null | LayoutDivider;
 
 export function calculate_intersection(
 	column: number,
 	row: number,
 	layout: Layout,
-	check_dividers: DOMRect | null = null,
+	check_dividers: { rect: DOMRect; size: number } | null = null,
 ): LayoutPath | null | LayoutDivider {
 	return calculate_intersection_recursive(column, row, layout, check_dividers);
 }
@@ -65,7 +64,7 @@ function calculate_intersection_recursive(
 	column: number,
 	row: number,
 	panel: Layout,
-	check_dividers: DOMRect | null,
+	check_dividers: { rect: DOMRect; size: number } | null,
 	parent_orientation: "horizontal" | "vertical" | null = null,
 	view_window: ViewWindow = structuredClone(VIEW_WINDOW),
 	path: number[] = [],
@@ -99,7 +98,10 @@ function calculate_intersection_recursive(
 	const position = is_vertical ? row : column;
 	const start_key = is_vertical ? "row_start" : "col_start";
 	const end_key = is_vertical ? "row_end" : "col_end";
-	const rect_dim = is_vertical ? check_dividers?.height : check_dividers?.width;
+	const rect_dim = is_vertical
+		? check_dividers?.rect?.height
+		: check_dividers?.rect?.width;
+
 	let current_pos = view_window[start_key];
 	const total_size = view_window[end_key] - view_window[start_key];
 	for (let i = 0; i < panel.children.length; i++) {
@@ -107,7 +109,7 @@ function calculate_intersection_recursive(
 
 		// Check if position is on a divider
 		if (check_dividers && rect_dim) {
-			const divider_threshold = GRID_DIVIDER_SIZE / rect_dim;
+			const divider_threshold = check_dividers.size / rect_dim;
 			if (Math.abs(position - next_pos) < divider_threshold) {
 				return {
 					path: [...path, i],

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,
+});