@zalify/storefront-kit 0.1.0

package/src/commerce/product.ts

@@ -0,0 +1,177 @@
+/**
+ * Canonical product data model (Storefront API camelCase shape) and the
+ * pure helpers the React storefronts share. The Liquid theme does this
+ * work in Liquid itself — these mirror those template rules 1:1, so a
+ * behavior fix lands here and every React target inherits it.
+ */
+import type {Money, UnitPriceMeasurement} from './money';
+
+export interface CardImage {
+  id?: string | null;
+  url: string;
+  altText?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface CardVariant {
+  id: string;
+  availableForSale?: boolean;
+  image?: CardImage | null;
+  price?: Money;
+  compareAtPrice?: Money | null;
+  unitPrice?: Money | null;
+  unitPriceMeasurement?: UnitPriceMeasurement | null;
+  selectedOptions?: Array<{name: string; value: string}>;
+}
+
+export interface CardSwatch {
+  color?: string | null;
+  image?: {previewImage?: {url?: string | null} | null} | null;
+}
+
+export interface CardOptionValue {
+  name: string;
+  swatch?: CardSwatch | null;
+  firstSelectableVariant?: CardVariant | null;
+}
+
+/** `metafield(...) { value }` node — null when the metafield is unset. */
+export interface CardMetafield {
+  value?: string | null;
+}
+
+export interface CardProduct {
+  id: string;
+  handle: string;
+  title: string;
+  vendor?: string;
+  tags?: string[];
+  availableForSale?: boolean;
+  featuredImage?: CardImage | null;
+  images?: {nodes: CardImage[]};
+  priceRange: {minVariantPrice: Money; maxVariantPrice: Money};
+  compareAtPriceRange?: {minVariantPrice: Money; maxVariantPrice: Money};
+  options?: Array<{name: string; optionValues: CardOptionValue[]}>;
+  selectedOrFirstAvailableVariant?: CardVariant | null;
+  /** Full variant list — mirror of Liquid's `product.variants`. */
+  variants?: {nodes: CardVariant[]};
+  /** reviews.rating / reviews.rating_count standardized metafields. */
+  rating?: CardMetafield | null;
+  ratingCount?: CardMetafield | null;
+  [key: string]: unknown;
+}
+
+export type CardOption = NonNullable<CardProduct['options']>[number];
+
+/** Product URL the way every card/quick-add link builds it. */
+export function productUrl(product: Pick<CardProduct, 'handle'>): string {
+  return `/products/${product.handle}`;
+}
+
+/** Numeric tail of a Storefront GID (mirror of Liquid's numeric ids). */
+export function numericId(gid: string): string {
+  return gid.split('/').pop()?.split('?')[0] ?? gid;
+}
+
+/**
+ * Mirror of Liquid's product.has_only_default_variant: a single
+ * variant whose only option value is Shopify's "Default Title".
+ */
+export function hasOnlyDefaultVariant(product: CardProduct): boolean {
+  const options = product.options ?? [];
+  const first = options[0];
+  if (!first) return true;
+  return (
+    options.length === 1 &&
+    first.optionValues.length === 1 &&
+    first.optionValues[0]?.name === 'Default Title'
+  );
+}
+
+/** The option value a variant carries for a given option name. */
+export function optionValueOf(
+  variant: CardVariant,
+  optionName: string,
+): string | undefined {
+  return variant.selectedOptions?.find((o) => o.name === optionName)?.value;
+}
+
+/**
+ * Which option a product card's variant picker should display — mirror
+ * of the picker_option resolution in snippets/product-card.liquid.
+ *
+ * @param colorNames localized names that mark an option as a color
+ *   (the theme's `products.color_option_match` locale value, split).
+ */
+export function resolvePickerOption(
+  product: CardProduct,
+  swatchStyleSetting: string,
+  colorNames: string[],
+): CardOption | null {
+  const options = product.options ?? [];
+  const variants = product.variants?.nodes ?? [];
+
+  if (swatchStyleSetting === 'swatch') {
+    // First option carrying swatch data, or named like a color
+    for (const option of options) {
+      // A single value is nothing to pick — matches the PDP picker
+      if (option.optionValues.length < 2) continue;
+      if (option.optionValues[0]?.swatch) return option;
+      const optionNameDown = option.name.toLowerCase();
+      if (colorNames.some((name) => optionNameDown.includes(name))) {
+        return option;
+      }
+    }
+    return null;
+  }
+
+  if (swatchStyleSetting === 'variant_image') {
+    // First option whose first two values map to distinct variant
+    // images (same rule as the PDP image picker, probed cheaply)
+    for (const option of options) {
+      const probeIds: string[] = [];
+      for (const value of option.optionValues.slice(0, 2)) {
+        for (const variant of variants) {
+          if (
+            optionValueOf(variant, option.name) === value.name &&
+            variant.image
+          ) {
+            probeIds.push(variant.image.id ?? variant.image.url);
+            break;
+          }
+        }
+      }
+      if (new Set(probeIds).size > 1) return option;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Prefer the first variant of this value that has an image — mirror of
+ * the target_variant loop in the Liquid card.
+ */
+export function targetVariantFor(
+  product: CardProduct,
+  option: CardOption,
+  valueName: string,
+): CardVariant | null {
+  const variants = product.variants?.nodes ?? [];
+  let target: CardVariant | null = null;
+  for (const variant of variants) {
+    if (optionValueOf(variant, option.name) === valueName) {
+      if (!target) target = variant;
+      if (variant.image) return variant;
+    }
+  }
+  if (target) return target;
+  // Fragment without the variants list: fall back to the option
+  // value's own first selectable variant.
+  return (
+    option.optionValues.find((value) => value.name === valueName)
+      ?.firstSelectableVariant ?? null
+  );
+}

package/src/editor/frame.ts

@@ -0,0 +1,305 @@
+/**
+ * Frame side of the canvas-editor bridge: runs inside the theme
+ * preview when it is iframed by the Zalify editor. Owns everything
+ * that needs same-document DOM access — hit-testing clicks/hovers to
+ * `data-z-path` nodes, selection highlight, rect reporting, height
+ * sync — and hands app-specific concerns (template hot-apply, device
+ * emulation) to callbacks.
+ *
+ * Editor mode neutralizes the page's own interactivity: clicks,
+ * double/middle clicks, form submits, and context menus are captured
+ * at the document root and suppressed, so selecting a node never
+ * navigates a link, opens a drawer, or submits a form — a click is
+ * only ever a selection. (Hover stays live for highlight tracking.)
+ *
+ * Security: the first `bridge:init` pins the editor origin; every
+ * later message must match it, and nothing but `bridge:ready` is ever
+ * posted before the pin.
+ */
+import {
+  BRIDGE_NAMESPACE,
+  CONTRACT_VERSION,
+  DATA_PATH_ATTR,
+  DATA_SELECTED_ATTR,
+  EDITOR_MODE_PARAM,
+  isBridgeMessage,
+  isCompatibleVersion,
+  type Device,
+  type DOMRectLike,
+  type FrameMessage,
+  type HostMessage,
+  type SectionGroupData,
+  type SettingsBag,
+  type TemplateData,
+  type ThemeEditorManifest,
+} from '../schemas/index.ts';
+
+export const DATA_HOVERED_ATTR = 'data-z-hovered';
+
+export interface FrameBridgeOptions {
+  /** Template currently rendered ("index", "product", …). */
+  templateName: string;
+  /** Content hash of the theme data the frame booted with. */
+  hash: string;
+  /** Serve the editor manifest (static import or dynamic build). */
+  getManifest: () =>
+    | ThemeEditorManifest
+    | Promise<ThemeEditorManifest>;
+  /**
+   * Hot-apply an updated template in memory (optimistic edit). Return
+   * false (or throw) if the app cannot apply without a reload.
+   */
+  applyTemplate?: (payload: {
+    templateName: string;
+    template: TemplateData;
+    groups?: Record<string, SectionGroupData>;
+    settingsData?: SettingsBag;
+  }) => boolean | Promise<boolean>;
+  onDeviceChange?: (device: Device) => void;
+  /** Overrides for tests / non-browser hosts. */
+  window?: Window & typeof globalThis;
+}
+
+/** True when this document should mount the editor bridge. */
+export function isEditorMode(win: Window = window): boolean {
+  if (win.self === win.top) return false;
+  try {
+    return (
+      new URL(win.location.href).searchParams.get(EDITOR_MODE_PARAM) === '1'
+    );
+  } catch {
+    return false;
+  }
+}
+
+function rectOf(element: Element): DOMRectLike {
+  const rect = element.getBoundingClientRect();
+  return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
+}
+
+function pathNodeOf(target: EventTarget | null): HTMLElement | null {
+  if (!(target instanceof Element)) return null;
+  return target.closest<HTMLElement>(`[${DATA_PATH_ATTR}]`);
+}
+
+export interface FrameBridgeController {
+  unmount: () => void;
+  /** Report that a persisted write round-tripped (HMR applied `hash`). */
+  notifySynced: (hash: string) => void;
+  /** Report an in-preview navigation to another template. */
+  notifyNavigation: (templateName: string, url: string) => void;
+  /** Re-send every block's rect (call after app-driven re-renders). */
+  reportRects: () => void;
+}
+
+/**
+ * Mount the frame bridge. Returns a controller with an `unmount`
+ * function. Call only when `isEditorMode()` is true.
+ */
+export function mountFrameBridge(
+  options: FrameBridgeOptions,
+): FrameBridgeController {
+  const win = options.window ?? window;
+  const doc = win.document;
+  let editorOrigin: string | null = null;
+  let lastHeight = 0;
+
+  const post = (message: Omit<FrameMessage, 'z' | 'v'>): void => {
+    // bridge:ready is the only pre-pin message; everything else waits.
+    const target = editorOrigin ?? '*';
+    if (!editorOrigin && message.type !== 'bridge:ready') return;
+    win.parent.postMessage(
+      {z: BRIDGE_NAMESPACE, v: CONTRACT_VERSION, ...message},
+      target,
+    );
+  };
+
+  const setUnique = (attr: string, path: string | null): void => {
+    for (const node of doc.querySelectorAll(`[${attr}]`)) {
+      node.removeAttribute(attr);
+    }
+    if (path === null) return;
+    const selector = `[${DATA_PATH_ATTR}="${CSS.escape(path)}"]`;
+    doc.querySelector(selector)?.setAttribute(attr, '1');
+  };
+
+  const reportRects = (): void => {
+    const rects = [...doc.querySelectorAll(`[${DATA_PATH_ATTR}]`)].map(
+      (node) => ({
+        path: node.getAttribute(DATA_PATH_ATTR)!,
+        rect: rectOf(node),
+      }),
+    );
+    post({type: 'block:rects', payload: {rects}});
+  };
+
+  const handleMessage = async (event: MessageEvent): Promise<void> => {
+    const data: unknown = event.data;
+    if (!isBridgeMessage(data)) return;
+    if (editorOrigin && event.origin !== editorOrigin) return;
+    if (!isCompatibleVersion(CONTRACT_VERSION, data.v)) {
+      post({
+        type: 'bridge:error',
+        payload: {
+          code: 'version-mismatch',
+          message: `frame speaks ${CONTRACT_VERSION}, host sent ${data.v}`,
+        },
+      });
+      return;
+    }
+    const message = data as HostMessage;
+    switch (message.type) {
+      case 'bridge:init': {
+        if (!editorOrigin) {
+          if (event.origin !== message.payload.editorOrigin) return;
+          editorOrigin = event.origin;
+        }
+        options.onDeviceChange?.(message.payload.device);
+        setUnique(DATA_SELECTED_ATTR, message.payload.selectedPath);
+        break;
+      }
+      case 'block:select':
+        setUnique(DATA_SELECTED_ATTR, message.payload.path);
+        // Rects let the host scroll its full-height canvas to the
+        // selection (the frame itself has no scrollbar in that mode).
+        reportRects();
+        break;
+      case 'block:hover':
+        setUnique(DATA_HOVERED_ATTR, message.payload.path);
+        break;
+      case 'block:scroll-to': {
+        const selector = `[${DATA_PATH_ATTR}="${CSS.escape(message.payload.path)}"]`;
+        doc
+          .querySelector(selector)
+          ?.scrollIntoView({behavior: 'smooth', block: 'center'});
+        break;
+      }
+      case 'template:apply': {
+        try {
+          const applied =
+            (await options.applyTemplate?.(message.payload)) ?? false;
+          if (!applied) {
+            post({
+              type: 'bridge:error',
+              payload: {
+                code: 'apply-unsupported',
+                message: 'frame cannot hot-apply templates; wait for the file write',
+              },
+            });
+          } else {
+            reportRects();
+          }
+        } catch (error) {
+          post({
+            type: 'bridge:error',
+            payload: {
+              code: 'apply-failed',
+              message: error instanceof Error ? error.message : String(error),
+            },
+          });
+        }
+        break;
+      }
+      case 'device:set':
+        options.onDeviceChange?.(message.payload.device);
+        break;
+      case 'manifest:request': {
+        const manifest = await options.getManifest();
+        post({type: 'manifest:response', payload: {manifest}});
+        break;
+      }
+    }
+  };
+
+  const handleClick = (event: MouseEvent): void => {
+    const node = pathNodeOf(event.target);
+    // Editor mode owns clicks: no navigation, no dialogs.
+    event.preventDefault();
+    event.stopPropagation();
+    if (!node) return;
+    const path = node.getAttribute(DATA_PATH_ATTR)!;
+    setUnique(DATA_SELECTED_ATTR, path);
+    post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
+  };
+
+  /** Suppress the page's own interactivity (capture phase, doc root). */
+  const suppress = (event: Event): void => {
+    event.preventDefault();
+    event.stopPropagation();
+  };
+  const SUPPRESSED_EVENTS = [
+    'dblclick',
+    'auxclick',
+    'submit',
+    'contextmenu',
+  ] as const;
+
+  const handleMouseMove = (() => {
+    let lastPath: string | null = null;
+    return (event: MouseEvent): void => {
+      const node = pathNodeOf(event.target);
+      const path = node?.getAttribute(DATA_PATH_ATTR) ?? null;
+      if (path === lastPath) return;
+      lastPath = path;
+      setUnique(DATA_HOVERED_ATTR, path);
+      post({
+        type: 'block:hovered',
+        payload: {path, rect: node ? rectOf(node) : undefined},
+      });
+    };
+  })();
+
+  const measure = (): void => {
+    // documentElement.scrollHeight never drops below the viewport, so a
+    // full-height host iframe would ratchet upward forever; the body's
+    // border box tracks actual content in both directions.
+    const height = Math.ceil(
+      doc.body?.getBoundingClientRect().height ??
+        doc.documentElement.scrollHeight,
+    );
+    if (height === lastHeight || height <= 0) return;
+    lastHeight = height;
+    post({type: 'height:changed', payload: {height}});
+  };
+  const resizeObserver = new win.ResizeObserver(measure);
+  resizeObserver.observe(doc.documentElement);
+  if (doc.body) resizeObserver.observe(doc.body);
+
+  win.addEventListener('message', handleMessage);
+  doc.addEventListener('click', handleClick, true);
+  doc.addEventListener('mousemove', handleMouseMove, true);
+  for (const type of SUPPRESSED_EVENTS) {
+    doc.addEventListener(type, suppress, true);
+  }
+
+  post({
+    type: 'bridge:ready',
+    payload: {
+      contractVersion: CONTRACT_VERSION,
+      templateName: options.templateName,
+      hash: options.hash,
+    },
+  });
+  measure();
+
+  return {
+    unmount: () => {
+      win.removeEventListener('message', handleMessage);
+      doc.removeEventListener('click', handleClick, true);
+      doc.removeEventListener('mousemove', handleMouseMove, true);
+      for (const type of SUPPRESSED_EVENTS) {
+        doc.removeEventListener(type, suppress, true);
+      }
+      resizeObserver.disconnect();
+      setUnique(DATA_SELECTED_ATTR, null);
+      setUnique(DATA_HOVERED_ATTR, null);
+    },
+    notifySynced: (hash) => {
+      post({type: 'template:synced', payload: {hash}});
+    },
+    notifyNavigation: (templateName, url) => {
+      post({type: 'navigation', payload: {templateName, url}});
+    },
+    reportRects,
+  };
+}

package/src/editor/host.ts

@@ -0,0 +1,101 @@
+/**
+ * Host side of the canvas-editor bridge: drives a theme preview iframe
+ * from the Zalify editor. Owns the handshake (pin the frame origin,
+ * answer `bridge:ready` with `bridge:init`), re-handshakes transparently
+ * when the iframe reloads (sandbox HMR hard-refresh, crash recovery),
+ * and exposes typed send/subscribe surfaces.
+ */
+import {
+  BRIDGE_NAMESPACE,
+  CONTRACT_VERSION,
+  EDITOR_MODE_PARAM,
+  isBridgeMessage,
+  isCompatibleVersion,
+  type Device,
+  type FrameMessage,
+  type HostMessage,
+} from '../schemas/index.ts';
+
+export interface HostBridgeOptions {
+  iframe: HTMLIFrameElement;
+  /** Origin the preview is served from (the sandbox preview URL). */
+  frameOrigin: string;
+  device?: Device;
+  /** Currently selected path, replayed on every (re)handshake. */
+  getSelectedPath?: () => string | null;
+  onMessage?: (message: FrameMessage) => void;
+  /** Called when the frame speaks an incompatible contract version. */
+  onIncompatible?: (frameVersion: string) => void;
+  /** Overrides for tests / non-browser hosts. */
+  window?: Window;
+}
+
+export interface HostBridge {
+  /** Send a message; silently dropped until the frame is ready. */
+  send: (message: Omit<HostMessage, 'z' | 'v'>) => void;
+  /** True after the current frame document completed the handshake. */
+  isReady: () => boolean;
+  destroy: () => void;
+}
+
+/** Append the editor-mode marker to a preview URL. */
+export function editorPreviewUrl(previewUrl: string): string {
+  const url = new URL(previewUrl);
+  url.searchParams.set(EDITOR_MODE_PARAM, '1');
+  return url.toString();
+}
+
+export function createHostBridge(options: HostBridgeOptions): HostBridge {
+  const win = options.window ?? window;
+  let ready = false;
+  let destroyed = false;
+
+  const post = (message: Omit<HostMessage, 'z' | 'v'>): void => {
+    if (destroyed) return;
+    options.iframe.contentWindow?.postMessage(
+      {z: BRIDGE_NAMESPACE, v: CONTRACT_VERSION, ...message},
+      options.frameOrigin,
+    );
+  };
+
+  const handleMessage = (event: MessageEvent): void => {
+    if (destroyed) return;
+    if (event.origin !== options.frameOrigin) return;
+    if (event.source !== options.iframe.contentWindow) return;
+    const data: unknown = event.data;
+    if (!isBridgeMessage(data)) return;
+    if (!isCompatibleVersion(CONTRACT_VERSION, data.v)) {
+      ready = false;
+      options.onIncompatible?.(data.v);
+      return;
+    }
+    const message = data as FrameMessage;
+    if (message.type === 'bridge:ready') {
+      // First load and every iframe reload land here: (re)init.
+      ready = true;
+      post({
+        type: 'bridge:init',
+        payload: {
+          editorOrigin: win.location.origin,
+          device: options.device ?? 'desktop',
+          selectedPath: options.getSelectedPath?.() ?? null,
+        },
+      });
+    }
+    options.onMessage?.(message);
+  };
+
+  win.addEventListener('message', handleMessage);
+
+  return {
+    send: (message) => {
+      if (ready) post(message);
+    },
+    isReady: () => ready,
+    destroy: () => {
+      destroyed = true;
+      ready = false;
+      win.removeEventListener('message', handleMessage);
+    },
+  };
+}

package/src/editor/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @zalify/storefront-kit/editor — both halves of the canvas-editor
+ * bridge. Protocol types come from @zalify/storefront-kit/schemas.
+ *
+ *   frame.ts — mounts inside the theme preview (sandbox side)
+ *   host.ts  — drives the preview iframe (editor side)
+ */
+export * from './frame.ts';
+export * from './host.ts';

package/src/react/adapter.tsx

@@ -0,0 +1,83 @@
+/**
+ * The framework seam. ui-react components never import a router or
+ * commerce SDK — the host app injects these primitives once:
+ *
+ *   <AdapterProvider adapter={hydrogenAdapter}>…</AdapterProvider>
+ *
+ * Keep this surface deliberately small: only what shared components
+ * actually need. Deeply framework-coupled features (cart page, variant
+ * system, predictive search) live in each app, not behind this seam.
+ */
+import {createContext, useContext} from 'react';
+import type {ComponentType, ReactNode} from 'react';
+
+/** Loose Link props — hosts map them onto their router's Link. */
+export interface AdapterLinkProps {
+  to: string;
+  className?: string;
+  children?: ReactNode;
+  /** Hint to prefetch on intent where the router supports it. */
+  prefetch?: boolean;
+  replace?: boolean;
+  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+  'aria-label'?: string;
+  [key: string]: unknown;
+}
+
+export interface CartLineInput {
+  merchandiseId: string;
+  quantity: number;
+}
+
+export interface CartAddFormProps {
+  lines: CartLineInput[];
+  /** Render prop receives the submission state for button disabling. */
+  children: (state: {submitting: boolean}) => ReactNode;
+}
+
+export interface ThemeAdapter {
+  /** Client-side navigation link. */
+  Link: ComponentType<AdapterLinkProps>;
+  /** Hook returning an imperative navigate(url, opts) function. */
+  useNavigate: () => (
+    url: string,
+    opts?: {replace?: boolean; preventScrollReset?: boolean},
+  ) => void;
+  /** Hook returning the current URL's search params (read-only). */
+  useSearchParams: () => URLSearchParams;
+  /** Hook returning the current pathname. */
+  usePathname: () => string;
+  /**
+   * A form that adds lines to the cart on submit. Hosts wire it to
+   * their cart mutation (Hydrogen CartForm, Next server action…) and
+   * are responsible for emitting commerce-core's 'cart:updated' /
+   * 'cart:error' events when the mutation settles.
+   */
+  CartAddForm: ComponentType<CartAddFormProps>;
+}
+
+const AdapterContext = createContext<ThemeAdapter | null>(null);
+
+export function AdapterProvider({
+  adapter,
+  children,
+}: {
+  adapter: ThemeAdapter;
+  children: ReactNode;
+}) {
+  return (
+    <AdapterContext.Provider value={adapter}>
+      {children}
+    </AdapterContext.Provider>
+  );
+}
+
+export function useAdapter(): ThemeAdapter {
+  const adapter = useContext(AdapterContext);
+  if (!adapter) {
+    throw new Error(
+      '[storefront-kit] No ThemeAdapter provided. Wrap the app in <AdapterProvider adapter={…}>.',
+    );
+  }
+  return adapter;
+}