@shoppexio/builder-contracts 0.1.0

package/src/fields.ts

@@ -0,0 +1,134 @@
+import * as z from 'zod/v4';
+import { ColorSchema } from './style-slots.ts';
+
+const FieldBaseSchema = z
+  .object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    defaultValue: z.unknown().optional(),
+    required: z.boolean().optional(),
+  })
+  .strict();
+
+export const FieldOptionSchema = z
+  .object({
+    label: z.string().min(1),
+    value: z.string().min(1),
+  })
+  .strict();
+export type FieldOption = z.infer<typeof FieldOptionSchema>;
+
+const TextFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('text'),
+  placeholder: z.string().optional(),
+  minLength: z.number().int().nonnegative().optional(),
+  maxLength: z.number().int().positive().optional(),
+}).strict();
+
+const RichTextFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('richtext'),
+  allowedMarks: z.array(z.enum(['bold', 'italic', 'link', 'code'])).optional(),
+}).strict();
+
+const ImageFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('image'),
+  aspectRatio: z.string().min(1).optional(),
+}).strict();
+
+const LinkFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('link'),
+}).strict();
+
+const BooleanFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('boolean'),
+  defaultValue: z.boolean().optional(),
+}).strict();
+
+const NumberFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('number'),
+  defaultValue: z.number().optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  step: z.number().positive().optional(),
+}).strict();
+
+const RangeFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('range'),
+  defaultValue: z.number().optional(),
+  min: z.number(),
+  max: z.number(),
+  step: z.number().positive().optional(),
+  unit: z.string().min(1).optional(),
+}).strict();
+
+const SelectFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('select'),
+  defaultValue: z.string().optional(),
+  options: z.array(FieldOptionSchema).min(1),
+}).strict();
+
+const ColorFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('color'),
+  defaultValue: ColorSchema.optional(),
+}).strict();
+
+const ProductFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('product'),
+}).strict();
+
+const ProductsFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('products'),
+  minItems: z.number().int().nonnegative().optional(),
+  maxItems: z.number().int().positive().optional(),
+}).strict();
+
+export const ListItemFieldTypeSchema = z.enum([
+  'text',
+  'richtext',
+  'image',
+  'link',
+  'boolean',
+  'number',
+  'range',
+  'select',
+  'color',
+  'product',
+]);
+export type ListItemFieldType = z.infer<typeof ListItemFieldTypeSchema>;
+
+export const ListItemFieldSchema = FieldBaseSchema.extend({
+  type: ListItemFieldTypeSchema,
+  options: z.array(FieldOptionSchema).optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  step: z.number().positive().optional(),
+  unit: z.string().min(1).optional(),
+  placeholder: z.string().optional(),
+}).strict();
+export type ListItemField = z.infer<typeof ListItemFieldSchema>;
+
+const ListFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('list'),
+  minItems: z.number().int().nonnegative().optional(),
+  maxItems: z.number().int().positive().optional(),
+  itemShape: z.record(z.string().min(1), ListItemFieldSchema),
+}).strict();
+
+export const BuilderFieldSchema = z.discriminatedUnion('type', [
+  TextFieldSchema,
+  RichTextFieldSchema,
+  ImageFieldSchema,
+  LinkFieldSchema,
+  BooleanFieldSchema,
+  NumberFieldSchema,
+  RangeFieldSchema,
+  SelectFieldSchema,
+  ColorFieldSchema,
+  ProductFieldSchema,
+  ProductsFieldSchema,
+  ListFieldSchema,
+]);
+export type BuilderField = z.infer<typeof BuilderFieldSchema>;
+
+export const BlockSettingsSchema = z.record(z.string().min(1), BuilderFieldSchema);
+export type BlockSettings = z.infer<typeof BlockSettingsSchema>;

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './builder-settings.ts';
+export * from './events.ts';
+export * from './fields.ts';
+export * from './legacy-manifest.ts';
+export * from './migrations.ts';
+export * from './preview-protocol.ts';
+export * from './style-slots.ts';
+export * from './theme-manifest.ts';
+export * from './validation.ts';

package/src/legacy-manifest.ts

@@ -0,0 +1,321 @@
+import * as z from 'zod/v4';
+import { BuilderFieldSchema, type BuilderField } from './fields.ts';
+import { ThemeManifestSchema, type ThemeManifest } from './theme-manifest.ts';
+
+const LegacyFieldOptionSchema = z
+  .object({
+    label: z.string().min(1),
+    value: z.string().min(1),
+  })
+  .passthrough();
+
+export const LegacyBuilderFieldSchema = z
+  .object({
+    path: z.string().min(1),
+    type: z.string().min(1).optional(),
+    label: z.string().min(1),
+    placeholder: z.string().optional(),
+    defaultValue: z.unknown().optional(),
+    description: z.string().optional(),
+    options: z.array(LegacyFieldOptionSchema).optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    step: z.number().positive().optional(),
+  })
+  .passthrough();
+export type LegacyBuilderField = z.infer<typeof LegacyBuilderFieldSchema>;
+
+export const LegacyBuilderListSchema = z
+  .object({
+    path: z.string().min(1),
+    label: z.string().min(1),
+    kind: z.string().min(1),
+    description: z.string().optional(),
+  })
+  .passthrough();
+export type LegacyBuilderList = z.infer<typeof LegacyBuilderListSchema>;
+
+export const LegacyBuilderBlockSchema = z
+  .object({
+    id: z.string().min(1).optional(),
+    label: z.string().min(1),
+    maxInstances: z.number().int().positive().optional(),
+    mountable: z.boolean().optional(),
+    fields: z.array(LegacyBuilderFieldSchema).optional(),
+    lists: z.array(LegacyBuilderListSchema).optional(),
+  })
+  .passthrough();
+export type LegacyBuilderBlock = z.infer<typeof LegacyBuilderBlockSchema>;
+
+export const LegacyBuilderPageSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    previewPath: z.string().min(1).optional(),
+    blocks: z.array(z.string().min(1)).default([]),
+    fields: z.array(LegacyBuilderFieldSchema).optional(),
+    lists: z.array(LegacyBuilderListSchema).optional(),
+  })
+  .passthrough();
+export type LegacyBuilderPage = z.infer<typeof LegacyBuilderPageSchema>;
+
+const LegacyThemePresetSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1).optional(),
+    label: z.string().min(1).optional(),
+    description: z.string().optional(),
+    overrides: z
+      .object({
+        content: z.record(z.string().min(1), z.unknown()).optional(),
+        layout: z.record(z.string().min(1), z.unknown()).optional(),
+        style_slots: z.record(z.string().min(1), z.unknown()).optional(),
+        styleSlots: z.record(z.string().min(1), z.unknown()).optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+export type LegacyThemePreset = z.infer<typeof LegacyThemePresetSchema>;
+
+export const LegacyThemeManifestSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    version: z.string().min(1),
+    presets: z.array(LegacyThemePresetSchema).optional(),
+    builder: z
+      .object({
+        pages: z.array(LegacyBuilderPageSchema).default([]),
+        blocks: z.record(z.string().min(1), LegacyBuilderBlockSchema).default({}),
+        presets: z.record(z.string().min(1), z.unknown()).optional(),
+      })
+      .passthrough(),
+  })
+  .passthrough();
+export type LegacyThemeManifest = z.infer<typeof LegacyThemeManifestSchema>;
+
+export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
+  const legacy = LegacyThemeManifestSchema.parse(input);
+  const blocks = Object.fromEntries(
+    Object.entries(legacy.builder.blocks).map(([blockType, block]) => [
+      blockType,
+      {
+        label: block.label,
+        maxInstances: block.maxInstances,
+        variants: [],
+        settings: convertLegacyFields(block.fields ?? [], block.lists ?? []),
+        exposedStyleSlots: [],
+        presets: [],
+      },
+    ]),
+  );
+
+  for (const page of legacy.builder.pages) {
+    const syntheticBlockType = createSyntheticPageBlockType(page.id);
+    if ((page.fields?.length ?? 0) === 0 && (page.lists?.length ?? 0) === 0) {
+      continue;
+    }
+
+    blocks[syntheticBlockType] = {
+      label: page.label,
+      maxInstances: 1,
+      variants: [],
+      settings: convertLegacyFields(page.fields ?? [], page.lists ?? []),
+      exposedStyleSlots: [],
+      presets: [],
+    };
+  }
+
+  const converted = {
+    id: normalizeLegacyThemeId(legacy.id),
+    name: legacy.name,
+    version: legacy.version,
+    pages: Object.fromEntries(
+      legacy.builder.pages.map((page) => {
+        const syntheticBlockType = createSyntheticPageBlockType(page.id);
+        const hasSyntheticBlock = blocks[syntheticBlockType] !== undefined;
+        const allowedBlocks = page.blocks.length > 0
+          ? page.blocks
+          : (hasSyntheticBlock ? [syntheticBlockType] : []);
+        // Seed synthetic page-level blocks as defaults so pages that
+        // only surface page.fields/lists still open with an editable
+        // block instance instead of an empty editor.
+        const defaultBlocks = page.blocks.length > 0
+          ? page.blocks.map((type) => ({ type }))
+          : (hasSyntheticBlock ? [{ type: syntheticBlockType }] : []);
+        return [
+          page.id,
+          {
+            label: page.label,
+            previewPath: page.previewPath,
+            allowedBlocks,
+            defaultBlocks,
+          },
+        ];
+      }),
+    ),
+    blocks,
+    styleSlots: {},
+    presets: convertLegacyThemePresets(legacy.presets ?? []),
+  };
+
+  return ThemeManifestSchema.parse(converted);
+}
+
+function normalizeLegacyThemeId(rawId: string): string {
+  const lowered = rawId.toLowerCase().replace(/[^a-z0-9\-_.]+/g, '-').replace(/^[-_.]+/, '');
+  if (lowered.length > 0 && /^[a-z0-9]/.test(lowered)) {
+    return lowered;
+  }
+  return `legacy-${lowered || 'theme'}`;
+}
+
+function createSyntheticPageBlockType(pageId: string): string {
+  const normalizedPageId = pageId.toLowerCase().replace(/[^a-z0-9\-_.]+/g, '-').replace(/^[-_.]+/, '');
+  return `page-${normalizedPageId || 'custom'}`;
+}
+
+function convertLegacyThemePresets(presets: LegacyThemePreset[]): ThemeManifest['presets'] {
+  return Object.fromEntries(
+    presets.map((preset) => [
+      preset.id,
+      {
+        label: preset.name ?? preset.label ?? preset.id,
+        description: preset.description,
+        content: flattenContentRecord(preset.overrides?.content ?? {}),
+        layout: preset.overrides?.layout ?? {},
+        style_slots: preset.overrides?.style_slots ?? preset.overrides?.styleSlots ?? {},
+      },
+    ]),
+  );
+}
+
+function flattenContentRecord(content: Record<string, unknown>, prefix = ''): Record<string, unknown> {
+  const flattened: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(content)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) {
+      Object.assign(flattened, flattenContentRecord(value, path));
+    } else {
+      flattened[path] = value;
+    }
+  }
+
+  return flattened;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function convertLegacyFields(fields: LegacyBuilderField[], lists: LegacyBuilderList[]): Record<string, BuilderField> {
+  const convertedFields = Object.fromEntries(
+    fields.map((field) => [field.path, convertLegacyField(field)]),
+  );
+
+  const convertedLists = Object.fromEntries(
+    lists.map((list) => [
+      list.path,
+      {
+        type: 'list',
+        label: list.label,
+        description: list.description,
+        itemShape: createListItemShape(list.kind),
+      } satisfies BuilderField,
+    ]),
+  );
+
+  return {
+    ...convertedFields,
+    ...convertedLists,
+  };
+}
+
+function convertLegacyField(field: LegacyBuilderField): BuilderField {
+  const type = normalizeLegacyFieldType(field.type);
+  const base = {
+    label: field.label,
+    description: field.description,
+    defaultValue: field.defaultValue,
+  };
+
+  const candidate =
+    type === 'select'
+      ? {
+          ...base,
+          type,
+          options: (field.options ?? []).map((option) => ({
+            label: option.label,
+            value: option.value,
+          })),
+        }
+      : type === 'range'
+        ? {
+            ...base,
+            type,
+            min: field.min ?? 0,
+            max: field.max ?? 100,
+            step: field.step,
+          }
+        : type === 'text'
+          ? {
+              ...base,
+              type,
+              placeholder: field.placeholder,
+            }
+        : {
+            ...base,
+            type,
+          };
+
+  return BuilderFieldSchema.parse(candidate);
+}
+
+function normalizeLegacyFieldType(type: string | undefined): BuilderField['type'] {
+  if (
+    type === 'richtext' ||
+    type === 'image' ||
+    type === 'link' ||
+    type === 'boolean' ||
+    type === 'number' ||
+    type === 'range' ||
+    type === 'select' ||
+    type === 'color' ||
+    type === 'product' ||
+    type === 'products'
+  ) {
+    return type;
+  }
+
+  return 'text';
+}
+
+function createListItemShape(kind: string): Extract<BuilderField, { type: 'list' }>['itemShape'] {
+  if (kind === 'faqItems') {
+    return {
+      question: { type: 'text', label: 'Question' },
+      answer: { type: 'richtext', label: 'Answer' },
+    };
+  }
+
+  if (kind === 'galleryItems') {
+    return {
+      image: { type: 'image', label: 'Image' },
+      alt: { type: 'text', label: 'Alt Text' },
+    };
+  }
+
+  if (kind === 'reviewItems') {
+    return {
+      quote: { type: 'richtext', label: 'Quote' },
+      author: { type: 'text', label: 'Author' },
+    };
+  }
+
+  return {
+    title: { type: 'text', label: 'Title' },
+    body: { type: 'richtext', label: 'Body' },
+  };
+}

package/src/migrations.ts

@@ -0,0 +1,240 @@
+import {
+  BUILDER_SETTINGS_VERSION,
+  type BlockInstance,
+  type BuilderSettings,
+  BuilderSettingsSchema,
+  type PageLayout,
+} from './builder-settings.ts';
+import type { StyleSlots } from './style-slots.ts';
+import type { ThemeManifest } from './theme-manifest.ts';
+
+export type LegacyBuilderSettingsInput = {
+  theme?: {
+    content?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    tokens_override?: Record<string, unknown>;
+    style_slots?: Record<string, unknown>;
+  };
+};
+
+export type LegacyRedisOverride = {
+  target?: string;
+  property?: string;
+  value?: unknown;
+  className?: string;
+};
+
+export function createEmptyBuilderSettings(revision = 0): BuilderSettings {
+  return {
+    version: BUILDER_SETTINGS_VERSION,
+    revision,
+    theme: {
+      content: {},
+      layout: {},
+      style_slots: {},
+      pages: [],
+      terms: {},
+    },
+  };
+}
+
+export function createBlockInstance(input: {
+  id: string;
+  type: string;
+  variant?: string;
+  visible?: boolean;
+  settings?: Record<string, unknown>;
+  style_overrides?: StyleSlots;
+}): BlockInstance {
+  return {
+    id: input.id,
+    type: input.type,
+    variant: input.variant,
+    visible: input.visible ?? true,
+    settings: input.settings ?? {},
+    style_overrides: input.style_overrides,
+  };
+}
+
+export function createPageLayoutFromBlocks(blocks: BlockInstance[]): PageLayout {
+  return { blocks };
+}
+
+export function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput, revision = 0): BuilderSettings {
+  const tokensOverride = input.theme?.tokens_override ?? {};
+  const styleSlots = {
+    ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
+    ...(input.theme?.style_slots ?? {}),
+  };
+
+  return BuilderSettingsSchema.parse({
+    version: BUILDER_SETTINGS_VERSION,
+    revision,
+    theme: {
+      content: input.theme?.content ?? {},
+      layout: normalizeLegacyLayout(input.theme?.layout ?? {}),
+      style_slots: styleSlots,
+      pages: [],
+      terms: {},
+    },
+  });
+}
+
+export function applyManifestDefaultLayout(settings: BuilderSettings, manifest: ThemeManifest): BuilderSettings {
+  const next = cloneBuilderSettings(settings);
+
+  for (const [pageId, page] of Object.entries(manifest.pages)) {
+    // Only seed defaults when the page has never been initialized
+    // (no layout entry at all). An explicit empty layout means the
+    // merchant intentionally removed all sections and must be
+    // preserved across reloads.
+    const hasPageLayoutEntry = Object.prototype.hasOwnProperty.call(next.theme.layout, pageId);
+    if (hasPageLayoutEntry || page.defaultBlocks.length === 0) {
+      continue;
+    }
+
+    next.theme.layout[pageId] = {
+      blocks: page.defaultBlocks.map((block, index) => createBlockInstance({
+        id: createDefaultBlockId(pageId, block.type, index),
+        type: block.type,
+        variant: block.variant,
+        settings: block.settings ?? {},
+      })),
+    };
+  }
+
+  return BuilderSettingsSchema.parse(next);
+}
+
+export function mapLegacyTokenOverridesToStyleSlots(tokens: Record<string, unknown>): StyleSlots {
+  const slots: StyleSlots = {};
+
+  assignResponsiveNumber(tokens, slots, 'buttons.borderRadius', 'button.radius');
+  assignResponsiveNumber(tokens, slots, 'inputs.borderRadius', 'input.radius');
+  assignResponsiveNumber(tokens, slots, 'inputs.height', 'input.height');
+  assignColor(tokens, slots, 'colors.primary', 'color.primary');
+  assignColor(tokens, slots, 'colors.accent', 'color.accent');
+  assignColor(tokens, slots, 'colors.background', 'color.background');
+  assignColor(tokens, slots, 'colors.foreground', 'color.foreground');
+  assignColor(tokens, slots, 'colors.muted', 'color.muted');
+
+  return slots;
+}
+
+function normalizeLegacyLayout(layout: Record<string, unknown>): Record<string, PageLayout> {
+  const normalized: Record<string, PageLayout> = {};
+
+  for (const [pageId, value] of Object.entries(layout)) {
+    if (isPageLayout(value)) {
+      normalized[pageId] = value;
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      normalized[pageId] = {
+        blocks: value.filter(isBlockInstance),
+      };
+      continue;
+    }
+
+    // Pre-v2 editor shape: { sections: [...] } with entries that
+    // commonly only carry { id, visible } (no type field). Use id as
+    // the type fallback so merchant layout/visibility survives the
+    // migration instead of being dropped by the stricter
+    // isBlockInstance check.
+    if (value && typeof value === 'object') {
+      const record = value as Record<string, unknown>;
+      const sections = Array.isArray(record.sections) ? record.sections : null;
+      if (sections) {
+        normalized[pageId] = {
+          blocks: sections.flatMap(normalizeLegacySection),
+        };
+      }
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeLegacySection(entry: unknown): BlockInstance[] {
+  if (!entry || typeof entry !== 'object') return [];
+  const record = entry as Record<string, unknown>;
+  const rawType = typeof record.type === 'string' ? record.type.trim() : '';
+  const rawId = typeof record.id === 'string' ? record.id.trim() : '';
+  const type = rawType || rawId;
+  if (!type) return [];
+  return [{
+    id: rawId || type,
+    type,
+    variant: typeof record.variant === 'string' ? record.variant : undefined,
+    visible: typeof record.visible === 'boolean' ? record.visible : true,
+    settings: isRecord(record.settings) ? record.settings : {},
+  }];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function assignResponsiveNumber(
+  tokens: Record<string, unknown>,
+  slots: StyleSlots,
+  tokenPath: string,
+  slotId: keyof StyleSlots,
+): void {
+  const value = tokens[tokenPath];
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    slots[slotId] = { base: value } as never;
+    return;
+  }
+
+  if (isResponsiveNumber(value)) {
+    slots[slotId] = value as never;
+  }
+}
+
+function assignColor(tokens: Record<string, unknown>, slots: StyleSlots, tokenPath: string, slotId: keyof StyleSlots): void {
+  const value = tokens[tokenPath];
+  if (typeof value === 'string') {
+    slots[slotId] = value as never;
+  }
+}
+
+function isResponsiveNumber(value: unknown): value is { base: number; sm?: number; md?: number; lg?: number; xl?: number } {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.base === 'number' && Number.isFinite(candidate.base);
+}
+
+function isBlockInstance(value: unknown): value is BlockInstance {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.id === 'string' && typeof candidate.type === 'string';
+}
+
+function isPageLayout(value: unknown): value is PageLayout {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return Array.isArray(candidate.blocks) && candidate.blocks.every(isBlockInstance);
+}
+
+function cloneBuilderSettings(settings: BuilderSettings): BuilderSettings {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(settings);
+  }
+
+  return JSON.parse(JSON.stringify(settings)) as BuilderSettings;
+}
+
+function createDefaultBlockId(pageId: string, blockType: string, index: number): string {
+  return `${pageId}-${blockType}-${index + 1}`;
+}