vintage-frames 0.6.2 → 0.7.0

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

@@ -1,6 +1,62 @@
 import { LitElement } from 'lit';
 /** Which member of the icon family paints — the two System 7 resource sizes. */
 export type VfIconSize = 'large' | 'small';
+/**
+ * The detail of `vf-drag` and `vf-drop`: the pointer, for the page's hit
+ * test; the proposal in the icon's own container; and the outline's top-left
+ * in the viewport, for a drop that lands in another container (convert it
+ * with that container's `placementAt`).
+ */
+export interface VfIconDragDetail {
+    /** The pointer, in viewport CSS px. */
+    clientX: number;
+    clientY: number;
+    /**
+     * The proposed origin in the icon's own container, whole system px on the
+     * placement lattice.
+     */
+    left: number;
+    top: number;
+    /**
+     * The outline's top-left — the icon's frame box translated by the delta —
+     * in viewport CSS px. The press offset is already inside it: an icon placed
+     * at `container.placementAt(x, y)` lands exactly where the outline was.
+     */
+    x: number;
+    y: number;
+    /**
+     * Every icon the drag carries: this one first, then the other selected
+     * movable icons of its field, in document order — the selection travels
+     * as one. Each follower's outline is its own box translated by the same
+     * delta, so a page filing the set converts each icon's own rect the way
+     * it converts `x`/`y`.
+     */
+    icons: VfIcon[];
+}
+/**
+ * A follower's handle in a group drag: what the dragged icon holds on each
+ * other selected icon of its field, so their outlines move as one and the
+ * drop writes each by the same delta. Internal to the kit's group drag.
+ */
+export interface VfIconDragFollower {
+    icon: VfIcon;
+    /** The follower's seeded origin, system px in the shared container. */
+    origin: {
+        x: number;
+        y: number;
+    };
+    /** The follower's box, system px, for the group clamp. */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Move the follower's outline by a lattice delta. */
+    move(dx: number, dy: number): void;
+    /** Write the follower's origin plus the delta through `left`/`top`. */
+    drop(dx: number, dy: number): void;
+    /** Take the outline down. */
+    end(): void;
+}
 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
@@ -121,6 +177,88 @@ declare const VfIcon_base: (new (...args: any[]) => import("../position.js").VfP
  * Shift. Focus is what `selectable` grants, so the keyboard half of `movable`
  * and `editable` presupposes it — see the role section below.
  *
+ * ### The drag is an outline; the icon stays put
+ *
+ * The Finder dragged an icon as a dotted outline — the mask's boundary and
+ * the name's rectangle — drawn over everything with the XOR pen, the icon
+ * itself staying put until the drop. The kit draws it from what it already
+ * has: {@link deriveDragOutline} finds the ring the way the open ghost does
+ * (the silhouette from the art's alpha, eroded by one pixel, the ring the
+ * erosion removes), adds the plate's rectangle, and {@link dotOutline} dots
+ * it against a 2×2 checker — compositing only, so cross-origin art derives
+ * too, and art the pipeline cannot draw falls back to the cell's rectangle.
+ * The canvas paints with the cursor's XOR recipe, `filter: invert(1)` under
+ * `mix-blend-mode: difference`: a dotted black line over a white window
+ * body, and over the desktop dither the composition QuickDraw's pattern pen
+ * gave, because the checker's phase is taken from where the outline lands
+ * on the *screen* — its dots share the dither's own phase wherever it goes.
+ *
+ * It draws on the desktop's drag surface: a layer in the screen's shadow,
+ * over windows, palettes and the menu bar alike, clipped at the raster's
+ * edge like everything else, reached through the `vf-drag-surface-request`
+ * handshake (bubbles, non-composed — it travels up the slots the icon is
+ * assigned to, so it works from inside a window body). With no desktop the
+ * canvas lives in the icon's own frame instead, translated by the delta,
+ * clipped by whatever clips the icon; the gesture and its events are the
+ * same either way. Its origin is a whole count of system px from the
+ * surface's, written as a live `sysLength()`, so a scale change mid-gesture
+ * cannot smear it.
+ *
+ * ### The drag reports, the page files
+ *
+ * The kit ships no filing semantics — folders are the page's own catalog —
+ * so a drag is a stream of events and a cancelable commit, on the icon:
+ *
+ * - `vf-drag-start` `{ left, top }` on the first lattice step away from the
+ *   press (a plain click never starts one, and never fires a drop);
+ * - `vf-drag` `{ clientX, clientY, left, top, x, y }` on every step that
+ *   changed the snapped proposal;
+ * - `vf-drop`, the same shape at the release, **cancelable**: its default
+ *   action is the move, the proposal written through `left`/`top` and
+ *   clamped whole in the container measured at the press. `preventDefault()`
+ *   writes nothing — the page re-parents or places the icon itself, the
+ *   outline's origin converted with the destination's `placementAt`;
+ * - `vf-drag-cancel` `{}` on Escape or a `pointercancel`: nothing written.
+ *
+ * `left`/`top` in the detail are the *proposal*, unclamped — the origin plus
+ * the lattice-snapped delta — and only the default action clamps, so a page
+ * that cancels gets the raw gesture. `x`/`y` are the outline's top-left in
+ * viewport CSS px: the frame's box at the press translated by the delta,
+ * the press offset already inside it, so an icon placed at the
+ * destination's `placementAt(x, y)` lands exactly where the outline was.
+ *
+ * ### The selection travels
+ *
+ * A drag that begins on a *selected* icon takes every other selected,
+ * movable icon of its field with it — the Finder outlined the whole
+ * selection under a drag on any member. Each follower draws its own outline
+ * ({@link followDrag}), moved by the same lattice delta as the leader's, and
+ * the leader's events carry the set as `detail.icons`, itself first. The
+ * default action of the drop clamps the delta once for the whole group —
+ * the arrangement is kept, and the group stops when its outermost member
+ * meets the container's edge — then writes each member's origin plus that
+ * delta. A cancel takes every outline down and writes nothing. A press on
+ * an unselected icon makes it the selection first (the outside listeners
+ * clear the others), so it drags alone; a Shift press that deselects the
+ * pressed icon drags it alone too, the rest staying where they are.
+ *
+ * For the selection to travel, a plain press on one of its members must not
+ * collapse it: the other icons' outside-press listeners leave a selection
+ * alone when the press landed on an icon already selected in the same
+ * field. A *click* on such an icon — released with no drag — collapses the
+ * selection to it on the release, so a click still single-selects and the
+ * same press could have dragged them all.
+ *
+ * Escape is heard by a document listener scoped to the gesture rather than
+ * by the icon's own key handler, because a `movable`-only icon never takes
+ * focus — an addition in the kit's idiom (a pointer-only gesture with no way
+ * out is the kind of gap SPEC §1 closes), not a claim about the Finder.
+ *
+ * `target` is the destination highlight the page sets on the folder under a
+ * drag: the selected treatment of the art alone — inverted, or darkened
+ * under `color` — with none of `selected`'s semantics: no event, no outside
+ * listener, no `aria-selected`, the plate untouched.
+ *
  * 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
@@ -160,21 +298,22 @@ declare const VfIcon_base: (new (...args: any[]) => import("../position.js").VfP
  * 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
+ * The owner is `vf-icon-field`, the container a field of icons sits in, and
  * it is what buys the selection state back:
  *
  * ```html
- * <div role="listbox" aria-label="Desktop" aria-multiselectable="true">
+ * <vf-icon-field label="Desktop">
  *   <vf-icon label="Macintosh HD" selectable movable editable>…</vf-icon>
  *   <vf-icon label="Trash" selectable movable editable>…</vf-icon>
- * </div>
+ * </vf-icon-field>
  * ```
  *
  * 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
+ * orphaned option was. The field is layout-neutral — placed icons anchor to
+ * the nearest *positioned* ancestor, which is still the desktop's raster. An
+ * element of your own carrying `role="listbox"` still owns an icon the same
+ * way. 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.
  *
@@ -250,6 +389,19 @@ declare const VfIcon_base: (new (...args: any[]) => import("../position.js").VfP
  *   edit was dropped and the old name put back.
  *   `detail: { attempted, kept, reason: 'empty' }`. A `vf-change` is *not*
  *   fired alongside it — nothing changed.
+ * @fires vf-drag-start - A drag began: the first lattice step away from the
+ *   press. `detail: { left, top, icons }` — the origin, whole system px in
+ *   the icon's container, and every icon the drag carries (this one first).
+ * @fires vf-drag - A step that changed the proposal. `detail: { clientX,
+ *   clientY, left, top, x, y, icons }` — the pointer in viewport CSS px, the
+ *   proposed origin in the container (whole system px on the lattice), the
+ *   outline's top-left in viewport CSS px, and the icons travelling.
+ * @fires vf-drop - The release; cancelable. The same detail as `vf-drag`.
+ *   Its default action writes the proposal through `left`/`top` — every
+ *   icon in `icons` by the same delta, clamped whole in the container as a
+ *   group; `preventDefault()` writes nothing.
+ * @fires vf-drag-cancel - The drag was abandoned — Escape, or a
+ *   `pointercancel` — and nothing was written. `detail: {}`.
  */
 export declare class VfIcon extends VfIcon_base {
     #private;
@@ -272,6 +424,15 @@ export declare class VfIcon extends VfIcon_base {
     selectable: boolean;
     /** Whether the icon is selected: the art inverts and the plate goes black. */
     selected: boolean;
+    /**
+     * The destination highlight: this icon is the folder under a drag, and its
+     * art paints the selected treatment — inverted, or darkened under
+     * {@link color} — with none of `selected`'s semantics: no `vf-select`, no
+     * outside-press listener, no `aria-selected`, the plate untouched. The page
+     * sets it on the folder a `vf-drag` reports the pointer over and clears it
+     * when the pointer leaves or the drop lands.
+     */
+    target: boolean;
     /**
      * Declares the slotted art a **color icon**, so selection darkens it — the
      * ttSelected transform, every color blended halfway toward black — instead
@@ -339,6 +500,14 @@ export declare class VfIcon extends VfIcon_base {
     private _draft;
     /** The derived open ghost, or null while there is nothing to derive from. */
     private _ghost;
+    /**
+     * Join another icon's drag as a follower (see the class doc): seed the
+     * origin the drop will add the delta to, draw this icon's own outline on
+     * `surface` (the desktop's, as the leader's handshake found it) or in its
+     * own frame, and hand back the handle the leader moves, drops and ends.
+     * Null when this icon cannot move. Internal to the kit's group drag.
+     */
+    followDrag(surface: HTMLElement | null): VfIconDragFollower | null;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: Map<PropertyKey, unknown>): void;
@@ -362,6 +531,27 @@ export declare class VfIcon extends VfIcon_base {
     /** Put the previous name back and close the field. */
     cancelEditing(): void;
     protected render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Select or deselect as a press would: the state changes and `vf-select`
+     * reports it. A `selected` write from code is silent, the way a value set
+     * fires no `vf-change`; this is the route for a gesture a container runs
+     * on the icon's behalf — `vf-icon-field`'s rubber band. A no-op when the
+     * state already matches.
+     */
+    setSelected(next: boolean): void;
+    /**
+     * Whether a viewport box (CSS px) touches the icon the way the Finder's
+     * selection rectangle asked: its art cell or its name plate. The empty
+     * cell around narrower art and the frame's margin beside the plate count
+     * for nothing — a rectangle dragged through the gap between two icons
+     * selects neither. `vf-icon-field`'s rubber band reads it.
+     */
+    touches(box: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    }): boolean;
 }
 declare global {
     interface HTMLElementTagNameMap {