@energy8platform/game-engine 0.14.10 → 0.15.1

package/dist/ui.d.ts

@@ -37,16 +37,35 @@ 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;
 }
 interface FlexContainerConfig {
     /** Layout direction (default: 'row') */
@@ -391,6 +410,62 @@ declare class Label extends Container {
     private fitText;
 }
 
+type LabelValueAlign = 'start' | 'center' | 'end';
+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"
+ * />
+ * ```
+ */
+declare class LabelValue extends FlexContainer {
+    private readonly _labelEl;
+    private readonly _valueEl;
+    private _valueMaxWidth;
+    constructor(config?: LabelValueConfig);
+    /** Get the caption Label (for advanced styling / animation) */
+    get labelElement(): Label;
+    /** Get the value Label */
+    get valueElement(): Label;
+    /** Update caption text */
+    setLabel(text: string): void;
+    /** Update value text */
+    setValue(text: string): void;
+    /** React reconciler update hook */
+    updateConfig(changed: Record<string, any>): void;
+}
+
 interface PanelConfig {
     /** Width */
     width?: number;
@@ -1037,5 +1112,5 @@ declare class Toggle extends Container {
     }): void;
 }
 
-export { BalanceDisplay, Button, FlexContainer, Label, Layout, Modal, Panel, ProgressBar, ScrollContainer, Slider, Toast, Toggle, WinDisplay, resolveView };
-export type { AlignContent, AlignItems, AlignSelf, BalanceDisplayConfig, ButtonConfig, ButtonState, FlexContainerConfig, FlexDirection, FlexItemConfig, JustifyContent, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, ModalConfig, PanelConfig, ProgressBarConfig, ScrollContainerConfig, ScrollDirection, SliderConfig, ToastConfig, ToastType, ToggleConfig, ViewInput, WinDisplayConfig };
+export { BalanceDisplay, Button, FlexContainer, Label, LabelValue, Layout, Modal, Panel, ProgressBar, ScrollContainer, Slider, Toast, Toggle, WinDisplay, resolveView };
+export type { AlignContent, AlignItems, AlignSelf, BalanceDisplayConfig, ButtonConfig, ButtonState, FlexContainerConfig, FlexDirection, FlexItemConfig, JustifyContent, LabelConfig, LabelValueAlign, LabelValueConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, ModalConfig, PanelConfig, ProgressBarConfig, ScrollContainerConfig, ScrollDirection, SliderConfig, ToastConfig, ToastType, ToggleConfig, ViewInput, WinDisplayConfig };

package/dist/ui.esm.js

@@ -558,22 +558,36 @@ class FlexContainer extends Container {
             this._computedWidth = this._explicitWidth > 0 ? this._explicitWidth : (pl + totalCrossNatural + pr);
             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;
+            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 - w - cfg.right;
-            if (cfg.top !== undefined)
-                child.y = cfg.top;
+                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 - h - cfg.bottom;
+                child.y = ch - cfg.bottom - bounds.y - bounds.height;
         }
     }
     /** Computed content size (after layout) */
@@ -1310,6 +1324,97 @@ class Label extends Container {
     }
 }
 
+/**
+ * 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"
+ * />
+ * ```
+ */
+class LabelValue extends FlexContainer {
+    _labelEl;
+    _valueEl;
+    _valueMaxWidth;
+    constructor(config = {}) {
+        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() {
+        return this._labelEl;
+    }
+    /** Get the value Label */
+    get valueElement() {
+        return this._valueEl;
+    }
+    /** Update caption text */
+    setLabel(text) {
+        this._labelEl.text = text;
+        this.updateLayout();
+    }
+    /** Update value text */
+    setValue(text) {
+        this._valueEl.text = text;
+        this.updateLayout();
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        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) {
+    return align;
+}
+
 /**
  * Background panel with optional flexbox content layout.
  *
@@ -2869,5 +2974,5 @@ class Toggle extends Container {
     }
 }
 
-export { BalanceDisplay, Button, FlexContainer, Label, Layout, Modal, Panel, ProgressBar, ScrollContainer, Slider, Toast, Toggle, WinDisplay, resolveView };
+export { BalanceDisplay, Button, FlexContainer, Label, LabelValue, Layout, Modal, Panel, ProgressBar, ScrollContainer, Slider, Toast, Toggle, WinDisplay, resolveView };
 //# sourceMappingURL=ui.esm.js.map