vintage-frames 0.19.0 → 0.19.1

package/dist/components/vf-menu-item.d.ts

@@ -1,4 +1,5 @@
 import { LitElement } from 'lit';
+import type { VfMenu } from './vf-menu.js';
 declare const VfMenuItem_base: (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
 /**
  * `<vf-menu-item>` — a single command inside a `<vf-menu>` panel.
@@ -10,6 +11,11 @@ declare const VfMenuItem_base: (new (...args: any[]) => import("../position.js")
  * 3-blink inversion (~250ms), then dispatches `vf-menu-select` and asks its
  * ancestors to close the menu.
  *
+ * A `<vf-menu>` in the `submenu` slot makes the item open a submenu: it ends
+ * in ▶ where a shortcut would go, and choosing it opens the submenu beside
+ * it rather than firing `vf-menu-select`. The item stays highlighted while
+ * its submenu is open.
+ *
  * Takes `top`/`left` like every other element ({@link VfPositioned}), for the
  * consumer who wants a row somewhere other than a pulldown. Inside its parent
  * `<vf-menu>` the panel is as wide as its widest row and stacks them in flow,
@@ -18,10 +24,12 @@ declare const VfMenuItem_base: (new (...args: any[]) => import("../position.js")
  * it says — but not how a pulldown is laid out.
  *
  * @slot - The item label.
+ * @slot submenu - A `vf-menu`, the submenu the item opens.
  * @csspart item - The row container.
  * @csspart check - The ✓ checkmark glyph (rendered when `checked`).
  * @csspart label - The label wrapper around the default slot.
  * @csspart shortcut - The shortcut text, left-aligned in the shared column.
+ * @csspart arrow - The ▶ of an item that opens a submenu.
  * @fires vf-menu-select - After the blink completes. `detail: { value, item }`.
  *   Named for the menu rather than plain `vf-select`, which would collide with
  *   the `<vf-select>` popup on any delegated ancestor listener (that component
@@ -46,12 +54,19 @@ export declare class VfMenuItem extends VfMenuItem_base {
     /** Shows the classic ✓ checkmark in the left gutter. */
     checked: boolean;
     /**
-     * Transient highlight — the full-row inversion the press-drag gesture paints
-     * on the row under the pointer (`:hover` can't: under touch the pointer is
-     * captured by the title the press started on). Managed by the menu, mirroring
-     * `vf-option[active]`; not part of the authoring API.
+     * Transient highlight — the full-row inversion on the row under the pointer
+     * while its menu is open, button down or not (`:hover` can't: under touch
+     * the pointer is captured by the title the press started on), or on the
+     * item whose submenu is open while the pointer is elsewhere. Managed by the
+     * menu, mirroring `vf-option[active]`; not part of the authoring API.
      */
     active: boolean;
+    /**
+     * Whether this item's submenu is open. Reflected, and announced as
+     * `aria-expanded`. Managed by the menu ({@link VfMenu.expand}), like
+     * {@link active}; not part of the authoring API.
+     */
+    expanded: boolean;
     /**
      * Declares the item a *checkable* toggle up front, so it carries
      * `role="menuitemcheckbox"` and `aria-checked="false"` from the first render
@@ -78,11 +93,21 @@ export declare class VfMenuItem extends VfMenuItem_base {
     shortcut: string;
     /**
      * Value reported in the `vf-menu-select` event detail. Defaults to the item's
-     * trimmed text content when unset.
+     * {@link labelText} when unset.
      */
     value?: string;
     /** `'on' | 'off'` while the selection blink runs, otherwise `null`. */
     private _blinkPhase;
+    /** Whether a `vf-menu` sits in the `submenu` slot. */
+    private _hasSubmenu;
+    /** The submenu this item opens: the `vf-menu` in its `submenu` slot, or null. */
+    get submenu(): VfMenu | null;
+    /**
+     * The item's label as text: what its default slot holds, trimmed, without
+     * the rows of a submenu. The default {@link value} and the menus'
+     * type-ahead read it, and it names an item that opens a submenu.
+     */
+    get labelText(): string;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -95,6 +120,9 @@ export declare class VfMenuItem extends VfMenuItem_base {
      * over, which the row's own `click` never sees (a press that started on the
      * title dispatches its click above both of them). No-op while disabled or
      * already blinking.
+     *
+     * An item that opens a submenu is never chosen: it opens the submenu and
+     * moves focus to its first enabled item, as Enter, Space and → do.
      */
     activate(): void;
 }

package/dist/components/vf-menu-item.js

@@ -7,47 +7,47 @@ import { vfDisplay as o } from "../styles/recipes/display-face.js";
 import { vfBase as s } from "../styles/recipes/host.js";
 import { releaseAfterGesture as c } from "../document-listeners.js";
 import { runSelectionBlink as l } from "../motion.js";
-import { CHECKMARK as u, glyphSvg as d } from "../glyphs.js";
-import { LitElement as f, css as p, html as m, nothing as h } from "lit";
-import { property as g, state as _ } from "lit/decorators.js";
-import { classMap as v } from "lit/directives/class-map.js";
+import { CARET_RIGHT as u, CHECKMARK as d, glyphSvg as f } from "../glyphs.js";
+import { LitElement as p, css as m, html as h, nothing as g } from "lit";
+import { property as _, state as v } from "lit/decorators.js";
+import { classMap as y } from "lit/directives/class-map.js";
 //#region src/components/vf-menu-item.ts
-var y = /* @__PURE__ */ new Map([
+var b = /* @__PURE__ */ new Map([
 	["⌃", "Control"],
 	["⌥", "Alt"],
 	["⇧", "Shift"],
 	["⌘", "Meta"]
-]), b = /* @__PURE__ */ new Map([
+]), x = /* @__PURE__ */ new Map([
 	["←", "ArrowLeft"],
 	["↑", "ArrowUp"],
 	["→", "ArrowRight"],
 	["↓", "ArrowDown"]
-]), x = (e) => b.get(e) ?? e;
-function S(e) {
+]), S = (e) => x.get(e) ?? e;
+function C(e) {
 	let t = [...e.trim()], n = [];
-	for (; t.length > 0 && y.has(t[0]);) n.push(y.get(t.shift()));
+	for (; t.length > 0 && b.has(t[0]);) n.push(b.get(t.shift()));
 	let r = t.join("");
-	return r ? [...n, x(r)].join("+") : "";
+	return r ? [...n, S(r)].join("+") : "";
 }
-function C(e, t) {
+function w(e, t) {
 	let n = [...t.trim()], r = {
 		Meta: !1,
 		Control: !1,
 		Alt: !1,
 		Shift: !1
 	};
-	for (; n.length > 0 && y.has(n[0]);) r[y.get(n.shift())] = !0;
+	for (; n.length > 0 && b.has(n[0]);) r[b.get(n.shift())] = !0;
 	let i = n.join("");
 	if (!i || !r.Meta && !r.Control && !r.Alt && [...i].length === 1) return !1;
 	let a = r.Meta ? e.metaKey || e.ctrlKey : !e.metaKey, o = r.Control ? e.ctrlKey : r.Meta || !e.ctrlKey;
-	return a && o && e.altKey === r.Alt && e.shiftKey === r.Shift && e.key.toLowerCase() === x(i).toLowerCase();
+	return a && o && e.altKey === r.Alt && e.shiftKey === r.Shift && e.key.toLowerCase() === S(i).toLowerCase();
 }
-var w = class extends a(f) {
+var T = class extends a(p) {
 	static {
 		this.styles = [
 			s,
 			o,
-			p`
+			m`
       :host {
         display: block;
         cursor: var(--vf-cursor, default);
@@ -137,15 +137,46 @@ var w = class extends a(f) {
       .item.has-shortcut {
         padding-right: calc(var(--vf-scale, 1) * 1px);
       }
+      /* An item that opens a submenu ends in ▶ where a shortcut would go: 8px
+         in from the row's end, as in Menus.png's submenu rows and a System 7.5
+         capture alike, and 2 rows down the 16px row (centered, the odd row
+         below). The 8px before it is the label↔▶ minimum, as the shortcut's
+         is, and only binds in the row that sets the panel's width. */
+      .item.has-submenu {
+        padding-right: calc(var(--vf-scale, 1) * 8px);
+      }
+      .arrow {
+        flex: none;
+        align-self: flex-start;
+        display: block;
+        margin: calc(var(--vf-scale, 1) * 2px) 0 0 calc(var(--vf-scale, 1) * 8px);
+      }
+      .arrow svg {
+        display: block;
+        width: calc(var(--vf-scale, 1) * 6px);
+        height: calc(var(--vf-scale, 1) * 11px);
+      }
+      /* What the submenu hangs from: a box as wide as the row at the row's
+         top, which the submenu's panel places itself against (vf-menu). Out
+         of flow, so the submenu never adds to its parent panel's width. */
+      .submenu {
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+      }
       :host([disabled]) .item {
         color: var(--vf-disabled, #c0c0c0);
       }
-      /* Highlight = full-width inversion (hover, the press-drag's [active],
-         keyboard focus, blink "on"). blink-on is scoped to the enabled host
-         like its siblings: an item disabled mid-blink has its timer cancelled
-         (see updated()), and this keeps it from flashing even for the frame
-         before that lands. */
-      :host(:not([disabled])) .item:hover,
+      /* Highlight = full-width inversion (the menu's [active], keyboard
+         focus, blink "on"; hover only for a row outside a menu). Inside a
+         menu the pointer's row is the menu's to say, since the item whose
+         submenu is open stays lit while the pointer is in the submenu, and
+         :hover would light a second row. blink-on is scoped to the enabled
+         host like its siblings: an item disabled mid-blink has its timer
+         cancelled (see updated()), and this keeps it from flashing even for
+         the frame before that lands. */
+      :host(:not([disabled])) .item:not(.in-menu):hover,
       :host(:not([disabled])[active]) .item,
       :host(:not([disabled]):focus) .item,
       :host(:not([disabled])) .item.blink-on {
@@ -173,84 +204,117 @@ var w = class extends a(f) {
     `
 		];
 	}
+	get submenu() {
+		for (let e of this.children) if (e.localName === "vf-menu" && e.slot === "submenu") return e;
+		return null;
+	}
+	get labelText() {
+		let e = "";
+		for (let t of this.childNodes) t instanceof Element ? t.slot || (e += t.textContent ?? "") : t.nodeType === Node.TEXT_NODE && (e += t.textContent ?? "");
+		return e.trim();
+	}
 	#e;
 	#t;
 	#n;
 	#r;
 	#i;
 	constructor() {
-		super(), this.scale = new r(this), this.disabled = !1, this.checked = !1, this.active = !1, this.checkable = !1, this.shortcut = "", this._blinkPhase = null, this.#t = !1, this.#n = !1, this.#r = this.attachInternals(), this.#i = !1, this.#d = (e) => {
-			e.defaultPrevented || e.isComposing || this.disabled || !this.shortcut || this.closest("vf-menu[shortcuts], vf-menu-bar[shortcuts]") && C(e, this.shortcut) && (e.preventDefault(), !(e.repeat || this.#t) && (t(this, "vf-menu-flash-request", { item: this }, { composed: !1 }), this.activate()));
-		}, this.addEventListener("keydown", this.#u), this.addEventListener("pointerdown", this.#c), this.addEventListener("click", this.#l);
+		super(), this.scale = new r(this), this.disabled = !1, this.checked = !1, this.active = !1, this.expanded = !1, this.checkable = !1, this.shortcut = "", this._blinkPhase = null, this._hasSubmenu = !1, this.#t = !1, this.#n = !1, this.#r = this.attachInternals(), this.#i = !1, this.#s = () => {
+			let e = this._hasSubmenu;
+			this.#r.ariaHasPopup = e ? "menu" : null, this.#r.ariaExpanded = e ? String(this.expanded) : null, this.#r.ariaLabel = e && this.labelText || null;
+		}, this.#c = () => {
+			this._hasSubmenu = this.submenu !== null;
+		}, this.#m = (e) => {
+			e.defaultPrevented || e.isComposing || this.disabled || !this.shortcut || this._hasSubmenu || this.closest("vf-menu[shortcuts], vf-menu-bar[shortcuts]") && w(e, this.shortcut) && (e.preventDefault(), !(e.repeat || this.#t) && (t(this, "vf-menu-flash-request", { item: this }, { composed: !1 }), this.activate()));
+		}, this.addEventListener("keydown", this.#p), this.addEventListener("pointerdown", this.#d), this.addEventListener("click", this.#f);
 	}
 	get #a() {
 		return this.checkable || this.#n;
 	}
 	connectedCallback() {
-		super.connectedCallback(), this.#s(), this.#o(), this.hasAttribute("tabindex") || (this.tabIndex = -1), document.addEventListener("keydown", this.#d);
+		super.connectedCallback(), this._hasSubmenu = this.submenu !== null, this.#u(), this.#o(), this.#s(), this.requestUpdate(), this.hasAttribute("tabindex") || (this.tabIndex = -1), document.addEventListener("keydown", this.#m);
 	}
 	disconnectedCallback() {
-		super.disconnectedCallback(), document.removeEventListener("keydown", this.#d), this.#f();
+		super.disconnectedCallback(), document.removeEventListener("keydown", this.#m), this.#h();
 	}
 	updated(e) {
-		e.has("disabled") && (this.#r.ariaDisabled = this.disabled ? "true" : null, this.disabled && this.#f()), e.has("checked") && this.checked && (this.#n = !0), (e.has("checked") || e.has("checkable")) && this.#s(), e.has("shortcut") && this.#o();
+		e.has("disabled") && (this.#r.ariaDisabled = this.disabled ? "true" : null, this.disabled && this.#h()), e.has("checked") && this.checked && (this.#n = !0), (e.has("checked") || e.has("checkable")) && this.#u(), (e.has("shortcut") || e.has("_hasSubmenu")) && this.#o(), (e.has("expanded") || e.has("_hasSubmenu")) && this.#s();
 	}
 	#o() {
-		this.#r.ariaKeyShortcuts = S(this.shortcut) || null;
+		this.#r.ariaKeyShortcuts = !this._hasSubmenu && C(this.shortcut) || null;
+	}
+	#s;
+	#c;
+	#l(e) {
+		let t = this.submenu;
+		return t !== null && e.composedPath().includes(t);
 	}
-	#s() {
+	#u() {
 		this.#a ? (this.#r.role = "menuitemcheckbox", this.#r.ariaChecked = this.checked ? "true" : "false") : (this.#r.role = "menuitem", this.#r.ariaChecked = null);
 	}
 	render() {
-		let e = {
+		let e = this._hasSubmenu, t = {
 			item: !0,
-			"has-shortcut": this.shortcut !== "",
+			"in-menu": this.closest("vf-menu") !== null,
+			"has-shortcut": !e && this.shortcut !== "",
+			"has-submenu": e,
 			"blink-on": this._blinkPhase === "on",
 			"blink-off": this._blinkPhase === "off"
 		};
-		return m`
-      <div class=${v(e)} part="item">
-        ${this.checked ? m`<span class="check" part="check" aria-hidden="true"
-              >${d(u, "checkmark")}</span
-            >` : h}
-        <span class="label" part="label"><slot></slot></span>
-        ${this.shortcut ? m`<span class="shortcut" part="shortcut" aria-hidden="true"
-              >${this.shortcut}</span
-            >` : h}
+		return h`
+      <div class=${y(t)} part="item">
+        ${this.checked ? h`<span class="check" part="check" aria-hidden="true"
+              >${f(d, "checkmark")}</span
+            >` : g}
+        <span class="label" part="label"><slot @slotchange=${this.#s}></slot></span>
+        ${e ? h`<span class="arrow" part="arrow" aria-hidden="true"
+              >${f(u, "caret")}</span
+            >` : this.shortcut ? h`<span class="shortcut" part="shortcut" aria-hidden="true"
+                >${this.shortcut}</span
+              >` : g}
+        <div class="submenu">
+          <slot name="submenu" @slotchange=${this.#c}></slot>
+        </div>
       </div>
     `;
 	}
-	#c() {
-		this.#i = this.closest("vf-menu") !== null, this.#i && c(() => {
+	#d(e) {
+		this.#l(e) || (this.#i = this.closest("vf-menu") !== null, this.#i && c(() => {
 			this.#i = !1;
-		});
+		}));
 	}
-	#l(t) {
-		if (this.#i) {
-			this.#i = !1;
-			return;
+	#f(t) {
+		if (!this.#l(t)) {
+			if (this.#i) {
+				this.#i = !1;
+				return;
+			}
+			e(this, t, () => this.activate());
 		}
-		e(this, t, () => this.activate());
 	}
-	#u(e) {
-		(e.key === "Enter" || e.key === " ") && (e.preventDefault(), e.stopPropagation(), this.activate());
+	#p(e) {
+		this.#l(e) || (e.key === "Enter" || e.key === " ") && (e.preventDefault(), e.stopPropagation(), this.activate());
 	}
-	#d;
+	#m;
 	activate() {
 		if (this.disabled || this.#t) return;
+		if (this._hasSubmenu) {
+			this.closest("vf-menu")?.expand(this, { focus: !0 });
+			return;
+		}
 		this.#t = !0;
 		let e = l((e) => {
 			this._blinkPhase = e ? "on" : "off";
 		}, () => {
-			this._blinkPhase = null, this.#t = !1, this.#e = void 0, this.#p();
+			this._blinkPhase = null, this.#t = !1, this.#e = void 0, this.#g();
 		});
 		this.#t && (this.#e = e);
 	}
-	#f() {
+	#h() {
 		this.#t && (this.#e?.cancel(), this.#e = void 0, this.#t = !1, this._blinkPhase = null);
 	}
-	#p() {
-		let e = this.value ?? (this.textContent ?? "").trim();
+	#g() {
+		let e = this.value ?? this.labelText;
 		t(this, "vf-menu-select", {
 			value: e,
 			item: this
@@ -259,18 +323,21 @@ var w = class extends a(f) {
 		(!n || n.hasAttribute("open")) && t(this, "vf-menu-close-request", { item: this }, { composed: !1 });
 	}
 };
-i([g({
+i([_({
+	type: Boolean,
+	reflect: !0
+})], T.prototype, "disabled", void 0), i([_({
 	type: Boolean,
 	reflect: !0
-})], w.prototype, "disabled", void 0), i([g({
+})], T.prototype, "checked", void 0), i([_({
 	type: Boolean,
 	reflect: !0
-})], w.prototype, "checked", void 0), i([g({
+})], T.prototype, "active", void 0), i([_({
 	type: Boolean,
 	reflect: !0
-})], w.prototype, "active", void 0), i([g({
+})], T.prototype, "expanded", void 0), i([_({
 	type: Boolean,
 	reflect: !0
-})], w.prototype, "checkable", void 0), i([g()], w.prototype, "shortcut", void 0), i([g()], w.prototype, "value", void 0), i([_()], w.prototype, "_blinkPhase", void 0), w = i([n("vf-menu-item")], w);
+})], T.prototype, "checkable", void 0), i([_()], T.prototype, "shortcut", void 0), i([_()], T.prototype, "value", void 0), i([v()], T.prototype, "_blinkPhase", void 0), i([v()], T.prototype, "_hasSubmenu", void 0), T = i([n("vf-menu-item")], T);
 //#endregion
-export { w as VfMenuItem };
+export { T as VfMenuItem };

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

@@ -17,6 +17,16 @@ declare const VfMenu_base: (new (...args: any[]) => import("../position.js").VfP
  * onto a command, release over it) and a modern quick tap that leaves the menu
  * dropped for a second click.
  *
+ * A `vf-menu` in a `vf-menu-item`'s `submenu` slot is a **submenu**: no title,
+ * only its panel, opened beside its item by the menu holding the item
+ * ({@link expand}). The pointer resting on the item opens it in either style,
+ * and so do a click or tap on the item, →, Enter and Space. It overlaps its
+ * parent as System 7.5's did: its first row level with its item, its frame
+ * 5px inside the parent's right edge, covering the parent's frame and
+ * shadow. It opens on the side its parent opened toward, the right first,
+ * flips where that side has no room, and moves up to fit the screen. Menus
+ * nest to any depth.
+ *
  * Takes `top`/`left` like every other element ({@link VfPositioned}) — the
  * natural fit being a standalone menu, which is a free-standing menu button and
  * places like any other control. The panel is anchored to the host's own box
@@ -95,6 +105,31 @@ export declare class VfMenu extends VfMenu_base {
      * src/menu-press.ts), so it wants the box, not the element.
      */
     get labelRect(): DOMRect | null;
+    private _panelEl;
+    /**
+     * Viewport rect of the dropped panel, or `null` while closed. The press
+     * gesture hit-tests the open menus by their panels, deepest first.
+     */
+    get panelRect(): DOMRect | null;
+    /** The item in this menu whose submenu is open, or `null`. */
+    get expandedItem(): VfMenuItem | null;
+    /**
+     * Opens `item`'s submenu, closing the one open in this menu and everything
+     * under it; `null` closes it. With `focus`, keyboard focus goes on to the
+     * submenu's first enabled item. The press gesture, the keyboard and an
+     * item's `activate()` all open submenus through here. Does nothing while
+     * this menu is closed, or for a disabled item or one without a submenu.
+     */
+    expand(item: VfMenuItem | null, options?: {
+        focus?: boolean;
+    }): void;
+    /**
+     * Where the pointer is, from the press gesture: on `row` of this menu's
+     * panel, on none of its rows (`null`), or not in its panel (`undefined`).
+     * The row under the pointer is highlighted; with the pointer elsewhere, the
+     * item whose submenu is open is. Not part of the authoring API.
+     */
+    pointerOver(row: VfMenuItem | null | undefined): void;
     /** `true` while the key-equivalent flash paints the title inverted. */
     private _flashOn;
     connectedCallback(): void;