@energy8platform/shell 0.2.0

package/src/ui/pixi/primitives/flex.ts

@@ -0,0 +1,335 @@
+import { Container, Graphics, Rectangle } from 'pixi.js';
+
+// A focused flexbox for Pixi — just the slice of CSS flex the shell's CSS actually uses:
+// row/column, gap, padding, justify (start/center/end/space-between), align
+// (start/center/end/stretch), per-child grow + alignSelf, an optional rounded "plaque"
+// background, and fixed-or-content sizing. Enough to reproduce the DOM bar & overlays 1:1
+// without pulling in a Yoga dependency.
+
+export type FlexDir = 'row' | 'column';
+export type Justify = 'start' | 'center' | 'end' | 'space-between';
+export type Align = 'start' | 'center' | 'end' | 'stretch';
+
+export interface Padding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+export interface BgStyle {
+  fill?: string;
+  radius?: number;
+  /** per-corner radii [tl, tr, br, bl] override `radius`. */
+  corners?: [number, number, number, number];
+  stroke?: { color: string; width: number };
+}
+
+export interface FlexOpts {
+  direction?: FlexDir;
+  gap?: number;
+  padding?: number | Padding;
+  justify?: Justify;
+  align?: Align;
+  background?: BgStyle;
+  /** Fixed outer size; omit a dimension for content sizing. */
+  width?: number;
+  height?: number;
+  /** Minimum outer height — content shorter than this is centred in the taller box (the DOM rows'
+   *  effective min height from the tallest child's line box). */
+  minHeight?: number;
+}
+
+export interface ChildOpts {
+  grow?: number;
+  alignSelf?: Align;
+}
+
+interface Entry {
+  node: Container;
+  grow: number;
+  alignSelf?: Align;
+}
+
+/** Anything that can be measured + sized by the layout (FlexBox and stretchable widgets). */
+export interface Sizable {
+  setLayoutSize(w: number | undefined, h: number | undefined): void;
+  measureSize(): { w: number; h: number };
+}
+
+function isSizable(n: unknown): n is Sizable {
+  return !!n && typeof (n as Sizable).measureSize === 'function' && typeof (n as Sizable).setLayoutSize === 'function';
+}
+
+/** Zero offset for Sizable widgets, which own a 0,0,w,h box (no getLocalBounds adjustment). */
+const ORIGIN = { x: 0, y: 0 };
+
+/** Local bounds of a node, used when it isn't a Sizable. */
+function rawSize(node: Container): { w: number; h: number } {
+  const b = node.getLocalBounds();
+  return { w: b.width, h: b.height };
+}
+
+function measureOuter(node: Container): { w: number; h: number } {
+  return isSizable(node) ? node.measureSize() : rawSize(node);
+}
+
+function pad(p: number | Padding | undefined): Required<Padding> {
+  if (p == null) return { top: 0, right: 0, bottom: 0, left: 0 };
+  if (typeof p === 'number') return { top: p, right: p, bottom: p, left: p };
+  return { top: p.top ?? 0, right: p.right ?? 0, bottom: p.bottom ?? 0, left: p.left ?? 0 };
+}
+
+export class FlexBox extends Container implements Sizable {
+  private dir: FlexDir;
+  private gap: number;
+  private padding: Required<Padding>;
+  private justify: Justify;
+  private align: Align;
+  private bgStyle?: BgStyle;
+  private bg?: Graphics;
+  private entries: Entry[] = [];
+  private fixedW?: number;
+  private fixedH?: number;
+  private minH?: number;
+  /** last computed outer size. */
+  private outW = 0;
+  private outH = 0;
+
+  constructor(opts: FlexOpts = {}) {
+    super();
+    this.dir = opts.direction ?? 'row';
+    this.gap = opts.gap ?? 0;
+    this.padding = pad(opts.padding);
+    this.justify = opts.justify ?? 'start';
+    this.align = opts.align ?? 'start';
+    this.bgStyle = opts.background;
+    this.fixedW = opts.width;
+    this.fixedH = opts.height;
+    this.minH = opts.minHeight;
+    if (this.bgStyle) {
+      this.bg = new Graphics();
+      this.addChild(this.bg);
+    }
+  }
+
+  add(node: Container, opts: ChildOpts = {}): this {
+    this.entries.push({ node, grow: opts.grow ?? 0, alignSelf: opts.alignSelf });
+    this.addChild(node);
+    return this;
+  }
+
+  addAll(nodes: Container[]): this {
+    for (const n of nodes) this.add(n);
+    return this;
+  }
+
+  clearChildren(): void {
+    for (const e of this.entries) {
+      this.removeChild(e.node);
+      e.node.destroy({ children: true });
+    }
+    this.entries = [];
+  }
+
+  setBackground(bg: BgStyle | undefined): void {
+    this.bgStyle = bg;
+    if (bg && !this.bg) {
+      this.bg = new Graphics();
+      this.addChildAt(this.bg, 0);
+    }
+    if (!bg && this.bg) {
+      this.bg.clear();
+    }
+  }
+
+  /** Recolour the background fill in place (e.g. a row's hover state) without a relayout. */
+  setBgFill(fill: string): void {
+    if (this.bgStyle) {
+      this.bgStyle.fill = fill;
+      this.drawBackground();
+    }
+  }
+
+  /** Make the whole box a button target. A FlexBox otherwise only hit-tests its children, so a row
+   *  used as a button (settings "Game info") was clickable/hoverable only over its icon/label, not
+   *  the padding or gaps. This maintains a hit area covering the full box across relayouts. */
+  private fullHit = false;
+  setInteractive(on = true): this {
+    this.fullHit = on;
+    this.eventMode = on ? 'static' : 'auto';
+    this.cursor = on ? 'pointer' : 'default';
+    this.updateHit();
+    return this;
+  }
+  private updateHit(): void {
+    if (this.fullHit) this.hitArea = new Rectangle(0, 0, this.outW, this.outH);
+  }
+
+  // ── Sizable ──────────────────────────────────────────────────────────────
+  setLayoutSize(w: number | undefined, h: number | undefined): void {
+    this.fixedW = w;
+    this.fixedH = h;
+    this.layout();
+  }
+
+  measureSize(): { w: number; h: number } {
+    this.layout();
+    return { w: this.outW, h: this.outH };
+  }
+
+  get outerWidth(): number {
+    return this.outW;
+  }
+  get outerHeight(): number {
+    return this.outH;
+  }
+  /** The width this box would take from its content alone (ignoring a fixed width) — used to
+   *  detect overflow inside a fixed-width plaque (the mobile bar's fit-scale). */
+  get naturalWidth(): number {
+    return this.natW;
+  }
+  private natW = 0;
+
+  /** Measure + position children. Idempotent. */
+  layout(): void {
+    const horizontal = this.dir === 'row';
+    const px = this.padding;
+    const padMainStart = horizontal ? px.left : px.top;
+    const padMainEnd = horizontal ? px.right : px.bottom;
+    const padCrossStart = horizontal ? px.top : px.left;
+    const padCrossEnd = horizontal ? px.bottom : px.right;
+
+    // Measure each child's outer size.
+    const sizes = this.entries.map((e) => measureOuter(e.node));
+
+    const contentMain = sizes.reduce((s, m) => s + (horizontal ? m.w : m.h), 0)
+      + this.gap * Math.max(0, this.entries.length - 1);
+    const contentCross = sizes.reduce((mx, m) => Math.max(mx, horizontal ? m.h : m.w), 0);
+    // natural width = content + horizontal padding, regardless of any imposed fixed width
+    this.natW = horizontal
+      ? contentMain + padMainStart + padMainEnd
+      : contentCross + padCrossStart + padCrossEnd;
+
+    const fixedMain = horizontal ? this.fixedW : this.fixedH;
+    const fixedCross = horizontal ? this.fixedH : this.fixedW;
+
+    let outerMain = fixedMain ?? contentMain + padMainStart + padMainEnd;
+    let outerCross = fixedCross ?? contentCross + padCrossStart + padCrossEnd;
+    // minHeight raises the box on whichever axis is vertical (cross for a row, main for a column).
+    if (this.minH != null) {
+      if (horizontal) outerCross = Math.max(outerCross, this.minH);
+      else outerMain = Math.max(outerMain, this.minH);
+    }
+    const innerMain = outerMain - padMainStart - padMainEnd;
+    const innerCross = outerCross - padCrossStart - padCrossEnd;
+
+    // Distribute free main-space to growers (or, when none grow, to justify spacing).
+    const totalGrow = this.entries.reduce((s, e) => s + e.grow, 0);
+    let free = innerMain - contentMain;
+    if (free < 0) free = 0;
+    const growUnit = totalGrow > 0 ? free / totalGrow : 0;
+
+    // Apply grow to child main sizes (stretch growers) and cross stretch.
+    this.entries.forEach((e, i) => {
+      const m = sizes[i];
+      if (e.grow > 0 && growUnit > 0 && isSizable(e.node)) {
+        const newMain = (horizontal ? m.w : m.h) + e.grow * growUnit;
+        if (horizontal) {
+          e.node.setLayoutSize(newMain, undefined);
+          sizes[i] = e.node.measureSize();
+        } else {
+          e.node.setLayoutSize(undefined, newMain);
+          sizes[i] = e.node.measureSize();
+        }
+      }
+      const a = e.alignSelf ?? this.align;
+      if (a === 'stretch' && isSizable(e.node)) {
+        if (horizontal) {
+          e.node.setLayoutSize(sizes[i].w, innerCross);
+          sizes[i] = e.node.measureSize();
+        } else {
+          e.node.setLayoutSize(innerCross, sizes[i].h);
+          sizes[i] = e.node.measureSize();
+        }
+      }
+    });
+
+    const usedMain = sizes.reduce((s, m) => s + (horizontal ? m.w : m.h), 0)
+      + this.gap * Math.max(0, this.entries.length - 1);
+    const leftover = innerMain - usedMain;
+
+    // Justify: leading offset + per-item spacing.
+    let cursor = (horizontal ? px.left : px.top);
+    let spacing = this.gap;
+    if (totalGrow === 0) {
+      if (this.justify === 'center') cursor += leftover / 2;
+      else if (this.justify === 'end') cursor += leftover;
+      else if (this.justify === 'space-between' && this.entries.length > 1) {
+        spacing = this.gap + leftover / (this.entries.length - 1);
+      }
+    }
+
+    this.entries.forEach((e, i) => {
+      const m = sizes[i];
+      const childMain = horizontal ? m.w : m.h;
+      const childCross = horizontal ? m.h : m.w;
+      const a = e.alignSelf ?? this.align;
+      let crossPos = padCrossStart;
+      if (a === 'center') crossPos += (innerCross - childCross) / 2;
+      else if (a === 'end') crossPos += innerCross - childCross;
+      // For raw content (Text/Graphics/icon) whose visible bounds don't start at (0,0), offset so
+      // the content lands on the slot. Sizable widgets define their own 0,0,w,h box (their glyph is
+      // already centred inside it), so offsetting by getLocalBounds would double-count and shift
+      // them (icons drifted up). Position those by the box origin instead.
+      const b = isSizable(e.node) ? ORIGIN : e.node.getLocalBounds();
+      if (horizontal) {
+        e.node.position.set(cursor - b.x, crossPos - b.y);
+      } else {
+        e.node.position.set(crossPos - b.x, cursor - b.y);
+      }
+      cursor += childMain + spacing;
+    });
+
+    this.outW = horizontal ? outerMain : outerCross;
+    this.outH = horizontal ? outerCross : outerMain;
+
+    this.drawBackground();
+    this.updateHit();
+  }
+
+  private drawBackground(): void {
+    if (!this.bgStyle || !this.bg) return;
+    const g = this.bg;
+    g.clear();
+    const r = this.bgStyle.corners;
+    if (r) {
+      roundedPath(g, 0, 0, this.outW, this.outH, r);
+    } else {
+      g.roundRect(0, 0, this.outW, this.outH, this.bgStyle.radius ?? 0);
+    }
+    if (this.bgStyle.fill) g.fill(this.bgStyle.fill);
+    if (this.bgStyle.stroke) g.stroke({ color: this.bgStyle.stroke.color, width: this.bgStyle.stroke.width });
+  }
+}
+
+/** Rounded rect with independent corner radii [tl, tr, br, bl] — Pixi's roundRect is uniform. */
+export function roundedPath(
+  g: Graphics,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  [tl, tr, br, bl]: [number, number, number, number],
+): void {
+  g.moveTo(x + tl, y);
+  g.lineTo(x + w - tr, y);
+  g.arcTo(x + w, y, x + w, y + tr, tr);
+  g.lineTo(x + w, y + h - br);
+  g.arcTo(x + w, y + h, x + w - br, y + h, br);
+  g.lineTo(x + bl, y + h);
+  g.arcTo(x, y + h, x, y + h - bl, bl);
+  g.lineTo(x, y + tl);
+  g.arcTo(x, y, x + tl, y, tl);
+  g.closePath();
+}

package/src/ui/pixi/primitives/overlay.ts

@@ -0,0 +1,181 @@
+import { Container, Graphics, Rectangle } from 'pixi.js';
+import type { PixiComponentContext, ShellLayer } from '../context';
+import { makeIcon } from '../pixi-icon';
+import { makeText } from '../text';
+import { attachHover, attachPress } from './widgets';
+import { ScrollBox } from './scroll';
+import { FlexBox } from './flex';
+
+export function clamp(min: number, pref: number, max: number): number {
+  return Math.max(min, Math.min(max, pref));
+}
+
+/** Small rounded icon nav button — the overlay header back/close and row chevrons.
+ *  `.ge-ov-nav`: 32×32, radius 9, plaque-dark bg, white icon, hover → glass bg + accent icon. */
+export function navButton(host: PixiComponentContext, iconName: 'close' | 'back', onTap: () => void, size = 32): Container {
+  const root = new Container();
+  const bg = new Graphics();
+  const draw = (hover: boolean): void => {
+    bg.clear();
+    bg.roundRect(0, 0, size, size, 9);
+    bg.fill(hover ? host.tokens.plaqueGlass : host.tokens.plaqueDark);
+  };
+  draw(false);
+  const gs = Math.round(size * 0.5625); // glyph tracks the box (default 32 → 18, unchanged)
+  const glyph = makeIcon(iconName, gs, '#ffffff');
+  glyph.position.set((size - gs) / 2, (size - gs) / 2);
+  root.addChild(bg, glyph);
+  root.eventMode = 'static';
+  root.cursor = 'pointer';
+  root.hitArea = new Rectangle(0, 0, size, size);
+  attachHover(root, () => {
+    draw(true);
+    glyph.setColor(host.tokens.accent);
+  }, () => {
+    draw(false);
+    glyph.setColor('#ffffff');
+  });
+  attachPress(root, 0.92, onTap);
+  return root;
+}
+
+export interface OverlayOpts {
+  title: string;
+  onClose: () => void;
+  onBack?: () => void;
+  /** Build the scrolling body content for a given inner width (a Sizable column). */
+  build: (bodyWidth: number) => Container;
+  /** dataset-style tag for debugging/tests. */
+  tag?: string;
+}
+
+/** Full-screen overlay: frosted dark veil, fixed header (title + back/close), scrolling body.
+ *  The body is rebuilt on resize so it reflows like the CSS overlay. */
+export class Overlay extends Container implements ShellLayer {
+  readonly tag?: string;
+  private host: PixiComponentContext;
+  private opts: OverlayOpts;
+  private veil = new Graphics();
+  private header = new Container();
+  private scroll: ScrollBox;
+  private titleNode = new Container();
+  private nav = new Container();
+  private w = 0;
+  private h = 0;
+  private headerH = 44;
+
+  /** Expose the scroll box for keyboard/test access. */
+  get scrollContent(): ScrollBox { return this.scroll; }
+
+  constructor(host: PixiComponentContext, opts: OverlayOpts) {
+    super();
+    this.host = host;
+    this.opts = opts;
+    this.tag = opts.tag;
+    this.scroll = new ScrollBox(host.canvas);
+    this.addChild(this.veil, this.scroll, this.header);
+    this.veil.eventMode = 'static'; // swallow clicks to the game behind
+    this.resize(host.screenW, host.screenH);
+  }
+
+  resize(w: number, h: number): void {
+    this.w = w;
+    this.h = h;
+    const vh = h / 100;
+    this.headerH = clamp(40, 6.4 * vh, 52);
+
+    // veil
+    this.veil.clear();
+    this.veil.rect(0, 0, w, h);
+    this.veil.fill(this.host.tokens.backdrop);
+    this.veil.hitArea = new Rectangle(0, 0, w, h);
+
+    this.buildHeader();
+    this.layoutBody();
+  }
+
+  private buildHeader(): void {
+    this.header.removeChildren().forEach((c) => c.destroy({ children: true }));
+    const pad = 10;
+    // back or spacer (left), centred title, close (right)
+    const left = this.opts.onBack
+      ? navButton(this.host, 'back', () => this.opts.onBack!())
+      : new Container();
+    const close = navButton(this.host, 'close', () => this.opts.onClose());
+    const titleSize = clamp(13, 2.6 * (this.h / 100), 16);
+    const title = makeText(this.opts.title, {
+      size: titleSize,
+      weight: '800',
+      color: '#ffffff',
+      letterSpacing: titleSize * 0.04,
+      upper: true,
+      align: 'center',
+    });
+    title.anchor.set(0.5);
+    title.position.set(this.w / 2, this.headerH / 2 + pad / 2);
+    left.position.set(pad, (this.headerH - 32) / 2 + pad / 2);
+    close.position.set(this.w - 32 - pad, (this.headerH - 32) / 2 + pad / 2);
+    this.header.addChild(title, left, close);
+  }
+
+  private layoutBody(): void {
+    const top = this.headerH + 6;
+    const sidePad = clamp(16, 4 * (this.w / 100), 24);
+    const vPad = clamp(6, 2 * (this.h / 100), 16);
+    const bodyW = Math.min(800, this.w - sidePad * 2);
+
+    this.scroll.position.set(0, top);
+    this.scroll.setViewport(this.w, this.h - top);
+    this.scroll.content.removeChildren().forEach((c) => c.destroy({ children: true }));
+
+    const content = this.opts.build(bodyW);
+    if (content instanceof FlexBox) content.setLayoutSize(bodyW, undefined);
+    content.position.set((this.w - bodyW) / 2, vPad);
+    this.scroll.content.addChild(content);
+    this.scroll.refresh();
+  }
+
+  /** Handle keyboard navigation while this overlay is the top layer. */
+  onKey(e: KeyboardEvent): boolean {
+    const viewH = this.h - (this.headerH + 6); // body viewport height
+    const lineStep = 60;
+    const pageStep = Math.floor(viewH * 0.9);
+    switch (e.code) {
+      case 'ArrowDown':
+        this.scroll.scrollBy(lineStep);
+        return true;
+      case 'ArrowUp':
+        this.scroll.scrollBy(-lineStep);
+        return true;
+      case 'PageDown':
+        this.scroll.scrollBy(pageStep);
+        return true;
+      case 'PageUp':
+        this.scroll.scrollBy(-pageStep);
+        return true;
+      case 'Space':
+        if (e.shiftKey) {
+          this.scroll.scrollBy(-pageStep);
+        } else {
+          this.scroll.scrollBy(pageStep);
+        }
+        return true;
+      case 'Home':
+        this.scroll.scrollBy(-999999);
+        return true;
+      case 'End':
+        this.scroll.scrollBy(999999);
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  fit(): void {
+    /* overlays scroll; no card fit needed */
+  }
+
+  onRemove(): void {
+    this.scroll.destroy({ children: true });
+  }
+}

package/src/ui/pixi/primitives/scroll.ts

@@ -0,0 +1,117 @@
+import { Container, Graphics, Rectangle, type FederatedPointerEvent } from 'pixi.js';
+
+/** A vertically-scrolling viewport — mask + drag + mouse-wheel, the Pixi analogue of the
+ *  overlay's `overflow-y:auto` scroll region. Add content to `.content`; call `refresh()`
+ *  after content changes or a resize. */
+export class ScrollBox extends Container {
+  readonly content = new Container();
+  private maskG = new Graphics();
+  private viewW = 0;
+  private viewH = 0;
+  private scrollY = 0;
+  private maxScroll = 0;
+  private dragging = false;
+  private lastY = 0;
+  private moved = false;
+  private canvas?: HTMLCanvasElement;
+  private wheelHandler?: (e: WheelEvent) => void;
+
+  constructor(canvas?: HTMLCanvasElement) {
+    super();
+    this.canvas = canvas;
+    this.addChild(this.content);
+    // maskG is added to the scene only while scrolling (see refresh) — a leftover unused mask
+    // graphic renders as a white rect, and a masked container blocks pointer events to its children.
+    this.eventMode = 'static';
+    this.on('pointerdown', this.onDown);
+    this.on('globalpointermove', this.onMove);
+    this.on('pointerup', this.onUp);
+    this.on('pointerupoutside', this.onUp);
+    if (this.canvas) {
+      this.wheelHandler = (e: WheelEvent) => {
+        // Always swallow the wheel while this scroll region is mounted (a modal is open) so the
+        // gesture never chains to the parent page — on Stake the game is in an iframe and an
+        // un-prevented wheel scrolls the host page. Still scroll our content when it overflows.
+        e.preventDefault();
+        if (this.maxScroll > 0) this.setScroll(this.scrollY + e.deltaY);
+      };
+      this.canvas.addEventListener('wheel', this.wheelHandler, { passive: false });
+    }
+  }
+
+  setViewport(w: number, h: number): void {
+    this.viewW = w;
+    this.viewH = h;
+    this.maskG.clear();
+    this.maskG.rect(0, 0, w, h);
+    this.maskG.fill(0xffffff);
+    this.refresh();
+  }
+
+  /** Re-measure content height, clamp the scroll, and clip only when it overflows. */
+  refresh(): void {
+    this.content.mask = null; // measure unmasked (a mask clips getLocalBounds to the viewport)
+    if (this.maskG.parent) this.removeChild(this.maskG);
+    const b = this.content.getLocalBounds();
+    const contentH = b.height + b.y; // content laid out from y≈0 downward
+    this.maxScroll = Math.max(0, contentH - this.viewH);
+    // Only clip + grab pointer/drag when the content actually overflows: a masked container blocks
+    // pointer events to its children in Pixi v8, so when it fits we leave it unmasked and passive →
+    // interactive controls (settings sliders/buttons) work. Tall scrolling content (game info) that
+    // does get masked has no interactive children, so nothing is lost there.
+    const scrollable = this.maxScroll > 0;
+    if (scrollable) {
+      this.addChild(this.maskG);
+      this.content.mask = this.maskG;
+      this.hitArea = new Rectangle(0, 0, this.viewW, this.viewH);
+    } else {
+      this.hitArea = null;
+    }
+    this.eventMode = scrollable ? 'static' : 'passive';
+    this.setScroll(this.scrollY);
+  }
+
+  /** Max scrollable distance (0 when content fits) — exposed for tests. */
+  get maxScrollY(): number {
+    return this.maxScroll;
+  }
+
+  /** Scroll by `dy` pixels (positive = down, negative = up), clamped to [0, maxScroll]. */
+  scrollBy(dy: number): void {
+    this.setScroll(this.scrollY + dy);
+  }
+
+  private setScroll(y: number): void {
+    this.scrollY = Math.max(0, Math.min(this.maxScroll, y)) || 0; // || 0 converts -0 to 0
+    this.content.y = this.scrollY === 0 ? 0 : -this.scrollY;
+  }
+
+  private onDown = (e: FederatedPointerEvent): void => {
+    this.dragging = true;
+    this.moved = false;
+    this.lastY = e.global.y;
+  };
+  private onMove = (e: FederatedPointerEvent): void => {
+    if (!this.dragging) return;
+    const dy = e.global.y - this.lastY;
+    if (Math.abs(dy) > 2) this.moved = true;
+    this.lastY = e.global.y;
+    if (this.maxScroll > 0) this.setScroll(this.scrollY - dy);
+  };
+  private onUp = (): void => {
+    this.dragging = false;
+  };
+
+  /** True if the last pointer sequence was a drag (so a tap handler can ignore it). */
+  get didDrag(): boolean {
+    return this.moved;
+  }
+
+  destroy(options?: Parameters<Container['destroy']>[0]): void {
+    if (this.canvas && this.wheelHandler) {
+      this.canvas.removeEventListener('wheel', this.wheelHandler);
+      this.wheelHandler = undefined;
+    }
+    super.destroy(options);
+  }
+}