@energy8platform/game-engine 0.10.11 → 0.11.0

package/dist/ui.d.ts

@@ -1,12 +1,148 @@
 import { Texture, Container, TextStyle, ColorSource } from 'pixi.js';
-import { FancyButton, ScrollBox } from '@pixi/ui';
-import { LayoutContainer } from '@pixi/layout/components';
+
+/**
+ * Universal view input type for UI component visual slots.
+ *
+ * - `string` — texture name, resolved via `Sprite.from()`
+ * - `Texture` — wrapped in a `Sprite`
+ * - `Container` — used as-is (Sprite, Graphics, NineSliceSprite, AnimatedSprite, custom...)
+ */
+type ViewInput = string | Texture | Container;
+/**
+ * Resolve a ViewInput to a Container instance.
+ *
+ * @example
+ * ```ts
+ * resolveView('btn-idle')          // → Sprite.from('btn-idle')
+ * resolveView(someTexture)         // → new Sprite(someTexture)
+ * resolveView(myCustomContainer)   // → myCustomContainer (as-is)
+ * resolveView(undefined)           // → null
+ * ```
+ */
+declare function resolveView(input: ViewInput | undefined | null): Container | null;
+
+type FlexDirection = 'row' | 'column';
+type JustifyContent = 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+type AlignItems = 'start' | 'center' | 'end' | 'stretch';
+interface FlexItemConfig {
+    /** Flex grow factor (0 = fixed size) */
+    flexGrow?: number;
+    /** Explicit width override for layout calculations */
+    layoutWidth?: number;
+    /** Explicit height override for layout calculations */
+    layoutHeight?: number;
+}
+interface FlexContainerConfig {
+    /** Layout direction (default: 'row') */
+    direction?: FlexDirection;
+    /** Main-axis distribution (default: 'start') */
+    justifyContent?: JustifyContent;
+    /** Cross-axis alignment (default: 'start') */
+    alignItems?: AlignItems;
+    /** Gap between children in pixels (default: 0) */
+    gap?: number;
+    /** Padding [top, right, bottom, left] or single number (default: 0) */
+    padding?: number | [number, number, number, number];
+    /** Enable wrapping to next line (default: false) */
+    flexWrap?: boolean;
+    /** Maximum width before wrapping (only with flexWrap) */
+    maxWidth?: number;
+    /** Maximum height before wrapping (only with flexWrap + column) */
+    maxHeight?: number;
+    /** Explicit container width (used for cross-axis alignment/stretch) */
+    width?: number;
+    /** Explicit container height (used for cross-axis alignment/stretch) */
+    height?: number;
+}
+/**
+ * Lightweight flexbox-like layout container for PixiJS.
+ *
+ * Supports row/column direction, justify/align, gap, padding, wrapping,
+ * and flex-grow distribution. Zero external dependencies.
+ *
+ * @example
+ * ```ts
+ * const toolbar = new FlexContainer({
+ *   direction: 'row',
+ *   justifyContent: 'space-between',
+ *   alignItems: 'center',
+ *   gap: 16,
+ *   padding: 12,
+ * });
+ *
+ * toolbar.addFlexChild(button1);
+ * toolbar.addFlexChild(button2);
+ * toolbar.resize(800, 60);
+ * ```
+ */
+declare class FlexContainer extends Container {
+    readonly __uiComponent: true;
+    private _config;
+    private _padding;
+    private _maxWidth;
+    private _maxHeight;
+    /** @internal */ _explicitWidth: number;
+    /** @internal */ _explicitHeight: number;
+    private _layoutChildren;
+    private _layoutDirty;
+    constructor(config?: FlexContainerConfig);
+    /** Add a child with optional flex config. Also registers in flex layout. */
+    addFlexChild(child: Container, flexConfig?: FlexItemConfig): this;
+    /** Remove a child from flex layout and display list */
+    removeFlexChild(child: Container): this;
+    /** Remove all flex children */
+    clearFlexChildren(): this;
+    /**
+     * Override addChild so children automatically participate in flex layout.
+     * This enables declarative usage from React JSX.
+     */
+    addChild<T extends Container>(...children: T[]): T;
+    removeChild<T extends Container>(...children: T[]): T;
+    /** Get all flex layout children (read-only) */
+    get flexChildren(): readonly Container[];
+    /** Update the container size and recalculate layout */
+    resize(width: number, height: number): void;
+    /** Update layout direction */
+    setDirection(direction: FlexDirection): void;
+    /** Update justifyContent */
+    setJustifyContent(justify: JustifyContent): void;
+    /** Update alignItems */
+    setAlignItems(align: AlignItems): void;
+    /** Update gap */
+    setGap(gap: number): void;
+    /** Update padding */
+    setPadding(padding: number | [number, number, number, number]): void;
+    /**
+     * Recalculate and apply layout positions for all children.
+     * Called automatically by `resize()`. Call manually after
+     * adding/removing children without resize.
+     */
+    updateLayout(): void;
+    /** Computed content size (after layout) */
+    getContentSize(): {
+        width: number;
+        height: number;
+    };
+    /** React reconciler update hook — applies changed config props */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
+}
 
 type ButtonState = 'default' | 'hover' | 'pressed' | 'disabled';
 interface ButtonConfig {
-    /** Default texture/sprite for each state (optional — uses Graphics if not provided) */
-    textures?: Partial<Record<ButtonState, string | Texture>>;
-    /** Width (for Graphics-based button) */
+    /** Custom view for default state (string texture name, Texture, or Container) */
+    defaultView?: ViewInput;
+    /** Custom view for hover state */
+    hoverView?: ViewInput;
+    /** Custom view for pressed state */
+    pressedView?: ViewInput;
+    /** Custom view for disabled state */
+    disabledView?: ViewInput;
+    /** Width (for Graphics-based button, ignored when custom views provided) */
     width?: number;
     /** Height (for Graphics-based button) */
     height?: number;
@@ -20,67 +156,138 @@ interface ButtonConfig {
     animationDuration?: number;
     /** Start disabled */
     disabled?: boolean;
-    /** Button text */
+    /** Button text (rendered on top of the view) */
     text?: string;
     /** Button text style */
     textStyle?: Record<string, unknown>;
+    /** Press callback */
+    onPress?: () => void;
 }
 /**
- * Interactive button component powered by `@pixi/ui` FancyButton.
+ * Interactive button with per-state custom views and animations.
  *
- * Supports both texture-based and Graphics-based rendering with
- * per-state views, press animation, and text.
+ * Each visual state accepts a `ViewInput`: texture name, Texture, or any Container
+ * (Sprite, NineSliceSprite, AnimatedSprite, custom artwork, etc).
+ * Falls back to colored Graphics when no custom view is provided.
  *
  * @example
  * ```ts
+ * // Graphics-based (quick prototyping)
  * const btn = new Button({
  *   width: 200, height: 60, borderRadius: 12,
  *   colors: { default: 0x22aa22, hover: 0x33cc33 },
  *   text: 'SPIN',
+ *   onPress: () => spin(),
+ * });
+ *
+ * // Asset-based (production art)
+ * const btn = new Button({
+ *   defaultView: 'btn-idle',
+ *   hoverView: 'btn-hover',
+ *   pressedView: 'btn-pressed',
+ *   disabledView: 'btn-disabled',
+ *   text: 'SPIN',
+ *   onPress: () => spin(),
  * });
  *
- * btn.onPress.connect(() => console.log('Clicked!'));
- * scene.container.addChild(btn);
+ * // Custom Container view
+ * const btn = new Button({
+ *   defaultView: myAnimatedSprite,
+ *   text: 'SPIN',
+ * });
  * ```
  */
-declare class Button extends FancyButton {
-    private _buttonConfig;
+declare class Button extends Container {
+    readonly __uiComponent: true;
+    private _views;
+    private _state;
+    private _enabled;
+    private _config;
+    private _textObj;
+    /** Press callback */
+    onPress?: () => void;
     constructor(config?: ButtonConfig);
+    /** Current button state */
+    get state(): ButtonState;
     /** Enable the button */
     enable(): void;
     /** Disable the button */
     disable(): void;
+    /** Whether the button is enabled */
+    get enabled(): boolean;
+    set enabled(value: boolean);
     /** Whether the button is disabled */
     get disabled(): boolean;
+    /** Update button text */
+    set text(value: string);
+    private _buildViews;
+    private _rebuildViews;
+    private _setState;
+    private _onPointerOver;
+    private _onPointerOut;
+    private _onPointerDown;
+    private _onPointerUp;
+    private _onPointerUpOutside;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 interface ProgressBarConfig {
+    /** Width of the bar */
     width?: number;
+    /** Height of the bar */
     height?: number;
+    /** Corner radius (for Graphics-based bar) */
     borderRadius?: number;
+    /** Fill color (for Graphics-based bar, ignored when fillView provided) */
     fillColor?: number;
+    /** Track background color (for Graphics-based bar, ignored when trackView provided) */
     trackColor?: number;
+    /** Border color */
     borderColor?: number;
+    /** Border width */
     borderWidth?: number;
     /** Animated fill (smoothly interpolate) */
     animated?: boolean;
     /** Animation speed (0..1 per frame, default: 0.1) */
     animationSpeed?: number;
+    /** Custom track background (string texture name, Texture, or Container) */
+    trackView?: ViewInput;
+    /** Custom fill bar (string texture name, Texture, or Container) */
+    fillView?: ViewInput;
 }
 /**
- * Horizontal progress bar powered by `@pixi/ui` ProgressBar.
+ * Horizontal progress bar with optional custom track/fill views.
  *
- * Provides optional smooth animated fill via per-frame `update()`.
+ * Supports asset-based skinning: provide `trackView` and/or `fillView`
+ * as texture names, Textures, or any Container (NineSliceSprite, custom artwork, etc).
+ * Falls back to colored Graphics when no custom views are provided.
  *
  * @example
  * ```ts
+ * // Graphics-based (quick prototyping)
  * const bar = new ProgressBar({ width: 300, height: 20, fillColor: 0x22cc22 });
- * scene.container.addChild(bar);
- * bar.progress = 0.5; // 50%
+ * bar.progress = 0.5;
+ *
+ * // Asset-based (production art)
+ * const bar = new ProgressBar({
+ *   width: 300, height: 20,
+ *   trackView: 'bar-track',
+ *   fillView: new NineSliceSprite({ texture: 'bar-fill', ... }),
+ * });
+ * bar.progress = 0.75;
  * ```
  */
 declare class ProgressBar extends Container {
-    private _bar;
+    readonly __uiComponent: true;
+    private _track;
+    private _fill;
+    private _fillMask;
     private _borderGfx;
     private _config;
     private _progress;
@@ -93,6 +300,9 @@ declare class ProgressBar extends Container {
      * Call each frame if animated is true.
      */
     update(_dt: number): void;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    private updateMask;
 }
 
 interface LabelConfig {
@@ -117,6 +327,7 @@ interface LabelConfig {
  * ```
  */
 declare class Label extends Container {
+    readonly __uiComponent: true;
     private _text;
     private _maxWidth;
     private _autoFit;
@@ -140,6 +351,8 @@ declare class Label extends Container {
      * Format a number with thousands separators.
      */
     setNumber(value: number, decimals?: number, locale?: string): void;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
     private fitText;
 }
 
@@ -164,12 +377,14 @@ interface PanelConfig {
     nineSliceBorders?: [number, number, number, number];
     /** Padding inside the panel */
     padding?: number;
+    /** Flex layout config for content */
+    layout?: Partial<FlexContainerConfig>;
 }
 /**
- * Background panel powered by `@pixi/layout` LayoutContainer.
+ * Background panel with optional flexbox content layout.
  *
  * Supports both Graphics-based (color + border) and 9-slice sprite backgrounds.
- * Children added to `content` participate in flexbox layout automatically.
+ * Children added via `addContent()` participate in flex layout automatically.
  *
  * @example
  * ```ts
@@ -184,13 +399,32 @@ interface PanelConfig {
  * });
  * ```
  */
-declare class Panel extends LayoutContainer {
+declare class Panel extends Container {
+    readonly __uiComponent: true;
+    private _bg;
+    private _content;
+    private _internalSetup;
     private _panelConfig;
     constructor(config?: PanelConfig);
-    /** Access the content container (children added here participate in layout) */
-    get content(): Container;
+    /** Access the content flex container — add children here for layout */
+    get content(): FlexContainer;
+    /** Convenience: add a child to the content layout */
+    addContent(child: Container): this;
     /** Resize the panel */
     setSize(width: number, height: number): void;
+    /**
+     * Override addChild so external children are routed to content FlexContainer.
+     * Enables `<panel><label /><button /></panel>` in React JSX.
+     */
+    addChild<T extends Container>(...children: T[]): T;
+    removeChild<T extends Container>(...children: T[]): T;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 interface BalanceDisplayConfig {
@@ -213,7 +447,7 @@ interface BalanceDisplayConfig {
  * Reactive balance display component.
  *
  * Automatically formats currency and can animate value changes
- * with a smooth countup/countdown effect.
+ * with a smooth countup/countdown effect using engine Tween.
  *
  * @example
  * ```ts
@@ -225,13 +459,14 @@ interface BalanceDisplayConfig {
  * ```
  */
 declare class BalanceDisplay extends Container {
+    readonly __uiComponent: true;
     private _prefixLabel;
     private _valueLabel;
     private _config;
     private _currentValue;
     private _displayedValue;
-    private _animating;
-    private _animationCancelled;
+    /** Internal target for Tween animation */
+    private _tweenTarget;
     constructor(config?: BalanceDisplayConfig);
     /** Current displayed value */
     get value(): number;
@@ -246,6 +481,13 @@ declare class BalanceDisplay extends Container {
     private animateValue;
     private updateDisplay;
     private layoutLabels;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 interface WinDisplayConfig {
@@ -264,7 +506,7 @@ interface WinDisplayConfig {
  * Win amount display with countup animation.
  *
  * Shows a dramatic countup from 0 to the win amount, with optional
- * scale pop effect — typical of slot games.
+ * scale pop effect — typical of slot games. Uses engine Tween system.
  *
  * @example
  * ```ts
@@ -275,9 +517,11 @@ interface WinDisplayConfig {
  * ```
  */
 declare class WinDisplay extends Container {
+    readonly __uiComponent: true;
     private _label;
     private _config;
-    private _cancelCountup;
+    /** Internal target for Tween countup */
+    private _tweenTarget;
     constructor(config?: WinDisplayConfig);
     /**
      * Show a win with countup animation.
@@ -295,6 +539,13 @@ declare class WinDisplay extends Container {
      */
     hide(): void;
     private displayAmount;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 interface ModalConfig {
@@ -311,7 +562,7 @@ interface ModalConfig {
  * Modal overlay component.
  * Shows content on top of a dark overlay with enter/exit animations.
  *
- * The content container uses `@pixi/layout` for automatic centering.
+ * Content is automatically centered via position calculations.
  *
  * @example
  * ```ts
@@ -322,6 +573,7 @@ interface ModalConfig {
  * ```
  */
 declare class Modal extends Container {
+    readonly __uiComponent: true;
     private _overlay;
     private _contentContainer;
     private _config;
@@ -341,6 +593,8 @@ declare class Modal extends Container {
      * Hide the modal with animation.
      */
     hide(): Promise<void>;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
 }
 
 type ToastType = 'info' | 'success' | 'warning' | 'error';
@@ -349,6 +603,8 @@ interface ToastConfig {
     duration?: number;
     /** Toast position from bottom */
     bottomOffset?: number;
+    /** Custom background view (string texture name, Texture, or Container). Sized to fit text. */
+    backgroundView?: ViewInput;
 }
 /**
  * Toast notification component for displaying transient messages.
@@ -361,10 +617,12 @@ interface ToastConfig {
  * ```
  */
 declare class Toast extends Container {
+    readonly __uiComponent: true;
     private _bg;
+    private _customBg;
     private _text;
     private _config;
-    private _dismissTimeout;
+    private _dismissPending;
     constructor(config?: ToastConfig);
     /**
      * Show a toast message.
@@ -374,6 +632,13 @@ declare class Toast extends Container {
      * Dismiss the toast.
      */
     dismiss(): Promise<void>;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 type LayoutDirection = 'horizontal' | 'vertical' | 'grid' | 'wrap';
@@ -400,7 +665,7 @@ interface LayoutConfig {
     breakpoints?: Record<number, Partial<LayoutConfig>>;
 }
 /**
- * Responsive layout container powered by `@pixi/layout` (Yoga flexbox engine).
+ * Responsive layout container powered by a lightweight built-in flex layout solver.
  *
  * Supports horizontal, vertical, grid, and wrap layout modes with
  * alignment, padding, gap, and viewport-anchor positioning.
@@ -427,6 +692,7 @@ interface LayoutConfig {
  * ```
  */
 declare class Layout extends Container {
+    readonly __uiComponent: true;
     private _layoutConfig;
     private _padding;
     private _anchor;
@@ -435,6 +701,7 @@ declare class Layout extends Container {
     private _items;
     private _viewportWidth;
     private _viewportHeight;
+    private _flex;
     constructor(config?: LayoutConfig);
     /** Add an item to the layout */
     addItem(child: Container): this;
@@ -450,9 +717,16 @@ declare class Layout extends Container {
      */
     updateViewport(width: number, height: number): void;
     private applyLayoutStyles;
-    private applyGridChildWidth;
+    private buildFlexItemConfig;
     private applyAnchor;
     private resolveConfig;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
 type ScrollDirection = 'vertical' | 'horizontal' | 'both';
@@ -471,18 +745,23 @@ interface ScrollContainerConfig {
     elementsMargin?: number;
     /** Padding */
     padding?: number;
-    /** Disable dynamic rendering (render all items even when offscreen) */
-    disableDynamicRendering?: boolean;
     /** Disable easing/inertia */
     disableEasing?: boolean;
-    /** Global scroll — scroll even when mouse is not over the component */
-    globalScroll?: boolean;
+    /** Show scrollbar indicator (default: false) */
+    scrollbar?: boolean;
+    /** Custom scrollbar thumb view (string texture name, Texture, or Container) */
+    thumbView?: ViewInput;
+    /** Scrollbar width in px (default: 6) */
+    scrollbarWidth?: number;
+    /** Scrollbar padding from edge (default: 4) */
+    scrollbarPadding?: number;
+    /** Scrollbar color (when no thumbView, default: 0xaaaaaa) */
+    scrollbarColor?: number;
+    /** Scrollbar alpha (default: 0.5) */
+    scrollbarAlpha?: number;
 }
 /**
- * Scrollable container powered by `@pixi/ui` ScrollBox.
- *
- * Provides touch/drag scrolling, mouse wheel support, inertia, and
- * dynamic rendering optimization for off-screen items.
+ * Scrollable container with touch/drag, mouse wheel, and inertia.
  *
  * @example
  * ```ts
@@ -500,21 +779,70 @@ interface ScrollContainerConfig {
  * scene.container.addChild(scroll);
  * ```
  */
-declare class ScrollContainer extends ScrollBox {
+declare class ScrollContainer extends Container {
+    readonly __uiComponent: true;
+    private _viewport;
+    private _internalSetup;
+    private _content;
+    private _maskGfx;
+    private _bg;
     private _scrollConfig;
+    private _items;
+    private _scrollbar;
+    private _scrollbarConfig;
+    private _dragging;
+    private _dragStart;
+    private _contentStart;
+    private _velocity;
+    private _lastDragPos;
+    private _lastDragTime;
+    private _inertiaActive;
+    private _onTickBound;
+    private _onWheelBound;
     constructor(config: ScrollContainerConfig);
-    /** Set scrollable content. Replaces any existing content. */
+    /**
+     * Override addChild so external children are routed to scroll content.
+     * Enables `<scrollContainer><label /><panel /></scrollContainer>` in React JSX.
+     */
+    addChild<T extends Container>(...children: T[]): T;
+    removeChild<T extends Container>(...children: T[]): T;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+    /** Enable mouse wheel scrolling (call after adding to stage) */
+    enableWheel(canvas: HTMLCanvasElement): void;
+    /** Set scrollable content. Replaces any existing items. */
     setContent(content: Container): void;
     /** Add a single item */
-    addItem(...items: Container[]): Container;
-    /** Scroll to make a specific item/child visible */
+    addItem(child: Container): this;
+    /** Remove all items */
+    clearItems(): void;
+    /** Get items */
+    get items(): readonly Container[];
+    /** Scroll to make a specific item index visible */
     scrollToItem(index: number): void;
     /** Current scroll position */
     get scrollPosition(): {
         x: number;
         y: number;
     };
+    /** Resize the scroll viewport */
+    setViewportSize(width: number, height: number): void;
+    private layoutItems;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private startInertia;
+    private stopInertia;
+    private _inertiaTick;
+    private _onWheel;
+    private clampScroll;
+    private updateScrollbar;
+    destroy(options?: boolean | {
+        children?: boolean;
+        texture?: boolean;
+        textureSource?: boolean;
+    }): void;
 }
 
-export { BalanceDisplay, Button, Label, Layout, Modal, Panel, ProgressBar, ScrollContainer, Toast, WinDisplay };
-export type { BalanceDisplayConfig, ButtonConfig, ButtonState, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, ModalConfig, PanelConfig, ProgressBarConfig, ScrollContainerConfig, ScrollDirection, ToastConfig, ToastType, WinDisplayConfig };
+export { BalanceDisplay, Button, FlexContainer, Label, Layout, Modal, Panel, ProgressBar, ScrollContainer, Toast, WinDisplay, resolveView };
+export type { AlignItems, BalanceDisplayConfig, ButtonConfig, ButtonState, FlexContainerConfig, FlexDirection, FlexItemConfig, JustifyContent, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, ModalConfig, PanelConfig, ProgressBarConfig, ScrollContainerConfig, ScrollDirection, ToastConfig, ToastType, ViewInput, WinDisplayConfig };