vintage-frames 0.1.0

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

@@ -0,0 +1,356 @@
+import { LitElement } from 'lit';
+/** Which member of the icon family paints — the two System 7 resource sizes. */
+export type VfIconSize = 'large' | 'small';
+declare const VfIcon_base: (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
+/**
+ * `<vf-icon>` — a Finder icon: pixel art in a reserved cell with its name on a
+ * plate below, selectable, movable and renameable in place.
+ *
+ * It is the one composite in the kit whose parts already existed separately —
+ * `vf-img` draws the art, `vf-list-item` inverts on selection, `vf-window`
+ * drags — and the reason to have it anyway is that the *icon* is the unit the
+ * Finder actually manipulates. A picture and a caption that select together,
+ * move together and rename together is a control, not a layout.
+ *
+ * ### The art arrives by slot
+ *
+ * Two slots, one per resource size — `large` is the 32×32 `ICN#` and `small`
+ * the 16×16 `ics#` — each holding a `vf-img` around the consumer's own `<img>`:
+ *
+ * ```html
+ * <vf-icon label="Macintosh HD" selectable movable editable>
+ *   <vf-img slot="large"><img src="hd-32.png" alt=""></vf-img>
+ *   <vf-img slot="small"><img src="hd-16.png" alt=""></vf-img>
+ * </vf-icon>
+ * ```
+ *
+ * Slots rather than `src` properties, for the reason `vf-img` exists at all:
+ * the kit ships no raster files and never builds an `<img>` on a consumer's
+ * behalf, so the graphic stays a real element in the light DOM with its own
+ * `alt`, `srcset`, loading behavior and asset URLs. A `src` string can express
+ * none of that, and it could not hold an inline `<svg>` or a `<canvas>` either.
+ * `vf-list-item`'s `icon` slot makes the same trade.
+ *
+ * The cost is that both files fetch even though one paints — pay it with two
+ * data URIs, or slot only the size that view uses.
+ *
+ * ### The cell is reserved, the art is registered in it
+ *
+ * `size` picks which slot paints *and* the cell it paints in: 32×32 or 16×16,
+ * held whether or not there is art for it. A folder is 32×20 of ink and a
+ * document 25×32, and a row of them keeps one baseline only because the cell —
+ * not the ink — is the unit, which is what an icon resource always was.
+ *
+ * ### Everything centered lands on a whole pixel, by parity
+ *
+ * The frame centers two things over one axis — the art cell and the name — and
+ * a centered child sits at `(box − child) / 2`. That is a whole number exactly
+ * when the box and the child have the **same parity**. Half a system pixel is
+ * what fringes 1-bit art: the glyph stems smear across two device columns and
+ * go gray, while the plate behind them stays sharp, because backgrounds are
+ * pixel-snapped by the compositor and glyphs are not. A crisp plate under a
+ * grey name is the signature of exactly this.
+ *
+ * So the component makes the parities agree instead of correcting afterwards.
+ * The cell is 32 or 16, and {@link #measurePlate} sizes the name plate to a
+ * whole **even** number of system px — measured from the text, rounded up. Both
+ * children are then even, and so is every offset, at every display density and
+ * whether or not a `width` is declared. Nothing is snapped, nothing leans on
+ * the rasterizer, and `verify:icon` asserts both the geometry and that a field
+ * of names renders without a single gray pixel — with the kit's normal
+ * antialiasing left on, since a run on whole pixels gives it nothing to smooth.
+ *
+ * Your side of it is one rule: **a declared `width` must be even**, since the
+ * component cannot round a number you chose. Supply art at the cell size too —
+ * which "one image pixel is one system pixel" already implies — because art
+ * differing from its cell by an odd number centers the same way.
+ *
+ * ### Selection inverts, because the art is a 1-bit mask
+ *
+ * A System 7 icon is black ink and opaque white on a transparent surround —
+ * precisely an image plus its mask — so inverting it flips ink and fill and
+ * leaves the surround alone, which is the whole of the classic selected
+ * appearance. `filter: invert(1)` reproduces it exactly for 1-bit art. Color
+ * art inverts too, into a photographic negative rather than the darkening
+ * System 7 gave it; that is the case to revisit if the kit ever grows a
+ * selected-state treatment of its own. The label plate inverts to the
+ * `--vf-highlight` pair, sharing one selection color with `vf-list-item`.
+ *
+ * ### Open is derived, not shipped
+ *
+ * With `open`, the art redraws as the Finder's open ghost: the outline held
+ * in solid black, the interior re-filled with the kit's loose 25% dither (the
+ * scrollbar trough's lattice), the transparent surround untouched. There is
+ * no second raster and no second fetch — the same alpha channel that makes
+ * selection an inversion makes the ghost derivable, and `src/open-art.ts`
+ * derives it from the slotted art by canvas compositing alone. No pixels are
+ * ever read back, so a cross-origin image that taints its canvas still works:
+ * taint forbids reading, not drawing or displaying.
+ *
+ * The ghost keeps the shape selection expects — ink and opaque white on a
+ * transparent surround — so a selected open icon inverts exactly as a closed
+ * one does, with no second treatment. The slot stays in the tree while the
+ * ghost paints, hidden (it is where the art loads, and re-loads, from), and
+ * art the pipeline cannot draw — nothing slotted yet, a failed load, an
+ * inline `<svg>` — keeps rendering as itself rather than vanishing behind a
+ * state it cannot show.
+ *
+ * ### `movable`, not `draggable`
+ *
+ * `draggable` is a global HTML attribute *and* an `HTMLElement` accessor, so
+ * declaring it would both shadow a platform member and hand the element to the
+ * browser's own drag-and-drop machinery. This is the `align` trap from
+ * `vf-stack` in a second costume — `align`, `hidden`, `dir`, `draggable` and
+ * `title` all carry behavior a custom element never asked for. The kit already
+ * spells this parameter `movable` on `vf-window`, so the icon does too, and it
+ * moves the same way: `DragController` tracks the gesture and
+ * `PlacementController` writes the result into `left`/`top` in whole system px,
+ * the art's own unit — the same pair markup places an icon with, so a moved
+ * icon is still where it was dropped after a zoom.
+ *
+ * Dragging is a pointer gesture with no keyboard equivalent, which is the kind
+ * of gap the kit closes rather than inherits (SPEC §1): a focused movable icon
+ * also moves under the arrow keys, one system px at a time and eight with
+ * Shift. Focus is what `selectable` grants, so the keyboard half of `movable`
+ * and `editable` presupposes it — see the role section below.
+ *
+ * Opening gets the same treatment. The double-click is the pointer gesture,
+ * and its keyboard route is ⌘O / ⌘↓ — the System 7 Open shortcuts, with Ctrl
+ * standing in for ⌘ off the Mac. Return is deliberately not one of them: the
+ * Finder's Return renamed, never opened, so on an editable icon it starts the
+ * edit and on a non-editable one it does nothing at all.
+ *
+ * ### The name and the art are one target, and the second click decides
+ *
+ * A double-click opens the icon *wherever it lands* — the name is as much the
+ * icon as the picture is, and the Finder never made you aim at the 32 pixels of
+ * art. But the name is also where a single click renames, so the two gestures
+ * begin with the same press and only the second one tells them apart.
+ *
+ * So the rename waits for it. A press on the plate of an already-selected icon
+ * arms the field rather than opening it, and the next press inside
+ * {@link RENAME_DELAY_MS} calls it off — leaving the double-click to open, with
+ * no rename box flashing up behind it. Nothing needs to *undo* an edit that
+ * began: the press that starts one and the press that opens are the same
+ * press, so the only thing that can be got right is not committing early.
+ *
+ * The window is generous in the one direction that is cheap. Reading a lone
+ * click as a pair costs a wait before the box appears; reading a pair as a lone
+ * click renames when the user asked to open. The same reasoning covers a press
+ * that turns into a drag, a press elsewhere, and any key — each calls the
+ * pending rename off, because none of them is the click it is waiting for.
+ *
+ * ### An icon alone is a picture; an icon in a field is an option
+ *
+ * `role="option"` is only meaningful inside a `listbox` that owns it. Written
+ * unconditionally it is not merely untidy — the browser *drops* it, and
+ * `aria-selected` with it, so a `selectable` icon announced as a bare generic
+ * and its selection state reached assistive tech nowhere at all.
+ *
+ * So the role follows the container. Owned, the icon is an `option` that names
+ * itself from its plate and publishes `aria-selected`. Unowned, it degrades to
+ * `role="img"` with a name — the same vocabulary the derived open ghost uses,
+ * and true of what it is. Deliberately not `button`: that would promise Enter
+ * and Space activate, and here Return *renames* while the open route is ⌘O / ⌘↓.
+ *
+ * Declaring the owner is one attribute on whatever already holds the field, and
+ * it is what buys the selection state back:
+ *
+ * ```html
+ * <div role="listbox" aria-label="Desktop" aria-multiselectable="true">
+ *   <vf-icon label="Macintosh HD" selectable movable editable>…</vf-icon>
+ *   <vf-icon label="Trash" selectable movable editable>…</vf-icon>
+ * </div>
+ * ```
+ *
+ * A `vf-desktop` cannot be that container itself: it also holds windows and a
+ * menu bar, and a non-`option` child of a listbox is invalid the same way the
+ * orphaned option was. The plain wrapper above is layout-neutral — placed icons
+ * anchor to the nearest *positioned* ancestor, which is still the desktop's
+ * raster. One divergence from the APG listbox is deliberate: its options share
+ * a single roving tab stop, while these stay one stop each, the way a Finder
+ * icon is reached on its own.
+ *
+ * **`selectable` is what makes an icon focusable**, and `movable`/`editable`
+ * presuppose it. That is the Finder's own model — you cannot move or rename
+ * what you have not selected — and the pointer path already assumed it: the
+ * rename opens on a press on the plate of an *already-selected* icon. A
+ * `movable`-only icon is a picture you can drag, not a widget.
+ *
+ * ### The label is a property, because it is editable
+ *
+ * The caption is `label` rather than slotted content: renaming means the
+ * component owns the string and hands it back on `vf-change`, and it cannot own
+ * text that lives in the consumer's DOM. An empty `label` draws no plate at
+ * all — that *is* the "no label" parameter, in preference to a second attribute
+ * that could disagree with it. `editable` then lets a click on the plate of an
+ * already-selected icon open the rename box a moment later, as the Finder's
+ * does (see above), with Return committing, Escape reverting, and the plate
+ * widening as you type.
+ *
+ * ### A name is never abbreviated, and never folded
+ *
+ * There is no ellipsis, no clipping and no wrapping: one line, always. System 7
+ * solved the long-name problem at the *other* end — HFS capped a filename at 31
+ * characters — so the Finder could afford to always draw the name in full, and
+ * did. A name wider than its cell simply overflows it, centered, the way a name
+ * wider than a 32-pixel icon always did.
+ *
+ * Staying on one line is also what keeps the name on the grid: a single run has
+ * a single measured width, so the even-plate rule above is one number rather
+ * than one per line, each with its own parity. `width` is therefore the cell —
+ * the grid pitch — not a bound on the name.
+ *
+ * `maxlength` (31) bounds the rename field rather than the `label` property:
+ * the name belongs to the consumer's model, and truncating one handed to us
+ * would lose data.
+ *
+ * The box hugs its text while you type it, not only once you are done, which is
+ * what keeps the name from moving when the edit commits: the plate is the same
+ * width either side of it, so the glyphs stay exactly where they were.
+ *
+ * A file also has to be called *something*, so a rename committed empty — or
+ * as nothing but spaces — is refused rather than applied, and the previous name
+ * comes back, which is what System 7 did. An empty `label` is still a perfectly
+ * good state to *start* in, though: a freshly made icon has no name until it is
+ * given one. Such an icon draws no plate but stays selectable, focusable and
+ * renameable — Return opens a field, and an edit with nothing in it yet is the
+ * one time the box stops hugging and reserves a cell's width, since a field you
+ * cannot see is one you cannot type into.
+ *
+ * @slot large - The 32×32 art, normally a `vf-img` around an `<img>`.
+ * @slot small - The 16×16 art, shown under `size="small"`.
+ * @csspart frame - The icon and its label plate, stacked.
+ * @csspart icon - The reserved art cell.
+ * @csspart label - The name block; its lines are centered under the art.
+ * @csspart plate - The inked run behind the name, which each wrapped line gets
+ *   its own of (inverts when selected).
+ * @csspart input - The rename field, while editing.
+ * @cssprop --vf-icon-gap - Space between the art cell and the name plate
+ * @cssprop --vf-icon-label-height - The name plate's line box
+ * @fires vf-select - Selection changed by user interaction. `detail: { selected: boolean }`.
+ * @fires vf-change - The name was committed. `detail: { label: string, previous: string }`.
+ * @fires vf-open - The icon was opened — double-clicked anywhere on it, its
+ *   name included, or ⌘O / ⌘↓ from the keyboard (Ctrl off the Mac), the
+ *   System 7 shortcuts. Return renames instead, as the Finder's did.
+ *   `detail: {}`.
+ * @fires vf-name-too-long - A rename was typed or pasted past `maxlength`, and
+ *   the field refused the excess. `detail: { attempted, accepted, limit }` —
+ *   enough to raise the alert System 7 raised rather than drop the characters
+ *   silently. Not fired for a `label` set from your own code, which is never
+ *   truncated in the first place.
+ * @fires vf-name-rejected - A rename was committed with no name in it, so the
+ *   edit was dropped and the old name put back.
+ *   `detail: { attempted, kept, reason: 'empty' }`. A `vf-change` is *not*
+ *   fired alongside it — nothing changed.
+ */
+export declare class VfIcon extends VfIcon_base {
+    #private;
+    static styles: import("lit").CSSResult[];
+    /** The icon's name. Empty draws no plate — that is the "no label" setting. */
+    label: string;
+    /**
+     * Which member of the icon family paints, and the cell it is registered in:
+     * `large` (32×32) or `small` (16×16).
+     */
+    size: VfIconSize;
+    /**
+     * Clicking selects. Set `selected` yourself to drive selection some other way.
+     *
+     * This is also the flag that makes an icon focusable and gives it a role, so
+     * the keyboard halves of {@link movable} and {@link editable} presuppose it —
+     * as the Finder did. A container carrying `role="listbox"` turns the role from
+     * `img` into a real `option`; see the class doc.
+     */
+    selectable: boolean;
+    /** Whether the icon is selected: the art inverts and the plate goes black. */
+    selected: boolean;
+    /**
+     * The icon's window is on screen, so the art paints as the Finder's open
+     * ghost — outline held, interior re-filled with the kit's loose dither —
+     * derived in the client from the slotted art itself (see the class doc).
+     * Set it when handling `vf-open`, clear it when the window goes away.
+     * Selection inverts the ghost exactly as it inverts the art.
+     */
+    open: boolean;
+    /**
+     * Drag to move — `movable`, never `draggable`, which is a platform attribute
+     * and accessor (see the class doc). Arrow keys move a focused icon too, which
+     * means pairing this with {@link selectable}: focus is what that grants.
+     */
+    movable: boolean;
+    /**
+     * The name can be renamed in place: click a selected plate, or press Return.
+     * Pair with {@link selectable} — both routes start from a selected icon.
+     *
+     * The pointer route opens the field once the double-click window has passed
+     * ({@link RENAME_DELAY_MS}), so double-clicking the *name* opens the icon the
+     * way double-clicking its art does. Return opens it at once — a keypress has
+     * no second half to wait for.
+     */
+    editable: boolean;
+    /**
+     * The cell width in whole system px — the grid pitch, and it must be
+     * **even**: the component rounds its own plate to keep every centered offset
+     * whole, but it cannot round a number you chose (see the class doc).
+     *
+     * It is not a bound on the name. Left off, the box is as wide as the wider of
+     * the art cell and the name; set, a longer name overflows it, centered.
+     * Declaring one is what keeps a field of icons on a single pitch, and what
+     * keeps a text-sized box off a fractional origin (contract rule 3).
+     */
+    width?: number;
+    /**
+     * The most characters the rename field will accept — 31, the HFS filename
+     * limit every System 7 name was cut to, which is also why the Finder could
+     * afford to always draw the whole name. Going past it fires
+     * `vf-name-too-long` with what was tried, so a host can say so rather than
+     * let characters vanish.
+     *
+     * It bounds *typing* only: a `label` set from your own data is displayed as
+     * given and fires nothing, since the name belongs to your model and silently
+     * truncating it would lose data.
+     */
+    maxlength: number;
+    /** 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;
+    /** Whether to wear the dashed focus rule; see src/focus-modality.ts. */
+    private readonly focusRule;
+    /** True while the rename field is open. */
+    private _editing;
+    /** The name as typed. The hidden plate renders it, so the box tracks it. */
+    private _draft;
+    /** The derived open ghost, or null while there is nothing to derive from. */
+    private _ghost;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<PropertyKey, unknown>): void;
+    firstUpdated(): void;
+    /**
+     * Open the rename field. The whole name starts selected, as the Finder's did
+     * — the common rename is a replacement, not an edit.
+     */
+    startEditing(): void;
+    /**
+     * Keep the typed name and close the field — unless there is no name left, in
+     * which case the edit is refused and the old one comes back.
+     *
+     * A file has to be called something: System 7 would not let you commit an
+     * empty name, and this does the same, treating a run of nothing but spaces
+     * as empty too (the plate would read as blank either way). The refusal is
+     * reported as `vf-name-rejected` for the same reason `vf-name-too-long` is —
+     * so a host can say why instead of leaving the name to silently snap back.
+     */
+    commitEditing(): void;
+    /** Put the previous name back and close the field. */
+    cancelEditing(): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'vf-icon': VfIcon;
+    }
+}
+export {};