@energy8platform/game-engine 0.11.0 → 0.13.0

package/src/ui/FlexContainer.ts

@@ -6,13 +6,21 @@ export type FlexDirection = 'row' | 'column';
 export type JustifyContent = 'start' | 'center' | 'end' | 'space-between' | 'space-around';
 export type AlignItems = 'start' | 'center' | 'end' | 'stretch';
 
+export type AlignSelf = 'auto' | 'start' | 'center' | 'end' | 'stretch';
+
 export interface FlexItemConfig {
   /** Flex grow factor (0 = fixed size) */
   flexGrow?: number;
+  /** Flex shrink factor (0 = don't shrink, default: 1) */
+  flexShrink?: number;
   /** Explicit width override for layout calculations */
   layoutWidth?: number;
   /** Explicit height override for layout calculations */
   layoutHeight?: number;
+  /** Override parent's alignItems for this child */
+  alignSelf?: AlignSelf;
+  /** Exclude from flex layout (acts like position: absolute) */
+  flexExclude?: boolean;
 }
 
 export interface FlexContainerConfig {
@@ -123,6 +131,37 @@ function layoutLine(
     }
   }
 
+  // Shrink: if content overflows and mainSize is finite, shrink eligible items
+  if (totalGrow === 0 && mainSize > 0) {
+    const overflow = totalFixed + totalGap - mainSize;
+    if (overflow > 0) {
+      let totalShrinkable = 0;
+      for (const item of items) {
+        const shrink = item.child._flexConfig?.flexShrink ?? 1;
+        if (shrink > 0) {
+          totalShrinkable += isRow ? item.w : item.h;
+        }
+      }
+      if (totalShrinkable > 0) {
+        for (const item of items) {
+          const shrink = item.child._flexConfig?.flexShrink ?? 1;
+          if (shrink > 0) {
+            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;
+            }
+          }
+        }
+      }
+    }
+  }
+
   // Calculate total main size after flex
   let totalMain = totalGap;
   for (const item of items) {
@@ -163,9 +202,12 @@ function layoutLine(
     const mainDim = isRow ? item.w : item.h;
     const crossDim = isRow ? item.h : item.w;
 
-    // Cross-axis alignment
+    // Cross-axis alignment (alignSelf overrides align)
+    const effectiveAlign = (item.child._flexConfig?.alignSelf && item.child._flexConfig.alignSelf !== 'auto')
+      ? item.child._flexConfig.alignSelf
+      : align;
     let crossPos = crossOffset;
-    switch (align) {
+    switch (effectiveAlign) {
       case 'start':
         break;
       case 'center':
@@ -369,11 +411,13 @@ export class FlexContainer extends Container {
     const mainLimit = isRow ? contentW : contentH;
     const crossLimit = isRow ? contentH : contentW;
 
-    // Measure children
-    const measured: LineItem[] = this._layoutChildren.map((child) => {
+    // Measure children (skip flexExclude — they position themselves)
+    const measured: LineItem[] = [];
+    for (const child of this._layoutChildren) {
+      if (child._flexConfig?.flexExclude) continue;
       const { w, h, ox, oy } = measureChild(child);
-      return { child, w, h, ox, oy };
-    });
+      measured.push({ child, w, h, ox, oy });
+    }
 
     // Split into lines (if wrapping)
     const lines: LineItem[][] = [];
@@ -419,6 +463,12 @@ export class FlexContainer extends Container {
       // 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,
@@ -427,7 +477,7 @@ export class FlexContainer extends Container {
         alignItems,
         gap,
         crossOffset,
-        crossLimit < Infinity ? Math.min(lineCross, crossLimit) : lineCross,
+        effectiveCross,
       );
 
       // Apply main-axis padding offset

package/src/ui/Slider.ts

@@ -0,0 +1,241 @@
+import { Container, Graphics, FederatedPointerEvent } from 'pixi.js';
+import { resolveView } from './view';
+import type { ViewInput } from './view';
+
+export interface SliderConfig {
+  /** Minimum value (default: 0) */
+  min?: number;
+  /** Maximum value (default: 1) */
+  max?: number;
+  /** Step increment (0 = continuous, default: 0) */
+  step?: number;
+  /** Initial value (default: min) */
+  value?: number;
+  /** Track width in pixels (default: 200) */
+  width?: number;
+  /** Track height in pixels (default: 8) */
+  height?: number;
+  /** Corner radius for Graphics-based track/fill (default: 4) */
+  borderRadius?: number;
+  /** Track background color (ignored when trackView provided) */
+  trackColor?: number;
+  /** Fill bar color (ignored when fillView provided) */
+  fillColor?: number;
+  /** Handle radius (for Graphics-based handle, default: 12) */
+  handleRadius?: number;
+  /** Handle color (for Graphics-based handle, ignored when handleView provided) */
+  handleColor?: number;
+
+  /** Custom track background view */
+  trackView?: ViewInput;
+  /** Custom fill bar view */
+  fillView?: ViewInput;
+  /** Custom handle view */
+  handleView?: ViewInput;
+
+  /** Called when value changes during drag */
+  onUpdate?: (value: number) => void;
+  /** Called when drag ends */
+  onChange?: (value: number) => void;
+}
+
+/**
+ * Draggable slider with customizable track, fill, and handle views.
+ *
+ * @example
+ * ```ts
+ * const volume = new Slider({
+ *   min: 0, max: 1, value: 0.5,
+ *   width: 200, height: 8,
+ *   fillColor: 0xffd700,
+ *   onUpdate: (v) => console.log('Volume:', v),
+ * });
+ * ```
+ */
+export class Slider extends Container {
+  readonly __uiComponent = true as const;
+
+  private _track: Container;
+  private _fill: Container;
+  private _fillMask: Graphics;
+  private _handle: Container;
+  private _config: Required<Pick<SliderConfig, 'min' | 'max' | 'step' | 'width' | 'height' | 'borderRadius' | 'trackColor' | 'fillColor' | 'handleRadius' | 'handleColor'>>;
+  private _value: number;
+  private _dragging = false;
+
+  onUpdate: ((value: number) => void) | null = null;
+  onChange: ((value: number) => void) | null = null;
+
+  constructor(config: SliderConfig = {}) {
+    super();
+
+    this._config = {
+      min: config.min ?? 0,
+      max: config.max ?? 1,
+      step: config.step ?? 0,
+      width: config.width ?? 200,
+      height: config.height ?? 8,
+      borderRadius: config.borderRadius ?? 4,
+      trackColor: config.trackColor ?? 0x333333,
+      fillColor: config.fillColor ?? 0xffd700,
+      handleRadius: config.handleRadius ?? 12,
+      handleColor: config.handleColor ?? 0xffffff,
+    };
+
+    this._value = config.value ?? this._config.min;
+    this.onUpdate = config.onUpdate ?? null;
+    this.onChange = config.onChange ?? null;
+
+    const { width, height, borderRadius, trackColor, fillColor, handleRadius, handleColor } = this._config;
+
+    // Track
+    const customTrack = resolveView(config.trackView);
+    if (customTrack) {
+      customTrack.width = width;
+      customTrack.height = height;
+      this._track = customTrack;
+    } else {
+      const g = new Graphics();
+      g.roundRect(0, 0, width, height, borderRadius).fill(trackColor);
+      this._track = g;
+    }
+    this.addChild(this._track);
+
+    // Fill
+    const customFill = resolveView(config.fillView);
+    if (customFill) {
+      customFill.width = width;
+      customFill.height = height;
+      this._fill = customFill;
+    } else {
+      const g = new Graphics();
+      g.roundRect(0, 0, width, height, borderRadius).fill(fillColor);
+      this._fill = g;
+    }
+    this.addChild(this._fill);
+
+    // Fill mask
+    this._fillMask = new Graphics();
+    this.addChild(this._fillMask);
+    this._fill.mask = this._fillMask;
+
+    // Handle
+    const customHandle = resolveView(config.handleView);
+    if (customHandle) {
+      this._handle = customHandle;
+    } else {
+      const g = new Graphics();
+      g.circle(0, 0, handleRadius).fill(handleColor);
+      this._handle = g;
+    }
+    this._handle.y = height / 2;
+    this.addChild(this._handle);
+
+    // Interaction
+    this.eventMode = 'static';
+    this.cursor = 'pointer';
+
+    // Hit area covers track + handle overflow
+    const hitPad = Math.max(handleRadius - height / 2, 0);
+    this.hitArea = { contains: (x: number, y: number) => x >= -hitPad && x <= width + hitPad && y >= -hitPad && y <= height + hitPad };
+
+    this.on('pointerdown', this._onPointerDown, this);
+    this.on('globalpointermove', this._onPointerMove, this);
+    this.on('pointerup', this._onPointerUp, this);
+    this.on('pointerupoutside', this._onPointerUp, this);
+
+    this._updateVisuals();
+  }
+
+  /** Current value */
+  get value(): number {
+    return this._value;
+  }
+
+  set value(v: number) {
+    const clamped = this._applyStep(Math.max(this._config.min, Math.min(this._config.max, v)));
+    if (clamped === this._value) return;
+    this._value = clamped;
+    this._updateVisuals();
+  }
+
+  get min(): number { return this._config.min; }
+  get max(): number { return this._config.max; }
+
+  /** React reconciler update hook */
+  updateConfig(changed: Record<string, any>): void {
+    if ('value' in changed) this.value = changed.value;
+    if ('min' in changed) { this._config.min = changed.min; this._updateVisuals(); }
+    if ('max' in changed) { this._config.max = changed.max; this._updateVisuals(); }
+    if ('step' in changed) this._config.step = changed.step;
+    if ('onUpdate' in changed) this.onUpdate = changed.onUpdate;
+    if ('onChange' in changed) this.onChange = changed.onChange;
+  }
+
+  private _fraction(): number {
+    const { min, max } = this._config;
+    return max === min ? 0 : (this._value - min) / (max - min);
+  }
+
+  private _applyStep(v: number): number {
+    const { step, min } = this._config;
+    if (step <= 0) return v;
+    return min + Math.round((v - min) / step) * step;
+  }
+
+  private _updateVisuals(): void {
+    const frac = this._fraction();
+    const w = this._config.width;
+    const h = this._config.height;
+
+    // Update fill mask
+    this._fillMask.clear();
+    this._fillMask.rect(0, 0, w * frac, h).fill(0xffffff);
+
+    // Update handle position
+    this._handle.x = w * frac;
+  }
+
+  private _valueFromPointer(e: FederatedPointerEvent): number {
+    const local = this.toLocal(e.global);
+    const frac = Math.max(0, Math.min(1, local.x / this._config.width));
+    const { min, max } = this._config;
+    return this._applyStep(min + frac * (max - min));
+  }
+
+  private _onPointerDown(e: FederatedPointerEvent): void {
+    this._dragging = true;
+    const newValue = this._valueFromPointer(e);
+    if (newValue !== this._value) {
+      this._value = newValue;
+      this._updateVisuals();
+      this.onUpdate?.(this._value);
+    }
+  }
+
+  private _onPointerMove(e: FederatedPointerEvent): void {
+    if (!this._dragging) return;
+    const newValue = this._valueFromPointer(e);
+    if (newValue !== this._value) {
+      this._value = newValue;
+      this._updateVisuals();
+      this.onUpdate?.(this._value);
+    }
+  }
+
+  private _onPointerUp(_e: FederatedPointerEvent): void {
+    if (!this._dragging) return;
+    this._dragging = false;
+    this.onChange?.(this._value);
+  }
+
+  override destroy(options?: boolean | { children?: boolean; texture?: boolean; textureSource?: boolean }): void {
+    this.off('pointerdown', this._onPointerDown, this);
+    this.off('globalpointermove', this._onPointerMove, this);
+    this.off('pointerup', this._onPointerUp, this);
+    this.off('pointerupoutside', this._onPointerUp, this);
+    this.onUpdate = null;
+    this.onChange = null;
+    super.destroy(options);
+  }
+}

package/src/ui/Toggle.ts

@@ -0,0 +1,201 @@
+import { Container, Graphics } from 'pixi.js';
+import { Tween } from '../animation/Tween';
+import { resolveView } from './view';
+import type { ViewInput } from './view';
+
+export interface ToggleConfig {
+  /** Initial state (default: false) */
+  value?: boolean;
+  /** Custom view for the ON state */
+  onView?: ViewInput;
+  /** Custom view for the OFF state */
+  offView?: ViewInput;
+  /** Width (for Graphics-based toggle, default: 52) */
+  width?: number;
+  /** Height (for Graphics-based toggle, default: 28) */
+  height?: number;
+  /** Track color when ON (ignored when custom views provided) */
+  onColor?: number;
+  /** Track color when OFF (ignored when custom views provided) */
+  offColor?: number;
+  /** Handle color (for Graphics-based toggle) */
+  handleColor?: number;
+  /** Handle radius (for Graphics-based toggle, default: auto) */
+  handleRadius?: number;
+  /** Animation duration in ms (default: 200) */
+  animationDuration?: number;
+
+  /** Called when value changes */
+  onChange?: (value: boolean) => void;
+}
+
+/**
+ * Toggle switch with two states.
+ *
+ * Supports custom ON/OFF views or auto-generated Graphics-based toggle.
+ * Click to toggle, or use `forceSwitch(value)` programmatically.
+ *
+ * @example
+ * ```ts
+ * const mute = new Toggle({
+ *   value: false,
+ *   onColor: 0x22cc22,
+ *   onChange: (on) => audioManager.mute(!on),
+ * });
+ * ```
+ */
+export class Toggle extends Container {
+  readonly __uiComponent = true as const;
+
+  private _value: boolean;
+  private _onView: Container | null = null;
+  private _offView: Container | null = null;
+  private _handle: Container | null = null;
+  private _trackGfx: Graphics | null = null;
+  private _config: Required<Pick<ToggleConfig, 'width' | 'height' | 'onColor' | 'offColor' | 'handleColor' | 'handleRadius' | 'animationDuration'>>;
+  private _useCustomViews: boolean;
+
+  onChange: ((value: boolean) => void) | null = null;
+
+  constructor(config: ToggleConfig = {}) {
+    super();
+
+    this._config = {
+      width: config.width ?? 52,
+      height: config.height ?? 28,
+      onColor: config.onColor ?? 0x22cc22,
+      offColor: config.offColor ?? 0x666666,
+      handleColor: config.handleColor ?? 0xffffff,
+      handleRadius: config.handleRadius ?? 0, // 0 = auto
+      animationDuration: config.animationDuration ?? 200,
+    };
+
+    this._value = config.value ?? false;
+    this.onChange = config.onChange ?? null;
+
+    const customOn = resolveView(config.onView);
+    const customOff = resolveView(config.offView);
+    this._useCustomViews = !!(customOn || customOff);
+
+    if (this._useCustomViews) {
+      // Custom view mode: show/hide ON and OFF views
+      if (customOn) {
+        this._onView = customOn;
+        this._onView.visible = this._value;
+        this.addChild(this._onView);
+      }
+      if (customOff) {
+        this._offView = customOff;
+        this._offView.visible = !this._value;
+        this.addChild(this._offView);
+      }
+    } else {
+      // Graphics mode: track + sliding handle
+      const { width, height, handleColor } = this._config;
+      const handleRadius = this._config.handleRadius || (height / 2 - 3);
+      this._config.handleRadius = handleRadius;
+
+      this._trackGfx = new Graphics();
+      this.addChild(this._trackGfx);
+      this._drawTrack();
+
+      const handle = new Graphics();
+      handle.circle(0, 0, handleRadius).fill(handleColor);
+      handle.y = height / 2;
+      handle.x = this._value ? width - handleRadius - 3 : handleRadius + 3;
+      this._handle = handle;
+      this.addChild(handle);
+    }
+
+    // Interaction
+    this.eventMode = 'static';
+    this.cursor = 'pointer';
+    this.on('pointertap', this._onTap, this);
+  }
+
+  /** Current toggle state */
+  get value(): boolean {
+    return this._value;
+  }
+
+  set value(v: boolean) {
+    if (v === this._value) return;
+    this.forceSwitch(v);
+  }
+
+  /** Programmatically switch to a specific state with animation */
+  forceSwitch(value: boolean): void {
+    this._value = value;
+    this._animateToState();
+  }
+
+  /** React reconciler update hook */
+  updateConfig(changed: Record<string, any>): void {
+    if ('value' in changed) this.value = changed.value;
+    if ('onChange' in changed) this.onChange = changed.onChange;
+    if ('animationDuration' in changed) this._config.animationDuration = changed.animationDuration;
+  }
+
+  private _onTap(): void {
+    this._value = !this._value;
+    this._animateToState();
+    this.onChange?.(this._value);
+  }
+
+  private _animateToState(): void {
+    const duration = this._config.animationDuration;
+
+    if (this._useCustomViews) {
+      // Custom views: crossfade
+      if (this._onView) {
+        Tween.killTweensOf(this._onView);
+        if (this._value) {
+          this._onView.visible = true;
+          Tween.to(this._onView, { alpha: 1 }, duration);
+        } else {
+          Tween.to(this._onView, { alpha: 0 }, duration).then(() => {
+            if (this._onView) this._onView.visible = false;
+          });
+        }
+      }
+      if (this._offView) {
+        Tween.killTweensOf(this._offView);
+        if (!this._value) {
+          this._offView.visible = true;
+          Tween.to(this._offView, { alpha: 1 }, duration);
+        } else {
+          Tween.to(this._offView, { alpha: 0 }, duration).then(() => {
+            if (this._offView) this._offView.visible = false;
+          });
+        }
+      }
+    } else {
+      // Graphics mode: slide handle + recolor track
+      this._drawTrack();
+      if (this._handle) {
+        const { width } = this._config;
+        const handleRadius = this._config.handleRadius;
+        const targetX = this._value ? width - handleRadius - 3 : handleRadius + 3;
+        Tween.killTweensOf(this._handle);
+        Tween.to(this._handle, { x: targetX }, duration);
+      }
+    }
+  }
+
+  private _drawTrack(): void {
+    if (!this._trackGfx) return;
+    const { width, height, onColor, offColor } = this._config;
+    const radius = height / 2;
+    this._trackGfx.clear();
+    this._trackGfx.roundRect(0, 0, width, height, radius).fill(this._value ? onColor : offColor);
+  }
+
+  override destroy(options?: boolean | { children?: boolean; texture?: boolean; textureSource?: boolean }): void {
+    this.off('pointertap', this._onTap, this);
+    if (this._handle) Tween.killTweensOf(this._handle);
+    if (this._onView) Tween.killTweensOf(this._onView);
+    if (this._offView) Tween.killTweensOf(this._offView);
+    this.onChange = null;
+    super.destroy(options);
+  }
+}

package/src/ui/index.ts

@@ -4,7 +4,7 @@ export type { ViewInput } from './view';
 
 // ─── Engine UI Components ─────────────────────────────────
 export { FlexContainer } from './FlexContainer';
-export type { FlexContainerConfig, FlexDirection, JustifyContent, AlignItems, FlexItemConfig } from './FlexContainer';
+export type { FlexContainerConfig, FlexDirection, JustifyContent, AlignItems, AlignSelf, FlexItemConfig } from './FlexContainer';
 export { Button } from './Button';
 export type { ButtonConfig, ButtonState } from './Button';
 export { ProgressBar } from './ProgressBar';
@@ -25,3 +25,7 @@ export { Layout } from './Layout';
 export type { LayoutConfig, LayoutDirection, LayoutAlignment, LayoutAnchor } from './Layout';
 export { ScrollContainer } from './ScrollContainer';
 export type { ScrollContainerConfig, ScrollDirection } from './ScrollContainer';
+export { Slider } from './Slider';
+export type { SliderConfig } from './Slider';
+export { Toggle } from './Toggle';
+export type { ToggleConfig } from './Toggle';