bsmnt 0.4.0 → 0.4.2

package/src/templates/next-experiments/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/src/templates/next-experiments/lib/utils/metadata.ts

@@ -1,5 +1,4 @@
-import type { Metadata } from "next";
-import { getBaseUrl } from "@/lib/utils/url";
+import type { Metadata } from "next"
 
 /**
  * Metadata Generation Utilities
@@ -9,25 +8,25 @@ import { getBaseUrl } from "@/lib/utils/url";
  */
 
 interface GenerateMetadataOptions {
-  title?: string;
-  description?: string;
-  keywords?: string[];
+  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[];
+    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 = getBaseUrl();
+const APP_BASE_URL = process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000"
 
 /**
  * Generate complete metadata object for pages
@@ -62,13 +61,13 @@ export function generatePageMetadata(
     publishedTime,
     modifiedTime,
     authors,
-  } = options;
+  } = 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 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),
@@ -113,14 +112,14 @@ export function generatePageMetadata(
     other: {
       "fb:app_id": process.env.NEXT_PUBLIC_FACEBOOK_APP_ID || "",
     },
-  };
+  }
 
   if (noIndex) {
     metadata.robots = {
       index: false,
       follow: false,
-    };
+    }
   }
 
-  return metadata;
+  return metadata
 }

package/src/templates/next-experiments/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/src/templates/next-experiments/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/src/templates/next-experiments/lib/utils/url.ts

@@ -8,9 +8,12 @@
  * 4. localhost fallback
  */
 export function getBaseUrl(): string {
-  if (process.env.NEXT_PUBLIC_BASE_URL) return process.env.NEXT_PUBLIC_BASE_URL;
-  if (process.env.VERCEL_PROJECT_PRODUCTION_URL)
-    return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
-  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
-  return "http://localhost:3000";
+  if (process.env.NEXT_PUBLIC_BASE_URL) {
+    return process.env.NEXT_PUBLIC_BASE_URL
+  }
+  if (process.env.VERCEL_PROJECT_PRODUCTION_URL) {
+    return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+  }
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`
+  return "http://localhost:3000"
 }