@maccesar/titools 2.2.11 → 2.3.0

package/skills/purgetss/references/apply-directive.md

@@ -2,22 +2,20 @@
 
 ## Create Complex Classes and IDs
 
-:::info
-Use the `apply` directive to compose multiple classes into reusable components, extract repetitive patterns, or create platform-specific variants.
-:::
-
-The `apply` directive allows you to:
-- Set any ID, class, or Ti Element
-- Use default PurgeTSS classes
-- Use arbitrary values
-- Use newly defined classes in `config.cjs`
-- Set a string or array of classes
-- Combine with platform, device, or conditional properties
+> **INFO**
+> Use `apply` to bundle classes into a new class, or to extract a repeated pattern into a reusable class.
+
+- Set any ID, class, or Ti Element.
+- Use any of the default classes.
+- Use arbitrary values.
+- Use any newly defined class in `config.cjs`.
+- Set a string of classes or an array of classes.
+- Combine it with any platform, device, or conditional-block properties.
 
 ## Set Any ID, Class, or Ti Element
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   extend: {},
   Label: {
@@ -38,9 +36,8 @@ theme: {
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 'Label': { color: '#374151', textColor: '#374151', font: { fontSize: 16, fontWeight: 'bold' } }
 
 /* Custom Classes */
@@ -50,23 +47,22 @@ theme: {
 '.font-bold': { font: { fontWeight: 'bold' } }
 ```
 
-## Use Any of the Default Classes
+## Use Default Classes
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   '.btn': {
     apply: 'font-bold border-2 rounded wh-auto my-0.5 font-saira-condensed'
   },
   '.btn-primary': {
     apply: 'bg-green-500 text-green-100 border-green-200'
-  },
+  }
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.btn': { borderRadius: 4, borderWidth: 2, top: 2, bottom: 2, width: Ti.UI.SIZE, height: Ti.UI.SIZE, font: { fontFamily: 'SairaCondensed-Regular', fontWeight: 'bold' } }
 '.btn-primary': { backgroundColor: '#22c55e', borderColor: '#bbf7d0', color: '#dcfce7', textColor: '#dcfce7' }
@@ -74,10 +70,10 @@ theme: {
 
 ## Use Arbitrary Values
 
-You can use arbitrary values to define your custom classes.
+You can use [Arbitrary Values](./arbitrary-values.md) to define your custom classes.
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   extend: {},
   '.progress': {
@@ -86,19 +82,18 @@ theme: {
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.progress': { backgroundColor: '#e9ecef', borderRadius: 4, height: 16, layout: 'horizontal', font: { fontSize: 12 } }
 ```
 
-## Use Any Newly Defined Class in config.cjs
+## Use Newly Defined Classes in `config.cjs`
 
 In the following example, we are creating `corporate` color classes so we can use them in the `apply` directive with `bg-corporate-500`, `text-corporate-100`, and `border-corporate-200`.
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   extend: {
     colors: {
@@ -112,15 +107,14 @@ theme: {
     apply: 'wh-auto font-bold border-2 rounded my-0.5'
   },
   '.btn-corporate': {
-    // Newly created classes ( see extend.colors.corporate )
+    // Newly created classes (see extend.colors.corporate)
     apply: 'bg-corporate-500 text-corporate-100 border-corporate-200'
   }
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.btn': { borderRadius: 4, borderWidth: 2, top: 2, bottom: 2, width: Ti.UI.SIZE, height: Ti.UI.SIZE, font: { fontWeight: 'bold' } }
 '.btn-corporate': { backgroundColor: '#53606b', borderColor: '#babfc4', color: '#dddfe1', textColor: '#dddfe1' }
@@ -137,13 +131,12 @@ theme: {
 '.border-corporate-100': { borderColor: '#dddfe1' }
 '.border-corporate-200': { borderColor: '#babfc4' }
 '.border-corporate-500': { borderColor: '#53606b' }
-/* And the rest of color properties! */
 ```
 
 ## Set a String of Classes or an Array of Classes
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   extend: {
     colors: {
@@ -167,18 +160,17 @@ theme: {
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.btn': { borderRadius: 4, borderWidth: 2, top: 2, bottom: 2, width: Ti.UI.SIZE, height: Ti.UI.SIZE, font: { fontWeight: 'bold' } }
 '.btn-corporate': { backgroundColor: '#53606b', borderColor: '#babfc4', color: '#dddfe1', textColor: '#dddfe1' }
 ```
 
-## Combine with Any Platform, Device, or Conditional-Block Properties
+## Combine with Platform, Device, or Conditional Blocks
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 theme: {
   '.btn': {
     // Default .btn
@@ -194,17 +186,16 @@ theme: {
       apply: 'h-20'
     },
 
-    // Specific to iPhoneX (if Alloy.Global.iPhoneX is set)
+    // Specific to iPhoneX (if Alloy.Globals.iPhoneX is set)
     '[if=Alloy.Globals.iPhoneX]': {
       apply: 'mb-12'
     }
-  },
+  }
 }
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.btn': { borderRadius: 4, borderWidth: 2, top: 2, bottom: 2, width: Ti.UI.SIZE, height: Ti.UI.SIZE, font: { fontWeight: 'bold' } }
 '.btn[platform=ios]': { right: 16, left: 16, width: Ti.UI.FILL }
@@ -214,144 +205,123 @@ theme: {
 
 ## Platform-Specific Classes
 
-Several classes in `utilities.tss` are platform-specific to prevent polluting objects with properties that are not specific to a particular platform.
-
-:::caution IMPORTANT
-To properly apply these platform styles when creating custom rules, you **must specify the platform variant** in the `apply` directive.
+Several classes in `utilities.tss` are platform-specific (e.g., `clip-enabled`, `status-bar-style-light-content`). These only exist with a `[platform=ios]` or `[platform=android]` suffix.
 
-**Even if you are not targeting a specific platform, you must specify the platform variant.**
-:::
+When you use these classes inside a platform block (`ios:` or `android:`), PurgeTSS automatically finds the platform-specific version -- no prefix needed:
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 module.exports = {
   theme: {
     '.my-view': {
-      // Targeting iOS.
-      'ios': {
-        'apply': 'bg-green-500 wh-32 ios:clip-enabled'
+      ios: {
+        apply: 'bg-green-500 wh-32 clip-enabled'
       }
     }
-  },
+  }
 };
 ```
 
-**Generated TSS:**
-
-```css
+`./purgetss/styles/utilities.tss`
+```tss
 /* Custom Classes */
 '.my-view[platform=ios]': { backgroundColor: '#22c55e', clipMode: Ti.UI.iOS.CLIP_MODE_ENABLED, width: 128, height: 128 }
 ```
 
-### Omitting the Platform Variant
+The `ios:` / `android:` prefix still works from a non-platform block (e.g., `default`), but use it with caution:
 
-If you omit the platform variant, **PurgeTSS** won't be able to determine which platform you are targeting, and the custom class will not have the corresponding property.
+> **WARNING -- Cross-Platform Apps**
+> Using `ios:` or `android:` in a `default` block applies the property on **all platforms**. Some iOS-only or Android-only properties can cause errors on the other platform at compile time or when the view opens. For cross-platform apps, always use platform blocks instead.
 
+`./purgetss/config.cjs`
 ```javascript
-// purgetss/config.cjs
 module.exports = {
   theme: {
-    // Even if you are not targeting a specific platform, you must specify the platform variant
+    // For single-platform apps, the prefix works from default:
     '.my-view': {
-      // Missing platform variant in clip-enabled
-      'apply': 'wh-32 clip-enabled bg-green-500'
+      apply: 'wh-32 bg-green-500 ios:clip-enabled'
+    },
+
+    // For cross-platform apps, use platform blocks instead:
+    '.my-view': {
+      apply: 'wh-32 bg-green-500',
+      ios: {
+        apply: 'clip-enabled'
+      }
     }
-  },
+  }
 };
 ```
 
-**Generated TSS (missing clip-enabled property):**
+### Classes Outside Platform Blocks
+
+If a platform-specific class is used outside a platform block (without the `ios:` or `android:` prefix), PurgeTSS will not find it because it only exists with the platform suffix in `utilities.tss`:
 
-```css
-/* Omitting the platform variant in `config.cjs` will not generate the corresponding property. */
-/* Missing the property related to `clip-enabled`. */
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    '.my-view': {
+      // clip-enabled only exists as '.clip-enabled[platform=ios]' in utilities.tss
+      // Without a platform block or ios: prefix, it will not be found
+      apply: 'wh-32 clip-enabled bg-green-500'
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+/* clip-enabled was not resolved because no platform context was available */
 '.my-view': { backgroundColor: '#22c55e', width: 128, height: 128 }
 ```
 
-## Complete Example with Platform Variants
+> **Titanium Fill Rule**
+> When composing layout utilities inside `apply`, prefer `w-screen` for fill behavior. `w-full` maps to `100%`, not `Ti.UI.FILL`.
+
+## Community-Discovered Patterns
+
+### Global Window defaults for Large Titles + ScrollView (iOS)
+
+When using `largeTitleEnabled` with a ScrollView inside NavigationWindow or TabGroup, three Window properties must work together: `auto-adjust-scroll-view-insets`, `extend-edges-all`, and `large-title-enabled`. Without all three, the ScrollView content overlaps behind the navigation bar — or the large title renders with a visible delay.
 
+Instead of repeating these classes on every Window XML, use `apply` in `config.cjs` to set the base properties as global defaults:
+
+`./purgetss/config.cjs`
 ```javascript
-// config.cjs
 module.exports = {
   theme: {
-    extend: {
-      colors: {
-        corporate: {
-          100: '#dddfe1',
-          200: '#babfc4',
-          500: '#53606b'
-        }
-      }
-    },
-    '.btn': {
-      // Default button
-      apply: 'wh-auto font-bold border-2 rounded my-0.5',
-      // iOS variant
-      ios: {
-        apply: 'w-screen mx-4'
-      },
-      // Handheld variant
-      handheld: {
-        apply: 'h-20'
-      },
-      // Conditional variant
-      '[if=Alloy.Globals.iPhoneX]': {
-        apply: 'mb-12'
-      }
-    },
-    '.btn-corporate': {
-      // Use custom colors
-      apply: [
-        'bg-corporate-500',
-        'text-corporate-100',
-        'border-corporate-200'
-      ],
-      // Platform-specific
+    Window: {
       ios: {
-        apply: 'ios:shadow-offset-0'
+        apply: 'auto-adjust-scroll-view-insets extend-edges-all status-bar-style-light-content'
       }
     }
   }
-}
+};
 ```
 
-**Generated TSS:**
+`./purgetss/styles/utilities.tss`
+```tss
+'Window[platform=ios]': { autoAdjustScrollViewInsets: true, extendEdges: [ Ti.UI.EXTEND_EDGE_ALL ], statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT }
+```
 
-```css
-'.btn': { borderRadius: 4, borderWidth: 2, top: 2, bottom: 2, width: Ti.UI.SIZE, height: Ti.UI.SIZE, font: { fontWeight: 'bold' } }
-'.btn[platform=ios]': { right: 16, left: 16, width: Ti.UI.FILL }
-'.btn[formFactor=handheld]': { height: 80 }
-'.btn[if=Alloy.Globals.iPhoneX]': { bottom: 48 }
+Then in each view XML, only add `largeTitleEnabled` and `largeTitleDisplayMode` as needed:
 
-'.btn-corporate': { backgroundColor: '#53606b', borderColor: '#babfc4', color: '#dddfe1', textColor: '#dddfe1' }
-'.btn-corporate[platform=ios]': { shadowOffset: { x: 0, y: 0 } }
+```xml
+<Window title="Home" class="large-title-enabled">
+  <ScrollView class="vertical w-screen" contentHeight="Ti.UI.SIZE">
+    <!-- Content starts below the nav bar automatically -->
+  </ScrollView>
+</Window>
 ```
 
-## Composing Component Libraries
+This works for both NavigationWindow and TabGroup — on iOS, TabGroup wraps each Tab in an implicit NavigationWindow.
 
-```javascript
-// config.cjs - Building a component library
-theme: {
-  // Base button
-  '.btn': {
-    apply: 'px-4 py-2 rounded font-semibold text-center cursor-pointer'
-  },
-  // Variants
-  '.btn-primary': {
-    apply: 'bg-blue-500 text-white hover:bg-blue-600'
-  },
-  '.btn-secondary': {
-    apply: 'bg-gray-200 text-gray-800 hover:bg-gray-300'
-  },
-  '.btn-danger': {
-    apply: 'bg-red-500 text-white hover:bg-red-600'
-  },
-  // Sizes
-  '.btn-sm': {
-    apply: 'px-2 py-1 text-sm'
-  },
-  '.btn-lg': {
-    apply: 'px-6 py-3 text-lg'
-  }
-}
-```
+| Class | Property | Value |
+|---|---|---|
+| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | `true` |
+| `extend-edges-all` | `extendEdges` | `[ Ti.UI.EXTEND_EDGE_ALL ]` |
+| `large-title-enabled` | `largeTitleEnabled` | `true` |
+| `large-title-display-mode` | `largeTitleDisplayMode` | Uses `LARGE_TITLE_DISPLAY_MODE_*` constants |
+
+> **Why `ios:` block instead of inline `ios:` prefix?** The three classes (`auto-adjust-scroll-view-insets`, `extend-edges-all`, `status-bar-style-light-content`) are platform-specific — they only exist with `[platform=ios]` suffix in `utilities.tss`. Using the `ios:` block in `config.cjs` ensures PurgeTSS resolves them correctly. See "Platform-Specific Classes" above.