refactor: Enhance XML Fragment context menu control with addXMLPlugin Integration

.changeset/stupid-clouds-search.md

@@ -0,0 +1,7 @@
+---
+"@sap-ux/adp-tooling": patch
+"@sap-ux-private/preview-middleware-client": patch
+"@sap-ux/preview-middleware": patch
+---
+
+refactor: Enhance XML Fragment context menu control with addXMLPlugin Integration

packages/adp-tooling/src/preview/adp-preview.ts

@@ -9,7 +9,13 @@ import { createAbapServiceProvider } from '@sap-ux/system-access';
 import type { LayeredRepositoryService, MergedAppDescriptor } from '@sap-ux/axios-extension';
 
 import RoutesHandler from './routes-handler';
-import type { AdpPreviewConfig, CommonChangeProperties, DescriptorVariant, OperationType } from '../types';
+import type {
+    AdpPreviewConfig,
+    CommonChangeProperties,
+    DescriptorVariant,
+    OperationType,
+    CommonAdditionalChangeInfoProperties
+} from '../types';
 import type { Editor } from 'mem-fs-editor';
 import {
     addAnnotationFile,
@@ -233,13 +239,15 @@ export class AdpPreview {
      * @param {CommonChangeProperties} change - An object containing properties common to all change types.
      * @param {Editor} fs - An instance of an editor interface for file system operations.
      * @param {Logger} logger - An instance of a logging interface for message logging.
+     * @param {CommonAdditionalChangeInfoProperties} [additionalChangeInfo] - An optional object containing extended change properties.
      * @returns {Promise<void>} A promise that resolves when the change request has been processed.
      */
     async onChangeRequest(
         type: OperationType,
         change: CommonChangeProperties,
         fs: Editor,
-        logger: Logger
+        logger: Logger,
+        additionalChangeInfo?: CommonAdditionalChangeInfoProperties
     ): Promise<void> {
         switch (type) {
             case 'read':
@@ -249,7 +257,7 @@ export class AdpPreview {
                 break;
             case 'write':
                 if (isAddXMLChange(change)) {
-                    addXmlFragment(this.util.getProject().getSourcePath(), change, fs, logger);
+                    addXmlFragment(this.util.getProject().getSourcePath(), change, fs, logger, additionalChangeInfo);
                 }
                 if (isAddAnnotationChange(change)) {
                     await addAnnotationFile(

packages/adp-tooling/src/preview/change-handler.ts

@@ -1,5 +1,11 @@
 import type { Editor } from 'mem-fs-editor';
-import type { AddXMLChange, CommonChangeProperties, CodeExtChange, AnnotationFileChange } from '../types';
+import type {
+    AddXMLChange,
+    CommonChangeProperties,
+    CodeExtChange,
+    AnnotationFileChange,
+    CommonAdditionalChangeInfoProperties
+} from '../types';
 import { ChangeType } from '../types';
 import { basename, join } from 'path';
 import { DirName, FileName } from '@sap-ux/project-access';
@@ -211,11 +217,18 @@ export function isAddAnnotationChange(change: CommonChangeProperties): change is
  * @param {AddXMLChange} change - The change data, including the fragment path.
  * @param {Editor} fs - The mem-fs-editor instance.
  * @param {Logger} logger - The logging instance.
+ * @param {CommonAdditionalChangeInfoProperties} additionalChangeInfo - Optional extended change properties.
  */
-export function addXmlFragment(basePath: string, change: AddXMLChange, fs: Editor, logger: Logger): void {
+export function addXmlFragment(
+    basePath: string,
+    change: AddXMLChange,
+    fs: Editor,
+    logger: Logger,
+    additionalChangeInfo?: CommonAdditionalChangeInfoProperties
+): void {
     const { fragmentPath } = change.content;
     const fullPath = join(basePath, DirName.Changes, fragmentPath);
-    const templateConfig = fragmentTemplateDefinitions[change.content?.templateName ?? ''];
+    const templateConfig = fragmentTemplateDefinitions[additionalChangeInfo?.templateName ?? ''];
     try {
         if (templateConfig) {
             const fragmentTemplatePath = join(__dirname, '../../templates/rta', templateConfig.path);

packages/adp-tooling/src/types.ts

@@ -218,6 +218,10 @@ export interface CommonChangeProperties {
     texts: Record<string, unknown>;
 }
 
+export interface CommonAdditionalChangeInfoProperties {
+    templateName?: string;
+}
+
 export interface ManifestChangeProperties {
     fileName: string;
     fileType: string;

packages/adp-tooling/test/unit/preview/adp-preview.test.ts

@@ -486,7 +486,13 @@ describe('AdaptationProject', () => {
         it('should add an XML fragment if type is "write" and change is AddXMLChange', async () => {
             await adp.onChangeRequest('write', addXMLChange, mockFs, mockLogger);
 
-            expect(addXmlFragmentMock).toHaveBeenCalledWith('/adp.project/webapp', addXMLChange, mockFs, mockLogger);
+            expect(addXmlFragmentMock).toHaveBeenCalledWith(
+                '/adp.project/webapp',
+                addXMLChange,
+                mockFs,
+                mockLogger,
+                undefined
+            );
         });
 
         it('should not perform any action if type is "delete"', async () => {

packages/adp-tooling/test/unit/preview/change-handler.test.ts

@@ -190,18 +190,13 @@ describe('change-handler', () => {
             });
             it('should create Object Page custom section fragment', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `OBJECT_PAGE_CUSTOM_SECTION`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.objectPageSection %>"
 id="<%- ids.objectPageSubSection %>"
 id="<%- ids.hBox %>"`);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `OBJECT_PAGE_CUSTOM_SECTION`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -226,17 +221,12 @@ id="<%- ids.hBox %>"`);
 
             it('should create Object Page header field fragment', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `OBJECT_PAGE_HEADER_FIELD`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.vBoxContainer %>"
 id="<%- ids.label %>"`);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `OBJECT_PAGE_HEADER_FIELD`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -260,16 +250,11 @@ id="<%- ids.label %>"`);
 
             it('should create custom action fragment', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `CUSTOM_ACTION`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.toolbarActionButton %>`);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `CUSTOM_ACTION`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -296,7 +281,6 @@ id="<%- ids.toolbarActionButton %>`);
                     ...change,
                     content: {
                         ...change.content,
-                        templateName: `V2_SMART_TABLE_COLUMN`,
                         index: 1
                     }
                 } as unknown as AddXMLChange;
@@ -306,7 +290,9 @@ id="<%- ids.columnTitle %>
 id="<%- ids.customData %>
 id="<%- ids.index %>
 `);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `V2_SMART_TABLE_COLUMN`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -333,17 +319,12 @@ id="<%- ids.index %>
 
             it('should create custom table cell fragment (V2 smart table)', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `V2_SMART_TABLE_CELL`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.text %>
 `);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `V2_SMART_TABLE_CELL`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -367,18 +348,13 @@ id="<%- ids.text %>
 
             it('should create custom table column fragment (V4 smart table)', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `V4_MDC_TABLE_COLUMN`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.column %>
 id="<%- ids.text %>
 `);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `V4_MDC_TABLE_COLUMN`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -420,7 +396,6 @@ id="<%- ids.text %>
                     ...change,
                     content: {
                         ...change.content,
-                        templateName: testCase.tableType,
                         index: 1
                     }
                 } as unknown as AddXMLChange;
@@ -431,7 +406,9 @@ id="<%- ids.text %>
 id="<%- ids.customData %>
 id="<%- ids.index %>
 `);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: testCase.tableType
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(
@@ -457,17 +434,12 @@ id="<%- ids.index %>
 
             it('should create custom page action', () => {
                 mockFs.exists.mockReturnValue(false);
-                const updatedChange = {
-                    ...change,
-                    content: {
-                        ...change.content,
-                        templateName: `TABLE_ACTION`
-                    }
-                } as unknown as AddXMLChange;
                 mockFs.read.mockReturnValue(`
 id="<%- ids.customToolbarAction %>"
 id="<%- ids.customActionButton %>"`);
-                addXmlFragment(path, updatedChange, mockFs as unknown as Editor, mockLogger as unknown as Logger);
+                addXmlFragment(path, change, mockFs as unknown as Editor, mockLogger as unknown as Logger, {
+                    templateName: `TABLE_ACTION`
+                });
 
                 expect(mockFs.read).toHaveBeenCalled();
                 expect(

packages/preview-middleware-client/src/adp/add-fragment.ts

@@ -0,0 +1,51 @@
+import type RuntimeAuthoring from 'sap/ui/rta/RuntimeAuthoring';
+import type UI5Element from 'sap/ui/core/Element';
+import CommandFactory from 'sap/ui/rta/command/CommandFactory';
+import { Deferred, createDeferred } from './utils';
+import { DialogFactory, DialogNames } from './dialog-factory';
+import AddXMLPlugin from 'sap/ui/rta/plugin/AddXMLPlugin';
+
+export interface AddFragmentData {
+    deferred: Deferred<DeferredXmlFragmentData>;
+}
+
+export type DeferredXmlFragmentData = {
+    fragment: string;
+    fragmentPath: string;
+    targetAggregation: string;
+    index: number;
+};
+
+/**
+ * Initializes the AddXMLPlugin and includes it in the Runtime Authoring (RTA) plugins.
+ *
+ * @param rta Runtime Authoring instance
+ */
+export function initAddXMLPlugin(rta: RuntimeAuthoring): void {
+    const flexSettings = rta.getFlexSettings();
+    const commandFactory = new CommandFactory({ flexSettings });
+
+    const plugin = new AddXMLPlugin({
+        commandFactory,
+        fragmentHandler: async (overlay: UI5Element) => await handleFragmentCreation(rta, overlay)
+    });
+
+    const plugins = rta.getPlugins();
+    plugins.addXMLPlugin = plugin;
+    rta.setPlugins(plugins);
+}
+
+/**
+ * Handles the creation of a fragment by opening a dialog and resolving the deferred data.
+ *
+ * @param rta Runtime Authoring instance
+ * @param overlay UI5 Element overlay
+ * @returns A promise that resolves with DeferredXmlFragmentData
+ */
+async function handleFragmentCreation(rta: RuntimeAuthoring, overlay: UI5Element): Promise<DeferredXmlFragmentData> {
+    const deferred = createDeferred<DeferredXmlFragmentData>();
+
+    await DialogFactory.createDialog(overlay, rta, DialogNames.ADD_FRAGMENT, { deferred });
+
+    return deferred.promise;
+}

packages/preview-middleware-client/src/adp/api-handler.ts

@@ -42,7 +42,7 @@ export interface AnnotationFileDetails {
 }
 
 export interface AnnotationDataSourceMap {
-    [key: string]: { serviceUrl: string; annotationDetails: AnnotationFileDetails, metadataReadErrorMsg: string };
+    [key: string]: { serviceUrl: string; annotationDetails: AnnotationFileDetails; metadataReadErrorMsg: string };
 }
 
 export interface AnnotationDataSourceResponse {
@@ -181,5 +181,5 @@ export async function getExistingController(controllerName: string): Promise<Cod
  * @returns Generic Promise<T>
  */
 export async function writeChange<T>(data: T): Promise<T> {
-    return request<T>(ApiEndpoints.CHANGES, RequestMethod.POST, data);
+    return request<T>(ApiEndpoints.CHANGES, RequestMethod.POST, { change: data });
 }