bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/default/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)
+  })
+})

package/packages/create-basement-app/templates/default/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/default/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
+}