regular-layout 0.1.0 → 0.2.1

package/dist/{common → layout}/calculate_edge.d.ts

@@ -1,4 +1,5 @@
-import type { Layout, LayoutPath } from "./layout_config";
+import { type Physics } from "./constants";
+import type { Layout, LayoutPath } from "./types";
 /**
  * Calculates an insertion point (which may involve splitting a single
  * `"child-panel"` into a new `"split-panel"`), based on the  cursor position.
@@ -12,4 +13,4 @@ import type { Layout, LayoutPath } from "./layout_config";
  * @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): LayoutPath;
+export declare function calculate_edge(col: number, row: number, panel: Layout, slot: string, drop_target: LayoutPath, box?: DOMRect, physics?: Physics): LayoutPath;

package/dist/{common → layout}/calculate_intersect.d.ts

@@ -1,18 +1,22 @@
-import type { LayoutPath, LayoutDivider, Layout } from "./layout_config.ts";
+import type { LayoutPath, LayoutDivider, Layout } from "./types.ts";
 /**
  * Determines which panel or divider is located at a given position in the
  * layout.
  *
- * @param row - Vertical position as a fraction (0-1) of the container
- * height
- * @param column - Horizontal position as a fraction (0-1) of the
- * container width
+ * @param column - Horizontal position as a fraction (0-1) of the container width
+ * @param row - Vertical position as a fraction (0-1) of the container height
  * @param layout - The layout tree to search
  * @param check_dividers - Whether `LayoutDivider` intersection should be
- * checked, which oyu may not want for e.g. `drop` actions.
+ * checked, which you may not want for e.g. `drop` actions.
  * @returns The panel path if over a panel, a divider if over a resizable
  * boundary, or null if outside all panels
  */
-export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers: false): LayoutPath;
-export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers: true): LayoutPath | null | LayoutDivider;
-export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: boolean): LayoutPath | null | LayoutDivider;
+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?: {
+    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

@@ -0,0 +1,81 @@
+import type { OverlayMode } from "./types";
+/**
+ * Instance-specific constants which define the behavior and rendering details
+ * of a `<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;
+}
+/**
+ * Like `GlobalPhysics`, but suitable for partial definition for incremental
+ * updates.
+ */
+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/{common → layout}/flatten.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./layout_config.ts";
+import type { Layout } from "./types.ts";
 /**
  * Flattens the layout tree by merging parent and child split panels that have
  * the same orientation and type.

package/dist/{common → layout}/generate_grid.d.ts

@@ -1,4 +1,5 @@
-import type { Layout } from "./layout_config.ts";
+import { type Physics } from "./constants.ts";
+import type { Layout } from "./types.ts";
 /**
  * Generates CSS Grid styles to render a layout tree.
  * Creates grid-template-rows, grid-template-columns, and positioning rules for
@@ -25,8 +26,8 @@ import type { Layout } from "./layout_config.ts";
  * const css = create_css_grid_layout(layout);
  * // Returns CSS like:
  * // :host { display: grid; grid-template-columns: 25% 75%; ... }
- * // :host ::slotted([slot=sidebar]) { grid-column: 1; grid-row: 1; }
- * // :host ::slotted([slot=main]) { grid-column: 2; grid-row: 1; }
+ * // :host ::slotted([name=sidebar]) { grid-column: 1; grid-row: 1; }
+ * // :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

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

package/dist/{common → layout}/insert_child.d.ts

@@ -1,4 +1,4 @@
-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.
  * Creates a split panel if necessary and redistributes sizes equally among all
@@ -10,6 +10,7 @@ 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 declare function insert_child(panel: Layout, child: string, path: number[], orientation?: "horizontal" | "vertical", is_edge?: boolean): Layout;
+export declare function insert_child(panel: Layout, child: string, path: number[], orientation?: "horizontal" | "vertical"): Layout;

package/dist/{common → layout}/redistribute_panel_sizes.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./layout_config.ts";
+import type { Layout } from "./types.ts";
 /**
  * Adjusts panel sizes during a drag operation on a divider.
  *
@@ -16,4 +16,4 @@ import type { Layout } from "./layout_config.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/{common → layout}/remove_child.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./layout_config.ts";
+import type { Layout } from "./types.ts";
 /**
  * Removes a child panel from the layout tree by its name.
  *

package/dist/{common/layout_config.d.ts → layout/types.d.ts}

@@ -25,6 +25,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";
@@ -60,7 +65,6 @@ export interface LayoutDivider {
 export interface LayoutPath<T = undefined> {
     type: "layout-path";
     slot: string;
-    panel: TabLayout;
     path: number[];
     view_window: ViewWindow;
     column: number;
@@ -69,16 +73,8 @@ export interface LayoutPath<T = undefined> {
     row_offset: number;
     orientation: Orientation;
     is_edge: boolean;
-    box: T;
+    layout: 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 declare function iter_panel_children(panel: Layout): Generator<string>;
 /**
  * An empty `Layout` with no panels.
  */

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

@@ -17,7 +17,7 @@
  * @example
  * ```html
  * <regular-layout>
- *     <regular-layout-frame slot="panel-1">
+ *     <regular-layout-frame name="panel-1">
  *         <!-- Panel content here -->
  *     </regular-layout-frame>
  * </regular-layout>
@@ -31,7 +31,6 @@ 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;
@@ -40,6 +39,4 @@ export declare class RegularLayoutFrame extends HTMLElement {
     private onPointerUp;
     private onPointerLost;
     private drawTabs;
-    private createTab;
-    private onTabClick;
 }

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

@@ -0,0 +1,26 @@
+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 declare class RegularLayoutTab extends HTMLElement {
+    private _layout?;
+    private _tab_panel?;
+    private _index?;
+    /**
+     * 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) => void;
+    private onTabClose;
+    private onTabClick;
+}

package/dist/regular-layout.d.ts

@@ -1,4 +1,5 @@
-import type { LayoutPath, Layout, TabLayout, OverlayMode } from "./common/layout_config.ts";
+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.
@@ -8,8 +9,8 @@ import type { LayoutPath, Layout, TabLayout, OverlayMode } from "./common/layout
  * @example
  * ```html
  * <regular-layout>
- *   <div slot="sidebar">Sidebar content</div>
- *   <div slot="main">Main content</div>
+ *   <div name="sidebar">Sidebar content</div>
+ *   <div name="main">Main content</div>
  * </regular-layout>
  * ```
  *
@@ -36,12 +37,22 @@ export declare class RegularLayout extends HTMLElement {
     private _shadowRoot;
     private _panel;
     private _stylesheet;
-    private _dragPath?;
-    private _slots;
-    private _unslotted_slot;
+    private _cursor_stylesheet;
+    private _drag_target?;
+    private _cursor_override;
+    private _dimensions?;
+    private _physics;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Determines which panel is at a given screen coordinate.
+     *
+     * @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<Layout> | null;
     /**
      * Sets the visual overlay state during drag-and-drop operations.
      * Displays a preview of where a panel would be placed at the given coordinates.
@@ -69,14 +80,19 @@ export declare class RegularLayout extends HTMLElement {
      * @param mode - Overlay rendering mode that was used, must match the mode
      *     passed to `setOverlayState`. Defaults to "absolute".
      */
-    clearOverlayState: (x: number, y: number, drag_target: LayoutPath<unknown>, className?: string, mode?: OverlayMode) => void;
+    clearOverlayState: (x: number, y: number, drag_target: LayoutPath<Layout>, className?: string) => 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.
+     * @param split - Force a split in the layout at the end of `path`
+     *     regardless if there is a leaf at this position or not. Optionally,
+     *.    `split` may be your preferred `Orientation`, which will be used by
+     *     the new `SplitPanel` _if_ there is an option of orientation (e.g. if
+     *     the layout had no pre-existing `SplitPanel`)
      */
-    insertPanel: (name: string, path?: number[]) => void;
+    insertPanel: (name: string, path?: number[], split?: boolean | Orientation) => void;
     /**
      * Removes a panel from the layout by name.
      *
@@ -91,14 +107,6 @@ export declare class RegularLayout extends HTMLElement {
      * @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.
-     *
-     * @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;
     /**
      * Clears the entire layout, unslotting all panels.
      */
@@ -129,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.
      *
@@ -142,8 +162,7 @@ export declare class RegularLayout extends HTMLElement {
      *   - 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;
+    relativeCoordinates: (clientX: number, clientY: number, recalculate_bounds?: boolean) => [number, number, DOMRect, CSSStyleDeclaration];
     private onPointerDown;
     private onPointerMove;
     private onPointerUp;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "regular-layout",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "A regular CSS `grid` container",
 	"keywords": [],
 	"license": "Apache-2.0",
@@ -9,18 +9,20 @@
 		"url": "https://github.com/texodus/regular-layout"
 	},
 	"browser": "dist/index.js",
+	"main": "dist/index.js",
 	"type": "module",
 	"files": [
 		"dist/**/*",
-		"src/**/*"
+		"src/**/*",
+		"themes/**/*"
 	],
 	"scripts": {
-		"build": "node build.mjs",
-		"build:watch": "node build.mjs --watch",
+		"build": "tsx build.ts",
+		"build:watch": "tsx build.ts --watch",
 		"clean": "rm -rf dist",
 		"test": "playwright test",
-		"example": "npx http-server . -p 8000",
-		"deploy": "node deploy.mjs",
+		"example": "tsx serve.ts",
+		"deploy": "tsx deploy.ts",
 		"lint": "biome lint src tests",
 		"format": "biome format --write src tests",
 		"check": "biome check --write src tests"
@@ -30,7 +32,7 @@
 		"@playwright/test": "^1.57.0",
 		"@types/node": "^22.10.5",
 		"esbuild": "^0.27.2",
-		"http-server": "^14.1.1",
+		"tsx": "^4.21.0",
 		"typescript": "^5.9.3"
 	}
 }

package/src/extensions.ts

@@ -11,10 +11,12 @@
 
 import { RegularLayout } from "./regular-layout.ts";
 import { RegularLayoutFrame } from "./regular-layout-frame.ts";
-import type { Layout } from "./common/layout_config.ts";
+import type { Layout } from "./layout/types.ts";
+import { RegularLayoutTab } from "./regular-layout-tab.ts";
 
 customElements.define("regular-layout", RegularLayout);
 customElements.define("regular-layout-frame", RegularLayoutFrame);
+customElements.define("regular-layout-tab", RegularLayoutTab);
 
 declare global {
 	interface Document {
@@ -28,9 +30,15 @@ declare global {
 			options?: ElementCreationOptions,
 		): RegularLayoutFrame;
 
+		createElement(
+			tagName: "regular-layout-tab",
+			options?: ElementCreationOptions,
+		): RegularLayoutTab;
+
 		querySelector<E extends Element = Element>(selectors: string): E | null;
 		querySelector(selectors: "regular-layout"): RegularLayout | null;
 		querySelector(selectors: "regular-layout-frame"): RegularLayoutFrame | null;
+		querySelector(selectors: "regular-layout-tab"): RegularLayoutTab | null;
 	}
 
 	interface CustomElementRegistry {
@@ -63,6 +71,4 @@ declare global {
 	}
 }
 
-export interface RegularLayoutEvent extends CustomEvent {
-	detail: Layout;
-}
+export type RegularLayoutEvent = CustomEvent<Layout>;

package/src/index.ts

@@ -19,8 +19,8 @@
  *
  * ```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-frame name="sidebar">Sidebar content</regular-layout-frame>
+ *   <regular-layout-frame name="main">Main content</regular-layout-frame>
  * </regular-layout>
  * ```
  *
@@ -59,11 +59,7 @@
  * @packageDocumentation
  */
 
-export type {
-	LayoutPath,
-	Layout,
-	LayoutDivider,
-} from "./common/layout_config.ts";
+export type * from "./layout/types.ts";
 
 export { RegularLayout } from "./regular-layout.ts";
 export { RegularLayoutFrame } from "./regular-layout-frame.ts";