regular-layout 0.5.0 → 0.6.1

package/dist/model/presize_queue.d.ts

@@ -1,4 +1,12 @@
-import type { Layout } from "../core/types.ts";
+import type { Layout, LayoutPath } from "../core/types.ts";
+/**
+ * The dragged panel's preview geometry during a drag transition - see
+ * {@link PresizeDetail.overlay}.
+ */
+export type PresizeOverlay = {
+    slot: string;
+    path: LayoutPath;
+} | null;
 /**
  * Manages cancelable pre-resize gating for layout updates.
  *
@@ -11,7 +19,8 @@ export declare class PresizeQueue {
     #private;
     private _target;
     private _eventName;
-    constructor(_target: EventTarget, _eventName: string);
-    run(layout: Layout, fn: () => void): Promise<void>;
+    private _onDispatch?;
+    constructor(_target: EventTarget, _eventName: string, _onDispatch?: (() => void) | undefined);
+    run(layout: Layout, fn: () => void, overlay?: PresizeOverlay): Promise<void>;
     resume(): void;
 }

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

@@ -35,11 +35,11 @@
 export declare class RegularLayoutFrame extends HTMLElement {
     private _shadowRoot;
     private _container_sheet;
-    private _title_sheet;
+    private _tab_sheet;
     private _layout;
     private _header;
+    private _default_tab;
     private _drag;
-    private _tab_to_index_map;
     /**
      * Initializes this elements. Override this method and
      * `disconnectedCallback` to modify how this subclass renders the Shadow
@@ -57,14 +57,16 @@ export declare class RegularLayoutFrame extends HTMLElement {
     private onPointerLost;
     private drawTabs;
     /**
-     * Regenerates this frame's title stylesheet, mapping each tab (by its slot
-     * `name`) to its label. The label is rendered via the title's `::before`
-     * `content`, reading the slot's `--regular-layout-<slot>--title` override
-     * variable with the slot name as the fallback - so a consumer can relabel a
-     * tab purely in CSS and the change applies reactively.
+     * Regenerates this frame's tab stylesheet: the shared titlebar grid template
+     * (so every frame in the stack aligns), the column this frame's tab occupies,
+     * and the tab label. The label renders via the title's `::before` `content`,
+     * reading the slot's `--regular-layout-<slot>--title` override variable with
+     * the slot name as the fallback - so a consumer can relabel a tab purely in
+     * CSS and the change applies reactively.
      *
-     * @param attr - The child name attribute (`CHILD_ATTRIBUTE_NAME`).
-     * @param tabs - The slot names rendered in this frame's titlebar.
+     * @param slot - This frame's panel name.
+     * @param index - This frame's column (zero-based) within the stack.
+     * @param count - The number of tabs in the stack.
      */
-    private drawTitles;
+    private drawTab;
 }

package/dist/regular-layout.d.ts

@@ -78,6 +78,7 @@ export declare class RegularLayout extends HTMLElement {
     private _presizeQueue;
     private _overlayController;
     private _maximized?;
+    private _resize_observer?;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -174,16 +175,27 @@ export declare class RegularLayout extends HTMLElement {
      * {@link save}, and any subsequent {@link restore} resets the layout to the
      * minimized (normal, multi-panel) view.
      *
+     * Before applying, dispatches a cancelable `regular-layout-before-resize`
+     * event (as {@link restore} does) whose paths describe the post-maximize
+     * geometry - a single full-window entry for `name`. If the event is
+     * cancelled via `preventDefault()`, the update is suspended until
+     * {@link resumeResize} is called.
+     *
      * Has no effect if `name` is not present in the current layout.
      *
      * @param name - The name of the panel to maximize.
      */
-    maximize: (name: string) => void;
+    maximize: (name: string) => Promise<void>;
     /**
      * Restores the normal multi-panel view after a {@link maximize}, without
      * altering the layout tree. No-op if no panel is currently maximized.
+     *
+     * Before applying, dispatches a cancelable `regular-layout-before-resize`
+     * event (as {@link restore} does) with paths for the restored multi-panel
+     * geometry. If the event is cancelled via `preventDefault()`, the update
+     * is suspended until {@link resumeResize} is called.
      */
-    minimize: () => void;
+    minimize: () => Promise<void>;
     /**
      * Restores the layout from a saved state synchronously, without
      * dispatching the `regular-layout-before-resize` event.

package/package.json

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

package/src/core/types.ts

@@ -100,6 +100,18 @@ export interface LayoutPath {
  */
 export interface PresizeDetail {
 	calculatePresizePaths(): Record<string, LayoutPath>;
+
+	/**
+	 * When the transition is a drag preview, the dragged panel's name and the
+	 * {@link LayoutPath} of its preview box. The dragged panel is removed from
+	 * the layout tree during a drag (so it is absent from
+	 * {@link PresizeDetail.calculatePresizePaths}), but `path.view_window` here
+	 * is exactly where the overlay renders it, letting consumers presize the
+	 * dragged panel like any other. `null` when the pointer is outside every
+	 * drop target (the dragged panel is hidden), `undefined` for non-drag
+	 * transitions.
+	 */
+	overlay?: { slot: string; path: LayoutPath } | null;
 }
 
 /**

package/src/layout/generate_grid.ts

@@ -18,6 +18,7 @@ interface GridCell {
 	colEnd: number;
 	rowStart: number;
 	rowEnd: number;
+	zIndex?: number;
 }
 
 function dedupe_sort(physics: Physics, result: number[], pos: number) {
@@ -102,15 +103,26 @@ function build_cells(
 ): GridCell[] {
 	if (panel.type === "tab-layout") {
 		const selected = panel.selected ?? 0;
-		return [
-			{
-				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),
-			},
-		];
+		const col_start = find_track_index(physics, colPositions, colStart);
+		const col_end = find_track_index(physics, colPositions, colEnd);
+		const row_start = find_track_index(physics, rowPositions, rowStart);
+		const row_end = find_track_index(physics, rowPositions, rowEnd);
+
+		// Stacked tabs all occupy the same cell, overlapping. Only the selected
+		// frame is lifted (`z-index:1`) so its content sits on top; the rest
+		// self-hide their content and just contribute their tab. Keeping the
+		// max frame `z-index` at 1 lets the drag overlay sit above any stack
+		// with a small constant (2). A single-tab stack
+		// emits one placement with no `z-index`, so non-stacked output is
+		// unchanged.
+		return panel.tabs.map((child, i) => ({
+			child,
+			colStart: col_start,
+			colEnd: col_end,
+			rowStart: row_start,
+			rowEnd: row_end,
+			zIndex: panel.tabs.length > 1 && i === selected ? 1 : undefined,
+		}));
 	}
 
 	const { children, sizes, orientation } = panel;
@@ -162,8 +174,11 @@ const child_template = (
 	slot: string,
 	rowPart: string,
 	colPart: string,
+	zIndex?: number,
 ) =>
-	`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){display:flex;grid-column:${colPart};grid-row:${rowPart}}`;
+	`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){display:flex;grid-column:${colPart};grid-row:${rowPart}${
+		zIndex === undefined ? "" : `;z-index:${zIndex}`
+	}}`;
 
 /**
  * Generates CSS Grid styles to render a layout tree.
@@ -202,9 +217,18 @@ export function create_css_grid_layout(
 ): string {
 	if (layout.type === "tab-layout") {
 		const selected = layout.selected ?? 0;
+		const stacked = layout.tabs.length > 1;
 		return [
 			host_template("100%", "100%"),
-			child_template(physics, layout.tabs[selected], "1", "1"),
+			...layout.tabs.map((tab, i) =>
+				child_template(
+					physics,
+					tab,
+					"1",
+					"1",
+					stacked && i === selected ? 1 : undefined,
+				),
+			),
 		].join("\n");
 	}
 
@@ -253,11 +277,13 @@ export function create_css_grid_layout(
 	for (const cell of cells) {
 		const colPart = formatGridLine(cell.colStart, cell.colEnd);
 		const rowPart = formatGridLine(cell.rowStart, cell.rowEnd);
-		css.push(child_template(physics, cell.child, rowPart, colPart));
+		css.push(
+			child_template(physics, cell.child, rowPart, colPart, cell.zIndex),
+		);
 		if (cell.child === overlay?.[1]) {
 			css.push(child_template(physics, overlay[0], rowPart, colPart));
 			css.push(
-				`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}=${overlay[0]}]){z-index:1}`,
+				`:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}=${overlay[0]}]){z-index:2}`,
 			);
 		}
 	}

package/src/layout/generate_overlay.ts

@@ -69,6 +69,6 @@ export function updateOverlaySheet(
 		margin,
 	);
 
-	const css = `display:flex;position:absolute!important;z-index:1;top:${local.y}px;left:${local.x}px;height:${local.height}px;width:${local.width}px;`;
+	const css = `display:flex;position:absolute!important;z-index:2;top:${local.y}px;left:${local.x}px;height:${local.height}px;width:${local.width}px;`;
 	return `::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){${css}}`;
 }

package/src/model/overlay_controller.ts

@@ -70,36 +70,49 @@ export class OverlayController {
 			);
 		}
 
-		await host.presizeQueue.run(panel, () => {
-			if (mode === "grid" && drop_target) {
-				const path: [string, string] = [slot, drop_target?.slot];
-				const css = create_css_grid_layout(panel, path, host.physics);
-				host.stylesheet.replaceSync(css);
-			} else if (mode === "absolute") {
-				const grid_css = create_css_grid_layout(panel, undefined, host.physics);
-
-				while (drag_element?.tagName === "SLOT" && drag_element) {
-					drag_element = (
-						drag_element as HTMLSlotElement
-					).assignedElements()[0];
+		// The dragged panel is removed from `panel` above, so it is absent from
+		// the presize paths - `drop_target` carries its preview box instead
+		// (null when the pointer is outside every drop target and the dragged
+		// panel is hidden).
+		const overlay = drop_target ? { slot, path: drop_target } : null;
+		await host.presizeQueue.run(
+			panel,
+			() => {
+				if (mode === "grid" && drop_target) {
+					const path: [string, string] = [slot, drop_target?.slot];
+					const css = create_css_grid_layout(panel, path, host.physics);
+					host.stylesheet.replaceSync(css);
+				} else if (mode === "absolute") {
+					const grid_css = create_css_grid_layout(
+						panel,
+						undefined,
+						host.physics,
+					);
+
+					while (drag_element?.tagName === "SLOT" && drag_element) {
+						drag_element = (
+							drag_element as HTMLSlotElement
+						).assignedElements()[0];
+					}
+
+					const margin = drag_element
+						? getComputedStyle(drag_element)
+						: undefined;
+
+					const overlay_css = updateOverlaySheet(
+						slot,
+						box,
+						style,
+						drop_target,
+						host.physics,
+						margin,
+					);
+
+					host.stylesheet.replaceSync([grid_css, overlay_css].join("\n"));
 				}
-
-				const margin = drag_element
-					? getComputedStyle(drag_element)
-					: undefined;
-
-				const overlay_css = updateOverlaySheet(
-					slot,
-					box,
-					style,
-					drop_target,
-					host.physics,
-					margin,
-				);
-
-				host.stylesheet.replaceSync([grid_css, overlay_css].join("\n"));
-			}
-		});
+			},
+			overlay,
+		);
 
 		const event_name = `${host.physics.CUSTOM_EVENT_NAME_PREFIX}-before-update`;
 		const custom_event = new CustomEvent<Layout>(event_name, {

package/src/model/presize_queue.ts

@@ -9,9 +9,15 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout, PresizeDetail } from "../core/types.ts";
+import type { Layout, LayoutPath, PresizeDetail } from "../core/types.ts";
 import { calculate_presize_paths } from "../layout/calculate_presize_paths.ts";
 
+/**
+ * The dragged panel's preview geometry during a drag transition - see
+ * {@link PresizeDetail.overlay}.
+ */
+export type PresizeOverlay = { slot: string; path: LayoutPath } | null;
+
 /**
  * Manages cancelable pre-resize gating for layout updates.
  *
@@ -22,27 +28,40 @@ import { calculate_presize_paths } from "../layout/calculate_presize_paths.ts";
  */
 export class PresizeQueue {
 	#resizing = false;
-	#queued: { layout: Layout; fn: () => void } | null = null;
+	#queued: {
+		layout: Layout;
+		fn: () => void;
+		overlay?: PresizeOverlay;
+	} | null = null;
 	#pending: (() => void) | null = null;
 
 	constructor(
 		private _target: EventTarget,
 		private _eventName: string,
+		private _onDispatch?: () => void,
 	) {}
 
-	async run(layout: Layout, fn: () => void): Promise<void> {
+	async run(
+		layout: Layout,
+		fn: () => void,
+		overlay?: PresizeOverlay,
+	): Promise<void> {
 		if (this.#resizing) {
-			this.#queued = { layout, fn };
+			this.#queued = { layout, fn, overlay };
 			return;
 		}
 
 		this.#resizing = true;
 		try {
-			await this.#dispatchAndMaybeWait(layout, fn);
+			await this.#dispatchAndMaybeWait(layout, fn, overlay);
 			while (this.#queued) {
-				const { layout: nextLayout, fn: nextFn } = this.#queued;
+				const {
+					layout: nextLayout,
+					fn: nextFn,
+					overlay: nextOverlay,
+				} = this.#queued;
 				this.#queued = null;
-				await this.#dispatchAndMaybeWait(nextLayout, nextFn);
+				await this.#dispatchAndMaybeWait(nextLayout, nextFn, nextOverlay);
 			}
 		} finally {
 			this.#resizing = false;
@@ -57,9 +76,15 @@ export class PresizeQueue {
 		}
 	}
 
-	async #dispatchAndMaybeWait(layout: Layout, fn: () => void): Promise<void> {
+	async #dispatchAndMaybeWait(
+		layout: Layout,
+		fn: () => void,
+		overlay?: PresizeOverlay,
+	): Promise<void> {
+		this._onDispatch?.();
 		const detail: PresizeDetail = {
 			calculatePresizePaths: () => calculate_presize_paths(layout),
+			overlay,
 		};
 
 		const event = new CustomEvent(this._eventName, {

package/src/regular-layout-frame.ts

@@ -15,17 +15,19 @@ import type { RegularLayout } from "./regular-layout.ts";
 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;}
+:host{box-sizing:border-box;flex-direction:column;pointer-events:none}
+[part~="titlebar"]{height:24px;user-select:none;overflow:hidden}
+[part~="container"]{flex:1 1 auto;pointer-events:auto}
+[part~="title"]{flex:1 1 auto;pointer-events:none}
+[part~="close"]{align-self:stretch}
+:host([inactive]) [part~="container"]{display:none}
+.tabs{display:grid;width:100%;height:100%}
+.tabs slot[name="tab"]{display:grid;grid-row:1;pointer-events:auto}
+.tabs regular-layout-tab{display:flex;overflow:hidden}
 `;
 
 const HTML_TEMPLATE = `
-	<div part="titlebar"></div>
+	<div part="titlebar"><div class="tabs" part="titlebar-track"><slot name="tab"><regular-layout-tab></regular-layout-tab></slot></div></div>
 	<div part="container"><slot></slot></div>
 `;
 
@@ -82,11 +84,11 @@ const title_variable = (slot: string): string =>
 export class RegularLayoutFrame extends HTMLElement {
 	private _shadowRoot!: ShadowRoot;
 	private _container_sheet!: CSSStyleSheet;
-	private _title_sheet!: CSSStyleSheet;
+	private _tab_sheet!: CSSStyleSheet;
 	private _layout!: RegularLayout;
 	private _header!: HTMLElement;
+	private _default_tab!: RegularLayoutTab;
 	private _drag: DragState | null = null;
-	private _tab_to_index_map: WeakMap<RegularLayoutTab, number> = new WeakMap();
 
 	/**
 	 * Initializes this elements. Override this method and
@@ -96,15 +98,20 @@ export class RegularLayoutFrame extends HTMLElement {
 	connectedCallback() {
 		this._container_sheet ??= new CSSStyleSheet();
 		this._container_sheet.replaceSync(CSS);
-		this._title_sheet ??= new CSSStyleSheet();
+		this._tab_sheet ??= new CSSStyleSheet();
 		this._shadowRoot ??= this.attachShadow({ mode: "open" });
 		this._shadowRoot.adoptedStyleSheets = [
 			this._container_sheet,
-			this._title_sheet,
+			this._tab_sheet,
 		];
 		this._shadowRoot.innerHTML = HTML_TEMPLATE;
 		this._layout = this.parentElement as RegularLayout;
 		this._header = this._shadowRoot.children[0] as HTMLElement;
+		// The built-in tab is the `slot="tab"` fallback; a consumer-supplied
+		// `slot="tab"` child replaces it.
+		this._default_tab = this._header.querySelector(
+			"regular-layout-tab",
+		) as RegularLayoutTab;
 		this._header.addEventListener("pointerdown", this.onPointerDown);
 		this.addEventListener("pointermove", this.onPointerMove);
 		this.addEventListener("pointerup", this.onPointerUp);
@@ -140,9 +147,17 @@ export class RegularLayoutFrame extends HTMLElement {
 
 		const elem = event.target as RegularLayoutTab;
 		if (elem.part.contains("tab")) {
+			const slot = this.getAttribute(
+				this._layout.savePhysics().CHILD_ATTRIBUTE_NAME,
+			);
+
 			const path = this._layout.calculateIntersect(event);
-			if (path) {
-				this._drag = { path };
+			if (path && slot) {
+				// Drag *this frame's* panel, not whichever panel is front-most at
+				// the pointer (which is what `calculateIntersect` resolves to in a
+				// stack). The overlapping stack shares geometry, so only the slot
+				// needs overriding.
+				this._drag = { path: { ...path, slot } };
 				this.setPointerCapture(event.pointerId);
 				event.preventDefault();
 			} else {
@@ -190,54 +205,41 @@ export class RegularLayoutFrame extends HTMLElement {
 			return;
 		}
 
-		const new_panel = event.detail;
-		let new_tab_panel = this._layout.getPanel(slot, new_panel);
-		if (!new_tab_panel) {
-			new_tab_panel = {
-				type: "tab-layout",
-				tabs: [slot],
-				selected: 0,
-			};
-		}
-
-		for (let i = 0; i < new_tab_panel.tabs.length; i++) {
-			if (i >= this._header.children.length) {
-				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 = this._header.children[i] as RegularLayoutTab;
-				tab.populate(this._layout, new_tab_panel, i);
-			}
-		}
-
-		const last_index = new_tab_panel.tabs.length;
-		for (let j = this._header.children.length - 1; j >= last_index; j--) {
-			this._header.removeChild(this._header.children[j]);
+		let tab_panel = this._layout.getPanel(slot, event.detail);
+		if (!tab_panel) {
+			tab_panel = { type: "tab-layout", tabs: [slot], selected: 0 };
 		}
 
-		this.drawTitles(attr, new_tab_panel.tabs);
+		// Each frame renders only its *own* tab. Frames in a stack overlap (see
+		// `create_css_grid_layout`); the tabs tile because every frame derives
+		// the same column template and places its tab in its own column. Only
+		// the selected frame shows its content; the rest keep just their tab.
+		const index = tab_panel.tabs.indexOf(slot);
+		const selected = (tab_panel.selected ?? 0) === index;
+		this.toggleAttribute("inactive", !selected);
+		this._default_tab.populate(this._layout, tab_panel, index);
+		this.drawTab(slot, index, tab_panel.tabs.length);
 	};
 
 	/**
-	 * Regenerates this frame's title stylesheet, mapping each tab (by its slot
-	 * `name`) to its label. The label is rendered via the title's `::before`
-	 * `content`, reading the slot's `--regular-layout-<slot>--title` override
-	 * variable with the slot name as the fallback - so a consumer can relabel a
-	 * tab purely in CSS and the change applies reactively.
+	 * Regenerates this frame's tab stylesheet: the shared titlebar grid template
+	 * (so every frame in the stack aligns), the column this frame's tab occupies,
+	 * and the tab label. The label renders via the title's `::before` `content`,
+	 * reading the slot's `--regular-layout-<slot>--title` override variable with
+	 * the slot name as the fallback - so a consumer can relabel a tab purely in
+	 * CSS and the change applies reactively.
 	 *
-	 * @param attr - The child name attribute (`CHILD_ATTRIBUTE_NAME`).
-	 * @param tabs - The slot names rendered in this frame's titlebar.
+	 * @param slot - This frame's panel name.
+	 * @param index - This frame's column (zero-based) within the stack.
+	 * @param count - The number of tabs in the stack.
 	 */
-	private drawTitles = (attr: string, tabs: string[]) => {
-		const css = tabs
-			.map(
-				(slot) =>
-					`regular-layout-tab[${attr}="${slot}"] [part~="title"]::before{content:var(${title_variable(slot)}, ${css_string(slot)})}`,
-			)
-			.join("\n");
-
-		this._title_sheet.replaceSync(css);
+	private drawTab = (slot: string, index: number, count: number) => {
+		this._tab_sheet.replaceSync(
+			[
+				`.tabs{grid-template-columns:repeat(${count},var(--rl-tab-width,1fr))}`,
+				`.tabs slot[name="tab"]{grid-column:${index + 1}}`,
+				`[part~="title"]::before{content:var(${title_variable(slot)}, ${css_string(slot)})}`,
+			].join("\n"),
+		);
 	};
 }