vintage-frames 0.14.0 → 0.15.0

package/dist/components/vf-button.d.ts

@@ -75,7 +75,11 @@ export declare class VfButton extends VfButton_base {
     type: 'button' | 'submit' | 'reset';
     /** Form field name; submitted as `name=value` when `type="submit"`. */
     name: string;
-    /** Value submitted under `name` when `type="submit"`. */
+    /**
+     * Value submitted under `name` when `type="submit"`. In a
+     * `<form method="dialog">` inside a `vf-dialog`, the dialog's answer
+     * (`returnValue`), with or without a `name`.
+     */
     value: string;
     /**
      * The submission overrides native `<button>` carries, honored on

package/dist/components/vf-button.js

@@ -253,7 +253,7 @@ var S = "vf-submitter", C = class extends i(h) {
 		let e = this.resolvedType;
 		if (!this.internals.form || e === "button" || this.isDisabled) return;
 		let t = document.createElement("button");
-		t.type = e, t.slot = S, t.addEventListener("click", (e) => e.stopPropagation()), e === "submit" && (this.name && (t.name = this.name, t.value = this.value), this.formAction && (t.formAction = this.formAction), this.formEnctype && (t.formEnctype = this.formEnctype), this.formMethod && (t.formMethod = this.formMethod), this.formTarget && (t.formTarget = this.formTarget), t.formNoValidate = this.formNoValidate), this.#e = !0;
+		t.type = e, t.slot = S, t.addEventListener("click", (e) => e.stopPropagation()), e === "submit" && (this.name && (t.name = this.name), t.value = this.value, this.formAction && (t.formAction = this.formAction), this.formEnctype && (t.formEnctype = this.formEnctype), this.formMethod && (t.formMethod = this.formMethod), this.formTarget && (t.formTarget = this.formTarget), t.formNoValidate = this.formNoValidate), this.#e = !0;
 		try {
 			this.append(t), t.click();
 		} finally {

package/dist/components/vf-container.d.ts

@@ -43,7 +43,9 @@ declare const VfContainer_base: (new (...args: any[]) => import("../size.js").Vf
  *
  * **It paints nothing and means nothing** — unless `pattern` or `rule` say
  * what to paint. No role, keyboard behavior or selection; what it holds
- * decides what it is.
+ * decides what it is. A page that gives it a role and a `tabindex` — a
+ * pattern chooser's cells as radios — gets the kit's keyboard focus mark
+ * rather than the browser's ring: the dashed rule below the box.
  *
  * **`rule` draws the 1px rule on the edges it names** — `rule="bottom"` is
  * the menu bar's anatomy (the box's rows over one row of ink), `rule="top"`

package/dist/components/vf-container.js

@@ -4,16 +4,18 @@ import n from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js
 import { VfPositioned as r } from "../position.js";
 import { vfBase as i } from "../styles/recipes/host.js";
 import { parsePattern as a } from "../patterns.js";
-import { parseRule as o, ruleClasses as s, vfRule as c } from "../styles/recipes/rule.js";
-import { PatternFillController as l, vfPatternFill as u } from "../pattern-fill.js";
-import { GridSnapController as d } from "../grid-snap.js";
-import { VfSized as f } from "../size.js";
-import { LitElement as p, css as m, html as h } from "lit";
-import { property as g, query as _ } from "lit/decorators.js";
+import { vfStrokeInset as o } from "../styles/recipes/stroke.js";
+import { parseRule as s, ruleClasses as c, vfRule as l } from "../styles/recipes/rule.js";
+import { vfFocusUnderline as u } from "../styles/recipes/focus.js";
+import { PatternFillController as d, vfPatternFill as f } from "../pattern-fill.js";
+import { GridSnapController as p } from "../grid-snap.js";
+import { VfSized as m } from "../size.js";
+import { LitElement as h, css as g, html as _ } from "lit";
+import { property as v, query as y } from "lit/decorators.js";
 //#region src/components/vf-container.ts
-var v = class extends f(r(p)) {
+var b = class extends m(r(h)) {
 	constructor(...e) {
-		super(...e), this._pattern = null, this.#e = !1, this._rule = [], this.#t = !1, this.scale = new t(this), this.gridSnap = new d(this), this.patternFill = new l(this, {
+		super(...e), this._pattern = null, this.#e = !1, this._rule = [], this.#t = !1, this.scale = new t(this), this.gridSnap = new p(this), this.patternFill = new d(this, {
 			getBox: () => this.box,
 			getPattern: () => this._pattern
 		});
@@ -21,9 +23,9 @@ var v = class extends f(r(p)) {
 	static {
 		this.styles = [
 			i,
-			u,
-			c,
-			m`
+			f,
+			l,
+			g`
       :host {
         display: block;
         /* Shrink-wrap an undeclared axis rather than claim the parent's
@@ -74,6 +76,22 @@ var v = class extends f(r(p)) {
         height: 100%;
       }
 
+      /* A box the page makes focusable — a pattern chooser's cells as
+         radios, say — wears the kit's focus mark, not the browser's ring: the
+         dashed rule below the box, one blank row under it, since a box like
+         that is nothing but fill (vf-swatch's placement). The rule spans the
+         box; under forced colors a ruled box's stroke is a border outside the
+         padding box the rule measures from, so the insets grow by it there. */
+      :host(:focus-visible) {
+        outline: none;
+      }
+      :host(:focus-visible) .box::after {
+        ${u}
+        bottom: ${o(-3)};
+        left: ${o(-1)};
+        right: ${o(-1)};
+      }
+
       /* The same two words a child uses, read about the host itself — for the
          parents that can give this box a size: a window body, a filled stack
          column, a grid cell. A percentage is the one fill a page can always
@@ -105,19 +123,19 @@ var v = class extends f(r(p)) {
 	#t;
 	willUpdate(e) {
 		if (super.willUpdate(e), e.has("pattern") && (this._pattern = a(this.pattern), this._pattern === null && this.pattern?.trim() && !this.#e && (this.#e = !0, console.warn(`vf-container: unknown pattern "${this.pattern}" — a library name (docs/PATTERNS.md) or sixteen hex digits. Painting nothing.`))), e.has("rule")) {
-			let e = o(this.rule);
+			let e = s(this.rule);
 			this._rule = e ?? [], e === null && !this.#t && (this.#t = !0, console.warn(`vf-container: unknown rule "${this.rule}" — edge names (top, right, bottom, left) separated by spaces. Drawing none.`));
 		}
 	}
 	render() {
-		let e = s(this._rule);
-		return h`<div
+		let e = c(this._rule);
+		return _`<div
       class="vf-snap box vf-pattern-fill${this._pattern ? " vf-patterned" : ""}${e ? ` ${e}` : ""}"
     >
       <slot></slot>
     </div>`;
 	}
 };
-n([g()], v.prototype, "pattern", void 0), n([g()], v.prototype, "rule", void 0), n([_(".box")], v.prototype, "box", void 0), v = n([e("vf-container")], v);
+n([v()], b.prototype, "pattern", void 0), n([v()], b.prototype, "rule", void 0), n([y(".box")], b.prototype, "box", void 0), b = n([e("vf-container")], b);
 //#endregion
-export { v as VfContainer };
+export { b as VfContainer };

package/dist/components/vf-desktop.d.ts

@@ -36,6 +36,25 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  * reads the current holder, and every change of holder — including to and
  * from none — fires `vf-activate`.
  *
+ * **Hidden windows.** A window with `hidden` — closed by a page that hides
+ * its windows rather than removing them, through `vf-window.hide()` or the
+ * attribute itself — never holds the active state. One slotted hidden waits
+ * to be shown; `bringToFront()` on one gives it its place in the stack and
+ * activates nothing; the holder hiding hands the state to the topmost shown
+ * document window, or to none. A window shown into a tier where none is
+ * active, unless the tier was deliberately deactivated, takes it.
+ * {@link stackingOrder} lists the windows as they stand, bottom-most first.
+ *
+ * **The work area.** A slotted `vf-menu-bar` along the top takes its band
+ * off the screen: {@link workArea} is what is left, and the gestures on the
+ * screen stay in it — a window dragged up stops with its title bar under the
+ * bar, where it can still be grabbed, and an icon dropped, nudged or walked
+ * on the desktop lands below the bar. `window-top` deepens the area for
+ * windows alone ({@link windowArea}), for a page with a strip of its own
+ * under the bar. A gesture asks for the box it is clamped into with
+ * `vf-placement-bounds-request` (bubbles, non-composed), the drag surface's
+ * handshake, and the desktop answers for the hosts placed on its screen.
+ *
  * The desktop is a raster with an explicit size, always: **`width` and
  * `height`**, in system px, the way a WIND resource declared a window's —
  * the host box renders at the declared screen plus `2 × bezel` per axis, a
@@ -88,8 +107,8 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  * @fires vf-activate - The active document-tier window changed. Detail
  *   `{ window: HTMLElement | null }` — the new holder, or `null` when the
  *   document tier deactivated (a {@link clearActive} call, or the active
- *   window leaving the DOM with none behind it). Fired once per change of
- *   holder, never for a re-assertion of the same one.
+ *   window leaving the DOM or hiding with no shown window behind it). Fired
+ *   once per change of holder, never for a re-assertion of the same one.
  * @csspart desktop - The patterned screen surface — the whole-system-px
  *   raster (inset by `bezel` when one is set).
  * @cssprop [--vf-desktop=#808080] - base color under the desktop pattern —
@@ -139,6 +158,38 @@ export declare class VfDesktop extends VfDesktop_base {
      * keeps the dither.
      */
     pattern: string | null | undefined;
+    /**
+     * The least `top` a window may take, in system px from the screen's top —
+     * for a page that keeps a strip of its own under the menu bar, over the
+     * windows. A window dragged on this desktop stops there, and
+     * {@link windowArea} starts there; icons still stop at the menu bar. Below
+     * the bar's bottom it changes nothing. Unset, windows stop at the bar.
+     */
+    windowTop?: number | null;
+    /**
+     * The screen less a slotted `vf-menu-bar` along its top edge, in system
+     * px from the screen's corner (the bezel excluded, as for
+     * {@link placementAt}): `{ left, top, width, height }`. The desktop clamps
+     * the gestures on its screen into it — an icon dropped, nudged or walked
+     * on the desktop lands below the menu bar, where it can be grabbed again.
+     * Without a bar it is the whole screen. Measured at the call.
+     */
+    get workArea(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * {@link workArea}, deepened to {@link windowTop} where that is lower: the
+     * area windows are dragged in. A window's title bar never goes above it.
+     */
+    get windowArea(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
     /**
      * Size the screen to the largest whole-system-px raster whose host box —
      * bezel included — fits a CSS-px bound, and return what was set. The
@@ -223,10 +274,13 @@ export declare class VfDesktop extends VfDesktop_base {
     private readonly _gestureEnd;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    /** Whether a slotted window belongs to the floating (utility) tier. The
-     *  attribute is the source of truth here so a not-yet-upgraded element
-     *  still lands in the right tier (variant reflects, so an upgraded
-     *  property-set window agrees). */
+    /** Whether a slotted window belongs to the floating (utility) tier: the
+     *  `variant` property where the window has one, else the attribute, so a
+     *  not-yet-upgraded element still lands in the right tier. Not the
+     *  attribute alone — it reflects in the window's next update, after a
+     *  window made by script and appended in the same task has been slotted,
+     *  and that palette would land in the document tier and lose its
+     *  `active`. */
     private _isUtility;
     /**
      * Bring a slotted window to the front of its tier. A document-tier window
@@ -247,8 +301,17 @@ export declare class VfDesktop extends VfDesktop_base {
      */
     bringToFront(win: HTMLElement): void;
     /** The active document-tier window, or null while the tier is deactivated
-     *  (or has no windows). Utility windows are never the holder. */
+     *  (or has no shown windows). Utility windows and hidden windows are never
+     *  the holder. */
     get activeWindow(): HTMLElement | null;
+    /**
+     * The slotted windows in stacking order, bottom-most first: the document
+     * tier, then the floating tier above it, each in the order its windows
+     * were last raised. Hidden windows are included where they stand. This is
+     * the order the eye sees; the windows' light-DOM order catches up with it
+     * only once a gesture ends, and a raise by keyboard focus moves no node.
+     */
+    get stackingOrder(): HTMLElement[];
     /**
      * Deactivate the whole document tier — clear `active` from every document
      * window, leaving none the holder. Pages route "the user clicked the
@@ -258,7 +321,11 @@ export declare class VfDesktop extends VfDesktop_base {
      * slotted.
      */
     clearActive(): void;
-    /** The z/active half of a raise, shared by every path. */
+    /**
+     * The z/active half of a raise, shared by every path. A hidden window
+     * takes its place in the stack and nothing else: it activates when it is
+     * shown and raised.
+     */
     private _restack;
     /**
      * Schedule the DOM-order sync: one task from now, coalesced, and never
@@ -316,6 +383,19 @@ export declare class VfDesktop extends VfDesktop_base {
      * detail alone.
      */
     private _onDragSurfaceRequest;
+    /**
+     * A gesture measuring the box it is clamped into (src/position.ts): for a
+     * host placed on this screen — a slotted window, an icon in an unplaced
+     * field — the screen, bezel excluded, and the work area's top as the
+     * floor: {@link windowArea}'s for a window, {@link workArea}'s for
+     * anything else. The floor is rounded up to the host's placement lattice,
+     * so a snapped landing never rounds above it. A host placed in a box of its
+     * own (a window body, a placed field) is that box's; an outer desktop
+     * leaves a filled detail alone.
+     */
+    private _onBoundsRequest;
+    /** The bottom of a slotted, shown menu bar along the screen's top edge, system px; else 0. */
+    private _menuBarFloor;
     /**
      * Delegated focusin: raise the window keyboard focus entered, so tabbing
      * into a background window brings it to front (and reveals its close/zoom
@@ -329,6 +409,19 @@ export declare class VfDesktop extends VfDesktop_base {
     private _windowFromEvent;
     /** Wire up newly slotted windows: seed z-indices, normalize `active`. */
     private _onSlotChange;
+    /**
+     * Resolve who should hold `active` after the window set or a window's
+     * visibility changed: a holder still slotted and shown keeps it, a
+     * deliberate deactivation is preserved (never promote a survivor over the
+     * user's "clicked the Finder"), and only then does the topmost shown
+     * window inherit — the active window left the DOM or was hidden, or a
+     * window was shown into a tier with none active. Applied even when null,
+     * so a stray `active` attribute on slotted markup, or on a hidden window,
+     * is normalized in the deactivated state too.
+     */
+    private _resolveActive;
+    /** Watch the `hidden` attribute of every slotted window, and no other. */
+    private _observeWindows;
     /**
      * Re-assert the single-active-window state after slotted `<vf-window>`
      * elements upgrade. One-shot: the flag collapses repeat slotchanges into a
@@ -365,15 +458,24 @@ export declare class VfDesktop extends VfDesktop_base {
      * Minimal-move: windows already in relative order are never touched (the
      * common case — after one raise, one window moves). Non-window siblings
      * (a menu bar, page content) keep their positions; only a window that must
-     * cross the stack moves past them. Moving a node containing the focused
-     * element drops focus to `<body>`, so it is restored afterwards — behind
-     * `_restoringFocus`, because the restore re-fires focusin (see
-     * {@link _onFocusIn}) on an element that may sit in a background window.
+     * cross the stack moves past them. `moveBefore()` keeps the focus inside a
+     * moved window where the browser has it ({@link _move}); re-inserting a
+     * node containing the focused element drops focus to `<body>`, so it is
+     * restored afterwards — behind `_restoringFocus`, because the restore
+     * re-fires focusin (see {@link _onFocusIn}) on an element that may sit in a
+     * background window.
      * Reached only through {@link _requestDomSync}'s task — after a pointer
      * gesture or a programmatic raise, never from a focus-driven one (see
      * {@link _raise} for why).
      */
     private _syncDomOrder;
+    /**
+     * Move a slotted window before `before`: with `Element.moveBefore()` where
+     * the browser has it, which keeps the focus inside the window — a rename
+     * field, a text field's caret — through the move; else by re-inserting it,
+     * and {@link _syncDomOrder} puts the focus back.
+     */
+    private _move;
     protected willUpdate(changed: PropertyValues<this>): void;
     protected updated(changed: Map<PropertyKey, unknown>): void;
     protected render(): unknown;