bsmnt 0.0.2 → 0.1.0

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

package/packages/create-basement-app/templates/experiment/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/packages/create-basement-app/templates/experiment/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/packages/create-basement-app/templates/experiment/lib/utils/viewport.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Unit tests for viewport utilities
+ *
+ * Run with: bun test lib/utils/viewport.test.ts
+ */
+
+import { describe, expect, it } from "bun:test"
+import { toem, torem, tovw } from "./viewport"
+
+// Helper to check vw values with floating point tolerance
+function expectVw(actual: string, expectedVw: number) {
+  const match = actual.match(/^([\d.]+)vw$/)
+  if (!match?.[1]) {
+    throw new Error(`Expected vw format, got: ${actual}`)
+  }
+  const actualVw = Number.parseFloat(match[1])
+  expect(actualVw).toBeCloseTo(expectedVw, 4)
+}
+
+// Helper to check max() values with floating point tolerance
+function expectMaxVw(actual: string, expectedMin: number, expectedVw: number) {
+  const match = actual.match(/^max\((\d+)px, ([\d.]+)vw\)$/)
+  if (!(match?.[1] && match[2])) {
+    throw new Error(`Expected max() format, got: ${actual}`)
+  }
+  const actualMin = Number.parseFloat(match[1])
+  const actualVw = Number.parseFloat(match[2])
+  expect(actualMin).toBe(expectedMin)
+  expect(actualVw).toBeCloseTo(expectedVw, 4)
+}
+
+describe("tovw", () => {
+  describe("basic conversion (default desktop context)", () => {
+    it("should convert pixels to vw with default desktop context (1440px)", () => {
+      expectVw(tovw(100), 6.9444)
+      expect(tovw(1440)).toBe("100vw")
+      expect(tovw(720)).toBe("50vw")
+    })
+
+    it("should handle zero", () => {
+      expect(tovw(0)).toBe("0")
+    })
+  })
+
+  describe("with minimum value", () => {
+    it("should apply minimum value using max()", () => {
+      expectMaxVw(tovw(100, 50), 50, 6.9444)
+      expectMaxVw(tovw(200, 100), 100, 13.8889)
+    })
+
+    it("should handle zero target with min", () => {
+      expect(tovw(0, 50)).toBe("0")
+    })
+  })
+
+  describe("with context identifier", () => {
+    it("should use mobile context (375px)", () => {
+      expectVw(tovw(16, "mobile"), 4.2667)
+      expect(tovw(375, "mobile")).toBe("100vw")
+    })
+
+    it("should use desktop-large context (1920px)", () => {
+      expectVw(tovw(100, "desktop-large"), 5.2083)
+      expect(tovw(1920, "desktop-large")).toBe("100vw")
+    })
+
+    it("should use tablet-lg context (1024px)", () => {
+      expectVw(tovw(100, "tablet-lg"), 9.7656)
+      expect(tovw(1024, "tablet-lg")).toBe("100vw")
+    })
+
+    it("should use tablet context (620px)", () => {
+      expectVw(tovw(100, "tablet"), 16.129)
+      expect(tovw(620, "tablet")).toBe("100vw")
+    })
+
+    it("should use desktop context explicitly", () => {
+      expectVw(tovw(100, "desktop"), 6.9444)
+    })
+  })
+
+  describe("with custom numeric context", () => {
+    it("should use custom pixel context as third parameter", () => {
+      // Numeric contexts must be passed as third parameter (with undefined min)
+      // Using type assertion to test the implementation behavior
+      expectVw(tovw(100, 1920), 5.2083)
+      expectVw(tovw(100, 800), 12.5)
+      expectVw(tovw(100, 2000), 5)
+    })
+
+    it("should treat numeric second parameter as min, not context", () => {
+      // When second param is a number, it's treated as min, not context
+      expectMaxVw(tovw(100, 1920), 1920, 6.9444)
+    })
+  })
+
+  describe("with both min and context", () => {
+    it("should apply min and context together", () => {
+      expectMaxVw(tovw(100, 50, "mobile"), 50, 26.6667)
+      expectMaxVw(tovw(200, 100, "desktop-large"), 100, 10.4167)
+    })
+
+    it("should use numeric context with min", () => {
+      expectMaxVw(tovw(100, 50, 1920), 50, 5.2083)
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle very small values", () => {
+      expectVw(tovw(1), 0.0694)
+      expectVw(tovw(0.5), 0.0347)
+    })
+
+    it("should handle very large values", () => {
+      expectVw(tovw(5000), 347.2222)
+    })
+
+    it("should handle decimal values", () => {
+      expectVw(tovw(16.5), 1.1458)
+      expectVw(tovw(16.5, "mobile"), 4.4)
+    })
+  })
+})
+
+describe("torem", () => {
+  describe("basic conversion (default 16px context)", () => {
+    it("should convert pixels to rem with default context", () => {
+      expect(torem(16)).toBe("1rem")
+      expect(torem(24)).toBe("1.5rem")
+      expect(torem(32)).toBe("2rem")
+      expect(torem(8)).toBe("0.5rem")
+    })
+
+    it("should handle zero", () => {
+      expect(torem(0)).toBe("0")
+    })
+  })
+
+  describe("with custom context", () => {
+    it("should use custom base font size", () => {
+      // Using toBeCloseTo for floating point comparison
+      const result1 = torem(18, 14)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(
+        1.2857142857142858,
+        4
+      )
+
+      expect(torem(20, 10)).toBe("2rem")
+      expect(torem(24, 12)).toBe("2rem")
+    })
+
+    it("should handle zero with custom context", () => {
+      expect(torem(0, 14)).toBe("0")
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle decimal values", () => {
+      const result1 = torem(16.5)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      // 16.5 / 16 = 1.03125, rounded to 4 decimals = 1.0313
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(1.0313, 4)
+
+      const result2 = torem(18.5, 14)
+      const match2 = result2.match(/^([\d.]+)rem$/)
+      // 18.5 / 14 = 1.3214285714285714, rounded to 4 decimals = 1.3214
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(1.3214, 4)
+    })
+
+    it("should handle very small values", () => {
+      const result1 = torem(1)
+      const match1 = result1.match(/^([\d.]+)rem$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(0.0625, 4)
+
+      const result2 = torem(0.5)
+      const match2 = result2.match(/^([\d.]+)rem$/)
+      // 0.5 / 16 = 0.03125, rounded to 4 decimals = 0.0313
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(0.0313, 4)
+    })
+
+    it("should handle very large values", () => {
+      expect(torem(100)).toBe("6.25rem")
+      expect(torem(200)).toBe("12.5rem")
+    })
+  })
+})
+
+describe("toem", () => {
+  describe("basic conversion", () => {
+    it("should convert pixels to em", () => {
+      expect(toem(24, 16)).toBe("1.5em")
+      expect(toem(16, 16)).toBe("1em")
+      expect(toem(32, 16)).toBe("2em")
+      expect(toem(8, 16)).toBe("0.5em")
+    })
+
+    it("should handle zero", () => {
+      expect(toem(0, 16)).toBe("0")
+    })
+  })
+
+  describe("with different contexts", () => {
+    it("should use custom context size", () => {
+      const result1 = toem(18, 14)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(
+        1.2857142857142858,
+        4
+      )
+
+      expect(toem(20, 10)).toBe("2em")
+      expect(toem(24, 12)).toBe("2em")
+    })
+
+    it("should handle zero with different contexts", () => {
+      expect(toem(0, 14)).toBe("0")
+      expect(toem(0, 20)).toBe("0")
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle decimal values", () => {
+      const result1 = toem(16.5, 16)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      // 16.5 / 16 = 1.03125, rounded to 4 decimals = 1.0313
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(1.0313, 4)
+
+      const result2 = toem(18.5, 14)
+      const match2 = result2.match(/^([\d.]+)em$/)
+      // 18.5 / 14 = 1.3214285714285714, rounded to 4 decimals = 1.3214
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(1.3214, 4)
+    })
+
+    it("should handle very small values", () => {
+      const result1 = toem(1, 16)
+      const match1 = result1.match(/^([\d.]+)em$/)
+      expect(Number.parseFloat(match1?.[1] || "0")).toBeCloseTo(0.0625, 4)
+
+      const result2 = toem(0.5, 16)
+      const match2 = result2.match(/^([\d.]+)em$/)
+      // 0.5 / 16 = 0.03125, rounded to 4 decimals = 0.0313
+      expect(Number.parseFloat(match2?.[1] || "0")).toBeCloseTo(0.0313, 4)
+    })
+
+    it("should handle very large values", () => {
+      expect(toem(100, 16)).toBe("6.25em")
+      expect(toem(200, 16)).toBe("12.5em")
+    })
+
+    it("should handle context larger than target", () => {
+      expect(toem(8, 16)).toBe("0.5em")
+      expect(toem(4, 16)).toBe("0.25em")
+    })
+  })
+})