@maccesar/titools 2.2.12 → 2.4.0

package/skills/purgetss/references/migration-guide.md

@@ -1,131 +1,76 @@
-# Migrating to PurgeTSS
+# Migration Guide
 
-Guide for migrating existing Titanium Alloy apps from manual TSS styling to PurgeTSS utility-first workflow.
+This guide is based on the PurgeTSS changelog sections in the official `README.md`. It covers the documented upgrade changes for recent versions.
 
-## Assessment Checklist
+## Upgrade to v7.4.0
 
-Before migrating, evaluate styling in the current codebase:
+PurgeTSS v7.4.0 includes a bug fix and documentation improvements.
 
-| Current State                                | Target State                              |
-| -------------------------------------------- | ----------------------------------------- |
-| Manual `.tss` files per controller           | PurgeTSS utility classes in XML           |
-| Inline attributes (`backgroundColor="#fff"`) | PurgeTSS classes (`bg-white`)             |
-| `id`-based styles in `app.tss`               | Class-based utility styling               |
-| Manual 2D Matrix animations                  | PurgeTSS Animation component              |
-| Platform conditionals in controllers         | PurgeTSS platform modifiers (`ios:mt-10`) |
+### Fixed
 
-:::info v7.3 Upgrade Note
-If your project or scripts reference `tailwind.tss`, update them to `utilities.tss` (the file was renamed in v7.3).
-:::
+- `backgroundGradient.colors` serialization now correctly handles arrays of objects in custom rules.
 
-## Step 1: Initialize PurgeTSS
+Before the fix, a config such as:
 
-```bash
-cd your-app
-purgetss init
+```javascript
+colors: [
+  { color: '#132C50', offset: 0 },
+  { color: '#0A1529', offset: 1 }
+]
 ```
 
-This creates the `./purgetss/` folder with `config.cjs` and sets up the auto-run hook.
+could produce broken output in `utilities.tss`.
+
+Now it serializes correctly.
+
+### What to Review
+
+- Re-test any custom classes that define `backgroundGradient.colors` with `{ color, offset }` objects.
+- Rebuild and inspect `utilities.tss` if you previously worked around this bug manually.
+
+## Upgrade to v7.3.x
+
+PurgeTSS v7.3 introduced a file rename and improved error handling.
 
-## Step 2: Backup Existing Styles
+### Breaking Changes
 
-PurgeTSS automatically backs up your existing `app.tss` to `_app.tss`. Your custom styles are preserved and will be merged during compilation.
+- The generated utilities output is now `utilities.tss`.
+  - Generated file: `purgetss/styles/utilities.tss`
+  - Distribution file: `dist/utilities.tss`
 
-## Step 3: Migrate Views Incrementally
+### Major Improvements
 
-Migrate one view at a time. Don't try to convert everything at once.
+- XML syntax validation now catches malformed Alloy XML before processing.
+- `deviceInfo()` now works in both Alloy and Classic Titanium projects.
+- The dependency on `Alloy.isTablet` and `Alloy.isHandheld` was removed.
 
-### Before (Manual TSS)
+### Required Actions
 
-```xml
-<!-- views/index.xml -->
-<View id="header">
-  <Label id="title" text="Welcome" />
-</View>
+1. Update any scripts, docs, or project references that still point to the previous output filename.
+2. Ensure your environment is running Node.js 20 or higher.
+3. If you use Font Awesome 7, verify the project after upgrade so PurgeTSS can handle the new `--fa:` properties.
+
+```bash
+# Current path
+purgetss/styles/utilities.tss
 ```
 
-```tss
-/* styles/index.tss */
-"#header": { backgroundColor: "#fff", height: 60, top: 0 }
-"#title": { color: "#333", font: { fontSize: 18, fontWeight: "bold" } }
+### Recommended Upgrade Command
+
+```bash
+npm install -g purgetss@latest
 ```
 
-### After (PurgeTSS)
+If you run into issues after upgrading:
 
-```xml
-<!-- views/index.xml -->
-<View class="top-0 h-16 bg-white">
-  <Label class="text-lg font-bold text-gray-800" text="Welcome" />
-</View>
+```bash
+npm uninstall -g purgetss
+npm install -g purgetss
 ```
 
-No manual TSS needed — delete the `#header` and `#title` styles.
-
-## Step 4: Remove Manual TSS Files
-
-Once a view is fully migrated to utility classes:
-
-1. Remove corresponding entries from `_app.tss`
-2. Delete any controller-specific `.tss` files (e.g., `styles/login.tss`)
-3. Run `purgetss` to regenerate `app.tss`
-
-## Common Style Translations
-
-| Manual TSS                     | PurgeTSS Class          |
-| ------------------------------ | ----------------------- |
-| `backgroundColor: "#ffffff"`   | `bg-white`              |
-| `backgroundColor: "#f3f4f6"`   | `bg-gray-100`           |
-| `color: "#1f2937"`             | `text-gray-800`         |
-| `font: { fontSize: 18 }`       | `text-lg`               |
-| `font: { fontWeight: "bold" }` | `font-bold`             |
-| `width: Ti.UI.FILL`            | `w-screen`              |
-| `height: Ti.UI.SIZE`           | `h-auto`                |
-| `height: 60`                   | `h-16` (64) or `h-(60)` |
-| `top: 0`                       | `top-0`                 |
-| `left: 16, right: 16`          | `mx-4`                  |
-| `top: 16`                      | `mt-4`                  |
-| `borderRadius: 8`              | `rounded-lg`            |
-| `opacity: 0.5`                 | `opacity-50`            |
-| `layout: "horizontal"`         | `horizontal`            |
-| `layout: "vertical"`           | `vertical`              |
-
-### Platform-Specific Translations
-
-| Manual Code                              | PurgeTSS                         |
-| ---------------------------------------- | -------------------------------- |
-| `if (OS_IOS) { view.top = 40 }`          | `class="ios:mt-10 mt-5"`         |
-| `if (OS_ANDROID) { view.elevation = 4 }` | `class="android:elevation-4"`    |
-| Tablet conditional in controller         | `class="tablet:w-6/12 w-screen"` |
-
-### Animation Translations
-
-| Manual Animation                       | PurgeTSS Animation                                      |
-| -------------------------------------- | ------------------------------------------------------- |
-| `Ti.UI.create2DMatrix()` + `animate()` | `<Animation module="purgetss.ui" class="..." />`        |
-| Manual opacity animation               | `class="close:opacity-0 open:opacity-100 duration-300"` |
-| Manual scale animation                 | `class="close:scale-100 open:scale-95 duration-150"`    |
-
-## Migration Pitfalls
-
-| Pitfall                          | Consequence                       | Prevention                       |
-| -------------------------------- | --------------------------------- | -------------------------------- |
-| Editing `app.tss` directly       | Changes overwritten on next build | Use `_app.tss` for custom styles |
-| Migrating styles without testing | Broken layouts                    | Test each view on both platforms |
-| Using `flex-row`/`justify-*`     | Classes don't exist               | Use `horizontal`/`vertical`      |
-| Using `p-*` on container Views   | No padding on containers          | Use `m-*` on children            |
-| Forgetting `autoStyle: false`    | Style conflicts                   | Set in `config.json`             |
-| Using `w-[100px]` syntax         | Wrong bracket style               | Use `w-(100px)` with parentheses |
-
-## Rollback Strategy
-
-For each view migration:
-
-1. **Create a branch** before starting
-2. **Migrate one view** completely
-3. **Test thoroughly** on both iOS and Android
-4. **Keep legacy styles** in `_app.tss` until stable
-5. **Delete legacy styles** only after confirming utility classes work
-
-:::tip Migration Order
-Start with simple views (static content, few elements) and progress to complex ones (forms, lists). This builds familiarity with PurgeTSS classes before tackling harder views.
-:::
+## Quick Checklist
+
+- Replace every legacy utilities filename reference with `utilities.tss`.
+- Verify Node.js 20+ before upgrading.
+- Rebuild after updating `config.cjs` or custom gradient rules.
+- Re-test any Classic Titanium code that depends on `deviceInfo()`.

package/skills/purgetss/references/opacity-modifier.md

@@ -1,64 +1,31 @@
-# Opacity Modifier
+# The `opacity` Modifier
 
-The opacity modifier allows you to add transparency to **ANY color property** by appending an opacity value between 0 and 100, separated by a slash (`/`).
+> **INFO**
+> Add an opacity modifier to any available color property by appending a value between 0 and 100 after a slash (`/`).
 
-:::info
-You can add an **opacity modifier to ANY of the available color properties** by adding an **opacity value** between 0 and 100 to the end of the color name separated by a slash ( / ).
-:::
-
-## Basic Syntax
-
-```xml
-<Label class="bg-blue-500/50 text-purple-900/75" />
-```
-
-The opacity value (0-100) is converted to a decimal (0.0-1.0) and applied as an 8-digit hex color with alpha channel.
-
-## How It Works
-
-Given `bg-blue-500/50`:
-- `blue-500` = `#3b82f6` (RGB: 59, 130, 246)
-- Opacity 50% = `0x80` (hex) = `128` (decimal)
-- Result: `#803b82f6` (80% of the way to transparent)
-
-## Usage in XML
-
-### Background Colors
+## In Your XML Files
 
 ```xml
-<!-- Semi-transparent backgrounds -->
-<View class="bg-red-500/25" />  <!-- 25% opacity -->
-<View class="bg-green-500/50" /> <!-- 50% opacity -->
-<View class="bg-blue-500/75" />  <!-- 75% opacity -->
+<Label class="w-11/12 h-8 text-center bg-sky-500/50 text-purple-900/75">My Button</Label>
 ```
 
-### Text Colors
-
-```xml
-<Label class="text-gray-900/50" text="Faded text" />
-<Label class="text-brand-600/80" text="Mostly opaque" />
-```
-
-### Border Colors
-
-```xml
-<View class="border-2 border-purple-500/30" />
-```
-
-### All Color Properties
+```tss
+/* Main styles */
+'Window': { backgroundColor: '#ffffff' }
+'.h-8': { height: 32 }
+'.text-center': { textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER }
+'.w-11/12': { width: '91.666667%' }
 
-```xml
-<Window class="bg-indigo-500/20">
-  <View class="border-(#ff0000)/50 shadow-(#000)/30">
-    <Label class="text-white/90 placeholder-gray-400/50" />
-  </View>
-</Window>
+/* Styles with color opacity modifiers */
+'.bg-sky-500/50': { backgroundColor: '#800ea5e9' }
+'.text-purple-900/75': { color: '#bf581c87', textColor: '#bf581c87' }
 ```
 
-## Usage with `@apply` Directive
+## In the `apply` Directive
 
-You can also use color opacity modifiers in the `apply` directive in `config.cjs`:
+You can also use color opacity modifiers in the `apply` directive in the `config.cjs` file.
 
+`./purgetss/config.cjs`
 ```javascript
 module.exports = {
   theme: {
@@ -74,184 +41,20 @@ module.exports = {
       ]
     }
   }
-}
+};
 ```
 
-**Generated classes:**
+`Generated classes`
 ```tss
-/* Custom Styles */
+/* Custom Styles and Resets */
 '.main-banner': { backgroundColor: '#59ce10cc', borderColor: '#bfce10cc' }
 
-/* Color Properties */
+/* backgroundColor Property */
 '.bg-primary': { backgroundColor: '#ce10cc' }
-'.bg-primary/35': { backgroundColor: '#59ce10cc' }
-'.border-primary': { borderColor: '#ce10cc' }
-'.border-primary/75': { borderColor: '#bfce10cc' }
-```
-
-## Complete List of Supported Color Properties
-
-The opacity modifier works with **ALL** color properties:
-
-### Background Properties
-- `bg-*` - backgroundColor
-- `bg-focused-*` - backgroundFocusedColor
-- `bg-selected-*` - backgroundSelectedColor
-- `from-*` - backgroundGradient (start)
-- `to-*` - backgroundGradient (end)
-
-### Text Properties
-- `text-*` - color / textColor
-- `title-*` - titleColor / titleTextColor
-- `subtitle-*` - subtitleColor / subtitleTextColor
-- `placeholder-*` - hintTextColor
-
-### Border Properties
-- `border-*` - borderColor
-- `separator-*` - separatorColor
-- `bar-*` - barColor
-
-### UI Element Properties
-- `badge-*` - badgeColor
-- `disabled-*` - disabledColor
-- `highlighted-*` - highlightedColor
-- `selected-*` - selectedColor
-- `selected-button-*` - selectedButtonColor
-- `selected-subtitle-*` - selectedSubtitleColor
-- `selected-text-*` - selectedTextColor
-
-### Navigation Properties
-- `nav-tint-*` - navTintColor
-- `active-tint-*` - activeTintColor
-- `on-tint-*` - onTintColor
-- `thumb-tint-*` - thumbTintColor
-- `track-tint-*` - trackTintColor
-
-### Indicator Properties
-- `indicator-*` - indicatorColor
-- `current-page-indicator-*` - currentPageIndicatorColor
-- `page-indicator-*` - pageIndicatorColor
-- `paging-control-*` - pagingControlColor
-
-### Tint Properties
-- `tint-*` - tintColor
-- `shadow-*` - shadowColor / viewShadowColor
-- `drop-shadow-*` - dropShadow color
-
-### Miscellaneous Properties
-- `active-title-*` - activeTitleColor
-- `date-time-*` - dateTimeColor
-- `image-touch-feedback-*` - imageTouchFeedbackColor
-- `keyboard-toolbar-*` - keyboardToolbarColor
-- `light-*` - lightColor
-- `navigation-icon-*` - navigationIconColor
-- `pull-bg-*` - pullBackgroundColor
-- `results-bg-*` - resultsBackgroundColor
-- `results-separator-*` - resultsSeparatorColor
-- `tabs-bg-*` - tabsBackgroundColor
-- `tabs-bg-selected-*` - tabsBackgroundSelectedColor
-- `title-attributes-*` - titleAttributes color
-- `title-attributes-shadow-*` - titleAttributes shadow color
-- `touch-feedback-*` - touchFeedbackColor
-
-## Opacity Value Reference
-
-| Opacity Value | Decimal | Hex Alpha | Result            |
-| ------------- | ------- | --------- | ----------------- |
-| `/0`          | 0.00    | `00`      | Fully transparent |
-| `/10`         | 0.10    | `1A`      | 10% visible       |
-| `/20`         | 0.20    | `33`      | 20% visible       |
-| `/25`         | 0.25    | `40`      | 25% visible       |
-| `/30`         | 0.30    | `4D`      | 30% visible       |
-| `/40`         | 0.40    | `66`      | 40% visible       |
-| `/50`         | 0.50    | `80`      | 50% visible       |
-| `/60`         | 0.60    | `99`      | 60% visible       |
-| `/70`         | 0.70    | `B3`      | 70% visible       |
-| `/75`         | 0.75    | `BF`      | 75% visible       |
-| `/80`         | 0.80    | `CC`      | 80% visible       |
-| `/90`         | 0.90    | `E6`      | 90% visible       |
-| `/95`         | 0.95    | `F2`      | 95% visible       |
-| `/100`        | 1.00    | `FF`      | Fully opaque      |
-
-## Common Patterns
-
-### Hover/Active States
-
-```xml
-<Button class="bg-brand-500 active:bg-brand-600/80" />
-```
-
-### Disabled Appearance
-
-```xml
-<Label class="text-gray-800 disabled:text-gray-400/50" />
-```
-
-### Overlay/Backdrop
-
-```xml
-<!-- Semi-transparent overlay -->
-<View class="absolute inset-0 bg-black/50" />
 ```
 
-### Glassmorphism Effect
-
-```xml
-<View class="border-white/30 bg-white/20 backdrop-blur-md" />
-```
-
-### Gradient Fades
-
-```xml
-<View class="from-brand-500/100 to-brand-500/0" />
-```
-
-## Limitations
-
-:::caution Semantic Colors Cannot Use Opacity Modifier
-
-Semantic colors (defined as objects with light/dark values) cannot be modified with the opacity modifier because they are defined as an object with light and dark values, not as a single color value.
-
-**This won't work:**
-```javascript
-// In config.cjs
-colors: {
-  semantic: {
-    light: '#ffffff',
-    dark: '#000000'
-  }
-}
-```
-
-```xml
-<!-- This will NOT work -->
-<View class="bg-semantic/50" />
-```
-
-**Solution:** Use standard color scales instead:
-```javascript
-colors: {
-  semantic: '#888888'
-}
-```
-
-```xml
-<!-- This WILL work -->
-<View class="bg-semantic/50" />
-```
-:::
-
-## Performance Considerations
-
-Using opacity modifiers is as performant as regular color classes since the conversion happens at build time, not runtime. The generated `app.tss` contains the final hex values with alpha channels.
-
-## Combining with Arbitrary Colors
-
-You can combine opacity modifiers with arbitrary color values:
-
-```xml
-<View class="bg-(#4C61E4)/50" />
-<Label class="text-(rgba(255,0,0,0.5))" />
-```
+> **CAUTION -- Semantic Colors**
+> Semantic colors cannot be modified with the opacity modifier because they are defined as an object with light and dark values.
 
-Note: When using `rgba()` directly, the opacity modifier is redundant since `rgba()` already includes alpha.
+> **Gradients**
+> The same modifier logic applies to color-based gradient utilities such as `from-*` and `to-*`. When you define custom `backgroundGradient.colors` arrays of `{ color, offset }` objects in `config.cjs`, PurgeTSS v7.4.0 correctly serializes those nested objects in `utilities.tss`.

package/skills/purgetss/references/performance-tips.md

@@ -141,14 +141,14 @@ setInterval(() => {
 
 ```xml
 <Animation id="slideIn" module="purgetss.ui"
-  class="close:translate-x-full duration-300 open:translate-x-0" />
+  class="close:opacity-0 open:opacity-100 duration-300" />
 ```
 
 ### Hardware-Accelerated Properties
 
 Fast (GPU-accelerated):
 - `opacity` — use for fade effects
-- `transform` (translate, scale, rotate)
+- `transform` (`scale`, `rotate`)
 
 Slow (triggers layout recalculation):
 - `width`, `height`