@snowcone-app/ui 0.1.42 → 0.2.0

package/src/layouts/hero-zoom/HeroShrinkLayout.tsx

@@ -0,0 +1,209 @@
+"use client";
+
+import { useEffect, useRef, useState, useCallback } from "react";
+import type { ReactNode, CSSProperties } from "react";
+
+/**
+ * Configuration for HeroShrinkLayout
+ */
+export interface HeroShrinkConfig {
+  /** Aspect ratio of the hero (width/height). Default: 16/9 */
+  aspectRatio?: number;
+  /** Initial height as percentage of viewport. Default: 70 */
+  initialHeightPercent?: number;
+  /** Minimum height as percentage of viewport. Default: 40 */
+  minHeightPercent?: number;
+  /** Header height in pixels. Default: 0 */
+  headerHeight?: number;
+}
+
+export interface HeroShrinkLayoutProps {
+  config?: HeroShrinkConfig;
+  header?: ReactNode;
+  hero: ReactNode;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const DEFAULT_CONFIG: Required<HeroShrinkConfig> = {
+  aspectRatio: 16 / 9,
+  initialHeightPercent: 70,
+  minHeightPercent: 40,
+  headerHeight: 0,
+};
+
+/**
+ * HeroShrinkLayout - GPU-accelerated hero that shrinks on scroll
+ *
+ * Unlike HeroZoomLayout which uses scale transforms, this uses
+ * height animation which is more performant for complex content
+ * like carousels.
+ *
+ * Uses CSS scroll-driven animations where supported, with JS fallback.
+ */
+export function HeroShrinkLayout({
+  config = {},
+  header,
+  hero,
+  children,
+  className = "",
+  style,
+}: HeroShrinkLayoutProps) {
+  const mergedConfig: Required<HeroShrinkConfig> = {
+    ...DEFAULT_CONFIG,
+    ...config,
+  };
+
+  const { aspectRatio, initialHeightPercent, minHeightPercent, headerHeight } = mergedConfig;
+
+  const heroRef = useRef<HTMLDivElement>(null);
+  const headerRef = useRef<HTMLDivElement>(null);
+  const [isClient, setIsClient] = useState(false);
+
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  // JavaScript fallback for browsers without scroll-driven animations
+  useEffect(() => {
+    if (!isClient) return;
+
+    const supportsScrollTimeline = CSS.supports("animation-timeline", "scroll()");
+    if (supportsScrollTimeline) return;
+
+    const heroEl = heroRef.current;
+    const headerEl = headerRef.current;
+    if (!heroEl) return;
+
+    // Calculate heights
+    const vh = window.innerHeight;
+    const initialHeight = (initialHeightPercent / 100) * vh;
+    const minHeight = (minHeightPercent / 100) * vh;
+    const scrollRange = initialHeight - minHeight;
+
+    let ticking = false;
+
+    const updateHeight = () => {
+      const scrollY = window.scrollY;
+      const progress = Math.min(1, Math.max(0, scrollY / scrollRange));
+
+      const currentHeight = initialHeight - (progress * (initialHeight - minHeight));
+      heroEl.style.height = `${currentHeight}px`;
+
+      // Header slide up after hero reaches min height
+      if (headerEl && scrollY > scrollRange) {
+        const headerProgress = Math.min(1, (scrollY - scrollRange) / headerHeight);
+        headerEl.style.transform = `translateY(${-headerProgress * headerHeight}px)`;
+      } else if (headerEl) {
+        headerEl.style.transform = 'translateY(0)';
+      }
+
+      ticking = false;
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        requestAnimationFrame(updateHeight);
+        ticking = true;
+      }
+    };
+
+    updateHeight();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, [isClient, initialHeightPercent, minHeightPercent, headerHeight]);
+
+  // Calculate CSS custom properties
+  const cssVars = {
+    "--hero-shrink-initial-height": `${initialHeightPercent}svh`,
+    "--hero-shrink-min-height": `${minHeightPercent}svh`,
+    "--hero-shrink-header-height": `${headerHeight}px`,
+    "--hero-shrink-scroll-range": `calc(${initialHeightPercent}svh - ${minHeightPercent}svh)`,
+  } as CSSProperties;
+
+  const scopedStyles = `
+    @keyframes hero-shrink-height {
+      from { height: var(--hero-shrink-initial-height); }
+      to { height: var(--hero-shrink-min-height); }
+    }
+
+    @keyframes hero-shrink-header-exit {
+      from { transform: translateY(0); }
+      to { transform: translateY(calc(var(--hero-shrink-header-height) * -1)); }
+    }
+
+    @supports (animation-timeline: scroll()) {
+      [data-hero-shrink-container] {
+        animation: hero-shrink-height linear both;
+        animation-timeline: scroll();
+        animation-range: 0px var(--hero-shrink-scroll-range);
+      }
+
+      [data-hero-shrink-header] {
+        animation: hero-shrink-header-exit linear both;
+        animation-timeline: scroll();
+        animation-range: var(--hero-shrink-scroll-range) calc(var(--hero-shrink-scroll-range) + var(--hero-shrink-header-height));
+      }
+    }
+
+    [data-hero-shrink-container] {
+      position: fixed;
+      top: ${headerHeight}px;
+      left: 0;
+      width: 100%;
+      height: var(--hero-shrink-initial-height);
+      overflow: hidden;
+      will-change: height;
+      contain: layout style;
+    }
+
+    [data-hero-shrink-header] {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      z-index: 30;
+      will-change: transform;
+    }
+  `;
+
+  // Spacer height to create scroll room
+  const spacerHeight = `calc(${initialHeightPercent}svh + ${headerHeight}px)`;
+
+  return (
+    <div
+      className={`relative min-h-screen ${className}`}
+      style={{ ...style, ...cssVars }}
+    >
+      <style dangerouslySetInnerHTML={{ __html: scopedStyles }} />
+
+      {/* Scroll spacer */}
+      <div style={{ height: spacerHeight }} />
+
+      {/* Header */}
+      {header && (
+        <div
+          ref={headerRef}
+          data-hero-shrink-header
+          style={{ height: `${headerHeight}px` }}
+        >
+          {header}
+        </div>
+      )}
+
+      {/* Hero container */}
+      <div
+        ref={heroRef}
+        data-hero-shrink-container
+      >
+        {hero}
+      </div>
+
+      {/* Content */}
+      <div className="relative z-10 bg-background">
+        {children}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,351 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { HeroZoomLayoutProps, HeroZoomConfig } from "./types";
+import { DEFAULT_HERO_ZOOM_CONFIG } from "./types";
+import { useHeroZoomScales } from "./useHeroZoomScales";
+
+/**
+ * HeroZoomLayout - A scroll-driven hero image layout with zoom animation.
+ *
+ * This layout creates a cinematic scroll experience where:
+ * 1. A hero image starts scaled up and zooms down as the user scrolls
+ * 2. An optional header slides up and exits the viewport
+ * 3. Content below becomes visible after the animation completes
+ *
+ * Uses modern CSS scroll-driven animations (`animation-timeline: scroll()`)
+ * with a JavaScript fallback for browsers that don't support it.
+ *
+ * @example
+ * ```tsx
+ * <HeroZoomLayout
+ *   config={{ aspectRatio: 16/9, headerHeight: 80 }}
+ *   header={<MyHeader />}
+ *   hero={<img src="/hero.jpg" alt="Hero" className="w-full h-full object-cover" />}
+ * >
+ *   <ProductDetails />
+ * </HeroZoomLayout>
+ * ```
+ *
+ * @example Without header
+ * ```tsx
+ * <HeroZoomLayout
+ *   hero={<video src="/hero.mp4" autoPlay muted loop className="w-full h-full object-cover" />}
+ * >
+ *   <PageContent />
+ * </HeroZoomLayout>
+ * ```
+ */
+export function HeroZoomLayout({
+  config = {},
+  header,
+  hero,
+  children,
+  className = "",
+  style,
+}: HeroZoomLayoutProps) {
+  const mergedConfig: Required<HeroZoomConfig> = {
+    ...DEFAULT_HERO_ZOOM_CONFIG,
+    ...config,
+  };
+
+  const { aspectRatio, initialScale, headerHeight } = mergedConfig;
+
+  const { visual, render, isHydrated } = useHeroZoomScales(mergedConfig);
+  const imageContainerRef = useRef<HTMLDivElement>(null);
+  const headerRef = useRef<HTMLDivElement>(null);
+
+  // Force scroll to top on mount to ensure the animation starts correctly
+  // This prevents the browser from restoring scroll position to the middle of the page,
+  // which would cause the hero to start in a "zoomed" state rather than the initial full view.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    // Save original setting
+    const originalRestoration =
+      "scrollRestoration" in history ? history.scrollRestoration : "auto";
+
+    // Disable auto scroll restoration
+    if ("scrollRestoration" in history) {
+      history.scrollRestoration = "manual";
+    }
+
+    // Force scroll to top
+    window.scrollTo(0, 0);
+
+    // Restore setting on unmount
+    return () => {
+      if ("scrollRestoration" in history) {
+        history.scrollRestoration = originalRestoration;
+      }
+    };
+  }, []);
+
+
+  // JavaScript fallback for browsers without scroll-driven animation support
+  useEffect(() => {
+    const supportsScrollTimeline = CSS.supports(
+      "animation-timeline",
+      "scroll()"
+    );
+
+    if (supportsScrollTimeline) {
+      return;
+    }
+
+    const imageEl = imageContainerRef.current;
+    const headerEl = headerRef.current;
+    if (!imageEl) return;
+
+    const finalHeight = window.innerWidth / aspectRatio;
+    // Phase 1: Scale animation range
+    const scaleScrollRange = finalHeight * (visual - 1);
+    // Phase 2: Slide-up animation range
+    const slideScrollRange = headerHeight;
+
+    // Transform values
+    const initialTransform = visual / render;
+    const finalTransform = 1 / render;
+
+    let ticking = false;
+
+    const updateTransform = () => {
+      // Skip transform updates when drawer is open
+      if (document.documentElement.hasAttribute("data-drawer-open")) {
+        ticking = false;
+        return;
+      }
+
+      const scrollY = window.scrollY;
+
+      // Phase 1: Scale down (0 to scaleScrollRange)
+      const scaleProgress = Math.min(
+        1,
+        Math.max(0, scrollY / scaleScrollRange)
+      );
+      const currentScale =
+        initialTransform - scaleProgress * (initialTransform - finalTransform);
+
+      // Phase 2: Slide up & header exit (scaleScrollRange to totalScrollRange)
+      let translateY = 0;
+      let headerTranslateY = 0;
+
+      if (scrollY > scaleScrollRange) {
+        const slideProgress = Math.min(
+          1,
+          (scrollY - scaleScrollRange) / slideScrollRange
+        );
+        translateY = -headerHeight * slideProgress;
+        headerTranslateY = -headerHeight * slideProgress;
+      }
+
+      // Apply individual transform properties (scale and translate)
+      imageEl.style.scale = String(currentScale);
+      imageEl.style.translate = `0 ${translateY}px`;
+
+      if (headerEl) {
+        headerEl.style.translate = `0 ${headerTranslateY}px`;
+      }
+
+      ticking = false;
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        requestAnimationFrame(updateTransform);
+        ticking = true;
+      }
+    };
+
+    updateTransform();
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, [visual, render, aspectRatio, headerHeight]);
+
+  // UNIFIED VW-BASED SIZING
+  // Both SSR and hydration use the same formula, eliminating layout shift.
+  //
+  // SSR values (from config, no measurement):
+  //   - visual = initialScale (from config)
+  //   - render = initialScale * 2 (assume 2x DPR)
+  //
+  // Hydrated values:
+  //   - visual = initialScale (same as SSR!)
+  //   - render = initialScale * actualDPR (may differ from SSR)
+  //
+  // The visual scale is ALWAYS the same, so the visible size never changes.
+  // Only the render quality changes (higher DPR = crisper images).
+  //
+  // Container sizing formula (same for both SSR and hydrated):
+  //   - Width: 100vw * render
+  //   - Height: (100vw / aspectRatio) * render
+  //   - Transform: visual / render
+  //   - Visible width: 100vw * render * (visual/render) = 100vw * visual
+  //   - Visible height: (100vw/aspect) * render * (visual/render) = (100vw/aspect) * visual
+  //
+  // Since visual is the same for SSR and hydration, visible size is identical = no layout shift!
+
+  // Active values - visual is always from config, render may change after hydration
+  const activeVisual = visual;
+  const activeRender = render;
+  const activeTransform = activeVisual / activeRender;
+
+  // Unified container sizing (vw-based)
+  const containerWidth = `calc(100vw * ${activeRender})`;
+  const containerHeight = `calc(100vw / ${aspectRatio} * ${activeRender})`;
+  const marginLeft = `calc(-50vw * ${activeRender})`;
+
+  // Use CSS variables to ensure exact match with the hero's visual height.
+  // After hydration, add header height to account for the fixed header being removed from document flow.
+  // Before hydration (SSR), the layout renders correctly without this adjustment.
+  const scrollTrackHeight = isHydrated
+    ? `calc(var(--hero-zoom-image-height) * var(--hero-zoom-visual-scale) + ${headerHeight}px)`
+    : `calc(var(--hero-zoom-image-height) * var(--hero-zoom-visual-scale))`;
+
+  // Generate scoped CSS for scroll-driven animations
+  const scopedStyles = `
+    :root {
+      --hero-zoom-image-height: calc(100vw / ${aspectRatio});
+      --hero-zoom-header-height: ${headerHeight}px;
+      --hero-zoom-visual-scale: ${activeVisual};
+      --hero-zoom-render-scale: ${activeRender};
+      --hero-zoom-initial-transform: ${activeTransform};
+      --hero-zoom-final-transform: ${1 / activeRender};
+      --hero-zoom-scale-scroll-range: calc(var(--hero-zoom-image-height) * (var(--hero-zoom-visual-scale) - 1));
+      --hero-zoom-total-scroll-range: calc(var(--hero-zoom-scale-scroll-range) + var(--hero-zoom-header-height));
+    }
+
+    /* Phase 1: Scale animation */
+    @keyframes hero-zoom-scale-down {
+      from { scale: var(--hero-zoom-initial-transform); }
+      to { scale: var(--hero-zoom-final-transform); }
+    }
+
+    /* Phase 2: Slide up animation */
+    @keyframes hero-zoom-slide-up {
+      from { translate: 0 0; }
+      to { translate: 0 calc(var(--hero-zoom-header-height) * -1); }
+    }
+
+    /* Header exit animation */
+    @keyframes hero-zoom-header-exit {
+      from { translate: 0 0; }
+      to { translate: 0 calc(var(--hero-zoom-header-height) * -1); }
+    }
+
+    /* Hero container - handles both scale and translate */
+    [data-hero-zoom-container] {
+      transform-origin: center top;
+      will-change: scale, translate;
+      -webkit-backface-visibility: hidden;
+      backface-visibility: hidden;
+      /* Initial scale from computed transform */
+      scale: ${activeTransform};
+      translate: 0 0;
+    }
+
+    /* Header - animated slide-up */
+    [data-hero-zoom-header] {
+      will-change: translate;
+      -webkit-backface-visibility: hidden;
+      backface-visibility: hidden;
+      contain: layout style paint;
+    }
+
+    /* Apply scroll-driven animations if supported */
+    @supports (animation-timeline: scroll()) {
+      [data-hero-zoom-container] {
+        animation: hero-zoom-scale-down linear both, hero-zoom-slide-up linear both;
+        animation-timeline: scroll(), scroll();
+        animation-range: 0px var(--hero-zoom-scale-scroll-range), var(--hero-zoom-scale-scroll-range) var(--hero-zoom-total-scroll-range);
+      }
+
+      [data-hero-zoom-header] {
+        animation: hero-zoom-header-exit linear both;
+        animation-timeline: scroll();
+        animation-range: var(--hero-zoom-scale-scroll-range) var(--hero-zoom-total-scroll-range);
+      }
+
+      /* Drawer no longer interferes with hero animations.
+         The drawer covers the hero completely, so let animation run continuously. */
+    }
+  `;
+
+  return (
+    <div
+      className={`relative min-h-screen ${className}`}
+      style={
+        {
+          ...style,
+          "--hero-zoom-image-height": `calc(100vw / ${aspectRatio})`,
+          "--hero-zoom-header-height": `${headerHeight}px`,
+          "--hero-zoom-visual-scale": activeVisual,
+          "--hero-zoom-render-scale": activeRender,
+          "--hero-zoom-initial-transform": activeTransform,
+          "--hero-zoom-final-transform": 1 / activeRender,
+        } as React.CSSProperties
+      }
+    >
+      <style dangerouslySetInnerHTML={{ __html: scopedStyles }} />
+
+      {/* Scroll track - determines total scrollable area */}
+      <div
+        style={{
+          height: scrollTrackHeight,
+        }}
+      />
+
+      {/* Optional Header */}
+      {header && (
+        <div
+          ref={headerRef}
+          data-hero-zoom-header
+          className="fixed left-0 w-full z-30"
+          style={{
+            height: `${headerHeight}px`,
+            top: 0,
+          }}
+        >
+          {header}
+        </div>
+      )}
+
+      {/* Hero Container - sized at render scale for crisp images */}
+      {/*
+        VW-BASED UNIFIED SIZING:
+        Both SSR and hydration use the exact same formula:
+        - Width: 100vw * render
+        - Height: (100vw / aspectRatio) * render
+        - Transform: visual / render
+
+        Since visual comes from config (not viewport measurement),
+        it's identical for SSR and hydration = NO LAYOUT SHIFT!
+
+        The only difference after hydration is the render scale (DPR),
+        which affects image quality but not visible size.
+      */}
+      <div
+        ref={imageContainerRef}
+        data-hero-zoom-container
+        className="fixed z-20"
+        style={{
+          width: containerWidth,
+          height: containerHeight,
+          left: "50%",
+          marginLeft: marginLeft,
+          top: header ? `${headerHeight}px` : 0,
+          // NOTE: Don't set inline scale here - it conflicts with CSS scroll-driven animations.
+          // The CSS sets the initial scale via: [data-hero-zoom-container] { scale: ${activeTransform}; }
+          // For JS fallback browsers, the scroll handler sets scale via imageEl.style.scale
+          transformOrigin: "center top",
+        }}
+      >
+        {hero}
+      </div>
+
+      {/* Content below the hero */}
+      <div className="relative z-10">{children}</div>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+/**
+ * HeroZoomLayout - Scroll-driven hero image layout with zoom animation.
+ *
+ * A cinematic scroll experience where a hero image scales down as
+ * the user scrolls, with an optional header that slides up.
+ *
+ * @example
+ * ```tsx
+ * import { HeroZoomLayout } from "@snowcone-app/ui";
+ *
+ * <HeroZoomLayout
+ *   config={{ aspectRatio: 16/9 }}
+ *   header={<MyHeader />}
+ *   hero={<img src="/hero.jpg" alt="" className="w-full h-full object-cover" />}
+ * >
+ *   <PageContent />
+ * </HeroZoomLayout>
+ * ```
+ */
+
+export { HeroZoomLayout } from "./HeroZoomLayout";
+export { HeroShrinkLayout } from "./HeroShrinkLayout";
+export type { HeroShrinkConfig, HeroShrinkLayoutProps } from "./HeroShrinkLayout";
+export { useHeroZoomScales } from "./useHeroZoomScales";
+export type {
+  HeroZoomConfig,
+  HeroZoomLayoutProps,
+  HeroZoomScales,
+} from "./types";
+export { DEFAULT_HERO_ZOOM_CONFIG } from "./types";