@maccesar/titools 2.2.11 → 2.3.0

package/skills/purgetss/references/dynamic-component-creation.md

@@ -7,9 +7,8 @@ When creating components dynamically in Controllers (not declaratively in XML),
 1. **`$.UI.create()`** - Create components with PurgeTSS classes (Recommended)
 2. **`Alloy.createStyle()` + `applyProperties()`** - Apply PurgeTSS styles to existing components
 
-:::tip BEST PRACTICE
-**Always prefer `$.UI.create()` for dynamic components** - it's cleaner, more readable, and PurgeTSS will process the classes automatically during build.
-:::
+> **💡 BEST PRACTICE**
+> **Always prefer `$.UI.create()` for dynamic components** - it's cleaner, more readable, and PurgeTSS will process the classes automatically during build.
 
 ---
 
@@ -110,17 +109,17 @@ classes: [
 ```javascript
 function createListItem(text, icon) {
   const container = $.UI.create('View', {
-    classes: ['horizontal', 'm-4', 'p-4', 'bg-white', 'rounded-lg']
+    classes: ['horizontal', 'bg-white', 'rounded-lg']
   })
 
   const iconView = $.UI.create('Label', {
     text: icon,
-    classes: ['text-2xl', 'mr-4']
+    classes: ['m-4', 'text-2xl']
   })
 
   const label = $.UI.create('Label', {
     text: text,
-    classes: ['text-base', 'font-semibold']
+    classes: ['my-4', 'text-base', 'font-semibold']
   })
 
   container.add(iconView)
@@ -212,7 +211,7 @@ Alloy.createStyle('index', {
 
 ```javascript
 // lib/factories/formFactory.js
-exports.createFormField = function fieldType, options) {
+exports.createFormField = function(fieldType, options) {
   const baseClasses = ['w-screen', 'h-12', 'mx-4', 'border-gray-300', 'border-(1)', 'rounded-lg']
 
   switch (fieldType) {
@@ -252,17 +251,17 @@ function createProductCard(product) {
   })
 
   const info = $.UI.create('View', {
-    classes: ['vertical', 'p-4']
+    classes: ['vertical']
   })
 
   const title = $.UI.create('Label', {
     text: product.name,
-    classes: ['text-lg', 'font-bold', 'mb-2']
+    classes: ['mx-4', 'mt-4', 'text-lg', 'font-bold']
   })
 
   const price = $.UI.create('Label', {
     text: `$${product.price}`,
-    classes: ['text-xl', 'text-green-600', 'font-bold']
+    classes: ['mx-4', 'mb-4', 'text-xl', 'text-green-600', 'font-bold']
   })
 
   info.add(title)
@@ -301,22 +300,22 @@ function applyTheme(theme) {
 // controllers/dashboard/grid.js
 function createIconGrid(items) {
   const grid = $.UI.create('View', {
-    classes: ['w-screen', 'grid-cols-4', 'gap-4', 'p-4']
+    classes: ['w-screen', 'grid-cols-4', 'gap-4']
   })
 
   items.forEach(item => {
     const icon = $.UI.create('View', {
-      classes: ['vertical', 'items-center']
+      classes: ['vertical']
     })
 
     const iconView = $.UI.create('Label', {
       text: item.icon,
-      classes: ['text-3xl', 'mb-2', 'text-blue-500']
+      classes: ['mx-auto', 'mt-4', 'text-3xl', 'text-blue-500']
     })
 
     const label = $.UI.create('Label', {
       text: item.label,
-      classes: ['text-xs', 'text-center', 'text-gray-600']
+      classes: ['mx-2', 'mb-4', 'text-xs', 'text-center', 'text-gray-600']
     })
 
     icon.add(iconView)
@@ -334,15 +333,14 @@ function createIconGrid(items) {
 
 ### PurgeTSS Processes Classes During Build
 
-:::info HOW IT WORKS
-When you use `$.UI.create()` or `Alloy.createStyle()` with classes:
-
-1. PurgeTSS scans your controllers for these class references
-2. It adds the classes to the generated `app.tss`
-3. At runtime, Alloy applies the styles to your components
-
-This means you get **full PurgeTSS power** even with dynamic components!
-:::
+> **️ℹ️ HOW IT WORKS**
+> When you use `$.UI.create()` or `Alloy.createStyle()` with classes:
+>
+> 1. PurgeTSS scans your controllers for these class references
+> 2. It adds the classes to the generated `app.tss`
+> 3. At runtime, Alloy applies the styles to your components
+>
+> This means you get **full PurgeTSS power** even with dynamic components!
 
 ### Class Verification
 
@@ -427,11 +425,10 @@ function setState(state) {
 }
 ```
 
-:::tip When to Use `classes` vs `applyProperties`
-- Use `classes` when you want to swap entire style sets (e.g., active/inactive states)
-- Use `applyProperties` with direct values when changing individual properties (e.g., text, enabled)
-- Combine both for complex state changes
-:::
+> **💡 When to Use `classes` vs `applyProperties`**
+> - Use `classes` when you want to swap entire style sets (e.g., active/inactive states)
+> - Use `applyProperties` with direct values when changing individual properties (e.g., text, enabled)
+> - Combine both for complex state changes
 
 ---
 
@@ -497,12 +494,11 @@ view.applyProperties(Alloy.createStyle('index', {
 | **`Alloy.createStyle()`** | Styling existing components | `Alloy.createStyle('view', { classes: 'bg-white' })` |
 | **`applyProperties()`**   | Apply style to component    | `component.applyProperties(style)`                   |
 
-:::tip REMEMBER
-Both methods give you **full access to PurgeTSS utilities**:
-- All color classes (`bg-*`, `text-*`, `border-*`)
-- All spacing classes (`m-*`, `p-*`, `gap-*`)
-- All layout classes (`horizontal`, `vertical`)
-- All typography classes (`text-*`, `font-*`)
-- Platform modifiers (`ios:*`, `android:*`)
-- Arbitrary values (`w-(100px)`, `bg-(#ff0000)`)
-:::
+> **💡 REMEMBER**
+> Both methods give you **full access to PurgeTSS utilities**:
+> - All color classes (`bg-*`, `text-*`, `border-*`)
+> - All spacing classes (`m-*`, `gap-*`, and `p-*` where the Titanium component supports padding)
+> - All layout classes (`horizontal`, `vertical`)
+> - All typography classes (`text-*`, `font-*`)
+> - Platform modifiers (`ios:*`, `android:*`)
+> - Arbitrary values (`w-(100px)`, `bg-(#ff0000)`)

package/skills/purgetss/references/grid-layout.md

@@ -1,20 +1,17 @@
-# Grid Layout System
+# Grid System
 
-The PurgeTSS grid system is a layout tool with utilities to lay out columns and rows using Titanium's layout properties.
+The grid system is a small layout tool that lets you build rows and columns with utility classes.
 
-:::caution Not CSS Grid
-**PurgeTSS grid does NOT work like CSS Grid.** Titanium lacks native CSS Grid support. The PurgeTSS grid system is an abstraction using `horizontal` and `vertical` layouts with percentage widths and margins.
-:::
+> **WARNING**
+> PurgeTSS grid is not CSS Grid. It is a Titanium-oriented layout helper built around horizontal and vertical layout behavior.
 
-## Basic Structure
-
-This is the most basic layout for using the grid system:
+The snippet below shows the simplest layout. From there, you can mix columns and rows as needed.
 
 ```xml
 <Alloy>
-  <View class='grid'>
+  <View class="grid">
     <View class="grid-cols-4">
-      <!-- Remove gap View if you don't need gutters between columns -->
+      <!-- Remove if you don't need a gutter between columns (or rows) -->
       <View class="gap-1">
         <!-- ANY CONTENT GOES HERE -->
       </View>
@@ -31,393 +28,67 @@ This is the most basic layout for using the grid system:
 
 ## Column Grid
 
-### `.grid-cols-{n}`
-
-With `grid-cols`, you tell the grid system how many columns you want to fit in each row:
-
-- `grid-cols-1` - 1 column per row (100% width each)
-- `grid-cols-2` - 2 columns per row (50% width each)
-- `grid-cols-3` - 3 columns per row (33.33% width each)
-- `grid-cols-4` - 4 columns per row (25% width each)
-- And so on...
-
-```xml
-<View class="grid">
-  <View class="grid-cols-2">
-    <!-- Each view is 50% width -->
-  </View>
-  <View class="grid-cols-2">
-    <!-- Each view is 50% width -->
-  </View>
-</View>
-```
-
-### `.col-span-{n}`
+### `grid-cols-{n}`
 
-With `col-span`, you set the number of columns each element will occupy in a **12-column grid**:
+Use `grid-cols` to set how many columns fit in each row. For example, `.grid-cols-2` fits two views per row, `.grid-cols-3` fits three, and so on.
 
-- `col-span-1` - Spans 1 column (8.33% width)
-- `col-span-2` - Spans 2 columns (16.66% width)
-- `col-span-3` - Spans 3 columns (25% width)
-- `col-span-4` - Spans 4 columns (33.33% width)
-- `col-span-6` - Spans 6 columns (50% width)
-- `col-span-12` - Spans 12 columns (100% width)
+### `col-span-{n}`
 
-If you set a view with `.col-span-3`, you can add three more views of equal width to fill the row, or any other combination like 3-6-3, 2-4-6, etc., as long as the sum fills a **12-column grid**.
+Use `col-span` to set how many columns an element occupies in a 12-column grid.
 
-```xml
-<!-- 12-column grid examples -->
-<View class="grid">
-  <!-- 3 + 3 + 3 + 3 = 12 -->
-  <View class="col-span-3">...</View>
-  <View class="col-span-3">...</View>
-  <View class="col-span-3">...</View>
-  <View class="col-span-3">...</View>
-</View>
-
-<View class="grid">
-  <!-- 6 + 6 = 12 -->
-  <View class="col-span-6">...</View>
-  <View class="col-span-6">...</View>
-</View>
-
-<View class="grid">
-  <!-- 4 + 4 + 4 = 12 -->
-  <View class="col-span-4">...</View>
-  <View class="col-span-4">...</View>
-  <View class="col-span-4">...</View>
-</View>
-```
+If a view uses `.col-span-3`, you can add three more views of the same width to fill the row. Other combos like 3-6-3 or 2-4-6 work too, as long as the total is 12.
 
 ## Row Grid
 
-### `.grid-rows-{n}`
-
-With `grid-rows`, you tell the grid system how many rows you want to fit in each column:
-
-- `grid-rows-2` - 2 rows per column
-- `grid-rows-3` - 3 rows per column
-- And so on...
-
-```xml
-<View class="grid-flow-row">
-  <View class="grid-rows-2">
-    <!-- Each view is 50% height -->
-  </View>
-  <View class="grid-rows-2">
-    <!-- Each view is 50% height -->
-  </View>
-</View>
-```
-
-### `.row-span-{n}`
-
-With `row-span`, you set the number of rows each element will occupy in a **12-row grid**:
-
-- `row-span-1` through `row-span-12`
-
-If you set a view with `.row-span-3`, you can add three more views of equal height to fill the column, or any other combination like 3-6-3, 2-4-6, etc., as long as the sum fills a **12-row grid**.
-
-```xml
-<!-- 12-row grid example -->
-<View class="grid-flow-row">
-  <!-- 6 + 6 = 12 -->
-  <View class="row-span-6">...</View>
-  <View class="row-span-6">...</View>
-</View>
-```
-
-## Gutter Utilities
-
-The gap utilities add spacing between grid items.
-
-:::warning Important Note on Gaps
-**`gap-{size}` adds margin to ALL sides** (top, right, bottom, left), not just between elements. This is different from CSS gap and can cause layout issues if not used carefully.
-:::
-
-### Available Gap Utilities
-
-- **`gap-{size}`** - Gap between rows and columns
-- **`gap-x-{size}`** - Gap between columns only
-- **`gap-y-{size}`** - Gap between rows only
-- **`gap-t-{size}`** - Gap on top side
-- **`gap-r-{size}`** - Gap on right side
-- **`gap-b-{size}`** - Gap on bottom side
-- **`gap-l-{size}`** - Gap on left side
-
-```xml
-<View class="grid">
-  <View class="gap-1">
-    <!-- 4px margin on all sides -->
-  </View>
-  <View class="gap-1">
-    <!-- 4px margin on all sides -->
-  </View>
-</View>
-```
-
-## Direction Utilities
-
-Control the flow direction of the grid:
-
-- **`.grid`** or **`.grid-flow-col`** - Sets `layout: 'horizontal'` (columns flow left to right)
-- **`.grid-flow-row`** - Sets `layout: 'vertical'` (rows flow top to bottom)
-
-```xml
-<!-- Horizontal grid (default) -->
-<View class="grid">
-  <View class="col-span-6">...</View>
-  <View class="col-span-6">...</View>
-</View>
-
-<!-- Vertical grid -->
-<View class="grid-flow-row">
-  <View class="row-span-6">...</View>
-  <View class="row-span-6">...</View>
-</View>
-```
-
-## Alignment Utilities
-
-Align items within the grid:
-
-- **`.start`** - Aligns element to the start of a row
-- **`.center`** - Aligns element to the center of a row
-- **`.end`** - Aligns element to the end of a row
-
-```xml
-<View class="grid">
-  <View class="start col-span-4">...</View>
-  <View class="center col-span-4">...</View>
-  <View class="end col-span-4">...</View>
-</View>
-```
-
-## Common Layout Patterns
-
-### Two-Column Layout
-
-```xml
-<View class="grid">
-  <View class="col-span-6 bg-blue-100">
-    <Label text="Left Column" />
-  </View>
-  <View class="col-span-6 bg-green-100">
-    <Label text="Right Column" />
-  </View>
-</View>
-```
-
-### Three-Column Layout
+### `grid-rows-{n}`
 
-```xml
-<View class="grid">
-  <View class="col-span-4 bg-blue-100">
-    <Label text="Column 1" />
-  </View>
-  <View class="col-span-4 bg-green-100">
-    <Label text="Column 2" />
-  </View>
-  <View class="col-span-4 bg-red-100">
-    <Label text="Column 3" />
-  </View>
-</View>
-```
+Use `grid-rows` to set how many rows fit in each column. For example, `.grid-rows-2` fits two views per column, `.grid-rows-3` fits three, and so on.
 
-### Sidebar + Main Content
+### `row-span-{n}`
 
-```xml
-<View class="grid">
-  <View class="col-span-3 bg-gray-100">
-    <Label text="Sidebar" />
-  </View>
-  <View class="col-span-9 bg-white">
-    <Label text="Main Content" />
-  </View>
-</View>
-```
+Use `row-span` to set how many rows an element occupies in a 12-row grid.
 
-### Asymmetric Layout
+If a view uses `.row-span-3`, you can add three more views of the same height to fill the column. Other combos like 3-6-3 or 2-4-6 work too, as long as the total is 12.
 
-```xml
-<View class="grid">
-  <View class="col-span-8 bg-blue-100">
-    <Label text="Wide Column" />
-  </View>
-  <View class="col-span-4 bg-green-100">
-    <Label text="Narrow Column" />
-  </View>
-</View>
-```
+## Available Utilities
 
-## Grid System Pitfalls and Solutions
+These are the available utilities to control the grid.
 
-### Problem: Gap Breaks Percentage Widths
+### Gutter Utilities
 
-```xml
-<!-- ❌ This may overflow -->
-<View class="grid grid-cols-2">
-  <View class="col-span-6 gap-2">
-    <!-- 50% width + 8px margin all sides = overflow -->
-  </View>
-  <View class="col-span-6 gap-2">
-    <!-- Same issue -->
-  </View>
-</View>
-```
+- `gap-{size}`: Change the gap between rows and columns.
+- `gap-x-{size}` and `gap-y-{size}`: Change the gap between rows and columns independently.
+- `gap-{side}-{size}`: Change the gap on a specific side (t=top, r=right, b=bottom, l=left).
 
-**Solution**: Use explicit widths with margins
+### Column Span Utilities
 
-```xml
-<!-- ✅ Better approach -->
-<View class="horizontal w-screen">
-  <View class="w-(48%) mr-2">
-    <!-- Card 1 -->
-  </View>
-  <View class="w-(48%) ml-2">
-    <!-- Card 2 -->
-  </View>
-</View>
-```
+- `col-span-{n}`: Make an element span `n` columns.
 
-### Problem: Grid Without w-screen
+### Row Span Utilities
 
-```xml
-<!-- ❌ Parent doesn't have explicit width -->
-<View>
-  <View class="grid grid-cols-2">
-    <!-- Percentage widths may not work correctly -->
-  </View>
-</View>
-```
+- `row-span-{n}`: Make an element span `n` rows.
 
-**Solution**: Add `w-screen` to parent
+### Direction Utilities
 
-```xml
-<!-- ✅ Parent has explicit width -->
-<View class="w-screen">
-  <View class="grid grid-cols-2">
-    <!-- Percentage widths work correctly -->
-  </View>
-</View>
-```
-
-### Problem: Missing Gap Container
-
-```xml
-<!-- ❌ Gap not applied correctly -->
-<View class="grid">
-  <View class="col-span-6 bg-white">
-    <!-- Content -->
-  </View>
-</View>
-```
-
-**Solution**: Wrap content in gap View
-
-```xml
-<!-- ✅ Correct structure -->
-<View class="grid">
-  <View class="col-span-6">
-    <View class="gap-2 bg-white">
-      <!-- Content -->
-    </View>
-  </View>
-</View>
-```
+- `grid` or `grid-flow-col`: Set the layout property to horizontal.
+- `grid-flow-row`: Set the layout property to vertical.
 
-## When to Use Grid vs. Manual Layout
+### Column Utilities
 
-### Use Grid System When:
-- You need simple column layouts (2, 3, 4 columns)
-- Content is uniform in size
-- You don't need complex gutters
-- Building a dashboard or card grid
+- `grid-cols-{n}`: Create grids with `n` equally sized columns.
 
-### Use Manual Layout When:
-- You need precise control over spacing
-- Using percentage widths with margins
-- Creating adaptive layouts (tablet vs handheld)
-- Dealing with complex responsive behavior
+### Row Utilities
 
-```xml
-<!-- Manual layout for more control -->
-<View class="horizontal mb-4 w-screen">
-  <View class="w-(48%) vertical mr-2 rounded-xl bg-white shadow">
-    <!-- Card content -->
-  </View>
-  <View class="w-(48%) vertical ml-2 rounded-xl bg-white shadow">
-    <!-- Card content -->
-  </View>
-</View>
-```
+- `grid-rows-{n}`: Create grids with `n` equally sized rows.
 
-## Complete Utility Reference
-
-| Utility          | Purpose                  | Example                        |
-| ---------------- | ------------------------ | ------------------------------ |
-| `.grid`          | Horizontal layout        | `<View class="grid">`          |
-| `.grid-flow-col` | Horizontal layout        | `<View class="grid-flow-col">` |
-| `.grid-flow-row` | Vertical layout          | `<View class="grid-flow-row">` |
-| `.grid-cols-{n}` | N columns per row        | `<View class="grid-cols-2">`   |
-| `.grid-rows-{n}` | N rows per column        | `<View class="grid-rows-2">`   |
-| `.col-span-{n}`  | Span N columns (12-grid) | `<View class="col-span-6">`    |
-| `.row-span-{n}`  | Span N rows (12-grid)    | `<View class="row-span-6">`    |
-| `.gap-{size}`    | Gap all sides            | `<View class="gap-4">`         |
-| `.gap-x-{size}`  | Gap horizontal           | `<View class="gap-x-4">`       |
-| `.gap-y-{size}`  | Gap vertical             | `<View class="gap-y-4">`       |
-| `.start`         | Align to start           | `<View class="start">`         |
-| `.center`        | Align to center          | `<View class="center">`        |
-| `.end`           | Align to end             | `<View class="end">`           |
-
-## Real-World Example
+### Row Placement Utilities
 
-```xml
-<Alloy>
-  <Window class="bg-gray-100">
-    <ScrollView class="vertical h-screen w-screen">
+Control horizontal alignment of elements within a row:
 
-      <!-- Header -->
-      <View class="bg-white p-4">
-        <Label class="text-xl font-bold text-gray-800" text="Dashboard" />
-      </View>
+| Class | Effect | Use case |
+| --- | --- | --- |
+| `start` | Align to the start of the row | Left-aligned content |
+| `end` | Align to the end of the row | Right-aligned buttons or labels |
+| `center` | Align to the center of the row | Centered content blocks |
 
-      <!-- Stats Grid -->
-      <View class="m-4 grid">
-        <View class="col-span-6">
-          <View class="gap-2 rounded-lg bg-white p-4">
-            <Label class="text-2xl font-bold text-blue-600" text="1,234" />
-            <Label class="text-sm text-gray-500" text="Total Users" />
-          </View>
-        </View>
-        <View class="col-span-6">
-          <View class="gap-2 rounded-lg bg-white p-4">
-            <Label class="text-2xl font-bold text-green-600" text="$56.7k" />
-            <Label class="text-sm text-gray-500" text="Revenue" />
-          </View>
-        </View>
-      </View>
-
-      <!-- Three Column Section -->
-      <View class="m-4 grid">
-        <View class="col-span-4">
-          <View class="h-32 gap-2 rounded-lg bg-white p-4">
-            <Label class="text-center text-gray-800" text="Card 1" />
-          </View>
-        </View>
-        <View class="col-span-4">
-          <View class="h-32 gap-2 rounded-lg bg-white p-4">
-            <Label class="text-center text-gray-800" text="Card 2" />
-          </View>
-        </View>
-        <View class="col-span-4">
-          <View class="h-32 gap-2 rounded-lg bg-white p-4">
-            <Label class="text-center text-gray-800" text="Card 3" />
-          </View>
-        </View>
-      </View>
-
-    </ScrollView>
-  </Window>
-</Alloy>
-```
+These apply to child views inside a `grid-cols-*` container and control horizontal placement within the grid cell.