@energy8platform/shell 0.6.5 → 0.7.0

package/dist/index.esm.js

@@ -50,6 +50,240 @@ class EventEmitter {
     }
 }
 
+// AUTO-GENERATED from ../../icons.svg by scripts/gen-icons-from-svg.mjs — do not edit by hand.
+// Sharp monochrome icon set: each glyph is a 24×24 viewBox fragment using currentColor
+// (hollow shapes use fill-rule="evenodd"). Coordinates are baked into the 24×24 space (no
+// <g transform>), so the same fragment renders identically in the DOM <svg> and in Pixi's
+// GraphicsContext.svg. To change an icon: edit icons.svg, then run
+// `node scripts/gen-icons-from-svg.mjs`.
+// The single glyph-name union, shared by core (menu items) and both renderers.
+const ICON_NAMES = [
+    'spin',
+    'turbo1',
+    'autoplay',
+    'stop',
+    'menu',
+    'minus',
+    'plus',
+    'gift',
+    'info',
+    'soundOn',
+    'soundOff',
+    'close',
+    'back',
+    'chevronRight',
+    'ticket',
+    'turbo2',
+    'turboOff',
+    'chevronUp',
+    'chevronDown',
+];
+
+const PRESET_IDS = ['sound', 'music', 'sfx', 'gameInfo'];
+function isPresetId(id) {
+    return PRESET_IDS.includes(id);
+}
+/** The rows shown when `ShellConfig.menu` is omitted — today's Settings content, minus master. */
+const DEFAULT_MENU = [
+    { id: 'sound' },
+    { id: 'music' },
+    { id: 'sfx' },
+    { type: 'separator' },
+    { id: 'gameInfo' },
+];
+const isSeparator = (i) => i.type === 'separator';
+/** Range bounds with defaults: 0..1 like a volume slider, step = a twentieth of the span. */
+function rangeBounds(item) {
+    const min = item.min ?? 0;
+    const max = item.max ?? 1;
+    const derivedStep = (max - min) / 20;
+    // A declared `step` must be a genuinely positive number. `??` alone doesn't catch this: an
+    // explicit 0 (or a negative value) is not null/undefined, so it would sail through unchanged —
+    // and a renderer's position math divides by it (Pixi's fromUnit: `(raw-min)/step`), turning the
+    // slider's value into NaN, which then reaches `state.menu` and the `settingChange` payload.
+    const step = item.step != null && item.step > 0 ? item.step : derivedStep;
+    return { min, max, step };
+}
+/** Initial values for CUSTOM items (presets keep their own homes). Values already in `prev` win, so
+ *  a later `setMenu()` with the same ids does not reset what the player has changed. */
+function seedMenuValues(items, prev = {}) {
+    const out = {};
+    for (const item of items) {
+        if (isSeparator(item))
+            continue;
+        const type = item.type;
+        if (!type || isPresetId(item.id))
+            continue;
+        // A previous value only carries over when its runtime type still matches this item's kind.
+        // Without this guard, reconfiguring the same id from a toggle to a range (or back) would seed
+        // a boolean into a slider's position math (or a stale number into a checkbox) — a legitimate
+        // reconfiguration, not a config error, so it falls through to the item's own default instead
+        // of warning.
+        const prevValue = prev[item.id];
+        if (type === 'toggle') {
+            out[item.id] = typeof prevValue === 'boolean' ? prevValue : (item.value ?? false);
+        }
+        else if (type === 'range') {
+            const r = item;
+            out[item.id] = typeof prevValue === 'number' ? prevValue : (r.value ?? rangeBounds(r).min);
+        }
+    }
+    return out;
+}
+const percent = (v) => `${Math.round(v * 100)}%`;
+function safeIcon(name) {
+    return name && ICON_NAMES.includes(name) ? name : undefined;
+}
+/** Every drop/collision warning goes through here so the message style stays uniform. */
+function warn(message) {
+    console.warn(`[shell] ${message}`);
+}
+/** Expand the configured list into render-ready rows. A config mistake — an unknown preset id, an
+ *  unrecognized custom `type`, or an invalid range span — is dropped with one warning rather than
+ *  silently misbehaving: a typo must be visible, not silently invisible. A custom id that collides
+ *  with a reserved preset id also warns, but keeps its row (see `custom()`). */
+function resolveMenu(host) {
+    const rows = [];
+    for (const item of host.menu) {
+        if (isSeparator(item)) {
+            rows.push({ kind: 'separator' });
+            continue;
+        }
+        const type = item.type;
+        if (!type) {
+            const row = preset(host, item);
+            if (row)
+                rows.push(row);
+            else
+                warn(`unknown menu preset id "${item.id}" — item skipped`);
+            continue;
+        }
+        const row = custom(host, item, type);
+        if (row)
+            rows.push(row);
+    }
+    return rows;
+}
+function preset(host, item) {
+    const disabled = item.disabled ?? false;
+    const label = host.t(item.label ?? DEFAULT_LABELS[item.id] ?? item.id);
+    switch (item.id) {
+        case 'sound':
+            return {
+                kind: 'toggle',
+                id: 'sound',
+                label,
+                disabled,
+                icon: (v) => safeIcon(item.icon) ?? (v ? 'soundOn' : 'soundOff'),
+                get: () => host.getMenuValue('sound') !== false,
+                set: (v) => host.setMenuValue('sound', v),
+            };
+        case 'music':
+        case 'sfx': {
+            const id = item.id;
+            return {
+                kind: 'range',
+                id,
+                label,
+                icon: safeIcon(item.icon),
+                disabled,
+                min: 0,
+                max: 1,
+                step: 0.05,
+                get: () => Number(host.getMenuValue(id) ?? 1),
+                set: (v) => host.setMenuValue(id, v),
+                format: percent,
+            };
+        }
+        case 'gameInfo':
+            return {
+                kind: 'button',
+                id: 'gameInfo',
+                label,
+                icon: safeIcon(item.icon) ?? 'info',
+                disabled,
+                chevron: true,
+                select: () => host.actions.openInfo(),
+            };
+        default:
+            return null;
+    }
+}
+const DEFAULT_LABELS = {
+    sound: 'Sound',
+    music: 'Music',
+    sfx: 'SFX',
+    gameInfo: 'Game info',
+};
+function custom(host, item, type) {
+    // Same store, different semantics: the real preset's get() and a custom row's get() disagree
+    // (see the preset cases below vs. the toggle case here). Routing does not change — Task 4's
+    // ShellHost is what actually owns the value — this warning just makes the clash visible.
+    if (isPresetId(item.id)) {
+        warn(`menu item id "${item.id}" collides with a built-in preset id — preset ids are reserved`);
+    }
+    const disabled = item.disabled ?? false;
+    const label = host.t(item.label ?? item.id);
+    const icon = safeIcon(item.icon);
+    if (type === 'toggle') {
+        const it = item;
+        return {
+            kind: 'toggle',
+            id: it.id,
+            label,
+            disabled,
+            icon: () => icon,
+            get: () => host.getMenuValue(it.id) === true,
+            set: (v) => {
+                host.setMenuValue(it.id, v);
+                it.onChange?.(v);
+            },
+        };
+    }
+    if (type === 'range') {
+        const it = item;
+        const { min, max, step } = rangeBounds(it);
+        if (max <= min) {
+            // A renderer's position math ((value - min) / (max - min)) turns this into Infinity/NaN —
+            // drop the row instead, exactly like an unknown preset id.
+            warn(`menu item "${it.id}" has invalid range bounds (min ${min}, max ${max}) — item skipped`);
+            return null;
+        }
+        return {
+            kind: 'range',
+            id: it.id,
+            label,
+            icon,
+            disabled,
+            min,
+            max,
+            step,
+            get: () => Number(host.getMenuValue(it.id) ?? min),
+            set: (v) => {
+                host.setMenuValue(it.id, v);
+                it.onChange?.(v);
+            },
+            format: it.format ?? (min === 0 && max === 1 ? percent : (v) => String(v)),
+        };
+    }
+    if (type === 'button') {
+        const it = item;
+        return {
+            kind: 'button',
+            id: it.id,
+            label,
+            icon,
+            disabled,
+            chevron: it.chevron ?? false,
+            select: () => it.onSelect?.(),
+        };
+    }
+    // Neither toggle, range, nor button — a typo'd `type` used to fall through to an unconditional
+    // button row with no onSelect. Drop it visibly instead.
+    warn(`menu item "${item.id}" has unknown type "${type}" — item skipped`);
+    return null;
+}
+
 function createInitialState(config) {
     return {
         mode: config.mode,
@@ -66,10 +300,10 @@ function createInitialState(config) {
         bonus: null,
         activeFeature: null,
         volumes: {
-            master: clampVolume(config.volumes?.master),
             music: clampVolume(config.volumes?.music),
             sfx: clampVolume(config.volumes?.sfx),
         },
+        menu: seedMenuValues(config.menu ?? DEFAULT_MENU),
     };
 }
 /** Clamp a configured volume to 0..1, defaulting to full (1) when unset/invalid. */
@@ -1427,7 +1661,7 @@ class KeyboardController {
 
 // AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-const PACKAGE_VERSION = '0.6.5';
+const PACKAGE_VERSION = '0.7.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1445,6 +1679,7 @@ function resolveConfig(config) {
         theme: config.theme,
         onBonusBuy: config.onBonusBuy,
         volumes: config.volumes,
+        menu: config.menu,
         version: config.version ?? '1.0.0',
         isSocial: config.isSocial ?? false,
         replay: config.replay ?? config.mode === 'replay',
@@ -1465,8 +1700,9 @@ class ShellController extends EventEmitter {
     i18n;
     kbd;
     overlay = null;
-    soundRefresh = null;
-    volumeRefresh = null;
+    menuItems;
+    menuRefresh = null;
+    overlayKind = null;
     prevBalance;
     prevWin;
     destroyed = false;
@@ -1477,6 +1713,7 @@ class ShellController extends EventEmitter {
         this.config = resolveConfig(config);
         this.i18n = createI18n({ language: this.config.language, isSocial: this.config.isSocial });
         this.state = createInitialState(this.config);
+        this.menuItems = this.config.menu ?? DEFAULT_MENU;
         this.tokens = resolveTheme(this.config.theme);
         this.prevBalance = this.state.balance;
         this.prevWin = this.state.win;
@@ -1610,14 +1847,21 @@ class ShellController extends EventEmitter {
     show(req) {
         this.closeModal();
         this.overlay = this.renderer.openOverlay(req) ?? null;
+        this.overlayKind = this.overlay ? req.kind : null;
     }
+    /** Open the bar menu. Called again while it is open, it closes it — the burger toggles. */
     openMenu() {
+        if (this.overlayKind === 'menu') {
+            this.closeModal();
+            return;
+        }
         this.emit('menuOpen');
-        this.openSettings();
+        this.show({ kind: 'menu' });
     }
+    /** @deprecated The Settings overlay is gone — this opens the bar menu. */
     openSettings() {
         this.emit('settingsOpen');
-        this.show({ kind: 'settings' });
+        this.openMenu();
     }
     openInfo() {
         this.emit('infoOpen');
@@ -1649,35 +1893,72 @@ class ShellController extends EventEmitter {
         if (!this.overlay)
             return;
         this.overlay = null;
-        this.soundRefresh = null;
-        this.volumeRefresh = null;
+        this.overlayKind = null;
+        this.menuRefresh = null;
         this.renderer.closeOverlay();
     }
     // ── sound ──────────────────────────────────────────────────────────────────
     setSound(on) {
         this.soundOn = on;
         this.emit('settingChange', { key: 'sound', value: on });
-        this.soundRefresh?.(on);
-        this.renderer.refreshSoundIcon?.(on);
-    }
-    setSoundRefresh(fn) {
-        this.soundRefresh = fn;
+        this.menuRefresh?.('sound', on);
     }
     // ── volume ─────────────────────────────────────────────────────────────────
     getVolume(key) {
         return this.state.volumes[key];
     }
     /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
-     *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
-     *  live-updates the slider if the overlay is currently open. */
+     *  clamps, stores so a reopened menu popover reflects it, emits `settingChange`, and
+     *  live-updates the slider if the menu is currently open. */
     setVolume(key, value) {
         const v = Math.max(0, Math.min(1, value));
         this.state.volumes[key] = v;
         this.emit('settingChange', { key, value: v });
-        this.volumeRefresh?.(key, v);
+        this.menuRefresh?.(key, v);
+    }
+    // ── menu ───────────────────────────────────────────────────────────────────
+    get menu() {
+        return this.menuItems;
+    }
+    /** Replace the item list. Values of ids already in state are kept; new ids are seeded. */
+    setMenu(items) {
+        this.menuItems = items;
+        this.state.menu = seedMenuValues(items, this.state.menu);
+        if (this.overlayKind === 'menu')
+            this.show({ kind: 'menu' });
     }
-    setVolumeRefresh(fn) {
-        this.volumeRefresh = fn;
+    getMenuValue(id) {
+        if (id === 'sound')
+            return this.soundOn;
+        if (id === 'music' || id === 'sfx')
+            return this.state.volumes[id];
+        return this.state.menu[id];
+    }
+    /** Set a menu value. Presets route to their own homes so there is never a second copy. */
+    setMenuValue(id, value) {
+        if (id === 'sound') {
+            this.setSound(value !== false);
+            return;
+        }
+        if (id === 'music' || id === 'sfx') {
+            this.setVolume(id, Number(value));
+            return;
+        }
+        const next = typeof value === 'number' ? this.clampRange(id, value) : value;
+        this.state.menu[id] = next;
+        this.emit('settingChange', { key: id, value: next });
+        this.menuRefresh?.(id, next);
+    }
+    setMenuRefresh(fn) {
+        this.menuRefresh = fn;
+    }
+    /** Clamp to the declared bounds of a custom `range` item (a non-range id passes through). */
+    clampRange(id, value) {
+        const item = this.menuItems.find((i) => i.id === id);
+        if (!item || item.type !== 'range')
+            return value;
+        const { min, max } = rangeBounds(item);
+        return Math.max(min, Math.min(max, value));
     }
     // ── features ─────────────────────────────────────────────────────────────────
     activateFeature(bonus) {
@@ -1694,10 +1975,10 @@ class ShellController extends EventEmitter {
         this.renderer.renderBar();
     }
     // ── game-facing public API (mirrors GameShell/PixiGameShell) ───────────────────
-    money(field, from, to) {
+    money(field, from, to, durationMs) {
         this.renderer.renderBar();
         if (to !== from)
-            this.renderer.animateMoney(field, from, to);
+            this.renderer.animateMoney(field, from, to, durationMs);
     }
     setBalance(n) {
         const from = this.prevBalance;
@@ -1707,7 +1988,9 @@ class ShellController extends EventEmitter {
     }
     /** Set the WIN readout. Counts up/down from the previous value by default. Pass
      *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
-     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
+     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong.
+     *  `{ durationMs }` shortens/lengthens the count-up (default 450ms) — a scene reporting a win per
+     *  cascade step passes its step length so each count-up finishes before the next step lands. */
     setWin(n, opts) {
         const from = this.prevWin;
         this.state.win = n;
@@ -1716,7 +1999,7 @@ class ShellController extends EventEmitter {
             this.renderer.renderBar(); // instant repaint from state; cancels running money anims
             return;
         }
-        this.money('win', from, n);
+        this.money('win', from, n, opts?.durationMs);
     }
     setBet(n) {
         this.state.bet = n;
@@ -1785,6 +2068,11 @@ class ShellController extends EventEmitter {
         if (this.destroyed)
             return Promise.resolve();
         this.destroyed = true;
+        // With the menu (or any overlay) open at teardown, `menuRefresh` / `overlay` / `overlayKind`
+        // would otherwise survive the renderer's destroy — so a later setVolume()/setSound() call
+        // invokes a stale row updater against already-destroyed Pixi Graphics (or a detached DOM node)
+        // and throws. Run BEFORE the renderer teardown below, while it can still close cleanly.
+        this.closeModal();
         if (typeof document !== 'undefined') {
             this.kbd?.detach();
             document.removeEventListener('pointerdown', this.pullFocus, true);
@@ -1794,6 +2082,64 @@ class ShellController extends EventEmitter {
     }
 }
 
+/** Geometry for the bar-menu popover. Pure math over rectangles so the DOM and Pixi renderers
+ *  place it identically — the renderers only supply measured sizes and apply the result. */
+const POPOVER = {
+    /** Keep-out from the surface edges. */
+    margin: 8,
+    /** Space between the anchor and the card. */
+    gap: 8,
+    /** Minimum distance from the arrow tip to either rounded corner. */
+    arrowInset: 14,
+    /** A card shorter than this does not fit — flip to the other side instead. */
+    minH: 120,
+    minW: 220,
+    maxW: 320,
+};
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/** Card width: content width clamped to [minW, maxW] and never wider than the surface. */
+function popoverWidth(surfaceW, contentW) {
+    const hi = Math.min(POPOVER.maxW, surfaceW - POPOVER.margin * 2);
+    return Math.max(0, clamp(contentW, Math.min(POPOVER.minW, hi), hi));
+}
+/** Place the card above the `anchor` (below if it does not fit), left-aligned to it and clamped
+ *  inside the surface. `anchor === null` (no bar / hidden shell) centres it, arrow off.
+ *
+ *  `anchor` drives PLACEMENT (x, y, maxH, below) — normally the bar's whole plaque ("plate"), so the
+ *  card sits flush with the bar as a whole rather than with whichever control opened it. `pointer` is
+ *  the (optional) rect the ARROW points at — normally the burger button, which can sit anywhere
+ *  inside the plate. Defaults to `anchor` when omitted, so every caller that only ever had one rect
+ *  (i.e. every caller before `pointer` existed) keeps behaving exactly as it did before. */
+function placePopover(anchor, surface, size, pointer = null) {
+    const { margin, gap, arrowInset, minH } = POPOVER;
+    if (!anchor) {
+        const maxH = Math.max(0, surface.h - margin * 2);
+        const h = Math.min(size.h, maxH);
+        const rawY = (surface.h - h) / 2;
+        const y = clamp(rawY, margin, Math.max(margin, surface.h - h - margin));
+        return {
+            x: Math.max(margin, (surface.w - size.w) / 2),
+            y,
+            maxH,
+            arrowX: -1,
+            below: false,
+        };
+    }
+    const spaceAbove = anchor.y - gap - margin;
+    const spaceBelow = surface.h - (anchor.y + anchor.h) - gap - margin;
+    // Prefer above; flip only when the card would be squeezed below its usable minimum AND there is
+    // genuinely more room on the other side.
+    const below = spaceAbove < Math.min(size.h, minH) && spaceBelow > spaceAbove;
+    const maxH = Math.max(0, below ? spaceBelow : spaceAbove);
+    const h = Math.min(size.h, maxH);
+    const x = clamp(anchor.x, margin, Math.max(margin, surface.w - size.w - margin));
+    const rawY = below ? anchor.y + anchor.h + gap : anchor.y - gap - h;
+    const y = clamp(rawY, margin, Math.max(margin, surface.h - h - margin));
+    const arrowAnchor = pointer ?? anchor;
+    const arrowX = clamp(arrowAnchor.x + arrowAnchor.w / 2 - x, arrowInset, Math.max(arrowInset, size.w - arrowInset));
+    return { x, y, maxH, arrowX, below };
+}
+
 const NO_INSET = { top: 0, right: 0, bottom: 0, left: 0 };
 /** Create a shell with an explicit renderer instance (custom or a built-in HtmlRenderer/PixiRenderer).
  *  Built-in renderers also have the createGameShell/createPixiShell sugar in /html and /pixi.
@@ -1812,5 +2158,5 @@ function createShell(opts) {
     return controller;
 }
 
-export { DEFAULT_ACCENT, PACKAGE_VERSION, SCHEMES, ShellController, createI18n, createShell, normalizeLang, resolveConfig, resolveTheme, socialize };
+export { DEFAULT_ACCENT, DEFAULT_MENU, PACKAGE_VERSION, POPOVER, SCHEMES, ShellController, createI18n, createShell, isPresetId, normalizeLang, placePopover, popoverWidth, rangeBounds, resolveConfig, resolveMenu, resolveTheme, seedMenuValues, socialize };
 //# sourceMappingURL=index.esm.js.map