@energy8platform/game-engine 0.14.10 → 0.15.0

package/src/react/{jsx.d.ts → jsx-runtime.ts}

@@ -1,20 +1,27 @@
 /**
- * JSX IntrinsicElements type declarations for the PixiJS React reconciler.
+ * Ambient JSX IntrinsicElements declarations for the PixiJS React reconciler.
  *
- * Provides TypeScript autocompletion and type safety for:
- * - Standard PixiJS elements: <container>, <sprite>, <text>, <graphics>
- * - Engine UI components: <button>, <label>, <panel>, <flexContainer>, etc.
+ * Consumer apps opt in once (e.g. from an app-level `vite-env.d.ts`):
+ *
+ *   import '@energy8platform/game-engine/react-jsx';
+ *
+ * After that, TypeScript recognises `<flexContainer>`, `<button>`, `<label>` etc.
+ * with fully-typed props — no need to hand-maintain a local `pixi-jsx.d.ts`.
+ *
+ * The JS entry for this subpath is intentionally empty: this module exists
+ * solely to carry type declarations that side-effect the global `JSX` namespace.
  *
  * Dash-notation is supported for nested config objects:
  *   <button colors-default={0xff0000} colors-hover={0x00ff00} />
  */
 
-import type { Container, Texture, TextStyle } from 'pixi.js';
+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, FlexItemConfig, AlignSelf, AlignContent } from '../ui/FlexContainer';
+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';
@@ -90,11 +97,18 @@ interface BaseProps extends PixiEventProps {
   layoutHeight?: number | string;
   alignSelf?: AlignSelf;
   flexExclude?: boolean;
-  // Absolute positioning for flexExclude children
+  // 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 ───────────────────────────
@@ -120,6 +134,14 @@ interface TextProps extends BaseProps {
 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;
 }
 
 // ─── Engine UI component props ───────────────────────────
@@ -157,11 +179,28 @@ interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
   'style-letterSpacing'?: number;
 }
 
+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;
+}
+
 interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
   layout?: Partial<FlexContainerConfig>;
 }
 
-interface FlexContainerComponentProps extends BaseProps, FlexContainerConfig {
+interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'>, FlexContainerConfig {
   padding?: number | [number, number, number, number];
   paddingTop?: number;
   paddingRight?: number;
@@ -243,6 +282,7 @@ declare global {
       // Engine UI components
       button: ButtonComponentProps;
       label: LabelComponentProps;
+      labelValue: LabelValueComponentProps;
       panel: PanelComponentProps;
       flexContainer: FlexContainerComponentProps;
       progressBar: ProgressBarComponentProps;

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,26 @@ 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, so we subtract
+    // `ox/oy` to compensate for children with a centered origin (Button, Label).
+    // `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 { w, h, ox, oy } = measureChild(child, pctRefW, pctRefH);
       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 - w / 2 - ox;
+      else if (cfg.left !== undefined) child.x = cfg.left - ox;
+      else if (cfg.right !== undefined) child.x = cw - w - cfg.right - ox;
+
+      const centerY = resolveDimension(cfg.centerY, pctRefH);
+      if (centerY !== undefined) child.y = centerY - h / 2 - oy;
+      else if (cfg.top !== undefined) child.y = cfg.top - oy;
+      else if (cfg.bottom !== undefined) child.y = ch - h - cfg.bottom - oy;
     }
   }
 

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';