@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/rotate-card.js

@@ -0,0 +1,97 @@
+/**
+ * The "turn it sideways" card for a landscape game on a phone held upright (interim API: Phase 2's
+ * portrait layout regions retire it, D-041).
+ *
+ * The card covers the whole viewport, outside the scaled overlay (upright, the overlay is a thin
+ * strip), and goes the moment the phone turns. Nothing is paused: the game underneath just waits
+ * for input. All words are the game's, passed as options.
+ *
+ * It shows when the viewport is portrait and the device is a phone in hand: a handheld by
+ * `deviceTraits()`, or a finger on a phone-scale screen by the device mode. A narrow desktop
+ * window never gets it.
+ */
+import { isPortrait } from '../platform/device.js';
+import { deviceTraits } from '../platform/environment.js';
+import { h } from './dom.js';
+const STYLE_ATTR = 'rotate-card';
+const CSS = /* css */ `
+.tc-rotate {
+  position: fixed; inset: 0; z-index: 50; display: flex; flex-direction: column; align-items: center;
+  justify-content: center; gap: 22px; padding: max(24px, env(safe-area-inset-top)) 28px;
+  box-sizing: border-box; text-align: center; background: var(--tc-rotate-bg, #0b0d14);
+  color: var(--tc-rotate-text, #ece6d8); font-family: var(--tc-rotate-font, Georgia, serif);
+  touch-action: none; user-select: none; -webkit-user-select: none;
+}
+.tc-rotate[hidden] { display: none; }
+.tc-rotate-phone {
+  width: 54px; height: 92px; border: 3px solid var(--tc-rotate-accent, #e0b45a); border-radius: 12px;
+  box-sizing: border-box; box-shadow: 0 0 24px var(--tc-rotate-glow, rgba(224,180,90,0.35));
+  animation: tc-rotate-turn 2.4s ease-in-out infinite;
+}
+.tc-rotate-phone::after {
+  content: ''; display: block; width: 14px; height: 3px; margin: 78px auto 0; border-radius: 2px;
+  background: var(--tc-rotate-accent, #e0b45a);
+}
+@keyframes tc-rotate-turn { 0%, 25% { transform: rotate(0deg); } 55%, 100% { transform: rotate(-90deg); } }
+@media (prefers-reduced-motion: reduce) { .tc-rotate-phone { animation: none; transform: rotate(-90deg); } }
+.tc-rotate h2 { margin: 0; font-size: 24px; color: var(--tc-rotate-accent, #e0b45a); letter-spacing: 1px; font-weight: 600; }
+.tc-rotate p { margin: 0; max-width: 300px; font-size: 17px; line-height: 1.45; }
+.tc-rotate .tc-rotate-note { font-size: 16px; font-style: italic; color: var(--tc-rotate-muted, #a7a091); }
+.tc-rotate .tc-rotate-note b {
+  font-style: normal; color: var(--tc-rotate-accent, #e0b45a); letter-spacing: 1px; font-size: 13px; margin-right: 6px;
+}
+`;
+export function createRotateCard(opts) {
+    const doc = opts.doc ?? document;
+    const win = doc.defaultView ?? window;
+    if (!doc.querySelector(`style[data-tc="${STYLE_ATTR}"]`)) {
+        doc.head.append(h('style', { 'data-tc': STYLE_ATTR }, CSS));
+    }
+    const c = opts.colors ?? {};
+    const style = {};
+    const vars = [
+        ['background', '--tc-rotate-bg'],
+        ['text', '--tc-rotate-text'],
+        ['accent', '--tc-rotate-accent'],
+        ['glow', '--tc-rotate-glow'],
+        ['muted', '--tc-rotate-muted'],
+        ['font', '--tc-rotate-font'],
+    ];
+    for (const [k, v] of vars)
+        if (c[k])
+            style[v] = c[k];
+    const note = opts.note
+        ? h('p', { class: 'tc-rotate-note' }, opts.note.tag ? h('b', null, opts.note.tag) : null, opts.note.text)
+        : null;
+    const element = h('div', {
+        class: 'tc-rotate',
+        role: 'dialog',
+        'aria-modal': 'true',
+        'aria-label': opts.ariaLabel ?? opts.title,
+        hidden: true,
+        style,
+    }, h('div', { class: 'tc-rotate-phone', 'aria-hidden': 'true' }), h('h2', null, opts.title), ...(opts.lines ?? []).map((t) => h('p', null, t)), note);
+    doc.body.append(element);
+    const device = opts.device;
+    const update = () => {
+        const phoneInHand = deviceTraits().handheld || (!!device?.touch && !!device?.phone);
+        element.hidden = !(isPortrait(win) && phoneInHand);
+    };
+    const offDevice = device?.onChange(update);
+    win.addEventListener('resize', update);
+    win.addEventListener('orientationchange', update);
+    update();
+    return {
+        element,
+        get visible() {
+            return !element.hidden;
+        },
+        update,
+        destroy() {
+            offDevice?.();
+            win.removeEventListener('resize', update);
+            win.removeEventListener('orientationchange', update);
+            element.remove();
+        },
+    };
+}

package/dist/ui/stack.d.ts

@@ -0,0 +1,128 @@
+export type CloseReason = 'escape' | 'backdrop' | 'programmatic' | 'replaced';
+/**
+ * Which arrow keys walk focus through a panel's controls (`PanelOptions.arrowNav`):
+ * `vertical` (ArrowUp/ArrowDown, the default), `both` (ArrowLeft/ArrowRight too) or `none`.
+ */
+export type ArrowNav = 'vertical' | 'both' | 'none';
+export interface PanelOptions {
+    /** Panel body. */
+    content: Node;
+    /** Visible heading (also the accessible name). Omit for chrome-less panels; then pass `label`. */
+    title?: string;
+    /** Accessible name when there's no visible title. */
+    label?: string;
+    /** Dim the background, trap focus, make lower layers inert, set `hasModal`. Default true. */
+    modal?: boolean;
+    /** Esc closes it. Default true. */
+    dismissible?: boolean;
+    /** Clicking the backdrop closes it. Default: same as `dismissible`. */
+    closeOnBackdrop?: boolean;
+    /** `card` (themed surface) or `none` (you style it, e.g. a full-screen book). Default `card`. */
+    chrome?: 'card' | 'none';
+    /** Extra class on the panel element. */
+    className?: string;
+    /** Element (or selector within the panel) to focus on open. Default: first focusable, else the panel. */
+    initialFocus?: HTMLElement | string;
+    /** `dialog` (default) or `alertdialog`. */
+    role?: 'dialog' | 'alertdialog';
+    /**
+     * Arrow keys move focus among the panel's focusable elements, wrapping, while this panel is on
+     * top: `vertical` (ArrowUp/ArrowDown; the default), `both` (ArrowLeft/ArrowRight too) or
+     * `none`. A focused text field, textarea, select or slider keeps the arrows it uses itself.
+     */
+    arrowNav?: ArrowNav;
+    onClose?: (reason: CloseReason) => void;
+}
+export interface PanelHandle {
+    /** The panel element (`role=dialog`), containing `content`. */
+    readonly element: HTMLElement;
+    readonly open: boolean;
+    close(reason?: CloseReason): void;
+}
+/**
+ * Put this attribute on an opener (or any ancestor, e.g. a HUD bar) whose buttons double as
+ * keyboard shortcuts. When a panel it opened closes, focus does not go back to it, because a
+ * focused button would swallow the game's keys. Focus goes to the next panel down, else to
+ * the stack's focus home.
+ */
+export declare const NO_RESTORE_FOCUS_ATTR = "data-tc-no-restore-focus";
+/** Who the gamepad belongs to: the panel stack while a modal is open, else the game. */
+export type PadOwner = 'stack' | 'game';
+export interface PanelStackFocusOptions {
+    /**
+     * Where focus goes when a panel closes and there is nowhere better: the opener is gone,
+     * inert, marked `NO_RESTORE_FOCUS_ATTR` or was nothing (`<body>`), and no panel is left
+     * to focus. Typically the game canvas, so key handling keeps working.
+     */
+    home?: () => HTMLElement | null;
+}
+/**
+ * A stack of panels inside one container. The top panel gets keyboard focus; Esc closes it
+ * (if dismissible); Tab cycles inside the top modal; the arrow keys walk its controls
+ * (`arrowNav`); lower panels and `inertWhenModal` elements are made `inert` while a modal is
+ * on top.
+ */
+export declare class PanelStack {
+    private readonly container;
+    private readonly inertWhenModal;
+    private readonly focus;
+    private readonly entries;
+    private readonly listeners;
+    private readonly padListeners;
+    private owner;
+    private readonly doc;
+    private readonly onKey;
+    /**
+     * @param container where panel hosts are appended (the overlay's `panels` layer).
+     * @param inertWhenModal other elements to make inert while a modal is open (e.g. the HUD layer).
+     * @param focus where focus goes on close when the opener shouldn't (or can't) get it back.
+     */
+    constructor(container: HTMLElement, inertWhenModal?: readonly HTMLElement[], focus?: PanelStackFocusOptions);
+    get size(): number;
+    /** True while any open panel is modal. Wire this to `input.blocked`. */
+    get hasModal(): boolean;
+    get top(): PanelHandle | null;
+    /**
+     * Who the gamepad belongs to (ws/ui-4): `'stack'` while any modal panel is open (PadNav drives
+     * the panel; the world cursor and the game's input yield), else `'game'`.
+     */
+    get padOwner(): PadOwner;
+    /**
+     * Called once per transition of `padOwner`, after the panel that caused it opened or closed
+     * (not on every push or pop: a second modal over the first changes nothing). Returns the
+     * remover. `PadNav` and `ui.cursor` subscribe to this instead of polling `hasModal` each frame.
+     */
+    onPadOwnerChange(fn: (owner: PadOwner) => void): () => void;
+    onChange(fn: (stack: PanelStack) => void): () => void;
+    push(opts: PanelOptions): PanelHandle;
+    /**
+     * What Esc does, for other input devices (e.g. a gamepad's back button): close the top
+     * panel if it is dismissible. Returns true if one closed.
+     */
+    dismissTop(): boolean;
+    /** The top panel's element if it is modal (the one keyboard focus is trapped in). */
+    get topModalElement(): HTMLElement | null;
+    /** Close the top panel. Returns false if the stack was empty. */
+    pop(reason?: CloseReason): boolean;
+    /** Close the top panel (if any) and push a new one. */
+    replace(opts: PanelOptions): PanelHandle;
+    /** Close everything, top first. */
+    clear(): void;
+    destroy(): void;
+    private closeEntry;
+    /** Tell the pad-owner listeners once when `hasModal` flipped. */
+    private syncPadOwner;
+    private canRestore;
+    /** Inert everything below the topmost modal. */
+    private refresh;
+    private focusInitial;
+    private handleKey;
+    /**
+     * ArrowUp/ArrowDown (and ArrowLeft/ArrowRight with `arrowNav: 'both'`) move focus through the
+     * top panel's focusable elements, wrapping, when focus is inside it (always, for a modal). A
+     * focused control that uses the arrow itself (a text field's caret, a select, a slider) keeps
+     * it; a consumed arrow is `preventDefault`ed and stopped, like Escape.
+     */
+    private handleArrow;
+    private emit;
+}

package/dist/ui/stack.js

@@ -0,0 +1,312 @@
+import { consumesArrows, focusableWithin, h } from './dom.js';
+let idCounter = 0;
+/**
+ * Put this attribute on an opener (or any ancestor, e.g. a HUD bar) whose buttons double as
+ * keyboard shortcuts. When a panel it opened closes, focus does not go back to it, because a
+ * focused button would swallow the game's keys. Focus goes to the next panel down, else to
+ * the stack's focus home.
+ */
+export const NO_RESTORE_FOCUS_ATTR = 'data-tc-no-restore-focus';
+/** `ArrowNav` per key: the step through the focusable list, or 0 when the key is not an arrow. */
+function arrowStep(key, nav) {
+    if (nav === 'none')
+        return 0;
+    if (key === 'ArrowDown')
+        return 1;
+    if (key === 'ArrowUp')
+        return -1;
+    if (nav === 'both') {
+        if (key === 'ArrowRight')
+            return 1;
+        if (key === 'ArrowLeft')
+            return -1;
+    }
+    return 0;
+}
+/**
+ * A stack of panels inside one container. The top panel gets keyboard focus; Esc closes it
+ * (if dismissible); Tab cycles inside the top modal; the arrow keys walk its controls
+ * (`arrowNav`); lower panels and `inertWhenModal` elements are made `inert` while a modal is
+ * on top.
+ */
+export class PanelStack {
+    container;
+    inertWhenModal;
+    focus;
+    entries = [];
+    listeners = new Set();
+    padListeners = new Set();
+    owner = 'game';
+    doc;
+    onKey = (e) => this.handleKey(e);
+    /**
+     * @param container where panel hosts are appended (the overlay's `panels` layer).
+     * @param inertWhenModal other elements to make inert while a modal is open (e.g. the HUD layer).
+     * @param focus where focus goes on close when the opener shouldn't (or can't) get it back.
+     */
+    constructor(container, inertWhenModal = [], focus = {}) {
+        this.container = container;
+        this.inertWhenModal = inertWhenModal;
+        this.focus = focus;
+        this.doc = container.ownerDocument;
+        this.doc.addEventListener('keydown', this.onKey);
+    }
+    get size() {
+        return this.entries.length;
+    }
+    /** True while any open panel is modal. Wire this to `input.blocked`. */
+    get hasModal() {
+        return this.entries.some((e) => e.opts.modal !== false);
+    }
+    get top() {
+        return this.entries.at(-1)?.handle ?? null;
+    }
+    /**
+     * Who the gamepad belongs to (ws/ui-4): `'stack'` while any modal panel is open (PadNav drives
+     * the panel; the world cursor and the game's input yield), else `'game'`.
+     */
+    get padOwner() {
+        return this.owner;
+    }
+    /**
+     * Called once per transition of `padOwner`, after the panel that caused it opened or closed
+     * (not on every push or pop: a second modal over the first changes nothing). Returns the
+     * remover. `PadNav` and `ui.cursor` subscribe to this instead of polling `hasModal` each frame.
+     */
+    onPadOwnerChange(fn) {
+        this.padListeners.add(fn);
+        return () => this.padListeners.delete(fn);
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    push(opts) {
+        const modal = opts.modal !== false;
+        const dismissible = opts.dismissible !== false;
+        const id = `tc-panel-${++idCounter}`;
+        const titleEl = opts.title
+            ? h('h2', { class: 'tc-panel-title', id: `${id}-title` }, opts.title)
+            : null;
+        const panel = h('div', {
+            class: ['tc-panel', opts.chrome === 'none' ? '' : 'tc-card', opts.className ?? '']
+                .join(' ')
+                .trim(),
+            role: opts.role ?? 'dialog',
+            'aria-modal': modal ? 'true' : null,
+            'aria-labelledby': titleEl ? titleEl.id : null,
+            'aria-label': !titleEl && opts.label ? opts.label : null,
+            tabindex: '-1',
+            id,
+        }, titleEl, opts.content);
+        const host = h('div', { class: 'tc-panel-host', dataset: { modal: String(modal) } });
+        if (modal) {
+            const backdrop = h('div', { class: 'tc-backdrop', 'aria-hidden': 'true' });
+            if (opts.closeOnBackdrop ?? dismissible) {
+                backdrop.addEventListener('click', () => entry.handle.close('backdrop'));
+            }
+            host.append(backdrop);
+        }
+        host.append(panel);
+        const entry = {
+            host,
+            panel,
+            opts,
+            restoreFocus: this.doc.activeElement,
+            open: true,
+            handle: {
+                element: panel,
+                get open() {
+                    return entry.open;
+                },
+                close: (reason = 'programmatic') => this.closeEntry(entry, reason),
+            },
+        };
+        this.entries.push(entry);
+        this.container.append(host);
+        this.refresh();
+        this.focusInitial(entry);
+        this.syncPadOwner();
+        this.emit();
+        return entry.handle;
+    }
+    /**
+     * What Esc does, for other input devices (e.g. a gamepad's back button): close the top
+     * panel if it is dismissible. Returns true if one closed.
+     */
+    dismissTop() {
+        const top = this.entries.at(-1);
+        if (!top || top.opts.dismissible === false)
+            return false;
+        top.handle.close('escape');
+        return true;
+    }
+    /** The top panel's element if it is modal (the one keyboard focus is trapped in). */
+    get topModalElement() {
+        const top = this.entries.at(-1);
+        return top && top.opts.modal !== false ? top.panel : null;
+    }
+    /** Close the top panel. Returns false if the stack was empty. */
+    pop(reason = 'programmatic') {
+        const top = this.entries.at(-1);
+        if (!top)
+            return false;
+        this.closeEntry(top, reason);
+        return true;
+    }
+    /** Close the top panel (if any) and push a new one. */
+    replace(opts) {
+        const top = this.entries.at(-1);
+        if (top)
+            this.closeEntry(top, 'replaced', false);
+        return this.push(opts);
+    }
+    /** Close everything, top first. */
+    clear() {
+        while (this.entries.length)
+            this.closeEntry(this.entries.at(-1), 'programmatic');
+    }
+    destroy() {
+        this.clear();
+        this.doc.removeEventListener('keydown', this.onKey);
+        this.listeners.clear();
+        this.padListeners.clear();
+    }
+    closeEntry(entry, reason, restore = true) {
+        if (!entry.open)
+            return;
+        const i = this.entries.indexOf(entry);
+        const wasTop = i === this.entries.length - 1;
+        entry.open = false;
+        this.entries.splice(i, 1);
+        entry.host.remove();
+        this.refresh();
+        if (restore && wasTop) {
+            const back = entry.restoreFocus;
+            const top = this.entries.at(-1);
+            if (this.canRestore(back)) {
+                back.focus();
+            }
+            else if (top) {
+                this.focusInitial(top);
+            }
+            else {
+                this.focus.home?.()?.focus({ preventScroll: true });
+            }
+        }
+        entry.opts.onClose?.(reason);
+        this.syncPadOwner();
+        this.emit();
+    }
+    /** Tell the pad-owner listeners once when `hasModal` flipped. */
+    syncPadOwner() {
+        const next = this.hasModal ? 'stack' : 'game';
+        if (next === this.owner)
+            return;
+        this.owner = next;
+        for (const fn of this.padListeners)
+            fn(next);
+    }
+    canRestore(el) {
+        if (!el?.isConnected || typeof el.focus !== 'function' || el.closest('[inert]'))
+            return false;
+        // With a focus home, "nothing was focused" restores to home rather than to <body>.
+        if (this.focus.home && (el === this.doc.body || el === this.doc.documentElement))
+            return false;
+        return !el.closest(`[${NO_RESTORE_FOCUS_ATTR}]`);
+    }
+    /** Inert everything below the topmost modal. */
+    refresh() {
+        let topModal = -1;
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            if (this.entries[i].opts.modal !== false) {
+                topModal = i;
+                break;
+            }
+        }
+        this.entries.forEach((e, i) => {
+            e.host.inert = i < topModal;
+            e.host.toggleAttribute('inert', i < topModal);
+        });
+        for (const el of this.inertWhenModal) {
+            el.inert = topModal >= 0;
+            el.toggleAttribute('inert', topModal >= 0);
+        }
+    }
+    focusInitial(entry) {
+        const f = entry.opts.initialFocus;
+        let target = null;
+        if (typeof f === 'string')
+            target = entry.panel.querySelector(f);
+        else if (f)
+            target = f;
+        target ??= focusableWithin(entry.panel)[0] ?? entry.panel;
+        target.focus({ preventScroll: true });
+    }
+    handleKey(e) {
+        const top = this.entries.at(-1);
+        if (!top || e.defaultPrevented)
+            return;
+        if (e.key === 'Escape') {
+            if (top.opts.dismissible === false)
+                return;
+            e.preventDefault();
+            // Keep the game's input map from also seeing this Escape.
+            e.stopPropagation();
+            top.handle.close('escape');
+            return;
+        }
+        if (e.key === 'Tab' && top.opts.modal !== false) {
+            const items = focusableWithin(top.panel);
+            if (items.length === 0) {
+                e.preventDefault();
+                top.panel.focus();
+                return;
+            }
+            const first = items[0];
+            const last = items[items.length - 1];
+            const active = this.doc.activeElement;
+            const inside = active instanceof Node && top.panel.contains(active);
+            if (e.shiftKey && (active === first || !inside)) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && (active === last || !inside)) {
+                e.preventDefault();
+                first.focus();
+            }
+            return;
+        }
+        this.handleArrow(e, top);
+    }
+    /**
+     * ArrowUp/ArrowDown (and ArrowLeft/ArrowRight with `arrowNav: 'both'`) move focus through the
+     * top panel's focusable elements, wrapping, when focus is inside it (always, for a modal). A
+     * focused control that uses the arrow itself (a text field's caret, a select, a slider) keeps
+     * it; a consumed arrow is `preventDefault`ed and stopped, like Escape.
+     */
+    handleArrow(e, top) {
+        const step = arrowStep(e.key, top.opts.arrowNav ?? 'vertical');
+        if (step === 0 || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey)
+            return;
+        const active = this.doc.activeElement;
+        const inside = active !== null && top.panel.contains(active);
+        if (!inside && top.opts.modal === false)
+            return;
+        const horizontal = e.key === 'ArrowLeft' || e.key === 'ArrowRight';
+        if (inside && active !== top.panel && consumesArrows(active, horizontal))
+            return;
+        const items = focusableWithin(top.panel);
+        if (items.length === 0)
+            return;
+        const i = inside ? items.indexOf(active) : -1;
+        const next = i < 0 ? (step > 0 ? 0 : items.length - 1) : (i + step + items.length) % items.length;
+        e.preventDefault();
+        e.stopPropagation();
+        items[next]?.focus();
+    }
+    emit() {
+        for (const fn of this.listeners)
+            fn(this);
+    }
+}

package/dist/ui/styles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The overlay's base stylesheet: tokens, layers, panels, widgets and units. Injected once
+ * per document by `ensureStyles`; the HUD, cursor, tooltip and other widget sheets add
+ * their own `<style>` beside it. Everything is under `.tc-overlay`.
+ */
+export declare const BASE_CSS: string;
+/** Add the base stylesheet to `doc` once. */
+export declare function ensureStyles(doc?: Document): void;
+/**
+ * True if the user prefers reduced motion in `win` (default the global window; false where
+ * `matchMedia` is unavailable). `platform`'s `prefersReducedMotion()` reads the global window only.
+ */
+export declare function prefersReducedMotionIn(win?: Window | undefined): boolean;