@sap-ux/fe-fpm-writer 1.2.0 → 1.3.0

package/dist/building-block/processAggregation.js

@@ -0,0 +1,408 @@
+import { create as createStorage } from 'mem-fs';
+import { create } from 'mem-fs-editor';
+import { render } from 'ejs';
+import { join } from 'node:path';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import format from 'xml-formatter';
+import * as xpath from 'xpath';
+import { coerce, lt } from 'semver';
+import { getMinimumUI5Version } from '@sap-ux/project-access';
+import { BuildingBlockType, PAGE_AGGREGATIONS, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT, PAGE_TEMPLATE_COMMENT, PageTemplateType } from './types.js';
+import { getTemplatePath } from '../templates.js';
+import { createIdGenerator } from '../common/file.js';
+import { getErrorMessage } from '../common/validate.js';
+import { i18nNamespaces, translate } from '../i18n.js';
+import { getOrAddNamespace } from './prompts/utils/xml.js';
+import { resolveAggregationPath } from './processor.js';
+/**
+ * Returns the UI5 xml file document (view/fragment).
+ *
+ * @param {string} basePath - the base path
+ * @param {string} viewPath - the path of the xml view relative to the base path
+ * @param {Editor} fs - the memfs editor instance
+ * @returns {Document} the view xml file document
+ */
+export function getUI5XmlDocument(basePath, viewPath, fs) {
+    let viewContent;
+    try {
+        viewContent = fs.read(join(basePath, viewPath));
+    }
+    catch (error) {
+        throw new Error(`Unable to read xml view file. Details: ${getErrorMessage(error)}`);
+    }
+    const errorHandler = (level, message) => {
+        throw new Error(`Unable to parse xml view file. Details: [${level}] - ${message}`);
+    };
+    let viewDocument;
+    try {
+        viewDocument = new DOMParser({ errorHandler }).parseFromString(viewContent, 'text/xml');
+    }
+    catch (error) {
+        throw new Error(`Unable to parse xml view file. Details: ${getErrorMessage(error)}`);
+    }
+    return viewDocument;
+}
+/**
+ * Returns the aggregation names to append for a Page building block, or undefined if not a Page.
+ * Full template appends all PAGE_AGGREGATIONS; basic template appends nothing.
+ *
+ * @param data - the building block data
+ * @returns aggregation names array, or undefined if not a Page building block
+ */
+export function getPageAggregationNames(data) {
+    if (data.buildingBlockType !== BuildingBlockType.Page) {
+        return undefined;
+    }
+    return data.templateType === PageTemplateType.Full ? PAGE_AGGREGATIONS : undefined;
+}
+/**
+ * Throws if the manifest's minUI5Version is set and does not meet the 1.145.0 requirement for the full Page template.
+ * If minUI5Version is not set, it is treated as latest and passes the check.
+ *
+ * @param manifest - the manifest content, or undefined if not available
+ */
+export function validateFullPageTemplateVersion(manifest) {
+    const minUI5Version = manifest ? coerce(getMinimumUI5Version(manifest)) : undefined;
+    if (minUI5Version && lt(minUI5Version, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT)) {
+        const t = translate(i18nNamespaces.buildingBlock, 'pageBuildingBlock.');
+        throw new Error(`${t('fullTemplateMinUi5VersionRequirement', { minUI5Version: minUI5Version.version })}`);
+    }
+}
+/**
+ * Resolves the sap.fe.macros namespace prefix from the view document.
+ * If sap.fe.macros is the default namespace (no prefix), declares xmlns:macros on the document element
+ * so that generated prefixed elements like <macros:items> remain valid.
+ *
+ * @param xmlDocument - the view XML document
+ * @returns the resolved namespace prefix string (e.g. 'macros')
+ */
+function resolveMacrosPrefix(xmlDocument) {
+    const prefix = getOrAddNamespace(xmlDocument, 'sap.fe.macros', 'macros');
+    if (prefix === '') {
+        xmlDocument.documentElement.setAttributeNS('http://www.w3.org/2000/xmlns/', 'xmlns:macros', 'sap.fe.macros');
+        return 'macros';
+    }
+    return prefix;
+}
+/** IDs needed per aggregation template, keyed by the variable name used in the EJS template. */
+/** Controls to generate IDs for per aggregation. `key` is the EJS template variable name, `base` is passed to generateId. */
+export const AGGREGATION_ID_KEYS = {
+    breadcrumbs: [
+        { key: 'Breadcrumbs', base: 'breadcrumbs_breadcrumbs' },
+        { key: 'Link', base: 'breadcrumbs_link' },
+        { key: 'Link1', base: 'breadcrumbs_link_1' },
+        { key: 'Link2', base: 'breadcrumbs_link_2' }
+    ],
+    navigationActions: [{ key: 'Button', base: 'navigationActions_button' }],
+    titleContent: [{ key: 'GenericTag', base: 'titleContent_genericTag' }],
+    actions: [
+        { key: 'Button', base: 'actions_button' },
+        { key: 'Button1', base: 'actions_button_1' }
+    ],
+    headerContent: [
+        { key: 'VBox', base: 'headerContent_vbox' },
+        { key: 'Title', base: 'headerContent_title' }
+    ],
+    footer: [
+        { key: 'OverflowToolbar', base: 'footer_overflowToolbar' },
+        { key: 'ToolbarSpacer', base: 'footer_toolbarSpacer' },
+        { key: 'Button', base: 'footer_button' },
+        { key: 'Button1', base: 'footer_button_1' }
+    ]
+};
+/**
+ * Generates a map of unique IDs for all controls in a given Page aggregation template.
+ * Keys match the `ids.*` variable names referenced in the EJS templates.
+ *
+ * @param aggName - the aggregation name
+ * @param generateId - the project-aware ID generator
+ * @returns an object mapping each template variable name to a unique ID string
+ */
+export function buildAggregationIds(aggName, generateId) {
+    const entries = AGGREGATION_ID_KEYS[aggName] ?? [];
+    const validatedIds = [];
+    const ids = {};
+    for (const { key, base } of entries) {
+        const id = generateId(base, validatedIds);
+        ids[key] = id;
+        validatedIds.push(id);
+    }
+    return ids;
+}
+/**
+ * Renders a Page aggregation EJS template and parses it as an XML fragment document.
+ * Inherits all xmlns:* declarations from the view root so inner content can use any view-declared prefix.
+ *
+ * @param fs - the memfs editor instance
+ * @param aggName - the aggregation name (e.g. 'footer', 'items')
+ * @param aggContext - the EJS template context
+ * @param aggContext.macrosPrefix - the namespace prefix string (e.g. 'macros:')
+ * @param aggContext.aggId - the generated unique ID for the aggregation element
+ * @param aggContext.showDefaultContent - when true, the items template renders the default IconTabBar
+ * @param aggContext.ids - map of unique IDs for named controls in the template (e.g. ids.Button, ids.Link)
+ * @param fragMacrosNS - the namespace prefix resolved for sap.fe.macros
+ * @param xmlDocument - the view XML document (used to inherit namespace declarations)
+ * @returns parsed XML document whose documentElement contains the aggregation child nodes
+ */
+function buildPageAggregationFragment(fs, aggName, aggContext, fragMacrosNS, xmlDocument) {
+    const aggPath = getTemplatePath(`/building-block/page/${aggName}.xml`);
+    const aggContent = render(fs.read(aggPath), aggContext, {}); // NOSONAR - template is a controlled file on disk, not user input
+    const extraNamespaces = Array.from(xmlDocument.documentElement.attributes)
+        .filter((a) => a.name.startsWith('xmlns:') && a.name !== `xmlns:${fragMacrosNS}` && a.name !== 'xmlns:m')
+        .map((a) => `${a.name}="${a.value}"`)
+        .join(' ');
+    const wrapped = `<root xmlns:${fragMacrosNS}="sap.fe.macros" xmlns="sap.m" xmlns:m="sap.m" ${extraNamespaces}>${aggContent}</root>`;
+    const errorHandler = (level, message) => {
+        throw new Error(`Unable to parse page aggregation fragment '${aggName}'. Details: [${level}] - ${message}`);
+    };
+    return new DOMParser({ errorHandler }).parseFromString(wrapped, 'text/xml');
+}
+/**
+ *
+ * @param {Editor} fs - the memfs editor instance
+ * @param {Document} xmlDocument - the view XML document (used to resolve namespace prefixes)
+ * @param {Document} templateDocument - the template document whose root element receives the children
+ * @param {IdGeneratorFunction} generateId - function to generate unique IDs
+ * @param {readonly PageAggregationName[]} [aggNames] - aggregation names to append; defaults to all PAGE_AGGREGATIONS
+ * @param useDefaults - when true, the items aggregation renders its default IconTabBar content
+ */
+export function appendPageAggregations(fs, xmlDocument, templateDocument, generateId, aggNames = PAGE_AGGREGATIONS, useDefaults = true) {
+    const fragMacrosNS = resolveMacrosPrefix(xmlDocument);
+    const macrosPrefix = `${fragMacrosNS}:`;
+    const pageElement = templateDocument.documentElement;
+    pageElement.appendChild(templateDocument.createComment(PAGE_TEMPLATE_COMMENT));
+    for (const aggName of aggNames) {
+        const aggId = generateId(aggName);
+        const showDefaultContent = aggName === 'items' && useDefaults;
+        const ids = buildAggregationIds(aggName, generateId);
+        const aggContext = { macrosPrefix, aggId, showDefaultContent, ids };
+        const aggDoc = buildPageAggregationFragment(fs, aggName, aggContext, fragMacrosNS, xmlDocument);
+        for (const node of Array.from(aggDoc.documentElement.childNodes)) {
+            if (node.nodeType === 1 /* Element */) {
+                pageElement.appendChild(templateDocument.importNode(node, true));
+            }
+        }
+    }
+}
+/**
+ * Returns the local name of an Element if it belongs to the sap.fe.macros namespace, otherwise an empty string.
+ * This ensures only Page aggregation elements are sorted by position; non-macros elements fall back to the items slot.
+ *
+ * @param el - the DOM Element
+ * @returns the local name string, or '' if not a sap.fe.macros element
+ */
+function getElementLocalName(el) {
+    if (el.namespaceURI !== 'sap.fe.macros') {
+        return '';
+    }
+    return typeof el.localName === 'string' ? el.localName : '';
+}
+/**
+ * Builds a comparator for sorting XmlAggregationGroups by their position in aggNames.
+ * Unknown elements fall back to the position of 'items'. Ties are broken by original index.
+ *
+ * @param aggNames - ordered list of aggregation names
+ * @returns comparator function for Array.prototype.sort
+ */
+function buildAggregationComparator(aggNames) {
+    const itemsIdx = aggNames.indexOf('items');
+    const fallbackIdx = itemsIdx === -1 ? aggNames.length : itemsIdx;
+    return (a, b) => {
+        const aIdx = aggNames.indexOf(getElementLocalName(a.element));
+        const bIdx = aggNames.indexOf(getElementLocalName(b.element));
+        const aOrder = aIdx === -1 ? fallbackIdx : aIdx;
+        const bOrder = bIdx === -1 ? fallbackIdx : bIdx;
+        return aOrder === bOrder ? a.originalIndex - b.originalIndex : aOrder - bOrder;
+    };
+}
+/**
+ * Reorders the child elements of a macros:Page node to match the canonical PAGE_AGGREGATIONS order.
+ * Preserves relative order of siblings with the same local name. Pure whitespace text nodes are dropped
+ * because the xml-formatter call that follows will regenerate proper indentation.
+ *
+ * @param pageElement - the macros:Page DOM node whose children should be sorted
+ */
+export function sortPageAggregationChildren(pageElement) {
+    const allChildren = Array.from(pageElement.childNodes);
+    const aggNames = PAGE_AGGREGATIONS;
+    // Build pairs of [preceding comments, element] to preserve user comments.
+    // Comments that appear before the first element are treated as leading and will remain before all aggregation elements.
+    const groups = [];
+    const leadingComments = [];
+    let pendingComments = [];
+    let firstElementSeen = false;
+    for (const node of allChildren) {
+        if (node.nodeType === 8 /* Comment */) {
+            // Comments before the first element are leading; after, they are pending
+            (firstElementSeen ? pendingComments : leadingComments).push(node);
+        }
+        else if (node.nodeType === 1 /* Element */) {
+            firstElementSeen = true;
+            groups.push({ comments: pendingComments, element: node, originalIndex: groups.length });
+            pendingComments = [];
+        }
+        else if (node.nodeType === 3 /* Text */ && node.data?.trim()) {
+            // Preserve non-whitespace text nodes with their surrounding group
+            pendingComments.push(node);
+        }
+        // Pure whitespace text nodes are intentionally dropped (xml-formatter regenerates indentation)
+    }
+    groups.sort(buildAggregationComparator(aggNames));
+    while (pageElement.firstChild) {
+        pageElement.removeChild(pageElement.firstChild); // NOSONAR - xmldom nodes do not implement Node.remove()
+    }
+    // Re-insert leading comments first (always before any element)
+    for (const comment of leadingComments) {
+        pageElement.appendChild(comment);
+    }
+    for (const { comments, element } of groups) {
+        for (const comment of comments) {
+            pageElement.appendChild(comment);
+        }
+        pageElement.appendChild(element);
+    }
+    // Trailing orphan comments (after the last element)
+    for (const comment of pendingComments) {
+        pageElement.appendChild(comment);
+    }
+}
+/**
+ * Ensures a namespaced aggregation element exists in the XML document at the given aggregation path.
+ * If the final segment (e.g. 'macros:items') is missing from the DOM, the parent node is located
+ * via the path prefix and the element is inserted in place. This allows generateBuildingBlock to
+ * handle missing aggregation containers in a single write pass, avoiding a separate commit.
+ *
+ * @param {Document} xmlDocument - The XML document to mutate
+ * @param {string} aggregationPath - Full XPath to the target aggregation (e.g. '/mvc:View/macros:Page/macros:items')
+ */
+export function ensureMissingAggregation(xmlDocument, aggregationPath) {
+    const nsMap = xmlDocument.documentElement?._nsMap ?? {};
+    const xpathSelect = xpath.useNamespaces(nsMap);
+    if (xpathSelect(resolveAggregationPath(aggregationPath), xmlDocument).length > 0) {
+        return;
+    }
+    const lastSlash = aggregationPath.lastIndexOf('/');
+    if (lastSlash <= 0) {
+        return;
+    }
+    const lastSegment = aggregationPath.slice(lastSlash + 1);
+    const colonIdx = lastSegment.indexOf(':');
+    if (colonIdx === -1) {
+        return;
+    }
+    const prefix = lastSegment.slice(0, colonIdx);
+    const localName = lastSegment.slice(colonIdx + 1);
+    // getOrAddNamespace resolves the URI from the document and declares it if missing.
+    // Fall back to 'sap.fe.macros' for the 'macros' prefix in case it's declared as a default
+    // namespace (xmlns="sap.fe.macros") and therefore absent from the prefix→URI nsMap.
+    let namespaceUri = nsMap[prefix];
+    if (!namespaceUri && prefix === 'macros') {
+        namespaceUri = 'sap.fe.macros';
+    }
+    if (!namespaceUri) {
+        return;
+    }
+    const resolvedPrefix = getOrAddNamespace(xmlDocument, namespaceUri, prefix);
+    if (resolvedPrefix === '' && prefix) {
+        xmlDocument.documentElement.setAttributeNS('http://www.w3.org/2000/xmlns/', `xmlns:${prefix}`, namespaceUri);
+    }
+    // Rebuild xpathSelect with the prefix explicitly mapped so XPath resolves prefixed steps
+    // correctly even when the document uses sap.fe.macros as its default namespace.
+    const xpathSelectWithPrefix = xpath.useNamespaces({ ...nsMap, [prefix]: namespaceUri });
+    const parentNodes = xpathSelectWithPrefix(resolveAggregationPath(aggregationPath.slice(0, lastSlash)), xmlDocument);
+    if (parentNodes.length === 0) {
+        return;
+    }
+    parentNodes[0].appendChild(xmlDocument.createElementNS(namespaceUri, `${prefix}:${localName}`));
+}
+/**
+ * Wraps any direct sap.fe.macros children of pageElement that are not named Page aggregations
+ * (i.e. loose building blocks like macros:Form, macros:Table) inside a <macros:items> element.
+ * Called before inserting a new named aggregation so the DOM stays well-formed.
+ *
+ * @param pageElement - the macros:Page DOM element
+ * @param xmlDocument - the owner document
+ * @param macrosNS - the sap.fe.macros namespace URI
+ * @param macrosPrefix - the resolved prefix string (e.g. 'macros')
+ */
+function wrapLooseBuildingBlocksInItems(pageElement, xmlDocument, macrosNS, macrosPrefix) {
+    const aggregationSet = new Set(PAGE_AGGREGATIONS);
+    const looseChildren = Array.from(pageElement.childNodes).filter((n) => n.nodeType === 1 /* Element */ &&
+        n.namespaceURI === macrosNS &&
+        !aggregationSet.has(n.localName));
+    if (looseChildren.length === 0) {
+        return;
+    }
+    const itemsName = `${macrosPrefix}:items`;
+    let itemsEl = Array.from(pageElement.childNodes).find((n) => n.nodeType === 1 && n.namespaceURI === macrosNS && n.localName === 'items');
+    if (!itemsEl) {
+        itemsEl = xmlDocument.createElementNS(macrosNS, itemsName);
+        pageElement.insertBefore(itemsEl, looseChildren[0]);
+    }
+    for (const child of looseChildren) {
+        itemsEl.appendChild(child);
+    }
+}
+/**
+ * Appends a single Page building block aggregation template to an existing `<macros:Page>` element in a view XML file.
+ *
+ * @param {string} basePath - the base path of the application
+ * @param {GenerateBuildingBlockAggregationConfig} config - the aggregation configuration containing aggregationName
+ * @param {Editor} [fs] - the memfs editor instance
+ * @returns {Editor} the updated memfs editor instance
+ */
+export async function generateBuildingBlockAggregation(basePath, config, fs) {
+    const { viewPath, buildingBlockType, aggregationName: aggName } = config;
+    fs ??= create(createStorage());
+    if (buildingBlockType !== BuildingBlockType.Page) {
+        throw new Error(`generateBuildingBlockAggregation: unsupported building block type '${buildingBlockType}'. Only 'Page' is currently supported.`);
+    }
+    const xmlDocument = getUI5XmlDocument(basePath, viewPath, fs);
+    const generateId = await createIdGenerator({ basePath, fsEditor: fs });
+    const aggId = generateId(aggName);
+    const fragMacrosNS = resolveMacrosPrefix(xmlDocument);
+    const macrosPrefix = `${fragMacrosNS}:`;
+    const ids = buildAggregationIds(aggName, generateId);
+    const aggContext = { macrosPrefix, aggId, showDefaultContent: false, ids };
+    const aggDoc = buildPageAggregationFragment(fs, aggName, aggContext, fragMacrosNS, xmlDocument);
+    const nsMap = xmlDocument.documentElement?._nsMap ?? {};
+    // Prefix-agnostic XPath — works regardless of the alias used in the view for sap.fe.macros.
+    const xpathSelect = xpath.useNamespaces(nsMap);
+    const pageNodes = xpathSelect(`//*[local-name()='Page' and namespace-uri()='sap.fe.macros']`, xmlDocument);
+    if (!pageNodes || !Array.isArray(pageNodes) || pageNodes.length === 0) {
+        throw new Error(`Page element (sap.fe.macros) not found in view ${viewPath}.`);
+    }
+    const pageElement = pageNodes[0];
+    if (aggName === 'footer' && pageElement.nodeType === 1 /* Element */) {
+        pageElement.setAttribute('showFooter', 'true');
+    }
+    const childNodes = Array.from(pageElement.childNodes);
+    const hasExistingAggregation = childNodes.some((node) => node.nodeType === 1 /* Element */ &&
+        node.localName === aggName &&
+        node.namespaceURI === (nsMap[fragMacrosNS] ?? 'sap.fe.macros'));
+    if (hasExistingAggregation) {
+        sortPageAggregationChildren(pageElement);
+        const existingXmlContent = new XMLSerializer().serializeToString(xmlDocument);
+        fs.write(join(basePath, viewPath), format(existingXmlContent));
+        return fs;
+    }
+    const hasExistingElementChildren = childNodes.some((n) => n.nodeType === 1 /* Element */);
+    const hasTemplateComment = childNodes.some((n) => n.nodeType === 8 /* Comment */ && n.data?.includes(PAGE_TEMPLATE_COMMENT));
+    // Move any loose macros building blocks (e.g. macros:Form, macros:Table) into macros:items
+    // before inserting the new named aggregation so the Page DOM stays well-formed.
+    const macrosNsUri = nsMap[fragMacrosNS] ?? 'sap.fe.macros';
+    wrapLooseBuildingBlocksInItems(pageElement, xmlDocument, macrosNsUri, fragMacrosNS);
+    if (!hasExistingElementChildren && !hasTemplateComment) {
+        pageElement.appendChild(xmlDocument.createComment(PAGE_TEMPLATE_COMMENT));
+    }
+    for (const node of Array.from(aggDoc.documentElement.childNodes)) {
+        if (node.nodeType === 1 /* Element */) {
+            pageElement.appendChild(xmlDocument.importNode(node, true));
+        }
+    }
+    sortPageAggregationChildren(pageElement);
+    const newXmlContent = new XMLSerializer().serializeToString(xmlDocument);
+    fs.write(join(basePath, viewPath), format(newXmlContent));
+    return fs;
+}
+//# sourceMappingURL=processAggregation.js.map

package/dist/building-block/processor.d.ts

@@ -51,6 +51,16 @@ export declare const BUTTON_GROUP_CONFIGS: {
  * Configuration map for building block types.
  */
 export declare const BUILDING_BLOCK_CONFIG: Partial<Record<BuildingBlockType, BuildingBlockTemplateConfig>>;
+/**
+ * Rewrites an XPath aggregation path so that unprefixed steps match elements in any namespace.
+ * XPath 1.0 with useNamespaces does not support default namespaces: an unprefixed name only
+ * matches no-namespace nodes. Steps like "IconTabBar" or "items" (in the sap.m default ns)
+ * would never match. This converts them to *[local-name()='step'] predicates.
+ *
+ * @param {string} aggregationPath - The original aggregation XPath
+ * @returns {string} The rewritten XPath safe for use with xpath.useNamespaces
+ */
+export declare function resolveAggregationPath(aggregationPath: string): string;
 /**
  * Processes building block configuration.
  *

package/dist/building-block/processor.js

@@ -291,7 +291,7 @@ function processRichTextEditorButtonGroups(buildingBlockData, context) {
     }
     const existingButtonGroupsMap = new Map();
     if (hasAggregation && xmlDocument && updatedAggregationPath) {
-        const xpathSelect = xpath.useNamespaces(xmlDocument.firstChild._nsMap);
+        const xpathSelect = xpath.useNamespaces(xmlDocument.documentElement?._nsMap ?? {});
         // Example: [<Element: richtexteditor:buttonGroups>] containing all ButtonGroup children
         const buttonGroupsElements = xpathSelect(updatedAggregationPath, xmlDocument);
         if (buttonGroupsElements.length > 0) {
@@ -314,6 +314,23 @@ function processRichTextEditorButtonGroups(buildingBlockData, context) {
     }
     buildingBlockData.buttonGroups = mergeButtonGroups(existingButtonGroupsMap, buildingBlockData);
 }
+/**
+ * Rewrites an XPath aggregation path so that unprefixed steps match elements in any namespace.
+ * XPath 1.0 with useNamespaces does not support default namespaces: an unprefixed name only
+ * matches no-namespace nodes. Steps like "IconTabBar" or "items" (in the sap.m default ns)
+ * would never match. This converts them to *[local-name()='step'] predicates.
+ *
+ * @param {string} aggregationPath - The original aggregation XPath
+ * @returns {string} The rewritten XPath safe for use with xpath.useNamespaces
+ */
+export function resolveAggregationPath(aggregationPath) {
+    return aggregationPath.replace(/\/([A-Za-z_][A-Za-z0-9_.-]*)(?=\/|$)/g, (_match, step) => {
+        if (step.includes(':')) {
+            return `/${step}`;
+        }
+        return `/*[local-name()='${step}']`;
+    });
+}
 /**
  * Updates aggregation path based on XML document structure.
  *
@@ -326,9 +343,11 @@ function processRichTextEditorButtonGroups(buildingBlockData, context) {
  * @returns {object} Object containing the updated aggregation path
  */
 function updateAggregationPath(xmlDocument, aggregationPath, config, namespace) {
-    const xpathSelect = xpath.useNamespaces(xmlDocument.firstChild._nsMap);
+    const nsMap = xmlDocument.documentElement?._nsMap ?? {};
+    const xpathSelect = xpath.useNamespaces(nsMap);
+    const resolvedPath = resolveAggregationPath(aggregationPath);
     // First, get the target element from the aggregationPath
-    const targetElement = xpathSelect(aggregationPath, xmlDocument);
+    const targetElement = xpathSelect(resolvedPath, xmlDocument);
     if (!targetElement || !Array.isArray(targetElement) || targetElement.length === 0) {
         return { updatedAggregationPath: aggregationPath, hasElement: false };
     }

package/dist/building-block/prompts/questions/page.js

@@ -1,7 +1,10 @@
 import { i18nNamespaces, translate } from '../../../i18n.js';
 import { getBuildingBlockIdPrompt, getViewOrFragmentPathPrompt, getAggregationPathPrompt } from '../utils/index.js';
-import { BuildingBlockType, PAGE_TEMPLATE_TYPE_BASIC, PAGE_TEMPLATE_TYPE_FULL } from '../../types.js';
+import { BuildingBlockType, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT, PageTemplateType } from '../../types.js';
 import { SapShortTextType, SapLongTextType } from '@sap-ux/i18n';
+import { getMinimumUI5Version } from '@sap-ux/project-access';
+import { coerce, lt } from 'semver';
+import { getManifest } from '../../../common/utils.js';
 /**
  * Returns a list of prompts required to generate a page building block.
  *
@@ -10,19 +13,26 @@ import { SapShortTextType, SapLongTextType } from '@sap-ux/i18n';
  */
 export async function getPageBuildingBlockPrompts(context) {
     const t = translate(i18nNamespaces.buildingBlock, 'prompts.page.');
+    const { content: manifest } = await getManifest(context.appPath, context.fs, false);
+    const minUI5Version = manifest ? coerce(getMinimumUI5Version(manifest)) : undefined;
+    const hideTemplateType = !!minUI5Version && lt(minUI5Version, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT);
     return {
         questions: [
-            {
-                type: 'list',
-                name: 'buildingBlockData.templateType',
-                message: t('templateType.message'),
-                default: PAGE_TEMPLATE_TYPE_BASIC,
-                choices: [
-                    { value: PAGE_TEMPLATE_TYPE_BASIC, name: t('templateType.basic') },
-                    { value: PAGE_TEMPLATE_TYPE_FULL, name: t('templateType.full') }
-                ],
-                guiOptions: { mandatory: true }
-            },
+            ...(hideTemplateType
+                ? []
+                : [
+                    {
+                        type: 'list',
+                        name: 'buildingBlockData.templateType',
+                        message: t('templateType.message'),
+                        default: PageTemplateType.Basic,
+                        choices: [
+                            { value: PageTemplateType.Basic, name: t('templateType.basic') },
+                            { value: PageTemplateType.Full, name: t('templateType.full') }
+                        ],
+                        guiOptions: { mandatory: true }
+                    }
+                ]),
             getViewOrFragmentPathPrompt(context, t('viewOrFragmentPath.validate'), {
                 message: t('viewOrFragmentPath.message'),
                 guiOptions: {
@@ -69,7 +79,8 @@ export async function getPageBuildingBlockPrompts(context) {
         ],
         initialAnswers: {
             buildingBlockData: {
-                buildingBlockType: BuildingBlockType.Page
+                buildingBlockType: BuildingBlockType.Page,
+                ...(hideTemplateType ? { templateType: PageTemplateType.Basic } : {})
             }
         }
     };

package/dist/building-block/prompts/utils/xml.js

@@ -1,5 +1,6 @@
 import { DOMParser } from '@xmldom/xmldom';
 import * as xpath from 'xpath';
+import { MACROS_NAMESPACE_URI } from '../../types.js';
 /**
  * Converts the provided xpath string from `/mvc:View/Page/content` to
  * `/mvc:View/*[local-name()='Page']/*[local-name()='content']`.
@@ -14,6 +15,29 @@ export const augmentXpathWithLocalNames = (path) => {
     }
     return result.join('/');
 };
+/**
+ * If the given node is a macros:Page element that has no macros:items child, adds a synthesized
+ * macros:items path to the result map so callers can target it as an aggregation path.
+ * ensureMissingAggregation in generateBuildingBlock will create the DOM element when needed.
+ *
+ * @param node - the current DOM node being visited
+ * @param parentNode - accumulated XPath prefix up to (but not including) this node
+ * @param macrosNamespace - the resolved macros namespace prefix (e.g. 'macros')
+ * @param result - mutable map of XPath choices to augment
+ */
+function addMacrosItemsPathIfMissing(node, parentNode, macrosNamespace, result) {
+    if (node.localName !== 'Page' || node.namespaceURI !== MACROS_NAMESPACE_URI) {
+        return;
+    }
+    const resolvedPrefix = macrosNamespace || 'macros';
+    const macrosItemsName = `${resolvedPrefix}:items`;
+    const hasItemsChild = Array.from(node.childNodes).some((child) => child.nodeType === child.ELEMENT_NODE && child.localName === 'items');
+    if (!hasItemsChild) {
+        const pageStep = node.prefix ? node.nodeName : `${resolvedPrefix}:Page`;
+        const itemsPath = `${parentNode}/${pageStep}/${macrosItemsName}`;
+        result[itemsPath] = augmentXpathWithLocalNames(itemsPath);
+    }
+}
 /**
  * Returns a list of xpath strings for each element of the xml file provided.
  *
@@ -44,10 +68,11 @@ export function getXPathStringsForXmlFile(xmlFilePath, fs) {
             // This prevents suggesting insertion points outside macros:Page when a macros:Page is present.
             hasPageMacroChild = Array.from(node.childNodes).some((child) => child.nodeType === child.ELEMENT_NODE &&
                 child.localName === 'Page' &&
-                child.nodeName === pageMacroDefinition);
+                child.namespaceURI === MACROS_NAMESPACE_URI);
             if (!hasPageMacroChild) {
                 result[`${parentNode}/${node.nodeName}`] = augmentXpathWithLocalNames(`${parentNode}/${node.nodeName}`);
             }
+            addMacrosItemsPathIfMissing(node, parentNode, macrosNamespace || 'macros', result);
             const childNodes = Array.from(node.childNodes);
             for (const childNode of childNodes) {
                 if (childNode.nodeType === childNode.ELEMENT_NODE) {

package/dist/building-block/types.d.ts

@@ -1,5 +1,14 @@
 import type { IdGeneratorFunction } from '../common/file.js';
 import type { CustomElement, CustomFragment, EventHandler, FragmentContentData, Position } from '../common/types.js';
+export declare const PageTemplateType: {
+    readonly Full: "full";
+    readonly Basic: "basic";
+};
+export type PageTemplateType = (typeof PageTemplateType)[keyof typeof PageTemplateType];
+/** Minimum UI5 version required for page building blocks. */
+export declare const MIN_UI5_VERSION_PAGE_BUILDING_BLOCK: "1.136.0";
+/** Minimum UI5 version required for full layout page building blocks. */
+export declare const MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT: "1.145.0";
 /**
  * Building block type.
  *
@@ -380,8 +389,8 @@ export interface Page extends BuildingBlock {
     description?: string;
     /**
      * The template type for the page building block.
-     * 'full' generates a full page template with all aggregations and controller stubs.
-     * 'basic' generates a minimal self-closing tag (default behavior).
+     * 'full' generates a full page template with all aggregations.
+     * 'basic' generates a minimal self-closing <macros:Page/> with no aggregations.
      */
     templateType?: PageTemplateType;
     /**
@@ -390,9 +399,8 @@ export interface Page extends BuildingBlock {
      */
     aggregations?: Partial<Record<PageAggregationName, string>>;
 }
-export declare const PAGE_TEMPLATE_TYPE_FULL: "full";
-export declare const PAGE_TEMPLATE_TYPE_BASIC: "basic";
-export type PageTemplateType = typeof PAGE_TEMPLATE_TYPE_FULL | typeof PAGE_TEMPLATE_TYPE_BASIC;
+export declare const PAGE_TEMPLATE_COMMENT = "This is a sample template, event handlers should be added for implementation";
+export declare const MACROS_NAMESPACE_URI = "sap.fe.macros";
 /**
  * A group of XML nodes representing one Page aggregation element and its preceding sibling comments.
  * Used when re-ordering aggregation children under a macros:Page element.
@@ -412,8 +420,6 @@ export interface GenerateBuildingBlockAggregationConfig {
     buildingBlockType: BuildingBlockType;
     /** Name of the aggregation to append. */
     aggregationName: PageAggregationName;
-    /** Optional inner XML content for the aggregation. */
-    mContent?: string;
 }
 /**
  * Represents a custom filter to be used inside the FilterBar.

package/dist/building-block/types.js

@@ -1,3 +1,11 @@
+export const PageTemplateType = {
+    Full: 'full',
+    Basic: 'basic'
+};
+/** Minimum UI5 version required for page building blocks. */
+export const MIN_UI5_VERSION_PAGE_BUILDING_BLOCK = '1.136.0';
+/** Minimum UI5 version required for full layout page building blocks. */
+export const MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT = '1.145.0';
 /**
  * Building block type.
  *
@@ -37,6 +45,6 @@ export const PAGE_AGGREGATIONS = [
     'items',
     'footer'
 ];
-export const PAGE_TEMPLATE_TYPE_FULL = 'full';
-export const PAGE_TEMPLATE_TYPE_BASIC = 'basic';
+export const PAGE_TEMPLATE_COMMENT = 'This is a sample template, event handlers should be added for implementation';
+export const MACROS_NAMESPACE_URI = 'sap.fe.macros';
 //# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -21,9 +21,8 @@ export { enableFPM } from './app/index.js';
 export type { FPMConfig } from './app/index.js';
 export { validateBasePath, validateVersion } from './common/validate.js';
 export { createIdGenerator, type IdGeneratorFunction, getRelativeTemplateComponentPath } from './common/file.js';
-export { BuildingBlockType } from './building-block/types.js';
-export type { FilterBar, Form, Chart, Field, FieldFormatOptions, Table, BuildingBlockConfig, Page, CustomColumn, CustomFilterField, CustomFormField, RichTextEditor, ButtonGroupConfig, Action, PageTemplateType } from './building-block/types.js';
-export { PAGE_TEMPLATE_TYPE_FULL, PAGE_TEMPLATE_TYPE_BASIC, PAGE_AGGREGATIONS } from './building-block/types.js';
+export { BuildingBlockType, PageTemplateType, PAGE_AGGREGATIONS, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK, MIN_UI5_VERSION_PAGE_BUILDING_BLOCK_FULL_LAYOUT } from './building-block/types.js';
+export type { FilterBar, Form, Chart, Field, FieldFormatOptions, Table, BuildingBlockConfig, Page, CustomColumn, CustomFilterField, CustomFormField, RichTextEditor, ButtonGroupConfig, Action } from './building-block/types.js';
 export type { PageAggregationName, GenerateBuildingBlockAggregationConfig } from './building-block/types.js';
 export { generateBuildingBlock, getSerializedFileContent, generateBuildingBlockAggregation } from './building-block/index.js';
 export type { ChartPromptsAnswer, FilterBarPromptsAnswer, FormPromptsAnswer, TablePromptsAnswer, PagePromptsAnswer, RichTextEditorPromptsAnswer, RichTextEditorButtonGroupsPromptsAnswer, BuildingBlockTypePromptsAnswer } from './building-block/prompts/questions/index.js';