@snowcone-app/ui 0.1.43 → 0.2.0

package/src/layouts/hero-zoom/stories/HeroZoomLayout.stories.tsx

@@ -0,0 +1,350 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import { HeroZoomLayout } from "../HeroZoomLayout";
+
+/**
+ * HeroZoomLayout - Scroll-Driven Hero Image Layout
+ *
+ * A cinematic scroll experience where a hero image starts scaled up and
+ * zooms down as the user scrolls, with an optional header that slides up.
+ *
+ * ## Features
+ *
+ * - **GPU-Accelerated**: Uses modern CSS `animation-timeline: scroll()` for 60fps performance
+ * - **Fallback Support**: JavaScript fallback for browsers without scroll-driven animations
+ * - **Retina-Ready**: Renders at device pixel ratio for crisp images
+ * - **Mobile-Safe**: Handles iOS address bar changes without jarring jumps
+ *
+ * ## Animation Phases
+ *
+ * 1. **Scale Phase**: Hero image scales down from ~2x to 1x as you scroll
+ * 2. **Slide Phase**: Header and image slide up, transitioning to content below
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <HeroZoomLayout
+ *   config={{ aspectRatio: 16/9, headerHeight: 80 }}
+ *   header={<MyHeader />}
+ *   hero={<img src="/hero.jpg" alt="" className="w-full h-full object-cover" />}
+ * >
+ *   <PageContent />
+ * </HeroZoomLayout>
+ * ```
+ */
+
+// Demo header component
+const DemoHeader = ({ transparent = false }: { transparent?: boolean }) => (
+  <div
+    className={`h-full flex items-center justify-center ${
+      transparent ? "bg-white/30 backdrop-blur-sm" : "bg-background"
+    }`}
+  >
+    <span className="text-lg font-semibold">Header</span>
+  </div>
+);
+
+// Demo content component
+const DemoContent = () => (
+  <div className="bg-background">
+    <div className="max-w-2xl mx-auto px-6 pb-24 space-y-8 text-lg leading-relaxed pt-12">
+      <h1 className="text-4xl font-bold mb-12">The Mountains</h1>
+      <p>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod
+        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+        commodo consequat.
+      </p>
+      <p>
+        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
+        dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+        proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+      </p>
+      <p>
+        Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+        accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab
+        illo inventore veritatis et quasi architecto beatae vitae dicta sunt
+        explicabo.
+      </p>
+      {Array.from({ length: 10 }).map((_, i) => (
+        <p key={i}>
+          Paragraph {i + 1}: At vero eos et accusamus et iusto odio dignissimos
+          ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti
+          quos dolores et quas molestias excepturi sint occaecati cupiditate non
+          provident.
+        </p>
+      ))}
+    </div>
+  </div>
+);
+
+const meta: Meta<typeof HeroZoomLayout> = {
+  title: "Layouts/HeroZoomLayout",
+  component: HeroZoomLayout,
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component: `
+# HeroZoomLayout
+
+A scroll-driven hero image layout that creates a cinematic zoom effect.
+
+## How It Works
+
+The layout uses CSS scroll-driven animations (\`animation-timeline: scroll()\`)
+for GPU-accelerated performance. For browsers that don't support this feature,
+it falls back to a JavaScript scroll handler using \`requestAnimationFrame\`.
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| \`aspectRatio\` | 16/9 | Hero image aspect ratio (width / height) |
+| \`initialFillPercent\` | 85 | Initial viewport height fill percentage |
+| \`headerHeight\` | 100 | Height of the header area in pixels |
+| \`accountForRetina\` | true | Render at higher resolution for Retina displays |
+| \`maxRetinaMultiplier\` | 2 | Cap the retina multiplier |
+
+## Browser Support
+
+- **Chrome 115+**: Native scroll-driven animations
+- **Safari 16+**: Native scroll-driven animations
+- **Firefox**: JavaScript fallback (smooth)
+- **Mobile Safari**: Optimized for iOS address bar changes
+        `,
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    config: {
+      description: "Configuration options for the scroll animation",
+    },
+    header: {
+      description: "Optional header content",
+    },
+    hero: {
+      description: "Hero content (image, video, etc.)",
+    },
+    children: {
+      description: "Content below the hero",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default configuration with a 16:9 aspect ratio hero image and header.
+ */
+export const Default: Story = {
+  args: {
+    config: {
+      aspectRatio: 16 / 9,
+      headerHeight: 100,
+      initialFillPercent: 85,
+    },
+    header: <DemoHeader transparent />,
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=2000&q=80"
+        alt="Mountain landscape"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * Without a header - the hero image starts at the top of the viewport.
+ */
+export const WithoutHeader: Story = {
+  args: {
+    config: {
+      aspectRatio: 16 / 9,
+      initialFillPercent: 90,
+    },
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1464822759023-fed622ff2c3b?w=2000&q=80"
+        alt="Mountain peaks"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * Square aspect ratio (1:1) - useful for product images.
+ */
+export const SquareAspectRatio: Story = {
+  args: {
+    config: {
+      aspectRatio: 1,
+      headerHeight: 80,
+      initialFillPercent: 80,
+    },
+    header: <DemoHeader />,
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=1500&q=80"
+        alt="Product shoe"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * 4:3 aspect ratio - classic photo dimensions.
+ */
+export const FourThreeAspectRatio: Story = {
+  args: {
+    config: {
+      aspectRatio: 4 / 3,
+      headerHeight: 100,
+      initialFillPercent: 85,
+    },
+    header: <DemoHeader transparent />,
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1519681393784-d120267933ba?w=2000&q=80"
+        alt="Night mountain"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * Ultra-wide 21:9 aspect ratio - cinematic experience.
+ */
+export const UltraWide: Story = {
+  args: {
+    config: {
+      aspectRatio: 21 / 9,
+      headerHeight: 60,
+      initialFillPercent: 70,
+    },
+    header: <DemoHeader transparent />,
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=2000&q=80"
+        alt="Landscape"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * With a video hero instead of an image.
+ */
+export const VideoHero: Story = {
+  args: {
+    config: {
+      aspectRatio: 16 / 9,
+      headerHeight: 100,
+      initialFillPercent: 85,
+    },
+    header: <DemoHeader transparent />,
+    hero: (
+      <video
+        autoPlay
+        muted
+        loop
+        playsInline
+        className="w-full h-full object-cover"
+        poster="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=2000&q=80"
+      >
+        <source
+          src="https://assets.mixkit.co/videos/preview/mixkit-white-sand-beach-and-palm-trees-1564-large.mp4"
+          type="video/mp4"
+        />
+      </video>
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * Gradient background hero - useful for abstract or branded headers.
+ */
+export const GradientHero: Story = {
+  args: {
+    config: {
+      aspectRatio: 16 / 9,
+      headerHeight: 100,
+      initialFillPercent: 85,
+    },
+    header: <DemoHeader transparent />,
+    hero: (
+      <div className="w-full h-full bg-gradient-to-br from-purple-600 via-pink-500 to-orange-400 flex items-center justify-center">
+        <h1 className="text-white text-6xl font-bold tracking-tight drop-shadow-lg">
+          Your Brand
+        </h1>
+      </div>
+    ),
+    children: <DemoContent />,
+  },
+};
+
+/**
+ * Product mockup use case - typical e-commerce product hero.
+ */
+export const ProductMockup: Story = {
+  args: {
+    config: {
+      aspectRatio: 16 / 9,
+      headerHeight: 80,
+      initialFillPercent: 80,
+    },
+    header: (
+      <div className="h-full flex items-center justify-between px-6 bg-background/80 backdrop-blur-sm">
+        <span className="font-bold">Store</span>
+        <div className="flex gap-4">
+          <button className="text-sm">Shop</button>
+          <button className="text-sm">Cart (0)</button>
+        </div>
+      </div>
+    ),
+    hero: (
+      <img
+        src="https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=2000&q=80"
+        alt="Watch product"
+        className="w-full h-full object-cover object-center"
+      />
+    ),
+    children: (
+      <div className="bg-background">
+        <div className="max-w-2xl mx-auto px-6 py-12">
+          <span className="text-primary text-sm font-medium">New Release</span>
+          <h1 className="text-3xl font-bold mt-2">Premium Watch</h1>
+          <p className="text-2xl font-semibold mt-4">$299.00</p>
+          <p className="text-muted-foreground mt-4">
+            Crafted with precision and designed for everyday elegance. This
+            premium timepiece combines modern aesthetics with reliable
+            performance.
+          </p>
+          <button className="mt-6 px-8 py-3 bg-primary text-primary-foreground rounded-lg font-medium">
+            Add to Cart
+          </button>
+          {Array.from({ length: 8 }).map((_, i) => (
+            <p key={i} className="mt-8 text-muted-foreground">
+              Product detail paragraph {i + 1}: Lorem ipsum dolor sit amet,
+              consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut
+              labore et dolore magna aliqua.
+            </p>
+          ))}
+        </div>
+      </div>
+    ),
+  },
+};

package/src/layouts/hero-zoom/types.ts

@@ -0,0 +1,113 @@
+import type { ReactNode, CSSProperties } from "react";
+
+/**
+ * Configuration options for the HeroZoomLayout component.
+ *
+ * These control the scroll-driven animation behavior including
+ * the hero image scaling and header slide-up effects.
+ */
+export interface HeroZoomConfig {
+  /**
+   * Aspect ratio of the hero image (width / height).
+   * Common values: 16/9 (1.778), 4/3 (1.333), 1 (square)
+   * @default 16/9
+   */
+  aspectRatio?: number;
+
+  /**
+   * Initial visual scale factor.
+   * Hero starts at initialScale× its final size, then zooms down to 1×.
+   * The final size is always 100vw width (full viewport width).
+   * @default 2.5
+   * @example initialScale: 2.0 means hero starts at 200% width and shrinks to 100%
+   */
+  initialScale?: number;
+
+  /**
+   * Height of the header area in pixels.
+   * This determines the scroll range for the slide-up phase.
+   * @default 100
+   */
+  headerHeight?: number;
+
+  /**
+   * Whether to account for Retina displays by rendering at higher resolution.
+   * When true, renders at devicePixelRatio for crisp images (uses more GPU memory).
+   * @default true
+   */
+  accountForRetina?: boolean;
+
+  /**
+   * Maximum retina multiplier to cap memory usage on 3x displays.
+   * Only applies when accountForRetina is true.
+   * @default 2
+   */
+  maxRetinaMultiplier?: number;
+}
+
+/**
+ * Props for the HeroZoomLayout component.
+ */
+export interface HeroZoomLayoutProps {
+  /**
+   * Configuration for the scroll animation behavior.
+   * All options have sensible defaults.
+   */
+  config?: HeroZoomConfig;
+
+  /**
+   * Optional header content that slides up as the user scrolls.
+   * Rendered in a fixed position at the top of the viewport.
+   */
+  header?: ReactNode;
+
+  /**
+   * The hero content (typically an image) that scales down on scroll.
+   * This is the main visual element that animates.
+   */
+  hero: ReactNode;
+
+  /**
+   * Content that appears below the hero after scrolling.
+   * This is the main page content.
+   */
+  children: ReactNode;
+
+  /**
+   * Additional CSS class names for the root container.
+   */
+  className?: string;
+
+  /**
+   * Additional inline styles for the root container.
+   */
+  style?: CSSProperties;
+}
+
+/**
+ * Internal scale values computed from viewport and config.
+ * Used by the useHeroZoomScales hook.
+ */
+export interface HeroZoomScales {
+  /**
+   * The visual scale the user sees (e.g., 2x → 1x during animation).
+   */
+  visual: number;
+
+  /**
+   * The render scale including retina multiplier for pixel density.
+   * Container is sized at this scale for crisp rendering.
+   */
+  render: number;
+}
+
+/**
+ * Default configuration values for HeroZoomLayout.
+ */
+export const DEFAULT_HERO_ZOOM_CONFIG: Required<HeroZoomConfig> = {
+  aspectRatio: 16 / 9,
+  initialScale: 2.5,
+  headerHeight: 100,
+  accountForRetina: true,
+  maxRetinaMultiplier: 2,
+};

package/src/layouts/hero-zoom/useHeroZoomScales.ts

@@ -0,0 +1,156 @@
+"use client";
+
+import { useEffect, useState, useCallback } from "react";
+import type { HeroZoomConfig, HeroZoomScales } from "./types";
+import { DEFAULT_HERO_ZOOM_CONFIG } from "./types";
+
+/**
+ * Extended scales including hydration state for SSR-safe rendering.
+ */
+export interface HeroZoomScalesWithHydration extends HeroZoomScales {
+  /**
+   * Whether JS has hydrated and computed exact scales.
+   * When false, the layout uses SSR-safe default values.
+   * When true, the layout uses JS-computed scales (may include DPR adjustment).
+   */
+  isHydrated: boolean;
+}
+
+/**
+ * Computes the visual and render scales for the hero zoom animation.
+ *
+ * This hook is significantly simplified from the viewport-measurement approach.
+ * The visual scale now comes directly from config (initialScale), making it:
+ * - SSR-safe: No viewport measurement needed
+ * - Predictable: Direct control over zoom level
+ * - Layout-shift-free: Same value used for SSR and hydration
+ *
+ * The only client-side computation is the device pixel ratio (DPR) for
+ * retina rendering, which only affects render quality, not visual size.
+ *
+ * @param config - Configuration options for the animation
+ * @returns The computed visual and render scales, plus hydration state
+ *
+ * @example
+ * ```tsx
+ * const scales = useHeroZoomScales({ initialScale: 2.0, aspectRatio: 16/9 });
+ * // scales.visual = 2.0 (from config, what user sees)
+ * // scales.render = 4.0 (includes retina multiplier for crisp images)
+ * // scales.isHydrated = true (after client-side DPR calculation)
+ * ```
+ */
+export function useHeroZoomScales(
+  config: HeroZoomConfig = {}
+): HeroZoomScalesWithHydration {
+  const { initialScale, accountForRetina, maxRetinaMultiplier } = {
+    ...DEFAULT_HERO_ZOOM_CONFIG,
+    ...config,
+  };
+
+  // Track whether we've hydrated (client-side calculation has run)
+  const [isHydrated, setIsHydrated] = useState(false);
+
+  // SSR-safe initial state - visual comes directly from config!
+  // No viewport measurement needed.
+  // For SSR, use the same multiplier that will be used after hydration.
+  // If accountForRetina is true, use maxRetinaMultiplier (capped DPR).
+  // If accountForRetina is false, use 2 (the fallback multiplier).
+  const ssrMultiplier = accountForRetina ? maxRetinaMultiplier : 2;
+  const [scales, setScales] = useState<HeroZoomScales>(() => ({
+    visual: initialScale,
+    render: initialScale * ssrMultiplier,
+  }));
+
+  const calculateScales = useCallback((): HeroZoomScales => {
+    // Visual scale comes directly from config - no viewport measurement!
+    // Clamp to reasonable bounds (1x to 4x)
+    const visualScale = Math.max(1, Math.min(4, initialScale));
+
+    // Render scale for retina displays
+    // This is the only client-side computation - affects image quality, not layout
+    let renderScale: number;
+    if (accountForRetina) {
+      const dpr = Math.min(
+        window.devicePixelRatio || 1,
+        maxRetinaMultiplier
+      );
+      renderScale = visualScale * dpr;
+    } else {
+      // Even without retina, we need render > visual for the scale animation.
+      // Use 2x as default multiplier.
+      renderScale = visualScale * 2;
+    }
+    renderScale = Math.max(1, Math.min(8, renderScale));
+
+    return { visual: visualScale, render: renderScale };
+  }, [initialScale, accountForRetina, maxRetinaMultiplier]);
+
+  useEffect(() => {
+    const supportsScrollTimeline = CSS.supports(
+      "animation-timeline",
+      "scroll()"
+    );
+
+    // Track last known width to detect real resizes vs address bar changes
+    let lastWidth = window.innerWidth;
+
+    const updateScales = (force = false) => {
+      const currentWidth = window.innerWidth;
+
+      // For scroll-timeline browsers, only update on actual width changes
+      // This prevents flash when iOS address bar expands/collapses
+      if (!force && supportsScrollTimeline && currentWidth === lastWidth) {
+        return;
+      }
+      lastWidth = currentWidth;
+
+      const newScales = calculateScales();
+      setScales(newScales);
+
+      // Update CSS custom properties for scroll-driven animations
+      document.documentElement.style.setProperty(
+        "--hero-zoom-render-scale",
+        String(newScales.render)
+      );
+      document.documentElement.style.setProperty(
+        "--hero-zoom-initial-transform",
+        String(newScales.visual / newScales.render)
+      );
+      document.documentElement.style.setProperty(
+        "--hero-zoom-final-transform",
+        String(1 / newScales.render)
+      );
+    };
+
+    // Initial update - mark as hydrated after first calculation
+    updateScales(true);
+    setIsHydrated(true);
+
+    // For scroll-timeline browsers, prefer orientationchange over resize
+    // to avoid updates during address bar changes
+    if (supportsScrollTimeline) {
+      const handleOrientationChange = () => {
+        // Small delay to let the viewport settle after orientation change
+        setTimeout(() => updateScales(true), 100);
+      };
+
+      const handleResize = () => updateScales(false);
+
+      window.addEventListener("orientationchange", handleOrientationChange);
+      window.addEventListener("resize", handleResize);
+
+      return () => {
+        window.removeEventListener("orientationchange", handleOrientationChange);
+        window.removeEventListener("resize", handleResize);
+      };
+    } else {
+      // Fallback browsers: update on all resizes
+      const handleResize = () => updateScales(true);
+      window.addEventListener("resize", handleResize);
+      return () => window.removeEventListener("resize", handleResize);
+    }
+  }, [calculateScales]);
+
+  // Return calculated scales with hydration state
+  return { ...scales, isHydrated };
+}

package/src/layouts/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Layout Components
+ *
+ * Pre-built layout patterns for common UI scenarios.
+ * Each layout is designed to be composable and customizable.
+ */
+
+export * from "./hero-zoom";
+export * from "./pdp";