@salesforce/metadata-plugins 1.0.0

package/dist/plugins/flexipage/transformer/FlexipageToUemTransformer.js

@@ -0,0 +1,302 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { SalesforceXMLParser, ErrorBuilder, ErrorCategory } from '@salesforce/metadata-core-sdk';
+import { transformVisibilityRule, resolvePropertyValue, buildFacetIndex, denormalizeFqn, ensureArray, extractApiName, } from './FlexipageTransformerUtils.js';
+/**
+ * Comprehensive FlexiPage to UEM transformer that correctly handles:
+ * - Facet regions (nested components via property references)
+ * - Visibility rules on components and fields
+ * - Field instance properties
+ * - ComponentInstance vs FieldInstance distinction
+ */
+export class FlexipageToUemTransformer {
+    constructor() {
+        this.warnings = [];
+        this.blockCount = 0;
+        // Configure parser to always treat these elements as arrays for consistency
+        const alwaysArray = new Set([
+            'flexiPageRegions',
+            'itemInstances',
+            'componentInstanceProperties',
+            'fieldInstanceProperties',
+            'criteria',
+            'valueListItems',
+            'properties',
+        ]);
+        this.parser = SalesforceXMLParser.createCustomParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '',
+            isArray: (name) => alwaysArray.has(name),
+            parseAttributeValue: false, // Keep as strings for consistent handling
+            trimValues: true,
+        });
+    }
+    /**
+     * Transform Flexipage XML content to UEM fragment
+     *
+     * @param xmlContent - The Flexipage XML content as a string
+     * @param filePath - The file path of the source file (for extracting API name)
+     * @returns Promise resolving to the UEM fragment and transformation metadata
+     */
+    async transform(xmlContent, filePath) {
+        this.warnings = [];
+        this.blockCount = 0;
+        let parsedFlexipage;
+        try {
+            parsedFlexipage = this.parser.parse(xmlContent);
+        }
+        catch (error) {
+            const pluginError = ErrorBuilder.fromError(ErrorCategory.Parsing, error, {
+                filePath,
+            }).build();
+            throw pluginError;
+        }
+        if (!parsedFlexipage) {
+            const pluginError = ErrorBuilder.fromError(ErrorCategory.Parsing, new Error('Failed to parse FlexiPage XML: parsed result is null'), { filePath }).build();
+            throw pluginError;
+        }
+        const flexiPage = parsedFlexipage.FlexiPage;
+        if (!flexiPage || !flexiPage.template || !flexiPage.type) {
+            const pluginError = ErrorBuilder.fromError(ErrorCategory.Parsing, new Error('Invalid FlexiPage XML: missing required elements'), { filePath }).build();
+            throw pluginError;
+        }
+        try {
+            // Extract API name from file path
+            const apiName = extractApiName(filePath);
+            // Build index of Facet regions for property-based embedding
+            const allRegions = flexiPage.flexiPageRegions ? ensureArray(flexiPage.flexiPageRegions) : [];
+            const facetByName = buildFacetIndex(allRegions);
+            const embeddedFacets = new Set();
+            // Transform root template to UEM block
+            const fragment = this.transformTemplate(flexiPage.template, flexiPage, apiName);
+            // Process only top-level "Region" type regions as direct children
+            const topLevelRegions = allRegions.filter((r) => !r.type || r.type.toLowerCase() === 'region');
+            let topLevelRegionCount = 0;
+            for (const region of topLevelRegions) {
+                const regionBlock = this.transformRegion(region, facetByName, embeddedFacets);
+                if (regionBlock) {
+                    fragment.children = fragment.children ?? [];
+                    fragment.children.push(regionBlock);
+                    topLevelRegionCount++;
+                }
+            }
+            // Add region count as top-level attribute
+            if (topLevelRegionCount > 0) {
+                fragment.attributes = fragment.attributes ?? {};
+                fragment.attributes.regions = topLevelRegionCount;
+            }
+            const metadata = {
+                sourceType: 'FlexiPage',
+                transformedAt: new Date().toISOString(),
+                blockCount: this.blockCount,
+                warnings: this.warnings.length > 0 ? this.warnings : undefined,
+            };
+            return { fragment, metadata };
+        }
+        catch (error) {
+            const pluginError = ErrorBuilder.fromError(ErrorCategory.Parsing, error, {
+                filePath,
+            }).build();
+            throw pluginError;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private transformation methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Transform <template> to root UEM block
+     */
+    transformTemplate(template, flexiPage, apiName) {
+        const definition = denormalizeFqn(template.name);
+        const attributes = {};
+        // API name (from file path)
+        if (apiName) {
+            attributes.apiName = apiName;
+        }
+        // masterLabel
+        if (flexiPage.masterLabel) {
+            attributes.masterLabel = flexiPage.masterLabel;
+        }
+        // Type
+        if (flexiPage.type) {
+            attributes.type = flexiPage.type;
+        }
+        // Sobject
+        if (flexiPage.sobjectType) {
+            attributes.sobjectType = flexiPage.sobjectType;
+        }
+        // Template
+        if (template.name) {
+            attributes.template = template.name;
+        }
+        // Description
+        if (flexiPage.description) {
+            attributes.description = flexiPage.description;
+        }
+        this.blockCount++; // Root block
+        return {
+            definition,
+            type: 'block',
+            attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
+            children: [],
+        };
+    }
+    /**
+     * Transform <flexiPageRegions> to RegionBlockType
+     */
+    transformRegion(region, facetByName, embeddedFacets) {
+        if (!region.name) {
+            this.warnings.push({
+                type: 'missing-property',
+                message: 'Region missing name property',
+                severity: 'warning',
+            });
+            return null;
+        }
+        const children = [];
+        const items = region.itemInstances ? ensureArray(region.itemInstances) : [];
+        for (const item of items) {
+            if (item?.componentInstance) {
+                const child = this.transformComponentInstance(item.componentInstance, facetByName, embeddedFacets);
+                if (child) {
+                    children.push(child);
+                }
+            }
+            else if (item?.fieldInstance) {
+                const child = this.transformFieldInstance(item.fieldInstance);
+                if (child) {
+                    children.push(child);
+                }
+            }
+        }
+        // denormalize region name
+        return {
+            type: 'region',
+            name: denormalizeFqn(region.name),
+            children: children.length > 0 ? children : undefined,
+        };
+    }
+    /**
+     * Transform <componentInstance> to Block or Field
+     *
+     * CRITICAL: Handles Facet embedding - when a property value references a Facet
+     * region name, that Facet is embedded as a nested RegionBlockType child.
+     *
+     */
+    transformComponentInstance(instance, facetByName, embeddedFacets) {
+        if (!instance.componentName) {
+            this.warnings.push({
+                type: 'missing-property',
+                message: 'Component missing componentName property',
+                severity: 'warning',
+            });
+            return null;
+        }
+        const definition = denormalizeFqn(instance.componentName);
+        // Extract properties as attributes
+        const rawProps = instance.componentInstanceProperties
+            ? ensureArray(instance.componentInstanceProperties)
+            : [];
+        const attributes = {};
+        for (const prop of rawProps) {
+            attributes[prop.name] = resolvePropertyValue(prop);
+        }
+        // ── FieldBlockType detection ────────────────────────────────────────────
+        // if componentInstance has "field" property, it's a FieldBlockType
+        if ('field' in attributes) {
+            const fieldItem = String(attributes['field']);
+            const fieldAttrs = { ...attributes, fieldItem };
+            delete fieldAttrs['field'];
+            this.blockCount++;
+            const field = {
+                type: 'field',
+                definition,
+                id: instance.identifier,
+                attributes: fieldAttrs,
+            };
+            if (instance.visibilityRule) {
+                field.visibilityRule = transformVisibilityRule(instance.visibilityRule);
+            }
+            return field;
+        }
+        // ── BlockType with Facet embedding ──────────────────────────────────────
+        this.blockCount++;
+        const block = {
+            type: 'block',
+            definition,
+            id: instance.identifier,
+            attributes: {},
+            children: [],
+        };
+        // Walk properties: scalar values → attributes; Facet references → child regions
+        for (const [key, val] of Object.entries(attributes)) {
+            if (typeof val === 'string' && facetByName.has(val)) {
+                // Property references a Facet region → embed as nested RegionBlockType child
+                // RegionBlockType children are added directly to components
+                const facetRegion = facetByName.get(val);
+                if (!embeddedFacets.has(val)) {
+                    embeddedFacets.add(val);
+                    // Use property key as the region name (semantic naming)
+                    const childRegion = this.transformRegion({ ...facetRegion, name: key }, facetByName, embeddedFacets);
+                    if (childRegion) {
+                        block.children.push(childRegion);
+                    }
+                }
+                // Property consumed by child region; don't add to attributes
+            }
+            else {
+                block.attributes[key] = val;
+            }
+        }
+        if (instance.visibilityRule) {
+            block.visibilityRule = transformVisibilityRule(instance.visibilityRule);
+        }
+        // Clean up empty children array
+        if (block.children?.length === 0) {
+            delete block.children;
+        }
+        return block;
+    }
+    /**
+     * Transform <fieldInstance> to FieldBlockType
+     *
+     * Note: fieldInstance has NO componentName; identified by fieldItem alone
+     */
+    transformFieldInstance(instance) {
+        if (!instance.fieldItem) {
+            this.warnings.push({
+                type: 'missing-property',
+                message: 'Field instance missing fieldItem property',
+                severity: 'warning',
+            });
+            return null;
+        }
+        this.blockCount++;
+        // Extract field instance properties (e.g., uiBehavior)
+        const fieldProps = instance.fieldInstanceProperties
+            ? ensureArray(instance.fieldInstanceProperties)
+            : [];
+        const attributes = { fieldItem: instance.fieldItem };
+        for (const prop of fieldProps) {
+            if (prop.value !== undefined) {
+                attributes[prop.name] = String(prop.value);
+            }
+        }
+        // For native fieldInstance, definition is empty (no componentName)
+        // For componentInstance with "field" property, definition comes from componentName
+        const field = {
+            type: 'field',
+            definition: '', // Native fieldInstance has no componentName
+            id: instance.identifier,
+            attributes,
+        };
+        if (instance.visibilityRule) {
+            field.visibilityRule = transformVisibilityRule(instance.visibilityRule);
+        }
+        return field;
+    }
+}

package/dist/plugins/flexipage/transformer/FlexipageTransformerUtils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { FlexiPageRegion, VisibilityRule, ComponentInstanceProperty } from '../types/FlexipageMetadata.js';
+/**
+ * Transform <visibilityRule> to VisibilityRule
+ */
+export declare function transformVisibilityRule(raw: VisibilityRule): VisibilityRule;
+/**
+ * Resolve a single <componentInstanceProperties> entry to a value
+ */
+export declare function resolvePropertyValue(prop: ComponentInstanceProperty): unknown;
+/**
+ * Build map of Facet region name → region object
+ * Facets can be embedded as nested children when referenced by component properties
+ */
+export declare function buildFacetIndex(regions: FlexiPageRegion[]): Map<string, FlexiPageRegion>;
+/**
+ * Denormalize FQN: "flexipage:recentItems" → "flexipage/recentItems"
+ */
+export declare function denormalizeFqn(definition: string): string;
+/**
+ * Ensure value is an array (for consistent handling of single vs multiple elements)
+ */
+export declare function ensureArray<T>(value: T | T[]): T[];
+/**
+ * Extract API name from file path
+ * Example: "/path/to/MyPage.flexipage-meta.xml" → "MyPage"
+ */
+export declare function extractApiName(filePath: string): string | undefined;
+//# sourceMappingURL=FlexipageTransformerUtils.d.ts.map

package/dist/plugins/flexipage/transformer/FlexipageTransformerUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlexipageTransformerUtils.d.ts","sourceRoot":"","sources":["../../../../src/plugins/flexipage/transformer/FlexipageTransformerUtils.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAEJ,OAAO,EACL,eAAe,EACf,cAAc,EACd,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AAEvC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAS3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAO7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQxF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,CAElD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnE"}

package/dist/plugins/flexipage/transformer/FlexipageTransformerUtils.js

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+/**
+ * Transform <visibilityRule> to VisibilityRule
+ */
+export function transformVisibilityRule(raw) {
+    return {
+        booleanFilter: raw.booleanFilter,
+        criteria: raw.criteria.map((c) => ({
+            leftValue: String(c.leftValue),
+            operator: String(c.operator),
+            rightValue: String(c.rightValue),
+        })),
+    };
+}
+/**
+ * Resolve a single <componentInstanceProperties> entry to a value
+ */
+export function resolvePropertyValue(prop) {
+    if (prop.valueList !== undefined) {
+        // <valueList> → string[] (flatten all valueListItems)
+        const items = ensureArray(prop.valueList.valueListItems);
+        return items.flatMap((item) => ensureArray(item.value));
+    }
+    return prop.value !== undefined ? String(prop.value) : undefined;
+}
+/**
+ * Build map of Facet region name → region object
+ * Facets can be embedded as nested children when referenced by component properties
+ */
+export function buildFacetIndex(regions) {
+    const map = new Map();
+    for (const region of regions) {
+        if (region.type?.toLowerCase() === 'facet') {
+            map.set(region.name, region);
+        }
+    }
+    return map;
+}
+/**
+ * Denormalize FQN: "flexipage:recentItems" → "flexipage/recentItems"
+ */
+export function denormalizeFqn(definition) {
+    if (!definition) {
+        return definition;
+    }
+    return definition.replace(/:/g, '/');
+}
+/**
+ * Ensure value is an array (for consistent handling of single vs multiple elements)
+ */
+export function ensureArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Extract API name from file path
+ * Example: "/path/to/MyPage.flexipage-meta.xml" → "MyPage"
+ */
+export function extractApiName(filePath) {
+    if (!filePath) {
+        return undefined;
+    }
+    const filename = filePath.split('/').pop() || filePath.split('\\').pop();
+    if (!filename) {
+        return undefined;
+    }
+    // Remove .flexipage-meta.xml or .flexipage extension
+    return filename.replace(/\.flexipage(-meta)?\.xml$/i, '');
+}

package/dist/plugins/flexipage/types/FlexipageMetadata.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+/**
+ * Type definitions for Salesforce FlexiPage metadata
+ */
+export interface SalesforceFlexipage {
+    FlexiPage: FlexipageMetadata;
+}
+export interface FlexipageMetadata {
+    type: string;
+    sobjectType?: string;
+    masterLabel?: string;
+    description?: string;
+    template: Template;
+    flexiPageRegions?: FlexiPageRegion | FlexiPageRegion[];
+}
+export interface Template {
+    name: string;
+    properties?: TemplateProperty | TemplateProperty[];
+}
+export interface TemplateProperty {
+    name: string;
+    value: string;
+}
+export interface FlexiPageRegion {
+    name: string;
+    type?: string;
+    mode?: string;
+    itemInstances?: ItemInstance | ItemInstance[];
+}
+export interface ItemInstance {
+    componentInstance?: ComponentInstance;
+    fieldInstance?: FieldInstance;
+}
+export interface ComponentInstance {
+    componentName: string;
+    identifier: string;
+    componentInstanceProperties?: ComponentInstanceProperty | ComponentInstanceProperty[];
+    visibilityRule?: VisibilityRule;
+}
+export interface ComponentInstanceProperty {
+    name: string;
+    value: string;
+    type?: string;
+    valueList?: ValueList;
+}
+export interface ValueList {
+    valueListItems: ValueListItem | ValueListItem[];
+}
+export interface ValueListItem {
+    value: string | string[];
+}
+export interface FieldInstance {
+    fieldItem: string;
+    identifier: string;
+    visibilityRule?: VisibilityRule;
+    fieldInstanceProperties?: FieldInstanceProperty | FieldInstanceProperty[];
+}
+export interface FieldInstanceProperty {
+    name: string;
+    value: string;
+}
+export interface VisibilityRule {
+    booleanFilter?: string;
+    criteria: VisibilityRuleCriteria[];
+}
+export interface VisibilityRuleCriteria {
+    leftValue: string;
+    operator: string;
+    rightValue: string;
+}
+//# sourceMappingURL=FlexipageMetadata.d.ts.map

package/dist/plugins/flexipage/types/FlexipageMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlexipageMetadata.d.ts","sourceRoot":"","sources":["../../../../src/plugins/flexipage/types/FlexipageMetadata.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAEJ;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B,CAAC,EAAE,yBAAyB,GAAG,yBAAyB,EAAE,CAAC;IACtF,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,uBAAuB,CAAC,EAAE,qBAAqB,GAAG,qBAAqB,EAAE,CAAC;CAC3E;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/plugins/flexipage/types/FlexipageMetadata.js

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+export {};