@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/inventory-card.js

@@ -0,0 +1,173 @@
+/**
+ * The item card (ws/ui-inventory): a `role="tooltip"` on the `hud` layer with a title, a subtitle,
+ * rows of label and value (with a tone and a compare arrow drawn in CSS) and a footer, shown
+ * beside an anchor and flipped to stay in the frame by the pure `placeCard`. A grid or a
+ * `slotsTarget` shows it on focus and on hover; the game fills it with `set`.
+ */
+import { h } from './dom.js';
+import { themePx } from './hud.js';
+import { ensureInventoryStyles } from './inventory.js';
+const ORDER = ['right', 'left', 'below', 'above'];
+const OPPOSITE = {
+    right: 'left',
+    left: 'right',
+    above: 'below',
+    below: 'above',
+};
+/**
+ * Where a card of `size` goes beside `anchor` inside `frame` (all in the same units). `auto`
+ * tries right, left, below, above and takes the first that fits, else the side with the most
+ * room; a named side flips to its opposite when it does not fit and the opposite does. The
+ * result is clamped into the frame on both axes. `gap` separates card and anchor.
+ */
+export function placeCard(anchor, size, frame, placement = 'auto', gap = 0) {
+    const room = {
+        right: frame.x + frame.width - (anchor.x + anchor.width) - gap,
+        left: anchor.x - frame.x - gap,
+        below: frame.y + frame.height - (anchor.y + anchor.height) - gap,
+        above: anchor.y - frame.y - gap,
+    };
+    const fits = (s) => room[s] >= (s === 'left' || s === 'right' ? size.width : size.height);
+    let side;
+    if (placement === 'auto') {
+        side = ORDER.find(fits) ?? ORDER.reduce((a, b) => (room[b] > room[a] ? b : a));
+    }
+    else {
+        side = placement;
+        if (!fits(side) && fits(OPPOSITE[side]))
+            side = OPPOSITE[side];
+    }
+    let x;
+    let y;
+    switch (side) {
+        case 'right':
+            x = anchor.x + anchor.width + gap;
+            y = anchor.y;
+            break;
+        case 'left':
+            x = anchor.x - gap - size.width;
+            y = anchor.y;
+            break;
+        case 'below':
+            x = anchor.x;
+            y = anchor.y + anchor.height + gap;
+            break;
+        case 'above':
+            x = anchor.x;
+            y = anchor.y - gap - size.height;
+            break;
+    }
+    x = Math.max(frame.x, Math.min(frame.x + frame.width - size.width, x));
+    y = Math.max(frame.y, Math.min(frame.y + frame.height - size.height, y));
+    return { x, y, placement: side };
+}
+let cardCounter = 0;
+/** An item card on the host's `hud` layer. See the module comment. */
+export function card(host, opts) {
+    const layer = host.layers.hud;
+    const doc = layer.ownerDocument;
+    ensureInventoryStyles(doc);
+    const id = `tc-inv-card-${++cardCounter}`;
+    const title = h('div', { class: 'tc-inv-card-title' });
+    const subtitle = h('div', { class: 'tc-inv-card-subtitle' });
+    const rows = h('dl', { class: 'tc-inv-card-rows' });
+    const footer = h('div', { class: 'tc-inv-card-footer' });
+    const element = h('div', { class: 'tc-inv-card', role: 'tooltip', id, hidden: true }, title, subtitle, rows, footer);
+    layer.append(element);
+    let current = null;
+    let describedEl = null;
+    let placement = null;
+    function set(o) {
+        if (!current || current.title !== o.title)
+            title.textContent = o.title;
+        if (!current || current.subtitle !== o.subtitle)
+            subtitle.textContent = o.subtitle ?? '';
+        if (!current || current.footer !== o.footer)
+            footer.textContent = o.footer ?? '';
+        if (!current || current.tone !== o.tone) {
+            if (o.tone)
+                element.dataset.tone = o.tone;
+            else
+                delete element.dataset.tone;
+        }
+        if (!current || current.width !== o.width)
+            element.style.setProperty('--tc-inv-card-width', themePx(o.width ?? 280));
+        if (!current || current.rows !== o.rows || !sameRows(current.rows, o.rows)) {
+            rows.replaceChildren();
+            for (const r of o.rows) {
+                rows.append(h('dt', null, r.label), h('dd', { 'data-tone': r.tone, 'data-compare': r.compare }, r.value));
+            }
+        }
+        current = o;
+    }
+    function sameRows(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            const x = a[i];
+            const y = b[i];
+            if (x.label !== y.label ||
+                x.value !== y.value ||
+                x.tone !== y.tone ||
+                x.compare !== y.compare)
+                return false;
+        }
+        return true;
+    }
+    function show(anchor, place = 'auto') {
+        const frameRect = layer.getBoundingClientRect();
+        let a;
+        if (anchor instanceof HTMLElement) {
+            const r = anchor.getBoundingClientRect();
+            a = {
+                x: r.left - frameRect.left,
+                y: r.top - frameRect.top,
+                width: r.width,
+                height: r.height,
+            };
+            if (describedEl !== anchor) {
+                describedEl?.removeAttribute('aria-describedby');
+                anchor.setAttribute('aria-describedby', id);
+                describedEl = anchor;
+            }
+        }
+        else {
+            describedEl?.removeAttribute('aria-describedby');
+            describedEl = null;
+            a = anchor;
+        }
+        element.hidden = false;
+        const size = { width: element.offsetWidth, height: element.offsetHeight };
+        const frame = { x: 0, y: 0, width: frameRect.width, height: frameRect.height };
+        const gap = parseFloat(getComputedStyle(element).getPropertyValue('--tc-space-2')) || 0;
+        const p = placeCard(a, size, frame, place, gap);
+        element.style.transform = `translate(${p.x}px, ${p.y}px)`;
+        placement = p.placement;
+        element.dataset.placement = p.placement;
+    }
+    function hide() {
+        if (element.hidden)
+            return;
+        element.hidden = true;
+        placement = null;
+        describedEl?.removeAttribute('aria-describedby');
+        describedEl = null;
+    }
+    set(opts);
+    return {
+        element,
+        set,
+        show,
+        hide,
+        get visible() {
+            return !element.hidden;
+        },
+        get placement() {
+            return placement;
+        },
+        remove() {
+            hide();
+            element.remove();
+        },
+    };
+}

package/dist/ui/inventory-context.d.ts

@@ -0,0 +1,29 @@
+import { type InventoryHost } from './inventory.js';
+export interface ContextItem {
+    id: string;
+    label: string;
+    /** A key hint or a note at the right. */
+    hint?: string;
+    disabled?: boolean;
+    /** Drawn in the danger colour. */
+    danger?: boolean;
+}
+export interface ContextListOptions {
+    /** A client point (CSS px) or the element to sit beside. */
+    at: {
+        x: number;
+        y: number;
+    } | HTMLElement;
+    onPick: (id: string) => void;
+    onCancel?: () => void;
+    /** Accessible name. Default `Actions`. */
+    label?: string;
+}
+export interface ContextList {
+    readonly element: HTMLElement;
+    /** Close without picking (no `onCancel`). */
+    close(): void;
+    readonly open: boolean;
+}
+/** A context list. See the module comment. */
+export declare function contextList(host: InventoryHost, items: ContextItem[], opts: ContextListOptions): ContextList;

package/dist/ui/inventory-context.js

@@ -0,0 +1,125 @@
+/**
+ * The context list (ws/ui-inventory): a small `role="menu"` of actions at a point or beside an
+ * element, placed by `placeCard` (below, flipping above), on the host's `toasts` layer (the top
+ * one, never inert under a modal) or its `hud` layer without one. ArrowUp and ArrowDown wrap over
+ * the enabled items, Enter or Space picks, Escape and a press outside cancel; the first item is
+ * focused on open and the focus returns to the opener on close.
+ */
+import { h } from './dom.js';
+import { ensureInventoryStyles } from './inventory.js';
+import { placeCard } from './inventory-card.js';
+/** A context list. See the module comment. */
+export function contextList(host, items, opts) {
+    const layer = host.layers.toasts ?? host.layers.hud;
+    const doc = layer.ownerDocument;
+    ensureInventoryStyles(doc);
+    const opener = doc.activeElement;
+    const buttons = items.map((it) => h('button', {
+        type: 'button',
+        class: 'tc-context-item',
+        role: 'menuitem',
+        tabindex: '-1',
+        'aria-disabled': it.disabled ? 'true' : undefined,
+        'data-danger': it.danger === true,
+        dataset: { id: it.id },
+    }, h('span', { class: 'tc-context-label' }, it.label), it.hint ? h('span', { class: 'tc-context-hint', 'aria-hidden': 'true' }, it.hint) : null));
+    const element = h('div', { class: 'tc-context', role: 'menu', tabindex: '-1', 'aria-label': opts.label ?? 'Actions' }, ...buttons);
+    layer.append(element);
+    let open = true;
+    const enabled = () => buttons.filter((b) => b.getAttribute('aria-disabled') !== 'true');
+    function focusItem(i) {
+        const list = enabled();
+        if (list.length === 0) {
+            element.focus({ preventScroll: true });
+            return;
+        }
+        const b = list[((i % list.length) + list.length) % list.length];
+        for (const x of buttons)
+            x.tabIndex = -1;
+        b.tabIndex = 0;
+        b.focus({ preventScroll: true });
+    }
+    function close() {
+        if (!open)
+            return;
+        open = false;
+        doc.removeEventListener('pointerdown', onOutside, true);
+        const hadFocus = element.contains(doc.activeElement);
+        element.remove();
+        if (hadFocus && opener?.isConnected)
+            opener.focus({ preventScroll: true });
+    }
+    function cancel() {
+        close();
+        opts.onCancel?.();
+    }
+    function pickEl(b) {
+        if (!b || b.getAttribute('aria-disabled') === 'true')
+            return;
+        const id = b.dataset.id;
+        close();
+        opts.onPick(id);
+    }
+    const onOutside = (e) => {
+        if (!element.contains(e.target))
+            cancel();
+    };
+    doc.addEventListener('pointerdown', onOutside, true);
+    element.addEventListener('keydown', (e) => {
+        const list = enabled();
+        const cur = list.indexOf(doc.activeElement);
+        switch (e.key) {
+            case 'ArrowDown':
+                focusItem(cur < 0 ? 0 : cur + 1);
+                break;
+            case 'ArrowUp':
+                focusItem(cur < 0 ? -1 : cur - 1);
+                break;
+            case 'Home':
+                focusItem(0);
+                break;
+            case 'End':
+                focusItem(-1);
+                break;
+            case 'Enter':
+            case ' ':
+                pickEl(doc.activeElement);
+                break;
+            case 'Escape':
+                cancel();
+                break;
+            case 'Tab':
+                cancel();
+                return;
+            default:
+                return;
+        }
+        e.preventDefault();
+        e.stopPropagation();
+    });
+    element.addEventListener('click', (e) => {
+        pickEl(e.target.closest('.tc-context-item'));
+    });
+    element.addEventListener('contextmenu', (e) => e.preventDefault());
+    // Place it: measure, then put it below the anchor, flipping above when the frame ends.
+    const lr = layer.getBoundingClientRect();
+    let anchor;
+    if (opts.at instanceof HTMLElement) {
+        const r = opts.at.getBoundingClientRect();
+        anchor = { x: r.left - lr.left, y: r.top - lr.top, width: r.width, height: r.height };
+    }
+    else {
+        anchor = { x: opts.at.x - lr.left, y: opts.at.y - lr.top, width: 0, height: 0 };
+    }
+    const p = placeCard(anchor, { width: element.offsetWidth, height: element.offsetHeight }, { x: 0, y: 0, width: lr.width, height: lr.height }, 'below');
+    element.style.transform = `translate(${p.x}px, ${p.y}px)`;
+    element.dataset.placement = p.placement;
+    focusItem(0);
+    return {
+        element,
+        close,
+        get open() {
+            return open;
+        },
+    };
+}

package/dist/ui/inventory-drag.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The drag context (ws/ui-inventory): one per overlay, it moves items between registered
+ * `DropTarget`s (grids, and `ui.slots` strips through `slotsTarget`).
+ *
+ * - Pointer: a mouse or pen drags once it moves `moveThreshold` (4 CSS px) from the press; a
+ *   touch waits `longPressMs` (160) and a pan before that is left to the page. A ghost (a clone
+ *   of the item's box) follows the pointer on the host's `hud` layer, `pointer-events: none`;
+ *   the spot under the pointer gets `data-over`, and `data-reject` when the target refuses. A
+ *   drop commits through both ends (`release` on the source, `drop` on the target); a refused
+ *   drop or a release over nothing snaps the ghost back over `--tc-duration-fast`, at once when
+ *   motion is reduced.
+ * - Keyboard and pad: a grid's pick-up (`carryStart`) is held here as `dragging`; at a grid's
+ *   left or right edge the carry walks to the neighbouring target in reading order (`cross`),
+ *   `commit` drops, `cancelCarry` puts it back.
+ *
+ * Per pointer move it writes one transform and runs the targets' `spotAt`, which return stored
+ * objects: nothing is allocated on the move path.
+ */
+import type { Slots } from './hud.js';
+import type { CellItem, CellRef, DragPick, DropTarget, InventoryHost } from './inventory.js';
+import type { Card, CardOptions } from './inventory-card.js';
+export interface DragContextOptions {
+    /** Touch hold before a drag starts, ms. Default 160. */
+    longPressMs?: number;
+    /** Mouse or pen travel that starts a drag, CSS px. Default 4. */
+    moveThreshold?: number;
+    /** Touch travel before the hold that leaves the touch to the page (a pan), CSS px. Default 10. */
+    panThreshold?: number;
+    /** Snap-back time, ms, when `--tc-duration-fast` cannot be read. Default 120. */
+    returnMs?: number;
+}
+export interface DragContext {
+    register(target: DropTarget): void;
+    unregister(target: DropTarget): void;
+    /** The item in flight (pointer or keyboard), or null. */
+    readonly dragging: DragPick | null;
+    /** Abort a drag or a carry; the item stays where it was. */
+    cancel(): void;
+    /** Registered targets in reading order (top to bottom, then left to right). A fresh array. */
+    readonly targets: DropTarget[];
+    destroy(): void;
+}
+/** A drag context over `host.layers.hud`. See the module comment. */
+export declare function createDragContext(host: InventoryHost, opts?: DragContextOptions): DragContext;
+export interface SlotsTargetOptions {
+    /** The game's rule; default: every slot takes every item. */
+    canAssign?: (index: number, item: CellItem, from: CellRef) => boolean;
+    /** A card shown while a pointer hovers a slot (after `hoverMs`), filled by `describe`. */
+    card?: Card;
+    describe?: (index: number) => CardOptions | null;
+    hoverMs?: number;
+}
+export interface SlotsTarget extends DropTarget {
+    readonly slots: Slots;
+    /** Stop listening for hover. */
+    remove(): void;
+}
+/**
+ * A `ui.slots` strip as a `DropTarget`: a drag over a slot highlights it and a drop calls
+ * `onAssign(index, item, from)`; the item stays in its grid (an assignment, not a move). Slots
+ * are not focusable, so the pad walk skips the strip.
+ */
+export declare function slotsTarget(slots: Slots, onAssign: (index: number, item: CellItem, from: CellRef) => void, opts?: SlotsTargetOptions): SlotsTarget;