@zalify/storefront-kit 0.3.0 → 0.3.1

package/dist/editor/frame.d.ts

@@ -6,20 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * 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:
+ * Editor mode has two interaction modes, switched by the host:
  *
- * - 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.
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `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.
  *
- * 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.
+ * Every click selects in both modes. 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
@@ -75,6 +79,7 @@ export declare function decideNavigation(href: string, base: string, flags: {
 }): NavigationDecision;
 /** The storefront path the editor should remember: no editor-mode param. */
 export declare function previewPathOf(href: string): string;
+export declare function isFormControl(target: EventTarget | null): boolean;
 export interface FrameBridgeController {
     unmount: () => void;
     /** Report that a persisted write round-tripped (HMR applied `hash`). */

package/dist/editor/frame.js

@@ -6,20 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * 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:
+ * Editor mode has two interaction modes, switched by the host:
  *
- * - 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.
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `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.
  *
- * 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.
+ * Every click selects in both modes. 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
@@ -100,6 +104,25 @@ export function previewPathOf(href) {
     url.searchParams.delete(EDITOR_MODE_PARAM);
     return url.pathname + url.search;
 }
+/**
+ * Controls that keep their native behaviour in `select` mode: everything a
+ * form is made of, plus standalone inputs. Links and other buttons are the
+ * things a merchant reaches for to edit, so those stay selection-only.
+ */
+const FORM_CONTROL_SELECTOR = [
+    'input',
+    'textarea',
+    'select',
+    'option',
+    'label',
+    '[contenteditable=""]',
+    '[contenteditable="true"]',
+    'form button',
+    'form [role="button"]',
+].join(',');
+export function isFormControl(target) {
+    return isElement(target) && target.closest(FORM_CONTROL_SELECTOR) !== null;
+}
 function anchorOf(target) {
     return isElement(target) ? target.closest('a[href]') : null;
 }
@@ -111,6 +134,7 @@ export function mountFrameBridge(options) {
     const win = options.window ?? window;
     const doc = win.document;
     let editorOrigin = null;
+    let interaction = 'select';
     let lastHeight = 0;
     let selectedPath = null;
     const selectionHighlight = doc.createElement('div');
@@ -223,6 +247,7 @@ export function mountFrameBridge(options) {
                     editorOrigin = event.origin;
                 }
                 options.onDeviceChange?.(message.payload.device);
+                interaction = message.payload.interaction ?? 'select';
                 setSelection(message.payload.selectedPath);
                 // The first measurement can run before bridge:init arrives. It is
                 // intentionally not posted until the editor origin is pinned, so
@@ -280,6 +305,9 @@ export function mountFrameBridge(options) {
             case 'device:set':
                 options.onDeviceChange?.(message.payload.device);
                 break;
+            case 'interaction:set':
+                interaction = message.payload.mode;
+                break;
             case 'manifest:request': {
                 const manifest = await options.getManifest();
                 post({ type: 'manifest:response', payload: { manifest } });
@@ -309,7 +337,16 @@ export function mountFrameBridge(options) {
             setSelection(path);
             post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
         }
-        // The page keeps its interactivity; only navigation is policed.
+        if (interaction === 'select') {
+            // Selection only: nothing fires except form controls.
+            if (!isFormControl(event.target)) {
+                event.preventDefault();
+                event.stopPropagation();
+            }
+            return;
+        }
+        // Interact mode: the page keeps its interactivity; only navigation is
+        // policed.
         const anchor = anchorOf(event.target);
         if (!anchor)
             return;

package/dist/schemas/bridge.d.ts

@@ -16,6 +16,12 @@ export declare const DATA_PATH_ATTR = "data-z-path";
 /** DOM attribute the bridge sets on the selected node. */
 export declare const DATA_SELECTED_ATTR = "data-z-selected";
 export type Device = 'desktop' | 'mobile';
+/**
+ * How clicks in the preview behave. `select` (default): a click selects the
+ * block; form controls still work but links and buttons do not fire.
+ * `interact`: the storefront is fully live and the editor follows navigation.
+ */
+export type InteractionMode = 'select' | 'interact';
 export type EditorCapability = 'editor-bootstrap-v1' | 'apply-template-v1' | 'apply-groups-v1' | 'apply-settings-v1' | 'preview-navigation-v1';
 export type PreviewResourceType = 'index' | 'product' | 'collection' | 'page' | 'blog' | 'article' | 'cart' | 'search' | 'list-collections' | '404';
 export interface PreviewContext {
@@ -79,6 +85,8 @@ export type HostMessage = BridgeEnvelope<'bridge:init', {
     editorOrigin: string;
     device: Device;
     selectedPath: string | null;
+    /** Omitted by older hosts: behaves as `select`. */
+    interaction?: InteractionMode;
 }> | BridgeEnvelope<'block:select', {
     path: string | null;
 }> | BridgeEnvelope<'block:hover', {
@@ -92,6 +100,8 @@ export type HostMessage = BridgeEnvelope<'bridge:init', {
     settingsData?: SettingsData;
 }> | BridgeEnvelope<'device:set', {
     device: Device;
+}> | BridgeEnvelope<'interaction:set', {
+    mode: InteractionMode;
 }> | BridgeEnvelope<'manifest:request', Record<string, never>> | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;
 export type FrameMessage = BridgeEnvelope<'bridge:ready', {
     contractVersion: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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,20 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * 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:
+ * Editor mode has two interaction modes, switched by the host:
  *
- * - 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.
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `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.
  *
- * 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.
+ * Every click selects in both modes. 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
@@ -37,6 +41,7 @@ import {
   type DOMRectLike,
   type EditorBootstrap,
   type EditorCapability,
+  type InteractionMode,
   type FrameMessage,
   type HostMessage,
   type SectionGroupData,
@@ -162,6 +167,27 @@ export function previewPathOf(href: string): string {
   return url.pathname + url.search;
 }
 
+/**
+ * Controls that keep their native behaviour in `select` mode: everything a
+ * form is made of, plus standalone inputs. Links and other buttons are the
+ * things a merchant reaches for to edit, so those stay selection-only.
+ */
+const FORM_CONTROL_SELECTOR = [
+  'input',
+  'textarea',
+  'select',
+  'option',
+  'label',
+  '[contenteditable=""]',
+  '[contenteditable="true"]',
+  'form button',
+  'form [role="button"]',
+].join(',');
+
+export function isFormControl(target: EventTarget | null): boolean {
+  return isElement(target) && target.closest(FORM_CONTROL_SELECTOR) !== null;
+}
+
 function anchorOf(target: EventTarget | null): HTMLAnchorElement | null {
   return isElement(target) ? target.closest<HTMLAnchorElement>('a[href]') : null;
 }
@@ -186,6 +212,7 @@ export function mountFrameBridge(
   const win = options.window ?? window;
   const doc = win.document;
   let editorOrigin: string | null = null;
+  let interaction: InteractionMode = 'select';
   let lastHeight = 0;
   let selectedPath: string | null = null;
 
@@ -306,6 +333,7 @@ export function mountFrameBridge(
           editorOrigin = event.origin;
         }
         options.onDeviceChange?.(message.payload.device);
+        interaction = message.payload.interaction ?? 'select';
         setSelection(message.payload.selectedPath);
         // The first measurement can run before bridge:init arrives. It is
         // intentionally not posted until the editor origin is pinned, so
@@ -362,6 +390,9 @@ export function mountFrameBridge(
       case 'device:set':
         options.onDeviceChange?.(message.payload.device);
         break;
+      case 'interaction:set':
+        interaction = message.payload.mode;
+        break;
       case 'manifest:request': {
         const manifest = await options.getManifest();
         post({type: 'manifest:response', payload: {manifest}});
@@ -392,7 +423,16 @@ export function mountFrameBridge(
       setSelection(path);
       post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
     }
-    // The page keeps its interactivity; only navigation is policed.
+    if (interaction === 'select') {
+      // Selection only: nothing fires except form controls.
+      if (!isFormControl(event.target)) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      return;
+    }
+    // Interact mode: 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, {

package/src/schemas/bridge.ts

@@ -25,6 +25,13 @@ export const DATA_SELECTED_ATTR = 'data-z-selected';
 
 export type Device = 'desktop' | 'mobile';
 
+/**
+ * How clicks in the preview behave. `select` (default): a click selects the
+ * block; form controls still work but links and buttons do not fire.
+ * `interact`: the storefront is fully live and the editor follows navigation.
+ */
+export type InteractionMode = 'select' | 'interact';
+
 export type EditorCapability =
   | 'editor-bootstrap-v1'
   | 'apply-template-v1'
@@ -139,6 +146,8 @@ export type HostMessage =
         editorOrigin: string;
         device: Device;
         selectedPath: string | null;
+        /** Omitted by older hosts: behaves as `select`. */
+        interaction?: InteractionMode;
       }
     >
   | BridgeEnvelope<'block:select', {path: string | null}>
@@ -154,6 +163,7 @@ export type HostMessage =
       }
     >
   | BridgeEnvelope<'device:set', {device: Device}>
+  | BridgeEnvelope<'interaction:set', {mode: InteractionMode}>
   | BridgeEnvelope<'manifest:request', Record<string, never>>
   | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;