@shoppexio/builder-runtime 0.1.1 → 0.1.3

package/src/manifest-setting-paths.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveManifestSettingRecordValue,
+  toSnakeCaseManifestPath,
+} from './manifest-setting-paths.js';
+
+describe('manifest-setting-paths', () => {
+  it('converts dotted manifest paths to snake_case aliases', () => {
+    expect(toSnakeCaseManifestPath('howItWorks.beforeImage')).toBe('how_it_works.before_image');
+    expect(toSnakeCaseManifestPath('theme.accentColor')).toBe('theme.accent_color');
+    expect(toSnakeCaseManifestPath('hero.image')).toBe('hero.image');
+  });
+
+  it('reads canonical and snake_cased block setting keys', () => {
+    const record = {
+      'howItWorks.beforeImage': '/media/before.png',
+      'how_it_works.after_image': '/media/after.png',
+    };
+
+    expect(resolveManifestSettingRecordValue(record, 'howItWorks.beforeImage')).toBe('/media/before.png');
+    expect(resolveManifestSettingRecordValue(record, 'howItWorks.afterImage')).toBe('/media/after.png');
+  });
+});

package/src/manifest-setting-paths.ts

@@ -0,0 +1,55 @@
+import type { JsonRecord } from './content.js';
+
+export function toSnakeCaseManifestSegment(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase();
+}
+
+export function toSnakeCaseManifestPath(path: string): string {
+  return path
+    .split('.')
+    .filter(Boolean)
+    .map(toSnakeCaseManifestSegment)
+    .join('.');
+}
+
+function getByDottedPath(record: JsonRecord, path: string): unknown {
+  let current: unknown = record;
+
+  for (const segment of path.split('.')) {
+    if (!current || typeof current !== 'object') {
+      return undefined;
+    }
+
+    current = (current as JsonRecord)[segment];
+  }
+
+  return current;
+}
+
+export function resolveManifestSettingRecordValue(
+  record: JsonRecord,
+  path: string,
+): unknown {
+  if (Object.prototype.hasOwnProperty.call(record, path)) {
+    return record[path];
+  }
+
+  const snakePath = toSnakeCaseManifestPath(path);
+  if (snakePath !== path && Object.prototype.hasOwnProperty.call(record, snakePath)) {
+    return record[snakePath];
+  }
+
+  const nested = getByDottedPath(record, path);
+  if (nested !== undefined) {
+    return nested;
+  }
+
+  if (snakePath !== path) {
+    return getByDottedPath(record, snakePath);
+  }
+
+  return undefined;
+}

package/src/merchant-custom-page.tsx

@@ -0,0 +1,161 @@
+'use client';
+
+import type { BlockInstance } from '@shoppex/builder-contracts';
+import { findCustomPageBySlug } from '@shoppex/builder-contracts';
+import type { ComponentType, ReactNode } from 'react';
+import { useMemo } from 'react';
+import { builderBlock } from './attributes.js';
+import { readManifestStyleBlockProps } from './block-style-settings.js';
+import { BuilderPage, useBuilderRuntime, useThemePageBlocks, type BuilderBlockRegistry } from './react.js';
+import { YouTubeEmbedBuilderBlock } from './YouTubeEmbedBuilderBlock.js';
+
+type CustomEmbedProps = {
+  embedHtml?: string;
+  height?: number;
+  autoResize?: boolean;
+  width?: 'full' | 'boxed' | 'embed';
+};
+
+type TextBlockProps = {
+  eyebrow?: string;
+  title?: string;
+  body?: string;
+  alignment?: 'left' | 'center' | 'right';
+  ctaLabel?: string;
+  ctaHref?: string;
+  styleBackground?: string;
+  styleAccentColor?: string;
+};
+
+export type MerchantCustomPageRegistryOptions = {
+  pageId: string;
+  CustomEmbed: ComponentType<CustomEmbedProps>;
+  TextBlock?: ComponentType<TextBlockProps>;
+};
+
+function readStringSetting(block: BlockInstance, key: string): string | undefined {
+  const value = block.settings[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function readNumberSetting(block: BlockInstance, key: string): number | undefined {
+  const value = block.settings[key];
+  return typeof value === 'number' && value > 0 ? value : undefined;
+}
+
+export function createMerchantCustomPageRegistry(
+  options: MerchantCustomPageRegistryOptions,
+): BuilderBlockRegistry {
+  const { pageId, CustomEmbed, TextBlock } = options;
+
+  const registry: BuilderBlockRegistry = {
+    'youtube-embed': ({ block }) => (
+      <YouTubeEmbedBuilderBlock block={block} pageId={pageId} />
+    ),
+    'custom-html': ({ block }) => {
+      const styleProps = readManifestStyleBlockProps(block.settings);
+      const width = block.settings.width;
+      return (
+        <div
+          key={block.id}
+          data-page-id={pageId}
+          {...builderBlock(block.id, block.type)}
+          style={Object.keys(styleProps).length > 0 ? styleProps : undefined}
+        >
+          <CustomEmbed
+            embedHtml={readStringSetting(block, 'embedHtml')}
+            height={readNumberSetting(block, 'height')}
+            autoResize={block.settings.autoResize === true}
+            width={
+              width === 'full' || width === 'boxed' || width === 'embed'
+                ? width
+                : 'embed'
+            }
+          />
+        </div>
+      );
+    },
+  };
+
+  if (TextBlock) {
+    registry['text-block'] = ({ block }) => (
+      <div key={block.id} data-page-id={pageId} {...builderBlock(block.id, block.type)}>
+        <TextBlock
+          eyebrow={readStringSetting(block, 'eyebrow')}
+          title={readStringSetting(block, 'title')}
+          body={readStringSetting(block, 'body')}
+          alignment={
+            (readStringSetting(block, 'alignment') as TextBlockProps['alignment']) ??
+            undefined
+          }
+          ctaLabel={readStringSetting(block, 'ctaLabel')}
+          ctaHref={readStringSetting(block, 'ctaHref')}
+          styleBackground={readStringSetting(block, 'style.background')}
+          styleAccentColor={readStringSetting(block, 'style.accentColor')}
+        />
+      </div>
+    );
+  }
+
+  return registry;
+}
+
+export function MerchantCustomPageBuilderView({
+  pageId,
+  registry,
+  className,
+  children,
+}: {
+  pageId: string;
+  registry: BuilderBlockRegistry;
+  className?: string;
+  children?: ReactNode;
+}) {
+  const blocks = useThemePageBlocks(pageId, []);
+
+  if (blocks.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={className}>
+      {children}
+      <BuilderPage pageId={pageId} blocks={blocks} registry={registry} context={null} />
+    </div>
+  );
+}
+
+export function useMerchantCustomPageRegistry(
+  options: MerchantCustomPageRegistryOptions | null,
+): BuilderBlockRegistry | null {
+  return useMemo(
+    () => (options ? createMerchantCustomPageRegistry(options) : null),
+    [options?.pageId, options?.CustomEmbed, options?.TextBlock],
+  );
+}
+
+export function useMerchantCustomPageView(
+  slug: string | undefined,
+  components: Pick<MerchantCustomPageRegistryOptions, 'CustomEmbed' | 'TextBlock'>,
+) {
+  const { settings } = useBuilderRuntime();
+  const customPage = slug ? findCustomPageBySlug(settings, slug) : undefined;
+  const registry = useMerchantCustomPageRegistry(
+    customPage
+      ? {
+          pageId: customPage.id,
+          CustomEmbed: components.CustomEmbed,
+          TextBlock: components.TextBlock,
+        }
+      : null,
+  );
+  const builderBlockCount = customPage
+    ? (settings.theme.layout[customPage.id]?.blocks.length ?? 0)
+    : 0;
+
+  return {
+    customPage,
+    registry,
+    hasBuilderContent: builderBlockCount > 0,
+  };
+}

package/src/preview-fixtures.ts

@@ -0,0 +1,56 @@
+export type BuilderPreviewReview = {
+  id: string;
+  author: string | null;
+  comment: string | null;
+  rating: number | null;
+  created_at: string;
+  is_automated?: boolean;
+};
+
+export type BuilderPreviewFaqItem = {
+  question: string;
+  answer: string;
+};
+
+export const BUILDER_PREVIEW_REVIEWS: BuilderPreviewReview[] = [
+  {
+    id: 'preview-review-1',
+    author: 'Alex M.',
+    comment: 'Instant delivery and clear instructions. Would buy again.',
+    rating: 5,
+    created_at: '2026-04-12T10:00:00.000Z',
+  },
+  {
+    id: 'preview-review-2',
+    author: 'Jamie R.',
+    comment: 'Support answered quickly when I had a setup question.',
+    rating: 5,
+    created_at: '2026-04-03T14:30:00.000Z',
+  },
+  {
+    id: 'preview-review-3',
+    author: 'Taylor S.',
+    comment: 'Smooth checkout experience and exactly what was advertised.',
+    rating: 4,
+    created_at: '2026-03-22T09:15:00.000Z',
+  },
+];
+
+export function getBuilderPreviewReviewFixtures<T = BuilderPreviewReview>(): T[] {
+  return BUILDER_PREVIEW_REVIEWS as T[];
+}
+
+export const BUILDER_PREVIEW_FAQ_ITEMS: BuilderPreviewFaqItem[] = [
+  {
+    question: 'How fast is delivery?',
+    answer: 'Most digital products are delivered instantly after payment confirmation.',
+  },
+  {
+    question: 'Which payment methods do you accept?',
+    answer: 'Available payment methods depend on your shop configuration and region.',
+  },
+  {
+    question: 'How do I get support?',
+    answer: 'Use the contact page or your customer portal for order-related help.',
+  },
+];

package/src/preview-mode.ts

@@ -0,0 +1,8 @@
+export function isBuilderPreviewMode(location: Pick<Location, 'search'> = window.location): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const mode = new URLSearchParams(location.search).get('shoppex-preview-mode');
+  return mode === 'theme' || mode === 'builder';
+}

package/src/product-page.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import { createBlockInstance } from '@shoppex/builder-contracts';
+import {
+  getBuilderBlockSettingText,
+  getLayoutPageBlockAttributes,
+  getProductPageBlockAttributes,
+} from './product-page.js';
+
+describe('product-page helpers', () => {
+  test('getBuilderBlockSettingText trims non-empty strings', () => {
+    const block = createBlockInstance({
+      type: 'buy-box',
+      settings: {
+        variantLabel: '  License Type  ',
+        addonsLabel: '   ',
+      },
+    });
+
+    expect(getBuilderBlockSettingText(block, 'variantLabel')).toBe('License Type');
+    expect(getBuilderBlockSettingText(block, 'addonsLabel')).toBeNull();
+    expect(getBuilderBlockSettingText(block, 'missing')).toBeNull();
+  });
+
+  test('getLayoutPageBlockAttributes includes page id and builder block attrs', () => {
+    const block = createBlockInstance({ id: 'gallery-1', type: 'gallery' });
+    expect(getProductPageBlockAttributes(block)).toEqual({
+      'data-page-id': 'product',
+      'data-builder-block': 'gallery-1',
+      'data-builder-block-type': 'gallery',
+    });
+    expect(getLayoutPageBlockAttributes('reviews-page', block)).toEqual({
+      'data-page-id': 'reviews-page',
+      'data-builder-block': 'gallery-1',
+      'data-builder-block-type': 'gallery',
+    });
+  });
+});

package/src/product-page.ts

@@ -0,0 +1,32 @@
+import type { BlockInstance } from '@shoppex/builder-contracts';
+import { builderBlock } from './attributes.js';
+
+export function getBuilderBlockSettingText(
+  block: Pick<BlockInstance, 'settings'>,
+  key: string,
+): string | null {
+  const value = block.settings[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function getLayoutPageBlockAttributes(
+  pageId: string,
+  block: Pick<BlockInstance, 'id' | 'type'>,
+) {
+  return {
+    'data-page-id': pageId,
+    ...builderBlock(block.id, block.type),
+  };
+}
+
+export function getProductPageBlockAttributes(
+  block: Pick<BlockInstance, 'id' | 'type'>,
+) {
+  return getLayoutPageBlockAttributes('product', block);
+}
+
+/** @deprecated Use getBuilderBlockSettingText */
+export const getProductBlockText = getBuilderBlockSettingText;
+
+/** @deprecated Use getProductPageBlockAttributes */
+export const getBuilderProductBlockAttributes = getProductPageBlockAttributes;

package/src/react-runtime.test.tsx

@@ -12,6 +12,7 @@ import {
   useBuilderContent,
   useBuilderContentRecord,
   useThemePageBlocks,
+  useThemePageBlockAttributes,
 } from './react.js';
 
 function createSettings(revision: number, title: string): BuilderSettings {
@@ -113,6 +114,18 @@ function PageBlocksProbe({ pageId = 'home', defaultOrder = ['hero', 'products']
   );
 }
 
+function PageBlockAttributesProbe({
+  pageId = 'contact-page',
+  defaultOrder = ['page-contact-page'],
+}: {
+  pageId?: string;
+  defaultOrder?: string[];
+}) {
+  const attrs = useThemePageBlockAttributes(pageId, defaultOrder);
+
+  return <section data-testid="page-block-attrs" {...attrs} />;
+}
+
 function HeroBlock({ block }: { block: BlockInstance }) {
   const title = useBuilderContent('hero.title', '');
 
@@ -468,6 +481,35 @@ describe('BuilderRuntimePreviewProvider', () => {
     expect(dom.window.document.querySelector('[data-testid="page-blocks"]')?.textContent).toBe('hero-1:hero');
   });
 
+  test('useThemePageBlockAttributes exposes page id and first block attrs', async () => {
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider
+          initialSettings={{
+            ...createEmptyBuilderSettings(1),
+            theme: {
+              ...createEmptyBuilderSettings(1).theme,
+              layout: {
+                'contact-page': {
+                  blocks: [
+                    { id: 'contact-1', type: 'page-contact-page', visible: true, settings: {} },
+                  ],
+                },
+              },
+            },
+          }}
+        >
+          <PageBlockAttributesProbe />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    const section = dom.window.document.querySelector('[data-testid="page-block-attrs"]');
+    expect(section?.getAttribute('data-page-id')).toBe('contact-page');
+    expect(section?.getAttribute('data-builder-block')).toBe('contact-1');
+    expect(section?.getAttribute('data-builder-block-type')).toBe('page-contact-page');
+  });
+
   test('shows missing registry blocks inside trusted builder preview', async () => {
     await act(async () => {
       root.render(