vintage-frames 0.13.0 → 0.14.1

package/dist/position.d.ts

@@ -97,14 +97,17 @@ type PositionedHost = HTMLElement & {
  * re-asserts a coordinate and costs nothing.
  *
  * **Every write it makes is announced** as `vf-placement-change` (bubbles,
- * `composed: false`, detail `{ left, top }` — nulls on a return to flow). It
- * is an internal coordination event on the terms of the menu handshakes:
- * parent and child share one light tree, and a kit protocol must not leak out
- * of a consumer's shadow boundary. `vf-scroll-area` listens for it and
+ * `composed: false`, detail `{ left, top }` — nulls on a return to flow), so
+ * a page hears every move the one way: a title-bar drag's steps and its
+ * release (an outline drag's single write), an arrow nudge, a drop, a walk's
+ * landing, an `origin` re-measure, and its own property writes. Non-composed,
+ * because parent and child share one light tree and the event has no reason
+ * to leave a consumer's shadow root. It is dispatched from the host's update,
+ * with the new pair already on its style: a handler that writes the pair
+ * again takes effect on the next update. `vf-scroll-area` listens for it and
  * re-measures, because a placed child moved through `top`/`left` changes the
  * scroll range with no box changing anywhere a ResizeObserver can see — the
- * plane's box is never grown by an absolutely positioned child. One funnel
- * covers a drop, an arrow nudge and a page's own `icon.left = …` alike.
+ * plane's box is never grown by an absolutely positioned child.
  *
  * **`origin`** names which point of the host's own box the pair places —
  * nine keywords, vertical then horizontal (`top center`, `bottom right`,
@@ -169,11 +172,26 @@ export declare function placementIn(anchor: Element, clientX: number, clientY: n
     left: number;
     top: number;
 };
-/** The box a gesture is clamped into, in system px — see {@link PlacementClamp}. */
+/**
+ * The box a gesture is clamped into, in system px — see {@link PlacementClamp}.
+ * `width` and `height` are the positioning parent's box; `top` is the least
+ * `top` a placement may take there: 0, or on a desktop's screen the bottom of
+ * its menu bar (`vf-desktop.workArea`).
+ */
 export type PlacementBounds = {
     width: number;
     height: number;
+    top: number;
 };
+/**
+ * The detail of `vf-placement-bounds-request`: the handshake a moved host
+ * makes when its gesture measures the box it is clamped into. A
+ * `vf-desktop` on its light-DOM path fills `bounds` for a host placed on its
+ * screen. Internal to the kit's placement.
+ */
+export interface PlacementBoundsRequest {
+    bounds: PlacementBounds | null;
+}
 /**
  * A moved host's own containment rule, in system px, against the box measured
  * once at the start of the gesture.

package/dist/position.js

@@ -193,10 +193,13 @@ var _ = class {
 		};
 	}
 	#i() {
-		let e = this.#e, t = e.offsetParent, n = t && t.clientWidth > 0 && t.clientHeight > 0 ? t : null;
+		let t = this.#e, n = { bounds: null };
+		if (e(t, "vf-placement-bounds-request", n, { composed: !1 }), n.bounds) return n.bounds;
+		let r = t.offsetParent, a = r && r.clientWidth > 0 && r.clientHeight > 0 ? r : null;
 		return {
-			width: i(n?.clientWidth ?? window.innerWidth, e),
-			height: i(n?.clientHeight ?? window.innerHeight, e)
+			width: i(a?.clientWidth ?? window.innerWidth, t),
+			height: i(a?.clientHeight ?? window.innerHeight, t),
+			top: 0
 		};
 	}
 }, v = /* @__PURE__ */ new Set([

package/dist/shell/alert.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The shell'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.
+ *
+ * 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.
+ */
+/** One button of an alert. */
+export interface AlertButton {
+    label: string;
+    /** What the alert resolves to when it is pressed. */
+    value: string;
+    /** The default button, which Return presses. */
+    default?: boolean;
+}
+export interface AlertOptions {
+    /** Default: OK, the default button. */
+    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. */
+    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>;

package/dist/shell/alert.js

@@ -0,0 +1,44 @@
+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 = [{
+		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) {
+		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);
+	}
+	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);
+	let h = document.createElement("vf-button-group");
+	h.origin = "bottom right";
+	let g = c.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();
+	});
+}
+//#endregion
+export { a as showAlert };

package/dist/shell/catalog.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The catalog: what is where. Pure and DOM-free — it runs under Node — and
+ * the source of truth for what a folder holds; the Finder renders it.
+ *
+ * - An item is a small record: a name, a kind, the container it sits in
+ *   (`parent`, a folder's id, or null for the desktop) and, once placed, its
+ *   position there in whole system px. A kind keeps small data of its own in
+ *   `data`; a large payload stays in its application's own store, keyed by
+ *   the item's id, and the kind's `copy` and `onRemove` keep that store in
+ *   step.
+ * - Volumes are containers no one made: the Trash and a startup disk, each
+ *   if the page wants one. They lead the listing, keep their names, and are
+ *   never renamed, moved, copied or removed; nothing is made in the Trash.
+ *   Deleting is a move into the Trash, and only Empty Trash removes. A
+ *   volume's position is stored on a record of its own id.
+ * - A folder never goes into itself or a folder inside it. A parent with no
+ *   record reads as the desktop.
+ * - An item whose kind no application registers is left out of the listing
+ *   and kept in storage.
+ * - Storage is three calls over item records (list, put, remove). The
+ *   catalog holds every record in memory, writes through to storage, and
+ *   lists from memory; a position change writes after a short delay, since
+ *   the resize rule moves every desktop icon on each resize event.
+ * - A seed runs once per storage: a persistent one stores a marker record
+ *   (`#seeded`), so a site that starts in memory and switches its storage
+ *   seeds once there.
+ */
+import type { Point } from './geometry.js';
+/** The Trash's id. */
+export declare const TRASH = "trash";
+/** The startup disk's id. */
+export declare const DISK = "disk";
+/** A folder's kind. */
+export declare const FOLDER = "folder";
+/** The name a new folder takes, counted up where it is taken. */
+export declare const UNTITLED_FOLDER = "untitled folder";
+/** One item of the catalog. */
+export interface Item {
+    id: string;
+    name: string;
+    /** `folder`, a volume's (`trash`, `disk`), or a kind an application registers. */
+    kind: string;
+    /** A folder's id, a volume's, or null for the desktop. */
+    parent: string | null;
+    /** Its place in its container, whole system px; unset, the next free cell. */
+    left?: number;
+    top?: number;
+    createdAt: number;
+    modifiedAt: number;
+    /** The kind's own, small and serializable. */
+    data?: unknown;
+}
+/** The listing: volumes first, then every listed item by creation. */
+export interface CatalogState {
+    /** Whether storage answers. Without it the catalog lists the volumes alone. */
+    available: boolean;
+    items: readonly Item[];
+}
+/** Where item records live. Any object with these three calls will do. */
+export interface CatalogStorage {
+    list(): Promise<Item[]>;
+    put(item: Item): Promise<unknown>;
+    remove(id: string): Promise<unknown>;
+}
+/** What a kind tells the catalog about its items' payloads. */
+export interface KindHooks {
+    /** Bytes, for Empty Trash's alert. */
+    size?(item: Item): number;
+    /** Copy `from`'s payload to `to`, a fresh copy of it. */
+    copy?(from: Item, to: Item): void | Promise<void>;
+    /** Empty Trash removed the item: drop its payload. */
+    onRemove?(item: Item): void | Promise<void>;
+}
+/** The volumes a page wants, by name; `false` or unset is none (the Trash defaults on). */
+export interface Volumes {
+    trash?: string | false;
+    disk?: string | false;
+}
+export interface CatalogOptions {
+    storage: CatalogStorage | null;
+    volumes?: Volumes;
+    /** Whether an application registers `kind`. Folders are always listed. Default: every kind. */
+    listed?(kind: string): boolean;
+    /** A kind's payload hooks. */
+    hooks?(kind: string): KindHooks | undefined;
+    now?(): number;
+    newId?(): string;
+    /** How long a position change waits before it is written, ms. Default 400. */
+    placeDelay?: number;
+}
+/** What an operation makes: the new item, or null where it was refused. */
+export interface NewItem {
+    name?: string;
+    kind?: string;
+    parent?: string | null;
+    left?: number;
+    top?: number;
+    data?: unknown;
+    /** The creation time, for a batch made in order. Default now. */
+    at?: number;
+}
+/** A catalog dumped or restored: its item records. */
+export interface CatalogArchive {
+    items: Item[];
+}
+/** Whether `kind` holds other items: a folder or a volume. */
+export declare const isContainerKind: (kind: string) => boolean;
+/** Whether `id` names a volume. */
+export declare const isVolume: (id: string | null | undefined) => boolean;
+/** The item with `id`, or null. */
+export declare function itemOf(state: CatalogState, id: string | null | undefined): Item | null;
+/** The container `parent` resolves to: that container while it is listed, else the desktop (null). */
+export declare function containerOf(state: CatalogState, parent: string | null | undefined): string | null;
+/** The items directly in a container (null: the desktop), in listing order. */
+export declare function childrenOf(state: CatalogState, parent: string | null): Item[];
+/** How many items a container holds directly. */
+export declare function itemCount(state: CatalogState, parent: string | null): number;
+/**
+ * Whether `ancestor` is on `id`'s chain of containers. An item is not inside
+ * itself; a looping chain stops at its first repeat.
+ */
+export declare function isInside(state: CatalogState, id: string, ancestor: string): boolean;
+/**
+ * Container `id` and the containers around it, innermost first. The desktop
+ * ends the chain, and so does an id with no container; a loop stops at its
+ * first repeat.
+ */
+export declare function enclosingFolders(state: CatalogState, id: string | null | undefined): string[];
+/** Whether `id` is the Trash or anything inside it. */
+export declare function isTrashed(state: CatalogState, id: string | null | undefined): boolean;
+/** Everything under a container, each container before what it holds; a loop is walked once. */
+export declare function descendantsOf(state: CatalogState, parent: string | null): Item[];
+/** The first free folder name in a container: "untitled folder", "untitled folder 2", … */
+export declare function nextFolderName(state: CatalogState, parent: string | null): string;
+/**
+ * The name for a copy in a container: `name` itself while no item of its
+ * kind there has it, else its base (less " copy" and " copy N") plus " copy",
+ * then " copy 2", " copy 3", …
+ */
+export declare function copyName(state: CatalogState, parent: string | null, name: string, kind: string): string;
+/** The catalog's operations, over its listing. */
+export interface Catalog {
+    get(): CatalogState;
+    subscribe(fn: (state: CatalogState) => void): () => void;
+    item(id: string | null | undefined): Item | null;
+    refresh(): Promise<void>;
+    seed(fn: (catalog: Catalog) => void | Promise<void>): Promise<boolean>;
+    create(input?: NewItem): Promise<Item | null>;
+    rename(id: string, name: string): Promise<boolean>;
+    update(id: string, data: unknown): Promise<boolean>;
+    move(ids: readonly string[], parent: string | null, landings?: ReadonlyMap<string, Point | null>): Promise<string[]>;
+    place(positions: ReadonlyMap<string, Point>): void;
+    flush(): Promise<void>;
+    copy(ids: readonly string[], parent: string | null): Promise<Item[]>;
+    emptyTrash(): Promise<Item[]>;
+    trashSize(): number;
+    dump(): CatalogArchive;
+    clear(): Promise<void>;
+    import(archive: CatalogArchive, options?: {
+        mode?: 'merge' | 'replace';
+    }): Promise<number>;
+    dispose(): Promise<void>;
+}
+export declare function createCatalog(options: CatalogOptions): Catalog;
+/** Storage that forgets everything on a reload. Its map is exposed for tests. */
+export declare function memoryStorage(initial?: readonly Item[]): CatalogStorage & {
+    records: Map<string, Item>;
+};

package/dist/shell/catalog.js

@@ -0,0 +1,278 @@
+//#region src/shell/catalog.ts
+var e = "trash", t = "disk", n = "folder", r = "untitled folder", i = "#seeded", a = (e) => e === "folder" || e === "trash" || e === "disk", o = (e) => e === "trash" || e === "disk";
+function s(e, t) {
+	return t == null ? null : e.items.find((e) => e.id === t) ?? null;
+}
+function c(e, t) {
+	let n = s(e, t);
+	return n && a(n.kind) ? n.id : null;
+}
+function l(e, t) {
+	let n = c(e, t);
+	return e.items.filter((t) => t.id !== n && c(e, t.parent) === n);
+}
+function u(e, t) {
+	return l(e, t).length;
+}
+var d = (e, t) => c(e, s(e, t)?.parent ?? null);
+function f(e, t, n) {
+	let r = /* @__PURE__ */ new Set(), i = d(e, t);
+	for (; i != null && !r.has(i);) {
+		if (i === n) return !0;
+		r.add(i), i = d(e, i);
+	}
+	return !1;
+}
+function p(e, t) {
+	let n = [], r = /* @__PURE__ */ new Set(), i = c(e, t ?? null);
+	for (; i != null && !r.has(i);) n.push(i), r.add(i), i = d(e, i);
+	return n;
+}
+function m(e, t) {
+	return t == null ? !1 : t === "trash" || f(e, t, "trash");
+}
+function h(e, t) {
+	let n = [], r = /* @__PURE__ */ new Set(), i = (t) => {
+		for (let o of l(e, t)) r.has(o.id) || (r.add(o.id), n.push(o), a(o.kind) && i(o.id));
+	};
+	return i(c(e, t)), n;
+}
+function g(e, t) {
+	let i = new Set(l(e, t).filter((e) => e.kind === n).map((e) => e.name));
+	if (!i.has("untitled folder")) return r;
+	for (let e = 2;; e++) {
+		let t = `${r} ${e}`;
+		if (!i.has(t)) return t;
+	}
+}
+var _ = (e) => e.replace(/ copy( \d+)?$/, "");
+function v(e, t, n, r) {
+	let i = new Set(l(e, t).filter((e) => e.kind === r).map((e) => e.name));
+	if (!i.has(n)) return n;
+	let a = _(n);
+	if (!i.has(`${a} copy`)) return `${a} copy`;
+	for (let e = 2;; e++) {
+		let t = `${a} copy ${e}`;
+		if (!i.has(t)) return t;
+	}
+}
+var y = (e, t) => e.createdAt - t.createdAt || (e.id < t.id ? -1 : 1);
+function b(e, t) {
+	let n = { ...e };
+	return t ? (n.left = t.left, n.top = t.top) : (delete n.left, delete n.top), n;
+}
+function x(n) {
+	let { storage: r, volumes: l = {}, listed: u = () => !0, hooks: d = () => void 0, placeDelay: p = 400 } = n, _ = () => (n.now ?? Date.now)(), x = () => n.newId ? n.newId() : crypto.randomUUID(), S = [];
+	l.disk && S.push({
+		id: t,
+		name: l.disk,
+		kind: t,
+		parent: null,
+		createdAt: 0,
+		modifiedAt: 0
+	}), l.trash !== !1 && S.push({
+		id: e,
+		name: l.trash ?? "Trash",
+		kind: e,
+		parent: null,
+		createdAt: 0,
+		modifiedAt: 0
+	});
+	let C = /* @__PURE__ */ new Map(), w = !1, T = !1, E = O(), D = /* @__PURE__ */ new Set();
+	function O() {
+		let e = S.map((e) => {
+			let t = C.get(e.id);
+			return t?.left != null && t.top != null ? {
+				...e,
+				left: t.left,
+				top: t.top
+			} : e;
+		}), t = [...C.values()].filter((e) => !o(e.id) && (e.kind === "folder" || u(e.kind))).sort(y);
+		return {
+			available: w,
+			items: [...e, ...t]
+		};
+	}
+	function k() {
+		E = O();
+		for (let e of [...D]) e(E);
+	}
+	let A = () => {
+		if (!r) throw Error("storage is unavailable");
+		return r;
+	};
+	async function j(e) {
+		await A().put(e), C.set(e.id, e);
+	}
+	let M = /* @__PURE__ */ new Set(), N = null;
+	async function P() {
+		N && clearTimeout(N), N = null;
+		let e = [...M];
+		if (M.clear(), !(!r || !w)) for (let t of e) {
+			let e = C.get(t);
+			e && await r.put(e).catch(() => {});
+		}
+	}
+	let F = (e) => {
+		let t = S.find((t) => t.id === e);
+		return C.get(e) ?? {
+			...t,
+			name: ""
+		};
+	}, I = {
+		get: () => E,
+		subscribe(e) {
+			return D.add(e), () => {
+				D.delete(e);
+			};
+		},
+		item: (e) => s(E, e),
+		async refresh() {
+			if (!r) {
+				C = /* @__PURE__ */ new Map(), w = !1, k();
+				return;
+			}
+			try {
+				let e = await r.list();
+				C = /* @__PURE__ */ new Map(), T = !1;
+				for (let t of e) t.id === i ? T = !0 : C.set(t.id, t);
+				w = !0;
+			} catch (e) {
+				console.warn("vintage-frames/shell: the catalog could not be read —", e), C = /* @__PURE__ */ new Map(), w = !1;
+			}
+			k();
+		},
+		async seed(e) {
+			return !r || !w || T ? !1 : (await e(I), await r.put({
+				id: i,
+				name: "",
+				kind: i,
+				parent: null,
+				createdAt: _(),
+				modifiedAt: _()
+			}), T = !0, !0);
+		},
+		async create(e = {}) {
+			let t = c(E, e.parent ?? null);
+			if (m(E, t)) return null;
+			let n = e.kind ?? "folder", r = e.at ?? _(), i = {
+				id: x(),
+				name: e.name ?? (n === "folder" ? g(E, t) : "untitled"),
+				kind: n,
+				parent: t,
+				createdAt: r,
+				modifiedAt: r
+			};
+			return e.data !== void 0 && (i.data = e.data), e.left != null && e.top != null && (i = b(i, {
+				left: e.left,
+				top: e.top
+			})), await j(i), k(), i;
+		},
+		async rename(e, t) {
+			let n = C.get(e);
+			return !n || o(e) || n.name === t ? !1 : (await j({
+				...n,
+				name: t,
+				modifiedAt: _()
+			}), k(), !0);
+		},
+		async update(e, t) {
+			let n = C.get(e);
+			return !n || o(e) ? !1 : (await j({
+				...n,
+				data: t,
+				modifiedAt: _()
+			}), k(), !0);
+		},
+		async move(e, t, n) {
+			let r = c(E, t), i = [];
+			for (let t of e) {
+				let e = C.get(t);
+				!e || o(t) || r === t || r != null && a(e.kind) && f(E, r, t) || c(E, e.parent) !== r && (M.delete(t), await j(b({
+					...e,
+					parent: r
+				}, n?.get(t) ?? null)), i.push(t));
+			}
+			return i.length && k(), i;
+		},
+		place(e) {
+			let t = !1;
+			for (let [n, r] of e) {
+				let e = o(n) ? S.some((e) => e.id === n) ? F(n) : null : C.get(n);
+				!e || e.left === r.left && e.top === r.top || (C.set(n, b(e, r)), M.add(n), t = !0);
+			}
+			t && (k(), N && clearTimeout(N), N = setTimeout(() => void P(), p));
+		},
+		flush: P,
+		async copy(e, t) {
+			let n = c(E, t);
+			if (m(E, n)) return [];
+			let r = [];
+			for (let t of e) {
+				let e = s(E, t);
+				if (!e || o(t)) continue;
+				let i = a(e.kind) ? h(E, t) : [], l = /* @__PURE__ */ new Map(), u = async (e, t, n) => {
+					let r = _(), i = {
+						...e,
+						id: x(),
+						name: n ? v(E, t, e.name, e.kind) : e.name,
+						parent: t,
+						createdAt: r,
+						modifiedAt: r
+					};
+					return n && (i = b(i, null)), l.set(e.id, i.id), await j(i), await d(e.kind)?.copy?.(e, i), i;
+				};
+				r.push(await u(e, n, !0));
+				for (let e of i) await u(e, l.get(c(E, e.parent) ?? "") ?? null, !1);
+				k();
+			}
+			return r;
+		},
+		async emptyTrash() {
+			let t = h(E, e);
+			for (let e of t) await A().remove(e.id), C.delete(e.id), M.delete(e.id), await d(e.kind)?.onRemove?.(e);
+			return t.length && k(), t;
+		},
+		trashSize() {
+			return h(E, e).reduce((e, t) => e + (d(t.kind)?.size?.(t) ?? 0), 0);
+		},
+		dump() {
+			return { items: [...C.values()] };
+		},
+		async clear() {
+			if (r) {
+				for (let e of await r.list()) e.id !== i && await r.remove(e.id);
+				C = /* @__PURE__ */ new Map(), M.clear(), k();
+			}
+		},
+		async import(e, { mode: t = "merge" } = {}) {
+			let n = e.items.filter((e) => e.id !== i && !o(e.id));
+			if (!n.length || !r) return 0;
+			let a = t === "replace", s = /* @__PURE__ */ new Map();
+			for (let e of n) s.set(e.id, a ? e.id : x());
+			let c = (e) => e == null || o(e) ? e : s.get(e) ?? null;
+			a && await I.clear();
+			for (let e of n) await j({
+				...e,
+				id: s.get(e.id),
+				parent: c(e.parent)
+			});
+			return k(), n.length;
+		},
+		async dispose() {
+			await P(), D.clear();
+		}
+	};
+	return I;
+}
+function S(e = []) {
+	let t = new Map(e.map((e) => [e.id, e]));
+	return {
+		records: t,
+		list: async () => [...t.values()],
+		put: async (e) => t.set(e.id, e),
+		remove: async (e) => t.delete(e)
+	};
+}
+//#endregion
+export { t as DISK, n as FOLDER, e as TRASH, r as UNTITLED_FOLDER, l as childrenOf, c as containerOf, v as copyName, x as createCatalog, h as descendantsOf, p as enclosingFolders, a as isContainerKind, f as isInside, m as isTrashed, o as isVolume, u as itemCount, s as itemOf, S as memoryStorage, g as nextFolderName };

package/dist/shell/clock.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The menu bar's clock: a label in the bar's `end` slot showing the time,
+ * updated on the minute. A press shows the date for a few seconds; a second
+ * press returns to the time early.
+ */
+/** How long a press shows the date, ms. */
+export declare const DATE_HOLD_MS = 3000;
+/** "7:27 PM": 12-hour local time. */
+export declare function formatTime(d: Date): string;
+/** "9/27/26": M/D/YY local date. */
+export declare function formatDate(d: Date): string;
+/** Render the clock into `label` now and on every minute boundary. Returns the stop function. */
+export declare function startClock(label: HTMLElement, { now, holdMs }?: {
+    now?: () => number;
+    holdMs?: number;
+}): () => void;

package/dist/shell/clock.js

@@ -0,0 +1,36 @@
+//#region src/shell/clock.ts
+var e = 3e3, t = (e) => String(e).padStart(2, "0");
+function n(e) {
+	let n = e.getHours();
+	return `${n % 12 || 12}:${t(e.getMinutes())} ${n < 12 ? "AM" : "PM"}`;
+}
+function r(e) {
+	return `${e.getMonth() + 1}/${e.getDate()}/${t(e.getFullYear() % 100)}`;
+}
+function i(t, { now: i = Date.now, holdMs: a = e } = {}) {
+	let o = !1, s = 0, c = 0, l = () => {
+		let e = new Date(i());
+		t.textContent = o ? r(e) : n(e);
+	}, u = () => {
+		c = window.setTimeout(() => {
+			l(), u();
+		}, 6e4 - i() % 6e4 + 20);
+	}, d = () => {
+		clearTimeout(s), s = 0, o = !1, l();
+	}, f = (e) => {
+		if (e.button === 0) {
+			if (e.preventDefault(), o) {
+				d();
+				return;
+			}
+			o = !0, l(), s = window.setTimeout(d, a);
+		}
+	}, p = () => {
+		document.hidden || l();
+	};
+	return l(), u(), t.addEventListener("pointerdown", f), document.addEventListener("visibilitychange", p), () => {
+		clearTimeout(c), clearTimeout(s), t.removeEventListener("pointerdown", f), document.removeEventListener("visibilitychange", p);
+	};
+}
+//#endregion
+export { e as DATE_HOLD_MS, r as formatDate, n as formatTime, i as startClock };

package/dist/shell/filing.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Filing by drag: what a drop of icons means. A drop onto a folder icon
+ * files the icons into that folder at its next free cells; a drop into a
+ * folder window lands each icon where its outline was let go; a drop out of
+ * a window onto the desktop the same. The folder under the pointer wears
+ * `target`. A folder never goes into itself or a folder inside it, and a
+ * drop over another application's window moves nothing. A drop inside the
+ * icons' own field is the kit's: its default action moves them there.
+ *
+ * The Finder runs it over its catalog; a page of its own can run it over the
+ * DOM, with callbacks that say what a container is and what filing does.
+ */
+import type { VfDesktop, VfIcon, VfWindow } from '../index.js';
+import type { Point } from './geometry.js';
+/** What filing needs to know, and what it does. */
+export interface FilingOptions {
+    /**
+     * The container a window shows — a folder's id — or undefined for a
+     * window that holds no icons of the page's: a drop over it moves nothing.
+     */
+    folderOfWindow(win: VfWindow): string | undefined;
+    /** The container a folder icon opens — its folder's id — or undefined for any other icon. */
+    folderOfIcon(icon: VfIcon): string | undefined;
+    /**
+     * The container an icon sits in: a folder's id, or null for the desktop.
+     * Undefined for an icon filing leaves alone, another application's: its
+     * drags go by.
+     */
+    containerOf(icon: VfIcon): string | null | undefined;
+    /** Whether `icons` may go into `folder` (null: the desktop). */
+    canFile(icons: VfIcon[], folder: string | null): boolean;
+    /**
+     * File the icons into `folder` (null: the desktop), each at its landing
+     * there in whole system px, or null for the folder's next free cell.
+     */
+    file(icons: VfIcon[], folder: string | null, landings: Map<VfIcon, Point | null>): void;
+}
+/** Wire filing by drag on a desktop. Returns the teardown. */
+export declare function fileByDrag(desktop: VfDesktop, options: FilingOptions): () => void;