@mgcrea/react-native-tailwind 0.6.0 → 0.7.0

package/README.md

@@ -1,13 +1,32 @@
-# React Native Tailwind
-
-<div align="center">
-
-[![npm version](https://img.shields.io/npm/v/@mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://www.npmjs.com/package/@mgcrea/react-native-tailwind)
-[![npm downloads](https://img.shields.io/npm/dt/@mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://www.npmjs.com/package/@mgcrea/react-native-tailwind)
-[![license](https://img.shields.io/github/license/mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://github.com/mgcrea/react-native-tailwind/blob/main/LICENSE)
-[![build status](https://img.shields.io/github/actions/workflow/status/mgcrea/react-native-tailwind/main.yaml?style=for-the-badge&branch=master)](https://github.com/mgcrea/react-native-tailwind/actions/workflows/main.yaml)
-
-</div>
+<!-- # React Native Tailwind -->
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <a href="https://mgcrea.github.io/react-native-swiftui">
+    <img src="./.github/assets/logo.png" alt="logo" width="480" height="300"/>
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mgcrea/react-native-tailwind">
+    <img src="https://img.shields.io/npm/v/@mgcrea/react-native-tailwind.svg?style=for-the-badge" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@mgcrea/react-native-tailwind">
+    <img src="https://img.shields.io/npm/dt/@mgcrea/react-native-tailwind.svg?style=for-the-badge" alt="npm total downloads" />
+  </a>
+  <a href="https://www.npmjs.com/package/@mgcrea/react-native-tailwind">
+    <img src="https://img.shields.io/npm/dm/@mgcrea/react-native-tailwind.svg?style=for-the-badge" alt="npm monthly downloads" />
+  </a>
+  <a href="https://www.npmjs.com/package/@mgcrea/react-native-tailwind">
+    <img src="https://img.shields.io/npm/l/@mgcrea/react-native-tailwind.svg?style=for-the-badge" alt="npm license" />
+  </a>
+  <br />
+  <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://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>
+</p>
 
 ## Overview
 
@@ -24,8 +43,14 @@ Compile-time Tailwind CSS for React Native with zero runtime overhead. Transform
 - 🎨 **Custom colors** — Extend the default palette via `tailwind.config.*`
 - 📐 **Arbitrary values** — Use custom sizes and borders: `w-[123px]`, `rounded-[20px]`
 - 🔀 **Dynamic className** — Conditional styles with hybrid compile-time optimization
+- 🏃 **Runtime option** — Optional `tw` template tag for fully dynamic styling (~25KB)
 - 🎯 **State modifiers** — `active:`, `hover:`, `focus:`, and `disabled:` modifiers for interactive components
 - 📜 **Special style props** — Support for `contentContainerClassName`, `columnWrapperClassName`, and more
+- 🎛️ **Custom attributes** — Configure which props to transform with exact matching or glob patterns
+
+## Demo
+
+![demo](./.github/assets/demo.gif)
 
 ## Installation
 
@@ -52,6 +77,28 @@ 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:
@@ -278,6 +325,219 @@ The Babel plugin will merge them:
 </View>
 ```
 
+### Compile-Time `tw` Template Tag
+
+For static or compile-time determinable styles, you can use the `tw` template tag that gets transformed by the Babel plugin. This provides **zero runtime overhead** as all styles are compiled to `StyleSheet.create` calls.
+
+#### Import
+
+```typescript
+import { tw } from "@mgcrea/react-native-tailwind";
+```
+
+#### Basic Usage
+
+```tsx
+import { View, Text, Pressable } from "react-native";
+import { tw } from "@mgcrea/react-native-tailwind";
+
+// Static styles - transformed at compile time
+const containerStyles = tw`flex-1 p-4 bg-gray-100`;
+const buttonStyles = tw`p-4 rounded-lg bg-blue-500`;
+const textStyles = tw`text-white font-bold text-center`;
+
+export function Example() {
+  return (
+    <View style={containerStyles.style}>
+      <Pressable style={buttonStyles.style}>
+        <Text style={textStyles.style}>Click me</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+#### With State Modifiers
+
+The compile-time `tw` supports state modifiers (`active:`, `focus:`, `disabled:`) that return a `TwStyle` object with separate style properties:
+
+```tsx
+import { Pressable, Text } from "react-native";
+import { tw } from "@mgcrea/react-native-tailwind";
+
+const buttonStyles = tw`bg-blue-500 active:bg-blue-700 disabled:bg-gray-300`;
+
+export function Button({ disabled }) {
+  return (
+    <Pressable
+      disabled={disabled}
+      style={(state) => [
+        buttonStyles.style,
+        state.pressed && buttonStyles.activeStyle,
+        disabled && buttonStyles.disabledStyle,
+      ]}
+    >
+      <Text style={tw`text-white font-bold`.style}>Press me</Text>
+    </Pressable>
+  );
+}
+```
+
+#### Transformation Example
+
+The Babel plugin transforms your code at compile time:
+
+```tsx
+// Input
+const styles = tw`bg-blue-500 active:bg-blue-700 m-4`;
+
+// Compiled Output
+const styles = {
+  style: _twStyles._bg_blue_500_m_4,
+  activeStyle: _twStyles._active_bg_blue_700,
+};
+
+const _twStyles = StyleSheet.create({
+  _bg_blue_500_m_4: { backgroundColor: "#2b7fff", margin: 16 },
+  _active_bg_blue_700: { backgroundColor: "#1854d6" },
+});
+```
+
+### Runtime `tw` Template Tag
+
+For cases where you need **fully dynamic styling** (values only known at runtime), you can use the runtime `tw` template tag function. This provides runtime parsing of Tailwind classes with memoization for performance.
+
+> **Note:** Use the compile-time `tw` (imported from `@mgcrea/react-native-tailwind`) when possible for zero runtime overhead. Only use the runtime version (imported from `@mgcrea/react-native-tailwind/runtime`) when styles must be determined at runtime.
+
+#### Installation
+
+The runtime module is already included in the package. Import it separately:
+
+```typescript
+import { tw, setConfig } from "@mgcrea/react-native-tailwind/runtime";
+```
+
+#### Basic Usage
+
+```tsx
+import { View, Text, Pressable } from "react-native";
+import { tw } from "@mgcrea/react-native-tailwind/runtime";
+
+export function RuntimeExample() {
+  const [isActive, setIsActive] = useState(false);
+
+  return (
+    <View style={tw`flex-1 p-4 bg-gray-100`}>
+      <Pressable
+        onPress={() => setIsActive(!isActive)}
+        style={tw`p-4 rounded-lg ${isActive ? "bg-green-500" : "bg-red-500"}`}
+      >
+        <Text style={tw`text-white font-bold text-center`}>{isActive ? "Active" : "Inactive"}</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+#### Configuration
+
+Configure custom colors and other theme options using `setConfig()`:
+
+```typescript
+import { setConfig } from '@mgcrea/react-native-tailwind/runtime';
+
+// Match your tailwind.config structure
+setConfig({
+  theme: {
+    extend: {
+      colors: {
+        primary: '#007AFF',
+        secondary: '#5856D6',
+        brand: {
+          light: '#FF6B6B',
+          dark: '#CC0000',
+        },
+      },
+    },
+  },
+});
+
+// Now you can use custom colors
+<View style={tw`bg-primary p-4`} />
+<Text style={tw`text-brand-light`}>Custom color</Text>
+```
+
+#### API Reference
+
+**`tw` tagged template**
+
+```typescript
+function tw(strings: TemplateStringsArray, ...values: unknown[]): TwStyle;
+
+type TwStyle = {
+  style: ViewStyle | TextStyle | ImageStyle;
+  activeStyle?: ViewStyle | TextStyle | ImageStyle;
+  focusStyle?: ViewStyle | TextStyle | ImageStyle;
+  disabledStyle?: ViewStyle | TextStyle | ImageStyle;
+};
+```
+
+Parses Tailwind classes at runtime and returns a `TwStyle` object with separate properties for base styles and state modifiers. Results are automatically memoized for performance.
+
+**`twStyle(className: string)`**
+
+```typescript
+function twStyle(className: string): TwStyle | undefined;
+```
+
+String version for cases where template literals aren't needed. Returns `undefined` for empty strings.
+
+**`setConfig(config: RuntimeConfig)`**
+
+```typescript
+function setConfig(config: RuntimeConfig): void;
+```
+
+Configure runtime theme settings (colors, etc.). Matches `tailwind.config.mjs` structure.
+
+**`clearCache()`**
+
+```typescript
+function clearCache(): void;
+```
+
+Clears the internal memoization cache. Useful for testing.
+
+**`getCacheStats()`**
+
+```typescript
+function getCacheStats(): { size: number; keys: string[] };
+```
+
+Returns cache statistics for debugging/monitoring.
+
+#### Performance Considerations
+
+- **Bundle Size**: The runtime module adds ~25KB minified (~15-20KB gzipped) to your bundle
+- **Caching**: All parsed styles are automatically memoized, so repeated className strings have minimal overhead
+- **When to Use**:
+  - ✅ Truly dynamic values that can't be determined at compile-time
+  - ✅ Prototyping and rapid development
+  - ❌ Static styles (use compile-time `className` instead for zero overhead)
+  - ❌ Performance-critical hot paths (compile-time is faster)
+
+#### Runtime vs Compile-Time
+
+| Feature        | Compile-Time (`className`)      | Runtime (`tw` tag)      |
+| -------------- | ------------------------------- | ----------------------- |
+| Bundle Size    | Only used styles (~4KB typical) | Full parser (~25KB)     |
+| Performance    | Zero overhead (pre-compiled)    | Fast (memoized parsing) |
+| Dynamic Values | Conditional only                | Fully dynamic           |
+| Custom Colors  | Via `tailwind.config.*`         | Via `setConfig()`       |
+| Type Safety    | Full TypeScript support         | Full TypeScript support |
+
+**Recommendation**: Use compile-time `className` by default for best performance. Use runtime `tw` only when you need fully dynamic styling that can't be expressed with conditional logic.
+
 ### State Modifiers
 
 Apply styles based on component state with zero runtime overhead. The Babel plugin automatically generates optimized style functions.
@@ -977,6 +1237,173 @@ This limitation exists because the current parser architecture uses `Object.assi
 
 ## Advanced
 
+### Custom Attributes
+
+By default, the Babel plugin transforms these className-like attributes to their corresponding style props:
+
+- `className` → `style`
+- `contentContainerClassName` → `contentContainerStyle` (ScrollView, FlatList)
+- `columnWrapperClassName` → `columnWrapperStyle` (FlatList)
+- `ListHeaderComponentClassName` → `ListHeaderComponentStyle` (FlatList)
+- `ListFooterComponentClassName` → `ListFooterComponentStyle` (FlatList)
+
+You can customize which attributes are transformed using the `attributes` plugin option:
+
+**Exact Matches:**
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        attributes: ["className", "buttonClassName", "containerClassName"],
+      },
+    ],
+  ],
+};
+```
+
+**Pattern Matching:**
+
+Use glob patterns to match multiple attributes:
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        // Matches any attribute ending in 'ClassName'
+        attributes: ["*ClassName"],
+      },
+    ],
+  ],
+};
+```
+
+**Combined:**
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        // Mix exact matches and patterns
+        attributes: [
+          "className",
+          "*ClassName", // containerClassName, buttonClassName, etc.
+          "custom*", // customButton, customHeader, etc.
+        ],
+      },
+    ],
+  ],
+};
+```
+
+**Usage Example:**
+
+```tsx
+// With custom attributes configured
+function Button({ title, onPress, buttonClassName, containerClassName }) {
+  return (
+    <View containerClassName="p-2 bg-gray-100">
+      <Pressable buttonClassName="bg-blue-500 px-6 py-4 rounded-lg" onPress={onPress}>
+        <Text className="text-white font-semibold">{title}</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+// Transforms to:
+function Button({ title, onPress, buttonStyle, containerStyle }) {
+  return (
+    <View style={[_twStyles._bg_gray_100_p_2, containerStyle]}>
+      <Pressable style={[_twStyles._bg_blue_500_px_6_py_4_rounded_lg, buttonStyle]} onPress={onPress}>
+        <Text style={_twStyles._font_semibold_text_white}>{title}</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+**Naming Convention:**
+
+Attributes ending in `ClassName` are automatically converted to their `Style` equivalent:
+
+- `buttonClassName` → `buttonStyle`
+- `containerClassName` → `containerStyle`
+- `headerClassName` → `headerStyle`
+
+For attributes not ending in `ClassName`, the `style` prop is used.
+
+**TypeScript Support:**
+
+When using custom attributes, you'll need to augment the component types to include your custom className props. See the [TypeScript section](#2-enable-typescript-support-typescript) for details on module augmentation.
+
+### Custom Styles Identifier
+
+By default, the Babel plugin generates a StyleSheet constant named `_twStyles`. You can customize this identifier to avoid conflicts or match your project's naming conventions:
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      "@mgcrea/react-native-tailwind/babel",
+      {
+        stylesIdentifier: "styles", // or 'tw', 'tailwind', etc.
+      },
+    ],
+  ],
+};
+```
+
+**Default behavior:**
+
+```tsx
+// Input
+<View className="p-4 bg-blue-500" />
+
+// Output
+<View style={_twStyles._bg_blue_500_p_4} />
+
+const _twStyles = StyleSheet.create({
+  _bg_blue_500_p_4: { padding: 16, backgroundColor: '#3B82F6' }
+});
+```
+
+**With custom identifier:**
+
+```tsx
+// Input (with stylesIdentifier: "styles")
+<View className="p-4 bg-blue-500" />
+
+// Output
+<View style={styles._bg_blue_500_p_4} />
+
+const styles = StyleSheet.create({
+  _bg_blue_500_p_4: { padding: 16, backgroundColor: '#3B82F6' }
+});
+```
+
+**Use Cases:**
+
+- **Avoid conflicts:** If you already have a `_twStyles` variable in your code
+- **Consistency:** Match your existing StyleSheet naming convention (`styles`, `styleSheet`, etc.)
+- **Shorter names:** Use a shorter identifier like `tw` or `s` for more compact code
+- **Team conventions:** Align with your team's coding standards
+
+**Important Notes:**
+
+- The identifier must be a valid JavaScript variable name
+- Choose a name that won't conflict with existing variables in your files
+- The same identifier is used across all files in your project
+
 ### Arbitrary Values
 
 Use arbitrary values for custom sizes, spacing, and borders not in the preset scales:

package/dist/babel/config-loader.ts

@@ -7,6 +7,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { flattenColors } from "../utils/flattenColors";
 
 export type TailwindConfig = {
   theme?: {
@@ -79,29 +80,6 @@ export function loadTailwindConfig(configPath: string): TailwindConfig | null {
   }
 }
 
-/**
- * Flatten nested color objects into dot notation
- * Example: { brand: { light: '#fff', dark: '#000' } } -> { 'brand-light': '#fff', 'brand-dark': '#000' }
- */
-function flattenColors(
-  colors: Record<string, string | Record<string, string>>,
-  prefix = "",
-): Record<string, string> {
-  const result: Record<string, string> = {};
-
-  for (const [key, value] of Object.entries(colors)) {
-    const newKey = prefix ? `${prefix}-${key}` : key;
-
-    if (typeof value === "string") {
-      result[newKey] = value;
-    } else if (typeof value === "object" && value !== null) {
-      Object.assign(result, flattenColors(value, newKey));
-    }
-  }
-
-  return result;
-}
-
 /**
  * Extract custom colors from tailwind config
  * Prefers theme.extend.colors over theme.colors to avoid overriding defaults