bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/webgl/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/webgl/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/webgl/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/webgl/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()

package/packages/create-basement-app/templates/webgl/lib/scripts/generate-component.ts

@@ -0,0 +1,322 @@
+#!/usr/bin/env bun
+/**
+ * Generate Component Module
+ *
+ * Generates new components with pre-configured templates through interactive prompts.
+ * Used by the unified generator: `bun run generate`
+ *
+ * Cross-platform compatible (Windows, macOS, Linux)
+ */
+
+import * as p from "@clack/prompts"
+import { createDir } from "./utils"
+
+interface ComponentOptions {
+  client?: boolean
+  category?: string
+}
+
+export interface ComponentConfig {
+  path: string
+  options: ComponentOptions
+}
+
+/**
+ * Interactive prompts for component configuration
+ */
+export const promptComponentConfig = async (): Promise<ComponentConfig> => {
+  const category = await p.select({
+    message: "Which category should this component belong to?",
+    options: [
+      {
+        value: "ui",
+        label: "UI Components",
+        hint: "Reusable primitives (buttons, inputs, etc.)",
+      },
+      {
+        value: "layout",
+        label: "Layout Components",
+        hint: "Site structure (navigation, footer, etc.)",
+      },
+      {
+        value: "magic",
+        label: "Magic Components",
+        hint: "Animations and visual enhancements",
+      },
+      {
+        value: "blocks",
+        label: "Block Components",
+        hint: "Pre-built page sections",
+      },
+    ],
+  })
+
+  if (p.isCancel(category)) {
+    p.cancel("Component generation cancelled")
+    process.exit(0)
+  }
+
+  const name = await p.text({
+    message: "What should the component be called?",
+    placeholder: "button, hero-section, animated-text",
+    validate: (value) => {
+      if (!value) return "Component name is required"
+      if (!/^[a-z][a-z0-9-]*$/.test(value)) {
+        return "Component name must be kebab-case (lowercase with hyphens)"
+      }
+      return undefined
+    },
+  })
+
+  if (p.isCancel(name)) {
+    p.cancel("Component generation cancelled")
+    process.exit(0)
+  }
+
+  const componentPath = `${category}/${name}`
+
+  const isClientComponent = await p.confirm({
+    message: "Should this be a client component ('use client')?",
+    initialValue: false,
+  })
+
+  if (p.isCancel(isClientComponent)) {
+    p.cancel("Component generation cancelled")
+    process.exit(0)
+  }
+
+  return {
+    path: componentPath,
+    options: {
+      client: isClientComponent,
+      category,
+    },
+  }
+}
+
+/**
+ * Convert kebab-case to PascalCase
+ */
+const toPascalCase = (str: string): string =>
+  str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("")
+
+/**
+ * Convert kebab-case to camelCase
+ */
+const toCamelCase = (str: string): string =>
+  str
+    .split("-")
+    .map((word, index) =>
+      index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)
+    )
+    .join("")
+
+/**
+ * Generate component index.tsx content
+ */
+const generateComponentContent = (
+  componentName: string,
+  options: ComponentOptions
+): string => {
+  const { client } = options
+  const pascalName = toPascalCase(componentName)
+  const camelCaseName = toCamelCase(componentName)
+  const directive = client ? `'use client'\n\n` : ""
+
+  return `${directive}import { cn } from '@/styles/cn'
+import type { HTMLAttributes, ReactNode } from 'react'
+import s from './${componentName}.module.css'
+
+interface ${pascalName}Props extends HTMLAttributes<HTMLDivElement> {
+  /** Component content */
+  children?: ReactNode
+}
+
+const ${camelCaseName}Variants = cva({
+  base: 'bg-primary text-white',
+  variants: {
+    variant: {
+      primary: 'bg-primary text-white',
+    },
+  },
+})
+
+/**
+ * ${pascalName} component.
+ *
+ * @example
+ * \`\`\`tsx
+ * import { ${pascalName} } from '@/components/${options.category}/${componentName}'
+ *
+ * <${pascalName}>
+ *   Content here
+ * </${pascalName}>
+ * \`\`\`
+ */
+export function ${pascalName}({
+  children,
+  className,
+  variant = 'primary',
+  ...props
+}: ${pascalName}Props) {
+  return (
+    <div className={cn(s.${camelCaseName}, className, ${pascalName}Variants({ variant: 'primary' }))} {...props}>
+      {children}
+    </div>
+  )
+}
+`
+}
+
+/**
+ * Generate CSS module content
+ */
+const generateCssContent = (componentName: string): string => {
+  const cssClassName = toCamelCase(componentName)
+
+  return `/* ${componentName}.module.css */
+
+.${cssClassName} {
+  /* Add your component styles here */
+}
+`
+}
+
+/**
+ * Update barrel export file
+ */
+const updateBarrelExport = async (
+  componentPath: string,
+  componentName: string
+): Promise<void> => {
+  const pathParts = componentPath.split("/")
+  const category = pathParts[0] ?? "components"
+  const barrelPath = `components/${category}/index.ts`
+  const pascalName = toPascalCase(componentName)
+
+  try {
+    // Check if barrel file exists
+    const file = Bun.file(barrelPath)
+    const exists = await file.exists()
+
+    if (!exists) {
+      // Create new barrel file with header comment based on category
+      const categoryTitles: Record<string, string> = {
+        ui: "UI Primitives - Reusable across any project",
+        layout: "Layout Components - Site chrome (customize per project)",
+        magic: "Magic Components - Animations and visual enhancements",
+        blocks: "Block Components - Pre-built page sections",
+      }
+
+      const header =
+        categoryTitles[category] || `${toPascalCase(category)} Components`
+      const content = `// ${header}
+// Import from '@/components/${category}' or '@/components/${category}/[component]'
+
+export { ${pascalName} } from './${componentName}'
+`
+      await Bun.write(barrelPath, content)
+      p.log.success(`Created barrel export: ${barrelPath}`)
+      return
+    }
+
+    // Update existing barrel file
+    const content = await file.text()
+
+    // Check if already exported
+    if (content.includes(`from './${componentName}'`)) {
+      p.log.warn(`Component already exported in ${barrelPath}`)
+      return
+    }
+
+    // Add export at the end, maintaining the file's style
+    const lines = content.split("\n")
+
+    // Find the last non-empty line to append after
+    let insertIndex = lines.length
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (lines[i]?.trim()) {
+        insertIndex = i + 1
+        break
+      }
+    }
+
+    // Insert the new export
+    lines.splice(
+      insertIndex,
+      0,
+      `export { ${pascalName} } from './${componentName}'`
+    )
+
+    await Bun.write(barrelPath, lines.join("\n"))
+    p.log.success(`Updated barrel export: ${barrelPath}`)
+  } catch (error) {
+    p.log.warn(
+      `Could not update barrel export: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+}
+
+/**
+ * Generate component files and directories
+ */
+export const createComponent = async (
+  componentPath: string,
+  options: ComponentOptions
+): Promise<void> => {
+  const s = p.spinner()
+
+  try {
+    const pathParts = componentPath.split("/")
+    const componentName = pathParts[pathParts.length - 1] ?? ""
+
+    // Validate component name
+    if (!/^[a-z][a-z0-9-]*$/.test(componentName)) {
+      throw new Error(
+        "Component name must be kebab-case (lowercase with hyphens)"
+      )
+    }
+
+    // Create directory structure
+    const componentDir = `components/${componentPath}`
+
+    s.start(`Generating component "${componentPath}"`)
+
+    // Create component directory (cross-platform)
+    await createDir(componentDir)
+
+    // Generate and write files
+    const componentContent = generateComponentContent(componentName, options)
+    const cssContent = generateCssContent(componentName)
+
+    await Bun.write(`${componentDir}/index.tsx`, componentContent)
+    await Bun.write(`${componentDir}/${componentName}.module.css`, cssContent)
+
+    s.stop(`Component "${componentPath}" generated successfully!`)
+
+    // Show what was created
+    p.log.success(`Created files:`)
+    p.log.message(`  📄 ${componentDir}/index.tsx`)
+    p.log.message(`  🎨 ${componentDir}/${componentName}.module.css`)
+
+    // Try to update barrel exports
+    await updateBarrelExport(componentPath, componentName)
+
+    const pascalName = toPascalCase(componentName)
+
+    p.note(
+      `Next steps:\n` +
+        `  1. Customize ${componentDir}/index.tsx\n` +
+        `  2. Style in ${componentDir}/${componentName}.module.css\n` +
+        `  3. Import: \`import { ${pascalName} } from '@/components/${componentPath}'\``
+    )
+  } catch (error) {
+    s.stop(`Failed to create component "${componentPath}"`)
+    throw error instanceof Error ? error : new Error(String(error))
+  }
+}
+
+// Export functions for use by unified create script