@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/tooltip.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Tooltips (ws/ui-3): one shared `role="tooltip"` element per overlay that follows either a DOM
+ * element (hover after a delay and focus show it; pointer leave, blur and Escape hide it) or a
+ * world point (an `AnchorHandle` or `[x, y, z]`, riding `Anchors` and hidden with it). The
+ * element lives on the `toasts` layer, which is never inert, so a tooltip reads over a modal
+ * panel's controls as well as over the HUD. Placement is the pure `placeTooltip`: the asked
+ * side, flipped to its opposite when it would leave the layer, centred on the anchor and clamped.
+ */
+import type { AnchorHandle, Anchors } from './anchor.js';
+import type { Rect } from './overlay.js';
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+export type TooltipPlacement = TooltipSide | 'auto';
+/** What a tooltip follows: an element, an anchored element, or a world point. */
+export type TooltipTarget = HTMLElement | AnchorHandle | ArrayLike<number>;
+export interface TooltipOptions {
+    /** ms from pointer enter to show (focus shows at once). Default 400. */
+    delay?: number;
+    /** The side of the target to sit on; `auto` tries top, bottom, right, left. Default `auto`. */
+    placement?: TooltipPlacement;
+    /** Draw the arrow. Default true. */
+    arrow?: boolean;
+    /** Keep it up while the pointer is over the tooltip itself (links, buttons). Default false. */
+    interactive?: boolean;
+    /** CSS px between the target and the tooltip. Default 8. */
+    gap?: number;
+}
+export interface Tooltip {
+    /** The overlay's shared tooltip element (`role="tooltip"`). */
+    readonly element: HTMLElement;
+    readonly target: TooltipTarget;
+    /** True while this tooltip owns the shared element and it is shown. */
+    readonly visible: boolean;
+    /** The side it landed on (`placeTooltip`'s choice), or null while hidden. */
+    readonly placement: TooltipSide | null;
+    set(content: string | Node): void;
+    show(): void;
+    hide(): void;
+    /** Unhook the target (and drop a world point's anchor). */
+    dispose(): void;
+}
+/** What the tooltips need from their overlay (`Overlay` fits). */
+export interface TooltipHost {
+    readonly layers: {
+        readonly hud: HTMLElement;
+        readonly toasts: HTMLElement;
+    };
+    /** The overlay's box: in `css` units the toasts layer covers it. */
+    readonly rect: Readonly<Rect>;
+    /** In `frame` units the toasts layer is the frame (`anchors().frame.rect`), else the box. */
+    readonly units: 'frame' | 'css';
+    /** The overlay's `Anchors`; throws until a camera built it. Needed for world-point targets. */
+    anchors(): Anchors;
+}
+/** The overlay's tooltip set: one element, many targets. */
+export interface Tooltips {
+    readonly element: HTMLElement;
+    /** The tooltip showing now, if any. */
+    readonly active: Tooltip | null;
+    tooltip(target: TooltipTarget, content: string | Node, opts?: TooltipOptions): Tooltip;
+    /** Re-place a shown world tooltip (after `anchors.update()`); `overlay.updateAnchors` calls it. */
+    update(): void;
+    dispose(): void;
+}
+export interface TooltipPlace {
+    x: number;
+    y: number;
+    side: TooltipSide;
+    /** The arrow's distance along the tooltip's near edge, from its left or top. */
+    arrow: number;
+}
+/**
+ * Where a tooltip of `size` goes beside `anchor` inside `frame` (same units). `auto` takes the
+ * first of top, bottom, right, left 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 box is centred on the
+ * anchor along the other axis and clamped into the frame; `arrow` says where the anchor's centre
+ * is along the near edge, kept `inset` from the corners.
+ */
+export declare function placeTooltip(anchor: Rect, size: {
+    width: number;
+    height: number;
+}, frame: Rect, placement?: TooltipPlacement, gap?: number, inset?: number): TooltipPlace;
+/** One shared tooltip element on the host's `toasts` layer. See the module comment. */
+export declare function createTooltips(host: TooltipHost): Tooltips;
+/**
+ * Stylesheet for the tooltip (design px, theme tokens).
+ */
+export declare const TOOLTIP_CSS: string;
+/** Add `TOOLTIP_CSS` to `doc` once (the first tooltip does it). */
+export declare function ensureTooltipStyles(doc?: Document): void;

package/dist/ui/tooltip.js

@@ -0,0 +1,333 @@
+import { h } from './dom.js';
+import { toFrameUnits } from './text-scale.js';
+const OPPOSITE = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left',
+};
+const ORDER = ['top', 'bottom', 'right', 'left'];
+/**
+ * Where a tooltip of `size` goes beside `anchor` inside `frame` (same units). `auto` takes the
+ * first of top, bottom, right, left 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 box is centred on the
+ * anchor along the other axis and clamped into the frame; `arrow` says where the anchor's centre
+ * is along the near edge, kept `inset` from the corners.
+ */
+export function placeTooltip(anchor, size, frame, placement = 'auto', gap = 8, inset = 12) {
+    const room = {
+        top: anchor.y - frame.y - gap,
+        bottom: frame.y + frame.height - (anchor.y + anchor.height) - gap,
+        right: frame.x + frame.width - (anchor.x + anchor.width) - gap,
+        left: anchor.x - frame.x - 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];
+    }
+    const cx = anchor.x + anchor.width / 2;
+    const cy = anchor.y + anchor.height / 2;
+    let x;
+    let y;
+    switch (side) {
+        case 'top':
+            x = cx - size.width / 2;
+            y = anchor.y - gap - size.height;
+            break;
+        case 'bottom':
+            x = cx - size.width / 2;
+            y = anchor.y + anchor.height + gap;
+            break;
+        case 'right':
+            x = anchor.x + anchor.width + gap;
+            y = cy - size.height / 2;
+            break;
+        case 'left':
+            x = anchor.x - gap - size.width;
+            y = cy - size.height / 2;
+            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));
+    const along = side === 'top' || side === 'bottom' ? cx - x : cy - y;
+    const span = side === 'top' || side === 'bottom' ? size.width : size.height;
+    const arrow = Math.max(inset, Math.min(span - inset, along));
+    return { x, y, side, arrow };
+}
+let tooltipCounter = 0;
+const isAnchorHandle = (t) => typeof t === 'object' && t !== null && 'el' in t && typeof t.set === 'function';
+/** One shared tooltip element on the host's `toasts` layer. See the module comment. */
+export function createTooltips(host) {
+    const layer = host.layers.toasts;
+    const doc = layer.ownerDocument;
+    ensureTooltipStyles(doc);
+    const id = `tc-tooltip-${++tooltipCounter}`;
+    const body = h('div', { class: 'tc-tooltip-body' });
+    const arrowEl = h('span', { class: 'tc-tooltip-arrow', 'aria-hidden': 'true' });
+    const element = h('div', { class: 'tc-tooltip', role: 'tooltip', id, hidden: true }, body, arrowEl);
+    layer.append(element);
+    let active = null;
+    let hoveringTip = false;
+    let hideTimer = null;
+    const anchorRect = { x: 0, y: 0, width: 0, height: 0 };
+    const frameRect = { x: 0, y: 0, width: 0, height: 0 };
+    const size = { width: 0, height: 0 };
+    const NO_FRAME = { x: 0, y: 0, width: 0, height: 0 };
+    // The overlay's anchors once a world point built them: their frame is the one source for
+    // where the frame is (ws/ui-4); before that, an empty frame.
+    let anchors = null;
+    const frameOf = () => anchors?.frame.rect ?? NO_FRAME;
+    function place(entry) {
+        const t = entry.target;
+        if (t instanceof HTMLElement) {
+            const lr = layer.getBoundingClientRect();
+            const r = t.getBoundingClientRect();
+            anchorRect.x = r.left - lr.left;
+            anchorRect.y = r.top - lr.top;
+            anchorRect.width = r.width;
+            anchorRect.height = r.height;
+        }
+        else {
+            const handle = entry.handle;
+            if (!handle.visible) {
+                if (!element.hidden)
+                    element.hidden = true;
+                entry.side = null;
+                return;
+            }
+            // Our proxy rides the tooltip layer; a caller's handle rides the hud layer (the frame),
+            // which the toasts layer only matches in frame units (in css units it is the whole root).
+            const shift = entry.ownsHandle || host.units === 'frame';
+            const fr = frameOf();
+            anchorRect.x = handle.x + (shift ? 0 : fr.x);
+            anchorRect.y = handle.y + (shift ? 0 : fr.y);
+            anchorRect.width = 0;
+            anchorRect.height = 0;
+        }
+        if (element.hidden)
+            element.hidden = false;
+        size.width = element.offsetWidth;
+        size.height = element.offsetHeight;
+        const box = host.units === 'frame' ? frameOf() : host.rect;
+        frameRect.width = box.width;
+        frameRect.height = box.height;
+        const p = placeTooltip(anchorRect, size, frameRect, entry.asked, entry.gap);
+        if (p.x !== entry.x || p.y !== entry.y) {
+            entry.x = p.x;
+            entry.y = p.y;
+            element.style.transform = `translate(${p.x}px, ${p.y}px)`;
+        }
+        if (p.side !== entry.side) {
+            entry.side = p.side;
+            element.dataset.placement = p.side;
+        }
+        if (p.arrow !== entry.arrowAt) {
+            entry.arrowAt = p.arrow;
+            element.style.setProperty('--tc-tooltip-arrow', `${p.arrow}px`);
+        }
+    }
+    const clearShow = (entry) => {
+        if (entry.showTimer) {
+            clearTimeout(entry.showTimer);
+            entry.showTimer = null;
+        }
+    };
+    function activate(entry) {
+        clearShow(entry);
+        if (active && active !== entry)
+            deactivate(active);
+        active = entry;
+        body.replaceChildren(entry.content);
+        element.toggleAttribute('data-interactive', entry.interactive);
+        element.toggleAttribute('data-no-arrow', !entry.arrow);
+        if (entry.target instanceof HTMLElement)
+            entry.target.setAttribute('aria-describedby', id);
+        entry.x = entry.y = entry.arrowAt = Number.NaN;
+        place(entry);
+    }
+    function deactivate(entry) {
+        clearShow(entry);
+        if (entry.target instanceof HTMLElement)
+            entry.target.removeAttribute('aria-describedby');
+        if (active === entry) {
+            active = null;
+            element.hidden = true;
+            entry.side = null;
+        }
+    }
+    element.addEventListener('pointerenter', () => {
+        hoveringTip = true;
+        if (hideTimer) {
+            clearTimeout(hideTimer);
+            hideTimer = null;
+        }
+    });
+    element.addEventListener('pointerleave', () => {
+        hoveringTip = false;
+        if (active?.interactive)
+            deactivate(active);
+    });
+    return {
+        element,
+        get active() {
+            return active ? active.tip : null;
+        },
+        tooltip(target, content, opts = {}) {
+            const isEl = target instanceof HTMLElement;
+            let handle = null;
+            let ownsHandle = false;
+            if (!isEl) {
+                if (isAnchorHandle(target))
+                    handle = target;
+                else {
+                    // A world point: a zero-size proxy on the hud layer rides the anchors.
+                    const proxy = h('span', { class: 'tc-tooltip-anchor', 'aria-hidden': 'true' });
+                    anchors = host.anchors();
+                    handle = anchors.add(proxy, target, { layer: 'toasts' });
+                    ownsHandle = true;
+                }
+            }
+            const delay = opts.delay ?? 400;
+            const onEnter = () => {
+                if (active === entry)
+                    return;
+                clearShow(entry);
+                entry.showTimer = setTimeout(() => {
+                    entry.showTimer = null;
+                    activate(entry);
+                }, delay);
+            };
+            const onLeave = () => {
+                clearShow(entry);
+                if (active !== entry)
+                    return;
+                if (!entry.interactive) {
+                    deactivate(entry);
+                    return;
+                }
+                if (hideTimer)
+                    clearTimeout(hideTimer);
+                hideTimer = setTimeout(() => {
+                    hideTimer = null;
+                    if (!hoveringTip && active === entry)
+                        deactivate(entry);
+                }, 120);
+            };
+            const onFocus = () => activate(entry);
+            const onKey = (e) => {
+                if (e.key === 'Escape' && active === entry)
+                    deactivate(entry);
+            };
+            const tip = {
+                element,
+                target,
+                get visible() {
+                    return active === entry && !element.hidden;
+                },
+                get placement() {
+                    return active === entry ? entry.side : null;
+                },
+                set(c) {
+                    entry.content = c;
+                    if (active === entry) {
+                        body.replaceChildren(c);
+                        entry.x = Number.NaN;
+                        place(entry);
+                    }
+                },
+                show() {
+                    activate(entry);
+                },
+                hide() {
+                    deactivate(entry);
+                },
+                dispose() {
+                    deactivate(entry);
+                    if (isEl) {
+                        target.removeEventListener('pointerenter', onEnter);
+                        target.removeEventListener('pointerleave', onLeave);
+                        target.removeEventListener('focus', onFocus);
+                        target.removeEventListener('blur', onLeave);
+                        target.removeEventListener('keydown', onKey);
+                    }
+                    if (ownsHandle)
+                        handle?.remove();
+                },
+            };
+            const entry = {
+                target,
+                content,
+                handle,
+                ownsHandle,
+                asked: opts.placement ?? 'auto',
+                gap: opts.gap ?? 8,
+                arrow: opts.arrow ?? true,
+                interactive: opts.interactive ?? false,
+                x: Number.NaN,
+                y: Number.NaN,
+                arrowAt: Number.NaN,
+                side: null,
+                showTimer: null,
+                tip,
+            };
+            if (isEl) {
+                target.addEventListener('pointerenter', onEnter);
+                target.addEventListener('pointerleave', onLeave);
+                target.addEventListener('focus', onFocus);
+                target.addEventListener('blur', onLeave);
+                target.addEventListener('keydown', onKey);
+            }
+            else {
+                // A world tooltip has no hover: it shows at once and rides the anchor.
+                activate(entry);
+            }
+            return tip;
+        },
+        update() {
+            if (active && !(active.target instanceof HTMLElement))
+                place(active);
+        },
+        dispose() {
+            if (active)
+                deactivate(active);
+            element.remove();
+        },
+    };
+}
+/**
+ * Stylesheet for the tooltip (design px, theme tokens).
+ */
+export const TOOLTIP_CSS = toFrameUnits(`
+.tc-tooltip { position: absolute; left: 0; top: 0; pointer-events: none; will-change: transform; box-sizing: border-box;
+  max-width: 560px; padding: var(--tc-space-2) var(--tc-space-3); font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s);
+  line-height: 1.35; color: var(--tc-color-text); background: var(--tc-color-surface);
+  border: var(--tc-border-width) solid var(--tc-color-border); border-radius: var(--tc-radius-m); box-shadow: var(--tc-shadow);
+  animation: tc-fade var(--tc-duration-fast) var(--tc-easing); }
+.tc-tooltip[hidden] { display: none; }
+.tc-tooltip[data-interactive] { pointer-events: auto; }
+.tc-tooltip-body { overflow-wrap: break-word; }
+.tc-tooltip-arrow { position: absolute; width: 16px; height: 16px; background: var(--tc-color-surface);
+  border: var(--tc-border-width) solid var(--tc-color-border); transform: rotate(45deg); }
+.tc-tooltip[data-no-arrow] .tc-tooltip-arrow { display: none; }
+.tc-tooltip[data-placement="top"] .tc-tooltip-arrow { left: var(--tc-tooltip-arrow, 50%); bottom: -9px; margin-left: -8px; border-top: 0; border-left: 0; }
+.tc-tooltip[data-placement="bottom"] .tc-tooltip-arrow { left: var(--tc-tooltip-arrow, 50%); top: -9px; margin-left: -8px; border-bottom: 0; border-right: 0; }
+.tc-tooltip[data-placement="left"] .tc-tooltip-arrow { top: var(--tc-tooltip-arrow, 50%); right: -9px; margin-top: -8px; border-bottom: 0; border-left: 0; }
+.tc-tooltip[data-placement="right"] .tc-tooltip-arrow { top: var(--tc-tooltip-arrow, 50%); left: -9px; margin-top: -8px; border-top: 0; border-right: 0; }
+.tc-tooltip-anchor { width: 0; height: 0; }
+`);
+const STYLE_ID = 'tc-ui-tooltip';
+/** Add `TOOLTIP_CSS` to `doc` once (the first tooltip does it). */
+export function ensureTooltipStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = TOOLTIP_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/widgets-2.d.ts

@@ -0,0 +1,134 @@
+/** A choice for `segmented` and `select`. */
+export interface ChoiceOption<T extends string = string> {
+    value: T;
+    label: string;
+}
+/** Colour of a `bar`: the accent, or one of the toast tones. */
+export type WidgetTone = 'accent' | 'info' | 'success' | 'warn' | 'danger';
+export interface WidgetReticleOptions {
+    /** Box the lines fit in at spread 0, design px. Default 48. */
+    size?: number;
+    /** Line thickness, design px. Default 2. */
+    thickness?: number;
+    /** Gap from the centre to each line at spread 0, design px. Default 6. */
+    gap?: number;
+    /** Centre dot. Default true. */
+    dot?: boolean;
+    /** Any CSS colour. Default the theme's text colour. */
+    color?: string;
+}
+export interface WidgetReticle {
+    element: HTMLDivElement;
+    /** Open the lines: 0 is the resting gap, 1 is a quarter of the size further out. */
+    set(spread: number): void;
+    /** Play the hit flash once (restarts if running). */
+    hit(): void;
+    hide(): void;
+    show(): void;
+}
+/**
+ * A four-line reticle with a centre dot, drawn with CSS only and centred in its parent
+ * (`position: absolute; left: 50%; top: 50%`), so it goes on the `hud` layer or any positioned
+ * box. Decorative: `aria-hidden`. `set(spread)` opens the lines; `hit()` flashes them.
+ */
+export declare function reticle(opts?: WidgetReticleOptions): WidgetReticle;
+export interface BarOptions {
+    min?: number;
+    max?: number;
+    /** Draw the track in this many segments (pips). */
+    segments?: number;
+    tone?: WidgetTone;
+    /** Text for `aria-valuetext` and the visible value. Default a whole percent. */
+    format?: (v: number) => string;
+}
+export interface Bar {
+    element: HTMLDivElement;
+    set(value: number): void;
+    tone(t: WidgetTone): void;
+}
+/**
+ * A labelled progress or health bar: `role=progressbar`, `aria-valuemin/max/now` and
+ * `aria-valuetext` (from `format`, else a percent). The fill is a `scaleX` transform driven by
+ * `--tc-ui-fill`; `segments` overlays pips; `tone` picks the fill colour.
+ */
+export declare function bar(label: string, value: number, opts?: BarOptions): Bar;
+export interface Segmented<T extends string = string> {
+    element: HTMLDivElement;
+    /** Select `value` without calling `onChange`. */
+    set(value: T): void;
+    readonly value: T;
+}
+/**
+ * A segmented choice: `role=radiogroup` with one `role=radio` button per option, roving
+ * tabindex (only the selected one is in the tab order), ArrowLeft/ArrowRight to move (wrapping)
+ * and a click to pick. Consumes only those two arrows, so a panel's ArrowUp/Down walk passes.
+ * `onChange` fires on user changes only.
+ */
+export declare function segmented<T extends string>(label: string, options: ChoiceOption<T>[], value: T, onChange: (value: T) => void): Segmented<T>;
+export interface Select<T extends string = string> {
+    element: HTMLLabelElement;
+    select: HTMLSelectElement;
+    /** Select `value` without calling `onChange`. */
+    set(value: T): void;
+}
+/** A labelled native `<select>` in the theme (`.tc-field.tc-ui-select`). */
+export declare function select<T extends string>(label: string, options: ChoiceOption<T>[], value: T, onChange: (value: T) => void): Select<T>;
+export interface KeyPromptOptions {
+    /** The bound key's text (`'E'`, `'Space'`). */
+    key?: string;
+    /** The pad button's glyph text (`'Ⓐ'`, `'RT'`). */
+    pad?: string;
+}
+export interface KeyPrompt {
+    element: HTMLSpanElement;
+    /** Show `key` in the key chip and `pad` (or nothing) in the pad chip. */
+    set(key: string, pad?: string): void;
+}
+/**
+ * An action with its binding: a key chip (`<kbd>`), a pad chip when a pad glyph is given, and
+ * the action's text. Strings in; no icon font. An empty chip hides itself.
+ */
+export declare function keyPrompt(action: string, opts?: KeyPromptOptions): KeyPrompt;
+export interface StepperOptions {
+    min: number;
+    max: number;
+    step: number;
+    /** Text for the value and `aria-valuetext`. Default the number. */
+    format?: (v: number) => string;
+}
+export interface Stepper {
+    element: HTMLDivElement;
+    /** Set the value (clamped and snapped to `step`) without calling `onChange`. */
+    set(value: number): void;
+    readonly value: number;
+}
+/**
+ * A numeric stepper: a `−` button, a focusable `role=spinbutton` value and a `+` button.
+ * ArrowUp/ArrowDown step, Home/End jump to the bounds; only those four keys are consumed.
+ * Values snap to `step` from `min` and clamp; the buttons disable at the bounds. `onChange`
+ * fires on user changes only.
+ */
+export declare function stepper(label: string, value: number, onChange: (value: number) => void, opts: StepperOptions): Stepper;
+export interface WidgetCooldownOptions {
+    /** Diameter, design px. Default 64. */
+    size?: number;
+}
+export interface WidgetCooldown {
+    element: HTMLDivElement;
+    /** 0 is just used, 1 is ready; the sweep fills clockwise. */
+    set(fraction: number): void;
+    /** True once `set` reached 1. */
+    readonly ready: boolean;
+}
+/**
+ * A radial cooldown: a disc whose `conic-gradient` sweep follows `--tc-ui-sweep`, lit when
+ * ready (`data-ready`). Decorative (`aria-hidden`): the game announces readiness itself.
+ */
+export declare function cooldown(opts?: WidgetCooldownOptions): WidgetCooldown;
+/**
+ * Stylesheet for these widgets in design px (`toFrameUnits`: every `px` here is one `--tc-unit`;
+ * `--tc-ui-px` carries that unit into the `calc`s on the size custom properties).
+ */
+export declare const WIDGETS2_CSS: string;
+/** Add `WIDGETS2_CSS` to `doc` once (`createOverlay` calls it beside `ensureStyles`). */
+export declare function ensureWidgets2Styles(doc?: Document): void;