@mgcrea/react-native-tailwind 0.9.1 → 0.11.0

package/README.md

@@ -23,6 +23,9 @@
   <a href="https://github.com/mgcrea/react-native-tailwind/actions/workflows/main.yaml">
     <img src="https://img.shields.io/github/actions/workflow/status/mgcrea/react-native-tailwind/main.yaml?style=for-the-badge&branch=main" alt="build status" />
   </a>
+  <a href="https://codecov.io/gh/mgcrea/react-native-tailwind">
+    <img src="https://img.shields.io/codecov/c/github/mgcrea/react-native-tailwind?style=for-the-badge" alt="coverage" />
+  </a>
   <a href="https://depfu.com/github/mgcrea/react-native-tailwind">
     <img src="https://img.shields.io/depfu/dependencies/github/mgcrea/react-native-tailwind?style=for-the-badge" alt="dependencies status" />
   </a>
@@ -46,6 +49,8 @@ Compile-time Tailwind CSS for React Native with zero runtime overhead. Transform
 - 🏃 **Runtime option** — Optional `tw` template tag for fully dynamic styling (~25KB)
 - 🎯 **State modifiers** — `active:`, `hover:`, `focus:`, and `disabled:` modifiers for interactive components
 - 📱 **Platform modifiers** — `ios:`, `android:`, and `web:` modifiers for platform-specific styling
+- 🌓 **Color scheme modifiers** — `dark:` and `light:` modifiers for automatic theme adaptation
+- 🎨 **Scheme modifier** — `scheme:` convenience modifier that expands to both `dark:` and `light:` variants
 - 📜 **Special style props** — Support for `contentContainerClassName`, `columnWrapperClassName`, and more
 - 🎛️ **Custom attributes** — Configure which props to transform with exact matching or glob patterns
 
@@ -78,28 +83,6 @@ module.exports = {
 };
 ```
 
-**Advanced:** You can customize which attributes are transformed and the generated styles identifier:
-
-```javascript
-module.exports = {
-  presets: ["module:@react-native/babel-preset"],
-  plugins: [
-    [
-      "@mgcrea/react-native-tailwind/babel",
-      {
-        // Specify which attributes to transform
-        // Default: ['className', 'contentContainerClassName', 'columnWrapperClassName', 'ListHeaderComponentClassName', 'ListFooterComponentClassName']
-        attributes: ["className", "buttonClassName", "containerClassName"],
-
-        // Custom identifier for the generated StyleSheet constant
-        // Default: '_twStyles'
-        stylesIdentifier: "styles",
-      },
-    ],
-  ],
-};
-```
-
 ### 2. Enable TypeScript Support (TypeScript)
 
 Create a type declaration file in your project to enable `className` prop autocomplete:
@@ -442,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';
@@ -459,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
@@ -722,9 +709,7 @@ import { View, Text } from "react-native";
 export function PlatformCard() {
   return (
     <View className="p-4 ios:p-6 android:p-8 bg-white rounded-lg">
-      <Text className="text-base ios:text-blue-600 android:text-green-600">
-        Platform-specific styles
-      </Text>
+      <Text className="text-base ios:text-blue-600 android:text-green-600">Platform-specific styles</Text>
     </View>
   );
 }
@@ -844,15 +829,16 @@ import { Pressable } from "@mgcrea/react-native-tailwind";
 
 **Supported Platforms:**
 
-| Modifier | Platform       | Description                   |
-| -------- | -------------- | ----------------------------- |
-| `ios:`   | iOS            | Styles specific to iOS        |
-| `android:` | Android      | Styles specific to Android    |
-| `web:`   | React Native Web | Styles for web platform     |
+| Modifier   | Platform         | Description                |
+| ---------- | ---------------- | -------------------------- |
+| `ios:`     | iOS              | Styles specific to iOS     |
+| `android:` | Android          | Styles specific to Android |
+| `web:`     | React Native Web | Styles for web platform    |
 
 **How it works:**
 
 The Babel plugin:
+
 1. Detects platform modifiers during compilation
 2. Parses all platform-specific classes at compile-time
 3. Generates `Platform.select()` expressions with references to pre-compiled styles
@@ -861,6 +847,350 @@ The Babel plugin:
 
 This approach provides the best of both worlds: compile-time optimization for all styles, with minimal runtime platform detection only for the conditional selection logic.
 
+### Color Scheme Modifiers
+
+Apply color scheme-specific styles using `dark:` and `light:` modifiers that automatically react to the device's appearance settings. These work on **all components in functional components** and compile to conditional expressions that use React Native's `useColorScheme()` hook.
+
+**Basic Example:**
+
+```tsx
+import { View, Text } from "react-native";
+
+export function ThemeCard() {
+  return (
+    <View className="bg-white dark:bg-gray-900 p-4 rounded-lg">
+      <Text className="text-gray-900 dark:text-white">Adapts to device theme</Text>
+    </View>
+  );
+}
+```
+
+**Transforms to:**
+
+```tsx
+import { useColorScheme, StyleSheet } from "react-native";
+
+export function ThemeCard() {
+  const _twColorScheme = useColorScheme();
+
+  return (
+    <View
+      style={[
+        _twStyles._bg_white_p_4_rounded_lg,
+        _twColorScheme === "dark" && _twStyles._dark_bg_gray_900,
+      ]}
+    >
+      <Text style={[_twStyles._text_gray_900, _twColorScheme === "dark" && _twStyles._dark_text_white]}>
+        Adapts to device theme
+      </Text>
+    </View>
+  );
+}
+
+// Generated styles:
+const _twStyles = StyleSheet.create({
+  _bg_white_p_4_rounded_lg: {
+    backgroundColor: "#FFFFFF",
+    padding: 16,
+    borderRadius: 8,
+  },
+  _dark_bg_gray_900: { backgroundColor: "#111827" },
+  _text_gray_900: { color: "#111827" },
+  _dark_text_white: { color: "#FFFFFF" },
+});
+```
+
+**Common Use Cases:**
+
+**Dark mode support:**
+
+```tsx
+// Automatically switches between light and dark themes
+<View className="bg-white dark:bg-gray-900">
+  <Text className="text-gray-900 dark:text-white">Theme-aware text</Text>
+</View>
+```
+
+**Both light and dark overrides:**
+
+```tsx
+// Specify both light and dark mode styles explicitly
+<View className="bg-gray-100 light:bg-white dark:bg-gray-900">
+  <Text className="text-gray-600 light:text-gray-900 dark:text-gray-100">Custom light & dark styles</Text>
+</View>
+```
+
+**Mixed color scheme and platform modifiers:**
+
+```tsx
+// Combine color scheme with platform-specific styles
+<View className="p-4 ios:p-6 dark:bg-gray-900 android:rounded-xl">
+  <Text className="text-base dark:text-white ios:text-blue-600">Platform + theme aware</Text>
+</View>
+```
+
+**Theme-aware cards:**
+
+```tsx
+// Card that looks great in both light and dark mode
+<View className="bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 p-4 rounded-lg">
+  <Text className="text-lg font-bold text-gray-900 dark:text-white mb-2">Card Title</Text>
+  <Text className="text-gray-600 dark:text-gray-300">Card description text</Text>
+</View>
+```
+
+**Key Features:**
+
+- ✅ **Reactive** — Automatically updates when user changes system appearance
+- ✅ **Zero runtime parsing** — All styles compiled at build time
+- ✅ **Auto-injected hook** — `useColorScheme()` automatically added to components
+- ✅ **Works with all modifiers** — Combine with platform and state modifiers
+- ✅ **Type-safe** — Full TypeScript autocomplete
+- ✅ **Optimized** — Minimal runtime overhead (just conditional checks)
+
+**Supported Modifiers:**
+
+| Modifier | Color Scheme | Description                    |
+| -------- | ------------ | ------------------------------ |
+| `dark:`  | Dark mode    | Styles when dark mode is active |
+| `light:` | Light mode   | Styles when light mode is active |
+
+**How it works:**
+
+The Babel plugin:
+
+1. Detects color scheme modifiers during compilation
+2. Finds the parent function component
+3. Auto-injects `const _twColorScheme = useColorScheme();` at the top of the component
+4. Parses all color scheme-specific classes at compile-time
+5. Generates conditional expressions: `_twColorScheme === 'dark' && styles._dark_bg_gray_900`
+6. Auto-imports `useColorScheme` from `react-native` when needed
+7. Reuses the same hook variable for multiple elements in the same component
+
+**Requirements:**
+
+- ⚠️ **Functional components only** — Color scheme modifiers require hooks (React Native's `useColorScheme()`)
+  - ✅ Works with function declarations: `function Component() { ... }`
+  - ✅ Works with arrow functions: `const Component = () => { ... }`
+  - ✅ Works with concise arrow functions: `const Component = () => <View className="dark:..." />`
+  - ✅ Works in nested callbacks: Hook injected at component level, not in callbacks
+  - ❌ **Not supported in class components** — Will show a warning
+- ⚠️ **React Native 0.62+** — Requires the `useColorScheme` API
+- ✅ **Dynamic expressions supported** — Works in template literals and conditional expressions:
+
+  ```tsx
+  <View className={`p-4 ${isActive ? "dark:bg-blue-500" : "dark:bg-gray-900"}`} />
+  ```
+
+**Performance:**
+
+- **Compile-time**: All styles parsed and registered during build
+- **Runtime**: One `useColorScheme()` hook call per component + minimal conditional checks
+- **Bundle size**: Only includes styles actually used in your code
+
+#### Scheme Modifier (Convenience)
+
+The `scheme:` modifier is a convenience feature that automatically expands to both `dark:` and `light:` modifiers for color classes. This is useful when you have custom colors with separate dark and light variants.
+
+**Basic Usage:**
+
+```tsx
+import { View, Text } from "react-native";
+
+export function ThemedCard() {
+  return (
+    <View className="scheme:bg-systemGray p-4 rounded-lg">
+      <Text className="scheme:text-systemLabel">Adaptive system colors</Text>
+    </View>
+  );
+}
+```
+
+**Transforms to:**
+
+```tsx
+// Automatically expands to both dark: and light: modifiers
+<View className="dark:bg-systemGray-dark light:bg-systemGray-light p-4 rounded-lg">
+  <Text className="dark:text-systemLabel-dark light:text-systemLabel-light">
+    Adaptive system colors
+  </Text>
+</View>
+```
+
+**Requirements:**
+
+To use the `scheme:` modifier, you must define both color variants in your `tailwind.config.*`:
+
+```javascript
+// tailwind.config.mjs
+export default {
+  theme: {
+    extend: {
+      colors: {
+        // Option 1: Nested structure
+        systemGray: {
+          light: "#8e8e93",
+          dark: "#8e8e93",
+        },
+        systemLabel: {
+          light: "#000000",
+          dark: "#ffffff",
+        },
+
+        // Option 2: Flat structure with suffixes
+        "primary-light": "#bfdbfe",
+        "primary-dark": "#1e40af",
+      },
+    },
+  },
+};
+```
+
+**Configuring Suffixes:**
+
+By default, the plugin looks for `-dark` and `-light` suffixes. You can customize these in your Babel configuration:
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        schemeModifier: {
+          darkSuffix: "-dark",   // default
+          lightSuffix: "-light", // default
+        },
+      },
+    ],
+  ],
+};
+```
+
+**Custom Suffixes Example:**
+
+```javascript
+// babel.config.js with custom suffixes
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        schemeModifier: {
+          darkSuffix: "Dark",
+          lightSuffix: "Light",
+        },
+      },
+    ],
+  ],
+};
+
+// tailwind.config.mjs
+export default {
+  theme: {
+    extend: {
+      colors: {
+        systemGrayDark: "#8e8e93",
+        systemGrayLight: "#8e8e93",
+      },
+    },
+  },
+};
+
+// Usage (same as before)
+<View className="scheme:bg-systemGray" />
+```
+
+**Validation:**
+
+The plugin validates that both color variants exist at compile time:
+
+```tsx
+// ✅ Works - both variants exist
+<View className="scheme:bg-systemGray" />
+// Expands to: dark:bg-systemGray-dark light:bg-systemGray-light
+
+// ⚠️ Warning (development only) - missing light variant
+<View className="scheme:bg-incomplete" />
+// Only has: incomplete-dark
+// Warning: "Missing: incomplete-light. This modifier will be ignored."
+
+// ⚠️ Warning - non-color class
+<View className="scheme:p-4" />
+// Warning: "scheme: modifier only supports color classes (text-*, bg-*, border-*)"
+```
+
+**Supported Color Classes:**
+
+The `scheme:` modifier only works with color utilities:
+
+- ✅ `scheme:text-{color}` — Text colors
+- ✅ `scheme:bg-{color}` — Background colors
+- ✅ `scheme:border-{color}` — Border colors
+- ❌ Other utilities — Ignored with development warning
+
+**Use Cases:**
+
+**Semantic color names:**
+
+```tsx
+// Define semantic system colors that adapt to appearance
+<View className="scheme:bg-systemBackground p-4">
+  <Text className="scheme:text-systemLabel">System-native appearance</Text>
+  <View className="scheme:border-systemSeparator border-t mt-2 pt-2">
+    <Text className="scheme:text-systemSecondaryLabel">Secondary text</Text>
+  </View>
+</View>
+```
+
+**Brand colors with theme variants:**
+
+```tsx
+// Brand colors that look good in both themes
+<View className="scheme:bg-brand p-6 rounded-xl">
+  <Text className="scheme:text-brandContrast text-xl font-bold">
+    Branded Card
+  </Text>
+  <Text className="scheme:text-brandSubtle mt-2">
+    Automatically adapts to user's theme preference
+  </Text>
+</View>
+```
+
+**Mixed with other modifiers:**
+
+```tsx
+import { Pressable } from "@mgcrea/react-native-tailwind";
+
+// Combine with state and platform modifiers
+<Pressable className="scheme:bg-interactive active:opacity-80 ios:p-6 android:p-4 rounded-lg">
+  <Text className="scheme:text-interactiveText font-semibold">
+    Press Me
+  </Text>
+</Pressable>
+```
+
+**Key Features:**
+
+- ✅ **DRY principle** — Define color pairs once, use everywhere with `scheme:`
+- ✅ **Compile-time expansion** — Expands to `dark:` and `light:` during build
+- ✅ **Type-safe** — Full TypeScript autocomplete
+- ✅ **Validates at compile-time** — Ensures both variants exist
+- ✅ **Zero runtime overhead** — Same performance as writing `dark:` and `light:` manually
+- ✅ **Configurable suffixes** — Adapt to your naming convention
+
+**How it works:**
+
+The Babel plugin:
+
+1. Detects `scheme:` modifiers during compilation
+2. Validates that the class is a color utility (`text-*`, `bg-*`, `border-*`)
+3. Checks that both color variants exist in your custom colors (e.g., `systemGray-dark` and `systemGray-light`)
+4. Expands to both `dark:` and `light:` modifiers before further processing
+5. Processes the expanded modifiers using the standard color scheme logic (injects `useColorScheme()` hook)
+
+This means `scheme:bg-systemGray` is functionally identical to writing `dark:bg-systemGray-dark light:bg-systemGray-light`, but more concise and maintainable.
+
 ### ScrollView Content Container
 
 Use `contentContainerClassName` to style the ScrollView's content container:
@@ -1039,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:**
 
@@ -1585,9 +1915,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
@@ -1603,16 +1933,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>
 ```
@@ -1620,13 +1955,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
 
@@ -1635,10 +1971,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;