@appium/universal-xml-plugin 2.0.4 → 2.1.0

package/build/lib/xpath.d.ts

@@ -1,11 +1,20 @@
-export function runQuery(query: any, xmlStr: any): ((string | number | boolean | Node | Node[]) & (string | number | boolean | Node)) | null;
+export declare function runQuery(query: string, xmlStr: string): any[];
 /**
+ * Transforms an XPath query to work with the original platform-specific XML
  *
- * @param {string} query
- * @param {string} xmlStr
- * @param {boolean} multiple
- * @returns {string|null}
+ * @param query - The XPath query to transform
+ * @param xmlStr - The transformed XML string
+ * @param multiple - Whether to return multiple matches
+ * @returns The transformed query string or null if no matches found
  */
-export function transformQuery(query: string, xmlStr: string, multiple: boolean): string | null;
-export function getNodeAttrVal(node: any, attr: any): any;
+export declare function transformQuery(query: string, xmlStr: string, multiple: boolean): string | null;
+/**
+ * Gets the value of a node attribute
+ *
+ * @param node - The XML node
+ * @param attr - The attribute name
+ * @returns The attribute value
+ * @throws {Error} If the attribute doesn't exist
+ */
+export declare function getNodeAttrVal(node: any, attr: string): string;
 //# sourceMappingURL=xpath.d.ts.map

package/build/lib/xpath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xpath.d.ts","sourceRoot":"","sources":["../../lib/xpath.js"],"names":[],"mappings":"AAIA,6IAMC;AAED;;;;;;GAMG;AACH,sCALW,MAAM,UACN,MAAM,YACN,OAAO,GACL,MAAM,GAAC,IAAI,CAkCvB;AAED,0DAMC"}
+{"version":3,"file":"xpath.d.ts","sourceRoot":"","sources":["../../lib/xpath.ts"],"names":[],"mappings":"AAIA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,CAM7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA2B9F;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9D"}

package/build/lib/xpath.js

@@ -17,11 +17,12 @@ function runQuery(query, xmlStr) {
     return nodes;
 }
 /**
+ * Transforms an XPath query to work with the original platform-specific XML
  *
- * @param {string} query
- * @param {string} xmlStr
- * @param {boolean} multiple
- * @returns {string|null}
+ * @param query - The XPath query to transform
+ * @param xmlStr - The transformed XML string
+ * @param multiple - Whether to return multiple matches
+ * @returns The transformed query string or null if no matches found
  */
 function transformQuery(query, xmlStr, multiple) {
     const nodes = runQuery(query, xmlStr);
@@ -31,9 +32,9 @@ function transformQuery(query, xmlStr, multiple) {
     const newQueries = nodes.map((node) => {
         const indexPath = getNodeAttrVal(node, 'indexPath');
         // at this point indexPath will look like /0/0/1/1/0/1/0/2
-        let newQuery = indexPath
+        const newQuery = indexPath
             .substring(1) // remove leading / so we can split
-            .split('/') // split into idnexes
+            .split('/') // split into indexes
             .map((indexStr) => {
             // map to xpath node indexes (1-based)
             const xpathIndex = parseInt(indexStr, 10) + 1;
@@ -43,19 +44,21 @@ function transformQuery(query, xmlStr, multiple) {
         // now to make this a valid xpath from the root, prepend the / we removed earlier
         return `/${newQuery}`;
     });
-    let newSelector = null;
-    if (newQueries.length) {
-        if (multiple) {
-            newSelector = newQueries.join(' | ');
-        }
-        else {
-            newSelector = newQueries[0];
-        }
+    if (newQueries.length === 0) {
+        return null;
     }
-    return newSelector;
+    return multiple ? newQueries.join(' | ') : newQueries[0];
 }
+/**
+ * Gets the value of a node attribute
+ *
+ * @param node - The XML node
+ * @param attr - The attribute name
+ * @returns The attribute value
+ * @throws {Error} If the attribute doesn't exist
+ */
 function getNodeAttrVal(node, attr) {
-    const attrObjs = Object.values(node.attributes).filter((obj) => obj.name === attr);
+    const attrObjs = Object.values(node.attributes || {}).filter((obj) => obj.name === attr);
     if (!attrObjs.length) {
         throw new Error(`Tried to retrieve a node attribute '${attr}' but the node didn't have it`);
     }

package/build/lib/xpath.js.map

@@ -1 +1 @@
-{"version":3,"file":"xpath.js","sourceRoot":"","sources":["../../lib/xpath.js"],"names":[],"mappings":";;;;;AAIA,4BAMC;AASD,wCAgCC;AAED,wCAMC;AA3DD,iCAA2C;AAC3C,2CAAoD;AACpD,oDAAuB;AAEvB,SAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACpC,MAAM,GAAG,GAAG,IAAI,kBAAS,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,kBAAS,CAAC,QAAQ,CAAC,CAAC;IACxE,2DAA2D;IAC3D,8CAA8C;IAC9C,MAAM,KAAK,GAAG,IAAA,cAAU,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,gBAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACpD,0DAA0D;QAC1D,IAAI,QAAQ,GAAG,SAAS;aACrB,SAAS,CAAC,CAAC,CAAC,CAAC,mCAAmC;aAChD,KAAK,CAAC,GAAG,CAAC,CAAC,qBAAqB;aAChC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;YAChB,sCAAsC;YACtC,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;YAC9C,OAAO,KAAK,UAAU,GAAG,CAAC;QAC5B,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;QAE1B,iFAAiF;QACjF,OAAO,IAAI,QAAQ,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,IAAI,WAAW,GAAG,IAAI,CAAC;IACvB,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACtB,IAAI,QAAQ,EAAE,CAAC;YACb,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAgB,cAAc,CAAC,IAAI,EAAE,IAAI;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACnF,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,+BAA+B,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"xpath.js","sourceRoot":"","sources":["../../lib/xpath.ts"],"names":[],"mappings":";;;;;AAIA,4BAMC;AAUD,wCA2BC;AAUD,wCAMC;AA/DD,iCAA2C;AAC3C,2CAAoD;AACpD,oDAAuB;AAEvB,SAAgB,QAAQ,CAAC,KAAa,EAAE,MAAc;IACpD,MAAM,GAAG,GAAG,IAAI,kBAAS,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,kBAAS,CAAC,QAAQ,CAAC,CAAC;IACxE,2DAA2D;IAC3D,8CAA8C;IAC9C,MAAM,KAAK,GAAG,IAAA,cAAU,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACrC,OAAO,KAAc,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,KAAa,EAAE,MAAc,EAAE,QAAiB;IAC7E,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,gBAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACpD,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,SAAS;aACvB,SAAS,CAAC,CAAC,CAAC,CAAC,mCAAmC;aAChD,KAAK,CAAC,GAAG,CAAC,CAAC,qBAAqB;aAChC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;YAChB,sCAAsC;YACtC,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;YAC9C,OAAO,KAAK,UAAU,GAAG,CAAC;QAC5B,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;QAE1B,iFAAiF;QACjF,OAAO,IAAI,QAAQ,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,IAAS,EAAE,IAAY;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC9F,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,+BAA+B,CAAC,CAAC;IAC9F,CAAC;IACD,OAAQ,QAAQ,CAAC,CAAC,CAAS,CAAC,KAAK,CAAC;AACpC,CAAC"}

package/lib/{attr-map.js → attr-map.ts}

@@ -1,5 +1,7 @@
 // uses the same format as NODE_MAP in node-map.js
-const ATTR_MAP = {
+import type {UniversalNameMap} from './types';
+
+export const ATTR_MAP: UniversalNameMap = {
   x: {ios: 'x', android: 'x'},
   y: {ios: 'y', android: 'y'},
   width: {ios: 'width', android: 'width'},
@@ -13,7 +15,7 @@ const ATTR_MAP = {
 };
 
 // these attributes shouldn't be mapped and should instead just be removed
-const REMOVE_ATTRS = [
+export const REMOVE_ATTRS = [
   'index',
   'type',
   'package',
@@ -30,6 +32,4 @@ const REMOVE_ATTRS = [
   'selected',
   'bounds',
   'rotation',
-];
-
-export {ATTR_MAP, REMOVE_ATTRS};
+] as const;

package/lib/{index.js → index.ts}

@@ -1,11 +1,25 @@
-import {UniversalXMLPlugin} from './plugin';
-import {transformSourceXml} from './source';
+export {UniversalXMLPlugin} from './plugin';
+export {transformSourceXml} from './source';
 import fs from 'node:fs/promises';
+import {transformSourceXml} from './source';
+import {UniversalXMLPlugin} from './plugin';
+
 export default UniversalXMLPlugin;
-export {UniversalXMLPlugin};
 
-export async function main() {
+export async function main(): Promise<void> {
   const [, , xmlDataPath, platform, optsJson] = process.argv;
+
+  // Handle smoke test flag
+  if (xmlDataPath === '--smoke-test') {
+    // Module loaded successfully, exit with code 0
+    process.exit(0);
+  }
+
+  if (!xmlDataPath || !platform) {
+    console.error('Usage: node index.js <xmlDataPath> <platform> [optsJson]'); // eslint-disable-line no-console
+    process.exit(1);
+  }
+
   const xmlData = await fs.readFile(xmlDataPath, 'utf8');
   const opts = optsJson ? JSON.parse(optsJson) : {};
   const {xml, unknowns} = await transformSourceXml(xmlData, platform, opts);
@@ -14,3 +28,7 @@ export async function main() {
     console.error(unknowns); // eslint-disable-line no-console
   }
 }
+
+if (require.main === module) {
+  (async () => await main())();
+}

package/lib/{node-map.js → node-map.ts}

@@ -6,7 +6,9 @@
  * array of strings. This means that there can be a many-to-one relationship between
  * platform-specific node names and universal node names.
  */
-export default {
+import type {UniversalNameMap} from './types';
+
+const NODE_MAP: UniversalNameMap = {
   Alert: {
     ios: 'XCUIElementTypeAlert',
     android: 'android.widget.Toast',
@@ -222,3 +224,5 @@ export default {
     ios: 'XCUIElementTypeWindow',
   },
 };
+
+export default NODE_MAP;

package/lib/plugin.ts

@@ -0,0 +1,119 @@
+import {BasePlugin} from 'appium/plugin';
+import {errors} from 'appium/driver';
+import {transformSourceXml} from './source';
+import {transformQuery} from './xpath';
+import type {ExternalDriver, NextPluginCallback, Element} from '@appium/types';
+import type {TransformMetadata} from './types';
+
+export class UniversalXMLPlugin extends BasePlugin {
+  async getPageSource(
+    next: NextPluginCallback | null,
+    driver: ExternalDriver,
+    sessId?: any,
+    addIndexPath: boolean = false
+  ): Promise<string> {
+    const source = (next ? await next() : await driver.getPageSource()) as string;
+    const metadata: TransformMetadata = {};
+    const platformName = getPlatformName(driver);
+    if (platformName.toLowerCase() === 'android') {
+      metadata.appPackage = (driver.opts as any)?.appPackage;
+    }
+    const {xml, unknowns} = await transformSourceXml(source, platformName.toLowerCase(), {
+      metadata,
+      addIndexPath,
+    });
+    if (unknowns.nodes.length) {
+      this.log.warn(
+        `The XML mapper found ${unknowns.nodes.length} node(s) / ` +
+          `tag name(s) that it didn't know about. These should be ` +
+          `reported to improve the quality of the plugin: ` +
+          unknowns.nodes.join(', ')
+      );
+    }
+    if (unknowns.attrs.length) {
+      this.log.warn(
+        `The XML mapper found ${unknowns.attrs.length} attributes ` +
+          `that it didn't know about. These should be reported to ` +
+          `improve the quality of the plugin: ` +
+          unknowns.attrs.join(', ')
+      );
+    }
+    return xml;
+  }
+
+  async findElement(
+    next: NextPluginCallback,
+    driver: ExternalDriver,
+    strategy: string,
+    selector: string
+  ): Promise<Element> {
+    return (await this._find(false, next, driver, strategy, selector)) as Element;
+  }
+
+  async findElements(
+    next: NextPluginCallback,
+    driver: ExternalDriver,
+    strategy: string,
+    selector: string
+  ): Promise<Element[]> {
+    return (await this._find(true, next, driver, strategy, selector)) as Element[];
+  }
+
+  private async _find(
+    multiple: false,
+    next: NextPluginCallback,
+    driver: ExternalDriver,
+    strategy: string,
+    selector: string
+  ): Promise<Element>;
+  private async _find(
+    multiple: true,
+    next: NextPluginCallback,
+    driver: ExternalDriver,
+    strategy: string,
+    selector: string
+  ): Promise<Element[]>;
+  private async _find(
+    multiple: boolean,
+    next: NextPluginCallback,
+    driver: ExternalDriver,
+    strategy: string,
+    selector: string
+  ): Promise<Element | Element[]> {
+    const platformName = getPlatformName(driver);
+    if (strategy.toLowerCase() !== 'xpath' || !driver.getCurrentContext || (await driver.getCurrentContext()) !== 'NATIVE_APP') {
+      return await next() as Element | Element[];
+    }
+    const xml = await this.getPageSource(null, driver, null, true);
+    let newSelector = transformQuery(selector, xml, multiple);
+
+    // if the selector was not able to be transformed, that means no elements were found that
+    // matched, so do the appropriate thing based on element vs elements
+    if (newSelector === null) {
+      this.log.warn(
+        `Selector was not able to be translated to underlying XML. Either the requested ` +
+          `element does not exist or there was an error in translation`
+      );
+      if (multiple) {
+        return [];
+      }
+      throw new errors.NoSuchElementError();
+    }
+
+    if (platformName.toLowerCase() === 'ios') {
+      // with the XCUITest driver, the <AppiumAUT> wrapper element is present in the source but is
+      // not present in the source considered by WDA, so our index path based xpath queries will
+      // not work with WDA as-is. We need to remove the first path segment.
+      newSelector = newSelector.replace(/^\/\*\[1\]/, '');
+    }
+    this.log.info(`Selector was translated to: ${newSelector}`);
+
+    // otherwise just run the transformed query!
+    const finder = multiple ? 'findElements' : 'findElement';
+    return await driver[finder](strategy, newSelector) as Element | Element[];
+  }
+}
+
+function getPlatformName(driver: ExternalDriver): string {
+  return ((driver.caps as any)?.platformName as string) || '';
+}

package/lib/source.ts

@@ -0,0 +1,265 @@
+import _ from 'lodash';
+import {XMLBuilder, XMLParser} from 'fast-xml-parser';
+import NODE_MAP from './node-map';
+import {ATTR_MAP, REMOVE_ATTRS} from './attr-map';
+import * as TRANSFORMS from './transformers';
+import type {
+  NodesAndAttributes,
+  TransformSourceXmlOptions,
+  TransformNodeOptions,
+  UniversalNameMap,
+  TransformMetadata,
+} from './types';
+
+export const ATTR_PREFIX = '@_';
+export const IDX_PATH_PREFIX = `${ATTR_PREFIX}indexPath`;
+export const IDX_PREFIX = `${ATTR_PREFIX}index`;
+
+const isAttr = (k: string): boolean => k.startsWith(ATTR_PREFIX);
+const isNode = (k: string): boolean => !isAttr(k);
+
+/**
+ * Transforms source XML to universal format
+ *
+ * @param xmlStr - The XML string to transform
+ * @param platform - The platform name ('ios' or 'android')
+ * @param opts - Transformation options
+ * @param opts.metadata - Optional metadata object
+ * @param opts.addIndexPath - Whether to add index path attributes
+ * @returns Promise resolving to transformed XML and unknown nodes/attributes
+ */
+export async function transformSourceXml(
+  xmlStr: string,
+  platform: string,
+  {metadata = {} as TransformMetadata, addIndexPath = false}: TransformSourceXmlOptions = {}
+): Promise<{xml: string; unknowns: NodesAndAttributes}> {
+  // first thing we want to do is modify the ios source root node, because it doesn't include the
+  // necessary index attribute, so we add it if it's not there
+  xmlStr = xmlStr.replace('<AppiumAUT>', '<AppiumAUT index="0">');
+  const xmlObj = singletonXmlParser().parse(xmlStr);
+  const unknowns = transformNode(xmlObj, platform, {
+    metadata,
+    addIndexPath,
+    parentPath: '',
+  });
+  let transformedXml = singletonXmlBuilder().build(xmlObj).trim();
+  transformedXml = `<?xml version="1.0" encoding="UTF-8"?>\n${transformedXml}`;
+  return {xml: transformedXml, unknowns};
+}
+
+/**
+ * Gets the universal name for a platform-specific name from a name map
+ *
+ * @param nameMap - The name mapping object
+ * @param name - The platform-specific name
+ * @param platform - The platform name
+ * @returns The universal name or null if not found
+ */
+function getUniversalName(
+  nameMap: UniversalNameMap | Readonly<UniversalNameMap>,
+  name: string,
+  platform: string
+): string | null {
+  for (const translatedName of Object.keys(nameMap)) {
+    const sourceNodes = nameMap[translatedName]?.[platform];
+    if (_.isArray(sourceNodes) && sourceNodes.includes(name)) {
+      return translatedName;
+    }
+    if (sourceNodes === name) {
+      return translatedName;
+    }
+  }
+  return null;
+}
+
+/**
+ * Gets the universal node name for a platform-specific node name
+ *
+ * @param nodeName - The platform-specific node name
+ * @param platform - The platform name
+ * @returns The universal node name or null if not found
+ */
+export function getUniversalNodeName(nodeName: string, platform: string): string | null {
+  return getUniversalName(NODE_MAP, nodeName, platform);
+}
+
+/**
+ * Gets the universal attribute name for a platform-specific attribute name
+ *
+ * @param attrName - The platform-specific attribute name
+ * @param platform - The platform name
+ * @returns The universal attribute name or null if not found
+ */
+export function getUniversalAttrName(attrName: string, platform: string): string | null {
+  return getUniversalName(ATTR_MAP, attrName, platform);
+}
+
+/**
+ * Transforms a node object recursively
+ *
+ * @param nodeObj - The node object to transform
+ * @param platform - The platform name
+ * @param opts - Transformation options
+ * @returns Object containing unknown nodes and attributes
+ */
+export function transformNode(
+  nodeObj: any,
+  platform: string,
+  {metadata, addIndexPath, parentPath}: TransformNodeOptions
+): NodesAndAttributes {
+  const unknownNodes: string[] = [];
+  const unknownAttrs: string[] = [];
+  if (_.isPlainObject(nodeObj)) {
+    const keys = Object.keys(nodeObj);
+    const childNodeNames = keys.filter(isNode);
+    const attrs = keys.filter(isAttr);
+    let thisIndexPath = parentPath || '';
+
+    if (attrs.length && addIndexPath) {
+      if (!attrs.includes(IDX_PREFIX)) {
+        throw new Error(`Index path is required but node found with no 'index' attribute`);
+      }
+
+      thisIndexPath = `${parentPath || ''}/${nodeObj[IDX_PREFIX]}`;
+      nodeObj[IDX_PATH_PREFIX] = thisIndexPath;
+    }
+
+    const transformFn = TRANSFORMS[platform as keyof typeof TRANSFORMS];
+    if (transformFn) {
+      transformFn(nodeObj, metadata || ({} as TransformMetadata));
+    }
+    unknownAttrs.push(...transformAttrs(nodeObj, attrs, platform));
+    const unknowns = transformChildNodes(nodeObj, childNodeNames, platform, {
+      metadata,
+      addIndexPath,
+      parentPath: thisIndexPath,
+    });
+    unknownAttrs.push(...unknowns.attrs);
+    unknownNodes.push(...unknowns.nodes);
+  } else if (_.isArray(nodeObj)) {
+    for (const childObj of nodeObj) {
+      const {nodes, attrs} = transformNode(childObj, platform, {
+        metadata,
+        addIndexPath,
+        parentPath: parentPath || '',
+      });
+      unknownNodes.push(...nodes);
+      unknownAttrs.push(...attrs);
+    }
+  }
+  return {
+    nodes: _.uniq(unknownNodes),
+    attrs: _.uniq(unknownAttrs),
+  };
+}
+
+/**
+ * Transforms child nodes of a node object
+ *
+ * @param nodeObj - The node object containing child nodes
+ * @param childNodeNames - Array of child node names
+ * @param platform - The platform name
+ * @param opts - Transformation options
+ * @returns Object containing unknown nodes and attributes
+ */
+export function transformChildNodes(
+  nodeObj: any,
+  childNodeNames: string[],
+  platform: string,
+  {metadata, addIndexPath, parentPath}: TransformNodeOptions
+): NodesAndAttributes {
+  const unknownNodes: string[] = [];
+  const unknownAttrs: string[] = [];
+  for (const nodeName of childNodeNames) {
+    // before modifying the name of this child node, recurse down and modify the subtree
+    const {nodes, attrs} = transformNode(nodeObj[nodeName], platform, {
+      metadata,
+      addIndexPath,
+      parentPath: parentPath || '',
+    });
+    unknownNodes.push(...nodes);
+    unknownAttrs.push(...attrs);
+
+    // now translate the node name and replace the subtree with this node
+    const universalName = getUniversalNodeName(nodeName, platform);
+    if (universalName === null) {
+      unknownNodes.push(nodeName);
+      continue;
+    }
+
+    // since multiple child node names could map to the same new transformed node name, we can't
+    // simply assign nodeObj[universalName] = nodeObj[nodeName]; we need to be sensitive to the
+    // situation where the end result is an array of children having the same node name
+    if (nodeObj[universalName]) {
+      // if we already have a node with the universal name, that means we are mapping a second
+      // original node name to the same universal node name, so we just push all its children into
+      // the list
+      if (_.isArray(nodeObj[universalName])) {
+        if (_.isArray(nodeObj[nodeName])) {
+          nodeObj[universalName].push(...nodeObj[nodeName]);
+        } else {
+          nodeObj[universalName].push(nodeObj[nodeName]);
+        }
+      } else {
+        nodeObj[universalName] = [nodeObj[universalName]];
+        if (_.isArray(nodeObj[nodeName])) {
+          nodeObj[universalName].push(...nodeObj[nodeName]);
+        } else {
+          nodeObj[universalName].push(nodeObj[nodeName]);
+        }
+      }
+    } else {
+      nodeObj[universalName] = nodeObj[nodeName];
+    }
+    delete nodeObj[nodeName];
+  }
+  return {nodes: unknownNodes, attrs: unknownAttrs};
+}
+
+/**
+ * Transforms attributes of a node object
+ *
+ * @param nodeObj - The node object containing attributes
+ * @param attrs - Array of attribute keys
+ * @param platform - The platform name
+ * @returns Array of unknown attribute names
+ */
+export function transformAttrs(nodeObj: any, attrs: string[], platform: string): string[] {
+  const unknownAttrs: string[] = [];
+  for (const attr of attrs) {
+    const cleanAttr = attr.substring(2);
+    if ((REMOVE_ATTRS as readonly string[]).includes(cleanAttr)) {
+      delete nodeObj[attr];
+      continue;
+    }
+    const universalAttr = getUniversalAttrName(cleanAttr, platform);
+    if (universalAttr === null) {
+      unknownAttrs.push(cleanAttr);
+      continue;
+    }
+    const newAttr = `${ATTR_PREFIX}${universalAttr}`;
+    if (newAttr !== attr) {
+      nodeObj[newAttr] = nodeObj[attr];
+      delete nodeObj[attr];
+    }
+  }
+  return unknownAttrs;
+}
+
+const singletonXmlBuilder = _.memoize(function makeXmlBuilder() {
+  return new XMLBuilder({
+    ignoreAttributes: false,
+    attributeNamePrefix: ATTR_PREFIX,
+    suppressBooleanAttributes: false,
+    format: true,
+  });
+});
+
+const singletonXmlParser = _.memoize(function makeXmlParser() {
+  return new XMLParser({
+    ignoreAttributes: false,
+    ignoreDeclaration: true,
+    attributeNamePrefix: ATTR_PREFIX,
+    isArray: (name, jPath, isLeafNode, isAttribute) => !isAttribute,
+  });
+});

package/lib/{transformers.js → transformers.ts}

@@ -1,10 +1,12 @@
 import {ATTR_PREFIX} from './source';
+import type {TransformMetadata} from './types';
 
-function ios(nodeObj /*, metadata*/) {
-  return nodeObj;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function ios(_nodeObj: any): void {
+  // iOS transformer does nothing
 }
 
-function android(nodeObj, metadata) {
+export function android(nodeObj: any, metadata: TransformMetadata): void {
   // strip android:id from front of id
   const resId = nodeObj[`${ATTR_PREFIX}resource-id`];
   if (resId && metadata.appPackage) {
@@ -17,16 +19,11 @@ function android(nodeObj, metadata) {
       .split(/\[|\]|,/)
       .filter((str) => str !== '');
     const [x, y, x2, y2] = boundsArray;
-    const width = x2 - x;
-    const height = y2 - y;
+    const width = parseInt(x2, 10) - parseInt(x, 10);
+    const height = parseInt(y2, 10) - parseInt(y, 10);
     nodeObj[`${ATTR_PREFIX}x`] = x;
     nodeObj[`${ATTR_PREFIX}y`] = y;
-    nodeObj[`${ATTR_PREFIX}width`] = width;
-    nodeObj[`${ATTR_PREFIX}height`] = height;
+    nodeObj[`${ATTR_PREFIX}width`] = width.toString();
+    nodeObj[`${ATTR_PREFIX}height`] = height.toString();
   }
 }
-
-export default {
-  ios,
-  android,
-};

package/lib/types.ts

@@ -0,0 +1,33 @@
+export interface NodesAndAttributes {
+  nodes: string[];
+  attrs: string[];
+}
+
+/**
+ * Metadata used for XML transformations
+ */
+export interface TransformMetadata {
+  appPackage?: string;
+  [key: string]: any;
+}
+
+export interface TransformSourceXmlOptions {
+  metadata?: TransformMetadata;
+  addIndexPath?: boolean;
+}
+
+export interface TransformNodeOptions extends TransformSourceXmlOptions {
+  parentPath?: string;
+}
+
+/**
+ * Type for platform-specific name mappings
+ * Values can be a string or an array of strings (for many-to-one mappings)
+ */
+export type PlatformNameMap = Record<string, string | readonly string[]>;
+
+/**
+ * Type for universal name maps
+ * Keys are universal names, values are platform-specific mappings
+ */
+export type UniversalNameMap = Record<string, Partial<PlatformNameMap>>;