bsmnt 0.4.1 → 0.4.2

package/src/templates/next-experiments/lib/utils/README.md

@@ -0,0 +1,40 @@
+# Utils
+
+Pure utility functions organized by concern.
+
+Use explicit imports for clarity and better tree-shaking:
+
+```tsx
+import { clamp, lerp, mapRange } from '@/utils/math'
+import { slugify } from '@/utils/strings'
+import { generatePageMetadata } from '@/utils/metadata'
+import { tovw, torem, toem } from '@/utils/viewport'
+```
+
+## Modules
+
+| Module | Functions |
+|--------|-----------|
+| `math` | `clamp`, `lerp`, `mapRange`, `modulo`, `normalize`, `distance` |
+| `easings` | All easing functions (`easeOutCubic`, etc.) |
+| `viewport` | `tovw`, `torem`, `toem` |
+| `strings` | `slugify`, `mergeRefs`, `capitalizeFirstLetter` |
+| `metadata` | `generatePageMetadata` |
+
+## Common Patterns
+
+```tsx
+// Math
+clamp(0, value, 100)
+lerp(0, 100, 0.5) // → 50
+mapRange(0, 1000, scrollY, 0, 1)
+
+// Viewport units
+tovw(100, 50, 'desktop') // → "max(50px, 6.94vw)"
+tovw(16, undefined, 'mobile') // → "4.27vw"
+torem(24) // → "1.5rem"
+toem(16, 14) // → "1.14em"
+
+// SEO
+export const metadata = generatePageMetadata({ title: 'About' })
+```

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

@@ -0,0 +1 @@
+declare module "@/lib/styles/index.css"

package/src/templates/next-experiments/lib/utils/json-ld.tsx

@@ -1,56 +1,58 @@
-type JsonLdValue = {
-  "@context": "https://schema.org";
-  "@type": string;
-  [key: string]: unknown;
-};
-
-const APP_BASE_URL = process.env.NEXT_PUBLIC_BASE_URL;
+import type {
+  Article,
+  BreadcrumbList,
+  Organization,
+  SearchAction,
+  Thing,
+  WebPage,
+  WebSite,
+  WithContext,
+} from "schema-dts"
+
+const APP_BASE_URL = process.env.NEXT_PUBLIC_BASE_URL
 
 function isAbsoluteUrl(value: string) {
-  return /^https?:\/\//.test(value);
+  return /^https?:\/\//.test(value)
 }
 
 function resolveUrl(value?: string) {
-  if (!value) return APP_BASE_URL;
-  if (isAbsoluteUrl(value)) return value;
-  if (!APP_BASE_URL) return undefined;
+  if (!value) return APP_BASE_URL
+  if (isAbsoluteUrl(value)) return value
+  if (!APP_BASE_URL) return undefined
 
-  return new URL(value, APP_BASE_URL).toString();
+  return new URL(value, APP_BASE_URL).toString()
 }
 
 /* -------------------------------- Component ------------------------------- */
 
-export function JsonLd<T extends JsonLdValue>({
-  data,
-}: {
-  data: T;
-}) {
+export function JsonLd<T extends Thing>({ data }: { data: WithContext<T> }) {
   return (
     <script
       type="application/ld+json"
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: JSON-LD must be emitted as a raw script payload; `<` is escaped above for XSS protection.
       dangerouslySetInnerHTML={{
         __html: JSON.stringify(data).replace(/</g, "\\u003c"),
       }}
     />
-  );
+  )
 }
 
 /* -------------------------------- Generators ------------------------------ */
 
 interface WebSiteJsonLdOptions {
-  name: string;
-  url?: string;
-  description?: string;
+  name: string
+  url?: string
+  description?: string
   /** URL to site-wide search (e.g. "/search?q={search_term_string}") */
-  searchUrl?: string;
+  searchUrl?: string
 }
 
 export function generateWebSiteJsonLd(
   options: WebSiteJsonLdOptions
-): JsonLdValue {
-  const { name, url, description, searchUrl } = options;
-  const resolvedUrl = resolveUrl(url);
-  const resolvedSearchUrl = resolveUrl(searchUrl);
+): WithContext<WebSite> {
+  const { name, url, description, searchUrl } = options
+  const resolvedUrl = resolveUrl(url)
+  const resolvedSearchUrl = resolveUrl(searchUrl)
 
   return {
     "@context": "https://schema.org",
@@ -63,25 +65,25 @@ export function generateWebSiteJsonLd(
         "@type": "SearchAction",
         target: resolvedSearchUrl,
         "query-input": "required name=search_term_string",
-      },
+      } as SearchAction & { "query-input": string },
     }),
-  };
+  }
 }
 
 interface OrganizationJsonLdOptions {
-  name: string;
-  url?: string;
-  logo?: string;
-  description?: string;
-  sameAs?: string[];
+  name: string
+  url?: string
+  logo?: string
+  description?: string
+  sameAs?: string[]
 }
 
 export function generateOrganizationJsonLd(
   options: OrganizationJsonLdOptions
-): JsonLdValue {
-  const { name, url, logo, description, sameAs } = options;
-  const resolvedUrl = resolveUrl(url);
-  const resolvedLogo = resolveUrl(logo);
+): WithContext<Organization> {
+  const { name, url, logo, description, sameAs } = options
+  const resolvedUrl = resolveUrl(url)
+  const resolvedLogo = resolveUrl(logo)
 
   return {
     "@context": "https://schema.org",
@@ -91,25 +93,25 @@ export function generateOrganizationJsonLd(
     ...(resolvedLogo && { logo: resolvedLogo }),
     ...(description && { description }),
     ...(sameAs && { sameAs }),
-  };
+  }
 }
 
 interface WebPageJsonLdOptions {
-  title: string;
-  url?: string;
-  description?: string;
-  image?: string;
-  datePublished?: string;
-  dateModified?: string;
+  title: string
+  url?: string
+  description?: string
+  image?: string
+  datePublished?: string
+  dateModified?: string
 }
 
 export function generateWebPageJsonLd(
   options: WebPageJsonLdOptions
-): JsonLdValue {
+): WithContext<WebPage> {
   const { title, url, description, image, datePublished, dateModified } =
-    options;
-  const resolvedUrl = resolveUrl(url);
-  const resolvedImage = resolveUrl(image);
+    options
+  const resolvedUrl = resolveUrl(url)
+  const resolvedImage = resolveUrl(image)
 
   return {
     "@context": "https://schema.org",
@@ -120,23 +122,23 @@ export function generateWebPageJsonLd(
     ...(resolvedImage && { image: resolvedImage }),
     ...(datePublished && { datePublished }),
     ...(dateModified && { dateModified }),
-  };
+  }
 }
 
 interface ArticleJsonLdOptions {
-  title: string;
-  url?: string;
-  description?: string;
-  image?: string;
-  datePublished?: string;
-  dateModified?: string;
-  authorName?: string;
-  authorUrl?: string;
+  title: string
+  url?: string
+  description?: string
+  image?: string
+  datePublished?: string
+  dateModified?: string
+  authorName?: string
+  authorUrl?: string
 }
 
 export function generateArticleJsonLd(
   options: ArticleJsonLdOptions
-): JsonLdValue {
+): WithContext<Article> {
   const {
     title,
     url,
@@ -146,9 +148,9 @@ export function generateArticleJsonLd(
     dateModified,
     authorName,
     authorUrl,
-  } = options;
-  const resolvedUrl = resolveUrl(url);
-  const resolvedImage = resolveUrl(image);
+  } = options
+  const resolvedUrl = resolveUrl(url)
+  const resolvedImage = resolveUrl(image)
 
   return {
     "@context": "https://schema.org",
@@ -166,29 +168,29 @@ export function generateArticleJsonLd(
         ...(authorUrl && { url: authorUrl }),
       },
     }),
-  };
+  }
 }
 
 interface BreadcrumbItem {
-  name: string;
-  url: string;
+  name: string
+  url: string
 }
 
 export function generateBreadcrumbJsonLd(
   items: BreadcrumbItem[]
-): JsonLdValue {
+): WithContext<BreadcrumbList> {
   return {
     "@context": "https://schema.org",
     "@type": "BreadcrumbList",
     itemListElement: items.map((item, index) => {
-      const resolvedItemUrl = resolveUrl(item.url);
+      const resolvedItemUrl = resolveUrl(item.url)
 
       return {
         "@type": "ListItem",
         position: index + 1,
         name: item.name,
         ...(resolvedItemUrl && { item: resolvedItemUrl }),
-      };
+      }
     }),
-  };
+  }
 }