@mgcrea/react-native-tailwind 0.10.0 → 0.11.1

package/README.md

@@ -425,7 +425,7 @@ export function RuntimeExample() {
 
 #### Configuration
 
-Configure custom colors and other theme options using `setConfig()`:
+Configure custom colors and font families using `setConfig()`:
 
 ```typescript
 import { setConfig } from '@mgcrea/react-native-tailwind/runtime';
@@ -442,13 +442,17 @@ setConfig({
           dark: '#CC0000',
         },
       },
+      fontFamily: {
+        sans: ['"SF Pro Rounded"'],
+        custom: ['"My Custom Font"'],
+      },
     },
   },
 });
 
-// Now you can use custom colors
+// Now you can use custom theme
 <View style={tw`bg-primary p-4`} />
-<Text style={tw`text-brand-light`}>Custom color</Text>
+<Text style={tw`text-brand-light font-custom`}>Custom styling</Text>
 ```
 
 #### API Reference
@@ -1365,7 +1369,7 @@ This pattern allows you to build component libraries with optimized default styl
 
 **Available shades:** `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`
 
-> **Note:** You can extend the color palette with custom colors via `tailwind.config.*` — see [Custom Colors](#custom-colors)
+> **Note:** You can extend the color palette with custom colors via `tailwind.config.*` — see [Custom Theme Extensions](#custom-theme-extensions)
 
 **Opacity Modifiers:**
 
@@ -1883,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:
@@ -1911,9 +2044,9 @@ Use arbitrary values for custom sizes, spacing, and borders not in the preset sc
 
 > **Note:** CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
 
-### Custom Colors
+### Custom Theme Extensions
 
-Extend the default color palette via `tailwind.config.*` in your project root:
+Extend the default color palette and font families via `tailwind.config.*` in your project root:
 
 ```javascript
 // tailwind.config.mjs
@@ -1929,16 +2062,21 @@ export default {
           dark: "#0c4a6e",
         },
       },
+      fontFamily: {
+        sans: ['"SF Pro Rounded"'],
+        custom: ['"My Custom Font"'],
+      },
     },
   },
 };
 ```
 
-Then use your custom colors:
+Then use your custom theme:
 
 ```tsx
 <View className="bg-primary p-4">
-  <Text className="text-brand">Custom branded text</Text>
+  <Text className="text-brand font-custom">Custom branded text</Text>
+  <Text className="font-sans">SF Pro Rounded text</Text>
   <View className="bg-brand-light rounded-lg" />
 </View>
 ```
@@ -1946,13 +2084,14 @@ Then use your custom colors:
 **How it works:**
 
 - Babel plugin discovers config by traversing up from source files
-- Custom colors merged with defaults at build time (custom takes precedence)
-- Nested objects flattened with dash notation: `brand.light` → `brand-light`
+- Custom theme merged with defaults at build time (custom takes precedence)
+- Nested color objects flattened with dash notation: `brand.light` → `brand-light`
+- Font families use first font in array (React Native doesn't support font stacks)
 - Zero runtime overhead — all loading happens during compilation
 
 **Supported formats:** `.js`, `.mjs`, `.cjs`, `.ts`
 
-> **Tip:** Use `theme.extend.colors` to keep default Tailwind colors. Using `theme.colors` directly will override all defaults.
+> **Tip:** Use `theme.extend.*` to keep defaults. Using `theme.colors` or `theme.fontFamily` directly will override all defaults.
 
 ### Programmatic API
 
@@ -1961,10 +2100,17 @@ Access the parser and constants programmatically:
 ```typescript
 import { parseClassName, COLORS, SPACING_SCALE } from "@mgcrea/react-native-tailwind";
 
-// Parse className strings
-const _twStyles = parseClassName("m-4 p-2 bg-blue-500");
+// Parse className strings (no custom theme)
+const styles = parseClassName("m-4 p-2 bg-blue-500");
 // Returns: { margin: 16, padding: 8, backgroundColor: '#3B82F6' }
 
+// Parse with custom theme
+const customStyles = parseClassName("m-4 bg-primary font-custom", {
+  colors: { primary: "#1d4ed8" },
+  fontFamily: { custom: "My Custom Font" },
+});
+// Returns: { margin: 16, backgroundColor: '#1d4ed8', fontFamily: 'My Custom Font' }
+
 // Access default scales
 const blueColor = COLORS["blue-500"]; // '#3B82F6'
 const spacing = SPACING_SCALE[4]; // 16

package/dist/babel/config-loader.d.ts

@@ -6,8 +6,10 @@ export type TailwindConfig = {
     theme?: {
         extend?: {
             colors?: Record<string, string | Record<string, string>>;
+            fontFamily?: Record<string, string | string[]>;
         };
         colors?: Record<string, string | Record<string, string>>;
+        fontFamily?: Record<string, string | string[]>;
     };
 };
 /**
@@ -19,7 +21,14 @@ export declare function findTailwindConfig(startDir: string): string | null;
  */
 export declare function loadTailwindConfig(configPath: string): TailwindConfig | null;
 /**
- * Extract custom colors from tailwind config
- * Prefers theme.extend.colors over theme.colors to avoid overriding defaults
+ * Custom theme configuration extracted from tailwind.config
  */
-export declare function extractCustomColors(filename: string): Record<string, string>;
+export type CustomTheme = {
+    colors: Record<string, string>;
+    fontFamily: Record<string, string>;
+};
+/**
+ * Extract all custom theme extensions from tailwind config
+ * Prefers theme.extend.* over theme.* to avoid overriding defaults
+ */
+export declare function extractCustomTheme(filename: string): CustomTheme;

package/dist/babel/config-loader.test.ts

@@ -1,6 +1,6 @@
 import * as fs from "fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { extractCustomColors, findTailwindConfig, loadTailwindConfig } from "./config-loader";
+import { extractCustomTheme, findTailwindConfig, loadTailwindConfig } from "./config-loader";
 
 // Mock fs
 vi.mock("fs");
@@ -115,15 +115,15 @@ describe("config-loader", () => {
     });
   });
 
-  describe("extractCustomColors", () => {
-    it("should return empty object when no config found", () => {
+  describe("extractCustomTheme", () => {
+    it("should return empty theme when no config found", () => {
       vi.spyOn(fs, "existsSync").mockReturnValue(false);
 
-      const result = extractCustomColors("/project/src/file.ts");
-      expect(result).toEqual({});
+      const result = extractCustomTheme("/project/src/file.ts");
+      expect(result).toEqual({ colors: {}, fontFamily: {} });
     });
 
-    it("should return empty object when config has no theme", () => {
+    it("should return empty theme when config has no theme", () => {
       const configPath = "/project/tailwind.config.js";
 
       vi.spyOn(fs, "existsSync").mockImplementation((filepath) => filepath === configPath);
@@ -131,22 +131,24 @@ describe("config-loader", () => {
 
       // loadTailwindConfig will be called, but we've already tested it
       // For integration, we'd need to mock the entire flow
-      const result = extractCustomColors("/project/src/file.ts");
+      const result = extractCustomTheme("/project/src/file.ts");
 
       // Without actual config loading, this returns empty
-      expect(result).toEqual({});
+      expect(result).toEqual({ colors: {}, fontFamily: {} });
     });
 
-    it("should extract colors from theme.extend.colors", () => {
+    it("should extract colors and fontFamily from theme.extend", () => {
       // This would require complex mocking of the entire require flow
-      // Testing the logic: theme.extend.colors is preferred
+      // Testing the logic: theme.extend is preferred
       const colors = { brand: { light: "#fff", dark: "#000" } };
+      const fontFamily = { sans: ['"SF Pro"'], custom: ['"Custom Font"'] };
       const theme = {
-        extend: { colors },
+        extend: { colors, fontFamily },
       };
 
-      // If we had the config, we'd flatten the colors
+      // If we had the config, we'd flatten the colors and convert fontFamily
       expect(theme.extend.colors).toEqual(colors);
+      expect(theme.extend.fontFamily).toEqual(fontFamily);
     });
   });
 });

package/dist/babel/config-loader.ts

@@ -13,8 +13,10 @@ export type TailwindConfig = {
   theme?: {
     extend?: {
       colors?: Record<string, string | Record<string, string>>;
+      fontFamily?: Record<string, string | string[]>;
     };
     colors?: Record<string, string | Record<string, string>>;
+    fontFamily?: Record<string, string | string[]>;
   };
 };
 
@@ -82,23 +84,31 @@ export function loadTailwindConfig(configPath: string): TailwindConfig | null {
 }
 
 /**
- * Extract custom colors from tailwind config
- * Prefers theme.extend.colors over theme.colors to avoid overriding defaults
+ * Custom theme configuration extracted from tailwind.config
  */
-export function extractCustomColors(filename: string): Record<string, string> {
+export type CustomTheme = {
+  colors: Record<string, string>;
+  fontFamily: Record<string, string>;
+};
+
+/**
+ * Extract all custom theme extensions from tailwind config
+ * Prefers theme.extend.* over theme.* to avoid overriding defaults
+ */
+export function extractCustomTheme(filename: string): CustomTheme {
   const projectDir = path.dirname(filename);
   const configPath = findTailwindConfig(projectDir);
 
   if (!configPath) {
-    return {};
+    return { colors: {}, fontFamily: {} };
   }
 
   const config = loadTailwindConfig(configPath);
   if (!config?.theme) {
-    return {};
+    return { colors: {}, fontFamily: {} };
   }
 
-  // Warn if using theme.colors instead of theme.extend.colors
+  // Extract colors
   /* v8 ignore next 5 */
   if (config.theme.colors && !config.theme.extend?.colors && process.env.NODE_ENV !== "production") {
     console.warn(
@@ -106,9 +116,31 @@ export function extractCustomColors(filename: string): Record<string, string> {
         "Use theme.extend.colors to add custom colors while keeping defaults.",
     );
   }
-
-  // Prefer theme.extend.colors
   const colors = config.theme.extend?.colors ?? config.theme.colors ?? {};
 
-  return flattenColors(colors);
+  // Extract fontFamily
+  /* v8 ignore next 5 */
+  if (config.theme.fontFamily && !config.theme.extend?.fontFamily && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[react-native-tailwind] Using theme.fontFamily will override all default font families. " +
+        "Use theme.extend.fontFamily to add custom fonts while keeping defaults.",
+    );
+  }
+  const fontFamily = config.theme.extend?.fontFamily ?? config.theme.fontFamily ?? {};
+
+  // Convert fontFamily values to strings (take first value if array)
+  const fontFamilyResult: Record<string, string> = {};
+  for (const [key, value] of Object.entries(fontFamily)) {
+    if (Array.isArray(value)) {
+      // Take first font in the array (React Native doesn't support font stacks)
+      fontFamilyResult[key] = value[0];
+    } else {
+      fontFamilyResult[key] = value;
+    }
+  }
+
+  return {
+    colors: flattenColors(colors),
+    fontFamily: fontFamilyResult,
+  };
 }