react-native-boost 1.0.0 → 1.2.0

package/src/plugin/optimizers/view/index.ts

@@ -1,19 +1,21 @@
 import { types as t } from '@babel/core';
 import { HubFile, Optimizer } from '../../types';
 import PluginError from '../../utils/plugin-error';
-import { getFirstBailoutReason } from '../../utils/helpers';
+import { BailoutCheck, getFirstBailoutReason } from '../../utils/helpers';
 import {
   hasBlacklistedProperty,
+  isForcedLine,
   isIgnoredLine,
   isValidJSXComponent,
   isReactNativeImport,
   replaceWithNativeComponent,
-  getViewAncestorClassification,
-  ViewAncestorClassification,
+  ancestorBailoutChecks,
 } from '../../utils/common';
 
 export const viewBlacklistedProperties = 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',
@@ -21,60 +23,55 @@ export const viewBlacklistedProperties = 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',
 ]);
 
 export const viewOptimizer: Optimizer = (path, logger, options) => {
   if (!isValidJSXComponent(path, 'View')) return;
+  if (!isReactNativeImport(path, 'View')) return;
 
-  let ancestorClassification: ViewAncestorClassification | undefined;
-  const getAncestorClassification = () => {
-    if (!ancestorClassification) {
-      ancestorClassification = getViewAncestorClassification(path);
-    }
-
-    return ancestorClassification;
-  };
+  const forced = isForcedLine(path);
 
-  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'),
-    },
+  const overridableChecks: BailoutCheck[] = [
     {
       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?.dangerouslyOptimizeViewWithUnknownAncestors !== true,
-    },
-  ]);
+    ...ancestorBailoutChecks(path, options?.dangerouslyOptimizeViewWithUnknownAncestors === true),
+  ];
 
-  if (skipReason) {
-    logger.skipped({
-      component: 'View',
-      path,
-      reason: skipReason,
-    });
+  if (forced) {
+    const overriddenReason = getFirstBailoutReason(overridableChecks);
 
-    return;
+    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;
+    }
   }
 
-  // Extract the file from the Babel hub
   const hub = path.hub as unknown;
   const file = typeof hub === 'object' && hub !== null && 'file' in hub ? (hub.file as HubFile) : undefined;
 
@@ -89,6 +86,5 @@ export const viewOptimizer: Optimizer = (path, logger, options) => {
 
   const parent = path.parent as t.JSXElement;
 
-  // Replace the View component with NativeView
   replaceWithNativeComponent(path, parent, file, 'NativeView');
 };

package/src/plugin/types/index.ts

@@ -52,6 +52,16 @@ export interface PluginOptions {
    * @default false
    */
   dangerouslyOptimizeViewWithUnknownAncestors?: boolean;
+  /**
+   * Opt-in flag that allows Text optimization when ancestor components cannot be statically resolved.
+   *
+   * This increases optimization coverage, but may introduce behavioral differences when an unresolved
+   * ancestor renders a React Native `Text` wrapper: a nested `Text` must render as the inline
+   * `NativeVirtualText` host rather than `NativeText`, and optimizing it would emit the wrong host.
+   * Prefer targeted `@boost-force` first, and enable this only after verifying affected screens.
+   * @default false
+   */
+  dangerouslyOptimizeTextWithUnknownAncestors?: boolean;
 }
 
 export type OptimizableComponent = 'Text' | 'View';
@@ -74,10 +84,17 @@ export interface WarningLogPayload {
 export interface PluginLogger {
   optimized: (payload: OptimizationLogPayload) => void;
   skipped: (payload: SkippedOptimizationLogPayload) => void;
+  forced: (payload: SkippedOptimizationLogPayload) => void;
   warning: (payload: WarningLogPayload) => void;
 }
 
-export type Optimizer = (path: NodePath<t.JSXOpeningElement>, logger: PluginLogger, options?: PluginOptions) => void;
+export type Optimizer = (
+  path: NodePath<t.JSXOpeningElement>,
+  logger: PluginLogger,
+  options?: PluginOptions,
+  /** Target platform from Babel's caller (e.g. Metro sets `'ios'`/`'android'`). Lets optimizers resolve platform-specific defaults at build time. */
+  platform?: string
+) => void;
 
 export type HubFile = t.File & {
   opts: {

package/src/plugin/utils/common/attributes.ts

@@ -289,21 +289,80 @@ export function extractSelectableAndUpdateStyle(styleExpr: t.Expression): boolea
 }
 
 /**
- * Checks if a node represents a string value.
+ * Determines whether an expression is statically provable to evaluate to a `string` or `number`
+ * primitive — and therefore can never be a React element.
  */
-export const isStringNode = (path: NodePath<t.JSXOpeningElement>, child: t.Node): boolean => {
-  if (t.isJSXText(child) || t.isStringLiteral(child)) return true;
+const isPrimitiveExpression = (
+  path: NodePath<t.JSXOpeningElement>,
+  expression: t.Expression,
+  // Identifier names already resolved along this chain, to break circular `const` references
+  // (`const a = b; const b = a;`) that would otherwise recurse forever.
+  resolved: Set<string> = new Set()
+): boolean => {
+  // Unambiguous primitives — these can never be a React element.
+  if (t.isStringLiteral(expression) || t.isNumericLiteral(expression)) return true;
 
-  if (t.isJSXExpressionContainer(child)) {
-    const expression = child.expression;
-    if (t.isIdentifier(expression)) {
-      const binding = path.scope.getBinding(expression.name);
-      if (binding && binding.path.node && t.isVariableDeclarator(binding.path.node)) {
-        return !!binding.path.node.init && t.isStringLiteral(binding.path.node.init);
-      }
-      return false;
+  // A template literal ALWAYS coerces its interpolations to string, regardless of their types.
+  if (t.isTemplateLiteral(expression)) return true;
+
+  // `a + b` (and numeric `-`, `*`, ...) is primitive only when BOTH operands are themselves
+  // provably primitive. `in`/`instanceof` have a non-Expression `left` (a `PrivateName`), so the
+  // `isExpression` guard rejects them.
+  if (t.isBinaryExpression(expression)) {
+    const { left, right } = expression;
+    return (
+      t.isExpression(left) &&
+      isPrimitiveExpression(path, left, resolved) &&
+      isPrimitiveExpression(path, right, resolved)
+    );
+  }
+
+  // `c ? a : b` — only the reachable results (`a`, `b`) are rendered; the test is irrelevant.
+  if (t.isConditionalExpression(expression)) {
+    return (
+      isPrimitiveExpression(path, expression.consequent, resolved) &&
+      isPrimitiveExpression(path, expression.alternate, resolved)
+    );
+  }
+
+  // `a && b` / `a || b` / `a ?? b` — short-circuiting makes the result one of the operands, so both
+  // must be primitive (unlike the conditional, the left operand is itself a reachable result).
+  if (t.isLogicalExpression(expression)) {
+    return (
+      isPrimitiveExpression(path, expression.left, resolved) && isPrimitiveExpression(path, expression.right, resolved)
+    );
+  }
+
+  // Identifier resolving to a non-reassigned `const` whose initializer is itself provably primitive.
+  // `binding.constant` excludes reassigned bindings (`let x = 'a'; x = <Foo/>`).
+  if (t.isIdentifier(expression)) {
+    if (resolved.has(expression.name)) return false; // circular reference — give up
+    const binding = path.scope.getBinding(expression.name);
+    if (binding && binding.constant && binding.path.node && t.isVariableDeclarator(binding.path.node)) {
+      const init = binding.path.node.init;
+      return (
+        !!init && t.isExpression(init) && isPrimitiveExpression(path, init, new Set(resolved).add(expression.name))
+      );
     }
-    if (t.isStringLiteral(expression)) return true;
+    return false;
+  }
+
+  return false;
+};
+
+/**
+ * Checks whether a Text child node is statically provable to render as a string/number primitive.
+ * Used to gate the Text optimizer: only such children are safe to keep when rewriting `<Text>` to
+ * its native host. See {@link isPrimitiveExpression} for the underlying expression rules.
+ */
+export const isPrimitiveChild = (path: NodePath<t.JSXOpeningElement>, child: t.Node): boolean => {
+  if (t.isJSXText(child)) return true; // raw text between tags
+  if (t.isStringLiteral(child)) return true; // explicit `children="..."` attribute value
+
+  if (t.isJSXExpressionContainer(child)) {
+    const { expression } = child;
+    if (t.isJSXEmptyExpression(expression)) return false; // `{/* comment */}` is not a primitive
+    return isPrimitiveExpression(path, expression);
   }
   return false;
 };

package/src/plugin/utils/common/validation.ts

@@ -1,5 +1,5 @@
 import { NodePath, types as t } from '@babel/core';
-import { ensureArray } from '../helpers';
+import { ensureArray, BailoutCheck } from '../helpers';
 import { HubFile } from '../../types';
 import { minimatch } from 'minimatch';
 import nodePath from 'node:path';
@@ -39,54 +39,52 @@ export const isIgnoredFile = (path: NodePath<t.JSXOpeningElement>, ignores: stri
   return false;
 };
 
+export const isForcedLine = (path: NodePath<t.JSXOpeningElement>): boolean => {
+  return hasDecoratorComment(path, '@boost-force');
+};
+
+export const isIgnoredLine = (path: NodePath<t.JSXOpeningElement>): boolean => {
+  return hasDecoratorComment(path, '@boost-ignore');
+};
+
 /**
- * Checks if the JSX element should be ignored based on a preceding comment.
- *
- * The function looks up the JSXOpeningElement's own leading comments as well as
- * the parent element's comments before falling back to inspect siblings.
+ * Checks if the JSX element has a preceding comment containing the given decorator string.
  *
- * @param path - The path to the JSXOpeningElement.
- * @returns true if the JSX element should be ignored.
+ * Scans the JSXOpeningElement's own leading comments, the parent element's comments,
+ * ObjectProperty containers, and backward siblings.
  */
-export const isIgnoredLine = (path: NodePath<t.JSXOpeningElement>): boolean => {
-  // Check for @boost-ignore in the leading comments on the JSX opening element.
-  if (path.node.leadingComments?.some((comment) => comment.value.includes('@boost-ignore'))) {
+function hasDecoratorComment(path: NodePath<t.JSXOpeningElement>, decorator: string): boolean {
+  if (path.node.leadingComments?.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
 
-  // Check for @boost-ignore in the leading comments on the parent JSX element.
   const jsxElementPath = path.parentPath;
-  if (jsxElementPath.node.leadingComments?.some((comment) => comment.value.includes('@boost-ignore'))) {
+  if (jsxElementPath.node.leadingComments?.some((comment) => comment.value.includes(decorator))) {
     return true;
   }
 
-  // NEW: Check for @boost-ignore in the leading comments on the ObjectProperty (if it exists)
-  // This handles cases where the JSX element is used as a value inside an object literal.
+  // Check leading comments on the ObjectProperty (if the JSX element is a value inside an object literal).
   const propertyPath = jsxElementPath.parentPath;
   if (
     propertyPath &&
     propertyPath.isObjectProperty() &&
-    propertyPath.node.leadingComments?.some((comment) => comment.value.includes('@boost-ignore'))
+    propertyPath.node.leadingComments?.some((comment) => comment.value.includes(decorator))
   ) {
     return true;
   }
 
   if (!jsxElementPath.parentPath) return false;
 
-  // Get the container that holds this element (for example, a JSX fragment or JSX element)
   const containerPath = jsxElementPath.parentPath;
   const siblings = ensureArray(containerPath.get('children'));
   const index = siblings.findIndex((sibling) => sibling.node === jsxElementPath.node);
   if (index === -1) return false;
 
-  // Look backward from the current element for a non-empty node.
   for (let index_ = index - 1; index_ >= 0; index_--) {
     const sibling = siblings[index_];
-    // Skip over any whitespace (only in JSXText nodes)
     if (sibling.isJSXText() && sibling.node.value.trim() === '') {
       continue;
     }
-    // If the sibling is a JSX expression container, check its empty expression's comments.
     if (sibling.isJSXExpressionContainer()) {
       const expression = sibling.get('expression');
       if (expression && expression.node) {
@@ -95,22 +93,21 @@ export const isIgnoredLine = (path: NodePath<t.JSXOpeningElement>): boolean => {
           ...(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;
         }
       }
     }
-    // Also check if the node itself carries a leadingComments property.
     if (
       sibling.node.leadingComments &&
-      sibling.node.leadingComments.some((comment) => comment.value.includes('@boost-ignore'))
+      sibling.node.leadingComments.some((comment) => comment.value.includes(decorator))
     ) {
       return true;
     }
-    break; // if the immediate non-whitespace node is not our ignore marker, stop
+    break;
   }
   return false;
-};
+}
 
 /**
  * Checks if the path represents a valid JSX component with the specified name.
@@ -180,8 +177,7 @@ export const isReactNativeImport = (path: NodePath<t.JSXOpeningElement>, expecte
   return false;
 };
 
-type AncestorClassification = 'safe' | 'text' | 'unknown';
-export type ViewAncestorClassification = AncestorClassification;
+export type AncestorClassification = 'safe' | 'text' | 'unknown';
 type ScopeBinding = NonNullable<ReturnType<NodePath<t.Node>['scope']['getBinding']>>;
 
 type AncestorAnalysisContext = {
@@ -190,11 +186,7 @@ type AncestorAnalysisContext = {
   renderExpressionInProgress: WeakSet<t.Node>;
 };
 
-export const getViewAncestorClassification = (path: NodePath<t.JSXOpeningElement>): ViewAncestorClassification => {
-  return classifyViewAncestors(path);
-};
-
-function classifyViewAncestors(path: NodePath<t.JSXOpeningElement>): AncestorClassification {
+export const getAncestorClassification = (path: NodePath<t.JSXOpeningElement>): AncestorClassification => {
   const context: AncestorAnalysisContext = {
     componentCache: new WeakMap<t.Node, AncestorClassification>(),
     componentInProgress: new WeakSet<t.Node>(),
@@ -216,7 +208,35 @@ function classifyViewAncestors(path: NodePath<t.JSXOpeningElement>): AncestorCla
   }
 
   return classification;
-}
+};
+
+/**
+ * The ancestor-safety bailout checks shared by the Text and View optimizers. An element nested under a
+ * `Text` renders as the inline `NativeVirtualText` host (`RCTVirtualText`) instead of the block
+ * `NativeText`/`NativeView` host, so optimizing it would emit the wrong host; an `'unknown'` ancestor
+ * chain cannot be proven free of such a `Text`, so it bails too unless the caller opts into the risk.
+ *
+ * The ancestor walk is lazy (it runs only if these checks are reached) and memoized across the two
+ * checks. Each optimizer passes its own resolved `dangerouslyOptimize*WithUnknownAncestors` flag.
+ */
+export const ancestorBailoutChecks = (
+  path: NodePath<t.JSXOpeningElement>,
+  dangerousOptimizationEnabled: boolean
+): BailoutCheck[] => {
+  let classification: AncestorClassification | undefined;
+  const classify = () => (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: NodePath<t.JSXElement>,

package/src/plugin/utils/logger.ts

@@ -12,10 +12,12 @@ const ANSI_RESET = '\u001B[0m';
 const ANSI_GREEN = '\u001B[32m';
 const ANSI_YELLOW = '\u001B[33m';
 const ANSI_MAGENTA = '\u001B[35m';
+const ANSI_RED = '\u001B[31m';
 
 export const noopLogger: PluginLogger = {
   optimized() {},
   skipped() {},
+  forced() {},
   warning() {},
 };
 
@@ -30,6 +32,12 @@ export const createLogger = ({ verbose, silent }: { verbose: boolean; silent: bo
       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;
@@ -52,12 +60,14 @@ function formatWarningContext(payload: WarningLogPayload): string {
   return location;
 }
 
-function writeLog(level: 'optimized' | 'skipped' | 'warning', message: string): void {
+type LogLevel = 'optimized' | 'skipped' | 'forced' | 'warning';
+
+function writeLog(level: LogLevel, message: string): void {
   const levelTag = formatLevel(level);
   console.log(`${LOG_PREFIX} ${levelTag} ${message}`);
 }
 
-function formatLevel(level: 'optimized' | 'skipped' | 'warning'): string {
+function formatLevel(level: LogLevel): string {
   if (level === 'optimized') {
     return colorize('[optimized]', ANSI_GREEN);
   }
@@ -66,6 +76,10 @@ function formatLevel(level: 'optimized' | 'skipped' | 'warning'): string {
     return colorize('[skipped]', ANSI_YELLOW);
   }
 
+  if (level === 'forced') {
+    return colorize('[forced]', ANSI_RED);
+  }
+
   return colorize('[warning]', ANSI_MAGENTA);
 }
 

package/src/runtime/index.ts

@@ -1,4 +1,4 @@
-import { TextProps, TextStyle, StyleSheet } from 'react-native';
+import { TextProps, TextStyle, StyleSheet, Platform } from 'react-native';
 import { GenericStyleProp } from './types';
 import { userSelectToSelectableMap, verticalAlignToTextAlignVerticalMap } from './utils/constants';
 
@@ -49,14 +49,28 @@ export function processTextStyle(style: GenericStyleProp<TextStyle>): Partial<Te
 }
 
 /**
- * Normalizes accessibility and ARIA props for runtime native components.
+ * The default value `Text` resolves for `accessible` when the prop is omitted: `true` on iOS (text is
+ * an accessibility element unless opted out), `false` on Android, and `undefined` elsewhere.
+ *
+ * @remarks
+ * Runtime fallback for the common optimized `<Text>` path (no accessibility props) when the target
+ * platform is unknown at build time. When it is known (Metro reports it on the Babel caller), the
+ * plugin inlines the literal instead and this is not emitted. Evaluated per render — like `Text`'s own
+ * `Platform.select` — rather than hoisted to a constant, so it always reflects the current platform.
+ */
+export const getDefaultTextAccessible = (): boolean | undefined => Platform.select({ ios: true, android: false });
+
+/**
+ * Normalizes accessibility and ARIA props for runtime native components, mirroring the reconciliation
+ * `Text` performs before handing off to its native host.
  *
  * @param props - Accessibility and ARIA props.
  * @returns Props with normalized accessibility fields.
  * @remarks
  * - Merges `aria-label` with `accessibilityLabel`
  * - Merges ARIA state fields into `accessibilityState`
- * - Defaults `accessible` to `true` when omitted
+ * - Reconciles `disabled` with `accessibilityState.disabled` (the explicit `disabled` prop wins)
+ * - Resolves the platform-specific `accessible` default (see {@link getDefaultTextAccessible})
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function processAccessibilityProps(props: Record<string, any>): Record<string, any> {
@@ -70,6 +84,7 @@ export function processAccessibilityProps(props: Record<string, any>): Record<st
     ['aria-expanded']: ariaExpanded,
     ['aria-selected']: ariaSelected,
     accessible,
+    disabled,
     ...restProperties
   } = props;
 
@@ -97,14 +112,33 @@ export function processAccessibilityProps(props: Record<string, any>): Record<st
           };
   }
 
-  // For the accessible prop, if not provided, default to `true`
-  const normalizedAccessible = accessible == null ? true : accessible;
+  // Reconcile `disabled` with `accessibilityState.disabled`. When the two are out of sync (and not
+  // both falsy) the explicit `disabled` prop wins and is mirrored back into the state object, so the
+  // native host receives a consistent value on both fields.
+  const stateDisabled = normalizedState?.disabled;
+  const normalizedDisabled = disabled ?? stateDisabled;
+  if (
+    normalizedDisabled !== stateDisabled &&
+    ((normalizedDisabled != null && normalizedDisabled !== false) || (stateDisabled != null && stateDisabled !== false))
+  ) {
+    normalizedState = { ...normalizedState, disabled: normalizedDisabled };
+  }
+
+  // Resolve `accessible` exactly as `Text` does: opt-out on iOS, off by default on Android. The
+  // Android pressable case (`onPress`/`onLongPress`) never applies — press handlers bail out of
+  // optimization — so an omitted prop falls back to the platform default.
+  const normalizedAccessible = Platform.select({
+    ios: accessible !== false,
+    android: accessible ?? false,
+    default: accessible,
+  });
 
   return {
     ...restProperties,
     accessibilityLabel: normalizedLabel,
     accessibilityState: normalizedState,
     accessible: normalizedAccessible,
+    disabled: normalizedDisabled,
   };
 }
 

package/src/runtime/index.web.ts

@@ -5,6 +5,11 @@ import { GenericStyleProp } from './types';
 
 export const processTextStyle = (style: GenericStyleProp<TextStyle>) => ({ style }) as Partial<TextProps>;
 
+// On Web there is no platform-specific `accessible` default to apply; react-native-web's `Text`
+// derives accessibility from the rendered DOM. Returning `undefined` makes the injected
+// `accessible={getDefaultTextAccessible()}` a no-op.
+export const getDefaultTextAccessible = (): boolean | undefined => undefined;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function processAccessibilityProps(props: Record<string, any>): Record<string, any> {
   return props;