@zalify/storefront-kit 0.1.12 → 0.2.0

package/src/react/engine/CssVariables.tsx

@@ -7,9 +7,15 @@
  * Static token scales (spacing, type, radii) live in the app's
  * critical.css (synced from the theme).
  */
-import {useMemo} from 'react';
+import {useMemo, useSyncExternalStore} from 'react';
 import {colorSchemes, themeSettings} from './settings';
-import {getThemeStoreVersion} from './store';
+import {
+  getThemeStoreVersion,
+  subscribePreview,
+  getPreviewVersion,
+  getServerPreviewVersion,
+  hasThemePreview,
+} from './store';
 import {
   googleFontsHrefsFromSettings,
   parseFontHandle,
@@ -35,7 +41,9 @@ function buildCss(): string {
   const lines: string[] = [];
   lines.push(':root {');
   lines.push(`  --font-body--family: ${bodyFamily};`);
-  lines.push(`  --font-body--style: ${bodyGoogle ? 'normal' : bodyFont.style};`);
+  lines.push(
+    `  --font-body--style: ${bodyGoogle ? 'normal' : bodyFont.style};`,
+  );
   lines.push(`  --font-body--weight: ${bodyGoogle ? 400 : bodyFont.weight};`);
   lines.push(`  --font-heading--family: ${headingFamily};`);
   if (monoGoogle) {
@@ -52,15 +60,23 @@ function buildCss(): string {
   }
   lines.push(`  --page-width: ${s.max_page_width ?? '90rem'};`);
   lines.push(`  --page-margin: ${s.min_page_margin ?? 20}px;`);
-  lines.push(`  --style-border-radius-inputs: ${s.input_corner_radius ?? 0}px;`);
-  lines.push(`  --style-border-radius-buttons: ${s.button_corner_radius ?? 0}px;`);
+  lines.push(
+    `  --style-border-radius-inputs: ${s.input_corner_radius ?? 0}px;`,
+  );
+  lines.push(
+    `  --style-border-radius-buttons: ${s.button_corner_radius ?? 0}px;`,
+  );
   lines.push(`  --style-border-radius-cards: ${s.card_corner_radius ?? 0}px;`);
-  lines.push(`  --style-badge-background: ${s.card_badge_background ?? '#F9EDEF'};`);
+  lines.push(
+    `  --style-badge-background: ${s.card_badge_background ?? '#F9EDEF'};`,
+  );
   lines.push(`  --style-badge-text: ${s.card_badge_text ?? '#1A1A1A'};`);
   lines.push(
     `  --style-badge-sale-background: ${s.card_badge_sale_background ?? '#F26B8A'};`,
   );
-  lines.push(`  --style-badge-sale-text: ${s.card_badge_sale_text ?? '#FFFFFF'};`);
+  lines.push(
+    `  --style-badge-sale-text: ${s.card_badge_sale_text ?? '#FFFFFF'};`,
+  );
   lines.push(
     `  --style-badge-1-background: ${s.badge_style_1_background ?? '#1A1A1A'};`,
   );
@@ -137,6 +153,11 @@ export function CssVariables({
   nonce,
   fonts,
 }: {nonce?: string; fonts?: ResolvedGoogleFontCss | null} = {}) {
+  useSyncExternalStore(
+    subscribePreview,
+    getPreviewVersion,
+    getServerPreviewVersion,
+  );
   const themeVersion = getThemeStoreVersion();
   const {css, links} = useMemo(
     () => ({css: buildCss(), links: googleFontsHrefs()}),
@@ -147,7 +168,7 @@ export function CssVariables({
   // inlined and the latin woff2 files preloaded, so the font downloads
   // with the HTML and usually beats first paint — no async stylesheet,
   // no FOUT, no request to fonts.googleapis.com at all.
-  if (fonts) {
+  if (fonts && !hasThemePreview()) {
     return (
       <>
         <link
@@ -182,13 +203,16 @@ export function CssVariables({
       {links.map((href) => (
         <link
           key={href}
-          rel="preload"
+          rel={hasThemePreview() ? 'stylesheet' : 'preload'}
           as="style"
           href={href}
           data-zfy-font-css=""
         />
       ))}
-      <script nonce={nonce} dangerouslySetInnerHTML={{__html: FONT_CSS_LOADER}} />
+      <script
+        nonce={nonce}
+        dangerouslySetInnerHTML={{__html: FONT_CSS_LOADER}}
+      />
       <noscript>
         {links.map((href) => (
           <link key={href} rel="stylesheet" href={href} />

package/src/react/engine/images.tsx

@@ -18,11 +18,8 @@ export function settingImageUrl(value: unknown): string | null {
 }
 
 /** Append a width to a Shopify CDN URL (mirror of `| image_url: width`). */
-export function imageUrl(url: string, width?: number): string {
-  if (!width || !url.includes('cdn.shopify.com')) return url;
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}width=${width}`;
-}
+export {imageUrl} from '../../commerce/image-url';
+import {imageUrl} from '../../commerce/image-url';
 
 /** Srcset across the theme's standard width ladder. */
 export function imageSrcSet(

package/src/react/engine/render.tsx

@@ -15,7 +15,15 @@
  * emitted unconditionally so server and client markup stay identical.
  */
 import {formatThemePath, DATA_PATH_ATTR} from '../../schemas/index.ts';
-import {getSectionGroup, getTemplate, getThemeStore} from './store';
+import {
+  getSectionGroup,
+  getTemplate,
+  getThemeStore,
+  subscribePreview,
+  getPreviewVersion,
+  getServerPreviewVersion,
+} from './store';
+import {useSyncExternalStore} from 'react';
 import {SectionProvider, TemplateProvider} from './context';
 import type {BlockData, SectionData, TemplateData} from './types';
 
@@ -181,6 +189,11 @@ export function SectionGroup({
   name: string;
   sectionData?: Record<string, unknown>;
 }) {
+  useSyncExternalStore(
+    subscribePreview,
+    getPreviewVersion,
+    getServerPreviewVersion,
+  );
   const group = getSectionGroup(name);
   return (
     <TemplateProvider value={{name, kind: 'group', resources: {}, sectionData}}>

package/src/react/engine/store.ts

@@ -26,7 +26,10 @@ export interface ThemeSchema {
   /** sections/*-group.json keyed by file name ("header-group"…). */
   sectionGroups: Record<string, SectionGroupData>;
   /** config/settings_schema.json. */
-  settingsSchema: Array<{name: string; settings?: Array<Record<string, unknown>>}>;
+  settingsSchema: Array<{
+    name: string;
+    settings?: Array<Record<string, unknown>>;
+  }>;
   /** config/settings_data.json. */
   settingsData: {
     current: string | Record<string, unknown>;
@@ -57,6 +60,40 @@ interface ThemeStore extends InstallThemeOptions {}
 
 let store: ThemeStore | null = null;
 let version = 0;
+let preview: {owner: ThemeStore; value: ThemeStore} | null = null;
+let previewVersion = 0;
+const previewListeners = new Set<() => void>();
+
+export function subscribePreview(listener: () => void): () => void {
+  previewListeners.add(listener);
+  return () => {
+    previewListeners.delete(listener);
+  };
+}
+export function getPreviewVersion(): number {
+  return previewVersion;
+}
+export function getServerPreviewVersion(): number {
+  return 0;
+}
+export function hasThemePreview(): boolean {
+  return (
+    typeof window !== 'undefined' && preview !== null && preview.owner === store
+  );
+}
+
+/** Browser-only overlay; the installed schema and SSR state remain untouched. */
+export function setThemePreview(
+  owner: ThemeStore,
+  schema: ThemeSchema | null,
+): void {
+  if (typeof window === 'undefined' || owner !== store) return;
+  preview = schema
+    ? {owner, value: {...owner, schema, settingsOverride: undefined}}
+    : null;
+  previewVersion++;
+  for (const listener of previewListeners) listener();
+}
 
 export function installTheme(options: InstallThemeOptions): void {
   store = options;
@@ -67,17 +104,19 @@ export function installTheme(options: InstallThemeOptions): void {
 
 /** Monotonic install counter — lets derived caches detect re-installs. */
 export function getThemeStoreVersion(): number {
-  return version;
+  return version + (typeof window === 'undefined' ? 0 : previewVersion);
 }
 
 export function getThemeStore(): ThemeStore {
   if (!store) {
     throw new Error(
-      '[storefront-kit] installTheme() has not been called. Import your app\'s ' +
+      "[storefront-kit] installTheme() has not been called. Import your app's " +
         'theme-setup module (which calls installTheme) before rendering.',
     );
   }
-  return store;
+  return typeof window !== 'undefined' && preview?.owner === store
+    ? preview.value
+    : store;
 }
 
 /** Look up a page template ("index", "product", "customers/login"…). */

package/src/react/index.ts

@@ -77,3 +77,5 @@ export {
 // Built-in registries (spread into installTheme with app extras).
 // Server-only loaders live in '@zalify/storefront-kit/react/server'.
 export {builtinSections, builtinBlocks} from './registries';
+
+export {useEditorTemplate} from './useEditorTemplate';

package/src/react/sections/article.tsx

@@ -1,3 +1,4 @@
+import {StoreImage} from '../components/StoreImage';
 /**
  * Port of sections/article.liquid. CSS: app/styles/components/sections-article.css
  *
@@ -75,7 +76,7 @@ export default function ArticleSection({
         </header>
 
         {article.image?.url && (
-          <img
+          <StoreImage
             className="article__image"
             src={imageUrl(article.image.url, 1500)}
             srcSet={imageSrcSet(article.image.url)}

package/src/react/sections/custom-section.tsx

@@ -1,3 +1,4 @@
+import {StoreImage} from '../components/StoreImage';
 /**
  * Port of sections/custom-section.liquid — the canonical v3 section
  * pattern: color_scheme + section_spacing on the wrapper, optional
@@ -34,7 +35,7 @@ export default function CustomSection({
     >
       {backgroundImage ? (
         <div className="custom-section__background">
-          <img src={imageUrl(backgroundImage, 2000)} alt="" />
+          <StoreImage src={imageUrl(backgroundImage, 2000)} alt="" />
         </div>
       ) : null}
 

package/src/react/sections/image-with-text.tsx

@@ -1,3 +1,4 @@
+import {StoreImage} from '../components/StoreImage';
 /**
  * Port of sections/image-with-text.liquid — media column + block stack.
  * CSS: app/styles/components/sections-image-with-text.css
@@ -42,7 +43,7 @@ export default function ImageWithTextSection({
       >
         <div className="image-with-text__media">
           {image ? (
-            <img
+            <StoreImage
               className="image-with-text__image"
               src={imageUrl(image, 1500)}
               srcSet={imageSrcSet(image, [400, 700, 1000, 1500])}

package/src/react/sections/video-bubble.tsx

@@ -1,3 +1,4 @@
+import {StoreImage} from '../components/StoreImage';
 /**
  * Port of sections/video-bubble.liquid — floating video bubble: a small
  * muted preview loop pinned to a bottom corner that expands into the
@@ -107,7 +108,7 @@ export default function VideoBubbleSection({
               <source src={previewMp4.url} type={previewMp4.mime_type} />
             </video>
           ) : poster ? (
-            <img
+            <StoreImage
               className="video-bubble__media"
               src={imageUrl(poster, 400)}
               loading="lazy"

package/src/react/useEditorTemplate.ts

@@ -0,0 +1,136 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import type { TemplateData } from "../schemas/data";
+import type { ThemeEditorManifest } from "../schemas/manifest";
+import type { FrameBridgeController } from "../editor/frame";
+import type { PreviewContext } from "../schemas/bridge";
+import type { EditorDocuments } from "../editor/bootstrap";
+import { getThemeStore, setThemePreview } from "./engine/store";
+
+type Options = {
+  origins: readonly string[];
+  loadManifest: () => Promise<ThemeEditorManifest>;
+  /** Authoritative, repository-relative merchant data targets. */
+  paths: EditorDocuments;
+  /** Real route targets keyed by template name. */
+  previews: Record<string, PreviewContext>;
+};
+
+/** No editor code or schema is fetched outside an explicitly allowed preview. */
+export function useEditorTemplate(
+  name: string,
+  options: Options,
+): TemplateData | null {
+  const [draft, setDraft] = useState<{
+    name: string;
+    template: TemplateData;
+  } | null>(null);
+  const controller = useRef<FrameBridgeController | null>(null);
+  useEffect(() => {
+    setDraft(null);
+    if (
+      !options.origins.length ||
+      window.self === window.top ||
+      new URL(window.location.href).searchParams.get("zalify-editor") !== "1"
+    )
+      return;
+    let parentOrigin: string;
+    try {
+      parentOrigin = new URL(document.referrer).origin;
+    } catch {
+      return;
+    }
+    if (!options.origins.includes(parentOrigin)) return;
+    let disposed = false;
+    const owner = getThemeStore();
+    void Promise.all([
+      import("../editor/frame"),
+      options.loadManifest(),
+      import("../editor/bootstrap"),
+      import("../editor/draft"),
+    ])
+      .then(([bridge, manifest, bootstrapModule, draftModule]) => {
+        if (disposed) return;
+        const settings = owner.schema.settingsData;
+        const current =
+          typeof settings.current === "string"
+            ? (settings.presets?.[settings.current] ?? {})
+            : settings.current;
+        const schema = {
+          ...owner.schema,
+          settingsData: {
+            ...settings,
+            current: { ...current, ...owner.settingsOverride },
+          },
+        };
+        const previews = { ...options.previews };
+        // The currently rendered route is also a verified context, including locale.
+        const url = new URL(window.location.href);
+        url.searchParams.delete("zalify-editor");
+        const kind = name.split(".")[0];
+        const resourceType = (
+          [
+            "index",
+            "product",
+            "collection",
+            "page",
+            "blog",
+            "article",
+            "cart",
+            "search",
+            "list-collections",
+            "404",
+          ].includes(kind)
+            ? kind
+            : "page"
+        ) as PreviewContext["resourceType"];
+        previews[name] = {
+          ...previews[name],
+          id: name,
+          title: previews[name]?.title ?? name,
+          resourceType,
+          url: url.pathname + url.search,
+        };
+        const bootstrap = bootstrapModule.createEditorBootstrap({
+          schema,
+          manifest,
+          paths: options.paths,
+          previews,
+        });
+        const draft = draftModule.createEditorDraft(schema);
+        controller.current = bridge.mountFrameBridge({
+          editorOrigin: parentOrigin,
+          templateName: name,
+          hash: manifest.hash,
+          getManifest: () => manifest,
+          capabilities: [
+            "editor-bootstrap-v1",
+            "apply-template-v1",
+            "apply-groups-v1",
+            "apply-settings-v1",
+            "preview-navigation-v1",
+          ],
+          getBootstrap: () => bootstrap,
+          applyTemplate(payload) {
+            if (payload.templateName !== name) return false;
+            setThemePreview(owner, { ...schema, ...draft.apply(payload) });
+            setDraft({ name, template: payload.template });
+            return true;
+          },
+        });
+      })
+      .catch(() => {
+        /* The storefront remains usable if preview assets fail. */
+      });
+    return () => {
+      disposed = true;
+      controller.current?.unmount();
+      controller.current = null;
+      setThemePreview(owner, null);
+    };
+  }, [name, options]);
+  useEffect(() => {
+    controller.current?.reportRects();
+  }, [draft]);
+  return draft?.name === name ? draft.template : null;
+}

package/src/schemas/bridge.ts

@@ -185,6 +185,7 @@ export type FrameMessage =
         deltaX: number;
         deltaY: number;
         ctrlKey: boolean;
+        shiftKey?: boolean;
         clientX: number;
         clientY: number;
       }