meno-core 1.0.0

package/lib/shared/validation/schemas.ts

@@ -0,0 +1,401 @@
+/**
+ * Validation Schemas
+ * Zod schemas for runtime validation of JSON data structures
+ * All schemas use .passthrough() to maintain backward compatibility with unknown fields
+ *
+ * Note: Node type definitions also define their own schemas for TypeScript type inference.
+ * The schemas here are the authoritative source for VALIDATION (with proper recursive
+ * ComponentNode references). Node type files use simplified schemas for type inference.
+ */
+
+import { z } from 'zod';
+import type { StyleObject, StyleMapping, LinkMapping } from '../types/styles';
+import { NODE_TYPE } from '../constants';
+
+/**
+ * Prop type schema - validates PropType values
+ */
+export const PropTypeSchema = z.enum(['string', 'select', 'boolean', 'number', 'link', 'file']);
+
+/**
+ * Prop definition schema
+ * Validates prop definitions from component interfaces
+ */
+export const PropDefinitionSchema = z.object({
+  type: PropTypeSchema,
+  default: z.union([z.string(), z.number(), z.boolean(), z.object({ href: z.string(), target: z.string().optional() })]).optional(),
+  options: z.array(z.string()).readonly().optional(),
+  accept: z.string().optional(), // For 'file' type: MIME pattern like "image/*", "video/*"
+}).passthrough();
+
+/**
+ * Style mapping schema
+ */
+export const StyleMappingSchema: z.ZodType<StyleMapping> = z.object({
+  _mapping: z.literal(true),
+  prop: z.string(),
+  values: z.record(z.string(), z.union([z.string(), z.number()])),
+}).passthrough();
+
+/**
+ * Link mapping schema - for object-link href mappings
+ * values is optional - when missing, acts as passthrough for link-type props
+ */
+export const LinkMappingSchema: z.ZodType<LinkMapping> = z.object({
+  _mapping: z.literal(true),
+  prop: z.string(),
+  values: z.record(z.string(), z.object({
+    href: z.string(),
+    target: z.string().optional(),
+  })).optional(),
+}).passthrough();
+
+/**
+ * Style object schema - flat style object
+ */
+export const StyleObjectSchema: z.ZodType<StyleObject> = z.record(
+  z.string(),
+  z.union([
+    z.string(),
+    z.number(),
+    StyleMappingSchema,
+  ])
+);
+
+/**
+ * Responsive style object schema
+ */
+export const ResponsiveStyleObjectSchema = z.object({
+  base: StyleObjectSchema.optional(),
+  tablet: StyleObjectSchema.optional(),
+  mobile: StyleObjectSchema.optional(),
+}).passthrough();
+
+/**
+ * Style value schema - can be either flat or responsive
+ */
+export const StyleValueSchema = z.union([
+  StyleObjectSchema,
+  ResponsiveStyleObjectSchema,
+]);
+
+// ============================================================================
+// Node Type Schemas (Validation)
+// These schemas handle proper recursive validation with ComponentNode references.
+// Node type files also have schemas for TypeScript type inference.
+// ============================================================================
+
+/**
+ * Slot marker schema
+ */
+export const SlotMarkerSchema = z.object({
+  type: z.literal(NODE_TYPE.SLOT),
+}).passthrough();
+
+/**
+ * Component node schema - discriminated union (forward declaration)
+ * Uses z.ZodType<any> because schema is more permissive than TypeScript types
+ */
+let ComponentNodeSchema: z.ZodType<any>;
+
+/**
+ * HTML node schema - recursive definition
+ */
+export const HtmlNodeSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.literal(NODE_TYPE.NODE),
+  tag: z.string(),
+  style: StyleValueSchema.optional(),
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  props: z.record(z.string(), z.any()).optional(), // Allow props for backward compatibility
+  children: z.union([
+    z.array(z.union([ComponentNodeSchema, z.string()])),
+    z.string(),
+  ]).optional(),
+}).passthrough());
+
+/**
+ * Component instance node schema - recursive definition
+ */
+export const ComponentInstanceNodeSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.literal(NODE_TYPE.COMPONENT),
+  component: z.string(),
+  props: z.record(z.string(), z.any()).optional(),
+  style: StyleValueSchema.optional(),
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  children: z.union([
+    z.array(z.union([ComponentNodeSchema, z.string()])),
+    z.string(),
+  ]).optional(),
+}).passthrough());
+
+/**
+ * Embed node schema - for rendering custom HTML/SVG content
+ */
+export const EmbedNodeSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.literal(NODE_TYPE.EMBED),
+  html: z.string(),
+  style: StyleValueSchema.optional(),
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+}).passthrough());
+
+/**
+ * Object link node schema - renders as div in editor, <a> in SSR
+ */
+export const ObjectLinkNodeSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.literal(NODE_TYPE.OBJECT_LINK),
+  href: z.union([z.string(), LinkMappingSchema]),
+  style: StyleValueSchema.optional(),
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  children: z.union([
+    z.array(z.union([ComponentNodeSchema, z.string()])),
+    z.string(),
+  ]).optional(),
+}).passthrough());
+
+/**
+ * Locale list node schema - renders locale switcher links
+ */
+export const LocaleListNodeSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.literal(NODE_TYPE.LOCALE_LIST),
+  style: StyleValueSchema.optional(),
+  itemStyle: StyleValueSchema.optional(),
+  activeItemStyle: StyleValueSchema.optional(),
+  separatorStyle: StyleValueSchema.optional(),
+  showCurrent: z.boolean().optional(),
+  showSeparator: z.boolean().optional(),
+  showFlag: z.boolean().optional(),
+  flagStyle: StyleValueSchema.optional(),
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+}).passthrough());
+
+/**
+ * Text node schema - static text in component structures
+ */
+export const TextNodeSchema = z.object({
+  type: z.literal(NODE_TYPE.TEXT),
+  value: z.string(),
+}).passthrough();
+
+/**
+ * Component node schema - discriminated union (now defined after dependencies)
+ */
+ComponentNodeSchema = z.union([
+  HtmlNodeSchema,
+  ComponentInstanceNodeSchema,
+  SlotMarkerSchema,
+  EmbedNodeSchema,
+  ObjectLinkNodeSchema,
+  LocaleListNodeSchema,
+  TextNodeSchema,
+]);
+
+// Export ComponentNodeSchema
+export { ComponentNodeSchema };
+
+/**
+ * Structured component definition schema
+ */
+export const StructuredComponentDefinitionSchema = z.object({
+  interface: z.record(z.string(), PropDefinitionSchema).optional(),
+  structure: ComponentNodeSchema.optional(),
+  javascript: z.string().optional(),
+  css: z.string().optional(),
+  category: z.string().optional(),
+}).passthrough();
+
+/**
+ * Component definition schema
+ * Accepts both legacy format (with type/props/children) and new format (just component)
+ * New format checked first since it's more common
+ */
+export const ComponentDefinitionSchema = z.union([
+  // New format: { component: {...} }
+  z.object({
+    component: StructuredComponentDefinitionSchema,
+  }).passthrough(),
+  // Legacy format: { type, props?, children?, component }
+  z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.any()).optional(),
+    children: z.array(z.any()).optional(),
+    component: StructuredComponentDefinitionSchema,
+  }).passthrough(),
+]);
+
+/**
+ * I18n value schema - accepts either a string or an i18n object
+ */
+const I18nOrStringSchema = z.union([
+  z.string(),
+  z.object({
+    _i18n: z.literal(true),
+  }).passthrough(),
+]);
+
+/**
+ * Page metadata schema (base version without CMS - used internally)
+ * Note: CMS fields added via PageMetaDataWithCMSSchema after CMS schemas are defined
+ */
+const PageMetaDataBaseSchema = z.object({
+  title: I18nOrStringSchema.optional(),
+  description: I18nOrStringSchema.optional(),
+  keywords: I18nOrStringSchema.optional(),
+  ogTitle: I18nOrStringSchema.optional(),
+  ogDescription: I18nOrStringSchema.optional(),
+  ogImage: z.string().optional(),
+  ogType: z.string().optional(),
+  slugs: z.record(z.string(), z.string()).optional(),
+}).passthrough();
+
+// Temporary export for backward compatibility - will be replaced with full schema below
+export const PageMetaDataSchema = PageMetaDataBaseSchema;
+
+/**
+ * Line range schema for element line number tracking
+ */
+export const LineRangeSchema = z.object({
+  startLine: z.number(),
+  endLine: z.number(),
+});
+
+/**
+ * JSON page schema
+ * Requires at least one field to prevent empty objects from matching
+ */
+export const JSONPageSchema = z.object({
+  components: z.record(z.string(), ComponentDefinitionSchema).optional(),
+  root: ComponentNodeSchema.optional(),
+  meta: PageMetaDataSchema.optional(),
+  _lineMap: z.record(z.string(), LineRangeSchema).optional(),
+}).passthrough().refine((data) => {
+  // Require at least one field to be present
+  return data.meta !== undefined || data.components !== undefined || data.root !== undefined;
+}, {
+  message: "JSONPage must have at least one of: meta, components, or root"
+});
+
+/**
+ * Page data with component schema
+ */
+export const PageDataWithComponentSchema = z.object({
+  component: z.object({
+    structure: ComponentNodeSchema.optional(),
+    interface: z.record(z.string(), PropDefinitionSchema).optional(),
+    javascript: z.string().optional(),
+    css: z.string().optional(),
+  }),
+}).passthrough();
+
+/**
+ * Page data schema - union of JSONPage and PageDataWithComponent
+ * PageDataWithComponent checked first because it's more specific
+ */
+export const PageDataSchema = z.union([
+  PageDataWithComponentSchema,
+  JSONPageSchema,
+]);
+
+// ============================================================================
+// CMS Schemas
+// ============================================================================
+
+/**
+ * CMS field type schema
+ */
+export const CMSFieldTypeSchema = z.enum([
+  'string', 'text', 'number', 'boolean', 'image', 'date', 'select', 'reference', 'i18n', 'i18n-text'
+]);
+
+/**
+ * CMS field definition schema
+ */
+export const CMSFieldDefinitionSchema = z.object({
+  type: CMSFieldTypeSchema,
+  required: z.boolean().optional(),
+  default: z.unknown().optional(),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  options: z.array(z.string()).optional(),
+  collection: z.string().optional(),
+}).passthrough();
+
+/**
+ * CMS schema schema (defines collection structure)
+ */
+export const CMSSchemaSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slugField: z.string(),
+  urlPattern: z.string(),
+  fields: z.record(CMSFieldDefinitionSchema),
+}).passthrough();
+
+/**
+ * CMS item schema (content entry)
+ */
+export const CMSItemSchema = z.object({
+  _id: z.string(),
+  _slug: z.string().optional(),
+  _createdAt: z.string().optional(),
+  _updatedAt: z.string().optional(),
+}).passthrough();
+
+/**
+ * CMS filter condition schema
+ */
+export const CMSFilterConditionSchema = z.object({
+  field: z.string(),
+  operator: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'in']).optional(),
+  value: z.unknown(),
+});
+
+/**
+ * CMS sort config schema
+ */
+export const CMSSortConfigSchema = z.object({
+  field: z.string(),
+  order: z.enum(['asc', 'desc']).optional(),
+});
+
+/**
+ * CMSList query schema
+ */
+export const CMSListQuerySchema = z.object({
+  collection: z.string(),
+  filter: z.union([
+    CMSFilterConditionSchema,
+    z.array(CMSFilterConditionSchema),
+    z.record(z.unknown()),
+  ]).optional(),
+  sort: z.union([CMSSortConfigSchema, z.array(CMSSortConfigSchema)]).optional(),
+  limit: z.number().positive().optional(),
+  offset: z.number().nonnegative().optional(),
+});
+
+/**
+ * Page CMS config schema (embedded in page meta)
+ */
+export const PageCmsConfigSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slugField: z.string(),
+  urlPattern: z.string(),
+  fields: z.record(CMSFieldDefinitionSchema),
+}).passthrough();
+
+/**
+ * Page metadata schema with CMS support
+ * Extends base schema with source and cms fields
+ */
+export const PageMetaDataWithCMSSchema = z.object({
+  title: z.union([z.string(), z.object({ _i18n: z.literal(true) }).passthrough()]).optional(),
+  description: z.union([z.string(), z.object({ _i18n: z.literal(true) }).passthrough()]).optional(),
+  keywords: z.union([z.string(), z.object({ _i18n: z.literal(true) }).passthrough()]).optional(),
+  ogTitle: z.union([z.string(), z.object({ _i18n: z.literal(true) }).passthrough()]).optional(),
+  ogDescription: z.union([z.string(), z.object({ _i18n: z.literal(true) }).passthrough()]).optional(),
+  ogImage: z.string().optional(),
+  ogType: z.string().optional(),
+  slugs: z.record(z.string(), z.string()).optional(),
+  source: z.enum(['static', 'cms']).optional(),
+  cms: PageCmsConfigSchema.optional(),
+}).passthrough();

package/lib/shared/validation/validators.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  validatePropDefinition,
+  validateComponentNode,
+  validateOrThrow,
+  type ValidationResult,
+} from './validators';
+import { NODE_TYPE } from '../constants';
+
+describe('validators', () => {
+  describe('validatePropDefinition', () => {
+    test('validates valid prop definition', () => {
+      const validProp = {
+        name: 'title',
+        type: 'string',
+        defaultValue: 'Hello',
+      };
+      const result = validatePropDefinition(validProp);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data.name).toBe('title');
+      }
+    });
+
+    test('returns errors for invalid prop definition', () => {
+      const invalidProp = {
+        name: 123, // Should be string
+      };
+      const result = validatePropDefinition(invalidProp);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.errors.length).toBeGreaterThan(0);
+      }
+    });
+
+    test('handles missing required fields', () => {
+      const result = validatePropDefinition({});
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe('validateComponentNode', () => {
+    test('validates valid HTML node', () => {
+      const validNode = {
+        type: NODE_TYPE.NODE,
+        tag: 'div',
+        children: [],
+      };
+      const result = validateComponentNode(validNode);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data.type).toBe(NODE_TYPE.NODE);
+      }
+    });
+
+    test('validates valid component node', () => {
+      const validNode = {
+        type: NODE_TYPE.COMPONENT,
+        component: 'Card',
+        props: {},
+      };
+      const result = validateComponentNode(validNode);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.data.type).toBe(NODE_TYPE.COMPONENT);
+      }
+    });
+
+    test('returns errors for invalid node', () => {
+      const invalidNode = {
+        type: 'invalid_type',
+      };
+      const result = validateComponentNode(invalidNode);
+      expect(result.valid).toBe(false);
+    });
+
+    test('handles null/undefined', () => {
+      expect(validateComponentNode(null).valid).toBe(false);
+      expect(validateComponentNode(undefined).valid).toBe(false);
+    });
+  });
+
+  describe('validateOrThrow', () => {
+    test('returns data on valid input', () => {
+      const validator = (data: unknown): ValidationResult<string> => ({
+        valid: true,
+        data: data as string,
+      });
+      const result = validateOrThrow('test', validator);
+      expect(result).toBe('test');
+    });
+
+    test('throws on invalid input', () => {
+      const validator = (data: unknown): ValidationResult<string> => ({
+        valid: false,
+        errors: [{ path: 'root', message: 'Invalid' }],
+      });
+      expect(() => validateOrThrow('test', validator)).toThrow();
+    });
+
+    test('includes custom error message', () => {
+      const validator = (data: unknown): ValidationResult<string> => ({
+        valid: false,
+        errors: [{ path: 'field', message: 'Required' }],
+      });
+      expect(() => validateOrThrow('test', validator, 'Custom error')).toThrow('Custom error');
+    });
+  });
+});