Improved REACME.md

Author: texodus

README.md

@@ -17,58 +17,146 @@
 
 
 
-A library for resizable & repositionable panel layouts, using
-[CSS `grid`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout).
+A library for resizable & repositionable panel layouts.
 
 - Zero depedencies, pure TypeScript, tiny.
 - Implemented as a [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),
-  interoperable with any framework and fully customizable.
+  interoperable with any framework.
+- Zero DOM mutation at runtime, implemented entirely by generating using
+[CSS `grid`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout) rules.
+- Supports arbitrary theming via CSS [variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) and [`::part`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/::part).
+- Supports async-aware container rendering for smooth animations even when rendering ovvurs over an event loop boundary.
 - Covered in bees.
 
+## Demo
+
+<a href="https://texodus.github.io/regular-layout/"><img src="./examples/PREVIEW.png" /></a>
+
 ## Installation
 
 ```bash
 npm install regular-layout
 ```
 
-## Usage
+## Quick Start
 
-Add the `<regular-layout>` custom element to your HTML:
+Import the library and add `<regular-layout>` to your HTML. Children are
+matched to layout slots by their `name` attribute.
 
 ```html
+<script type="module" src="regular-layout/dist/index.js"></script>
+
 <regular-layout>
     <div name="main">Main content</div>
     <div name="sidebar">Sidebar content</div>
 </regular-layout>
 ```
 
-Create and manipulate layouts programmatically:
+For draggable, tabbed panels, use `<regular-layout-frame>`:
+
+```html
+<regular-layout>
+    <regular-layout-frame name="main">
+        Main content
+    </regular-layout-frame>
+    <regular-layout-frame name="sidebar">
+        Sidebar content
+    </regular-layout-frame>
+</regular-layout>
+```
+
+Panels must be added and remove programmatically (e.g they are not 
+auto-registered):
 
 ```javascript
-import "regular-layout/dist/index.js";
+const layout = document.querySelector("regular-layout");
 
-const layout = document.querySelector('regular-layout');
+// This adds the panel definition to the layout (and makes it visible via CSS),
+// but does not mutat the DOM.
+layout.insertPanel("main");
+layout.insertPanel("sidebar");
 
-// Add panels
-layout.insertPanel('main');
-layout.insertPanel('sidebar');
+// This removes the panel from the layout (and hides it via CSS) but does not
+// mutate the DOM.
+layout.removePanel("sidebar");
+```
 
-// Save layout state
+## Save/Restore
+
+Layout state serializes to a JSON tree of splits and tabs, which can be
+persisted and restored:
+
+```javascript
 const state = layout.save();
+localStorage.setItem("layout", JSON.stringify(state));
+
+// Later...
+layout.restore(JSON.parse(localStorage.getItem("layout")));
+```
 
-// Remove panels (this does not change the DOM, the element is unslotted).
-layout.removePanel('sidebar');
+`restore()` dispatches a cancelable `regular-layout-resize-before` event before
+applying the new state. Call `preventDefault()` to suspend the update, then
+`layout.resumeResize()` when ready:
 
-// Restore saved state
-layout.restore(state);
+```javascript
+layout.addEventListener("regular-layout-resize-before", (event) => {
+    event.preventDefault();
+    // ... prepare for resize ...
+    layout.resumeResize();
+});
 ```
 
-Create repositionable panels using `<regular-layout-frame>`:
+The `restore()` API can also be used as an alternative to 
+`insertPanel`/`removePanel` for initializing a `<regular-layout>`.
+
+## Theming
+
+Themes are plain CSS files that style the layout and its `::part()` selectors,
+scoped by a class on `<regular-layout>`. Apply a theme by adding its stylesheet
+and setting the class:
 
 ```html
-<regular-layout>
-    <regular-layout-frame name="main">
-        Main content
-    </regular-layout-frame>
+<link rel="stylesheet" href="regular-layout/themes/chicago.css">
+
+<regular-layout class="chicago">
+    ...
 </regular-layout>
-```
+```
+
+`<regular-layout-frame>` exposes these CSS parts:
+
+| Part | Description |
+|------|-------------|
+| `titlebar` | Tab bar container |
+| `tab` | Individual tab |
+| `active-tab` | Currently selected tab |
+| `close` | Close button |
+| `active-close` | Close button on the active tab |
+| `container` | Content area |
+
+```css
+regular-layout.mytheme regular-layout-frame::part(titlebar) {
+    background: #333;
+}
+
+regular-layout.mytheme regular-layout-frame::part(active-tab) {
+    background: #fff;
+    color: #000;
+}
+```
+
+See [the example `themes/`](./themes) directory for examples of how to write a
+complete theme for `<regular-layout>` and `regular-layout-frame>`.
+
+## Events
+
+| Event | Detail | Cancelable | Description |
+|-------|--------|------------|-------------|
+| `regular-layout-resize-before` | `{ calculatePresizePaths() }` | Yes | Fired before any layout change. Cancel to suspend until `resumeResize()`. |
+| `regular-layout-update` | `Layout` | No | Fired after layout state is updated. |
+
+```javascript
+layout.addEventListener("regular-layout-update", (event) => {
+    console.log("New layout:", event.detail);
+});
+```

examples/PREVIEW.png

@@ -11,6 +11,7 @@
     <link rel="stylesheet" href="../themes/gibson.css">
     <link rel="stylesheet" href="../themes/fluxbox.css">
     <link rel="stylesheet" href="../themes/hotdog.css">
+    <link rel="stylesheet" href="../themes/borland.css">
     <script type="module" src="/.esbuild-serve/index.js"></script>
 </head>
 <body>
@@ -25,17 +26,18 @@
             <option value="chicago">Chicago</option>
             <option value="fluxbox">Fluxbox</option>
             <option value="hotdog">Hot Dog</option>
+            <option value="borland">Borland</option>
         </select>
     </header>
     <regular-layout class="lorax">
-        <regular-layout-frame name="AAA"> </regular-layout-frame>
-        <regular-layout-frame name="BBB"></regular-layout-frame>
-        <regular-layout-frame name="CCC"></regular-layout-frame>
-        <regular-layout-frame name="DDD"></regular-layout-frame>
-        <regular-layout-frame name="EEE"></regular-layout-frame>
-        <regular-layout-frame name="FFF"></regular-layout-frame>
-        <regular-layout-frame name="GGG"></regular-layout-frame>
-        <regular-layout-frame name="HHH"></regular-layout-frame>
+        <regular-layout-frame name="AAA">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</regular-layout-frame>
+        <regular-layout-frame name="BBB">Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</regular-layout-frame>
+        <regular-layout-frame name="CCC">Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</regular-layout-frame>
+        <regular-layout-frame name="DDD">Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</regular-layout-frame>
+        <regular-layout-frame name="EEE">Curabitur pretium tincidunt lacus. Nulla gravida orci a odio. Nullam varius, turpis et commodo pharetra.</regular-layout-frame>
+        <regular-layout-frame name="FFF">Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus.</regular-layout-frame>
+        <regular-layout-frame name="GGG">Maecenas faucibus mollis interdum. Donec sed odio dui. Cras justo odio, dapibus ut facilisis in, egestas eget quam.</regular-layout-frame>
+        <regular-layout-frame name="HHH">Vestibulum id ligula porta felis euismod semper. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis.</regular-layout-frame>
     </regular-layout>
 </body>
 

examples/index.html

@@ -38,6 +38,12 @@ add.addEventListener("click", () => {
 	layout.insertPanel(name, []);
 });
 
+const urlTheme = new URLSearchParams(window.location.search).get("theme");
+if (urlTheme) {
+	themes.value = urlTheme;
+	layout.className = urlTheme;
+}
+
 themes.addEventListener("change", (_event) => {
 	layout.className = themes.value;
 });

examples/index.ts

@@ -0,0 +1,54 @@
+import { chromium } from "@playwright/test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const themes = ["lorax", "gibson", "chicago", "fluxbox", "hotdog", "borland"];
+const dir = "screenshots";
+const cols = 3;
+const rows = 2;
+const tileW = 300;
+
+const images = themes.map((t) =>
+	fs.readFileSync(path.join(dir, `${t}.png`)).toString("base64"),
+);
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.setContent("<html><body></body></html>");
+
+const pngData = await page.evaluate(
+	async ({ images, cols, rows, tileW }) => {
+		const loaded = await Promise.all(
+			images.map((b64) => {
+				return new Promise<HTMLImageElement>((resolve) => {
+					const img = new Image();
+					img.onload = () => resolve(img);
+					img.src = `data:image/png;base64,${b64}`;
+				});
+			}),
+		);
+
+		const aspect = loaded[0].naturalHeight / loaded[0].naturalWidth;
+		const tileH = Math.round(tileW * aspect);
+		const canvas = document.createElement("canvas");
+		canvas.width = cols * tileW;
+		canvas.height = rows * tileH;
+		const ctx = canvas.getContext("2d")!;
+
+		loaded.forEach((img, i) => {
+			const col = i % cols;
+			const row = Math.floor(i / cols);
+			ctx.drawImage(img, col * tileW, row * tileH, tileW, tileH);
+		});
+
+		return canvas.toDataURL("image/png").split(",")[1];
+	},
+	{ images, cols, rows, tileW },
+);
+
+fs.writeFileSync(
+	path.join(dir, "montage.png"),
+	Buffer.from(pngData, "base64"),
+);
+console.log("Created montage.png");
+await browser.close();

montage.ts

@@ -0,0 +1,45 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  Copyright (c) 2026, the Regular Layout Authors. This file is part  *  ┃
+// ┃  *  of the Regular Layout library, distributed under the terms of the  *  ┃
+// ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { chromium } from "@playwright/test";
+import * as fs from "node:fs";
+
+const THEMES = ["lorax", "gibson", "chicago", "fluxbox", "hotdog", "borland"];
+const BASE_URL = "http://127.0.0.1:8081";
+const OUT_DIR = "screenshots";
+
+async function main() {
+	fs.mkdirSync(OUT_DIR, { recursive: true });
+	const browser = await chromium.launch();
+	const page = await browser.newPage();
+
+	for (const theme of THEMES) {
+		await page.goto(
+			`${BASE_URL}/examples/index.html?theme=${theme}`,
+		);
+		await page.waitForSelector("regular-layout");
+		await page.evaluate(() => {
+			const header = document.querySelector("header");
+			if (header) header.style.display = "none";
+		});
+
+		const layout = page.locator("regular-layout");
+		await layout.screenshot({
+			path: `${OUT_DIR}/${theme}.png`,
+		});
+
+		console.log(`Captured ${theme}.png`);
+	}
+
+	await browser.close();
+}
+
+main();

screenshots.ts

@@ -26,7 +26,7 @@ const CSS = `
 
 const HTML_TEMPLATE = `
 	<div part="titlebar"></div>
-	<slot part="container"></slot>
+	<div part="container"><slot></slot></div>
 `;
 
 type DragState = { moved?: boolean; path: LayoutPath };