@energy8platform/game-engine 0.13.0 → 0.14.1

package/README.md

@@ -410,7 +410,7 @@ If no custom view is provided, components fall back to Graphics-based rendering
 
 ### FlexContainer
 
-Lightweight flexbox-like layout container. Children added via `addChild()` automatically participate in flex layout.
+Lightweight flexbox-like layout container. Children added via `addChild()` automatically participate in flex layout. Supports auto-sizing (no explicit `width`/`height` required), percentage dimensions, absolute positioning for excluded children, and multi-line alignment.
 
 ```typescript
 const toolbar = new FlexContainer({
@@ -426,6 +426,32 @@ toolbar.addFlexChild(spacer, { flexGrow: 1 });   // with flex config
 toolbar.resize(800, 60);
 ```
 
+**FlexContainerConfig:**
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `'row' \| 'column'` | `'row'` | Layout direction |
+| `justifyContent` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around'` | `'start'` | Main-axis distribution |
+| `alignItems` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'start'` | Cross-axis alignment |
+| `alignContent` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'stretch'` | `'start'` | Multi-line cross-axis distribution (with `flexWrap`) |
+| `gap` | `number` | `0` | Gap between children |
+| `padding` | `number \| [top, right, bottom, left]` | `0` | Padding (shorthand) |
+| `paddingTop/Right/Bottom/Left` | `number` | — | Individual padding overrides (take priority over `padding`) |
+| `flexWrap` | `boolean` | `false` | Enable wrapping to next line |
+| `width` | `number \| string` | — | Container width — pixels or `"50%"` relative to parent |
+| `height` | `number \| string` | — | Container height — pixels or `"50%"` relative to parent |
+
+**Auto-sizing:** When no explicit `width`/`height` is set, the container computes its size from content (`_computedWidth`/`_computedHeight`). Cross-axis `alignItems` works automatically (centers relative to tallest/widest child). Parent FlexContainers correctly measure auto-sized children.
+
+**Percentage dimensions:** String values like `"100%"` or `"50%"` resolve against the parent FlexContainer's content area. Works for both container `width`/`height` and child `layoutWidth`/`layoutHeight`.
+
+```typescript
+// Parent with explicit size, child fills 100% width and 50% height
+const parent = new FlexContainer({ direction: 'column', width: 800, height: 600 });
+const child = new FlexContainer({ width: '100%', height: '50%', direction: 'row' });
+parent.addFlexChild(child); // child resolves to 800×300
+```
+
 **FlexItemConfig** — per-child options passed via `addFlexChild(child, config)` or JSX props:
 
 | Property | Type | Default | Description |
@@ -434,16 +460,21 @@ toolbar.resize(800, 60);
 | `flexShrink` | `number` | `1` | Flex shrink factor (`0` = don't shrink when content overflows) |
 | `alignSelf` | `'auto' \| 'start' \| 'center' \| 'end' \| 'stretch'` | `'auto'` | Override parent's `alignItems` for this child |
 | `flexExclude` | `boolean` | `false` | Exclude from flex layout (like `position: absolute`) |
-| `layoutWidth` | `number` | — | Explicit width override for layout calculations |
-| `layoutHeight` | `number` | — | Explicit height override for layout calculations |
+| `layoutWidth` | `number \| string` | — | Width override — pixels or `"50%"` of parent content area |
+| `layoutHeight` | `number \| string` | — | Height override — pixels or `"50%"` of parent content area |
+| `top` | `number` | — | Absolute positioning (only with `flexExclude`) — distance from top edge |
+| `right` | `number` | — | Absolute positioning — distance from right edge |
+| `bottom` | `number` | — | Absolute positioning — distance from bottom edge |
+| `left` | `number` | — | Absolute positioning — distance from left edge |
 
 ```typescript
 // Fixed item that won't shrink + centered override
 toolbar.addFlexChild(logo, { flexShrink: 0 });
 toolbar.addFlexChild(badge, { alignSelf: 'center' });
 
-// Background excluded from layout flow
-toolbar.addFlexChild(background, { flexExclude: true });
+// Absolute positioning (like CSS position: absolute)
+toolbar.addFlexChild(closeBtn, { flexExclude: true, top: 8, right: 8 });
+toolbar.addFlexChild(background, { flexExclude: true, top: 0, left: 0 });
 ```
 
 ### Layout
@@ -906,10 +937,30 @@ All engine UI components are config-based: the reconciler passes JSX props as a
 
 {/* Flex item props — work on any element inside <flexContainer> */}
 <flexContainer direction="row" width={800} height={60}>
-  <graphics draw={drawBg} flexExclude />       {/* excluded from flow */}
-  <label text="Logo" flexShrink={0} />          {/* won't shrink */}
-  <container flexGrow={1} />                     {/* fills remaining space */}
-  <button text="Menu" alignSelf="center" />      {/* centered on cross-axis */}
+  <graphics draw={drawBg} flexExclude top={0} left={0} /> {/* absolute positioning */}
+  <label text="Logo" flexShrink={0} />                      {/* won't shrink */}
+  <container flexGrow={1} />                                 {/* fills remaining space */}
+  <button text="Menu" alignSelf="center" />                  {/* centered on cross-axis */}
+  <sprite texture="close" flexExclude top={4} right={4} />  {/* top-right corner */}
+</flexContainer>
+
+{/* Individual padding props */}
+<flexContainer direction="column" paddingTop={20} paddingLeft={16} paddingRight={16}>
+  <label text="Content" />
+</flexContainer>
+
+{/* Percentage dimensions */}
+<flexContainer direction="column" width={screen.width} height={screen.height}>
+  <flexContainer width="100%" height="50%" direction="row" alignItems="center">
+    <label text="Top half" />
+  </flexContainer>
+</flexContainer>
+
+{/* alignContent for wrapped lines */}
+<flexContainer direction="row" flexWrap alignContent="center" width={400} height={400} gap={8}>
+  <button width={180} height={40} text="A" />
+  <button width={180} height={40} text="B" />
+  <button width={180} height={40} text="C" />
 </flexContainer>
 ```
 

package/dist/index.cjs.js

@@ -2912,26 +2912,90 @@ class SpriteAnimation {
 function normalizePadding(p) {
     return typeof p === 'number' ? [p, p, p, p] : p;
 }
+/** Resolve padding from config: individual props override the base `padding` value */
+function resolvePadding(config) {
+    const base = normalizePadding(config.padding ?? 0);
+    return [
+        config.paddingTop ?? base[0],
+        config.paddingRight ?? base[1],
+        config.paddingBottom ?? base[2],
+        config.paddingLeft ?? base[3],
+    ];
+}
+/** Resolve a dimension value — number passes through, "50%" resolves against reference */
+function resolveDimension(value, reference) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value.endsWith('%')) {
+        const pct = parseFloat(value);
+        if (!isNaN(pct) && reference > 0 && isFinite(reference))
+            return (pct / 100) * reference;
+    }
+    return undefined;
+}
 /** Measure a child's size and bounds offset for layout purposes */
-function measureChild(child) {
+function measureChild(child, parentContentW = 0, parentContentH = 0) {
     const cfg = child._flexConfig;
-    if (cfg?.layoutWidth !== undefined && cfg?.layoutHeight !== undefined) {
-        return { w: cfg.layoutWidth, h: cfg.layoutHeight, ox: 0, oy: 0 };
+    const resolvedLW = resolveDimension(cfg?.layoutWidth, parentContentW);
+    const resolvedLH = resolveDimension(cfg?.layoutHeight, parentContentH);
+    if (resolvedLW !== undefined && resolvedLH !== undefined) {
+        return { w: resolvedLW, h: resolvedLH, ox: 0, oy: 0 };
     }
-    // For FlexContainers, use their explicit size if set
+    // For FlexContainers, use their explicit or computed size
     if (child instanceof FlexContainer) {
         const fc = child;
-        if (fc._explicitWidth > 0 && fc._explicitHeight > 0) {
-            return { w: fc._explicitWidth, h: fc._explicitHeight, ox: 0, oy: 0 };
+        const w = fc._explicitWidth > 0 ? fc._explicitWidth : (fc._computedWidth > 0 ? fc._computedWidth : undefined);
+        const h = fc._explicitHeight > 0 ? fc._explicitHeight : (fc._computedHeight > 0 ? fc._computedHeight : undefined);
+        if (w !== undefined && h !== undefined) {
+            return { w, h, ox: 0, oy: 0 };
         }
     }
     // Use localBounds to get the true visual extent and origin offset.
     // This handles children with non-zero anchors (e.g. Button, Label with centered text).
     const bounds = child.getLocalBounds();
-    const w = cfg?.layoutWidth ?? bounds.width;
-    const h = cfg?.layoutHeight ?? bounds.height;
+    const w = resolvedLW ?? bounds.width;
+    const h = resolvedLH ?? bounds.height;
     return { w, h, ox: bounds.x, oy: bounds.y };
 }
+/**
+ * Set a child's main or cross dimension.
+ * For FlexContainer children, calls resize() to trigger internal relayout
+ * instead of the PixiJS scale setter.
+ */
+function setChildMainSize(child, isRow, mainSize, item) {
+    if (child instanceof FlexContainer) {
+        const fc = child;
+        fc.resize(isRow ? mainSize : fc._explicitWidth || fc._computedWidth, isRow ? fc._explicitHeight || fc._computedHeight : mainSize);
+    }
+    else {
+        if (isRow) {
+            child.width = mainSize;
+        }
+        else {
+            child.height = mainSize;
+        }
+    }
+    if (isRow)
+        item.w = mainSize;
+    else
+        item.h = mainSize;
+}
+function setChildCrossSize(child, isRow, crossSize) {
+    if (child instanceof FlexContainer) {
+        const fc = child;
+        fc.resize(isRow ? fc._explicitWidth || fc._computedWidth : crossSize, isRow ? crossSize : fc._explicitHeight || fc._computedHeight);
+    }
+    else {
+        if (isRow) {
+            child.height = crossSize;
+        }
+        else {
+            child.width = crossSize;
+        }
+    }
+}
 function layoutLine(items, isRow, mainSize, justify, align, gap, crossOffset, crossSize) {
     if (items.length === 0)
         return;
@@ -2955,14 +3019,7 @@ function layoutLine(items, isRow, mainSize, justify, align, gap, crossOffset, cr
             const grow = item.child._flexConfig?.flexGrow ?? 0;
             if (grow > 0) {
                 const flexSize = (grow / totalGrow) * availableForFlex;
-                if (isRow) {
-                    item.w = flexSize;
-                    item.child.width = flexSize;
-                }
-                else {
-                    item.h = flexSize;
-                    item.child.height = flexSize;
-                }
+                setChildMainSize(item.child, isRow, flexSize, item);
             }
         }
     }
@@ -2984,14 +3041,7 @@ function layoutLine(items, isRow, mainSize, justify, align, gap, crossOffset, cr
                         const itemMain = isRow ? item.w : item.h;
                         const reduction = overflow * (itemMain / totalShrinkable);
                         const newSize = Math.max(0, itemMain - reduction);
-                        if (isRow) {
-                            item.w = newSize;
-                            item.child.width = newSize;
-                        }
-                        else {
-                            item.h = newSize;
-                            item.child.height = newSize;
-                        }
+                        setChildMainSize(item.child, isRow, newSize, item);
                     }
                 }
             }
@@ -3048,12 +3098,7 @@ function layoutLine(items, isRow, mainSize, justify, align, gap, crossOffset, cr
                 crossPos += crossSize - crossDim;
                 break;
             case 'stretch':
-                if (isRow) {
-                    item.child.height = crossSize;
-                }
-                else {
-                    item.child.width = crossSize;
-                }
+                setChildCrossSize(item.child, isRow, crossSize);
                 break;
         }
         // Compensate for local bounds offset (e.g. centered anchors)
@@ -3098,6 +3143,12 @@ class FlexContainer extends pixi_js.Container {
     _maxHeight;
     /** @internal */ _explicitWidth;
     /** @internal */ _explicitHeight;
+    /** @internal */ _computedWidth = 0;
+    /** @internal */ _computedHeight = 0;
+    /** @internal */ _availableWidth = 0;
+    /** @internal */ _availableHeight = 0;
+    /** @internal */ _rawWidth;
+    /** @internal */ _rawHeight;
     _layoutChildren = [];
     _layoutDirty = true;
     constructor(config = {}) {
@@ -3108,12 +3159,15 @@ class FlexContainer extends pixi_js.Container {
             alignItems: config.alignItems ?? 'start',
             gap: config.gap ?? 0,
             flexWrap: config.flexWrap ?? false,
+            alignContent: config.alignContent ?? 'start',
         };
-        this._padding = normalizePadding(config.padding ?? 0);
+        this._padding = resolvePadding(config);
         this._maxWidth = config.maxWidth ?? Infinity;
         this._maxHeight = config.maxHeight ?? Infinity;
-        this._explicitWidth = config.width ?? 0;
-        this._explicitHeight = config.height ?? 0;
+        this._rawWidth = config.width ?? 0;
+        this._rawHeight = config.height ?? 0;
+        this._explicitWidth = typeof this._rawWidth === 'number' ? this._rawWidth : 0;
+        this._explicitHeight = typeof this._rawHeight === 'number' ? this._rawHeight : 0;
     }
     // ─── Public API ──────────────────────────────────────
     /** Add a child with optional flex config. Also registers in flex layout. */
@@ -3215,19 +3269,41 @@ class FlexContainer extends pixi_js.Container {
      */
     updateLayout() {
         this._layoutDirty = false;
-        const { direction, justifyContent, alignItems, gap, flexWrap } = this._config;
+        const { direction, justifyContent, alignItems, gap, flexWrap, alignContent } = this._config;
         const [pt, pr, pb, pl] = this._padding;
         const isRow = direction === 'row';
+        // Resolve percentage width/height against parent's available space
+        if (typeof this._rawWidth === 'string') {
+            this._explicitWidth = resolveDimension(this._rawWidth, this._availableWidth) ?? 0;
+        }
+        if (typeof this._rawHeight === 'string') {
+            this._explicitHeight = resolveDimension(this._rawHeight, this._availableHeight) ?? 0;
+        }
         const contentW = this._explicitWidth > 0 ? this._explicitWidth - pl - pr : Infinity;
         const contentH = this._explicitHeight > 0 ? this._explicitHeight - pt - pb : Infinity;
         const mainLimit = isRow ? contentW : contentH;
         const crossLimit = isRow ? contentH : contentW;
+        // Pass content area to measureChild for percentage resolution
+        const pctRefW = contentW < Infinity ? contentW : 0;
+        const pctRefH = contentH < Infinity ? contentH : 0;
+        // Propagate available size to child FlexContainers and resolve their percentages
+        for (const child of this._layoutChildren) {
+            if (child instanceof FlexContainer) {
+                const fc = child;
+                fc._availableWidth = pctRefW;
+                fc._availableHeight = pctRefH;
+                // If child has percentage dimensions, trigger its layout to resolve them
+                if (typeof fc._rawWidth === 'string' || typeof fc._rawHeight === 'string') {
+                    fc.updateLayout();
+                }
+            }
+        }
         // Measure children (skip flexExclude — they position themselves)
         const measured = [];
         for (const child of this._layoutChildren) {
             if (child._flexConfig?.flexExclude)
                 continue;
-            const { w, h, ox, oy } = measureChild(child);
+            const { w, h, ox, oy } = measureChild(child, pctRefW, pctRefH);
             measured.push({ child, w, h, ox, oy });
         }
         // Split into lines (if wrapping)
@@ -3264,42 +3340,106 @@ class FlexContainer extends pixi_js.Container {
             }
             return maxCross;
         });
+        // Compute natural main size (for auto-sizing when no explicit size given)
+        let naturalMainSize = 0;
+        if (mainLimit === Infinity) {
+            for (const line of lines) {
+                let lineMain = 0;
+                for (const item of line) {
+                    lineMain += isRow ? item.w : item.h;
+                }
+                lineMain += gap * Math.max(0, line.length - 1);
+                naturalMainSize = Math.max(naturalMainSize, lineMain);
+            }
+        }
+        // Effective main size: explicit if set, otherwise natural content size
+        const effectiveMainSize = mainLimit < Infinity ? mainLimit : naturalMainSize;
+        // Compute alignContent offsets for multi-line layouts
+        const totalLinesCross = lineCrossSizes.reduce((s, v) => s + v, 0) + gap * Math.max(0, lines.length - 1);
+        let acOffset = 0;
+        let acExtraGap = 0;
+        if (lines.length > 1 && crossLimit < Infinity) {
+            const freeSpace = Math.max(0, crossLimit - totalLinesCross);
+            switch (alignContent) {
+                case 'center':
+                    acOffset = freeSpace / 2;
+                    break;
+                case 'end':
+                    acOffset = freeSpace;
+                    break;
+                case 'space-between':
+                    if (lines.length > 1) {
+                        acExtraGap = freeSpace / (lines.length - 1);
+                    }
+                    break;
+                case 'stretch':
+                    if (lines.length > 0) {
+                        const extra = freeSpace / lines.length;
+                        for (let i = 0; i < lineCrossSizes.length; i++) {
+                            lineCrossSizes[i] += extra;
+                        }
+                    }
+                    break;
+                // 'start' — no adjustment
+            }
+        }
         // Layout each line
-        let crossOffset = isRow ? pt : pl;
+        let crossOffset = (isRow ? pt : pl) + acOffset;
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
             const lineCross = lineCrossSizes[i];
             const mainStart = isRow ? pl : pt;
             // Offset items by padding
             const tempItems = line.map((item) => ({ ...item }));
-            // For single-line layouts, use the full available cross space for alignment;
-            // for multi-line (wrapping), each line gets its own measured cross size.
-            const effectiveCross = lines.length === 1 && crossLimit < Infinity
-                ? crossLimit
-                : (crossLimit < Infinity ? Math.min(lineCross, crossLimit) : lineCross);
-            layoutLine(tempItems, isRow, mainLimit < Infinity ? mainLimit : 0, mainLimit < Infinity ? justifyContent : 'start', alignItems, gap, crossOffset, effectiveCross);
+            // Cross size for alignment: use container cross size for single-line, line cross for multi-line
+            const effectiveCross = lines.length === 1 && crossLimit < Infinity ? crossLimit : lineCross;
+            layoutLine(tempItems, isRow, effectiveMainSize, mainLimit < Infinity ? justifyContent : 'start', alignItems, gap, crossOffset, effectiveCross);
             // Apply main-axis padding offset
             for (const item of tempItems) {
                 const origChild = line.find((l) => l.child === item.child);
                 origChild.child.x = item.child.x + (isRow ? mainStart : 0);
                 origChild.child.y = item.child.y + (isRow ? 0 : mainStart);
             }
-            crossOffset += lineCross + gap;
+            crossOffset += lineCross + gap + acExtraGap;
+        }
+        // Compute and store actual dimensions for measureChild() and getContentSize()
+        let totalCrossNatural = 0;
+        for (let i = 0; i < lineCrossSizes.length; i++) {
+            totalCrossNatural += lineCrossSizes[i];
+            if (i < lineCrossSizes.length - 1)
+                totalCrossNatural += gap;
+        }
+        if (isRow) {
+            this._computedWidth = this._explicitWidth > 0 ? this._explicitWidth : (pl + naturalMainSize + pr);
+            this._computedHeight = this._explicitHeight > 0 ? this._explicitHeight : (pt + totalCrossNatural + pb);
+        }
+        else {
+            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)
+        for (const child of this._layoutChildren) {
+            if (!child._flexConfig?.flexExclude)
+                continue;
+            const cfg = child._flexConfig;
+            const { w, h } = 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;
         }
     }
     /** Computed content size (after layout) */
     getContentSize() {
         if (this._layoutDirty)
             this.updateLayout();
-        let maxX = 0;
-        let maxY = 0;
-        for (const child of this._layoutChildren) {
-            const { w, h } = measureChild(child);
-            maxX = Math.max(maxX, child.x + w);
-            maxY = Math.max(maxY, child.y + h);
-        }
-        const [, pr, pb] = this._padding;
-        return { width: maxX + pr, height: maxY + pb };
+        return { width: this._computedWidth, height: this._computedHeight };
     }
     /** React reconciler update hook — applies changed config props */
     updateConfig(changed) {
@@ -3311,15 +3451,34 @@ class FlexContainer extends pixi_js.Container {
             this.setAlignItems(changed.alignItems);
         if ('gap' in changed)
             this.setGap(changed.gap);
-        if ('padding' in changed)
-            this.setPadding(changed.padding);
+        if ('padding' in changed || 'paddingTop' in changed || 'paddingRight' in changed || 'paddingBottom' in changed || 'paddingLeft' in changed) {
+            this._padding = resolvePadding(changed);
+            this._layoutDirty = true;
+        }
         if ('flexWrap' in changed) {
             this._config.flexWrap = changed.flexWrap;
             this._layoutDirty = true;
         }
+        if ('alignContent' in changed) {
+            this._config.alignContent = changed.alignContent;
+            this._layoutDirty = true;
+        }
         if ('width' in changed || 'height' in changed) {
-            this.resize(changed.width ?? this._explicitWidth, changed.height ?? this._explicitHeight);
-            return; // resize calls updateLayout
+            const w = changed.width ?? this._rawWidth;
+            const h = changed.height ?? this._rawHeight;
+            this._rawWidth = w;
+            this._rawHeight = h;
+            if (typeof w === 'number' && typeof h === 'number') {
+                this.resize(w, h);
+            }
+            else {
+                // Percentage — will resolve in updateLayout
+                this._explicitWidth = typeof w === 'number' ? w : 0;
+                this._explicitHeight = typeof h === 'number' ? h : 0;
+                this._layoutDirty = true;
+                this.updateLayout();
+            }
+            return;
         }
         if (this._layoutDirty)
             this.updateLayout();