@guinetik/gcanvas 1.0.0

package/types/state.d.ts

@@ -0,0 +1,251 @@
+/**
+ * GCanvas State Machine Types
+ * State management utilities for game objects.
+ * @module state
+ */
+
+// ==========================================================================
+// State Machine Configuration
+// ==========================================================================
+
+/** State transition definition */
+export interface StateTransition {
+  /** Target state to transition to */
+  target?: string;
+  /** Guard function - transition only if returns true */
+  guard?: (data?: any) => boolean;
+  /** Action to run before transition */
+  action?: (data?: any) => void;
+}
+
+/** Event handlers for a state */
+export interface StateEvents {
+  [triggerName: string]: string | StateTransition;
+}
+
+/** Individual state configuration */
+export interface StateConfig {
+  /** Duration in seconds before auto-transitioning (optional) */
+  duration?: number;
+  /** Next state to transition to after duration (for timed states) */
+  next?: string;
+  /** Called when entering this state */
+  enter?: (data?: any) => void;
+  /** Called each frame while in this state */
+  update?: (dt: number) => void;
+  /** Called when leaving this state */
+  exit?: (data?: any) => void;
+  /** Called when a timed state completes without a 'next' state */
+  onComplete?: () => void;
+  /** Event-based transitions */
+  on?: StateEvents;
+}
+
+/** State definitions object */
+export interface States {
+  [stateName: string]: StateConfig;
+}
+
+/** StateMachine constructor options */
+export interface StateMachineOptions {
+  /** Initial state name */
+  initial?: string;
+  /** State definitions */
+  states?: States;
+  /** Context object passed to callbacks (usually `this`) */
+  context?: any;
+}
+
+/** Phase definition for sequence-based state machines */
+export interface PhaseConfig {
+  /** Phase name */
+  name: string;
+  /** Phase duration in seconds */
+  duration: number;
+  /** Called when entering this phase */
+  enter?: () => void;
+  /** Called each frame during this phase */
+  update?: (dt: number) => void;
+  /** Called when leaving this phase */
+  exit?: () => void;
+}
+
+/** Options for StateMachine.fromSequence() */
+export interface SequenceOptions {
+  /** Whether to loop back to first phase after last */
+  loop?: boolean;
+  /** Called when sequence completes (if not looping) */
+  onComplete?: () => void;
+  /** Context object passed to callbacks */
+  context?: any;
+}
+
+// ==========================================================================
+// StateMachine Class
+// ==========================================================================
+
+/**
+ * Flexible state management for game objects.
+ * Manages states with enter/update/exit lifecycle callbacks.
+ * Supports timed transitions, sequential phases, and conditional triggers.
+ *
+ * @example
+ * // Basic usage
+ * const fsm = new StateMachine({
+ *   initial: 'idle',
+ *   states: {
+ *     idle: {
+ *       enter: () => console.log('Now idle'),
+ *       update: (dt) => { // per-frame logic },
+ *       exit: () => console.log('Leaving idle')
+ *     },
+ *     walking: {
+ *       enter: () => player.startWalkAnimation(),
+ *       update: (dt) => player.move(dt)
+ *     }
+ *   }
+ * });
+ *
+ * @example
+ * // Timed phase sequence
+ * const laser = new StateMachine({
+ *   initial: 'warning',
+ *   states: {
+ *     warning: { duration: 0.3, next: 'charging' },
+ *     charging: { duration: 0.2, next: 'active' },
+ *     active: {
+ *       duration: 0.4,
+ *       next: 'fade',
+ *       enter: () => { laser.canDamage = true; }
+ *     },
+ *     fade: {
+ *       duration: 0.2,
+ *       exit: () => { laser.destroy(); }
+ *     }
+ *   }
+ * });
+ */
+export class StateMachine {
+  /** State definitions */
+  states: States;
+
+  /** Current state name */
+  currentState: string | null;
+
+  /** Previous state name */
+  previousState: string | null;
+
+  /** Time spent in current state */
+  stateTime: number;
+
+  /** Context passed to state callbacks */
+  context: any;
+
+  /** Whether the state machine is paused */
+  paused: boolean;
+
+  /** Global state change callback */
+  onStateChange: ((newState: string, previousState: string | null, data?: any) => void) | null;
+
+  constructor(config?: StateMachineOptions);
+
+  /**
+   * Get the current state name
+   */
+  get state(): string | null;
+
+  /**
+   * Get the current state configuration
+   */
+  get currentStateConfig(): StateConfig | null;
+
+  /**
+   * Check if currently in a specific state
+   */
+  is(stateName: string): boolean;
+
+  /**
+   * Check if currently in any of the given states
+   */
+  isAny(...stateNames: string[]): boolean;
+
+  /**
+   * Add or update a state definition
+   * @returns this for chaining
+   */
+  addState(name: string, config: StateConfig): this;
+
+  /**
+   * Remove a state definition
+   * @returns this for chaining
+   */
+  removeState(name: string): this;
+
+  /**
+   * Transition to a new state
+   * @param newState - State to transition to
+   * @param data - Optional data passed to enter callback
+   * @returns True if transition occurred
+   */
+  setState(newState: string, data?: any): boolean;
+
+  /**
+   * Attempt to transition based on a trigger/event
+   * @param trigger - Trigger name to check against state transitions
+   * @param data - Optional data passed to callbacks
+   * @returns True if a transition occurred
+   */
+  trigger(trigger: string, data?: any): boolean;
+
+  /**
+   * Update the state machine (call each frame)
+   * @param dt - Delta time in seconds
+   */
+  update(dt: number): void;
+
+  /**
+   * Get normalized progress through current state (0-1)
+   * Only meaningful for states with a duration
+   */
+  get progress(): number;
+
+  /**
+   * Get remaining time in current state
+   * Only meaningful for states with a duration
+   */
+  get remaining(): number;
+
+  /**
+   * Check if current state is a timed state
+   */
+  get isTimed(): boolean;
+
+  /**
+   * Pause the state machine (stops update processing)
+   */
+  pause(): void;
+
+  /**
+   * Resume the state machine
+   */
+  resume(): void;
+
+  /**
+   * Reset to initial state or specific state
+   * @param state - State to reset to (defaults to first defined state)
+   */
+  reset(state?: string): void;
+
+  /**
+   * Create a state machine from a simple phase sequence.
+   * Convenience method for common "phase 1 → phase 2 → phase 3" patterns.
+   *
+   * @example
+   * const lightning = StateMachine.fromSequence([
+   *   { name: 'tracing', duration: 0.4, enter: () => startTrace() },
+   *   { name: 'active', duration: 0.3, enter: () => enableDamage() },
+   *   { name: 'fade', duration: 0.2, exit: () => destroy() }
+   * ]);
+   */
+  static fromSequence(phases: PhaseConfig[], options?: SequenceOptions): StateMachine;
+}

package/types/util.d.ts

@@ -0,0 +1,253 @@
+/**
+ * GCanvas Util Module
+ * Utility classes and functions for layout, positioning, z-ordering, and task management.
+ * @module util
+ */
+
+import { Point, LayoutResult } from './common';
+import { Transformable } from './shapes';
+
+// ==========================================================================
+// Z-Ordered Collection
+// ==========================================================================
+
+/** Options for ZOrderedCollection */
+export interface ZOrderedCollectionOptions {
+  /** Sort children by zIndex when rendering */
+  sortByZIndex?: boolean;
+}
+
+/**
+ * Z-ordered collection for managing child objects.
+ * Maintains rendering order based on zIndex property.
+ */
+export class ZOrderedCollection {
+  /** Array of child objects */
+  children: Transformable[];
+
+  constructor(options?: ZOrderedCollectionOptions);
+
+  /**
+   * Add an object to the collection.
+   * @param object - Object to add
+   */
+  add(object: Transformable): void;
+
+  /**
+   * Remove an object from the collection.
+   * @param object - Object to remove
+   * @returns Whether object was found and removed
+   */
+  remove(object: Transformable): boolean;
+
+  /** Remove all objects */
+  clear(): void;
+
+  /**
+   * Get children sorted by zIndex.
+   * @returns Sorted array of children
+   */
+  getSortedChildren(): Transformable[];
+
+  /** Move object to front (highest z-order) */
+  bringToFront(object: Transformable): void;
+
+  /** Move object to back (lowest z-order) */
+  sendToBack(object: Transformable): void;
+
+  /** Move object forward one z-level */
+  bringForward(object: Transformable): void;
+
+  /** Move object backward one z-level */
+  sendBackward(object: Transformable): void;
+}
+
+// ==========================================================================
+// Position Constants
+// ==========================================================================
+
+/**
+ * Position/anchor utilities with layout constants.
+ * Provides named constants for common anchor positions.
+ *
+ * @example
+ * const pos = Position.parse(Position.CENTER, canvasWidth, canvasHeight);
+ */
+export class Position {
+  static readonly TOP_LEFT: string;
+  static readonly TOP_CENTER: string;
+  static readonly TOP_RIGHT: string;
+  static readonly CENTER_LEFT: string;
+  static readonly CENTER: string;
+  static readonly CENTER_RIGHT: string;
+  static readonly BOTTOM_LEFT: string;
+  static readonly BOTTOM_CENTER: string;
+  static readonly BOTTOM_RIGHT: string;
+
+  /**
+   * Parse a position string into coordinates.
+   * @param position - Position string (e.g., "center", "top-left")
+   * @param containerWidth - Container width
+   * @param containerHeight - Container height
+   * @param objectWidth - Optional object width for centering
+   * @param objectHeight - Optional object height for centering
+   * @returns Calculated position
+   */
+  static parse(
+    position: string,
+    containerWidth: number,
+    containerHeight: number,
+    objectWidth?: number,
+    objectHeight?: number
+  ): Point;
+}
+
+// ==========================================================================
+// Task Manager
+// ==========================================================================
+
+/**
+ * Task manager for scheduling delayed operations.
+ */
+export class TaskManager {
+  /**
+   * Add a task to be executed after a delay.
+   * @param task - Function to execute
+   * @param delay - Delay in seconds (default: 0)
+   */
+  add(task: () => void, delay?: number): void;
+
+  /**
+   * Update all tasks.
+   * @param dt - Delta time in seconds
+   */
+  update(dt: number): void;
+
+  /** Clear all pending tasks */
+  clear(): void;
+}
+
+// ==========================================================================
+// Layout Functions
+// ==========================================================================
+
+/** Item with dimensions for layout calculations */
+export interface LayoutItem {
+  width?: number;
+  height?: number;
+  x?: number;
+  y?: number;
+}
+
+/** Options for applyLayout */
+export interface ApplyLayoutOptions {
+  /** X offset to apply to all positions */
+  offsetX?: number;
+  /** Y offset to apply to all positions */
+  offsetY?: number;
+  /** Transform function to apply to positions */
+  transform?: (pos: Point) => Point;
+}
+
+/** Options for horizontal/vertical layouts */
+export interface LinearLayoutOptions {
+  /** Space between items (default: 10) */
+  spacing?: number;
+  /** Padding around entire layout (default: 0) */
+  padding?: number;
+  /** Alignment: "start", "center", or "end" (default: "start") */
+  align?: 'start' | 'center' | 'end';
+  /** Position items relative to their centers (default: true) */
+  centerItems?: boolean;
+}
+
+/** Options for tile layout */
+export interface TileLayoutOptions {
+  /** Number of columns (default: 4) */
+  columns?: number;
+  /** Space between items (default: 10) */
+  spacing?: number;
+  /** Padding around entire layout (default: 0) */
+  padding?: number;
+  /** Position items relative to their centers (default: true) */
+  centerItems?: boolean;
+}
+
+/** Options for grid layout */
+export interface GridLayoutOptions {
+  /** Number of columns */
+  columns?: number;
+  /** Number of rows */
+  rows?: number;
+  /** Fixed cell width */
+  cellWidth?: number;
+  /** Fixed cell height */
+  cellHeight?: number;
+  /** Space between cells (default: 10) */
+  spacing?: number;
+  /** Padding around entire layout (default: 0) */
+  padding?: number;
+  /** Position items relative to their centers (default: true) */
+  centerItems?: boolean;
+}
+
+/**
+ * Apply calculated positions to items.
+ * @param items - Array of objects to position (must have x, y properties)
+ * @param positions - Array of position objects from layout functions
+ * @param options - Options for applying positions
+ * @returns The items with updated positions
+ */
+export function applyLayout<T extends LayoutItem>(
+  items: T[],
+  positions: Point[],
+  options?: ApplyLayoutOptions
+): T[];
+
+/**
+ * Create a horizontal layout (items arranged left to right).
+ * @param items - Array of objects with width and height
+ * @param options - Layout options
+ * @returns Layout result with positions and dimensions
+ *
+ * @example
+ * const result = horizontalLayout(buttons, { spacing: 20 });
+ * applyLayout(buttons, result.positions);
+ */
+export function horizontalLayout(
+  items: LayoutItem[],
+  options?: LinearLayoutOptions
+): LayoutResult;
+
+/**
+ * Create a vertical layout (items arranged top to bottom).
+ * @param items - Array of objects with width and height
+ * @param options - Layout options
+ * @returns Layout result with positions and dimensions
+ */
+export function verticalLayout(
+  items: LayoutItem[],
+  options?: LinearLayoutOptions
+): LayoutResult;
+
+/**
+ * Create a tile layout (items in a grid with fixed columns).
+ * @param items - Array of objects with width and height
+ * @param options - Layout options
+ * @returns Layout result with positions and dimensions
+ */
+export function tileLayout(
+  items: LayoutItem[],
+  options?: TileLayoutOptions
+): LayoutResult;
+
+/**
+ * Create a flexible grid layout.
+ * @param items - Array of objects with width and height
+ * @param options - Layout options
+ * @returns Layout result with positions and dimensions
+ */
+export function gridLayout(
+  items: LayoutItem[],
+  options?: GridLayoutOptions
+): LayoutResult;

package/vite.config.js

@@ -0,0 +1,50 @@
+import { defineConfig } from "vite";
+import path from "path";
+
+const libEntry = path.resolve(__dirname, "src/index.js");
+
+export default defineConfig(({ mode }) => {
+  const isDebug = mode === "debug";
+
+  return {
+    server: {
+      port: 9195,
+      strictPort: true, // Don't try other ports if 9195 is in use
+    },
+    build: {
+      lib: {
+        entry: libEntry,
+        name: "GCanvas",
+        formats: isDebug ? ["umd"] : ["umd", "es"],
+        fileName: (format) => {
+          if (isDebug) return "gcanvas.debug.js";
+          return `gcanvas.${format}.js`;
+        },
+      },
+      minify: isDebug ? false : "terser",
+      terserOptions: {
+        compress: true,
+        mangle: true,
+        format: {
+          comments: false,
+        },
+      },
+      outDir: "dist",
+      emptyOutDir: true,
+      rollupOptions: {
+        output: [
+          {
+            format: "umd",
+            entryFileNames: "gcanvas.umd.js",
+            name: "GCanvas",
+            globals: {},
+          },
+          {
+            format: "es",
+            entryFileNames: "gcanvas.es.js",
+          },
+        ],
+      },
+    },
+  };
+});

package/vitest.config.js

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./test/setup.js'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});