@energy8platform/game-engine 0.14.10 → 0.15.1

package/src/react/jsx-runtime.ts

@@ -0,0 +1,346 @@
+/**
+ * JSX prop types for the PixiJS React reconciler.
+ *
+ * The engine auto-augments `react`'s module-scoped `JSX.IntrinsicElements`
+ * with every registered element (`<flexContainer>`, `<button>`, `<label>`,
+ * `<labelValue>`, etc). Because the augmentation is scoped to the `react`
+ * module (not the legacy global `JSX` namespace), it reliably wins over
+ * `@types/react`'s HTML defaults for colliding names like `<button>` / `<label>`.
+ *
+ * **Consumers don't need any shim.** Any import from `@energy8platform/game-engine/react`
+ * (e.g. `createPixiRoot`, `extendUIElements`, `ReactScene` — you're already
+ * importing these to boot the reconciler) pulls this module in and the JSX
+ * types activate automatically.
+ *
+ * If a project imports only from `/ui` or `/core` and never touches `/react`,
+ * add a one-line side-effect import to trigger the augmentation:
+ *
+ * ```ts
+ * // app/src/pixi-jsx.d.ts
+ * import '@energy8platform/game-engine/react-jsx';
+ * ```
+ *
+ * Dash-notation for nested config objects is supported:
+ *   <button colors-default={0xff0000} colors-hover={0x00ff00} />
+ */
+
+import type { Texture, TextStyle } from 'pixi.js';
+import type { ViewInput } from '../ui/view';
+import type { ButtonConfig, ButtonState } from '../ui/Button';
+import type { LabelConfig } from '../ui/Label';
+import type { LabelValueConfig } from '../ui/LabelValue';
+import type { PanelConfig } from '../ui/Panel';
+import type { FlexContainerConfig, AlignSelf, AlignContent } from '../ui/FlexContainer';
+import type { ProgressBarConfig } from '../ui/ProgressBar';
+import type { ScrollContainerConfig } from '../ui/ScrollContainer';
+import type { ModalConfig } from '../ui/Modal';
+import type { ToastConfig } from '../ui/Toast';
+import type { BalanceDisplayConfig } from '../ui/BalanceDisplay';
+import type { WinDisplayConfig } from '../ui/WinDisplay';
+import type { LayoutConfig } from '../ui/Layout';
+import type { SliderConfig } from '../ui/Slider';
+import type { ToggleConfig } from '../ui/Toggle';
+
+// ─── Event props ─────────────────────────────────────────
+
+export interface PixiEventProps {
+  onClick?: (e: any) => void;
+  onPointerDown?: (e: any) => void;
+  onPointerUp?: (e: any) => void;
+  onPointerMove?: (e: any) => void;
+  onPointerOver?: (e: any) => void;
+  onPointerOut?: (e: any) => void;
+  onPointerEnter?: (e: any) => void;
+  onPointerLeave?: (e: any) => void;
+  onPointerCancel?: (e: any) => void;
+  onPointerTap?: (e: any) => void;
+  onPointerUpOutside?: (e: any) => void;
+  onMouseDown?: (e: any) => void;
+  onMouseUp?: (e: any) => void;
+  onMouseMove?: (e: any) => void;
+  onMouseOver?: (e: any) => void;
+  onMouseOut?: (e: any) => void;
+  onWheel?: (e: any) => void;
+  onTap?: (e: any) => void;
+  onRightClick?: (e: any) => void;
+}
+
+// ─── Base container props (shared by all elements) ───────
+
+export interface BaseProps extends PixiEventProps {
+  key?: React.Key;
+  ref?: React.Ref<any>;
+  children?: React.ReactNode;
+
+  // Container props
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  alpha?: number;
+  visible?: boolean;
+  rotation?: number;
+  angle?: number;
+  zIndex?: number;
+  label?: string;
+  cursor?: string;
+  eventMode?: 'auto' | 'none' | 'passive' | 'static' | 'dynamic';
+
+  // Nested via dash-notation
+  'scale-x'?: number;
+  'scale-y'?: number;
+  'pivot-x'?: number;
+  'pivot-y'?: number;
+  'position-x'?: number;
+  'position-y'?: number;
+  'anchor-x'?: number;
+  'anchor-y'?: number;
+
+  // Allow scale as number (uniform)
+  scale?: number | { x: number; y: number };
+
+  // Flex item props (used when child of <flexContainer>)
+  flexGrow?: number;
+  flexShrink?: number;
+  layoutWidth?: number | string;
+  layoutHeight?: number | string;
+  alignSelf?: AlignSelf;
+  flexExclude?: boolean;
+  // Absolute positioning for flexExclude children.
+  // Values describe the visual bounding rectangle (top-left of the rendered
+  // frame), so elements with centered origin like Button/Label are positioned
+  // intuitively — (left: 100, top: 50) puts the visible corner at (100, 50).
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+  /** X coordinate of the visual center within parent (px or `'50%'`). Overrides left/right. */
+  centerX?: number | string;
+  /** Y coordinate of the visual center within parent (px or `'50%'`). Overrides top/bottom. */
+  centerY?: number | string;
+}
+
+// ─── PixiJS primitive elements ───────────────────────────
+
+export interface SpriteProps extends BaseProps {
+  texture?: string | Texture;
+  anchor?: number | { x: number; y: number };
+  tint?: number;
+}
+
+export interface TextProps extends BaseProps {
+  text?: string;
+  style?: Partial<TextStyle>;
+  anchor?: number | { x: number; y: number };
+  // Dash-notation for style
+  'style-fontSize'?: number;
+  'style-fill'?: number | string;
+  'style-fontFamily'?: string;
+  'style-fontWeight'?: string;
+  'style-letterSpacing'?: number;
+}
+
+export interface GraphicsProps extends BaseProps {
+  /** Draw function: receives the Graphics instance, called on mount and updates */
+  draw?: (g: any) => void;
+  /**
+   * Layout size hint (pixels). For Graphics, `width`/`height` do NOT apply a scale
+   * transform (unlike Container.width). They're forwarded to the parent
+   * FlexContainer as `layoutWidth`/`layoutHeight` so layout measures the element
+   * at the requested size while the actual geometry stays in the `draw` callback.
+   */
+  width?: number;
+  height?: number;
+}
+
+export interface AnimatedSpriteProps extends BaseProps {
+  textures?: Texture[];
+  animationSpeed?: number;
+  loop?: boolean;
+  playing?: boolean;
+}
+
+export interface NineSliceSpriteProps extends BaseProps {
+  texture?: string | Texture;
+  leftWidth?: number;
+  topHeight?: number;
+  rightWidth?: number;
+  bottomHeight?: number;
+}
+
+export interface TilingSpriteProps extends BaseProps {
+  texture?: string | Texture;
+  tilePosition?: { x: number; y: number };
+}
+
+// ─── Engine UI component props ───────────────────────────
+
+export interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' | 'textStyle'> {
+  // Full object form
+  colors?: Partial<Record<ButtonState, number>>;
+  textStyle?: Record<string, unknown>;
+  // Custom views (ViewInput: string texture name, Texture, or Container)
+  defaultView?: ViewInput;
+  hoverView?: ViewInput;
+  pressedView?: ViewInput;
+  disabledView?: ViewInput;
+  // Dash-notation for nested objects
+  'colors-default'?: number;
+  'colors-hover'?: number;
+  'colors-pressed'?: number;
+  'colors-disabled'?: number;
+  'textStyle-fontSize'?: number;
+  'textStyle-fill'?: number | string;
+  'textStyle-fontFamily'?: string;
+  'textStyle-fontWeight'?: string;
+  'textStyle-fontStyle'?: string;
+  'textStyle-letterSpacing'?: number;
+  // Component callbacks
+  onPress?: () => void;
+}
+
+export interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
+  style?: Partial<TextStyle>;
+  'style-fontSize'?: number;
+  'style-fill'?: number | string;
+  'style-fontFamily'?: string;
+  'style-fontWeight'?: string;
+  'style-letterSpacing'?: number;
+}
+
+export interface LabelValueComponentProps extends Omit<BaseProps, 'width' | 'height' | 'label'>,
+  Omit<LabelValueConfig, 'labelStyle' | 'valueStyle'> {
+  labelStyle?: Partial<TextStyle>;
+  valueStyle?: Partial<TextStyle>;
+  width?: number | string;
+  height?: number | string;
+  // Dash-notation for nested styles
+  'labelStyle-fontSize'?: number;
+  'labelStyle-fill'?: number | string;
+  'labelStyle-fontFamily'?: string;
+  'labelStyle-fontWeight'?: string;
+  'valueStyle-fontSize'?: number;
+  'valueStyle-fill'?: number | string;
+  'valueStyle-fontFamily'?: string;
+  'valueStyle-fontWeight'?: string;
+}
+
+export interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
+  layout?: Partial<FlexContainerConfig>;
+}
+
+export interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'>, FlexContainerConfig {
+  padding?: number | [number, number, number, number];
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  alignContent?: AlignContent;
+  width?: number | string;
+  height?: number | string;
+}
+
+export interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
+  progress?: number;
+  /** Custom track background (string texture name, Texture, or Container) */
+  trackView?: ViewInput;
+  /** Custom fill bar */
+  fillView?: ViewInput;
+}
+
+export interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerConfig, 'width' | 'height'> {
+  width: number;
+  height: number;
+  /** Show scrollbar indicator */
+  scrollbar?: boolean;
+  /** Custom scrollbar thumb view */
+  thumbView?: ViewInput;
+  scrollbarWidth?: number;
+  scrollbarPadding?: number;
+  scrollbarColor?: number;
+  scrollbarAlpha?: number;
+}
+
+export interface ModalComponentProps extends BaseProps, ModalConfig {
+  onClose?: () => void;
+}
+
+export interface ToastComponentProps extends BaseProps, ToastConfig {
+  /** Custom background view */
+  backgroundView?: ViewInput;
+}
+
+export interface BalanceDisplayComponentProps extends BaseProps, BalanceDisplayConfig {
+  /** Current balance value */
+  value?: number;
+}
+
+export interface WinDisplayComponentProps extends BaseProps, WinDisplayConfig {}
+
+export interface LayoutComponentProps extends BaseProps, LayoutConfig {}
+
+export interface SliderComponentProps extends BaseProps, Omit<SliderConfig, 'width' | 'height'> {
+  width?: number;
+  height?: number;
+  onUpdate?: (value: number) => void;
+  onChange?: (value: number) => void;
+}
+
+export interface ToggleComponentProps extends BaseProps, Omit<ToggleConfig, 'width' | 'height'> {
+  width?: number;
+  height?: number;
+  onView?: ViewInput;
+  offView?: ViewInput;
+  onChange?: (value: boolean) => void;
+}
+
+// ─── IntrinsicElements map ───────────────────────────────
+
+/**
+ * Complete element → prop-type map for all engine-registered JSX elements.
+ * Also consumable directly for typing custom wrappers around engine elements.
+ */
+export interface EngineIntrinsicElements {
+  // PixiJS primitives
+  container: BaseProps;
+  sprite: SpriteProps;
+  text: TextProps;
+  graphics: GraphicsProps;
+  animatedSprite: AnimatedSpriteProps;
+  nineSliceSprite: NineSliceSpriteProps;
+  tilingSprite: TilingSpriteProps;
+
+  // Engine UI components
+  button: ButtonComponentProps;
+  label: LabelComponentProps;
+  labelValue: LabelValueComponentProps;
+  panel: PanelComponentProps;
+  flexContainer: FlexContainerComponentProps;
+  progressBar: ProgressBarComponentProps;
+  scrollContainer: ScrollContainerComponentProps;
+  modal: ModalComponentProps;
+  toast: ToastComponentProps;
+  balanceDisplay: BalanceDisplayComponentProps;
+  winDisplay: WinDisplayComponentProps;
+  layout: LayoutComponentProps;
+  slider: SliderComponentProps;
+  toggle: ToggleComponentProps;
+}
+
+// ─── Auto-augment React's JSX namespace ──────────────────
+//
+// React 19 scopes `JSX.IntrinsicElements` inside `declare module 'react'`,
+// so we augment the same module. `extends EngineIntrinsicElements {}` adds
+// every engine element to the interface the reconciler sees.
+//
+// Interface merging with `@types/react`'s HTML defaults: property names
+// unique to the engine (`flexContainer`, `labelValue`, `button` since it
+// carries our ButtonComponentProps, etc.) merge cleanly. For HTML-colliding
+// names (`button`, `label`), this module-scoped augmentation takes precedence
+// over the legacy global JSX namespace in React-19 apps.
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends EngineIntrinsicElements {}
+  }
+}

package/src/react/reconciler.ts

@@ -7,7 +7,7 @@ import { FlexContainer } from '../ui/FlexContainer';
 import type { FlexItemConfig } from '../ui/FlexContainer';
 
 /** Flex item prop names that should be forwarded to _flexConfig on the child */
-const FLEX_ITEM_PROPS = ['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude', 'top', 'right', 'bottom', 'left'] as const;
+const FLEX_ITEM_PROPS = ['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude', 'top', 'right', 'bottom', 'left', 'centerX', 'centerY'] as const;
 
 /** Any component with suspendLayout/resumeLayout (FlexContainer, Panel, etc.) */
 interface Suspendable {

package/src/ui/FlexContainer.ts

@@ -20,16 +20,35 @@ export interface FlexItemConfig {
   layoutHeight?: number | string;
   /** Override parent's alignItems for this child */
   alignSelf?: AlignSelf;
-  /** Exclude from flex layout (acts like position: absolute) */
+  /**
+   * Exclude from flex layout (acts like position: absolute).
+   *
+   * Positioning props (`top`/`right`/`bottom`/`left`/`centerX`/`centerY`) describe
+   * the **visual bounding rectangle**, so children with a centered internal
+   * origin (Button, Label — `anchor = 0.5`) are positioned intuitively.
+   * `left: 100` places the visible left edge at 100px, regardless of origin.
+   */
   flexExclude?: boolean;
-  /** Absolute positioning for flexExclude children (distance from top edge) */
+  /** Distance from top edge of parent content area to the child's visual top */
   top?: number;
-  /** Absolute positioning for flexExclude children (distance from right edge) */
+  /** Distance from right edge of parent content area to the child's visual right */
   right?: number;
-  /** Absolute positioning for flexExclude children (distance from bottom edge) */
+  /** Distance from bottom edge of parent content area to the child's visual bottom */
   bottom?: number;
-  /** Absolute positioning for flexExclude children (distance from left edge) */
+  /** Distance from left edge of parent content area to the child's visual left */
   left?: number;
+  /**
+   * X coordinate of the child's visual center within parent content area.
+   * Accepts pixels (`200`) or a percentage of parent content width (`'50%'`).
+   * Takes precedence over `left`/`right`.
+   */
+  centerX?: number | string;
+  /**
+   * Y coordinate of the child's visual center within parent content area.
+   * Accepts pixels or a percentage of parent content height (`'50%'`).
+   * Takes precedence over `top`/`bottom`.
+   */
+  centerY?: number | string;
 }
 
 export interface FlexContainerConfig {
@@ -679,17 +698,31 @@ export class FlexContainer extends Container {
       this._computedHeight = this._explicitHeight > 0 ? this._explicitHeight : (pt + naturalMainSize + pb);
     }
 
-    // Position flexExclude children (absolute positioning)
+    // Position flexExclude children (absolute positioning).
+    // All position props describe the visual (bounds) rectangle. We derive the
+    // visual rectangle directly from `getLocalBounds()` rather than the
+    // layout-config `w`/`h` returned by measureChild — those may differ from
+    // actual bounds when the user pins `layoutWidth`/`layoutHeight` to a value
+    // that doesn't match the child's real visual extent (e.g. a Button whose
+    // text overflows its configured `width`). Mixing layout size with real
+    // bounds-origin would shift the visual center off the requested point.
+    // `centerX/centerY` take precedence over `left/right` / `top/bottom` on each axis.
     for (const child of this._layoutChildren) {
       if (!child._flexConfig?.flexExclude) continue;
       const cfg = child._flexConfig;
-      const { w, h } = measureChild(child, pctRefW, pctRefH);
+      const bounds = child.getLocalBounds();
       const cw = this._computedWidth;
       const ch = this._computedHeight;
-      if (cfg.left !== undefined) child.x = cfg.left;
-      else if (cfg.right !== undefined) child.x = cw - w - cfg.right;
-      if (cfg.top !== undefined) child.y = cfg.top;
-      else if (cfg.bottom !== undefined) child.y = ch - h - cfg.bottom;
+
+      const centerX = resolveDimension(cfg.centerX, pctRefW);
+      if (centerX !== undefined) child.x = centerX - bounds.x - bounds.width / 2;
+      else if (cfg.left !== undefined) child.x = cfg.left - bounds.x;
+      else if (cfg.right !== undefined) child.x = cw - cfg.right - bounds.x - bounds.width;
+
+      const centerY = resolveDimension(cfg.centerY, pctRefH);
+      if (centerY !== undefined) child.y = centerY - bounds.y - bounds.height / 2;
+      else if (cfg.top !== undefined) child.y = cfg.top - bounds.y;
+      else if (cfg.bottom !== undefined) child.y = ch - cfg.bottom - bounds.y - bounds.height;
     }
   }
 

package/src/ui/LabelValue.ts

@@ -0,0 +1,122 @@
+import type { TextStyle } from 'pixi.js';
+import { FlexContainer, type FlexContainerConfig } from './FlexContainer';
+import { Label } from './Label';
+
+export type LabelValueAlign = 'start' | 'center' | 'end';
+
+export interface LabelValueConfig {
+  /** Caption text (top row, typically smaller/muted) */
+  label?: string;
+  /** Value text (bottom row, typically larger/prominent) */
+  value?: string;
+  /** Style for the caption Label */
+  labelStyle?: Partial<TextStyle>;
+  /** Style for the value Label */
+  valueStyle?: Partial<TextStyle>;
+  /** Gap in pixels between caption and value (default: 4) */
+  gap?: number;
+  /** Horizontal alignment of both rows (default: 'center') */
+  align?: LabelValueAlign;
+  /** Maximum width — value will be auto-scaled to fit when exceeded */
+  maxWidth?: number;
+  /** Optional padding (forwarded to the underlying FlexContainer) */
+  padding?: FlexContainerConfig['padding'];
+}
+
+/**
+ * Two-row text cell with a muted caption above and a prominent value below —
+ * the archetypal casino UI pattern (BALANCE/€500, BET/€1, WIN/€0.00).
+ *
+ * Extends FlexContainer, so it participates in parent flex layouts directly
+ * (you can pass `flexGrow`, `alignSelf`, etc. when it's a child of another
+ * FlexContainer) and auto-sizes to its contents when no explicit size is set.
+ *
+ * @example
+ * ```tsx
+ * <labelValue
+ *   label="BALANCE"
+ *   value={`€${balance.toFixed(2)}`}
+ *   labelStyle={{ fontSize: 12, fill: 0x888888 }}
+ *   valueStyle={{ fontSize: 22, fill: 0xffffff, fontWeight: 'bold' }}
+ *   gap={6}
+ *   align="center"
+ * />
+ * ```
+ */
+export class LabelValue extends FlexContainer {
+  private readonly _labelEl: Label;
+  private readonly _valueEl: Label;
+  private _valueMaxWidth: number;
+
+  constructor(config: LabelValueConfig = {}) {
+    super({
+      direction: 'column',
+      alignItems: toAlignItems(config.align ?? 'center'),
+      gap: config.gap ?? 4,
+      padding: config.padding,
+    });
+
+    this._valueMaxWidth = config.maxWidth ?? Infinity;
+
+    this._labelEl = new Label({
+      text: config.label ?? '',
+      style: config.labelStyle,
+    });
+    this._valueEl = new Label({
+      text: config.value ?? '',
+      style: config.valueStyle,
+      maxWidth: config.maxWidth,
+      autoFit: config.maxWidth !== undefined,
+    });
+
+    this.addFlexChild(this._labelEl);
+    this.addFlexChild(this._valueEl);
+  }
+
+  /** Get the caption Label (for advanced styling / animation) */
+  get labelElement(): Label {
+    return this._labelEl;
+  }
+
+  /** Get the value Label */
+  get valueElement(): Label {
+    return this._valueEl;
+  }
+
+  /** Update caption text */
+  setLabel(text: string): void {
+    this._labelEl.text = text;
+    this.updateLayout();
+  }
+
+  /** Update value text */
+  setValue(text: string): void {
+    this._valueEl.text = text;
+    this.updateLayout();
+  }
+
+  /** React reconciler update hook */
+  override updateConfig(changed: Record<string, any>): void {
+    if ('label' in changed) this._labelEl.text = changed.label ?? '';
+    if ('value' in changed) this._valueEl.text = changed.value ?? '';
+    if ('labelStyle' in changed && typeof changed.labelStyle === 'object') {
+      Object.assign(this._labelEl.style, changed.labelStyle);
+    }
+    if ('valueStyle' in changed && typeof changed.valueStyle === 'object') {
+      Object.assign(this._valueEl.style, changed.valueStyle);
+    }
+    if ('maxWidth' in changed) {
+      this._valueMaxWidth = changed.maxWidth ?? Infinity;
+      this._valueEl.maxWidth = this._valueMaxWidth;
+    }
+    if ('gap' in changed) this.setGap(changed.gap);
+    if ('align' in changed) this.setAlignItems(toAlignItems(changed.align));
+
+    // Forward remaining FlexContainer props (e.g. padding, width, height)
+    super.updateConfig(changed);
+  }
+}
+
+function toAlignItems(align: LabelValueAlign): 'start' | 'center' | 'end' {
+  return align;
+}

package/src/ui/index.ts

@@ -11,6 +11,8 @@ export { ProgressBar } from './ProgressBar';
 export type { ProgressBarConfig } from './ProgressBar';
 export { Label } from './Label';
 export type { LabelConfig } from './Label';
+export { LabelValue } from './LabelValue';
+export type { LabelValueConfig, LabelValueAlign } from './LabelValue';
 export { Panel } from './Panel';
 export type { PanelConfig } from './Panel';
 export { BalanceDisplay } from './BalanceDisplay';