@shoppexio/builder-runtime 0.1.2 → 0.1.4

package/src/YouTubeEmbedBuilderBlock.tsx

@@ -0,0 +1,49 @@
+import type { BlockInstance } from '@shoppex/builder-contracts';
+import { builderBlock } from './attributes.js';
+import { isBuilderPreviewMode } from './preview-mode.js';
+import { YouTubeEmbed, YouTubeEmbedPreviewPlaceholder } from './YouTubeEmbed.js';
+import {
+  getYouTubeEmbedBlockStyleProps,
+  readYouTubeEmbedBlockSettings,
+} from './youtube-embed-block.js';
+import { parseYouTubeVideoId } from './youtube.js';
+
+export type YouTubeEmbedBuilderBlockProps = {
+  block: Pick<BlockInstance, 'id' | 'type' | 'settings'>;
+  pageId?: string;
+};
+
+export function YouTubeEmbedBuilderBlock({
+  block,
+  pageId = 'home',
+}: YouTubeEmbedBuilderBlockProps) {
+  const settings = readYouTubeEmbedBlockSettings(block);
+  const videoId = parseYouTubeVideoId(settings.videoUrl);
+  const showPreviewPlaceholder = !videoId && isBuilderPreviewMode();
+
+  if (!videoId && !showPreviewPlaceholder) {
+    return null;
+  }
+
+  const styleProps = getYouTubeEmbedBlockStyleProps(block);
+
+  return (
+    <div
+      key={block.id}
+      data-page-id={pageId}
+      {...builderBlock(block.id, block.type)}
+      style={Object.keys(styleProps).length > 0 ? styleProps : undefined}
+    >
+      {videoId ? (
+        <YouTubeEmbed
+          videoUrl={settings.videoUrl}
+          title={settings.title}
+          height={settings.height}
+          privacyEnhanced={settings.privacyEnhanced}
+        />
+      ) : (
+        <YouTubeEmbedPreviewPlaceholder height={settings.height} />
+      )}
+    </div>
+  );
+}

package/src/block-style-settings.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+
+type StyleBlockSettings = Record<string, unknown>;
+
+export function readManifestStyleBlockProps(
+  settings: StyleBlockSettings,
+): CSSProperties {
+  const bg = settings['style.background'];
+  const radius = settings['style.borderRadius'];
+  const padding = settings['style.padding'];
+  const style: CSSProperties = {};
+
+  if (typeof bg === 'string' && bg.length > 0) {
+    style.backgroundColor = bg;
+  }
+  if (typeof radius === 'number') {
+    style.borderRadius = `${radius}px`;
+  }
+  if (typeof padding === 'number') {
+    style.padding = `${padding}px`;
+  }
+
+  return style;
+}

package/src/builder-runtime.test.ts

@@ -8,7 +8,9 @@ import {
   createBuilderCss,
   getBuilderContentList,
   getBuilderContentString,
+  normalizeGalleryItems,
   getPageBlocks,
+  getBlockSettingValue,
   getThemePageBlockOrderFromManifest,
   resolveBlockSettings,
   resolveStyleSlotValue,
@@ -90,6 +92,19 @@ describe('@shoppex/builder-runtime', () => {
     expect(getBuilderContentString(settings, 'hero.subtitle', 'Default subtitle')).toBe('');
   });
 
+  test('normalizes gallery list items from image or url keys', () => {
+    expect(
+      normalizeGalleryItems([
+        { image: '/media/a.png', alt: 'A' },
+        { url: '/media/b.png' },
+        { image: '' },
+      ]),
+    ).toEqual([
+      { url: '/media/a.png', alt: 'A' },
+      { url: '/media/b.png' },
+    ]);
+  });
+
   test('resolves page blocks', () => {
     const settings = createSettings();
 
@@ -186,6 +201,27 @@ describe('@shoppex/builder-runtime', () => {
     expect(resolveBlockSettings(block, manifest)).toEqual({ title: 'Default hero' });
   });
 
+  test('reads block settings from snake_cased storefront manifest keys', () => {
+    const settings = createSettings();
+    settings.theme.layout.home.blocks.push(
+      createBlockInstance({
+        id: 'how-it-works-1',
+        type: 'how-it-works',
+        settings: {
+          'how_it_works.before_image': '/media/before.png',
+          'how_it_works.after_image': '/media/after.png',
+        },
+      }),
+    );
+
+    expect(getBlockSettingValue(settings, {
+      pageId: 'home',
+      blockId: 'how-it-works-1',
+      path: 'howItWorks.beforeImage',
+      fallback: '',
+    })).toBe('/media/before.png');
+  });
+
   test('creates the three supported builder attributes', () => {
     expect(builderContent('hero.title')).toEqual({ 'data-builder-content': 'hero.title' });
     expect(builderSlot('button.radius', { blockId: 'hero-1' })).toEqual({

package/src/content.ts

@@ -1,15 +1,10 @@
 import type { BuilderSettings } from '@shoppex/builder-contracts';
+import { resolveManifestSettingRecordValue } from './manifest-setting-paths.js';
 
 export type JsonRecord = Record<string, unknown>;
 
 export function getBuilderContentValue(settings: BuilderSettings, path: string): unknown {
-  const content = settings.theme.content;
-
-  if (Object.prototype.hasOwnProperty.call(content, path)) {
-    return content[path];
-  }
-
-  return getByDottedPath(content, path);
+  return resolveManifestSettingRecordValue(settings.theme.content, path);
 }
 
 export function getBuilderContentString(settings: BuilderSettings, path: string, fallback?: string): string | undefined {
@@ -22,6 +17,45 @@ export function getBuilderContentList<T = unknown>(settings: BuilderSettings, pa
   return Array.isArray(value) ? (value as T[]) : fallback;
 }
 
+export type NormalizedGalleryItem = {
+  url: string;
+  alt?: string;
+  caption?: string;
+};
+
+export function normalizeGalleryItems(raw: unknown): NormalizedGalleryItem[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const items: NormalizedGalleryItem[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) {
+      continue;
+    }
+
+    const record = entry as Record<string, unknown>;
+    const url =
+      typeof record.url === 'string' && record.url.length > 0
+        ? record.url
+        : typeof record.image === 'string' && record.image.length > 0
+          ? record.image
+          : null;
+
+    if (!url) {
+      continue;
+    }
+
+    items.push({
+      url,
+      alt: typeof record.alt === 'string' ? record.alt : undefined,
+      caption: typeof record.caption === 'string' ? record.caption : undefined,
+    });
+  }
+
+  return items;
+}
+
 export function getBuilderContentRecord(settings: BuilderSettings): JsonRecord {
   return settings.theme.content;
 }
@@ -35,8 +69,9 @@ export function getBlockSettingValue<T = unknown>(
     return input.fallback;
   }
 
-  if (Object.prototype.hasOwnProperty.call(block.settings, input.path)) {
-    return block.settings[input.path] as T;
+  const resolved = resolveManifestSettingRecordValue(block.settings, input.path);
+  if (resolved !== undefined) {
+    return resolved as T;
   }
 
   const nested = getByDottedPath(block.settings, input.path);

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './manifest-setting-paths.js';
 export * from './preview-fixtures.js';
 export * from './product-page.js';
 export * from './standard-product-page.js';
@@ -8,3 +9,6 @@ export * from './layout.js';
 export * from './react.js';
 export * from './storefront-google-fonts.js';
 export * from './style-slots.js';
+export * from './block-style-settings.js';
+export * from './preview-mode.js';
+export * from './youtube.js';

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-mode.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { isBuilderPreviewMode } from './preview-mode.js';
+
+describe('isBuilderPreviewMode', () => {
+  const previousWindow = globalThis.window;
+
+  afterEach(() => {
+    globalThis.window = previousWindow;
+  });
+
+  test('returns false during SSR without touching window.location', () => {
+    delete (globalThis as { window?: Window }).window;
+
+    expect(isBuilderPreviewMode()).toBe(false);
+  });
+
+  test('reads the provided location search params', () => {
+    expect(isBuilderPreviewMode({ search: '?shoppex-preview-mode=builder' })).toBe(true);
+    expect(isBuilderPreviewMode({ search: '?shoppex-preview-mode=theme' })).toBe(true);
+    expect(isBuilderPreviewMode({ search: '?shoppex-preview-mode=live' })).toBe(false);
+  });
+});

package/src/preview-mode.ts

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

package/src/react.tsx

@@ -27,6 +27,7 @@ import {
   getBuilderContentString,
   getBuilderContentValue,
 } from './content.js';
+import { resolveManifestSettingRecordValue } from './manifest-setting-paths.js';
 import { BUILDER_PREVIEW_REVIEWS } from './preview-fixtures.js';
 import { createBuilderCss } from './css-vars.js';
 import { builderBlock, type BuilderAttributeMap } from './attributes.js';
@@ -542,13 +543,17 @@ 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 resolved = resolveManifestSettingRecordValue(block.settings, path);
+  if (resolved !== undefined) {
+    return resolved;
   }
 
   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];
+  if (shortPath) {
+    const shortResolved = resolveManifestSettingRecordValue(block.settings, shortPath);
+    if (shortResolved !== undefined) {
+      return shortResolved;
+    }
   }
 
   const nested = shortPath ? getNestedBuilderSetting(block.settings, shortPath) : undefined;
@@ -903,6 +908,7 @@ function installBuilderPreviewHoverInspector(): () => void {
           // we keep a small override table for these.
           const SLUG_LABEL_OVERRIDES: Record<string, string> = {
             'custom-html': 'Custom Embed',
+            'youtube-embed': 'YouTube Video',
           };
           const override = SLUG_LABEL_OVERRIDES[type];
           const label = override ?? type
@@ -1271,4 +1277,23 @@ export type {
   StandardProductSettingScope,
   StandardProductTabSpec,
 } from './standard-product-blocks.js';
+export { YouTubeEmbed, YouTubeEmbedPreviewPlaceholder, type YouTubeEmbedProps } from './YouTubeEmbed.js';
+export {
+  YouTubeEmbedBuilderBlock,
+  type YouTubeEmbedBuilderBlockProps,
+} from './YouTubeEmbedBuilderBlock.js';
+export {
+  createMerchantCustomPageRegistry,
+  MerchantCustomPageBuilderView,
+  useMerchantCustomPageRegistry,
+  useMerchantCustomPageView,
+  type MerchantCustomPageRegistryOptions,
+} from './merchant-custom-page.js';
+export { isBuilderPreviewMode } from './preview-mode.js';
+export {
+  getYouTubeEmbedBlockStyleProps,
+  readYouTubeEmbedBlockSettings,
+  type YouTubeEmbedBlockInstance,
+} from './youtube-embed-block.js';
+export { readManifestStyleBlockProps } from './block-style-settings.js';
 export { getBuilderPreviewReviewFixtures } from './preview-fixtures.js';

package/src/youtube-embed-block.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import { readManifestStyleBlockProps } from './block-style-settings.js';
+import {
+  getYouTubeEmbedBlockStyleProps,
+  readYouTubeEmbedBlockSettings,
+} from './youtube-embed-block.js';
+
+describe('readYouTubeEmbedBlockSettings', () => {
+  test('reads url, title, height, and privacy flag from block settings', () => {
+    expect(
+      readYouTubeEmbedBlockSettings({
+        id: 'yt-1',
+        settings: {
+          videoUrl: 'https://youtu.be/dQw4w9WgXcQ',
+          title: 'Launch trailer',
+          height: 480,
+          privacyEnhanced: true,
+        },
+      }),
+    ).toEqual({
+      videoUrl: 'https://youtu.be/dQw4w9WgXcQ',
+      title: 'Launch trailer',
+      height: 480,
+      privacyEnhanced: true,
+    });
+  });
+
+  test('falls back to defaults for missing or invalid values', () => {
+    expect(
+      readYouTubeEmbedBlockSettings({
+        id: 'yt-1',
+        settings: {
+          videoUrl: 42,
+          title: '   ',
+          height: 0,
+        },
+      }),
+    ).toEqual({
+      videoUrl: '',
+      title: 'YouTube video',
+      height: undefined,
+      privacyEnhanced: false,
+    });
+  });
+});
+
+describe('readManifestStyleBlockProps', () => {
+  test('maps manifest style settings to inline styles', () => {
+    expect(
+      readManifestStyleBlockProps({
+        'style.background': '#111111',
+        'style.borderRadius': 12,
+        'style.padding': 16,
+      }),
+    ).toEqual({
+      backgroundColor: '#111111',
+      borderRadius: '12px',
+      padding: '16px',
+    });
+  });
+});
+
+describe('getYouTubeEmbedBlockStyleProps', () => {
+  test('delegates to shared manifest style reader', () => {
+    expect(
+      getYouTubeEmbedBlockStyleProps({
+        id: 'yt-1',
+        settings: {
+          'style.background': '#00000000',
+        },
+      }),
+    ).toEqual({
+      backgroundColor: '#00000000',
+    });
+  });
+});

package/src/youtube-embed-block.ts

@@ -0,0 +1,28 @@
+import type { BlockInstance } from '@shoppex/builder-contracts';
+import { readManifestStyleBlockProps } from './block-style-settings.js';
+
+export type YouTubeEmbedBlockInstance = Pick<BlockInstance, 'id' | 'settings'>;
+
+export function readYouTubeEmbedBlockSettings(block: YouTubeEmbedBlockInstance) {
+  const videoUrl =
+    typeof block.settings.videoUrl === 'string' ? block.settings.videoUrl : '';
+  const title =
+    typeof block.settings.title === 'string' && block.settings.title.trim().length > 0
+      ? block.settings.title.trim()
+      : 'YouTube video';
+  const heightRaw = block.settings.height;
+  const height =
+    typeof heightRaw === 'number' && heightRaw > 0 ? heightRaw : undefined;
+  const privacyEnhanced = block.settings.privacyEnhanced === true;
+
+  return {
+    videoUrl,
+    title,
+    height,
+    privacyEnhanced,
+  };
+}
+
+export function getYouTubeEmbedBlockStyleProps(block: YouTubeEmbedBlockInstance) {
+  return readManifestStyleBlockProps(block.settings);
+}