meno-core 1.0.20 → 1.0.21

package/lib/client/templateEngine.ts

@@ -10,7 +10,7 @@ import { isResponsiveStyle } from '../shared/styleUtils';
 import { normalizeStyle as normalizeStyleShared, mergeResponsiveStyles } from '../shared/responsiveStyleUtils';
 import { DEFAULT_BREAKPOINTS } from '../shared/breakpoints';
 import { NODE_TYPE } from '../shared/constants';
-import { isValidNodeType, isComponentNode, isHtmlNode, isSlotMarker, isEmbedNode, isLocaleListNode, isLinkNode, isCMSListNode } from '../shared/nodeUtils';
+import { isValidNodeType, isComponentNode, isHtmlNode, isSlotMarker, isEmbedNode, isLocaleListNode, isLinkNode, isCMSListNode, isListNode } from '../shared/nodeUtils';
 import { applyStylesToNode } from '../shared/styleNodeUtils';
 import { isRichTextMarker, richTextMarkerToHtml } from '../shared/propResolver';
 import { isTiptapDocument, tiptapToHtml } from '../shared/richtext';
@@ -379,8 +379,16 @@ export function processStructure(
               const processedChild = processStructure(child, context, viewportWidth, instanceChildren, preserveResponsiveStyles, depth + 1);
               addProcessedItemToArray(processedChild, processed);
             }
+          } else if ('default' in item && (item as any).default !== undefined) {
+            // Fallback: use slot's default content if no instance children provided
+            const defaultContent = (item as any).default;
+            const defaultsArray = Array.isArray(defaultContent) ? defaultContent : [defaultContent];
+            for (const defaultChild of defaultsArray) {
+              const processedChild = processStructure(defaultChild, context, viewportWidth, undefined, preserveResponsiveStyles, depth + 1);
+              addProcessedItemToArray(processedChild, processed);
+            }
           }
-          // If no instance children, marker renders nothing (skip it)
+          // If no instance children AND no default, marker renders nothing (skip it)
         } else {
           // Regular item - process normally
           const processedItem = processStructure(item, context, viewportWidth, instanceChildren, preserveResponsiveStyles, depth + 1);
@@ -393,7 +401,7 @@ export function processStructure(
     if (typeof structure === 'object' && !Array.isArray(structure) && structure !== null) {
       // Check if this is a slot marker (shouldn't happen here since we handle it in array processing, but guard anyway)
       if (isSlotMarker(structure)) {
-        // This shouldn't happen in object processing, but if it does, return instance children
+        // This shouldn't happen in object processing, but if it does, return instance children or default
         if (instanceChildren) {
           const processed: Array<ComponentNode | string> = [];
           const childrenArray = Array.isArray(instanceChildren) ? instanceChildren : [instanceChildren];
@@ -403,6 +411,17 @@ export function processStructure(
           }
           return processed.length === 1 ? processed[0] : processed;
         }
+        // Fallback: use slot's default content
+        if ('default' in structure && (structure as any).default !== undefined) {
+          const defaultContent = (structure as any).default;
+          const processed: Array<ComponentNode | string> = [];
+          const defaultsArray = Array.isArray(defaultContent) ? defaultContent : [defaultContent];
+          for (const defaultChild of defaultsArray) {
+            const processedChild = processStructure(defaultChild, context, viewportWidth, undefined, preserveResponsiveStyles, depth + 1);
+            addProcessedItemToArray(processedChild, processed);
+          }
+          return processed.length === 1 ? processed[0] : processed;
+        }
         return null;
       }
       
@@ -452,11 +471,12 @@ export function processStructure(
         processed = {
           type: NODE_TYPE.LOCALE_LIST,
         } as any;
-      } else if (preservedType === NODE_TYPE.CMS_LIST) {
-        // Handle cms-list nodes - they have collection, limit, offset, filter, sort, style, children
+      } else if (preservedType === NODE_TYPE.LIST || (preservedType as string) === 'cms-list') {
+        // Handle list nodes (unified - handles both prop and collection source types)
+        // Also supports legacy 'cms-list' type for migration
         processed = {
-          type: NODE_TYPE.CMS_LIST,
-          collection: '',
+          type: NODE_TYPE.LIST,
+          source: '',
           children: [] as Array<ComponentNode | string>
         } as any;
       } else {
@@ -480,7 +500,8 @@ export function processStructure(
               processed.children = [processedChildren as ComponentNode | string];
             }
           } else if (key === 'tag') {
-            if (isHtmlNode(processed)) {
+            // Handle tag for HTML nodes and list nodes
+            if (isHtmlNode(processed) || isListNode(processed)) {
               if (typeof value === 'string') {
                 // Process template in tag (e.g., "h{{size}}" -> "h1")
                 const evalContext: Record<string, unknown> = { ...getGlobalTemplateContext(), ...context.props };
@@ -488,9 +509,9 @@ export function processStructure(
                   Object.assign(evalContext, context.componentDef as Record<string, unknown>);
                 }
                 // Use processCodeTemplates to handle partial templates like "h{{size}}"
-                processed.tag = processCodeTemplates(value, evalContext);
+                (processed as any).tag = processCodeTemplates(value, evalContext);
               } else {
-                processed.tag = String(value);
+                (processed as any).tag = String(value);
               }
             }
           } else if (key === 'component') {
@@ -737,7 +758,7 @@ export function processStructure(
           if (isComponentNode(processed)) {
             processed.props = processed.props || {};
             processed.props.style = resolvedStyle as ResponsiveStyleObject;
-          } else if (isHtmlNode(processed) || isEmbedNode(processed) || isLocaleListNode(processed) || isLinkNode(processed) || isCMSListNode(processed)) {
+          } else if (isHtmlNode(processed) || isEmbedNode(processed) || isLocaleListNode(processed) || isLinkNode(processed) || isListNode(processed)) {
             processed.style = resolvedStyle as ResponsiveStyleObject;
           }
         } else {

package/lib/server/ssr/attributeBuilder.ts

@@ -7,6 +7,14 @@
  * Escape HTML special characters to prevent XSS
  */
 export function escapeHtml(unsafe: string): string {
+  // Handle non-string values defensively
+  if (typeof unsafe !== 'string') {
+    if (unsafe === null || unsafe === undefined) {
+      return '';
+    }
+    // Convert arrays/objects/numbers to string
+    unsafe = String(unsafe);
+  }
   return unsafe
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')

package/lib/server/ssr/index.ts

@@ -14,7 +14,7 @@
  */
 
 // Main rendering functions
-export { renderPageSSR, extractPageMeta, generateMetaTags } from './ssrRenderer';
+export { renderPageSSR, extractPageMeta, generateMetaTags, buildComponentHTML } from './ssrRenderer';
 export type { CMSContext, PageMeta } from './ssrRenderer';
 export { generateSSRHTML } from './htmlGenerator';
 export type { SSRHTMLResult, GenerateSSRHTMLOptions } from './htmlGenerator';

package/lib/server/ssr/ssrRenderer.ts

@@ -3,7 +3,7 @@
  * Converts JSON component structures to HTML strings for SEO-friendly initial page loads
  */
 
-import type { ComponentNode, ComponentDefinition, JSONPage, CMSListNode, CMSItem, EmbedNode, LinkNode, LocaleListNode, CMSFilterCondition } from '../../shared/types';
+import type { ComponentNode, ComponentDefinition, JSONPage, CMSItem, EmbedNode, LinkNode, LocaleListNode, CMSFilterCondition } from '../../shared/types';
 import type { TemplateContext, NestedCMSListConfig } from '../../shared/types/cms';
 import { processItemTemplate, processItemPropsTemplate, hasItemTemplates, buildTemplateContext, resolveItemsTemplate, resolveTemplateRawValue, addItemUrl, getNestedValue, type ValueResolver } from '../../shared/itemTemplateUtils';
 import { singularize } from '../../shared/types/cms';
@@ -15,7 +15,8 @@ import { loadBreakpointConfig, loadI18nConfig } from '../jsonLoader';
 import type { I18nConfig } from '../../shared/types/components';
 import { extractLocaleFromPath, DEFAULT_I18N_CONFIG, resolveI18nValue, buildLocalizedPath, isI18nValue } from '../../shared/i18n';
 import { NODE_TYPE } from '../../shared/constants';
-import { isComponentNode, isHtmlNode, isLinkNode, isEmbedNode, isLocaleListNode, isCMSListNode, markAsSlotContent, isBooleanMapping } from '../../shared/nodeUtils';
+import { isComponentNode, isHtmlNode, isLinkNode, isEmbedNode, isLocaleListNode, isListNode, markAsSlotContent, isBooleanMapping } from '../../shared/nodeUtils';
+import type { ListNode } from '../../shared/registry/nodeTypes/ListNodeType';
 import type { CMSService } from '../services/cmsService';
 import { extractAttributesFromNode } from '../../shared/attributeNodeUtils';
 import { SSRRegistry } from '../../shared/registry/SSRRegistry';
@@ -218,8 +219,9 @@ const ssrComponentRegistry = new SSRRegistry();
 
 /**
  * Build HTML string from component node (server-side)
+ * Exported for component preview rendering
  */
-async function buildComponentHTML(
+export async function buildComponentHTML(
   node: ComponentNode | ComponentNode[] | string | number | null | undefined,
   globalComponents: Record<string, ComponentDefinition> = {},
   pageComponents: Record<string, ComponentDefinition> = {},
@@ -275,25 +277,29 @@ async function buildComponentHTML(
 }
 
 /**
- * Render a nested CMS list as a placeholder for client-side hydration.
- * Used when parent cms-list has emitTemplate: true.
+ * Render a nested list (collection mode) as a placeholder for client-side hydration.
+ * Used when parent list has emitTemplate: true.
  * The placeholder contains the configuration and template for MenoFilter to hydrate.
  */
-async function renderNestedCMSListPlaceholder(
-  node: CMSListNode,
+async function renderNestedListPlaceholder(
+  node: ListNode,
   ctx: SSRContext
 ): Promise<string> {
+  // Get source - handle both string and pre-resolved array sources
+  const sourceValue = node.source || (node as any).collection;
+  const sourceStr = typeof sourceValue === 'string' ? sourceValue : '';
+
   // Track this collection for client-side data injection
-  if (ctx.neededCollections) {
-    ctx.neededCollections.add(node.collection);
+  if (ctx.neededCollections && sourceStr) {
+    ctx.neededCollections.add(sourceStr);
   }
 
   // Build configuration for client-side hydration
   const config: NestedCMSListConfig = {
-    collection: node.collection,
+    collection: sourceStr,
     itemAs: node.itemAs,
     items: node.items,
-    filter: node.filter,
+    filter: node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined,
     sort: node.sort,
     limit: node.limit,
     offset: node.offset,
@@ -315,7 +321,7 @@ async function renderNestedCMSListPlaceholder(
   const classes: string[] = [];
   if (node.style) {
     const nodeStyle = node.style as ResponsiveStyleObject;
-    validateStyleCoverage(nodeStyle, 'nested-cms-list');
+    validateStyleCoverage(nodeStyle, 'nested-list');
     classes.push(...responsiveStylesToClasses(nodeStyle));
   }
   const classAttr = classes.length > 0
@@ -326,108 +332,103 @@ async function renderNestedCMSListPlaceholder(
   const configJson = escapeHtml(JSON.stringify(config));
 
   // Emit placeholder with embedded config and template
-  return `<div${classAttr} data-cms-list-nested="true" data-collection="${escapeHtml(node.collection)}" data-cms-config="${configJson}">` +
+  return `<div${classAttr} data-cms-list-nested="true" data-collection="${escapeHtml(sourceStr)}" data-cms-config="${configJson}">` +
     `<template data-nested-template>${templateContent}</template>` +
     `</div>`;
 }
 
 /**
- * Process CMSList node - renders children for each CMS item
- * Wraps children in a container div with styles and attributes (like ComponentBuilder)
- * Supports named contexts via `itemAs` and direct item IDs via `items`
+ * Unified List node processor - renders children for each item
+ * Supports both source types:
+ * - 'prop': Reads from component props or template context
+ * - 'collection': Queries from CMS collections
  */
-async function processCMSList(node: CMSListNode, ctx: SSRContext): Promise<string> {
-  if (!ctx.cmsService) {
-    console.warn('CMSList requires CMS service');
+async function processList(node: ListNode, ctx: SSRContext): Promise<string> {
+  // Determine source type (default to 'prop', but handle legacy 'cms-list' type)
+  const nodeType = (node as any).type;
+  const isLegacyCMSList = nodeType === 'cms-list';
+  const sourceType = isLegacyCMSList ? 'collection' : (node.sourceType || 'prop');
+
+  // For collection mode, check CMS service availability
+  if (sourceType === 'collection' && !ctx.cmsService) {
+    console.warn('List with sourceType "collection" requires CMS service');
     return '';
   }
 
   // When in templateMode with nestedCMSListMode, emit placeholder for client-side hydration
-  // This allows nested cms-lists inside emitTemplate to work with MenoFilter
-  if (ctx.templateMode && ctx.nestedCMSListMode) {
-    return renderNestedCMSListPlaceholder(node, ctx);
+  // This allows nested lists inside emitTemplate to work with MenoFilter
+  if (sourceType === 'collection' && ctx.templateMode && ctx.nestedCMSListMode) {
+    return renderNestedListPlaceholder(node, ctx);
   }
 
-  // Determine variable name for this list's items
-  const variableName = node.itemAs || singularize(node.collection);
-
-  // Get schema to compute _url for items
-  const schema = ctx.cmsService.getSchema(node.collection);
-
-  let items: CMSItem[];
+  // Get source - handle both new 'source' and legacy 'collection' property
+  // Source can be a string (prop name) or array (pre-resolved by processStructure)
+  const rawSource = node.source || (node as any).collection;
+  const source = typeof rawSource === 'string' ? rawSource : '';
+  const sourceIsResolved = Array.isArray(rawSource);
 
-  // Check if items are specified directly (for nested reference lists)
-  if (node.items) {
-    // If items is a template expression, resolve it from current context
-    if (typeof node.items === 'string' && node.items.startsWith('{{')) {
-      let resolvedIds: string | string[] | undefined;
+  // Determine variable name for this list's items
+  let variableName: string;
+  if (node.itemAs) {
+    variableName = node.itemAs;
+  } else if (sourceType === 'collection') {
+    variableName = singularize(source);
+  } else {
+    variableName = 'item';
+  }
 
-      // Check if this is a CMS template ({{cms.field}}) - resolve from cmsContext
-      if (node.items.startsWith('{{cms.') && ctx.cmsContext?.cms) {
-        const fieldPath = node.items.slice(6, -2); // Extract "field" from "{{cms.field}}"
-        let value: unknown = ctx.cmsContext.cms;
-        for (const part of fieldPath.split('.')) {
-          if (value && typeof value === 'object' && part in value) {
-            value = (value as Record<string, unknown>)[part];
-          } else {
-            value = undefined;
-            break;
-          }
-        }
-        if (value !== null && value !== undefined) {
-          resolvedIds = Array.isArray(value) ? value.map(v => String(v)) : String(value);
-        }
-      } else {
-        // Otherwise resolve from template context (for nested cms-lists)
-        const parentContext = ctx.templateContext || { _type: 'template' as const };
-        resolvedIds = resolveItemsTemplate(node.items, parentContext);
-      }
+  // Get items based on sourceType
+  let items: unknown[];
 
-      if (!resolvedIds) {
-        return '';
-      }
-      const ids = Array.isArray(resolvedIds) ? resolvedIds : [resolvedIds];
-      items = await ctx.cmsService.getItemsByIds(node.collection, ids);
+  if (sourceType === 'collection') {
+    // Collection mode: Query from CMS service
+    items = await getCollectionItems(node, source, ctx);
+  } else {
+    // Prop mode: Read from component props or template context
+    // If source was already resolved to an array by processStructure (e.g., from {{features}}),
+    // use it directly instead of looking up by prop name
+    if (sourceIsResolved) {
+      // Source was resolved to array by processStructure
+      items = rawSource as unknown[];
+    } else if (source) {
+      // Source is a prop name or template expression - resolve it
+      items = getPropItems(source, ctx);
     } else {
-      // Direct IDs (string or array)
-      const ids = Array.isArray(node.items) ? node.items : [node.items];
-      items = await ctx.cmsService.getItemsByIds(node.collection, ids);
+      items = [];
     }
-  } else {
-    // Build query from node props (resolve filter templates for nested cms-list support)
-    const query = {
-      collection: node.collection,
-      filter: resolveFilterTemplates(node.filter, ctx.templateContext),
-      sort: node.sort,
-      limit: node.limit,
-      offset: node.offset,
-    };
-    items = await ctx.cmsService.queryItems(query);
   }
 
-  // Exclude current item if option is set and we have a current CMS context
-  if (node.excludeCurrentItem && ctx.cmsContext?.cms?._id) {
-    const currentId = ctx.cmsContext.cms._id as string;
-    items = items.filter(item => item._id !== currentId);
+  // Apply shared options: offset and limit
+  if (node.offset && sourceType === 'prop') {
+    items = items.slice(node.offset);
+  }
+  if (node.limit && sourceType === 'prop') {
+    items = items.slice(0, node.limit);
   }
 
   if (items.length === 0) {
     return '';
   }
 
+  // Get schema for URL computation (collection mode only)
+  const schema = sourceType === 'collection' && ctx.cmsService
+    ? ctx.cmsService.getSchema(source)
+    : undefined;
+
   // Render children for each item
   const renderedItems: string[] = [];
 
   for (let i = 0; i < items.length; i++) {
     // Add computed _url field if schema is available
+    const rawItem = items[i] as Record<string, unknown>;
     const item = schema
-      ? addItemUrl(items[i], schema, ctx.locale, ctx.i18nConfig)
-      : items[i];
+      ? addItemUrl(rawItem as CMSItem, schema, ctx.locale, ctx.i18nConfig)
+      : rawItem;
 
     // Build template context with named variable (preserves parent context for nested lists)
     const templateContext = buildTemplateContext(
       variableName,
-      item,
+      item as CMSItem,
       i,
       items.length,
       ctx.templateContext
@@ -446,23 +447,23 @@ async function processCMSList(node: CMSListNode, ctx: SSRContext): Promise<strin
 
   const childrenHTML = renderedItems.join('');
 
-  // Build wrapper div with styles and attributes (like ComponentBuilder)
+  // Build wrapper div with styles and attributes
   const classes: string[] = [];
 
   // Convert node.style to utility classes
   if (node.style) {
     const nodeStyle = node.style as ResponsiveStyleObject;
-    validateStyleCoverage(nodeStyle, 'cms-list');
+    validateStyleCoverage(nodeStyle, 'list');
     classes.push(...responsiveStylesToClasses(nodeStyle));
   }
 
-  // Handle interactive styles for cms-list wrapper (cast to InteractiveStyles since inferred type is slightly different)
-  const cmsListInteractiveStyles = node.interactiveStyles as InteractiveStyles | undefined;
-  const cmsListGenerateElementClass = node.generateElementClass;
-  const cmsListLabel = node.label;
-  let cmsListCssVariables: Record<string, string> = {};
+  // Handle interactive styles for list wrapper
+  const listInteractiveStyles = node.interactiveStyles as InteractiveStyles | undefined;
+  const listGenerateElementClass = node.generateElementClass;
+  const listLabel = node.label;
+  let listCssVariables: Record<string, string> = {};
 
-  if ((cmsListInteractiveStyles && cmsListInteractiveStyles.length > 0) || cmsListGenerateElementClass) {
+  if ((listInteractiveStyles && listInteractiveStyles.length > 0) || listGenerateElementClass) {
     const useComponentContext = Boolean(ctx.componentContext);
     const effectiveFileType = useComponentContext ? 'component' : 'page';
     const effectiveFileName = useComponentContext ? ctx.componentContext : (ctx.pagePath
@@ -472,7 +473,7 @@ async function processCMSList(node: CMSListNode, ctx: SSRContext): Promise<strin
     const elementClassCtx: ElementClassContext = {
       fileType: effectiveFileType,
       fileName: effectiveFileName || 'page',
-      label: cmsListLabel,
+      label: listLabel,
       path: ctx.elementPath || [],
     };
     const elementClass = generateElementClassName(elementClassCtx);
@@ -481,24 +482,24 @@ async function processCMSList(node: CMSListNode, ctx: SSRContext): Promise<strin
     classes.unshift(elementClass);
 
     // Register interactive styles for CSS generation with mapping support
-    if (cmsListInteractiveStyles && cmsListInteractiveStyles.length > 0 && ctx.interactiveStylesMap) {
-      if (ctx.componentResolvedProps && hasInteractiveStyleMappings(cmsListInteractiveStyles)) {
-        const { resolvedStyles, mappings } = extractInteractiveStyleMappings(cmsListInteractiveStyles);
-        cmsListCssVariables = resolveExtractedMappings(mappings, ctx.componentResolvedProps);
+    if (listInteractiveStyles && listInteractiveStyles.length > 0 && ctx.interactiveStylesMap) {
+      if (ctx.componentResolvedProps && hasInteractiveStyleMappings(listInteractiveStyles)) {
+        const { resolvedStyles, mappings } = extractInteractiveStyleMappings(listInteractiveStyles);
+        listCssVariables = resolveExtractedMappings(mappings, ctx.componentResolvedProps);
         ctx.interactiveStylesMap.set(elementClass, resolvedStyles);
       } else {
-        ctx.interactiveStylesMap.set(elementClass, cmsListInteractiveStyles);
+        ctx.interactiveStylesMap.set(elementClass, listInteractiveStyles);
       }
     }
   }
 
   // Build style attribute with CSS variables if any
-  let cmsListStyleAttr = '';
-  if (Object.keys(cmsListCssVariables).length > 0) {
-    const styleString = Object.entries(cmsListCssVariables)
+  let listStyleAttr = '';
+  if (Object.keys(listCssVariables).length > 0) {
+    const styleString = Object.entries(listCssVariables)
       .map(([k, v]) => `${k}: ${v}`)
       .join('; ');
-    cmsListStyleAttr = ` style="${escapeHtml(styleString)}"`;
+    listStyleAttr = ` style="${escapeHtml(styleString)}"`;
   }
 
   // Extract attributes from node
@@ -523,28 +524,139 @@ async function processCMSList(node: CMSListNode, ctx: SSRContext): Promise<strin
     }
   }
 
-  // Add data attributes for consistency with client
-  attrsStr += ` data-cms-list="true"`;
-  attrsStr += ` data-collection="${escapeHtml(node.collection || '')}"`;
+  // Add data attributes based on source type
+  if (sourceType === 'collection') {
+    attrsStr += ` data-cms-list="true"`;
+    attrsStr += ` data-collection="${escapeHtml(source || '')}"`;
+  } else {
+    attrsStr += ` data-list="true"`;
+    attrsStr += ` data-source="${escapeHtml(source || (sourceIsResolved ? 'resolved' : ''))}"`;
+  }
 
-  // Emit item template when emitTemplate is enabled
+  // Emit item template when emitTemplate is enabled (collection mode)
   // This allows MenoFilter to dynamically render items from JSON data
   let templateHtml = '';
-  if (node.emitTemplate && node.children && node.children.length > 0) {
+  if (sourceType === 'collection' && node.emitTemplate && node.children && node.children.length > 0) {
     // Render children with templateMode to preserve {{item.field}} placeholders
-    // Keep templateContext for nested cms-list resolution, set nestedCMSListMode
-    // so nested cms-lists emit placeholders for client-side hydration
+    // Keep templateContext for nested list resolution, set nestedCMSListMode
+    // so nested lists emit placeholders for client-side hydration
     const templateCtx: SSRContext = {
       ...ctx,
       templateMode: true,
-      templateContext: ctx.templateContext, // Keep parent context for nested cms-list resolution
-      nestedCMSListMode: true, // Nested cms-lists will emit placeholders for client hydration
+      templateContext: ctx.templateContext, // Keep parent context for nested list resolution
+      nestedCMSListMode: true, // Nested lists will emit placeholders for client hydration
     };
     const templateContent = await renderChildrenAsync(node.children, templateCtx);
     templateHtml = `<template data-meno-item>${templateContent}</template>`;
   }
 
-  return `<div${classAttr}${cmsListStyleAttr}${attrsStr}>${childrenHTML}${templateHtml}</div>`;
+  // Use configurable tag (defaults to 'div')
+  const tag = node.tag || 'div';
+  return `<${tag}${classAttr}${listStyleAttr}${attrsStr}>${childrenHTML}${templateHtml}</${tag}>`;
+}
+
+/**
+ * Get items from CMS collection (for sourceType: 'collection')
+ */
+async function getCollectionItems(node: ListNode, source: string, ctx: SSRContext): Promise<CMSItem[]> {
+  if (!ctx.cmsService) return [];
+
+  let items: CMSItem[];
+
+  // Check if items are specified directly (for nested reference lists)
+  if (node.items) {
+    // If items is a template expression, resolve it from current context
+    if (typeof node.items === 'string' && node.items.startsWith('{{')) {
+      let resolvedIds: string | string[] | undefined;
+
+      // Check if this is a CMS template ({{cms.field}}) - resolve from cmsContext
+      if (node.items.startsWith('{{cms.') && ctx.cmsContext?.cms) {
+        const fieldPath = node.items.slice(6, -2); // Extract "field" from "{{cms.field}}"
+        let value: unknown = ctx.cmsContext.cms;
+        for (const part of fieldPath.split('.')) {
+          if (value && typeof value === 'object' && part in value) {
+            value = (value as Record<string, unknown>)[part];
+          } else {
+            value = undefined;
+            break;
+          }
+        }
+        if (value !== null && value !== undefined) {
+          resolvedIds = Array.isArray(value) ? value.map(v => String(v)) : String(value);
+        }
+      } else {
+        // Otherwise resolve from template context (for nested lists)
+        const parentContext = ctx.templateContext || { _type: 'template' as const };
+        resolvedIds = resolveItemsTemplate(node.items, parentContext);
+      }
+
+      if (!resolvedIds) {
+        return [];
+      }
+      const ids = Array.isArray(resolvedIds) ? resolvedIds : [resolvedIds];
+      items = await ctx.cmsService.getItemsByIds(source, ids);
+    } else {
+      // Direct IDs (string or array)
+      const ids = Array.isArray(node.items) ? node.items : [node.items];
+      items = await ctx.cmsService.getItemsByIds(source, ids);
+    }
+  } else {
+    // Build query from node props (resolve filter templates for nested list support)
+    const query = {
+      collection: source,
+      filter: resolveFilterTemplates(node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined, ctx.templateContext),
+      sort: node.sort,
+      limit: node.limit,
+      offset: node.offset,
+    };
+    items = await ctx.cmsService.queryItems(query);
+  }
+
+  // Exclude current item if option is set and we have a current CMS context
+  if (node.excludeCurrentItem && ctx.cmsContext?.cms?._id) {
+    const currentId = ctx.cmsContext.cms._id as string;
+    items = items.filter(item => item._id !== currentId);
+  }
+
+  return items;
+}
+
+/**
+ * Get items from component props or template context (for sourceType: 'prop')
+ */
+function getPropItems(source: string, ctx: SSRContext): unknown[] {
+  // Resolve the source - can be a direct prop name or a template expression
+  if (source.startsWith('{{') && source.endsWith('}}')) {
+    // Template expression - resolve from template context (for nested lists)
+    // e.g., {{category.items}} where category is from parent list
+    const templateCtx = ctx.templateContext;
+    if (templateCtx) {
+      const path = source.slice(2, -2).trim(); // Extract "category.items"
+      const resolved = getNestedValue(templateCtx as Record<string, unknown>, path);
+      if (Array.isArray(resolved)) {
+        return resolved;
+      } else if (resolved !== undefined) {
+        // Warn if resolved to non-array value (likely a bug in template)
+        console.warn(`List source "${source}" resolved to non-array value (type: ${typeof resolved})`);
+      }
+    }
+    return [];
+  } else {
+    // Direct prop name - resolve from component props
+    const propValue = ctx.componentResolvedProps?.[source];
+    if (Array.isArray(propValue)) {
+      return propValue;
+    }
+
+    // Also try template context for prop mode (for cms context values)
+    if (ctx.cmsContext?.cms) {
+      const cmsValue = ctx.cmsContext.cms[source];
+      if (Array.isArray(cmsValue)) {
+        return cmsValue;
+      }
+    }
+  }
+  return [];
 }
 
 /**
@@ -617,9 +729,10 @@ async function renderNode(
     return '';
   }
 
-  // Handle CMSList nodes (async operation)
-  if (isCMSListNode(node)) {
-    return await processCMSList(node, ctx);
+  // Handle List nodes (async operation - handles both prop and collection source types)
+  // isListNode() also matches legacy 'cms-list' type for migration
+  if (isListNode(node)) {
+    return await processList(node, ctx);
   }
 
   const nodeType = 'type' in node ? node.type : undefined;