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

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

@@ -1,6 +1,7 @@
 import type { Editor } from 'mem-fs-editor';
-import { type BuildingBlock, type BuildingBlockConfig, type GenerateBuildingBlockAggregationConfig } from './types.js';
+import { type BuildingBlock, type BuildingBlockConfig } from './types.js';
 import { type CodeSnippet } from '../prompts/types.js';
+export { generateBuildingBlockAggregation, getUI5XmlDocument } from './processAggregation.js';
 /**
  * Generates a building block into the provided xml view file.
  *
@@ -10,15 +11,6 @@ import { type CodeSnippet } from '../prompts/types.js';
  * @returns {Editor} the updated memfs editor instance
  */
 export declare function generateBuildingBlock<T extends BuildingBlock>(basePath: string, config: BuildingBlockConfig<T>, fs?: Editor): Promise<Editor>;
-/**
- * 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 and mContent
- * @param {Editor} [fs] - the memfs editor instance
- * @returns {Editor} the updated memfs editor instance
- */
-export declare function generateBuildingBlockAggregation(basePath: string, config: GenerateBuildingBlockAggregationConfig, fs?: Editor): Promise<Editor>;
 /**
  * Method returns the manifest content for the required dependency library.
  *

package/dist/building-block/index.js

@@ -6,22 +6,23 @@ import { join, parse, relative } from 'node:path';
 import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
 import format from 'xml-formatter';
 import * as xpath from 'xpath';
-import { getMinimumUI5Version, getAppProgrammingLanguage } from '@sap-ux/project-access';
-import { BuildingBlockType, PAGE_AGGREGATIONS, PAGE_TEMPLATE_TYPE_FULL, bindingContextAbsolute } from './types.js';
+import { getMinimumUI5Version } from '@sap-ux/project-access';
+import { BuildingBlockType, PAGE_TEMPLATE_TYPE_FULL, bindingContextAbsolute } from './types.js';
 import { getErrorMessage, validateBasePath, validateDependenciesLibs } from '../common/validate.js';
 import { getTemplatePath } from '../templates.js';
 import { CodeSnippetLanguage } from '../prompts/types.js';
-import { CONFIG, copyTpl, createIdGenerator, detectTabSpacing, extendJSON, getRelativeTemplateComponentPath } from '../common/file.js';
+import { CONFIG, createIdGenerator, detectTabSpacing, extendJSON, getRelativeTemplateComponentPath } from '../common/file.js';
 import { getManifest, getManifestPath } from '../common/utils.js';
 import { getOrAddNamespace } from './prompts/utils/xml.js';
 import { i18nNamespaces, translate } from '../i18n.js';
-import { processBuildingBlock } from './processor.js';
+import { processBuildingBlock, resolveAggregationPath } from './processor.js';
+import { appendPageAggregations, ensureMissingAggregation, getPageAggregationNames, getUI5XmlDocument, validateFullPageTemplateVersion } from './processAggregation.js';
+export { generateBuildingBlockAggregation, getUI5XmlDocument } from './processAggregation.js';
 const PLACEHOLDERS = {
     'id': 'REPLACE_WITH_BUILDING_BLOCK_ID',
     'entitySet': 'REPLACE_WITH_ENTITY',
     'qualifier': 'REPLACE_WITH_A_QUALIFIER'
 };
-const PAGE_TEMPLATE_COMMENT = 'This is a sample template, event handlers should be added for implementation';
 /**
  * Returns true if the building block data represents a Page building block with the full template type.
  *
@@ -51,6 +52,9 @@ export async function generateBuildingBlock(basePath, config, fs) {
     const { path: manifestPath, content: manifest } = await getManifest(basePath, fs);
     // Read the view xml and template files and update contents of the view xml file
     const xmlDocument = getUI5XmlDocument(basePath, viewOrFragmentPath, fs);
+    if (aggregationPath) {
+        ensureMissingAggregation(xmlDocument, aggregationPath);
+    }
     const { updatedAggregationPath, processedBuildingBlockData, hasAggregation, aggregationNamespace } = processBuildingBlock({ ...buildingBlockData, generateId: fnGenerateId }, xmlDocument, manifestPath, manifest, aggregationPath, fs);
     const templateConfig = {
         hasAggregation,
@@ -58,9 +62,12 @@ export async function generateBuildingBlock(basePath, config, fs) {
     };
     const templateDocument = getTemplateDocument({ ...processedBuildingBlockData, generateId: fnGenerateId }, xmlDocument, fs, manifest, templateConfig);
     const fullPageTemplate = isFullPageTemplate(buildingBlockData);
+    const pageAggregationNames = getPageAggregationNames(buildingBlockData);
     if (fullPageTemplate) {
-        const pageData = buildingBlockData;
-        appendPageAggregations(fs, xmlDocument, templateDocument, fnGenerateId, pageData);
+        validateFullPageTemplateVersion(manifest);
+    }
+    if (pageAggregationNames) {
+        appendPageAggregations(fs, xmlDocument, templateDocument, fnGenerateId, pageAggregationNames, fullPageTemplate);
     }
     if (buildingBlockData.buildingBlockType === BuildingBlockType.RichTextEditor ||
         buildingBlockData.buildingBlockType === BuildingBlockType.RichTextEditorButtonGroups) {
@@ -72,9 +79,6 @@ export async function generateBuildingBlock(basePath, config, fs) {
         getOrAddNamespace(xmlDocument, 'sap.fe.macros.richtexteditor', 'richtexteditor');
     }
     fs = updateViewFile(basePath, viewOrFragmentPath, updatedAggregationPath, xmlDocument, templateDocument, fs, config.replace);
-    if (fullPageTemplate) {
-        await applyPageControllerTemplate(fs, basePath, viewOrFragmentPath);
-    }
     if (allowAutoAddDependencyLib && manifest && !validateDependenciesLibs(manifest, ['sap.fe.macros'])) {
         // "sap.fe.macros" is missing - enhance manifest.json for missing "sap.fe.macros"
         const manifestPath = await getManifestPath(basePath, fs);
@@ -89,271 +93,6 @@ export async function generateBuildingBlock(basePath, config, fs) {
     }
     return fs;
 }
-/**
- * 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;
-}
-/**
- * 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.mContent - optional inner XML content for the aggregation
- * @param aggContext.aggId - the generated unique ID for the aggregation element
- * @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');
-}
-/**
- * Appends the 7 Page building block aggregation fragments as child elements of the templateDocument root.
- *
- * @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 {Page} pageData - the Page building block data containing optional aggregation mContent
- */
-function appendPageAggregations(fs, xmlDocument, templateDocument, generateId, pageData) {
-    const fragMacrosNS = resolveMacrosPrefix(xmlDocument);
-    const macrosPrefix = `${fragMacrosNS}:`;
-    const pageElement = templateDocument.documentElement;
-    pageElement.appendChild(templateDocument.createComment(PAGE_TEMPLATE_COMMENT));
-    for (const aggName of PAGE_AGGREGATIONS) {
-        const mContent = pageData.aggregations?.[aggName] ?? '';
-        const aggId = generateId(aggName);
-        const aggContext = { macrosPrefix, mContent, aggId };
-        const aggDoc = buildPageAggregationFragment(fs, aggName, aggContext, fragMacrosNS, xmlDocument);
-        for (const node of Array.from(aggDoc.documentElement.childNodes)) {
-            if (node.nodeType === 1 /* Element */) {
-                node.setAttribute('id', aggId);
-                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
- */
-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);
-    }
-}
-/**
- * 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 and mContent
- * @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, mContent = '' } = 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 aggContext = { macrosPrefix, mContent, aggId };
-    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 === '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));
-    if (!hasExistingElementChildren && !hasTemplateComment) {
-        pageElement.appendChild(xmlDocument.createComment(PAGE_TEMPLATE_COMMENT));
-    }
-    for (const node of Array.from(aggDoc.documentElement.childNodes)) {
-        if (node.nodeType === 1 /* Element */) {
-            node.setAttribute('id', aggId);
-            pageElement.appendChild(xmlDocument.importNode(node, true));
-        }
-    }
-    sortPageAggregationChildren(pageElement);
-    const newXmlContent = new XMLSerializer().serializeToString(xmlDocument);
-    fs.write(join(basePath, viewPath), format(newXmlContent));
-    return fs;
-}
-/**
- * Copies the Page controller template (JS or TS) into the view directory if no controller file exists yet.
- * Uses getAppProgrammingLanguage to decide whether to generate a JS or TS controller stub.
- *
- * @param {Editor} fs - the memfs editor instance
- * @param {string} basePath - the base path of the application
- * @param {string} viewOrFragmentPath - the relative path of the view/fragment file
- */
-async function applyPageControllerTemplate(fs, basePath, viewOrFragmentPath) {
-    if (!viewOrFragmentPath.endsWith('.view.xml')) {
-        return;
-    }
-    const { dir: viewDir, name: viewName } = parse(viewOrFragmentPath);
-    const viewBaseName = viewName.replace(/\.view$/, '');
-    const tsControllerPath = join(basePath, viewDir, `${viewBaseName}.controller.ts`);
-    const jsControllerPath = join(basePath, viewDir, `${viewBaseName}.controller.js`);
-    // Skip if a controller already exists in either language to avoid duplicate stubs
-    if (fs.exists(tsControllerPath) || fs.exists(jsControllerPath)) {
-        return;
-    }
-    const detectedLanguage = await getAppProgrammingLanguage(basePath, fs);
-    const isTypeScript = detectedLanguage === 'TypeScript';
-    const controllerExt = isTypeScript ? 'ts' : 'js';
-    const controllerPath = isTypeScript ? tsControllerPath : jsControllerPath;
-    copyTpl(fs, getTemplatePath(`/building-block/page/Controller.${controllerExt}`), controllerPath);
-}
-/**
- * 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
- */
-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}`);
-    };
-    // Parse the xml view content
-    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;
-}
 /**
  * Method returns default values for metadata path.
  *
@@ -513,14 +252,17 @@ function getTemplateDocument(buildingBlockData, viewDocument, fs, manifest, temp
  * @returns {Editor} the updated memfs editor instance
  */
 function updateViewFile(basePath, viewPath, aggregationPath, viewDocument, templateDocument, fs, replace = false) {
-    const firstChild = viewDocument.firstChild;
-    if (!firstChild) {
+    const root = viewDocument.documentElement ?? viewDocument.firstChild;
+    if (!root) {
         throw new Error(`Unable to read namespace map from view ${viewPath}.`);
     }
-    const nsMap = firstChild?._nsMap ?? {};
+    const nsMap = root?._nsMap ?? {};
     const xpathSelect = xpath.useNamespaces(nsMap);
+    // XPath 1.0 does not support default namespaces: unprefixed names match only no-namespace
+    // elements. Rewrite each unprefixed step to a *[local-name()='X'] predicate.
+    const resolvedPath = resolveAggregationPath(aggregationPath);
     // Find target aggregated element and append template as child
-    const targetNodes = xpathSelect(aggregationPath, viewDocument);
+    const targetNodes = xpathSelect(resolvedPath, viewDocument);
     if (targetNodes && Array.isArray(targetNodes) && targetNodes.length > 0) {
         const targetNode = targetNodes[0];
         const sourceNode = viewDocument.importNode(templateDocument.documentElement, true);
@@ -577,11 +319,13 @@ export async function getSerializedFileContent(basePath, config, fs) {
     const { content: manifest, path: manifestPath } = await getManifest(basePath, fs, false);
     const fnGenerateId = buildingBlockData.generateId ?? (await createIdGenerator({ basePath, fsEditor: fs }));
     const content = getTemplateContent({ ...buildingBlockData, generateId: fnGenerateId }, xmlDocument, manifest, fs, true);
-    // For the full Page template, augment the snippet with all 7 aggregations
+    // For full Page templates, augment the snippet with all PAGE_AGGREGATIONS
     let viewOrFragmentContent = content;
-    const pageData = buildingBlockData;
-    const isFullPage = isFullPageTemplate(buildingBlockData);
-    if (isFullPage) {
+    const pageAggNames = getPageAggregationNames(buildingBlockData);
+    if (pageAggNames) {
+        if (isFullPageTemplate(buildingBlockData)) {
+            validateFullPageTemplateVersion(manifest);
+        }
         // Use the real view document for namespace resolution if available, otherwise create a minimal fallback
         const nsDoc = xmlDocument ??
             new DOMParser().parseFromString('<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns:macros="sap.fe.macros" xmlns="sap.m"/>', 'text/xml');
@@ -593,7 +337,7 @@ export async function getSerializedFileContent(basePath, config, fs) {
         const snippetMacrosNS = getOrAddNamespace(nsDoc, 'sap.fe.macros', 'macros') || 'macros';
         const snippetContent = `${content}`.replace(new RegExp(`^<(${snippetMacrosNS}:Page)`), `<$1 xmlns:${snippetMacrosNS}="sap.fe.macros"`);
         const snippetDoc = new DOMParser({ errorHandler: snippetErrorHandler }).parseFromString(snippetContent, 'text/xml');
-        appendPageAggregations(fs, nsDoc, snippetDoc, fnGenerateId, pageData);
+        appendPageAggregations(fs, nsDoc, snippetDoc, fnGenerateId, pageAggNames, isFullPageTemplate(buildingBlockData));
         const resultNode = snippetDoc.documentElement;
         viewOrFragmentContent = resultNode ? format(new XMLSerializer().serializeToString(resultNode)) : content;
     }

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

@@ -0,0 +1,81 @@
+import type { Editor } from 'mem-fs-editor';
+import { type BuildingBlock, type PageAggregationName, type GenerateBuildingBlockAggregationConfig } from './types.js';
+import type { Manifest } from '../common/types.js';
+import { type IdGeneratorFunction } from '../common/file.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 declare function getUI5XmlDocument(basePath: string, viewPath: string, fs: Editor): Document;
+/**
+ * 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 declare function getPageAggregationNames(data: BuildingBlock): readonly PageAggregationName[] | 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 declare function validateFullPageTemplateVersion(manifest: Manifest | undefined): void;
+/** 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 declare const AGGREGATION_ID_KEYS: Partial<Record<PageAggregationName, {
+    key: string;
+    base: string;
+}[]>>;
+/**
+ * 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 declare function buildAggregationIds(aggName: PageAggregationName, generateId: IdGeneratorFunction): Record<string, string>;
+/**
+ *
+ * @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 declare function appendPageAggregations(fs: Editor, xmlDocument: Document, templateDocument: Document, generateId: IdGeneratorFunction, aggNames?: readonly PageAggregationName[], useDefaults?: boolean): void;
+/**
+ * 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 declare function sortPageAggregationChildren(pageElement: Node): void;
+/**
+ * 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 declare function ensureMissingAggregation(xmlDocument: Document, aggregationPath: string): void;
+/**
+ * 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 declare function generateBuildingBlockAggregation(basePath: string, config: GenerateBuildingBlockAggregationConfig, fs?: Editor): Promise<Editor>;
+//# sourceMappingURL=processAggregation.d.ts.map

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, PAGE_FULL_TEMPLATE_MIN_UI5_VERSION, PAGE_TEMPLATE_COMMENT, PAGE_TEMPLATE_TYPE_FULL } 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 === PAGE_TEMPLATE_TYPE_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, PAGE_FULL_TEMPLATE_MIN_UI5_VERSION)) {
+        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, PAGE_FULL_TEMPLATE_MIN_UI5_VERSION, PAGE_TEMPLATE_TYPE_BASIC, PAGE_TEMPLATE_TYPE_FULL } 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, PAGE_FULL_TEMPLATE_MIN_UI5_VERSION);
     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: 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 }
+                    }
+                ]),
             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: PAGE_TEMPLATE_TYPE_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

@@ -380,8 +380,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;
     /**
@@ -393,6 +393,9 @@ export interface Page extends BuildingBlock {
 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_FULL_TEMPLATE_MIN_UI5_VERSION = "1.145.0";
+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 +415,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

@@ -39,4 +39,7 @@ export const PAGE_AGGREGATIONS = [
 ];
 export const PAGE_TEMPLATE_TYPE_FULL = 'full';
 export const PAGE_TEMPLATE_TYPE_BASIC = 'basic';
+export const PAGE_FULL_TEMPLATE_MIN_UI5_VERSION = '1.145.0';
+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/prompts/translations/i18n.d.ts

@@ -277,6 +277,7 @@ declare const ns1: {
     };
     pageBuildingBlock: {
         minUi5VersionRequirement: string;
+        fullTemplateMinUi5VersionRequirement: string;
     };
     richTextEditorBuildingBlock: {
         minUi5VersionRequirement: string;

package/dist/prompts/translations/i18n.js

@@ -305,7 +305,8 @@ const ns1 = {
         }
     },
     'pageBuildingBlock': {
-        'minUi5VersionRequirement': 'The Page building block feature requires SAPUI5 1.136.0 or higher. The current version is {{ minUI5Version }}, so the Page building block will not be added.'
+        'minUi5VersionRequirement': 'The Page building block feature requires SAPUI5 1.136.0 or higher. The current version is {{ minUI5Version }}, so the Page building block will not be added.',
+        'fullTemplateMinUi5VersionRequirement': 'The full Page building block feature requires SAPUI5 1.145.0 or higher. The current version is {{ minUI5Version }}, so the full template will not be added.'
     },
     'richTextEditorBuildingBlock': {
         'minUi5VersionRequirement': 'The Rich Text Editor building block feature requires SAPUI5 1.117.0 or higher. The current version is {{ minUI5Version }}, so the Rich Text Editor building block will not be added.'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sap-ux/fe-fpm-writer",
   "description": "SAP Fiori elements flexible programming model writer",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/SAP/open-ux-tools.git",
@@ -33,8 +33,8 @@
     "xpath": "0.0.34",
     "@sap-ux/fiori-annotation-api": "1.0.15",
     "@sap-ux/i18n": "1.0.2",
-    "@sap-ux/project-access": "2.1.6",
-    "@sap-ux/logger": "1.0.3"
+    "@sap-ux/logger": "1.0.3",
+    "@sap-ux/project-access": "2.1.6"
   },
   "devDependencies": {
     "@jest/globals": "30.4.1",

package/templates/building-block/page/actions.xml

@@ -1,4 +1,5 @@
 <<%- macrosPrefix %>actions>
     <!-- Actions aggregation -->
-    <%- mContent %>
+    <Button id="<%- ids.Button %>" text="Action 1" press=".onActionsClickAction1" type="Ghost" />
+    <Button id="<%- ids.Button1 %>" text="Action 2" press=".onActionsClickAction2" type="Ghost" />
 </<%- macrosPrefix %>actions>

package/templates/building-block/page/breadcrumbs.xml

@@ -1,4 +1,8 @@
 <<%- macrosPrefix %>breadcrumbs>
     <!-- Breadcrumbs aggregation -->
-    <%- mContent %>
+    <Breadcrumbs id="<%- ids.Breadcrumbs %>">
+        <Link id="<%- ids.Link %>" text="Home" press=".onBreadcrumbsPressHome" />
+        <Link id="<%- ids.Link1 %>" text="Page 1" press=".onBreadcrumbsPressPage1" />
+        <Link id="<%- ids.Link2 %>" text="Page 2" press=".onBreadcrumbsPressPage2" />
+    </Breadcrumbs>
 </<%- macrosPrefix %>breadcrumbs>

package/templates/building-block/page/footer.xml

@@ -1,4 +1,8 @@
 <<%- macrosPrefix %>footer>
     <!-- Footer aggregation -->
-    <%- mContent %>
+    <OverflowToolbar id="<%- ids.OverflowToolbar %>">
+        <ToolbarSpacer id="<%- ids.ToolbarSpacer %>" />
+        <Button id="<%- ids.Button %>" text="Approve" press=".onFooterApprove" type="Accept" icon="" />
+        <Button id="<%- ids.Button1 %>" text="Reject" press=".onFooterReject" type="Reject" icon="" />
+    </OverflowToolbar>
 </<%- macrosPrefix %>footer>

package/templates/building-block/page/headerContent.xml

@@ -1,4 +1,6 @@
 <<%- macrosPrefix %>headerContent>
     <!-- Header content aggregation (content after avatar) -->
-    <%- mContent %>
+    <VBox id="<%- ids.VBox %>">
+        <Title id="<%- ids.Title %>" text="Page Title" />
+    </VBox>
 </<%- macrosPrefix %>headerContent>

package/templates/building-block/page/items.xml

@@ -1,9 +1,11 @@
 <<%- macrosPrefix %>items>
     <!-- Main content -->
+<% if (showDefaultContent) { -%>
     <IconTabBar id="iconTabBar<%- aggId %>" class="sapUiResponsiveContentPadding">
         <items>
             <IconTabFilter id="iconTabFilter<%- aggId %>" text="Tab 1">
             </IconTabFilter>
         </items>
     </IconTabBar>
+<% } -%>
 </<%- macrosPrefix %>items>

package/templates/building-block/page/navigationActions.xml

@@ -1,4 +1,4 @@
 <<%- macrosPrefix %>navigationActions>
     <!-- Navigation actions aggregation -->
-    <%- mContent %>
+    <Button id="<%- ids.Button %>" icon="sap-icon://full-screen" press=".onNavigationActionsFullScreen" type="Transparent" />
 </<%- macrosPrefix %>navigationActions>

package/templates/building-block/page/titleContent.xml

@@ -1,4 +1,4 @@
 <<%- macrosPrefix %>titleContent>
     <!-- Title content aggregation (content next to title) -->
-    <%- mContent %>
+    <GenericTag id="<%- ids.GenericTag %>" text="Status" design="StatusIconHidden" status="Information" />
 </<%- macrosPrefix %>titleContent>

package/templates/building-block/page/Controller.js

@@ -1,17 +0,0 @@
-sap.ui.define([], function () {
-    'use strict';
-
-    return {
-        onPressHome: function (_event) {},
-
-        onPressPage1: function (_event) {},
-
-        onPressPage2: function (_event) {},
-
-        onFullScreen: function (_event) {},
-
-        onClickAction1: function (_event) {},
-
-        onClickAction2: function (_event) {}
-    };
-});

package/templates/building-block/page/Controller.ts

@@ -1,14 +0,0 @@
-import ExtensionAPI from 'sap/fe/core/ExtensionAPI';
-import Event from 'sap/ui/base/Event';
-
-export function onPressHome(this: ExtensionAPI, _event: Event): void {}
-
-export function onPressPage1(this: ExtensionAPI, _event: Event): void {}
-
-export function onPressPage2(this: ExtensionAPI, _event: Event): void {}
-
-export function onFullScreen(this: ExtensionAPI, _event: Event): void {}
-
-export function onClickAction1(this: ExtensionAPI, _event: Event): void {}
-
-export function onClickAction2(this: ExtensionAPI, _event: Event): void {}