mcp-magento-cms 1.0.3 → 1.2.0

package/src/pageBuilderElements.js

@@ -0,0 +1,789 @@
+/**
+ * Magento Page Builder native content-type composers (project-agnostic).
+ * Covers core types from Magento_PageBuilder master templates.
+ * Theme CSS class names are passed via css_classes — never hardcoded here.
+ */
+
+const ROW_ATTRS =
+  'data-enable-parallax="0" data-parallax-speed="0.5" data-background-images="{}" ' +
+  'data-background-type="image" data-video-loop="true" data-video-play-only-visible="true" ' +
+  'data-video-lazy-load="true" data-video-fallback-src=""';
+
+const FLEX_COL =
+  'justify-content:flex-start;display:flex;flex-direction:column;' +
+  'background-position:left top;background-size:cover;background-repeat:no-repeat;background-attachment:scroll';
+
+const WIDTH_FOR_COUNT = {
+  1: '100%',
+  2: '50%',
+  3: '33.3333%',
+  4: '25%',
+  5: '20%',
+  6: '16.6667%',
+};
+
+/** All Magento_PageBuilder core content types this package can compose. */
+export const PAGEBUILDER_ELEMENT_TYPES = [
+  'row',
+  'column-group',
+  'column-line',
+  'column',
+  'columns', // convenience: column-group + line + equal columns
+  'text',
+  'heading',
+  'image',
+  'buttons',
+  'button-item',
+  'banner',
+  'html',
+  'divider',
+  'video',
+  'map',
+  'tabs',
+  'tab-item',
+  'slider',
+  'slide',
+  'products',
+  'block',
+];
+
+export class StyleBag {
+  constructor() {
+    /** @type {Record<string, string>} */
+    this.styles = {};
+  }
+
+  /** @param {string} css */
+  add(css) {
+    const id = genStyleId();
+    this.styles[id] = css;
+    return id;
+  }
+
+  toHtml() {
+    const entries = Object.entries(this.styles);
+    if (!entries.length) return '';
+    const rules = entries
+      .map(([id, css]) => `#html-body [data-pb-style=${id}]{${css}}`)
+      .join('');
+    return `<style>${rules}</style>`;
+  }
+}
+
+function genStyleId() {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let id = '';
+  for (let i = 0; i < 7; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+
+export function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+function looksLikeHtml(value) {
+  return /<[^>]+>/.test(String(value || ''));
+}
+
+export function normalizeHtml(htmlContent) {
+  const t = String(htmlContent || '').trim();
+  if (!t) return '<p></p>';
+  if (!looksLikeHtml(t)) {
+    return String(t)
+      .split(/\r\n|\r|\n/)
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .map((l) => `<p>${escapeHtml(l)}</p>`)
+      .join('') || '<p></p>';
+  }
+  return t;
+}
+
+function classAttr(cssClasses) {
+  const c = String(cssClasses || '').trim();
+  return c ? ` class="${escapeHtml(c)}"` : '';
+}
+
+function mergeClass(...parts) {
+  return parts
+    .map((p) => String(p || '').trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function childrenHtml(node, bag) {
+  const kids = node.children || node.elements || [];
+  if (!Array.isArray(kids) || !kids.length) return '';
+  return kids.map((c) => composeElement(c, bag)).join('');
+}
+
+/**
+ * Compose one Page Builder element (and nested children).
+ * @param {object} node
+ * @param {StyleBag} bag
+ */
+export function composeElement(node, bag) {
+  if (!node || typeof node !== 'object') {
+    throw new Error('composeElement: node must be an object');
+  }
+  const type = String(node.type || node.content_type || '')
+    .toLowerCase()
+    .trim();
+  if (!type) throw new Error('composeElement: missing type');
+
+  switch (type) {
+    case 'row':
+      return composeRow(node, bag);
+    case 'columns':
+    case 'column_group':
+    case 'column-group':
+      return composeColumnGroup(node, bag);
+    case 'column-line':
+    case 'column_line':
+      return composeColumnLine(node, bag);
+    case 'column':
+      return composeColumn(node, bag);
+    case 'text':
+      return composeText(node, bag);
+    case 'heading':
+      return composeHeading(node, bag);
+    case 'image':
+      return composeImage(node, bag);
+    case 'buttons':
+      return composeButtons(node, bag);
+    case 'button-item':
+    case 'button_item':
+    case 'button':
+      return composeButtonItem(node, bag);
+    case 'banner':
+      return composeBanner(node, bag);
+    case 'html':
+      return composeHtml(node, bag);
+    case 'divider':
+      return composeDivider(node, bag);
+    case 'video':
+      return composeVideo(node, bag);
+    case 'map':
+      return composeMap(node, bag);
+    case 'tabs':
+      return composeTabs(node, bag);
+    case 'tab-item':
+    case 'tab_item':
+    case 'tab':
+      return composeTabItem(node, bag);
+    case 'slider':
+      return composeSlider(node, bag);
+    case 'slide':
+      return composeSlide(node, bag);
+    case 'products':
+      return composeProducts(node, bag);
+    case 'block':
+    case 'cms_block':
+      return composeBlock(node, bag);
+    default:
+      throw new Error(
+        `Unsupported Page Builder type "${type}". Supported: ${PAGEBUILDER_ELEMENT_TYPES.join(', ')}`
+      );
+  }
+}
+
+/**
+ * @param {object[]} sections
+ * @returns {{ html: string, used_types: string[], allow_full_bleed: boolean }}
+ */
+export function composeDocument(sections) {
+  if (!Array.isArray(sections) || !sections.length) {
+    throw new Error('composeDocument: sections must be a non-empty array');
+  }
+  const bag = new StyleBag();
+  const used = new Set();
+  const walk = (n) => {
+    if (!n || typeof n !== 'object') return;
+    const t = String(n.type || n.content_type || '').toLowerCase();
+    if (t) used.add(t);
+    for (const c of n.children || n.elements || n.columns || n.tabs || n.slides || n.items || []) {
+      walk(c);
+    }
+  };
+  sections.forEach(walk);
+
+  const body = sections.map((s) => composeElement(s, bag)).join('');
+  const html = body + bag.toHtml();
+  const allowFullBleed = sections.some(
+    (s) =>
+      String(s.type || '').toLowerCase() === 'row' &&
+      String(s.appearance || '').toLowerCase() === 'full-bleed'
+  );
+  return {
+    html,
+    used_types: [...used],
+    allow_full_bleed: allowFullBleed,
+  };
+}
+
+// —— Row ——
+
+function composeRow(node, bag) {
+  const appearance = String(node.appearance || 'contained').toLowerCase();
+  const allowed = ['contained', 'full-width', 'full-bleed'];
+  if (!allowed.includes(appearance)) {
+    throw new Error(`row appearance must be one of: ${allowed.join(', ')}`);
+  }
+  const styleId = bag.add(FLEX_COL);
+  const css = classAttr(node.css_classes);
+  const inner = childrenHtml(node, bag);
+
+  if (appearance === 'full-bleed') {
+    return (
+      `<div${css} data-content-type="row" data-appearance="full-bleed" ${ROW_ATTRS} ` +
+      `data-element="main" data-pb-style="${styleId}">${inner}</div>`
+    );
+  }
+  if (appearance === 'full-width') {
+    const innerId = bag.add('');
+    return (
+      `<div${css} data-content-type="row" data-appearance="full-width" ${ROW_ATTRS} ` +
+      `data-element="main" data-pb-style="${styleId}">` +
+      `<div class="row-full-width-inner" data-element="inner" data-pb-style="${innerId}">${inner}</div></div>`
+    );
+  }
+  // contained
+  return (
+    `<div${css} data-content-type="row" data-appearance="contained" ${ROW_ATTRS} ` +
+    `data-element="main" data-pb-style="${styleId}">` +
+    `<div data-element="inner">${inner}</div></div>`
+  );
+}
+
+// —— Columns ——
+
+function composeColumnGroup(node, bag) {
+  // Convenience: { type:'columns', columns:[{width?, children}] }
+  if (Array.isArray(node.columns) && node.columns.length) {
+    const n = node.columns.length;
+    const defaultW = WIDTH_FOR_COUNT[n] || `${(100 / n).toFixed(4)}%`;
+    const cols = node.columns.map((col) =>
+      composeColumn(
+        {
+          type: 'column',
+          width: col.width || defaultW,
+          css_classes: col.css_classes,
+          children: col.children || col.elements || [],
+        },
+        bag
+      )
+    );
+    const gId = bag.add(
+      'display:flex;background-position:left top;background-size:cover;background-repeat:no-repeat;background-attachment:scroll;'
+    );
+    const lineId = bag.add('display:flex;justify-content:flex-start;');
+    const css = classAttr(mergeClass('pagebuilder-column-group', node.css_classes));
+    return (
+      `<div${css} data-content-type="column-group" data-grid-size="12" data-background-images="{}" ` +
+      `data-element="main" data-pb-style="${gId}">` +
+      `<div class="pagebuilder-column-line" data-content-type="column-line" data-element="main" data-pb-style="${lineId}">` +
+      `${cols.join('')}</div></div>`
+    );
+  }
+  const gId = bag.add(
+    'display:flex;background-position:left top;background-size:cover;background-repeat:no-repeat;background-attachment:scroll;'
+  );
+  const css = classAttr(mergeClass('pagebuilder-column-group', node.css_classes));
+  return (
+    `<div${css} data-content-type="column-group" data-grid-size="12" data-background-images="{}" ` +
+    `data-element="main" data-pb-style="${gId}">${childrenHtml(node, bag)}</div>`
+  );
+}
+
+function composeColumnLine(node, bag) {
+  const lineId = bag.add('display:flex;justify-content:flex-start;');
+  const css = classAttr(mergeClass('pagebuilder-column-line', node.css_classes));
+  return (
+    `<div${css} data-content-type="column-line" data-element="main" data-pb-style="${lineId}">` +
+    `${childrenHtml(node, bag)}</div>`
+  );
+}
+
+function composeColumn(node, bag) {
+  const width = String(node.width || '100%');
+  const styleId = bag.add(
+    `${FLEX_COL};width:${width};align-self:stretch`
+  );
+  const css = classAttr(mergeClass('pagebuilder-column', node.css_classes));
+  return (
+    `<div${css} data-content-type="column" data-appearance="full-height" data-background-images="{}" ` +
+    `data-element="main" data-pb-style="${styleId}">${childrenHtml(node, bag)}</div>`
+  );
+}
+
+// —— Text / Heading ——
+
+function composeText(node, bag) {
+  const styleId = bag.add('border-style:none');
+  const html = normalizeHtml(node.html ?? node.content ?? node.text ?? '');
+  const css = classAttr(mergeClass('bypass-html-filter', node.css_classes));
+  return (
+    `<div${css} data-content-type="text" data-appearance="default" data-element="main" ` +
+    `data-pb-style="${styleId}">${html}</div>`
+  );
+}
+
+function composeHeading(node, bag) {
+  const level = String(node.heading_type || node.level || 'h2').toLowerCase();
+  const tag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(level) ? level : 'h2';
+  const text = node.html != null ? String(node.html) : escapeHtml(String(node.text || node.content || ''));
+  const styleId = bag.add('text-align:left;border-style:none');
+  const css = classAttr(node.css_classes);
+  // Magento master: attributes on the heading element itself
+  return (
+    `<${tag}${css} data-content-type="heading" data-appearance="default" data-element="main" ` +
+    `data-pb-style="${styleId}">${text}</${tag}>`
+  );
+}
+
+// —— Image ——
+
+function composeImage(node, bag) {
+  const src = String(node.src || node.desktop_image || node.url || '').trim();
+  if (!src) throw new Error('image requires src (or desktop_image)');
+  const mobile = String(node.mobile_src || node.mobile_image || src).trim();
+  const alt = escapeHtml(String(node.alt || ''));
+  const caption = node.caption != null ? String(node.caption) : '';
+  const href = String(node.link_url || node.href || '').trim();
+  const mainId = bag.add('border-style:none');
+  const imgId = bag.add('max-width:100%;height:auto');
+  const imgMId = bag.add('max-width:100%;height:auto');
+  const css = classAttr(node.css_classes);
+  const appearance = String(node.appearance || 'full-width');
+
+  const imgs =
+    `<img class="pagebuilder-mobile-hidden" src="${escapeHtml(src)}" alt="${alt}" title="${alt}" ` +
+    `loading="lazy" data-element="desktop_image" data-pb-style="${imgId}">` +
+    `<img class="pagebuilder-mobile-only" src="${escapeHtml(mobile)}" alt="${alt}" title="${alt}" ` +
+    `loading="lazy" data-element="mobile_image" data-pb-style="${imgMId}">`;
+
+  const body = href
+    ? `<a href="${escapeHtml(href)}" target="" data-link-type="default" data-element="link">${imgs}</a>`
+    : imgs;
+
+  const cap = caption
+    ? `<figcaption data-element="caption">${caption}</figcaption>`
+    : `<figcaption data-element="caption"></figcaption>`;
+
+  return (
+    `<figure${css} data-content-type="image" data-appearance="${escapeHtml(appearance)}" ` +
+    `data-element="main" data-pb-style="${mainId}">${body}${cap}</figure>`
+  );
+}
+
+// —— Buttons ——
+
+function composeButtons(node, bag) {
+  const items = Array.isArray(node.items)
+    ? node.items
+    : Array.isArray(node.children)
+      ? node.children
+      : [];
+  const itemsHtml = items
+    .map((it) =>
+      composeButtonItem(
+        { type: 'button-item', ...it, text: it.text || it.label, url: it.url || it.href || it.link_url },
+        bag
+      )
+    )
+    .join('');
+  const appearance = String(node.appearance || 'inline');
+  const css = classAttr(node.css_classes);
+  return (
+    `<div${css} data-content-type="buttons" data-appearance="${escapeHtml(appearance)}" ` +
+    `data-element="main">${itemsHtml}</div>`
+  );
+}
+
+function composeButtonItem(node, bag) {
+  const label = String(node.text || node.label || node.link_text || 'Button');
+  const href = String(node.url || node.href || node.link_url || '#').trim();
+  const btnType = String(node.button_type || node.style || 'primary').replace(/^pagebuilder-button-/, '');
+  const btnClass = `pagebuilder-button-${btnType}`;
+  const styleId = bag.add('display:inline-block');
+  const extra = String(node.css_classes || '').trim();
+  const cls = mergeClass(btnClass, extra);
+  return (
+    `<div class="${escapeHtml(cls)}" data-content-type="button-item" data-appearance="default" ` +
+    `data-element="main" data-pb-style="${styleId}">` +
+    `<a class="${escapeHtml(btnClass)}" href="${escapeHtml(href)}" target="" data-link-type="default" data-element="link">` +
+    `<span data-element="link_text">${escapeHtml(label)}</span></a></div>`
+  );
+}
+
+// —— Banner ——
+
+function composeBanner(node, bag) {
+  const appearance = String(node.appearance || 'poster');
+  const bg = String(node.background_image || node.src || '').trim();
+  const contentHtml = normalizeHtml(node.content_html || node.html || node.content || '');
+  const showButton = String(node.show_button || (node.button_text ? 'always' : 'never')).toLowerCase();
+  const buttonText = String(node.button_text || '');
+  const linkUrl = String(node.link_url || node.href || '').trim();
+  const minHeight = String(node.min_height || '300px');
+  const overlayColor = node.overlay_color != null ? String(node.overlay_color) : '';
+
+  const mainId = bag.add('border-style:none');
+  const wrapId = bag.add(`min-height:${minHeight};background-position:center center;background-size:cover;`);
+  const overlayId = bag.add(
+    `min-height:${minHeight};padding:0;background-color:${overlayColor || 'transparent'};`
+  );
+
+  const bgAttr = bg
+    ? `{&quot;desktop_image&quot;:&quot;${String(bg).replace(/"/g, '')}&quot;}`
+    : '{}';
+
+  const buttonHtml =
+    showButton === 'never'
+      ? `<div data-element="button" style="display:none"></div>`
+      : `<button type="button" class="pagebuilder-banner-button" data-element="button">${escapeHtml(buttonText || 'Button')}</button>`;
+
+  const posterInner =
+    `<div class="pagebuilder-banner-wrapper" data-background-images="${bgAttr}" data-background-type="image" ` +
+    `data-video-loop="true" data-video-play-only-visible="true" data-video-lazy-load="true" data-video-fallback-src="" ` +
+    `data-element="wrapper" data-pb-style="${wrapId}">` +
+    `<div class="pagebuilder-overlay pagebuilder-poster-overlay" data-overlay-color="${escapeHtml(overlayColor)}" ` +
+    `data-element="overlay" data-pb-style="${overlayId}">` +
+    `<div class="pagebuilder-poster-content"><div data-element="content">${contentHtml}</div>${buttonHtml}` +
+    `</div></div></div>`;
+
+  const css = classAttr(node.css_classes);
+  const showBtnAttr = showButton === 'hover' ? 'hover' : showButton === 'always' ? 'always' : 'never';
+
+  if (linkUrl && showBtnAttr !== 'never') {
+    return (
+      `<div${css} data-content-type="banner" data-appearance="${escapeHtml(appearance)}" ` +
+      `data-show-button="${showBtnAttr}" data-show-overlay="always" data-element="main" data-pb-style="${mainId}">` +
+      `<a href="${escapeHtml(linkUrl)}" target="" data-link-type="default" data-element="link" ` +
+      `title="${escapeHtml(buttonText || '')}">${posterInner}</a></div>`
+    );
+  }
+
+  return (
+    `<div${css} data-content-type="banner" data-appearance="${escapeHtml(appearance)}" ` +
+    `data-show-button="${showBtnAttr}" data-show-overlay="always" data-element="main" data-pb-style="${mainId}">` +
+    `<div data-element="empty_link">${posterInner}</div></div>`
+  );
+}
+
+// —— HTML / Divider / Video / Map ——
+
+function composeHtml(node, bag) {
+  // Magento HTML content type stores markup as text content (escaped when saved via stage);
+  // for master format we put raw HTML inside and rely on bypass-html-filter on storefront.
+  const styleId = bag.add('border-style:none');
+  const html = String(node.html ?? node.content ?? '');
+  const css = classAttr(mergeClass('bypass-html-filter', node.css_classes));
+  return (
+    `<div${css} data-content-type="html" data-appearance="default" data-element="main" ` +
+    `data-pb-style="${styleId}">${html}</div>`
+  );
+}
+
+function composeDivider(node, bag) {
+  const mainId = bag.add('border-style:none;text-align:center');
+  const thickness = String(node.line_thickness || node.thickness || '1px');
+  const color = String(node.line_color || node.color || '#cccccc');
+  const width = String(node.line_width || node.width || '100%');
+  const lineId = bag.add(
+    `border-bottom-width:${thickness};border-bottom-style:solid;border-bottom-color:${color};width:${width};`
+  );
+  const css = classAttr(node.css_classes);
+  return (
+    `<div${css} data-content-type="divider" data-appearance="default" data-element="main" data-pb-style="${mainId}">` +
+    `<hr data-element="line" data-pb-style="${lineId}"></div>`
+  );
+}
+
+function composeVideo(node, bag) {
+  const src = String(node.src || node.video_source || node.url || '').trim();
+  if (!src) throw new Error('video requires src');
+  const mainId = bag.add('border-style:none');
+  const innerId = bag.add('');
+  const wrapId = bag.add('');
+  const css = classAttr(node.css_classes);
+  const hosted = /youtube|youtu\.be|vimeo|player\./i.test(src);
+  const media = hosted
+    ? `<iframe frameborder="0" allowfullscreen src="${escapeHtml(src)}" data-element="video"></iframe>`
+    : `<video controls src="${escapeHtml(src)}" data-element="video"></video>`;
+  return (
+    `<div${css} data-content-type="video" data-appearance="default" data-element="main" data-pb-style="${mainId}">` +
+    `<div class="pagebuilder-video-inner" data-element="inner" data-pb-style="${innerId}">` +
+    `<div class="pagebuilder-video-wrapper" data-element="wrapper" data-pb-style="${wrapId}">` +
+    `<div class="pagebuilder-video-container">${media}</div></div></div></div>`
+  );
+}
+
+function composeMap(node, bag) {
+  const locations = node.locations || [
+    {
+      latitude: node.latitude ?? node.lat ?? 0,
+      longitude: node.longitude ?? node.lng ?? 0,
+      location_name: node.location_name || node.name || '',
+    },
+  ];
+  const locJson = escapeHtml(JSON.stringify(locations));
+  const height = String(node.height || '300px');
+  const styleId = bag.add(`height:${height};border-style:none`);
+  const css = classAttr(node.css_classes);
+  return (
+    `<div${css} data-content-type="map" data-appearance="default" data-show-controls="true" ` +
+    `data-locations="${locJson}" data-element="main" data-pb-style="${styleId}"></div>`
+  );
+}
+
+// —— Tabs ——
+
+function composeTabs(node, bag) {
+  const tabs = Array.isArray(node.tabs) ? node.tabs : node.children || [];
+  if (!tabs.length) throw new Error('tabs requires tabs[]');
+  const mainId = bag.add('border-style:none');
+  const navId = bag.add('');
+  const contentId = bag.add('');
+  const css = classAttr(node.css_classes);
+  const defaultActive = Number(node.default_active ?? 0);
+
+  const nav = tabs
+    .map((tab, i) => {
+      const id = tab.id || `tab${genStyleId()}`;
+      tab._id = id;
+      const active = i === defaultActive ? ' true' : '';
+      const name = escapeHtml(String(tab.name || tab.title || `Tab ${i + 1}`));
+      return (
+        `<li role="tab" class="tab-header" data-element="headers" data-active="${active.trim() || 'false'}">` +
+        `<a href="#${id}" class="tab-title"><span class="tab-title">${name}</span></a></li>`
+      );
+    })
+    .join('');
+
+  const panels = tabs
+    .map((tab) =>
+      composeTabItem(
+        {
+          type: 'tab-item',
+          id: tab._id,
+          name: tab.name || tab.title,
+          css_classes: tab.css_classes,
+          children: tab.children || tab.elements || [],
+        },
+        bag
+      )
+    )
+    .join('');
+
+  return (
+    `<div${css} data-content-type="tabs" data-appearance="default" data-element="main" data-pb-style="${mainId}">` +
+    `<ul role="tablist" class="tabs-navigation" data-element="navigation" data-pb-style="${navId}">${nav}</ul>` +
+    `<div class="tabs-content" data-element="content" data-pb-style="${contentId}">${panels}</div></div>`
+  );
+}
+
+function composeTabItem(node, bag) {
+  const id = node.id || `tab${genStyleId()}`;
+  const styleId = bag.add(FLEX_COL);
+  const css = classAttr(node.css_classes);
+  return (
+    `<div id="${escapeHtml(id)}"${css} data-content-type="tab-item" data-appearance="default" ` +
+    `data-element="main" data-pb-style="${styleId}">${childrenHtml(node, bag)}</div>`
+  );
+}
+
+// —— Slider / Slide ——
+
+function composeSlider(node, bag) {
+  const slides = Array.isArray(node.slides) ? node.slides : node.children || [];
+  const mainId = bag.add(`min-height:${node.min_height || '300px'};border-style:none`);
+  const css = classAttr(mergeClass('pagebuilder-slider', node.css_classes));
+  const showDots = node.show_dots === false ? 'false' : 'true';
+  const showArrows = node.show_arrows === false ? 'false' : 'true';
+  const autoplay = node.autoplay ? 'true' : 'false';
+  const slidesHtml = slides
+    .map((s) => composeSlide({ type: 'slide', ...s }, bag))
+    .join('');
+  return (
+    `<div${css} data-content-type="slider" data-appearance="default" data-autoplay="${autoplay}" ` +
+    `data-autoplay-speed="${escapeHtml(String(node.autoplay_speed || '4000'))}" ` +
+    `data-fade="false" data-infinite-loop="true" data-show-arrows="${showArrows}" data-show-dots="${showDots}" ` +
+    `data-element="main" data-pb-style="${mainId}">${slidesHtml}</div>`
+  );
+}
+
+function composeSlide(node, bag) {
+  const bg = String(node.background_image || node.src || '').trim();
+  const contentHtml = normalizeHtml(node.content_html || node.html || node.content || '');
+  const showButton = String(node.show_button || (node.button_text ? 'always' : 'never')).toLowerCase();
+  const buttonText = String(node.button_text || '');
+  const linkUrl = String(node.link_url || node.href || '').trim();
+  const minHeight = String(node.min_height || '300px');
+  const appearance = String(node.appearance || 'poster');
+
+  const mainId = bag.add('border-style:none');
+  const wrapId = bag.add(`min-height:${minHeight};background-position:center center;background-size:cover;`);
+  const overlayId = bag.add(`min-height:${minHeight};padding:0;background-color:transparent;`);
+  const bgAttr = bg
+    ? `{&quot;desktop_image&quot;:&quot;${String(bg).replace(/"/g, '')}&quot;}`
+    : '{}';
+
+  const buttonHtml =
+    showButton === 'never'
+      ? ''
+      : `<button type="button" class="pagebuilder-slide-button" data-element="button">${escapeHtml(buttonText || 'Button')}</button>`;
+
+  const inner =
+    `<div class="pagebuilder-slide-wrapper" data-background-images="${bgAttr}" data-background-type="image" ` +
+    `data-element="wrapper" data-pb-style="${wrapId}">` +
+    `<div class="pagebuilder-overlay pagebuilder-poster-overlay" data-overlay-color="" data-element="overlay" ` +
+    `data-pb-style="${overlayId}"><div class="pagebuilder-poster-content">` +
+    `<div data-element="content">${contentHtml}</div>${buttonHtml}</div></div></div>`;
+
+  const css = classAttr(node.css_classes);
+  const showBtnAttr = showButton === 'always' ? 'always' : showButton === 'hover' ? 'hover' : 'never';
+
+  if (linkUrl) {
+    return (
+      `<div${css} data-content-type="slide" data-appearance="${escapeHtml(appearance)}" ` +
+      `data-show-button="${showBtnAttr}" data-show-overlay="always" data-element="main" data-pb-style="${mainId}">` +
+      `<a href="${escapeHtml(linkUrl)}" target="" data-link-type="default" data-element="link">${inner}</a></div>`
+    );
+  }
+  return (
+    `<div${css} data-content-type="slide" data-appearance="${escapeHtml(appearance)}" ` +
+    `data-show-button="${showBtnAttr}" data-show-overlay="always" data-element="main" data-pb-style="${mainId}">` +
+    `<div data-element="empty_link">${inner}</div></div>`
+  );
+}
+
+// —— Products / Block (widget wrappers) ——
+
+function composeProducts(node, bag) {
+  const appearance = String(node.appearance || 'grid');
+  const styleId = bag.add('border-style:none');
+  const css = classAttr(node.css_classes);
+  let inner = String(node.html || node.widget_html || '').trim();
+
+  if (!inner) {
+    const skus = Array.isArray(node.skus) ? node.skus : [];
+    const count = Number(node.products_count || (skus.length ? skus.length : 5));
+    const template =
+      appearance === 'carousel'
+        ? 'Magento_PageBuilder::catalog/product/widget/content/carousel.phtml'
+        : 'Magento_PageBuilder::catalog/product/widget/content/grid.phtml';
+
+    if (skus.length) {
+      // Magento widget conditions_encoded uses a compact substitute alphabet.
+      const raw = JSON.stringify({
+        '1': {
+          type: 'Magento\\CatalogWidget\\Model\\Rule\\Condition\\Combine',
+          aggregator: 'all',
+          value: '1',
+          new_child: '',
+        },
+        '1--1': {
+          type: 'Magento\\CatalogWidget\\Model\\Rule\\Condition\\Product',
+          attribute: 'sku',
+          operator: '()',
+          value: skus.join(','),
+        },
+      });
+      const encoded = encodeWidgetConditions(raw);
+      inner =
+        `{{widget type="Magento\\CatalogWidget\\Block\\Product\\ProductsList" ` +
+        `template="${template}" show_pager="0" products_count="${count}" ` +
+        `conditions_encoded="${encoded}" type_name="Catalog Products List"}}`;
+    } else if (node.category_id) {
+      const raw = JSON.stringify({
+        '1': {
+          type: 'Magento\\CatalogWidget\\Model\\Rule\\Condition\\Combine',
+          aggregator: 'all',
+          value: '1',
+          new_child: '',
+        },
+        '1--1': {
+          type: 'Magento\\CatalogWidget\\Model\\Rule\\Condition\\Product',
+          attribute: 'category_ids',
+          operator: '==',
+          value: String(node.category_id),
+        },
+      });
+      const encoded = encodeWidgetConditions(raw);
+      inner =
+        `{{widget type="Magento\\CatalogWidget\\Block\\Product\\ProductsList" ` +
+        `template="${template}" show_pager="0" products_count="${count}" ` +
+        `conditions_encoded="${encoded}" type_name="Catalog Products List"}}`;
+    } else {
+      inner = '<!-- Pass skus[], category_id, or widget_html — or configure Products in Admin -->';
+    }
+  }
+
+  return (
+    `<div${css} data-content-type="products" data-appearance="${escapeHtml(appearance)}" ` +
+    `data-element="main" data-pb-style="${styleId}">${inner}</div>`
+  );
+}
+
+/** Magento \Magento\Widget\Helper\Conditions-style encoding for widget directives. */
+function encodeWidgetConditions(json) {
+  return String(json)
+    .replace(/\[/g, '^[')
+    .replace(/\]/g, '^]')
+    .replace(/{/g, '`{')
+    .replace(/}/g, '`}')
+    .replace(/"/g, '``')
+    .replace(/\\/g, '^\\')
+    .replace(/</g, '^<')
+    .replace(/>/g, '^>');
+}
+
+
+function composeBlock(node, bag) {
+  const styleId = bag.add('border-style:none');
+  const css = classAttr(node.css_classes);
+  let inner = String(node.html || node.widget_html || '').trim();
+  if (!inner) {
+    const blockId = node.block_id || node.identifier;
+    if (!blockId) throw new Error('block requires block_id or identifier (or html)');
+    inner =
+      `{{widget type="Magento\\Cms\\Block\\Widget\\Block" ` +
+      `template="widget/static_block/default.phtml" ` +
+      `block_id="${escapeHtml(String(blockId))}" type_name="CMS Static Block"}}`;
+  }
+  return (
+    `<div${css} data-content-type="block" data-appearance="default" data-element="main" ` +
+    `data-pb-style="${styleId}">${inner}</div>`
+  );
+}
+
+/** Machine-readable catalog for list_section_types / agents. */
+export function describeElements() {
+  return [
+    { type: 'row', params: ['appearance=contained|full-width|full-bleed', 'css_classes?', 'children[]'], notes: 'full-bleed only when explicitly requested; then allow_full_bleed=true on save' },
+    { type: 'columns', params: ['columns[{width?, css_classes?, children[]}]', 'css_classes?'], notes: 'Convenience for column-group + column-line + equal widths' },
+    { type: 'column-group', params: ['children[] (column-line or columns)', 'css_classes?'] },
+    { type: 'column', params: ['width%', 'css_classes?', 'children[]'] },
+    { type: 'text', params: ['html|content|text', 'css_classes?'] },
+    { type: 'heading', params: ['text|html', 'heading_type=h1..h6', 'css_classes?'] },
+    { type: 'image', params: ['src', 'alt?', 'mobile_src?', 'link_url?', 'caption?', 'css_classes?'] },
+    { type: 'buttons', params: ['items[{text,url,button_type?}]', 'appearance?', 'css_classes?'] },
+    { type: 'banner', params: ['background_image', 'content_html', 'show_button?', 'button_text?', 'link_url?', 'min_height?', 'css_classes?'], notes: 'Prefer native Banner button over separate Buttons in hero' },
+    { type: 'html', params: ['html', 'css_classes?'], notes: 'Use sparingly; prefer native types' },
+    { type: 'divider', params: ['line_color?', 'line_thickness?', 'line_width?', 'css_classes?'] },
+    { type: 'video', params: ['src', 'css_classes?'] },
+    { type: 'map', params: ['locations[]|{latitude,longitude}', 'height?', 'css_classes?'] },
+    { type: 'tabs', params: ['tabs[{name, children[]}]', 'default_active?', 'css_classes?'] },
+    { type: 'slider', params: ['slides[{background_image, content_html, button_text?, link_url?}]', 'autoplay?', 'css_classes?'] },
+    { type: 'products', params: ['skus[]|category_id|html', 'appearance=grid|carousel', 'products_count?', 'css_classes?'] },
+    { type: 'block', params: ['block_id|identifier|html', 'css_classes?'] },
+  ];
+}