@maccesar/titools 2.0.0

package/skills/ti-ui/references/platform-ui-ios.md

@@ -0,0 +1,469 @@
+# iOS UI Components and Conventions
+
+## Table of Contents
+
+- [iOS UI Components and Conventions](#ios-ui-components-and-conventions)
+  - [Table of Contents](#table-of-contents)
+  - [1. Overview](#1-overview)
+  - [2. iPad-Only UI Components](#2-ipad-only-ui-components)
+    - [Popover](#popover)
+    - [Popover Events](#popover-events)
+    - [SplitWindow](#splitwindow)
+    - [SplitWindow in Portrait](#splitwindow-in-portrait)
+  - [3. Badges](#3-badges)
+    - [App Icon Badge](#app-icon-badge)
+    - [Tab Badge](#tab-badge)
+    - [Accessing Preferences in App](#accessing-preferences-in-app)
+      - [Dynamic Quick Actions](#dynamic-quick-actions)
+      - [Handling Quick Actions](#handling-quick-actions)
+    - [Peek and Pop](#peek-and-pop)
+      - [Enabling Peek and Pop](#enabling-peek-and-pop)
+      - [Preview Action Styles](#preview-action-styles)
+  - [6. Navigation Bar (iOS)](#6-navigation-bar-ios)
+    - [NavigationWindow](#navigationwindow)
+    - [Toolbar](#toolbar)
+    - [System Buttons](#system-buttons)
+  - [7. Tab Bar](#7-tab-bar)
+    - [Creating Tab Bar](#creating-tab-bar)
+    - [Tab Bar Customization (iOS)](#tab-bar-customization-ios)
+  - [8. Activity Indicator](#8-activity-indicator)
+    - [iOS-Specific Location](#ios-specific-location)
+  - [9. Platform Best Practices](#9-platform-best-practices)
+    - [Follow iOS Human Interface Guidelines](#follow-ios-human-interface-guidelines)
+    - [iOS-Specific Patterns](#ios-specific-patterns)
+  - [10. Common Issues](#10-common-issues)
+    - [Settings Not Appearing](#settings-not-appearing)
+    - [3D Touch Not Working](#3d-touch-not-working)
+    - [SplitWindow Issues](#splitwindow-issues)
+
+---
+
+## 1. Overview
+
+iOS offers several UI components and conventions that differ from Android. This guide covers iPad-specific controls, app badges, Settings integration, 3D Touch, and iOS-specific navigation patterns.
+
+## 2. iPad-Only UI Components
+
+### Popover
+
+Popovers present content temporarily without taking over the entire screen. Used for menus, options, or detail views.
+
+```javascript
+const button = Ti.UI.createButton({
+  title: 'Show popover',
+  width: 250,
+  height: 50,
+  top: 30,
+  right: 5
+});
+
+const popover = Ti.UI.iPad.createPopover({
+  width: 300,
+  height: 250,
+  title: 'Popover Content',
+  arrowDirection: Ti.UI.iPad.POPOVER_ARROW_DIRECTION_RIGHT
+});
+
+// Add content to popover
+const popoverContent = Ti.UI.createView({
+  backgroundColor: 'white'
+});
+popover.add(popoverContent);
+
+button.addEventListener('click', (e) => {
+  popover.show({
+    view: button,  // Anchor to this view
+    animated: true
+  });
+});
+
+win.add(button);
+```
+...
+### Popover Events
+
+```javascript
+popover.addEventListener('hide', (e) => {
+  Ti.API.info('Popover hidden');
+});
+
+popover.addEventListener('show', (e) => {
+  Ti.API.info('Popover shown');
+});
+
+// Dismiss programmatically
+popover.hide();
+```
+
+### SplitWindow
+
+SplitWindow manages master-detail interface (left pane list, right pane details). iPad only.
+
+```javascript
+// Master (left) window
+const masterWin = Ti.UI.createWindow({
+  backgroundColor: '#fff',
+  title: 'Master'
+});
+masterWin.add(Ti.UI.createLabel({
+  text: 'Master View - Select an item',
+  font: { fontWeight: 'bold', fontSize: 16 }
+}));
+
+// Detail (right) window
+const detailWin = Ti.UI.createWindow({
+  backgroundColor: '#dfdfdf',
+  title: 'Detail'
+});
+detailWin.add(Ti.UI.createLabel({
+  text: 'Detail View - Item details',
+  font: { fontWeight: 'bold', fontSize: 16 }
+}));
+
+// Create split window
+const splitwin = Ti.UI.iPad.createSplitWindow({
+  detailView: detailWin,
+  masterView: masterWin,
+  orientationModes: [
+    Ti.UI.LANDSCAPE_LEFT,
+    Ti.UI.LANDSCAPE_RIGHT
+  ]
+});
+
+splitwin.open();
+```
+...
+### SplitWindow in Portrait
+
+By default, master view hides in portrait. To show master view:
+
+```javascript
+splitwin.addEventListener('visible', (e) => {
+  if (e.view === 'master' && !e.visible) {
+    // Master is hidden, show it in a popover or navigation
+    splitwin.showMasterViewInPopover();
+  }
+});
+```
+
+## 3. Badges
+
+### App Icon Badge
+
+```javascript
+// Set badge to number
+Ti.UI.iOS.appBadge = 23;
+
+// Remove badge (set to null, not 0)
+Ti.UI.iOS.appBadge = null;
+
+// Note: Setting to 0 still displays "0"
+```
+
+### Tab Badge
+
+```javascript
+const tabGroup = Ti.UI.createTabGroup();
+
+const win1 = Ti.UI.createWindow({ title: 'Window 1' });
+
+const tab1 = Ti.UI.createTab({
+  icon: 'myIcon.png',
+  title: 'Tab 1',
+  window: win1,
+  badge: 10  // Show badge with number
+});
+
+// Update badge
+tab1.setBadge(5);
+tab1.badge = 5;
+
+// Clear badge
+tab1.setBadge(null);
+tab1.badge = null;
+```
+...
+### Accessing Preferences in App
+
+```javascript
+// Must match the "Key" value from Root.plist
+const name = Ti.App.Properties.getString('name_preference');
+const enabled = Ti.App.Properties.getBool('enabled_preference');
+```
+...
+#### Dynamic Quick Actions
+
+```javascript
+if (Ti.UI.iOS.forceTouchSupported) {
+  const appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
+
+  appShortcuts.addDynamicShortcut({
+    itemtype: 'com.myapp.share',
+    title: 'Share Photo',
+    subtitle: 'Share last photo',
+    icon: Ti.UI.iOS.SHORTCUT_ICON_TYPE_SHARE,
+    userInfo: {
+      action: 'share_photo',
+      photoId: '123'
+    }
+  });
+
+  // Remove specific shortcut
+  appShortcuts.removeDynamicShortcut('com.myapp.share');
+
+  // Remove all dynamic shortcuts
+  appShortcuts.removeAllDynamicShortcuts();
+}
+```
+
+#### Handling Quick Actions
+
+```javascript
+Ti.App.iOS.addEventListener('shortcutitemclick', (e) => {
+  Ti.API.info(`Shortcut clicked: ${e.itemtype}`);
+
+  switch(e.itemtype) {
+    case 'com.myapp.add':
+      addNewItem();
+      break;
+    case 'com.myapp.recent':
+      openRecent();
+      break;
+    case 'com.myapp.share':
+      sharePhoto(e.userInfo.photoId);
+      break;
+  }
+});
+```
+
+### Peek and Pop
+
+Peek provides a preview of content, Pop opens it fully.
+
+#### Enabling Peek and Pop
+
+```javascript
+if (Ti.UI.iOS.forceTouchSupported) {
+
+  const preview = Alloy.createController('preview').getView();
+  const detail = Alloy.createController('detail').getView();
+
+  const shareAction = Ti.UI.iOS.createPreviewAction({
+    title: "Share",
+    style: Ti.UI.iOS.PREVIEW_ACTION_STYLE_DEFAULT
+  });
+
+  shareAction.addEventListener('click', (e) => {
+    // Handle share action
+  });
+
+  const previewContext = Ti.UI.iOS.createPreviewContext({
+    preview: preview,
+    contentHeight: 400,
+    actions: [shareAction]
+  });
+
+  previewContext.addEventListener('peek', () => {
+    Ti.API.info('User started peeking');
+  });
+
+  previewContext.addEventListener('pop', () => {
+    Ti.API.info('User popped to full view');
+    detail.open();
+  });
+
+  // Attach to view
+  $.peekView.previewContext = previewContext;
+}
+```
+
+#### Preview Action Styles
+
+```javascript
+Ti.UI.iOS.PREVIEW_ACTION_STYLE_DEFAULT
+Ti.UI.iOS.PREVIEW_ACTION_STYLE_SELECTED  // Blue background
+Ti.UI.iOS.PREVIEW_ACTION_STYLE_DESTRUCTIVE  // Red background
+```
+
+## 6. Navigation Bar (iOS)
+
+### NavigationWindow
+
+```javascript
+const win1 = Ti.UI.createWindow({
+  backgroundColor: 'white',
+  title: 'First Window'
+});
+
+const navWindow = Ti.UI.createNavigationWindow({
+  window: win1
+});
+
+// Open second window
+const win2 = Ti.UI.createWindow({
+  backgroundColor: 'gray',
+  title: 'Second Window'
+});
+
+navWindow.openWindow(win2, { animated: true });
+
+// Close to go back
+win2.close();
+
+// Hide navigation bar
+win1.navBarHidden = true;
+```
+
+### Toolbar
+
+```javascript
+const flexSpace = Ti.UI.createButton({
+  systemButton: Ti.UI.iOS.SystemButton.FLEXIBLE_SPACE
+});
+
+const refreshButton = Ti.UI.createButton({
+  title: 'Refresh'
+});
+
+const toolbar = Ti.UI.createToolbar({
+  items: [refreshButton, flexSpace],
+  bottom: 0
+});
+
+win.add(toolbar);
+```
+
+### System Buttons
+
+```javascript
+Ti.UI.iOS.SystemButton.DONE
+Ti.UI.iOS.SystemButton.CANCEL
+Ti.UI.iOS.SystemButton.EDIT
+Ti.UI.iOS.SystemButton.SAVE
+Ti.UI.iOS.SystemButton.ADD
+Ti.UI.iOS.SystemButton.FLEXIBLE_SPACE
+Ti.UI.iOS.SystemButton.FIXED_SPACE
+// ... and more
+```
+
+## 7. Tab Bar
+
+### Creating Tab Bar
+
+```javascript
+const tabGroup = Ti.UI.createTabGroup();
+
+const tab1 = Ti.UI.createTab({
+  icon: 'home.png',
+  title: 'Home',
+  window: Ti.UI.createWindow({ backgroundColor: 'white' })
+});
+
+const tab2 = Ti.UI.createTab({
+  icon: 'settings.png',
+  title: 'Settings',
+  window: Ti.UI.createWindow({ backgroundColor: 'gray' })
+});
+
+tabGroup.addTab(tab1);
+tabGroup.addTab(tab2);
+
+tabGroup.open();
+```
+
+### Tab Bar Customization (iOS)
+
+```javascript
+tabGroup.setActiveTabIconColor('blue');
+tabGroup.setActiveTabColor('#f0f0f0');
+
+// Hide tab bar on specific window
+win1.tabBarHidden = true;
+
+// Set tab bar style (deprecated in iOS 13+)
+tabGroup.tabsStyle = Ti.UI.iOS.TABS_STYLE_BOTTOM;
+```
+
+## 8. Activity Indicator
+
+```javascript
+const activityIndicator = Ti.UI.createActivityIndicator({
+  message: 'Loading...',
+  color: 'white',
+  backgroundColor: '#333',
+  font: { fontSize: 16, fontWeight: 'bold' }
+});
+
+activityIndicator.show();
+
+// Later
+activityIndicator.hide();
+```
+
+### iOS-Specific Location
+
+```javascript
+const activityIndicator = Ti.UI.createActivityIndicator({
+  message: 'Loading...',
+  location: Ti.UI.iOS.ACTIVITY_INDICATOR_DIALOG,
+  opacity: 0.8
+});
+```
+
+## 9. Platform Best Practices
+
+### Follow iOS Human Interface Guidelines
+
+- Use NavigationWindow for hierarchical navigation
+- Use Tab Bar for top-level categories
+- Present modal views for focused tasks
+- Use Popovers for auxiliary content (iPad)
+- Respect 3D Touch conventions
+
+### iOS-Specific Patterns
+
+```javascript
+// Use system buttons for standard actions
+const doneButton = Ti.UI.createButton({
+  systemButton: Ti.UI.iOS.SystemButton.DONE
+});
+
+// Use NavigationWindow animations
+navWindow.openWindow(win2, {
+  animated: true,
+  transition: Ti.UI.iOS.NavigationWindowTransitionStyle.NONE
+});
+
+// Respect safe area (iPhone X+)
+const view = Ti.UI.createView({
+  top: Ti.Platform.displayCaps.platformHeight > 800 ? 44 : 20  // Account for notch
+});
+```
+
+## 10. Common Issues
+
+### Settings Not Appearing
+
+**Problem**: Settings not visible in Settings app
+
+**Solutions**:
+1. Clean and rebuild project
+2. Check plist syntax
+3. Ensure Settings.bundle is in platform/iphone/
+4. Kill and relaunch Settings app
+
+### 3D Touch Not Working
+
+**Problem**: 3D Touch features don't respond
+
+**Solutions**:
+1. Must test on physical 3D Touch device
+2. Check `Ti.UI.iOS.forceTouchSupported` before using
+3. Ensure iOS 9 or later
+4. Verify `previewContext` is properly attached
+
+### SplitWindow Issues
+
+**Problem**: Master view not visible in portrait
+
+**Solution**: This is default behavior. Use `showMasterViewInPopover()` or handle via NavigationWindow.

package/skills/ti-ui/references/scrolling-views.md

@@ -0,0 +1,252 @@
+# Scrolling Views
+
+## Table of Contents
+
+- [Scrolling Views](#scrolling-views)
+  - [Table of Contents](#table-of-contents)
+  - [1. ScrollView vs ScrollableView](#1-scrollview-vs-scrollableview)
+  - [2. ScrollView](#2-scrollview)
+    - [Creating a ScrollView](#creating-a-scrollview)
+    - [ScrollView Events](#scrollview-events)
+    - [Android ScrollView Direction](#android-scrollview-direction)
+  - [3. ScrollableView](#3-scrollableview)
+    - [Creating a ScrollableView](#creating-a-scrollableview)
+    - [ScrollableView Events](#scrollableview-events)
+    - [Image Gallery](#image-gallery)
+    - [Onboarding Wizard](#onboarding-wizard)
+    - [Long Form Content](#long-form-content)
+    - [Scrollable Form](#scrollable-form)
+    - [ScrollableView](#scrollableview)
+  - [8. Detecting Scroll Position](#8-detecting-scroll-position)
+  - [Best Practices](#best-practices)
+
+---
+
+## 1. ScrollView vs ScrollableView
+
+| Feature          | ScrollView                     | ScrollableView                   |
+| ---------------- | ------------------------------ | -------------------------------- |
+| Purpose          | Scrollable area of content     | Paging through multiple views    |
+| Scroll Direction | Vertical and/or horizontal     | Horizontal only                  |
+| Content Size     | `contentHeight`/`contentWidth` | Full-screen views                |
+| User Interaction | Drag to scroll                 | Swipe to snap between pages      |
+| Use Case         | Long content, forms, images    | Image gallery, onboarding wizard |
+
+## 2. ScrollView
+
+### Creating a ScrollView
+
+```javascript
+const scrollView = Ti.UI.createScrollView({
+  width: 300,
+  height: 200,
+  contentWidth: Ti.UI.SIZE,   // Auto-fit to content
+  contentHeight: Ti.UI.SIZE,  // Auto-fit to content
+  backgroundColor: 'white'
+});
+
+// Add content
+const content = Ti.UI.createView({
+  width: 500,
+  height: 500,
+  backgroundColor: 'blue'
+});
+
+scrollView.add(content);
+win.add(scrollView);
+```
+...
+### ScrollView Events
+
+```javascript
+scrollView.addEventListener('scroll', (e) => {
+  Ti.API.info('Scrolling...');
+  Ti.API.info(`Content offset: x=${e.contentOffset.x} y=${e.contentOffset.y}`);
+});
+
+scrollView.addEventListener('dragEnd', (e) => {
+  Ti.API.info('Drag ended');
+  e.source.setContentOffset({ x: 0, y: 0 }, { animated: true });
+});
+
+scrollView.addEventListener('scrollEnd', (e) => {
+  Ti.API.info('Scroll completely ended');
+  e.source.setContentOffset({ x: 0, y: 0 }, { animated: true });
+});
+```
+...
+### Android ScrollView Direction
+
+Android ScrollView can be vertical OR horizontal, not both:
+
+```javascript
+// Explicit horizontal scroll
+const scrollView = Ti.UI.createScrollView({
+  width: 300,
+  height: 200,
+  scrollType: 'horizontal',  // Android: horizontal only
+  contentWidth: 600,  // Must be larger than width
+  contentHeight: 200  // Same as height = no vertical scroll
+});
+```
+...
+## 3. ScrollableView
+
+### Creating a ScrollableView
+
+```javascript
+const view1 = Ti.UI.createView({ backgroundColor: '#123' });
+const view2 = Ti.UI.createView({ backgroundColor: '#234' });
+const view3 = Ti.UI.createView({ backgroundColor: '#345' });
+
+const scrollableView = Ti.UI.createScrollableView({
+  views: [view1, view2, view3],
+  showPagingControl: true,
+  pagingControlHeight: 30,
+  pagingControlColor: 'blue'
+});
+
+win.add(scrollableView);
+```
+...
+### ScrollableView Events
+
+```javascript
+scrollableView.addEventListener('scroll', (e) => {
+  Ti.API.info(`Current page: ${e.currentPage}`);
+  Ti.API.info(`Views: ${e.view}`);  // View object reference
+});
+
+scrollableView.addEventListener('dragEnd', (e) => {
+  Ti.API.info(`Drag ended, settled on page: ${e.currentPage}`);
+});
+```
+...
+### Image Gallery
+
+```javascript
+const images = [];
+for (let i = 1; i <= 10; i++) {
+  images.push(Ti.UI.createImageView({
+    image: `image${i}.jpg`,
+    width: Ti.UI.FILL,
+    height: Ti.UI.FILL
+  }));
+}
+
+const gallery = Ti.UI.createScrollableView({
+  views: images,
+  showPagingControl: true
+});
+```
+
+### Onboarding Wizard
+
+```javascript
+const page1 = createOnboardingPage('Welcome', 'Get started with our app');
+const page2 = createOnboardingPage('Features', 'Learn about key features');
+const page3 = createOnboardingPage('Get Started', 'Create your account');
+
+const onboarding = Ti.UI.createScrollableView({
+  views: [page1, page2, page3],
+  showPagingControl: true
+});
+
+const nextButton = Ti.UI.createButton({
+  title: 'Next',
+  bottom: 20
+});
+nextButton.addEventListener('click', () => {
+  const current = onboarding.currentPage;
+  if (current < 2) {
+    onboarding.scrollToView(current + 1);
+  } else {
+    onboarding.close();
+    showMainApp();
+  }
+});
+```
+
+### Long Form Content
+
+```javascript
+const scrollView = Ti.UI.createScrollView({
+  width: Ti.UI.FILL,
+  height: Ti.UI.FILL,
+  contentHeight: Ti.UI.SIZE,
+  layout: 'vertical'
+});
+
+// Add many components
+for (let i = 0; i < 50; i++) {
+  scrollView.add(Ti.UI.createLabel({
+    text: `Item ${i}`,
+    top: 10,
+    height: 40
+  }));
+}
+```
+
+### Scrollable Form
+
+```javascript
+const formScrollView = Ti.UI.createScrollView({
+  layout: 'vertical',
+  height: Ti.UI.FILL
+});
+
+const nameField = Ti.UI.createTextField({
+  hintText: 'Name',
+  top: 10, height: 40
+});
+
+const emailField = Ti.UI.createTextField({
+  hintText: 'Email',
+  top: 10, height: 40
+});
+
+const submitButton = Ti.UI.createButton({
+  title: 'Submit',
+  top: 10
+});
+
+formScrollView.add(nameField);
+formScrollView.add(emailField);
+formScrollView.add(submitButton);
+```
+...
+### ScrollableView
+
+```javascript
+// Move to page 2
+scrollableView.scrollToView(1);
+
+// Move to last page
+scrollableView.scrollToView(scrollableView.views.length - 1);
+
+// Get current page
+const current = scrollableView.currentPage;
+```
+
+## 8. Detecting Scroll Position
+
+```javascript
+scrollView.addEventListener('scroll', (e) => {
+  const { x, y } = e.contentOffset;
+
+  // Detect near bottom
+  const maxScroll = scrollView.contentHeight - scrollView.height;
+  if (y > maxScroll - 50) {
+    loadMoreContent();
+  }
+});
+```
+
+## Best Practices
+
+1. **Use ScrollableView** for paginated content (galleries, wizards)
+2. **Use ScrollView** for continuous scrolling content (long forms, articles)
+3. **Specify dimensions** explicitly on Android when possible
+4. **Consider performance** with large datasets
+5. **Test on real devices** - simulator behavior may differ
+6. **Use paging controls** for ScrollableView to improve UX