@open-slot-ui/pixi 0.4.1 → 0.5.0

package/dist/OpenUIPixi-D4Z7emFO.d.cts

@@ -0,0 +1,202 @@
+import * as pixi_js from 'pixi.js';
+import { Container, Ticker, Texture, Application } from 'pixi.js';
+import { Theme, Control, OpenUI, ScreenState, BlockSpec, EventLog } from '@open-slot-ui/core';
+
+/**
+ * A skin owns a control's *look* and nothing else. The view drives it with the
+ * current state name; the skin swaps art accordingly. This is the seam where a
+ * game's design (Graphics, SVG, Spine, …) plugs in without touching control logic.
+ */
+interface SpinSkin {
+    /** The display object the view adds into its animated `art` container. */
+    readonly view: Container;
+    /** React to a state change (swap art, recolor, etc.). */
+    update(state: string): void;
+    destroy(): void;
+}
+type SpinSkinFactory = (theme: Theme) => SpinSkin;
+
+/**
+ * Base view: a Pixi Container bound to a core Control. Owns layout placement and
+ * registers the introspection hook so the core can report bounds/animation state.
+ * Subclasses draw and wire input. Dumb on its own (Charter B3).
+ */
+declare abstract class ControlView extends Container {
+    protected readonly control: Control;
+    protected readonly ui: OpenUI;
+    protected animating: boolean;
+    protected readonly disposers: Array<() => void>;
+    constructor(control: Control, ui: OpenUI);
+    /** Position + fit-scale from the control's layout spec against the screen. */
+    applyLayout(screen: ScreenState): void;
+    private computeRect;
+    dispose(): void;
+}
+
+/** Per-id view override — swap a control's renderer without forking (Charter P7). */
+type ControlViewFactory = (control: Control, ui: OpenUI, ticker: Ticker) => ControlView;
+interface BlockColumnOptions {
+    controlSkins?: Partial<Record<string, ControlViewFactory>>;
+    /** Unclipped layer for select dropdowns (so a scroll mask doesn't clip them). */
+    dropdownLayer?: Container;
+}
+interface BlockColumn {
+    /** Rows laid top→down (first row near y=0); the caller positions/scrolls it. */
+    content: Container;
+    /** Interactive child views, for disposal. */
+    views: ControlView[];
+    /** Total column height. */
+    height: number;
+    /** Inner content width (body width minus padding). */
+    innerW: number;
+}
+/**
+ * Render a declarative `BlockSpec[]` into a column of rows — interactive controls
+ * (slider/toggle/button/select/value/stepper) and static content (heading/text/
+ * callout/stat-grid/steps/paytable/image). All text flows through `ui.t`. This is
+ * the single renderer shared by the small panel body AND the scrollable menu, so
+ * blocks look identical wherever they appear (Charter B3/B9).
+ */
+declare function buildBlockColumn(blocks: BlockSpec[], controls: Control[], ui: OpenUI, ticker: Ticker, bodyW: number, opts?: BlockColumnOptions): BlockColumn;
+
+interface CellRenderer<C extends Container = Container> {
+    createCell(digit: number): C;
+    setDigit(cell: C, digit: number): void;
+    setFiller(cell: C, digit: number): void;
+    createSeparator?(char: string): Container;
+    destroyCell?(cell: C): void;
+}
+/**
+ * Minimal GSAP-compatible API the Counter uses for `fit` animation.
+ * Passing the default `gsap` import satisfies this shape — no need for type imports.
+ */
+interface GsapLike {
+    to(target: object, vars: Record<string, unknown>): unknown;
+    killTweensOf(target: object): void;
+}
+
+interface OpenUIIcons {
+    settingsIdle?: Texture;
+    settingsActive?: Texture;
+    close?: Texture;
+    rules?: Texture;
+    sliderMusic?: Texture;
+    sliderSound?: Texture;
+    turboOff?: Texture;
+    turboOn?: Texture;
+    /** One texture per turbo mode (index-aligned) — for 3-mode art. Wins over off/on. */
+    turboModes?: Texture[];
+    autoIdle?: Texture;
+    autoActive?: Texture;
+    bonus?: Texture;
+    betPlus?: Texture;
+    betMinus?: Texture;
+}
+interface OpenUIPixiOptions {
+    /** Expose `window.__OPENUI__` for e2e/introspection. Default true. */
+    expose?: boolean;
+    /** Override the spin control's skin (default = the art-free Graphics placeholder). */
+    spinSkin?: SpinSkinFactory;
+    /** Real art for the menu/close/slider controls (else neutral placeholders). */
+    icons?: OpenUIIcons;
+    /**
+     * The composed MENU blocks (Settings → Paytable → Rules) the ☰ button opens in a
+     * scrollable sheet. Usually built by `mountHud` via `composeMenu(spec.menu, …)`;
+     * omitted → a default Settings-only menu (Music/Sound). Pass `false` to skip the
+     * built-in Pixi menu entirely (e.g. when supplying your own HTML/DOM menu).
+     */
+    menu?: BlockSpec[] | false;
+    /** Header title for the menu sheet (localizable). Default 'Menu'. */
+    menuTitle?: string;
+    /** Per-id view override — swap a control's renderer without forking (Charter P7). */
+    controlSkins?: Partial<Record<string, ControlViewFactory>>;
+    /**
+     * Host `gsap` — enables the value counter's auto-downscale so wide currencies
+     * (8-decimal BTC, big SATS counts, long codes) shrink to fit instead of spilling.
+     * Kept out of the lib's deps (Charter B5); the host passes its own gsap.
+     */
+    gsap?: GsapLike;
+    /**
+     * Autoplay count-picker presentation. `'drawer'` (default) is a bottom sheet;
+     * `'radial'` fans the count chips around the spin button.
+     */
+    autoplayPicker?: 'drawer' | 'radial';
+    /**
+     * Text colour for the top-corner compliance readouts (RTP / net / session). Defaults
+     * to the theme text colour; a light-background host can pass a dark colour so the
+     * Figma-style `Label: value` block stays legible.
+     */
+    readoutColor?: string;
+    /**
+     * How the interactive HUD appears on mount: `'shown'` (default), `'hidden'` (off
+     * screen + non-interactive; reveal later with `showControls()`), or `'slide-in'`
+     * (start hidden, then slide in from the edges).
+     */
+    intro?: 'shown' | 'hidden' | 'slide-in';
+}
+/**
+ * The controller: mounts ONE root Container onto the host's existing stage,
+ * shares the host ticker/renderer, drives resize, and exposes introspection.
+ * `unmount()` removes the layer and every listener it created (Charter P2/P12).
+ */
+declare class OpenUIPixi {
+    private readonly ui;
+    private readonly opts;
+    readonly root: Container<pixi_js.ContainerChild>;
+    private readonly views;
+    /** Full-screen overlays (e.g. the autoplay drawer) that own their own layout. */
+    private readonly overlays;
+    private readonly disposers;
+    private _eventLog?;
+    /** Show/hide slide: each interactive view slides toward its anchored edge (bottom
+     *  controls down, top up — behind the status-bar plaque). Views stay direct children
+     *  of `root` (introspection bounds unchanged); only their y moves, and the
+     *  ref-counted input lock makes them non-interactive while moving/hidden. */
+    private slideProg;
+    private slideTarget;
+    private slideHeld;
+    private lastScreenH;
+    private appTicker?;
+    private slideTickFn?;
+    private readonly slideBaseY;
+    private readonly slideSign;
+    /** Buy-feature ⇄ total-win swap: only one shows at a time (see `setupBonusSwap`). */
+    private bonusView?;
+    private totalWinView?;
+    private readonly fadeFns;
+    constructor(ui: OpenUI, opts?: OpenUIPixiOptions);
+    /** The bus event log backing `window.__OPENUI__.events` (available after mount). */
+    get eventLog(): EventLog | undefined;
+    mount(app: Application): void;
+    /**
+     * Wire the buy-feature ⇄ total-win swap. In base play the buy button shows (unless
+     * hidden by config/jurisdiction); once the spin button enters free-spins mode
+     * (`setFreeSpins(n > 0)` — you "can't buy" mid-bonus) the buy button fades out and
+     * the localized total-win counter fades in over the same slot, then back on exit.
+     */
+    private setupBonusSwap;
+    /** Fade a view's alpha to `to` over `ms` (wall-clock paced); cancels any prior fade
+     *  on the same view. `onDone` runs once when it settles. */
+    private fadeTo;
+    /** Cancel an in-flight fade on `view` (if any). */
+    private stopFade;
+    /**
+     * Build the unified scrollable MENU bound to the ☰ panel. Composed `menu` blocks
+     * are given by `mountHud`; absent → a default Settings-only menu. Built-in ids
+     * ('music'/'sfx') are reused, not shadowed (P10); button blocks wire `closePanel`.
+     */
+    private buildMenu;
+    /**
+     * Slide the whole interactive HUD in (`true`) or out (`false`): bottom-anchored
+     * controls travel down, top-anchored travel up (behind the status-bar plaque).
+     * Pure translation (no scaling); controls are non-interactive while moving/hidden.
+     */
+    setControlsVisible(visible: boolean): void;
+    /** Apply the current slide progress: translate each interactive view toward its
+     *  anchored edge (pure translation — no scaling). */
+    private applySlide;
+    unmount(): void;
+    private expose;
+}
+
+export { type BlockColumn as B, ControlView as C, type GsapLike as G, type OpenUIIcons as O, type SpinSkinFactory as S, type ControlViewFactory as a, OpenUIPixi as b, type OpenUIPixiOptions as c, type CellRenderer as d, type SpinSkin as e, type BlockColumnOptions as f, buildBlockColumn as g };

package/dist/OpenUIPixi-D4Z7emFO.d.ts

@@ -0,0 +1,202 @@
+import * as pixi_js from 'pixi.js';
+import { Container, Ticker, Texture, Application } from 'pixi.js';
+import { Theme, Control, OpenUI, ScreenState, BlockSpec, EventLog } from '@open-slot-ui/core';
+
+/**
+ * A skin owns a control's *look* and nothing else. The view drives it with the
+ * current state name; the skin swaps art accordingly. This is the seam where a
+ * game's design (Graphics, SVG, Spine, …) plugs in without touching control logic.
+ */
+interface SpinSkin {
+    /** The display object the view adds into its animated `art` container. */
+    readonly view: Container;
+    /** React to a state change (swap art, recolor, etc.). */
+    update(state: string): void;
+    destroy(): void;
+}
+type SpinSkinFactory = (theme: Theme) => SpinSkin;
+
+/**
+ * Base view: a Pixi Container bound to a core Control. Owns layout placement and
+ * registers the introspection hook so the core can report bounds/animation state.
+ * Subclasses draw and wire input. Dumb on its own (Charter B3).
+ */
+declare abstract class ControlView extends Container {
+    protected readonly control: Control;
+    protected readonly ui: OpenUI;
+    protected animating: boolean;
+    protected readonly disposers: Array<() => void>;
+    constructor(control: Control, ui: OpenUI);
+    /** Position + fit-scale from the control's layout spec against the screen. */
+    applyLayout(screen: ScreenState): void;
+    private computeRect;
+    dispose(): void;
+}
+
+/** Per-id view override — swap a control's renderer without forking (Charter P7). */
+type ControlViewFactory = (control: Control, ui: OpenUI, ticker: Ticker) => ControlView;
+interface BlockColumnOptions {
+    controlSkins?: Partial<Record<string, ControlViewFactory>>;
+    /** Unclipped layer for select dropdowns (so a scroll mask doesn't clip them). */
+    dropdownLayer?: Container;
+}
+interface BlockColumn {
+    /** Rows laid top→down (first row near y=0); the caller positions/scrolls it. */
+    content: Container;
+    /** Interactive child views, for disposal. */
+    views: ControlView[];
+    /** Total column height. */
+    height: number;
+    /** Inner content width (body width minus padding). */
+    innerW: number;
+}
+/**
+ * Render a declarative `BlockSpec[]` into a column of rows — interactive controls
+ * (slider/toggle/button/select/value/stepper) and static content (heading/text/
+ * callout/stat-grid/steps/paytable/image). All text flows through `ui.t`. This is
+ * the single renderer shared by the small panel body AND the scrollable menu, so
+ * blocks look identical wherever they appear (Charter B3/B9).
+ */
+declare function buildBlockColumn(blocks: BlockSpec[], controls: Control[], ui: OpenUI, ticker: Ticker, bodyW: number, opts?: BlockColumnOptions): BlockColumn;
+
+interface CellRenderer<C extends Container = Container> {
+    createCell(digit: number): C;
+    setDigit(cell: C, digit: number): void;
+    setFiller(cell: C, digit: number): void;
+    createSeparator?(char: string): Container;
+    destroyCell?(cell: C): void;
+}
+/**
+ * Minimal GSAP-compatible API the Counter uses for `fit` animation.
+ * Passing the default `gsap` import satisfies this shape — no need for type imports.
+ */
+interface GsapLike {
+    to(target: object, vars: Record<string, unknown>): unknown;
+    killTweensOf(target: object): void;
+}
+
+interface OpenUIIcons {
+    settingsIdle?: Texture;
+    settingsActive?: Texture;
+    close?: Texture;
+    rules?: Texture;
+    sliderMusic?: Texture;
+    sliderSound?: Texture;
+    turboOff?: Texture;
+    turboOn?: Texture;
+    /** One texture per turbo mode (index-aligned) — for 3-mode art. Wins over off/on. */
+    turboModes?: Texture[];
+    autoIdle?: Texture;
+    autoActive?: Texture;
+    bonus?: Texture;
+    betPlus?: Texture;
+    betMinus?: Texture;
+}
+interface OpenUIPixiOptions {
+    /** Expose `window.__OPENUI__` for e2e/introspection. Default true. */
+    expose?: boolean;
+    /** Override the spin control's skin (default = the art-free Graphics placeholder). */
+    spinSkin?: SpinSkinFactory;
+    /** Real art for the menu/close/slider controls (else neutral placeholders). */
+    icons?: OpenUIIcons;
+    /**
+     * The composed MENU blocks (Settings → Paytable → Rules) the ☰ button opens in a
+     * scrollable sheet. Usually built by `mountHud` via `composeMenu(spec.menu, …)`;
+     * omitted → a default Settings-only menu (Music/Sound). Pass `false` to skip the
+     * built-in Pixi menu entirely (e.g. when supplying your own HTML/DOM menu).
+     */
+    menu?: BlockSpec[] | false;
+    /** Header title for the menu sheet (localizable). Default 'Menu'. */
+    menuTitle?: string;
+    /** Per-id view override — swap a control's renderer without forking (Charter P7). */
+    controlSkins?: Partial<Record<string, ControlViewFactory>>;
+    /**
+     * Host `gsap` — enables the value counter's auto-downscale so wide currencies
+     * (8-decimal BTC, big SATS counts, long codes) shrink to fit instead of spilling.
+     * Kept out of the lib's deps (Charter B5); the host passes its own gsap.
+     */
+    gsap?: GsapLike;
+    /**
+     * Autoplay count-picker presentation. `'drawer'` (default) is a bottom sheet;
+     * `'radial'` fans the count chips around the spin button.
+     */
+    autoplayPicker?: 'drawer' | 'radial';
+    /**
+     * Text colour for the top-corner compliance readouts (RTP / net / session). Defaults
+     * to the theme text colour; a light-background host can pass a dark colour so the
+     * Figma-style `Label: value` block stays legible.
+     */
+    readoutColor?: string;
+    /**
+     * How the interactive HUD appears on mount: `'shown'` (default), `'hidden'` (off
+     * screen + non-interactive; reveal later with `showControls()`), or `'slide-in'`
+     * (start hidden, then slide in from the edges).
+     */
+    intro?: 'shown' | 'hidden' | 'slide-in';
+}
+/**
+ * The controller: mounts ONE root Container onto the host's existing stage,
+ * shares the host ticker/renderer, drives resize, and exposes introspection.
+ * `unmount()` removes the layer and every listener it created (Charter P2/P12).
+ */
+declare class OpenUIPixi {
+    private readonly ui;
+    private readonly opts;
+    readonly root: Container<pixi_js.ContainerChild>;
+    private readonly views;
+    /** Full-screen overlays (e.g. the autoplay drawer) that own their own layout. */
+    private readonly overlays;
+    private readonly disposers;
+    private _eventLog?;
+    /** Show/hide slide: each interactive view slides toward its anchored edge (bottom
+     *  controls down, top up — behind the status-bar plaque). Views stay direct children
+     *  of `root` (introspection bounds unchanged); only their y moves, and the
+     *  ref-counted input lock makes them non-interactive while moving/hidden. */
+    private slideProg;
+    private slideTarget;
+    private slideHeld;
+    private lastScreenH;
+    private appTicker?;
+    private slideTickFn?;
+    private readonly slideBaseY;
+    private readonly slideSign;
+    /** Buy-feature ⇄ total-win swap: only one shows at a time (see `setupBonusSwap`). */
+    private bonusView?;
+    private totalWinView?;
+    private readonly fadeFns;
+    constructor(ui: OpenUI, opts?: OpenUIPixiOptions);
+    /** The bus event log backing `window.__OPENUI__.events` (available after mount). */
+    get eventLog(): EventLog | undefined;
+    mount(app: Application): void;
+    /**
+     * Wire the buy-feature ⇄ total-win swap. In base play the buy button shows (unless
+     * hidden by config/jurisdiction); once the spin button enters free-spins mode
+     * (`setFreeSpins(n > 0)` — you "can't buy" mid-bonus) the buy button fades out and
+     * the localized total-win counter fades in over the same slot, then back on exit.
+     */
+    private setupBonusSwap;
+    /** Fade a view's alpha to `to` over `ms` (wall-clock paced); cancels any prior fade
+     *  on the same view. `onDone` runs once when it settles. */
+    private fadeTo;
+    /** Cancel an in-flight fade on `view` (if any). */
+    private stopFade;
+    /**
+     * Build the unified scrollable MENU bound to the ☰ panel. Composed `menu` blocks
+     * are given by `mountHud`; absent → a default Settings-only menu. Built-in ids
+     * ('music'/'sfx') are reused, not shadowed (P10); button blocks wire `closePanel`.
+     */
+    private buildMenu;
+    /**
+     * Slide the whole interactive HUD in (`true`) or out (`false`): bottom-anchored
+     * controls travel down, top-anchored travel up (behind the status-bar plaque).
+     * Pure translation (no scaling); controls are non-interactive while moving/hidden.
+     */
+    setControlsVisible(visible: boolean): void;
+    /** Apply the current slide progress: translate each interactive view toward its
+     *  anchored edge (pure translation — no scaling). */
+    private applySlide;
+    unmount(): void;
+    private expose;
+}
+
+export { type BlockColumn as B, ControlView as C, type GsapLike as G, type OpenUIIcons as O, type SpinSkinFactory as S, type ControlViewFactory as a, OpenUIPixi as b, type OpenUIPixiOptions as c, type CellRenderer as d, type SpinSkin as e, type BlockColumnOptions as f, buildBlockColumn as g };