@snowcone-app/ui 0.1.43 → 0.2.0

package/src/personalization/usePersonalizationShimmer.ts

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * usePersonalizationShimmer — tracks the full personalization → mockup pipeline
+ * and returns whether a shimmer overlay should be visible.
+ *
+ * Shimmer is ON from the first personalization input until the final server-rendered
+ * mockup image has loaded in the browser. Handles throttled blob sends, stale server
+ * results, and rapid typing correctly.
+ *
+ * Must be used inside both `<PersonalizationProvider>` and `<RealtimeProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const heroRef = useRef<HTMLDivElement>(null);
+ * const { shimmerActive } = usePersonalizationShimmer(heroRef);
+ *
+ * return (
+ *   <div ref={heroRef}>
+ *     <MobileProductCarousel ... />
+ *     {shimmerActive && <ShimmerOverlay />}
+ *   </div>
+ * );
+ * ```
+ */
+
+import { useState, useEffect, useRef, useCallback, type RefObject } from "react";
+import { usePersonalizationContext } from "./PersonalizationContext";
+import { useRealtimeOptional } from "../patterns/RealtimeProvider";
+
+export interface UsePersonalizationShimmerReturn {
+  /** Whether the shimmer overlay should be visible. */
+  shimmerActive: boolean;
+  /**
+   * Manually trigger shimmer (e.g. when product options change).
+   * Shimmer clears automatically when a new image loads in the container.
+   */
+  triggerShimmer: () => void;
+}
+
+/**
+ * Track personalization → mockup shimmer state.
+ *
+ * @param containerRef - ref to the element containing mockup `<img>` tags.
+ *   The hook watches for `src` attribute changes and `load` events inside this container.
+ * @param safetyTimeoutMs - auto-clear shimmer after this duration (default 10000ms).
+ */
+export function usePersonalizationShimmer(
+  containerRef: RefObject<HTMLElement | null>,
+  safetyTimeoutMs = 10000,
+): UsePersonalizationShimmerReturn {
+  const personCtx = usePersonalizationContext();
+  const realtime = useRealtimeOptional();
+
+  const [shimmerActive, setShimmerActive] = useState(false);
+  const sdkSettledRef = useRef(false);   // gate for personalization pipeline
+  const manualTriggerRef = useRef(false); // gate for manual triggers (option changes)
+  const safetyTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // Helper: start shimmer with safety timeout
+  const startShimmer = useCallback(() => {
+    setShimmerActive(true);
+    if (safetyTimeoutRef.current) clearTimeout(safetyTimeoutRef.current);
+    safetyTimeoutRef.current = setTimeout(
+      () => {
+        sdkSettledRef.current = false;
+        manualTriggerRef.current = false;
+        setShimmerActive(false);
+      },
+      safetyTimeoutMs,
+    );
+  }, [safetyTimeoutMs]);
+
+  // personValues change → shimmer ON, close gate, reset pipeline
+  useEffect(() => {
+    if (!personCtx?.isActive) return;
+
+    sdkSettledRef.current = false;
+    manualTriggerRef.current = false;
+    realtime?.resetPipelineSettled();
+    startShimmer();
+  }, [personCtx?.personValues, personCtx?.isActive, startShimmer]);
+
+  // Manual trigger (e.g. option changes) → shimmer ON, clear on next img load
+  const triggerShimmer = useCallback(() => {
+    sdkSettledRef.current = false;
+    manualTriggerRef.current = true;
+    startShimmer();
+  }, [startShimmer]);
+
+  // subscribePipelineSettled → open gate for IMG loads
+  useEffect(() => {
+    if (!realtime?.subscribePipelineSettled) return;
+    return realtime.subscribePipelineSettled(() => {
+      sdkSettledRef.current = true;
+    });
+  }, [realtime]);
+
+  // IMG load inside container while gate is open → shimmer OFF
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const observer = new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        if (m.type !== "attributes" || m.attributeName !== "src") continue;
+        const img = m.target as HTMLImageElement;
+        if (!container.contains(img)) continue;
+
+        // Gate: only track src changes when we're expecting a new image.
+        // sdkSettledRef = personalization pipeline done (waiting for img load)
+        // manualTriggerRef = option change (waiting for next img load)
+        const shouldTrack = sdkSettledRef.current || manualTriggerRef.current;
+        if (!shouldTrack) continue;
+
+        img.addEventListener(
+          "load",
+          () => {
+            // Re-check gates — user may have typed again (closing the gate)
+            if (sdkSettledRef.current || manualTriggerRef.current) {
+              sdkSettledRef.current = false;
+              manualTriggerRef.current = false;
+              setShimmerActive(false);
+              if (safetyTimeoutRef.current)
+                clearTimeout(safetyTimeoutRef.current);
+            }
+          },
+          { once: true },
+        );
+        img.addEventListener(
+          "error",
+          () => {
+            if (sdkSettledRef.current || manualTriggerRef.current) {
+              sdkSettledRef.current = false;
+              manualTriggerRef.current = false;
+              setShimmerActive(false);
+            }
+          },
+          { once: true },
+        );
+      }
+    });
+
+    observer.observe(container, {
+      attributes: true,
+      subtree: true,
+      attributeFilter: ["src"],
+    });
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  useEffect(() => {
+    return () => {
+      if (safetyTimeoutRef.current) clearTimeout(safetyTimeoutRef.current);
+    };
+  }, []);
+
+  return { shimmerActive, triggerShimmer };
+}

package/src/personalization/utils.ts

@@ -0,0 +1,59 @@
+"use client";
+
+/**
+ * Personalization Utilities
+ */
+
+import { useEffect, useState } from "react";
+
+/** Normalize any hex color to uppercase 6-digit form (#RGB → #RRGGBB) */
+export function normalizeHex(color: string): string {
+  let hex = color.trim().toUpperCase();
+  if (hex.length === 4 && hex.startsWith("#")) {
+    hex = "#" + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3];
+  }
+  return hex;
+}
+
+/** Check if a string looks like a complete, loadable URL */
+export function isValidImageUrl(url: string): boolean {
+  if (!url || url.length < 10) return false;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+    if (!parsed.hostname.includes(".")) return false;
+    if (parsed.pathname.length <= 1) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Debounce a string value — only emits after `delay` ms of inactivity */
+export function useDebouncedValue(value: string, delay: number): string {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+
+/**
+ * Scroll an input to sit just above the iOS keyboard after it appears.
+ * Uses visualViewport.height to determine the visible area above the keyboard.
+ */
+export function scrollInputAboveKeyboard(input: HTMLElement) {
+  const position = () => {
+    const rect = input.getBoundingClientRect();
+    const visibleBottom =
+      window.visualViewport?.height || window.innerHeight * 0.5;
+    const target = visibleBottom - rect.height - 20;
+    const delta = rect.top - target;
+    if (Math.abs(delta) > 10) {
+      window.scrollBy({ top: delta, behavior: "smooth" });
+    }
+  };
+  setTimeout(position, 400);
+  window.visualViewport?.addEventListener("resize", position, { once: true });
+}

package/src/primitives/BrandLogo.tsx

@@ -0,0 +1,65 @@
+import React from "react";
+import { getBrand, brandAssets, type SupportedLanguage } from "../lib/locale";
+
+export interface BrandLogoProps {
+  /** Language — selects the correct wordmark. */
+  locale?: SupportedLanguage;
+  /** Icon height in pixels (default: 32). Wordmark scales proportionally. */
+  size?: number;
+  /** Gap between icon and wordmark in pixels (default: 8). */
+  gap?: number;
+  /** Hide the wordmark; show icon only. */
+  iconOnly?: boolean;
+  /** Additional CSS class names for the container. */
+  className?: string;
+}
+
+/**
+ * BrandLogo — Composes the universal Rainbow Snowcone icon with a
+ * locale-aware wordmark. See ADR-0035.
+ *
+ * The icon is identical across all locales (persistent visual anchor).
+ * The wordmark varies: "Snowcone" for Latin-script locales, "雪绘" for zh-CN.
+ *
+ * @example
+ * ```tsx
+ * <BrandLogo />                     // Icon + "Snowcone" wordmark
+ * <BrandLogo locale="zh-CN" />      // Icon + "雪绘" wordmark
+ * <BrandLogo iconOnly />            // Icon only (e.g., mobile nav)
+ * <BrandLogo size={48} gap={12} />  // Larger logo
+ * ```
+ */
+export function BrandLogo({
+  locale = "en",
+  size = 32,
+  gap = 8,
+  iconOnly = false,
+  className,
+}: BrandLogoProps) {
+  const brand = getBrand(locale);
+
+  return (
+    <span
+      className={className}
+      style={{ display: "inline-flex", alignItems: "center", gap }}
+      translate="no"
+    >
+      <img
+        src={brandAssets.icon_svg}
+        alt=""
+        aria-hidden="true"
+        width={size}
+        height={size}
+        style={{ width: size, height: size }}
+      />
+      {!iconOnly && (
+        <img
+          src={brand.wordmark}
+          alt={brand.localized_name}
+          lang={brand.lang}
+          style={{ height: size * 0.75 }}
+        />
+      )}
+    </span>
+  );
+}

package/src/primitives/BrandName.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { getBrand, type SupportedLanguage } from "../lib/locale";
+
+export interface BrandNameProps {
+  /** Language to render the brand name for. */
+  locale?: SupportedLanguage;
+  /**
+   * Which name field to use:
+   * - "localized" — the locale's registered trademark (default). "Snowcone" or "雪绘".
+   * - "display" — mixed-language form for cross-cultural contexts. "雪绘 (Snowcone)".
+   * - "primary" — always "Snowcone" regardless of locale.
+   */
+  variant?: "localized" | "display" | "primary";
+  /** Additional CSS class names. */
+  className?: string;
+}
+
+/**
+ * BrandName — Renders the Snowcone brand name with trademark protection.
+ *
+ * Applies `translate="no"` to prevent browser auto-translate from mangling
+ * the registered trademark, and sets the correct `lang` attribute for
+ * screen reader pronunciation. See ADR-0035.
+ *
+ * @example
+ * ```tsx
+ * <BrandName />                          // "Snowcone"
+ * <BrandName locale="zh-CN" />           // "雪绘"
+ * <BrandName locale="zh-CN" variant="display" /> // "雪绘 (Snowcone)"
+ * ```
+ */
+export function BrandName({
+  locale = "en",
+  variant = "localized",
+  className,
+}: BrandNameProps) {
+  const brand = getBrand(locale);
+
+  const name =
+    variant === "display"
+      ? brand.display_name
+      : variant === "primary"
+        ? brand.primary_name
+        : brand.localized_name;
+
+  return (
+    <span translate="no" lang={brand.lang} className={className}>
+      {name}
+    </span>
+  );
+}

package/src/primitives/Button.tsx

@@ -0,0 +1,123 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../lib/utils';
+import { useSurface } from './surface';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center gap-2 rounded-button text-sm transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50 font-button',
+  {
+    variants: {
+      variant: {
+        // Use proper Tailwind tokens — the previous `btn-primary-auto`
+        // class lives in ui-react/styles/globals.css, which snowcone (and
+        // any consumer using only defaults.css/base.css/utilities.css)
+        // does NOT import, so primary buttons rendered with no background
+        // there. `bg-primary text-primary-foreground` is universal.
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90', // HeroUI alias
+        secondary: 'bg-default text-default-foreground hover:bg-default/80',
+        tertiary: 'hover:bg-muted', // HeroUI alias
+        field: 'bg-field text-foreground hover:bg-field/80 shadow-soft dark:shadow-none rounded-input',
+        ghost: 'text-foreground/70 hover:text-foreground hover:bg-muted',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-divider bg-transparent hover:bg-muted',
+        link: 'text-primary underline-offset-4 hover:underline',
+        // Option variants for product selectors (sizes, colors)
+        'option-text': 'px-5 py-2.5 text-base font-medium rounded-full border-2 bg-background min-w-[70px] data-[selected=true]:border-primary data-[selected=false]:border-border hover:border-primary/50',
+        'option-swatch': 'relative h-12 w-12 shrink-0 aspect-square rounded-full data-[selected=true]:scale-105 data-[selected=true]:border-2 data-[selected=true]:border-primary ring-1 ring-border/30',
+        // Standalone action buttons (not part of a selection set)
+        'action': 'px-5 py-2.5 text-base font-medium rounded-full bg-card shadow-sm hover:shadow-md transition-shadow',
+        'action-icon': 'shrink-0 rounded-full bg-card shadow-sm hover:shadow-md transition-shadow px-3 py-2.5',
+      },
+      size: {
+        none: '',
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 px-3',
+        md: 'h-10 px-4 py-2', // HeroUI alias
+        lg: 'h-11 px-8',
+        icon: 'h-10 w-10',
+        // Toolbar size: 44px on mobile, 36px on desktop (md+)
+        toolbar: 'size-11 md:size-9 p-2 rounded-lg',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+  // HeroUI compatibility props
+  onPress?: (e?: React.MouseEvent<HTMLButtonElement>) => void;
+  isPending?: boolean;
+  // Option selection state (for option-text and option-swatch variants)
+  selected?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, onPress, isPending, onClick, disabled, selected, children, ...props }, ref) => {
+    const { variant: surfaceVariant } = useSurface();
+    const isOnDefaultSurface = surfaceVariant === 'default';
+    const isOnSecondarySurface = surfaceVariant === 'secondary';
+
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (onPress) onPress(e);
+      if (onClick) onClick(e);
+    };
+
+    // Surface-aware variant overrides
+    // - On default surface (white card): dark mode needs lighter bg, light mode base color is fine
+    // - On secondary surface: both modes need the raised color for contrast
+    const surfaceOverrides = {
+      secondary:
+        variant === 'secondary' &&
+        (isOnSecondarySurface
+          ? 'bg-[var(--color-default-on-surface)] hover:bg-[var(--color-default-on-surface)]/80'
+          : isOnDefaultSurface
+            ? 'dark:bg-[var(--color-default-on-surface)] dark:hover:bg-[var(--color-default-on-surface)]/80'
+            : false),
+      field:
+        variant === 'field' &&
+        (isOnSecondarySurface
+          ? 'bg-[var(--color-field-on-surface)] hover:bg-[var(--color-field-on-surface)]/80'
+          : isOnDefaultSurface
+            ? 'dark:bg-[var(--color-field-on-surface)] dark:hover:bg-[var(--color-field-on-surface)]/80'
+            : false),
+      ghost:
+        variant === 'ghost' &&
+        (isOnDefaultSurface || isOnSecondarySurface) &&
+        'hover:bg-[var(--color-default-on-surface)]',
+      outline:
+        variant === 'outline' &&
+        (isOnDefaultSurface || isOnSecondarySurface) &&
+        'hover:bg-[var(--color-default-on-surface)]',
+    };
+
+    return (
+      <button
+        className={cn(
+          buttonVariants({ variant, size }),
+          surfaceOverrides.secondary,
+          surfaceOverrides.field,
+          surfaceOverrides.ghost,
+          surfaceOverrides.outline,
+          className
+        )}
+        ref={ref}
+        onClick={handleClick}
+        disabled={disabled || isPending}
+        data-selected={selected}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };

package/src/primitives/ColorSwatch.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+export interface ColorSwatchChoice {
+  value: string;
+  label: string;
+  hex?: string;
+  imageUrl?: string;
+  selected?: boolean;
+  disabled?: boolean;
+}
+
+export interface ColorSwatchProps {
+  /** Array of color choices to display */
+  choices: ColorSwatchChoice[];
+  /** Callback when a color is selected */
+  onChange: (value: string) => void;
+  /** Optional ARIA label for the color group */
+  ariaLabel?: string;
+  /** Show tooltip on selection (default: true) */
+  showTooltip?: boolean;
+  /** Custom size in pixels (default: 40) */
+  size?: number;
+  /** Custom className for the container */
+  className?: string;
+}
+
+/**
+ * ColorSwatch - Interactive color selector with visual feedback
+ *
+ * A primitive component for displaying color choices as clickable swatches with
+ * support for hex colors, image thumbnails, selection states, and tooltips.
+ * Designed for maximum accessibility and visual clarity.
+ *
+ * Features:
+ * - Hex color or image thumbnail backgrounds
+ * - Visual selection indicators (checkmark, rings)
+ * - Disabled state with diagonal slash
+ * - Hover scaling for interactivity
+ * - Tooltip feedback on selection
+ * - Screen reader announcements
+ * - Accessible with ARIA roles and labels
+ * - Dark mode support
+ * - Customizable size
+ * - Colorblind-friendly selection indicators
+ *
+ * **Visual States:**
+ * - Default: Simple round swatch with subtle border
+ * - Selected: Double ring + checkmark icon + pattern overlay
+ * - Disabled: Diagonal slash overlay
+ * - Hover: Slight scale animation
+ *
+ * **Accessibility:**
+ * - Keyboard navigable
+ * - Screen reader friendly with status announcements
+ * - Visible selection indicators for colorblind users
+ * - Proper ARIA roles and labels
+ *
+ * @example
+ * ```tsx
+ * // Basic color swatches
+ * <ColorSwatch
+ *   choices={[
+ *     { value: "red", label: "Red", hex: "#ff0000", selected: true },
+ *     { value: "blue", label: "Blue", hex: "#0000ff" },
+ *     { value: "green", label: "Green", hex: "#00ff00", disabled: true }
+ *   ]}
+ *   onChange={(value) => console.log('Selected:', value)}
+ *   ariaLabel="Choose product color"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With image thumbnails (patterns/textures)
+ * <ColorSwatch
+ *   choices={[
+ *     { value: "marble", label: "Marble", imageUrl: "/textures/marble.jpg" },
+ *     { value: "wood", label: "Wood Grain", imageUrl: "/textures/wood.jpg" }
+ *   ]}
+ *   onChange={handleMaterialChange}
+ *   size={50}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling and no tooltips
+ * <ColorSwatch
+ *   choices={colorOptions}
+ *   onChange={setColor}
+ *   showTooltip={false}
+ *   size={60}
+ *   className="gap-4 justify-center"
+ * />
+ * ```
+ *
+ * @param choices - Array of color/pattern choices to display
+ * @param onChange - Callback when a swatch is clicked (receives choice value)
+ * @param ariaLabel - Accessible label for the color group
+ * @param showTooltip - Show selection tooltip (default: true)
+ * @param size - Swatch diameter in pixels (default: 40)
+ * @param className - Additional CSS classes for container
+ */
+export function ColorSwatch({
+  choices,
+  onChange,
+  ariaLabel,
+  showTooltip = true,
+  size = 40,
+  className = "",
+}: ColorSwatchProps) {
+  const [activeTooltip, setActiveTooltip] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (activeTooltip && showTooltip) {
+      const timer = setTimeout(() => {
+        setActiveTooltip(null);
+      }, 2000);
+      return () => clearTimeout(timer);
+    }
+  }, [activeTooltip, showTooltip]);
+
+  const handleSwatchClick = (choice: ColorSwatchChoice) => {
+    onChange(choice.value);
+    if (showTooltip) {
+      setActiveTooltip(choice.value);
+    }
+  };
+
+  return (
+    <>
+      <div
+        className={`flex flex-wrap gap-2 ${className}`}
+        role="group"
+        aria-label={ariaLabel}
+      >
+        {choices.map((choice) => (
+          <div key={choice.value} className="relative">
+            <button
+              type="button"
+              onClick={() => handleSwatchClick(choice)}
+              className={`relative rounded-full transition-all duration-200 flex-shrink-0 ${
+                choice.disabled ? "cursor-not-allowed" : "cursor-pointer"
+              } ${
+                choice.selected ? "scale-105 border-2 border-primary" : "ring-1 ring-border"
+              }`}
+              style={{
+                width: `${size}px`,
+                height: `${size}px`,
+              }}
+              aria-label={`${choice.label} color${choice.selected ? ', selected' : ''}`}
+              aria-pressed={choice.selected}
+              disabled={choice.disabled}
+              title={choice.label}
+            >
+              <span
+                className={`absolute ${
+                  choice.selected ? "inset-[3px]" : "inset-0"
+                } rounded-full block bg-cover bg-center transition-all duration-200`}
+                style={{
+                  backgroundColor: choice.hex || "#ccc",
+                  backgroundImage: choice.imageUrl
+                    ? `url(${choice.imageUrl})`
+                    : undefined,
+                }}
+              />
+              {choice.disabled && (
+                <>
+                  <span
+                    className="absolute inset-0 rounded-full pointer-events-none opacity-80"
+                    style={{
+                      background:
+                        "linear-gradient(to bottom right, transparent calc(50% - 3px), var(--color-foreground) calc(50% - 3px), var(--color-foreground) calc(50% + 3px), transparent calc(50% + 3px))",
+                    }}
+                  />
+                  <span
+                    className="absolute inset-0 rounded-full pointer-events-none bg-background opacity-40"
+                  />
+                </>
+              )}
+            </button>
+          </div>
+        ))}
+      </div>
+
+      {/* Screen reader announcement and visual tooltip for swatch selection */}
+      {activeTooltip && showTooltip && (
+        <>
+          <div
+            className="sr-only"
+            role="status"
+            aria-live="polite"
+            aria-atomic="true"
+          >
+            {ariaLabel}: {
+              choices.find((c) => c.value === activeTooltip)?.label
+            } selected
+          </div>
+          {/* Visual tooltip for sighted users */}
+          <div
+            className="fixed bg-primary text-primary-foreground text-sm px-3 py-2 rounded-tooltip shadow-xl pointer-events-none"
+            style={{
+              top: "20px",
+              left: "50%",
+              transform: "translateX(-50%)",
+              zIndex: 9999,
+              maxWidth: "90vw",
+            }}
+            aria-hidden="true"
+          >
+            {ariaLabel}: {
+              choices.find((c) => c.value === activeTooltip)?.label
+            } selected
+          </div>
+        </>
+      )}
+    </>
+  );
+}