bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/default/lib/styles/scripts/postcss-functions.mjs

@@ -0,0 +1,168 @@
+// THIS FILE HAS TO STAY .mjs AS ITS CONSUMED BY POSTCSS
+import { breakpoints } from "../layout.mjs"
+
+/**
+ * Resolves a context size to a pixel value.
+ * @param {string | number} context - Context identifier or pixel value
+ * @returns {number} Pixel value
+ */
+function resolveContext(context) {
+  if (typeof context === "number") {
+    return context
+  }
+  const numContext = Number.parseFloat(context)
+  if (!Number.isNaN(numContext)) {
+    return numContext
+  }
+  return breakpoints[context] ?? breakpoints.desktop
+}
+
+/**
+ * Validates and parses a pixel value.
+ * @param {string} value - Pixel value to parse
+ * @returns {number} Parsed pixel value
+ */
+function parsePixels(value) {
+  const numValue = Number.parseFloat(value)
+  if (Number.isNaN(numValue)) {
+    throw new Error(`Invalid pixel value: ${value}`)
+  }
+  return numValue
+}
+
+/**
+ * Rounds a number to a maximum of 4 decimal places, removing trailing zeros.
+ * @param {number} value - Number to round
+ * @returns {string} Rounded number as string without trailing zeros
+ */
+function roundToMaxDecimals(value) {
+  // 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")
+}
+
+export const functions = {
+  /**
+   * 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 (numeric)
+   * - `tovw(target, context)` - Sets context (string identifier)
+   * - `tovw(target, min, context)` - Sets both min and context
+   *
+   * @param {string} target - Target pixel value to convert
+   * @param {string} [minOrContext] - Minimum pixel value OR context identifier
+   * @param {string} [context] - Context size identifier (if min was provided)
+   * @returns {string} CSS string with vw units
+   *
+   * @example
+   * tovw(100) // "6.94vw"
+   * tovw(100, 50) // "max(50px, 6.94vw)"
+   * tovw(16, 'mobile') // "4.27vw" (no need for undefined!)
+   * tovw(100, 50, 'mobile') // "max(50px, 6.94vw)" with mobile context
+   */
+  tovw: (target, minOrContext, context) => {
+    const numTarget = parsePixels(target)
+    if (numTarget === 0) {
+      return "0"
+    }
+
+    let min
+    let resolvedContext = "desktop"
+
+    if (minOrContext !== undefined && minOrContext !== "") {
+      // Fast check: is it a known breakpoint key?
+      if (minOrContext in breakpoints) {
+        // Second param is context
+        resolvedContext = minOrContext
+        if (context !== undefined && context !== "") {
+          resolvedContext = context
+        }
+      } else {
+        // Second param is min value (numeric)
+        min = parsePixels(minOrContext)
+        if (context !== undefined && context !== "") {
+          resolvedContext = context
+        }
+      }
+    } else if (context !== undefined && context !== "") {
+      // Only context provided as third param (legacy support)
+      resolvedContext = context
+    }
+
+    const contextSize = resolveContext(resolvedContext)
+    const vwValue = (numTarget / contextSize) * 100
+
+    if (min !== undefined) {
+      return `max(${min}px, ${roundToMaxDecimals(vwValue)}vw)`
+    }
+
+    return `${roundToMaxDecimals(vwValue)}vw`
+  },
+
+  /**
+   * Converts a pixel value to rem units.
+   *
+   * @param {string} target - Target pixel value to convert
+   * @param {string} [context='16'] - Base font size in pixels
+   * @returns {string} CSS string with rem units
+   *
+   * @example
+   * torem(24) // "1.5rem"
+   * torem(18, 14) // "1.29rem"
+   */
+  torem: (target, context = "16") => {
+    const numTarget = parsePixels(target)
+    if (numTarget === 0) {
+      return "0"
+    }
+
+    const numContext = parsePixels(context)
+    return `${roundToMaxDecimals(numTarget / numContext)}rem`
+  },
+
+  /**
+   * Converts a pixel value to em units.
+   *
+   * @param {string} target - Target pixel value to convert
+   * @param {string} context - Context size in pixels (required)
+   * @returns {string} CSS string with em units
+   *
+   * @example
+   * toem(24, 16) // "1.5em"
+   * toem(18, 14) // "1.29em"
+   */
+  toem: (target, context) => {
+    const numTarget = parsePixels(target)
+    if (numTarget === 0) {
+      return "0"
+    }
+
+    if (!context) {
+      throw new Error("toem requires a context parameter")
+    }
+
+    const numContext = parsePixels(context)
+    return `${roundToMaxDecimals(numTarget / numContext)}em`
+  },
+
+  /**
+   * Calculates column width based on number of columns.
+   *
+   * @param {string} columns - Number of columns
+   * @returns {string} CSS calc expression
+   */
+  columns: (columns) => {
+    const numColumns = Number.parseFloat(columns)
+    if (Number.isNaN(numColumns)) {
+      throw new Error(`Invalid column value: ${columns}`)
+    }
+    return `calc((${numColumns} * var(--column-width)) + ((${numColumns} - 1) * var(--gap)))`
+  },
+}

package/packages/create-basement-app/templates/default/lib/styles/scripts/setup-styles.ts

@@ -0,0 +1,24 @@
+import * as config from "../config"
+import { generateRoot } from "./generate-root"
+import { generateTailwind } from "./generate-tailwind"
+
+const tailwind = generateTailwind(config)
+const root = generateRoot(config)
+
+const banner = `/*
+ * THIS FILE IS GENERATED BY setup-styles.ts
+ * DO NOT EDIT IT DIRECTLY.
+ */`
+
+const tailwindcss = [banner, tailwind]
+const rootcss = [banner, root]
+
+await Bun.write("./lib/styles/css/tailwind.css", tailwindcss.join("\n\n"))
+await Bun.write("./lib/styles/css/root.css", rootcss.join("\n\n"))
+
+console.log(
+  Bun.color("green", "ansi"),
+  "✓",
+  Bun.color("black", "ansi"),
+  "Style config generated successfully"
+)

package/packages/create-basement-app/templates/default/lib/styles/scripts/utils.ts

@@ -0,0 +1,20 @@
+export function scalingCalc(value: number) {
+  return `calc(((${value} * 100) / var(--device-width)) * 1vw)`
+}
+
+/**
+ * Format an object into a string of CSS variables
+ * @param obj - The object to format
+ * @param mapper - A function that maps the object's entries to a string
+ * @param joiner - The string to join the mapped entries with
+ * @returns A string of CSS variables
+ */
+export function formatObject<Obj extends Record<string, unknown>>(
+  obj: Obj,
+  mapper: (args: [key: keyof Obj, value: Obj[keyof Obj]]) => string,
+  joiner = "\n\t"
+) {
+  return Object.entries(obj)
+    .map(([key, value]) => mapper([key as keyof Obj, value as Obj[keyof Obj]]))
+    .join(joiner)
+}

package/packages/create-basement-app/templates/default/lib/styles/typography.ts

@@ -0,0 +1,36 @@
+import type { CSSProperties } from "react"
+
+const fonts = {
+  mono: "--geist-mono", // this should be the variable name defined in fonts.ts
+} as const
+
+const typography: TypeStyles = {
+  "test-mono": {
+    "font-family": `var(${fonts.mono})`,
+    "font-style": "normal",
+    "font-weight": 400,
+    "line-height": "90%",
+    "letter-spacing": "0em",
+    "font-size": { mobile: 20, desktop: 24 },
+  },
+} as const
+
+export { fonts, typography }
+
+// UTIL TYPES
+type TypeStyles = Record<
+  string,
+  {
+    "font-family": string
+    "font-style": CSSProperties["fontStyle"]
+    "font-weight": CSSProperties["fontWeight"]
+    "line-height":
+      | `${number}%`
+      | { mobile: `${number}%`; desktop: `${number}%` }
+    "letter-spacing":
+      | `${number}em`
+      | { mobile: `${number}em`; desktop: `${number}em` }
+    "font-feature-settings"?: string
+    "font-size": number | { mobile: number; desktop: number }
+  }
+>

package/packages/create-basement-app/templates/default/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/packages/create-basement-app/templates/default/lib/utils/css.d.ts

@@ -0,0 +1,21 @@
+// CSS module type declarations (ambient - no imports allowed)
+
+declare module "*.module.css" {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+declare module "*.module.scss" {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+declare module "*.module.sass" {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+// Regular CSS imports
+declare module "*.css"
+declare module "*.scss"
+declare module "*.sass"

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