@mgcrea/react-native-tailwind 0.2.0

package/README.md

@@ -0,0 +1,576 @@
+# 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)
+
+</div>
+
+## Overview
+
+Compile-time Tailwind CSS for React Native with zero runtime overhead. Transform `className` props to optimized `StyleSheet.create` calls at build time using a Babel plugin.
+
+## Features
+
+- ⚡ **Zero runtime overhead** — All transformations happen at compile time
+- 🎯 **Babel-only setup** — No Metro configuration required (like Reanimated)
+- 📝 **TypeScript-first** — Full type safety and autocomplete support
+- 🚀 **Optimized performance** — Uses `StyleSheet.create` for optimal React Native performance
+- 📦 **Small bundle size** — Only includes actual styles used in your app
+- 🔧 **No dependencies** — Direct-to-React-Native style generation without tailwindcss package
+- 🎨 **Custom colors** — Extend the default palette via `tailwind.config.*`
+- 📐 **Arbitrary values** — Use custom sizes and borders: `w-[123px]`, `rounded-[20px]`
+- 📜 **Special style props** — Support for `contentContainerClassName`, `columnWrapperClassName`, and more
+
+## Installation
+
+```bash
+npm install @mgcrea/react-native-tailwind
+# or
+yarn add @mgcrea/react-native-tailwind
+# or
+pnpm add @mgcrea/react-native-tailwind
+```
+
+## Setup
+
+### 1. Add Babel Plugin
+
+Update your `babel.config.js`:
+
+```javascript
+module.exports = {
+  presets: ["module:@react-native/babel-preset"],
+  plugins: [
+    "@mgcrea/react-native-tailwind/babel", // Add this line
+  ],
+};
+```
+
+### 2. Enable TypeScript Support (TypeScript)
+
+Create a type declaration file in your project to enable `className` prop autocomplete:
+
+**Create `src/types/react-native-tailwind.d.ts`:**
+
+```typescript
+import "@mgcrea/react-native-tailwind/react-native";
+```
+
+This file will be automatically picked up by TypeScript and enables autocomplete for the `className` prop on all React Native components.
+
+> **Why is this needed?** TypeScript module augmentation requires the declaration file to be part of your project's compilation context. This one-time setup ensures the `className` prop is recognized throughout your codebase.
+
+### 3. Start Using className
+
+```tsx
+import { View, Text } from "react-native";
+
+export function MyComponent() {
+  return (
+    <View className="flex-1 bg-gray-100 p-4">
+      <Text className="text-xl font-bold text-blue-500">Hello, Tailwind!</Text>
+    </View>
+  );
+}
+```
+
+## How It Works
+
+The Babel plugin transforms your code at compile time:
+
+**Input** (what you write):
+
+```tsx
+<View className="m-4 p-2 bg-blue-500 rounded-lg" />
+<ScrollView contentContainerClassName="items-center gap-4" />
+<FlatList columnWrapperClassName="gap-4" ListHeaderComponentClassName="p-4 bg-gray-100" />
+```
+
+**Output** (what Babel generates):
+
+```tsx
+import { StyleSheet } from "react-native";
+
+<View style={styles._bg_blue_500_m_4_p_2_rounded_lg} />;
+<ScrollView contentContainerStyle={styles._gap_4_items_center} />;
+<FlatList columnWrapperStyle={styles._gap_4} ListHeaderComponentStyle={styles._bg_gray_100_p_4} />;
+
+const styles = StyleSheet.create({
+  _bg_blue_500_m_4_p_2_rounded_lg: {
+    margin: 16,
+    padding: 8,
+    backgroundColor: "#3B82F6",
+    borderRadius: 8,
+  },
+  _gap_4_items_center: {
+    gap: 16,
+    alignItems: "center",
+  },
+  _gap_4: {
+    gap: 16,
+  },
+  _bg_gray_100_p_4: {
+    backgroundColor: "#F3F4F6",
+    padding: 16,
+  },
+});
+```
+
+## API Reference
+
+### Spacing
+
+**Margin & Padding:**
+
+- `m-{size}`, `p-{size}` — All sides
+- `mx-{size}`, `my-{size}`, `px-{size}`, `py-{size}` — Horizontal/vertical
+- `mt-{size}`, `mr-{size}`, `mb-{size}`, `ml-{size}` — Directional margin
+- `pt-{size}`, `pr-{size}`, `pb-{size}`, `pl-{size}` — Directional padding
+- `gap-{size}` — Gap between flex items
+
+**Available sizes:** `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `14`, `16`, `20`, `24`, `28`, `32`, `36`, `40`, `44`, `48`, `52`, `56`, `60`, `64`, `72`, `80`, `96`
+
+### Layout
+
+**Flexbox:**
+
+- `flex`, `flex-1`, `flex-auto`, `flex-none` — Flex sizing
+- `flex-row`, `flex-row-reverse`, `flex-col`, `flex-col-reverse` — Direction
+- `flex-wrap`, `flex-wrap-reverse`, `flex-nowrap` — Wrapping
+- `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch` — Align items
+- `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`, `justify-evenly` — Justify content
+- `self-auto`, `self-start`, `self-end`, `self-center`, `self-stretch`, `self-baseline` — Align self
+- `grow`, `grow-0`, `shrink`, `shrink-0` — Flex grow/shrink
+
+**Other:**
+
+- `absolute`, `relative` — Position
+- `overflow-hidden`, `overflow-visible`, `overflow-scroll` — Overflow
+- `flex`, `hidden` — Display
+
+### Colors
+
+- `bg-{color}-{shade}` — Background color
+- `text-{color}-{shade}` — Text color
+- `border-{color}-{shade}` — Border color
+
+**Available colors:** `gray`, `red`, `blue`, `green`, `yellow`, `purple`, `pink`, `orange`, `indigo`, `white`, `black`, `transparent`
+
+**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)
+
+### Typography
+
+**Font Size:**
+
+`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`, `text-7xl`, `text-8xl`, `text-9xl`
+
+**Font Weight:**
+
+`font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`
+
+**Other:**
+
+- `italic`, `not-italic` — Font style
+- `text-left`, `text-center`, `text-right`, `text-justify` — Text alignment
+- `underline`, `line-through`, `no-underline` — Text decoration
+- `uppercase`, `lowercase`, `capitalize`, `normal-case` — Text transform
+- `leading-none`, `leading-tight`, `leading-snug`, `leading-normal`, `leading-relaxed`, `leading-loose` — Line height
+
+### Borders
+
+**Width:**
+
+- `border`, `border-0`, `border-2`, `border-4`, `border-8` — All sides
+- `border-t`, `border-r`, `border-b`, `border-l` (with variants `-0`, `-2`, `-4`, `-8`) — Directional
+- `border-[8px]`, `border-t-[12px]` — Arbitrary values
+
+**Radius:**
+
+- `rounded-none`, `rounded-sm`, `rounded`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full` — All corners
+- `rounded-t`, `rounded-r`, `rounded-b`, `rounded-l` (with size variants) — Directional
+- `rounded-tl`, `rounded-tr`, `rounded-bl`, `rounded-br` (with size variants) — Individual corners
+- `rounded-[12px]`, `rounded-t-[8px]`, `rounded-tl-[16px]` — Arbitrary values
+
+**Style:**
+
+`border-solid`, `border-dotted`, `border-dashed`
+
+### Sizing
+
+- `w-{size}`, `h-{size}` — Width/height
+- `min-w-{size}`, `min-h-{size}` — Min width/height
+- `max-w-{size}`, `max-h-{size}` — Max width/height
+
+**Available sizes:**
+
+- **Numeric:** `0`-`96` (same as spacing scale)
+- **Fractional:** `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/5`, `2/5`, `3/5`, `4/5`, `1/6`, `2/6`, `3/6`, `4/6`, `5/6`
+- **Special:** `full` (100%), `auto`
+- **Arbitrary:** `w-[123px]`, `h-[50%]`, `min-w-[200px]`, `max-h-[80%]`
+
+> **Note:** Arbitrary sizing supports pixel values (`[123px]` or `[123]`) and percentages (`[50%]`). Other units (`rem`, `em`, `vh`, `vw`) are not supported in React Native.
+
+## Usage Examples
+
+### Basic Example
+
+```tsx
+import { View, Text } from "react-native";
+
+export function MyComponent() {
+  return (
+    <View className="flex-1 bg-gray-100 p-4">
+      <Text className="text-xl font-bold text-blue-500">Hello, Tailwind!</Text>
+    </View>
+  );
+}
+```
+
+### Card Component
+
+```tsx
+import { View, Text, Pressable } from "react-native";
+
+export function Card({ title, description, onPress }) {
+  return (
+    <View className="bg-white rounded-lg p-6 mb-4 border border-gray-200">
+      <Text className="text-xl font-semibold text-gray-900 mb-2">{title}</Text>
+      <Text className="text-base text-gray-600 mb-4">{description}</Text>
+      <Pressable className="bg-blue-500 px-4 py-2 rounded-lg items-center" onPress={onPress}>
+        <Text className="text-white font-semibold">Learn More</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+### Combining with Inline Styles
+
+You can use inline `style` prop alongside `className`:
+
+```tsx
+<View className="flex-1 p-4 bg-blue-500" style={{ paddingTop: safeAreaInsets.top }}>
+  <Text>Content</Text>
+</View>
+```
+
+The Babel plugin will merge them:
+
+```tsx
+<View style={[styles._className_styles, { paddingTop: safeAreaInsets.top }]}>
+  <Text>Content</Text>
+</View>
+```
+
+### ScrollView Content Container
+
+Use `contentContainerClassName` to style the ScrollView's content container:
+
+```tsx
+import { ScrollView, View, Text } from "react-native";
+
+export function MyScrollView() {
+  return (
+    <ScrollView className="flex-1 bg-gray-100" contentContainerClassName="items-center p-4 gap-4">
+      <View className="bg-white rounded-lg p-4">
+        <Text className="text-lg">Item 1</Text>
+      </View>
+      <View className="bg-white rounded-lg p-4">
+        <Text className="text-lg">Item 2</Text>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+### FlatList with Column Wrapper
+
+Use `columnWrapperClassName` for multi-column FlatLists:
+
+```tsx
+import { FlatList, View, Text } from "react-native";
+
+export function GridList({ items }) {
+  return (
+    <FlatList
+      className="flex-1 bg-gray-100"
+      contentContainerClassName="p-4"
+      columnWrapperClassName="gap-4 mb-4"
+      numColumns={2}
+      data={items}
+      renderItem={({ item }) => (
+        <View className="flex-1 bg-white rounded-lg p-4">
+          <Text className="text-lg">{item.name}</Text>
+        </View>
+      )}
+    />
+  );
+}
+```
+
+### FlatList with Header and Footer
+
+Use `ListHeaderComponentClassName` and `ListFooterComponentClassName`:
+
+```tsx
+import { FlatList, View, Text } from "react-native";
+
+export function ListWithHeaderFooter({ items }) {
+  return (
+    <FlatList
+      className="flex-1"
+      contentContainerClassName="p-4"
+      ListHeaderComponentClassName="p-4 bg-blue-500 mb-4 rounded-lg"
+      ListFooterComponentClassName="p-4 bg-gray-200 mt-4 rounded-lg"
+      data={items}
+      ListHeaderComponent={<Text className="text-white font-bold">Header</Text>}
+      ListFooterComponent={<Text className="text-gray-600">End of list</Text>}
+      renderItem={({ item }) => (
+        <View className="bg-white rounded-lg p-4 mb-2">
+          <Text>{item.name}</Text>
+        </View>
+      )}
+    />
+  );
+}
+```
+
+## Architecture
+
+### Compile-Time Transformation
+
+The Babel plugin performs all transformations during build time, ensuring zero runtime overhead:
+
+1. **AST Transformation** — Visits JSX elements and finds `className` attributes
+2. **Static Analysis** — Only processes string literals (dynamic values produce warnings)
+3. **Style Registry** — Collects all className → style mappings per file
+4. **Code Generation** — Injects `StyleSheet.create()` at end of file
+5. **Import Management** — Adds `StyleSheet` import if needed
+
+### Performance Characteristics
+
+| Metric           | Value              |
+| ---------------- | ------------------ |
+| Runtime Overhead | 0ms (compile-time) |
+| Bundle Size      | ~4KB typical       |
+| Build Time       | +50-200ms          |
+
+**Why it's fast:**
+
+- ⚡ All className parsing happens at build time
+- 🎯 Uses React Native's optimized `StyleSheet.create` API
+- 📦 Tree shaking — only includes styles actually used
+- 🔄 Deduplication — identical styles reused across components
+
+## Limitations
+
+**Dynamic class names are not supported** — The Babel plugin can only transform static string literals:
+
+```tsx
+// ❌ This will NOT work
+const spacing = 4;
+<View className={`m-${spacing} p-2`} />
+
+// ✅ Use inline styles for dynamic values
+<View className="p-2" style={{ margin: spacing * 4 }} />
+```
+
+For dynamic styling, use the `style` prop alongside `className`.
+
+## Advanced
+
+### Arbitrary Values
+
+Use arbitrary values for custom sizes and borders not in the preset scales:
+
+```tsx
+<View className="w-[350px] h-[85%] border-[3px] rounded-[20px]" />
+```
+
+**Supported:**
+
+- **Sizing:** `w-[...]`, `h-[...]`, `min-w-[...]`, `min-h-[...]`, `max-w-[...]`, `max-h-[...]`
+- **Border width:** `border-[...]`, `border-t-[...]`, `border-r-[...]`, `border-b-[...]`, `border-l-[...]`
+- **Border radius:** `rounded-[...]`, `rounded-t-[...]`, `rounded-tl-[...]`, etc.
+
+**Formats:**
+
+- Pixels: `[123px]` or `[123]`
+- Percentages: `[50%]`, `[33.333%]`
+
+> **Note:** Only `px` and `%` units are supported. CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
+
+### Custom Colors
+
+Extend the default color palette via `tailwind.config.*` in your project root:
+
+```javascript
+// tailwind.config.mjs
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: "#1d4ed8",
+        secondary: "#9333ea",
+        brand: {
+          light: "#f0f9ff",
+          DEFAULT: "#0284c7",
+          dark: "#0c4a6e",
+        },
+      },
+    },
+  },
+};
+```
+
+Then use your custom colors:
+
+```tsx
+<View className="bg-primary p-4">
+  <Text className="text-brand">Custom branded text</Text>
+  <View className="bg-brand-light rounded-lg" />
+</View>
+```
+
+**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`
+- 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.
+
+### Programmatic API
+
+Access the parser and constants programmatically:
+
+```typescript
+import { parseClassName, COLORS, SPACING_SCALE } from "@mgcrea/react-native-tailwind";
+
+// Parse className strings
+const styles = parseClassName("m-4 p-2 bg-blue-500");
+// Returns: { margin: 16, padding: 8, backgroundColor: '#3B82F6' }
+
+// Access default scales
+const blueColor = COLORS["blue-500"]; // '#3B82F6'
+const spacing = SPACING_SCALE[4]; // 16
+```
+
+## Troubleshooting
+
+### TypeScript `className` Errors
+
+If TypeScript doesn't recognize the `className` prop:
+
+1. Create the type declaration file:
+
+   ```typescript
+   // src/types/react-native-tailwind.d.ts
+   import "@mgcrea/react-native-tailwind/react-native";
+   ```
+
+2. Verify it's covered by your `tsconfig.json` `include` pattern
+3. Restart TypeScript server (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server")
+
+### Babel Plugin Not Working
+
+**Clear Metro cache:**
+
+```bash
+npx react-native start --reset-cache
+```
+
+**Verify `babel.config.js`:**
+
+```javascript
+plugins: ["@mgcrea/react-native-tailwind/babel"];
+```
+
+### Custom Colors Not Recognized
+
+1. **Config location** — Must be in project root or parent directory
+2. **Config format** — Verify proper export:
+
+   ```javascript
+   // CommonJS
+   module.exports = { theme: { extend: { colors: { ... } } } };
+
+   // ESM
+   export default { theme: { extend: { colors: { ... } } } };
+   ```
+
+3. **Clear cache** — Config changes require Metro cache reset
+4. **Use `theme.extend.colors`** — Don't use `theme.colors` directly (overrides defaults)
+
+## Development
+
+### Project Setup
+
+```bash
+git clone https://github.com/mgcrea/react-native-tailwind.git
+cd react-native-tailwind
+pnpm install
+```
+
+### Build
+
+```bash
+pnpm build              # Full build
+pnpm build:babel        # Compile TypeScript
+pnpm build:babel-plugin # Bundle Babel plugin
+pnpm build:types        # Generate type declarations
+```
+
+### Testing
+
+```bash
+pnpm test               # Run all tests
+pnpm lint               # ESLint
+pnpm check              # TypeScript type check
+pnpm spec               # Jest tests
+```
+
+### Example App
+
+```bash
+pnpm dev                # Run example app
+cd example && npm run dev -- --reset-cache
+```
+
+## Authors
+
+- [Olivier Louvignes](https://github.com/mgcrea) - [@mgcrea](https://twitter.com/mgcrea)
+
+## License
+
+```text
+MIT License
+
+Copyright (c) 2025 Olivier Louvignes <olivier@mgcrea.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

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

@@ -0,0 +1,25 @@
+/**
+ * Tailwind config loader for Babel plugin
+ * Discovers and loads tailwind.config.* files from the project
+ */
+export type TailwindConfig = {
+    theme?: {
+        extend?: {
+            colors?: Record<string, string | Record<string, string>>;
+        };
+        colors?: Record<string, string | Record<string, string>>;
+    };
+};
+/**
+ * Find tailwind.config.* file by traversing up from startDir
+ */
+export declare function findTailwindConfig(startDir: string): string | null;
+/**
+ * Load and parse tailwind config file
+ */
+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
+ */
+export declare function extractCustomColors(filename: string): Record<string, string>;