vintage-frames 0.1.0

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

@@ -0,0 +1,117 @@
+import { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
+declare const VfLabel_base: (new (...args: any[]) => import("../size.js").VfSizedInterface) & (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
+/**
+ * `<vf-label>` — a static System 7 caption.
+ *
+ * The "Name:" beside a field, the "Mode" heading over a group of radios, a
+ * numeric readout beside a slider. Text the page was previously setting by hand
+ * in the display face — this is that, as a component, on the kit's grid:
+ *
+ * - the **Chicago-style chrome face** by default (dialog captions are chrome),
+ *   with `face="body"` to switch to Geneva — which is also the kit's fine
+ *   print, as it was System 7's: a dialog's small captions are Geneva 9 at
+ *   its own strike size;
+ * - a **whole-system-pixel line box at the face's native pitch**
+ *   (`--vf-label-line-height`: 16px — Chicago 12's own line, which is also the
+ *   em; `face="body"` drops to 12px, Geneva 9's), so a column of captions
+ *   accumulates whole offsets instead of pushing what follows off the
+ *   device-pixel grid the way a ratio `line-height` does (docs/SIZING.md
+ *   rule 2);
+ * - its own {@link GridSnapController}, so the bitmap stems stay on the grid
+ *   wherever the page puts it;
+ * - a **declared `width`** ({@link VfSized}) — the shared width of a caption
+ *   column, so a run of label-and-field rows lands every field on one x.
+ *   Left to its text a caption measures whatever its glyphs measure (the
+ *   showcase's Apple menu title came to 32.641 system px) and anything sized
+ *   from it inherits the fraction; a declared width is whole, and so is the
+ *   row built on it (layout contract rule 3). A caption wider than its column
+ *   overflows rather than reflowing the row: the number is the column, and a
+ *   caption that doesn't fit is a number to raise.
+ *
+ * `for` points at a control by id, as a native `<label>` does — clicking the
+ * caption focuses that control, and the caption text becomes its accessible
+ * name (see {@link for} for how, and for what it deliberately doesn't do).
+ *
+ * Chrome text, so the host is not selectable (SPEC §1); prose belongs in
+ * `<vf-paragraph>`, which is.
+ *
+ * @slot - The caption text.
+ * @csspart label - The inner text box.
+ * @cssprop --vf-label-line-height - The caption's own line box, in system px.
+ *   Unset (the default) the box follows the face tokens below; set, it
+ *   overrides both faces for labels alone. Keep any override a whole *even*
+ *   number — a ratio puts every following line off the grid, and an odd value
+ *   halves into the em's half-leading and puts the baseline on a half pixel.
+ * @cssprop --vf-line-height - The body face's native line (default `12px`,
+ *   Geneva 9's) — the face-level knob a body-face retheme states alongside
+ *   `--vf-font-family` / `--vf-font-size`.
+ * @cssprop --vf-line-height-display - The display face's native line
+ *   (default `16px`, Chicago 12's) — the display retheme's third number.
+ */
+export declare class VfLabel extends VfLabel_base {
+    #private;
+    static styles: import("lit").CSSResult[];
+    /** Default-on display scaling (true 72dpi size); see src/scale.ts. */
+    private readonly scale;
+    /** Device-pixel grid snapping (opt in with applyGridSnap()); see src/grid-snap.ts. */
+    private readonly gridSnap;
+    /**
+     * The id of the control this caption names, resolved in the label's own tree
+     * scope (its document or shadow root), like a native `<label for>`.
+     *
+     * Two things follow from it. **Clicking the caption focuses the control** —
+     * a focus shortcut, not an activation: the kit's toggles carry their own
+     * labels, so forwarding a click to one would double up on the label they
+     * already have. And **the caption text becomes the control's accessible
+     * name**, by whichever route reaches it:
+     *
+     * - a `vf-*` control's focusable element lives in its shadow root, where an
+     *   `aria-label` on the host cannot reach it — which is why each of them
+     *   exposes a `label` property that lands on the inner control. That property
+     *   is what gets filled in, and only when the consumer left it empty.
+     * - anything else (a native `<input>`, an element with a role) is in this
+     *   label's own tree scope, so an `aria-labelledby` id reference works; it is
+     *   set only when the target has no name of its own — and a name computed
+     *   from the target's *content* counts: a `vf-checkbox` with slotted text, a
+     *   `vf-button`, a native `<button>` are already named by what they show, and
+     *   the caption declines rather than stamping over it.
+     *
+     * The one target neither route reaches is a control whose focusable element
+     * is shadow-internal but which exposes no `label` property because it names
+     * from content — `vf-button` is the kit's case. With visible text it needs
+     * no caption; an icon-only one should carry its name on the art (`alt` on
+     * the slotted `<img>`), which name-from-content picks up the same way.
+     *
+     * Either way the label puts back what it found when it is removed, the id
+     * changes, or the caption text does.
+     *
+     * Left `undefined` rather than `''` so an unset `for` reflects no attribute
+     * at all: `vf-label[for]` is a selector a page will reasonably write, and an
+     * empty `for=""` on every plain caption would make it match all of them.
+     */
+    for?: string;
+    /**
+     * Which embedded face to set the caption in — `'display'` (the Chicago-style
+     * chrome face, the default) or `'body'` (Geneva). Applied by
+     * `vfStaticText`; declared here so it types and reflects.
+     */
+    face?: 'display' | 'body';
+    /**
+     * Greys the caption to `--vf-disabled`. System 7 dims the label, not the
+     * control (SPEC §1), so this is what a caption beside a disabled control
+     * wears — the control keeps its solid black box.
+     */
+    dim: boolean;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'vf-label': VfLabel;
+    }
+}
+export {};

package/dist/components/vf-label.js

@@ -0,0 +1,151 @@
+import { vfElement as e } from "../define.js";
+import { ScaleController as t } from "../scale.js";
+import n from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { VfPositioned as r } from "../position.js";
+import { vfDisplayDecls as i } from "../styles/recipes/display-face.js";
+import { vfBase as a } from "../styles/recipes/host.js";
+import { vfStaticText as o } from "../styles/recipes/static-text.js";
+import { GridSnapController as s } from "../grid-snap.js";
+import { VfSized as c } from "../size.js";
+import { LitElement as l, css as u, html as d } from "lit";
+import { property as f } from "lit/decorators.js";
+//#region src/components/vf-label.ts
+var p = 0, m = /* @__PURE__ */ new Set([
+	"button",
+	"checkbox",
+	"link",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"radio",
+	"switch",
+	"tab",
+	"treeitem"
+]);
+function h(e) {
+	if (!(e.textContent ?? "").trim()) return !1;
+	let t = e.getAttribute("role");
+	if (t) return m.has(t.split(/\s+/)[0] ?? "");
+	let n = e.localName;
+	return n.includes("-") ? !0 : n === "button" || n === "summary" || n === "a" && e.hasAttribute("href");
+}
+var g = class extends c(r(l)) {
+	static {
+		this.styles = [
+			a,
+			o,
+			u`
+      :host {
+        /* A real box, so a page can give a caption column a shared width
+           (layout contract rule 3) — inline text can't take one. */
+        display: inline-block;
+        /* Chrome by default; vfStaticText's face="body" overrides it. */
+        ${i}
+        /* Whole system px, never a ratio — see the class comment. The pitch
+           is the face's, so it reads the face token under a per-component
+           override. 16px is Chicago 12's native line and the faces' own em
+           (12 above the baseline + 4 below), which is also vf-menu-item's row
+           pitch, so a caption beside a menu or a popup sits on the same
+           rhythm. */
+        line-height: calc(
+          var(--vf-scale, 1) *
+            var(--vf-label-line-height, var(--vf-line-height-display, 16px))
+        );
+        cursor: var(--vf-cursor, default);
+      }
+      /* Fine print sits on Geneva 9's native 12px line, like the paragraph's
+         body copy and vf-icon's name plate — the 16px em centers into it,
+         baseline at 10. Later sheet than vfStaticText's face rule, so the
+         pitch follows the face. */
+      :host([face='body']) {
+        line-height: calc(
+          var(--vf-scale, 1) *
+            var(--vf-label-line-height, var(--vf-line-height, 12px))
+        );
+      }
+    `
+		];
+	}
+	#e;
+	#t;
+	constructor() {
+		super(), this.scale = new t(this), this.gridSnap = new s(this), this.dim = !1, this.#e = null, this.#r = () => {
+			this.for && this.#a();
+		}, this.#i = () => {
+			this.isConnected && this.#a();
+		}, this.#s = () => {
+			let e = this.#n();
+			e && ((e.isDisabled ?? e.hasAttribute("disabled")) || e.focus());
+		}, this.addEventListener("click", this.#s);
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.#t ??= new MutationObserver(() => {
+			this.for && this.#i();
+		}), this.#t.observe(this, {
+			characterData: !0,
+			childList: !0,
+			subtree: !0
+		}), this.#a();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback(), this.#t?.disconnect(), this.#o();
+	}
+	updated(e) {
+		e.has("for") && this.#a();
+	}
+	render() {
+		return d`<span class="vf-snap" part="label"
+      ><slot @slotchange=${this.#r}></slot
+    ></span>`;
+	}
+	#n() {
+		if (!this.for) return null;
+		let e = this.getRootNode();
+		return e instanceof Document || e instanceof ShadowRoot ? e.getElementById(this.for) : null;
+	}
+	#r;
+	#i;
+	#a() {
+		this.#o();
+		let e = this.#n();
+		if (!e) {
+			this.for && document.readyState === "loading" && document.addEventListener("DOMContentLoaded", this.#i, { once: !0 });
+			return;
+		}
+		let t = e.localName;
+		if (t.includes("-") && !customElements.get(t)) {
+			customElements.whenDefined(t).then(() => {
+				this.isConnected && !this.#e && this.#a();
+			});
+			return;
+		}
+		let n = (this.textContent ?? "").trim();
+		if (n) {
+			if ("label" in e) {
+				typeof e.label == "string" && !e.label && (e.label = n, this.#e = {
+					target: e,
+					via: "property",
+					value: n
+				});
+				return;
+			}
+			e.hasAttribute("aria-label") || e.hasAttribute("aria-labelledby") || h(e) || (this.id ||= `vf-label-${++p}`, e.setAttribute("aria-labelledby", this.id), this.#e = {
+				target: e,
+				via: "aria",
+				value: this.id
+			});
+		}
+	}
+	#o() {
+		let e = this.#e;
+		this.#e = null, e && (e.via === "property" ? e.target.label === e.value && (e.target.label = "") : e.target.getAttribute("aria-labelledby") === e.value && e.target.removeAttribute("aria-labelledby"));
+	}
+	#s;
+};
+n([f({ reflect: !0 })], g.prototype, "for", void 0), n([f({ reflect: !0 })], g.prototype, "face", void 0), n([f({
+	type: Boolean,
+	reflect: !0
+})], g.prototype, "dim", void 0), g = n([e("vf-label")], g);
+//#endregion
+export { g as VfLabel };

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

@@ -0,0 +1,48 @@
+import { LitElement } from 'lit';
+/**
+ * `<vf-list-item>` — a row inside a `<vf-list>` list box.
+ *
+ * A 20px-tall single-line row; when selected the entire row inverts
+ * (white-on-black), the classic System 7 selection style. Selection and
+ * keyboard focus are managed by the parent `<vf-list>`.
+ *
+ * @slot - The row's text/content.
+ * @slot icon - A leading graphic — usually a `vf-img` holding a 16×16 System 7
+ *   small icon, but any element rides here. The row lays it out as the icon
+ *   gutter: flex-centered vertically (keep the difference between the row
+ *   height and the icon height even, so the centering offset stays a whole
+ *   pixel — 16 in a 20px row is a whole 2px), with the reference art's 4px gap
+ *   to the text. Contributes no text, so first-letter type-ahead still reads
+ *   the row's words. On a selected row the graphic rides the inverted bar
+ *   as-is — System 7 left color icons unfiltered on the highlight.
+ * @csspart text - The text span beside the icon gutter (ellipsizes).
+ */
+export declare class VfListItem extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult[];
+    private readonly scale;
+    /** The value this row contributes to the list's `value`/`values`. */
+    value: string;
+    /** Whether the row is selected (inverted). Managed by `<vf-list>`. */
+    selected: boolean;
+    /** Disables the row: dimmed text, not selectable or focusable. */
+    disabled: boolean;
+    /**
+     * True while the containing `<vf-list>` is disabled. Managed by the list —
+     * not intended to be set by consumers. Kept distinct from `disabled` so
+     * re-enabling the list doesn't clear rows that are disabled in their own
+     * right. (The dimming already arrives by inheritance: the list host sets
+     * `color: var(--vf-disabled)` and rows inherit it.) Mirrors
+     * `vf-radio.groupDisabled`.
+     */
+    listDisabled: boolean;
+    constructor();
+    connectedCallback(): void;
+    protected updated(changed: Map<PropertyKey, unknown>): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'vf-list-item': VfListItem;
+    }
+}

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

@@ -0,0 +1,98 @@
+import { vfElement as e } from "../define.js";
+import { ScaleController as t } from "../scale.js";
+import n from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { vfBase as r } from "../styles/recipes/host.js";
+import { vfFocusRing as i } from "../styles/recipes/focus.js";
+import { emit as a } from "../events.js";
+import { LitElement as o, css as s, html as c } from "lit";
+import { property as l } from "lit/decorators.js";
+//#region src/components/vf-list-item.ts
+var u = class extends o {
+	static {
+		this.styles = [r, s`
+      :host {
+        display: flex;
+        align-items: center;
+        /* Icon-to-text gap, per the reference art (Menus.png's icon-gutter
+           popup: 16px icon cell, 4px to the first glyph). Collapses to
+           nothing when the icon slot is empty — no icon, no flex item. */
+        gap: calc(var(--vf-scale, 1) * 4px);
+        height: calc(var(--vf-scale, 1) * 20px);
+        line-height: calc(var(--vf-scale, 1) * 20px);
+        padding: 0 calc(var(--vf-scale, 1) * 6px);
+        cursor: var(--vf-cursor, default);
+        background: transparent;
+      }
+      ::slotted([slot='icon']) {
+        flex: none;
+      }
+      .text {
+        /* min-width lets the span shrink below its content so the ellipsis
+           can happen (flex items otherwise floor at min-content). */
+        flex: 1;
+        min-width: 0;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      /* Plain :focus, not :focus-visible — vf-list drives a roving tabindex and
+         moves the cursor with item.focus(), and programmatic focus that isn't
+         preceded by a keyboard event doesn't match :focus-visible, so a
+         mouse-clicked cursor row would show no ring until the next Arrow key.
+         The roving tabindex guarantees only the cursor row is focusable, so
+         :focus is exactly the cursor. Matches sibling vf-menu-item. On a
+         *selected* row the ring rides currentColor (see vfFocusRing) and
+         inverts to white on the highlight bar — it has to stay legible there,
+         because in multiple mode Ctrl+Arrow deliberately moves the cursor
+         across selected rows while Space still acts on it. */
+      :host(:focus) {
+        --vf-focus-offset: -1px;
+        ${i}
+      }
+      :host([selected]) {
+        background: var(--vf-highlight, #000);
+        color: var(--vf-highlight-text, #fff);
+        /* Forced colors: both tokens already remap to the user's
+           Highlight/HighlightText pair (vfBase), but the mode also paints an
+           opaque Canvas READABILITY BACKPLATE behind any text run whose
+           backdrop it doesn't consider a flat opaque color — and Chromium's
+           Highlight carries alpha, so the plate lands ON the highlight bar
+           and the row's text drowns in it (measured: the bar renders as a
+           Canvas slab under HighlightText ink). Opting the inverted row out
+           of forced adjustments drops the backplate; every color in play is
+           a system pair anyway, so this changes nothing else. The same
+           exemption rides every 1-bit inversion in the kit — vf-option,
+           vf-menu-item, vf-menu's open label, vf-icon's plate. */
+        @media (forced-colors: active) {
+          forced-color-adjust: none;
+        }
+      }
+      :host([disabled]) {
+        color: var(--vf-disabled, #c0c0c0);
+      }
+    `];
+	}
+	#e;
+	constructor() {
+		super(), this.scale = new t(this), this.value = "", this.selected = !1, this.disabled = !1, this.listDisabled = !1, this.#e = this.attachInternals(), this.#e.role = "option";
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.hasAttribute("tabindex") || (this.tabIndex = -1);
+	}
+	updated(e) {
+		e.has("selected") && (this.#e.ariaSelected = this.selected ? "true" : "false"), (e.has("disabled") || e.has("listDisabled")) && (this.#e.ariaDisabled = this.disabled || this.listDisabled ? "true" : null), e.has("disabled") && e.get("disabled") !== void 0 && a(this, "vf-list-item-disabled-change", { item: this }, { composed: !1 });
+	}
+	render() {
+		return c`<slot name="icon"></slot
+      ><span class="text" part="text"><slot></slot></span>`;
+	}
+};
+n([l()], u.prototype, "value", void 0), n([l({
+	type: Boolean,
+	reflect: !0
+})], u.prototype, "selected", void 0), n([l({
+	type: Boolean,
+	reflect: !0
+})], u.prototype, "disabled", void 0), n([l({ attribute: !1 })], u.prototype, "listDisabled", void 0), u = n([e("vf-list-item")], u);
+//#endregion
+export { u as VfListItem };

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

@@ -0,0 +1,77 @@
+import { LitElement } from 'lit';
+declare const VfList_base: (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
+/**
+ * `<vf-list>` — the classic System 7 list box.
+ *
+ * A white, black-bordered scrolling box of `<vf-list-item>` rows with the
+ * kit-drawn System 7 scroll rail (dither trough, boxed arrow buttons, fixed
+ * thumb — the shared `vfScrollRail` subtree, synced to the native scrolling
+ * by {@link ScrollRailController}). The vertical rail is a permanent
+ * placeholder — arrows on an empty white channel when the rows fit, the
+ * dither and thumb filling in only on overflow (driven by
+ * {@link ScrollStateController}). Selection inverts rows. Supports single and
+ * multiple selection, roving tabindex, arrow-key navigation, and classic Finder
+ * first-letter type-ahead.
+ *
+ * Max height defaults to 200px; override with `--vf-list-max-height`.
+ *
+ * @slot - `vf-list-item` elements.
+ * @csspart list - The scrolling viewport around the slotted items.
+ * @fires vf-change - When the user changes the selection.
+ *   `detail: { value: string, values: string[] }`.
+ * @cssprop [--vf-list-max-height=200px] - `vf-list` max height before its rail
+ *   takes over (the host adds the 2px frame)
+ * @cssprop --vf-scrollbar-thumb - scrollbar thumb/elevator (white)
+ * @cssprop --vf-scrollbar-track - the scroll trough's base color under the
+ *   dot-dither (white)
+ */
+export declare class VfList extends VfList_base {
+    #private;
+    static styles: import("lit").CSSResult[];
+    private readonly scale;
+    /** Device-pixel grid snapping (opt in with applyGridSnap()); see src/grid-snap.ts. */
+    private readonly gridSnap;
+    private viewport;
+    private content;
+    /** Reserves the vertical rail and toggles it active on overflow. */
+    private readonly scrollState;
+    /** Syncs the drawn rail to the row viewport and drives its interactions. */
+    private readonly rail;
+    /** Whether the rows actually overflow the box (either axis). */
+    private _scrollable;
+    /** Allows multiple selection (Shift extends, Cmd/Ctrl toggles). */
+    multiple: boolean;
+    /** Value of the (first) selected item. Settable. */
+    value: string;
+    /** Values of all selected items (multiple mode). Settable. */
+    values: string[];
+    /** Disables the whole list: dimmed, no interaction. */
+    disabled: boolean;
+    /**
+     * Accessible name for the list, applied as `aria-label` on the host (which
+     * carries `role="listbox"`). Without it a caption-less list is announced
+     * anonymously. A consumer-supplied `aria-label`/`aria-labelledby` attribute
+     * is left alone.
+     */
+    label: string;
+    private _items;
+    constructor();
+    /**
+     * Moves keyboard focus to the row holding the roving tab stop — or, while
+     * the list is disabled, to the scrolling viewport (the disabled list's own
+     * Tab stop; the rows are all at -1 then). Overridden because the platform's
+     * `focus()` is a silent no-op on this host — no `delegatesFocus`, no host
+     * tabindex — so `vf-label for` (which calls `target.focus()`) never reached
+     * the list.
+     */
+    focus(options?: FocusOptions): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<PropertyKey, unknown>): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'vf-list': VfList;
+    }
+}
+export {};