@fragments-sdk/core 0.1.0

package/src/schema.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for runtime validation of fragment definitions
+ */
+
+// Figma property mapping schemas
+const figmaStringMappingSchema = z.object({
+  __type: z.literal('figma-string'),
+  figmaProperty: z.string().min(1),
+});
+
+const figmaBooleanMappingSchema = z.object({
+  __type: z.literal('figma-boolean'),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.object({ true: z.unknown(), false: z.unknown() }).optional(),
+});
+
+const figmaEnumMappingSchema = z.object({
+  __type: z.literal('figma-enum'),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.record(z.unknown()),
+});
+
+const figmaInstanceMappingSchema = z.object({
+  __type: z.literal('figma-instance'),
+  figmaProperty: z.string().min(1),
+});
+
+const figmaChildrenMappingSchema = z.object({
+  __type: z.literal('figma-children'),
+  layers: z.array(z.string().min(1)),
+});
+
+const figmaTextContentMappingSchema = z.object({
+  __type: z.literal('figma-text-content'),
+  layer: z.string().min(1),
+});
+
+export const figmaPropMappingSchema = z.discriminatedUnion('__type', [
+  figmaStringMappingSchema,
+  figmaBooleanMappingSchema,
+  figmaEnumMappingSchema,
+  figmaInstanceMappingSchema,
+  figmaChildrenMappingSchema,
+  figmaTextContentMappingSchema,
+]);
+
+export const fragmentMetaSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+  status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
+  since: z.string().optional(),
+  dependencies: z.array(z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    reason: z.string().optional(),
+  })).optional(),
+  figma: z.string().url().optional(),
+  figmaProps: z.record(figmaPropMappingSchema).optional(),
+});
+
+export const fragmentUsageSchema = z.object({
+  when: z.array(z.string()),
+  whenNot: z.array(z.string()),
+  guidelines: z.array(z.string()).optional(),
+  accessibility: z.array(z.string()).optional(),
+});
+
+export const propTypeSchema: z.ZodType<string> = z.enum([
+  'string',
+  'number',
+  'boolean',
+  'enum',
+  'function',
+  'node',
+  'element',
+  'object',
+  'array',
+  'union',
+  'custom',
+]);
+
+export const propDefinitionSchema = z.object({
+  type: propTypeSchema,
+  values: z.array(z.string()).readonly().optional(),
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  constraints: z.array(z.string()).optional(),
+  typeDetails: z.record(z.unknown()).optional(),
+});
+
+export const relationshipTypeSchema = z.enum([
+  'alternative',
+  'sibling',
+  'parent',
+  'child',
+  'composition',
+  'complementary',
+  'used-by',
+]);
+
+export const componentRelationSchema = z.object({
+  component: z.string().min(1),
+  relationship: relationshipTypeSchema,
+  note: z.string().min(1),
+});
+
+export const fragmentVariantSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  render: z.function().returns(z.unknown()),
+  code: z.string().optional(),
+  figma: z.string().url().optional(),
+});
+
+/**
+ * Schema for banned patterns in codebase
+ */
+export const fragmentBanSchema = z.object({
+  pattern: z.string().min(1),
+  message: z.string().min(1),
+});
+
+/**
+ * Schema for agent-optimized contract metadata
+ */
+export const fragmentContractSchema = z.object({
+  propsSummary: z.array(z.string()).optional(),
+  a11yRules: z.array(z.string()).optional(),
+  bans: z.array(fragmentBanSchema).optional(),
+  scenarioTags: z.array(z.string()).optional(),
+  performanceBudget: z.number().positive().optional(),
+});
+
+/**
+ * Schema for provenance tracking of generated fragments
+ */
+export const fragmentGeneratedSchema = z.object({
+  source: z.enum(['storybook', 'manual', 'ai']),
+  sourceFile: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  timestamp: z.string().datetime().optional(),
+});
+
+/**
+ * Schema for AI-specific metadata for playground context generation
+ */
+export const aiMetadataSchema = z.object({
+  compositionPattern: z.enum(['compound', 'simple', 'controlled', 'wrapper']).optional(),
+  subComponents: z.array(z.string()).optional(),
+  requiredChildren: z.array(z.string()).optional(),
+  commonPatterns: z.array(z.string()).optional(),
+});
+
+/**
+ * Schema for block definitions
+ */
+export const blockDefinitionSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  components: z.array(z.string().min(1)).min(1),
+  code: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+});
+
+export const fragmentDefinitionSchema = z.object({
+  component: z.any(), // Allow any component type (function, class, forwardRef, etc.)
+  meta: fragmentMetaSchema,
+  usage: fragmentUsageSchema,
+  props: z.record(propDefinitionSchema),
+  relations: z.array(componentRelationSchema).optional(),
+  variants: z.array(fragmentVariantSchema), // Allow empty variants array
+  contract: fragmentContractSchema.optional(),
+  ai: aiMetadataSchema.optional(),
+  _generated: fragmentGeneratedSchema.optional(),
+});
+
+/**
+ * Config schema - validates required fields, passes through optional config objects.
+ * Type definitions are in types.ts - schema just ensures basic structure.
+ */
+export const fragmentsConfigSchema = z.object({
+  include: z.array(z.string()).min(1),
+  exclude: z.array(z.string()).optional(),
+  components: z.array(z.string()).optional(),
+  outFile: z.string().optional(),
+  framework: z.enum(['react', 'vue', 'svelte']).optional(),
+  figmaFile: z.string().url().optional(),
+  figmaToken: z.string().optional(),
+  screenshots: z.object({}).passthrough().optional(),
+  service: z.object({}).passthrough().optional(),
+  registry: z.object({}).passthrough().optional(),
+  tokens: z.object({
+    include: z.array(z.string()).min(1),
+  }).passthrough().optional(),
+  snippets: z.object({
+    mode: z.enum(['warn', 'error']).optional(),
+    scope: z.enum(['snippet', 'snippet+render']).optional(),
+    requireFullSnippet: z.boolean().optional(),
+    allowedExternalModules: z.array(z.string().min(1)).optional(),
+  }).optional(),
+  performance: z.union([
+    z.enum(['strict', 'standard', 'relaxed']),
+    z.object({
+      preset: z.enum(['strict', 'standard', 'relaxed']).optional(),
+      budgets: z.object({
+        bundleSize: z.number().positive().optional(),
+      }).optional(),
+    }),
+  ]).optional(),
+  storybook: z.object({
+    exclude: z.array(z.string()).optional(),
+    include: z.array(z.string()).optional(),
+    excludeDeprecated: z.boolean().optional(),
+    excludeTests: z.boolean().optional(),
+    excludeSvgIcons: z.boolean().optional(),
+    excludeSubComponents: z.boolean().optional(),
+  }).optional(),
+});
+
+/**
+ * @deprecated Use blockDefinitionSchema instead
+ */
+export const recipeDefinitionSchema = blockDefinitionSchema;