@shoppexio/builder-contracts 0.1.1 → 0.1.3

package/src/style-slots.ts

@@ -25,9 +25,12 @@ export const ResponsiveStringSchema = z
   .strict();
 export type ResponsiveString = z.infer<typeof ResponsiveStringSchema>;
 
-export const ColorSchema = z
-  .string()
-  .regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, 'Expected a hex color');
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+export const ColorSchema = z.union([
+  z.literal('transparent'),
+  z.string().regex(HEX_COLOR_PATTERN, 'Expected a hex color'),
+]);
 export type Color = z.infer<typeof ColorSchema>;
 
 export const FontWeightSchema = z.union([

package/src/theme-schemes.ts

@@ -7,6 +7,8 @@ export const PUBLIC_BUILDER_THEME_SCHEMES = [
   'starlight',
   'apex',
   'vault',
+  'vortex',
+  'clean-minimal',
 ] as const;
 
 export const STARTER_BUILDER_THEME_SCHEMES = ['blank'] as const;

package/src/validation.ts

@@ -1,4 +1,5 @@
 import type { BlockInstance, BuilderSettings } from './builder-settings.ts';
+import { mergeCustomPagesIntoManifest } from './custom-pages.ts';
 import { ThemeStyleSlotIdSchema } from './style-slots.ts';
 import type { ThemeManifest } from './theme-manifest.ts';
 
@@ -33,12 +34,13 @@ export function validateBuilderSettingsAgainstManifest(
   settings: BuilderSettings,
   manifest: ThemeManifest,
 ): BuilderManifestValidationIssue[] {
+  const effectiveManifest = mergeCustomPagesIntoManifest(manifest, settings);
   const issues: BuilderManifestValidationIssue[] = [];
 
-  validateGlobalStyleSlots(settings, manifest, issues);
+  validateGlobalStyleSlots(settings, effectiveManifest, issues);
 
   for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
-    const page = manifest.pages[pageId];
+    const page = effectiveManifest.pages[pageId];
     if (!page) {
       issues.push({
         code: 'unknown_page',
@@ -63,7 +65,7 @@ export function validateBuilderSettingsAgainstManifest(
       }
       blockIds.add(block.id);
 
-      const blockDefinition = manifest.blocks[block.type];
+      const blockDefinition = effectiveManifest.blocks[block.type];
       if (!blockDefinition) {
         issues.push({
           code: 'unknown_block_type',
@@ -88,7 +90,7 @@ export function validateBuilderSettingsAgainstManifest(
     }
 
     for (const [blockType, count] of blockTypeCounts.entries()) {
-      const maxInstances = manifest.blocks[blockType]?.maxInstances;
+      const maxInstances = effectiveManifest.blocks[blockType]?.maxInstances;
       if (maxInstances !== undefined && count > maxInstances) {
         issues.push({
           code: 'too_many_block_instances',

package/dist/builder-contracts.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=builder-contracts.test.d.ts.map

package/dist/builder-contracts.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builder-contracts.test.d.ts","sourceRoot":"","sources":["../src/builder-contracts.test.ts"],"names":[],"mappings":""}

package/dist/builder-contracts.test.js

@@ -1,431 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { BuilderEventSchema, BuilderSettingsSchema, PreviewResponseSchema, PreviewMessageSchema, StyleSlotsSchema, ThemeManifestSchema, applyManifestDefaultLayout, validateBuilderSettingsAgainstManifest, createBlockInstance, createEmptyBuilderSettings, convertLegacyThemeManifest, migrateLegacyBuilderSettings, } from "./index.js";
-describe('@shoppex/builder-contracts', () => {
-    test('accepts an empty builder settings document', () => {
-        const settings = createEmptyBuilderSettings(7);
-        expect(BuilderSettingsSchema.parse(settings)).toEqual({
-            version: 2,
-            revision: 7,
-            theme: {
-                content: {},
-                layout: {},
-                style_slots: {},
-                pages: [],
-                terms: {},
-            },
-        });
-    });
-    test('rejects unknown style slots', () => {
-        const result = StyleSlotsSchema.safeParse({
-            'button.radius': { base: 10 },
-            'hero.magic.glow': true,
-        });
-        expect(result.success).toBe(false);
-    });
-    test('rejects invalid colors', () => {
-        const result = StyleSlotsSchema.safeParse({
-            'color.primary': 'tomato',
-        });
-        expect(result.success).toBe(false);
-    });
-    test('validates manifest block references', () => {
-        const result = ThemeManifestSchema.safeParse({
-            id: 'default',
-            name: 'Default',
-            version: '2.0.0',
-            pages: {
-                home: {
-                    label: 'Home',
-                    allowedBlocks: ['hero', 'faq'],
-                    defaultBlocks: [{ type: 'hero', variant: 'split' }],
-                },
-            },
-            blocks: {
-                hero: {
-                    label: 'Hero',
-                    variants: [{ id: 'split', label: 'Split' }],
-                    settings: {
-                        title: { type: 'text', label: 'Headline' },
-                    },
-                    exposedStyleSlots: ['button.radius'],
-                },
-            },
-        });
-        expect(result.success).toBe(false);
-    });
-    test('accepts preview APPLY_STATE messages', () => {
-        const settings = createEmptyBuilderSettings(3);
-        const result = PreviewMessageSchema.safeParse({
-            type: 'APPLY_STATE',
-            revision: 3,
-            state: settings,
-        });
-        expect(result.success).toBe(true);
-    });
-    test('accepts preview REQUEST_READY messages', () => {
-        const result = PreviewMessageSchema.safeParse({
-            type: 'REQUEST_READY',
-        });
-        expect(result.success).toBe(true);
-    });
-    test('accepts preview READY health and runtime error responses', () => {
-        expect(PreviewResponseSchema.safeParse({
-            type: 'READY',
-            revision: 3,
-            health: {
-                reactMounted: true,
-                builderRuntimeProvider: true,
-                protocolVersion: 2,
-            },
-        }).success).toBe(true);
-        expect(PreviewResponseSchema.safeParse({
-            type: 'PREVIEW_ERROR',
-            revision: 3,
-            message: 'useBuilderRuntime must be used inside BuilderRuntimeProvider',
-            stack: 'Error: useBuilderRuntime must be used inside BuilderRuntimeProvider',
-            source: 'error',
-        }).success).toBe(true);
-    });
-    test('accepts block add events', () => {
-        const result = BuilderEventSchema.safeParse({
-            id: 'evt_1',
-            type: 'block.add',
-            revision: 4,
-            createdAt: '2026-04-23T10:00:00.000Z',
-            source: 'dashboard',
-            pageId: 'home',
-            block: createBlockInstance({
-                id: 'hero-1',
-                type: 'hero',
-                settings: { title: 'New drop' },
-            }),
-            index: 0,
-        });
-        expect(result.success).toBe(true);
-    });
-    test('migrates legacy content and token overrides', () => {
-        const migrated = migrateLegacyBuilderSettings({
-            theme: {
-                content: {
-                    'hero.title': 'Summer sale',
-                },
-                tokens_override: {
-                    'buttons.borderRadius': 12,
-                    'colors.primary': '#ff5500',
-                },
-            },
-        }, 12);
-        expect(migrated.revision).toBe(12);
-        expect(migrated.theme.content['hero.title']).toBe('Summer sale');
-        expect(migrated.theme.style_slots['button.radius']).toEqual({ base: 12 });
-        expect(migrated.theme.style_slots['color.primary']).toBe('#ff5500');
-    });
-    test('converts legacy theme manifests into the v2 manifest contract', () => {
-        const manifest = convertLegacyThemeManifest({
-            id: 'default',
-            name: 'Default Theme',
-            version: '1.0.0',
-            presets: [
-                {
-                    id: 'gaming',
-                    name: 'Gaming Store',
-                    description: 'Gaming copy preset',
-                    overrides: {
-                        content: {
-                            hero: {
-                                title: 'Instant keys',
-                            },
-                        },
-                    },
-                },
-            ],
-            builder: {
-                pages: [
-                    {
-                        id: 'home',
-                        label: 'Home',
-                        previewPath: '/',
-                        blocks: ['hero', 'faq'],
-                    },
-                    {
-                        id: 'contact-page',
-                        label: 'Contact',
-                        previewPath: '/contact',
-                        blocks: [],
-                        fields: [
-                            { path: 'pages.contact.title', label: 'Title', defaultValue: 'Contact Us' },
-                        ],
-                    },
-                ],
-                blocks: {
-                    hero: {
-                        label: 'Hero',
-                        maxInstances: 1,
-                        fields: [
-                            { path: 'hero.title', label: 'Title' },
-                            {
-                                path: 'hero.style',
-                                type: 'select',
-                                label: 'Hero Style',
-                                options: [{ value: 'split', label: 'Split' }],
-                            },
-                        ],
-                    },
-                    faq: {
-                        label: 'FAQ',
-                        lists: [
-                            { path: 'faq.items', label: 'FAQ Items', kind: 'faqItems' },
-                        ],
-                    },
-                },
-            },
-        });
-        expect(manifest.pages.home.allowedBlocks).toEqual(['hero', 'faq']);
-        expect(manifest.pages.home.defaultBlocks).toEqual([{ type: 'hero' }, { type: 'faq' }]);
-        expect(manifest.blocks.hero.settings['hero.title']).toMatchObject({ type: 'text', label: 'Title' });
-        expect(manifest.blocks.hero.settings['hero.style']).toMatchObject({ type: 'select' });
-        expect(manifest.blocks.faq.settings['faq.items']).toMatchObject({ type: 'list' });
-        expect(manifest.blocks['page-contact-page'].settings['pages.contact.title']).toMatchObject({ type: 'text' });
-        expect(manifest.pages['contact-page'].allowedBlocks).toEqual(['page-contact-page']);
-        expect(manifest.presets.gaming).toMatchObject({
-            label: 'Gaming Store',
-            description: 'Gaming copy preset',
-            content: {
-                'hero.title': 'Instant keys',
-            },
-        });
-    });
-    test('applies manifest default blocks to empty builder settings', () => {
-        const settings = applyManifestDefaultLayout(createEmptyBuilderSettings(2), {
-            id: 'default',
-            name: 'Default',
-            version: '2.0.0',
-            pages: {
-                home: {
-                    label: 'Home',
-                    allowedBlocks: ['hero', 'faq'],
-                    defaultBlocks: [{ type: 'hero' }, { type: 'faq' }],
-                },
-            },
-            blocks: {
-                hero: { label: 'Hero', settings: {}, variants: [], exposedStyleSlots: [], presets: [] },
-                faq: { label: 'FAQ', settings: {}, variants: [], exposedStyleSlots: [], presets: [] },
-            },
-            styleSlots: {},
-            presets: {},
-        });
-        expect(settings.theme.layout.home.blocks.map((block) => block.type)).toEqual(['hero', 'faq']);
-        expect(settings.theme.layout.home.blocks.map((block) => block.id)).toEqual(['home-hero-1', 'home-faq-2']);
-    });
-    test('applies default layout for converted page-level fields', () => {
-        const manifest = convertLegacyThemeManifest({
-            id: 'classic',
-            name: 'Classic',
-            version: '1.0.0',
-            builder: {
-                pages: [
-                    {
-                        id: 'faq-page',
-                        label: 'FAQ',
-                        previewPath: '/faq',
-                        fields: [
-                            { path: 'pages.faq.title', label: 'Title', defaultValue: 'Questions' },
-                        ],
-                    },
-                ],
-                blocks: {},
-            },
-        });
-        const settings = applyManifestDefaultLayout(createEmptyBuilderSettings(0), manifest);
-        expect(settings.theme.layout['faq-page'].blocks).toHaveLength(1);
-        expect(settings.theme.layout['faq-page'].blocks[0]).toMatchObject({
-            id: 'faq-page-page-faq-page-1',
-            type: 'page-faq-page',
-            visible: true,
-        });
-    });
-    test('validates builder settings against the active manifest', () => {
-        const settings = BuilderSettingsSchema.parse({
-            version: 2,
-            revision: 1,
-            theme: {
-                content: {},
-                layout: {
-                    home: {
-                        blocks: [
-                            {
-                                id: 'hero-1',
-                                type: 'hero',
-                                variant: 'missing',
-                                visible: true,
-                                settings: {
-                                    'hero.title': 'Launch sale',
-                                    title: 'Launch sale',
-                                    'hero.magic': 'not declared',
-                                },
-                                style_overrides: {
-                                    'input.radius': { base: 10 },
-                                },
-                            },
-                            { id: 'hero-2', type: 'hero', visible: true, settings: {} },
-                            { id: 'hero-2', type: 'faq', visible: true, settings: {} },
-                            { id: 'ghost-1', type: 'ghost', visible: true, settings: {} },
-                        ],
-                    },
-                    checkout: {
-                        blocks: [],
-                    },
-                },
-                style_slots: {},
-                pages: [],
-                terms: {},
-            },
-        });
-        const issues = validateBuilderSettingsAgainstManifest(settings, {
-            id: 'default',
-            name: 'Default',
-            version: '2.0.0',
-            pages: {
-                home: {
-                    label: 'Home',
-                    allowedBlocks: ['hero'],
-                    defaultBlocks: [{ type: 'hero' }],
-                },
-            },
-            blocks: {
-                hero: {
-                    label: 'Hero',
-                    settings: {
-                        'hero.title': { type: 'text', label: 'Title' },
-                    },
-                    variants: [{ id: 'split', label: 'Split' }],
-                    exposedStyleSlots: ['button.radius'],
-                    maxInstances: 1,
-                    presets: [],
-                },
-                faq: {
-                    label: 'FAQ',
-                    settings: {},
-                    variants: [],
-                    exposedStyleSlots: [],
-                    presets: [],
-                },
-            },
-            styleSlots: {},
-            presets: {},
-        });
-        expect(issues.map((issue) => issue.code)).toContain('unknown_page');
-        expect(issues.map((issue) => issue.code)).toContain('duplicate_block_id');
-        expect(issues.map((issue) => issue.code)).toContain('unknown_block_type');
-        expect(issues.map((issue) => issue.code)).toContain('block_not_allowed');
-        expect(issues.map((issue) => issue.code)).toContain('too_many_block_instances');
-        expect(issues.map((issue) => issue.code)).toContain('unknown_block_variant');
-        expect(issues.map((issue) => issue.code)).toContain('unknown_block_setting');
-        expect(issues.map((issue) => issue.code)).toContain('unexposed_style_slot');
-    });
-    test('accepts full and short block setting keys declared by the manifest', () => {
-        const settings = BuilderSettingsSchema.parse({
-            version: 2,
-            revision: 1,
-            theme: {
-                content: {},
-                layout: {
-                    home: {
-                        blocks: [
-                            {
-                                id: 'hero-1',
-                                type: 'hero',
-                                visible: true,
-                                settings: {
-                                    'hero.title': 'Launch sale',
-                                    title: 'Launch sale',
-                                },
-                            },
-                        ],
-                    },
-                },
-                style_slots: {},
-                pages: [],
-                terms: {},
-            },
-        });
-        const issues = validateBuilderSettingsAgainstManifest(settings, {
-            id: 'default',
-            name: 'Default',
-            version: '2.0.0',
-            pages: {
-                home: {
-                    label: 'Home',
-                    allowedBlocks: ['hero'],
-                    defaultBlocks: [{ type: 'hero' }],
-                },
-            },
-            blocks: {
-                hero: {
-                    label: 'Hero',
-                    settings: {
-                        'hero.title': { type: 'text', label: 'Title' },
-                    },
-                    variants: [],
-                    exposedStyleSlots: [],
-                    presets: [],
-                },
-            },
-            styleSlots: {},
-            presets: {},
-        });
-        expect(issues).toEqual([]);
-    });
-    test('accepts block-prefixed setting keys when the manifest declares short block fields', () => {
-        const settings = BuilderSettingsSchema.parse({
-            version: 2,
-            revision: 1,
-            theme: {
-                content: {},
-                layout: {
-                    home: {
-                        blocks: [
-                            {
-                                id: 'home-hero-1',
-                                type: 'hero',
-                                visible: true,
-                                settings: {
-                                    'hero.title': 'Launch sale',
-                                },
-                            },
-                        ],
-                    },
-                },
-                style_slots: {},
-                pages: [],
-                terms: {},
-            },
-        });
-        const issues = validateBuilderSettingsAgainstManifest(settings, {
-            id: 'starlight',
-            name: 'Starlight',
-            version: '1.0.0',
-            pages: {
-                home: {
-                    label: 'Home',
-                    allowedBlocks: ['hero'],
-                    defaultBlocks: [{ type: 'hero' }],
-                },
-            },
-            blocks: {
-                hero: {
-                    label: 'Hero',
-                    settings: {
-                        title: { type: 'text', label: 'Title' },
-                    },
-                    variants: [],
-                    exposedStyleSlots: [],
-                    presets: [],
-                },
-            },
-            styleSlots: {},
-            presets: {},
-        });
-        expect(issues).toEqual([]);
-    });
-});