styled-components-to-stylex-codemod 0.0.19 → 0.0.21

package/README.md

@@ -192,7 +192,7 @@ Adapters are the main extension point, see full example above. They let you cont
 
 - how theme paths, CSS variables, and imported values are turned into StyleX-compatible JS values (`resolveValue`)
 - what extra imports to inject into transformed files (returned from `resolveValue`)
-- how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`; `null`/`undefined` bails the file)
+- 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 runtime theme hook import/call to use for emitted wrapper theme conditionals (`themeHook`)
@@ -304,6 +304,8 @@ When the codemod encounters an interpolation inside a styled template literal, i
   - With `ctx.cssProperty` (e.g., `color: ${helper()}`) → result used as CSS value in `stylex.create()`
   - Without `ctx.cssProperty` (e.g., `${helper()}`) → result used as StyleX styles in `stylex.props()`
   - Use the optional `usage: "create" | "props"` field to override the default inference
+  - Use `preserveRuntimeCall: true` to keep the original helper call as a runtime style-function
+    override (with or without a static fallback from `expr`)
 - if `resolveCall` returns `null` or `undefined`, the transform **bails the file** and logs a warning
 - helper calls applied to prop values (e.g. `shadow(props.shadow)`) by emitting a StyleX style function that calls the helper at runtime
 - conditional CSS blocks via ternary (e.g. `props.$dim ? "opacity: 0.5;" : ""`)

package/dist/{bridge-consumer-patcher-DhMoL4Od.mjs → bridge-consumer-patcher-C2mFaVmd.mjs}

@@ -1,4 +1,4 @@
-import { t as isSelectorContext } from "./selector-context-heuristic-CGwiJ3HL.mjs";
+import { t as isSelectorContext } from "./selector-context-heuristic-Cki9_tTH.mjs";
 import { resolve } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
 

package/dist/forwarded-as-consumer-patcher-GPnjkzc_.mjs

@@ -0,0 +1,91 @@
+import { n as escapeRegex } from "./string-utils-Dmym5IkG.mjs";
+import { resolve } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+
+//#region src/internal/forwarded-as-consumer-patcher.ts
+/**
+* Post-transform consumer patching for `as` → `forwardedAs`.
+*
+* When a component (e.g., `Flex`) is converted from styled-components to StyleX,
+* unconverted consumer files that wrap it with `styled(Flex)` break when using
+* the `as` prop — styled-components intercepts `as` and replaces `Flex` entirely,
+* losing all StyleX styles.
+*
+* `forwardedAs` tells styled-components to pass the prop through to the wrapped
+* component's own `as` prop, preserving StyleX styles.
+*/
+/**
+* Filter prepass consumers to exclude:
+* - consumers that were actually transformed (no longer use styled-components)
+* - entries whose wrapped target bailed and didn't actually transform
+*
+* Returns a map of consumer paths → entries to patch.
+*/
+function buildForwardedAsReplacements(prepassConsumers, transformedFiles) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [consumerPath, entries] of prepassConsumers) {
+		if (transformedFiles.has(toRealPath(consumerPath))) continue;
+		const surviving = entries.filter((e) => transformedFiles.has(e.targetPath));
+		if (surviving.length > 0) result.set(consumerPath, surviving);
+	}
+	return result;
+}
+/**
+* Patch a single consumer file: replace `as` with `forwardedAs` in JSX props
+* and `.attrs()` calls for the given styled wrapper components.
+*
+* Returns the patched source or `null` if no changes were made.
+*/
+function patchConsumerForwardedAs(filePath, entries) {
+	let source;
+	try {
+		source = readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+	if (entries.length === 0) return null;
+	let modified = source;
+	for (const { localStyledName } of entries) {
+		modified = patchJsxAsProp(modified, localStyledName);
+		modified = patchAttrsAsProp(modified, localStyledName);
+	}
+	return modified !== source ? modified : null;
+}
+/**
+* Replace `as=` with `forwardedAs=` in JSX tags for the given component name.
+* Handles both `as="span"` and `as={expr}` forms.
+* Skips tags that already contain `forwardedAs`.
+*/
+function patchJsxAsProp(source, componentName) {
+	const tagRegex = new RegExp(`(<${escapeRegex(componentName)}\\b[^<>]*)\\bas(\\s*[={])`, "g");
+	return source.replace(tagRegex, (match, before, after) => {
+		if (before.includes("forwardedAs") || match.includes("forwardedAs")) return match;
+		return `${before}forwardedAs${after}`;
+	});
+}
+/**
+* Replace `as:` with `forwardedAs:` in object-form `.attrs({...})` calls on
+* the styled declaration for the given component name.
+* Only matches object-form `.attrs({ as: ... })`, NOT function-form
+* `.attrs(({ as }) => ...)` where the destructuring param would be incorrectly patched.
+* Skips attrs blocks that already contain `forwardedAs`.
+*/
+function patchAttrsAsProp(source, componentName) {
+	const attrsRegex = new RegExp(`(const\\s+${escapeRegex(componentName)}\\b[^;]*\\.attrs\\s*\\(\\s*\\{[^)]*?)\\bas(\\s*:)`, "g");
+	return source.replace(attrsRegex, (match, before, after) => {
+		if (before.includes("forwardedAs")) return match;
+		return `${before}forwardedAs${after}`;
+	});
+}
+/** Resolve symlinks so paths match the keys in transformedFiles. */
+function toRealPath(filePath) {
+	const resolved = resolve(filePath);
+	try {
+		return realpathSync(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+//#endregion
+export { buildForwardedAsReplacements, patchConsumerForwardedAs };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-DyMTX-U6.mjs";
+import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-tKRY0yOA.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as assertValidAdapterInput, o as describeValue, r as defineAdapter, t as Logger } from "./logger-D7X3KrX1.mjs";
+import { a as assertValidAdapterInput, o as describeValue, r as defineAdapter, t as Logger } from "./logger-Bi5-MGBs.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
@@ -141,9 +141,9 @@ async function runTransform(options) {
 		`Pattern(s): ${consumerPatterns.join(", ")}`,
 		"Check that the glob pattern is correct and files exist."
 	].join("\n"));
-	const { createModuleResolver } = await import("./resolve-imports-BDk6Ms09.mjs");
+	const { createModuleResolver } = await import("./resolve-imports-4bFqrkrQ.mjs");
 	const sharedResolver = createModuleResolver();
-	const { runPrepass } = await import("./run-prepass-ByjC18e6.mjs");
+	const { runPrepass } = await import("./run-prepass-BuYfEK4M.mjs");
 	const absoluteFiles = filePaths.map((f) => resolve(f));
 	const absoluteConsumers = consumerFilePaths.map((f) => resolve(f));
 	let prepassResult;
@@ -165,7 +165,8 @@ async function runTransform(options) {
 				componentsNeedingMarkerSidecar: /* @__PURE__ */ new Map(),
 				componentsNeedingGlobalSelectorBridge: /* @__PURE__ */ new Map()
 			},
-			consumerAnalysis: void 0
+			consumerAnalysis: void 0,
+			forwardedAsConsumers: /* @__PURE__ */ new Map()
 		};
 	}
 	const crossFilePrepassResult = prepassResult.crossFileInfo;
@@ -183,7 +184,8 @@ async function runTransform(options) {
 					}
 					return analysisMap.get(`${realPath}:${ctx.componentName}`) ?? {
 						styles: false,
-						as: false
+						as: false,
+						ref: false
 					};
 				}
 			};
@@ -229,7 +231,7 @@ async function runTransform(options) {
 	});
 	if (sidecarFiles.size > 0 && !dryRun) for (const [sidecarPath, content] of sidecarFiles) await writeFile(sidecarPath, mergeSidecarContent(sidecarPath, content), "utf-8");
 	if (bridgeResults.size > 0 && !dryRun) {
-		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-DhMoL4Od.mjs");
+		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-C2mFaVmd.mjs");
 		const consumerReplacements = buildConsumerReplacements(crossFilePrepassResult.selectorUsages, bridgeResults, transformedFiles);
 		const patchedFiles = [];
 		for (const [consumerPath, replacements] of consumerReplacements) {
@@ -241,6 +243,19 @@ async function runTransform(options) {
 		}
 		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
 	}
+	if (prepassResult.forwardedAsConsumers.size > 0 && !dryRun) {
+		const { buildForwardedAsReplacements, patchConsumerForwardedAs } = await import("./forwarded-as-consumer-patcher-GPnjkzc_.mjs");
+		const forwardedAsReplacements = buildForwardedAsReplacements(prepassResult.forwardedAsConsumers, transformedFiles);
+		const patchedFiles = [];
+		for (const [consumerPath, entries] of forwardedAsReplacements) {
+			const patched = patchConsumerForwardedAs(consumerPath, entries);
+			if (patched !== null) {
+				await writeFile(consumerPath, patched, "utf-8");
+				patchedFiles.push(consumerPath);
+			}
+		}
+		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
+	}
 	if (formatterCommands && formatterCommands.length > 0 && result.ok > 0 && !dryRun) await runFormatters(formatterCommands, filePaths);
 	const report = Logger.createReport();
 	report.print();

package/dist/{logger-D7X3KrX1.mjs → logger-Bi5-MGBs.mjs}

@@ -229,11 +229,11 @@ const DEFAULT_THEME_HOOK = {
 *
 *     // Configure external interface for exported components
 *     externalInterface(ctx) {
-*       // Example: Enable styles and `as` for shared components folder
+*       // Example: Enable styles, `as`, and `ref` for shared components folder
 *       if (ctx.filePath.includes("/shared/components/")) {
-*         return { styles: true, as: true };
+*         return { styles: true, as: true, ref: true };
 *       }
-*       return { styles: false, as: false };
+*       return { styles: false, as: false, ref: false };
 *     },
 *
 *     // Optional: provide a custom merger, or use `null` for the default verbose merge output

package/dist/{logger-DyMTX-U6.d.mts → logger-tKRY0yOA.d.mts}

@@ -164,7 +164,7 @@ type ResolveValueResult = {
    */
   usage?: "props";
 };
-type CallResolveResult = {
+type CallResolveResultWithExpr = {
   /**
    * JS expression string to inline into generated output.
    *
@@ -217,7 +217,38 @@ type CallResolveResult = {
    * Example: `"white-space: nowrap; overflow: hidden; text-overflow: ellipsis;"`
    */
   cssText?: string;
+  /**
+   * When true, keeps the original helper call as a runtime style-function override
+   * in addition to the resolved static value.
+   *
+   * This is useful for incremental migrations where you still want to run an
+   * existing runtime helper (for example `ColorConverter.cssWithAlpha(...)`) while
+   * also emitting a static StyleX fallback.
+   *
+   * Behavior notes:
+   * - In `CallResolveResultWithExpr`, `expr`/`imports` are used as a static fallback in
+   *   `stylex.create(...)`.
+   * - In `CallResolveRuntimeOnlyResult`, no static fallback is emitted.
+   * - The runtime override is only emitted for arrow-function helper call interpolations.
+   * - Theme access in the original call is rewritten to use the wrapper `useTheme()` value.
+   */
+  preserveRuntimeCall?: boolean;
+};
+type CallResolveRuntimeOnlyResult = {
+  /**
+   * Keep the original helper call as a runtime style-function override, without
+   * requiring a static fallback expression.
+   *
+   * This mode is only supported for helper calls used as CSS values (not StyleX
+   * style-object references).
+   */
+  preserveRuntimeCall: true;
+  /**
+   * Optional usage hint. Runtime-only results are treated as CSS-value usage.
+   */
+  usage?: "create";
 };
+type CallResolveResult = CallResolveResultWithExpr | CallResolveRuntimeOnlyResult;
 type ImportSource = {
   kind: "absolutePath";
   value: string;
@@ -361,14 +392,19 @@ interface ExternalInterfaceContext {
 /**
  * Result type for `adapter.externalInterface(...)`.
  *
- * - `{ styles: true, as: false }` → enable className/style support only
- * - `{ styles: true, as: true }` → enable className/style support AND polymorphic `as` prop
- * - `{ styles: false, as: true }` → enable only polymorphic `as` prop (no style merging)
- * - `{ styles: false, as: false }` → no external interface support
+ * - `styles` — accept external className/style props
+ * - `as` — accept polymorphic `as` prop
+ * - `ref` — include `ref` in the component's public type
+ *
+ * Examples:
+ * - `{ styles: true, as: false, ref: false }` → className/style support only
+ * - `{ styles: true, as: true, ref: true }` → full external interface
+ * - `{ styles: false, as: false, ref: false }` → no external interface support
  */
 type ExternalInterfaceResult = {
   styles: boolean;
   as: boolean;
+  ref: boolean;
 };
 /**
  * Configuration for a custom style merger function that combines stylex.props()
@@ -430,6 +466,10 @@ interface Adapter {
    *
    * Return:
    * - `{ expr, imports }` with the resolved expression
+   * - `{ preserveRuntimeCall: true }` to keep only the original runtime helper call
+   *   (no static fallback)
+   * - Optional: add `preserveRuntimeCall: true` to also keep the original helper
+   *   call at runtime as a wrapper style-function override
    * - `undefined` to bail/skip the file
    */
   resolveCall: (context: CallResolveContext) => CallResolveResult | undefined;
@@ -458,10 +498,10 @@ interface Adapter {
    * Called for exported styled components to determine their external interface.
    *
    * Return:
-   * - `{ styles: false, as: false }` → no external interface
-   * - `{ styles: true, as: false }` → accept className/style props only
-   * - `{ styles: true, as: true }` → accept className/style props AND polymorphic `as` prop
-   * - `{ styles: false, as: true }` → accept only polymorphic `as` prop
+   * - `{ styles: false, as: false, ref: false }` → no external interface
+   * - `{ styles: true, as: false, ref: false }` → accept className/style props only
+   * - `{ styles: true, as: true, ref: true }` → full external interface
+   * - `{ styles: false, as: true, ref: false }` → accept only polymorphic `as` prop
    */
   externalInterface: (context: ExternalInterfaceContext) => ExternalInterfaceResult;
   /**
@@ -474,7 +514,7 @@ interface Adapter {
    * ```typescript
    * function merger(
    *   styles: StyleXStyles | StyleXStyles[],
-   *   className?: string,
+   *   className?: string | (string | undefined | false | null)[],
    *   style?: React.CSSProperties
    * ): { className?: string; style?: React.CSSProperties }
    * ```
@@ -552,11 +592,11 @@ interface AdapterInput {
  *
  *     // Configure external interface for exported components
  *     externalInterface(ctx) {
- *       // Example: Enable styles and `as` for shared components folder
+ *       // Example: Enable styles, `as`, and `ref` for shared components folder
  *       if (ctx.filePath.includes("/shared/components/")) {
- *         return { styles: true, as: true };
+ *         return { styles: true, as: true, ref: true };
  *       }
- *       return { styles: false, as: false };
+ *       return { styles: false, as: false, ref: false };
  *     },
  *
  *     // Optional: provide a custom merger, or use `null` for the default verbose merge output
@@ -573,7 +613,7 @@ declare function defineAdapter<T extends AdapterInput>(adapter: T): T;
 //#endregion
 //#region src/internal/logger.d.ts
 type Severity = "info" | "warning" | "error";
-type WarningType = "`css` helper function switch must return css templates in all branches" | "`css` helper usage as a function call (css(...)) is not supported" | "`css` helper used outside of a styled component template cannot be statically transformed" | "Adapter helper call in border interpolation did not resolve to a single CSS value" | "Adapter resolveCall returned an unparseable styles expression" | "Adapter resolveCall returned an unparseable value expression" | "Adapter resolveCall returned StyleX styles for helper call where a CSS value was expected" | "Adapter resolveCall returned undefined for helper call" | "Adapter resolveBaseComponent threw an error" | "Adapter resolved StyleX styles cannot be applied under nested selectors/at-rules" | "Adapter resolved StyleX styles inside pseudo selector but did not provide cssText for property expansion — add cssText to resolveCall result to enable pseudo-wrapping" | 'Adapter resolveCall cssText could not be parsed as CSS declarations — expected semicolon-separated property: value pairs (e.g. "white-space: nowrap; overflow: hidden;")' | "Adapter resolveValue returned an unparseable value expression" | "Adapter resolveValue returned undefined for imported value" | "Arrow function: body is not a recognized pattern (expected ternary, logical, call, or member expression)" | "Arrow function: conditional branches could not be resolved to static or theme values" | "Arrow function: helper call body is not supported" | "Arrow function: indexed theme lookup pattern not matched" | "Arrow function: logical expression pattern not supported" | "Arrow function: prop access cannot be converted to style function for this CSS property" | "Arrow function: theme access path could not be resolved" | "Component selectors like `${OtherComponent}:hover &` are not directly representable in StyleX. Manual refactor is required" | "Conditional `css` block: !important is not supported in StyleX" | "Conditional `css` block: @-rules (e.g., @media, @supports) are not supported" | "CSS block contains unsupported at-rule (only @media is supported; @supports, @container, etc. require manual handling)" | "Conditional `css` block: dynamic interpolation could not be resolved to a single component prop" | "Conditional `css` block: failed to parse expression" | "Conditional `css` block: missing CSS property name" | "Conditional `css` block: missing interpolation expression" | "Conditional `css` block: mixed static/dynamic values with non-theme expressions cannot be safely transformed" | "Conditional `css` block: multiple interpolation slots in a single property value" | "Conditional `css` block: ternary branch value could not be resolved (imported values require adapter support)" | "Conditional `css` block: ternary expressions inside pseudo selectors are not supported" | "Conditional `css` block: unsupported selector" | "Directional border helper styles are not supported" | "Multi-slot border interpolation could not be resolved" | "createGlobalStyle is not supported in StyleX. Global styles should be handled separately (e.g., in a CSS file or using CSS reset libraries)" | "Dynamic styles inside pseudo elements (::before/::after) are not supported by StyleX. See https://github.com/facebook/stylex/issues/1396" | "Failed to parse theme expressions" | "Heterogeneous background values (mix of gradients and colors) not currently supported" | "Higher-order styled factory wrappers (e.g. hoc(styled)) are not supported" | "Imported CSS helper mixins: cannot determine inherited properties for correct pseudo selector handling" | "Styled-components specificity hacks like `&&` / `&&&` are not representable in StyleX" | "Theme-dependent block-level conditional could not be fully resolved (branches may contain dynamic interpolations)" | "Theme-dependant call expression could not be resolved (e.g. theme helper calls like theme.highlight() are not supported)" | "Theme value with fallback (props.theme.X ?? / || default) cannot be resolved statically — use adapter.resolveValue to map theme paths to StyleX tokens" | "Theme-dependent nested prop access requires a project-specific theme source (e.g. useTheme())" | "Theme-dependent template literals require a project-specific theme source (e.g. useTheme())" | "Theme prop overrides on styled components are not supported" | "Universal selectors (`*`) are currently unsupported" | "Unsupported call expression (expected imported helper(...) or imported helper(...)(...))" | "Unsupported conditional test in shouldForwardProp" | "Unsupported shouldForwardProp pattern (only !prop.startsWith(), ![].includes(prop), and prop !== are supported)" | "Unsupported interpolation: arrow function" | "Unsupported interpolation: call expression" | "Unsupported interpolation: identifier" | "Unsupported interpolation: member expression" | "Unsupported interpolation: property" | "Unsupported interpolation: unknown" | "Unsupported nested conditional interpolation" | "Unsupported prop-based inline style expression cannot be safely inlined" | "Unsupported prop-based inline style props.theme access is not supported" | "Unsupported selector interpolation: imported value in selector position" | "Unsupported selector: class selector" | "Unsupported selector: comma-separated selectors must all be simple pseudos or pseudo-elements" | "Unsupported selector: descendant pseudo selector (space before pseudo)" | "Unsupported selector: descendant/child/sibling selector" | "Unsupported selector: interpolated pseudo selector" | "Unsupported selector: sibling combinator" | "Unsupported selector: unresolved interpolation in sibling selector" | "Unsupported selector: ambiguous element selector" | "Unsupported selector: attribute selector on unsupported element" | "Unsupported selector: element selector on exported component" | "Unsupported selector: element selector with combined ancestor and child pseudos" | "Unsupported selector: element selector with dynamic children" | "Unsupported selector: element selector with plain intrinsic children" | "Unsupported selector: element selector pseudo collision" | "Unsupported selector: unresolved interpolation in cross-file component selector" | "Unsupported selector: unresolved interpolation in descendant component selector" | "Unsupported selector: unresolved interpolation in element selector" | "Unsupported selector: unresolved interpolation in reverse component selector" | "Unsupported selector: grouped reverse selector references different components" | "Unsupported selector: unknown component selector" | "Unsupported css`` mixin: after-base mixin style is not a plain object" | "Unsupported css`` mixin: nested contextual conditions in after-base mixin" | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)" | "css`` helper function interpolation references closure variable that cannot be hoisted" | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match" | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead" | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts";
+type WarningType = "`css` helper function switch must return css templates in all branches" | "`css` helper usage as a function call (css(...)) is not supported" | "`css` helper used outside of a styled component template cannot be statically transformed" | "Adapter helper call in border interpolation did not resolve to a single CSS value" | "Adapter resolveCall returned an unparseable styles expression" | "Adapter resolveCall returned an unparseable value expression" | "Adapter resolveCall returned StyleX styles for helper call where a CSS value was expected" | "Adapter resolveCall returned undefined for helper call" | "Adapter resolveBaseComponent threw an error" | "Adapter resolved StyleX styles cannot be applied under nested selectors/at-rules" | "Adapter resolved StyleX styles inside pseudo selector but did not provide cssText for property expansion — add cssText to resolveCall result to enable pseudo-wrapping" | 'Adapter resolveCall cssText could not be parsed as CSS declarations — expected semicolon-separated property: value pairs (e.g. "white-space: nowrap; overflow: hidden;")' | "Adapter resolveValue returned an unparseable value expression" | "Adapter resolveValue returned undefined for imported value" | "Arrow function: body is not a recognized pattern (expected ternary, logical, call, or member expression)" | "Arrow function: conditional branches could not be resolved to static or theme values" | "Arrow function: helper call body is not supported" | "Arrow function: indexed theme lookup pattern not matched" | "Arrow function: logical expression pattern not supported" | "Arrow function: prop access cannot be converted to style function for this CSS property" | "Arrow function: theme access path could not be resolved" | "Component selectors like `${OtherComponent}:hover &` are not directly representable in StyleX. Manual refactor is required" | "Conditional `css` block: !important is not supported in StyleX" | "Conditional `css` block: @-rules (e.g., @media, @supports) are not supported" | "CSS block contains unsupported at-rule (only @media and @container are supported; @supports, etc. require manual handling)" | "Conditional `css` block: dynamic interpolation could not be resolved to a single component prop" | "Conditional `css` block: failed to parse expression" | "Conditional `css` block: missing CSS property name" | "Conditional `css` block: missing interpolation expression" | "Conditional `css` block: mixed static/dynamic values with non-theme expressions cannot be safely transformed" | "Conditional `css` block: multiple interpolation slots in a single property value" | "Conditional `css` block: ternary branch value could not be resolved (imported values require adapter support)" | "Conditional `css` block: ternary expressions inside pseudo selectors are not supported" | "Conditional `css` block: media query contains unresolvable interpolation" | "Conditional `css` block: unsupported selector" | "Directional border helper styles are not supported" | "Multi-slot border interpolation could not be resolved" | "Resolved border helper value could not be expanded to longhand properties" | "createGlobalStyle is not supported in StyleX. Global styles should be handled separately (e.g., in a CSS file or using CSS reset libraries)" | "Dynamic styles inside pseudo elements (::before/::after) are not supported by StyleX. See https://github.com/facebook/stylex/issues/1396" | "Failed to parse theme expressions" | "Heterogeneous background values (mix of gradients and colors) not currently supported" | "Higher-order styled factory wrappers (e.g. hoc(styled)) are not supported" | "Imported CSS helper mixins: cannot determine inherited properties for correct pseudo selector handling" | "Local helper function returns CSS that cannot be decomposed into individual properties" | "Local helper function computes CSS values that cannot be statically traced to the component prop" | "Styled-components specificity hacks like `&&` / `&&&` are not representable in StyleX" | "Theme-dependent block-level conditional could not be fully resolved (branches may contain dynamic interpolations)" | "Theme-dependant call expression could not be resolved (e.g. theme helper calls like theme.highlight() are not supported)" | "Theme value with fallback (props.theme.X ?? / || default) cannot be resolved statically — use adapter.resolveValue to map theme paths to StyleX tokens" | "Theme-dependent nested prop access requires a project-specific theme source (e.g. useTheme())" | "Theme-dependent template literals require a project-specific theme source (e.g. useTheme())" | "Theme prop overrides on styled components are not supported" | "Universal selectors (`*`) are currently unsupported" | "Unsupported call expression (expected imported helper(...) or imported helper(...)(...))" | "Unsupported conditional test in shouldForwardProp" | "Unsupported shouldForwardProp pattern (only !prop.startsWith(), ![].includes(prop), and prop !== are supported)" | "Unsupported interpolation: arrow function" | "Unsupported interpolation: call expression" | "Unsupported interpolation: identifier" | "Unsupported interpolation: member expression" | "Unsupported interpolation: property" | "Unsupported interpolation: unknown" | "Unsupported nested conditional interpolation" | "Unsupported prop-based inline style expression cannot be safely inlined" | "Unsupported prop-based inline style props.theme access is not supported" | "Unsupported selector interpolation: imported value in selector position" | "Unsupported: media query contains unresolvable interpolation" | "Unsupported selector: class selector" | "Unsupported selector: comma-separated selectors must all be simple pseudos or pseudo-elements" | "Unsupported selector: descendant pseudo selector (space before pseudo)" | "Unsupported selector: descendant/child/sibling selector" | "Unsupported selector: interpolated pseudo selector" | "Unsupported selector: sibling combinator" | "Unsupported selector: unresolved interpolation in sibling selector" | "Unsupported selector: ambiguous element selector" | "Unsupported selector: attribute selector on unsupported element" | "Unsupported selector: element selector on exported component" | "Unsupported selector: element selector with combined ancestor and child pseudos" | "Unsupported selector: element selector with dynamic children" | "Unsupported selector: element selector with plain intrinsic children" | "Unsupported selector: element selector pseudo collision" | "Unsupported selector: unresolved interpolation in cross-file component selector" | "Unsupported selector: unresolved interpolation in descendant component selector" | "Unsupported selector: unresolved interpolation in element selector" | "Unsupported selector: unresolved interpolation in reverse component selector" | "Unsupported selector: grouped reverse selector references different components" | "Unsupported selector: unknown component selector" | "Unsupported css`` mixin: after-base mixin style is not a plain object" | "Unsupported css`` mixin: nested contextual conditions in after-base mixin" | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)" | "css`` helper function interpolation references closure variable that cannot be hoisted" | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match" | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead" | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts";
 interface WarningLog {
   severity: Severity;
   type: WarningType;

package/dist/{run-prepass-ByjC18e6.mjs → run-prepass-BuYfEK4M.mjs}

@@ -1,5 +1,5 @@
 import { t as PLACEHOLDER_RE } from "./styled-css-DBryFqQM.mjs";
-import { t as isSelectorContext } from "./selector-context-heuristic-CGwiJ3HL.mjs";
+import { t as isSelectorContext } from "./selector-context-heuristic-Cki9_tTH.mjs";
 import path, { relative, resolve } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
 import { execSync } from "node:child_process";
@@ -466,10 +466,15 @@ function deduplicateAndResolve(filesToTransform, consumerPaths) {
 * and runs AST parsing + consumer analysis only on relevant files.
 */
 const AS_PROP_RE = /\bas[={]/;
+const REF_PROP_RE = /\bref[={]/;
 const STYLED_CALL_RE = /styled\(([A-Z][A-Za-z0-9]+)/g;
 const STYLED_DEF_RE = /const\s+([A-Z][A-Za-z0-9]*)\b[^=]*=\s*styled[.(]/g;
 /** Matches <Component ...as= across lines. [^<>]* avoids crossing tag boundaries. */
 const JSX_AS_COMPONENT_RE = /<([A-Z][A-Za-z0-9]*)\b[^<>]*\bas[={]/g;
+/** Matches <Component ...ref= across lines. [^<>]* avoids crossing tag boundaries. */
+const JSX_REF_COMPONENT_RE = /<([A-Z][A-Za-z0-9]*)\b[^<>]*\bref[={]/g;
+/** Captures both the local styled name and the wrapped component: styled(Flex) → ["StyledFlex", "Flex"] */
+const STYLED_COMPONENT_WRAPPER_RE = /const\s+([A-Z][A-Za-z0-9]*)\b[^=]*=\s*styled\(\s*([A-Z][A-Za-z0-9]*)\s*\)/g;
 async function runPrepass(options) {
 	const { filesToTransform, consumerPaths, resolver, parserName, createExternalInterface, enableAstCache } = options;
 	const t0 = performance.now();
@@ -517,9 +522,11 @@ async function runPrepass(options) {
 	const componentsNeedingMarkerSidecar = /* @__PURE__ */ new Map();
 	const componentsNeedingGlobalSelectorBridge = /* @__PURE__ */ new Map();
 	const asUsages = /* @__PURE__ */ new Map();
+	const refUsages = /* @__PURE__ */ new Map();
 	const styledCallUsages = [];
 	const styledDefFiles = /* @__PURE__ */ new Map();
 	const classNameStyleUsages = /* @__PURE__ */ new Map();
+	const styledWrapperUsages = [];
 	const fileContents = /* @__PURE__ */ new Map();
 	const cachedRead = (filePath) => {
 		const content = fileContents.get(filePath);
@@ -543,7 +550,8 @@ async function runPrepass(options) {
 		}
 		const hasStyled = source.includes("styled-components");
 		const hasAsProp = createExternalInterface && AS_PROP_RE.test(source);
-		if (!hasStyled && !hasAsProp) continue;
+		const hasRefProp = createExternalInterface && REF_PROP_RE.test(source);
+		if (!hasStyled && !hasAsProp && !hasRefProp) continue;
 		fileContents.set(filePath, source);
 		if (hasStyled && BARE_TEMPLATE_IDENTIFIER_RE.test(source) && hasRegexSelectorCandidate(source)) {
 			const usages = scanFileForSelectorsAst(filePath, source, transformSet, resolver, parser, toRealPath, cachedRead, astCache, createExternalInterface);
@@ -560,11 +568,21 @@ async function runPrepass(options) {
 			});
 			STYLED_DEF_RE.lastIndex = 0;
 			for (const m of source.matchAll(STYLED_DEF_RE)) if (m[1]) addToSetMap(styledDefFiles, filePath, m[1]);
+			STYLED_COMPONENT_WRAPPER_RE.lastIndex = 0;
+			for (const m of source.matchAll(STYLED_COMPONENT_WRAPPER_RE)) if (m[1] && m[2]) styledWrapperUsages.push({
+				file: filePath,
+				localStyledName: m[1],
+				wrappedName: m[2]
+			});
 		}
 		if (hasAsProp) {
 			JSX_AS_COMPONENT_RE.lastIndex = 0;
 			for (const m of source.matchAll(JSX_AS_COMPONENT_RE)) if (m[1]) addToSetMap(asUsages, m[1], filePath);
 		}
+		if (hasRefProp) {
+			JSX_REF_COMPONENT_RE.lastIndex = 0;
+			for (const m of source.matchAll(JSX_REF_COMPONENT_RE)) if (m[1]) addToSetMap(refUsages, m[1], filePath);
+		}
 	}
 	const styledFileCount = fileContents.size;
 	if (createExternalInterface && styledDefFiles.size > 0) {
@@ -590,44 +608,35 @@ async function runPrepass(options) {
 			if (!entry) {
 				entry = {
 					styles: false,
-					as: false
+					as: false,
+					ref: false
 				};
 				consumerAnalysis.set(key, entry);
 			}
 			return entry;
 		};
-		if (asUsages.size > 0) for (const [defFile, names] of styledDefFiles) {
-			const defSrc = cachedRead(defFile);
-			for (const name of names) {
-				const usageFiles = asUsages.get(name);
-				if (!usageFiles) continue;
-				if (!fileExports(defSrc, name)) continue;
-				if (usageFiles.has(defFile)) {
-					ensure(defFile, name).as = true;
-					continue;
-				}
-				for (const usageFile of usageFiles) if (fileImportsFrom(cachedRead(usageFile), usageFile, name, defFile, resolve$1)) {
-					ensure(defFile, name).as = true;
-					break;
+		const matchUsagesToDefinitions = (usages, field) => {
+			if (usages.size === 0) return;
+			for (const [defFile, names] of styledDefFiles) {
+				const defSrc = cachedRead(defFile);
+				for (const name of names) {
+					const usageFiles = usages.get(name);
+					if (!usageFiles) continue;
+					if (!fileExports(defSrc, name)) continue;
+					if (usageFiles.has(defFile)) {
+						ensure(defFile, name)[field] = true;
+						continue;
+					}
+					for (const usageFile of usageFiles) if (fileImportsFrom(cachedRead(usageFile), usageFile, name, defFile, resolve$1)) {
+						ensure(defFile, name)[field] = true;
+						break;
+					}
 				}
 			}
-		}
-		if (classNameStyleUsages.size > 0) for (const [defFile, names] of styledDefFiles) {
-			const defSrc = cachedRead(defFile);
-			for (const name of names) {
-				const usageFiles = classNameStyleUsages.get(name);
-				if (!usageFiles) continue;
-				if (!fileExports(defSrc, name)) continue;
-				if (usageFiles.has(defFile)) {
-					ensure(defFile, name).styles = true;
-					continue;
-				}
-				for (const usageFile of usageFiles) if (fileImportsFrom(cachedRead(usageFile), usageFile, name, defFile, resolve$1)) {
-					ensure(defFile, name).styles = true;
-					break;
-				}
-			}
-		}
+		};
+		matchUsagesToDefinitions(asUsages, "as");
+		matchUsagesToDefinitions(refUsages, "ref");
+		matchUsagesToDefinitions(classNameStyleUsages, "styles");
 		{
 			const seen = /* @__PURE__ */ new Set();
 			for (const { file, name } of styledCallUsages) {
@@ -649,6 +658,26 @@ async function runPrepass(options) {
 			}
 		}
 	}
+	const forwardedAsConsumers = /* @__PURE__ */ new Map();
+	if (createExternalInterface && styledWrapperUsages.length > 0) for (const { file, localStyledName, wrappedName } of styledWrapperUsages) {
+		if (transformSet.has(file)) continue;
+		const importInfo = findImportSource(cachedRead(file), wrappedName);
+		if (!importInfo) continue;
+		const { source: importSource, exportedName } = importInfo;
+		let defFile = resolve$1(importSource, file);
+		if (!defFile) continue;
+		defFile = resolveBarrelReExport(defFile, exportedName, resolve$1, cachedRead) ?? defFile;
+		if (!transformSet.has(defFile)) continue;
+		let entries = forwardedAsConsumers.get(file);
+		if (!entries) {
+			entries = [];
+			forwardedAsConsumers.set(file, entries);
+		}
+		entries.push({
+			localStyledName,
+			targetPath: defFile
+		});
+	}
 	const crossFileInfo = {
 		selectorUsages,
 		componentsNeedingMarkerSidecar,
@@ -659,12 +688,14 @@ async function runPrepass(options) {
 		const elapsed = ((performance.now() - t0) / 1e3).toFixed(1);
 		const reStyled = consumerAnalysis ? [...consumerAnalysis.values()].filter((v) => v.styles).length : 0;
 		const asProp = consumerAnalysis ? [...consumerAnalysis.values()].filter((v) => v.as).length : 0;
-		process.stdout.write(`Prepass: scanned ${uniqueAllFiles.length} files in ${elapsed}s — ${styledFileCount} with styled-components, ${selectorUsages.size} cross-file selectors, ${reStyled} re-styled, ${asProp} as-prop, ${classNameStyleUsages.size} className/style\n`);
+		const refProp = consumerAnalysis ? [...consumerAnalysis.values()].filter((v) => v.ref).length : 0;
+		process.stdout.write(`Prepass: scanned ${uniqueAllFiles.length} files in ${elapsed}s — ${styledFileCount} with styled-components, ${selectorUsages.size} cross-file selectors, ${reStyled} re-styled, ${asProp} as-prop, ${refProp} ref-prop, ${classNameStyleUsages.size} className/style, ${forwardedAsConsumers.size} forwardedAs\n`);
 	}
 	if (process.env.DEBUG_CODEMOD) logPrepassDebug(uniqueAllFiles, crossFileInfo, consumerAnalysis);
 	return {
 		crossFileInfo,
-		consumerAnalysis
+		consumerAnalysis,
+		forwardedAsConsumers
 	};
 }
 /** Matches `${Identifier}` in source — used to find potential selector expressions. */
@@ -850,7 +881,7 @@ function rgPreFilter(files) {
 	const dirs = deduplicateParentDirs(files);
 	if (dirs.length === 0) return;
 	try {
-		const pattern = String.raw`(styled-components|\bas[={])`;
+		const pattern = String.raw`(styled-components|\bas[={]|\bref[={])`;
 		const globArgs = [
 			"*.tsx",
 			"*.ts",

package/dist/string-utils-Dmym5IkG.mjs

@@ -0,0 +1,80 @@
+//#region src/internal/utilities/string-utils.ts
+/**
+* Shared string formatting utilities.
+* Core concepts: casing conversions and whitespace normalization.
+*/
+/**
+* Capitalizes the first character of a string.
+* @example capitalize("hello") => "Hello"
+*/
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+* Converts a kebab-case string to camelCase.
+* @example kebabToCamelCase("focus-visible") => "focusVisible"
+* @example kebabToCamelCase("placeholder-shown") => "placeholderShown"
+* @example kebabToCamelCase("hover") => "hover"
+*/
+function kebabToCamelCase(s) {
+	return s.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+* Lowercases the first character of a string.
+* @example lowerFirst("Hello") => "hello"
+*/
+function lowerFirst(s) {
+	return s.charAt(0).toLowerCase() + s.slice(1);
+}
+/**
+* Removes non-alphanumeric characters (except underscores) from a string.
+* Useful for sanitizing strings to be valid JavaScript identifiers.
+* @example sanitizeIdentifier("my-var!") => "my_var_"
+*/
+function sanitizeIdentifier(s) {
+	return s.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+/**
+* Checks if a CSS value looks like a length unit (px, rem, em, %, etc.).
+* Matches numeric values with optional CSS length units.
+* @example looksLikeLength("10px") => true
+* @example looksLikeLength("1.5rem") => true
+* @example looksLikeLength("auto") => false
+*/
+function looksLikeLength(token) {
+	return /^-?\d*\.?\d+(px|rem|em|vh|vw|vmin|vmax|ch|ex|lh|svh|svw|dvh|dvw|cqw|cqh|%)?$/.test(token);
+}
+/**
+* Checks if a CSS value appears to be a background image (gradient or url).
+* @example isBackgroundImageValue("linear-gradient(red, blue)") => true
+* @example isBackgroundImageValue("url(image.png)") => true
+* @example isBackgroundImageValue("#fff") => false
+*/
+function isBackgroundImageValue(value) {
+	return /\b(linear|radial|conic|repeating-linear|repeating-radial|repeating-conic)-gradient\b/.test(value) || /\burl\s*\(/.test(value);
+}
+/**
+* Escapes special regex characters in a string so it can be safely used in a RegExp.
+* @example escapeRegex("foo.bar") => "foo\\.bar"
+* @example escapeRegex("$test") => "\\$test"
+*/
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Normalizes whitespace in a CSS value string.
+* Collapses all sequences of whitespace (including newlines) to single spaces
+* and trims leading/trailing whitespace.
+*
+* This is useful for multiline template literals that are used for formatting
+* convenience but should produce compact CSS values.
+*
+* @example normalizeWhitespace("  foo\n    bar  ") => "foo bar"
+* @example normalizeWhitespace("\n  value  \n") => "value"
+*/
+function normalizeWhitespace(s) {
+	return s.replace(/\s+/g, " ").trim();
+}
+
+//#endregion
+export { looksLikeLength as a, sanitizeIdentifier as c, kebabToCamelCase as i, escapeRegex as n, lowerFirst as o, isBackgroundImageValue as r, normalizeWhitespace as s, capitalize as t };

package/dist/transform.d.mts

@@ -1,4 +1,4 @@
-import { n as WarningLog, r as Adapter } from "./logger-DyMTX-U6.mjs";
+import { n as WarningLog, r as Adapter } from "./logger-tKRY0yOA.mjs";
 import "stylis";
 import { API, FileInfo, Options } from "jscodeshift";