@snowcone-app/ui 0.1.43 → 0.2.1

package/src/personalization/PersonalizationProvider.tsx

@@ -0,0 +1,407 @@
+"use client";
+
+/**
+ * PersonalizationProvider — encapsulates all personalization state, the hidden
+ * canvas, and the realtime mockup connection.
+ *
+ * Just wrap your product page content and pass the design's field definitions
+ * and canvas state. Everything else (canvas import, bridge, blob forwarding,
+ * realtime connection) is handled automatically.
+ *
+ * Requires `@snowcone-app/canvas` as a peer dependency (optional — if not
+ * installed, the provider works for state management but skips canvas rendering).
+ *
+ * @example
+ * ```tsx
+ * <PersonalizationProvider
+ *   fields={personalization}
+ *   canvasState={canvasState}
+ *   canvasImport={() => import("@snowcone-app/canvas")}
+ *   lazy
+ * >
+ *   <PersonalizationInputs />
+ *   <MobileProductCarousel ... />
+ * </PersonalizationProvider>
+ * ```
+ */
+
+import React, {
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  type ReactNode,
+} from "react";
+import { PersonalizationContext } from "./PersonalizationContext";
+import { useRealtimeOptional } from "../patterns/RealtimeProvider";
+import type {
+  PersonalizationField,
+  PersonalizationValues,
+} from "./types";
+import { normalizeHex, isValidImageUrl, useDebouncedValue } from "./utils";
+
+// ---------------------------------------------------------------------------
+// Bridge factory — creates the PersonalizationBridge component from the canvas
+// module's hooks at runtime. This avoids a static import of @snowcone-app/canvas
+// in the bundle, since canvas is an optional peer dependency.
+// ---------------------------------------------------------------------------
+
+function createBridgeFromCanvas(canvasModule: any): React.ComponentType<{
+  fields?: PersonalizationField[];
+  values?: PersonalizationValues;
+}> {
+  const { useEditor, useCommands, useImageBinding } = canvasModule;
+
+  function TextBinder({ name, value }: { name: string; value: string }) {
+    const { elements } = useEditor();
+    const { executeElementUpdate } = useCommands();
+    const elementsRef = React.useRef(elements);
+    elementsRef.current = elements;
+    const executeRef = React.useRef(executeElementUpdate);
+    executeRef.current = executeElementUpdate;
+    const hasUserInput = React.useRef(false);
+
+    React.useEffect(() => {
+      if (value == null) return;
+      if (value === "" && !hasUserInput.current) return;
+      hasUserInput.current = true;
+      const exec = executeRef.current;
+      for (const el of elementsRef.current) {
+        if (el.name !== name) continue;
+        if (!("setText" in el) || typeof (el as any).setText !== "function") continue;
+        const cloned = el.clone();
+        (cloned as any).setText(value);
+        exec(el, cloned);
+      }
+    }, [value, name, elements.length]);
+    return null;
+  }
+
+  function ColorBinder({ originalColor, newColor }: { originalColor: string; newColor: string }) {
+    const { elements } = useEditor();
+    const { executeElementUpdate } = useCommands();
+    const elementsRef = React.useRef(elements);
+    elementsRef.current = elements;
+    const executeRef = React.useRef(executeElementUpdate);
+    executeRef.current = executeElementUpdate;
+    const appliedColorRef = React.useRef(normalizeHex(originalColor));
+
+    React.useEffect(() => {
+      const normalizedNew = normalizeHex(newColor);
+      if (normalizedNew === appliedColorRef.current) return;
+      const matchColor = appliedColorRef.current;
+      const exec = executeRef.current;
+      for (const el of elementsRef.current) {
+        let needsUpdate = false;
+        const cloned = el.clone();
+        if ("color" in el && typeof (el as any).color === "string") {
+          if (normalizeHex((el as any).color) === matchColor) {
+            if (typeof (cloned as any).setColor === "function") {
+              (cloned as any).setColor(newColor);
+            } else {
+              (cloned as any).color = newColor;
+            }
+            needsUpdate = true;
+          }
+        }
+        if (normalizeHex((el as any).transformData?.fillColor ?? "") === matchColor) {
+          (cloned as any).transformData = { ...(cloned as any).transformData, fillColor: newColor };
+          needsUpdate = true;
+        }
+        if (normalizeHex((el as any).transformData?.strokeColor ?? "") === matchColor) {
+          (cloned as any).transformData = { ...(cloned as any).transformData, strokeColor: newColor };
+          needsUpdate = true;
+        }
+        if ((el as any).stroke?.enabled && normalizeHex((el as any).stroke?.color ?? "") === matchColor) {
+          (cloned as any).stroke = { ...(cloned as any).stroke, color: newColor };
+          needsUpdate = true;
+        }
+        if (needsUpdate) exec(el, cloned);
+      }
+      // Only update the tracking ref if elements have loaded.
+      // With lazy mounting, the effect can fire before elements exist —
+      // keeping the old ref ensures the change retries when elements appear.
+      if (elementsRef.current.length > 0) {
+        appliedColorRef.current = normalizedNew;
+      }
+    }, [newColor, elements.length]);
+    return null;
+  }
+
+  function ImageBinder({ name, value, fit = "cover" }: { name: string; value: string; fit?: "cover" | "contain" }) {
+    const { setImageUrl } = useImageBinding(name, { fit: fit as any });
+    const hasUserInput = React.useRef(false);
+    const debouncedValue = useDebouncedValue(value, 500);
+    const setImageUrlRef = React.useRef(setImageUrl);
+    setImageUrlRef.current = setImageUrl;
+
+    React.useEffect(() => {
+      if (debouncedValue == null) return;
+      if (debouncedValue === "" && !hasUserInput.current) return;
+      hasUserInput.current = true;
+      if (debouncedValue !== "" && !isValidImageUrl(debouncedValue)) return;
+      setImageUrlRef.current(debouncedValue);
+    }, [debouncedValue]);
+    return null;
+  }
+
+  return function PersonalizationBridge({ fields = [], values = {} }: { fields?: PersonalizationField[]; values?: PersonalizationValues } = {}) {
+    return (
+      <>
+        {fields.map((field) => {
+          if (field.type === "text") {
+            return <TextBinder key={`text-${field.name}`} name={field.name} value={values[field.name] ?? ""} />;
+          }
+          if (field.type === "color") {
+            return <ColorBinder key={`color-${field.color}`} originalColor={field.color} newColor={values[field.color] ?? field.color} />;
+          }
+          if (field.type === "image") {
+            return <ImageBinder key={`image-${field.name}`} name={field.name} value={values[field.name] ?? ""} fit={field.fit ?? "cover"} />;
+          }
+          return null;
+        })}
+      </>
+    );
+  };
+}
+
+// Module-level cache — shared across all provider instances
+let cachedCanvasComponent: React.ComponentType<any> | null = null;
+let cachedBridgeComponent: React.ComponentType<any> | null = null;
+let cachedSerialize: ((state: any) => any) | null = null;
+let canvasLoadPromise: Promise<boolean> | null = null;
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface PersonalizationProviderProps {
+  /** Personalization field definitions (from design's state.json) */
+  fields: PersonalizationField[];
+  /** Full canvas state (elements + artboards) for the hidden canvas */
+  canvasState?: {
+    elements?: any[];
+    artboards?: any[];
+    activeArtboard?: string;
+  } | null;
+  /**
+   * Lazy import for `@snowcone-app/canvas`. Runs in the consumer's webpack context
+   * so module resolution works even though this package doesn't depend on canvas.
+   *
+   * @example `canvasImport={() => import("@snowcone-app/canvas")}`
+   */
+  canvasImport?: () => Promise<any>;
+  /** If true, canvas only mounts after first field interaction (saves resources). @default true */
+  lazy?: boolean;
+  /** Export config overrides */
+  exportConfig?: {
+    debounceMs?: number;
+    maxWaitMs?: number;
+    scale?: number;
+    maxSize?: number;
+    imageFormat?: "png" | "webp";
+    imageQuality?: number;
+  };
+  /** Product placement name used when sending blobs to RealtimeProvider.
+   *  Defaults to the export artboard name. Override when the product uses
+   *  a different placement name (e.g. "Main" instead of "Front"). */
+  placement?: string;
+  /** Initial personalization values (e.g. from a cart item link). */
+  initialValues?: Record<string, string>;
+  /** Increment to force the hidden canvas to remount with fresh canvasState
+   *  (e.g. after an editor session modifies element positions). */
+  canvasStateVersion?: number;
+  children: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function PersonalizationProvider({
+  fields,
+  canvasState,
+  canvasImport,
+  lazy = true,
+  exportConfig,
+  placement: placementOverride,
+  initialValues,
+  canvasStateVersion,
+  children,
+}: PersonalizationProviderProps) {
+  const realtime = useRealtimeOptional();
+
+  // --- State ---
+  const [personValues, setPersonValues] = useState<PersonalizationValues>(initialValues ?? {});
+  const [isActive, setIsActive] = useState(!!(initialValues && Object.keys(initialValues).length > 0));
+  const [isExporting, setIsExporting] = useState(false);
+  const [exportedBlobUrls, setExportedBlobUrls] = useState<
+    Record<string, string>
+  >({});
+  const [exportCount, setExportCount] = useState(0);
+  const blobUrlsRef = useRef<Record<string, string>>({});
+
+  // --- Resolve canvas + bridge via the consumer's import thunk ---
+  const [CanvasComponent, setCanvasComponent] = useState<React.ComponentType<any> | null>(
+    cachedCanvasComponent,
+  );
+  const [BridgeComponent, setBridgeComponent] = useState<React.ComponentType<any> | null>(
+    cachedBridgeComponent,
+  );
+
+  useEffect(() => {
+    if (CanvasComponent && BridgeComponent) return;
+    if (!canvasImport) return;
+
+    // Reuse in-flight promise if another instance already started loading
+    if (!canvasLoadPromise) {
+      canvasLoadPromise = canvasImport()
+        .then((mod) => {
+          cachedCanvasComponent = mod.SnowconeCanvas || mod.default;
+          cachedBridgeComponent = createBridgeFromCanvas(mod);
+          cachedSerialize = mod.serializeStateForServer || null;
+          return true;
+        })
+        .catch(() => false);
+    }
+
+    canvasLoadPromise.then((ok) => {
+      if (ok) {
+        setCanvasComponent(() => cachedCanvasComponent);
+        setBridgeComponent(() => cachedBridgeComponent);
+      }
+    });
+  }, [CanvasComponent, BridgeComponent, canvasImport]);
+
+  // --- Realtime connection (lazy — only on first export) ---
+  const realtimeEnabledRef = useRef(false);
+
+  // --- Cleanup blob URLs on unmount ---
+  useEffect(() => {
+    return () => {
+      for (const url of Object.values(blobUrlsRef.current)) {
+        try { URL.revokeObjectURL(url); } catch { /* ignore */ }
+      }
+    };
+  }, []);
+
+  // --- Actions ---
+
+  const updateField = useCallback((key: string, value: string) => {
+    setIsActive(true);
+    setPersonValues((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setPersonValues({});
+    setIsActive(false);
+    setIsExporting(false);
+  }, []);
+
+  const handleExport = useCallback(
+    (exports: Record<string, string | Blob>) => {
+      // Store blob URLs locally
+      const newUrls: Record<string, string> = {};
+      for (const [name, data] of Object.entries(exports)) {
+        if (blobUrlsRef.current[name]) {
+          try { URL.revokeObjectURL(blobUrlsRef.current[name]); } catch { /* ignore */ }
+        }
+        if (data instanceof Blob) {
+          newUrls[name] = URL.createObjectURL(data);
+        } else if (typeof data === "string") {
+          newUrls[name] = data;
+        }
+      }
+      blobUrlsRef.current = { ...blobUrlsRef.current, ...newUrls };
+      setExportedBlobUrls({ ...blobUrlsRef.current });
+      setExportCount((c) => c + 1);
+      setIsExporting(false);
+
+      // Forward blobs to RealtimeProvider for server mockup rendering
+      if (realtime) {
+        if (!realtimeEnabledRef.current) {
+          realtimeEnabledRef.current = true;
+          realtime.enableRealtime();
+        }
+        for (const [artboardName, data] of Object.entries(exports)) {
+          if (data instanceof Blob) {
+            realtime.sendCanvasBlob(placementOverride ?? artboardName, data);
+          }
+        }
+      }
+    },
+    [realtime, placementOverride],
+  );
+
+  const handleExportScheduled = useCallback(() => {
+    setIsExporting(true);
+  }, []);
+
+  // --- Should the hidden canvas be mounted? ---
+  const shouldMountCanvas =
+    CanvasComponent &&
+    BridgeComponent &&
+    canvasState?.elements &&
+    canvasState.elements.length > 0 &&
+    (!lazy || isActive);
+
+  // --- Context ---
+  const contextValue = React.useMemo(
+    () => ({
+      fields,
+      personValues,
+      updateField,
+      isActive,
+      isExporting,
+      exportedBlobUrls,
+      exportCount,
+      reset,
+    }),
+    [fields, personValues, updateField, isActive, isExporting, exportedBlobUrls, exportCount, reset],
+  );
+
+  return (
+    <PersonalizationContext.Provider value={contextValue}>
+      {shouldMountCanvas && CanvasComponent && BridgeComponent && (
+        <div
+          key={`person-canvas-${canvasStateVersion ?? 0}`}
+          style={{
+            position: "fixed",
+            left: -9999,
+            top: 0,
+            width: 500,
+            height: 700,
+            overflow: "hidden",
+            pointerEvents: "none",
+          }}
+          aria-hidden
+        >
+          <CanvasComponent
+            initialElements={canvasState?.elements}
+            artboards={canvasState?.artboards}
+            kit="embed-only"
+            inheritTheme
+            autoExportConfig={{
+              enabled: true,
+              debounceMs: exportConfig?.debounceMs ?? 100,
+              maxWaitMs: exportConfig?.maxWaitMs ?? 1000,
+            }}
+            autoExportFormat="blob"
+            autoExportAll={false}
+            exportScale={exportConfig?.scale ?? 1}
+            maxExportSize={exportConfig?.maxSize ?? 2000}
+            exportImageFormat={exportConfig?.imageFormat ?? "webp"}
+            exportImageQuality={exportConfig?.imageQuality ?? 0.85}
+            onExport={handleExport}
+            onExportScheduled={handleExportScheduled}
+            overlay={
+              <BridgeComponent fields={fields} values={personValues} />
+            }
+          />
+        </div>
+      )}
+
+      {children}
+    </PersonalizationContext.Provider>
+  );
+}

package/src/personalization/canvas-stub.d.ts

@@ -0,0 +1,22 @@
+// @snowcone-app/canvas is declared as an OPTIONAL peer dependency in
+// packages/ui's package.json — consumers that need personalization must
+// install it themselves. For typechecking inside this package alone we
+// stub the imports so tsc resolves without pulling the canvas package
+// (which has its own pre-existing typecheck issues and would couple ui's
+// build to canvas's).
+//
+// Runtime behavior is unaffected; consumers that actually use
+// PersonalizationBridge will have @snowcone-app/canvas installed and the
+// real types will win.
+
+declare module "@snowcone-app/canvas" {
+  export function useEditor(): { elements: any[] };
+  export function useCommands(): {
+    executeElementUpdate: (oldEl: any, newEl: any) => void;
+  };
+  export function useImageBinding(
+    name: string,
+    opts?: { fit?: ImageFitMode }
+  ): { setImageUrl: (url: string | null) => void };
+  export type ImageFitMode = "contain" | "cover" | "fill" | "scale-down";
+}

package/src/personalization/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Personalization — reusable buyer customization system for product designs.
+ *
+ * Add personalization to any product page:
+ *
+ * ```tsx
+ * <PersonalizationProvider fields={fields} canvasState={canvasState} lazy>
+ *   <PersonalizationInputs />
+ *   <YourProductCarousel />
+ * </PersonalizationProvider>
+ * ```
+ *
+ * Access state from any child component:
+ *
+ * ```tsx
+ * const { personValues, updateField, isExporting, exportedBlobUrls } = usePersonalization();
+ * ```
+ */
+
+// Types
+export type {
+  PersonalizationField,
+  PersonalizationTextField,
+  PersonalizationColorField,
+  PersonalizationImageField,
+  PersonalizationValues,
+} from "./types";
+
+// Provider
+export { PersonalizationProvider } from "./PersonalizationProvider";
+
+// Hook
+export { usePersonalization, usePersonalizationOptional } from "./usePersonalization";
+
+// Input UI
+export { PersonalizationInputs } from "./PersonalizationInputs";
+
+// Shimmer — tracks full pipeline, returns { shimmerActive }
+export { usePersonalizationShimmer } from "./usePersonalizationShimmer";
+export type { UsePersonalizationShimmerReturn } from "./usePersonalizationShimmer";
+
+// Utilities (for custom input implementations)
+export { scrollInputAboveKeyboard, normalizeHex } from "./utils";

package/src/personalization/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Personalization Types
+ *
+ * Discriminated union for buyer-customizable design fields.
+ * Used by PersonalizationProvider, PersonalizationInputs, and PersonalizationBridge.
+ */
+
+/** Text field — buyer can change text on the design */
+export interface PersonalizationTextField {
+  type: "text";
+  /** Element name in the canvas (matches TextElement.name) */
+  name: string;
+  /** Buyer-facing label */
+  label: string;
+  /** Input placeholder */
+  placeholder?: string;
+}
+
+/** Color field — buyer can change a color throughout the design */
+export interface PersonalizationColorField {
+  type: "color";
+  /** Original hex color to match against canvas elements */
+  color: string;
+  /** Buyer-facing label */
+  label: string;
+}
+
+/** Image field — buyer can replace an image in the design */
+export interface PersonalizationImageField {
+  type: "image";
+  /** Element name in the canvas (matches ImageElement.name) */
+  name: string;
+  /** Buyer-facing label */
+  label: string;
+  /** Input placeholder */
+  placeholder?: string;
+  /** How the image fits in the placement area */
+  fit?: "cover" | "contain";
+}
+
+/** A single personalizable field in a design */
+export type PersonalizationField =
+  | PersonalizationTextField
+  | PersonalizationColorField
+  | PersonalizationImageField;
+
+/** Buyer's current personalization values. Keys are field names (text/image) or original hex colors (color). */
+export type PersonalizationValues = Record<string, string>;

package/src/personalization/usePersonalization.ts

@@ -0,0 +1,32 @@
+"use client";
+
+/**
+ * usePersonalization — consumer hook for personalization state.
+ *
+ * Must be used within a <PersonalizationProvider>.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { personValues, updateField, isExporting, exportedBlobUrls } = usePersonalization();
+ *   return <input onChange={e => updateField("Name", e.target.value)} />;
+ * }
+ * ```
+ */
+
+import { usePersonalizationContext, type PersonalizationContextValue } from "./PersonalizationContext";
+
+export function usePersonalization(): PersonalizationContextValue {
+  const ctx = usePersonalizationContext();
+  if (!ctx) {
+    throw new Error(
+      "usePersonalization must be used within a <PersonalizationProvider>"
+    );
+  }
+  return ctx;
+}
+
+/** Optional version that returns null outside provider (for shared components) */
+export function usePersonalizationOptional(): PersonalizationContextValue | null {
+  return usePersonalizationContext();
+}