react-native-boost 1.0.0 → 1.2.0

package/README.md

@@ -20,10 +20,22 @@ The documentation is available at [react-native-boost.oss.kuatsu.de](https://rea
 The app in the `apps/example` directory serves as a benchmark for the performance of the plugin.
 
 <div align="center">
-  <img src="./apps/docs/docs/introduction/img/benchmark-ios.png" width="500" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./apps/docs/content/docs/information/img/fps-ios.svg" />
+    <img alt="React Native Boost — iOS frame rate vs render load" src="./apps/docs/content/docs/information/img/fps-ios-light.svg" width="640" />
+  </picture>
 </div>
 
-More benchmarks are available in the [docs](https://react-native-boost.oss.kuatsu.de/docs/introduction/benchmarks).
+See the [benchmarks page](https://react-native-boost.oss.kuatsu.de/docs/information/benchmarks) for Android results and the full methodology.
+
+## Compatibility
+
+| `react-native-boost` | React Native     |
+| -------------------- | ---------------- |
+| `0.x`                | All versions[^1] |
+| `1.x`                | `>=0.83`         |
+
+[^1]: Starting from React Native `0.80`, `react-native-boost@0` prints import deprecation warnings.
 
 ## Installation
 
@@ -59,11 +71,11 @@ yarn start --clear
 
 That's it! No imports in your code, rebuilding, or anything else is required.
 
-Optionally, you can configure the Babel plugin with a few options described in the [documentation](https://react-native-boost.oss.kuatsu.de/docs/babel-plugin/configure).
+Optionally, you can configure the Babel plugin with a few options described in the [documentation](https://react-native-boost.oss.kuatsu.de/docs/configuration/configure).
 
 ## How it works
 
-A technical rundown of how the plugin works can be found in the [docs](https://react-native-boost.oss.kuatsu.de/docs/introduction/how-it-works).
+A technical rundown of how the plugin works can be found in the [docs](https://react-native-boost.oss.kuatsu.de/docs/information/how-it-works).
 
 ## Contributing
 

package/dist/plugin/esm/index.mjs

@@ -40,17 +40,23 @@ const isIgnoredFile = (path, ignores) => {
   }
   return false;
 };
+const isForcedLine = (path) => {
+  return hasDecoratorComment(path, "@boost-force");
+};
 const isIgnoredLine = (path) => {
+  return hasDecoratorComment(path, "@boost-ignore");
+};
+function hasDecoratorComment(path, decorator) {
   var _a, _b, _c;
-  if ((_a = path.node.leadingComments) == null ? void 0 : _a.some((comment) => comment.value.includes("@boost-ignore"))) {
+  if ((_a = path.node.leadingComments) == null ? void 0 : _a.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
   const jsxElementPath = path.parentPath;
-  if ((_b = jsxElementPath.node.leadingComments) == null ? void 0 : _b.some((comment) => comment.value.includes("@boost-ignore"))) {
+  if ((_b = jsxElementPath.node.leadingComments) == null ? void 0 : _b.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
   const propertyPath = jsxElementPath.parentPath;
-  if (propertyPath && propertyPath.isObjectProperty() && ((_c = propertyPath.node.leadingComments) == null ? void 0 : _c.some((comment) => comment.value.includes("@boost-ignore")))) {
+  if (propertyPath && propertyPath.isObjectProperty() && ((_c = propertyPath.node.leadingComments) == null ? void 0 : _c.some((comment) => comment.value.includes(decorator)))) {
     return true;
   }
   if (!jsxElementPath.parentPath) return false;
@@ -71,18 +77,18 @@ const isIgnoredLine = (path) => {
           ...expression.node.trailingComments || [],
           ...expression.node.innerComments || []
         ].map((comment) => comment.value.trim());
-        if (comments.some((comment) => comment.includes("@boost-ignore"))) {
+        if (comments.some((comment) => comment.includes(decorator))) {
           return true;
         }
       }
     }
-    if (sibling.node.leadingComments && sibling.node.leadingComments.some((comment) => comment.value.includes("@boost-ignore"))) {
+    if (sibling.node.leadingComments && sibling.node.leadingComments.some((comment) => comment.value.includes(decorator))) {
       return true;
     }
     break;
   }
   return false;
-};
+}
 const isValidJSXComponent = (path, componentName) => {
   if (!types.isJSXIdentifier(path.node.name)) return false;
   const parent = path.parent;
@@ -119,10 +125,7 @@ const isReactNativeImport = (path, expectedImportedName) => {
   }
   return false;
 };
-const getViewAncestorClassification = (path) => {
-  return classifyViewAncestors(path);
-};
-function classifyViewAncestors(path) {
+const getAncestorClassification = (path) => {
   const context = {
     componentCache: /* @__PURE__ */ new WeakMap(),
     componentInProgress: /* @__PURE__ */ new WeakSet(),
@@ -139,7 +142,21 @@ function classifyViewAncestors(path) {
     ancestorPath = ancestorPath.parentPath;
   }
   return classification;
-}
+};
+const ancestorBailoutChecks = (path, dangerousOptimizationEnabled) => {
+  let classification;
+  const classify = () => classification != null ? classification : classification = getAncestorClassification(path);
+  return [
+    {
+      reason: "has Text ancestor",
+      shouldBail: () => classify() === "text"
+    },
+    {
+      reason: "has unresolved ancestor and dangerous optimization is disabled",
+      shouldBail: () => classify() === "unknown" && !dangerousOptimizationEnabled
+    }
+  ];
+};
 function classifyJSXElementAsAncestor(path, context) {
   const openingElementName = path.node.openingElement.name;
   if (types.isJSXIdentifier(openingElementName)) {
@@ -667,18 +684,37 @@ function extractSelectableAndUpdateStyle(styleExpr) {
   }
   return void 0;
 }
-const isStringNode = (path, child) => {
-  if (types.isJSXText(child) || types.isStringLiteral(child)) return true;
-  if (types.isJSXExpressionContainer(child)) {
-    const expression = child.expression;
-    if (types.isIdentifier(expression)) {
-      const binding = path.scope.getBinding(expression.name);
-      if (binding && binding.path.node && types.isVariableDeclarator(binding.path.node)) {
-        return !!binding.path.node.init && types.isStringLiteral(binding.path.node.init);
-      }
-      return false;
+const isPrimitiveExpression = (path, expression, resolved = /* @__PURE__ */ new Set()) => {
+  if (types.isStringLiteral(expression) || types.isNumericLiteral(expression)) return true;
+  if (types.isTemplateLiteral(expression)) return true;
+  if (types.isBinaryExpression(expression)) {
+    const { left, right } = expression;
+    return types.isExpression(left) && isPrimitiveExpression(path, left, resolved) && isPrimitiveExpression(path, right, resolved);
+  }
+  if (types.isConditionalExpression(expression)) {
+    return isPrimitiveExpression(path, expression.consequent, resolved) && isPrimitiveExpression(path, expression.alternate, resolved);
+  }
+  if (types.isLogicalExpression(expression)) {
+    return isPrimitiveExpression(path, expression.left, resolved) && isPrimitiveExpression(path, expression.right, resolved);
+  }
+  if (types.isIdentifier(expression)) {
+    if (resolved.has(expression.name)) return false;
+    const binding = path.scope.getBinding(expression.name);
+    if (binding && binding.constant && binding.path.node && types.isVariableDeclarator(binding.path.node)) {
+      const init = binding.path.node.init;
+      return !!init && types.isExpression(init) && isPrimitiveExpression(path, init, new Set(resolved).add(expression.name));
     }
-    if (types.isStringLiteral(expression)) return true;
+    return false;
+  }
+  return false;
+};
+const isPrimitiveChild = (path, child) => {
+  if (types.isJSXText(child)) return true;
+  if (types.isStringLiteral(child)) return true;
+  if (types.isJSXExpressionContainer(child)) {
+    const { expression } = child;
+    if (types.isJSXEmptyExpression(expression)) return false;
+    return isPrimitiveExpression(path, expression);
   }
   return false;
 };
@@ -717,6 +753,10 @@ const replaceWithNativeComponent = (path, parent, file, nativeComponentName) =>
 };
 
 const textBlacklistedProperties = /* @__PURE__ */ new Set([
+  // The `Text` wrapper translates `aria-hidden` into `accessibilityElementsHidden` /
+  // `importantForAccessibility`, which `processAccessibilityProps` does not yet handle. Passing it
+  // through would drop it, so bail. TODO: handle this in the runtime helper instead.
+  "aria-hidden",
   "id",
   "nativeID",
   "onLongPress",
@@ -734,18 +774,14 @@ const textBlacklistedProperties = /* @__PURE__ */ new Set([
   "selectionColor"
   // TODO: we can use react-native's internal `processColor` to process this at runtime
 ]);
-const textOptimizer = (path, logger) => {
+const NORMALIZED_PROPERTIES = /* @__PURE__ */ new Set([...ACCESSIBILITY_PROPERTIES, "disabled"]);
+const isNormalizedProperty = (attribute) => types.isJSXAttribute(attribute) && types.isJSXIdentifier(attribute.name) && NORMALIZED_PROPERTIES.has(attribute.name.name);
+const textOptimizer = (path, logger, options, platform) => {
   if (!isValidJSXComponent(path, "Text")) return;
+  if (!isReactNativeImport(path, "Text")) return;
   const parent = path.parent;
-  const skipReason = getFirstBailoutReason([
-    {
-      reason: "line is marked with @boost-ignore",
-      shouldBail: () => isIgnoredLine(path)
-    },
-    {
-      reason: "Text is not imported from react-native",
-      shouldBail: () => !isReactNativeImport(path, "Text")
-    },
+  const forced = isForcedLine(path);
+  const overridableChecks = [
     {
       reason: "contains blacklisted props",
       shouldBail: () => hasBlacklistedProperty(path, textBlacklistedProperties)
@@ -754,18 +790,31 @@ const textOptimizer = (path, logger) => {
       reason: "is a direct child of expo-router Link with asChild",
       shouldBail: () => hasExpoRouterLinkParentWithAsChild(path)
     },
+    // The local children check runs before the ancestor checks because it is cheap and prunes the
+    // common nested-element `Text` before the unbounded ancestor walk those checks trigger.
     {
-      reason: "contains non-string children",
+      reason: "contains non-primitive children",
       shouldBail: () => hasInvalidChildren(path, parent)
+    },
+    ...ancestorBailoutChecks(path, (options == null ? void 0 : options.dangerouslyOptimizeTextWithUnknownAncestors) === true)
+  ];
+  if (forced) {
+    const overriddenReason = getFirstBailoutReason(overridableChecks);
+    if (overriddenReason) {
+      logger.forced({ component: "Text", path, reason: overriddenReason });
+    }
+  } else {
+    const skipReason = getFirstBailoutReason([
+      {
+        reason: "line is marked with @boost-ignore",
+        shouldBail: () => isIgnoredLine(path)
+      },
+      ...overridableChecks
+    ]);
+    if (skipReason) {
+      logger.skipped({ component: "Text", path, reason: skipReason });
+      return;
     }
-  ]);
-  if (skipReason) {
-    logger.skipped({
-      component: "Text",
-      path,
-      reason: skipReason
-    });
-    return;
   }
   const hub = path.hub;
   const file = typeof hub === "object" && hub !== null && "file" in hub ? hub.file : void 0;
@@ -779,18 +828,18 @@ const textOptimizer = (path, logger) => {
   fixNegativeNumberOfLines({ path, logger });
   addDefaultProperty(path, "allowFontScaling", types.booleanLiteral(true));
   addDefaultProperty(path, "ellipsizeMode", types.stringLiteral("tail"));
-  processProps(path, file);
+  processProps(path, file, platform);
   replaceWithNativeComponent(path, parent, file, "NativeText");
 };
 function hasInvalidChildren(path, parent) {
   for (const attribute of path.node.attributes) {
     if (types.isJSXSpreadAttribute(attribute)) continue;
-    if (types.isJSXIdentifier(attribute.name) && attribute.value && // For a "children" attribute, optimization is allowed only if it is a string
-    attribute.name.name === "children" && !isStringNode(path, attribute.value)) {
+    if (types.isJSXIdentifier(attribute.name) && attribute.value && // For a "children" attribute, optimization is allowed only if it is a provable primitive
+    attribute.name.name === "children" && !isPrimitiveChild(path, attribute.value)) {
       return true;
     }
   }
-  return !parent.children.every((child) => isStringNode(path, child));
+  return !parent.children.every((child) => isPrimitiveChild(path, child));
 }
 function fixNegativeNumberOfLines({ path, logger }) {
   for (const attribute of path.node.attributes) {
@@ -812,16 +861,15 @@ function fixNegativeNumberOfLines({ path, logger }) {
     }
   }
 }
-function processProps(path, file) {
+function processProps(path, file, platform) {
   const currentAttributes = [...path.node.attributes];
   const { styleExpr, styleAttribute } = extractStyleAttribute(currentAttributes);
-  const hasA11y = hasAccessibilityProperty(path, currentAttributes);
+  const shouldNormalize = hasAccessibilityProperty(path, currentAttributes) || currentAttributes.some(
+    (attribute) => types.isJSXAttribute(attribute) && types.isJSXIdentifier(attribute.name, { name: "disabled" })
+  );
   const spreadAttributes = [];
-  if (hasA11y) {
-    const accessibilityAttributes = currentAttributes.filter((attribute) => {
-      if (!types.isJSXAttribute(attribute)) return false;
-      return types.isJSXIdentifier(attribute.name) && ACCESSIBILITY_PROPERTIES.has(attribute.name.name);
-    });
+  if (shouldNormalize) {
+    const normalizedAttributes = currentAttributes.filter((attribute) => isNormalizedProperty(attribute));
     const normalizeIdentifier = addFileImportHint({
       file,
       nameHint: "processAccessibilityProps",
@@ -829,7 +877,7 @@ function processProps(path, file) {
       importName: "processAccessibilityProps",
       moduleName: RUNTIME_MODULE_NAME
     });
-    const accessibilityObject = buildPropertiesFromAttributes(accessibilityAttributes);
+    const accessibilityObject = buildPropertiesFromAttributes(normalizedAttributes);
     const accessibilityExpr = types.callExpression(types.identifier(normalizeIdentifier.name), [accessibilityObject]);
     spreadAttributes.push(types.jsxSpreadAttribute(accessibilityExpr));
   }
@@ -855,26 +903,45 @@ function processProps(path, file) {
   const remainingAttributes = [];
   for (const attribute of currentAttributes) {
     if (styleAttribute && attribute === styleAttribute) continue;
-    if (hasA11y && types.isJSXAttribute(attribute) && types.isJSXIdentifier(attribute.name) && ACCESSIBILITY_PROPERTIES.has(attribute.name.name)) {
-      continue;
-    }
+    if (shouldNormalize && isNormalizedProperty(attribute)) continue;
     remainingAttributes.push(attribute);
   }
-  path.node.attributes = [...spreadAttributes, selectableAttribute, ...remainingAttributes].filter(
+  const accessibleAttribute = shouldNormalize ? void 0 : buildAccessibleDefault(path, file, platform);
+  path.node.attributes = [...spreadAttributes, selectableAttribute, ...remainingAttributes, accessibleAttribute].filter(
     (attribute) => attribute !== void 0
   );
 }
+function buildAccessibleDefault(path, file, platform) {
+  if (platform === "web") return void 0;
+  let value;
+  if (platform === "ios" || platform === "android") {
+    value = types.booleanLiteral(platform === "ios");
+  } else {
+    const accessibleIdentifier = addFileImportHint({
+      file,
+      nameHint: "getDefaultTextAccessible",
+      path,
+      importName: "getDefaultTextAccessible",
+      moduleName: RUNTIME_MODULE_NAME
+    });
+    value = types.callExpression(types.identifier(accessibleIdentifier.name), []);
+  }
+  return types.jsxAttribute(types.jsxIdentifier("accessible"), types.jsxExpressionContainer(value));
+}
 
 const LOG_PREFIX = "[react-native-boost]";
 const ANSI_RESET = "\x1B[0m";
 const ANSI_GREEN = "\x1B[32m";
 const ANSI_YELLOW = "\x1B[33m";
 const ANSI_MAGENTA = "\x1B[35m";
+const ANSI_RED = "\x1B[31m";
 const noopLogger = {
   optimized() {
   },
   skipped() {
   },
+  forced() {
+  },
   warning() {
   }
 };
@@ -888,6 +955,12 @@ const createLogger = ({ verbose, silent }) => {
       if (!verbose) return;
       writeLog("skipped", `Skipped ${payload.component} in ${formatPathLocation(payload.path)} (${payload.reason})`);
     },
+    forced(payload) {
+      writeLog(
+        "forced",
+        `Force-optimized ${payload.component} in ${formatPathLocation(payload.path)} (skipped bailout: ${payload.reason})`
+      );
+    },
     warning(payload) {
       const context = formatWarningContext(payload);
       const message = context.length > 0 ? `${context}: ${payload.message}` : payload.message;
@@ -916,6 +989,9 @@ function formatLevel(level) {
   if (level === "skipped") {
     return colorize("[skipped]", ANSI_YELLOW);
   }
+  if (level === "forced") {
+    return colorize("[forced]", ANSI_RED);
+  }
   return colorize("[warning]", ANSI_MAGENTA);
 }
 function colorize(value, colorCode) {
@@ -950,7 +1026,9 @@ function formatPathLocation(payloadPath) {
 }
 
 const viewBlacklistedProperties = /* @__PURE__ */ new Set([
-  // TODO: process a11y props at runtime
+  // The `View` wrapper translates these into native props (e.g. `aria-*` → `accessibility*`,
+  // `tabIndex` → `focusable`). The native host does not understand them, so passing them through
+  // would silently drop them. TODO: process these at runtime instead of bailing.
   "accessible",
   "accessibilityLabel",
   "accessibilityState",
@@ -958,51 +1036,47 @@ const viewBlacklistedProperties = /* @__PURE__ */ new Set([
   "aria-checked",
   "aria-disabled",
   "aria-expanded",
+  "aria-hidden",
   "aria-label",
+  "aria-labelledby",
+  "aria-live",
   "aria-selected",
+  "aria-valuemax",
+  "aria-valuemin",
+  "aria-valuenow",
+  "aria-valuetext",
   "id",
   "nativeID",
-  "style"
-  // TODO: process style at runtime
+  "tabIndex"
 ]);
 const viewOptimizer = (path, logger, options) => {
   if (!isValidJSXComponent(path, "View")) return;
-  let ancestorClassification;
-  const getAncestorClassification = () => {
-    if (!ancestorClassification) {
-      ancestorClassification = getViewAncestorClassification(path);
-    }
-    return ancestorClassification;
-  };
-  const skipReason = getFirstBailoutReason([
-    {
-      reason: "line is marked with @boost-ignore",
-      shouldBail: () => isIgnoredLine(path)
-    },
-    {
-      reason: "View is not imported from react-native",
-      shouldBail: () => !isReactNativeImport(path, "View")
-    },
+  if (!isReactNativeImport(path, "View")) return;
+  const forced = isForcedLine(path);
+  const overridableChecks = [
     {
       reason: "contains blacklisted props",
       shouldBail: () => hasBlacklistedProperty(path, viewBlacklistedProperties)
     },
-    {
-      reason: "has Text ancestor",
-      shouldBail: () => getAncestorClassification() === "text"
-    },
-    {
-      reason: "has unresolved ancestor and dangerous optimization is disabled",
-      shouldBail: () => getAncestorClassification() === "unknown" && (options == null ? void 0 : options.dangerouslyOptimizeViewWithUnknownAncestors) !== true
+    ...ancestorBailoutChecks(path, (options == null ? void 0 : options.dangerouslyOptimizeViewWithUnknownAncestors) === true)
+  ];
+  if (forced) {
+    const overriddenReason = getFirstBailoutReason(overridableChecks);
+    if (overriddenReason) {
+      logger.forced({ component: "View", path, reason: overriddenReason });
+    }
+  } else {
+    const skipReason = getFirstBailoutReason([
+      {
+        reason: "line is marked with @boost-ignore",
+        shouldBail: () => isIgnoredLine(path)
+      },
+      ...overridableChecks
+    ]);
+    if (skipReason) {
+      logger.skipped({ component: "View", path, reason: skipReason });
+      return;
     }
-  ]);
-  if (skipReason) {
-    logger.skipped({
-      component: "View",
-      path,
-      reason: skipReason
-    });
-    return;
   }
   const hub = path.hub;
   const file = typeof hub === "object" && hub !== null && "file" in hub ? hub.file : void 0;
@@ -1019,6 +1093,7 @@ const viewOptimizer = (path, logger, options) => {
 
 var index = declare((api) => {
   api.assertVersion(7);
+  const platform = api.caller((caller) => caller == null ? void 0 : caller.platform);
   return {
     name: "react-native-boost",
     visitor: {
@@ -1028,7 +1103,7 @@ var index = declare((api) => {
         const options = (_a = pluginState.opts) != null ? _a : {};
         const logger = getOrCreateLogger(pluginState, options);
         if (isIgnoredFile(path, (_b = options.ignores) != null ? _b : [])) return;
-        if (((_c = options.optimizations) == null ? void 0 : _c.text) !== false) textOptimizer(path, logger);
+        if (((_c = options.optimizations) == null ? void 0 : _c.text) !== false) textOptimizer(path, logger, options, platform);
         if (((_d = options.optimizations) == null ? void 0 : _d.view) !== false) viewOptimizer(path, logger, options);
       }
     }