Vintage Frames

Install

npm install vintage-frames

import 'vintage-frames' // registers every <vf-*> element

Or import individual elements:

import 'vintage-frames/vf-button.js'
import 'vintage-frames/vf-checkbox.js'

vf-desktop

The gray desktop: a 50% dither, plus window management. Pointerdown or keyboard focus in a slotted vf-window brings it to front and marks it active, clearing active on the others. DOM order follows the stacking order, synced in a task after the press ends, so a click on a control in a background window still reaches it. Utility windows float on their own tier above document windows, outside the single-active rule; a slotted vf-menu-bar (or free-standing vf-menu) sits above both, so its dropped menus cover palettes too. clearActive() deactivates the whole document tier — zero active windows is a legal state — until a press, keyboard focus, or a newly slotted window reactivates it. A press on the desktop's own dither changes nothing: the page decides which presses mean the Finder. Every change of holder fires vf-activate.

Sized in system px, never from your stylesheet — the component's own inline size wins. Set the numbers directly or let fitWithin derive them, then position the desktop with your own CSS. Windows and icons inside place themselves with their own top/left.

vf-window

The window shell. The 1992 Macintosh Human Interface Guidelines names five standard windows; each is a one-line recipe.

vf-dialog

The modal-dialog shell, over a native <dialog>: it opens in the top layer, traps focus and closes on Escape — and, with light-dismiss, on a click outside it. Both chromes are the modal double frame — 1px rule, 2px gap, 2px band, no shadow. Movable modal by default (the striped bar set into the top of the frame, no close box); frame="plain" is the modal dialog box (no bar, immovable). No backdrop dimming. top/left are viewport coordinates, and unset means centered. It opens with focus in its first text field, or on the default button; Return activates the default button from anywhere in the dialog.

An alert box is a recipe, not a component: the plain frame, a row vf-stack with 32×32 art, copy in the chrome face, and a vf-button-group, each placed with top/left. Set label — the plain frame has no title bar to take a name from.

vf-separator

A 1px black rule. Inside a menu panel it renders as the dimmed dotted rule. It has no width of its own: give it one.

vf-button

The push button: pixel-stepped corners, not rounded. Pressing inverts the face; Tab draws the dashed rule under the label.

vf-button-group

A row of buttons sized to the widest, faces aligned. A plain flex row aligns a default button's ring instead of its face — compare the two stages below.

vf-swatch

A color-swatch button: a white-inset color well sized in system pixels. With no color it shows the transparency checker, and a translucent value layers over it. Flat by default; shadow adds the kit's hard drop shadow.

vf-checkbox

A 13×13 white box with the corner-to-corner ✕. Pressing thickens the border to 2px.

vf-radio & vf-radio-group

A 13×13 circle: a 1-bit outline over a white disc. The group is the form control: it owns value, the roving tabindex and the submitted name. A bare vf-radio outside a group manages itself.

vf-text-field

A bordered text input, 22px tall, typed in the chrome face. Selected text inverts to the 1-bit selection all three editable fields share.

vf-text-area

The multi-line field: everything vf-text-field takes, plus rows. It reserves a permanent scroll rail — an empty white channel until the text overflows.

vf-number-field

A numeric field with the "little arrows" stepper. The well is 22 system px, the same as the other fields; the 25-px stepper beside it sets the host's height.

vf-select & vf-option

The popup menu control. Two pointer styles: press-drag-release (press the pill, drag onto an item, release to pick) and click-to-open (a quick tap leaves the list open for a second click). Selecting blinks the row, then closes.

The panel opens with the selected row over the closed pill, and the control sizes to its widest option. Set min-width on the host for a floor.

size="small" sets the pill and its list in the body face, on a 12px pill with 10px rows.

no-shadow draws the pill without its 1px shadow. The open list keeps its shadow.

A list taller than the screen is clipped, not scrolled. An edge row with items beyond it shows a solid arrow; rest the pointer on it and the list rolls a row at a time. A clipped panel still opens with its selected row over the pill. Set --vf-popup-inset-top once on :root to keep clamped panels clear of a menu bar (24px for a vf-menu-bar).

vf-progress-bar

Determinate: a solid black fill from the left with a 1px leading edge. Indeterminate: full-width diagonal barber stripes, stepped rather than smoothed. Give the host a width.

vf-slider

A horizontal slider: a 4px capsule rail, solid black up to the shield-shaped handle and hollow after it. A 1-bit adaptation of the later Mac OS control, not a System 7 original. Give the host a width.

vf-menu-bar, vf-menu & vf-menu-item

Pull-down menus with press-drag-release: press a title, slide onto a command, release to run it. Sliding onto another title switches menus mid-press; releasing over a disabled row, a separator or off the menu chooses nothing. A quick tap leaves the menu open for a second click. Selecting blinks the row (skipped under prefers-reduced-motion), then fires vf-menu-select.

A vf-menu also works standalone:

vf-list & vf-list-item

The list box: inverted selection, a permanent scroll rail, and first-letter type-ahead. Each row takes a leading graphic in its icon slot, usually a 16×16 vf-img.

vf-scroll-area

A container with System 7 scrollbars: 16px cells, a dot-dither trough, the white elevator, and hollow arrow glyphs that fill solid when pressed. A reserved axis keeps its rail as a permanent empty white channel and fills it in only when the content overflows. In a non-frontmost vf-window, both rails blank. For rails on a window's own frame rather than inset in its body, use vf-window[scrollbars].

vf-fieldset

The group box, with the legend punching through the top border. The legend's backdrop comes from --vf-surface (white by default; vf-window/vf-dialog set it) — on a tinted background, set it on the container.

vf-grid

A lattice of equal cells with 1px rules between them: a tool palette, a swatch table, a pattern chooser. Solid and dashed pens share one layout, and the rules run behind the cells.

A cell is centered in its well on both axes; place-self: stretch fills the well instead, and is the default under collapse. The grid takes no role, keyboard behavior or selection — put role="group" or role="radiogroup" on the host as the content warrants.

vf-stack

A flexbox whose gap, pad, width and height are declared in whole system pixels — one of the two stylesheet-free layouts; the other is coordinate placement, below.

A page stylesheet cannot state system pixels: each element sets --vf-scale on itself, never on the document, so var(--vf-scale, 1) outside a vf-* ancestor silently resolves to 1.

Content governs the box: a column is as wide as its widest child, a row as tall as its tallest, and children keep the size they were drawn at. The stack paints nothing, takes no role, and returns face, line box, color and selectability to inherit.

The other way: top and left

Every component takes top and left in whole system px. Set either and the element is absolutely positioned within its parent, the missing coordinate defaulting to 0; set neither and it renders in flow. (0,0) is the nearest positioned ancestor — every kit container is one; a container of your own needs position: relative, or use a vf-container, below.

That includes the rows a container usually owns — vf-option, vf-menu-item, vf-list-item and a bar's vf-menu. A placed child leaves the parent's flow: a select or menu panel no longer counts it toward its width, the popup's scroll clamp skips it, and the rows after it close the gap.

vf-dialog takes the pair in viewport coordinates — the top layer's containing block is the viewport — and unset means centered. A drag writes through the same two properties, so read a moved element's position off el.left, not style.left, which holds a live calc().

fixed holds the placement against the visible region of the nearest scrolling ancestor instead of its scrolled plane: the element keeps its top/left while the content scrolls under it, and the flag alone places it at (0,0). A fixed child comes before the flow content in its parent and paints over placed siblings. Where nothing scrolls it renders as placed.

origin names which point of the element's own box the pair places: nine keywords, vertical then horizontal — top left (the default), top center, top right, center left, center, center right, bottom left, bottom center, bottom right. The point is measured in whole system px and kept current as the box changes, an odd size's leftover half going toward the start; it is never a transform. A drag keeps the point, and placementAt(x, y, child) returns the pair that lands a dropped child's corner there. The Page Setup dialog under vf-dialog centers its title on left="145" and holds its button row's bottom-right corner at (274, 168) this way.

vf-container

A box that is nothing but its declared size: width and height in whole system px around anything you slot into it. It paints nothing but what pattern and rule name, and has no layout opinion — in-flow children get normal flow, placed children get a coordinate system.

vf-label

The static caption: "Name:" beside a field, "Mode" over a radio group. Chrome type on a 16px line box, stated in whole system pixels.

for works like a native <label for>: clicking focuses the target, and the caption text becomes its accessible name. It never overwrites a name you set.

vf-paragraph

A run of copy on the kit's body face and its native 12px line; the display face wraps at 16px. No margin — paragraph spacing is the page's.

vf-img

Pixel art on the kit's grid: a slotted <img> sized to one system pixel per image pixel, magnified nearest-neighbor on whole device pixels. The graphic stays a native <img> in your light DOM — alt, srcset and loading behavior are untouched.

vf-icon

The Finder icon: a picture and a caption that select, move and rename together.

The art arrives by slot: large is the 32×32 ICN#, small the 16×16 ics#. size picks which one paints and the cell it paints in. The cell is reserved whether or not the art fills it, so a row of icons keeps one baseline. A field of icons sits in a vf-icon-field, which is what makes a selectable icon an option.

color declares the art a color icon: selection darkens it — every color blended halfway toward black — instead of inverting it into a negative. The plate inverts either way.

open — the icon's window is on screen — redraws the art as a ghost: outline held, interior re-filled with the kit's dither. It is derived from the slotted art — no second file, and cross-origin art works.

A name is never abbreviated or folded. Wider than its cell, it overflows, centered: width is the cell pitch, not a bound on the name. A declared width must be even.

A drag draws the outline on the desktop, over windows, palettes and the menu bar alike, and is reported rather than interpreted: vf-drag-start, vf-drag on every step, and a cancelable vf-drop whose default action is the move. The page decides what a drop means — the kit ships no filing semantics — and cancels the default action when it files the icon itself. target paints the destination highlight on the folder under the pointer; placementAt() on the destination converts the outline's origin into that container's own coordinates.

vf-icon-field

The container a field of icons sits in: a desktop's icons, a folder window's contents. A multiselectable listbox named from label, so a selectable icon inside is an option with aria-selected. It paints nothing and, until placed or filled, takes no size and no position of its own: a field of placed icons is a zero-height block, and the icons anchor to the desktop's raster or the window's plane as if it were not there.

Focus

The components are good citizens of the modern web: focusable, keyboard-operable, and named for assistive tech, like the native elements they stand in for. Keyboard access postdates System 7, so the focus mark is the kit's own, added in the 1-bit idiom — a 1px dashed rule under the focused control. It is keyboard-only: a mouse click never draws it.