@shoppexio/builder-contracts 0.1.0 → 0.1.2

package/src/storefront-typography-fonts.ts

@@ -0,0 +1,108 @@
+export type StorefrontCuratedFont = {
+  value: string;
+  label: string;
+  stack: string;
+};
+
+export const STOREFRONT_SYSTEM_FONTS = new Set(['Arial', 'Georgia', 'System UI']);
+
+export const STOREFRONT_CURATED_FONTS: StorefrontCuratedFont[] = [
+  { value: 'Inter', label: 'Inter', stack: 'Inter, system-ui, sans-serif' },
+  { value: 'Geist', label: 'Geist', stack: 'Geist, system-ui, sans-serif' },
+  { value: 'Manrope', label: 'Manrope', stack: 'Manrope, system-ui, sans-serif' },
+  {
+    value: 'Plus Jakarta Sans',
+    label: 'Plus Jakarta Sans',
+    stack: '"Plus Jakarta Sans", system-ui, sans-serif',
+  },
+  { value: 'DM Sans', label: 'DM Sans', stack: '"DM Sans", system-ui, sans-serif' },
+  {
+    value: 'Space Grotesk',
+    label: 'Space Grotesk',
+    stack: '"Space Grotesk", system-ui, sans-serif',
+  },
+  { value: 'Sora', label: 'Sora', stack: 'Sora, system-ui, sans-serif' },
+  {
+    value: 'IBM Plex Sans',
+    label: 'IBM Plex Sans',
+    stack: '"IBM Plex Sans", system-ui, sans-serif',
+  },
+  { value: 'Arial', label: 'Arial', stack: 'Arial, sans-serif' },
+  { value: 'Georgia', label: 'Georgia', stack: 'Georgia, serif' },
+  { value: 'System UI', label: 'System UI', stack: 'system-ui, sans-serif' },
+];
+
+const GOOGLE_FONT_FAMILY_PATTERN = /^[A-Za-z0-9 +\-_]+$/;
+
+export function resolvePrimaryFontFamilyName(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  const exact = STOREFRONT_CURATED_FONTS.find(
+    (font) => font.value === trimmed || font.stack === trimmed,
+  );
+  if (exact) return exact.value;
+
+  const prefix = STOREFRONT_CURATED_FONTS.find((font) => trimmed.startsWith(`${font.value},`));
+  if (prefix) return prefix.value;
+
+  const quoted = trimmed.match(/^["'](.+?)["']/);
+  if (quoted?.[1]) {
+    return quoted[1].trim() || null;
+  }
+
+  const primary = trimmed.split(',')[0]?.trim();
+  return primary && primary.length > 0 ? primary : null;
+}
+
+export function resolveCuratedFontValue(raw: unknown, fallback: string): string {
+  return resolvePrimaryFontFamilyName(raw) ?? fallback;
+}
+
+export function curatedFontOptionsForValue(value: string): StorefrontCuratedFont[] {
+  if (STOREFRONT_CURATED_FONTS.some((font) => font.value === value)) {
+    return STOREFRONT_CURATED_FONTS;
+  }
+
+  return [
+    ...STOREFRONT_CURATED_FONTS,
+    {
+      value,
+      label: value,
+      stack: value.includes(',') ? value : `${value}, system-ui, sans-serif`,
+    },
+  ];
+}
+
+export function findStorefrontCuratedFont(value: string): StorefrontCuratedFont | undefined {
+  return curatedFontOptionsForValue(value).find((font) => font.value === value);
+}
+
+export function isValidGoogleFontFamily(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  return trimmed.length > 0 && trimmed.length <= 60 && GOOGLE_FONT_FAMILY_PATTERN.test(trimmed);
+}
+
+export function buildStorefrontGoogleFontHref(family: string): string {
+  const familyParam = family.trim().replace(/\s+/g, '+');
+  return `https://fonts.googleapis.com/css2?family=${familyParam}:wght@400;500;600;700&display=swap`;
+}
+
+export function getStorefrontGoogleFontHrefs(input: {
+  bodyFont?: unknown;
+  headingFont?: unknown;
+}): string[] {
+  const families = new Set<string>();
+
+  for (const raw of [input.bodyFont, input.headingFont]) {
+    const family = resolvePrimaryFontFamilyName(raw);
+    if (!family) continue;
+    if (STOREFRONT_SYSTEM_FONTS.has(family)) continue;
+    if (!isValidGoogleFontFamily(family)) continue;
+    families.add(family);
+  }
+
+  return [...families].map((family) => buildStorefrontGoogleFontHref(family));
+}

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([
@@ -43,7 +46,7 @@ export const FontWeightSchema = z.union([
 ]);
 export type FontWeight = z.infer<typeof FontWeightSchema>;
 
-export const StyleSlotIdSchema = z.enum([
+export const CoreStyleSlotIdSchema = z.enum([
   'button.radius',
   'button.background',
   'button.foreground',
@@ -69,39 +72,104 @@ export const StyleSlotIdSchema = z.enum([
   'typography.heading.weight',
   'typography.body.size',
 ]);
-export type StyleSlotId = z.infer<typeof StyleSlotIdSchema>;
+export type CoreStyleSlotId = z.infer<typeof CoreStyleSlotIdSchema>;
+
+export const ThemeStyleSlotIdSchema = z
+  .string()
+  .regex(/^theme\.[a-z0-9][a-z0-9._-]*$/, 'Expected a theme-scoped style slot id');
+export type ThemeStyleSlotId = `theme.${string}`;
+
+export const StyleSlotIdSchema = z.union([CoreStyleSlotIdSchema, ThemeStyleSlotIdSchema]);
+export type StyleSlotId = CoreStyleSlotId | ThemeStyleSlotId;
+
+export const CORE_STYLE_SLOT_IDS = CoreStyleSlotIdSchema.options;
+
+export const ThemeStyleSlotValueSchema = z.union([
+  ColorSchema,
+  ResponsiveNumberSchema,
+  ResponsiveStringSchema,
+  FontWeightSchema,
+  z.string().min(1),
+  z.number().finite(),
+  z.boolean(),
+]);
+export type ThemeStyleSlotValue = z.infer<typeof ThemeStyleSlotValueSchema>;
+
+export type StyleSlotValue =
+  | Color
+  | ResponsiveNumber
+  | ResponsiveString
+  | FontWeight
+  | string
+  | number
+  | boolean;
 
-export const CORE_STYLE_SLOT_IDS = StyleSlotIdSchema.options;
+const CORE_STYLE_SLOT_SCHEMAS: Record<CoreStyleSlotId, z.ZodType<unknown>> = {
+  'button.radius': ResponsiveNumberSchema,
+  'button.background': ColorSchema,
+  'button.foreground': ColorSchema,
+  'button.border': ColorSchema,
+  'button.font.weight': FontWeightSchema,
+  'input.radius': ResponsiveNumberSchema,
+  'input.height': ResponsiveNumberSchema,
+  'input.border': ColorSchema,
+  'input.background': ColorSchema,
+  'input.foreground': ColorSchema,
+  'card.radius': ResponsiveNumberSchema,
+  'card.background': ColorSchema,
+  'card.border': ColorSchema,
+  'section.padding.y': ResponsiveNumberSchema,
+  'section.padding.x': ResponsiveNumberSchema,
+  'container.width': ResponsiveNumberSchema,
+  'color.primary': ColorSchema,
+  'color.accent': ColorSchema,
+  'color.background': ColorSchema,
+  'color.foreground': ColorSchema,
+  'color.muted': ColorSchema,
+  'link.color': ColorSchema,
+  'typography.heading.weight': FontWeightSchema,
+  'typography.body.size': ResponsiveNumberSchema,
+};
+
+export type StyleSlots = Partial<Record<StyleSlotId, StyleSlotValue>>;
 
 export const StyleSlotsSchema = z
-  .object({
-    'button.radius': ResponsiveNumberSchema.optional(),
-    'button.background': ColorSchema.optional(),
-    'button.foreground': ColorSchema.optional(),
-    'button.border': ColorSchema.optional(),
-    'button.font.weight': FontWeightSchema.optional(),
-    'input.radius': ResponsiveNumberSchema.optional(),
-    'input.height': ResponsiveNumberSchema.optional(),
-    'input.border': ColorSchema.optional(),
-    'input.background': ColorSchema.optional(),
-    'input.foreground': ColorSchema.optional(),
-    'card.radius': ResponsiveNumberSchema.optional(),
-    'card.background': ColorSchema.optional(),
-    'card.border': ColorSchema.optional(),
-    'section.padding.y': ResponsiveNumberSchema.optional(),
-    'section.padding.x': ResponsiveNumberSchema.optional(),
-    'container.width': ResponsiveNumberSchema.optional(),
-    'color.primary': ColorSchema.optional(),
-    'color.accent': ColorSchema.optional(),
-    'color.background': ColorSchema.optional(),
-    'color.foreground': ColorSchema.optional(),
-    'color.muted': ColorSchema.optional(),
-    'link.color': ColorSchema.optional(),
-    'typography.heading.weight': FontWeightSchema.optional(),
-    'typography.body.size': ResponsiveNumberSchema.optional(),
-  })
-  .strict();
-export type StyleSlots = z.infer<typeof StyleSlotsSchema>;
+  .record(z.string().min(1), z.unknown())
+  .superRefine((slots, ctx) => {
+    for (const [slotId, value] of Object.entries(slots)) {
+      const coreSlotId = CoreStyleSlotIdSchema.safeParse(slotId);
+      if (coreSlotId.success) {
+        const parsedValue = CORE_STYLE_SLOT_SCHEMAS[coreSlotId.data].safeParse(value);
+        if (!parsedValue.success) {
+          ctx.addIssue({
+            code: 'custom',
+            path: [slotId],
+            message: `Invalid value for core style slot "${slotId}"`,
+          });
+        }
+        continue;
+      }
+
+      const themeSlotId = ThemeStyleSlotIdSchema.safeParse(slotId);
+      if (!themeSlotId.success) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [slotId],
+          message: `Unknown style slot "${slotId}"`,
+        });
+        continue;
+      }
+
+      const parsedThemeValue = ThemeStyleSlotValueSchema.safeParse(value);
+      if (!parsedThemeValue.success) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [slotId],
+          message: `Invalid value for theme style slot "${slotId}"`,
+        });
+      }
+    }
+  }) as z.ZodType<StyleSlots>;
 
 export const StyleSlotDefaultsSchema = StyleSlotsSchema;
 export type StyleSlotDefaults = StyleSlots;

package/src/theme-manifest.ts

@@ -1,6 +1,6 @@
 import * as z from 'zod/v4';
 import { BlockSettingsSchema } from './fields.ts';
-import { StyleSlotDefaultsSchema, StyleSlotIdSchema } from './style-slots.ts';
+import { StyleSlotDefaultsSchema, StyleSlotIdSchema, type StyleSlotDefaults } from './style-slots.ts';
 
 export const ThemeIdSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_.]*$/);
 export type ThemeId = z.infer<typeof ThemeIdSchema>;
@@ -62,6 +62,7 @@ export const ThemePresetSchema = z
   .object({
     label: z.string().min(1),
     description: z.string().min(1).optional(),
+    preview: z.string().min(1).optional(),
     content: z.record(z.string().min(1), z.unknown()).default({}),
     layout: z.record(z.string().min(1), z.unknown()).default({}),
     style_slots: StyleSlotDefaultsSchema.default({}),
@@ -69,15 +70,63 @@ export const ThemePresetSchema = z
   .strict();
 export type ThemePreset = z.infer<typeof ThemePresetSchema>;
 
+export const ThemeManifestMetadataSchema = z
+  .object({
+    author: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    preview: z.string().min(1).optional(),
+    features: z.array(z.string().min(1)).optional(),
+    techStack: z.array(z.string().min(1)).optional(),
+    templates: z.array(z.string().min(1)).optional(),
+    createdAt: z.string().min(1).optional(),
+    demoUrl: z.string().min(1).optional(),
+    audience: z.string().min(1).optional(),
+    tags: z.array(z.string().min(1)).optional(),
+    hotfixPaths: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+export type ThemeManifestMetadata = z.infer<typeof ThemeManifestMetadataSchema>;
+
+export const ThemeManifestLinkGroupSchema = z
+  .object({
+    path: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    pageIds: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+export type ThemeManifestLinkGroup = z.infer<typeof ThemeManifestLinkGroupSchema>;
+
+export const ThemeManifestLinkItemSchema = z
+  .object({
+    label: z.string().min(1),
+    href: z.string().min(1),
+  })
+  .strict();
+export type ThemeManifestLinkItem = z.infer<typeof ThemeManifestLinkItemSchema>;
+
 export const ThemeManifestSchema = z
   .object({
     id: ThemeIdSchema,
     name: z.string().min(1),
     version: z.string().min(1),
+    author: ThemeManifestMetadataSchema.shape.author,
+    description: ThemeManifestMetadataSchema.shape.description,
+    preview: ThemeManifestMetadataSchema.shape.preview,
+    features: ThemeManifestMetadataSchema.shape.features,
+    techStack: ThemeManifestMetadataSchema.shape.techStack,
+    templates: ThemeManifestMetadataSchema.shape.templates,
+    createdAt: ThemeManifestMetadataSchema.shape.createdAt,
+    demoUrl: ThemeManifestMetadataSchema.shape.demoUrl,
+    audience: ThemeManifestMetadataSchema.shape.audience,
+    tags: ThemeManifestMetadataSchema.shape.tags,
+    hotfixPaths: ThemeManifestMetadataSchema.shape.hotfixPaths,
     pages: z.record(z.string().min(1), ManifestPageSchema),
     blocks: z.record(z.string().min(1), ManifestBlockSchema),
     styleSlots: StyleSlotDefaultsSchema.default({}),
     presets: z.record(z.string().min(1), ThemePresetSchema).default({}),
+    linkGroups: z.array(ThemeManifestLinkGroupSchema).optional(),
+    defaultLinkItems: z.record(z.string().min(1), z.array(ThemeManifestLinkItemSchema)).optional(),
   })
   .strict()
   .superRefine((manifest, ctx) => {
@@ -138,3 +187,71 @@ export type ThemeManifest = z.infer<typeof ThemeManifestSchema>;
 export function parseThemeManifest(input: unknown): ThemeManifest {
   return ThemeManifestSchema.parse(input);
 }
+
+export type ThemeManifestPresetListItem = {
+  id: string;
+  name: string;
+  description?: string;
+  preview?: string;
+  overrides: {
+    content?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    tokens?: Record<string, unknown>;
+    style_slots?: StyleSlotDefaults;
+  };
+};
+
+export function listThemeManifestPresets(input: unknown): ThemeManifestPresetListItem[] {
+  if (!isRecord(input) || !isRecord(input.presets)) {
+    if (isRecord(input) && Array.isArray(input.presets)) {
+      return input.presets.flatMap((preset) => normalizeLegacyPresetListItem(preset));
+    }
+    return [];
+  }
+
+  const manifest = ThemeManifestSchema.safeParse(input);
+  if (!manifest.success) {
+    return [];
+  }
+
+  return Object.entries(manifest.data.presets).map(([id, preset]) => ({
+    id,
+    name: preset.label,
+    ...(preset.description ? { description: preset.description } : {}),
+    ...(preset.preview ? { preview: preset.preview } : {}),
+    overrides: {
+      ...(Object.keys(preset.content).length > 0 ? { content: preset.content } : {}),
+      ...(Object.keys(preset.layout).length > 0 ? { layout: preset.layout } : {}),
+      ...(Object.keys(preset.style_slots).length > 0 ? { style_slots: preset.style_slots } : {}),
+    },
+  }));
+}
+
+function normalizeLegacyPresetListItem(input: unknown): ThemeManifestPresetListItem[] {
+  if (!isRecord(input) || typeof input.id !== 'string') {
+    return [];
+  }
+
+  const overrides = isRecord(input.overrides) ? input.overrides : {};
+  const styleSlots = StyleSlotDefaultsSchema.safeParse(overrides.style_slots ?? overrides.styleSlots);
+  return [{
+    id: input.id,
+    name: typeof input.name === 'string'
+      ? input.name
+      : typeof input.label === 'string'
+        ? input.label
+        : input.id,
+    ...(typeof input.description === 'string' ? { description: input.description } : {}),
+    ...(typeof input.preview === 'string' ? { preview: input.preview } : {}),
+    overrides: {
+      ...(isRecord(overrides.content) ? { content: overrides.content } : {}),
+      ...(isRecord(overrides.layout) ? { layout: overrides.layout } : {}),
+      ...(isRecord(overrides.tokens) ? { tokens: overrides.tokens } : {}),
+      ...(styleSlots.success && Object.keys(styleSlots.data).length > 0 ? { style_slots: styleSlots.data } : {}),
+    },
+  }];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/theme-schemes.ts

@@ -0,0 +1,34 @@
+export const PUBLIC_BUILDER_THEME_SCHEMES = [
+  'default',
+  'classic',
+  'nebula',
+  'pulse',
+  'phantom',
+  'starlight',
+  'apex',
+  'vault',
+  'clean-minimal',
+] as const;
+
+export const STARTER_BUILDER_THEME_SCHEMES = ['blank'] as const;
+
+export const BUILDER_READY_THEME_SCHEMES = [
+  ...STARTER_BUILDER_THEME_SCHEMES,
+  ...PUBLIC_BUILDER_THEME_SCHEMES,
+] as const;
+
+export type PublicBuilderThemeScheme = (typeof PUBLIC_BUILDER_THEME_SCHEMES)[number];
+export type StarterBuilderThemeScheme = (typeof STARTER_BUILDER_THEME_SCHEMES)[number];
+export type BuilderReadyThemeScheme = (typeof BUILDER_READY_THEME_SCHEMES)[number];
+
+export function isPublicBuilderThemeScheme(value: string): value is PublicBuilderThemeScheme {
+  return (PUBLIC_BUILDER_THEME_SCHEMES as readonly string[]).includes(value);
+}
+
+export function isStarterBuilderThemeScheme(value: string): value is StarterBuilderThemeScheme {
+  return (STARTER_BUILDER_THEME_SCHEMES as readonly string[]).includes(value);
+}
+
+export function isBuilderReadyThemeScheme(value: string): value is BuilderReadyThemeScheme {
+  return (BUILDER_READY_THEME_SCHEMES as readonly string[]).includes(value);
+}

package/src/validation.ts

@@ -1,4 +1,6 @@
 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';
 
 export type BuilderManifestValidationIssueCode =
@@ -9,6 +11,7 @@ export type BuilderManifestValidationIssueCode =
   | 'too_many_block_instances'
   | 'unknown_block_variant'
   | 'unknown_block_setting'
+  | 'unknown_style_slot'
   | 'unexposed_style_slot';
 
 export type BuilderManifestValidationIssue = {
@@ -31,10 +34,13 @@ export function validateBuilderSettingsAgainstManifest(
   settings: BuilderSettings,
   manifest: ThemeManifest,
 ): BuilderManifestValidationIssue[] {
+  const effectiveManifest = mergeCustomPagesIntoManifest(manifest, settings);
   const issues: BuilderManifestValidationIssue[] = [];
 
+  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',
@@ -59,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',
@@ -84,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',
@@ -98,6 +104,28 @@ export function validateBuilderSettingsAgainstManifest(
   return issues;
 }
 
+function validateGlobalStyleSlots(
+  settings: BuilderSettings,
+  manifest: ThemeManifest,
+  issues: BuilderManifestValidationIssue[],
+): void {
+  const declaredThemeSlots = new Set(Object.keys(manifest.styleSlots));
+
+  for (const slotId of Object.keys(settings.theme.style_slots)) {
+    if (!ThemeStyleSlotIdSchema.safeParse(slotId).success) {
+      continue;
+    }
+
+    if (!declaredThemeSlots.has(slotId)) {
+      issues.push({
+        code: 'unknown_style_slot',
+        path: `theme.style_slots.${slotId}`,
+        message: `Theme style slot "${slotId}" is not declared by the manifest`,
+      });
+    }
+  }
+}
+
 export function assertBuilderSettingsMatchManifest(
   settings: BuilderSettings,
   manifest: ThemeManifest,
@@ -130,11 +158,7 @@ function validateBlockSettings(
     return;
   }
 
-  const allowedSettings = new Set<string>();
-  for (const path of settingPaths) {
-    allowedSettings.add(path);
-    allowedSettings.add(getShortSettingKey(path));
-  }
+  const allowedSettings = new Set(settingPaths);
 
   for (const key of Object.keys(block.settings)) {
     if (allowedSettings.has(key)) {
@@ -168,11 +192,6 @@ function validateBlockVariant(
   }
 }
 
-function getShortSettingKey(path: string): string {
-  const parts = path.split('.').filter(Boolean);
-  return parts.at(-1) ?? path;
-}
-
 function validateBlockStyleOverrides(
   block: BlockInstance,
   exposedStyleSlots: string[],

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":""}