@snowcone-app/ui 0.2.6 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -103,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.16.0"
+    "@snowcone-app/sdk": "0.16.1"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",

package/src/components/LoadingOverlayPrismCandy.tsx

@@ -0,0 +1,476 @@
+"use client";
+
+/**
+ * Candy-variant loading overlay — the snowcone rainbow. Same external API as
+ * `LoadingOverlayPrism` (drop-in replacement). Lifted from apps/www (where it
+ * was born on the PDP hero) so every surface can use the brand loader; the
+ * www module re-exports from here.
+ *
+ * Two flavours exported:
+ *   - `LoadingOverlayPrismCandy` (default) — visual content portals to
+ *     `document.body` with `position: absolute` (no z-index), positioned at
+ *     document-coordinate top/left matching an in-place anchor element's
+ *     bounding rect. Used on the PDP hero where the artwork sits in the
+ *     normal document flow.
+ *   - `LoadingOverlayPrismCandyInline` — renders the same visual in-place,
+ *     `position: absolute; inset: 0` filling its parent. Used inside
+ *     fixed-position modal stacks (e.g. the mobile editor overlay at
+ *     z-[9999]) where a body-level portal can't paint above the modal.
+ *
+ * Three stacking-context properties had to be avoided to keep
+ * `mix-blend-mode: screen` reaching the artwork below:
+ *   - `z-index` on a positioned element (creates stacking context + isolated
+ *     blend group)
+ *   - `position: fixed` (creates stacking context unconditionally)
+ *   - `opacity < 1` (creates an isolated blend group)
+ *
+ * That last one ruled out fading via `opacity` — both for the overlay mount
+ * fade AND for each band's per-sweep fade-in / fade-out. Both are driven by
+ * registered CSS custom properties (`--candy-mount` for the overlay-wide
+ * mount, `--band-alpha` per-band for the sweep) that scale the rgba alphas
+ * of the white plate and band gradients. `@property` registration lets the
+ * browser interpolate the variables across `transition` / `@keyframes`.
+ *
+ * (Earlier versions animated band `opacity` 0→1→0 in the sweep keyframes —
+ * each band became its own isolated blend group during fade-in/out, and
+ * `mix-blend-mode: screen` collapsed to plain alpha-blending in those
+ * frames, so the bands read as dark coloured rectangles on bright artwork.
+ * Most visible inside fixed/modal stacks like the mobile editor preview.)
+ *
+ * Sparkle particles still use `opacity` — they have no `mix-blend-mode`,
+ * so opacity-induced isolation has no visible effect on them.
+ */
+
+import {
+  memo,
+  useState,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useCallback,
+} from "react";
+import { createPortal } from "react-dom";
+
+const BANDS: ReadonlyArray<{ rgb: string; delay: string }> = [
+  { rgb: "230, 45, 55", delay: "-0.0s" }, // red
+  { rgb: "250, 125, 30", delay: "-0.3s" }, // orange
+  { rgb: "244, 215, 60", delay: "-0.6s" }, // yellow
+  { rgb: "110, 200, 70", delay: "-0.9s" }, // green
+  { rgb: "65, 145, 205", delay: "-1.2s" }, // blue
+  { rgb: "140, 90, 175", delay: "-1.5s" }, // purple
+];
+
+type Particle = {
+  left: number;
+  top: number;
+  delay: string;
+  duration: string;
+  size: number;
+};
+
+function generateParticles(): Particle[] {
+  return Array.from({ length: 10 }, () => ({
+    left: 2 + Math.random() * 96,
+    top: 2 + Math.random() * 96,
+    delay: (Math.random() * 3.5).toFixed(1),
+    duration: (3 + Math.random() * 2).toFixed(1),
+    size: 3 + Math.random() * 5,
+  }));
+}
+
+const PLATE_ALPHA = 0.1;
+const BAND_ALPHA = 0.55;
+const FADE_IN_MS = 600;
+const FADE_OUT_MS = 400;
+
+const STYLES = `
+/* Registered custom properties — required for the browser to interpolate
+   them across a CSS transition / animation. Without @property, value
+   changes snap rather than animate. */
+@property --candy-mount {
+  syntax: "<number>";
+  initial-value: 0;
+  inherits: true;
+}
+/* Per-band sweep-fade. Animated by the keyframes below to scale the band
+   rgba alpha 0 → 1 → 1 → 0 across a sweep cycle. Lives on .candy-band
+   only (not inherited), so each band has its own animated value. */
+@property --band-alpha {
+  syntax: "<number>";
+  initial-value: 0;
+  inherits: false;
+}
+
+.candy-loading-overlay {
+  --candy-mount: 0;
+  overflow: hidden;
+  background-color: rgba(255, 255, 255, calc(${PLATE_ALPHA} * var(--candy-mount)));
+  transition: --candy-mount ${FADE_IN_MS}ms ease-in,
+              background-color ${FADE_IN_MS}ms ease-in;
+}
+.candy-loading-overlay.candy-fade-in  { --candy-mount: 1; }
+.candy-loading-overlay.candy-fade-out {
+  --candy-mount: 0;
+  transition: --candy-mount ${FADE_OUT_MS}ms ease-out,
+              background-color ${FADE_OUT_MS}ms ease-out;
+}
+
+.candy-band {
+  --band-alpha: 0;
+  position: absolute;
+  width: 220%; height: 30%;
+  left: -60%;
+  mix-blend-mode: screen;
+  -webkit-mask-image: linear-gradient(180deg, transparent 0%, black 35%, black 65%, transparent 100%);
+          mask-image: linear-gradient(180deg, transparent 0%, black 35%, black 65%, transparent 100%);
+  animation-timing-function: ease-in-out;
+  animation-iteration-count: infinite;
+  animation-duration: 6s;
+}
+${BANDS.map((b, i) => {
+  const top = -5 + i * 16;
+  const direction = i % 2 === 0 ? "ltr" : "rtl";
+  // Band rgba alpha scales with both --candy-mount (overlay mount fade)
+  // and --band-alpha (per-sweep fade-in/out). Neither uses the `opacity`
+  // property, which would form an isolated blend group and break
+  // mix-blend-mode: screen — the very thing that lets these bands tint
+  // the artwork below. With opacity, screen-blend collapses to plain
+  // alpha-blending and the bands read as dark coloured rectangles on
+  // bright artwork (most visible inside fixed/modal stacks where
+  // an ancestor's own opacity transition is mid-flight).
+  return `.candy-band:nth-child(${i + 1}) { top: ${top}%; background: linear-gradient(90deg, transparent 0%, rgba(${b.rgb}, calc(${BAND_ALPHA} * var(--candy-mount) * var(--band-alpha) * var(--band-strength, 1))) 30%, rgba(${b.rgb}, calc(${BAND_ALPHA} * var(--candy-mount) * var(--band-alpha) * var(--band-strength, 1))) 70%, transparent 100%); animation-name: candy-sweep-${direction}; animation-delay: ${b.delay}; }`;
+}).join("\n")}
+@keyframes candy-sweep-ltr {
+  0%   { transform: translateX(-45%) rotate(-6deg); --band-alpha: 0; }
+  25%  { --band-alpha: 1; }
+  50%  { transform: translateX(0%)   rotate(-6deg); }
+  75%  { --band-alpha: 1; }
+  100% { transform: translateX(45%)  rotate(-6deg); --band-alpha: 0; }
+}
+@keyframes candy-sweep-rtl {
+  0%   { transform: translateX(45%)  rotate(-6deg); --band-alpha: 0; }
+  25%  { --band-alpha: 1; }
+  50%  { transform: translateX(0%)   rotate(-6deg); }
+  75%  { --band-alpha: 1; }
+  100% { transform: translateX(-45%) rotate(-6deg); --band-alpha: 0; }
+}
+
+.candy-particle {
+  position: absolute; border-radius: 50%;
+  /* Particle background and glow alphas also scale with --candy-mount so
+     the sparkles fade with the rest of the overlay. */
+  background: rgba(255, 255, 255, calc(1 * var(--candy-mount)));
+  box-shadow: 0 0 8px rgba(255, 255, 255, calc(0.85 * var(--candy-mount)));
+  opacity: 0;
+  animation: candy-sparkle infinite ease-in-out;
+}
+@keyframes candy-sparkle {
+  0%   { opacity: 0;   transform: scale(0);   }
+  15%  { opacity: 0.7; transform: scale(1.4); }
+  30%  { opacity: 0.4; transform: scale(0.6); }
+  55%  { opacity: 1;   transform: scale(2);   }
+  75%  { opacity: 0.5; transform: scale(0.9); }
+  100% { opacity: 0;   transform: scale(0);   }
+}
+
+/* Light-backdrop variant. The default bands screen-blend — vivid on a dark
+   stage, but they wash out to nothing over white (screen over white = white).
+   On a light card we multiply-blend instead, so each band tints the backdrop
+   toward its hue (jewel/pastel rainbow rather than neon). The sparkle particles
+   stay white in both variants — they read as snow, and the white glow keeps
+   them legible over the multiply rainbow bands. */
+.candy-on-light .candy-band { mix-blend-mode: multiply; }
+/* Opaque light stage baked into the overlay so it fades in/out as one unit
+   with the bands — matching the PDP hero's smooth crossfade — instead of a
+   hard backdrop on the parent that snaps on/off. The alpha scales with
+   --candy-mount (overriding the default 0.1 white plate), so it rides the
+   same candy-fade-in / candy-fade-out transition the bands do. The bands
+   multiply-blend against this opaque stage to read as the candy rainbow.
+   #f5f5f5 = the site page background (defaults.css --color-background), kept
+   as a fixed hex (not the token, which would flip dark in dark mode and break
+   the multiply blend) so the loader sits flush with the surrounding page. */
+.candy-on-light {
+  background-color: rgba(245, 245, 245, calc(1 * var(--candy-mount)));
+  /* Half the band opacity on the light stage — multiply-blended bands read
+     stronger on light gray than the screen-blended ones do on the dark PDP
+     stage, so dial them back to ~50%. Inherits down to .candy-band; the dark
+     default leaves --band-strength at its 1 fallback, untouched. */
+  --band-strength: 0.5;
+}
+
+`;
+
+let stylesInjected = false;
+function ensureStyles() {
+  if (stylesInjected || typeof document === "undefined") return;
+
+  // Belt-and-suspenders: also register via the JS API. iOS Safari has a
+  // long-standing quirk where `@property` declared inside a dynamically
+  // inserted `<style>` (the path below) silently fails to register, leaving
+  // the custom properties unregistered → CSS transitions snap rather than
+  // interpolate → the rainbow overlay vanishes instantly when the mockup
+  // image lands. `CSS.registerProperty` doesn't go through the stylesheet
+  // path and isn't affected by that bug. If it succeeds, the `@property`
+  // declarations in `STYLES` are redundant; if it fails (already registered
+  // by an HMR remount, or older browser), we fall back to those rules.
+  if (typeof CSS !== "undefined" && typeof CSS.registerProperty === "function") {
+    try {
+      CSS.registerProperty({
+        name: "--candy-mount",
+        syntax: "<number>",
+        initialValue: "0",
+        inherits: true,
+      });
+    } catch {
+      // Already registered (HMR) — fine.
+    }
+    try {
+      CSS.registerProperty({
+        name: "--band-alpha",
+        syntax: "<number>",
+        initialValue: "0",
+        inherits: false,
+      });
+    } catch {
+      // Already registered (HMR) — fine.
+    }
+  }
+
+  const s = document.createElement("style");
+  s.textContent = STYLES;
+  document.head.appendChild(s);
+  stylesInjected = true;
+}
+
+export interface LoadingOverlayPrismCandyProps {
+  /** When false, the overlay fades out then calls onExited. Default true. */
+  visible?: boolean;
+  /** Called after the fade-out transition completes. Use this to unmount. */
+  onExited?: () => void;
+  /**
+   * Backdrop the overlay is rendered over. Default `"dark"`: bands
+   * screen-blend, vivid neon rainbow on a dark stage (the PDP hero). `"light"`:
+   * bands multiply-blend and sparkles recolor dark so the rainbow reads as
+   * candy/pastel tones over a white/light-gray backdrop (chat mockup cards).
+   * Only the Inline variant honors this today.
+   */
+  variant?: "dark" | "light";
+}
+
+interface Bounds {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Plate + bands + particles markup. Rendered by both the portal and inline
+ * variants so the visual stays identical. Caller owns positioning of the
+ * `.candy-loading-overlay` element via `style`.
+ */
+function CandyVisual({
+  fadeClass,
+  style,
+  onTransitionEnd,
+  variantClass = "",
+}: {
+  fadeClass: string;
+  style: React.CSSProperties;
+  onTransitionEnd?: (e: React.TransitionEvent<HTMLDivElement>) => void;
+  /** Extra root-level class for variant overrides (e.g. "candy-inline"). */
+  variantClass?: string;
+}) {
+  // Empty on first render so SSR matches; populate after mount so each
+  // show of the loader gets a fresh random field.
+  const [particles, setParticles] = useState<Particle[]>([]);
+  useEffect(() => {
+    setParticles(generateParticles());
+  }, []);
+
+  return (
+    <div
+      className={`candy-loading-overlay ${variantClass} ${fadeClass}`.trim()}
+      style={style}
+      onTransitionEnd={onTransitionEnd}
+    >
+      {BANDS.map((_, i) => (
+        <div key={`b-${i}`} className="candy-band" />
+      ))}
+      {particles.map((p, i) => (
+        <div
+          key={`p-${i}`}
+          className="candy-particle"
+          style={{
+            left: `${p.left}%`,
+            top: `${p.top}%`,
+            animationDelay: `${p.delay}s`,
+            animationDuration: `${p.duration}s`,
+            width: `${p.size}px`,
+            height: `${p.size}px`,
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Wrapped in React.memo so a parent re-render with unchanged `visible` /
+ * `onExited` props doesn't trigger reconciliation of all 6 bands + 10
+ * particles inside this component. Cuts a meaningful amount of work during
+ * realtime mockup updates, where `HeroProductImage`'s internal state
+ * thrashes a few times per swap and would otherwise cascade up.
+ */
+export const LoadingOverlayPrismCandy = memo(function LoadingOverlayPrismCandy({
+  visible = true,
+  onExited,
+}: LoadingOverlayPrismCandyProps) {
+  ensureStyles();
+
+  const anchorRef = useRef<HTMLDivElement>(null);
+  const [bounds, setBounds] = useState<Bounds | null>(null);
+  // Trigger fade-in on next frame after mount so the CSS transition plays.
+  // (If we applied .candy-fade-in on the first render, the browser would
+  // never see a transition between two states.)
+  const [mounted, setMounted] = useState(false);
+
+  const measure = useCallback(() => {
+    const el = anchorRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    setBounds({
+      top: r.top + window.scrollY,
+      left: r.left + window.scrollX,
+      width: r.width,
+      height: r.height,
+    });
+  }, []);
+
+  useLayoutEffect(() => {
+    measure();
+    window.addEventListener("resize", measure);
+
+    let ro: ResizeObserver | null = null;
+    if (typeof ResizeObserver !== "undefined" && anchorRef.current) {
+      ro = new ResizeObserver(measure);
+      ro.observe(anchorRef.current);
+    }
+
+    return () => {
+      window.removeEventListener("resize", measure);
+      ro?.disconnect();
+    };
+  }, [measure]);
+
+  useEffect(() => {
+    const raf = requestAnimationFrame(() => setMounted(true));
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  const handleTransitionEnd = useCallback(
+    (e: React.TransitionEvent<HTMLDivElement>) => {
+      // background-color transitions in lockstep with --candy-mount; fire
+      // onExited only when the fade-out finishes.
+      if (e.propertyName !== "background-color") return;
+      if (!visible) onExited?.();
+    },
+    [visible, onExited],
+  );
+
+  let fadeClass = "";
+  if (!visible) fadeClass = "candy-fade-out";
+  else if (mounted) fadeClass = "candy-fade-in";
+
+  return (
+    <>
+      {/* Anchor: invisible, in-place; gets layout from `position: absolute;
+          inset: 0` of its parent so its bounding rect drives the portal's
+          position. Always rendered, even during fade-out, so we can keep
+          re-measuring if the parent resizes mid-fade. */}
+      <div
+        ref={anchorRef}
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+        }}
+        aria-hidden="true"
+      />
+      {/* Portal: actual visual content at body level. position: absolute (no
+          z-index, no fixed) keeps it from forming a stacking context, so the
+          bands' mix-blend-mode: screen reaches the artwork through the body's
+          stacking context. */}
+      {bounds &&
+        typeof document !== "undefined" &&
+        createPortal(
+          <CandyVisual
+            fadeClass={fadeClass}
+            style={{
+              position: "absolute",
+              top: bounds.top,
+              left: bounds.left,
+              width: bounds.width,
+              height: bounds.height,
+              pointerEvents: "none",
+            }}
+            onTransitionEnd={handleTransitionEnd}
+          />,
+          document.body,
+        )}
+    </>
+  );
+});
+
+/**
+ * Inline variant — renders the candy visual directly in place, filling its
+ * parent (which must be `position: relative` / `absolute` / `fixed`). Use
+ * when the overlay needs to paint inside a higher-stacking-context modal
+ * (e.g. the mobile editor at z-[9999]) where a body-level portal can't reach
+ * above the modal.
+ *
+ * Bands still screen-blend with the artwork as long as the IMG and the
+ * overlay share the same isolated blend group (true even when an ancestor
+ * has `opacity < 1` mid-transition — the IMG and bands are inside that
+ * group together, so screen-blending between them works).
+ */
+export const LoadingOverlayPrismCandyInline = memo(
+  function LoadingOverlayPrismCandyInline({
+    visible = true,
+    onExited,
+    variant = "dark",
+  }: LoadingOverlayPrismCandyProps) {
+    ensureStyles();
+
+    const [mounted, setMounted] = useState(false);
+    useEffect(() => {
+      const raf = requestAnimationFrame(() => setMounted(true));
+      return () => cancelAnimationFrame(raf);
+    }, []);
+
+    const handleTransitionEnd = useCallback(
+      (e: React.TransitionEvent<HTMLDivElement>) => {
+        if (e.propertyName !== "background-color") return;
+        if (!visible) onExited?.();
+      },
+      [visible, onExited],
+    );
+
+    let fadeClass = "";
+    if (!visible) fadeClass = "candy-fade-out";
+    else if (mounted) fadeClass = "candy-fade-in";
+
+    return (
+      <CandyVisual
+        fadeClass={fadeClass}
+        variantClass={variant === "light" ? "candy-on-light" : ""}
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+        }}
+        onTransitionEnd={handleTransitionEnd}
+      />
+    );
+  },
+);

package/src/index.ts

@@ -126,6 +126,11 @@ export type { CanvasExportServiceConfig } from "./services/CanvasExportService";
 export { CanvasIsolationBoundary, CanvasIsolationConfigurator, useIsolatedCanvas } from "./components/CanvasIsolationBoundary";
 export { LoadingOverlayPrism, useLoadingOverlay } from "./components/LoadingOverlayPrism";
 export type { LoadingOverlayPrismProps } from "./components/LoadingOverlayPrism";
+export {
+  LoadingOverlayPrismCandy,
+  LoadingOverlayPrismCandyInline,
+} from "./components/LoadingOverlayPrismCandy";
+export type { LoadingOverlayPrismCandyProps } from "./components/LoadingOverlayPrismCandy";
 
 // Re-export realtime mockup hook from SDK for convenience
 export { useRealtimeMockup } from "@snowcone-app/sdk/react";