@maccesar/titools 4.1.0 → 4.4.0

package/skills/ti-expert/references/testing-unit.md

@@ -5,6 +5,26 @@
 > Testing is useful for teams practicing CI/CD, projects with complex business logic, or refactoring confidence.
 > If you prefer manual testing on device, you can safely skip this guide.
 
+<!-- TOC-START -->
+## Contents
+
+- [What can be tested (Without Compiling)](#what-can-be-tested-without-compiling)
+- [What cannot be easily tested](#what-cannot-be-easily-tested)
+- [Testing philosophy](#testing-philosophy)
+- [Project structure](#project-structure)
+- [Writing testable code](#writing-testable-code)
+- [Unit testing services](#unit-testing-services)
+- [Unit testing helpers](#unit-testing-helpers)
+- [Integration testing controllers](#integration-testing-controllers)
+- [Mock factory](#mock-factory)
+- [Test helper functions](#test-helper-functions)
+- [Test setup configuration](#test-setup-configuration)
+- [Running tests](#running-tests)
+- [Anti-patterns to avoid](#anti-patterns-to-avoid)
+- [Test checklist](#test-checklist)
+
+<!-- TOC-END -->
+
 ## What can be tested (Without Compiling)
 
 **Pure JavaScript Logic:**

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

@@ -1,428 +1,190 @@
-# Theming & dark mode
+# Theming and dark mode
 
-## Alloy theme system
+Choose the styling path from the project, not from personal memory. Semantic
+roles are the shared contract; PurgeTSS or standard Alloy materializes them.
 
-Alloy has a built-in theme system via the `app/themes/` folder. Themes override views, styles, and assets without modifying originals.
+## Contents
 
-### Theme folder structure
+- [Decision path](#decision-path)
+- [Semantic color contract](#semantic-color-contract)
+- [PurgeTSS projects](#purgetss-projects)
+- [Standard Alloy projects](#standard-alloy-projects)
+- [Alloy build-time themes](#alloy-build-time-themes)
+- [Runtime custom themes](#runtime-custom-themes)
+- [Component rules](#component-rules)
+- [Verification](#verification)
 
-```
-app/
-├── themes/
-│   ├── light/                   # Light theme (or default)
-│   │   ├── styles/
-│   │   │   └── app.tss          # Overrides app/styles/app.tss
-│   │   └── assets/
-│   │       └── images/
-│   │           └── logo.png     # Overrides app/assets/images/logo.png
-│   └── dark/                    # Dark theme
-│       ├── styles/
-│       │   └── app.tss          # Dark overrides
-│       └── assets/
-│           └── images/
-│               └── logo.png     # Dark version of logo
-├── styles/
-│   └── app.tss                  # Base styles (used when no theme active)
-├── config.json
-```
-
-### Activating a theme
-
-Set the theme in `config.json`:
-
-```json
-{
-  "global": {
-    "theme": "light"
-  },
-  "env:development": {
-    "theme": "light"
-  }
-}
-```
-
-> **⚠️ Theme is compile-time only**
-> Alloy themes are applied at **build time**. You cannot switch themes at runtime using this system alone. For runtime switching, use the Dynamic Theming approach below.
-
-### Theme cascade
-
-When a theme is active, Alloy merges files in this order:
-1. `app/styles/app.tss` (base)
-2. `app/themes/<theme>/styles/app.tss` (theme override)
-3. `app/styles/<controller>.tss` (controller-specific)
-4. `app/themes/<theme>/styles/<controller>.tss` (theme + controller override)
-
-Theme files **merge** with base files , you only need to include properties you want to override.
-
----
-
-## Dynamic theming with Alloy.Globals
-
-For runtime theme switching (including Dark Mode), use `Alloy.Globals` as a centralized color palette.
-
-### Step 1: define color palette
-
-```javascript
-// alloy.js
-const themes = {
-  light: {
-    bg: '#ffffff',
-    bgSecondary: '#f3f4f6',
-    text: '#111827',
-    textSecondary: '#6b7280',
-    primary: '#2563eb',
-    primaryText: '#ffffff',
-    border: '#e5e7eb',
-    card: '#ffffff',
-    danger: '#ef4444',
-    success: '#22c55e'
-  },
-  dark: {
-    bg: '#111827',
-    bgSecondary: '#1f2937',
-    text: '#f9fafb',
-    textSecondary: '#9ca3af',
-    primary: '#3b82f6',
-    primaryText: '#ffffff',
-    border: '#374151',
-    card: '#1f2937',
-    danger: '#f87171',
-    success: '#4ade80'
-  }
-}
-
-// Load saved preference or default to light
-const savedTheme = Ti.App.Properties.getString('app:theme', 'light')
-Alloy.Globals.theme = themes[savedTheme]
-Alloy.Globals.themeName = savedTheme
-```
+## Decision path
 
-### Step 2: use in TSS with Alloy.Globals
+1. Detect `purgetss/` or `purgetss/config.cjs`.
+2. If detected, invoke the `purgetss` skill before writing any class or style.
+3. If not detected, use standard Alloy TSS and Titanium semantic colors.
+4. Use `Alloy.Globals` for a runtime palette only when the product requires
+   custom themes beyond the semantic light/dark/system model.
 
-```tss
-/* app.tss - Global base styles using theme colors */
-"Window": {
-  backgroundColor: Alloy.Globals.theme.bg
-}
+Do not mix these paths accidentally. In particular, never teach a PurgeTSS
+project to maintain the generated `app/styles/app.tss` by hand.
 
-"Label": {
-  color: Alloy.Globals.theme.text
-}
+## Semantic color contract
 
-".card": {
-  backgroundColor: Alloy.Globals.theme.card,
-  borderWidth: 1,
-  borderColor: Alloy.Globals.theme.border,
-  borderRadius: 12
-}
+Name colors by purpose rather than appearance. A practical design-system
+contract includes:
 
-".btn-primary": {
-  backgroundColor: Alloy.Globals.theme.primary,
-  color: Alloy.Globals.theme.primaryText,
-  height: 48,
-  borderRadius: 8,
-  font: { fontWeight: 'bold' }
-}
-
-".text-secondary": {
-  color: Alloy.Globals.theme.textSecondary
-}
+- app background and elevated surface;
+- primary and secondary text;
+- border/divider;
+- accent and text on accent;
+- modal overlay;
+- success, warning, error, and their readable foreground colors;
+- disabled surface/text where needed.
 
-".bg-secondary": {
-  backgroundColor: Alloy.Globals.theme.bgSecondary
-}
-```
+Define light and dark values in:
 
-### Step 3: theme switching service
+- Alloy: `app/assets/semantic.colors.json`
+- Classic: `Resources/semantic.colors.json`
 
-```javascript
-// lib/services/themeService.js
-const EventBus = require('services/eventBus')
+Example:
 
-const themes = {
-  light: { /* ... same as alloy.js ... */ },
-  dark: { /* ... same as alloy.js ... */ }
-}
-
-exports.ThemeService = {
-  getCurrentTheme() {
-    return Alloy.Globals.themeName
-  },
-
-  setTheme(name) {
-    if (!themes[name]) return
-
-    Alloy.Globals.theme = themes[name]
-    Alloy.Globals.themeName = name
-    Ti.App.Properties.setString('app:theme', name)
-
-    // Notify all listeners
-    EventBus.trigger('theme:changed', { theme: name })
+```json
+{
+  "surfaceColor": {
+    "light": "#FFFFFF",
+    "dark": "#1E293B"
   },
-
-  toggle() {
-    const next = Alloy.Globals.themeName === 'light' ? 'dark' : 'light'
-    this.setTheme(next)
+  "textColor": {
+    "light": "#111827",
+    "dark": "#F1F5F9"
   },
-
-  // Follow system Dark Mode (iOS 13+, Android 10+)
-  followSystem() {
-    if (Ti.UI.semanticColorType !== undefined) {
-      const isDark = Ti.UI.semanticColorType === Ti.UI.SEMANTIC_COLOR_TYPE_DARK
-      this.setTheme(isDark ? 'dark' : 'light')
-    }
+  "overlayColor": {
+    "light": "#00000080",
+    "dark": "#000000CC"
   }
 }
 ```
 
-### Step 4: respond to theme changes in controllers
+Titanium resolves a semantic color name when a color-accepting property uses
+that name. Keep component APIs tone-based (`neutral`, `success`, `warning`,
+`error`) and map tones to semantic roles inside the visual layer. Do not pass
+raw brand hex values through business controllers.
 
-> **⚠️ Theme change requires UI rebuild**
-> Since TSS is applied at controller creation time, changing `Alloy.Globals.theme` does NOT retroactively update already-rendered views. You must manually update visible elements or restart the root controller.
+## PurgeTSS projects
 
-**Approach A: Rebuild root controller (simplest)**
+The `purgetss` skill is the source of truth for supported classes, configuration,
+appearance behavior, and commands. Apply these integration rules:
 
-```javascript
-// controllers/settings.js
-const { ThemeService } = require('services/themeService')
-
-function onToggleTheme() {
-  ThemeService.toggle()
+- Map semantic color names under `theme.extend.colors` in
+  `purgetss/config.cjs`.
+- Use verified utility classes in Alloy XML.
+- Configure `options.widgets: true` when Widgets contain utility classes.
+- Prefer `config.cjs` for reusable custom rules.
+- Treat `app/styles/app.tss` as generated output and never edit it.
+- Keep only truly specific properties in Widget/controller TSS when no verified
+  utility exists.
+- Use the PurgeTSS Appearance module for light/dark/system selection instead of
+  creating a competing mode service.
+- Read the current PurgeTSS references before naming any utility. Similarity to
+  Tailwind is not evidence that a class exists.
 
-  // Restart app from root controller
-  const root = Alloy.createController('index')
-  root.getView().open()
-
-  // Close current window tree
-  $.getView().close()
-}
-```
-
-**Approach B: Update visible elements in-place (smoother)**
+Conceptual mapping only; verify the actual PurgeTSS syntax before use:
 
 ```javascript
-// controllers/settings.js
-const EventBus = require('services/eventBus')
-const { ThemeService } = require('services/themeService')
-
-function init() {
-  EventBus.on('theme:changed', applyTheme)
-}
-
-function applyTheme() {
-  const t = Alloy.Globals.theme
-
-  $.settingsWindow.applyProperties({ backgroundColor: t.bg })
-  $.titleLabel.applyProperties({ color: t.text })
-  $.themeToggle.applyProperties({ backgroundColor: t.bgSecondary })
-}
-
-function onToggleTheme() {
-  ThemeService.toggle()
-}
-
-function cleanup() {
-  EventBus.off('theme:changed', applyTheme)
-  $.destroy()
-}
-
-$.cleanup = cleanup
-```
-
----
-
-## System dark mode detection
-
-### iOS 13+ / Android 10+
-
-```javascript
-// lib/services/themeService.js (add to existing service)
-
-exports.ThemeService = {
-  // ... existing methods ...
-
-  // Initialize system theme listener
-  initSystemListener() {
-    // Detect current system theme at startup
-    this.followSystem()
-
-    // Re-check on resume (user may have changed system Dark Mode while app was backgrounded)
-    // Note: Titanium does not fire a dedicated dark-mode-change event.
-    // `Ti.UI.semanticColorType` is the correct way to check the current setting.
-    Ti.App.addEventListener('resumed', () => {
-      this.followSystem()
-    })
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        surface: 'surfaceColor',
+        'on-surface': 'textColor',
+        overlay: 'overlayColor'
+      }
+    }
   }
 }
 ```
 
-### Semantic colors (Cross-Platform)
+After generation, inspect the final `app.tss` section for unused or unsupported
+classes. A clean build that still lists a new unsupported class is not complete.
 
-Titanium provides a cross-platform semantic colors API for Dark Mode support. Define colors in a `semantic.colors.json` file:
+## Standard Alloy projects
 
-**File location:**
-- **Classic apps**: `Resources/semantic.colors.json`
-- **Alloy apps**: `app/assets/semantic.colors.json`
+Without PurgeTSS:
 
-```json
-{
-  "textColor": {
-    "dark": {
-      "color": "#ff85e2",
-      "alpha": "50"
-    },
-    "light": "#ff1f1f"
-  },
-  "backgroundColor": {
-    "dark": "#1a1a2e",
-    "light": "#ffffff"
-  },
-  "primaryColor": {
-    "dark": {
-      "color": "#4ade80",
-      "alpha": "100"
-    },
-    "light": {
-      "color": "#22c55e",
-      "alpha": "100"
-    }
-  }
-}
-```
+- keep global selectors in manually maintained `app/styles/app.tss`;
+- keep screen-specific selectors in `app/styles/<controller>.tss`;
+- keep Widget-specific properties in `app/widgets/<id>/styles/widget.tss`;
+- reference semantic color names from TSS or controller properties;
+- use platform and form-factor modifiers for platform-specific properties.
 
-**Using semantic colors:**
+Example:
 
 ```tss
-/* Reference via Ti.UI.fetchSemanticColor() */
-"#label": {
-  color: Ti.UI.fetchSemanticColor('textColor')
+"Window": {
+  backgroundColor: "backgroundColor"
 }
 
-"#container": {
-  backgroundColor: Ti.UI.fetchSemanticColor('backgroundColor')
+".card": {
+  backgroundColor: "surfaceColor",
+  borderColor: "borderColor",
+  borderWidth: 1
 }
-```
 
-```javascript
-// Or use color names directly as property values
-$.label.color = 'textColor';
-$.container.backgroundColor = 'backgroundColor';
+".bodyText": {
+  color: "textColor"
+}
 ```
 
-**How it works:**
-- On iOS 13+ it uses the native system method that checks the user's system-wide Dark Mode setting
-- On all other platforms it checks `Ti.UI.semanticColorType` and returns the correct color variant
-- Alpha can be set from 0.0-100.0 (integer or float)
-- Light values can use hex with alpha via ARGB/AARRGGBB format
+Do not copy a large utility system into manual TSS. Create only the small set of
+selectors the app actually uses.
 
-> **💡 When to use Semantic Colors vs Alloy.Globals**
-> - **Semantic Colors**: Built-in Dark Mode support, automatic switching, simpler setup. Works cross-platform.
-> - **Alloy.Globals palette**: More control over when/how themes switch, easier to add custom themes beyond light/dark, runtime theme changes with UI rebuild.
+## Alloy build-time themes
 
----
+Alloy's `app/themes/<name>/` folders can override views, styles, and assets at
+build time. Select a theme through `app/config.json`. This is appropriate for
+separate branded builds or compile-time variants.
 
-## Reusable style classes pattern
+Do not describe an Alloy build-time theme as runtime light/dark switching.
+Semantic colors are the default for appearance changes while the app runs.
 
-Define a library of reusable TSS classes in `app.tss` for consistency across the app:
+## Runtime custom themes
 
-```tss
-/* app.tss - Design System */
-
-/* === Layout === */
-".row": { layout: 'horizontal', width: Ti.UI.FILL, height: Ti.UI.SIZE }
-".col": { layout: 'vertical', width: Ti.UI.FILL, height: Ti.UI.SIZE }
-".centered": { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
-
-/* === Cards === */
-".card": {
-  backgroundColor: Alloy.Globals.theme.card,
-  borderRadius: 12,
-  borderWidth: 1,
-  borderColor: Alloy.Globals.theme.border,
-  width: Ti.UI.FILL,
-  height: Ti.UI.SIZE
-}
-
-/* === Buttons === */
-".btn-primary": {
-  backgroundColor: Alloy.Globals.theme.primary,
-  color: Alloy.Globals.theme.primaryText,
-  height: 48,
-  width: Ti.UI.FILL,
-  borderRadius: 8,
-  font: { fontSize: 16, fontWeight: 'bold' }
-}
+Use a centralized runtime palette or theme service only when semantic
+light/dark/system colors cannot model the requirement, such as multiple user
+selectable brand themes.
 
-".btn-secondary": {
-  backgroundColor: 'transparent',
-  color: Alloy.Globals.theme.primary,
-  height: 48,
-  width: Ti.UI.FILL,
-  borderRadius: 8,
-  borderWidth: 1,
-  borderColor: Alloy.Globals.theme.primary,
-  font: { fontSize: 16, fontWeight: 'bold' }
-}
+If that exception applies:
 
-".btn-danger": {
-  backgroundColor: Alloy.Globals.theme.danger,
-  color: '#ffffff',
-  height: 48,
-  width: Ti.UI.FILL,
-  borderRadius: 8,
-  font: { fontSize: 16, fontWeight: 'bold' }
-}
+- keep the selected theme in one service;
+- expose semantic roles, not control IDs;
+- document how already-created proxies receive updates;
+- remove all listeners in controller cleanup;
+- avoid rebuilding the entire window tree unless the app has measured and
+  accepted that tradeoff.
 
-/* === Typography === */
-".text-title": { font: { fontSize: 24, fontWeight: 'bold' }, color: Alloy.Globals.theme.text }
-".text-subtitle": { font: { fontSize: 18, fontWeight: 'semibold' }, color: Alloy.Globals.theme.text }
-".text-body": { font: { fontSize: 16 }, color: Alloy.Globals.theme.text }
-".text-caption": { font: { fontSize: 14 }, color: Alloy.Globals.theme.textSecondary }
-".text-small": { font: { fontSize: 12 }, color: Alloy.Globals.theme.textSecondary }
-
-/* === Inputs === */
-".input": {
-  height: 48,
-  width: Ti.UI.FILL,
-  borderRadius: 8,
-  borderWidth: 1,
-  borderColor: Alloy.Globals.theme.border,
-  backgroundColor: Alloy.Globals.theme.bg,
-  color: Alloy.Globals.theme.text,
-  paddingLeft: 12,
-  font: { fontSize: 16 }
-}
+`Alloy.Globals` is a legacy/advanced interoperability option, not the first
+recommendation for ordinary dark mode.
 
-/* === Spacing (applied via class in XML) === */
-".mt-sm": { top: 8 }
-".mt-md": { top: 16 }
-".mt-lg": { top: 24 }
-".mt-xl": { top: 32 }
-".mx-md": { left: 16, right: 16 }
-".mx-lg": { left: 24, right: 24 }
-```
+## Component rules
 
-### Using style classes in views
+- Components consume semantic roles owned by the host app.
+- Widgets own anatomy and behavior, not the product palette.
+- Localized strings and business callbacks come from the host.
+- Destructive styling must remain distinguishable in both appearances.
+- Overlays, focus indicators, disabled states, and text must retain usable
+  contrast in light, dark, and system modes.
+- Do not create separate light/dark controller branches when a semantic color
+  can express the difference.
 
-```xml
-<Alloy>
-  <Window>
-    <View class="col mx-md">
-      <Label class="text-title mt-lg" text="L('settings')" />
+## Verification
 
-      <View class="card mt-md">
-        <Label class="text-body mx-md mt-md" text="L('appearance')" />
-        <Button class="btn-secondary mx-md mt-md" title="L('toggle_theme')" onClick="onToggleTheme" />
-      </View>
+For every supported platform and form factor:
 
-      <Button class="btn-danger mt-xl mx-md" title="L('logout')" onClick="onLogout" />
-    </View>
-  </Window>
-</Alloy>
-```
+1. test light, dark, and follow-system modes;
+2. change appearance while the relevant window remains open;
+3. inspect dialogs, sheets, Snackbars, disabled controls, and overlays;
+4. test localized long text and accessibility focus;
+5. run PurgeTSS generation when detected and resolve unsupported classes;
+6. compile and build both platform targets before claiming completion.
 
-This approach gives you:
-- Consistent spacing and typography across the entire app
-- Theme-aware colors that change with `Alloy.Globals.theme`
-- Clean XML views without inline styles
-- A single place to update design decisions (`app.tss`)
+For exact PurgeTSS behavior, load its current `semantic-colors.md` and
+`appearance-module.md` references. For Titanium property availability, verify
+against the current `ti-api` skill.

package/skills/ti-guides/references/app-distribution.md

@@ -2,6 +2,40 @@
 
 Guide for distributing Titanium apps to Google Play (Android) and the App Store (iOS).
 
+<!-- TOC-START -->
+## Contents
+
+- [Android distribution](#android-distribution)
+  - [1. Generate keystore and certificate](#1-generate-keystore-and-certificate)
+  - [2. Verify keystore](#2-verify-keystore)
+  - [3. Build for Google Play](#3-build-for-google-play)
+  - [4. Verify APK signing](#4-verify-apk-signing)
+  - [5. Deploy to device for testing](#5-deploy-to-device-for-testing)
+  - [6. Google Play submission requirements](#6-google-play-submission-requirements)
+  - [7. SD card installation](#7-sd-card-installation)
+- [iOS distribution](#ios-distribution)
+  - [1. Distribution types](#1-distribution-types)
+  - [2. Create distribution certificate](#2-create-distribution-certificate)
+  - [3. Create distribution provisioning profile](#3-create-distribution-provisioning-profile)
+  - [4. Create App ID on App Store Connect](#4-create-app-id-on-app-store-connect)
+  - [5. Build and package](#5-build-and-package)
+  - [6. Upload to App Store Connect](#6-upload-to-app-store-connect)
+  - [7. Ad Hoc distribution](#7-ad-hoc-distribution)
+- [Mac Catalyst distribution (Mac App Store)](#mac-catalyst-distribution-mac-app-store)
+  - [1. Enable Mac Catalyst for your App ID](#1-enable-mac-catalyst-for-your-app-id)
+  - [2. Create Mac App Store Distribution Certificate](#2-create-mac-app-store-distribution-certificate)
+  - [3. Mac Catalyst build targets](#3-mac-catalyst-build-targets)
+  - [4. Build for Mac Catalyst (Development)](#4-build-for-mac-catalyst-development)
+  - [5. Build for Mac App Store (Distribution)](#5-build-for-mac-app-store-distribution)
+  - [6. Upload to Mac App Store Connect](#6-upload-to-mac-app-store-connect)
+  - [7. Create app listing in App Store Connect](#7-create-app-listing-in-app-store-connect)
+  - [8. Mac Catalyst entitlements](#8-mac-catalyst-entitlements)
+  - [9. Common issues](#9-common-issues)
+  - [10. Versioning](#10-versioning)
+  - [11. Testing on Mac](#11-testing-on-mac)
+
+<!-- TOC-END -->
+
 ## Android distribution
 
 ### 1. Generate keystore and certificate

package/skills/ti-guides/references/application-frameworks.md

@@ -2,6 +2,19 @@
 
 Framework options and architecture patterns for Titanium applications.
 
+<!-- TOC-START -->
+## Contents
+
+- [Alloy framework](#alloy-framework)
+- [Classic Titanium](#classic-titanium)
+- [Choosing a framework](#choosing-a-framework)
+- [Architecture patterns](#architecture-patterns)
+- [Framework interoperability](#framework-interoperability)
+- [Best practices](#best-practices)
+- [Resources](#resources)
+
+<!-- TOC-END -->
+
 ## Alloy framework
 
 Alloy is the official MVC framework for Titanium. It was developed by Appcelerator and is now maintained by TiDev.

package/skills/ti-guides/references/cli-reference.md

@@ -2,6 +2,22 @@
 
 Reference for Titanium CLI commands, options, and configuration.
 
+<!-- TOC-START -->
+## Contents
+
+- [Environment setup](#environment-setup)
+- [Project commands](#project-commands)
+- [Build commands](#build-commands)
+- [Distribution commands](#distribution-commands)
+- [SDK management](#sdk-management)
+- [Configuration options](#configuration-options)
+- [Common issues](#common-issues)
+- [Command quick reference](#command-quick-reference)
+- [SDK version precedence](#sdk-version-precedence)
+- [References](#references)
+
+<!-- TOC-END -->
+
 ## Environment setup
 
 ### Check environment