@maccesar/titools 2.0.0

package/skills/ti-ui/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: ti-ui
+description: "Titanium SDK UI/UX patterns and components expert. Use when working with, reviewing, analyzing, or examining Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar)."
+argument-hint: "[component]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
+---
+
+# Titanium SDK UI Expert
+
+Comprehensive expert covering all official Titanium SDK UI how-to guides. Provides guidance on cross-platform UI/UX, event handling, animations, performance optimization, and platform-specific components.
+
+## Project Detection
+
+:::info AUTO-DETECTS TITANIUM PROJECTS
+This skill automatically detects Titanium projects when invoked and provides UI/UX component guidance.
+
+**Detection occurs automatically** - no manual command needed.
+
+**Titanium project indicator:**
+- `tiapp.xml` file (required for all Titanium projects)
+
+**Applicable to BOTH:**
+- **Alloy projects** (app/ folder structure)
+- **Classic projects** (Resources/ folder)
+
+**Behavior based on detection:**
+- **Titanium detected** → Provides UI component guidance for both Alloy and Classic, ListView/TableView patterns, platform-specific UI differences
+- **Not detected** → Indicates this is for Titanium projects only, does NOT provide Titanium UI guidance
+:::
+
+## Table of Contents
+
+- [Titanium SDK UI Expert](#titanium-sdk-ui-expert)
+  - [Project Detection](#project-detection)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Reference](#quick-reference)
+  - [Critical Rules (Low Freedom)](#critical-rules-low-freedom)
+    - [Performance](#performance)
+    - [iOS Accessibility](#ios-accessibility)
+    - [Layout](#layout)
+    - [Platform-Specific Properties](#platform-specific-properties)
+    - [Event Management](#event-management)
+    - [App Architecture](#app-architecture)
+  - [Platform Differences Summary](#platform-differences-summary)
+  - [UI Design Workflow](#ui-design-workflow)
+  - [Searching References](#searching-references)
+  - [Related Skills](#related-skills)
+
+---
+
+## Quick Reference
+
+| Topic                            | Reference                                                               |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| **App Structures**               | [application-structures.md](references/application-structures.md)       |
+| Layouts, positioning, units      | [layouts-and-positioning.md](references/layouts-and-positioning.md)     |
+| Events, bubbling, lifecycle      | [event-handling.md](references/event-handling.md)                       |
+| ScrollView vs ScrollableView     | [scrolling-views.md](references/scrolling-views.md)                     |
+| **TableView**                    | [tableviews.md](references/tableviews.md)                               |
+| ListView templates & performance | [listviews-and-performance.md](references/listviews-and-performance.md) |
+| Touch, swipe, pinch, gestures    | [gestures.md](references/gestures.md)                                   |
+| Orientation handling             | [orientation.md](references/orientation.md)                             |
+| Custom fonts, attributed strings | [custom-fonts-styling.md](references/custom-fonts-styling.md)           |
+| Animations, 2D/3D matrices       | [animation-and-matrices.md](references/animation-and-matrices.md)       |
+| Icons, splash screens, densities | [icons-and-splash-screens.md](references/icons-and-splash-screens.md)   |
+| Android Action Bar, themes       | [platform-ui-android.md](references/platform-ui-android.md)             |
+| iOS Navigation, 3D Touch         | [platform-ui-ios.md](references/platform-ui-ios.md)                     |
+| VoiceOver, TalkBack, a11y        | [accessibility-deep-dive.md](references/accessibility-deep-dive.md)     |
+
+## Critical Rules (Low Freedom)
+
+### Performance
+- **NO `Ti.UI.SIZE` in ListViews**: Causes jerky scrolling. Use fixed heights.
+- **Prefer ListView over TableView** for new apps with large datasets.
+- **Batch updates**: Use `applyProperties` to reduce bridge crossing overhead.
+- **WebView in TableView**: Anti-pattern causing severe scrolling issues.
+
+### iOS Accessibility
+- **NO accessibility properties on container views**: Blocks children interaction.
+- **NO accessibilityLabel on text controls** (Android): Overrides visible text.
+
+### Layout
+- **Use `dp` units** for cross-platform consistency.
+- **Android ScrollView**: Vertical OR horizontal, not both. Set `scrollType`.
+
+### Platform-Specific Properties
+
+:::danger CRITICAL: Platform-Specific Properties Require Modifiers
+Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties WITHOUT platform modifiers causes cross-platform compilation failures.
+
+**Example of the damage:**
+```javascript
+// ❌ WRONG - Adds Ti.UI.iOS to Android project
+const win = Ti.UI.createWindow({
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
+})
+```
+
+**CORRECT approaches:**
+
+**Option 1 - TSS modifier (Alloy projects):**
+```tss
+"#mainWindow[platform=ios]": {
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+}
+```
+
+**Option 2 - Conditional code:**
+```javascript
+if (OS_IOS) {
+  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+}
+```
+
+**Properties that ALWAYS require platform modifiers:**
+- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
+- Android: `actionBar` config, any `Ti.UI.Android.*` constant
+
+**For complete platform-specific UI patterns, see** [Platform UI - iOS](references/platform-ui-ios.md) and [Platform UI - Android](references/platform-ui-android.md).
+:::
+
+### Event Management
+- **Remove global listeners** (`Ti.App`, `Ti.Gesture`, `Ti.Accelerometer`) on pause to save battery.
+- **Event bubbling**: Input events bubble up; system events do not.
+
+### App Architecture
+- **Limit tabs to 4 or less** for better UX across platforms.
+- **Use NavigationWindow for iOS** hierarchical navigation.
+- **Handle androidback** to prevent unexpected app exits.
+
+## Platform Differences Summary
+
+| Feature                | iOS                          | Android                 |
+| ---------------------- | ---------------------------- | ----------------------- |
+| 3D Matrix              | ✅ Full support               | ❌ No                    |
+| Pinch gesture          | ✅ Full support               | ⚠️ Limited               |
+| ScrollView             | Bidirectional                | Unidirectional          |
+| TableView              | ✅ Full support               | ✅ Full support          |
+| ListView               | ✅ Full support               | ✅ Full support          |
+| Default template image | Left side                    | Right side              |
+| ListView action items  | ✅ Swipe actions              | ❌ No                    |
+| Modal windows          | Fills screen, covers tab bar | No effect (always full) |
+| Navigation pattern     | NavigationWindow             | Back button + Menu      |
+
+## UI Design Workflow
+
+1. **Choose App Structure**: Tab-based (most common) or Window-based
+2. **Layout Selection**: Choose mode (composite/vertical/horizontal) based on structure
+3. **Sizing Strategy**: Assign `SIZE` or `FILL` based on component defaults
+4. **Event Architecture**: Plan bubbling, app-level events, lifecycle
+5. **Performance**: Use ListView/TableView templates, batch updates
+6. **Accessibility**: Apply a11y properties per platform requirements
+7. **Motion**: Add animations, 2D/3D transforms, transitions
+
+## Searching References
+
+When looking for specific patterns, grep these terms in reference files:
+- **App Structure**: `TabGroup`, `NavigationWindow`, `modal`, `execution context`, `androidback`
+- **Layouts**: `dp`, `Ti.UI.SIZE`, `Ti.UI.FILL`, `composite`, `vertical`, `horizontal`
+- **Events**: `addEventListener`, `cancelBubble`, `bubbling`, `Ti.App.fireEvent`
+- **TableView**: `TableView`, `TableViewRow`, `setData`, `appendRow`, `className`
+- **ListView**: `ItemTemplate`, `bindId`, `setItems`, `updateItemAt`, `marker`
+- **Gestures**: `swipe`, `pinch`, `longpress`, `shake`, `accelerometer`
+- **Animation**: `animate`, `create2DMatrix`, `create3DMatrix`, `autoreverse`
+- **Fonts**: `fontFamily`, `PostScript`, `createAttributedString`, `ATTRIBUTE_`
+- **Icons/Splash**: `DefaultIcon`, `appicon`, `nine-patch`, `drawable`, `splash`, `iTunesArtwork`, `adaptive`
+- **Android**: `Action Bar`, `onCreateOptionsMenu`, `theme`, `Material3`, `talkback`
+- **iOS**: `3D Touch`, `Popover`, `SplitWindow`, `badge`, `NavigationWindow`
+- **Accessibility**: `accessibilityLabel`, `VoiceOver`, `TalkBack`, `accessibilityHidden`
+
+## Related Skills
+
+For tasks beyond UI components, use these complementary skills:
+
+| Task                                            | Use This Skill |
+| ----------------------------------------------- | -------------- |
+| Project architecture, services, memory cleanup  | `alloy-expert` |
+| Native features (camera, location, push, media) | `ti-howtos`    |
+| Alloy MVC, data binding, widgets                | `alloy-guides` |

package/skills/ti-ui/references/accessibility-deep-dive.md

@@ -0,0 +1,242 @@
+# Accessibility (a11y) Deep Dive
+
+## Table of Contents
+
+- [Accessibility (a11y) Deep Dive](#accessibility-a11y-deep-dive)
+  - [Table of Contents](#table-of-contents)
+  - [1. Overview](#1-overview)
+  - [2. Core Accessibility Properties](#2-core-accessibility-properties)
+    - [Basic Usage](#basic-usage)
+    - [Android TalkBack](#android-talkback)
+    - [Star Rating Example](#star-rating-example)
+    - [Toggle Button Example](#toggle-button-example)
+  - [6. System-Level Accessibility Events](#6-system-level-accessibility-events)
+    - [Monitor Accessibility Changes](#monitor-accessibility-changes)
+    - [Code Patterns](#code-patterns)
+    - [Accessibility First Development](#accessibility-first-development)
+  - [9. External Resources](#9-external-resources)
+  - [10. Common Issues](#10-common-issues)
+    - [Issue: VoiceOver Can't Access Children](#issue-voiceover-cant-access-children)
+    - [Issue: TalkBack Doesn't Speak Text](#issue-talkback-doesnt-speak-text)
+    - [Issue: Complex Custom Controls Not Accessible](#issue-complex-custom-controls-not-accessible)
+    - [Issue: State Changes Not Announced](#issue-state-changes-not-announced)
+
+---
+
+## 1. Overview
+
+Accessibility ensures your app is usable by everyone, including users with visual, hearing, and motor disabilities. Titanium supports both Android TalkBack and iOS VoiceOver spoken feedback systems.
+
+## 2. Core Accessibility Properties
+
+All Titanium view elements support these accessibility properties:
+
+| Property              | Default Value                 | Description                                                                     |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
+| `accessibilityHidden` | `false`                       | If `true`, the view is ignored by the accessibility service                     |
+| `accessibilityLabel`  | Title or label of the control | Succinct label identifying the view                                             |
+| `accessibilityHint`   | -                             | Briefly describes what performing an action will do (e.g., "Closes the window") |
+| `accessibilityValue`  | State or value of the control | String describing current state (e.g., "Selected", "50 percent")                |
+
+### Basic Usage
+
+```javascript
+const button = Ti.UI.createButton({
+  title: 'Save',
+  accessibilityLabel: 'Save changes',
+  accessibilityHint: 'Saves your modifications to the server'
+});
+
+const slider = Ti.UI.createSlider({
+  min: 0,
+  max: 100,
+  value: 50,
+  accessibilityLabel: 'Volume control',
+  accessibilityValue: '50 percent'
+});
+
+// Update accessibilityValue as slider changes
+slider.addEventListener('change', (e) => {
+  slider.accessibilityValue = `${e.value.toFixed(0)} percent`;
+});
+```
+...
+### Android TalkBack
+...
+```javascript
+// GOOD - Button uses default text
+const button = Ti.UI.createButton({
+  title: 'Submit Form'
+  // accessibilityLabel NOT needed - title is spoken
+});
+
+// CUSTOM - Override default
+const button = Ti.UI.createButton({
+  title: 'Submit',
+  accessibilityLabel: 'Submit the registration form'
+});
+```
+...
+```javascript
+// BAD - Container with accessibility properties
+const container = Ti.UI.createView({
+  accessibilityLabel: 'Form container',  // DON'T DO THIS
+  accessibilityHint: 'Contains input fields'
+});
+container.add(nameField);
+container.add(emailField);
+container.add(submitButton);
+
+// GOOD - No accessibility on container, children accessible
+const container = Ti.UI.createView({
+  // No accessibility properties
+});
+container.add(nameField);
+container.add(emailField);
+container.add(submitButton);
+```
+...
+### Star Rating Example
+
+```javascript
+const starView = Ti.UI.createView({
+  width: 200,
+  height: 40,
+  accessibilityLabel: 'Rating',
+  accessibilityValue: '4 out of 5 stars',
+  accessibilityHint: 'User rating for this product'
+});
+
+// Visual representation (images or drawn stars)
+for (let i = 0; i < 5; i++) {
+  const star = Ti.UI.createImageView({
+    image: i < 4 ? 'star-filled.png' : 'star-empty.png',
+    left: i * 35,
+    accessibilityHidden: true  // Hide individual stars
+  });
+  starView.add(star);
+}
+```
+
+### Toggle Button Example
+
+```javascript
+let isMuted = false;
+const muteButton = Ti.UI.createButton({
+  title: 'Mute',
+  accessibilityLabel: 'Mute audio',
+  accessibilityValue: 'Off'  // Current state
+});
+
+muteButton.addEventListener('click', () => {
+  isMuted = !isMuted;
+  muteButton.title = isMuted ? 'Unmute' : 'Mute';
+  muteButton.accessibilityValue = isMuted ? 'On' : 'Off';
+});
+```
+
+## 6. System-Level Accessibility Events
+
+### Monitor Accessibility Changes
+
+```javascript
+Ti.App.addEventListener('accessibilitychanged', (e) => {
+  Ti.API.info(`Accessibility mode changed: ${e.enabled}`);
+  // Adjust UI behavior as needed
+  if (e.enabled) {
+    // Increase touch targets, simplify animations, etc.
+  }
+});
+```
+...
+### Code Patterns
+
+**DO**:
+```javascript
+// Provide meaningful labels
+const iconButton = Ti.UI.createButton({
+  image: 'settings.png',
+  accessibilityLabel: 'Open settings'
+});
+
+// Update state changes
+checkbox.accessibilityValue = isChecked ? 'Checked' : 'Unchecked';
+
+// Hide decorative elements
+decorativeIcon.accessibilityHidden = true;
+```
+
+**DON'T**:
+```javascript
+// Don't set accessibilityLabel for text controls (Android)
+const label = Ti.UI.createLabel({
+  text: 'Hello',
+  accessibilityLabel: 'Hello'  // REDUNDANT on Android
+});
+
+// Don't set accessibility on containers (iOS)
+const container = Ti.UI.createView({
+  accessibilityLabel: 'Container'  // BLOCKS children on iOS
+});
+```
+
+### Accessibility First Development
+
+When designing complex UIs, consider accessibility from the start:
+
+```javascript
+function createAccessibleListItem(title, subtitle, action) {
+  const item = Ti.UI.createView({
+    height: 60,
+    accessibilityLabel: title,
+    accessibilityHint: `${subtitle}. Double tap to ${action}`
+  });
+
+  const titleLabel = Ti.UI.createLabel({
+    text: title,
+    accessibilityHidden: true  // Already announced by container
+  });
+
+  const subtitleLabel = Ti.UI.createLabel({
+    text: subtitle,
+    accessibilityHidden: true  // Already announced by container
+  });
+
+  item.add(titleLabel);
+  item.add(subtitleLabel);
+  return item;
+}
+```
+
+## 9. External Resources
+
+- [Accessibility Programming Guide for iOS](https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/iPhoneAccessibility/Introduction/Introduction.html)
+- [Android Accessibility API Guide](http://developer.android.com/guide/topics/ui/accessibility/index.html)
+- [Android Accessibility Design Guide](http://developer.android.com/design/patterns/accessibility.html)
+- [W3C Web Content Accessibility Guidelines](http://www.w3.org/WAI/WCAG20/quickref/)
+
+## 10. Common Issues
+
+### Issue: VoiceOver Can't Access Children
+
+**Cause**: Container view has accessibility properties set
+
+**Solution**: Remove all accessibility properties from container views
+
+### Issue: TalkBack Doesn't Speak Text
+
+**Cause**: `accessibilityLabel` set on Label/Button overrides visible text
+
+**Solution**: Don't set `accessibilityLabel` on textual controls unless intentionally overriding
+
+### Issue: Complex Custom Controls Not Accessible
+
+**Cause**: No accessibility properties set on custom-drawn views
+
+**Solution**: Always provide `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` for custom controls
+
+### Issue: State Changes Not Announced
+
+**Cause**: `accessibilityValue` not updated when state changes
+
+**Solution**: Always update `accessibilityValue` in change event handlers