@shoppexio/builder-contracts 0.1.0

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

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

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

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

package/dist/builder-contracts.test.js

@@ -0,0 +1,361 @@
+import { describe, expect, test } from 'bun:test';
+import { BuilderEventSchema, BuilderSettingsSchema, 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 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([]);
+    });
+});