bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/experiment/components/ui/image/README.md

@@ -0,0 +1,37 @@
+# Image Component
+
+Optimized images with smart loading, blur placeholders, and responsive sizing.
+
+## Usage
+
+```tsx
+import { Image } from '@/components/ui/image'
+
+// Basic
+<Image src="/hero.jpg" alt="Hero" aspectRatio={16/9} />
+
+// Priority (LCP images)
+<Image src="/hero.jpg" alt="Hero" aspectRatio={16/9} priority />
+
+// Responsive
+<Image 
+  src="/product.jpg" 
+  alt="Product" 
+  mobileSize="100vw" 
+  desktopSize="33vw" 
+/>
+```
+
+## Props
+
+| Prop | Description |
+|------|-------------|
+| `aspectRatio` | Prevents layout shift, enables blur placeholder |
+| `priority` | Eager loading for above-the-fold images |
+| `mobileSize` / `desktopSize` | Responsive sizing |
+
+## Best Practices
+
+- Always provide `aspectRatio` (prevents CLS)
+- Use `priority` for LCP images
+- Never use `next/image` directly

package/packages/create-basement-app/templates/experiment/components/ui/image/index.tsx

@@ -0,0 +1,224 @@
+/**
+ * Enhanced Image Component
+ *
+ * Next.js Image wrapper with optimized defaults and error handling.
+ * Always use this component instead of next/image directly.
+ */
+"use client"
+
+import cn from "clsx"
+import NextImage, { type ImageProps as NextImageProps } from "next/image"
+import type { CSSProperties, Ref } from "react"
+import { breakpoints } from "@/lib/styles/config"
+import s from "./image.module.css"
+
+/**
+ * Enhanced Image component props extending Next.js Image.
+ *
+ * Adds responsive sizing, aspect ratio support, and automatic blur placeholders.
+ * Always use this component instead of next/image directly.
+ */
+export type ImageProps = Omit<NextImageProps, "objectFit" | "alt"> & {
+  /** CSS object-fit property for image positioning */
+  objectFit?: CSSProperties["objectFit"]
+  /** Display as block element (adds display: block) */
+  block?: boolean
+  /** Size on mobile devices (e.g., "100vw", "50vw") */
+  mobileSize?: `${number}vw`
+  /** Size on desktop devices (e.g., "33vw", "25vw") */
+  desktopSize?: `${number}vw`
+  /** Ref for accessing the underlying img element */
+  ref?: Ref<HTMLImageElement>
+  /** Alt text for accessibility (required for meaningful images) */
+  alt?: string
+  /** Aspect ratio for automatic placeholder and layout stability */
+  aspectRatio?: number
+}
+
+// Memoize helper functions to avoid recreation
+const toBase64 = (str: string) =>
+  typeof window === "undefined"
+    ? Buffer.from(str).toString("base64")
+    : window.btoa(str)
+
+// Helper to generate blur placeholder with transparent background by default
+const generateShimmer = (w: number, h: number) => `
+  <svg width="${w}" height="${h}" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <defs>
+      <linearGradient id="g">
+        <stop stop-color="rgba(255,255,255,0.1)" offset="20%" />
+        <stop stop-color="rgba(255,255,255,0.2)" offset="50%" />
+        <stop stop-color="rgba(255,255,255,0.1)" offset="70%" />
+      </linearGradient>
+    </defs>
+    <rect width="${w}" height="${h}" fill="rgba(0,0,0,0)" />
+    <rect id="r" width="${w}" height="${h}" fill="url(#g)" />
+    <animate xlink:href="#r" attributeName="x" from="-${w}" to="${w}" dur="1s" repeatCount="indefinite"  />
+  </svg>`
+
+// Helper to determine if blur placeholder should be used
+const shouldUseBlurPlaceholder = (
+  src: NextImageProps["src"],
+  placeholder: string,
+  blurDataURL: string | undefined
+): boolean => {
+  if (!src) return false
+  const isSvg = typeof src === "string" && src.includes(".svg")
+  return !isSvg && placeholder === "blur" && !blurDataURL
+}
+
+// Helper to generate blur data URL
+const generateBlurDataURL = (
+  shouldUse: boolean,
+  aspectRatio: number | undefined,
+  existingBlurDataURL: string | undefined
+): string | undefined => {
+  if (!(shouldUse && aspectRatio)) return existingBlurDataURL
+
+  const shimmerSvg = generateShimmer(700, Math.round(700 / aspectRatio))
+  return `data:image/svg+xml;base64,${toBase64(shimmerSvg)}`
+}
+
+// Helper to determine final placeholder value
+const getFinalPlaceholder = (
+  shouldUse: boolean,
+  aspectRatio: number | undefined,
+  blurDataURL: string | undefined,
+  originalPlaceholder: NextImageProps["placeholder"]
+): NextImageProps["placeholder"] => {
+  if (!shouldUse) {
+    return originalPlaceholder === "blur" && !blurDataURL
+      ? "empty"
+      : originalPlaceholder
+  }
+
+  return aspectRatio || blurDataURL ? "blur" : "empty"
+}
+
+/**
+ * Enhanced Image component with responsive sizing and automatic optimizations.
+ *
+ * Always use this component instead of next/image directly. Provides:
+ * - Automatic responsive sizes generation
+ * - Smart blur placeholders with aspect ratio support
+ * - Performance optimizations (lazy loading by default)
+ * - Preload for LCP images
+ *
+ * @param props - Image props extending Next.js Image
+ * @param props.aspectRatio - Aspect ratio for layout stability and blur placeholder
+ * @param props.mobileSize - Size on mobile (e.g., "100vw")
+ * @param props.desktopSize - Size on desktop (e.g., "50vw")
+ * @param props.block - Display as block element
+ * @param props.preload - Enable preloading for LCP images
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with aspect ratio
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="Hero image"
+ *   aspectRatio={16/9}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // LCP image with preload
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="Hero image"
+ *   aspectRatio={16/9}
+ *   preload // Preloads image for LCP
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive grid image
+ * <Image
+ *   src="/product.jpg"
+ *   alt="Product"
+ *   aspectRatio={1}
+ *   mobileSize="100vw"
+ *   desktopSize="33vw"
+ * />
+ * ```
+ */
+export function Image({
+  style,
+  className,
+  loading,
+  objectFit = "cover",
+  quality = 90,
+  alt = "",
+  fill,
+  block = !fill,
+  width = block ? 1 : undefined,
+  height = block ? 1 : undefined,
+  mobileSize = "100vw",
+  desktopSize = "100vw",
+  sizes,
+  src,
+  unoptimized,
+  ref,
+  aspectRatio,
+  placeholder = "blur",
+  preload = false,
+  ...props
+}: ImageProps) {
+  // Determine loading strategy
+  const finalLoading = loading ?? (preload ? "eager" : "lazy")
+
+  // Generate responsive sizes if not provided
+  const finalSizes =
+    sizes ||
+    `(max-width: ${breakpoints.desktop}px) ${mobileSize}, ${desktopSize}`
+
+  // Early return after hooks
+  if (!src) return null
+
+  // Determine SVG status and placeholder logic
+  const isSvg = typeof src === "string" && src.includes(".svg")
+  const shouldUsePlaceholder = shouldUseBlurPlaceholder(
+    src,
+    placeholder,
+    props.blurDataURL
+  )
+  const blurDataURL = generateBlurDataURL(
+    shouldUsePlaceholder,
+    aspectRatio,
+    props.blurDataURL
+  )
+  const finalPlaceholder = getFinalPlaceholder(
+    shouldUsePlaceholder,
+    aspectRatio,
+    props.blurDataURL,
+    placeholder
+  )
+
+  return (
+    <NextImage
+      ref={ref}
+      fill={!block}
+      {...(width !== undefined && { width })}
+      {...(height !== undefined && { height })}
+      loading={finalLoading}
+      quality={quality}
+      alt={alt}
+      style={{
+        objectFit,
+        ...style,
+      }}
+      className={cn(className, block && s.block)}
+      sizes={finalSizes}
+      src={src}
+      unoptimized={unoptimized || isSvg}
+      draggable={false}
+      onDragStart={(e) => e.preventDefault()}
+      {...(finalPlaceholder && { placeholder: finalPlaceholder })}
+      {...(blurDataURL && { blurDataURL })}
+      preload={preload}
+      {...props}
+    />
+  )
+}

package/packages/create-basement-app/templates/experiment/components/ui/link/index.tsx

@@ -0,0 +1,146 @@
+"use client"
+
+import NextLink from "next/link"
+import { usePathname } from "next/navigation"
+import {
+  type AnchorHTMLAttributes,
+  type ComponentProps,
+  type MouseEvent,
+  useEffect,
+  useState,
+} from "react"
+
+// Helper to extract props safe for button elements
+function getButtonProps(props: Record<string, unknown>) {
+  const {
+    href,
+    target,
+    rel,
+    "data-external": _dataExternal,
+    ...buttonProps
+  } = props
+  return buttonProps
+}
+
+// Helper to extract props safe for div elements
+function getDivProps(props: Record<string, unknown>) {
+  const {
+    href,
+    target,
+    rel,
+    onClick,
+    "data-external": _dataExternal,
+    ...divProps
+  } = props
+  return divProps
+}
+
+type CustomLinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  keyof ComponentProps<typeof NextLink> | "href"
+> &
+  Omit<ComponentProps<typeof NextLink>, "href"> & {
+    href?: string
+    onClick?: (e: MouseEvent<HTMLElement>) => void
+    scroll?: boolean
+  }
+
+export function Link({
+  href,
+  children,
+  onClick,
+  scroll = false, // Default to false to prevent scroll restoration warnings with fixed/sticky elements
+  ...props
+}: CustomLinkProps) {
+  const [shouldPrefetch, setShouldPrefetch] = useState(false)
+  const [isExternal, setIsExternal] = useState(false)
+  const [isActive, setIsActive] = useState(false)
+
+  // Get pathname - deferred to avoid blocking static generation
+  // usePathname is safe to call but we defer the active check to useEffect
+  const pathname = usePathname()
+
+  useEffect(() => {
+    // Check if this link is active (current page)
+    if (href && pathname) {
+      setIsActive(pathname === href)
+    }
+  }, [href, pathname])
+
+  useEffect(() => {
+    // Skip if no href
+    if (!href) return
+
+    // Check if external link
+    try {
+      const url = new URL(href, window.location.href)
+      setIsExternal(url.host !== window.location.host)
+    } catch {
+      setIsExternal(false)
+    }
+
+    // Only prefetch on good connections
+    const connection = (
+      navigator as Navigator & {
+        connection?: { effectiveType: string; saveData: boolean }
+      }
+    ).connection
+    if (connection) {
+      const { effectiveType, saveData } = connection
+      setShouldPrefetch(effectiveType === "4g" && !saveData)
+    } else {
+      // Default to prefetching if API not available
+      setShouldPrefetch(true)
+    }
+  }, [href])
+
+  // If no href is provided but there's an onClick, render a button
+  if (!href && onClick) {
+    return (
+      <button
+        onClick={(e: MouseEvent<HTMLButtonElement>) => onClick(e)}
+        type="button"
+        {...getButtonProps(props)}
+      >
+        {children}
+      </button>
+    )
+  }
+
+  // If no href and no onClick, render a div
+  if (!href) {
+    return <div {...getDivProps(props)}>{children}</div>
+  }
+
+  // For SSR, check if it's external based on the href pattern
+  const isExternalSSR =
+    href.startsWith("http://") || href.startsWith("https://")
+
+  if (isExternalSSR || isExternal) {
+    return (
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        data-external
+        onClick={onClick}
+        {...props}
+      >
+        {children}
+      </a>
+    )
+  }
+
+  return (
+    <NextLink
+      href={href as ComponentProps<typeof NextLink>["href"]}
+      prefetch={shouldPrefetch}
+      scroll={scroll}
+      data-active={isActive || undefined}
+      {...(onClick && { onClick })}
+      {...props}
+    >
+      {children}
+    </NextLink>
+  )
+}

package/packages/create-basement-app/templates/experiment/lib/README.md

@@ -0,0 +1,33 @@
+# Lib
+
+Non-UI code: hooks, integrations, styles, and utilities.
+
+> **Rule**: Renders UI → `components/` · Everything else → `lib/`
+
+## Quick Imports
+
+```tsx
+// Utilities - explicit imports for better tree-shaking
+import { clamp, lerp } from '@/lib/utils/math'
+import { slugify } from '@/lib/utils/strings'
+
+// Styles
+import { colors, themes, breakpoints } from '@/lib/styles/config'
+```
+
+## Directories
+
+| Directory | Purpose | Optional? |
+|-----------|---------|-----------|
+| [hooks/](hooks/README.md) | React hooks + Zustand store | ❌ Core |
+| [styles/](styles/README.md) | CSS & Tailwind config | ❌ Core |
+| [utils/](utils/README.md) | Pure utility functions | ❌ Core |
+
+## Scripts
+
+```bash
+bun dev              # Start dev server
+bun run generate     # Generate pages/components
+bun run setup:project  # Configure integrations
+bun setup:styles     # Regenerate CSS
+```

package/packages/create-basement-app/templates/experiment/lib/constants.ts

@@ -0,0 +1,12 @@
+const EXPERIMENTS = [
+  {
+    name: "EXPERIMENT 1",
+    path: "/experiment-1",
+  },
+  {
+    name: "EXPERIMENT 2",
+    path: "/experiment-2",
+  },
+]
+
+export default EXPERIMENTS

package/packages/create-basement-app/templates/experiment/lib/hooks/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Custom React Hooks
+ *
+ * Import individual hooks:
+ *   import { useDeviceDetection } from '@/hooks/use-device-detection'
+ *
+ * Or import from barrel:
+ *   import { useDeviceDetection, usePrefetch } from '@/hooks/use-device-detection'
+ */
+
+export { useDeviceDetection } from "./use-device-detection"
+export { usePrefetch } from "./use-prefetch"

package/packages/create-basement-app/templates/experiment/lib/hooks/use-device-detection.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from "react"
+import { useMedia } from "react-use"
+import { breakpoints } from "@/lib/styles/config"
+
+/**
+ * Hook for detecting device capabilities and characteristics.
+ *
+ * Provides comprehensive device detection including screen size, input methods,
+ * performance preferences, and browser capabilities. Useful for responsive design,
+ * performance optimization, and feature detection.
+ *
+ * @returns Object with device detection results
+ *
+ * @example
+ * ```tsx
+ * import { useDeviceDetection } from '@/hooks/use-device-detection'
+ *
+ * function ResponsiveComponent() {
+ *   const {
+ *     isMobile,
+ *     isDesktop,
+ *     isReducedMotion,
+ *     isWebGL,
+ *     isLowPowerMode,
+ *     dpr,
+ *     isSafari
+ *   } = useDeviceDetection()
+ *
+ *   // Adapt behavior based on device capabilities
+ *   if (isReducedMotion) {
+ *     // Disable animations
+ *   }
+ *
+ *   if (isWebGL && !isLowPowerMode) {
+ *     // Enable WebGL features
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       {isMobile ? <MobileLayout /> : <DesktopLayout />}
+ *       {isSafari && <SafariSpecificStyles />}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Performance optimizations
+ * const { isLowPowerMode, dpr, isReducedMotion } = useDeviceDetection()
+ *
+ * // Reduce quality on low-power devices
+ * const quality = isLowPowerMode ? 'low' : 'high'
+ * const pixelRatio = Math.min(dpr || 1, 2) // Cap DPR
+ *
+ * // Respect user motion preferences
+ * const enableAnimations = !isReducedMotion
+ * ```
+ */
+export function useDeviceDetection() {
+  const isMobile = useMedia(`(max-width: ${breakpoints.mobile - 1}px)`, true)
+  const isReducedMotion = useMedia("(prefers-reduced-motion: reduce)")
+  const [dpr, setDpr] = useState<number | undefined>(undefined)
+  const [isSafari, setIsSafari] = useState<boolean | undefined>(undefined)
+
+  // Check for low power mode with fallback for unsupported browsers
+  const isTouchDevice = useMedia("(any-pointer: coarse) and (hover: none)")
+
+  useEffect(() => {
+    setDpr(window.devicePixelRatio)
+    setIsSafari(/^((?!chrome|android).)*safari/i.test(navigator.userAgent))
+  }, [])
+
+  return {
+    isMobile,
+    isReducedMotion,
+    isTouchDevice,
+    dpr,
+    isSafari,
+  }
+}

package/packages/create-basement-app/templates/experiment/lib/hooks/use-media-breakpoint.ts

@@ -0,0 +1,15 @@
+import { useMedia } from "react-use"
+import { breakpoints } from "@/lib/styles/config"
+
+/**
+ * Hook for detecting if the viewport is at a specific breakpoint.
+ *
+ * @param breakpoint - The breakpoint to detect
+ * @returns True if the viewport is at the breakpoint
+ */
+export function useMediaBreakpoint(
+  breakpoint: keyof typeof breakpoints,
+  defaultState = false
+) {
+  return useMedia(`(min-width: ${breakpoints[breakpoint]}px)`, defaultState)
+}

package/packages/create-basement-app/templates/experiment/lib/hooks/use-prefetch.ts

@@ -0,0 +1,74 @@
+import type { Route } from "next"
+import { useRouter } from "next/navigation"
+import { useEffect, useRef } from "react"
+
+/**
+ * Hook to prefetch a route when an element becomes visible in the viewport
+ * @param href - The route to prefetch
+ * @param options - Intersection Observer options
+ * @returns ref to attach to the element that should trigger prefetching
+ */
+export function usePrefetch<T extends HTMLElement = HTMLElement>(
+  href: Route | null | undefined,
+  options?: IntersectionObserverInit
+) {
+  const ref = useRef<T>(null)
+  const router = useRouter()
+  const prefetchedRef = useRef(false)
+
+  useEffect(() => {
+    // Early return if no href or already prefetched
+    if (!href || prefetchedRef.current) return
+
+    const element = ref.current
+    if (!element) return
+
+    // Reset prefetched state when href changes
+    prefetchedRef.current = false
+
+    const handleIntersection = (entries: IntersectionObserverEntry[]) => {
+      const [entry] = entries
+      if (entry?.isIntersecting && !prefetchedRef.current) {
+        // Check network conditions before prefetching
+        const connection = (
+          navigator as Navigator & {
+            connection?: NetworkInformation
+          }
+        ).connection
+
+        const shouldPrefetch =
+          !connection ||
+          (connection.effectiveType !== "slow-2g" &&
+            connection.effectiveType !== "2g" &&
+            !connection.saveData)
+
+        if (shouldPrefetch) {
+          router.prefetch(href)
+          prefetchedRef.current = true
+        }
+      }
+    }
+
+    const observer = new IntersectionObserver(handleIntersection, {
+      rootMargin: "50px",
+      ...options,
+    })
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [href, options, router])
+
+  // Return null ref if href is not provided
+  return href ? ref : { current: null }
+}
+
+// TypeScript types for Network Information API
+interface NetworkInformation {
+  readonly effectiveType: "slow-2g" | "2g" | "3g" | "4g"
+  readonly saveData: boolean
+  readonly rtt?: number
+  readonly downlink?: number
+}

package/packages/create-basement-app/templates/experiment/lib/scripts/dev.ts

@@ -0,0 +1,52 @@
+/**
+ * Cross-platform parallel dev script
+ * Replaces npm-run-all for running multiple processes simultaneously
+ * Works on Windows, macOS, and Linux using Bun's native APIs
+ */
+
+import { bunExecutable, colorEnv } from "./utils"
+
+const isHttps = process.argv.includes("--https")
+const isInspect = process.argv.includes("--inspect")
+
+// Build next dev command args
+const nextDevArgs = [bunExecutable, "next", "dev"]
+if (isHttps) nextDevArgs.push("--experimental-https")
+if (isInspect) nextDevArgs.push("--inspect")
+
+// Build environment with FORCE_COLOR
+const devEnv = colorEnv()
+
+const processes = [
+  // Style watcher
+  Bun.spawn(
+    [bunExecutable, "--watch", "./lib/styles/scripts/setup-styles.ts"],
+    {
+      stdout: "inherit",
+      stderr: "inherit",
+      env: devEnv,
+    }
+  ),
+
+  // Next.js dev server
+  Bun.spawn(nextDevArgs, {
+    stdout: "inherit",
+    stderr: "inherit",
+    env: devEnv,
+  }),
+]
+
+// Handle graceful shutdown
+const cleanup = () => {
+  for (const proc of processes) {
+    proc.kill()
+  }
+  process.exit(0)
+}
+
+process.on("SIGINT", cleanup)
+process.on("SIGTERM", cleanup)
+
+// Wait for any process to exit (if one crashes, we want to know)
+await Promise.race(processes.map((p) => p.exited))
+cleanup()