@zalify/storefront-kit 0.2.0 → 0.3.0

package/dist/editor/frame.d.ts

@@ -6,11 +6,20 @@
  * 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.)
+ * Editor mode keeps the page interactive — buttons, drawers, variant
+ * pickers, forms all work, so any state can be previewed — while the
+ * bridge takes over two things a click must never do on its own:
+ *
+ * - Leave the storefront. Same-origin links and GET forms are turned
+ *   into `location.replace` navigations that keep the editor-mode
+ *   query param (so the next document mounts the bridge again) and
+ *   add no browser-history entries; off-site links, new-tab links,
+ *   modifier-clicks and off-site paths (checkout, account) are blocked.
+ * - Escape selection: every click still selects the enclosing block.
+ *
+ * Double/middle clicks and context menus stay suppressed. Each mount
+ * reports its URL as a `navigation`, which is how the editor follows
+ * in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -47,6 +56,25 @@ export interface FrameBridgeOptions {
 }
 /** True when this document should mount the editor bridge. */
 export declare function isEditorMode(win?: Window): boolean;
+export type NavigationDecision = {
+    kind: 'allow';
+    url: string;
+} | {
+    kind: 'block';
+    reason: 'off-origin' | 'new-tab' | 'modifier' | 'off-site' | 'download';
+};
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export declare function decideNavigation(href: string, base: string, flags: {
+    target?: string | null;
+    download?: boolean;
+    modifier?: boolean;
+}): NavigationDecision;
+/** The storefront path the editor should remember: no editor-mode param. */
+export declare function previewPathOf(href: string): string;
 export interface FrameBridgeController {
     unmount: () => void;
     /** Report that a persisted write round-tripped (HMR applied `hash`). */

package/dist/editor/frame.js

@@ -6,11 +6,20 @@
  * 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.)
+ * Editor mode keeps the page interactive — buttons, drawers, variant
+ * pickers, forms all work, so any state can be previewed — while the
+ * bridge takes over two things a click must never do on its own:
+ *
+ * - Leave the storefront. Same-origin links and GET forms are turned
+ *   into `location.replace` navigations that keep the editor-mode
+ *   query param (so the next document mounts the bridge again) and
+ *   add no browser-history entries; off-site links, new-tab links,
+ *   modifier-clicks and off-site paths (checkout, account) are blocked.
+ * - Escape selection: every click still selects the enclosing block.
+ *
+ * Double/middle clicks and context menus stay suppressed. Each mount
+ * reports its URL as a `navigation`, which is how the editor follows
+ * in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -49,10 +58,51 @@ function visibleRectOf(element) {
     return { x: left, y: top, width: right - left, height: bottom - top };
 }
 function pathNodeOf(target) {
-    if (!(target instanceof Element))
+    if (!isElement(target))
         return null;
     return target.closest(`[${DATA_PATH_ATTR}]`);
 }
+function isElement(target) {
+    return (typeof Element !== 'undefined' && target instanceof Element);
+}
+/** Storefront paths that hand off to Shopify-hosted pages; never previewable. */
+const OFF_SITE_PATHS = [/^\/checkout(?:s)?(?:\/|$)/, /^\/cart\/c\//, /^\/account(?:\/|$)/, /^\/admin(?:\/|$)/];
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export function decideNavigation(href, base, flags) {
+    if (flags.modifier)
+        return { kind: 'block', reason: 'modifier' };
+    if (flags.download)
+        return { kind: 'block', reason: 'download' };
+    if (flags.target && flags.target !== '_self')
+        return { kind: 'block', reason: 'new-tab' };
+    let url;
+    try {
+        url = new URL(href, base);
+    }
+    catch {
+        return { kind: 'block', reason: 'off-origin' };
+    }
+    if (url.origin !== new URL(base).origin)
+        return { kind: 'block', reason: 'off-origin' };
+    if (OFF_SITE_PATHS.some((pattern) => pattern.test(url.pathname))) {
+        return { kind: 'block', reason: 'off-site' };
+    }
+    url.searchParams.set(EDITOR_MODE_PARAM, '1');
+    return { kind: 'allow', url: url.toString() };
+}
+/** The storefront path the editor should remember: no editor-mode param. */
+export function previewPathOf(href) {
+    const url = new URL(href);
+    url.searchParams.delete(EDITOR_MODE_PARAM);
+    return url.pathname + url.search;
+}
+function anchorOf(target) {
+    return isElement(target) ? target.closest('a[href]') : null;
+}
 /**
  * Mount the frame bridge. Returns a controller with an `unmount`
  * function. Call only when `isEditorMode()` is true.
@@ -82,6 +132,15 @@ export function mountFrameBridge(options) {
             return;
         win.parent.postMessage({ z: BRIDGE_NAMESPACE, v: CONTRACT_VERSION, ...message }, target);
     };
+    // Every mount tells the editor where the preview is now: after an
+    // in-preview link or search the host would otherwise keep showing the
+    // page it originally asked for. Sent once the editor origin is pinned.
+    const reportNavigation = () => {
+        post({
+            type: 'navigation',
+            payload: { templateName: options.templateName, url: previewPathOf(win.location.href) },
+        });
+    };
     const setUnique = (attr, path) => {
         for (const node of doc.querySelectorAll(`[${attr}]`)) {
             node.removeAttribute(attr);
@@ -171,6 +230,7 @@ export function mountFrameBridge(options) {
                 queueMicrotask(() => {
                     lastHeight = 0;
                     measure();
+                    reportNavigation();
                 });
                 break;
             }
@@ -244,14 +304,41 @@ export function mountFrameBridge(options) {
     };
     const handleClick = (event) => {
         const node = pathNodeOf(event.target);
-        // Editor mode owns clicks: no navigation, no dialogs.
+        if (node) {
+            const path = node.getAttribute(DATA_PATH_ATTR);
+            setSelection(path);
+            post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
+        }
+        // The page keeps its interactivity; only navigation is policed.
+        const anchor = anchorOf(event.target);
+        if (!anchor)
+            return;
+        const decision = decideNavigation(anchor.getAttribute('href') ?? '', win.location.href, {
+            target: anchor.getAttribute('target'),
+            download: anchor.hasAttribute('download'),
+            modifier: event.metaKey || event.ctrlKey || event.shiftKey || event.altKey,
+        });
         event.preventDefault();
-        event.stopPropagation();
-        if (!node)
+        if (decision.kind === 'allow')
+            win.location.replace(decision.url);
+    };
+    const handleSubmit = (event) => {
+        const form = event.target;
+        if (!(form instanceof win.HTMLFormElement))
             return;
-        const path = node.getAttribute(DATA_PATH_ATTR);
-        setSelection(path);
-        post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
+        if ((form.getAttribute('method') ?? 'get').toLowerCase() !== 'get')
+            return;
+        // A GET form is a navigation: route it like a link so the editor-mode
+        // param survives and history stays clean. POST forms run as they are.
+        const action = new URL(form.getAttribute('action') || win.location.pathname, win.location.href);
+        for (const [key, value] of new FormData(form)) {
+            if (typeof value === 'string')
+                action.searchParams.set(key, value);
+        }
+        const decision = decideNavigation(action.toString(), win.location.href, {});
+        event.preventDefault();
+        if (decision.kind === 'allow')
+            win.location.replace(decision.url);
     };
     const handleWheel = (event) => {
         // Cross-origin iframe wheel events never reach the host canvas. Forward
@@ -274,12 +361,7 @@ export function mountFrameBridge(options) {
         event.preventDefault();
         event.stopPropagation();
     };
-    const SUPPRESSED_EVENTS = [
-        'dblclick',
-        'auxclick',
-        'submit',
-        'contextmenu',
-    ];
+    const SUPPRESSED_EVENTS = ['dblclick', 'auxclick', 'contextmenu'];
     const handleMouseMove = (() => {
         let lastPath = null;
         return (event) => {
@@ -315,6 +397,7 @@ export function mountFrameBridge(options) {
     win.addEventListener('resize', syncSelectionHighlight);
     win.addEventListener('scroll', syncSelectionHighlight, true);
     doc.addEventListener('click', handleClick, true);
+    doc.addEventListener('submit', handleSubmit, true);
     doc.addEventListener('mousemove', handleMouseMove, true);
     doc.addEventListener('wheel', handleWheel, { capture: true, passive: false });
     for (const type of SUPPRESSED_EVENTS) {
@@ -336,6 +419,7 @@ export function mountFrameBridge(options) {
             win.removeEventListener('resize', syncSelectionHighlight);
             win.removeEventListener('scroll', syncSelectionHighlight, true);
             doc.removeEventListener('click', handleClick, true);
+            doc.removeEventListener('submit', handleSubmit, true);
             doc.removeEventListener('mousemove', handleMouseMove, true);
             doc.removeEventListener('wheel', handleWheel, true);
             for (const type of SUPPRESSED_EVENTS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "The Zalify storefront SDK: framework-agnostic commerce logic (/commerce), the theme contract types and validators (/schemas), the canvas-editor bridge (/editor), and the React theme engine + shared components (/ui, /react/server). Consumed as TypeScript source inside the zalify-storefronts monorepo; published as compiled ESM + d.ts.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/editor/frame.ts

@@ -6,11 +6,20 @@
  * 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.)
+ * Editor mode keeps the page interactive — buttons, drawers, variant
+ * pickers, forms all work, so any state can be previewed — while the
+ * bridge takes over two things a click must never do on its own:
+ *
+ * - Leave the storefront. Same-origin links and GET forms are turned
+ *   into `location.replace` navigations that keep the editor-mode
+ *   query param (so the next document mounts the bridge again) and
+ *   add no browser-history entries; off-site links, new-tab links,
+ *   modifier-clicks and off-site paths (checkout, account) are blocked.
+ * - Escape selection: every click still selects the enclosing block.
+ *
+ * Double/middle clicks and context menus stay suppressed. Each mount
+ * reports its URL as a `navigation`, which is how the editor follows
+ * in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -102,10 +111,61 @@ function visibleRectOf(element: Element): DOMRectLike | null {
 }
 
 function pathNodeOf(target: EventTarget | null): HTMLElement | null {
-  if (!(target instanceof Element)) return null;
+  if (!isElement(target)) return null;
   return target.closest<HTMLElement>(`[${DATA_PATH_ATTR}]`);
 }
 
+function isElement(target: EventTarget | null): target is Element {
+  return (
+    typeof Element !== 'undefined' && target instanceof Element
+  );
+}
+
+/** Storefront paths that hand off to Shopify-hosted pages; never previewable. */
+const OFF_SITE_PATHS = [/^\/checkout(?:s)?(?:\/|$)/, /^\/cart\/c\//, /^\/account(?:\/|$)/, /^\/admin(?:\/|$)/];
+
+export type NavigationDecision =
+  | {kind: 'allow'; url: string}
+  | {kind: 'block'; reason: 'off-origin' | 'new-tab' | 'modifier' | 'off-site' | 'download'};
+
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export function decideNavigation(
+  href: string,
+  base: string,
+  flags: {target?: string | null; download?: boolean; modifier?: boolean},
+): NavigationDecision {
+  if (flags.modifier) return {kind: 'block', reason: 'modifier'};
+  if (flags.download) return {kind: 'block', reason: 'download'};
+  if (flags.target && flags.target !== '_self') return {kind: 'block', reason: 'new-tab'};
+  let url: URL;
+  try {
+    url = new URL(href, base);
+  } catch {
+    return {kind: 'block', reason: 'off-origin'};
+  }
+  if (url.origin !== new URL(base).origin) return {kind: 'block', reason: 'off-origin'};
+  if (OFF_SITE_PATHS.some((pattern) => pattern.test(url.pathname))) {
+    return {kind: 'block', reason: 'off-site'};
+  }
+  url.searchParams.set(EDITOR_MODE_PARAM, '1');
+  return {kind: 'allow', url: url.toString()};
+}
+
+/** The storefront path the editor should remember: no editor-mode param. */
+export function previewPathOf(href: string): string {
+  const url = new URL(href);
+  url.searchParams.delete(EDITOR_MODE_PARAM);
+  return url.pathname + url.search;
+}
+
+function anchorOf(target: EventTarget | null): HTMLAnchorElement | null {
+  return isElement(target) ? target.closest<HTMLAnchorElement>('a[href]') : null;
+}
+
 export interface FrameBridgeController {
   unmount: () => void;
   /** Report that a persisted write round-tripped (HMR applied `hash`). */
@@ -152,6 +212,16 @@ export function mountFrameBridge(
     );
   };
 
+  // Every mount tells the editor where the preview is now: after an
+  // in-preview link or search the host would otherwise keep showing the
+  // page it originally asked for. Sent once the editor origin is pinned.
+  const reportNavigation = (): void => {
+    post({
+      type: 'navigation',
+      payload: {templateName: options.templateName, url: previewPathOf(win.location.href)},
+    });
+  };
+
   const setUnique = (attr: string, path: string | null): void => {
     for (const node of doc.querySelectorAll(`[${attr}]`)) {
       node.removeAttribute(attr);
@@ -243,6 +313,7 @@ export function mountFrameBridge(
         queueMicrotask(() => {
           lastHeight = 0;
           measure();
+          reportNavigation();
         });
         break;
       }
@@ -316,13 +387,36 @@ export function mountFrameBridge(
 
   const handleClick = (event: MouseEvent): void => {
     const node = pathNodeOf(event.target);
-    // Editor mode owns clicks: no navigation, no dialogs.
+    if (node) {
+      const path = node.getAttribute(DATA_PATH_ATTR)!;
+      setSelection(path);
+      post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
+    }
+    // The page keeps its interactivity; only navigation is policed.
+    const anchor = anchorOf(event.target);
+    if (!anchor) return;
+    const decision = decideNavigation(anchor.getAttribute('href') ?? '', win.location.href, {
+      target: anchor.getAttribute('target'),
+      download: anchor.hasAttribute('download'),
+      modifier: event.metaKey || event.ctrlKey || event.shiftKey || event.altKey,
+    });
     event.preventDefault();
-    event.stopPropagation();
-    if (!node) return;
-    const path = node.getAttribute(DATA_PATH_ATTR)!;
-    setSelection(path);
-    post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
+    if (decision.kind === 'allow') win.location.replace(decision.url);
+  };
+
+  const handleSubmit = (event: Event): void => {
+    const form = event.target;
+    if (!(form instanceof win.HTMLFormElement)) return;
+    if ((form.getAttribute('method') ?? 'get').toLowerCase() !== 'get') return;
+    // A GET form is a navigation: route it like a link so the editor-mode
+    // param survives and history stays clean. POST forms run as they are.
+    const action = new URL(form.getAttribute('action') || win.location.pathname, win.location.href);
+    for (const [key, value] of new FormData(form)) {
+      if (typeof value === 'string') action.searchParams.set(key, value);
+    }
+    const decision = decideNavigation(action.toString(), win.location.href, {});
+    event.preventDefault();
+    if (decision.kind === 'allow') win.location.replace(decision.url);
   };
 
   const handleWheel = (event: WheelEvent): void => {
@@ -347,12 +441,7 @@ export function mountFrameBridge(
     event.preventDefault();
     event.stopPropagation();
   };
-  const SUPPRESSED_EVENTS = [
-    'dblclick',
-    'auxclick',
-    'submit',
-    'contextmenu',
-  ] as const;
+  const SUPPRESSED_EVENTS = ['dblclick', 'auxclick', 'contextmenu'] as const;
 
   const handleMouseMove = (() => {
     let lastPath: string | null = null;
@@ -390,6 +479,7 @@ export function mountFrameBridge(
   win.addEventListener('resize', syncSelectionHighlight);
   win.addEventListener('scroll', syncSelectionHighlight, true);
   doc.addEventListener('click', handleClick, true);
+  doc.addEventListener('submit', handleSubmit, true);
   doc.addEventListener('mousemove', handleMouseMove, true);
   doc.addEventListener('wheel', handleWheel, {capture: true, passive: false});
   for (const type of SUPPRESSED_EVENTS) {
@@ -413,6 +503,7 @@ export function mountFrameBridge(
       win.removeEventListener('resize', syncSelectionHighlight);
       win.removeEventListener('scroll', syncSelectionHighlight, true);
       doc.removeEventListener('click', handleClick, true);
+      doc.removeEventListener('submit', handleSubmit, true);
       doc.removeEventListener('mousemove', handleMouseMove, true);
       doc.removeEventListener('wheel', handleWheel, true);
       for (const type of SUPPRESSED_EVENTS) {