@maccesar/titools 2.0.0

package/skills/purgetss/references/installation-setup.md

@@ -0,0 +1,366 @@
+# PurgeTSS Installation & Setup
+
+PurgeTSS must be installed globally and initialized within each Titanium Alloy project to enable its utility-first workflow.
+
+## Table of Contents
+
+- [PurgeTSS Installation \& Setup](#purgetss-installation--setup)
+  - [Table of Contents](#table-of-contents)
+  - [Prerequisites](#prerequisites)
+  - [Global Installation](#global-installation)
+  - [Initial Project Setup](#initial-project-setup)
+    - [Running PurgeTSS for the First Time](#running-purgetss-for-the-first-time)
+    - [What Happens on First Run](#what-happens-on-first-run)
+      - [1. Auto-Run Hook Setup](#1-auto-run-hook-setup)
+      - [2. purgetss Folder Structure](#2-purgetss-folder-structure)
+      - [3. app.tss Backup](#3-apptss-backup)
+  - [Creating a Fresh config.cjs](#creating-a-fresh-configcjs)
+  - [Visual Studio Code Integration](#visual-studio-code-integration)
+    - [Quick Setup with install-dependencies](#quick-setup-with-install-dependencies)
+    - [Manual Extension Setup](#manual-extension-setup)
+    - [Extension Configuration](#extension-configuration)
+    - [Tailwind Config for VS Code](#tailwind-config-for-vs-code)
+  - [LiveView Development](#liveview-development)
+    - [Enabling LiveView](#enabling-liveview)
+    - [LiveView with TiKit Components](#liveview-with-tikit-components)
+    - [LiveView Development Workflow](#liveview-development-workflow)
+    - [Common LiveView Issues](#common-liveview-issues)
+  - [First Run Example](#first-run-example)
+  - [Quick Start with Example Files](#quick-start-with-example-files)
+  - [Troubleshooting](#troubleshooting)
+    - [PurgeTSS Not Running on Compile](#purgetss-not-running-on-compile)
+    - [Classes Not Appearing in IntelliSense](#classes-not-appearing-in-intellisense)
+    - [Missing Classes Report](#missing-classes-report)
+
+---
+
+## Prerequisites
+
+:::caution Node.js 20+ Required
+PurgeTSS has been thoroughly tested and proven to be compatible with Node 20.0.0 or higher.
+:::
+
+## Global Installation
+
+Install PurgeTSS globally on your machine using NPM:
+
+```bash
+[sudo] npm install -g purgetss
+```
+
+:::info
+On macOS/Linux systems, you may need to use `sudo` for global NPM installations. On Windows, run your terminal as Administrator if needed.
+:::
+
+## Initial Project Setup
+
+:::info
+**You only need to execute `purgetss` once within your project to automatically generate the required files and folders.**
+
+Subsequently, whenever you build your application, **PurgeTSS** will parse all your XML files and generate a clean `app.tss` file containing only the classes used in your project.
+:::
+
+### Running PurgeTSS for the First Time
+
+```bash
+cd /path/to/your/alloy/project
+purgetss
+```
+
+### What Happens on First Run
+
+When you run `purgetss` for the first time in your project, it will perform the following tasks:
+
+#### 1. Auto-Run Hook Setup
+
+**PurgeTSS** adds a task in `alloy.jmk` to auto-run `purgetss` every time you compile your app.
+
+**This is especially useful when using `liveview`** - changes to XML files are automatically reflected in your app.
+
+Your `alloy.jmk` will contain:
+
+```javascript
+task('pre:compile', function(event, logger) {
+	require('child_process').execSync('purgetss', logger.warn('::PurgeTSS:: Auto-Purging ' + event.dir.project));
+})
+```
+
+#### 2. purgetss Folder Structure
+
+PurgeTSS creates a `purgetss` folder at the root of your project:
+
+```bash
+./purgetss
+├─ fonts/              # Place custom font files (.ttf, .otf) here
+├─ styles/
+│  ├─ definitions.css # Used for VS Code IntelliSense
+│  └─ utilities.tss    # All PurgeTSS utility classes
+└─ config.cjs         # Your project's theme configuration
+```
+
+**File descriptions:**
+
+- **`config.cjs`**: Where you customize colors, spacing, fonts, border radius, and add custom rules for Ti Elements
+- **`styles/utilities.tss`**: All Tailwind-like utility classes + any custom classes from `config.cjs`
+- **`styles/definitions.css`**: Special CSS file incorporating ALL classes from `utilities.tss`, `_app.tss`, remaining `.tss` files, and `fonts.tss`. Used by VS Code extension for IntelliSense
+- **`fonts/`**: Directory for custom fonts (Icon, Serif, Sans-Serif, Cursive, Fantasy, Monospace). Use `purgetss build-fonts` after adding fonts
+
+#### 3. app.tss Backup
+
+:::caution IMPORTANT NOTICE!!!
+**PurgeTSS will OVERWRITE your existing `app.tss` file.**
+
+Upon the initial execution of **PurgeTSS**, your `app.tss` file is backed up to `_app.tss`.
+
+From this point forward, you have the option to add, delete, or update your custom classes in `_app.tss`.
+
+Alternatively, a better approach is to include your custom values in `config.cjs`.
+:::
+
+Every time `purgetss` runs, it copies the content of `_app.tss` to `app.tss` (if it exists).
+
+## Creating a Fresh config.cjs
+
+If you need to start with a fresh `config.cjs` file, delete the existing one and run:
+
+```bash
+purgetss init
+```
+
+This will create a minimal `./purgetss/config.cjs`:
+
+```javascript
+module.exports = {
+  purge: {
+    mode: 'all',
+    method: 'sync', // How to execute the auto-purging task: sync or async
+
+    // These options are passed directly to PurgeTSS
+    options: {
+      missing: true, // Reports missing classes
+      widgets: false, // Purges widgets too
+      safelist: [], // Array of classes to keep
+      plugins: [] // Array of properties to ignore
+    }
+  },
+  theme: {
+    extend: {}
+  }
+};
+```
+
+:::info
+Every section of the config file is optional, so you only need to specify what you'd like to change. Any missing sections will fall back to the default configuration.
+:::
+
+## Visual Studio Code Integration
+
+For the best development experience with PurgeTSS, we recommend installing and configuring the following VS Code extensions.
+
+### Quick Setup with install-dependencies
+
+The fastest way to set up VS Code integration is to use the `install-dependencies` command:
+
+```bash
+purgetss install-dependencies
+# or
+purgetss id
+```
+
+This command automatically installs and configures:
+- ESLint with Titanium-specific rules
+- Tailwind CSS (for IntelliSense integration)
+- VS Code settings and recommended extensions
+- Configuration files (`.editorconfig`, `eslint.config.js`, `tailwind.config.js`, `.vscode/extensions.json`, `.vscode/settings.json`)
+
+:::caution
+This command will overwrite existing `extensions.json` and `settings.json` files. Create a backup if you want to preserve them.
+:::
+
+### Manual Extension Setup
+
+If you prefer manual setup, install these extensions:
+
+1. **[XML Tools](https://marketplace.visualstudio.com/items?itemName=DotJoshJohnson.xml)** - For XML formatting
+2. **[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)** - Code quality and consistency
+3. **[Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)** - Intelligent PurgeTSS class support
+4. **[Tailwind RAW Reorder](https://marketplace.visualstudio.com/items?itemName=KevinYouu.tailwind-raw-reorder-tw4)** - Opinionated class sorter for better readability
+5. **[IntelliSense for CSS class names in HTML](https://marketplace.visualstudio.com/items?itemName=Zignd.html-css-class-completion)** - Class name completion based on your PurgeTSS definitions
+
+### Extension Configuration
+
+Add this to your VS Code `settings.json`:
+
+```json
+{
+  "html-css-class-completion.HTMLLanguages": [
+    "html",
+    "vue",
+    "razor",
+    "blade",
+    "handlebars",
+    "twig",
+    "django-html",
+    "php",
+    "markdown",
+    "erb",
+    "ejs",
+    "svelte",
+    "xml"
+  ],
+  "html-css-class-completion.excludeGlobPattern": "**/node_modules/**,purgetss/fonts/**/*.{css,html}"
+}
+```
+
+This enables:
+- Class name completion in XML files
+- Exclusion of generated files from caching
+- IntelliSense based on your actual PurgeTSS configuration
+
+### Tailwind Config for VS Code
+
+Create or update `tailwind.config.js` at your project root for optimal IntelliSense:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./app/views/**/*.xml",
+    "./purgetss/**/*.cjs"
+  ],
+  theme: {
+    extend: {}
+  },
+  plugins: []
+}
+```
+
+This helps Tailwind CSS IntelliSense understand your project structure.
+
+## LiveView Development
+
+:::tip
+We recommend using `liveview` to speed up testing and development time. **LiveView provides instant feedback** when you make changes to your XML files or styles.
+:::
+
+### Enabling LiveView
+
+LiveView is typically enabled through Titanium's development tools. When using LiveView with PurgeTSS:
+
+1. **Auto-purge is automatically enabled** when you run `purgetss`
+2. Changes to XML files trigger auto-purge on next compile
+3. LiveView reloads your app with the new styles
+
+### LiveView with TiKit Components
+
+If you don't see any changes reflected when changing and rebuilding a project with TiKit Components and LiveView, set the compile method to `async` in `config.cjs`:
+
+```javascript
+module.exports = {
+  purge: {
+    mode: 'all',
+    method: 'async' // Use async for LiveView + TiKit compatibility
+  }
+}
+```
+
+### LiveView Development Workflow
+
+**Optimal workflow with LiveView:**
+
+1. **Enable auto-purge** (done automatically by `purgetss`)
+2. **Set method to 'async'** if using TiKit Components
+3. **Make changes to XML or config.cjs**
+4. **Save file** (triggers auto-compile)
+5. **LiveView automatically reflects changes**
+
+**Example workflow:**
+```bash
+# Terminal 1: Run LiveView
+appc run --liveview
+
+# Terminal 2: Make changes
+# Edit app/views/index.xml
+# Save file - LiveView auto-reloads with new styles
+```
+
+### Common LiveView Issues
+
+**Problem:** Styles not updating in LiveView
+
+**Solutions:**
+1. Verify `alloy.jmk` has the pre:compile task
+2. Try `method: 'async'` in `config.cjs`
+3. Ensure `purgetss` ran successfully (check console output)
+4. Manually trigger compile if auto-compile isn't working
+
+**Problem:** Changes to `config.cjs` not reflected
+
+**Solutions:**
+1. Run `purgetss build` manually after config changes
+2. Check that `utilities.tss` was regenerated
+3. Verify your config syntax is correct (no trailing commas, etc.)
+
+## First Run Example
+
+After running `purgetss`, here's what your generated `app.tss` will look like:
+
+```tss
+/* PurgeTSS v7.2.7 */
+/* Created by César Estrada */
+/* https://purgetss.com */
+
+/* _app.tss styles */
+'.my-custom-class': {
+  backgroundColor: '#002359'
+}
+
+/* Ti Elements */
+'ImageView[platform=ios]': { hires: true }
+'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
+'Window': { backgroundColor: '#FFFFFF' }
+
+/* Main Styles */
+'.bg-white': { backgroundColor: '#ffffff' }
+'.font-semibold': { font: { fontWeight: 'semibold' } }
+'.h-16': { height: 64 }
+'.h-auto': { height: Ti.UI.SIZE }
+'.horizontal': { layout: 'horizontal' }
+// ... all other classes used in your XML files
+```
+
+:::info
+After running `purgetss`, you will have a new `app.tss` file with only the classes used in the XML files. Your original `app.tss` file is backed up in `_app.tss`. You can use this file to add, delete, or update any of your original styles. Every time `purgetss` runs, it will copy the content of `_app.tss` to `app.tss`.
+:::
+
+## Quick Start with Example Files
+
+PurgeTSS includes example files to get you started:
+
+1. Copy the content of `index.xml` into a new Alloy project
+2. Install Font Awesome: `purgetss icon-library --vendor=fontawesome`
+3. Run `purgetss` once to generate necessary files
+4. Compile your app as usual
+5. Use `liveview` for faster iteration
+
+For more examples, see the [Tailwind TSS Sample App](https://github.com/macCesar/utilities.tss-sample-app).
+
+## Troubleshooting
+
+### PurgeTSS Not Running on Compile
+
+Check that `alloy.jmk` exists in your project root and contains the pre:compile task. If missing, run `purgetss` again.
+
+### Classes Not Appearing in IntelliSense
+
+1. Ensure `definitions.css` is being generated (check `purgetss/styles/definitions.css`)
+2. Verify VS Code extension is installed and configured
+3. Try reloading VS Code after running `purgetss`
+
+### Missing Classes Report
+
+If `purge.options.missing` is set to `true`, check the end of your `app.tss` file for a list of missing or misspelled classes.
+
+:::info
+This is very useful if you want to check if you forgot to add a class definition or if you forgot to remove non-existing classes from your views, especially if you have upgraded from PurgeTSS v5 to v6.
+:::

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

@@ -0,0 +1,291 @@
+# 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
+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 ( / ).
+:::
+
+## Table of Contents
+
+- [Opacity Modifier](#opacity-modifier)
+  - [Table of Contents](#table-of-contents)
+  - [Basic Syntax](#basic-syntax)
+  - [How It Works](#how-it-works)
+  - [Usage in XML](#usage-in-xml)
+    - [Background Colors](#background-colors)
+    - [Text Colors](#text-colors)
+    - [Border Colors](#border-colors)
+    - [All Color Properties](#all-color-properties)
+  - [Usage with `@apply` Directive](#usage-with-apply-directive)
+  - [Complete List of Supported Color Properties](#complete-list-of-supported-color-properties)
+    - [Background Properties](#background-properties)
+    - [Text Properties](#text-properties)
+    - [Border Properties](#border-properties)
+    - [UI Element Properties](#ui-element-properties)
+    - [Navigation Properties](#navigation-properties)
+    - [Indicator Properties](#indicator-properties)
+    - [Tint Properties](#tint-properties)
+    - [Miscellaneous Properties](#miscellaneous-properties)
+  - [Opacity Value Reference](#opacity-value-reference)
+  - [Common Patterns](#common-patterns)
+    - [Hover/Active States](#hoveractive-states)
+    - [Disabled Appearance](#disabled-appearance)
+    - [Overlay/Backdrop](#overlaybackdrop)
+    - [Glassmorphism Effect](#glassmorphism-effect)
+    - [Gradient Fades](#gradient-fades)
+  - [Limitations](#limitations)
+  - [Performance Considerations](#performance-considerations)
+  - [Combining with Arbitrary Colors](#combining-with-arbitrary-colors)
+
+---
+
+## 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
+
+```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 -->
+```
+
+### 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
+
+```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>
+```
+
+## Usage with `@apply` Directive
+
+You can also use color opacity modifiers in the `apply` directive in `config.cjs`:
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#ce10cc'
+      }
+    },
+    '.main-banner': {
+      apply: [
+        'bg-primary/35',
+        'border-primary/75'
+      ]
+    }
+  }
+}
+```
+
+**Generated classes:**
+```tss
+/* Custom Styles */
+'.main-banner': { backgroundColor: '#59ce10cc', borderColor: '#bfce10cc' }
+
+/* Color Properties */
+'.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))" />
+```
+
+Note: When using `rgba()` directly, the opacity modifier is redundant since `rgba()` already includes alpha.