@snowcone-app/ui 0.1.43 → 0.2.1

package/src/composed/TileCount.tsx

@@ -0,0 +1,348 @@
+"use client";
+
+import React, { useTransition } from "react";
+import * as SliderPrimitive from "@radix-ui/react-slider";
+import type { SeamlessPattern } from "./ProductImage";
+import { useDesignOptional } from "../patterns/Product";
+
+interface TileCountProps {
+  value?: SeamlessPattern["tileCount"];
+  imageUrl?: string;
+  className?: string;
+  valueClassName?: string;
+  valueStyle?: React.CSSProperties;
+  thumbBorderColor?: string;
+  placement?: string; // Optional placement label to update specific placement design
+  artwork?: { src: string; tileCount?: SeamlessPattern["tileCount"] }; // Optional artwork prop
+}
+
+// Helper function to convert tile count to descriptive name
+function nameTileDensity(tiles: number): string {
+  switch (tiles) {
+    case 0.25:
+      return "Fewest";
+    case 0.5:
+      return "Less";
+    case 1:
+      return "Normal";
+    case 2:
+      return "More";
+    case 4:
+      return "Most";
+    default:
+      return `${tiles}×${tiles}`;
+  }
+}
+
+// Helper function for className merging (simplified version)
+function cn(...classes: (string | undefined | false)[]) {
+  return classes.filter(Boolean).join(" ");
+}
+
+// Internal slider component
+const TileCountSlider = React.forwardRef<
+  React.ElementRef<typeof SliderPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> & {
+    thumbBorderColor?: string;
+  }
+>(({ className, thumbBorderColor, ...props }, ref) => (
+  <SliderPrimitive.Root
+    ref={ref}
+    className={cn(
+      "relative flex w-full touch-none select-none items-center",
+      className
+    )}
+    {...props}
+  >
+    <SliderPrimitive.Track className="relative h-3 w-full grow overflow-hidden rounded-full bg-border/30">
+      <SliderPrimitive.Range className="absolute h-full" />
+    </SliderPrimitive.Track>
+    <SliderPrimitive.Thumb
+      className="block h-6 w-6 rounded-full bg-background shadow transition-all focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary disabled:pointer-events-none disabled:opacity-50 cursor-grab active:cursor-grabbing hover:scale-105"
+      style={{
+        border: thumbBorderColor ? `2px solid ${thumbBorderColor}` : "2px solid var(--color-primary)",
+      }}
+      aria-label={props["aria-label"]}
+    />
+  </SliderPrimitive.Root>
+));
+
+TileCountSlider.displayName = "TileCountSlider";
+
+/**
+ * TileCount - Interactive tile density control for seamless patterns
+ *
+ * A composed component that allows users to adjust the tile density (repetition frequency)
+ * of seamless pattern artwork. Features a live tiled preview and a slider with 5 preset
+ * density levels, making it easy to control how many times a pattern repeats.
+ *
+ * **🚨 DO NOT USE THIS COMPONENT DIRECTLY!**
+ * **Use `<ArtworkCustomizer />` instead - it automatically handles both regular artwork AND patterns.**
+ *
+ * **Why use ArtworkCustomizer:**
+ * - ✅ Single component for both regular artwork and patterns
+ * - ✅ TypeScript enforces correct props based on artwork type
+ * - ✅ Impossible to make mistakes (no manual conditionals needed)
+ * - ✅ Cleaner, simpler code
+ *
+ * **Only use TileCount directly if:**
+ * - You are 100% certain you only have seamless patterns (never regular artwork)
+ * - You are building a custom component that wraps TileCount
+ * - You have read the ArtworkCustomizer docs and understand why you need direct access
+ *
+ * **⚠️ CRITICAL: If you use TileCount directly:**
+ * - ONLY for seamless pattern artwork - NEVER for regular photos/illustrations
+ * - For regular artwork, use `ArtAlignment` component instead
+ * - NEVER show both TileCount and ArtAlignment at the same time
+ * - Check `artwork.type === 'seamless'` to decide which component to render
+ * - Pattern: `{artwork.type === 'seamless' ? <TileCount /> : <ArtAlignment />}`
+ *
+ * **👉 See ArtworkCustomizer for the recommended approach!**
+ *
+ * **Features:**
+ * - Live preview showing actual tile repetition at 64x64px
+ * - 5 preset tile densities (Fewest → Most)
+ * - Smooth slider with snap-to-preset behavior
+ * - Descriptive labels for each density level
+ * - Checkerboard background for transparent patterns
+ * - Theme-aware styling with CSS variables
+ * - Accessible slider with ARIA labels
+ * - Customizable thumb border color
+ *
+ * **Tile Density Values:**
+ * - `0.25` - "Fewest" - Pattern displays at 4x original size (120px tiles in preview)
+ * - `0.5` - "Less" - Pattern displays at 2x original size (100px tiles in preview)
+ * - `1` - "Normal" - Pattern displays at original size (80px tiles in preview)
+ * - `2` - "More" - Pattern displays at 0.5x original size (60px tiles in preview)
+ * - `4` - "Most" - Pattern displays at 0.25x original size (44px tiles in preview)
+ *
+ * **Visual Behavior:**
+ * - Preview box: 64x64px with 2px border in border color
+ * - Slider: 128px wide with 5 snap points (0, 25, 50, 75, 100)
+ * - Thumb: 24x24px with customizable border, hover scale effect
+ * - Label: "Tiles" with current density name in muted color
+ *
+ * **Context Independence:**
+ * This is a controlled component that doesn't depend on any context. It simply
+ * displays a preview and fires onChange events. Parent components handle state
+ * and integration with design/artwork contexts.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with state
+ * const [tileCount, setTileCount] = useState(1);
+ *
+ * <TileCount
+ *   value={tileCount}
+ *   onChange={setTileCount}
+ *   imageUrl="https://example.com/pattern.png"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling with theme integration
+ * <TileCount
+ *   value={tileDensity}
+ *   onChange={handleTileChange}
+ *   imageUrl={patternUrl}
+ *   className="mb-6"
+ *   valueClassName="text-primary font-semibold"
+ *   thumbBorderColor="var(--color-primary)"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Without preview (slider only)
+ * <TileCount
+ *   value={1}
+ *   onChange={setTileCount}
+ *   // No imageUrl = no preview shown
+ * />
+ * ```
+ *
+ * @param value - Current tile density (0.25, 0.5, 1, 2, or 4). Defaults to 1 (Normal). If not provided, reads from artwork or Design context
+ * @param imageUrl - URL of the seamless pattern image to preview. If omitted, no preview is shown
+ * @param className - Additional CSS classes for the container element
+ * @param valueClassName - CSS classes for the density label text. Defaults to "text-sm font-normal text-muted-foreground"
+ * @param valueStyle - Inline styles for the density label text
+ * @param thumbBorderColor - Border color for the slider thumb. Defaults to black (#000)
+ */
+export function TileCount({
+  value: propValue,
+  imageUrl,
+  className,
+  valueClassName,
+  valueStyle,
+  thumbBorderColor,
+  placement,
+  artwork,
+}: TileCountProps) {
+  // Get design context
+  const designContext = useDesignOptional();
+
+  // Get tile count from multiple sources (in order of priority):
+  // 1. Explicit value prop (highest priority)
+  // 2. Placement design tiles (if placement is specified) ← PLACEMENT-FIRST PRIORITY
+  // 3. Selected artwork from context (global fallback)
+  // 4. Artwork prop tileCount (initial value fallback)
+  // 5. Default to 1
+  const placementDesign =
+    placement && designContext
+      ? designContext.getPlacementDesign(placement)
+      : undefined;
+
+  // Only use context tileCount if the context artwork matches our artwork/imageUrl
+  // This prevents stale tileCount from previous pattern selection
+  const contextArtworkMatches =
+    designContext?.selectedArtwork?.src === (artwork?.src || imageUrl);
+
+  const contextTileCount =
+    contextArtworkMatches &&
+    designContext?.selectedArtwork?.type === "pattern"
+      ? designContext.selectedArtwork.tileCount
+      : undefined;
+
+  const sourceValue =
+    propValue ??
+    placementDesign?.tiles ??  // ← Prioritize placement design (product-specific)
+    contextTileCount ??         // ← Fall back to global selectedArtwork
+    artwork?.tileCount ??
+    1;
+
+  // Local state for immediate visual updates during drag
+  const [optimisticValue, setOptimisticValue] = React.useState<SeamlessPattern["tileCount"]>(sourceValue);
+  const [isPending, startTransition] = useTransition();
+
+  // Sync optimistic value when source changes
+  React.useEffect(() => {
+    setOptimisticValue(sourceValue);
+  }, [sourceValue]);
+
+  // Use optimistic value for display
+  const value = optimisticValue;
+  // Determine background size based on tile scale
+  // Smaller tile count = larger tiles in preview
+  let bgSize = "32px 32px";
+  if (value === 0.25) bgSize = "120px 120px";
+  else if (value === 0.5) bgSize = "100px 100px";
+  else if (value === 1) bgSize = "80px 80px";
+  else if (value === 2) bgSize = "60px 60px";
+  else if (value === 4) bgSize = "44px 44px";
+
+  // Convert tile value to slider position (0-100)
+  const sliderValue =
+    value === 0.25
+      ? 0
+      : value === 0.5
+      ? 25
+      : value === 1
+      ? 50
+      : value === 2
+      ? 75
+      : value === 4
+      ? 100
+      : 50;
+
+  const handleSliderChange = (values: number[]) => {
+    const sliderVal = values[0];
+    // Snap to nearest valid tile value
+    let newTileCount: SeamlessPattern["tileCount"];
+    if (sliderVal < 12.5) {
+      newTileCount = 0.25;
+    } else if (sliderVal < 37.5) {
+      newTileCount = 0.5;
+    } else if (sliderVal < 62.5) {
+      newTileCount = 1;
+    } else if (sliderVal < 87.5) {
+      newTileCount = 2;
+    } else {
+      newTileCount = 4;
+    }
+
+    if (newTileCount !== value) {
+      // Immediate optimistic update for responsive UI
+      setOptimisticValue(newTileCount);
+
+      // Defer expensive context updates
+      if (designContext) {
+        startTransition(() => {
+          // PLACEMENT-FIRST PRIORITY (matches ArtAlignment pattern)
+          // If we have a placement, update placement design ONLY
+          if (placement) {
+            designContext.setPlacementDesign(placement, {
+              tiles: newTileCount,
+            });
+          }
+          // FALLBACK: Update global selectedArtwork only if NO placement specified
+          else {
+            // Update selected artwork if it's a pattern
+            if (designContext.selectedArtwork?.type === "pattern") {
+              designContext.setSelectedArtwork({
+                ...designContext.selectedArtwork,
+                tileCount: newTileCount,
+              });
+            }
+            // If no selected artwork in context but we have artwork prop, set it
+            else if (!designContext.selectedArtwork && artwork) {
+              designContext.setSelectedArtwork({
+                type: "pattern",
+                src: artwork.src,
+                tileCount: newTileCount,
+              });
+            }
+          }
+        });
+      }
+    }
+  };
+
+  return (
+    <div className={className}>
+      <div className="flex items-center gap-3 text-sm font-semibold text-foreground mb-2 mt-2">
+        Tiles
+        <span
+          className={valueClassName || "text-sm font-normal text-muted-foreground"}
+          style={valueStyle}
+        >
+          {nameTileDensity(value)}
+        </span>
+      </div>
+      <div className="flex items-center gap-4">
+        {/* Tile Preview */}
+        {imageUrl && (
+          <div className="flex-shrink-0 border-2 border-border/30 rounded-sm overflow-hidden">
+            <div
+              className="h-16 w-16 bg-center bg-repeat"
+              style={{
+                backgroundColor: '#fff',
+                backgroundPosition: 'center, 0 0, 8px 8px',
+                backgroundImage: `
+                  url('${imageUrl}'),
+                  linear-gradient(45deg, #e5e5e5 25%, transparent 25%, transparent 75%, #e5e5e5 75%, #e5e5e5),
+                  linear-gradient(45deg, #e5e5e5 25%, transparent 25%, transparent 75%, #e5e5e5 75%, #e5e5e5)
+                `,
+                backgroundSize: `${bgSize}, 16px 16px, 16px 16px`,
+              }}
+            />
+          </div>
+        )}
+
+        {/* Slider */}
+        <div className="w-32">
+          <TileCountSlider
+            value={[sliderValue]}
+            max={100}
+            step={25}
+            className="w-full"
+            onValueChange={handleSliderChange}
+            thumbBorderColor={thumbBorderColor}
+            aria-label="Adjust tile density"
+            aria-valuetext={`${nameTileDensity(value)} tile density`}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/composed/carousels/HeroCarousel.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+/**
+ * HeroCarousel - Lightweight carousel optimized for HeroZoomLayout
+ *
+ * A simplified carousel designed for use within scroll-driven animation contexts.
+ * Key optimizations for performance:
+ * 1. Uses CSS containment to isolate compositing layers
+ * 2. Uses translate3d for GPU-accelerated slides
+ * 3. Minimal JavaScript - no transform updates during scroll
+ * 4. Swipe-only navigation (no competing scroll handlers)
+ * 5. will-change hints for browser optimization
+ *
+ * Use this carousel when:
+ * - You're inside a HeroZoomLayout or similar scroll-driven animation
+ * - You need maximum performance with minimal features
+ * - You don't need drag feedback during swipe
+ *
+ * Use MobileProductCarousel when:
+ * - You need drag feedback during swipe
+ * - You want peek animation for UX education
+ * - You need EnhancedImageViewer integration
+ *
+ * @example
+ * ```tsx
+ * <HeroZoomLayout>
+ *   <HeroCarousel
+ *     images={heroImages}
+ *     productId="tshirt-001"
+ *     currentArtwork={artwork}
+ *   />
+ * </HeroZoomLayout>
+ * ```
+ */
+
+import React, { useState, useRef, useCallback, useEffect } from "react";
+import type { CarouselImage } from "./types";
+import { HeroProductImage } from "../HeroProductImage";
+import type { ArtworkData } from "@snowcone-app/sdk";
+
+export interface HeroCarouselProps {
+  /** Array of images to display in the carousel */
+  images: CarouselImage[];
+
+  /** Current active slide index (controlled) */
+  currentIndex?: number;
+
+  /** Callback when the active slide changes */
+  onIndexChange?: (index: number) => void;
+
+  /** Additional CSS classes */
+  className?: string;
+
+  /** Current artwork for mockup generation */
+  currentArtwork?: ArtworkData;
+
+  /** Product ID for mockup generation */
+  productId?: string;
+
+  /** Callback when image is tapped */
+  onImageTap?: (index: number) => void;
+}
+
+export function HeroCarousel({
+  images,
+  currentIndex = 0,
+  onIndexChange,
+  className = "",
+  currentArtwork,
+  productId,
+  onImageTap,
+}: HeroCarouselProps) {
+  const [activeIndex, setActiveIndex] = useState(currentIndex);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const touchStartRef = useRef<{ x: number; y: number; time: number } | null>(
+    null
+  );
+  const isSwipingRef = useRef(false);
+
+  // Sync with external index changes
+  useEffect(() => {
+    setActiveIndex(currentIndex);
+  }, [currentIndex]);
+
+  const goToSlide = useCallback(
+    (index: number) => {
+      const clampedIndex = Math.max(0, Math.min(images.length - 1, index));
+      setActiveIndex(clampedIndex);
+      onIndexChange?.(clampedIndex);
+    },
+    [images.length, onIndexChange]
+  );
+
+  // Simple touch handler - only horizontal swipes, no drag animation
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleTouchStart = (e: TouchEvent) => {
+      const touch = e.touches[0];
+      touchStartRef.current = {
+        x: touch.clientX,
+        y: touch.clientY,
+        time: Date.now(),
+      };
+      isSwipingRef.current = false;
+    };
+
+    const handleTouchMove = (e: TouchEvent) => {
+      if (!touchStartRef.current) return;
+
+      const touch = e.touches[0];
+      const deltaX = Math.abs(touch.clientX - touchStartRef.current.x);
+      const deltaY = Math.abs(touch.clientY - touchStartRef.current.y);
+
+      // If horizontal swipe detected, prevent vertical scroll
+      if (deltaX > 10 && deltaX > deltaY * 1.5) {
+        isSwipingRef.current = true;
+        e.preventDefault();
+      }
+    };
+
+    const handleTouchEnd = (e: TouchEvent) => {
+      if (!touchStartRef.current) return;
+
+      const touch = e.changedTouches[0];
+      const deltaX = touch.clientX - touchStartRef.current.x;
+      const deltaY = Math.abs(touch.clientY - touchStartRef.current.y);
+      const elapsed = Date.now() - touchStartRef.current.time;
+
+      // Only process horizontal swipes
+      if (Math.abs(deltaX) > 50 && Math.abs(deltaX) > deltaY) {
+        if (deltaX < 0 && activeIndex < images.length - 1) {
+          // Swipe left - next
+          goToSlide(activeIndex + 1);
+        } else if (deltaX > 0 && activeIndex > 0) {
+          // Swipe right - previous
+          goToSlide(activeIndex - 1);
+        }
+      } else if (elapsed < 300 && Math.abs(deltaX) < 10 && deltaY < 10) {
+        // Tap - trigger callback
+        onImageTap?.(activeIndex);
+      }
+
+      touchStartRef.current = null;
+      isSwipingRef.current = false;
+    };
+
+    container.addEventListener("touchstart", handleTouchStart, {
+      passive: true,
+    });
+    container.addEventListener("touchmove", handleTouchMove, { passive: false });
+    container.addEventListener("touchend", handleTouchEnd, { passive: true });
+
+    return () => {
+      container.removeEventListener("touchstart", handleTouchStart);
+      container.removeEventListener("touchmove", handleTouchMove);
+      container.removeEventListener("touchend", handleTouchEnd);
+    };
+  }, [activeIndex, images.length, goToSlide, onImageTap]);
+
+  if (!images || images.length === 0) {
+    return <div className="w-full h-full bg-muted" />;
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={`relative w-full h-full ${className}`}
+      style={{
+        // CSS containment - critical for performance with parent scale transform
+        contain: "layout paint style",
+        overflow: "hidden",
+      }}
+    >
+      {/* Slides container */}
+      <div
+        className="flex h-full transition-transform duration-300 ease-out"
+        style={{
+          // Use translate3d for GPU compositing layer
+          transform: `translate3d(${-activeIndex * 100}%, 0, 0)`,
+          willChange: "transform",
+          backfaceVisibility: "hidden",
+          WebkitBackfaceVisibility: "hidden",
+        }}
+      >
+        {images.map((image, index) => (
+          <div
+            key={index}
+            className="w-full h-full flex-shrink-0"
+            style={{
+              contain: "layout paint",
+            }}
+          >
+            {image.isRealMockup && currentArtwork ? (
+              <HeroProductImage
+                productId={productId}
+                artwork={currentArtwork}
+                placement={image.placement}
+                mockupId={image.mockupId}
+                className="w-full h-full object-cover"
+              />
+            ) : (
+              <img
+                src={image.src}
+                alt={image.label || `Slide ${index + 1}`}
+                crossOrigin="anonymous"
+                className="w-full h-full object-cover"
+                loading={index <= 1 ? "eager" : "lazy"}
+                decoding="async"
+                draggable={false}
+              />
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Dot indicators */}
+      {images.length > 1 && (
+        <div
+          className="absolute bottom-4 left-0 right-0 flex justify-center gap-2 z-10"
+          style={{ contain: "layout style" }}
+        >
+          {images.map((_, index) => (
+            <button
+              key={index}
+              onClick={() => goToSlide(index)}
+              className={`w-2 h-2 rounded-full transition-colors ${
+                index === activeIndex ? "bg-white" : "bg-white/50"
+              }`}
+              aria-label={`Go to slide ${index + 1}`}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default HeroCarousel;