bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/webgl/lib/utils/easings.ts

@@ -0,0 +1,240 @@
+/**
+ * Easing Functions
+ *
+ * A complete collection of easing curves for animations.
+ * All functions take a progress value (0-1) and return an eased value (0-1).
+ *
+ * @see https://easings.net for visual references
+ *
+ * @example
+ * ```ts
+ * import { easings, type EasingName } from '@/utils/easings'
+ *
+ * // Direct usage
+ * const eased = easings.easeOutCubic(0.5)
+ *
+ * // With a variable easing name
+ * const easingName: EasingName = 'easeInOutQuart'
+ * const value = easings[easingName](progress)
+ * ```
+ *
+ * ## Choosing an Easing
+ *
+ * | Category | Use Case |
+ * |----------|----------|
+ * | `easeOut*` | UI feedback, appearing elements (most common) |
+ * | `easeIn*` | Exiting elements, building tension |
+ * | `easeInOut*` | State transitions, loading indicators |
+ * | `*Cubic/Quart` | Natural, balanced motion |
+ * | `*Expo` | Dramatic, snappy motion |
+ * | `*Elastic/Bounce` | Playful, attention-grabbing |
+ */
+
+const pow = Math.pow
+const sqrt = Math.sqrt
+const sin = Math.sin
+const cos = Math.cos
+const PI = Math.PI
+
+// Easing constants
+const c1 = 1.70158
+const c2 = c1 * 1.525
+const c3 = c1 + 1
+const c4 = (2 * PI) / 3
+const c5 = (2 * PI) / 4.5
+
+/** Bounce out helper (used by bounce easings) */
+const bounceOut = (x: number): number => {
+  const n1 = 7.5625
+  const d1 = 2.75
+
+  if (x < 1 / d1) {
+    return n1 * x * x
+  }
+  if (x < 2 / d1) {
+    return n1 * (x - 1.5 / d1) * x + 0.75
+  }
+  if (x < 2.5 / d1) {
+    return n1 * (x - 2.25 / d1) * x + 0.9375
+  }
+  return n1 * (x - 2.625 / d1) * x + 0.984375
+}
+
+/**
+ * Collection of easing functions.
+ * Each function takes progress (0-1) and returns eased value (0-1).
+ */
+export const easings = {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Linear (no easing)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** No easing - constant speed */
+  linear: (x: number): number => x,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Quadratic (power of 2)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Slow start */
+  easeInQuad: (x: number): number => x * x,
+
+  /** Slow end */
+  easeOutQuad: (x: number): number => 1 - (1 - x) * (1 - x),
+
+  /** Slow start and end */
+  easeInOutQuad: (x: number): number =>
+    x < 0.5 ? 2 * x * x : 1 - pow(-2 * x + 2, 2) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Cubic (power of 3) - Most commonly used
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Slow start, natural feel */
+  easeInCubic: (x: number): number => x * x * x,
+
+  /** Slow end, natural feel - great for UI interactions */
+  easeOutCubic: (x: number): number => 1 - pow(1 - x, 3),
+
+  /** Smooth start and end - great for transitions */
+  easeInOutCubic: (x: number): number =>
+    x < 0.5 ? 4 * x * x * x : 1 - pow(-2 * x + 2, 3) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Quartic (power of 4)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Slower start than cubic */
+  easeInQuart: (x: number): number => x * x * x * x,
+
+  /** Slower end than cubic */
+  easeOutQuart: (x: number): number => 1 - pow(1 - x, 4),
+
+  /** More pronounced ease than cubic */
+  easeInOutQuart: (x: number): number =>
+    x < 0.5 ? 8 * x * x * x * x : 1 - pow(-2 * x + 2, 4) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Quintic (power of 5)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Very slow start */
+  easeInQuint: (x: number): number => x * x * x * x * x,
+
+  /** Very slow end */
+  easeOutQuint: (x: number): number => 1 - pow(1 - x, 5),
+
+  /** Very pronounced ease */
+  easeInOutQuint: (x: number): number =>
+    x < 0.5 ? 16 * x * x * x * x * x : 1 - pow(-2 * x + 2, 5) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Sinusoidal - Gentle, wave-like
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Gentle slow start */
+  easeInSine: (x: number): number => 1 - cos((x * PI) / 2),
+
+  /** Gentle slow end */
+  easeOutSine: (x: number): number => sin((x * PI) / 2),
+
+  /** Gentle ease both ends */
+  easeInOutSine: (x: number): number => -(cos(PI * x) - 1) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Exponential - Dramatic, snappy
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Dramatic slow start - almost stationary then fast */
+  easeInExpo: (x: number): number => (x === 0 ? 0 : pow(2, 10 * x - 10)),
+
+  /** Dramatic slow end - fast then almost stops */
+  easeOutExpo: (x: number): number => (x === 1 ? 1 : 1 - pow(2, -10 * x)),
+
+  /** Dramatic both ends */
+  easeInOutExpo: (x: number): number => {
+    if (x === 0) return 0
+    if (x === 1) return 1
+    if (x < 0.5) return pow(2, 20 * x - 10) / 2
+    return (2 - pow(2, -20 * x + 10)) / 2
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Circular - Based on circle quarter
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Circular slow start */
+  easeInCirc: (x: number): number => 1 - sqrt(1 - pow(x, 2)),
+
+  /** Circular slow end */
+  easeOutCirc: (x: number): number => sqrt(1 - pow(x - 1, 2)),
+
+  /** Circular both ends */
+  easeInOutCirc: (x: number): number =>
+    x < 0.5
+      ? (1 - sqrt(1 - pow(2 * x, 2))) / 2
+      : (sqrt(1 - pow(-2 * x + 2, 2)) + 1) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Back - Overshoots then returns
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Pulls back before accelerating */
+  easeInBack: (x: number): number => c3 * x * x * x - c1 * x * x,
+
+  /** Overshoots target then settles */
+  easeOutBack: (x: number): number =>
+    1 + c3 * pow(x - 1, 3) + c1 * pow(x - 1, 2),
+
+  /** Pulls back, overshoots, settles */
+  easeInOutBack: (x: number): number =>
+    x < 0.5
+      ? (pow(2 * x, 2) * ((c2 + 1) * 2 * x - c2)) / 2
+      : (pow(2 * x - 2, 2) * ((c2 + 1) * (x * 2 - 2) + c2) + 2) / 2,
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Elastic - Spring-like oscillation
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Wobbles at start */
+  easeInElastic: (x: number): number => {
+    if (x === 0) return 0
+    if (x === 1) return 1
+    return -pow(2, 10 * x - 10) * sin((x * 10 - 10.75) * c4)
+  },
+
+  /** Wobbles at end - great for attention */
+  easeOutElastic: (x: number): number => {
+    if (x === 0) return 0
+    if (x === 1) return 1
+    return pow(2, -10 * x) * sin((x * 10 - 0.75) * c4) + 1
+  },
+
+  /** Wobbles both ends */
+  easeInOutElastic: (x: number): number => {
+    if (x === 0) return 0
+    if (x === 1) return 1
+    if (x < 0.5) return -(pow(2, 20 * x - 10) * sin((20 * x - 11.125) * c5)) / 2
+    return (pow(2, -20 * x + 10) * sin((20 * x - 11.125) * c5)) / 2 + 1
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Bounce - Ball bouncing effect
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Bounces at start */
+  easeInBounce: (x: number): number => 1 - bounceOut(1 - x),
+
+  /** Bounces at end - like a ball settling */
+  easeOutBounce: bounceOut,
+
+  /** Bounces both ends */
+  easeInOutBounce: (x: number): number =>
+    x < 0.5 ? (1 - bounceOut(1 - 2 * x)) / 2 : (1 + bounceOut(2 * x - 1)) / 2,
+} as const
+
+/** All available easing function names */
+export type EasingName = keyof typeof easings
+
+/** An easing function signature */
+export type EasingFunction = (progress: number) => number

package/packages/create-basement-app/templates/webgl/lib/utils/fetch.ts

@@ -0,0 +1,84 @@
+/**
+ * Fetch Utilities
+ *
+ * Wrapper around fetch that adds timeout protection to prevent hanging requests.
+ * Use this for all external API calls to improve reliability.
+ */
+
+export interface FetchWithTimeoutOptions extends RequestInit {
+  timeout?: number // Timeout in milliseconds (default: 10000ms)
+}
+
+/**
+ * Fetch with automatic timeout protection
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options with optional timeout
+ * @returns Promise<Response>
+ * @throws AbortError if timeout is reached
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const response = await fetchWithTimeout('https://api.example.com/data', {
+ *     timeout: 5000, // 5 second timeout
+ *     method: 'POST',
+ *     body: JSON.stringify(data)
+ *   })
+ *   const result = await response.json()
+ * } catch (error) {
+ *   if (error.name === 'AbortError') {
+ *     console.error('Request timed out')
+ *   }
+ * }
+ * ```
+ */
+export async function fetchWithTimeout(
+  url: string,
+  options: FetchWithTimeoutOptions = {}
+): Promise<Response> {
+  const { timeout = 10000, signal: externalSignal, ...fetchOptions } = options
+
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeout)
+
+  // If an external signal is provided, listen to it and abort our controller
+  if (externalSignal) {
+    externalSignal.addEventListener("abort", () => controller.abort())
+  }
+
+  try {
+    const response = await fetch(url, {
+      ...fetchOptions,
+      signal: controller.signal,
+    })
+    return response
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Fetch JSON with timeout protection
+ *
+ * Convenience wrapper that automatically parses JSON and handles errors
+ *
+ * @example
+ * ```ts
+ * const data = await fetchJSON<{ name: string }>('https://api.example.com/user', {
+ *   timeout: 5000
+ * })
+ * ```
+ */
+export async function fetchJSON<T = unknown>(
+  url: string,
+  options: FetchWithTimeoutOptions = {}
+): Promise<T> {
+  const response = await fetchWithTimeout(url, options)
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+  }
+
+  return response.json() as Promise<T>
+}

package/packages/create-basement-app/templates/webgl/lib/utils/math.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for math utilities
+ *
+ * Run with: bun test lib/utils/math.test.ts
+ */
+
+import { describe, expect, it } from "bun:test"
+import {
+  clamp,
+  degToRad,
+  distance,
+  lerp,
+  mapRange,
+  modulo,
+  normalize,
+  radToDeg,
+  roundTo,
+  truncate,
+} from "./math"
+
+describe("clamp", () => {
+  it("should return input when within bounds", () => {
+    expect(clamp(0, 50, 100)).toBe(50)
+    expect(clamp(-10, 0, 10)).toBe(0)
+  })
+
+  it("should return min when input is below min", () => {
+    expect(clamp(0, -5, 100)).toBe(0)
+    expect(clamp(10, 5, 20)).toBe(10)
+  })
+
+  it("should return max when input is above max", () => {
+    expect(clamp(0, 150, 100)).toBe(100)
+    expect(clamp(10, 25, 20)).toBe(20)
+  })
+
+  it("should handle edge cases", () => {
+    expect(clamp(0, 0, 100)).toBe(0)
+    expect(clamp(0, 100, 100)).toBe(100)
+  })
+})
+
+describe("lerp", () => {
+  it("should return start when amount is 0", () => {
+    expect(lerp(0, 100, 0)).toBe(0)
+    expect(lerp(-50, 50, 0)).toBe(-50)
+  })
+
+  it("should return end when amount is 1", () => {
+    expect(lerp(0, 100, 1)).toBe(100)
+    expect(lerp(-50, 50, 1)).toBe(50)
+  })
+
+  it("should return midpoint when amount is 0.5", () => {
+    expect(lerp(0, 100, 0.5)).toBe(50)
+    expect(lerp(-100, 100, 0.5)).toBe(0)
+  })
+
+  it("should handle intermediate values", () => {
+    expect(lerp(0, 100, 0.25)).toBe(25)
+    expect(lerp(0, 100, 0.75)).toBe(75)
+  })
+
+  it("should extrapolate beyond 0-1 range", () => {
+    expect(lerp(0, 100, 1.5)).toBe(150)
+    expect(lerp(0, 100, -0.5)).toBe(-50)
+  })
+})
+
+describe("mapRange", () => {
+  it("should map value from one range to another", () => {
+    expect(mapRange(0, 100, 50, 0, 1)).toBe(0.5)
+    expect(mapRange(0, 1000, 500, 0, 1)).toBe(0.5)
+  })
+
+  it("should handle inverted output ranges", () => {
+    expect(mapRange(0, 100, 50, 1, 0)).toBe(0.5)
+    expect(mapRange(0, 100, 0, 1, 0)).toBe(1)
+    expect(mapRange(0, 100, 100, 1, 0)).toBe(0)
+  })
+
+  it("should not clamp by default", () => {
+    expect(mapRange(0, 100, 150, 0, 1)).toBe(1.5)
+    expect(mapRange(0, 100, -50, 0, 1)).toBe(-0.5)
+  })
+
+  it("should clamp when shouldClamp is true", () => {
+    expect(mapRange(0, 100, 150, 0, 1, true)).toBe(1)
+    expect(mapRange(0, 100, -50, 0, 1, true)).toBe(0)
+  })
+
+  it("should clamp inverted ranges correctly", () => {
+    expect(mapRange(0, 100, 150, 1, 0, true)).toBe(0)
+    expect(mapRange(0, 100, -50, 1, 0, true)).toBe(1)
+  })
+})
+
+describe("truncate", () => {
+  it("should truncate to specified decimal places", () => {
+    expect(truncate(1.23456789, 2)).toBe(1.23)
+    expect(truncate(1.23456789, 3)).toBe(1.235)
+    expect(truncate(1.23456789, 4)).toBe(1.2346)
+  })
+
+  it("should handle 0 decimal places", () => {
+    expect(truncate(1.23456789, 0)).toBe(1)
+    expect(truncate(3.9, 0)).toBe(4)
+  })
+
+  it("should handle already truncated numbers", () => {
+    expect(truncate(3.14, 2)).toBe(3.14)
+    expect(truncate(5, 2)).toBe(5)
+  })
+})
+
+describe("modulo", () => {
+  it("should work like JavaScript % for positive numbers", () => {
+    expect(modulo(5, 3)).toBe(2)
+    expect(modulo(10, 4)).toBe(2)
+  })
+
+  it("should handle negative dividends correctly (true modulo)", () => {
+    expect(modulo(-1, 3)).toBe(2)
+    expect(modulo(-5, 3)).toBe(1)
+    expect(modulo(-10, 4)).toBe(2)
+  })
+
+  it("should return input when divisor is 0", () => {
+    expect(modulo(5, 0)).toBe(5)
+    expect(modulo(-5, 0)).toBe(-5)
+  })
+
+  it("should return NaN for negative divisors", () => {
+    expect(modulo(5, -3)).toBeNaN()
+  })
+
+  it("should wrap array indices correctly", () => {
+    const length = 5
+    expect(modulo(-1, length)).toBe(4)
+    expect(modulo(5, length)).toBe(0)
+    expect(modulo(7, length)).toBe(2)
+  })
+})
+
+describe("roundTo", () => {
+  it("should round to the nearest multiple", () => {
+    expect(roundTo(23, 10)).toBe(20)
+    expect(roundTo(27, 10)).toBe(30)
+    expect(roundTo(25, 10)).toBe(30)
+  })
+
+  it("should handle decimal multiples", () => {
+    expect(roundTo(0.23, 0.1)).toBeCloseTo(0.2, 10)
+    expect(roundTo(0.27, 0.1)).toBeCloseTo(0.3, 10)
+  })
+
+  it("should handle exact multiples", () => {
+    expect(roundTo(20, 10)).toBe(20)
+    expect(roundTo(0.5, 0.5)).toBe(0.5)
+  })
+})
+
+describe("degToRad", () => {
+  it("should convert degrees to radians", () => {
+    expect(degToRad(0)).toBe(0)
+    expect(degToRad(180)).toBeCloseTo(Math.PI, 10)
+    expect(degToRad(90)).toBeCloseTo(Math.PI / 2, 10)
+    expect(degToRad(360)).toBeCloseTo(Math.PI * 2, 10)
+  })
+
+  it("should handle negative degrees", () => {
+    expect(degToRad(-90)).toBeCloseTo(-Math.PI / 2, 10)
+  })
+})
+
+describe("radToDeg", () => {
+  it("should convert radians to degrees", () => {
+    expect(radToDeg(0)).toBe(0)
+    expect(radToDeg(Math.PI)).toBeCloseTo(180, 10)
+    expect(radToDeg(Math.PI / 2)).toBeCloseTo(90, 10)
+    expect(radToDeg(Math.PI * 2)).toBeCloseTo(360, 10)
+  })
+
+  it("should handle negative radians", () => {
+    expect(radToDeg(-Math.PI / 2)).toBeCloseTo(-90, 10)
+  })
+})
+
+describe("distance", () => {
+  it("should calculate distance between two points", () => {
+    expect(distance(0, 0, 3, 4)).toBe(5)
+    expect(distance(0, 0, 0, 0)).toBe(0)
+  })
+
+  it("should handle negative coordinates", () => {
+    expect(distance(-3, -4, 0, 0)).toBe(5)
+    expect(distance(-1, -1, 1, 1)).toBeCloseTo(Math.sqrt(8), 10)
+  })
+
+  it("should be symmetric", () => {
+    expect(distance(0, 0, 3, 4)).toBe(distance(3, 4, 0, 0))
+  })
+})
+
+describe("normalize", () => {
+  it("should normalize value to 0-1 range", () => {
+    expect(normalize(0, 100, 50)).toBe(0.5)
+    expect(normalize(0, 100, 0)).toBe(0)
+    expect(normalize(0, 100, 100)).toBe(1)
+  })
+
+  it("should handle non-zero min values", () => {
+    expect(normalize(50, 100, 75)).toBe(0.5)
+    expect(normalize(-100, 100, 0)).toBe(0.5)
+  })
+
+  it("should extrapolate outside range", () => {
+    expect(normalize(0, 100, 150)).toBe(1.5)
+    expect(normalize(0, 100, -50)).toBe(-0.5)
+  })
+})