feat(adapter): auto-detect sx-aware wrapped components, with optional override hook (#394)

* feat(adapter): wrappedComponentInterface to emit sx prop when re-styling sx-aware components

Adds an optional adapter hook 'wrappedComponentInterface' that lets the
codemod know an imported component already accepts a StyleX 'sx' prop.
When wrapping such a component via styled(Component) and 'useSxProp' is
enabled, the codemod emits 'sx={styles.x}' instead of
'{...stylex.props(styles.x)}' and forwards className/style unchanged so
the wrapped component handles merging itself.

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

* fix(adapter): compose caller sx and destructure when wrapped component is sx-aware

Addresses two P1 review comments on the wrappedComponentInterface feature:

1. Wrapper functions emitted for styled(SxAwareComponent) referenced an
   undeclared 'sx' identifier when the wrapper accepted external sx
   (allowSxProp). The wrapper now destructures 'sx' whenever the wrapped
   component is sx-aware OR the wrapper exposes external sx.

2. The emitted 'sx={...}' on the wrapped component appeared after the
   '{...props}' / '{...rest}' spread, silently overriding any caller-passed
   sx. The simple wrapper path, the destructure wrapper path, and the
   inlined-JSX rewrite path now all compose the caller's sx with the
   internal styles via 'sx={[styles.x, sx]}' so consumer sx values
   survive re-styling.

Test coverage extends test-cases/wrapper-sxAware to cover an exported
wrapper with external sx, an inlined call site receiving caller sx, and
the wrapper function receiving caller sx.

Also extracts a small isWrappedComponentSxAware helper so the lookup
logic isn't duplicated between the wrapper-emitter and the JSX-rewrite
step.

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

* feat(adapter): auto-detect sx-aware wrapped components from prop type

The codemod now scans an imported component's definition file and walks
its declared prop type (intersections, type aliases, interfaces in the
same file) to find an `sx?:` member. When detected, `styled(Component)`
emits `<Component sx={styles.x} />` instead of
`<Component {...stylex.props(styles.x)} />` automatically — no adapter
configuration required.

The existing `wrappedComponentInterface` adapter hook is kept as an
explicit override for cases auto-detection cannot reach (typically
package imports where the source isn't on disk, or components whose sx
support is added by a HOC at runtime). It now wins over auto-detection
only when it returns a defined value; `undefined` falls through to the
auto-detector.

Adds unit tests for the detection helper covering:
  - inline literal prop type
  - generic component using `Type<C> = TextProps & Omit<…> & { sx?: … }`
    (the canonical real-world pattern)
  - interface-typed props
  - negative case (no sx member)
  - package imports (out of reach)
  - all three adapter override outcomes

Extends the wrapper-sxAware fixture with a Text-style generic component
to lock in the type-alias intersection path end-to-end.

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

* test: lock in Omit<…, "sx"> and value-position negatives for sx-aware detection

Adds two regression tests proving the auto-detector returns false when:
  1. The component's prop type explicitly omits sx via
     Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "sx">
  2. "sx" appears as part of a string-literal value of an unrelated prop
     (e.g. `variant?: "sx-like" | "other"`)

Both already pass with the current walker because:
  - Type parameter lists of opaque utility types (Omit/Pick/etc) are not
    descended into; only declared aliases/interfaces in the same file are
    resolved.
  - Detection only inspects literal/interface member *keys*, never value
    positions, so substring matches in string literals can't trigger a
    false positive.

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

* test: comprehensive unit-test coverage for sx-aware auto-detection

Expands the wrapped-component-interface test suite to 43 cases organised
by intent, documenting both supported patterns and known limitations of
the static walker. Sections:

  - Positive: prop type signatures
    * function declarations / arrow / function expression
    * required vs optional sx
    * string-literal property keys
    * any-typed sx values
    * default exports
    * non-exported declarations (the consumer's import is what makes it
      'exported' for the codemod's purposes)

  - Positive: type alias / interface resolution
    * single alias hop, intersection (Text-style generic component),
      nested chain, interface
    * union types where one branch carries sx
    * parenthesised types
    * cyclic aliases (no infinite loop)

  - Negative: sx absent or out of reach
    * plain components, Omit<…, "sx">, Pick utility narrowing
    * sx as a string literal value of an unrelated prop
    * sx mentioned only in a comment
    * components with no parameters / no parameter type annotation
    * sx on a sibling component
    * unknown local name
    * package-style imports (no source path on disk)

  - Negative: documented walker limitations
    * React.FC<Props> generic on the variable annotation
    * forwardRef HOC wrapper
    * interface 'extends' clauses
    * type imports across files

  - File-system edge cases
    * missing file, empty file, syntax error (no throw)
    * extension probing for bare absolute paths

  - Adapter override semantics
    * true / false / undefined fallthrough
    * package-import override path
    * useSxProp disabled
    * missing or empty importMap

  - Caching
    * repeat lookups stay consistent
    * (file, componentName) keying — different components in same file
      do not poison each other

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: skovhus

README.md

@@ -36,6 +36,13 @@ const adapter = defineAdapter({
   styleMerger: null,
   // Emit sx={} JSX attributes instead of {...stylex.props()} spreads (requires StyleX ≥0.18)
   useSxProp: false,
+  // Optional override for sx-aware wrapped components. Auto-detection is on by
+  // default when `useSxProp: true` — the codemod scans the imported component's
+  // prop type for an `sx?:` member. Use this hook to override (e.g. for package
+  // imports that auto-detection can't reach).
+  wrappedComponentInterface(ctx) {
+    return undefined;
+  },
   // Optional: customize the runtime theme hook import/call used for theme conditionals
   // Defaults to { functionName: "useTheme", importSource: { kind: "specifier", value: "styled-components" } }
   themeHook: {
@@ -172,6 +179,28 @@ const adapter = defineAdapter({
    */
   useSxProp: false,
 
+  /**
+   * Optional override for sx-aware wrapped components.
+   *
+   * When `useSxProp: true`, the codemod auto-detects whether an imported
+   * component accepts an `sx` prop by walking its declared prop type
+   * (intersections, type aliases, and interfaces in the same file). When
+   * `styled(Component)` wraps an sx-aware component, the codemod emits
+   * `<Component sx={styles.x} />` instead of `<Component {...stylex.props(styles.x)} />`
+   * and lets the wrapped component merge className/style itself.
+   *
+   * Use this hook to override auto-detection for cases it can't see — typically
+   * package imports (where the source isn't on disk) or components whose sx
+   * support is added by a HOC at runtime. Returning `undefined` falls through
+   * to auto-detection.
+   */
+  wrappedComponentInterface(ctx) {
+    if (ctx.importSource.startsWith("@company/ui/")) {
+      return { acceptsSx: true };
+    }
+    return undefined;
+  },
+
   /**
    * Optional: customize the runtime theme hook used when wrappers need theme booleans.
    * Defaults to useTheme from styled-components.
@@ -203,6 +232,7 @@ Adapters are the main extension point, see full example above. They let you cont
 - how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`, or `{ preserveRuntimeCall: true }` to keep only the original helper runtime call; `null`/`undefined` bails the file)
 - which exported components should support external className/style extension and/or polymorphic `as` prop (`externalInterface`)
 - how className/style merging is handled for components accepting external styling (`styleMerger`)
+- which imported components already accept a StyleX `sx` prop (auto-detected from the imported component's prop type when `useSxProp: true`; can be overridden via `wrappedComponentInterface`). When detected, the codemod emits `sx={styles.x}` on the wrapped component instead of `{...stylex.props(styles.x)}`.
 - which runtime theme hook import/call to use for emitted wrapper theme conditionals (`themeHook`)
 - how `styled(ImportedComponent)` wrapping an external base component can be inlined into an intrinsic element with static StyleX styles (`resolveBaseComponent`)
 

src/__tests__/extract-external-interface.test.ts

@@ -1134,6 +1134,24 @@ describe("runPrepass createExternalInterface snapshot on test-cases", () => {
           "style": false,
           "styles": true,
         },
+        "test-cases/lib/sx-aware-component.tsx:SxAwareButton": {
+          "as": false,
+          "className": false,
+          "elementProps": true,
+          "ref": false,
+          "spreadProps": true,
+          "style": false,
+          "styles": true,
+        },
+        "test-cases/lib/sx-aware-text.tsx:Text": {
+          "as": false,
+          "className": false,
+          "elementProps": true,
+          "ref": false,
+          "spreadProps": true,
+          "style": false,
+          "styles": true,
+        },
         "test-cases/lib/text.ts:Text": {
           "as": false,
           "className": false,

src/__tests__/fixture-adapters.ts

@@ -56,6 +56,7 @@ export const fixtureAdapter = defineAdapter({
         "basic-jsdocExported",
         "htmlProp-element",
         "wrapper-mergerImported",
+        "wrapper-sxAware",
         "htmlProp-input",
         "transientProp-notForwarded",
         "inlineBase-booleanVariantKey",

src/adapter.ts

@@ -573,6 +573,47 @@ export interface MarkerFileContext {
   filePath: string;
 }
 
+// ────────────────────────────────────────────────────────────────────────────
+// Wrapped Component Interface
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Context for `adapter.wrappedComponentInterface(...)`.
+ *
+ * Called for each `styled(Component)` declaration where `Component` is
+ * imported from another module. Lets the adapter declare that the wrapped
+ * component already accepts a StyleX `sx` prop so the codemod can emit
+ * `sx={style}` instead of `{...stylex.props(style)}`.
+ */
+export interface WrappedComponentInterfaceContext {
+  /**
+   * Import source for the wrapped base component.
+   * - package import: e.g. `"@company/ui"`
+   * - relative import: resolved absolute path
+   */
+  importSource: string;
+  /**
+   * Imported binding name for the wrapped base component.
+   * Example: `import { Button as UiButton } ...` -> importedName: "Button"
+   */
+  importedName: string;
+  /**
+   * Absolute path of the file currently being transformed.
+   */
+  filePath: string;
+}
+
+/**
+ * Result for `adapter.wrappedComponentInterface(...)`.
+ *
+ * - `acceptsSx: true` — the wrapped component accepts an `sx` prop. The codemod
+ *   emits `sx={style}` instead of `{...stylex.props(style)}` and skips
+ *   className/style merging in the wrapper (the wrapped component owns that).
+ */
+export interface WrappedComponentInterfaceResult {
+  acceptsSx: boolean;
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Style Merger Configuration
 // ────────────────────────────────────────────────────────────────────────────
@@ -763,6 +804,31 @@ export interface Adapter {
    */
   usePhysicalProperties?: boolean;
 
+  /**
+   * Optional override for sx-aware wrapped component detection.
+   *
+   * When `useSxProp: true`, the codemod auto-detects whether an imported
+   * component accepts a StyleX `sx` prop by reading its definition file and
+   * walking its declared prop type (intersections, type aliases, interfaces
+   * in the same file). When detected, `styled(Component)` emits
+   * `<Component sx={styles.x} />` instead of
+   * `<Component {...stylex.props(styles.x)} />`.
+   *
+   * Use this hook to override auto-detection for cases it cannot see — most
+   * commonly package imports (e.g. `@company/ui`) where the source isn't on
+   * disk, or components whose sx support is added by a HOC at runtime.
+   *
+   * Return:
+   * - `{ acceptsSx: true }` to force the `sx={...}` path
+   * - `{ acceptsSx: false }` to force the `{...stylex.props(...)}` path
+   * - `undefined` to fall through to auto-detection (default)
+   *
+   * Only consulted for `styled(ImportedComponent)` declarations.
+   */
+  wrappedComponentInterface?: (
+    context: WrappedComponentInterfaceContext,
+  ) => WrappedComponentInterfaceResult | undefined;
+
   /**
    * Optional function to customize where marker sidecar files (`stylex.defineMarker()`)
    * are written. By default, markers are placed in a `.stylex.ts` file next to the source.
@@ -818,6 +884,7 @@ export interface AdapterInput {
   themeHook?: Adapter["themeHook"];
   useSxProp: Adapter["useSxProp"];
   usePhysicalProperties?: Adapter["usePhysicalProperties"];
+  wrappedComponentInterface?: Adapter["wrappedComponentInterface"];
   markerFile?: Adapter["markerFile"];
 }
 

src/internal/emit-wrappers.ts

@@ -3,7 +3,13 @@
  * Core concepts: intrinsic vs component wrappers and insertion ordering.
  */
 import type { ASTNode, Collection, JSCodeshift, Property } from "jscodeshift";
-import { DEFAULT_THEME_HOOK, type StyleMergerConfig, type ThemeHookConfig } from "../adapter.js";
+import {
+  DEFAULT_THEME_HOOK,
+  type ImportSource,
+  type StyleMergerConfig,
+  type ThemeHookConfig,
+  type WrappedComponentInterfaceResult,
+} from "../adapter.js";
 import type { StyledDecl } from "./transform-types.js";
 import { emitComponentWrappers } from "./emit-wrappers/emit-component.js";
 import { emitIntrinsicWrappers } from "./emit-wrappers/emit-intrinsic.js";
@@ -28,6 +34,12 @@ export function emitWrappers(args: {
   siblingMarkerKeys?: Set<string>;
   parentsNeedingDefaultMarker?: Set<string>;
   useSxProp: boolean;
+  importMap?: Map<string, { importedName: string; source: ImportSource }>;
+  wrappedComponentInterface?: (ctx: {
+    importSource: string;
+    importedName: string;
+    filePath: string;
+  }) => WrappedComponentInterfaceResult | undefined;
 }): void {
   const {
     root,
@@ -46,6 +58,8 @@ export function emitWrappers(args: {
     siblingMarkerKeys,
     parentsNeedingDefaultMarker,
     useSxProp,
+    importMap,
+    wrappedComponentInterface,
   } = args;
 
   const wrapperDecls = styledDecls.filter((d) => d.needsWrapperComponent && !d.isCssHelper);
@@ -70,6 +84,8 @@ export function emitWrappers(args: {
     siblingMarkerKeys,
     parentsNeedingDefaultMarker,
     useSxProp,
+    importMap,
+    wrappedComponentInterface,
   });
 
   const emitted: ASTNode[] = [];

src/internal/emit-wrappers/emit-component.ts

@@ -145,6 +145,12 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
     const allowSxProp = emitter.shouldAllowSxProp(d);
     const allowClassNameProp = shouldAllowClassName || wrappedHasClassName;
     const allowStyleProp = shouldAllowStyle || wrappedHasStyle;
+    // When the wrapped component accepts a StyleX `sx` prop (per adapter), the
+    // wrapper passes className/style through unchanged via `{...rest}` and the
+    // wrapped component merges them with its `sx` itself. The wrapper still
+    // accepts className/style in its type, but does not destructure them.
+    const wrappedAcceptsSx =
+      emitter.useSxProp && emitter.wrappedComponentAcceptsSxProp(wrappedComponent);
     // When the wrapped component has className/style as REQUIRED props, we must
     // force them to be optional in the wrapper's type. Otherwise, the wrapper would
     // inherit the requiredness, breaking call sites that don't pass className/style
@@ -780,7 +786,11 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
       const forwardedAsId = j.identifier("forwardedAs");
       const wrappedComponentExpr = buildWrappedComponentExpr();
 
-      if (allowSxProp) {
+      // When the wrapped component accepts a StyleX `sx` prop, callers may also
+      // pass `sx` even when the wrapper does not declare it externally. Destructure
+      // it so we can compose with internal styles instead of letting `{...rest}`
+      // forward it (which would be overwritten by the wrapper's own `sx={...}`).
+      if (allowSxProp || wrappedAcceptsSx) {
         styleArgs.push(sxId);
       }
 
@@ -792,6 +802,13 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
         }
       }
 
+      // When the wrapped component is sx-aware, className/style flow through
+      // `{...rest}` unchanged — the wrapped component merges them with its
+      // internal styles itself. `sx` is destructured so the wrapper can compose
+      // it with its own internal styles via `sx={[styles.x, sx]}`.
+      const destructureClassName = allowClassNameProp && !wrappedAcceptsSx;
+      const destructureStyle = allowStyleProp && !wrappedAcceptsSx;
+      const destructureSx = allowSxProp || wrappedAcceptsSx;
       const patternProps = emitter.buildDestructurePatternProps({
         baseProps: [
           ...(isPolymorphicComponentWrapper
@@ -803,10 +820,10 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
                 ) as Property,
               ]
             : []),
-          ...(allowClassNameProp ? [patternProp("className", classNameId)] : []),
+          ...(destructureClassName ? [patternProp("className", classNameId)] : []),
           ...(includeChildren ? [patternProp("children", childrenId)] : []),
-          ...(allowStyleProp ? [patternProp("style", styleId)] : []),
-          ...(allowSxProp ? [patternProp("sx", sxId)] : []),
+          ...(destructureStyle ? [patternProp("style", styleId)] : []),
+          ...(destructureSx ? [patternProp("sx", sxId)] : []),
           ...((d.supportsRefProp ?? false) ? [patternProp("ref", refId)] : []),
           ...(shouldLowerForwardedAs ? [patternProp("forwardedAs", forwardedAsId)] : []),
         ],
@@ -833,6 +850,7 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
         inlineStyleProps: (d.inlineStyleProps ?? []) as InlineStyleProp[],
         staticClassNameExpr,
         isIntrinsicElement: false,
+        wrappedAcceptsSxProp: wrappedAcceptsSx,
       });
 
       const stmts: StatementKind[] = [declStmt];
@@ -1027,7 +1045,21 @@ export function emitComponentWrappers(emitter: WrapperEmitter): {
       openingAttrs.push(
         ...emitter.buildStaticAttrsFromRecord(staticAttrs, { booleanTrueAsShorthand: false }),
       );
-      openingAttrs.push(j.jsxSpreadAttribute(stylexPropsCall));
+      // When the wrapped component accepts a StyleX `sx` prop, emit `sx={...}`
+      // instead of `{...stylex.props(...)}` so the wrapped component can merge it
+      // with className/style it receives from `{...props}`. The caller's `sx` (if
+      // any) is composed in by appending `props.sx` to the array — the spread
+      // above would otherwise be overwritten by this `sx` attribute.
+      if (wrappedAcceptsSx) {
+        const composedStyleArgs: ExpressionKind[] = [
+          ...styleArgs,
+          j.memberExpression(propsId, j.identifier("sx")),
+        ];
+        const sxExpr = j.arrayExpression(composedStyleArgs);
+        openingAttrs.push(j.jsxAttribute(j.jsxIdentifier("sx"), j.jsxExpressionContainer(sxExpr)));
+      } else {
+        openingAttrs.push(j.jsxSpreadAttribute(stylexPropsCall));
+      }
 
       const jsx = emitter.buildJsxElement({
         tagName: jsxTagName,

src/internal/emit-wrappers/style-merger.ts

@@ -87,6 +87,9 @@ export function emitStyleMerging(args: {
   /** Set to true when the rendered tag is an intrinsic HTML element (lowercase).
    * The sx prop is only valid on intrinsic elements (processed by the StyleX babel plugin). */
   isIntrinsicElement?: boolean;
+  /** Set to true when the rendered (non-intrinsic) component already accepts a
+   * StyleX `sx` prop. Enables the `sx={...}` fast path for component wrappers. */
+  wrappedAcceptsSxProp?: boolean;
 }): StyleMergingResult {
   const {
     j,
@@ -100,6 +103,7 @@ export function emitStyleMerging(args: {
     inlineStyleProps = [],
     staticClassNameExpr,
     isIntrinsicElement = true,
+    wrappedAcceptsSxProp = false,
   } = args;
 
   const {
@@ -166,6 +170,24 @@ export function emitStyleMerging(args: {
     });
   }
 
+  // When the wrapped component accepts a StyleX `sx` prop (per adapter), emit
+  // `sx={...}` directly and skip className/style merging — the wrapped component
+  // handles className/style itself. The destructured className/style values are
+  // forwarded to the wrapped component via the surrounding `{...rest}` spread.
+  if (wrappedAcceptsSxProp && inlineStyleProps.length === 0 && !staticClassNameExpr) {
+    const sxExpr =
+      styleArgs.length === 1 && styleArgs[0] ? styleArgs[0] : j.arrayExpression(styleArgs);
+    return {
+      needsSxVar: false,
+      sxDecl: null,
+      jsxSpreadExpr: null,
+      sxPropExpr: sxExpr,
+      classNameAttr: null,
+      classNameBeforeSpread: false,
+      styleAttr: null,
+    };
+  }
+
   // If neither className nor style merging is needed, just use stylex.props directly
   if (
     !allowClassNameProp &&