@maccesar/titools 2.0.0

package/skills/alloy-expert/references/alloy-structure.md

@@ -0,0 +1,381 @@
+# Alloy MVC + PurgeTSS Structure Reference
+
+## Standard Project Structure
+
+```
+app/
+├── controllers/           # View orchestrators
+│   ├── index.js          # Bootstrap only (no business logic)
+│   └── feature/
+│       └── 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
+│   ├── index.xml
+│   └── feature/
+│       ├── list.xml      # View definition (Utility classes here)
+├── 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
+│   └── 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
+
+:::danger CRITICAL: lib/ Folder is FLATTENED During Build
+When Alloy compiles, the **entire `lib/` folder is flattened to the root of Resources**. This means:
+- `app/lib/services/picsum.js` → `Resources/iphone/services/picsum.js`
+- `app/lib/api/client.js` → `Resources/iphone/api/client.js`
+
+**Therefore, require statements should NOT include `lib/` prefix:**
+```javascript
+// ❌ WRONG - Will fail at runtime
+const client = require('lib/api/client')
+
+// ✅ CORRECT - Path relative to flattened lib/
+const client = require('api/client')
+const picsum = require('services/picsum')
+```
+
+**This applies to:**
+- All files in `app/lib/` (services, api, helpers, etc.)
+- Cross-references within lib/ files
+- Controller requires of lib/ files
+
+**Example project structure:**
+```
+app/
+├── lib/
+│   ├── services/
+│   │   ├── picsum.js     # require('services/logger')
+│   │   ├── navigation.js # require('services/logger')
+│   │   └── logger.js
+│   └── api/
+│       └── client.js     # require('services/logger')
+├── controllers/
+│   └── index.js          # require('services/picsum')
+```
+:::
+
+## Data Layer: Two Approaches
+
+### Approach A: Alloy Models (app/models/) - For Persistence
+
+**Use when:**
+- You need SQLite persistence
+- You need schema migrations between app versions
+- You need offline-first functionality
+
+```javascript
+// app/models/User.js
+exports.definition = {
+  config: {
+    columns: {
+      id: 'INTEGER PRIMARY KEY',
+      name: 'TEXT',
+      email: 'TEXT'
+    },
+    adapter: {
+      type: 'sql',
+      collection_name: 'users'
+    }
+  }
+}
+
+// Usage
+const users = Alloy.createCollection('User')
+users.fetch()
+```
+
+---
+
+### Approach B: Backbone Collections Direct (alloy.js) - For API Data
+
+**Use when:**
+- Data comes from APIs
+- No local persistence needed
+- You want simplicity and flexibility
+
+```javascript
+// alloy.js - Define collections globally
+Alloy.Collections.frames = new Backbone.Collection()
+Alloy.Collections.mockups = new Backbone.Collection()
+```
+
+**In views - bind with dataCollection:**
+```xml
+<ListSection id="section" dataCollection="frames">
+  <ListItem title:text="{title}" />
+</ListSection>
+```
+
+**In controllers - manipulate directly:**
+```javascript
+// Reset collection
+Alloy.Collections.frames.reset()
+
+// Add items
+Alloy.Collections.frames.add(newItem)
+
+// Fetch from API
+api.getFrames()
+  .then(frames => Alloy.Collections.frames.reset(frames))
+```
+
+## Controller Rules
+
+**DO:**
+- Use **PurgeTSS classes** in XML for 100% of the styling.
+- 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).
+- Make direct API calls (use lib/api/ or lib/services/).
+- Contain heavy business logic.
+- Call native modules directly (use a service wrapper).
+
+## Navigation & Cleanup Pattern
+
+### Automatic Cleanup with ControllerAutoCleanup
+
+For automatic controller cleanup without code changes, use the ControllerAutoCleanup utility.
+
+**Installation:**
+
+1. Copy `ControllerAutoCleanup.js` to `app/lib/`
+2. Add as first line in `alloy.js`:
+
+```javascript
+// alloy.js
+require('ControllerAutoCleanup')
+
+// Rest of your alloy.js initialization...
+Alloy.Collections.frames = new Backbone.Collection()
+```
+
+**How it works:**
+
+- Monkey-patches `Alloy.createController` to add automatic cleanup
+- Listens for `close` events and recursively cleans up controllers
+- No code changes needed - existing `Alloy.createController().getView().open()` calls get cleanup automatically
+
+**Benefits:**
+
+| Without ControllerAutoCleanup              | With ControllerAutoCleanup |
+| ------------------------------------------ | -------------------------- |
+| Must remember manual cleanup               | Cleanup automatic          |
+| Easy to forget, causes memory leaks        | Memory leaks prevented     |
+| Repetitive code in each navigation service | One-line install           |
+
+See [ControllerAutoCleanup.js](../assets/ControllerAutoCleanup.js) for the complete source code.
+
+## i18n and Accessibility Rules
+
+- 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.
+
+## Widget Structure
+
+Widgets are self-contained, reusable components used in 3+ places across the app.
+
+```
+app/widgets/
+└── loadingOverlay/
+    ├── controllers/
+    │   └── widget.js      # Main widget controller
+    ├── views/
+    │   └── widget.xml     # Main widget view
+    ├── styles/
+    │   └── widget.tss     # Widget-specific styles (optional with PurgeTSS)
+    └── widget.json        # Widget manifest
+```
+
+### widget.json Configuration
+```json
+{
+  "id": "com.app.loadingOverlay",
+  "name": "Loading Overlay",
+  "description": "Full-screen loading indicator with optional message",
+  "author": "Your Name",
+  "version": "1.0.0",
+  "copyright": "Copyright (c) 2024",
+  "license": "MIT",
+  "min-alloy-version": "1.0.0",
+  "min-titanium-version": "9.0.0",
+  "tags": "ui, loading",
+  "platforms": "android,ios"
+}
+```
+
+### 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>
+  </View>
+</Alloy>
+```
+
+### Widget Controller (widget.js)
+```javascript
+// Widget controller receives args via $.args
+const args = $.args || {}
+
+// Initialize with defaults
+let message = args.message || L('loading')
+
+// Public API
+$.show = (msg) => {
+  if (msg) message = msg
+  $.messageLabel.text = message
+  $.spinner.show()
+  $.container.visible = true
+}
+
+$.hide = () => {
+  $.spinner.hide()
+  $.container.visible = false
+}
+
+$.setMessage = (msg) => {
+  $.messageLabel.text = msg
+}
+
+// Cleanup
+$.cleanup = () => {
+  $.spinner.hide()
+  $.destroy()
+}
+```
+
+### Using Widgets
+```xml
+<!-- In any view -->
+<Alloy>
+  <Window>
+    <!-- Your content -->
+
+    <!-- Add widget -->
+    <Widget id="loader" src="loadingOverlay" message="L('please_wait')" />
+  </Window>
+</Alloy>
+```
+
+```javascript
+// In controller
+const loadData = () => {
+  $.loader.show(L('loading_data'))
+
+  api.fetchData()
+    .then(renderData)
+    .finally(() => $.loader.hide())
+}
+```
+
+:::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`:
+
+```javascript
+// ./purgetss/config.cjs
+module.exports = {
+  purge: {
+    options: {
+      widgets: true  // Enable PurgeTSS class processing for widgets
+    }
+  }
+}
+```
+
+Without this setting, PurgeTSS will NOT process classes in widget files.
+:::
+
+## config.json Reference
+
+The `app/config.json` file configures Alloy compilation and runtime behavior.
+
+```json
+{
+  "global": {
+    "theme": "default"
+  },
+  "env:development": {
+    "apiUrl": "https://dev-api.example.com",
+    "debug": true,
+    "logLevel": "debug"
+  },
+  "env:test": {
+    "apiUrl": "https://staging-api.example.com",
+    "debug": true,
+    "logLevel": "info"
+  },
+  "env:production": {
+    "apiUrl": "https://api.example.com",
+    "debug": false,
+    "logLevel": "error"
+  },
+  "os:android": {
+    "androidSpecificSetting": true
+  },
+  "os:ios": {
+    "iosSpecificSetting": true
+  },
+  "dependencies": {
+    "com.app.loadingOverlay": "1.0"
+  },
+  "autoStyle": false,
+  "backbone": "1.4.0",
+  "sourcemap": true
+}
+```
+
+### Accessing Config Values
+```javascript
+// In any controller or lib file
+const apiUrl = Alloy.CFG.apiUrl
+const isDebug = Alloy.CFG.debug
+const logLevel = Alloy.CFG.logLevel
+
+// Environment check
+if (Alloy.CFG.debug) {
+  console.log('Debug mode enabled')
+}
+```
+
+### 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                     |

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

@@ -0,0 +1,133 @@
+# Titanium Alloy + PurgeTSS Anti-Patterns
+
+## 1. Manual Styling (Legacy & Overwrite Risk)
+**Symptom:** Editing `app.tss` manually or using inline attributes like `backgroundColor="#fff"`.
+**Problem:** PurgeTSS will overwrite manual changes in `app.tss`. Inline attributes make theme changes impossible.
+**Solution:** Use **PurgeTSS classes** in XML.
+
+## 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()`.
+**Solution:** Use the **PurgeTSS Animation Module** with state modifiers (`class="close:opacity-0 open:opacity-100"`).
+
+## 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 through PurgeTSS classes.
+
+---
+
+## PurgeTSS-Specific Anti-Patterns
+
+## 9. Flexbox Classes (Don't Exist)
+**Symptom:** Using `flex-row`, `flex-col`, `justify-between`, `justify-center`, `items-center`.
+**Problem:** Titanium does NOT support CSS Flexbox. These classes don't exist in PurgeTSS.
+**Solution:** Use Titanium layout modes:
+```xml
+<!-- WRONG -->
+<View class="flex-row justify-between">
+
+<!-- CORRECT -->
+<View class="horizontal">
+```
+
+## 10. Padding on Container Views
+**Symptom:** Using `p-4`, `px-2`, `py-3` on View, Window, ScrollView, or TableView.
+**Problem:** Base container elements don't support padding in Titanium.
+**Solution:** Use margins on children instead:
+```xml
+<!-- WRONG -->
+<View class="p-4">
+  <Label text="Hello" />
+</View>
+
+<!-- CORRECT -->
+<View>
+  <Label class="m-4" text="Hello" />
+</View>
+```
+
+## 11. Confusing `w-full` with `w-screen`
+**Symptom:** Using `w-full` when `w-screen` is needed.
+**Difference:** `w-full` sets `width: '100%'` (100% of parent), while `w-screen` sets `width: Ti.UI.FILL` (fills available space).
+**Solution:** Use `w-screen` for full-width elements that should fill space. `w-full` is useful when you need percentage-based sizing.
+
+## 12. Using `rounded-full` Without Size
+**Symptom:** Using `rounded-full` expecting a circle.
+**Problem:** `rounded-full` (without number) doesn't exist. You need `rounded-full-XX` where XX × 4 = element size.
+**Note:** `rounded-full-XX` already includes width and height. Don't add `w-XX h-XX` with it.
+**Solution:** For a 48×48 circle, use `rounded-full-12` (includes size). For percentage-based, use `w-12 h-12 rounded-full`.
+
+## 13. Adding `composite` Class Explicitly
+**Symptom:** Adding `class="composite"` to Views.
+**Problem:** Composite (absolute positioning) is the DEFAULT layout. Adding it is redundant.
+**Solution:** Omit layout class for composite, only use `horizontal` or `vertical` when needed.
+
+## 14. Square Brackets for Arbitrary Values
+**Symptom:** Using `w-[100px]` or `bg-[#ff0000]` with square brackets.
+**Problem:** PurgeTSS uses parentheses, not square brackets.
+**Solution:** Use parentheses: `w-(100px)`, `bg-(#ff0000)`.
+
+## 15. Creating Manual .tss Files Per Controller
+**Symptom:** Creating `app/styles/login.tss`, `app/styles/profile.tss`, etc.
+**Problem:** Defeats the purpose of PurgeTSS which auto-generates a single optimized `app.tss`.
+**Solution:** Use ONLY utility classes in XML. Delete all manual `.tss` files except `_app.tss`.
+
+## 16. 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')`
+
+## 17. 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()`
+
+## 18. 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.
+
+## 19. 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        |
+| -------------------- | ------------------------ | ----------------------- |
+| `flex-row`           | Flexbox not supported    | `horizontal`            |
+| `flex-col`           | Flexbox not supported    | `vertical`              |
+| `justify-*`          | Flexbox not supported    | Use margins/positioning |
+| `p-4` on View        | No padding on containers | `m-4` on children       |
+| `w-full`             | Doesn't exist            | `w-screen`              |
+| `rounded-full`       | Needs size suffix        | `rounded-full-12`       |
+| `composite` class    | Already default          | Omit it                 |
+| `w-[100px]`          | Wrong syntax             | `w-(100px)`             |
+| Manual `.tss`        | Overwritten by PurgeTSS  | Use utility classes     |
+| `lib/` prefix        | lib/ is flattened        | Use path without lib/   |
+| `$.index.open()`     | Wrong ID reference       | Use actual Window ID    |
+| `createNotification` | API doesn't exist        | `createAlertDialog`     |