bsmnt 0.0.2 → 0.1.0

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

@@ -0,0 +1,236 @@
+/**
+ * Math Utilities
+ *
+ * Pure mathematical functions with no side effects.
+ * These are the building blocks for animations, layouts, and data transformations.
+ *
+ * @example
+ * ```ts
+ * import { clamp, lerp, mapRange } from '@/utils/math'
+ *
+ * // Constrain a value
+ * const bounded = clamp(0, value, 100)
+ *
+ * // Interpolate between values
+ * const mid = lerp(0, 100, 0.5) // 50
+ *
+ * // Map scroll position to opacity
+ * const opacity = mapRange(0, 500, scrollY, 0, 1, true)
+ * ```
+ */
+
+/**
+ * Constrains a value between a minimum and maximum.
+ *
+ * @param min - Lower bound
+ * @param input - Value to constrain
+ * @param max - Upper bound
+ * @returns The clamped value
+ *
+ * @example
+ * ```ts
+ * clamp(0, -5, 100)  // 0
+ * clamp(0, 50, 100)  // 50
+ * clamp(0, 150, 100) // 100
+ * ```
+ */
+export function clamp(min: number, input: number, max: number): number {
+  return Math.max(min, Math.min(input, max))
+}
+
+/**
+ * Linear interpolation between two values.
+ *
+ * @param start - Starting value
+ * @param end - Ending value
+ * @param amount - Interpolation factor (0 = start, 1 = end)
+ * @returns The interpolated value
+ *
+ * @example
+ * ```ts
+ * lerp(0, 100, 0)    // 0
+ * lerp(0, 100, 0.5)  // 50
+ * lerp(0, 100, 1)    // 100
+ * lerp(0, 100, 0.25) // 25
+ * ```
+ */
+export function lerp(start: number, end: number, amount: number): number {
+  return (1 - amount) * start + amount * end
+}
+
+/**
+ * Maps a value from one range to another.
+ *
+ * @param inMin - Input range minimum
+ * @param inMax - Input range maximum
+ * @param input - Value to map
+ * @param outMin - Output range minimum
+ * @param outMax - Output range maximum
+ * @param shouldClamp - Whether to clamp output to range (default: false)
+ * @returns The mapped value
+ *
+ * @example
+ * ```ts
+ * // Map scroll (0-1000) to opacity (0-1)
+ * mapRange(0, 1000, 500, 0, 1) // 0.5
+ *
+ * // Map with clamping (won't exceed bounds)
+ * mapRange(0, 100, 150, 0, 1, true) // 1
+ *
+ * // Inverted ranges work too
+ * mapRange(0, 100, 50, 1, 0) // 0.5
+ * ```
+ */
+export function mapRange(
+  inMin: number,
+  inMax: number,
+  input: number,
+  outMin: number,
+  outMax: number,
+  shouldClamp = false
+): number {
+  const result =
+    ((input - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin
+
+  if (!shouldClamp) return result
+
+  const isInverted = outMin > outMax
+  return isInverted
+    ? clamp(outMax, result, outMin)
+    : clamp(outMin, result, outMax)
+}
+
+/**
+ * Truncates a number to a specified number of decimal places.
+ *
+ * @param value - Number to truncate
+ * @param decimals - Number of decimal places
+ * @returns The truncated number
+ *
+ * @example
+ * ```ts
+ * truncate(3.14159, 2) // 3.14
+ * truncate(3.14159, 0) // 3
+ * ```
+ */
+export function truncate(value: number, decimals: number): number {
+  return Number.parseFloat(value.toFixed(decimals))
+}
+
+/**
+ * True modulo operation (handles negative numbers correctly).
+ *
+ * JavaScript's % operator is remainder, not modulo.
+ * This function returns a value in [0, d) for positive divisors.
+ *
+ * @param n - Dividend
+ * @param d - Divisor (must be positive)
+ * @returns The modulo result
+ *
+ * @example
+ * ```ts
+ * // JavaScript remainder vs true modulo
+ * -1 % 3        // -1 (remainder)
+ * modulo(-1, 3) // 2  (modulo)
+ *
+ * // Useful for wrapping array indices
+ * modulo(index - 1, array.length)
+ * ```
+ */
+export function modulo(n: number, d: number): number {
+  if (d === 0) return n
+  if (d < 0) return Number.NaN
+  return ((n % d) + d) % d
+}
+
+/**
+ * Rounds a number to the nearest multiple.
+ *
+ * @param value - Number to round
+ * @param multiple - Multiple to round to
+ * @returns The rounded value
+ *
+ * @example
+ * ```ts
+ * roundTo(23, 10)  // 20
+ * roundTo(27, 10)  // 30
+ * roundTo(0.23, 0.1) // 0.2
+ * ```
+ */
+export function roundTo(value: number, multiple: number): number {
+  return Math.round(value / multiple) * multiple
+}
+
+/**
+ * Converts degrees to radians.
+ *
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ *
+ * @example
+ * ```ts
+ * degToRad(180) // Math.PI
+ * degToRad(90)  // Math.PI / 2
+ * ```
+ */
+export function degToRad(degrees: number): number {
+  return (degrees * Math.PI) / 180
+}
+
+/**
+ * Converts radians to degrees.
+ *
+ * @param radians - Angle in radians
+ * @returns Angle in degrees
+ *
+ * @example
+ * ```ts
+ * radToDeg(Math.PI)     // 180
+ * radToDeg(Math.PI / 2) // 90
+ * ```
+ */
+export function radToDeg(radians: number): number {
+  return (radians * 180) / Math.PI
+}
+
+/**
+ * Calculates the distance between two 2D points.
+ *
+ * @param x1 - First point X
+ * @param y1 - First point Y
+ * @param x2 - Second point X
+ * @param y2 - Second point Y
+ * @returns The distance
+ *
+ * @example
+ * ```ts
+ * distance(0, 0, 3, 4) // 5
+ * ```
+ */
+export function distance(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number
+): number {
+  return Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2)
+}
+
+/**
+ * Normalizes a value to a 0-1 range.
+ *
+ * @param min - Range minimum
+ * @param max - Range maximum
+ * @param value - Value to normalize
+ * @returns Normalized value (0-1)
+ *
+ * @example
+ * ```ts
+ * normalize(0, 100, 50)  // 0.5
+ * normalize(0, 100, 0)   // 0
+ * normalize(0, 100, 100) // 1
+ * ```
+ */
+export function normalize(min: number, max: number, value: number): number {
+  return (value - min) / (max - min)
+}

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

@@ -0,0 +1,126 @@
+import type { Metadata } from "next"
+
+/**
+ * Metadata Generation Utilities
+ *
+ * Helpers to generate consistent metadata across pages,
+ * reducing duplication and ensuring SEO best practices.
+ */
+
+interface GenerateMetadataOptions {
+  title?: string
+  description?: string
+  keywords?: string[]
+  image?: {
+    url?: string
+    width?: number
+    height?: number
+    alt?: string
+  }
+  url?: string
+  siteName?: string
+  noIndex?: boolean
+  type?: "website" | "article"
+  publishedTime?: string
+  modifiedTime?: string
+  authors?: string[]
+}
+
+const APP_BASE_URL =
+  process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000"
+
+/**
+ * Generate complete metadata object for pages
+ *
+ * @example
+ * ```ts
+ * export async function generateMetadata({ params }) {
+ *   const page = await fetchPage(params.slug)
+ *
+ *   return generatePageMetadata({
+ *     title: page.metadata?.title || page.title,
+ *     description: page.metadata?.description,
+ *     image: { url: page.metadata?.image?.asset?.url },
+ *     url: `/page/${params.slug}`,
+ *     noIndex: page.metadata?.noIndex,
+ *   })
+ * }
+ * ```
+ */
+export function generatePageMetadata(
+  options: GenerateMetadataOptions
+): Metadata {
+  const {
+    title,
+    description,
+    keywords,
+    image,
+    url,
+    siteName = "Satūs",
+    noIndex = false,
+    type = "website",
+    publishedTime,
+    modifiedTime,
+    authors,
+  } = options
+
+  const fullUrl = url ? `${APP_BASE_URL}${url}` : APP_BASE_URL
+  const imageUrl = image?.url || "/opengraph-image.jpg"
+  const imageWidth = image?.width || 1200
+  const imageHeight = image?.height || 630
+  const imageAlt = image?.alt || title || siteName
+
+  const metadata: Metadata = {
+    metadataBase: new URL(APP_BASE_URL),
+    title,
+    description,
+    keywords,
+    alternates: {
+      canonical: url || "/",
+    },
+    openGraph: {
+      title,
+      description,
+      url: fullUrl,
+      siteName,
+      locale: "en_US",
+      type,
+      images: [
+        {
+          url: imageUrl,
+          width: imageWidth,
+          height: imageHeight,
+          alt: imageAlt,
+        },
+      ],
+      ...(publishedTime && { publishedTime }),
+      ...(modifiedTime && { modifiedTime }),
+      ...(authors && { authors }),
+    },
+    twitter: {
+      card: "summary_large_image",
+      title,
+      description,
+      images: [
+        {
+          url: imageUrl,
+          width: imageWidth,
+          height: imageHeight,
+          alt: imageAlt,
+        },
+      ],
+    },
+    other: {
+      "fb:app_id": process.env.NEXT_PUBLIC_FACEBOOK_APP_ID || "",
+    },
+  }
+
+  if (noIndex) {
+    metadata.robots = {
+      index: false,
+      follow: false,
+    }
+  }
+
+  return metadata
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Unit tests for string utilities
+ *
+ * Run with: bun test lib/utils/strings.test.ts
+ */
+
+import { describe, expect, it } from "bun:test"
+import {
+  capitalizeFirstLetter,
+  convertToCamelCase,
+  isEmptyArray,
+  isEmptyObject,
+  numberWithCommas,
+  slugify,
+  twoDigits,
+} from "./strings"
+
+describe("slugify", () => {
+  it("should convert text to URL-friendly format", () => {
+    expect(slugify("Hello World")).toBe("hello-world")
+    expect(slugify("Hello World!")).toBe("hello-world")
+  })
+
+  it("should handle special characters", () => {
+    expect(slugify("Café & Restaurant")).toBe("cafe-restaurant")
+    expect(slugify("Rock & Roll")).toBe("rock-roll")
+  })
+
+  it("should handle multiple spaces and dashes", () => {
+    expect(slugify("Hello   World")).toBe("hello-world")
+    expect(slugify("Hello--World")).toBe("hello-world")
+    expect(slugify("Hello - World")).toBe("hello-world")
+  })
+
+  it("should trim whitespace", () => {
+    expect(slugify("  Hello World  ")).toBe("hello-world")
+  })
+
+  it("should handle numbers", () => {
+    expect(slugify("Product 123")).toBe("product-123")
+    expect(slugify("2024 Review")).toBe("2024-review")
+  })
+
+  it("should handle objects with toString", () => {
+    const obj = { toString: () => "Custom Object" }
+    expect(slugify(obj)).toBe("custom-object")
+  })
+})
+
+describe("convertToCamelCase", () => {
+  it("should convert first character to lowercase", () => {
+    expect(convertToCamelCase("HelloWorld")).toBe("helloWorld")
+    expect(convertToCamelCase("MyComponent")).toBe("myComponent")
+  })
+
+  it("should handle already camelCase strings", () => {
+    expect(convertToCamelCase("helloWorld")).toBe("helloWorld")
+  })
+
+  it("should handle single characters", () => {
+    expect(convertToCamelCase("A")).toBe("a")
+    expect(convertToCamelCase("a")).toBe("a")
+  })
+
+  it("should handle empty strings", () => {
+    expect(convertToCamelCase("")).toBe("")
+  })
+})
+
+describe("capitalizeFirstLetter", () => {
+  it("should capitalize the first letter", () => {
+    expect(capitalizeFirstLetter("hello")).toBe("Hello")
+    expect(capitalizeFirstLetter("world")).toBe("World")
+  })
+
+  it("should handle already capitalized strings", () => {
+    expect(capitalizeFirstLetter("Hello")).toBe("Hello")
+  })
+
+  it("should handle single characters", () => {
+    expect(capitalizeFirstLetter("a")).toBe("A")
+    expect(capitalizeFirstLetter("A")).toBe("A")
+  })
+
+  it("should handle empty strings", () => {
+    expect(capitalizeFirstLetter("")).toBe("")
+  })
+})
+
+describe("twoDigits", () => {
+  it("should pad single digit numbers with zero", () => {
+    expect(twoDigits(0)).toBe("00")
+    expect(twoDigits(5)).toBe("05")
+    expect(twoDigits(9)).toBe("09")
+  })
+
+  it("should not pad two-digit numbers", () => {
+    expect(twoDigits(10)).toBe("10")
+    expect(twoDigits(23)).toBe("23")
+    expect(twoDigits(99)).toBe("99")
+  })
+
+  it("should handle numbers greater than 99", () => {
+    expect(twoDigits(100)).toBe("100")
+    expect(twoDigits(999)).toBe("999")
+  })
+})
+
+describe("numberWithCommas", () => {
+  it("should add commas as thousands separators", () => {
+    expect(numberWithCommas(1000)).toBe("1,000")
+    expect(numberWithCommas(1234)).toBe("1,234")
+    expect(numberWithCommas(1234567)).toBe("1,234,567")
+  })
+
+  it("should not add commas to numbers less than 1000", () => {
+    expect(numberWithCommas(999)).toBe("999")
+    expect(numberWithCommas(1)).toBe("1")
+    expect(numberWithCommas(0)).toBe("0")
+  })
+
+  it("should handle objects with toString", () => {
+    const obj = { toString: () => "1234567" }
+    expect(numberWithCommas(obj)).toBe("1,234,567")
+  })
+})
+
+describe("isEmptyObject", () => {
+  it("should return true for empty objects", () => {
+    expect(isEmptyObject({})).toBe(true)
+  })
+
+  it("should return false for non-empty objects", () => {
+    expect(isEmptyObject({ a: 1 })).toBe(false)
+    expect(isEmptyObject({ key: "value" })).toBe(false)
+  })
+
+  it("should return true for null/undefined", () => {
+    expect(isEmptyObject(null as unknown as Record<string, unknown>)).toBe(true)
+    expect(isEmptyObject(undefined as unknown as Record<string, unknown>)).toBe(
+      true
+    )
+  })
+})
+
+describe("isEmptyArray", () => {
+  it("should return true for empty arrays", () => {
+    expect(isEmptyArray([])).toBe(true)
+  })
+
+  it("should return false for non-empty arrays", () => {
+    expect(isEmptyArray([1, 2, 3])).toBe(false)
+    expect(isEmptyArray(["a"])).toBe(false)
+  })
+
+  it("should return false for non-arrays (strings)", () => {
+    // Note: strings are not arrays, so Array.isArray returns false
+    // The function returns false for non-arrays that have a truthy value
+    expect(isEmptyArray("test")).toBe(false)
+  })
+
+  it("should return true for null/undefined", () => {
+    expect(isEmptyArray(null as unknown as unknown[])).toBe(true)
+    expect(isEmptyArray(undefined as unknown as unknown[])).toBe(true)
+  })
+})