@snowcone-app/ui 0.1.43 → 0.2.1

package/src/hooks/useRenderGuard.ts

@@ -0,0 +1,96 @@
+"use client";
+
+import { useRef } from 'react';
+
+interface RenderGuardOptions {
+  /** Name of the component being monitored */
+  name: string;
+  /** Maximum renders per second before warning (default: 3) */
+  maxRendersPerSecond?: number;
+  /** Whether to enable the guard (default: only in development) */
+  enabled?: boolean;
+}
+
+/**
+ * useRenderGuard - Development tool to detect excessive re-renders
+ *
+ * This hook monitors component render frequency and warns when a component
+ * is re-rendering too frequently, which can cause performance issues
+ * especially during canvas drag operations.
+ *
+ * **Why this exists:**
+ * Canvas drag operations are extremely sensitive to React re-renders.
+ * Even a single unnecessary re-render during drag can cause visible lag.
+ * This hook helps identify which components are re-rendering excessively.
+ *
+ * **Usage:**
+ * ```tsx
+ * function MyCanvasComponent() {
+ *   useRenderGuard({ name: 'MyCanvasComponent', maxRendersPerSecond: 2 });
+ *   // ... rest of component
+ * }
+ * ```
+ *
+ * **Console output:**
+ * ```
+ * [RenderGuard:MyCanvasComponent] 5 renders/sec - check for re-render leaks
+ * ```
+ *
+ * @param options - Configuration options
+ */
+export function useRenderGuard({
+  name,
+  maxRendersPerSecond = 3,
+  enabled = process.env.NODE_ENV === 'development',
+}: RenderGuardOptions): void {
+  // Skip entirely in production
+  if (!enabled) return;
+
+  // Track render timestamps in a ref (persists across renders)
+  const timestampsRef = useRef<number[]>([]);
+
+  const now = performance.now();
+
+  // Filter out timestamps older than 1 second
+  timestampsRef.current = timestampsRef.current.filter(t => t > now - 1000);
+
+  // Add current timestamp
+  timestampsRef.current.push(now);
+
+  const rendersInLastSecond = timestampsRef.current.length;
+
+  // Warn if exceeding threshold
+  if (rendersInLastSecond > maxRendersPerSecond) {
+    console.warn(
+      `[RenderGuard:${name}] ${rendersInLastSecond} renders/sec (max: ${maxRendersPerSecond}) - check for re-render leaks\n` +
+      `  Common causes:\n` +
+      `    - Context subscriptions to frequently-changing values (e.g., mockupResults)\n` +
+      `    - Callbacks with dependencies that change every render\n` +
+      `    - Props that are new objects/arrays every render\n` +
+      `    - Parent component re-rendering unnecessarily`
+    );
+  }
+}
+
+/**
+ * useRenderCount - Simple render counter for debugging
+ *
+ * Returns the current render count for a component.
+ * Useful for adding to console.log statements to track renders.
+ *
+ * **Usage:**
+ * ```tsx
+ * const renderCount = useRenderCount('MyComponent');
+ * console.log(`[MyComponent] Render #${renderCount}`);
+ * ```
+ */
+export function useRenderCount(componentName?: string): number {
+  const countRef = useRef(0);
+  countRef.current++;
+
+  // Log every 5th render in development
+  if (process.env.NODE_ENV === 'development' && componentName && countRef.current % 5 === 0) {
+  }
+
+  return countRef.current;
+}

package/src/hooks/useScrollDirection.ts

@@ -0,0 +1,196 @@
+"use client";
+
+/**
+ * useScrollDirection Hook
+ *
+ * Detects scroll direction and velocity for predicting which mockups
+ * are most likely to be viewed next (Level 3 ordering).
+ *
+ * Key features:
+ * - RAF-debounced for performance
+ * - Calculates velocity in pixels per second
+ * - Filters noise (ignores small movements < 5px)
+ * - Automatic idle detection after 150ms of no scroll
+ *
+ * @example
+ * ```tsx
+ * const { direction, velocity } = useScrollDirection();
+ *
+ * // direction: 'up' | 'down' | 'idle'
+ * // velocity: number (pixels per second)
+ * ```
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export type ScrollDirection = 'up' | 'down' | 'idle';
+
+export interface ScrollState {
+  /** Current scroll direction */
+  direction: ScrollDirection;
+  /** Scroll velocity in pixels per second */
+  velocity: number;
+  /** Last known scroll position */
+  scrollY: number;
+}
+
+const IDLE_TIMEOUT_MS = 150;
+const MIN_DELTA_PX = 5;
+
+export function useScrollDirection(): ScrollState {
+  const [state, setState] = useState<ScrollState>({
+    direction: 'idle',
+    velocity: 0,
+    scrollY: typeof window !== 'undefined' ? window.scrollY : 0,
+  });
+
+  const lastScrollRef = useRef({
+    top: typeof window !== 'undefined' ? window.scrollY : 0,
+    time: Date.now(),
+  });
+
+  const rafIdRef = useRef<number | null>(null);
+  const idleTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const handleScroll = useCallback(() => {
+    // Debounce via RAF - skip if we already have a pending update
+    if (rafIdRef.current !== null) return;
+
+    rafIdRef.current = requestAnimationFrame(() => {
+      const currentTop = window.scrollY;
+      const currentTime = Date.now();
+      const last = lastScrollRef.current;
+
+      const deltaY = currentTop - last.top;
+      const deltaTime = currentTime - last.time;
+
+      // Clear any pending idle timeout since we're scrolling
+      if (idleTimeoutRef.current) {
+        clearTimeout(idleTimeoutRef.current);
+        idleTimeoutRef.current = null;
+      }
+
+      // Only update for meaningful scroll (avoid noise from tiny movements)
+      if (Math.abs(deltaY) > MIN_DELTA_PX && deltaTime > 0) {
+        const velocity = (Math.abs(deltaY) / deltaTime) * 1000;
+        const direction: ScrollDirection = deltaY > 0 ? 'down' : 'up';
+
+        setState({
+          direction,
+          velocity,
+          scrollY: currentTop,
+        });
+
+        lastScrollRef.current = {
+          top: currentTop,
+          time: currentTime,
+        };
+
+        // Set idle timeout - will reset direction to 'idle' after scroll stops
+        idleTimeoutRef.current = setTimeout(() => {
+          setState((prev) => ({
+            ...prev,
+            direction: 'idle',
+            velocity: 0,
+          }));
+        }, IDLE_TIMEOUT_MS);
+      }
+
+      rafIdRef.current = null;
+    });
+  }, []);
+
+  useEffect(() => {
+    // Only run on client
+    if (typeof window === 'undefined') return;
+
+    // Initialize with current scroll position
+    lastScrollRef.current = {
+      top: window.scrollY,
+      time: Date.now(),
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => {
+      window.removeEventListener('scroll', handleScroll);
+
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+
+      if (idleTimeoutRef.current) {
+        clearTimeout(idleTimeoutRef.current);
+      }
+    };
+  }, [handleScroll]);
+
+  return state;
+}
+
+/**
+ * Get scroll direction without React state (for use outside components)
+ * Returns a getter function that always returns the current scroll direction
+ */
+export function createScrollDirectionTracker(): {
+  getDirection: () => ScrollDirection;
+  getVelocity: () => number;
+  destroy: () => void;
+} {
+  let direction: ScrollDirection = 'idle';
+  let velocity = 0;
+  let lastTop = typeof window !== 'undefined' ? window.scrollY : 0;
+  let lastTime = Date.now();
+  let rafId: number | null = null;
+  let idleTimeout: NodeJS.Timeout | null = null;
+
+  const handleScroll = () => {
+    if (rafId !== null) return;
+
+    rafId = requestAnimationFrame(() => {
+      const currentTop = window.scrollY;
+      const currentTime = Date.now();
+      const deltaY = currentTop - lastTop;
+      const deltaTime = currentTime - lastTime;
+
+      if (idleTimeout) {
+        clearTimeout(idleTimeout);
+        idleTimeout = null;
+      }
+
+      if (Math.abs(deltaY) > MIN_DELTA_PX && deltaTime > 0) {
+        velocity = (Math.abs(deltaY) / deltaTime) * 1000;
+        direction = deltaY > 0 ? 'down' : 'up';
+        lastTop = currentTop;
+        lastTime = currentTime;
+
+        idleTimeout = setTimeout(() => {
+          direction = 'idle';
+          velocity = 0;
+        }, IDLE_TIMEOUT_MS);
+      }
+
+      rafId = null;
+    });
+  };
+
+  if (typeof window !== 'undefined') {
+    window.addEventListener('scroll', handleScroll, { passive: true });
+  }
+
+  return {
+    getDirection: () => direction,
+    getVelocity: () => velocity,
+    destroy: () => {
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('scroll', handleScroll);
+      }
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+      }
+      if (idleTimeout) {
+        clearTimeout(idleTimeout);
+      }
+    },
+  };
+}

package/src/hooks/viewport/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Viewport Hooks
+ *
+ * A set of hooks for responsive viewport handling with consolidated resize listeners.
+ * These hooks work together to provide efficient viewport-aware layout without
+ * the performance issues of multiple resize listeners (especially on mobile).
+ *
+ * Usage pattern:
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 768px)");
+ * const dimensions = useViewportDimensions(isDesktop);
+ * const imageCapInfo = useResponsiveImageCap(dimensions);
+ * const isWideMonitor = useWideMonitorMode(imageCapInfo);
+ * ```
+ */
+
+export { useMediaQuery } from "./useMediaQuery";
+
+export { useViewportDimensions } from "./useViewportDimensions";
+export type { ViewportDimensions } from "./useViewportDimensions";
+
+export { useResponsiveImageCap, DEFAULT_IMAGE_CONFIG } from "./useResponsiveImageCap";
+export type { ResponsiveImageCapInfo, ResponsiveImageCapOptions } from "./useResponsiveImageCap";
+
+export { useWideMonitorMode, isWideMonitor, hasEdgeBlur } from "./useWideMonitorMode";

package/src/hooks/viewport/useContainerWidth.ts

@@ -0,0 +1,59 @@
+"use client";
+
+import { useState, useLayoutEffect, useEffect, useRef, type RefObject } from "react";
+
+/**
+ * Measures a container element's width in device pixels (CSS width × devicePixelRatio).
+ *
+ * Uses useLayoutEffect for the initial measurement so the correct width is
+ * available before any useEffect (like mockup URL generation) fires.
+ * Updates on window resize (debounced).
+ * Clamps to maxWidth to avoid absurdly large image requests.
+ *
+ * @param containerRef - Ref to the container element to measure
+ * @param maxWidth - Maximum device-pixel width to return (default: 3000)
+ * @returns Width in device pixels (0 until the container is mounted and laid out)
+ */
+export function useContainerWidth(
+  containerRef: RefObject<HTMLElement | null>,
+  maxWidth = 3000
+): number {
+  const [width, setWidth] = useState(0);
+  const resizeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Synchronous measurement after DOM commit — fires before any useEffect,
+  // so mockup URL generation always sees the real container width.
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const cssWidth = el.offsetWidth;
+    if (cssWidth === 0) return;
+    const dpr = window.devicePixelRatio ?? 1;
+    setWidth(Math.min(Math.round(cssWidth * dpr), maxWidth));
+  }, [containerRef, maxWidth]);
+
+  // Debounced resize listener
+  useEffect(() => {
+    const measure = () => {
+      const el = containerRef.current;
+      if (!el) return;
+      const cssWidth = el.offsetWidth;
+      if (cssWidth === 0) return;
+      const dpr = window.devicePixelRatio ?? 1;
+      setWidth(Math.min(Math.round(cssWidth * dpr), maxWidth));
+    };
+
+    const handleResize = () => {
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current);
+      resizeTimeoutRef.current = setTimeout(measure, 200);
+    };
+
+    window.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current);
+    };
+  }, [containerRef, maxWidth]);
+
+  return width;
+}

package/src/hooks/viewport/useMediaQuery.ts

@@ -0,0 +1,52 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+/**
+ * SSR-safe hook to detect if a media query matches.
+ *
+ * Returns:
+ * - `null` during SSR and initial hydration (unknown state)
+ * - `true` if the media query matches
+ * - `false` if the media query doesn't match
+ *
+ * The null return value is important for:
+ * - Rendering both layouts during SSR to avoid hydration mismatch
+ * - Using CSS classes (md:hidden, md:block) for initial visibility
+ * - Transitioning to JS-based layout after hydration
+ *
+ * @param query - CSS media query string (e.g., "(min-width: 768px)")
+ * @returns boolean | null - null during SSR, boolean after hydration
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 768px)");
+ *
+ * // Render both layouts during SSR, hide with CSS
+ * return (
+ *   <>
+ *     {(isDesktop === false || isDesktop === null) && (
+ *       <div className="md:hidden">Mobile Layout</div>
+ *     )}
+ *     {(isDesktop === true || isDesktop === null) && (
+ *       <div className="hidden md:block">Desktop Layout</div>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export function useMediaQuery(query: string): boolean | null {
+  // Start with null to indicate "unknown" during SSR
+  const [matches, setMatches] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    // Set immediately on mount - this is the first time we know the actual value
+    setMatches(media.matches);
+    const listener = () => setMatches(media.matches);
+    media.addEventListener("change", listener);
+    return () => media.removeEventListener("change", listener);
+  }, [query]);
+
+  return matches;
+}

package/src/hooks/viewport/useResponsiveImageCap.ts

@@ -0,0 +1,149 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ViewportDimensions } from "./useViewportDimensions";
+
+/**
+ * Default layout configuration.
+ */
+export const DEFAULT_IMAGE_CONFIG = {
+  ASPECT_RATIO: 16 / 9,
+  WIDTH_VW: 140, // Large enough to extend to viewport edge past sidebar
+  MAX_WIDTH_PX: 2700, // Allow larger images for bigger viewports
+  SIDEBAR_MAX_PX: 384,
+  SIDEBAR_MARGIN_PX: 32,
+} as const;
+
+/**
+ * Information about the viewport for responsive image layouts.
+ */
+export interface ResponsiveImageCapInfo {
+  /** Maximum width in pixels (uncapped - just returns viewport * 1.5) */
+  maxWidthPx: number;
+  /** Descriptive zone name for debugging */
+  zone: string;
+  /** Current viewport aspect ratio */
+  viewportAspectRatio: number;
+  /** Current viewport width */
+  viewportWidth: number;
+  /** Current viewport height */
+  viewportHeight: number;
+  /** Calculated image height based on width and aspect ratio */
+  imageHeight: number;
+  /** Increments on resize - use for Safari mask repaint workaround */
+  resizeVersion: number;
+}
+
+/**
+ * Options for customizing the hook behavior.
+ */
+export interface ResponsiveImageCapOptions {
+  /** Image aspect ratio (default: 16/9) */
+  aspectRatio?: number;
+  /** Image width in viewport width units (default: 150) */
+  widthVw?: number;
+  /** Maximum width in pixels - no longer used, kept for backwards compat */
+  maxWidthPx?: number;
+  /** Sidebar width in pixels (for dynamic sidebar mode) */
+  sidebarWidthPx?: number;
+}
+
+/**
+ * Hook to provide viewport dimensions for responsive image layouts.
+ *
+ * Calculates the exact image width needed to extend from the content area
+ * center to the viewport right edge (covering the sidebar zone).
+ *
+ * Formula: imageWidth = viewportWidth + sidebarPx + sidebarMargin
+ *
+ * @param dimensions - Viewport dimensions from useViewportDimensions hook
+ * @param options - Optional configuration
+ * @returns Viewport info and calculated image dimensions
+ */
+export function useResponsiveImageCap(
+  dimensions: ViewportDimensions,
+  options: ResponsiveImageCapOptions = {}
+): ResponsiveImageCapInfo {
+  const { aspectRatio = DEFAULT_IMAGE_CONFIG.ASPECT_RATIO, sidebarWidthPx } =
+    options;
+
+  return useMemo(() => {
+    const vw = dimensions.width;
+    const vh = dimensions.height;
+    const viewportAspectRatio = dimensions.aspectRatio;
+
+    // Mobile/SSR - return sensible defaults
+    if (vw < 768) {
+      return {
+        maxWidthPx: DEFAULT_IMAGE_CONFIG.MAX_WIDTH_PX,
+        zone: "mobile",
+        viewportAspectRatio: viewportAspectRatio || 0,
+        viewportWidth: vw,
+        viewportHeight: vh,
+        imageHeight: 0,
+        resizeVersion: dimensions.resizeVersion,
+      };
+    }
+
+    // Calculate sidebar width (use provided value or default 35% capped at 384px)
+    const sidebarPx =
+      sidebarWidthPx ??
+      Math.min(vw * 0.35, DEFAULT_IMAGE_CONFIG.SIDEBAR_MAX_PX);
+
+    // Content area is the space left of sidebar (where image is centered)
+    const contentAreaWidth =
+      vw - sidebarPx - DEFAULT_IMAGE_CONFIG.SIDEBAR_MARGIN_PX;
+
+    // Calculate width needed to reach viewport edge
+    const widthToFillEdge =
+      vw + sidebarPx + DEFAULT_IMAGE_CONFIG.SIDEBAR_MARGIN_PX;
+
+    // Smooth height cap based on aspect ratio
+    // At aspect ratio 1.8 or below: use 100% of vh (no cap)
+    // At aspect ratio 2.6 or above: use 92% of vh (full cap)
+    // In between: smooth linear interpolation
+    const minAspect = 1.8;
+    const maxAspect = 2.6;
+    const minHeightPercent = 1.2;
+    const maxHeightPercent = 1.0;
+
+    const aspectBlend = Math.max(
+      0,
+      Math.min(1, (viewportAspectRatio - minAspect) / (maxAspect - minAspect))
+    );
+    const heightPercent =
+      maxHeightPercent - aspectBlend * (maxHeightPercent - minHeightPercent);
+
+    const maxHeight = vh * heightPercent;
+    const widthFromHeightCap = maxHeight * aspectRatio;
+
+    // Image must be at least as wide as content area (no left gap)
+    // Then try to fill to edge, but respect height cap and absolute max
+    const imageWidth = Math.max(
+      contentAreaWidth,
+      Math.min(
+        widthToFillEdge,
+        widthFromHeightCap,
+        DEFAULT_IMAGE_CONFIG.MAX_WIDTH_PX
+      )
+    );
+    const imageHeight = imageWidth / aspectRatio;
+
+    return {
+      maxWidthPx: imageWidth,
+      zone: "desktop",
+      viewportAspectRatio,
+      viewportWidth: vw,
+      viewportHeight: vh,
+      imageHeight,
+      resizeVersion: dimensions.resizeVersion,
+    };
+  }, [
+    dimensions.width,
+    dimensions.height,
+    dimensions.aspectRatio,
+    dimensions.resizeVersion,
+    aspectRatio,
+    sidebarWidthPx,
+  ]);
+}