@mgcrea/react-native-tailwind 0.11.0 → 0.11.1

package/README.md

@@ -1887,6 +1887,135 @@ const styles = StyleSheet.create({
 - Choose a name that won't conflict with existing variables in your files
 - The same identifier is used across all files in your project
 
+### Custom Color Scheme Hook
+
+By default, the plugin uses React Native's built-in `useColorScheme()` hook for `dark:` and `light:` modifiers. You can configure it to use a custom color scheme hook from theme providers like React Navigation, Expo, or your own implementation.
+
+**Configuration:**
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        colorScheme: {
+          importFrom: "@/hooks/useColorScheme", // Module to import from
+          importName: "useColorScheme",          // Hook name to import
+        },
+      },
+    ],
+  ],
+};
+```
+
+**Use Cases:**
+
+#### 1. Custom Theme Provider
+
+Override system color scheme with user preferences from a store:
+
+```typescript
+// src/hooks/useColorScheme.ts
+import { useColorScheme as useSystemColorScheme } from "react-native";
+import { profileStore } from "@/stores/profileStore";
+import { type ColorSchemeName } from "react-native";
+
+export const useColorScheme = (): ColorSchemeName => {
+  const systemColorScheme = useSystemColorScheme();
+  const userTheme = profileStore.theme; // 'dark' | 'light' | 'auto'
+
+  // Return user preference, or fall back to system if set to 'auto'
+  return userTheme === 'auto' ? systemColorScheme : userTheme;
+};
+```
+
+```javascript
+// babel.config.js
+{
+  colorScheme: {
+    importFrom: "@/hooks/useColorScheme",
+    importName: "useColorScheme"
+  }
+}
+```
+
+#### 2. React Navigation Theme
+
+Integrate with React Navigation's theme system:
+
+```typescript
+// Wrap React Navigation's useTheme to return ColorSchemeName
+import { useTheme as useNavTheme } from "@react-navigation/native";
+import { type ColorSchemeName } from "react-native";
+
+export const useColorScheme = (): ColorSchemeName => {
+  const { dark } = useNavTheme();
+  return dark ? "dark" : "light";
+};
+```
+
+#### 3. Expo Router Theme
+
+Use Expo Router's theme hook:
+
+```javascript
+// babel.config.js
+{
+  colorScheme: {
+    importFrom: "expo-router",
+    importName: "useColorScheme"
+  }
+}
+```
+
+#### 4. Testing
+
+Mock color scheme for tests:
+
+```typescript
+// test/mocks/useColorScheme.ts
+export const useColorScheme = () => "light"; // Or "dark" for dark mode tests
+```
+
+```javascript
+// babel.config.js (test environment)
+{
+  colorScheme: {
+    importFrom: "@/test/mocks/useColorScheme",
+    importName: "useColorScheme"
+  }
+}
+```
+
+#### How it works
+
+When you use `dark:` or `light:` modifiers:
+
+```tsx
+<View className="bg-white dark:bg-gray-900" />
+```
+
+The plugin will:
+
+1. Import your custom hook: `import { useColorScheme } from "@/hooks/useColorScheme"`
+2. Inject it in components: `const _twColorScheme = useColorScheme();`
+3. Generate conditionals: `_twColorScheme === "dark" && styles._dark_bg_gray_900`
+
+#### Default behavior (no configuration)
+
+Without custom configuration, the plugin uses React Native's built-in hook:
+
+- Import: `import { useColorScheme } from "react-native"`
+- This works out of the box for basic system color scheme detection
+
+#### Requirements
+
+- Your custom hook must return `ColorSchemeName` (type from React Native: `"light" | "dark" | null | undefined`)
+- The hook must be compatible with React's rules of hooks (can only be called in function components)
+- Import merging works automatically if you already import from the same source
+
 ### Arbitrary Values
 
 Use arbitrary values for custom sizes, spacing, and borders not in the preset scales:

package/dist/babel/index.cjs

@@ -2518,33 +2518,33 @@ function addPlatformImport(path2, t) {
     path2.unshiftContainer("body", importDeclaration);
   }
 }
-function addColorSchemeImport(path2, t) {
+function addColorSchemeImport(path2, importSource, hookName, t) {
   const body = path2.node.body;
-  let reactNativeImport = null;
+  let existingValueImport = null;
   for (const statement of body) {
-    if (t.isImportDeclaration(statement) && statement.source.value === "react-native") {
-      reactNativeImport = statement;
-      break;
+    if (t.isImportDeclaration(statement) && statement.source.value === importSource) {
+      if (statement.importKind !== "type") {
+        existingValueImport = statement;
+        break;
+      }
     }
   }
-  if (reactNativeImport) {
-    const hasUseColorScheme = reactNativeImport.specifiers.some(
-      (spec) => t.isImportSpecifier(spec) && spec.imported.type === "Identifier" && spec.imported.name === "useColorScheme"
+  if (existingValueImport) {
+    const hasHook = existingValueImport.specifiers.some(
+      (spec) => t.isImportSpecifier(spec) && spec.imported.type === "Identifier" && spec.imported.name === hookName
     );
-    if (!hasUseColorScheme) {
-      reactNativeImport.specifiers.push(
-        t.importSpecifier(t.identifier("useColorScheme"), t.identifier("useColorScheme"))
-      );
+    if (!hasHook) {
+      existingValueImport.specifiers.push(t.importSpecifier(t.identifier(hookName), t.identifier(hookName)));
     }
   } else {
     const importDeclaration = t.importDeclaration(
-      [t.importSpecifier(t.identifier("useColorScheme"), t.identifier("useColorScheme"))],
-      t.stringLiteral("react-native")
+      [t.importSpecifier(t.identifier(hookName), t.identifier(hookName))],
+      t.stringLiteral(importSource)
     );
     path2.unshiftContainer("body", importDeclaration);
   }
 }
-function injectColorSchemeHook(functionPath, colorSchemeVariableName, t) {
+function injectColorSchemeHook(functionPath, colorSchemeVariableName, hookName, localIdentifier, t) {
   let body = functionPath.node.body;
   if (!t.isBlockStatement(body)) {
     if (t.isArrowFunctionExpression(functionPath.node) && t.isExpression(body)) {
@@ -2566,10 +2566,11 @@ function injectColorSchemeHook(functionPath, colorSchemeVariableName, t) {
   if (hasHook) {
     return false;
   }
+  const identifierToCall = localIdentifier ?? hookName;
   const hookCall = t.variableDeclaration("const", [
     t.variableDeclarator(
       t.identifier(colorSchemeVariableName),
-      t.callExpression(t.identifier("useColorScheme"), [])
+      t.callExpression(t.identifier(identifierToCall), [])
     )
   ]);
   body.body.unshift(hookCall);
@@ -2852,6 +2853,8 @@ function reactNativeTailwindBabelPlugin({ types: t }, options) {
     darkSuffix: options?.schemeModifier?.darkSuffix ?? "-dark",
     lightSuffix: options?.schemeModifier?.lightSuffix ?? "-light"
   };
+  const colorSchemeImportSource = options?.colorScheme?.importFrom ?? "react-native";
+  const colorSchemeHookName = options?.colorScheme?.importName ?? "useColorScheme";
   return {
     name: "react-native-tailwind",
     visitor: {
@@ -2865,6 +2868,8 @@ function reactNativeTailwindBabelPlugin({ types: t }, options) {
           state.hasColorSchemeImport = false;
           state.needsColorSchemeImport = false;
           state.colorSchemeVariableName = "_twColorScheme";
+          state.colorSchemeImportSource = colorSchemeImportSource;
+          state.colorSchemeHookName = colorSchemeHookName;
           state.supportedAttributes = exactMatches;
           state.attributePatterns = patterns;
           state.stylesIdentifier = stylesIdentifier;
@@ -2888,11 +2893,17 @@ function reactNativeTailwindBabelPlugin({ types: t }, options) {
             addPlatformImport(path2, t);
           }
           if (state.needsColorSchemeImport && !state.hasColorSchemeImport) {
-            addColorSchemeImport(path2, t);
+            addColorSchemeImport(path2, state.colorSchemeImportSource, state.colorSchemeHookName, t);
           }
           if (state.needsColorSchemeImport) {
             for (const functionPath of state.functionComponentsNeedingColorScheme) {
-              injectColorSchemeHook(functionPath, state.colorSchemeVariableName, t);
+              injectColorSchemeHook(
+                functionPath,
+                state.colorSchemeVariableName,
+                state.colorSchemeHookName,
+                state.colorSchemeLocalIdentifier,
+                t
+              );
             }
           }
           injectStylesAtTop(path2, state.styleRegistry, state.stylesIdentifier, t);
@@ -2915,23 +2926,26 @@ function reactNativeTailwindBabelPlugin({ types: t }, options) {
             }
             return false;
           });
-          const hasUseColorScheme = specifiers.some((spec) => {
-            if (t.isImportSpecifier(spec) && t.isIdentifier(spec.imported)) {
-              return spec.imported.name === "useColorScheme";
-            }
-            return false;
-          });
           if (hasStyleSheet) {
             state.hasStyleSheetImport = true;
           }
           if (hasPlatform) {
             state.hasPlatformImport = true;
           }
-          if (hasUseColorScheme) {
-            state.hasColorSchemeImport = true;
-          }
           state.reactNativeImportPath = path2;
         }
+        if (node.source.value === state.colorSchemeImportSource) {
+          const specifiers = node.specifiers;
+          for (const spec of specifiers) {
+            if (t.isImportSpecifier(spec) && t.isIdentifier(spec.imported)) {
+              if (spec.imported.name === state.colorSchemeHookName) {
+                state.hasColorSchemeImport = true;
+                state.colorSchemeLocalIdentifier = spec.local.name;
+                break;
+              }
+            }
+          }
+        }
         if (node.source.value === "@mgcrea/react-native-tailwind") {
           const specifiers = node.specifiers;
           specifiers.forEach((spec) => {

package/dist/babel/plugin.d.ts

@@ -41,6 +41,40 @@ export type PluginOptions = {
         darkSuffix?: string;
         lightSuffix?: string;
     };
+    /**
+     * Configuration for color scheme hook import (dark:/light: modifiers)
+     *
+     * Allows using custom color scheme hooks from theme providers instead of
+     * React Native's built-in useColorScheme.
+     *
+     * @example
+     * // Use custom hook from theme provider
+     * {
+     *   importFrom: '@/hooks/useColorScheme',
+     *   importName: 'useColorScheme'
+     * }
+     *
+     * @example
+     * // Use React Navigation theme
+     * {
+     *   importFrom: '@react-navigation/native',
+     *   importName: 'useTheme'  // You'd wrap this to return ColorSchemeName
+     * }
+     *
+     * @default { importFrom: 'react-native', importName: 'useColorScheme' }
+     */
+    colorScheme?: {
+        /**
+         * Module to import the color scheme hook from
+         * @default 'react-native'
+         */
+        importFrom?: string;
+        /**
+         * Name of the hook to import
+         * @default 'useColorScheme'
+         */
+        importName?: string;
+    };
 };
 type PluginState = PluginPass & {
     styleRegistry: Map<string, StyleObject>;
@@ -51,6 +85,9 @@ type PluginState = PluginPass & {
     hasColorSchemeImport: boolean;
     needsColorSchemeImport: boolean;
     colorSchemeVariableName: string;
+    colorSchemeImportSource: string;
+    colorSchemeHookName: string;
+    colorSchemeLocalIdentifier?: string;
     customTheme: CustomTheme;
     schemeModifierConfig: SchemeModifierConfig;
     supportedAttributes: Set<string>;

package/dist/babel/plugin.test.ts

@@ -7,7 +7,9 @@ import babelPlugin, { type PluginOptions } from "./plugin.js";
  * Helper to transform code with the Babel plugin
  */
 function transform(code: string, options?: PluginOptions, includeJsx = false) {
-  const presets = includeJsx ? ["@babel/preset-react"] : [];
+  const presets = includeJsx
+    ? ["@babel/preset-react", ["@babel/preset-typescript", { isTSX: true, allExtensions: true }]]
+    : [];
 
   const result = transformSync(code, {
     presets,
@@ -1022,6 +1024,278 @@ describe("Babel plugin - color scheme modifier transformation", () => {
   });
 });
 
+describe("Babel plugin - custom color scheme hook import", () => {
+  it("should use custom import source for color scheme hook", () => {
+    const input = `
+      import React from 'react';
+      import { View } from 'react-native';
+
+      export function Component() {
+        return <View className="dark:bg-gray-900" />;
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@/hooks/useColorScheme",
+          importName: "useColorScheme",
+        },
+      },
+      true,
+    );
+
+    // Should import from custom source
+    expect(output).toContain('from "@/hooks/useColorScheme"');
+    expect(output).not.toContain('useColorScheme } from "react-native"');
+
+    // Should inject hook call
+    expect(output).toContain("_twColorScheme = useColorScheme()");
+
+    // Should have conditional styling
+    expect(output).toMatch(/_twColorScheme\s*===\s*['"]dark['"]/);
+  });
+
+  it("should use custom hook name", () => {
+    const input = `
+      import React from 'react';
+      import { View } from 'react-native';
+
+      export function Component() {
+        return <View className="dark:bg-gray-900" />;
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@react-navigation/native",
+          importName: "useTheme",
+        },
+      },
+      true,
+    );
+
+    // Should import useTheme from React Navigation
+    expect(output).toContain('from "@react-navigation/native"');
+    expect(output).toContain("useTheme");
+
+    // Should call useTheme hook
+    expect(output).toContain("_twColorScheme = useTheme()");
+
+    // Should have conditional styling
+    expect(output).toMatch(/_twColorScheme\s*===\s*['"]dark['"]/);
+  });
+
+  it("should merge custom hook with existing import from same source", () => {
+    const input = `
+      import React from 'react';
+      import { View, Text } from 'react-native';
+      import { useNavigation } from '@react-navigation/native';
+
+      export function Component() {
+        const navigation = useNavigation();
+        return (
+          <View className="dark:bg-gray-900">
+            <Text onPress={() => navigation.navigate('Home')}>Go Home</Text>
+          </View>
+        );
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@react-navigation/native",
+          importName: "useTheme",
+        },
+      },
+      true,
+    );
+
+    // Should merge with existing import (both useNavigation and useTheme in same import)
+    expect(output).toMatch(
+      /import\s+\{\s*useNavigation[^}]*useTheme[^}]*\}\s+from\s+['"]@react-navigation\/native['"]/,
+    );
+    expect(output).toContain("useNavigation()");
+    expect(output).toContain("useTheme()");
+
+    // Should only have one import from that source
+    const importCount = (output.match(/@react-navigation\/native/g) ?? []).length;
+    expect(importCount).toBe(1);
+  });
+
+  it("should not duplicate custom hook if already imported", () => {
+    const input = `
+      import React from 'react';
+      import { View } from 'react-native';
+      import { useColorScheme } from '@/hooks/useColorScheme';
+
+      export function Component() {
+        return <View className="dark:bg-gray-900" />;
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@/hooks/useColorScheme",
+          importName: "useColorScheme",
+        },
+      },
+      true,
+    );
+
+    // Should not add duplicate import
+    const importMatches = output.match(/import.*useColorScheme.*from ['"]@\/hooks\/useColorScheme['"]/g);
+    expect(importMatches).toHaveLength(1);
+
+    // Should still inject hook call
+    expect(output).toContain("_twColorScheme = useColorScheme()");
+  });
+
+  it("should use react-native by default when no custom config provided", () => {
+    const input = `
+      import React from 'react';
+      import { View } from 'react-native';
+
+      export function Component() {
+        return <View className="dark:bg-gray-900" />;
+      }
+    `;
+
+    const output = transform(input, undefined, true);
+
+    // Should use default react-native import (can be single or double quotes)
+    expect(output).toMatch(/useColorScheme\s*}\s*from\s+['"]react-native['"]/);
+    expect(output).not.toContain("@/hooks");
+    expect(output).not.toContain("@react-navigation");
+
+    // Should inject hook call with default name
+    expect(output).toContain("_twColorScheme = useColorScheme()");
+  });
+
+  it("should create separate import when only type-only import exists", () => {
+    const input = `
+      import React from 'react';
+      import { View } from 'react-native';
+      import type { NavigationProp } from '@react-navigation/native';
+
+      export function Component() {
+        return <View className="dark:bg-gray-900" />;
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@react-navigation/native",
+          importName: "useTheme",
+        },
+      },
+      true,
+    );
+
+    // TypeScript preset strips type-only imports, but the important thing is:
+    // 1. useTheme hook is imported (not skipped thinking it was already imported)
+    // 2. Hook is correctly called in the component
+    expect(output).toMatch(/import\s+\{\s*useTheme\s*\}\s+from\s+['"]@react-navigation\/native['"]/);
+    expect(output).toContain("_twColorScheme = useTheme()");
+  });
+
+  it("should use aliased identifier when hook is already imported with alias", () => {
+    const input = `
+      import React from 'react';
+      import { View, Text } from 'react-native';
+      import { useTheme as navTheme } from '@react-navigation/native';
+
+      export function Component() {
+        const theme = navTheme();
+        return (
+          <View className="dark:bg-gray-900">
+            <Text>{theme.dark ? 'Dark' : 'Light'}</Text>
+          </View>
+        );
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@react-navigation/native",
+          importName: "useTheme",
+        },
+      },
+      true,
+    );
+
+    // Should not add duplicate import
+    const importMatches = output.match(
+      /import\s+\{[^}]*useTheme[^}]*\}\s+from\s+['"]@react-navigation\/native['"]/g,
+    );
+    expect(importMatches).toHaveLength(1);
+
+    // Should still have the aliased import
+    expect(output).toMatch(/useTheme\s+as\s+navTheme/);
+
+    // Should call the aliased name (navTheme), not the export name (useTheme)
+    // Both the user's code and our injected hook should use navTheme
+    expect(output).toContain("_twColorScheme = navTheme()");
+    expect(output).not.toContain("_twColorScheme = useTheme()");
+  });
+
+  it("should handle both type-only and aliased imports together", () => {
+    const input = `
+      import React from 'react';
+      import { View, Text } from 'react-native';
+      import type { Theme } from '@react-navigation/native';
+      import { useTheme as getNavTheme } from '@react-navigation/native';
+
+      export function Component() {
+        const theme = getNavTheme();
+        return (
+          <View className="dark:bg-gray-900">
+            <Text>{theme.dark ? 'Dark Mode' : 'Light Mode'}</Text>
+          </View>
+        );
+      }
+    `;
+
+    const output = transform(
+      input,
+      {
+        colorScheme: {
+          importFrom: "@react-navigation/native",
+          importName: "useTheme",
+        },
+      },
+      true,
+    );
+
+    // TypeScript preset strips type-only imports
+    // The important thing is: should not add duplicate import, and should use aliased name
+    expect(output).toMatch(
+      /import\s+\{[^}]*useTheme\s+as\s+getNavTheme[^}]*\}\s+from\s+['"]@react-navigation\/native['"]/,
+    );
+
+    // Should not add duplicate import - useTheme should only appear in the aliased import
+    const useThemeImports = output.match(
+      /import\s+\{[^}]*useTheme[^}]*\}\s+from\s+['"]@react-navigation\/native['"]/g,
+    );
+    expect(useThemeImports).toHaveLength(1);
+
+    // Should call the aliased name for both user code and our injected hook
+    expect(output).toContain("_twColorScheme = getNavTheme()");
+    expect(output).not.toContain("_twColorScheme = useTheme()");
+  });
+});
+
 describe("Babel plugin - import injection", () => {
   it("should not add StyleSheet import to files without className usage", () => {
     const input = `