@shoppexio/builder-runtime 0.1.0

package/src/react.tsx

@@ -0,0 +1,550 @@
+import type { BlockInstance, BuilderSelection, BuilderSettings, Breakpoint, StyleSlotId } from '@shoppex/builder-contracts';
+import {
+  BuilderSettingsSchema,
+  PreviewMessageSchema,
+  createEmptyBuilderSettings,
+  migrateLegacyBuilderSettings,
+} from '@shoppex/builder-contracts';
+import {
+  createElement,
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ElementType,
+  type ReactNode,
+} 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';
+
+type BuilderRuntimeContextValue = {
+  settings: BuilderSettings;
+};
+
+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<BuilderRuntimeContextValue | null>(null);
+const BuilderBlockContext = createContext<BlockInstance | null>(null);
+
+export function BuilderRuntimeProvider({ settings, children }: { settings: BuilderSettings; children: ReactNode }) {
+  const value = useMemo(() => ({ settings }), [settings]);
+  return <BuilderRuntimeContext.Provider value={value}>{children}</BuilderRuntimeContext.Provider>;
+}
+
+export function BuilderBlockProvider({ block, children }: { block: BlockInstance; children: ReactNode }) {
+  return <BuilderBlockContext.Provider value={block}>{children}</BuilderBlockContext.Provider>;
+}
+
+export function BuilderRuntimePreviewProvider({
+  initialSettings,
+  children,
+}: {
+  initialSettings?: unknown;
+  children: ReactNode;
+}) {
+  const [settings, setSettings] = useState(() => parseInitialBuilderSettings(initialSettings));
+  const settingsRevisionRef = useRef(settings.revision);
+
+  useEffect(() => {
+    settingsRevisionRef.current = settings.revision;
+  }, [settings.revision]);
+
+  useEffect(() => {
+    const currentWindow = window as Window & {
+      __SHOPPEX_BUILDER_SETTINGS__?: BuilderSettings;
+    };
+    const parentOrigin = getPreviewParentOrigin(document.referrer);
+    const isTrustedPreviewEmbed = isTrustedBuilderPreviewEmbed(window.location, parentOrigin);
+    const removeInspectorStyles = isTrustedPreviewEmbed ? installBuilderPreviewInspectorStyles() : () => {};
+    const removeHoverInspector = isTrustedPreviewEmbed ? installBuilderPreviewHoverInspector() : () => {};
+
+    const postToParent = (event: MessageEvent<unknown> | null, response: unknown) => {
+      const target = event?.source && 'postMessage' in event.source ? event.source : window.parent;
+      if (!target || target === window) return;
+      const targetOrigin = parentOrigin ?? event?.origin ?? '*';
+      (target as { postMessage: (message: unknown, targetOrigin: string) => void }).postMessage(
+        response,
+        targetOrigin || '*',
+      );
+    };
+
+    const applySettings = (input: unknown): { status: 'applied'; settings: BuilderSettings } | { status: 'invalid' | 'stale' } => {
+      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: Event) => {
+      const detail = event instanceof CustomEvent ? event.detail : null;
+      applySettings(detail);
+    };
+
+    const handlePreviewMessage = (event: MessageEvent<unknown>) => {
+      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: MouseEvent) => {
+      if (!isTrustedPreviewEmbed) return;
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      const blockElement = target.closest<HTMLElement>(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 <BuilderRuntimeProvider settings={settings}>{children}</BuilderRuntimeProvider>;
+}
+
+export function BuilderRuntimeStyle({ selector = ':root' }: { selector?: string }) {
+  const css = useBuilderCss(selector);
+  if (!css) {
+    return null;
+  }
+
+  return <style data-shoppex-builder-runtime="v2">{css}</style>;
+}
+
+export type BuilderBlockComponent<TContext = unknown> = ComponentType<{
+  block: BlockInstance;
+  context: TContext;
+}>;
+
+export type BuilderBlockRegistry<TContext = unknown> = Record<string, BuilderBlockComponent<TContext>>;
+
+export function BuilderBlockFrame<TElement extends ElementType = 'div'>({
+  as,
+  pageId,
+  block,
+  className,
+  children,
+}: {
+  as?: TElement;
+  pageId: string;
+  block: BlockInstance;
+  className?: string;
+  children: ReactNode;
+}) {
+  return createElement(
+    as ?? 'div',
+    {
+      className,
+      'data-page-id': pageId,
+      'data-builder-block': block.id,
+      'data-builder-block-type': block.type,
+    },
+    children,
+  );
+}
+
+export function BuilderPage<TContext = unknown>({
+  pageId,
+  blocks,
+  registry,
+  context,
+  fallback = null,
+}: {
+  pageId: string;
+  blocks?: BlockInstance[];
+  registry: BuilderBlockRegistry<TContext>;
+  context: TContext;
+  fallback?: ReactNode;
+}) {
+  const runtimeBlocks = useVisibleBuilderPageBlocks(pageId);
+  const pageBlocks = blocks ?? runtimeBlocks;
+
+  return (
+    <>
+      {pageBlocks.map((block) => {
+        const Component = registry[block.type];
+        if (!Component) {
+          return fallback;
+        }
+
+        return (
+          <BuilderBlockProvider key={block.id} block={block}>
+            <Component block={block} context={context} />
+          </BuilderBlockProvider>
+        );
+      })}
+    </>
+  );
+}
+
+export function useBuilderRuntime(): BuilderRuntimeContextValue {
+  const context = useContext(BuilderRuntimeContext);
+  if (!context) {
+    throw new Error('useBuilderRuntime must be used inside BuilderRuntimeProvider');
+  }
+
+  return context;
+}
+
+export function useBuilderContent(path: string, fallback?: string): string | undefined {
+  const scopedValue = useScopedBuilderContentValue(path);
+  if (typeof scopedValue === 'string') return scopedValue;
+  return getBuilderContentString(useBuilderRuntime().settings, path, fallback);
+}
+
+export function useBuilderContentValue(path: string): unknown {
+  const scopedValue = useScopedBuilderContentValue(path);
+  if (scopedValue !== undefined) return scopedValue;
+  return getBuilderContentValue(useBuilderRuntime().settings, path);
+}
+
+export function useBuilderContentList<T = unknown>(path: string, fallback: T[] = []): T[] {
+  const scopedValue = useScopedBuilderContentValue(path);
+  if (Array.isArray(scopedValue)) return scopedValue as T[];
+  return getBuilderContentList<T>(useBuilderRuntime().settings, path, fallback);
+}
+
+export function useBuilderContentRecord(): Record<string, unknown> {
+  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] as Record<string, unknown>
+        : {}),
+      ...block.settings,
+    },
+  };
+}
+
+export function useBuilderBlockSetting<T = unknown>(input: {
+  pageId: string;
+  blockId: string;
+  path: string;
+  fallback: T;
+}): T {
+  return getBlockSettingValue<T>(useBuilderRuntime().settings, input);
+}
+
+export function useBuilderPageLayout(pageId: string) {
+  return getPageLayout(useBuilderRuntime().settings, pageId);
+}
+
+export function useBuilderPageBlocks(pageId: string) {
+  return getPageBlocks(useBuilderRuntime().settings, pageId);
+}
+
+export function useVisibleBuilderPageBlocks(pageId: string) {
+  return getVisiblePageBlocks(useBuilderRuntime().settings, pageId);
+}
+
+export function useBuilderStyleSlot(
+  slotId: StyleSlotId,
+  input: { breakpoint?: Breakpoint; fallback?: unknown } = {},
+): unknown {
+  return resolveStyleSlotValue(useBuilderRuntime().settings, slotId, input);
+}
+
+export function useBuilderCss(selector = ':root'): string {
+  return createBuilderCss(useBuilderRuntime().settings, selector);
+}
+
+function useScopedBuilderContentValue(path: string): unknown {
+  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: Record<string, unknown>, path: string): unknown {
+  let current: unknown = record;
+  for (const segment of path.split('.')) {
+    if (!current || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function parseInitialBuilderSettings(input: unknown): BuilderSettings {
+  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: unknown): unknown {
+  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: unknown): number {
+  return typeof input === 'number' && Number.isInteger(input) && input >= 0 ? input : 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getPreviewParentOrigin(referrer: string): string | null {
+  if (!referrer) return null;
+  try {
+    return new URL(referrer).origin;
+  } catch {
+    return null;
+  }
+}
+
+function isTrustedBuilderPreviewEmbed(location: Location, parentOrigin: string | null): boolean {
+  if (window.parent === window || !parentOrigin) return false;
+  if (!hasBuilderPreviewMode(location)) return false;
+  return isTrustedBuilderPreviewParentOrigin(parentOrigin);
+}
+
+function hasBuilderPreviewMode(location: Location): boolean {
+  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: string): boolean {
+  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: string | undefined): void {
+  document
+    .querySelectorAll<HTMLElement>(BUILDER_SELECTED_SELECTOR)
+    .forEach((node) => node.removeAttribute('data-builder-selected'));
+
+  if (!blockId) return;
+
+  const target = document.querySelector<HTMLElement>(
+    `[data-builder-block="${CSS.escape(blockId)}"]`,
+  );
+  if (!target) return;
+
+  target.setAttribute('data-builder-selected', 'true');
+  target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+}
+
+function createBuilderSelection(blockElement: HTMLElement, target: Element): BuilderSelection {
+  const contentElement = target.closest<HTMLElement>(BUILDER_CONTENT_SELECTOR);
+  const slotElement = target.closest<HTMLElement>('[data-builder-slot]');
+  const linkElement = target.closest<HTMLAnchorElement>('a[href]');
+  const selection: BuilderSelection = {
+    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: Element,
+  blockElement: HTMLElement,
+  contentElement: HTMLElement | null,
+  slotElement: HTMLElement | null,
+): BuilderSelection['elementType'] {
+  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(): () => void {
+  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(): () => void {
+  let hovered: HTMLElement | null = null;
+
+  const clearHovered = () => {
+    hovered?.removeAttribute('data-builder-hovered');
+    hovered = null;
+  };
+
+  const handleMouseOver = (event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const blockElement = target.closest<HTMLElement>(BUILDER_BLOCK_SELECTOR);
+    if (blockElement === hovered) return;
+    clearHovered();
+    if (!blockElement) return;
+    hovered = blockElement;
+    hovered.setAttribute('data-builder-hovered', 'true');
+  };
+
+  const handleMouseOut = (event: MouseEvent) => {
+    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/src/style-slots.ts

@@ -0,0 +1,46 @@
+import type { BlockInstance, BuilderSettings, Breakpoint, StyleSlotId, StyleSlots } from '@shoppex/builder-contracts';
+
+const BREAKPOINT_ORDER: Breakpoint[] = ['base', 'sm', 'md', 'lg', 'xl'];
+
+export function getStyleSlotValue(settings: BuilderSettings, slotId: StyleSlotId, input: { block?: BlockInstance } = {}): unknown {
+  return input.block?.style_overrides?.[slotId] ?? settings.theme.style_slots[slotId];
+}
+
+export function resolveStyleSlotValue(
+  settings: BuilderSettings,
+  slotId: StyleSlotId,
+  input: { block?: BlockInstance; breakpoint?: Breakpoint; fallback?: unknown } = {},
+): unknown {
+  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: StyleSlots, overrides: StyleSlots | undefined): StyleSlots {
+  return {
+    ...base,
+    ...(overrides ?? {}),
+  };
+}
+
+export function isResponsiveRecord(value: unknown): value is Partial<Record<Breakpoint, unknown>> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  return BREAKPOINT_ORDER.some((breakpoint) => Object.prototype.hasOwnProperty.call(value, breakpoint));
+}