bsmnt 0.2.0 → 0.2.5

package/src/templates/next-default/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/src/templates/next-default/components/ui/image/index.tsx

@@ -0,0 +1,219 @@
+/**
+ * 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)
+ * - Priority flag 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.priority - Prioritize loading 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 priority
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="Hero image"
+ *   aspectRatio={16/9}
+ *   priority // 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,
+  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",
+  priority = false,
+  ...props
+}: ImageProps) {
+  // 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 })}
+      priority={priority}
+      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 })}
+      {...props}
+    />
+  )
+}

package/src/templates/next-default/components/ui/link/index.tsx

@@ -0,0 +1,152 @@
+"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>;
+  }
+
+  // Block dangerous URIs (javascript:, data:, vbscript:)
+  const isDangerousHref = /^(javascript|data|vbscript):/i.test(href);
+  if (isDangerousHref) {
+    return <span {...getDivProps(props)}>{children}</span>;
+  }
+
+  // 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/src/templates/next-default/lib/utils/metadata.ts

@@ -1,4 +1,4 @@
-import type { Metadata } from "next"
+import type { Metadata } from "next";
 
 /**
  * Metadata Generation Utilities
@@ -8,26 +8,26 @@ import type { Metadata } from "next"
  */
 
 interface GenerateMetadataOptions {
-  title?: string
-  description?: string
-  keywords?: string[]
+  title?: string;
+  description?: string;
+  keywords?: string[];
   image?: {
-    url?: string
-    width?: number
-    height?: number
-    alt?: string
-  }
-  url?: string
-  siteName?: string
-  noIndex?: boolean
-  type?: "website" | "article"
-  publishedTime?: string
-  modifiedTime?: string
-  authors?: string[]
+    url?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+  };
+  url?: string;
+  siteName?: string;
+  noIndex?: boolean;
+  type?: "website" | "article";
+  publishedTime?: string;
+  modifiedTime?: string;
+  authors?: string[];
 }
 
 const APP_BASE_URL =
-  process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000"
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
 
 /**
  * Generate complete metadata object for pages
@@ -62,13 +62,13 @@ export function generatePageMetadata(
     publishedTime,
     modifiedTime,
     authors,
-  } = options
+  } = options;
 
-  const fullUrl = url ? `${APP_BASE_URL}${url}` : APP_BASE_URL
-  const imageUrl = image?.url || "/opengraph-image.jpg"
-  const imageWidth = image?.width || 1200
-  const imageHeight = image?.height || 630
-  const imageAlt = image?.alt || title || siteName
+  const fullUrl = url ? `${APP_BASE_URL}${url}` : APP_BASE_URL;
+  const imageUrl = image?.url || "/opengraph-image.jpg";
+  const imageWidth = image?.width || 1200;
+  const imageHeight = image?.height || 630;
+  const imageAlt = image?.alt || title || siteName;
 
   const metadata: Metadata = {
     metadataBase: new URL(APP_BASE_URL),
@@ -113,14 +113,14 @@ export function generatePageMetadata(
     other: {
       "fb:app_id": process.env.NEXT_PUBLIC_FACEBOOK_APP_ID || "",
     },
-  }
+  };
 
   if (noIndex) {
     metadata.robots = {
       index: false,
       follow: false,
-    }
+    };
   }
 
-  return metadata
+  return metadata;
 }

package/src/templates/next-default/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "basement-next-starter",
+  "name": "bsmnt-next-starter",
   "description": "Basement Next.js starter template",
   "version": "0.1.0",
   "private": true,
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "class-variance-authority": "^0.7.1",
-    "next": "16.1.4",
+    "next": "16.1.6",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "react-use": "^17.6.0",
@@ -35,10 +35,10 @@
     "zustand": "^5.0.10"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.11",
+    "@biomejs/biome": "2.3.14",
     "@clack/prompts": "^0.11.0",
     "@csstools/postcss-global-data": "^3.1.0",
-    "@next/bundle-analyzer": "16.1.1",
+    "@next/bundle-analyzer": "16.1.6",
     "@svgr/webpack": "^8.1.0",
     "@tailwindcss/postcss": "^4.1.18",
     "@types/bun": "^1.3.6",

package/src/templates/next-experiments/app/layout.tsx

@@ -1,23 +1,23 @@
-import type { Metadata, Viewport } from "next"
-import { Geist } from "next/font/google"
-import { type PropsWithChildren, Suspense } from "react"
-import { Link } from "@/components/ui/link"
-import { themes } from "@/lib/styles/colors"
-import { fontsVariable } from "@/lib/styles/fonts"
-import AppData from "@/package.json"
-import "@/lib/styles/css/index.css"
-import { cn } from "@/lib/styles/cn"
+import type { Metadata, Viewport } from "next";
+import { Geist } from "next/font/google";
+import { type PropsWithChildren, Suspense } from "react";
+import { Link } from "@/components/ui/link";
+import { themes } from "@/lib/styles/colors";
+import { fontsVariable } from "@/lib/styles/fonts";
+import AppData from "@/package.json";
+import "@/lib/styles/css/index.css";
+import { cn } from "@/lib/styles/cn";
 
-const APP_NAME = AppData.name
-const APP_DEFAULT_TITLE = "Basement Starter"
-const APP_TITLE_TEMPLATE = "%s - Basement Starter"
-const APP_DESCRIPTION = AppData.description
+const APP_NAME = AppData.name;
+const APP_DEFAULT_TITLE = "Basement Starter";
+const APP_TITLE_TEMPLATE = "%s - Basement Starter";
+const APP_DESCRIPTION = AppData.description;
 const APP_BASE_URL =
-  process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000"
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
 
 const geist = Geist({
   subsets: ["latin"],
-})
+});
 
 export const metadata: Metadata = {
   alternates: {
@@ -70,12 +70,12 @@ export const metadata: Metadata = {
       template: APP_TITLE_TEMPLATE,
     },
   },
-}
+};
 
 export const viewport: Viewport = {
   colorScheme: "normal",
   themeColor: themes.dark.primary,
-}
+};
 
 export default async function Layout({ children }: PropsWithChildren) {
   return (
@@ -100,5 +100,5 @@ export default async function Layout({ children }: PropsWithChildren) {
         {children}
       </body>
     </html>
-  )
+  );
 }

package/src/templates/next-experiments/app/robots.ts

@@ -1,7 +1,7 @@
-import type { MetadataRoute } from "next"
+import type { MetadataRoute } from "next";
 
 const APP_BASE_URL =
-  process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000"
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
 
 export default function robots(): MetadataRoute.Robots {
   return {
@@ -11,5 +11,5 @@ export default function robots(): MetadataRoute.Robots {
       disallow: [],
     },
     sitemap: `${APP_BASE_URL}/sitemap.xml`,
-  }
+  };
 }

package/src/templates/next-experiments/app/sitemap.ts

@@ -1,7 +1,7 @@
-import type { MetadataRoute } from "next"
+import type { MetadataRoute } from "next";
 
 const APP_BASE_URL =
-  process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000"
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const baseRoutes: MetadataRoute.Sitemap = [
@@ -11,6 +11,6 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
       changeFrequency: "daily",
       priority: 1,
     },
-  ]
-  return baseRoutes
+  ];
+  return baseRoutes;
 }

package/src/templates/next-experiments/biome.json

@@ -1,5 +1,5 @@
 {
-  "root": false,
+  "root": true,
   "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
   "assist": {
     "actions": {
@@ -245,6 +245,6 @@
   "vcs": {
     "clientKind": "git",
     "enabled": true,
-    "useIgnoreFile": true
+    "useIgnoreFile": false
   }
 }

package/src/templates/next-experiments/components/layout/theme/index.tsx

@@ -47,7 +47,7 @@ export function Theme({
 
   return (
     <>
-      {global && (
+      {global && /^[a-z]+$/.test(currentTheme) && (
         <script>
           {`document.documentElement.setAttribute('data-theme', '${currentTheme}');`}
         </script>

package/src/templates/next-experiments/components/layout/wrapper/index.tsx

@@ -3,20 +3,18 @@
  *
  * Customize the Header and Footer components for your project needs.
  */
-"use client"
-
-import cn from "clsx"
-import { Footer } from "@/components/layout/footer"
-import { Header } from "@/components/layout/header"
-import { Theme } from "@/components/layout/theme"
-import type { ThemeName } from "@/lib/styles/config"
+import cn from "clsx";
+import { Footer } from "@/components/layout/footer";
+import { Header } from "@/components/layout/header";
+import { Theme } from "@/components/layout/theme";
+import type { ThemeName } from "@/lib/styles/config";
 
 /**
  * Props for the Wrapper component.
  */
 interface WrapperProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Theme to apply ('dark' | 'light'). Defaults to 'dark'. */
-  theme?: ThemeName
+  theme?: ThemeName;
 }
 
 /**
@@ -61,5 +59,5 @@ export function Wrapper({
       </main>
       <Footer />
     </Theme>
-  )
+  );
 }