vintage-frames 0.14.1 → 0.15.0

package/dist/modal-dialog.js

@@ -1,10 +1,10 @@
-import { emit as e } from "./events.js";
-import { ScaleController as t, onScaleChange as n, snapSys as r, sysLength as i, toSysExact as a } from "./scale.js";
-import o from "./_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
-import { DocumentListenersController as s } from "./document-listeners.js";
-import { LitElement as c, css as l } from "lit";
-import { property as u, query as d } from "lit/decorators.js";
-var f = 24, p = /* @__PURE__ */ new Set([
+import { deferActivation as e, emit as t } from "./events.js";
+import { ScaleController as n, onScaleChange as r, snapSys as i, sysLength as a, toSysExact as o } from "./scale.js";
+import s from "./_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { DocumentListenersController as c } from "./document-listeners.js";
+import { LitElement as l, css as u } from "lit";
+import { property as d, query as f } from "lit/decorators.js";
+var p = 24, m = /* @__PURE__ */ new Set([
 	"text",
 	"search",
 	"url",
@@ -12,7 +12,7 @@ var f = 24, p = /* @__PURE__ */ new Set([
 	"email",
 	"password",
 	"number"
-]), m = (e) => e instanceof HTMLInputElement ? p.has(e.type) : !0, h = l`
+]), h = (e) => e instanceof HTMLInputElement ? m.has(e.type) : !0, g = u`
   dialog {
     padding: 0;
     margin: auto;
@@ -51,110 +51,119 @@ var f = 24, p = /* @__PURE__ */ new Set([
        the fallback is the arrow it always showed. */
     cursor: var(--vf-cursor, default);
   }
-`, g = class extends c {
-	constructor(...e) {
-		super(...e), this.scale = new t(this), this.open = !1, this.lightDismiss = !1, this.#e = !1, this.#n = null, this.#r = null, this.#i = new s(this, () => [
+`, _ = class extends l {
+	get dialogSize() {
+		return {
+			width: a(this.width ?? 260),
+			height: this.height === void 0 ? null : a(this.height)
+		};
+	}
+	#e;
+	#t() {
+		if (this.#e || !this.open) return;
+		let e = [];
+		if (this.width === void 0 && e.push("width (falling back to 260 system px)"), this.height === void 0 && e.push("height (falling back to the content)"), e.length === 0) return;
+		this.#e = !0;
+		let t = this.getAttribute("heading") ?? this.getAttribute("label") ?? "";
+		console.warn(`${this.localName}${t ? ` ("${t}")` : ""}: no ${e.join(", no ")}. A modal owns its whole box — declare both in system px: <${this.localName} width="320" height="140">.`);
+	}
+	#n;
+	#r;
+	constructor() {
+		super(), this.scale = new n(this), this.open = !1, this.returnValue = "", this.lightDismiss = !1, this.#e = !1, this.#n = null, this.#r = null, this.#i = (t) => {
+			let n = t.target;
+			if (!(n instanceof HTMLFormElement) || v(n) !== this) return;
+			let r = t.submitter;
+			if ((r?.hasAttribute("formmethod") ? r.getAttribute("formmethod") : n.getAttribute("method"))?.toLowerCase() !== "dialog") return;
+			let i = r instanceof HTMLButtonElement || r instanceof HTMLInputElement ? r.value : void 0;
+			e(this, t, () => this.close(i));
+		}, this.#a = null, this.#o = new c(this, () => [
 			[
 				this._dialog,
 				"pointerdown",
-				this.#s
+				this.#l
 			],
 			[
 				this._dialog,
 				"pointerup",
-				this.#c
+				this.#u
 			],
 			[
 				this._dialog,
 				"pointercancel",
-				this.#l
+				this.#d
 			],
 			[
 				this._dialog,
 				"keydown",
-				this.#o
+				this.#c
 			]
-		]), this.#o = (e) => {
+		]), this.#c = (e) => {
 			if (e.key !== "Enter" || e.defaultPrevented || e.isComposing || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
 			let t = e.composedPath();
 			if (t.some((e) => e instanceof HTMLAnchorElement && e.hasAttribute("href")) || t.some((e) => e instanceof HTMLTextAreaElement || e instanceof HTMLElement && e.isContentEditable) && e.code !== "NumpadEnter") return;
 			let n = this.defaultButton;
 			n && (e.preventDefault(), n.click());
-		}, this.#s = (e) => {
-			this.#r = e.target === this._dialog ? e.pointerId : null;
-		}, this.#c = (e) => {
-			let t = this.#r === e.pointerId;
-			this.#r = null, !(!t || e.target !== this._dialog || !this.lightDismiss) && (this.#n = "outside", this.close());
-		}, this.#l = () => {
-			this.#r = null;
-		}, this.#u = null, this.#g = () => this.settle();
-	}
-	get dialogSize() {
-		return {
-			width: i(this.width ?? 260),
-			height: this.height === void 0 ? null : i(this.height)
-		};
-	}
-	#e;
-	#t() {
-		if (this.#e || !this.open) return;
-		let e = [];
-		if (this.width === void 0 && e.push("width (falling back to 260 system px)"), this.height === void 0 && e.push("height (falling back to the content)"), e.length === 0) return;
-		this.#e = !0;
-		let t = this.getAttribute("heading") ?? this.getAttribute("label") ?? "";
-		console.warn(`${this.localName}${t ? ` ("${t}")` : ""}: no ${e.join(", no ")}. A modal owns its whole box — declare both in system px: <${this.localName} width="320" height="140">.`);
+		}, this.#l = (e) => {
+			this.#a = e.target === this._dialog ? e.pointerId : null;
+		}, this.#u = (e) => {
+			let t = this.#a === e.pointerId;
+			this.#a = null, !(!t || e.target !== this._dialog || !this.lightDismiss) && (this.#n = "outside", this.close());
+		}, this.#d = () => {
+			this.#a = null;
+		}, this.#f = null, this.#v = () => this.settle(), this.addEventListener("submit", this.#i);
 	}
-	#n;
-	#r;
 	#i;
+	#a;
+	#o;
 	get defaultButton() {
 		let e = "vf-button[variant=\"default\"]";
 		return [...this.querySelectorAll(e), ...this.renderRoot.querySelectorAll(e)].find((e) => !e.matches(":disabled")) ?? null;
 	}
 	get initialFocusTarget() {
-		return this.querySelector("[autofocus]") || ([...this.querySelectorAll("vf-text-field, vf-number-field, vf-text-area, textarea, input")].find((e) => m(e) && !e.matches(":disabled")) ?? this.defaultButton);
+		return this.querySelector("[autofocus]") || ([...this.querySelectorAll("vf-text-field, vf-number-field, vf-text-area, textarea, input")].find((e) => h(e) && !e.matches(":disabled")) ?? this.defaultButton);
 	}
-	#a() {
+	#s() {
 		this.initialFocusTarget?.focus();
 	}
-	#o;
-	#s;
 	#c;
 	#l;
 	#u;
+	#d;
+	#f;
 	show() {
-		this.open = !0, this.hasUpdated && this.#h();
+		this.open = !0, this.hasUpdated && this.#_();
 	}
-	close() {
-		this.open = !1, this.hasUpdated && this.#h();
+	close(e) {
+		this.open && e !== void 0 && (this.#r = e), this.open = !1, this.hasUpdated && this.#_();
 	}
 	updated(e) {
-		e.has("open") && this.#h(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
+		e.has("open") && this.#_(), (e.has("top") || e.has("left")) && this.settle(), this.#t();
 	}
-	#d() {
+	#p() {
 		let e = document.documentElement;
 		return {
-			width: a(e.clientWidth || window.innerWidth, this),
-			height: a(e.clientHeight || window.innerHeight, this)
+			width: o(e.clientWidth || window.innerWidth, this),
+			height: o(e.clientHeight || window.innerHeight, this)
 		};
 	}
-	#f(e, t) {
-		let n = this.#d(), r = a(this._dialog?.offsetWidth ?? 0, this);
+	#m(e, t) {
+		let n = this.#p(), r = o(this._dialog?.offsetWidth ?? 0, this);
 		return {
-			x: Math.min(Math.max(e, f - r), n.width - f),
-			y: Math.min(Math.max(t, 0), Math.max(0, n.height - f))
+			x: Math.min(Math.max(e, p - r), n.width - p),
+			y: Math.min(Math.max(t, 0), Math.max(0, n.height - p))
 		};
 	}
-	#p() {
-		let e = this.#d(), t = this._dialog?.getBoundingClientRect();
+	#h() {
+		let e = this.#p(), t = this._dialog?.getBoundingClientRect();
 		return {
-			x: (e.width - a(t?.width ?? 0, this)) / 2,
-			y: (e.height - a(t?.height ?? 0, this)) / 2
+			x: (e.width - o(t?.width ?? 0, this)) / 2,
+			y: (e.height - o(t?.height ?? 0, this)) / 2
 		};
 	}
 	placeAt(e, t) {
-		let n = this.#f(e, t);
-		this.left = r(n.x, this), this.top = r(n.y, this);
+		let n = this.#m(e, t);
+		this.left = i(n.x, this), this.top = i(n.y, this);
 	}
 	settle() {
 		let e = this._dialog;
@@ -162,10 +171,10 @@ var f = 24, p = /* @__PURE__ */ new Set([
 		let t = this.left != null || this.top != null ? {
 			x: this.left ?? 0,
 			y: this.top ?? 0
-		} : this.#p(), n = this.#f(t.x, t.y);
-		e.style.left = i(r(n.x, this)), e.style.top = i(r(n.y, this)), e.style.right = "auto", e.style.bottom = "auto", e.style.margin = "0";
+		} : this.#h(), n = this.#m(t.x, t.y);
+		e.style.left = a(i(n.x, this)), e.style.top = a(i(n.y, this)), e.style.right = "auto", e.style.bottom = "auto", e.style.margin = "0";
 	}
-	#m() {
+	#g() {
 		let e = this._dialog?.style;
 		if (e) for (let t of [
 			"left",
@@ -175,44 +184,51 @@ var f = 24, p = /* @__PURE__ */ new Set([
 			"margin"
 		]) e.removeProperty(t);
 	}
-	#h() {
+	#_() {
 		let e = this._dialog;
-		e && (this.open && !e.open ? (this.#u = document.activeElement, e.showModal(), this.#a(), this.settle(), this.#y(e), this.#i.attach()) : !this.open && e.open && e.close());
+		e && (this.open && !e.open ? (this.#f = document.activeElement, this.returnValue = "", e.showModal(), this.#s(), this.settle(), this.#x(e), this.#o.attach()) : !this.open && e.open && e.close());
 	}
-	#g;
-	#_;
 	#v;
-	#y(e) {
-		typeof ResizeObserver < "u" && !this.#_ && (this.#_ = new ResizeObserver(this.#g), this.#_.observe(e)), window.addEventListener("resize", this.#g), this.#v ??= n(this.#g);
+	#y;
+	#b;
+	#x(e) {
+		typeof ResizeObserver < "u" && !this.#y && (this.#y = new ResizeObserver(this.#v), this.#y.observe(e)), window.addEventListener("resize", this.#v), this.#b ??= r(this.#v);
 	}
-	#b() {
-		this.#_?.disconnect(), this.#_ = void 0, window.removeEventListener("resize", this.#g), this.#v?.(), this.#v = void 0;
+	#S() {
+		this.#y?.disconnect(), this.#y = void 0, window.removeEventListener("resize", this.#v), this.#b?.(), this.#b = void 0;
 	}
 	disconnectedCallback() {
-		super.disconnectedCallback(), this.#b();
+		super.disconnectedCallback(), this.#S();
 		let e = this._dialog;
 		if (e?.open) {
 			e.close();
-			let t = this.#u, n = document.activeElement;
+			let t = this.#f, n = document.activeElement;
 			t instanceof HTMLElement && t.isConnected && (n === null || n === document.body) && t.focus();
 		}
-		this.#u = null;
+		this.#f = null;
 	}
 	_onNativeCancel() {
 		this.#n = "escape";
 	}
 	_onNativeClose() {
-		let t = this.#n ?? "close";
-		this.#n = null, this.#u = null, this.#r = null, this.#i.detach(), this.#b(), this.open = !1, this.#m(), e(this, "vf-close", { reason: t });
+		let e = this.#n ?? "close", n = this.#r;
+		this.#n = null, this.#r = null, n !== null && (this.returnValue = n), this.#f = null, this.#a = null, this.#o.detach(), this.#S(), this.open = !1, this.#g(), t(this, "vf-close", {
+			reason: e,
+			returnValue: n
+		});
 	}
 };
-o([u({
+s([d({
 	type: Boolean,
 	reflect: !0
-})], g.prototype, "open", void 0), o([u({ type: Number })], g.prototype, "width", void 0), o([u({ type: Number })], g.prototype, "height", void 0), o([u({ type: Number })], g.prototype, "top", void 0), o([u({ type: Number })], g.prototype, "left", void 0), o([u({
+})], _.prototype, "open", void 0), s([d({ type: Number })], _.prototype, "width", void 0), s([d({ type: Number })], _.prototype, "height", void 0), s([d({ type: Number })], _.prototype, "top", void 0), s([d({ type: Number })], _.prototype, "left", void 0), s([d({
 	type: Boolean,
 	reflect: !0,
 	attribute: "light-dismiss"
-})], g.prototype, "lightDismiss", void 0), o([d("dialog")], g.prototype, "_dialog", void 0);
+})], _.prototype, "lightDismiss", void 0), s([f("dialog")], _.prototype, "_dialog", void 0);
+function v(e) {
+	for (let t = e.parentElement; t; t = t.parentElement) if (t instanceof _) return t;
+	return null;
+}
 //#endregion
-export { g as VfModalDialog, h as modalDialogStyles };
+export { _ as VfModalDialog, g as modalDialogStyles };

package/dist/position.js

@@ -70,25 +70,25 @@ var h = class {
 		return u(e.width, e.height, this.#s, t(this.#e));
 	}
 	hostConnected() {
-		this.#a && (this.#r || this.#l) && this.#y();
+		this.#a && (this.#r || this.#l) && this.#b();
 	}
 	hostDisconnected() {
-		this.#b();
+		this.#x();
 	}
 	hostUpdated() {
 		let e = this.#e.top ?? null, t = this.#e.left ?? null, n = this.#e.fixed === !0, r = this.#e.origin ?? null, i = this.#e.style;
 		if (r !== this.#o && (this.#o = r, this.#s = this.#p(r)), e === null && t === null && !n) {
 			if (!this.#a) return;
-			this.#r && this.#v(), this.#b(), this.#a = !1, this.#r = !1, this.#l = !1, this.#u = 0, this.#d = 0, i.removeProperty("position"), i.removeProperty("top"), i.removeProperty("left"), i.removeProperty("right"), i.removeProperty("bottom"), i.removeProperty("margin"), this.#g(null, null);
+			this.#r && this.#y(), this.#x(), this.#a = !1, this.#r = !1, this.#l = !1, this.#u = 0, this.#d = 0, i.removeProperty("position"), i.removeProperty("top"), i.removeProperty("left"), i.removeProperty("right"), i.removeProperty("bottom"), i.removeProperty("margin"), this.#_(null, null);
 			return;
 		}
 		if (this.#a && e === this.#t && t === this.#n && n === this.#r && r === this.#i) return;
 		let a = this.#a && this.#r, o = this.#s !== c;
 		if (this.#a = !0, this.#t = e, this.#n = t, this.#r = n, this.#i = r, this.#l = o, i.position = n ? "sticky" : "absolute", o) {
 			let e = this.#e.getBoundingClientRect();
-			(e.width > 0 || e.height > 0) && this.#h(e.width, e.height);
+			(e.width > 0 || e.height > 0) && this.#g(e.width, e.height);
 		} else this.#u = 0, this.#d = 0;
-		this.#m(), i.right = "auto", i.bottom = "auto", n ? a || this.#_() : (a && this.#v(), i.margin = "0"), n || o ? this.#y() : this.#b(), this.#g(t ?? 0, e ?? 0);
+		this.#m(), i.right = "auto", i.bottom = "auto", n ? a || this.#v() : (a && this.#y(), i.margin = "0", this.#h()), n || o ? this.#b() : this.#x(), this.#_(t ?? 0, e ?? 0);
 	}
 	#p(e) {
 		if (e == null) return c;
@@ -97,49 +97,54 @@ var h = class {
 	}
 	#m() {
 		let e = this.#e.style;
-		e.top = r((this.#t ?? 0) - this.#d), e.left = r((this.#n ?? 0) - this.#u);
+		e.top = r((this.#t ?? 0) - this.#d), e.left = r((this.#n ?? 0) - this.#u), this.#h();
 	}
-	#h(e, n) {
+	#h() {
+		!this.#l || this.#r || (this.#e.style.marginRight = r(-((this.#n ?? 0) - this.#u)));
+	}
+	#g(e, n) {
 		let r = u(e, n, this.#s, t(this.#e));
 		return r.x === this.#u && r.y === this.#d ? !1 : (this.#u = r.x, this.#d = r.y, !0);
 	}
-	#g(t, n) {
+	#_(t, n) {
 		e(this.#e, "vf-placement-change", {
 			left: t,
 			top: n
 		}, { composed: !1 });
 	}
-	#_() {
+	#v() {
 		let e = this.#e.style;
-		e.maxWidth = "fit-content", e.zIndex = "1", this.#x = !1;
+		e.maxWidth = "fit-content", e.zIndex = "1", this.#S = !1;
 		let t = this.#e.getBoundingClientRect();
-		(t.width > 0 || t.height > 0) && this.#S(t.width, t.height);
+		(t.width > 0 || t.height > 0) && this.#C(t.width, t.height);
 	}
-	#v() {
-		this.#x = !1;
+	#y() {
+		this.#S = !1;
 		let e = this.#e.style;
 		e.removeProperty("display"), e.removeProperty("max-width"), e.removeProperty("z-index");
 	}
-	#y() {
+	#b() {
 		this.#f ??= new ResizeObserver((e) => {
 			let t = e[e.length - 1]?.borderBoxSize?.[0], n = t ? {
 				width: t.inlineSize,
 				height: t.blockSize
 			} : this.#e.getBoundingClientRect();
-			this.#r && this.#S(n.width, n.height), this.#l && this.#h(n.width, n.height) && (this.#m(), this.#g(this.#n ?? 0, this.#t ?? 0));
+			this.#r && this.#C(n.width, n.height);
+			let r = n.width > 0 || n.height > 0;
+			this.#l && r && this.#g(n.width, n.height) && (this.#m(), this.#_(this.#n ?? 0, this.#t ?? 0));
 		}), this.#f.observe(this.#e);
 	}
-	#b() {
+	#x() {
 		this.#f?.disconnect(), this.#f = null;
 	}
-	#x = !1;
-	#S(e, t) {
+	#S = !1;
+	#C(e, t) {
 		let n = this.#e.style;
-		if (!this.#x) {
+		if (!this.#S) {
 			let e = getComputedStyle(this.#e).display;
 			if (e) {
 				let t = d[e];
-				t && (n.display = t), this.#x = !0;
+				t && (n.display = t), this.#S = !0;
 			}
 		}
 		n.margin = `0 ${-e}px ${-t}px 0`;

package/dist/shell/alert.d.ts

@@ -1,16 +1,19 @@
 /**
- * The shell's alert: a plain-framed `vf-dialog` with the site's caution art,
+ * The Finder's alert: a plain-framed `vf-dialog` with the site's caution art,
  * a message and a row of buttons, sized to the message — composed from kit
- * elements, as every alert in the kit is.
+ * elements, as every alert in the kit is. Its buttons submit a
+ * `<form method="dialog">`, so it answers with the pressed button's `value`
+ * like any dialog an application holds.
  *
  * The layout follows the plain frame's body, its width and height less 10:
  * the art and the message 16 in from the body's top-left, the buttons'
  * bottom-right corner 16 in from the body's.
  */
+import type { VfDialog } from '../index.js';
 /** One button of an alert. */
 export interface AlertButton {
     label: string;
-    /** What the alert resolves to when it is pressed. */
+    /** What the alert answers when it is pressed. */
     value: string;
     /** The default button, which Return presses. */
     default?: boolean;
@@ -20,13 +23,18 @@ export interface AlertOptions {
     buttons?: AlertButton[];
     /** The dialog's width, system px. Default 400. */
     width?: number;
-    /** The 32×32 art beside the message; default the shell's caution art. */
+    /** The 32×32 art beside the message, or null for none. */
     art?: string | null;
     /** The dialog's accessible name. Default "Alert". */
     label?: string;
 }
-/**
- * Show an alert inside `host` (the desktop), and resolve the value of the
- * button pressed — or null when it closed any other way, Escape say.
- */
-export declare function showAlert(host: Element, message: string, options?: AlertOptions): Promise<string | null>;
+/** An alert, made but not yet shown. */
+export interface ComposedAlert {
+    dialog: VfDialog;
+    /** Resolves once its parts have rendered, so `show()` opens it at once. Call it once the dialog is in the page. */
+    rendered(): Promise<unknown>;
+    /** Size the box to the message. Call it right after `show()`: a closed dialog lays out nothing. */
+    fit(): void;
+}
+/** Make an alert for `message`. */
+export declare function composeAlert(message: string, options?: AlertOptions): ComposedAlert;

package/dist/shell/alert.js

@@ -2,43 +2,40 @@ import { effectiveScale as e } from "../scale.js";
 import "../index.js";
 //#region src/shell/alert.ts
 var t = 10, n = 16, r = 32, i = 28;
-async function a(a, o, s = {}) {
-	let { buttons: c = [{
+function a(a, o = {}) {
+	let { buttons: s = [{
 		label: "OK",
 		value: "ok",
 		default: !0
-	}], width: l = 400, art: u = null, label: d = "Alert" } = s, f = document.createElement("vf-dialog");
-	f.frame = "plain", f.label = d, f.width = l, f.height = 120;
-	let p = u ? 64 : n;
-	if (u) {
+	}], width: c = 400, art: l = null, label: u = "Alert" } = o, d = document.createElement("vf-dialog");
+	d.frame = "plain", d.label = u, d.width = c, d.height = 120;
+	let f = document.createElement("form");
+	f.method = "dialog", f.noValidate = !0;
+	let p = l ? 64 : n;
+	if (l) {
 		let e = document.createElement("vf-img");
 		e.width = r, e.height = r, e.left = n, e.top = n;
 		let t = document.createElement("img");
-		t.src = u, t.alt = "", e.append(t), f.append(e);
+		t.src = l, t.alt = "", e.append(t), f.append(e);
 	}
 	let m = document.createElement("vf-paragraph");
-	m.face = "display", m.width = l - t - p - n, m.left = p, m.top = n, m.textContent = o, f.append(m);
+	m.face = "display", m.width = c - t - p - n, m.left = p, m.top = n, m.textContent = a, f.append(m);
 	let h = document.createElement("vf-button-group");
-	h.origin = "bottom right";
-	let g = c.map((e) => {
+	return h.origin = "bottom right", h.append(...s.map((e) => {
 		let t = document.createElement("vf-button");
-		return t.textContent = e.label, t.dataset.value = e.value, e.default && (t.variant = "default"), t;
-	});
-	h.append(...g), f.append(h), a.append(f), await Promise.all([
-		f.updateComplete,
-		m.updateComplete,
-		h.updateComplete
-	]);
-	let _ = Math.ceil(m.getBoundingClientRect().height / e(m)), v = Math.max(u ? 48 : 0, n + _) + n + i + n;
-	return f.height = v + t, h.left = l - t - n, h.top = v - n, new Promise((e) => {
-		let t = null;
-		for (let e of g) e.addEventListener("click", () => {
-			t = e.dataset.value ?? null, f.close();
-		});
-		f.addEventListener("vf-close", () => {
-			f.remove(), e(t);
-		}, { once: !0 }), f.show();
-	});
+		return t.textContent = e.label, t.type = "submit", t.value = e.value, e.default && (t.variant = "default"), t;
+	})), f.append(h), d.append(f), {
+		dialog: d,
+		rendered: () => Promise.all([
+			d.updateComplete,
+			m.updateComplete,
+			h.updateComplete
+		]),
+		fit() {
+			let r = Math.ceil(m.getBoundingClientRect().height / e(m)), a = Math.max(l ? 48 : 0, n + r) + n + i + n;
+			d.height = a + t, h.left = c - t - n, h.top = a - n;
+		}
+	};
 }
 //#endregion
-export { a as showAlert };
+export { a as composeAlert };

package/dist/shell/finder.d.ts

@@ -23,6 +23,9 @@
  *   View (Arrange Windows), Special (Clean Up, Empty Trash…), each disabled
  *   while it has nothing to act on. A site switches commands off and adds
  *   its own.
+ * - Alerts are the Finder's own, composed with the site's caution art and
+ *   held by it while they are up. A site answers any of them with its own
+ *   dialog through `alertWith`.
  */
 import type { VfIcon, VfMenuItem, VfViewportBox } from '../index.js';
 import type { Catalog, CatalogStorage, Item, Volumes } from './catalog.js';
@@ -43,7 +46,40 @@ export interface FinderArt {
     disk?: string;
     /** 12×12: the mark before the item count in the Trash's window and trashed folders. */
     trashMark?: string;
+    /** 32×32: beside the message in the Finder's alerts. Without it they have no art. */
+    caution?: string;
 }
+/** What a failed command was, in the `failed` alert. */
+export type FinderFailedAction = 'new-folder' | 'empty-trash' | 'paste' | 'add-file';
+/** The Finder's alerts, by id, with the details each one's handler gets. */
+export interface FinderAlerts {
+    /** Special → Empty Trash…: an answer of `'ok'` empties the Trash. */
+    'empty-trash': {
+        count: number;
+        bytes: number;
+    };
+    /** New Folder, Paste or a dropped file, without storage. */
+    'storage-unavailable': Record<string, never>;
+    /** A rename past the limit. */
+    'name-too-long': {
+        limit: number;
+    };
+    /** A rename to nothing. */
+    'name-rejected': Record<string, never>;
+    /** A filing storage refused. */
+    'move-failed': {
+        error: Error;
+    };
+    /** New Folder, Empty Trash, Paste or a dropped file failed. */
+    failed: {
+        action: FinderFailedAction;
+        error: Error;
+    };
+}
+/** One of the Finder's alerts. */
+export type FinderAlert = keyof FinderAlerts;
+/** Answers one of the Finder's alerts: resolves the answer, or null. */
+export type FinderAlertHandler<K extends FinderAlert> = (details: FinderAlerts[K]) => string | null | Promise<string | null>;
 /** The Finder's own commands, each of which a site can switch off. */
 export type FinderCommand = 'open' | 'new-folder' | 'close' | 'copy' | 'paste' | 'select-all' | 'arrange' | 'clean-up' | 'empty-trash';
 /** The Finder's menus, by `data-menu`. */
@@ -85,6 +121,8 @@ export interface FinderApi {
     iconFor(id: string): VfIcon | null;
     /** Add a command to the Finder's menus. Call it from `extend`, before the menus first reach the bar. */
     addCommand(spec: FinderCommandSpec): VfMenuItem;
+    /** Answer one of the Finder's alerts with the site's own dialog. Call it from `extend`. */
+    alertWith<K extends FinderAlert>(id: K, handler: FinderAlertHandler<K>): void;
 }
 export interface FinderOptions {
     /** Where the catalog is kept: `memoryStorage()`, `indexedDbStorage(name)`, the site's own, or null for nothing. */
@@ -107,7 +145,9 @@ export interface FinderOptions {
     cleanUpAfterResize?: boolean;
     /** Switch commands off: `{ 'empty-trash': false }`. */
     commands?: Partial<Record<FinderCommand, boolean>>;
-    /** Add the site's own commands. */
+    /** The site's dialogs for the Finder, each with a `data-dialog` name, held by it: `ctx.dialog(name)` in `extend`. */
+    dialogs?: string;
+    /** Add the site's own commands, and answer the Finder's alerts. */
     extend?(finder: FinderApi, ctx: AppContext): void;
     /** A folder window's size, system px. Default 320 × 223: three columns and two rows of icons. */
     window?: Size;