@mgcrea/react-native-tailwind 0.4.0 → 0.5.0

package/README.md

@@ -15,14 +15,15 @@ Compile-time Tailwind CSS for React Native with zero runtime overhead. Transform
 ## Features
 
 - ⚡ **Zero runtime overhead** — All transformations happen at compile time
-- 🎯 **Babel-only setup** — No Metro configuration required (like Reanimated)
+- 🔧 **No dependencies** — Direct-to-React-Native style generation without tailwindcss package
+- 🎯 **Babel-only setup** — No Metro configuration required
 - 📝 **TypeScript-first** — Full type safety and autocomplete support
-- 🚀 **Optimized performance** — Uses `StyleSheet.create` for optimal React Native performance
+- 🚀 **Optimized performance** — Compiles down to `StyleSheet.create` for optimal 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]`
 - 🔀 **Dynamic className** — Conditional styles with hybrid compile-time optimization
+- 🎯 **State modifiers** — `active:`, `hover:`, `focus:`, and `disabled:` modifiers for interactive components
 - 📜 **Special style props** — Support for `contentContainerClassName`, `columnWrapperClassName`, and more
 
 ## Installation
@@ -134,6 +135,8 @@ const _twStyles = StyleSheet.create({
 
 **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`
 
+**Arbitrary values:** `m-[16px]`, `p-[20]`, `mx-[24px]`, `gap-[12px]` — Custom spacing values (px only)
+
 ### Layout
 
 **Flexbox:**
@@ -164,6 +167,48 @@ const _twStyles = StyleSheet.create({
 
 > **Note:** You can extend the color palette with custom colors via `tailwind.config.*` — see [Custom Colors](#custom-colors)
 
+**Opacity Modifiers:**
+
+Apply transparency to any color using the `/` operator with a percentage value (0-100):
+
+```tsx
+<View className="bg-black/50 p-4">         {/* 50% opacity black background */}
+  <Text className="text-gray-900/80">     {/* 80% opacity gray text */}
+    Semi-transparent content
+  </Text>
+  <View className="border-2 border-red-500/30" /> {/* 30% opacity red border */}
+</View>
+```
+
+- Works with all color types: `bg-*`, `text-*`, `border-*`
+- Supports preset colors: `bg-blue-500/75`, `text-red-600/50`
+- Supports arbitrary colors: `bg-[#ff0000]/40`, `text-[#3B82F6]/90`
+- Supports custom colors: `bg-primary/60`, `text-brand/80`
+- Uses React Native's 8-digit hex format: `#RRGGBBAA`
+
+**Examples:**
+
+```tsx
+// Background opacity
+<View className="bg-white/90" />          // #FFFFFFE6
+<View className="bg-blue-500/50" />       // #3B82F680
+
+// Text opacity
+<Text className="text-black/70" />        // #000000B3
+<Text className="text-gray-900/60" />     // #11182799
+
+// Border opacity
+<View className="border-2 border-purple-500/40" /> // #A855F766
+
+// Arbitrary colors with opacity
+<View className="bg-[#ff6b6b]/25" />      // #FF6B6B40
+
+// Edge cases
+<View className="bg-black/0" />           // Fully transparent
+<View className="bg-blue-500/100" />      // Fully opaque
+<View className="bg-transparent/50" />    // Remains transparent
+```
+
 ### Typography
 
 **Font Size:**
@@ -201,6 +246,152 @@ const _twStyles = StyleSheet.create({
 
 `border-solid`, `border-dotted`, `border-dashed`
 
+### Shadows & Elevation
+
+Apply platform-specific shadows and elevation to create depth and visual hierarchy. Automatically uses iOS shadow properties or Android elevation based on the platform:
+
+**Available shadow sizes:**
+
+- `shadow-sm` — Subtle shadow
+- `shadow` — Default shadow
+- `shadow-md` — Medium shadow
+- `shadow-lg` — Large shadow
+- `shadow-xl` — Extra large shadow
+- `shadow-2xl` — Extra extra large shadow
+- `shadow-none` — Remove shadow
+
+**Platform Differences:**
+
+| Platform | Properties Used | Example Output |
+|----------|----------------|----------------|
+| **iOS** | `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius` | Native iOS shadow rendering |
+| **Android** | `elevation` | Native Android elevation (Material Design) |
+
+**Examples:**
+
+```tsx
+// Card with shadow
+<View className="bg-white rounded-lg shadow-lg p-6 m-4">
+  <Text className="text-xl font-bold">Card Title</Text>
+  <Text className="text-gray-600">Card with large shadow</Text>
+</View>
+
+// Button with subtle shadow
+<Pressable className="bg-blue-500 shadow-sm rounded-lg px-6 py-3">
+  <Text className="text-white">Press Me</Text>
+</Pressable>
+
+// Different shadow sizes
+<View className="shadow-sm p-4">Subtle</View>
+<View className="shadow p-4">Default</View>
+<View className="shadow-md p-4">Medium</View>
+<View className="shadow-lg p-4">Large</View>
+<View className="shadow-xl p-4">Extra Large</View>
+<View className="shadow-2xl p-4">2X Large</View>
+
+// Remove shadow
+<View className="shadow-lg md:shadow-none p-4">
+  Conditional shadow removal
+</View>
+```
+
+**iOS Shadow Values:**
+
+| Class | shadowOpacity | shadowRadius | shadowOffset |
+|-------|---------------|--------------|--------------|
+| `shadow-sm` | 0.05 | 1 | { width: 0, height: 1 } |
+| `shadow` | 0.1 | 2 | { width: 0, height: 1 } |
+| `shadow-md` | 0.15 | 4 | { width: 0, height: 3 } |
+| `shadow-lg` | 0.2 | 8 | { width: 0, height: 6 } |
+| `shadow-xl` | 0.25 | 12 | { width: 0, height: 10 } |
+| `shadow-2xl` | 0.3 | 24 | { width: 0, height: 20 } |
+
+**Android Elevation Values:**
+
+| Class | elevation |
+|-------|-----------|
+| `shadow-sm` | 1 |
+| `shadow` | 2 |
+| `shadow-md` | 4 |
+| `shadow-lg` | 8 |
+| `shadow-xl` | 12 |
+| `shadow-2xl` | 16 |
+
+> **Note:** All shadow parsing happens at compile-time with zero runtime overhead. The platform detection uses React Native's `Platform.select()` API.
+
+### Aspect Ratio
+
+Control the aspect ratio of views using preset or arbitrary values. Requires React Native 0.71+:
+
+**Preset values:**
+
+- `aspect-auto` — Remove aspect ratio constraint
+- `aspect-square` — 1:1 aspect ratio
+- `aspect-video` — 16:9 aspect ratio
+
+**Arbitrary values:**
+
+Use `aspect-[width/height]` for custom ratios:
+
+```tsx
+<View className="aspect-[4/3]" />    // 4:3 ratio (1.333...)
+<View className="aspect-[16/9]" />   // 16:9 ratio (1.778...)
+<View className="aspect-[21/9]" />   // 21:9 ultrawide
+<View className="aspect-[9/16]" />   // 9:16 portrait
+<View className="aspect-[3/2]" />    // 3:2 ratio (1.5)
+```
+
+**Examples:**
+
+```tsx
+// Square image container
+<View className="w-full aspect-square bg-gray-200">
+  <Image source={avatar} className="w-full h-full" />
+</View>
+
+// Video player container (16:9)
+<View className="w-full aspect-video bg-black">
+  <VideoPlayer />
+</View>
+
+// Instagram-style square grid
+<View className="flex-row flex-wrap gap-2">
+  {photos.map((photo) => (
+    <View key={photo.id} className="w-[32%] aspect-square">
+      <Image source={photo.uri} className="w-full h-full rounded" />
+    </View>
+  ))}
+</View>
+
+// Custom aspect ratio for wide images
+<View className="w-full aspect-[21/9] rounded-lg overflow-hidden">
+  <Image source={banner} className="w-full h-full" resizeMode="cover" />
+</View>
+
+// Portrait orientation
+<View className="h-full aspect-[9/16]">
+  <Story />
+</View>
+
+// Remove aspect ratio constraint
+<View className="aspect-square md:aspect-auto">
+  Responsive aspect ratio
+</View>
+```
+
+**Common Aspect Ratios:**
+
+| Ratio | Class | Decimal | Use Case |
+|-------|-------|---------|----------|
+| 1:1 | `aspect-square` | 1.0 | Profile pictures, thumbnails |
+| 16:9 | `aspect-video` | 1.778 | Videos, landscape photos |
+| 4:3 | `aspect-[4/3]` | 1.333 | Standard photos |
+| 3:2 | `aspect-[3/2]` | 1.5 | Classic photography |
+| 21:9 | `aspect-[21/9]` | 2.333 | Ultrawide/cinematic |
+| 9:16 | `aspect-[9/16]` | 0.5625 | Stories, vertical video |
+
+> **Note:** The aspect ratio is calculated as `width / height`. When combined with `w-full`, the height will be automatically calculated to maintain the ratio.
+
 ### Sizing
 
 - `w-{size}`, `h-{size}` — Width/height
@@ -235,14 +426,18 @@ export function MyComponent() {
 ### Card Component
 
 ```tsx
-import { View, Text, Pressable } from "react-native";
+import { View, Text } from "react-native";
+import { Pressable } from "@mgcrea/react-native-tailwind";
 
 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}>
+      <Pressable
+        className="bg-blue-500 active:bg-blue-700 px-4 py-2 rounded-lg items-center"
+        onPress={onPress}
+      >
         <Text className="text-white font-semibold">Learn More</Text>
       </Pressable>
     </View>
@@ -368,6 +563,179 @@ The Babel plugin will merge them:
 </View>
 ```
 
+### State Modifiers
+
+Apply styles based on component state with zero runtime overhead. The Babel plugin automatically generates optimized style functions.
+
+#### Active Modifier (Pressable)
+
+Use the `active:` modifier to apply styles when a `Pressable` component is pressed. **Requires using the enhanced `Pressable` component from this package.**
+
+**Basic Example:**
+
+```tsx
+import { Text } from "react-native";
+import { Pressable } from "@mgcrea/react-native-tailwind";
+
+export function MyButton() {
+  return (
+    <Pressable className="bg-blue-500 active:bg-blue-700 p-4 rounded-lg">
+      <Text className="text-white font-semibold">Press Me</Text>
+    </Pressable>
+  );
+}
+```
+
+**Transforms to:**
+
+```tsx
+<Pressable
+  style={({ pressed }) => [_twStyles._bg_blue_500_p_4_rounded_lg, pressed && _twStyles._active_bg_blue_700]}
+>
+  <Text style={_twStyles._font_semibold_text_white}>Press Me</Text>
+</Pressable>;
+
+// Generated styles:
+const _twStyles = StyleSheet.create({
+  _bg_blue_500_p_4_rounded_lg: { backgroundColor: "#3B82F6", padding: 16, borderRadius: 8 },
+  _active_bg_blue_700: { backgroundColor: "#1D4ED8" },
+  _font_semibold_text_white: { fontWeight: "600", color: "#FFFFFF" },
+});
+```
+
+**Multiple Active Modifiers:**
+
+```tsx
+<Pressable className="bg-green-500 active:bg-green-700 p-4 active:p-6 rounded-lg">
+  <Text className="text-white">Press for darker & larger padding</Text>
+</Pressable>
+```
+
+**Complex Styling:**
+
+```tsx
+<Pressable className="bg-purple-500 active:bg-purple-800 border-2 border-purple-700 active:border-purple-900 p-4 rounded-lg">
+  <Text className="text-white">Background + Border Changes</Text>
+</Pressable>
+```
+
+**Key Features:**
+
+- ✅ **Zero runtime overhead** — All parsing happens at compile-time
+- ✅ **Native Pressable API** — Uses Pressable's `style={({ pressed }) => ...}` pattern
+- ✅ **Type-safe** — Full TypeScript autocomplete for `active:` classes
+- ✅ **Optimized** — Styles deduplicated via `StyleSheet.create`
+- ✅ **Works with custom colors** — `active:bg-primary`, `active:bg-secondary`, etc.
+
+#### Focus Modifier (TextInput)
+
+Use the `focus:` modifier to apply styles when a `TextInput` component is focused. **Requires using the enhanced `TextInput` component from this package.**
+
+**Basic Example:**
+
+```tsx
+import { TextInput } from "@mgcrea/react-native-tailwind";
+
+export function MyInput() {
+  return (
+    <TextInput
+      className="border-2 border-gray-300 focus:border-blue-500 p-3 rounded-lg bg-white"
+      placeholder="Email address"
+    />
+  );
+}
+```
+
+**How it works:**
+
+The package exports an enhanced `TextInput` component that:
+
+1. Manages focus state internally using `onFocus`/`onBlur` callbacks
+2. Passes focus state to the style function: `style={({ focused }) => ...}`
+3. Works seamlessly with the `focus:` modifier in className
+
+**Multiple Focus Modifiers:**
+
+```tsx
+<TextInput className="border-2 border-gray-300 focus:border-green-500 bg-gray-50 focus:bg-white p-3 rounded-lg" />
+```
+
+**Supported Modifiers by Component:**
+
+| Component              | Supported Modifiers                          | Notes                                      |
+| ---------------------- | -------------------------------------------- | ------------------------------------------ |
+| `Pressable` (enhanced) | `active:`, `hover:`, `focus:`, `disabled:`   | Use `@mgcrea/react-native-tailwind` export |
+| `TextInput` (enhanced) | `focus:`, `disabled:`                        | Use `@mgcrea/react-native-tailwind` export |
+
+#### Disabled Modifier (Pressable & TextInput)
+
+Use the `disabled:` modifier to apply styles when a component is disabled. **Requires using the enhanced components from this package.**
+
+**Pressable Example:**
+
+```tsx
+import { Pressable, Text } from "@mgcrea/react-native-tailwind";
+
+export function SubmitButton({ isLoading }) {
+  return (
+    <Pressable
+      disabled={isLoading}
+      className="bg-blue-500 active:bg-blue-700 disabled:bg-gray-400 p-4 rounded-lg"
+    >
+      <Text className="text-white font-semibold">
+        {isLoading ? "Loading..." : "Submit"}
+      </Text>
+    </Pressable>
+  );
+}
+```
+
+**TextInput Example:**
+
+```tsx
+import { TextInput } from "@mgcrea/react-native-tailwind";
+
+export function MyInput({ isEditing }) {
+  return (
+    <TextInput
+      disabled={!isEditing}
+      className="border-2 border-gray-300 focus:border-blue-500 disabled:bg-gray-100 disabled:border-gray-200 p-3 rounded-lg"
+      placeholder="Enter text"
+    />
+  );
+}
+```
+
+**How it works:**
+
+The enhanced components inject the `disabled` prop value into the style function context:
+
+- **Pressable**: Extends the existing `{ pressed, hovered, focused }` state with `disabled`
+- **TextInput**: Provides `{ focused, disabled }` state to style functions
+
+**TextInput `disabled` Prop:**
+
+The enhanced `TextInput` also provides a convenient `disabled` prop that overrides React Native's `editable` prop:
+
+```tsx
+// These are equivalent:
+<TextInput disabled={true} />
+<TextInput editable={false} />
+
+// If both are provided, disabled takes precedence:
+<TextInput disabled={true} editable={true} /> // Component is disabled
+```
+
+**Important Notes:**
+
+- ⚠️ **Enhanced components required** — State modifiers require using the enhanced components from this package
+- ℹ️ **Component-specific** — Each modifier only works on compatible components
+- ℹ️ **No nested modifiers** — Combinations like `active:focus:bg-blue-500` are not currently supported
+- ✅ **Zero styling overhead** — All className parsing happens at compile-time
+- ✅ **Minimal runtime cost** — Only adds state management (focus tracking, disabled injection)
+- ✅ **Type-safe** — Full TypeScript autocomplete for all modifiers
+- ✅ **Works with custom colors** — `focus:border-primary`, `active:bg-secondary`, `disabled:bg-gray-200`, etc.
+
 ### ScrollView Content Container
 
 Use `contentContainerClassName` to style the ScrollView's content container:
@@ -441,6 +809,67 @@ export function ListWithHeaderFooter({ items }) {
 }
 ```
 
+### Building Reusable Components
+
+When building reusable components, use static `className` strings internally. To support `className` props from parent components, you **must** accept the corresponding `style` props (the Babel plugin transforms `className` to `style` before your component receives it):
+
+```tsx
+import { Pressable, Text, View, StyleProp, ViewStyle } from "react-native";
+
+type ButtonProps = {
+  title: string;
+  onPress?: () => void;
+  // REQUIRED: Must accept style props for className to work
+  style?: StyleProp<ViewStyle>;
+  containerStyle?: StyleProp<ViewStyle>;
+  // Optional: Include in type for TypeScript compatibility
+  className?: string; // compile-time only
+  containerClassName?: string; // compile-time only
+};
+
+export function Button({ title, onPress, style, containerStyle }: ButtonProps) {
+  // Use static className strings - these get optimized at compile-time
+  return (
+    <View className="p-2 bg-gray-100 rounded-lg" style={containerStyle}>
+      <Pressable className="bg-blue-500 px-6 py-4 rounded-lg items-center" onPress={onPress} style={style}>
+        <Text className="text-white text-center font-semibold text-base">{title}</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+**Key Points:**
+
+- ✅ Use **static className strings** internally for default styling
+- ✅ **Must accept `style` props** - the Babel plugin transforms `className` → `style` before your component receives it
+- ✅ Include `className` props in the type (for TypeScript compatibility)
+- ✅ **Don't destructure** className props - they're already transformed to `style` and will be `undefined` at runtime
+- ✅ Babel plugin optimizes all static strings to `StyleSheet.create` calls
+
+**Usage:**
+
+```tsx
+// Default styling (uses internal static classNames)
+<Button title="Click Me" onPress={handlePress} />
+
+// Override with runtime styles
+<Button
+  title="Custom"
+  style={{ backgroundColor: '#10B981' }}
+  containerStyle={{ padding: 16 }}
+  onPress={handlePress}
+/>
+
+// className props are accepted but transformed by Babel upstream
+<Button className="bg-red-500 p-8" title="Red Button" />
+// At compile-time, this becomes:
+// <Button style={_twStyles._bg_red_500_p_8} title="Red Button" />
+// At runtime, className is undefined (already transformed to style)
+```
+
+This pattern allows you to build component libraries with optimized default styling while still supporting full customization.
+
 ## Architecture
 
 ### Compile-Time Transformation
@@ -487,24 +916,25 @@ For dynamic styling, use the `style` prop alongside `className`.
 
 ### Arbitrary Values
 
-Use arbitrary values for custom sizes and borders not in the preset scales:
+Use arbitrary values for custom sizes, spacing, and borders not in the preset scales:
 
 ```tsx
-<View className="w-[350px] h-[85%] border-[3px] rounded-[20px]" />
+<View className="w-[350px] h-[85%] m-[16px] p-[24px] 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.
+- **Spacing:** `m-[...]`, `mx-[...]`, `my-[...]`, `mt-[...]`, `p-[...]`, `px-[...]`, `gap-[...]`, etc. (px only)
+- **Sizing:** `w-[...]`, `h-[...]`, `min-w-[...]`, `min-h-[...]`, `max-w-[...]`, `max-h-[...]` (px and %)
+- **Border width:** `border-[...]`, `border-t-[...]`, `border-r-[...]`, `border-b-[...]`, `border-l-[...]` (px only)
+- **Border radius:** `rounded-[...]`, `rounded-t-[...]`, `rounded-tl-[...]`, etc. (px only)
 
 **Formats:**
 
-- Pixels: `[123px]` or `[123]`
-- Percentages: `[50%]`, `[33.333%]`
+- Pixels: `[123px]` or `[123]` — Supported by all utilities
+- Percentages: `[50%]`, `[33.333%]` — Only supported by sizing utilities (`w-*`, `h-*`, etc.)
 
-> **Note:** Only `px` and `%` units are supported. CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
+> **Note:** CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
 
 ### Custom Colors