@maccesar/titools 2.0.6 → 2.2.0

package/skills/{alloy-expert → ti-expert}/references/alloy-structure.md

@@ -1,4 +1,4 @@
-# Alloy MVC + PurgeTSS Structure Reference
+# Alloy MVC Structure Reference
 
 ## Standard Project Structure
 
@@ -10,34 +10,29 @@ app/
 │       └── list.js       # Controller for list view
 ├── models/               # OPTIONAL: For persistence with migrations
 │   └── user.js           # Model definition (ONLY if using SQLite)
-├── views/                # XML views styled with PurgeTSS
+├── views/                # XML views
 │   ├── index.xml
 │   └── feature/
-│       ├── list.xml      # View definition (Utility classes here)
+│       └── list.xml      # View definition
+├── styles/               # TSS styles (one per view + global)
+│   ├── app.tss           # Global application styles
+│   ├── index.tss         # Styles for index view
+│   └── feature/
+│       └── list.tss      # Styles for feature/list view
 ├── lib/                  # Reusable logic (no UI)
 │   ├── api/
 │   │   └── client.js     # API calls
 │   ├── services/
 │   │   ├── auth.js       # Business logic services
 │   │   ├── navigation.js # Navigation orchestration
-│   │   ├── nativeService.js # Native module wrapper (e.g. Audio, FB, Maps)
-│   │   └── purgetss.animation.js # PurgeTSS Animation module
+│   │   └── nativeService.js # Native module wrapper (e.g. Audio, FB, Maps)
 │   └── helpers/
 │       ├── utils.js      # Pure utility functions
 │       └── i18n.js       # Complex string transformations
 ├── widgets/              # Truly reusable components (used in 3+ places)
 │   └── customButton/
-├── styles/               # Global styles
-│   ├── app.tss            # GENERATED by PurgeTSS (Do not edit)
-│   ├── _app.tss           # YOUR custom styles (persists across runs)
-│   └── fonts.tss          # GENERATED by PurgeTSS build-fonts
 ├── config.json           # Alloy configuration
 └── alloy.js              # Collections & Global services
-
-./purgetss/
-├── config.cjs             # PurgeTSS theme configuration
-└── styles/
-    └── utilities.tss       # All utility classes
 ```
 
 ## lib/ Folder and Module Require Paths
@@ -145,14 +140,14 @@ api.getFrames()
 ## Controller Rules
 
 **DO:**
-- Use **PurgeTSS classes** in XML for 100% of the styling.
+- Define styles in TSS files (per-controller + `app.tss` for global).
 - Orchestrate view and model/collection interactions.
 - Handle UI events and delegate to services.
 - Format data for display (simple cases).
 - Manage view lifecycle (including cleanup).
 
 **DON'T:**
-- Create per-controller `.tss` files (Use PurgeTSS utility classes).
+- Use inline style attributes in XML (define in TSS files).
 - Make direct API calls (use lib/api/ or lib/services/).
 - Contain heavy business logic.
 - Call native modules directly (use a service wrapper).
@@ -197,7 +192,7 @@ See [ControllerAutoCleanup.js](../assets/ControllerAutoCleanup.js) for the compl
 - All static text must use `L('key')`.
 - All interactive elements must have `accessibilityLabel`.
 - Use `lib/helpers/i18n.js` for strings that require logic (e.g., "You have 5 messages").
-- Use **PurgeTSS modifiers** for platform-specific design instead of conditional code.
+- Use **TSS platform modifiers** (`[platform=ios]`, `[platform=android]`) for platform-specific design instead of conditional code.
 
 ## Widget Structure
 
@@ -211,7 +206,7 @@ app/widgets/
     ├── views/
     │   └── widget.xml     # Main widget view
     ├── styles/
-    │   └── widget.tss     # Widget-specific styles (optional with PurgeTSS)
+    │   └── widget.tss     # Widget-specific styles
     └── widget.json        # Widget manifest
 ```
 
@@ -235,15 +230,23 @@ app/widgets/
 ### Widget View (widget.xml)
 ```xml
 <Alloy>
-  <View id="container" class="wh-screen hidden bg-black/50">
-    <View class="wh-32 vertical rounded-2xl bg-white">
-      <ActivityIndicator id="spinner" class="mt-6" />
-      <Label id="messageLabel" class="mx-4 mt-4 text-sm text-gray-600" />
+  <View id="container">
+    <View id="box">
+      <ActivityIndicator id="spinner" />
+      <Label id="messageLabel" />
     </View>
   </View>
 </Alloy>
 ```
 
+```tss
+/* styles/widget.tss */
+"#container": { width: Ti.UI.FILL, height: Ti.UI.FILL, visible: false, backgroundColor: 'rgba(0,0,0,0.5)' }
+"#box": { width: 128, height: 128, layout: 'vertical', borderRadius: 16, backgroundColor: '#fff' }
+"#spinner": { top: 24 }
+"#messageLabel": { left: 16, right: 16, top: 16, font: { fontSize: 14 }, color: '#4b5563' }
+```
+
 ### Widget Controller (widget.js)
 ```javascript
 // Widget controller receives args via $.args
@@ -300,22 +303,126 @@ const loadData = () => {
 }
 ```
 
-:::tip PurgeTSS with Widgets
-If your widget uses PurgeTSS utility classes (as shown in the example above), you must enable widget processing in `./purgetss/config.cjs`:
+:::tip Widget Styles
+Widgets have their own `styles/widget.tss` file. Define all widget-specific styles there to keep them self-contained and portable.
+:::
+
+### Widget ↔ Controller Communication
+
+**Pattern 1: Public methods on $**
+
+The widget exposes methods directly on `$`:
 
 ```javascript
-// ./purgetss/config.cjs
-module.exports = {
-  purge: {
-    options: {
-      widgets: true  // Enable PurgeTSS class processing for widgets
-    }
+// widgets/loadingOverlay/controllers/widget.js
+$.show = (msg) => { /* ... */ }
+$.hide = () => { /* ... */ }
+
+// Parent controller
+$.loader.show(L('loading'))
+$.loader.hide()
+```
+
+**Pattern 2: Callbacks via $.args**
+
+Pass functions as arguments for child → parent communication:
+
+```xml
+<!-- Parent view -->
+<Widget id="picker" src="datePicker" />
+```
+
+```javascript
+// Parent controller - pass callback after creation
+$.picker.onDateSelected = (date) => {
+  $.dateLabel.text = formatDate(date)
+}
+
+// Widget controller
+function handleSelection(e) {
+  if ($.args.onDateSelected) {
+    $.args.onDateSelected(e.value)
+  }
+  // Or if set as property:
+  if ($._onDateSelected) {
+    $._onDateSelected(e.value)
   }
 }
 ```
 
-Without this setting, PurgeTSS will NOT process classes in widget files.
-:::
+**Pattern 3: Backbone Events (for complex communication)**
+
+```javascript
+// Widget controller (emits events)
+$.trigger('item:selected', { item: selectedItem })
+$.trigger('search:changed', { query: text })
+
+// Parent controller (listens)
+$.searchWidget.on('search:changed', (data) => {
+  filterResults(data.query)
+})
+
+// Cleanup in parent
+function cleanup() {
+  $.searchWidget.off('search:changed')
+  $.destroy()
+}
+```
+
+### Widget with Internal State
+
+```javascript
+// widgets/counter/controllers/widget.js
+let count = parseInt($.args.initial || '0', 10)
+
+function render() {
+  $.countLabel.text = String(count)
+  $.decrementBtn.enabled = count > 0
+}
+
+$.increment = () => {
+  count++
+  render()
+  $.trigger('change', { value: count })
+}
+
+$.decrement = () => {
+  if (count > 0) {
+    count--
+    render()
+    $.trigger('change', { value: count })
+  }
+}
+
+$.getValue = () => count
+
+$.setValue = (val) => {
+  count = val
+  render()
+}
+
+// Expose for click handlers in XML
+$.incrementBtn.addEventListener('click', $.increment)
+$.decrementBtn.addEventListener('click', $.decrement)
+
+$.cleanup = () => {
+  $.incrementBtn.removeEventListener('click', $.increment)
+  $.decrementBtn.removeEventListener('click', $.decrement)
+  $.destroy()
+}
+
+render()
+```
+
+### When to Use Widget vs Require
+
+| Use `<Widget>` when                   | Use `<Require>` when            |
+| ------------------------------------- | ------------------------------- |
+| Component is used in 3+ places        | Component is used in 1-2 places |
+| Needs its own self-contained styles   | Shares styles with parent       |
+| Has public API (show/hide/setValue)   | Just renders, no API needed     |
+| Could be extracted to another project | Specific to this app            |
+| Needs its own `widget.json` manifest  | Lightweight, no manifest needed |
 
 ## config.json Reference
 
@@ -371,11 +478,11 @@ if (Alloy.CFG.debug) {
 
 ### Key Configuration Options
 
-| Property       | Description                                       |
-| -------------- | ------------------------------------------------- |
-| `theme`        | Theme folder to use from `app/themes/`            |
-| `autoStyle`    | Auto-apply TSS styles (set `false` with PurgeTSS) |
-| `backbone`     | Backbone.js version to use                        |
-| `sourcemap`    | Generate source maps for debugging                |
-| `dependencies` | Widget dependencies and versions                  |
-| `adaptersPath` | Custom path for sync adapters                     |
+| Property       | Description                               |
+| -------------- | ----------------------------------------- |
+| `theme`        | Theme folder to use from `app/themes/`    |
+| `autoStyle`    | Auto-apply TSS styles by element ID/class |
+| `backbone`     | Backbone.js version to use                |
+| `sourcemap`    | Generate source maps for debugging        |
+| `dependencies` | Widget dependencies and versions          |
+| `adaptersPath` | Custom path for sync adapters             |

package/skills/ti-expert/references/anti-patterns.md

@@ -0,0 +1,90 @@
+# Titanium Alloy Anti-Patterns
+
+## 1. Inline Styling Instead of TSS
+**Symptom:** Using inline attributes like `backgroundColor="#fff"` directly in XML views.
+**Problem:** Inline attributes make theme changes impossible and scatter visual definitions across views.
+**Solution:** Define styles in TSS files using IDs or class selectors.
+
+## 2. Fat Controllers
+**Symptom:** Controllers with 100+ lines handling logic, API, and UI.
+**Solution:** Delegate business logic to `lib/services/` and API calls to `lib/api/`.
+
+## 3. Memory Leaks (Missing Cleanup)
+**Symptom:** Adding `Ti.App` or `Alloy.Collections` listeners without a `cleanup()` function.
+**Solution:** Always implement `$.cleanup = cleanup` and remove listeners there.
+
+## 4. Direct Native Module Calls
+**Symptom:** Calling `require('ti.module')` directly in a controller.
+**Solution:** Wrap it in a service in `lib/services/` (e.g., `audioService.js`).
+
+## 5. Direct Controller Navigation
+**Symptom:** `Alloy.createController('name').getView().open()`.
+**Solution:** Use a Navigation Service to centralize `open/close` and trigger the `cleanup()` function automatically.
+
+## 6. Complex Matrix Animations
+**Symptom:** Manual use of `Ti.UI.create2DMatrix()` for simple animations.
+**Solution:** Use `Ti.UI.createAnimation()` for opacity, transform, and duration-based animations. Reserve 2D Matrix for complex multi-property transforms.
+
+## 7. Hardcoded Strings & Missing a11y
+**Symptom:** `text="Login"` instead of `text="L('login')"`, or missing `accessibilityLabel`.
+**Solution:** Always use i18n and accessibility properties.
+
+## 8. Logic in TSS
+**Symptom:** Using conditionals or calculations inside TSS.
+**Solution:** Keep styling declarative in TSS files.
+
+---
+
+## Titanium Layout Anti-Patterns
+
+## 9. Padding on Container Views
+**Symptom:** Setting `padding` on View, Window, ScrollView, or TableView.
+**Problem:** Base container elements don't support padding in Titanium.
+**Solution:** Use margins on children instead:
+```tss
+/* WRONG */
+"#container": { padding: 16 }
+
+/* CORRECT - margin on children */
+"#childLabel": { left: 16, top: 16, right: 16 }
+```
+
+## 10. Redundant Composite Layout
+**Symptom:** Adding `layout: 'composite'` to Views.
+**Problem:** Composite (absolute positioning) is the DEFAULT layout. Setting it is redundant.
+**Solution:** Omit `layout` for composite, only specify `layout: 'horizontal'` or `layout: 'vertical'` when needed.
+
+## 11. Using `lib/` Prefix in Require Statements
+**Symptom:** `const service = require('lib/services/picsum')`
+**Problem:** Alloy flattens the `lib/` folder during build. Files in `app/lib/services/` become `Resources/iphone/services/`.
+**Solution:** Omit the `lib/` prefix: `const service = require('services/picsum')`
+
+## 12. Wrong Window ID in Controller
+**Symptom:** Using `$.index.open()` when the Window has `id="mainWindow"`.
+**Problem:** Alloy generates `$` references from XML IDs. If Window is `id="mainWindow"`, `$.index` doesn't exist.
+**Solution:** Match the ID: `$.mainWindow.open()`
+
+## 13. Using `Ti.UI.createNotification`
+**Symptom:** `Ti.UI.createNotification({ message: 'Hi' }).show()`
+**Problem:** This API doesn't exist in Titanium. Causes "invalid method" error.
+**Solution:** Use `Ti.UI.createAlertDialog` for simple messages, or create custom toast views.
+
+## 14. Using Nonexistent iOS Share APIs
+**Symptom:** `Ti.UI.iOS.createActivityPopover` or `alloy/social` with wrong methods.
+**Problem:** These APIs either don't exist or have changed. Causes runtime errors.
+**Solution:**
+- iOS: Use `Ti.UI.iOS.createDocumentViewer` for files, or simple `Ti.UI.createOptionDialog` + `Ti.UI.Clipboard` for links
+- Android: Use `Ti.Android.createIntent` with ACTION_SEND
+
+---
+
+## Quick Reference Table
+
+| Anti-Pattern            | Why It Fails             | Correct Approach      |
+| ----------------------- | ------------------------ | --------------------- |
+| `padding` on View       | No padding on containers | Margins on children   |
+| `layout: 'composite'`   | Already default          | Omit it               |
+| Inline style attributes | Scattered styling        | Define in TSS files   |
+| `lib/` prefix           | lib/ is flattened        | Use path without lib/ |
+| `$.index.open()`        | Wrong ID reference       | Use actual Window ID  |
+| `createNotification`    | API doesn't exist        | `createAlertDialog`   |

package/skills/ti-expert/references/cli-expert.md

@@ -0,0 +1,109 @@
+# CLI Expert Strategies & TiNy
+
+Mastering the command line is essential for a Titanium expert. This guide covers advanced workflows, optimization techniques, and the use of **TiNy (`tn`)** for efficient development.
+
+## The Expert Workflow
+
+An expert doesn't just run `ti build`. They optimize for speed, reliability, and automation.
+
+### 1. The "Inner Loop" Optimization
+Reduce the time between writing code and seeing it on the device.
+
+- **LiveView**: Use `--liveview` for near-instant UI updates without full recompilation.
+  ```bash
+  ti build -p ios --liveview
+  ```
+- **Build Only**: Use `-b` to verify Alloy compilation and JavaScript syntax without launching the simulator.
+  ```bash
+  ti build -p ios -b
+  ```
+- **Skip Minification**: In development, always skip minification to speed up the build process.
+  ```bash
+  ti build -p ios --skip-js-minify
+  ```
+
+### 2. Precise Cleaning
+Don't use `ti clean` as a first resort (it's slow).
+- **Targeted Clean**: If Alloy isn't reflecting changes, try deleting `Resources/` and `build/` manually or use `ti clean -p <platform>`.
+- **Pre-Production**: Always run a full `ti clean` before a production/App Store build to ensure no stale assets are included.
+
+### 3. Advanced Debugging
+- **Trace Logging**: Use `--log-level trace` when a build fails for mysterious reasons (e.g., a broken hook or native module issue).
+- **Build Logs**: Check `build/build.log` for the full output of the last build process.
+
+---
+
+## TiNy (`tn`): The Expert's Power Tool
+
+**TiNy** is a modern CLI wrapper for Titanium SDK that drastically reduces keystrokes and manages complex build configurations through "recipes".
+
+### Why Experts Use TiNy
+- **Speed**: `tn ios` vs `ti build -p ios -T simulator`.
+- **Consistency**: Recipes ensure every team member builds with the same flags.
+- **Device Management**: Easily target specific simulators/emulators by name.
+
+### Quick Start
+1. **Install**: `npm install -g tn`
+2. **Repo**: https://github.com/jasonkneen/tn
+3. **Generate Recipes**: Detect all connected devices/simulators.
+   ```bash
+   tn generate
+   ```
+4. **Build**:
+   ```bash
+   tn iphone-16-pro
+   tn pixel-8-pro-api-34
+   ```
+
+### Expert Recipes
+Recipes can be flags or options. Multiple recipes can be combined.
+
+| Command        | Expansion                           |
+| -------------- | ----------------------------------- |
+| `tn ios`       | `--platform ios`                    |
+| `tn android`   | `--platform android`                |
+| `tn appstore`  | `--ios --target dist-appstore`      |
+| `tn playstore` | `--android --target dist-playstore` |
+| `tn watch`     | `--ios --launch-watch-app`          |
+
+### Customizing Your Workflow
+- **Save Global Recipe**:
+  ```bash
+  tn save my-debug --ios --simulator --log-level trace --skip-js-minify
+  ```
+- **Project-Specific Recipes**: Save a `tn.json` in your project root for team-wide recipes (e.g., specific provisioning profiles).
+  ```bash
+  tn project save release --playstore --keystore ./android/release.keystore
+  ```
+
+### Composition & Placeholders
+You can use `%s` as a placeholder in recipes for values:
+```bash
+tn save ci -b --pp-uuid <UUID> --distribution-name "<NAME>" --ah --installr --installr-release-notes %s
+
+# Usage:
+tn ci "Fixed login bug"
+```
+
+---
+
+## Automation Integration
+
+Experts automate their builds using `package.json` scripts, often combining `ti` or `tn` with other tools.
+
+```json
+"scripts": {
+  "start": "tn ios --liveview",
+  "build:android": "tn android",
+  "clean": "ti clean",
+  "prod:ios": "tn appstore --distribution-name 'My Company'",
+  "lint": "eslint app/"
+}
+```
+
+---
+
+## Pro-Tips
+- **SDK Switching**: Use `-s <version>` to test your app against a specific SDK version without changing your global default.
+- **Sim Focus**: Use `--no-sim-focus` if you want to keep your editor in focus while the simulator launches in the background.
+- **Concurrent Builds**: You can often build for iOS and Android simultaneously in different terminal tabs if your machine has the resources.