@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/notify.js

@@ -0,0 +1,141 @@
+/**
+ * Notifications (ws/ui-3): richer than toasts (which are one line of text, top-centre): a titled
+ * card with a body, an icon, a tone and action buttons, stacked top-right on the `toasts` layer
+ * in a `role="status"` polite live region. Each one times out unless hovered or focused (or
+ * `timeout: 0`); a close button and Escape dismiss it. The actions are plain buttons, so the
+ * game's pad drives them through `menuNav(input, ui.notifications.element)` when it wants to.
+ */
+import { h } from './dom.js';
+import { toFrameUnits } from './text-scale.js';
+import { button } from './widgets.js';
+/** A notifier stacked top-right in `container` (the overlay's `toasts` layer). */
+export function createNotifier(container, max = 4) {
+    const doc = container.ownerDocument;
+    ensureNotifyStyles(doc);
+    const element = h('div', { class: 'tc-notify', role: 'status', 'aria-live': 'polite' });
+    container.append(element);
+    const live = [];
+    const notifier = {
+        element,
+        get count() {
+            return live.length;
+        },
+        notify(opts) {
+            const tone = opts.tone ?? 'info';
+            const actions = (opts.actions ?? []).map((a) => button(a.label, () => {
+                a.onClick();
+                if (!a.keep)
+                    handle.dismiss();
+            }, { variant: 'ghost', className: 'tc-notification-action' }));
+            const close = button('×', () => handle.dismiss(), {
+                variant: 'ghost',
+                className: 'tc-notification-close',
+                ariaLabel: 'Dismiss',
+            });
+            const card = h('div', { class: 'tc-notification', dataset: { tone }, tabindex: '-1' }, opts.icon !== undefined
+                ? h('span', { class: 'tc-notification-icon', 'aria-hidden': 'true' }, opts.icon)
+                : null, h('div', { class: 'tc-notification-main' }, h('div', { class: 'tc-notification-title' }, opts.title), opts.body !== undefined ? h('div', { class: 'tc-notification-body' }, opts.body) : null, actions.length > 0 ? h('div', { class: 'tc-notification-actions' }, ...actions) : null), close);
+            let timer = null;
+            let open = true;
+            const timeout = opts.timeout ?? 6000;
+            const arm = () => {
+                if (timer)
+                    clearTimeout(timer);
+                timer = timeout > 0 ? setTimeout(() => handle.dismiss(), timeout) : null;
+            };
+            const pause = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const handle = {
+                element: card,
+                get open() {
+                    return open;
+                },
+                dismiss() {
+                    if (!open)
+                        return;
+                    open = false;
+                    pause();
+                    const i = live.indexOf(handle);
+                    if (i >= 0)
+                        live.splice(i, 1);
+                    const hadFocus = card.contains(doc.activeElement);
+                    card.remove();
+                    // Keep a pad user on the stack rather than dropping focus to the body.
+                    if (hadFocus)
+                        notifier.focus();
+                },
+            };
+            card.addEventListener('pointerenter', pause);
+            card.addEventListener('pointerleave', arm);
+            card.addEventListener('focusin', pause);
+            card.addEventListener('focusout', (e) => {
+                if (!card.contains(e.relatedTarget))
+                    arm();
+            });
+            card.addEventListener('keydown', (e) => {
+                if (e.key === 'Escape') {
+                    e.stopPropagation();
+                    handle.dismiss();
+                }
+            });
+            element.prepend(card);
+            live.push(handle);
+            while (live.length > max)
+                live[0].dismiss();
+            arm();
+            return handle;
+        },
+        dismissAll() {
+            for (const n of [...live])
+                n.dismiss();
+        },
+        focus() {
+            const first = element.querySelector('.tc-notification button');
+            if (!first)
+                return false;
+            first.focus();
+            return true;
+        },
+        dispose() {
+            notifier.dismissAll();
+            element.remove();
+        },
+    };
+    return notifier;
+}
+/**
+ * Stylesheet for notifications (design px, theme tokens).
+ */
+export const NOTIFY_CSS = toFrameUnits(`
+.tc-notify { position: absolute; top: var(--tc-space-5); right: var(--tc-space-5); display: flex; flex-direction: column;
+  gap: var(--tc-space-2); width: min(560px, calc(100% - 2 * var(--tc-space-5))); pointer-events: none; }
+.tc-notification { display: flex; align-items: flex-start; gap: var(--tc-space-3); pointer-events: auto;
+  padding: var(--tc-space-3) var(--tc-space-3) var(--tc-space-3) var(--tc-space-4); color: var(--tc-color-text);
+  font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s); background: var(--tc-color-surface);
+  border: var(--tc-border-width) solid var(--tc-color-border); border-left-width: 6px; border-left-color: var(--tc-color-info);
+  border-radius: var(--tc-radius-m); box-shadow: var(--tc-shadow); animation: tc-drop var(--tc-duration-normal) var(--tc-easing); outline: none; }
+.tc-notification[data-tone="success"] { border-left-color: var(--tc-color-success); }
+.tc-notification[data-tone="warn"] { border-left-color: var(--tc-color-warn); }
+.tc-notification[data-tone="danger"] { border-left-color: var(--tc-color-danger); }
+.tc-notification-icon { flex: none; font-size: var(--tc-font-size-m); line-height: 1.2; }
+.tc-notification-main { flex: 1 1 auto; min-width: 0; display: grid; gap: var(--tc-space-1); }
+.tc-notification-title { font-weight: 700; }
+.tc-notification-body { color: var(--tc-color-text-muted); overflow-wrap: break-word; }
+.tc-notification-actions { display: flex; flex-wrap: wrap; gap: var(--tc-space-2); margin-top: var(--tc-space-1); }
+.tc-notification-close { flex: none; margin: calc(-1 * var(--tc-space-2)) calc(-1 * var(--tc-space-2)) 0 0; }
+@media (prefers-reduced-motion: reduce) { .tc-notification { animation: none; } }
+`);
+const STYLE_ID = 'tc-ui-notify';
+/** Add `NOTIFY_CSS` to `doc` once (the first notification does it). */
+export function ensureNotifyStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = NOTIFY_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/orb.d.ts

@@ -0,0 +1,53 @@
+import type { HudHost, Meter, MeterOptions, MeterTrailOptions } from './hud.js';
+import { type RegionName, type WidgetOptions } from './layout.js';
+/**
+ * Where a lagging band is, from the times of the last change: it holds at `from` for `delay` ms
+ * after `t0`, then moves linearly to `to` over `duration` ms (a CSS `linear` transition with that
+ * delay draws the same curve). @internal
+ */
+export declare class TrailClock {
+    readonly delay: number;
+    readonly duration: number;
+    private readonly now;
+    from: number;
+    to: number;
+    t0: number;
+    constructor(delay: number, duration: number, now: () => number);
+    /** The band's value at time `t` (default now). */
+    at(t?: number): number;
+    /** Retarget to `to` from wherever the band is now, as a restarted CSS transition does. */
+    retarget(to: number): void;
+    /** Jump to `v` with no lag. */
+    reset(v: number): void;
+    /** The clock's time now, ms. */
+    time(): number;
+}
+/**
+ * Restart a trail band's CSS transition where `clock` has it (ws/ui-11). Moving a node (the
+ * layout putting a meter in another region) cancels its transitions, so the band would jump to
+ * the value; this puts it back where the model is and runs the rest of the hold and the drain,
+ * on the same curve. `prefix` is `orb` or `meter`: `--tc-<prefix>-trail` goes on `valueEl`, the
+ * timings (`--tc-<prefix>-trail-delay`, `-duration`) on `timingEl`. Returns whether it re-armed
+ * (the caller puts the configured timings back on its next change). @internal
+ */
+export declare function rearmTrail(clock: TrailClock, band: HTMLElement, prefix: 'orb' | 'meter', valueEl: HTMLElement, timingEl: HTMLElement): boolean;
+/** A meter's layout placement: `MeterOptions.place`, else `region` (default `bottom`). @internal */
+export declare function meterPlace(place: RegionName | WidgetOptions['place'] | undefined, region: RegionName | undefined): WidgetOptions['place'];
+/** Resolve `MeterOptions.trail` into timings, or null when off (or under reduced motion). */
+export declare function trailTimings(opts: MeterOptions, reduced: boolean): Required<MeterTrailOptions> | null;
+export declare function meterClock(opts: MeterOptions): () => number;
+export declare function meterReducedMotion(host: HudHost, opts: MeterOptions): boolean;
+/**
+ * The orb stylesheet, under `.tc-overlay` and in `--tc-*` tokens. `--tc-orb-color` is the fill
+ * (the tone's token, or the per-call `color`); `--tc-color-meter-trail` the trail band.
+ */
+export declare const ORB_CSS: string;
+/** Add `ORB_CSS` to `doc` once (the first orb does it). */
+export declare function ensureOrbStyles(doc?: Document): void;
+/** What a readout shows for `value` of `max`. @internal */
+export declare function readoutText(mode: MeterOptions['readout'], value: number, max: number, format?: (value: number, max: number) => string): string;
+/**
+ * The orb (see the module comment). `ui.meter({ shape: 'orb' })` and `createMeter(host, { shape:
+ * 'orb' })` come here; it returns the same `Meter` handle as the bar.
+ */
+export declare function createOrbMeter(host: HudHost, opts?: MeterOptions): Meter;

package/dist/ui/orb.js

@@ -0,0 +1,304 @@
+/**
+ * Orb meter (ws/ui-5): `ui.meter({ shape: 'orb' })`, the round fill gauge an action-RPG HUD puts
+ * either side of its ability row. The fill rises from the bottom of a round well with a bright
+ * meniscus line on its surface; an optional damage `trail` (a lighter band) holds where the value
+ * was for `delay` ms, then drains to it over `duration` ms. A readout in the middle shows the value,
+ * a percent or nothing.
+ *
+ * Everything moves by `transform` on CSS transitions, so an orb costs nothing per frame: a `set`
+ * writes two custom properties and the compositor does the rest. `trail` (the trail's value now)
+ * is computed from the same clock and timings as the transition, so a test or a game reads where
+ * the band is without measuring it. `prefers-reduced-motion` (or `reducedMotion: true`) turns the
+ * trail and the fill's easing off.
+ *
+ * The trail model is shared with the bar meter (`createMeter` with `trail`).
+ */
+import { h } from './dom.js';
+import { formSize, } from './layout.js';
+import { prefersReducedMotionIn } from './styles.js';
+/** `n` theme px (the same `calc` as `themePx` in `hud.ts`, kept local to avoid an import cycle). */
+const tpx = (n) => `calc(${n} * var(--tc-space-1) / 4)`;
+/**
+ * Where a lagging band is, from the times of the last change: it holds at `from` for `delay` ms
+ * after `t0`, then moves linearly to `to` over `duration` ms (a CSS `linear` transition with that
+ * delay draws the same curve). @internal
+ */
+export class TrailClock {
+    delay;
+    duration;
+    now;
+    from = 0;
+    to = 0;
+    t0 = -1e12;
+    constructor(delay, duration, now) {
+        this.delay = delay;
+        this.duration = duration;
+        this.now = now;
+    }
+    /** The band's value at time `t` (default now). */
+    at(t = this.now()) {
+        const k = this.duration > 0 ? (t - this.t0 - this.delay) / this.duration : 1;
+        if (k <= 0)
+            return this.from;
+        if (k >= 1)
+            return this.to;
+        return this.from + (this.to - this.from) * k;
+    }
+    /** Retarget to `to` from wherever the band is now, as a restarted CSS transition does. */
+    retarget(to) {
+        const t = this.now();
+        this.from = this.at(t);
+        this.to = to;
+        this.t0 = t;
+    }
+    /** Jump to `v` with no lag. */
+    reset(v) {
+        this.from = v;
+        this.to = v;
+        this.t0 = -1e12;
+    }
+    /** The clock's time now, ms. */
+    time() {
+        return this.now();
+    }
+}
+/**
+ * Restart a trail band's CSS transition where `clock` has it (ws/ui-11). Moving a node (the
+ * layout putting a meter in another region) cancels its transitions, so the band would jump to
+ * the value; this puts it back where the model is and runs the rest of the hold and the drain,
+ * on the same curve. `prefix` is `orb` or `meter`: `--tc-<prefix>-trail` goes on `valueEl`, the
+ * timings (`--tc-<prefix>-trail-delay`, `-duration`) on `timingEl`. Returns whether it re-armed
+ * (the caller puts the configured timings back on its next change). @internal
+ */
+export function rearmTrail(clock, band, prefix, valueEl, timingEl) {
+    const t = clock.time();
+    const v = clock.at(t);
+    if (v === clock.to)
+        return false;
+    const since = t - clock.t0;
+    band.style.transition = 'none';
+    valueEl.style.setProperty(`--tc-${prefix}-trail`, String(v));
+    // One style read so the jump lands before the transition comes back (off the frame path).
+    void band.ownerDocument.defaultView?.getComputedStyle(band).transform;
+    band.style.transition = '';
+    timingEl.style.setProperty(`--tc-${prefix}-trail-delay`, `${Math.max(0, clock.delay - since)}ms`);
+    timingEl.style.setProperty(`--tc-${prefix}-trail-duration`, `${clock.duration - Math.max(0, since - clock.delay)}ms`);
+    valueEl.style.setProperty(`--tc-${prefix}-trail`, String(clock.to));
+    return true;
+}
+/** A meter's layout placement: `MeterOptions.place`, else `region` (default `bottom`). @internal */
+export function meterPlace(place, region) {
+    if (typeof place === 'string')
+        return { default: place };
+    return place ?? { default: region ?? 'bottom' };
+}
+/** Resolve `MeterOptions.trail` into timings, or null when off (or under reduced motion). */
+export function trailTimings(opts, reduced) {
+    if (!opts.trail || reduced)
+        return null;
+    const t = opts.trail === true ? {} : opts.trail;
+    return { delay: Math.max(0, t.delay ?? 400), duration: Math.max(0, t.duration ?? 600) };
+}
+export function meterClock(opts) {
+    return opts.now ?? (() => globalThis.performance?.now() ?? Date.now());
+}
+export function meterReducedMotion(host, opts) {
+    return (opts.reducedMotion ??
+        prefersReducedMotionIn(host.layers.hud.ownerDocument.defaultView ?? undefined));
+}
+const STYLE_ID = 'tc-ui-orb';
+/**
+ * The orb stylesheet, under `.tc-overlay` and in `--tc-*` tokens. `--tc-orb-color` is the fill
+ * (the tone's token, or the per-call `color`); `--tc-color-meter-trail` the trail band.
+ */
+export const ORB_CSS = `
+.tc-overlay .tc-orb { position: relative; width: var(--tc-orb-size, ${tpx(128)}); height: var(--tc-orb-size, ${tpx(128)});
+  flex: none; pointer-events: none; font-family: var(--tc-font-ui); color: var(--tc-color-text);
+  --tc-orb-tone: var(--tc-color-accent); --tc-orb-color: var(--tc-meter-color, var(--tc-orb-tone)); }
+.tc-overlay .tc-orb[data-tone="info"] { --tc-orb-tone: var(--tc-color-info); }
+.tc-overlay .tc-orb[data-tone="success"] { --tc-orb-tone: var(--tc-color-success); }
+.tc-overlay .tc-orb[data-tone="warn"] { --tc-orb-tone: var(--tc-color-warn); }
+.tc-overlay .tc-orb[data-tone="danger"] { --tc-orb-tone: var(--tc-color-danger); }
+.tc-overlay .tc-orb-well { position: absolute; inset: 0; border-radius: 50%; overflow: hidden; isolation: isolate;
+  background: radial-gradient(circle at 50% 60%, var(--tc-color-surface-alt), var(--tc-color-bg));
+  border: calc(var(--tc-border-width) * 1.5) solid var(--tc-color-border);
+  box-shadow: var(--tc-shadow), inset 0 0 ${tpx(18)} rgba(0, 0, 0, 0.8); }
+.tc-overlay .tc-orb-fill, .tc-overlay .tc-orb-trail { position: absolute; left: 0; right: 0; top: 0; height: 100%;
+  will-change: transform; transform: translateY(calc((1 - var(--tc-orb-value, 1)) * 100%)); }
+.tc-overlay .tc-orb-trail { transform: translateY(calc((1 - var(--tc-orb-trail, 1)) * 100%));
+  background: var(--tc-color-meter-trail); transition: transform var(--tc-orb-trail-duration, 600ms) linear var(--tc-orb-trail-delay, 400ms); }
+.tc-overlay .tc-orb-fill { transition: transform var(--tc-duration-fast) var(--tc-easing);
+  background: radial-gradient(circle at 38% 30%, color-mix(in srgb, var(--tc-orb-color) 55%, white), var(--tc-orb-color) 45%,
+    color-mix(in srgb, var(--tc-orb-color) 40%, black)); }
+.tc-overlay .tc-orb-fill::before { content: ''; position: absolute; left: 0; right: 0; top: 0; height: ${tpx(3)};
+  background: color-mix(in srgb, var(--tc-orb-color) 30%, white); box-shadow: 0 0 ${tpx(6)} color-mix(in srgb, var(--tc-orb-color) 50%, white);
+  opacity: 0.9; }
+.tc-overlay .tc-orb[data-empty] .tc-orb-fill::before { display: none; }
+.tc-overlay .tc-orb-gloss { position: absolute; inset: 8% 22% 56% 18%; border-radius: 50%; pointer-events: none;
+  background: linear-gradient(rgba(255, 255, 255, 0.35), rgba(255, 255, 255, 0)); }
+.tc-overlay .tc-orb-readout { position: absolute; inset: 0; display: grid; place-items: center; font-weight: 700;
+  font-size: var(--tc-font-size-m); line-height: 1; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9), 0 0 ${tpx(4)} rgba(0, 0, 0, 0.6);
+  font-variant-numeric: tabular-nums; }
+.tc-overlay .tc-orb-readout:empty { display: none; }
+.tc-overlay .tc-orb[data-reduced] .tc-orb-fill { transition: none; }
+@media (prefers-reduced-motion: reduce) {
+  .tc-overlay .tc-orb-fill { transition: none; }
+  .tc-overlay .tc-orb-trail { display: none; }
+}
+`;
+/** Add `ORB_CSS` to `doc` once (the first orb does it). */
+export function ensureOrbStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = ORB_CSS;
+    doc.head.appendChild(style);
+}
+/** What a readout shows for `value` of `max`. @internal */
+export function readoutText(mode, value, max, format) {
+    if (mode === 'none')
+        return '';
+    if (mode === 'percent')
+        return `${Math.round(max > 0 ? (value / max) * 100 : 0)}%`;
+    return format ? format(value, max) : String(Math.round(value));
+}
+/**
+ * The orb (see the module comment). `ui.meter({ shape: 'orb' })` and `createMeter(host, { shape:
+ * 'orb' })` come here; it returns the same `Meter` handle as the bar.
+ */
+export function createOrbMeter(host, opts = {}) {
+    const doc = host.layers.hud.ownerDocument;
+    ensureOrbStyles(doc);
+    let max = Math.max(0, opts.max ?? 1);
+    let value = Math.min(max, Math.max(0, opts.value ?? max));
+    const reduced = meterReducedMotion(host, opts);
+    const timings = trailTimings(opts, reduced);
+    const clock = timings ? new TrailClock(timings.delay, timings.duration, meterClock(opts)) : null;
+    const mode = opts.readout ?? 'value';
+    const fill = h('div', { class: 'tc-orb-fill' });
+    const trailEl = clock ? h('div', { class: 'tc-orb-trail' }) : null;
+    const readout = h('span', { class: 'tc-orb-readout', 'aria-hidden': 'true' });
+    const well = h('div', { class: 'tc-orb-well' }, trailEl, fill, h('div', { class: 'tc-orb-gloss' }));
+    const style = {};
+    if (opts.color)
+        style['--tc-meter-color'] = opts.color;
+    if (timings) {
+        style['--tc-orb-trail-delay'] = `${timings.delay}ms`;
+        style['--tc-orb-trail-duration'] = `${timings.duration}ms`;
+    }
+    const el = h('div', {
+        class: 'tc-orb',
+        role: 'meter',
+        'aria-label': opts.label,
+        'aria-valuemin': '0',
+        dataset: { tone: opts.tone ?? 'accent', shape: 'orb', ...(reduced ? { reduced: '' } : {}) },
+        style,
+    }, well, readout);
+    const frac = (v) => (max > 0 ? v / max : 0);
+    /** The band's timings were rewritten by a re-arm after a move (ws/ui-11). */
+    let rearmed = false;
+    const write = () => {
+        el.setAttribute('aria-valuenow', String(value));
+        el.setAttribute('aria-valuemax', String(max));
+        const f = frac(value);
+        el.style.setProperty('--tc-orb-value', String(f));
+        el.toggleAttribute('data-empty', f <= 0);
+        const text = readoutText(mode, value, max, opts.format);
+        if (readout.textContent !== text)
+            readout.textContent = text;
+        if (opts.format)
+            el.setAttribute('aria-valuetext', opts.format(value, max));
+        else if (mode === 'percent')
+            el.setAttribute('aria-valuetext', text);
+        if (clock && timings) {
+            if (rearmed) {
+                rearmed = false;
+                el.style.setProperty('--tc-orb-trail-delay', `${timings.delay}ms`);
+                el.style.setProperty('--tc-orb-trail-duration', `${timings.duration}ms`);
+            }
+            clock.retarget(f);
+            el.style.setProperty('--tc-orb-trail', String(f));
+        }
+    };
+    // The diameter in the current form factor (ws/ui-10): written now and on every re-layout,
+    // before the layout measures, so a content bar or rail sizes to it.
+    let size = opts.size;
+    let sized = '';
+    const writeSize = (ff) => {
+        const v = size === undefined ? '' : tpx(formSize(size, ff));
+        if (v === sized)
+            return false;
+        sized = v;
+        if (v)
+            el.style.setProperty('--tc-orb-size', v);
+        else
+            el.style.removeProperty('--tc-orb-size');
+        return true;
+    };
+    writeSize(host.layout.formFactor);
+    clock?.reset(frac(value));
+    if (trailEl)
+        el.style.setProperty('--tc-orb-trail', String(frac(value)));
+    write();
+    const handle = host.layout.add(el, {
+        place: meterPlace(opts.place, opts.region),
+        order: opts.order,
+        onForm: writeSize,
+        // A move cancels the band's transition: run the rest of it from where the model is.
+        onMove: () => {
+            if (clock && trailEl && rearmTrail(clock, trailEl, 'orb', el, el))
+                rearmed = true;
+        },
+    });
+    return {
+        el,
+        shape: 'orb',
+        get value() {
+            return value;
+        },
+        get max() {
+            return max;
+        },
+        get trail() {
+            // The band never shows under the fill, so a rising value reads as the value.
+            return clock ? Math.max(value, clock.at() * max) : value;
+        },
+        get size() {
+            return size ?? 128;
+        },
+        get region() {
+            return handle.region;
+        },
+        set(v, m) {
+            if (m !== undefined)
+                max = Math.max(0, m);
+            const next = Math.min(max, Math.max(0, v));
+            if (next === value && m === undefined)
+                return;
+            value = next;
+            write();
+        },
+        setTone(tone) {
+            el.dataset.tone = tone;
+        },
+        setColor(color) {
+            if (color)
+                el.style.setProperty('--tc-meter-color', color);
+            else
+                el.style.removeProperty('--tc-meter-color');
+        },
+        setSize(next) {
+            size = next;
+            if (writeSize(host.layout.formFactor))
+                host.layout.refresh();
+        },
+        setPlace(place) {
+            handle.setPlace(meterPlace(place, undefined));
+        },
+        remove() {
+            handle.remove();
+            el.remove();
+        },
+    };
+}