@getaster/elements 0.3.0 → 0.4.0

package/dist/window/config.js

@@ -0,0 +1,40 @@
+/** Minimize and maximize stay managed-window chrome unless the host overrides them. */
+export function resolveWindowChrome(chrome, managed) {
+    return {
+        header: chrome.header ?? true,
+        title: chrome.title ?? true,
+        close: chrome.close ?? true,
+        minimize: chrome.minimize ?? managed,
+        maximize: chrome.maximize ?? managed,
+        resizer: chrome.resizer ?? true,
+        footer: chrome.footer ?? false,
+        statusBar: chrome.statusBar ?? false,
+    };
+}
+/** A placement is rejected atomically; bounds are finite and positive. */
+export function parseWindowPlacement(value) {
+    const placement = value;
+    if (!placement || !["normal", "maximized", "minimized"].includes(placement.state))
+        throw new TypeError("Invalid window state");
+    const b = placement.bounds;
+    if (b && (![b.x, b.y, b.width, b.height].every(Number.isFinite) || b.width <= 0 || b.height <= 0))
+        throw new TypeError("Invalid window bounds");
+    return {
+        state: placement.state,
+        ...(b ? { bounds: { x: b.x, y: b.y, width: b.width, height: b.height } } : {}),
+        restoreMaximized: placement.restoreMaximized === true,
+    };
+}
+/** Keeps a window's top-left inside `limits`, never computing layout of its own. */
+export function clampWindow(at, size, limits) {
+    return {
+        x: Math.max(limits.left, Math.min(at.x, limits.right - size.width)),
+        y: Math.max(limits.top, Math.min(at.y, limits.bottom - size.height)),
+    };
+}
+export function centerWindow(size, limits) {
+    return {
+        x: limits.left + (limits.right - limits.left - size.width) / 2,
+        y: limits.top + (limits.bottom - limits.top - size.height) / 2,
+    };
+}

package/dist/window/window.d.ts

@@ -1,17 +1,7 @@
 import { AsterElement, type View } from "../base/element.ts";
-export type WindowState = "normal" | "maximized" | "minimized";
-export interface WindowBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-export interface WindowPlacement {
-    state: WindowState;
-    bounds?: WindowBounds;
-    restoreMaximized?: boolean;
-}
-/** Non-modal chrome; content ownership stays with the host page. */
+import { type WindowChrome, type WindowPlacement, type WindowState } from "./config.ts";
+export type { WindowBounds, WindowChrome, WindowPlacement, WindowState } from "./config.ts";
+/** Window chrome and content; content ownership stays with the host page. */
 export declare class Window extends AsterElement {
     #private;
     get heading(): string;
@@ -28,6 +18,54 @@ export declare class Window extends AsterElement {
     get closing(): boolean;
     get beforeClose(): (() => boolean | Promise<boolean>) | undefined;
     set beforeClose(v: (() => boolean | Promise<boolean>) | undefined);
+    /** Which parts of the window chrome it draws, as [[object:WindowChrome]]. Default `{}`. */
+    get chrome(): WindowChrome;
+    set chrome(v: WindowChrome);
+    /** Sugar for `chrome.header`. Default `true`. */
+    get showHeader(): boolean;
+    set showHeader(v: boolean);
+    /** Sugar for `chrome.title`. Default `true`; a hidden title still names the window. */
+    get showTitle(): boolean;
+    set showTitle(v: boolean);
+    /** Sugar for `chrome.close`. Default `true`. */
+    get showCloseButton(): boolean;
+    set showCloseButton(v: boolean);
+    /** Sugar for `chrome.minimize`. Default: shown for managed windows. */
+    get showMinimizeButton(): boolean;
+    set showMinimizeButton(v: boolean);
+    /** Sugar for `chrome.maximize`. Default: shown for managed windows. */
+    get showMaximizeButton(): boolean;
+    set showMaximizeButton(v: boolean);
+    /** Sugar for `chrome.resizer`. Default `true`. */
+    get showResizer(): boolean;
+    set showResizer(v: boolean);
+    /** Sugar for `chrome.footer`. Default `false`. */
+    get showFooter(): boolean;
+    set showFooter(v: boolean);
+    /** Sugar for `chrome.statusBar`. Default `false`. */
+    get showStatusBar(): boolean;
+    set showStatusBar(v: boolean);
+    /** The footer's contents. Setting it also sets `chrome.footer`; `nothing` clears the flag. */
+    get footer(): View;
+    set footer(v: View);
+    /** The status bar's contents. Setting it also sets `chrome.statusBar`; `nothing` clears the flag. */
+    get status(): View;
+    set status(v: View);
+    /** Geometry used the first time the window opens, before any placement is captured. */
+    get initialPlacement(): WindowPlacement | undefined;
+    set initialPlacement(v: WindowPlacement | undefined);
+    /** Whether the window makes the rest of the page inert while open. Default `false`. */
+    get modal(): boolean;
+    set modal(v: boolean);
+    /** Whether Escape inside the window closes it. Default `true`. */
+    get dismissOnEscape(): boolean;
+    set dismissOnEscape(v: boolean);
+    /** Whether dragging keeps the window inside its parent element. Default `false`. */
+    get keepInParentRect(): boolean;
+    set keepInParentRect(v: boolean);
+    /** Whether the window centres itself the first time it opens. Default `false`. */
+    get autoCenter(): boolean;
+    set autoCenter(v: boolean);
     connectedCallback(): void;
     show(opener?: HTMLElement | null): void;
     /** Activates chrome without reparenting the content or recreating its models. */

package/dist/window/window.js

@@ -2,10 +2,11 @@ import { html, nothing } from "lit-html";
 import { AsterElement, define, uid } from "../base/element.js";
 import { openWhen } from "../overlay/anchor.js";
 import { windowBar } from "./chrome.js";
+import { centerWindow, clampWindow, parseWindowPlacement, resolveWindowChrome, } from "./config.js";
 const STEP = 16;
 const BIG_STEP = 64;
 const MARGIN = 8;
-/** Non-modal chrome; content ownership stays with the host page. */
+/** Window chrome and content; content ownership stays with the host page. */
 export class Window extends AsterElement {
     #content = this.prop(nothing);
     #heading = this.prop("");
@@ -15,6 +16,14 @@ export class Window extends AsterElement {
     #active = this.prop(false);
     #preserve = this.prop(false);
     #closing = this.prop(false);
+    #chrome = this.prop({});
+    #footer = this.prop(nothing);
+    #status = this.prop(nothing);
+    #initial = this.prop(undefined);
+    #modal = this.prop(false);
+    #dismissOnEscape = this.prop(true);
+    #keepInParentRect = this.prop(false);
+    #autoCenter = this.prop(false);
     #id = uid("aster-window");
     #opener = null;
     #at;
@@ -25,6 +34,10 @@ export class Window extends AsterElement {
     #observed = null;
     #focus = null;
     #closeTask;
+    #modalQueued = false;
+    #hostCloses = 0;
+    /** Modality as captured when the window opened; changing `modal` applies on the next open. */
+    #shownModal = false;
     #generation = 0;
     #beforeClose;
     #dragEnd;
@@ -42,6 +55,62 @@ export class Window extends AsterElement {
     get closing() { return this.#closing.value; }
     get beforeClose() { return this.#beforeClose; }
     set beforeClose(v) { this.#beforeClose = v; }
+    /** Which parts of the window chrome it draws, as [[object:WindowChrome]]. Default `{}`. */
+    get chrome() { return this.#chrome.value; }
+    set chrome(v) { this.#chrome.value = { ...(v ?? {}) }; }
+    /** Sugar for `chrome.header`. Default `true`. */
+    get showHeader() { return this.#resolved().header; }
+    set showHeader(v) { this.#setChrome("header", v); }
+    /** Sugar for `chrome.title`. Default `true`; a hidden title still names the window. */
+    get showTitle() { return this.#resolved().title; }
+    set showTitle(v) { this.#setChrome("title", v); }
+    /** Sugar for `chrome.close`. Default `true`. */
+    get showCloseButton() { return this.#resolved().close; }
+    set showCloseButton(v) { this.#setChrome("close", v); }
+    /** Sugar for `chrome.minimize`. Default: shown for managed windows. */
+    get showMinimizeButton() { return this.#resolved().minimize; }
+    set showMinimizeButton(v) { this.#setChrome("minimize", v); }
+    /** Sugar for `chrome.maximize`. Default: shown for managed windows. */
+    get showMaximizeButton() { return this.#resolved().maximize; }
+    set showMaximizeButton(v) { this.#setChrome("maximize", v); }
+    /** Sugar for `chrome.resizer`. Default `true`. */
+    get showResizer() { return this.#resolved().resizer; }
+    set showResizer(v) { this.#setChrome("resizer", v); }
+    /** Sugar for `chrome.footer`. Default `false`. */
+    get showFooter() { return this.#resolved().footer; }
+    set showFooter(v) { this.#setChrome("footer", v); }
+    /** Sugar for `chrome.statusBar`. Default `false`. */
+    get showStatusBar() { return this.#resolved().statusBar; }
+    set showStatusBar(v) { this.#setChrome("statusBar", v); }
+    /** The footer's contents. Setting it also sets `chrome.footer`; `nothing` clears the flag. */
+    get footer() { return this.#footer.value; }
+    set footer(v) {
+        this.#footer.value = v;
+        this.#setChrome("footer", v !== nothing);
+    }
+    /** The status bar's contents. Setting it also sets `chrome.statusBar`; `nothing` clears the flag. */
+    get status() { return this.#status.value; }
+    set status(v) {
+        this.#status.value = v;
+        this.#setChrome("statusBar", v !== nothing);
+    }
+    /** Geometry used the first time the window opens, before any placement is captured. */
+    get initialPlacement() { return this.#initial.value; }
+    set initialPlacement(v) {
+        this.#initial.value = v === undefined ? undefined : parseWindowPlacement(v);
+    }
+    /** Whether the window makes the rest of the page inert while open. Default `false`. */
+    get modal() { return this.#modal.value; }
+    set modal(v) { this.#modal.value = v === true; }
+    /** Whether Escape inside the window closes it. Default `true`. */
+    get dismissOnEscape() { return this.#dismissOnEscape.value; }
+    set dismissOnEscape(v) { this.#dismissOnEscape.value = v !== false; }
+    /** Whether dragging keeps the window inside its parent element. Default `false`. */
+    get keepInParentRect() { return this.#keepInParentRect.value; }
+    set keepInParentRect(v) { this.#keepInParentRect.value = v === true; }
+    /** Whether the window centres itself the first time it opens. Default `false`. */
+    get autoCenter() { return this.#autoCenter.value; }
+    set autoCenter(v) { this.#autoCenter.value = v === true; }
     connectedCallback() {
         super.connectedCallback();
         this.#resize = new ResizeObserver(() => {
@@ -64,8 +133,11 @@ export class Window extends AsterElement {
     }
     show(opener = document.activeElement) {
         if (!this.#open.peek()) {
+            if (!this.#mounted)
+                this.#adoptInitial();
             this.#opener = opener;
             this.#mounted = true;
+            this.#shownModal = this.#modal.peek();
             this.#open.value = true;
         }
         if (this.#state.peek() === "minimized")
@@ -76,8 +148,9 @@ export class Window extends AsterElement {
             const panel = this.#panel();
             if (!panel)
                 return;
-            if (this.#state.peek() === "normal")
-                this.#place(this.#at ?? beside(opener, panel));
+            if (this.#state.peek() === "normal") {
+                this.#place(this.#at ?? (this.#autoCenter.peek() ? centerWindow(sizeOf(panel), this.#limits()) : beside(opener, panel)));
+            }
             this.#applySize();
             this.activate();
             this.emit("statechange", this.#state.peek());
@@ -86,15 +159,19 @@ export class Window extends AsterElement {
     /** Activates chrome without reparenting the content or recreating its models. */
     activate(focus = true) {
         const panel = this.#panel();
-        if (!panel || !this.#open.peek() || this.#state.peek() === "minimized" || document.querySelector("dialog:modal"))
+        const modalHost = this.#modalHost();
+        const blocked = document.querySelector("dialog:modal");
+        if (!panel || !this.#open.peek() || this.#state.peek() === "minimized" || (blocked && blocked !== modalHost))
             return;
         if (!this.#active.peek()) {
             const previous = document.activeElement;
             this.#active.value = true;
-            // Top-layer order is insertion order; z-index cannot raise a popover.
-            if (panel.matches(":popover-open"))
-                panel.hidePopover();
-            panel.showPopover();
+            if (!this.#shownModal) {
+                // Top-layer order is insertion order; z-index cannot raise a popover.
+                if (panel.matches(":popover-open"))
+                    panel.hidePopover();
+                panel.showPopover();
+            }
             if (!focus && previous instanceof HTMLElement && previous.isConnected)
                 previous.focus({ preventScroll: true });
             this.emit("activate");
@@ -147,7 +224,7 @@ export class Window extends AsterElement {
         const returnFocus = this.#active.peek() || this.#panel()?.contains(document.activeElement);
         this.#state.value = "minimized";
         this.#active.value = false;
-        this.#panel()?.hidePopover();
+        this.#closeHost();
         if (returnFocus)
             this.#returnFocus();
         this.#changed();
@@ -173,19 +250,12 @@ export class Window extends AsterElement {
     }
     /** Invalid persisted data is rejected atomically. CSS limits size to the viewport. */
     setPlacement(value) {
-        if (!["normal", "maximized", "minimized"].includes(value?.state))
-            throw new TypeError("Invalid window state");
-        const b = value.bounds;
-        if (b && (![b.x, b.y, b.width, b.height].every(Number.isFinite) || b.width <= 0 || b.height <= 0))
-            throw new TypeError("Invalid window bounds");
-        this.#bounds = b ? { ...b } : undefined;
-        this.#at = b ? { x: b.x, y: b.y } : undefined;
-        this.#restoreMaximized = value.restoreMaximized === true;
-        this.#state.value = value.state;
+        this.#adopt(parseWindowPlacement(value));
         requestAnimationFrame(() => this.#applySize());
     }
     updated() {
         this.#observe();
+        this.#syncModal();
         if (this.#open.peek() && this.#state.peek() !== "minimized")
             this.#applySize();
     }
@@ -196,39 +266,60 @@ export class Window extends AsterElement {
         if (!open && !(preserve && this.#mounted))
             return nothing;
         const heading = `${this.#id}-heading`;
-        const managed = this.#managed.value;
-        return html `<div class="aster-window" popover="manual" role="dialog" aria-modal="false" aria-labelledby=${heading}
+        const title = this.#heading.value;
+        const chrome = this.#resolved();
+        const modal = this.#shownModal;
+        const titleView = chrome.title ? title : html `<span class="aster-sr-only">${title}</span>`;
+        const panel = html `<div class="aster-window" popover=${modal ? nothing : "manual"} role="dialog" aria-modal=${modal ? "true" : "false"}
+      aria-labelledby=${chrome.header ? heading : nothing} aria-label=${chrome.header ? nothing : title || nothing}
       data-state=${state} data-active=${String(this.#active.value)} aria-busy=${String(this.#closing.value)}
-      tabindex="-1" ${openWhen(open && state !== "minimized")}
+      data-resizer=${chrome.resizer ? nothing : "false"}
+      tabindex="-1" ${modal ? nothing : openWhen(open && state !== "minimized")}
       @pointerdown=${() => this.activate(false)} @focusin=${() => { this.#rememberFocus(); this.activate(false); }}
       @keydown=${(e) => {
             if (e.key !== "Escape" || e.defaultPrevented)
                 return;
             e.preventDefault();
             e.stopPropagation();
-            void this.close();
+            if (this.#dismissOnEscape.value)
+                void this.close();
         }}>
-      ${windowBar(heading, this.#heading.value, html `<button type="button" class="aster-window-move" aria-label=${`Move ${this.#heading.value}`}
+      ${chrome.header ? windowBar(heading, titleView, html `<button type="button" class="aster-window-move" aria-label=${`Move ${title}`}
           ?disabled=${state !== "normal"} aria-describedby=${`${this.#id}-move-help`}
           @keydown=${(e) => this.#geometryKey(e, false)}>
           <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1.5v13M1.5 8h13M8 1.5 6 3.5M8 1.5l2 2M8 14.5l-2-2M8 14.5l2-2M1.5 8l2-2M1.5 8l2 2M14.5 8l-2-2M14.5 8l-2 2"/></svg>
         </button>
         <span id=${`${this.#id}-move-help`} hidden>Arrow keys move the window; with Shift, further.</span>
-        <button type="button" aria-label=${`Resize ${this.#heading.value}`} ?disabled=${state !== "normal"}
+        ${chrome.resizer ? html `<button type="button" aria-label=${`Resize ${title}`} ?disabled=${state !== "normal"}
           aria-describedby=${`${this.#id}-resize-help`} @keydown=${(e) => this.#geometryKey(e, true)}>
           <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 13 13 3M7 3h6v6M3 7v6h6"/></svg>
         </button>
-        <span id=${`${this.#id}-resize-help`} hidden>Arrow keys resize the window; with Shift, further.</span>
-        ${managed ? html `<button type="button" aria-label=${`Minimize ${this.#heading.value}`} @click=${() => this.minimize()}>
-          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 12h10"/></svg></button>
-          <button type="button" aria-label=${`${state === "maximized" ? "Restore" : "Maximize"} ${this.#heading.value}`}
+        <span id=${`${this.#id}-resize-help`} hidden>Arrow keys resize the window; with Shift, further.</span>` : nothing}
+        ${chrome.minimize ? html `<button type="button" aria-label=${`Minimize ${title}`} @click=${() => this.minimize()}>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 12h10"/></svg></button>` : nothing}
+        ${chrome.maximize ? html `<button type="button" aria-label=${`${state === "maximized" ? "Restore" : "Maximize"} ${title}`}
             @click=${() => state === "maximized" ? this.restore() : this.maximize()}>
             <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3h10v10H3zM3 6h10"/></svg></button>` : nothing}
-        <button type="button" class="aster-window-close" aria-label=${`Close ${this.#heading.value}`} ?disabled=${this.#closing.value} @click=${() => void this.close()}>
+        ${chrome.close ? html `<button type="button" class="aster-window-close" aria-label=${`Close ${title}`} ?disabled=${this.#closing.value} @click=${() => void this.close()}>
           <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>
-        </button>`, (event) => this.#drag(event))}
+        </button>` : nothing}`, (event) => this.#drag(event)) : nothing}
       <div class="aster-window-body">${this.#content.value}</div>
+      ${chrome.footer ? html `<div class="aster-window-footer">${this.#footer.value}</div>` : nothing}
+      ${chrome.statusBar ? html `<div class="aster-window-status" role="status">${this.#status.value}</div>` : nothing}
     </div>`;
+        // The wrapper is always rendered so a modality change between openings can
+        // move the live panel instead of recreating its content and drafts.
+        return html `<dialog class="aster-window-modal"
+      @cancel=${(e) => { e.preventDefault(); if (this.#dismissOnEscape.peek())
+            void this.close(); }}
+      @close=${() => {
+            if (this.#hostCloses > 0) {
+                this.#hostCloses--;
+                return;
+            }
+            if (this.#open.peek() && this.#state.peek() !== "minimized")
+                this.#finishClose();
+        }}></dialog>${panel}`;
     }
     #finishClose() {
         const returnFocus = this.#active.peek() || this.#panel()?.contains(document.activeElement);
@@ -236,11 +327,26 @@ export class Window extends AsterElement {
         this.#capture();
         this.#open.value = false;
         this.#active.value = false;
-        this.#panel()?.hidePopover();
+        this.#closeHost();
         if (returnFocus)
             this.#returnFocus();
         this.emit("close");
     }
+    /** Closes the wrapper without treating its queued `close` event as external. */
+    #closeHost() {
+        // Only a modal window has a wrapper that closes it; the always-present
+        // dialog stays empty and closed for a non-modal window.
+        const host = this.#shownModal ? this.#modalHost() : null;
+        if (host) {
+            // A `<form method="dialog">` close leaves the host closed; its panel is already hidden with it.
+            if (host.open) {
+                this.#hostCloses++;
+                host.close();
+            }
+            return;
+        }
+        this.#panel()?.hidePopover();
+    }
     #rememberFocus() {
         if (document.activeElement instanceof HTMLElement && this.#panel()?.contains(document.activeElement))
             this.#focus = document.activeElement;
@@ -297,7 +403,7 @@ export class Window extends AsterElement {
     }
     #capture() {
         const panel = this.#panel();
-        if (!panel?.matches(":popover-open") || this.#state.peek() !== "normal" || panel.dataset.state !== "normal")
+        if (!panel || !this.#shown(panel) || this.#state.peek() !== "normal" || panel.dataset.state !== "normal")
             return;
         const r = panel.getBoundingClientRect();
         this.#bounds = { x: r.x, y: r.y, width: r.width, height: r.height };
@@ -306,6 +412,16 @@ export class Window extends AsterElement {
         const panel = this.#panel();
         if (!panel)
             return;
+        const limits = this.#limits();
+        // CSS owns the window's min/max geometry; the panel reads these intent variables.
+        if (this.#keepInParentRect.peek()) {
+            panel.style.setProperty("--window-cap-width", `${limits.right - limits.left}px`);
+            panel.style.setProperty("--window-cap-height", `${limits.bottom - limits.top}px`);
+        }
+        else {
+            panel.style.removeProperty("--window-cap-width");
+            panel.style.removeProperty("--window-cap-height");
+        }
         if (this.#bounds) {
             panel.style.width = `${this.#bounds.width}px`;
             panel.style.height = `${this.#bounds.height}px`;
@@ -313,7 +429,7 @@ export class Window extends AsterElement {
         this.#recover();
     }
     #recover() {
-        if (this.#state.peek() === "normal" && this.#at && this.#panel()?.matches(":popover-open"))
+        if (this.#state.peek() === "normal" && this.#at && this.#shown(this.#panel()))
             this.#place(this.#at);
     }
     #observe() {
@@ -329,14 +445,93 @@ export class Window extends AsterElement {
         const panel = this.#panel();
         if (!panel)
             return;
-        const x = Math.max(MARGIN, Math.min(to.x, innerWidth - panel.offsetWidth - MARGIN));
-        const y = Math.max(MARGIN, Math.min(to.y, innerHeight - panel.offsetHeight - MARGIN));
-        this.#at = { x, y };
-        panel.style.setProperty("--window-x", `${x}px`);
-        panel.style.setProperty("--window-y", `${y}px`);
+        const at = clampWindow(to, sizeOf(panel), this.#limits());
+        this.#at = at;
+        panel.style.setProperty("--window-x", `${at.x}px`);
+        panel.style.setProperty("--window-y", `${at.y}px`);
+    }
+    /** The nearest viewport edge inside the parent, when `keepInParentRect` is on. */
+    #limits() {
+        const viewport = { left: MARGIN, top: MARGIN, right: innerWidth - MARGIN, bottom: innerHeight - MARGIN };
+        if (!this.#keepInParentRect.peek())
+            return viewport;
+        const r = this.parentElement?.getBoundingClientRect();
+        if (!r || r.width <= 0 || r.height <= 0)
+            return viewport;
+        return { left: Math.max(viewport.left, r.left), top: Math.max(viewport.top, r.top), right: Math.min(viewport.right, r.right), bottom: Math.min(viewport.bottom, r.bottom) };
+    }
+    #shown(panel) {
+        if (!panel)
+            return false;
+        if (this.#shownModal)
+            return this.#modalHost()?.open === true;
+        return panel.matches(":popover-open");
+    }
+    #resolved() {
+        return resolveWindowChrome(this.#chrome.value, this.#managed.value);
+    }
+    #setChrome(key, value) {
+        if (typeof value !== "boolean")
+            throw new TypeError(`${key} must be a boolean`);
+        this.#chrome.value = { ...this.#chrome.peek(), [key]: value };
+    }
+    #adopt(placement) {
+        this.#bounds = placement.bounds ? { ...placement.bounds } : undefined;
+        this.#at = placement.bounds ? { x: placement.bounds.x, y: placement.bounds.y } : undefined;
+        this.#restoreMaximized = placement.restoreMaximized === true;
+        this.#state.value = placement.state;
+    }
+    /** A declarative first placement applies only until any placement has been captured. */
+    #adoptInitial() {
+        const initial = this.#initial.peek();
+        if (initial && this.#at === undefined && this.#bounds === undefined)
+            this.#adopt(initial);
+    }
+    #modalHost() {
+        return this.querySelector("dialog.aster-window-modal");
+    }
+    /** The wrapper follows open, minimized and modal; the panel itself never owns modality. */
+    #syncModal() {
+        const host = this.#modalHost();
+        const panel = this.#panel();
+        // Move the live panel to the wrapper the captured modality needs. Keeping
+        // the same element preserves its DOM, focus memory and native input values.
+        if (host && panel) {
+            if (this.#shownModal && panel.parentElement !== host)
+                host.append(panel);
+            else if (!this.#shownModal && panel.parentElement === host)
+                this.append(panel);
+        }
+        if (this.#modalQueued || !host)
+            return;
+        this.#modalQueued = true;
+        // After the commit: showModal() moves focus, which must not re-enter the render effect.
+        queueMicrotask(() => {
+            this.#modalQueued = false;
+            const host = this.#modalHost();
+            if (!host)
+                return;
+            const wants = this.#shownModal && this.#open.peek() && this.#state.peek() !== "minimized";
+            if (wants && !host.open) {
+                // Modals don't stack: with a foreign modal open, showModal() throws.
+                // Fall back to show(), which keeps the window usable inside that
+                // modal's subtree and inert with the rest of the page otherwise.
+                try {
+                    host.showModal();
+                }
+                catch {
+                    host.show();
+                }
+            }
+            else if (!wants && host.open)
+                this.#closeHost();
+        });
     }
     #panel() { return this.querySelector(".aster-window"); }
 }
+function sizeOf(panel) {
+    return { width: panel.offsetWidth, height: panel.offsetHeight };
+}
 function beside(opener, panel) {
     const r = opener?.getBoundingClientRect();
     if (!r)

package/dist/yaml.d.ts

@@ -0,0 +1,19 @@
+import { type CompositeDefinition, type CompositeLocation } from "./composition/definition.ts";
+/**
+ * Compiles a YAML composition definition into the same plain-data definition
+ * that `defineComposite` accepts, plus the file/line/column of every node.
+ *
+ * YAML carries configuration, never code: tags, anchors and aliases are
+ * rejected, so a definition can only contain JSON-compatible values. Pass the
+ * sources to `defineCompositeRegistry(...).validate(definition, sources)` to
+ * check model, component and renderer names with located diagnostics before
+ * mounting.
+ *
+ * @param text The YAML 1.2 document, at most 256 KiB.
+ * @param file The path reported in diagnostics.
+ * @returns The detached definition and a path-to-location map.
+ */
+export declare function compileCompositeYaml(text: string, file?: string): {
+    definition: CompositeDefinition;
+    sources: Record<string, CompositeLocation>;
+};

package/dist/yaml.js

@@ -0,0 +1,57 @@
+import { isAlias, isMap, isNode, isScalar, isSeq, LineCounter, parseDocument } from "yaml";
+import { CompositeError, defineComposite, located } from "./composition/definition.js";
+/**
+ * Compiles a YAML composition definition into the same plain-data definition
+ * that `defineComposite` accepts, plus the file/line/column of every node.
+ *
+ * YAML carries configuration, never code: tags, anchors and aliases are
+ * rejected, so a definition can only contain JSON-compatible values. Pass the
+ * sources to `defineCompositeRegistry(...).validate(definition, sources)` to
+ * check model, component and renderer names with located diagnostics before
+ * mounting.
+ *
+ * @param text The YAML 1.2 document, at most 256 KiB.
+ * @param file The path reported in diagnostics.
+ * @returns The detached definition and a path-to-location map.
+ */
+export function compileCompositeYaml(text, file = "composite.yaml") {
+    if (text.length > 262144)
+        throw new Error(`${file}: definition exceeds 256 KiB`);
+    const lines = new LineCounter();
+    const doc = parseDocument(text, { version: "1.2", schema: "core", lineCounter: lines, uniqueKeys: true, strict: true });
+    const invalid = doc.errors[0] ?? doc.warnings[0];
+    if (invalid) {
+        const position = invalid.linePos?.[0];
+        throw new Error(position ? `${file}:${position.line}:${position.col}: ${invalid.message}` : `${file}: ${invalid.message}`);
+    }
+    if (doc.directives?.yaml.version !== "1.2")
+        throw new Error(`${file}: only YAML 1.2 is supported`);
+    const sources = Object.create(null);
+    let count = 0;
+    function walk(node, path, depth) {
+        if (++count > 10000 || depth > 40)
+            throw located(new CompositeError(path, "definition exceeds node/depth limit"), sources);
+        if (!node)
+            return;
+        const { line, col } = lines.linePos(node.range?.[0] ?? 0);
+        sources[path] = { file, line, column: col };
+        if (isAlias(node) || node.tag || node.anchor)
+            throw located(new CompositeError(path, "tags, anchors and aliases are not supported"), sources);
+        if (isMap(node))
+            for (const pair of node.items) {
+                if (!isScalar(pair.key) || typeof pair.key.value !== "string")
+                    throw located(new CompositeError(path, "mapping keys must be strings"), sources);
+                const next = `${path}.${pair.key.value}`;
+                walk(isNode(pair.value) ? pair.value : null, next, depth + 1);
+            }
+        else if (isSeq(node))
+            node.items.forEach((item, i) => walk(isNode(item) ? item : null, `${path}.${i}`, depth + 1));
+    }
+    walk(doc.contents, "definition", 0);
+    try {
+        return { definition: defineComposite(doc.toJS({ maxAliasCount: 0 })), sources };
+    }
+    catch (error) {
+        throw located(error, sources);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getaster/elements",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {
@@ -8,12 +8,18 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./styles/*": "./styles/*"
+    "./styles/*": "./styles/*",
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "import": "./dist/yaml.js",
+      "default": "./dist/yaml.js"
+    }
   },
   "dependencies": {
-    "@getaster/data": "0.3.0",
+    "@getaster/data": "0.4.0",
     "@preact/signals-core": "1.14.4",
-    "lit-html": "3.3.3"
+    "lit-html": "3.3.3",
+    "yaml": "^2.9.1"
   },
   "bin": {
     "aster-theme-check": "./bin/aster-theme-check.js"