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

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, PageTemplateType, 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.
  *
@@ -29,7 +30,7 @@ const PAGE_TEMPLATE_COMMENT = 'This is a sample template, event handlers should
  * @returns true if full Page template
  */
 function isFullPageTemplate(data) {
-    return data.buildingBlockType === BuildingBlockType.Page && data.templateType === PAGE_TEMPLATE_TYPE_FULL;
+    return data.buildingBlockType === BuildingBlockType.Page && data.templateType === PageTemplateType.Full;
 }
 /**
  * Generates a building block into the provided xml view file.
@@ -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