styled-components-to-stylex-codemod 0.0.2 → 0.0.3

package/README.md

@@ -147,6 +147,46 @@ Adapters are the main extension point. They let you control:
 - what extra imports to inject into transformed files (returned from `resolveValue`)
 - how helper calls are resolved (via `resolveValue({ kind: "call", ... })`)
 - which exported components should support external className/style extension (`shouldSupportExternalStyling`)
+- how className/style merging is handled for components accepting external styling (`styleMerger`)
+
+#### Style Merger
+
+When a component accepts external `className` and/or `style` props (e.g., via `shouldSupportExternalStyling`, or when wrapping a base component that already accepts these props), the generated code needs to merge StyleX styles with externally passed values.
+
+> **Note:** Allowing external className/style props is generally discouraged in StyleX as it bypasses the type-safe styling system. However, it can be useful during migration to maintain compatibility with existing code that passes these props.
+
+By default, this generates verbose inline merging code. You can provide a `styleMerger` to use a helper function instead for cleaner output:
+
+```ts
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    // ... value resolution logic
+    return null;
+  },
+
+  shouldSupportExternalStyling(ctx) {
+    return ctx.filePath.includes("/shared/components/");
+  },
+
+  // Use a custom merger function for cleaner output
+  styleMerger: {
+    functionName: "mergedSx",
+    importSource: { kind: "specifier", value: "./lib/mergedSx" },
+  },
+});
+```
+
+The merger function should have this signature:
+
+```ts
+function mergedSx(
+  styles: StyleXStyles,
+  className?: string,
+  style?: React.CSSProperties
+): ReturnType<typeof stylex.props>;
+```
+
+See [`test-cases/lib/mergedSx.ts`](./test-cases/lib/mergedSx.ts) for a reference implementation.
 
 #### External Styles Support
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-Cry4CAGJ.mjs";
+import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-t2Vk9Bka.mjs";
 
 //#region src/internal/logger.d.ts
 interface CollectedWarning extends TransformWarning {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as describeValue, i as assertValidAdapter, n as logWarning, t as flushWarnings } from "./logger-Ckk2VkqY.mjs";
+import { a as describeValue, i as assertValidAdapter, n as logWarning, t as flushWarnings } from "./logger-Dhb8r1Ry.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -93,6 +93,7 @@ async function runTransform(options) {
 	const adapter = options.adapter;
 	assertValidAdapter(adapter, "runTransform(options)");
 	const adapterWithLogging = {
+		styleMerger: adapter.styleMerger,
 		shouldSupportExternalStyling(ctx) {
 			return adapter.shouldSupportExternalStyling(ctx);
 		},

package/dist/{logger-Ckk2VkqY.mjs → logger-Dhb8r1Ry.mjs}

@@ -1,5 +1,4 @@
 //#region src/internal/public-api-validation.ts
-const ADAPTER_DOCS_URL = `https://github.com/skovhus/styled-components-to-stylex-codemod#adapter`;
 function describeValue(value) {
 	if (value === null) return "null";
 	if (value === void 0) return "undefined";
@@ -52,11 +51,38 @@ function assertValidAdapter(candidate, where) {
 		`Docs/examples: ${ADAPTER_DOCS_URL}`
 	].join("\n"));
 	if (typeof shouldSupportExternalStyling !== "function") throw new Error([`[styled-components-to-stylex] ${where}: adapter.shouldSupportExternalStyling must be a function.`, `Received: shouldSupportExternalStyling=${describeValue(shouldSupportExternalStyling)}`].join("\n"));
+	const styleMerger = obj?.styleMerger;
+	if (styleMerger !== null && styleMerger !== void 0) {
+		if (typeof styleMerger !== "object") throw new Error([
+			`[styled-components-to-stylex] ${where}: adapter.styleMerger must be null or an object.`,
+			`Received: styleMerger=${describeValue(styleMerger)}`,
+			"",
+			"Expected shape:",
+			"  {",
+			"    functionName: \"stylexProps\",",
+			"    importSource: { kind: \"specifier\", value: \"@company/ui-utils\" }",
+			"  }"
+		].join("\n"));
+		const { functionName, importSource } = styleMerger;
+		if (typeof functionName !== "string" || !functionName.trim()) throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.functionName must be a non-empty string.`, `Received: functionName=${describeValue(functionName)}`].join("\n"));
+		if (!importSource || typeof importSource !== "object") throw new Error([
+			`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource must be an object.`,
+			`Received: importSource=${describeValue(importSource)}`,
+			"",
+			"Expected shape:",
+			"  { kind: \"specifier\", value: \"@company/ui-utils\" }",
+			"  or",
+			"  { kind: \"absolutePath\", value: \"/path/to/module.ts\" }"
+		].join("\n"));
+		const { kind, value } = importSource;
+		if (kind !== "specifier" && kind !== "absolutePath") throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource.kind must be "specifier" or "absolutePath".`, `Received: kind=${describeValue(kind)}`].join("\n"));
+		if (typeof value !== "string" || !value.trim()) throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource.value must be a non-empty string.`, `Received: value=${describeValue(value)}`].join("\n"));
+	}
 }
+const ADAPTER_DOCS_URL = `https://github.com/skovhus/styled-components-to-stylex-codemod#adapter`;
 
 //#endregion
 //#region src/internal/logger.ts
-let collected = [];
 /**
 * Clear collected warnings and return them.
 */
@@ -84,6 +110,7 @@ function logWarnings(warnings, filePath) {
 		logWarning(`[styled-components-to-stylex] Warning${warning.loc ? ` (${filePath}:${warning.loc.line}:${warning.loc.column})` : ` (${filePath})`}: ${warning.message}\n`);
 	}
 }
+let collected = [];
 
 //#endregion
 export { describeValue as a, assertValidAdapter as i, logWarning as n, logWarnings as r, flushWarnings as t };

package/dist/{transform-types-Cry4CAGJ.d.mts → transform-types-t2Vk9Bka.d.mts}

@@ -87,6 +87,26 @@ interface ExternalStylesContext {
   /** Whether it's a default export */
   isDefaultExport: boolean;
 }
+/**
+ * Configuration for a custom style merger function that combines stylex.props()
+ * results with external className/style props.
+ *
+ * When configured, generates cleaner output:
+ *   `{...stylexProps(styles.foo, className, style)}`
+ * instead of the verbose pattern:
+ *   `{...sx} className={[sx.className, className].filter(Boolean).join(" ")} style={{...sx.style, ...style}}`
+ */
+interface StyleMergerConfig {
+  /**
+   * Function name to use for merging (e.g., "stylexProps" or "mergeStylexProps").
+   */
+  functionName: string;
+  /**
+   * Import source for the merger function.
+   * Example: `{ kind: "specifier", value: "@company/ui-utils" }`
+   */
+  importSource: ImportSource;
+}
 interface Adapter {
   /** Unified resolver for theme paths + CSS variables. Return null to leave unresolved. */
   resolveValue: (context: ResolveContext) => ResolveResult | null;
@@ -96,6 +116,22 @@ interface Adapter {
    * className/style/rest merging.
    */
   shouldSupportExternalStyling: (context: ExternalStylesContext) => boolean;
+  /**
+   * Custom merger function for className/style combining.
+   * When provided, generates cleaner output using this function instead of
+   * the verbose className/style merging pattern.
+   * Set to `null` to use the verbose pattern (default).
+   *
+   * Expected merger function signature:
+   * ```typescript
+   * function merger(
+   *   styles: StyleXStyles | StyleXStyles[],
+   *   className?: string,
+   *   style?: React.CSSProperties
+   * ): { className?: string; style?: React.CSSProperties }
+   * ```
+   */
+  styleMerger: StyleMergerConfig | null;
 }
 /**
  * Helper for nicer user authoring + type inference.

package/dist/transform.d.mts

@@ -1,4 +1,4 @@
-import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-Cry4CAGJ.mjs";
+import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-t2Vk9Bka.mjs";
 import { API, FileInfo, Options } from "jscodeshift";
 
 //#region src/transform.d.ts