vintage-frames 0.1.0

package/dist/scale.d.ts

@@ -0,0 +1,259 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { CLASSIC_DPI, CSS_REFERENCE_DPI, SYSTEM_PX_IN_CSS_PX } from './zoom.js';
+/**
+ * Display scaling — replicate the classic 72 dpi "system pixel" on modern
+ * screens.
+ *
+ * Vintage Frames' components are authored in *system pixels* (the 1-bit art
+ * grid: a 1px border, a 13px checkbox, a 22px control). A system pixel is
+ * 1/{@link CLASSIC_DPI} inch — the Macintosh screen the art was drawn for — and
+ * the job here is to put that size on a modern display without ever landing on
+ * a fractional device pixel.
+ *
+ * So the device-pixel count is *computed from the display*
+ * ({@link devicePxPerSystemPx}): `round(96/72 × trueDpr)`, the whole count
+ * nearest 1/72 inch, where 96 is {@link CSS_REFERENCE_DPI} and `trueDpr` is
+ * {@link truePixelRatio} — device px per CSS px *including* zoom, which
+ * `window.devicePixelRatio` reports in Chrome/Firefox but not Safari. The scale
+ * is that count divided back into CSS px:
+ *
+ *   1× display  → 1 device px  → scale 1.0    (1 CSS px × 1 dpr)
+ *   1.5× (Win)  → 2 device px  → scale 1.333  (1.333 CSS px × 1.5 dpr)
+ *   2× retina   → 3 device px  → scale 1.5    (1.5 CSS px × 2 dpr)
+ *   3× display  → 4 device px  → scale 1.333  (1.333 CSS px × 3 dpr)
+ *
+ * Zoom needs no term of its own: it multiplies device px per CSS px, so it is
+ * already inside `trueDpr`, and a zoomed page walks the same ladder (a 2×
+ * display at 200% is trueDpr 4 → 5 device px). The kit therefore grows with the
+ * page instead of dividing the zoom back out and holding its physical size
+ * while the copy around it doubles. The invariant is `--vf-scale × trueDpr = a
+ * whole device-px count`; because the count is always whole, the art is crisp
+ * at every density and every zoom level.
+ *
+ * Components multiply their metrics by the inherited `--vf-scale` custom
+ * property in `calc()`; JS geometry uses {@link sys} / {@link toSys} to
+ * convert between system and CSS px. The scale is a plain multiplier, so
+ * nesting never compounds: a window and a button inside it each scale their
+ * own metrics once.
+ *
+ * Nothing here runs automatically — a component with no `--vf-scale` in scope
+ * renders at 1× (today's behavior). Opt in with {@link applyScale} or by setting
+ * `--vf-scale` yourself.
+ */
+export { CLASSIC_DPI, CSS_REFERENCE_DPI, SYSTEM_PX_IN_CSS_PX };
+/**
+ * The CSS scale factor for the current display and zoom:
+ * `devicePxPerSystemPx(trueDpr) / trueDpr`. The numerator is whole, so the
+ * product with `trueDpr` is whole — the scale contract — and the value is
+ * `SYSTEM_PX_IN_CSS_PX` (1.333) to within the rounding.
+ */
+export declare function getScale(): number;
+/**
+ * The effective `--vf-scale` in force at `el` — the resolved custom property
+ * CSS multiplies every metric by. Reading the computed value keeps JS geometry
+ * in the SAME coordinate system as CSS: a consumer/ancestor override
+ * (`:root{--vf-scale:1}`, `.dense{--vf-scale:1.25}`) wins for both, so
+ * JS-written positions (drag origins, slider fill, panel placement, resize
+ * floors) never drift off the device grid the way a hardcoded `3/dpr` would.
+ * Falls back to the display scale when no property is in scope (before connect /
+ * SSR), matching {@link ScaleController}'s own default.
+ */
+export declare function effectiveScale(el: Element): number;
+/** Convert system (art) units to display (CSS) px, honoring `--vf-scale` at `el`. */
+export declare function sys(value: number, el: Element): number;
+/**
+ * A length of `size` system px as a CSS length that stays live: the scale is
+ * read at paint time, so the box follows the display the way every metric
+ * declared in a component's stylesheet does. `sys()` resolves the number *now*
+ * and freezes it; this is what a size written onto an element belongs in.
+ *
+ * `undefined` gives back the empty string — the inline declaration is removed
+ * and the box goes back to whatever layout gives it. So does `null`, which is
+ * what Lit's Number converter hands back when the attribute is *removed* rather
+ * than never set; `0` is a real length and still emits one.
+ */
+export declare function sysLength(size: number | null | undefined): string;
+/**
+ * A CSS shorthand of one to four system-px lengths — `padding`, `margin`,
+ * `inset` — each one live against `--vf-scale` the way {@link sysLength}'s
+ * single value is. `12` gives one length, `'10 12'` two, and so on in the usual
+ * top/right/bottom/left order.
+ *
+ * Whole system px only: a fractional entry is truncated rather than passed
+ * through, because an 8.5-system-px padding is precisely the off-grid metric
+ * the layout contract exists to prevent (docs/SIZING.md rule 2). A value that can't be
+ * read as one to four whole numbers gives back the empty string — the
+ * declaration is removed rather than half-applied.
+ */
+export declare function sysLengths(value: number | string | null | undefined): string;
+/** Convert display (CSS) px to whole system (art) units, honoring `--vf-scale` at `el`. */
+export declare function toSys(value: number, el: Element): number;
+/**
+ * Convert display (CSS) px to system units *without* rounding — the seed
+ * conversion for geometry that is about to be snapped onto the placement
+ * lattice anyway ({@link snapSys}), where rounding twice only loses precision.
+ */
+export declare function toSysExact(value: number, el: Element): number;
+/**
+ * Snap a CSS-px coordinate onto the device-pixel grid.
+ *
+ * The 1-bit art is only crisp when its container's origin sits on a whole
+ * device pixel: at a fractional origin every edge inside — clip-path
+ * staircases, 1px borders, stripes, dithers, bitmap glyphs — rasterizes with
+ * fractional coverage and grows a gray antialiasing fringe. Positions
+ * declared in CSS as `calc(var(--vf-scale) * Npx)` land on the grid by
+ * construction (N system px = 3N device px), but positions written from JS
+ * (pointer drags report fractional clientX/Y on trackpads, computed styles
+ * resolve percentages fractionally) must round through this before being
+ * applied.
+ *
+ * At an integral density the snap is to whole CSS px — still whole device px
+ * (1 CSS px = dpr device px). Historically that was also what kept WebKit's
+ * native scrollbar rects (which it pinned to whole CSS px) on the frame; the
+ * kit now draws its own scroll rails, so the whole-CSS-px lift survives on
+ * its remaining merits: drag granularity of one CSS px instead of one device
+ * px is imperceptible, engines still quantize sub-CSS-px paint per box (the
+ * border-floor wobble), and the dpr-2 baseline nudge always
+ * takes its known whole-CSS-px rendering rather than sometimes its exact
+ * half-px one. Fractional densities keep the finest crisp grid: whole device
+ * px.
+ */
+export declare function snapToDevicePx(value: number): number;
+/**
+ * Snap a CSS-px coordinate or length onto the system-pixel grid — the art's
+ * own unit — as resolved by `--vf-scale` at `el`.
+ *
+ * Window chrome geometry (title-bar drags, grow-box sizes, dialog pins) is
+ * held to whole system pixels rather than merely whole device pixels: a
+ * window N system px wide keeps every interior metric — the flexing body, an
+ * edge-mounted scroll rail — a whole count of system px too, and drags step
+ * whole art pixels, the way QuickDraw moved windows. Every step is a whole
+ * count of device px by the scale contract (`scale × dpr` integral), so the
+ * 1-bit art stays fringe-free.
+ *
+ * The step is the smallest run of system px that is also whole in CSS px —
+ * one system px at dpr 1 and 3, two at dpr 2's 1.5 scale, where an odd count
+ * lands an edge on a half CSS px. The lift earns its keep at dpr 2: engines
+ * still quantize sub-CSS-px paint per box (floored borders distribute their
+ * half-CSS slack by snap direction — the border-floor wobble), so whole-CSS
+ * edges are the positions every line renders the same at. It was once also
+ * load-bearing for the native scrollbars WebKit pinned to whole CSS px; the
+ * kit draws its own rails now, and the lattice keeps its gesture and
+ * art-crispness roles. A scale whole in no small run (a fractional density)
+ * falls back to single system px: whole device px, the finest crisp grid
+ * there.
+ */
+export declare function snapToSystemPx(value: number, el: Element): number;
+/**
+ * The placement lattice **in system px**: the smallest run of k ≤ 4 system px
+ * that is also whole in CSS px at `el`'s scale (see {@link snapToSystemPx} for
+ * why dpr 2 takes two). Identical to the historical behavior at 100% zoom
+ * (k = 1 for scales 3 and 1, k = 2 for 1.5); under zoom the scale can be a
+ * ratio like 5/3, where k = 3 is what keeps every drag step whole in CSS px —
+ * the positions every engine-quantized line (see {@link snapToSystemPx})
+ * renders the same at. A scale whole in no k ≤ 4 falls back to single system
+ * px: whole device px, the finest crisp grid there. The float tolerance absorbs a scale
+ * that round-trips through a custom-property string (5/3 stringifies and parses
+ * exactly, but k × scale can land a few ulps off a whole number).
+ *
+ * The quantum moves with the scale, which is why a *stored* placement has to be
+ * re-snapped when the display or zoom changes: 94 system px is legal at k = 2
+ * and lands on a half CSS px at k = 3. Whole system px is always whole device
+ * px (the scale contract), so that re-snap is about the CSS-px edge alone.
+ */
+export declare function systemPxQuantum(el: Element): number;
+/**
+ * Snap a **system-px** coordinate onto the placement lattice
+ * ({@link systemPxQuantum}) — the system-px twin of {@link snapToSystemPx},
+ * and the one gestures use, because a placement is *stored* in system px and
+ * written as a live `calc()` ({@link sysLength}) so it survives a zoom.
+ */
+export declare function snapSys(value: number, el: Element): number;
+type ScaleListener = (scale: number) => void;
+/**
+ * Watch for anything that moves the scale *or* the device grid under it — the
+ * window moving to a different-density monitor (via a resolution media query),
+ * or the user changing browser zoom (via `onZoomChange`, which also carries
+ * Safari's dpr-invisible zoom) — and invoke `callback` with the new scale.
+ * Returns a cleanup function.
+ *
+ * Ordering guarantee: by the time a callback runs, every `--vf-scale` the kit
+ * itself manages (component defaults via {@link ScaleController}, a root set
+ * by {@link applyScale}) has already been updated — so reading
+ * {@link effectiveScale} or a computed style inside the callback is sound.
+ * The full-screen pattern (`onScaleChange(fit)` re-deriving a
+ * `vf-desktop` raster) depends on this.
+ */
+export declare function onScaleChange(callback: ScaleListener): () => void;
+/**
+ * Opt a subtree into true-size rendering: set `--vf-scale` on `target` (default
+ * the document root) to the dynamic scale and keep it in sync as the display
+ * changes. Returns a cleanup function that stops watching (it leaves the last
+ * value in place). Strictly opt-in — call it once from your app.
+ */
+export declare function applyScale(target?: HTMLElement): () => void;
+/**
+ * Reactive controller that makes true-size rendering the DEFAULT for a
+ * component: on connect it sets `--vf-scale` to the display scale
+ * ({@link getScale}) on the host — UNLESS a `--vf-scale` is already in scope
+ * (a consumer or ancestor
+ * override always wins) — and keeps it synced as the display's dpr changes.
+ * Because `--vf-scale` is a plain inherited multiplier, a component whose
+ * ancestor already set it just inherits that value (no compounding).
+ *
+ * Add one line to each component:  `new ScaleController(this)`.
+ */
+export declare class ScaleController implements ReactiveController {
+    private readonly host;
+    private stop?;
+    /**
+     * True once THIS controller has written the inline `--vf-scale`, so a
+     * reconnect resumes syncing the value it already owns.
+     *
+     * Ownership cannot be sniffed from the inline property merely being present:
+     * on a *first* connect that value is the consumer's own
+     * (`<vf-window style="--vf-scale:1">`), and treating it as ours overwrote
+     * exactly the override the contract promises always wins.
+     */
+    private owns;
+    constructor(host: ReactiveControllerHost & HTMLElement);
+    /**
+     * True while the connect-time read was not yet trustworthy, so the decision
+     * is waiting for the host to be rendered (see {@link decide}).
+     */
+    private pending;
+    hostConnected(): void;
+    /**
+     * Re-decide once the host has rendered. Controllers' `hostUpdated` runs
+     * before the component's own `firstUpdated`/`updated` and before paint, so a
+     * deferred takeover still lands in the first frame and ahead of any JS
+     * geometry the component derives from {@link sys}.
+     */
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    /**
+     * A consumer/ancestor value always wins: an inline value we did not write, or
+     * any value inherited from a rule, leaves the controller dormant. Only take
+     * over when the property is genuinely unset — or when it is already ours from
+     * a previous connect.
+     *
+     * `deferrable` marks the connect-time call, whose inherited read can be a
+     * false negative: Lit attaches a shadow root synchronously on connect but
+     * renders its `<slot>`s on the first update, so during the
+     * `customElements.define` sweep a light-DOM child whose parent upgraded first
+     * is assigned to no slot. Such an element sits outside the flat tree — it
+     * still reports a computed style, because its own rules apply, but it
+     * inherits nothing, so `--vf-scale` reads back empty whether or not the page
+     * set one. Taking over on that read is how three components ended up pinned
+     * at 3× inside a `:root { --vf-scale: 1 }` page; which components were hit
+     * was pure module-evaluation order.
+     */
+    private decide;
+    /**
+     * Whether inherited properties can resolve on the host at all: every shadow
+     * host between it and the document must have assigned it (or its ancestor) to
+     * a slot. Keeps a host whose parent renders its slot late — or never — from
+     * being decided on an unresolvable read.
+     */
+    private inFlatTree;
+}

package/dist/scale.js

@@ -0,0 +1,133 @@
+import { CLASSIC_DPI as e, CSS_REFERENCE_DPI as t, SYSTEM_PX_IN_CSS_PX as n, devicePxPerSystemPx as r, onZoomChange as i, truePixelRatio as a } from "./zoom.js";
+//#region src/scale.ts
+function o() {
+	let e = a() || 1;
+	return r(e) / e;
+}
+function s(e) {
+	return parseFloat(getComputedStyle(e).getPropertyValue("--vf-scale")) || o();
+}
+function c(e, t) {
+	return e * s(t);
+}
+function l(e) {
+	return e == null ? "" : `calc(var(--vf-scale, 1) * ${e}px)`;
+}
+function u(e) {
+	if (e == null) return "";
+	let t = String(e).trim().split(/\s+/).filter(Boolean).slice(0, 4);
+	if (t.length === 0) return "";
+	let n = t.map((e) => {
+		let t = Math.trunc(Number(e));
+		return Number.isFinite(t) ? l(t) : "";
+	});
+	return n.every(Boolean) ? n.join(" ") : "";
+}
+function d(e, t) {
+	return Math.round(e / s(t));
+}
+function f(e, t) {
+	return e / s(t);
+}
+function p(e) {
+	let t = a() || 1;
+	return Number.isInteger(t) ? Math.round(e) : Math.round(e * t) / t;
+}
+function m(e, t) {
+	let n = _(t);
+	return Math.round(e / n) * n;
+}
+function h(e) {
+	let t = s(e);
+	for (let e = 1; e <= 4; e++) {
+		let n = e * t;
+		if (Math.abs(n - Math.round(n)) < 1e-9) return e;
+	}
+	return 1;
+}
+function g(e, t) {
+	let n = h(t);
+	return Math.round(e / n) * n;
+}
+function _(e) {
+	return h(e) * s(e);
+}
+var v = /* @__PURE__ */ new Set(), y = /* @__PURE__ */ new Set(), b = 0, x = {
+	scale: 0,
+	dpr: 0
+}, S, C, w = () => {
+	let e = {
+		scale: o(),
+		dpr: a()
+	};
+	if (e.scale !== x.scale || e.dpr !== x.dpr) {
+		x = e;
+		for (let t of [...v]) t(e.scale);
+		for (let t of [...y]) t(e.scale);
+	}
+}, T = () => {
+	D(), C = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`), C.addEventListener("change", E);
+}, E = () => {
+	w(), T();
+}, D = () => {
+	C?.removeEventListener("change", E), C = void 0;
+};
+function O(e, t) {
+	if (typeof window > "u" || !window.matchMedia) return () => {};
+	t.add(e), b++ === 0 && (x = {
+		scale: o(),
+		dpr: a()
+	}, S = i(w), T());
+	let n = !1;
+	return () => {
+		n || (n = !0, t.delete(e), --b === 0 && (S?.(), S = void 0, D()));
+	};
+}
+function k(e) {
+	return O(e, y);
+}
+function A(e = document.documentElement) {
+	let t = () => e.style.setProperty("--vf-scale", String(o()));
+	return t(), O(t, v);
+}
+var j = class {
+	constructor(e) {
+		this.host = e, this.owns = !1, this.pending = !1, e.addController(this);
+	}
+	hostConnected() {
+		typeof window > "u" || this.decide(!0);
+	}
+	hostUpdated() {
+		this.pending && this.decide(!1);
+	}
+	hostDisconnected() {
+		this.stop?.(), this.stop = void 0;
+	}
+	decide(e) {
+		let t = () => {
+			this.owns = !0, this.host.style.setProperty("--vf-scale", String(o()));
+		}, n = () => {
+			this.pending = !1, t(), this.stop = O(t, v);
+		};
+		if (this.owns) return n();
+		if (this.host.style.getPropertyValue("--vf-scale") !== "") {
+			this.pending = !1;
+			return;
+		}
+		if (getComputedStyle(this.host).getPropertyValue("--vf-scale").trim() !== "") {
+			this.pending = !1;
+			return;
+		}
+		if (e || !this.inFlatTree()) {
+			this.pending = !0;
+			return;
+		}
+		n();
+	}
+	inFlatTree() {
+		for (let e = this.host; e; e = e.parentElement) if (e.parentElement?.shadowRoot && !e.assignedSlot) return !1;
+		return !0;
+	}
+};
+//#endregion
+export { e as CLASSIC_DPI, t as CSS_REFERENCE_DPI, n as SYSTEM_PX_IN_CSS_PX, j as ScaleController, A as applyScale, s as effectiveScale, o as getScale, k as onScaleChange, g as snapSys, p as snapToDevicePx, m as snapToSystemPx, c as sys, l as sysLength, u as sysLengths, h as systemPxQuantum, d as toSys, f as toSysExact };

package/dist/scroll-rail.d.ts

@@ -0,0 +1,112 @@
+import { type TemplateResult } from 'lit';
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** Which way a rail runs. A component renders one rail per reserved axis. */
+export type RailAxis = 'vertical' | 'horizontal';
+/** What the components hand the controller. */
+export interface ScrollRailOptions {
+    /** The scrolling element the rail reflects and drives (a div or textarea). */
+    getScroll: () => HTMLElement | null | undefined;
+    /**
+     * Optionally, the content whose growth changes `scrollHeight` without the
+     * scroller's own box resizing (slotted rows, wrapping copy) — observed so
+     * the thumb re-syncs when it grows.
+     */
+    getContent?: () => Element | null | undefined;
+}
+/**
+ * The behavior half of the kit-drawn scroll rails (SCROLL-RAILS-PLAN.md):
+ * syncs the rail subtree {@link renderScrollRail} renders to the scroller's
+ * native scroll state, and drives the three classic pointer interactions.
+ *
+ * The native scrollbar is hidden (`vfScrollRail` recipe), never the native
+ * scrolling — wheel, trackpad momentum, keyboard and AT scrolling stay the
+ * platform's, and this controller writes scroll position exclusively through
+ * `scrollTop`/`scrollLeft`, so native scrolling, `ScrollStateController` and
+ * consumers observing scroll events see one source of truth.
+ *
+ * What it owns:
+ * - **Sync** — a `scroll` listener on the scroller (plus a ResizeObserver on
+ *   scroller and content) recomputes the thumb's travel and writes it as a
+ *   whole-system-px translate, so the art is crisp mid-scroll; accepts the
+ *   ≤1-frame lag behind compositor wheel scrolling every scripted scrollbar
+ *   has (at 1-bit there is no smooth motion to betray it — no rAF loop, no
+ *   polling). The same pass sizes the trough's whole-surface dither raster
+ *   (the exact-tile idiom, `tileRaster`) and writes the degenerate-track
+ *   state the recipe's decision table styles.
+ * - **Thumb drag** — pointer-captured and axis-locked, live scrolling (the
+ *   modern expectation; System 7's dotted-outline drag is a possible later
+ *   opt-in). The thumb's paint position always snaps to whole system px.
+ * - **Trough press** — pages by one viewport minus one 16px line of overlap
+ *   toward the press, auto-repeating after {@link PRESS_HOLD_MS} while held
+ *   and pausing when the thumb reaches the pointer (classic behavior).
+ * - **Arrow press** — steps one 16px line, auto-repeats on hold, and holds
+ *   `data-pressed` on the button so the glyph fills solid for the press's
+ *   whole extent.
+ *
+ * The rail subtree is `aria-hidden` and pointer-only — System 7 scrollbars
+ * were never keyboard targets; keyboard users scroll the focused viewport
+ * natively and screen readers scroll content their own way — so the
+ * viewport's focus ring, tabindex gating and role/name logic are untouched.
+ * Deliberately NOT reused: `snapSys`'s placement lattice — the rail needs
+ * plain whole-system-px snapping, not the k-lattice a drag gesture stores
+ * coordinates on.
+ */
+export declare class ScrollRailController implements ReactiveController {
+    private readonly host;
+    private readonly opts;
+    private resizeObserver?;
+    private scroller;
+    private press;
+    private holdTimer;
+    private repeatTimer;
+    /** One raster per axis, re-encoded only when the track's size changes. */
+    private readonly troughCache;
+    constructor(host: ReactiveControllerHost & HTMLElement & {
+        readonly renderRoot: HTMLElement | DocumentFragment;
+    }, opts: ScrollRailOptions);
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    /** (Re-)attach the scroll listener and observers to the current scroller. */
+    private wire;
+    private unwire;
+    private readonly onScroll;
+    /**
+     * Re-derive every measured output: thumb position, trough raster,
+     * degenerate state. Safe to call any time; components hit it imperatively
+     * when content changes without a box resize (a `<textarea>` on input —
+     * the same moments they call `ScrollStateController.measure()`).
+     */
+    sync(): void;
+    private syncRail;
+    readonly onPointerDown: (event: PointerEvent) => void;
+    readonly onPointerMove: (event: PointerEvent) => void;
+    /** Ends a press on pointerup / pointercancel / lostpointercapture. */
+    readonly onPointerUp: (event: PointerEvent) => void;
+    private scrollRange;
+    /** One line ({@link LINE_SYS} system px) in `dir`. */
+    private stepBy;
+    /** One viewport minus one line of overlap in `dir` (the classic page). */
+    private pageBy;
+    /**
+     * One auto-repeat beat of a held trough press: page again unless the thumb
+     * has reached the pointer — classic behavior; the press keeps repeating if
+     * the pointer then moves past the thumb again.
+     */
+    private pageTowardPointer;
+    private armRepeat;
+    private clearRepeat;
+}
+/**
+ * The rail subtree the `vfScrollRail` recipe styles — arrows at each end, the
+ * dithered trough and the fixed thumb between them — wired to a
+ * {@link ScrollRailController}.
+ *
+ * Render it as a **later sibling of the scrolling element** (the recipe's
+ * state selectors reach the rail from the scroller's attributes), inside a
+ * container that lays the rail along the component's edge; the component's
+ * own 1px frame border supplies the rail's outer line. The subtree is
+ * `aria-hidden` and contributes nothing to the accessibility tree or tab
+ * order — scrolling's keyboard and AT contract lives on the viewport, where
+ * it always did.
+ */
+export declare function renderScrollRail(rail: ScrollRailController, axis: RailAxis): TemplateResult;