@shoppexio/builder-runtime 0.1.0

package/dist/react.js

@@ -0,0 +1,408 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { BuilderSettingsSchema, PreviewMessageSchema, createEmptyBuilderSettings, migrateLegacyBuilderSettings, } from '@shoppex/builder-contracts';
+import { createElement, createContext, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { getBlockSettingValue, getBuilderContentList, getBuilderContentRecord, getBuilderContentString, getBuilderContentValue, } from './content.js';
+import { createBuilderCss } from './css-vars.js';
+import { getPageBlocks, getPageLayout, getVisiblePageBlocks } from './layout.js';
+import { resolveStyleSlotValue } from './style-slots.js';
+const BUILDER_SETTINGS_WINDOW_KEY = '__SHOPPEX_BUILDER_SETTINGS__';
+const BUILDER_STATE_EVENT_NAME = 'shoppex:builder-state';
+const BUILDER_BLOCK_SELECTOR = '[data-builder-block]';
+const BUILDER_CONTENT_SELECTOR = '[data-builder-content]';
+const BUILDER_SELECTED_SELECTOR = '[data-builder-selected="true"]';
+const BuilderRuntimeContext = createContext(null);
+const BuilderBlockContext = createContext(null);
+export function BuilderRuntimeProvider({ settings, children }) {
+    const value = useMemo(() => ({ settings }), [settings]);
+    return _jsx(BuilderRuntimeContext.Provider, { value: value, children: children });
+}
+export function BuilderBlockProvider({ block, children }) {
+    return _jsx(BuilderBlockContext.Provider, { value: block, children: children });
+}
+export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
+    const [settings, setSettings] = useState(() => parseInitialBuilderSettings(initialSettings));
+    const settingsRevisionRef = useRef(settings.revision);
+    useEffect(() => {
+        settingsRevisionRef.current = settings.revision;
+    }, [settings.revision]);
+    useEffect(() => {
+        const currentWindow = window;
+        const parentOrigin = getPreviewParentOrigin(document.referrer);
+        const isTrustedPreviewEmbed = isTrustedBuilderPreviewEmbed(window.location, parentOrigin);
+        const removeInspectorStyles = isTrustedPreviewEmbed ? installBuilderPreviewInspectorStyles() : () => { };
+        const removeHoverInspector = isTrustedPreviewEmbed ? installBuilderPreviewHoverInspector() : () => { };
+        const postToParent = (event, response) => {
+            const target = event?.source && 'postMessage' in event.source ? event.source : window.parent;
+            if (!target || target === window)
+                return;
+            const targetOrigin = parentOrigin ?? event?.origin ?? '*';
+            target.postMessage(response, targetOrigin || '*');
+        };
+        const applySettings = (input) => {
+            const parsed = BuilderSettingsSchema.safeParse(input);
+            if (!parsed.success)
+                return { status: 'invalid' };
+            if (parsed.data.revision < settingsRevisionRef.current)
+                return { status: 'stale' };
+            settingsRevisionRef.current = parsed.data.revision;
+            setSettings(parsed.data);
+            return { status: 'applied', settings: parsed.data };
+        };
+        applySettings(currentWindow[BUILDER_SETTINGS_WINDOW_KEY]);
+        const handleBuilderState = (event) => {
+            const detail = event instanceof CustomEvent ? event.detail : null;
+            applySettings(detail);
+        };
+        const handlePreviewMessage = (event) => {
+            if (!isTrustedPreviewEmbed)
+                return;
+            if (parentOrigin && event.origin !== parentOrigin)
+                return;
+            if (!parentOrigin && event.source !== window.parent)
+                return;
+            const parsed = PreviewMessageSchema.safeParse(event.data);
+            if (!parsed.success)
+                return;
+            const message = parsed.data;
+            if (message.type === 'REQUEST_READY') {
+                postToParent(event, { type: 'READY', revision: settingsRevisionRef.current });
+                return;
+            }
+            if (message.type === 'APPLY_STATE') {
+                const result = applySettings(message.state);
+                postToParent(event, result.status === 'applied'
+                    ? { type: 'APPLIED', revision: message.revision }
+                    : {
+                        type: 'APPLY_FAILED',
+                        revision: message.revision,
+                        error: result.status === 'stale' ? 'Stale builder revision' : 'Invalid builder state message',
+                    });
+                return;
+            }
+            if (message.type === 'RELOAD') {
+                postToParent(event, { type: 'APPLIED', revision: message.revision });
+                window.setTimeout(() => window.location.reload(), 0);
+                return;
+            }
+            if (message.type === 'SELECT_ELEMENT') {
+                selectBuilderElement(message.selection.blockId);
+            }
+        };
+        const handleBuilderClick = (event) => {
+            if (!isTrustedPreviewEmbed)
+                return;
+            const target = event.target;
+            if (!(target instanceof Element))
+                return;
+            const blockElement = target.closest(BUILDER_BLOCK_SELECTOR);
+            if (!blockElement)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            const selection = createBuilderSelection(blockElement, target);
+            if (!selection.blockId)
+                return;
+            postToParent(null, {
+                type: 'ELEMENT_CLICKED',
+                revision: settingsRevisionRef.current,
+                selection,
+            });
+        };
+        if (isTrustedPreviewEmbed) {
+            postToParent(null, { type: 'READY', revision: settingsRevisionRef.current });
+        }
+        window.addEventListener(BUILDER_STATE_EVENT_NAME, handleBuilderState);
+        window.addEventListener('message', handlePreviewMessage);
+        window.addEventListener('click', handleBuilderClick, true);
+        return () => {
+            removeInspectorStyles();
+            removeHoverInspector();
+            window.removeEventListener(BUILDER_STATE_EVENT_NAME, handleBuilderState);
+            window.removeEventListener('message', handlePreviewMessage);
+            window.removeEventListener('click', handleBuilderClick, true);
+        };
+    }, []);
+    return _jsx(BuilderRuntimeProvider, { settings: settings, children: children });
+}
+export function BuilderRuntimeStyle({ selector = ':root' }) {
+    const css = useBuilderCss(selector);
+    if (!css) {
+        return null;
+    }
+    return _jsx("style", { "data-shoppex-builder-runtime": "v2", children: css });
+}
+export function BuilderBlockFrame({ as, pageId, block, className, children, }) {
+    return createElement(as ?? 'div', {
+        className,
+        'data-page-id': pageId,
+        'data-builder-block': block.id,
+        'data-builder-block-type': block.type,
+    }, children);
+}
+export function BuilderPage({ pageId, blocks, registry, context, fallback = null, }) {
+    const runtimeBlocks = useVisibleBuilderPageBlocks(pageId);
+    const pageBlocks = blocks ?? runtimeBlocks;
+    return (_jsx(_Fragment, { children: pageBlocks.map((block) => {
+            const Component = registry[block.type];
+            if (!Component) {
+                return fallback;
+            }
+            return (_jsx(BuilderBlockProvider, { block: block, children: _jsx(Component, { block: block, context: context }) }, block.id));
+        }) }));
+}
+export function useBuilderRuntime() {
+    const context = useContext(BuilderRuntimeContext);
+    if (!context) {
+        throw new Error('useBuilderRuntime must be used inside BuilderRuntimeProvider');
+    }
+    return context;
+}
+export function useBuilderContent(path, fallback) {
+    const scopedValue = useScopedBuilderContentValue(path);
+    if (typeof scopedValue === 'string')
+        return scopedValue;
+    return getBuilderContentString(useBuilderRuntime().settings, path, fallback);
+}
+export function useBuilderContentValue(path) {
+    const scopedValue = useScopedBuilderContentValue(path);
+    if (scopedValue !== undefined)
+        return scopedValue;
+    return getBuilderContentValue(useBuilderRuntime().settings, path);
+}
+export function useBuilderContentList(path, fallback = []) {
+    const scopedValue = useScopedBuilderContentValue(path);
+    if (Array.isArray(scopedValue))
+        return scopedValue;
+    return getBuilderContentList(useBuilderRuntime().settings, path, fallback);
+}
+export function useBuilderContentRecord() {
+    const block = useContext(BuilderBlockContext);
+    const content = getBuilderContentRecord(useBuilderRuntime().settings);
+    if (!block)
+        return content;
+    return {
+        ...content,
+        [block.type]: {
+            ...(typeof content[block.type] === 'object' && content[block.type] !== null
+                ? content[block.type]
+                : {}),
+            ...block.settings,
+        },
+    };
+}
+export function useBuilderBlockSetting(input) {
+    return getBlockSettingValue(useBuilderRuntime().settings, input);
+}
+export function useBuilderPageLayout(pageId) {
+    return getPageLayout(useBuilderRuntime().settings, pageId);
+}
+export function useBuilderPageBlocks(pageId) {
+    return getPageBlocks(useBuilderRuntime().settings, pageId);
+}
+export function useVisibleBuilderPageBlocks(pageId) {
+    return getVisiblePageBlocks(useBuilderRuntime().settings, pageId);
+}
+export function useBuilderStyleSlot(slotId, input = {}) {
+    return resolveStyleSlotValue(useBuilderRuntime().settings, slotId, input);
+}
+export function useBuilderCss(selector = ':root') {
+    return createBuilderCss(useBuilderRuntime().settings, selector);
+}
+function useScopedBuilderContentValue(path) {
+    const block = useContext(BuilderBlockContext);
+    if (!block)
+        return undefined;
+    if (Object.prototype.hasOwnProperty.call(block.settings, path)) {
+        return block.settings[path];
+    }
+    const shortPath = path.startsWith(`${block.type}.`) ? path.slice(block.type.length + 1) : path.split('.').at(-1);
+    if (shortPath && Object.prototype.hasOwnProperty.call(block.settings, shortPath)) {
+        return block.settings[shortPath];
+    }
+    const nested = shortPath ? getNestedBuilderSetting(block.settings, shortPath) : undefined;
+    return nested ?? getNestedBuilderSetting(block.settings, path);
+}
+function getNestedBuilderSetting(record, path) {
+    let current = record;
+    for (const segment of path.split('.')) {
+        if (!current || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function parseInitialBuilderSettings(input) {
+    const parsed = BuilderSettingsSchema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    const candidate = unwrapBuilderSettingsInput(input);
+    const candidateParsed = BuilderSettingsSchema.safeParse(candidate);
+    if (candidateParsed.success)
+        return candidateParsed.data;
+    if (!isRecord(candidate) || !isRecord(candidate.theme)) {
+        return createEmptyBuilderSettings(0);
+    }
+    const revision = parseBuilderRevision(candidate.revision);
+    const migrated = migrateLegacyBuilderSettings({ theme: candidate.theme }, revision);
+    const mixedCandidate = BuilderSettingsSchema.safeParse({
+        ...migrated,
+        theme: {
+            ...migrated.theme,
+            pages: Array.isArray(candidate.theme.pages) ? candidate.theme.pages : migrated.theme.pages,
+            terms: isRecord(candidate.theme.terms) ? candidate.theme.terms : migrated.theme.terms,
+        },
+    });
+    return mixedCandidate.success ? mixedCandidate.data : migrated;
+}
+function unwrapBuilderSettingsInput(input) {
+    if (!isRecord(input))
+        return input;
+    if (isRecord(input.builder_settings))
+        return input.builder_settings;
+    if (isRecord(input.builderSettings))
+        return input.builderSettings;
+    return input;
+}
+function parseBuilderRevision(input) {
+    return typeof input === 'number' && Number.isInteger(input) && input >= 0 ? input : 0;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getPreviewParentOrigin(referrer) {
+    if (!referrer)
+        return null;
+    try {
+        return new URL(referrer).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function isTrustedBuilderPreviewEmbed(location, parentOrigin) {
+    if (window.parent === window || !parentOrigin)
+        return false;
+    if (!hasBuilderPreviewMode(location))
+        return false;
+    return isTrustedBuilderPreviewParentOrigin(parentOrigin);
+}
+function hasBuilderPreviewMode(location) {
+    const searchParams = new URLSearchParams(location.search);
+    return (searchParams.get('shoppex-preview-mode') === 'theme'
+        || searchParams.get('shoppex-preview-mode') === 'builder'
+        || searchParams.get('shoppex-preview') === 'builder');
+}
+function isTrustedBuilderPreviewParentOrigin(origin) {
+    try {
+        const parsed = new URL(origin);
+        const hostname = parsed.hostname.toLowerCase();
+        return (hostname === 'dashboard.shoppex.io'
+            || hostname === 'dashboard.shoppex.test'
+            || hostname === 'localhost'
+            || hostname === '127.0.0.1'
+            || hostname === '::1'
+            || hostname.endsWith('.localhost')
+            || hostname.endsWith('.vercel.app')
+            || hostname.endsWith('.vercel.run'));
+    }
+    catch {
+        return false;
+    }
+}
+function selectBuilderElement(blockId) {
+    document
+        .querySelectorAll(BUILDER_SELECTED_SELECTOR)
+        .forEach((node) => node.removeAttribute('data-builder-selected'));
+    if (!blockId)
+        return;
+    const target = document.querySelector(`[data-builder-block="${CSS.escape(blockId)}"]`);
+    if (!target)
+        return;
+    target.setAttribute('data-builder-selected', 'true');
+    target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+}
+function createBuilderSelection(blockElement, target) {
+    const contentElement = target.closest(BUILDER_CONTENT_SELECTOR);
+    const slotElement = target.closest('[data-builder-slot]');
+    const linkElement = target.closest('a[href]');
+    const selection = {
+        blockId: blockElement.getAttribute('data-builder-block') ?? undefined,
+        blockType: blockElement.getAttribute('data-builder-block-type') ?? undefined,
+        pageId: blockElement.getAttribute('data-page-id') ?? undefined,
+        contentPath: contentElement?.getAttribute('data-builder-content') ?? undefined,
+        slotId: slotElement?.getAttribute('data-builder-slot') ?? undefined,
+        elementType: inferBuilderElementType(target, blockElement, contentElement, slotElement),
+    };
+    if (linkElement && blockElement.contains(linkElement)) {
+        selection.href = linkElement.getAttribute('href') ?? '';
+        selection.target = linkElement.getAttribute('target') ?? '';
+        selection.rel = linkElement.getAttribute('rel') ?? '';
+    }
+    return selection;
+}
+function inferBuilderElementType(target, blockElement, contentElement, slotElement) {
+    const element = contentElement ?? target;
+    if (element.closest('a[href]'))
+        return 'link';
+    if (element.closest('button'))
+        return 'button';
+    if (element instanceof HTMLImageElement || element.closest('img'))
+        return 'image';
+    if (slotElement)
+        return 'style';
+    return element === blockElement ? 'block' : 'text';
+}
+function installBuilderPreviewInspectorStyles() {
+    const style = document.createElement('style');
+    style.setAttribute('data-shoppex-builder-inspector', 'v2');
+    style.textContent = `
+    [data-builder-block] {
+      position: relative;
+    }
+    [data-builder-block][data-builder-selected="true"] {
+      outline: 2px solid #2563eb;
+      outline-offset: 4px;
+    }
+    [data-builder-block][data-builder-hovered="true"] {
+      outline: 1px dashed #2563eb;
+      outline-offset: 4px;
+      cursor: pointer;
+    }
+  `;
+    document.head.appendChild(style);
+    return () => style.remove();
+}
+function installBuilderPreviewHoverInspector() {
+    let hovered = null;
+    const clearHovered = () => {
+        hovered?.removeAttribute('data-builder-hovered');
+        hovered = null;
+    };
+    const handleMouseOver = (event) => {
+        const target = event.target;
+        if (!(target instanceof Element))
+            return;
+        const blockElement = target.closest(BUILDER_BLOCK_SELECTOR);
+        if (blockElement === hovered)
+            return;
+        clearHovered();
+        if (!blockElement)
+            return;
+        hovered = blockElement;
+        hovered.setAttribute('data-builder-hovered', 'true');
+    };
+    const handleMouseOut = (event) => {
+        const relatedTarget = event.relatedTarget;
+        if (relatedTarget instanceof Node && hovered?.contains(relatedTarget))
+            return;
+        clearHovered();
+    };
+    window.addEventListener('mouseover', handleMouseOver, true);
+    window.addEventListener('mouseout', handleMouseOut, true);
+    return () => {
+        clearHovered();
+        window.removeEventListener('mouseover', handleMouseOver, true);
+        window.removeEventListener('mouseout', handleMouseOut, true);
+    };
+}

package/dist/style-slots.d.ts

@@ -0,0 +1,12 @@
+import type { BlockInstance, BuilderSettings, Breakpoint, StyleSlotId, StyleSlots } from '@shoppex/builder-contracts';
+export declare function getStyleSlotValue(settings: BuilderSettings, slotId: StyleSlotId, input?: {
+    block?: BlockInstance;
+}): unknown;
+export declare function resolveStyleSlotValue(settings: BuilderSettings, slotId: StyleSlotId, input?: {
+    block?: BlockInstance;
+    breakpoint?: Breakpoint;
+    fallback?: unknown;
+}): unknown;
+export declare function mergeStyleSlots(base: StyleSlots, overrides: StyleSlots | undefined): StyleSlots;
+export declare function isResponsiveRecord(value: unknown): value is Partial<Record<Breakpoint, unknown>>;
+//# sourceMappingURL=style-slots.d.ts.map

package/dist/style-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-slots.d.ts","sourceRoot":"","sources":["../src/style-slots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAItH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,aAAa,CAAA;CAAO,GAAG,OAAO,CAEhI;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,WAAW,EACnB,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACjF,OAAO,CAkBT;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAK/F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAMhG"}

package/dist/style-slots.js

@@ -0,0 +1,31 @@
+const BREAKPOINT_ORDER = ['base', 'sm', 'md', 'lg', 'xl'];
+export function getStyleSlotValue(settings, slotId, input = {}) {
+    return input.block?.style_overrides?.[slotId] ?? settings.theme.style_slots[slotId];
+}
+export function resolveStyleSlotValue(settings, slotId, input = {}) {
+    const value = getStyleSlotValue(settings, slotId, input);
+    if (!isResponsiveRecord(value)) {
+        return value ?? input.fallback;
+    }
+    const breakpoint = input.breakpoint ?? 'base';
+    const breakpointIndex = BREAKPOINT_ORDER.indexOf(breakpoint);
+    for (let index = breakpointIndex; index >= 0; index -= 1) {
+        const candidate = value[BREAKPOINT_ORDER[index]];
+        if (candidate !== undefined) {
+            return candidate;
+        }
+    }
+    return input.fallback;
+}
+export function mergeStyleSlots(base, overrides) {
+    return {
+        ...base,
+        ...(overrides ?? {}),
+    };
+}
+export function isResponsiveRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return BREAKPOINT_ORDER.some((breakpoint) => Object.prototype.hasOwnProperty.call(value, breakpoint));
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@shoppexio/builder-runtime",
+  "version": "0.1.0",
+  "description": "Theme-side Builder v2 runtime helpers for Shoppex storefront themes",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShoppexIO/shoppex.git",
+    "directory": "packages/builder-runtime"
+  },
+  "homepage": "https://docs.shoppex.io",
+  "bugs": {
+    "url": "https://github.com/ShoppexIO/shoppex/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./attributes": {
+      "bun": "./src/attributes.ts",
+      "types": "./src/attributes.ts",
+      "import": "./src/attributes.ts",
+      "default": "./src/attributes.ts"
+    },
+    "./content": {
+      "bun": "./src/content.ts",
+      "types": "./src/content.ts",
+      "import": "./src/content.ts",
+      "default": "./src/content.ts"
+    },
+    "./css-vars": {
+      "bun": "./src/css-vars.ts",
+      "types": "./src/css-vars.ts",
+      "import": "./src/css-vars.ts",
+      "default": "./src/css-vars.ts"
+    },
+    "./layout": {
+      "bun": "./src/layout.ts",
+      "types": "./src/layout.ts",
+      "import": "./src/layout.ts",
+      "default": "./src/layout.ts"
+    },
+    "./react": {
+      "bun": "./src/react.tsx",
+      "types": "./src/react.tsx",
+      "import": "./src/react.tsx",
+      "default": "./src/react.tsx"
+    },
+    "./style-slots": {
+      "bun": "./src/style-slots.ts",
+      "types": "./src/style-slots.ts",
+      "import": "./src/style-slots.ts",
+      "default": "./src/style-slots.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src",
+    "clean": "rm -rf dist"
+  },
+  "author": "Shoppex",
+  "license": "MIT",
+  "peerDependencies": {
+    "@shoppexio/builder-contracts": "0.1.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@shoppex/builder-contracts": "npm:@shoppexio/builder-contracts@0.1.0"
+  },
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "react-dom": "^19.2.4",
+    "@types/react": "^19.2.14",
+    "react": "^19.2.4",
+    "typescript": "^5.8.3"
+  }
+}

package/src/attributes.ts

@@ -0,0 +1,23 @@
+import type { StyleSlotId } from '@shoppex/builder-contracts';
+
+export type BuilderAttributeMap = Record<string, string>;
+
+export function builderContent(path: string): BuilderAttributeMap {
+  return {
+    'data-builder-content': path,
+  };
+}
+
+export function builderSlot(slotId: StyleSlotId, input: { blockId?: string } = {}): BuilderAttributeMap {
+  return {
+    'data-builder-slot': slotId,
+    ...(input.blockId ? { 'data-builder-block': input.blockId } : {}),
+  };
+}
+
+export function builderBlock(blockId: string, blockType: string): BuilderAttributeMap {
+  return {
+    'data-builder-block': blockId,
+    'data-builder-block-type': blockType,
+  };
+}