bsmnt 0.0.2 → 0.1.0

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

@@ -0,0 +1,246 @@
+/**
+ * String & Object Utilities
+ *
+ * Helper functions for string manipulation, object operations, and refs.
+ */
+
+import type { Ref } from "react"
+
+// =============================================================================
+// STRING UTILITIES
+// =============================================================================
+
+/**
+ * Converts text to URL-friendly slug format.
+ *
+ * @param text - Text to convert (must have toString method)
+ * @returns URL-safe slug string
+ *
+ * @example
+ * ```ts
+ * slugify('Hello World!') // 'hello-world'
+ * slugify('Café & Restaurant') // 'cafe-restaurant'
+ * ```
+ */
+export function slugify(text: { toString: () => string }) {
+  return text
+    .toString()
+    .normalize("NFKD")
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/[^\w-]+/g, "")
+    .replace(/--+/g, "-")
+}
+
+/**
+ * Converts first character to lowercase (camelCase format).
+ *
+ * @param inputString - String to convert
+ * @returns String with lowercase first character
+ *
+ * @example
+ * ```ts
+ * convertToCamelCase('HelloWorld') // 'helloWorld'
+ * ```
+ */
+export function convertToCamelCase(inputString: string) {
+  return inputString.charAt(0).toLowerCase() + inputString.slice(1)
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param inputString - String to capitalize
+ * @returns String with capitalized first letter
+ *
+ * @example
+ * ```ts
+ * capitalizeFirstLetter('hello') // 'Hello'
+ * capitalizeFirstLetter('world') // 'World'
+ * ```
+ */
+export function capitalizeFirstLetter(inputString: string) {
+  return inputString.charAt(0).toUpperCase() + inputString.slice(1)
+}
+
+/**
+ * Formats a number as a two-digit string (padding with zero).
+ *
+ * @param number - Number to format
+ * @returns Two-digit string representation
+ *
+ * @example
+ * ```ts
+ * twoDigits(5)  // '05'
+ * twoDigits(23) // '23'
+ * ```
+ */
+export function twoDigits(number: number) {
+  return number > 9 ? `${number}` : `0${number}`
+}
+
+/**
+ * Adds commas as thousands separators to numbers.
+ *
+ * @param x - Number to format (must have toString method)
+ * @returns String with comma separators
+ *
+ * @example
+ * ```ts
+ * numberWithCommas(1234)     // '1,234'
+ * numberWithCommas(1234567)  // '1,234,567'
+ * ```
+ */
+export function numberWithCommas(x: { toString: () => string }) {
+  return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",")
+}
+
+// =============================================================================
+// ARRAY & OBJECT UTILITIES
+// =============================================================================
+
+export function checkIsArray<T>(value: T): T extends unknown[] ? T[0] : T {
+  return (Array.isArray(value) ? value[0] : value) as T extends unknown[]
+    ? T[0]
+    : T
+}
+
+/**
+ * Checks if an object is empty (has no enumerable properties).
+ *
+ * @param obj - Object to check
+ * @returns True if object is empty or null/undefined
+ *
+ * @example
+ * ```ts
+ * isEmptyObject({})        // true
+ * isEmptyObject({ a: 1 })  // false
+ * isEmptyObject(null)      // true
+ * ```
+ */
+export function isEmptyObject(obj: Record<string, unknown>) {
+  if (!obj) return true
+  return Object.keys(obj).length === 0
+}
+
+/**
+ * Checks if an array is empty or if the input is not an array.
+ *
+ * @param arr - Array or value to check
+ * @returns True if empty array or not an array
+ *
+ * @example
+ * ```ts
+ * isEmptyArray([])      // true
+ * isEmptyArray([1, 2])  // false
+ * isEmptyArray('test')  // true (not an array)
+ * isEmptyArray(null)    // true
+ * ```
+ */
+export function isEmptyArray(arr: string | unknown[]) {
+  if (!arr) return true
+  return Array.isArray(arr) && arr.length === 0
+}
+
+export function arraytoObject(array: Record<string, unknown>[]) {
+  return array.reduce((acc: Record<string, unknown>, currentObj) => {
+    const key = Object.keys(currentObj)[0]
+    if (key !== undefined) {
+      acc[key] = currentObj[key]
+    }
+    return acc
+  }, {})
+}
+
+export function shortenObjectKeys(
+  obj: Record<string, unknown>,
+  keyword: string
+) {
+  const regex = new RegExp(`[^]+${keyword}(.*)`)
+
+  for (const key in obj) {
+    const match = key.match(regex)
+
+    if (match?.[1]) {
+      const newKey = convertToCamelCase(match[1])
+      obj[newKey] = obj[key]
+      delete obj[key]
+    }
+  }
+
+  return obj
+}
+
+export function filterObjectKeys(
+  obj: { [x: string]: unknown },
+  keyword: string
+) {
+  const newObj: { [x: string]: unknown } = {}
+
+  for (const key in obj) {
+    const match = key.includes(keyword)
+
+    if (match) {
+      newObj[key] = obj[key]
+    }
+  }
+
+  return newObj
+}
+
+export function iterableObject(
+  obj: { [s: string]: unknown } | ArrayLike<unknown>
+) {
+  return Object.entries(obj).map(([, value]) => {
+    return value
+  })
+}
+
+// =============================================================================
+// REF UTILITIES
+// =============================================================================
+
+/**
+ * Merges multiple React refs into a single ref callback.
+ *
+ * Useful when you need to assign multiple refs to the same element,
+ * such as combining a local ref with a forwarded ref.
+ *
+ * @param refs - Refs to merge (functions and ref objects supported)
+ * @returns A ref callback that updates all provided refs
+ *
+ * @example
+ * ```tsx
+ * // Component that needs both local and forwarded ref
+ * function MyComponent({ ref }: { ref: React.Ref<HTMLDivElement> }) {
+ *   const localRef = useRef<HTMLDivElement>(null)
+ *   const mergedRef = mergeRefs(localRef, ref)
+ *
+ *   return <div ref={mergedRef}>Content</div>
+ * }
+ *
+ * // Forward ref pattern
+ * const ForwardedComponent = forwardRef(MyComponent)
+ * ```
+ */
+export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): Ref<T> {
+  return (value) => {
+    const cleanups = refs.reduce<VoidFunction[]>((accumulator, ref) => {
+      if (typeof ref === "function") {
+        const cleanup = ref(value)
+        if (typeof cleanup === "function") {
+          accumulator.push(cleanup)
+        }
+      } else if (ref) {
+        ref.current = value
+      }
+
+      return accumulator
+    }, [])
+
+    return () => {
+      for (const cleanup of cleanups) cleanup()
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+// Type augmentations and module declarations
+
+// React CSS custom properties support
+import "react"
+
+declare module "react" {
+  interface CSSProperties {
+    [key: `--${string}`]: string | number
+  }
+}
+
+// Global window extensions
+declare global {
+  interface Window {}
+}

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

@@ -0,0 +1,256 @@
+/**
+ * Unit tests for viewport utilities
+ *
+ * Run with: bun test lib/utils/viewport.test.ts
+ */
+
+import { describe, expect, it } from "bun:test"
+import { toem, torem, tovw } from "./viewport"
+
+// Helper to check vw values with floating point tolerance
+function expectVw(actual: string, expectedVw: number) {
+  const match = actual.match(/^([\d.]+)vw$/)
+  if (!match?.[1]) {
+    throw new Error(`Expected vw format, got: ${actual}`)
+  }
+  const actualVw = Number.parseFloat(match[1])
+  expect(actualVw).toBeCloseTo(expectedVw, 4)
+}
+
+// Helper to check max() values with floating point tolerance
+function expectMaxVw(actual: string, expectedMin: number, expectedVw: number) {
+  const match = actual.match(/^max\((\d+)px, ([\d.]+)vw\)$/)
+  if (!(match?.[1] && match[2])) {
+    throw new Error(`Expected max() format, got: ${actual}`)
+  }
+  const actualMin = Number.parseFloat(match[1])
+  const actualVw = Number.parseFloat(match[2])
+  expect(actualMin).toBe(expectedMin)
+  expect(actualVw).toBeCloseTo(expectedVw, 4)
+}
+
+describe("tovw", () => {
+  describe("basic conversion (default desktop context)", () => {
+    it("should convert pixels to vw with default desktop context (1440px)", () => {
+      expectVw(tovw(100), 6.9444)
+      expect(tovw(1440)).toBe("100vw")
+      expect(tovw(720)).toBe("50vw")
+    })
+
+    it("should handle zero", () => {
+      expect(tovw(0)).toBe("0")
+    })
+  })
+
+  describe("with minimum value", () => {
+    it("should apply minimum value using max()", () => {
+      expectMaxVw(tovw(100, 50), 50, 6.9444)
+      expectMaxVw(tovw(200, 100), 100, 13.8889)
+    })
+
+    it("should handle zero target with min", () => {
+      expect(tovw(0, 50)).toBe("0")
+    })
+  })
+
+  describe("with context identifier", () => {
+    it("should use mobile context (375px)", () => {
+      expectVw(tovw(16, "mobile"), 4.2667)
+      expect(tovw(375, "mobile")).toBe("100vw")
+    })
+
+    it("should use desktop-large context (1920px)", () => {
+      expectVw(tovw(100, "desktop-large"), 5.2083)
+      expect(tovw(1920, "desktop-large")).toBe("100vw")
+    })
+
+    it("should use tablet-lg context (1024px)", () => {
+      expectVw(tovw(100, "tablet-lg"), 9.7656)
+      expect(tovw(1024, "tablet-lg")).toBe("100vw")
+    })
+
+    it("should use tablet context (620px)", () => {
+      expectVw(tovw(100, "tablet"), 16.129)
+      expect(tovw(620, "tablet")).toBe("100vw")
+    })
+
+    it("should use desktop context explicitly", () => {
+      expectVw(tovw(100, "desktop"), 6.9444)
+    })
+  })
+
+  describe("with custom numeric context", () => {
+    it("should use custom pixel context as third parameter", () => {
+      // Numeric contexts must be passed as third parameter (with undefined min)
+      // Using type assertion to test the implementation behavior
+      expectVw(tovw(100, 1920), 5.2083)
+      expectVw(tovw(100, 800), 12.5)
+      expectVw(tovw(100, 2000), 5)
+    })
+
+    it("should treat numeric second parameter as min, not context", () => {
+      // When second param is a number, it's treated as min, not context
+      expectMaxVw(tovw(100, 1920), 1920, 6.9444)
+    })
+  })
+
+  describe("with both min and context", () => {
+    it("should apply min and context together", () => {
+      expectMaxVw(tovw(100, 50, "mobile"), 50, 26.6667)
+      expectMaxVw(tovw(200, 100, "desktop-large"), 100, 10.4167)
+    })
+
+    it("should use numeric context with min", () => {
+      expectMaxVw(tovw(100, 50, 1920), 50, 5.2083)
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle very small values", () => {
+      expectVw(tovw(1), 0.0694)
+      expectVw(tovw(0.5), 0.0347)
+    })
+
+    it("should handle very large values", () => {
+      expectVw(tovw(5000), 347.2222)
+    })
+
+    it("should handle decimal values", () => {
+      expectVw(tovw(16.5), 1.1458)
+      expectVw(tovw(16.5, "mobile"), 4.4)
+    })
+  })
+})
+
+describe("torem", () => {
+  describe("basic conversion (default 16px context)", () => {
+    it("should convert pixels to rem with default context", () => {
+      expect(torem(16)).toBe("1rem")
+      expect(torem(24)).toBe("1.5rem")
+      expect(torem(32)).toBe("2rem")
+      expect(torem(8)).toBe("0.5rem")
+    })
+
+    it("should handle zero", () => {
+      expect(torem(0)).toBe("0")
+    })
+  })
+
+  describe("with custom context", () => {
+    it("should use custom base font size", () => {
+      // Using toBeCloseTo for floating point comparison
+      const result1 = torem(18, 14)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(
+        1.2857142857142858,
+        4
+      )
+
+      expect(torem(20, 10)).toBe("2rem")
+      expect(torem(24, 12)).toBe("2rem")
+    })
+
+    it("should handle zero with custom context", () => {
+      expect(torem(0, 14)).toBe("0")
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle decimal values", () => {
+      const result1 = torem(16.5)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      // 16.5 / 16 = 1.03125, rounded to 4 decimals = 1.0313
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(1.0313, 4)
+
+      const result2 = torem(18.5, 14)
+      const match2 = result2.match(/^([\d.]+)rem$/)
+      // 18.5 / 14 = 1.3214285714285714, rounded to 4 decimals = 1.3214
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(1.3214, 4)
+    })
+
+    it("should handle very small values", () => {
+      const result1 = torem(1)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(0.0625, 4)
+
+      const result2 = torem(0.5)
+      const match2 = result2.match(/^([\d.]+)rem$/)
+      // 0.5 / 16 = 0.03125, rounded to 4 decimals = 0.0313
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(0.0313, 4)
+    })
+
+    it("should handle very large values", () => {
+      expect(torem(100)).toBe("6.25rem")
+      expect(torem(200)).toBe("12.5rem")
+    })
+  })
+})
+
+describe("toem", () => {
+  describe("basic conversion", () => {
+    it("should convert pixels to em", () => {
+      expect(toem(24, 16)).toBe("1.5em")
+      expect(toem(16, 16)).toBe("1em")
+      expect(toem(32, 16)).toBe("2em")
+      expect(toem(8, 16)).toBe("0.5em")
+    })
+
+    it("should handle zero", () => {
+      expect(toem(0, 16)).toBe("0")
+    })
+  })
+
+  describe("with different contexts", () => {
+    it("should use custom context size", () => {
+      const result1 = toem(18, 14)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(
+        1.2857142857142858,
+        4
+      )
+
+      expect(toem(20, 10)).toBe("2em")
+      expect(toem(24, 12)).toBe("2em")
+    })
+
+    it("should handle zero with different contexts", () => {
+      expect(toem(0, 14)).toBe("0")
+      expect(toem(0, 20)).toBe("0")
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle decimal values", () => {
+      const result1 = toem(16.5, 16)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      // 16.5 / 16 = 1.03125, rounded to 4 decimals = 1.0313
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(1.0313, 4)
+
+      const result2 = toem(18.5, 14)
+      const match2 = result2.match(/^([\d.]+)em$/)
+      // 18.5 / 14 = 1.3214285714285714, rounded to 4 decimals = 1.3214
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(1.3214, 4)
+    })
+
+    it("should handle very small values", () => {
+      const result1 = toem(1, 16)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(0.0625, 4)
+
+      const result2 = toem(0.5, 16)
+      const match2 = result2.match(/^([\d.]+)em$/)
+      // 0.5 / 16 = 0.03125, rounded to 4 decimals = 0.0313
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(0.0313, 4)
+    })
+
+    it("should handle very large values", () => {
+      expect(toem(100, 16)).toBe("6.25em")
+      expect(toem(200, 16)).toBe("12.5em")
+    })
+
+    it("should handle context larger than target", () => {
+      expect(toem(8, 16)).toBe("0.5em")
+      expect(toem(4, 16)).toBe("0.25em")
+    })
+  })
+})

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

@@ -0,0 +1,193 @@
+/**
+ * Viewport Utilities
+ *
+ * Convert pixel values to viewport-relative sizes and relative units.
+ * Mirrors the SASS functions for consistent responsive scaling.
+ *
+ * @example
+ * ```ts
+ * import { tovw, torem, toem } from '@/utils/viewport'
+ *
+ * // Convert to viewport width units
+ * const paddingX = tovw(16, 24) // "1.5625vw" with a minimum of 24px
+ * const fontSize = tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ * const width = tovw(100, 50, 'desktop') // "max(50px, 6.94vw)"
+ *
+ * // Convert to rem/em
+ * const spacing = torem(24) // "1.5rem"
+ * const padding = toem(16, 14) // "1.14em"
+ * ```
+ *
+ * ## When to Use
+ *
+ * - **CSS**: Prefer the PostCSS functions `tovw()`, `torem()`, and `toem()`
+ * - **JavaScript/TypeScript**: Use these for dynamic calculations or inline styles
+ * - **Runtime calculations**: Use for canvas, WebGL, or dynamic sizing
+ */
+
+import { breakpoints } from "@/lib/styles/config"
+
+type ContextSize = keyof typeof breakpoints | number
+
+/**
+ * Resolves a context size to a pixel value.
+ *
+ * @param context - Context identifier or pixel value
+ * @returns Pixel value
+ */
+function resolveContext(context: ContextSize): number {
+  if (typeof context === "number") {
+    return context
+  }
+  return breakpoints[context] ?? breakpoints.desktop
+}
+
+/**
+ * Checks if a value is a context identifier (breakpoint key).
+ *
+ * @param value - Value to check
+ * @returns True if value is a breakpoint key
+ */
+function isContextIdentifier(
+  value: unknown
+): value is keyof typeof breakpoints {
+  return typeof value === "string" && value in breakpoints
+}
+
+/**
+ * Rounds a number to a maximum of 4 decimal places, removing trailing zeros.
+ *
+ * @param value - Number to round
+ * @returns Rounded number as string without trailing zeros
+ */
+function roundToMaxDecimals(value: number): string {
+  // Round to 4 decimal places
+  const rounded = Math.round(value * 10000) / 10000
+  // Convert to string and remove trailing zeros only after decimal point
+  return rounded
+    .toString()
+    .replace(/\.0+$/, "")
+    .replace(/(\.\d*?)0+$/, "$1")
+}
+
+// Function overloads for tovw
+export function tovw(target: number): string
+export function tovw(target: number, min: number): string
+export function tovw(target: number, context: ContextSize): string
+export function tovw(target: number, min: number, context: ContextSize): string
+/**
+ * Converts a pixel value to viewport width units (vw).
+ * Optionally applies a minimum value using CSS max().
+ *
+ * Supports flexible parameter patterns:
+ * - `tovw(target)` - Uses default desktop context
+ * - `tovw(target, min)` - Sets minimum value
+ * - `tovw(target, context)` - Sets context (auto-detected if string identifier)
+ * - `tovw(target, min, context)` - Sets both min and context
+ *
+ * @param target - Target pixel value to convert
+ * @param minOrContext - Optional minimum pixel value OR context identifier
+ * @param context - Context size identifier (if min was provided)
+ * @returns CSS string with vw units (e.g., "6.94vw" or "max(50px, 6.94vw)")
+ *
+ * @example
+ * ```ts
+ * // Basic conversion
+ * tovw(100) // "6.94vw"
+ * tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ *
+ * // With minimum value
+ * tovw(100, 50) // "max(50px, 6.94vw)"
+ * tovw(100, 50, 'mobile') // "max(50px, 6.94vw)" with mobile context
+ *
+ * // Custom context
+ * tovw(100, 1920) // "5.21vw"
+ *
+ * // Handles zero
+ * tovw(0) // "0"
+ * ```
+ */
+export function tovw(
+  target: number,
+  minOrContext?: number | ContextSize,
+  context?: ContextSize
+): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  let min: number | undefined
+  let resolvedContext: ContextSize = "desktop"
+
+  if (minOrContext !== undefined) {
+    if (isContextIdentifier(minOrContext)) {
+      // Second param is context
+      resolvedContext = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    } else if (typeof minOrContext === "number") {
+      // Second param is min value
+      min = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    }
+  } else if (context !== undefined) {
+    // Only context provided as third param (legacy support)
+    resolvedContext = context
+  }
+
+  const contextSize = resolveContext(resolvedContext)
+  const vwValue = (target / contextSize) * 100
+
+  if (min !== undefined) {
+    return `max(${min}px, ${roundToMaxDecimals(vwValue)}vw)`
+  }
+
+  return `${roundToMaxDecimals(vwValue)}vw`
+}
+
+/**
+ * Converts a pixel value to rem units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Base font size in pixels (default: 16)
+ * @returns CSS string with rem units (e.g., "1.5rem")
+ *
+ * @example
+ * ```ts
+ * torem(24) // "1.5rem" (24 / 16)
+ * torem(18, 14) // "1.29rem" (18 / 14)
+ * torem(0) // "0"
+ * ```
+ */
+export function torem(target: number, context = 16): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}rem`
+}
+
+/**
+ * Converts a pixel value to em units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Context size in pixels (required)
+ * @returns CSS string with em units (e.g., "1.5em")
+ *
+ * @example
+ * ```ts
+ * toem(24, 16) // "1.5em" (24 / 16)
+ * toem(18, 14) // "1.29em" (18 / 14)
+ * toem(0, 16) // "0"
+ * ```
+ */
+export function toem(target: number, context: number): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}em`
+}