@snowcone-app/ui 0.1.43 → 0.2.1

package/src/layouts/pdp/PDPLayout.tsx

@@ -0,0 +1,246 @@
+"use client";
+
+import React from "react";
+import {
+  useMediaQuery,
+  useViewportDimensions,
+  useResponsiveImageCap,
+  useWideMonitorMode,
+  type ViewportDimensions,
+  type ResponsiveImageCapInfo,
+} from "../../hooks/viewport";
+import { ImageEdgeBlur } from "./ImageEdgeBlur";
+
+/**
+ * Props passed to the hero image render function.
+ */
+export interface HeroImageRenderProps {
+  /** Maximum width in pixels for the image (responsive to ultra-wide monitors) */
+  maxWidth: number;
+  /** Whether we're in wide monitor mode (images don't cover full viewport) */
+  isWideMonitor: boolean;
+  /** Full viewport dimensions */
+  dimensions: ViewportDimensions;
+  /** Detailed image cap info */
+  imageCapInfo: ResponsiveImageCapInfo;
+}
+
+/**
+ * Props passed to the mobile carousel render function.
+ */
+export interface CarouselRenderProps {
+  /** Image URLs or CarouselImage objects */
+  images: string[];
+}
+
+/**
+ * Props passed to the content render function.
+ */
+export interface ContentRenderProps {
+  /** Whether we're on desktop (true), mobile (false), or unknown/SSR (null) */
+  isDesktop: boolean | null;
+  /** Whether we're in wide monitor mode */
+  isWideMonitor: boolean;
+}
+
+export interface PDPLayoutProps {
+  /**
+   * Render function for the hero/main product image on desktop.
+   * Receives responsive sizing info based on viewport.
+   */
+  renderHeroImage: (props: HeroImageRenderProps) => React.ReactNode;
+
+  /**
+   * Render function for the main content (options, cart button, etc.).
+   * This renders in both mobile and desktop layouts.
+   */
+  renderContent: (props: ContentRenderProps) => React.ReactNode;
+
+  /**
+   * Optional render function for the mobile product carousel.
+   * If not provided, mobile will only show the content section.
+   */
+  renderMobileCarousel?: (props: CarouselRenderProps) => React.ReactNode;
+
+  /**
+   * Image URLs for mobile carousel.
+   * Only used if renderMobileCarousel is provided.
+   */
+  carouselImages?: string[];
+
+  /**
+   * Sidebar width as a percentage (default: 0.35 for 35%).
+   * Used for wide monitor calculations.
+   */
+  sidebarPercent?: number;
+
+  /**
+   * Sidebar width as CSS value for desktop layout (default: "35%").
+   */
+  sidebarWidth?: string;
+
+  /**
+   * Whether to show edge blur on wide monitors (default: true).
+   */
+  showEdgeBlur?: boolean;
+
+  /**
+   * Current image URL for the edge blur effect.
+   * Required if showEdgeBlur is true.
+   */
+  blurImageSrc?: string;
+
+  /**
+   * Height of the image container as CSS value (default: "83vw").
+   * Used for edge blur positioning.
+   */
+  containerHeight?: string;
+
+  /**
+   * Additional class names for the layout container.
+   */
+  className?: string;
+
+  /**
+   * Children rendered after the layout (floating elements, FABs, etc.).
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * PDPLayout - All-in-one Product Detail Page layout component.
+ *
+ * Handles:
+ * - Mobile vs desktop layout switching (SSR-safe)
+ * - Wide monitor detection and handling
+ * - Responsive image capping for ultra-wide monitors
+ * - Edge blur effect for image gaps
+ *
+ * Uses render props for maximum flexibility while handling the
+ * complex viewport-aware logic internally.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <PDPLayout
+ *   carouselImages={mockupUrls}
+ *   renderHeroImage={({ maxWidth }) => (
+ *     <HeroProductImage maxWidth={maxWidth} />
+ *   )}
+ *   renderContent={() => (
+ *     <>
+ *       <ProductOptions />
+ *       <AddToCart />
+ *     </>
+ *   )}
+ *   renderMobileCarousel={({ images }) => (
+ *     <MobileProductCarousel images={images} />
+ *   )}
+ * />
+ * ```
+ *
+ * @example With edge blur
+ * ```tsx
+ * <PDPLayout
+ *   showEdgeBlur
+ *   blurImageSrc={currentMockupUrl}
+ *   renderHeroImage={...}
+ *   renderContent={...}
+ * >
+ *   <FloatingActionGroup />
+ * </PDPLayout>
+ * ```
+ */
+export function PDPLayout({
+  renderHeroImage,
+  renderContent,
+  renderMobileCarousel,
+  carouselImages = [],
+  sidebarPercent = 0.35,
+  sidebarWidth = "35%",
+  showEdgeBlur = true,
+  blurImageSrc,
+  containerHeight = "83vw",
+  className = "",
+  children,
+}: PDPLayoutProps) {
+  // SSR-safe viewport detection
+  const isDesktop = useMediaQuery("(min-width: 768px)");
+
+  // Consolidated viewport dimensions (single resize listener on desktop, none on mobile)
+  const dimensions = useViewportDimensions(isDesktop);
+
+  // Responsive image capping for ultra-wide monitors
+  const imageCapInfo = useResponsiveImageCap(dimensions);
+
+  // Wide monitor mode detection
+  const isWideMonitor = useWideMonitorMode(imageCapInfo, sidebarPercent);
+
+  // Render props data
+  const heroProps: HeroImageRenderProps = {
+    maxWidth: imageCapInfo.maxWidthPx,
+    isWideMonitor,
+    dimensions,
+    imageCapInfo,
+  };
+
+  const contentProps: ContentRenderProps = {
+    isDesktop,
+    isWideMonitor,
+  };
+
+  return (
+    <div className={`pdp-layout ${className}`}>
+      {/* Mobile Layout */}
+      {(isDesktop === false || isDesktop === null) && (
+        <div className="md:hidden">
+          {/* Mobile Carousel (if provided) */}
+          {renderMobileCarousel && (
+            <div className="mobile-carousel-container">
+              {renderMobileCarousel({ images: carouselImages })}
+            </div>
+          )}
+
+          {/* Mobile Content */}
+          <div className="mobile-content p-4">
+            {renderContent(contentProps)}
+          </div>
+        </div>
+      )}
+
+      {/* Desktop Layout */}
+      {(isDesktop === true || isDesktop === null) && (
+        <div className="hidden md:block relative">
+          {/* Hero Image Section */}
+          <div className="desktop-hero relative">
+            {renderHeroImage(heroProps)}
+
+            {/* Edge Blur for Wide Monitors */}
+            {showEdgeBlur && blurImageSrc && isWideMonitor && (
+              <ImageEdgeBlur
+                imageSrc={blurImageSrc}
+                imageCapInfo={imageCapInfo}
+                sidebarPercent={sidebarPercent}
+                sidebarWidth={sidebarWidth}
+                containerHeight={containerHeight}
+              />
+            )}
+          </div>
+
+          {/* Desktop Sidebar/Content */}
+          <div
+            className="desktop-sidebar"
+            style={{
+              width: sidebarWidth,
+              maxWidth: "24rem",
+            }}
+          >
+            {renderContent(contentProps)}
+          </div>
+        </div>
+      )}
+
+      {/* Floating Elements (FABs, etc.) */}
+      {children}
+    </div>
+  );
+}

package/src/layouts/pdp/SimpleImageBlur.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import React from "react";
+
+/**
+ * Blur configuration - these values produce smooth edge blur effects
+ */
+const BLUR_CONFIG = {
+  blur: 24,
+  crossfade: 60,
+} as const;
+
+/**
+ * Progressive blur layers for smooth sharp-to-blurred transition.
+ */
+const BLUR_LAYERS = [
+  { blur: Math.round(BLUR_CONFIG.blur * 0.2), zone: 0.3 },
+  { blur: Math.round(BLUR_CONFIG.blur * 0.5), zone: 0.6 },
+  { blur: BLUR_CONFIG.blur, zone: 1.0 },
+];
+
+/**
+ * Generate smooth fade-in mask gradient from left edge
+ */
+function getFadeInMask(crossfadeWidth: number): string {
+  return `linear-gradient(to right,
+    transparent 0px,
+    rgba(0,0,0,0.02) ${crossfadeWidth * 0.05}px,
+    rgba(0,0,0,0.08) ${crossfadeWidth * 0.15}px,
+    rgba(0,0,0,0.2) ${crossfadeWidth * 0.3}px,
+    rgba(0,0,0,0.4) ${crossfadeWidth * 0.5}px,
+    rgba(0,0,0,0.6) ${crossfadeWidth * 0.7}px,
+    rgba(0,0,0,0.8) ${crossfadeWidth * 0.85}px,
+    rgba(0,0,0,0.95) ${crossfadeWidth}px,
+    black ${crossfadeWidth + 10}px
+  )`;
+}
+
+export interface SimpleImageBlurProps {
+  /** Source URL of the image to blur */
+  imageSrc: string;
+  /** Width of the blur box in pixels */
+  width: number;
+  /** Height of the blur box (CSS value, e.g., "100%", "500px") */
+  height?: string;
+  /** Additional CSS class names */
+  className?: string;
+  /** Object position for the image (default: "center") */
+  objectPosition?: string;
+}
+
+/**
+ * SimpleImageBlur - A simple blur box component with explicit dimensions.
+ *
+ * Renders a box of specified dimensions filled with progressively blurred
+ * versions of the source image. The blur fades in from the left edge for
+ * seamless blending with adjacent sharp images.
+ *
+ * Usage: Position this component where you need blur, and specify exact dimensions.
+ * The caller is responsible for layout/positioning.
+ *
+ * @example
+ * ```tsx
+ * // Position as overlay on right side of container
+ * <div className="relative">
+ *   <img src={heroImage} className="w-full" />
+ *   <div className="absolute top-0 right-0 bottom-0" style={{ width: 300 }}>
+ *     <SimpleImageBlur
+ *       imageSrc={heroImage}
+ *       width={300}
+ *       height="100%"
+ *     />
+ *   </div>
+ * </div>
+ * ```
+ */
+export const SimpleImageBlur = React.memo(function SimpleImageBlur({
+  imageSrc,
+  width,
+  height = "100%",
+  className = "",
+  objectPosition = "center",
+}: SimpleImageBlurProps) {
+  if (!imageSrc || width <= 0) return null;
+
+  // Generate fade-in mask for smooth transition from left
+  const fadeInMask = getFadeInMask(BLUR_CONFIG.crossfade);
+
+  // Extend width slightly to prevent blur edge artifacts
+  const extendedWidth = width + BLUR_CONFIG.blur * 2;
+
+  return (
+    <div
+      className={`relative overflow-hidden ${className}`}
+      style={{
+        width,
+        height,
+      }}
+    >
+      {/* Blur layers with progressive blur amounts */}
+      {BLUR_LAYERS.map((layer, index) => {
+        // Each layer has a mask that reveals it in its zone
+        // Last layer has no mask (fills everything)
+        const layerMask =
+          index === BLUR_LAYERS.length - 1
+            ? fadeInMask
+            : `linear-gradient(to right,
+                black 0%,
+                black ${layer.zone * 100}%,
+                transparent ${layer.zone * 100 + 10}%)`;
+
+        return (
+          <img
+            key={`blur-${index}`}
+            src={imageSrc}
+            alt=""
+            crossOrigin="anonymous"
+            style={{
+              position: "absolute",
+              // Extend bounds slightly to prevent edge artifacts
+              top: "-5%",
+              left: "-5%",
+              bottom: "-5%",
+              width: `${extendedWidth * 1.1}px`,
+              height: "110%",
+              objectFit: "cover",
+              objectPosition,
+              filter: `blur(${layer.blur}px)`,
+              clipPath: "inset(0)",
+              maskImage: layerMask,
+              WebkitMaskImage: layerMask,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+});
+
+export default SimpleImageBlur;

package/src/layouts/pdp/index.ts

@@ -0,0 +1,40 @@
+/**
+ * PDP (Product Detail Page) Layout Components
+ *
+ * A collection of components for building product detail pages with:
+ * - Mobile/desktop responsive switching
+ * - Ultra-wide monitor support
+ * - Render props for maximum flexibility
+ *
+ * @example
+ * ```tsx
+ * import { PDPLayout } from '@snowcone-app/ui';
+ *
+ * <PDPLayout
+ *   renderHeroImage={({ maxWidth }) => <HeroProductImage maxWidth={maxWidth} />}
+ *   renderContent={() => <ProductOptions />}
+ *   renderMobileCarousel={({ images }) => <MobileProductCarousel images={images} />}
+ *   carouselImages={mockupUrls}
+ * />
+ * ```
+ */
+
+export { PDPLayout } from "./PDPLayout";
+export type {
+  PDPLayoutProps,
+  HeroImageRenderProps,
+  CarouselRenderProps,
+  ContentRenderProps,
+} from "./PDPLayout";
+
+export { ImageEdgeBlur } from "./ImageEdgeBlur";
+export type { ImageEdgeBlurProps } from "./ImageEdgeBlur";
+
+export { SimpleImageBlur } from "./SimpleImageBlur";
+export type { SimpleImageBlurProps } from "./SimpleImageBlur";
+
+export { EdgeBlurBox } from "./EdgeBlurBox";
+export type { EdgeBlurBoxProps } from "./EdgeBlurBox";
+
+export { ImageBlurExtension } from "./ImageBlurExtension";
+export type { ImageBlurExtensionProps } from "./ImageBlurExtension";

package/src/lib/env.ts

@@ -0,0 +1,15 @@
+/**
+ * Bundler-agnostic env reader.
+ *
+ * `@snowcone-app/ui` ships browser code that must import cleanly under any
+ * bundler — Next, but also Vite/CRA/esbuild where `process` is not defined.
+ * A bare `process.env.X` at module top-level throws `ReferenceError: process
+ * is not defined` during module evaluation, which surfaces as a silent
+ * white-screen with zero console errors (an uncaught module-eval exception).
+ *
+ * `globalThis.process?.env?.[key]` never throws: it reads undefined instead of
+ * referencing a missing binding. Always use this instead of bare `process.env`.
+ */
+export function readEnv(key: string): string | undefined {
+  return globalThis.process?.env?.[key];
+}

package/src/lib/locale.ts

@@ -0,0 +1,167 @@
+import brandConfig from "@snowcone-app/brand";
+import type {
+  SupportedLanguage,
+  SupportedCountry,
+  SupportedLocale,
+  BrandLocale,
+  BrandAssets,
+} from "@snowcone-app/brand";
+
+export type { SupportedLanguage, SupportedCountry, SupportedLocale, BrandLocale, BrandAssets };
+
+// ---------------------------------------------------------------------------
+// Brand access
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns brand data for a language. Throws if the language is missing —
+ * brand tokens must never silently fall back. See ADR-0035.
+ */
+export function getBrand(language: SupportedLanguage): BrandLocale {
+  const data = (brandConfig.locales as Record<string, BrandLocale>)[language];
+  if (!data) {
+    throw new Error(
+      `[brand] Missing language "${language}" in brand.json. ` +
+        `Available: ${Object.keys(brandConfig.locales).join(", ")}. ` +
+        `Add it to brand.json (requires trademark + marketing sign-off).`
+    );
+  }
+  return data;
+}
+
+/** Global brand assets shared across all locales. */
+export const brandAssets: BrandAssets = brandConfig.global_assets;
+
+// ---------------------------------------------------------------------------
+// Currency formatting
+// ---------------------------------------------------------------------------
+
+export interface FormatCurrencyOptions {
+  /** Input is in cents (default: true). When false, input is whole dollars. */
+  inCents?: boolean;
+  /** ISO 4217 currency code (default: "USD"). */
+  currency?: string;
+  /** Minimum fraction digits (default: 0 — hides ".00"). */
+  minimumFractionDigits?: number;
+  /** Maximum fraction digits (default: 2). */
+  maximumFractionDigits?: number;
+  /** Fallback string when amount is null/undefined (default: "—"). */
+  fallback?: string;
+}
+
+/**
+ * Locale-aware currency formatting. Language controls number formatting
+ * (decimal separator, digit grouping); currency is independent.
+ *
+ * @example
+ * ```ts
+ * formatCurrency(2999)                                    // "$29.99"  (cents, en, USD)
+ * formatCurrency(2900)                                    // "$29"     (hides .00)
+ * formatCurrency(29.99, "en", { inCents: false })         // "$29.99"
+ * formatCurrency(2999, "es", { currency: "EUR" })         // "29,99 €"
+ * formatCurrency(2999, "es", { currency: "USD" })         // "29,99 US$"
+ * formatCurrency(2999, "zh-CN")                           // "US$29.99"
+ * formatCurrency(null)                                    // "—"
+ * ```
+ */
+export function formatCurrency(
+  amount: number | null | undefined,
+  language: SupportedLanguage | string = "en",
+  options: FormatCurrencyOptions = {}
+): string {
+  if (amount == null) return options.fallback ?? "—";
+
+  const {
+    inCents = true,
+    currency = "USD",
+    minimumFractionDigits = 0,
+    maximumFractionDigits = 2,
+  } = options;
+
+  const value = inCents ? amount / 100 : amount;
+
+  // Map our language keys to BCP 47 tags that Intl understands
+  const bcp47 = languageToIntl(language);
+
+  return new Intl.NumberFormat(bcp47, {
+    style: "currency",
+    currency,
+    minimumFractionDigits,
+    maximumFractionDigits,
+  }).format(value);
+}
+
+// ---------------------------------------------------------------------------
+// Date formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Locale-aware date formatting. Replaces all hardcoded `toLocaleDateString("en-US", ...)`.
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date())                             // "Apr 10, 2026" (en)
+ * formatDate("2026-04-10", "zh-CN")                  // "2026年4月10日"
+ * formatDate(new Date(), "en", { dateStyle: "full" }) // "Friday, April 10, 2026"
+ * formatDate(null)                                    // "—"
+ * ```
+ */
+export function formatDate(
+  date: Date | string | number | null | undefined,
+  language: SupportedLanguage | string = "en",
+  options?: Intl.DateTimeFormatOptions,
+  fallback = "—"
+): string {
+  if (date == null) return fallback;
+
+  const d = date instanceof Date ? date : new Date(date);
+  if (isNaN(d.getTime())) return fallback;
+
+  const bcp47 = languageToIntl(language);
+  const defaults: Intl.DateTimeFormatOptions = options ?? {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  };
+
+  return new Intl.DateTimeFormat(bcp47, defaults).format(d);
+}
+
+/**
+ * Locale-aware date+time formatting.
+ *
+ * @example
+ * ```ts
+ * formatDateTime(new Date())            // "Apr 10, 2026, 3:45 PM"
+ * formatDateTime(new Date(), "zh-CN")   // "2026年4月10日 下午3:45"
+ * ```
+ */
+export function formatDateTime(
+  date: Date | string | number | null | undefined,
+  language: SupportedLanguage | string = "en",
+  options?: Intl.DateTimeFormatOptions,
+  fallback = "—"
+): string {
+  const defaults: Intl.DateTimeFormatOptions = options ?? {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  };
+  return formatDate(date, language, defaults, fallback);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps our language keys (e.g. "en", "zh-CN", "es") to BCP 47 tags that Intl APIs need.
+ * "en" → "en-US", "es" → "es-ES", "zh-CN" stays "zh-CN".
+ */
+function languageToIntl(language: string): string {
+  if (language === "en") return "en-US";
+  if (language === "es") return "es-ES";
+  return language;
+}

package/src/lib/router.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+/**
+ * The minimal navigation surface @snowcone-app/ui needs — framework-agnostic.
+ * ui never imports next/navigation directly; components go through this so the
+ * library resolves in any framework (Vite, Remix, Astro, plain React, Next).
+ */
+export interface UiRouter {
+  push(url: string): void;
+  replace(url: string): void;
+}
+
+// Default: drive the browser's History API. Works everywhere; does a real
+// navigation (not a no-op). SSR-guarded.
+const historyRouter: UiRouter = {
+  push: (url) => {
+    if (typeof window !== "undefined") window.location.assign(url);
+  },
+  replace: (url) => {
+    if (typeof window !== "undefined") window.location.replace(url);
+  },
+};
+
+const UiRouterContext = createContext<UiRouter | null>(null);
+
+/**
+ * Inject your framework's client-side router so ui navigation (e.g. search
+ * result clicks) is SPA-smooth instead of a full-page load. Next apps can use
+ * `UiNextRouterProvider` from `@snowcone-app/ui/next`; other frameworks pass
+ * their own `{ push, replace }`.
+ */
+export const UiRouterProvider = UiRouterContext.Provider;
+
+/** Resolve the active router: the injected one, else the History default. */
+export function useUiRouter(): UiRouter {
+  return useContext(UiRouterContext) ?? historyRouter;
+}
+
+/** Read the current URL query params. Framework-agnostic, SSR-safe. */
+export function useUiSearchParams(): URLSearchParams {
+  return new URLSearchParams(
+    typeof window !== "undefined" ? window.location.search : "",
+  );
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}