@shoppexio/builder-contracts 0.1.0 → 0.1.1

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,33 @@
+export const PUBLIC_BUILDER_THEME_SCHEMES = [
+  'default',
+  'classic',
+  'nebula',
+  'pulse',
+  'phantom',
+  'starlight',
+  'apex',
+  'vault',
+] 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,5 @@
 import type { BlockInstance, BuilderSettings } from './builder-settings.ts';
+import { ThemeStyleSlotIdSchema } from './style-slots.ts';
 import type { ThemeManifest } from './theme-manifest.ts';
 
 export type BuilderManifestValidationIssueCode =
@@ -9,6 +10,7 @@ export type BuilderManifestValidationIssueCode =
   | 'too_many_block_instances'
   | 'unknown_block_variant'
   | 'unknown_block_setting'
+  | 'unknown_style_slot'
   | 'unexposed_style_slot';
 
 export type BuilderManifestValidationIssue = {
@@ -33,6 +35,8 @@ export function validateBuilderSettingsAgainstManifest(
 ): BuilderManifestValidationIssue[] {
   const issues: BuilderManifestValidationIssue[] = [];
 
+  validateGlobalStyleSlots(settings, manifest, issues);
+
   for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
     const page = manifest.pages[pageId];
     if (!page) {
@@ -98,6 +102,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 +156,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 +190,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[],