regular-layout 0.4.0 → 0.6.0

package/dist/layout/generate_grid.d.ts

@@ -31,3 +31,12 @@ import type { Layout } from "../core/types.ts";
  * ```
  */
 export declare function create_css_grid_layout(layout: Layout, overlay?: [string, string], physics?: Physics): string;
+/**
+ * Generates CSS Grid styles that render a single panel maximized to fill the
+ * entire layout, hiding all other slotted children.
+ *
+ * @param name - The name of the panel to maximize.
+ * @param physics - Instance constants (defaults to {@link DEFAULT_PHYSICS}).
+ * @returns CSS string showing only `name`, full-size.
+ */
+export declare function create_css_maximize_layout(name: string, physics?: Physics): string;

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

@@ -14,8 +14,17 @@
  * [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.
  *
+ * The `name` attribute identifies the panel within the layout. The tab label
+ * defaults to `name`, but can be overridden with pure CSS by setting the
+ * `--regular-layout-<name>--title` custom property to a CSS string - the label
+ * is rendered via the tab title's `::before` `content`, so the override
+ * applies reactively with no JavaScript.
+ *
  * @example
  * ```html
+ * <style>
+ *     regular-layout { --regular-layout-panel-1--title: "Panel 1"; }
+ * </style>
  * <regular-layout>
  *     <regular-layout-frame name="panel-1">
  *         <!-- Panel content here -->
@@ -26,10 +35,11 @@
 export declare class RegularLayoutFrame extends HTMLElement {
     private _shadowRoot;
     private _container_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
@@ -46,4 +56,17 @@ export declare class RegularLayoutFrame extends HTMLElement {
     private onPointerCancel;
     private onPointerLost;
     private drawTabs;
+    /**
+     * 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 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 drawTab;
 }

package/dist/regular-layout.d.ts

@@ -57,6 +57,14 @@ export interface PointerEventCoordinates {
  * latter implementation would require synchronizing the light DOM
  * and shadow DOM slots/slotted children continuously.
  *
+ * Note that `::slotted()` only matches *directly* slotted nodes - it
+ * does not pierce a slotted `<slot>`. A consumer that wants to forward
+ * its own light-DOM content through `<regular-layout>` therefore cannot
+ * place a bare `<slot name="X">` as a layout child and expect it to be
+ * grid-positioned; instead, wrap the forwarding slot in a concrete
+ * `<regular-layout-frame name="X">` (which *is* directly slotted and so
+ * matched by the generated `::slotted([name="X"])` rules).
+ *
  */
 export declare class RegularLayout extends HTMLElement {
     private _shadowRoot;
@@ -69,6 +77,7 @@ export declare class RegularLayout extends HTMLElement {
     private _physics;
     private _presizeQueue;
     private _overlayController;
+    private _maximized?;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -133,6 +142,20 @@ export declare class RegularLayout extends HTMLElement {
      * @param name - Name of the panel to remove
      */
     removePanel: (name: string) => Promise<void>;
+    /**
+     * Selects a panel by `name`, making it the front-most tab within its
+     * containing stack, then dispatches a `<prefix>-select` event with
+     * `detail: { name }`.
+     *
+     * The event fires whenever a tab is selected - including re-selecting the
+     * already-active tab, or selecting the sole tab of a single-element stack -
+     * so consumers can always map a tab interaction to an "active panel". When
+     * the selection actually changes, a `<prefix>-update` event is dispatched
+     * first (via {@link restore}).
+     *
+     * @param name - The name of the panel to select.
+     */
+    select: (name: string) => Promise<void>;
     /**
      * Retrieves a panel by name from the layout tree.
      *
@@ -145,6 +168,22 @@ export declare class RegularLayout extends HTMLElement {
      * Clears the entire layout, unslotting all panels.
      */
     clear: () => Promise<void>;
+    /**
+     * Maximizes a panel by `name`, rendering it full-size and hiding every
+     * other panel. This is transient display state - it is **not** persisted by
+     * {@link save}, and any subsequent {@link restore} resets the layout to the
+     * minimized (normal, multi-panel) view.
+     *
+     * 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;
+    /**
+     * Restores the normal multi-panel view after a {@link maximize}, without
+     * altering the layout tree. No-op if no panel is currently maximized.
+     */
+    minimize: () => 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.4.0",
+	"version": "0.6.0",
 	"description": "A regular CSS `grid` container",
 	"keywords": [],
 	"license": "Apache-2.0",

package/src/extensions.ts

@@ -65,6 +65,12 @@ declare global {
 			options?: { signal: AbortSignal },
 		): void;
 
+		addEventListener(
+			name: "regular-layout-select",
+			cb: (e: RegularLayoutSelectEvent) => void,
+			options?: { signal: AbortSignal },
+		): void;
+
 		removeEventListener(
 			name: "regular-layout-update",
 			cb: (e: RegularLayoutEvent) => void,
@@ -79,8 +85,14 @@ declare global {
 			name: "regular-layout-before-resize",
 			cb: (e: RegularLayoutPresizeEvent) => void,
 		): void;
+
+		removeEventListener(
+			name: "regular-layout-select",
+			cb: (e: RegularLayoutSelectEvent) => void,
+		): void;
 	}
 }
 
 export type RegularLayoutEvent = CustomEvent<Layout>;
 export type RegularLayoutPresizeEvent = CustomEvent<PresizeDetail>;
+export type RegularLayoutSelectEvent = CustomEvent<{ name: string }>;

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,14 +277,34 @@ 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}`,
 			);
 		}
 	}
 
 	return css.join("\n");
 }
+
+/**
+ * Generates CSS Grid styles that render a single panel maximized to fill the
+ * entire layout, hiding all other slotted children.
+ *
+ * @param name - The name of the panel to maximize.
+ * @param physics - Instance constants (defaults to {@link DEFAULT_PHYSICS}).
+ * @returns CSS string showing only `name`, full-size.
+ */
+export function create_css_maximize_layout(
+	name: string,
+	physics: Physics = DEFAULT_PHYSICS,
+): string {
+	return [
+		host_template("100%", "100%"),
+		child_template(physics, name, "1", "1"),
+	].join("\n");
+}

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

@@ -58,7 +58,6 @@ export class OverlayController {
 
 		const [col, row, box, style] = host.relativeCoordinates(event, true);
 		let drop_target = calculate_intersection(col, row, panel);
-		console.log(row, col, drop_target);
 		if (drop_target) {
 			drop_target = calculate_edge(
 				col,

package/src/regular-layout-frame.ts

@@ -15,22 +15,38 @@ 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"><slot name="tab"><regular-layout-tab></regular-layout-tab></slot></div></div>
 	<div part="container"><slot></slot></div>
 `;
 
 type DragState = { moved?: boolean; path: LayoutPath };
 
+/**
+ * Escapes a string for safe use as a CSS `<string>` token (the `content`
+ * fallback), handling backslashes, double-quotes, and newlines.
+ */
+const css_string = (value: string): string =>
+	`"${value.replace(/[\\"\n]/g, (c) => (c === "\n" ? "\\A " : `\\${c}`))}"`;
+
+/**
+ * The per-slot CSS custom property a consumer sets to override a tab's label,
+ * e.g. `regular-layout { --regular-layout-my-panel--title: "My Panel"; }`.
+ */
+const title_variable = (slot: string): string =>
+	`--regular-layout-${globalThis.CSS.escape(slot)}--title`;
+
 /**
  * A custom element that represents a draggable panel within a
  * `<regular-layout>`.
@@ -47,8 +63,17 @@ type DragState = { moved?: boolean; path: LayoutPath };
  * [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.
  *
+ * The `name` attribute identifies the panel within the layout. The tab label
+ * defaults to `name`, but can be overridden with pure CSS by setting the
+ * `--regular-layout-<name>--title` custom property to a CSS string - the label
+ * is rendered via the tab title's `::before` `content`, so the override
+ * applies reactively with no JavaScript.
+ *
  * @example
  * ```html
+ * <style>
+ *     regular-layout { --regular-layout-panel-1--title: "Panel 1"; }
+ * </style>
  * <regular-layout>
  *     <regular-layout-frame name="panel-1">
  *         <!-- Panel content here -->
@@ -59,10 +84,11 @@ type DragState = { moved?: boolean; path: LayoutPath };
 export class RegularLayoutFrame extends HTMLElement {
 	private _shadowRoot!: ShadowRoot;
 	private _container_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
@@ -72,11 +98,20 @@ export class RegularLayoutFrame extends HTMLElement {
 	connectedCallback() {
 		this._container_sheet ??= new CSSStyleSheet();
 		this._container_sheet.replaceSync(CSS);
+		this._tab_sheet ??= new CSSStyleSheet();
 		this._shadowRoot ??= this.attachShadow({ mode: "open" });
-		this._shadowRoot.adoptedStyleSheets = [this._container_sheet];
+		this._shadowRoot.adoptedStyleSheets = [
+			this._container_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);
@@ -106,11 +141,23 @@ export class RegularLayoutFrame extends HTMLElement {
 	}
 
 	private onPointerDown = (event: PointerEvent): void => {
+		if (event.button !== 0) {
+			return;
+		}
+
 		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 {
@@ -158,31 +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,
-			};
+		let tab_panel = this._layout.getPanel(slot, event.detail);
+		if (!tab_panel) {
+			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);
-			}
-		}
+		// 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);
+	};
 
-		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]);
-		}
+	/**
+	 * 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 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 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"),
+		);
 	};
 }

package/src/regular-layout-tab.ts

@@ -34,6 +34,14 @@ export class RegularLayoutTab extends HTMLElement {
 	 * @param index - The index of this tab within the tab panel.
 	 */
 	populate = (layout: RegularLayout, tab_panel: TabLayout, index: number) => {
+		// Stamp the slot onto the tab so its title can be styled by name (see
+		// `RegularLayoutFrame#drawTitles`). Tag-qualified selectors keep this
+		// distinct from the panel `name` on `<regular-layout-frame>`.
+		this.setAttribute(
+			layout.savePhysics().CHILD_ATTRIBUTE_NAME,
+			tab_panel.tabs[index],
+		);
+
 		if (this._tab_panel) {
 			const tab_changed =
 				(index === tab_panel.selected) !==
@@ -44,9 +52,6 @@ export class RegularLayoutTab extends HTMLElement {
 
 			if (index_changed) {
 				const selected = tab_panel.selected === index;
-				const slot = tab_panel.tabs[index];
-				this.children[0].textContent = slot;
-
 				if (selected) {
 					this.children[1].part.add("active-close");
 					this.part.add("active-tab");
@@ -56,7 +61,6 @@ export class RegularLayoutTab extends HTMLElement {
 				}
 			}
 		} else {
-			const slot = tab_panel.tabs[index];
 			const selected = tab_panel.selected === index;
 			const parts = selected ? "active-close close" : "close";
 			this.innerHTML = `<div part="title"></div><button part="${parts}"></button>`;
@@ -67,7 +71,6 @@ export class RegularLayoutTab extends HTMLElement {
 			}
 
 			this.addEventListener("pointerdown", this.onTabClick);
-			this.children[0].textContent = slot;
 			this.children[1].addEventListener("pointerdown", this.onTabClose);
 		}
 
@@ -76,28 +79,23 @@ export class RegularLayoutTab extends HTMLElement {
 		this._index = index;
 	};
 
-	private onTabClose = (_: Event) => {
+	private onTabClose = (event: Event) => {
+		if (event instanceof PointerEvent && event?.button !== 0) {
+			return;
+		}
+
 		if (this._tab_panel !== undefined && this._index !== undefined) {
 			this._layout?.removePanel(this._tab_panel.tabs[this._index]);
 		}
 	};
 
-	private onTabClick = (_: PointerEvent) => {
-		if (
-			this._tab_panel !== undefined &&
-			this._index !== undefined &&
-			this._index !== this._tab_panel.selected
-		) {
-			const new_layout = this._layout?.save();
-			const new_tab_panel = this._layout?.getPanel(
-				this._tab_panel.tabs[this._index],
-				new_layout,
-			);
+	private onTabClick = (event: PointerEvent) => {
+		if (event.button !== 0) {
+			return;
+		}
 
-			if (new_tab_panel && new_layout) {
-				new_tab_panel.selected = this._index;
-				this._layout?.restore(new_layout);
-			}
+		if (this._tab_panel !== undefined && this._index !== undefined) {
+			this._layout?.select(this._tab_panel.tabs[this._index]);
 		}
 	};
 }