@app-brew/brewery 1.0.0

package/src/types/src/blocks-definition/common.def.ts

@@ -0,0 +1,793 @@
+import { z } from 'zod'
+import { BlockDefinitionCodeJson } from './types'
+
+/**
+ * Base Component IDs for UI Builder
+ * These are the core components that can be used in layouts
+ */
+export const baseComponentIds = [
+  'accordion',
+  'icon',
+  'image',
+  'link',
+  'list',
+  'rich-text',
+  'text',
+  'youtube-video',
+  'link-button',
+  'spacer',
+  'html-rich-text',
+  'video',
+  'vertical-list',
+  'social-signin',
+] as const
+
+/**
+ * Layout Item Schema - recursive for tree structure
+ * Supports string shorthand, object with kind/key, and container types
+ *
+ * This schema is used across multiple blocks that support dynamic layouts
+ */
+export const layoutItemSchema: z.ZodType<any> = z.union([
+  // Object with kind and key (base component or container)
+  z.object({
+    kind: z.union([
+      z.enum(baseComponentIds),
+      z.enum(['row', 'column']),
+      z.string(),
+    ]),
+    key: z.string(),
+    children: z.array(z.lazy(() => layoutItemSchema)).optional(),
+  }),
+  // String shorthand (e.g., "text", "image")
+  z.string(),
+])
+
+/**
+ * Layout Schema
+ * Root layout configuration with tree structure
+ *
+ * This schema defines the root layout structure for blocks that support
+ * dynamic layouts using the UI Builder base components
+ */
+export const layoutSchema = z.object({
+  key: z.literal('root'),
+  kind: z.enum(['row', 'column']),
+  children: z.array(layoutItemSchema),
+})
+
+/**
+ * Base Component CodeJson Structure
+ *
+ * This defines the common structure for base components in the layout tree.
+ * Used in codeJson definitions to document how base components are rendered.
+ */
+export const baseComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'Base Component',
+  condition:
+    'layoutItem.kind is one of: text, image, icon, rich-text, html-rich-text, video, youtube-video, link-button, spacer, accordion, list, vertical-list, social-signin',
+  stylePath: 'style[layoutItem.key]',
+  sourcePath: 'source[layoutItem.key]',
+  optionsPath: 'options[layoutItem.key]',
+  description:
+    'Base UI Builder components. Each component receives data, style, and options keyed by its layout key.',
+  usage: {
+    componentMapping: {
+      text: 'TextLayoutItem',
+      image: 'ImageLayoutItem',
+      icon: 'Icon',
+      'rich-text': 'RichTextLayoutItem',
+      'html-rich-text': 'HtmlRichTextLayoutItem',
+      video: 'VideoLayoutElement',
+      'youtube-video': 'YoutubeVideo',
+      'link-button': 'LinkButtonLayoutElement',
+      spacer: 'SpacerLayoutElement',
+      accordion: 'AccordionLayoutItem',
+      list: 'ListLayoutItem',
+      'vertical-list': 'VerticalListWrapper',
+      'social-signin': 'SocialSigninLayoutItem',
+    },
+    data: 'source[layoutItem.key]',
+    style: 'style[layoutItem.key]',
+    options: 'options[layoutItem.key]',
+  },
+  children: [
+    {
+      level: 0,
+      component: 'TextLayoutItem',
+      condition: 'layoutItem.kind === "text"',
+      description:
+        'Text component displaying text content. Accepts string or object with text property.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: 'string | { text: string }',
+          examples: ['"Hello World"', '{ text: "Hello World" }'],
+        },
+        propertyAccess: {
+          string: 'source[layoutItem.key] (used directly)',
+          object: 'source[layoutItem.key].text (extracted from object)',
+        },
+        style: 'BaseTextStyle - React Native Text style properties',
+        options:
+          'Omit<TextProps, "style"> - React Native Text props (excluding style)',
+      },
+    },
+    {
+      level: 0,
+      component: 'ImageLayoutItem',
+      condition: 'layoutItem.kind === "image"',
+      description:
+        'Image component displaying image content. Supports regular images, SVG files, and inline SVG strings. Uses "src" property (NOT "url").',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ src: string, width?: number, height?: number }',
+          examples: [
+            '{ src: "https://example.com/image.jpg" }',
+            '{ src: "https://example.com/image.svg", width: 100, height: 100 }',
+            '{ src: "<svg>...</svg>" } (inline SVG)',
+          ],
+          note: 'The property is "src", NOT "url". AI-generated code often uses "url" which is incorrect.',
+        },
+        propertyAccess: {
+          imageUrl: 'source[layoutItem.key].src (required)',
+          dimensions:
+            'source[layoutItem.key].width, source[layoutItem.key].height (optional, used for aspect ratio)',
+        },
+        imageTypes: {
+          regular:
+            'Standard image formats (jpg, png, etc.) - rendered via Image component',
+          svgFile: 'SVG files (.svg extension) - rendered via SvgUri',
+          inlineSvg:
+            'Inline SVG strings (starts with "<svg") - rendered via SvgXml',
+        },
+        aspectRatio: {
+          calculation:
+            'Calculated from: style width/height, data width/height, or options.aspectRatio (in priority order)',
+          autoHeight:
+            'options.autoHeight=true allows flexible height based on container',
+        },
+        style:
+          '{ width?: number | string, height?: number | string, aspectRatio?: number, ...rest }',
+        options: {
+          aspectRatio: 'number (overrides calculated aspect ratio)',
+          resizeMode: "'contain' | 'cover'",
+          roundness: 'number (border radius)',
+          autoHeight: 'boolean (flexible height mode)',
+        },
+      },
+    },
+    {
+      level: 0,
+      component: 'Icon',
+      condition: 'layoutItem.kind === "icon"',
+      description:
+        'Icon component displaying icon from icon registry. Uses iconId to lookup icon.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ iconId: string }',
+          examples: ['{ iconId: "arrow-right" }', '{ iconId: "heart" }'],
+        },
+        propertyAccess: {
+          iconId:
+            'source[layoutItem.key].iconId (required - must be valid icon ID from registry)',
+        },
+        style:
+          'BaseIconStyle - Icon styling properties (width, height, stroke, fill, etc.)',
+        options: 'SvgProps - React Native SVG props',
+      },
+    },
+    {
+      level: 0,
+      component: 'RichTextLayoutItem',
+      condition: 'layoutItem.kind === "rich-text"',
+      description:
+        'Rich text component with Shopify rich text HTML support. Renders HTML content with tag-based styling.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: 'string (HTML content)',
+          examples: [
+            '"<p>Hello <strong>World</strong></p>"',
+            '"<h1>Title</h1><p>Content</p>"',
+          ],
+        },
+        propertyAccess: {
+          content:
+            'source[layoutItem.key] (passed as "data" prop - string containing HTML)',
+        },
+        style: {
+          wrapper: 'View style for wrapper container',
+          tags: 'Record<string, BaseStyle | BaseTextStyle> - Style mapping for HTML tags (e.g., { p: { fontSize: 14 }, h1: { fontSize: 24 } })',
+        },
+        options: {
+          enableUserAgentStyles:
+            'boolean (default: false) - Enable browser default styles',
+        },
+        note: 'Uses ShopifyRichText component internally which parses and renders HTML with tag-based styling.',
+      },
+    },
+    {
+      level: 0,
+      component: 'HtmlRichTextLayoutItem',
+      condition: 'layoutItem.kind === "html-rich-text"',
+      description:
+        'HTML rich text component for rendering raw HTML content. Simpler than rich-text, uses HtmlRichText component.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: 'string (HTML content)',
+          examples: [
+            '"<div>Hello World</div>"',
+            '"<span style="color: red;">Text</span>"',
+          ],
+        },
+        propertyAccess: {
+          content:
+            'source[layoutItem.key] (passed as "data" prop - string containing HTML)',
+        },
+        style: 'any - Styling for HTML content',
+        options: 'any - Additional options for HTML rendering',
+        note: 'Uses HtmlRichText component internally. Simpler alternative to rich-text for basic HTML rendering.',
+      },
+    },
+    {
+      level: 0,
+      component: 'VideoLayoutElement',
+      condition: 'layoutItem.kind === "video"',
+      description:
+        'Video component for playing video files. Uses nested structure with src.url property.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ src: { url: string, width?: number, height?: number, format?: string } }',
+          examples: [
+            '{ src: { url: "https://example.com/video.mp4" } }',
+            '{ src: { url: "https://example.com/video.mp4", width: 1920, height: 1080, format: "mp4" } }',
+          ],
+          note: 'The video URL is nested: source[layoutItem.key].src.url (NOT source[layoutItem.key].url)',
+        },
+        propertyAccess: {
+          videoUrl: 'source[layoutItem.key].src.url (required)',
+          dimensions:
+            'source[layoutItem.key].src.width, source[layoutItem.key].src.height (optional, used for aspect ratio)',
+          format: 'source[layoutItem.key].src.format (optional, e.g., "mp4")',
+        },
+        aspectRatio: {
+          calculation:
+            'Calculated from: source.src.width/height, style width/height, or options.aspectRatio (in priority order)',
+        },
+        style:
+          'BaseImageStyle & { aspectRatio?: number } - Video container styling',
+        options: {
+          aspectRatio: 'number (overrides calculated aspect ratio)',
+          controls: 'boolean (default: true) - Show video controls',
+        },
+      },
+    },
+    {
+      level: 0,
+      component: 'YoutubeVideo',
+      condition: 'layoutItem.kind === "youtube-video"',
+      description:
+        'YouTube video embed component. Displays thumbnail with play button, opens in web view on press.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ videoId: string, thumbnailUrl?: string, params?: Record<string, any> }',
+          examples: [
+            '{ videoId: "dQw4w9WgXcQ" }',
+            '{ videoId: "dQw4w9WgXcQ", thumbnailUrl: "https://custom-thumbnail.jpg", params: { autoplay: 1 } }',
+          ],
+        },
+        propertyAccess: {
+          videoId:
+            'source[layoutItem.key].videoId (required - YouTube video ID)',
+          thumbnailUrl:
+            'source[layoutItem.key].thumbnailUrl (optional - defaults to YouTube thumbnail)',
+          params:
+            'source[layoutItem.key].params (optional - YouTube embed parameters)',
+        },
+        behavior: {
+          thumbnail:
+            'Displays thumbnail image (custom or default YouTube thumbnail)',
+          playButton:
+            'Shows play button overlay (can be hidden via options.hidePlayButton)',
+          navigation:
+            'On press, navigates to web-view screen with YouTube embed URL',
+        },
+        style: {
+          root: 'BaseStyle - Container style',
+          thumbnailImage: 'BaseStyle - Thumbnail image style',
+          playButton: 'BaseIconStyle - Play button icon style',
+        },
+        options: {
+          thumbnailAspectRatio:
+            'number (default: 16/9) - Thumbnail aspect ratio',
+          embedBaseUrl:
+            'string (default: YouTube embed service URL) - Custom embed base URL',
+          hidePlayButton: 'boolean (default: false) - Hide play button overlay',
+        },
+      },
+    },
+    {
+      level: 0,
+      component: 'LinkButtonLayoutElement',
+      condition: 'layoutItem.kind === "link-button"',
+      description:
+        'Link button component. Button with text that navigates to a link on press.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ text: string }',
+          examples: ['{ text: "Click Me" }', '{ text: "Shop Now" }'],
+        },
+        propertyAccess: {
+          buttonText: 'source[layoutItem.key].text (required - button label)',
+        },
+        linkConfiguration: {
+          path: 'options[layoutItem.key].link',
+          structure:
+            '{ kind: string, value: string, params?: Record<string, any> }',
+          examples: [
+            '{ kind: "screen", value: "product-list" }',
+            '{ kind: "product", value: "product-handle" }',
+            '{ kind: "url", value: "https://example.com", params: { external: true } }',
+          ],
+        },
+        style:
+          'ButtonV2Config style - Button styling (text, root, startIcon, endIcon)',
+        options: {
+          link: 'Link configuration object (see linkConfiguration above)',
+          other:
+            'Omit<ButtonProps, "onPress" | "style" | "text"> - Other button props',
+        },
+        behavior: 'On press, calls gotoLink with options.link configuration',
+      },
+    },
+    {
+      level: 0,
+      component: 'SpacerLayoutElement',
+      condition: 'layoutItem.kind === "spacer"',
+      description:
+        'Spacer component for layout spacing. Creates empty space in layout. No data required.',
+      sourcePath: 'N/A (no data needed)',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: 'none (no data required)',
+          note: 'Spacer does not use source data. Only style and options are used.',
+        },
+        style:
+          'ViewProps style - Spacing and layout properties (height, width, margin, padding, etc.)',
+        options: 'ViewProps - React Native View props (excluding style)',
+        commonUse:
+          'Use style.height or style.width to create vertical or horizontal spacing',
+      },
+    },
+    {
+      level: 0,
+      component: 'AccordionLayoutItem',
+      condition: 'layoutItem.kind === "accordion"',
+      description:
+        'Accordion component with collapsible content. Requires exactly 2 children: heading and body.',
+      sourcePath: 'source (special - not keyed)',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{ heading: React.ReactElement[] }',
+          note: 'Heading is automatically generated from layoutItem.children[0] rendering. Body comes from layoutItem.children[1].',
+        },
+        propertyAccess: {
+          heading:
+            'source.heading (array of React elements rendered from layoutItem.children[0])',
+          body: 'layoutItem.children[1] (rendered as accordion body content)',
+        },
+        layoutRequirement: {
+          children:
+            'Must have exactly 2 children: children[0] = heading, children[1] = body',
+        },
+        style: 'AccordianProps style - Accordion styling (heading, body, root)',
+        options: 'any - Accordion options (collapsed state, animations, etc.)',
+        behavior: 'Heading is clickable and toggles body visibility',
+      },
+    },
+    {
+      level: 0,
+      component: 'ListLayoutItem',
+      condition: 'layoutItem.kind === "list"',
+      description:
+        'List component that renders items from source data array. Uses first child as template layout for each item.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options',
+      usage: {
+        dataStructure: {
+          type: 'Array<any> (array of items)',
+          examples: [
+            '[{ id: "1", name: "Item 1" }, { id: "2", name: "Item 2" }]',
+            '[{ title: "Title", description: "Desc" }, ...]',
+          ],
+        },
+        propertyAccess: {
+          items: 'source[layoutItem.key] (required - array of items to render)',
+        },
+        templateLayout: {
+          path: 'layoutItem.children[0]',
+          description: 'First child defines the template layout for each item',
+          itemData:
+            'Each item from source array is passed as data to template layout',
+        },
+        style: {
+          root: 'Style for list container',
+          flatList: 'Style for FlatList component (if using FlatList)',
+        },
+        options: {
+          itemGap: 'number - Gap between items',
+          other:
+            'Omit<ListProps, "data"> - Other React Native List/FlatList props',
+        },
+        behavior:
+          'Renders each item in source array using the template layout from children[0]',
+      },
+    },
+    {
+      level: 0,
+      component: 'VerticalListWrapper',
+      condition: 'layoutItem.kind === "vertical-list"',
+      description:
+        'Vertical list component. Renders items in a vertical grid/list layout. Uses first child as template for each item.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style',
+      optionsPath: 'options',
+      usage: {
+        dataStructure: {
+          type: '{ data: Array<any> }',
+          examples: [
+            '{ data: [{ id: "1", name: "Item 1" }] }',
+            '{ data: [{ title: "Title", image: "url" }] }',
+          ],
+          note: 'Data is nested: source[layoutItem.key].data (array of items)',
+        },
+        propertyAccess: {
+          items:
+            'source[layoutItem.key].data (required - array of items to render)',
+          itemId: 'Each item must have an "id" property for keyExtractor',
+        },
+        templateLayout: {
+          path: 'layoutItem.children[0]',
+          description: 'First child defines the template layout for each item',
+          itemData:
+            'Each item from source.data array is passed as data to template layout',
+        },
+        style: {
+          list: 'Style object for list container and items',
+          separator: 'Style for item separators (gap between items)',
+        },
+        options: {
+          itemGap: 'number - Gap between items (applied to separator height)',
+        },
+        behavior:
+          'Renders vertical list with separators. Each item uses template from children[0].',
+      },
+    },
+    {
+      level: 0,
+      component: 'SocialSigninLayoutItem',
+      condition: 'layoutItem.kind === "social-signin"',
+      description:
+        'Social sign-in component. Displays social authentication buttons (Apple, Google, etc.). Only shows when user is not authenticated.',
+      sourcePath: 'source[layoutItem.key]',
+      stylePath: 'style[layoutItem.key]',
+      optionsPath: 'options[layoutItem.key]',
+      usage: {
+        dataStructure: {
+          type: '{} (empty object - data not used)',
+          note: 'Component uses options for configuration, not source data',
+        },
+        propertyAccess: {
+          data: 'source[layoutItem.key] (not used, can be empty object)',
+        },
+        style: {
+          root: 'Style for social buttons container',
+          apple: 'Style for Apple sign-in button',
+          google: 'Style for Google sign-in button',
+        },
+        options: {
+          successRedirectScreenId:
+            'string (optional) - Screen ID to redirect after successful sign-in',
+          socialSigninProviders: {
+            ios: 'string[] (optional) - Array of provider IDs for iOS (e.g., ["apple", "google"])',
+            android: 'string[] (optional) - Array of provider IDs for Android',
+          },
+        },
+        behavior: {
+          visibility:
+            'Only renders when user is NOT authenticated (isUserAuthenticated() returns false)',
+          platform:
+            'Uses options.socialSigninProviders.ios on iOS, .android on Android',
+          navigation:
+            'After sign-in, redirects to successRedirectScreenId if provided',
+        },
+      },
+    },
+  ],
+}
+
+/**
+ * Container Component CodeJson Structure
+ *
+ * Defines the structure for row/column container components in layouts
+ */
+export const containerComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'Box (row/column)',
+  condition: 'layoutItem.kind === "row" OR layoutItem.kind === "column"',
+  stylePath: 'style[layoutItem.key]',
+  optionsPath: 'options[layoutItem.key]',
+  description:
+    'Container Box component for row or column layout. Recursively renders children.',
+  usage: {
+    background: 'options[layoutItem.key].background',
+    style: 'style[layoutItem.key]',
+    children: 'Recursively rendered layoutItem.children',
+  },
+  children: [
+    {
+      level: 0,
+      component: 'Recursive Layout Items',
+      description:
+        'Recursively renders all children layout items using layoutRenderer',
+    },
+  ],
+}
+
+/**
+ * Link Component CodeJson Structure
+ *
+ * Defines the structure for link wrapper components in layouts
+ */
+export const linkComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'LinkLayoutItem',
+  condition: 'layoutItem.kind === "link"',
+  stylePath: 'style[layoutItem.key]',
+  sourcePath: 'source[layoutItem.key]',
+  optionsPath: 'options',
+  description:
+    'Link wrapper component. Renders children as clickable link content. Wraps any child components in a clickable link.',
+  usage: {
+    dataStructure: {
+      type: '{ kind: string, value: string, params?: Record<string, any>, external?: boolean }',
+      examples: [
+        '{ kind: "screen", value: "product-list" }',
+        '{ kind: "product", value: "product-handle" }',
+        '{ kind: "collection", value: "collection-handle" }',
+        '{ kind: "url", value: "https://example.com", external: true }',
+        '{ kind: "screen", value: "product-detail", params: { productHandle: "my-product" } }',
+      ],
+    },
+    propertyAccess: {
+      kind: 'source[layoutItem.key].kind (required - link type: "screen", "product", "collection", "url", etc.)',
+      value: 'source[layoutItem.key].value (required - link target value)',
+      params:
+        'source[layoutItem.key].params (optional - additional parameters for navigation)',
+      external:
+        'source[layoutItem.key].external (optional - boolean, for external URLs)',
+    },
+    style: '{ root: BaseTextStyle } - Style for link wrapper (text styling)',
+    options: {
+      pressableProps:
+        'PressableProps - React Native Pressable props for link behavior',
+    },
+    children:
+      'layoutItem.children (required - rendered as clickable link content)',
+    behavior:
+      'Children are wrapped in a Link component. On press, navigates based on source configuration.',
+  },
+}
+
+/**
+ * Accordion Component CodeJson Structure
+ *
+ * Defines the structure for accordion components in layouts
+ */
+export const accordionComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'AccordionLayoutItem',
+  condition: 'layoutItem.kind === "accordion"',
+  stylePath: 'style[layoutItem.key]',
+  sourcePath: 'source',
+  optionsPath: 'options[layoutItem.key]',
+  description:
+    'Accordion component with collapsible heading and body. Requires exactly 2 children: heading (children[0]) and body (children[1]).',
+  usage: {
+    layoutRequirement: {
+      children: 'Must have exactly 2 children layout items',
+      heading:
+        'layoutItem.children[0] - Rendered as accordion heading (clickable)',
+      body: 'layoutItem.children[1] - Rendered as accordion body (collapsible content)',
+    },
+    dataStructure: {
+      type: '{ heading: React.ReactElement[] }',
+      note: 'Heading elements are automatically generated from rendering layoutItem.children[0]. Body comes from layoutItem.children[1].',
+    },
+    propertyAccess: {
+      heading:
+        'source.heading (array of React elements - auto-generated from children[0])',
+      body: 'layoutItem.children[1] (rendered directly as body content)',
+    },
+    style:
+      'AccordianProps style - Accordion styling with heading, body, and root styles',
+    options:
+      'any - Accordion options (default collapsed state, animations, etc.)',
+    behavior: {
+      interaction: 'Heading is clickable and toggles body visibility',
+      rendering:
+        'Heading and body are rendered separately, then combined into accordion component',
+    },
+  },
+  children: [
+    {
+      level: 0,
+      component: 'Heading Components',
+      description:
+        'Rendered from layoutItem.children[0]. Can be any layout items (text, image, etc.). Rendered elements are passed as heading prop.',
+      sourcePath: 'source (shared with body)',
+      stylePath: 'style (nested under accordion key)',
+      optionsPath: 'options (nested under accordion key)',
+    },
+    {
+      level: 0,
+      component: 'Body Components',
+      description:
+        'Rendered from layoutItem.children[1]. Can be any layout items. Rendered as children of Accordion component.',
+      sourcePath: 'source (shared with heading)',
+      stylePath: 'style (nested under accordion key)',
+      optionsPath: 'options (nested under accordion key)',
+    },
+  ],
+}
+
+/**
+ * List Component CodeJson Structure
+ *
+ * Defines the structure for list components in layouts
+ */
+export const listComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'ListLayoutItem',
+  condition: 'layoutItem.kind === "list"',
+  stylePath: 'style[layoutItem.key]',
+  sourcePath: 'source[layoutItem.key]',
+  optionsPath: 'options',
+  description:
+    'List component that renders items from source data array. Uses first child as template layout for each item. Renders using React Native List/FlatList component.',
+  usage: {
+    dataStructure: {
+      type: 'Array<any> (array of item objects)',
+      examples: [
+        '[{ id: "1", name: "Item 1", image: "url1.jpg" }, { id: "2", name: "Item 2", image: "url2.jpg" }]',
+        '[{ title: "Title", description: "Description" }, ...]',
+      ],
+    },
+    propertyAccess: {
+      items: 'source[layoutItem.key] (required - array of items to render)',
+      itemData: 'Each item from array is passed as data to template layout',
+    },
+    templateLayout: {
+      path: 'layoutItem.children[0]',
+      description:
+        'First child defines the template layout structure for each item',
+      rendering:
+        'Each item from source array is rendered using this template layout',
+      itemContext: 'Item data is available in template as source[templateKey]',
+    },
+    style: {
+      root: 'Style for list container (FlatList root style)',
+      flatList: 'Style for FlatList component (if using FlatList)',
+    },
+    options: {
+      itemGap: 'number - Gap between list items',
+      other:
+        'Omit<ListProps<Array<any>>, "data"> - Other React Native List/FlatList props (renderItem, keyExtractor, etc.)',
+    },
+    behavior: {
+      rendering:
+        'Iterates through source array and renders each item using template from children[0]',
+      listType: 'Uses React Native List/FlatList component for rendering',
+    },
+  },
+  children: [
+    {
+      level: 0,
+      component: 'List Item Template',
+      description:
+        'Template layout defined by layoutItem.children[0]. Each item from source array is rendered using this template.',
+      usage: {
+        itemData:
+          'source[layoutItem.key][index] - Current item data available in template',
+        layout: 'layoutItem.children[0] - Template layout structure',
+        style:
+          'Computed from style[layoutItem.key] - Styles applied to each item',
+        index: 'Item index available for conditional rendering',
+      },
+    },
+  ],
+}
+
+/**
+ * Vertical List Component CodeJson Structure
+ *
+ * Defines the structure for vertical list components in layouts
+ */
+export const verticalListComponentCodeJson: BlockDefinitionCodeJson = {
+  level: 0,
+  component: 'VerticalListWrapper',
+  condition: 'layoutItem.kind === "vertical-list"',
+  stylePath: 'style',
+  sourcePath: 'source[layoutItem.key]',
+  optionsPath: 'options',
+  description:
+    'Vertical list component. Renders items in a vertical grid/list layout. Uses first child as template layout for each item. Supports custom separators and item gaps.',
+  usage: {
+    dataStructure: {
+      type: '{ data: Array<any> }',
+      examples: [
+        '{ data: [{ id: "1", name: "Item 1" }] }',
+        '{ data: [{ id: "1", title: "Title", image: "url.jpg" }, ...] }',
+      ],
+      note: 'Data is nested: source[layoutItem.key].data (array of items). Each item must have an "id" property.',
+    },
+    propertyAccess: {
+      items:
+        'source[layoutItem.key].data (required - array of items to render)',
+      itemId: 'Each item must have an "id" property (used by keyExtractor)',
+    },
+    templateLayout: {
+      path: 'layoutItem.children[0]',
+      description:
+        'First child defines the template layout structure for each item',
+      rendering:
+        'Each item from source.data array is rendered using this template layout',
+      itemContext: 'Item data is available in template as source data',
+    },
+    style: {
+      list: 'Style object for list container and items',
+      separator: 'Style for item separators (gap between items)',
+      root: 'Style for list root container',
+      item: 'Style for individual items',
+    },
+    options: {
+      itemGap: 'number - Gap between items (applied to separator height)',
+    },
+    behavior: {
+      rendering: 'Renders vertical list with separators between items',
+      keyExtraction:
+        'Uses item.id for keyExtractor (each item must have id property)',
+      separators:
+        'Automatically adds separators between items based on itemGap option',
+    },
+  },
+}