bsmnt 0.0.2 → 0.1.0

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

@@ -0,0 +1,193 @@
+/**
+ * Viewport Utilities
+ *
+ * Convert pixel values to viewport-relative sizes and relative units.
+ * Mirrors the SASS functions for consistent responsive scaling.
+ *
+ * @example
+ * ```ts
+ * import { tovw, torem, toem } from '@/utils/viewport'
+ *
+ * // Convert to viewport width units
+ * const paddingX = tovw(16, 24) // "1.5625vw" with a minimum of 24px
+ * const fontSize = tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ * const width = tovw(100, 50, 'desktop') // "max(50px, 6.94vw)"
+ *
+ * // Convert to rem/em
+ * const spacing = torem(24) // "1.5rem"
+ * const padding = toem(16, 14) // "1.14em"
+ * ```
+ *
+ * ## When to Use
+ *
+ * - **CSS**: Prefer the PostCSS functions `tovw()`, `torem()`, and `toem()`
+ * - **JavaScript/TypeScript**: Use these for dynamic calculations or inline styles
+ * - **Runtime calculations**: Use for canvas, WebGL, or dynamic sizing
+ */
+
+import { breakpoints } from "@/lib/styles/config"
+
+type ContextSize = keyof typeof breakpoints | number
+
+/**
+ * Resolves a context size to a pixel value.
+ *
+ * @param context - Context identifier or pixel value
+ * @returns Pixel value
+ */
+function resolveContext(context: ContextSize): number {
+  if (typeof context === "number") {
+    return context
+  }
+  return breakpoints[context] ?? breakpoints.desktop
+}
+
+/**
+ * Checks if a value is a context identifier (breakpoint key).
+ *
+ * @param value - Value to check
+ * @returns True if value is a breakpoint key
+ */
+function isContextIdentifier(
+  value: unknown
+): value is keyof typeof breakpoints {
+  return typeof value === "string" && value in breakpoints
+}
+
+/**
+ * Rounds a number to a maximum of 4 decimal places, removing trailing zeros.
+ *
+ * @param value - Number to round
+ * @returns Rounded number as string without trailing zeros
+ */
+function roundToMaxDecimals(value: number): string {
+  // 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")
+}
+
+// Function overloads for tovw
+export function tovw(target: number): string
+export function tovw(target: number, min: number): string
+export function tovw(target: number, context: ContextSize): string
+export function tovw(target: number, min: number, context: ContextSize): string
+/**
+ * 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
+ * - `tovw(target, context)` - Sets context (auto-detected if string identifier)
+ * - `tovw(target, min, context)` - Sets both min and context
+ *
+ * @param target - Target pixel value to convert
+ * @param minOrContext - Optional minimum pixel value OR context identifier
+ * @param context - Context size identifier (if min was provided)
+ * @returns CSS string with vw units (e.g., "6.94vw" or "max(50px, 6.94vw)")
+ *
+ * @example
+ * ```ts
+ * // Basic conversion
+ * tovw(100) // "6.94vw"
+ * tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ *
+ * // With minimum value
+ * tovw(100, 50) // "max(50px, 6.94vw)"
+ * tovw(100, 50, 'mobile') // "max(50px, 6.94vw)" with mobile context
+ *
+ * // Custom context
+ * tovw(100, 1920) // "5.21vw"
+ *
+ * // Handles zero
+ * tovw(0) // "0"
+ * ```
+ */
+export function tovw(
+  target: number,
+  minOrContext?: number | ContextSize,
+  context?: ContextSize
+): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  let min: number | undefined
+  let resolvedContext: ContextSize = "desktop"
+
+  if (minOrContext !== undefined) {
+    if (isContextIdentifier(minOrContext)) {
+      // Second param is context
+      resolvedContext = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    } else if (typeof minOrContext === "number") {
+      // Second param is min value
+      min = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    }
+  } else if (context !== undefined) {
+    // Only context provided as third param (legacy support)
+    resolvedContext = context
+  }
+
+  const contextSize = resolveContext(resolvedContext)
+  const vwValue = (target / contextSize) * 100
+
+  if (min !== undefined) {
+    return `max(${min}px, ${roundToMaxDecimals(vwValue)}vw)`
+  }
+
+  return `${roundToMaxDecimals(vwValue)}vw`
+}
+
+/**
+ * Converts a pixel value to rem units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Base font size in pixels (default: 16)
+ * @returns CSS string with rem units (e.g., "1.5rem")
+ *
+ * @example
+ * ```ts
+ * torem(24) // "1.5rem" (24 / 16)
+ * torem(18, 14) // "1.29rem" (18 / 14)
+ * torem(0) // "0"
+ * ```
+ */
+export function torem(target: number, context = 16): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}rem`
+}
+
+/**
+ * Converts a pixel value to em units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Context size in pixels (required)
+ * @returns CSS string with em units (e.g., "1.5em")
+ *
+ * @example
+ * ```ts
+ * toem(24, 16) // "1.5em" (24 / 16)
+ * toem(18, 14) // "1.29em" (18 / 14)
+ * toem(0, 16) // "0"
+ * ```
+ */
+export function toem(target: number, context: number): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}em`
+}

package/packages/create-basement-app/templates/experiment/next.config.ts

@@ -0,0 +1,142 @@
+import withBundleAnalyzer from "@next/bundle-analyzer"
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  reactCompiler: true,
+  typedRoutes: true,
+  turbopack: {
+    rules: {
+      "*.svg": {
+        loaders: [
+          {
+            loader: "@svgr/webpack",
+            options: {
+              memo: true,
+              dimensions: false,
+              svgoConfig: {
+                multipass: true,
+                plugins: [
+                  "removeDimensions",
+                  "removeOffCanvasPaths",
+                  "reusePaths",
+                  "removeElementsByAttr",
+                  "removeStyleElement",
+                  "removeScriptElement",
+                  "prefixIds",
+                  "cleanupIds",
+                  {
+                    name: "cleanupNumericValues",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "convertPathData",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "convertTransform",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "cleanupListOfValues",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                ],
+              },
+            },
+          },
+        ],
+        as: "*.js",
+      },
+    },
+  },
+  cacheComponents: true,
+  experimental: {
+    browserDebugInfoInTerminal: true,
+    optimizePackageImports: [
+      "@react-three/drei",
+      "@react-three/fiber",
+      "gsap",
+      "three",
+      "postprocessing",
+      "lenis",
+      "zustand",
+    ],
+  },
+  images: {
+    dangerouslyAllowSVG: true,
+    remotePatterns: [],
+    minimumCacheTTL: 60 * 60 * 24 * 30, // 30 days
+    qualities: [90],
+    formats: ["image/avif", "image/webp"],
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  },
+  headers: async () => [
+    {
+      source: "/(.*)",
+      headers: [
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        {
+          key: "Content-Security-Policy",
+          value: "frame-ancestors 'self';",
+        },
+        {
+          key: "X-Frame-Options",
+          value: "SAMEORIGIN",
+        },
+        {
+          key: "X-XSS-Protection",
+          value: "1; mode=block",
+        },
+        {
+          key: "X-DNS-Prefetch-Control",
+          value: "on",
+        },
+        {
+          key: "Strict-Transport-Security",
+          value: "max-age=63072000; includeSubDomains; preload",
+        },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
+      ],
+    },
+  ],
+  redirects: async () => [
+    {
+      source: "/home",
+      destination: "/",
+      permanent: true,
+    },
+  ],
+  rewrites: async () => [
+    {
+      source: "/",
+      destination: "/home",
+    },
+  ],
+}
+
+const bundleAnalyzerPlugin = withBundleAnalyzer({
+  enabled: process.env.ANALYZE === "true",
+})
+
+const NextApp = () => {
+  const plugins = [bundleAnalyzerPlugin]
+  return plugins.reduce((config, plugin) => plugin(config), nextConfig)
+}
+
+export default NextApp

package/packages/create-basement-app/templates/experiment/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "basement-next-starter",
+  "description": "Basement Next.js starter template",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "bun@1.3.5",
+  "scripts": {
+    "analyze": "cross-env ANALYZE=true bun run build",
+    "analyze:experimental": "next experimental-analyze",
+    "build": "bun run setup:styles && next build",
+    "dev": "bun ./lib/scripts/dev.ts",
+    "dev:https": "bun ./lib/scripts/dev.ts --https",
+    "dev:inspect": "bun ./lib/scripts/dev.ts --inspect",
+    "format": "biome format --write .",
+    "generate": "bun ./lib/scripts/generate.ts",
+    "lighthouse": "bunx @unlighthouse/cli --site http://localhost:3000",
+    "lint": "biome lint --max-diagnostics=200",
+    "lint:fix": "biome lint --write --unsafe --max-diagnostics=200",
+    "setup:styles": "bun ./lib/styles/scripts/setup-styles.ts",
+    "start": "next start",
+    "test": "bun test",
+    "test:setup": "bun test lib/scripts/setup-project.test.ts",
+    "typecheck": "tsgo --noEmit",
+    "typecheck:compare": "bun run typecheck:tsc && bun run typecheck",
+    "typecheck:tsc": "tsc --noEmit --incremental false"
+  },
+  "dependencies": {
+    "@radix-ui/react-navigation-menu": "^1.2.5",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "class-variance-authority": "^0.7.1",
+    "leva": "^0.9.35",
+    "lucide-react": "^0.474.0",
+    "next": "16.1.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-use": "^17.6.0",
+    "tailwind-merge": "^3.4.0",
+    "three": "^0.182.0",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.10"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@clack/prompts": "^0.11.0",
+    "@csstools/postcss-global-data": "^3.1.0",
+    "@next/bundle-analyzer": "16.1.1",
+    "@svgr/webpack": "^8.1.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/bun": "^1.3.6",
+    "@types/node": "^20.19.30",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.182.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260122.3",
+    "babel-plugin-react-compiler": "1.0.0",
+    "cross-env": "^10.1.0",
+    "postcss-functions": "^4.0.2",
+    "postcss-preset-env": "^10.6.1",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3"
+  },
+  "trustedDependencies": [
+    "@biomejs/biome",
+    "@tailwindcss/oxide",
+    "esbuild",
+    "sharp"
+  ]
+}

package/packages/create-basement-app/templates/experiment/postcss.config.mjs

@@ -0,0 +1,42 @@
+import { functions } from "./lib/styles/scripts/postcss-functions.mjs"
+
+/**
+ * PostCSS preset-env config
+ * @see Docs {@link https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/README.md#options}
+ * @see Features Flags {@link https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/FEATURES.md}
+ * @type {import('postcss-preset-env').pluginOptions}
+ */
+const presetEnvConfig = {
+  autoprefixer: {
+    flexbox: "no-2009",
+  },
+  stage: 3,
+  features: {
+    "custom-properties": false,
+    "custom-media-queries": true,
+    "nesting-rules": true,
+  },
+}
+
+/**
+ * PostCSS global data config
+ * Makes sure the css module files have access to these context files
+ * @see {@link https://github.com/csstools/postcss-global-data?tab=readme-ov-file#options}
+ * @type {import('@csstools/postcss-global-data').pluginOptions}
+ */
+const globalDataConfig = {
+  files: ["./lib/styles/css/root.css"],
+}
+
+const postcssConfig = {
+  // NOTE: Order is important
+  plugins: {
+    "@tailwindcss/postcss": {},
+    "@csstools/postcss-global-data": globalDataConfig,
+    "postcss-functions": { functions },
+    // NOTE: This has to be last config
+    "postcss-preset-env": presetEnvConfig,
+  },
+}
+
+export default postcssConfig

package/packages/create-basement-app/templates/experiment/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "noUncheckedSideEffectImports": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedIndexedAccess": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/packages/create-basement-app/templates/webgl/.biome/plugins/README.md

@@ -0,0 +1,21 @@
+## Plugins
+
+### 1. `no-anchor-element.grit`
+Enforces using Next.js `<Link>` component instead of HTML `<a>` elements.
+
+### 2. `no-unnecessary-forwardref.grit`
+Checks for unnecessary `forwardRef` usage in React 19 with the compiler.
+
+### 3. `no-relative-parent-imports.grit`
+Forbids relative parent imports (`../`) and encourages alias imports (`@/`).
+
+## Plugin Configuration
+
+The plugins are configured in `biome.json`:
+```json
+"plugins": [
+  "./biome-plugins/no-anchor-element.grit",
+  "./biome-plugins/no-unnecessary-forwardref.grit",
+  "./biome-plugins/no-relative-parent-imports.grit"
+]
+``` 

package/packages/create-basement-app/templates/webgl/.biome/plugins/no-anchor-element.grit

@@ -0,0 +1,12 @@
+language js;
+
+`<a $attrs>$content</a>` as $anchor where {
+    !$anchor <: within `if ($condition) { return ($jsx) }` where {
+        $condition <: contains or { `isExternal`, `isExternalSSR` }
+    },
+    register_diagnostic(
+        span = $anchor,
+        message = "Use custom Link component instead of <a> element. The Link component handles both internal and external links automatically.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/webgl/.biome/plugins/no-relative-parent-imports.grit

@@ -0,0 +1,10 @@
+language js;
+
+`import $imports from $source` as $import where {
+    $source <: r"['\"]\.\.\/\.\.\/.*['\"]",
+    register_diagnostic(
+        span = $import,
+        message = "Use alias imports (~/dir/) instead of deep relative imports (../../). Single level imports (../) are allowed for colocated files.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/webgl/.biome/plugins/no-unnecessary-forwardref.grit

@@ -0,0 +1,9 @@
+language js;
+
+`forwardRef($func)` as $ref where {
+    register_diagnostic(
+        span = $ref,
+        message = "forwardRef is unnecessary in React 19 with the compiler",
+        severity = "warning"
+    )
+}