@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-howtos/references/web-content-integration.md

@@ -1,287 +0,0 @@
-# Web content integration
-
-## 1. The WebView component
-
-### WKWebView (Titanium SDK 8.0.0+)
-As of Titanium SDK 8.0.0, WKWebView is the only supported web view on iOS. UIWebView was deprecated and removed. WKWebView behaves differently, so plan for that.
-
-### Basic WebView creation
-
-Remote URL:
-```javascript
-const webview = Ti.UI.createWebView({
-  url: 'https://titaniumsdk.com'
-});
-win.add(webview);
-win.open();
-```
-
-Local HTML:
-```javascript
-const webview = Ti.UI.createWebView({
-  url: 'local.html' // Relative to Resources or app/assets/app/lib
-});
-win.add(webview);
-```
-
-Inline HTML:
-```javascript
-const webview = Ti.UI.createWebView({
-  html: '<html><body><h1>Hello</h1></body></html>'
-});
-```
-
-### Local web content with assets
-Local content can include CSS, JS, and images. Paths are relative to Resources (Classic) or app/assets/app/lib (Alloy).
-
-`local.html`:
-```html
-<html>
-  <head>
-    <link rel="stylesheet" type="text/css" href="local.css"/>
-    <script src="local.js"></script>
-  </head>
-  <body>
-    <p>Local content</p>
-  </body>
-</html>
-```
-
-### WebView properties and methods
-
-Navigation:
-- `canGoBack()` - returns true if possible to go back
-- `canGoForward()` - returns true if possible to go forward
-- `goBack()` - navigate back in history
-- `goForward()` - navigate forward in history
-
-Load control:
-- `loading` (Boolean) - current loading state
-- `reload()` - refresh the page
-- `stopLoading()` - stop loading
-- `repaint()` - force repaint
-
-Data handling:
-- `url` - local or remote URL
-- `html` - inline HTML string
-- `scalesPageToFit` - scale content to dimensions
-- `setBasicAuthentication(host, username, password)` - HTTP auth
-
-```javascript
-webView.setBasicAuthentication('myDomain.com', 'username', 'password');
-```
-
-Events:
-- `beforeload` - fires before loading begins (`e.url` contains the source)
-- `load` - fires when content has loaded
-- `error` - fires on load failures (`e.url`, `e.message`)
-
-## 2. Communication between WebViews and Titanium
-
-### Local web content communication
-
-Logging from WebView: Ti.API methods work inside local HTML.
-
-```html
-<html>
-  <body onload="Ti.API.info('Page loaded!');">
-    <p>Logging works!</p>
-  </body>
-</html>
-```
-
-Bidirectional events with `Ti.App`:
-
-In local HTML:
-```html
-<html>
-  <head>
-    <script>
-      // Listen for events from Titanium
-      Ti.App.addEventListener('app:fromTitanium', (e) => {
-        alert(e.message);
-        document.getElementById('output').textContent = e.message;
-      });
-
-      // Send event to Titanium
-      function sendToApp() {
-        Ti.App.fireEvent('app:fromWebView', {
-          message: 'Hello from WebView!'
-        });
-      }
-    </script>
-  </head>
-  <body>
-    <button onclick="sendToApp()">Send to Titanium</button>
-    <div id="output"></div>
-  </body>
-</html>
-```
-
-In Titanium:
-```javascript
-const webview = Ti.UI.createWebView({ url: 'local.html' });
-
-// Listen for events from the WebView
-Ti.App.addEventListener('app:fromWebView', (e) => {
-  alert(e.message);
-});
-
-// Send event to the WebView
-const button = Ti.UI.createButton({
-  title: 'Send to WebView'
-});
-button.addEventListener('click', () => {
-  Ti.App.fireEvent('app:fromTitanium', {
-    message: 'Hello from Titanium!'
-  });
-});
-```
-
-### Remote web content communication
-
-Titanium statements (`Ti.API`, `Ti.App`) do not work in remote HTML content.
-
-Warning: On iOS 12.0+, calling `evalJS()` synchronously from some contexts can deadlock. Prefer the async version with a callback.
-
-#### Using `evalJS()` for remote content
-Inject JavaScript and retrieve results as strings:
-
-```javascript
-const webview = Ti.UI.createWebView({ url: 'https://example.com' });
-
-webview.addEventListener('load', (e) => {
-  // Get the page title
-  const title = webview.evalJS('document.title');
-  Ti.API.info(`Page title: ${title}`);
-
-  // Get cookies
-  const cookies = webview.evalJS('document.cookie');
-  Ti.API.info(`Cookies: ${cookies}`);
-
-  // Execute a custom function
-  webview.evalJS('alert("Hello from Titanium!");');
-});
-```
-
-`evalJS()` rules:
-- Call it from the `load` event (page must be loaded)
-- Pass code as a single string
-- Returns a string (or null)
-- Use `JSON.stringify()` for complex data
-
-#### Passing data to remote content
-
-```javascript
-webview.addEventListener('load', () => {
-  const data = { user: 'John', score: 100 };
-  webview.evalJS(`window.appData = ${JSON.stringify(data)};`);
-});
-```
-
-Then in remote HTML:
-```html
-<script>
-  console.log(window.appData.user); // 'John'
-</script>
-```
-
-## 3. Performance and interaction concerns
-
-### WebView performance
-WebView consumes significant resources:
-- Each WebView has its own rendering context
-- Memory overhead is high
-- Load time is independent of content complexity
-
-Best practice: if you can recreate the content with native Titanium components, do it.
-
-### WebView in TableViews
-Anti-pattern: embedding WebViews in TableViewRows causes slow scrolling.
-
-### WebView in scrollable components
-WebViews do not behave well inside other scrollable containers (ScrollView, TableView). They consume touch events.
-
-Workaround: set `touchEnabled: false` on the WebView if it sits inside a scrollable parent:
-
-```javascript
-const webview = Ti.UI.createWebView({
-  url: 'content.html',
-  touchEnabled: false // Allow parent to handle touches
-});
-```
-
-### Viewport meta tag
-For mobile-optimized content, use the viewport meta tag:
-
-```html
-<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
-```
-
-## 4. WebView use cases
-
-Common WebView use cases:
-- HTML forms: auto-scroll to focused fields, next/previous navigation, native keyboard integration
-- Rich text or HTML email: render styled content that is hard to replicate with native labels
-- Canvas/graphics: HTML5 Canvas provides 2D drawing not available in native Titanium APIs
-- OAuth flows: load third-party auth pages in a WebView and intercept redirects
-
-### Authentication flows
-Many OAuth providers use WebView for login (for example, the Facebook module).
-
-```javascript
-const authWebView = Ti.UI.createWebView({
-  url: 'https://auth.example.com/oauth'
-});
-
-authWebView.addEventListener('load', (e) => {
-  // Detect redirect to callback URL with token
-  if (e.url.indexOf('myapp://callback') === 0) {
-    const token = extractTokenFromUrl(e.url);
-    Ti.App.fireEvent('auth:success', { token: token });
-  }
-});
-```
-
-### Canvas and graphics
-For complex graphics, use HTML5 Canvas:
-
-`local.html`:
-```html
-<canvas id="myCanvas" width="300" height="200"></canvas>
-<script>
-  const ctx = document.getElementById('myCanvas').getContext('2d');
-  ctx.fillStyle = 'green';
-  ctx.fillRect(10, 10, 150, 100);
-</script>
-```
-
-## 5. WKWebView behavioral differences (iOS)
-
-- Cookies: WKWebView uses a separate cookie store from `Ti.Network`. Cookies set via HTTPClient are not shared with WebViews.
-- `localStorage`/`sessionStorage`: not shared between the native app and the WebView. Each WKWebView has its own storage.
-- `evalJS` is async: on iOS 12.0+, synchronous `evalJS()` can deadlock. Use the callback form instead:
-
-```javascript
-webView.evalJS('document.title', (result) => {
-  Ti.API.info(`Title: ${result}`);
-});
-```
-
-- Viewport meta tag required: WKWebView needs an explicit viewport tag to scale content correctly:
-
-```html
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-```
-
-- Custom fonts: use a special `@font-face` path format in WKWebView CSS. Fonts must be in the app bundle and referenced correctly.
-- Remote HTML limitations: `Ti.API`, `Ti.App.fireEvent()`, and other Titanium calls do not work in remotely-loaded HTML. Only local HTML can communicate with the Titanium runtime.
-
-## Best practices summary
-
-1. Avoid WebViews when possible. Use native components.
-2. Never embed a WebView in a TableView.
-3. Use local content for integration. Only local content supports `Ti.App` events.
-4. Use `evalJS()` for remote content. It is the only way to interact with remote pages.
-5. Wait for the `load` event before calling `evalJS()`.
-6. Configure the viewport for proper mobile rendering.

package/skills/ti-howtos/references/webpack-build-pipeline.md

@@ -1,124 +0,0 @@
-# Webpack build pipeline
-
-> **⚠️ Appcelerator/Axway era feature**
-> The Webpack pipeline documented here was introduced with Titanium SDK 9.1.0 as part of the Axway AMPLIFY toolchain (`appcd` daemon). Since Axway discontinued Appcelerator, this feature is **not maintained** in the current TiDev CLI (`ti`). If you are using the community TiDev CLI, this pipeline may not be available. Prefer the standard `ti build` pipeline unless your project already uses Webpack.
-
-Webpack integration is an alternative build pipeline starting with Titanium SDK 9.1.0. It is optional. When enabled, Webpack manages asset and code bundling.
-
-## 1. Key benefits
-- Fast incremental builds: only changed files are processed.
-- npm support: install packages in the root and import them directly.
-- Build-time resolution: `require` calls are resolved during compilation, not at runtime.
-
-## 2. The `@` alias
-Webpack adds the `@` alias to reference the source root without deep relative paths.
-
-| Project type | Path mapped by `@` |
-| :----------- | :----------------- |
-| Alloy        | `app/lib`          |
-| Classic      | `src`              |
-
-Usage example:
-
-```javascript
-// Before (without webpack)
-import Utils from '../../utils/helper';
-
-// Now (with webpack)
-import Utils from '@/utils/helper';
-```
-
-## 3. npm dependency management
-Install a package in the project root:
-
-```bash
-npm install lodash
-```
-
-Use it in Titanium code:
-
-```javascript
-import _ from 'lodash';
-const data = _.chunk(['a', 'b', 'c', 'd'], 2);
-```
-
-## 4. Platform-specific files
-Webpack detects platform-specific files using the `filename.<platform>.js` pattern.
-
-Example:
-- `utils.js` (common)
-- `utils.ios.js` (iOS only)
-- `utils.android.js` (Android only)
-
-When you `import { func } from '@/utils'`, Webpack picks the correct version for the build target.
-
-## 5. Diagnostic web UI
-Webpack includes a web interface to analyze builds and asset sizes. Default URL: `http://localhost:1732/webpack/latest/web`
-
-## 6. Project plugins
-Webpack support is powered by plugins chosen based on project type:
-
-| Plugin                             | Purpose                 |
-| ---------------------------------- | ----------------------- |
-| `@appcd/webpack-plugin-alloy`      | Alloy project support   |
-| `@appcd/webpack-plugin-classic`    | Classic project support |
-| `@appcd/webpack-plugin-babel`      | Babel transpilation     |
-| `@appcd/webpack-plugin-typescript` | TypeScript support      |
-
-### Custom plugin configuration
-Customize with the `webpack-chain` API in `webpack.config.js`:
-
-```javascript
-module.exports = (api) => {
-  // Add a custom alias
-  api.chainWebpack((config) => {
-    config.resolve.alias.set('@utils', api.resolve('app/lib/utils'));
-  });
-};
-```
-
-Common customizations:
-- Add alias: `config.resolve.alias.set(name, path)`
-- Add loader: `config.module.rule(name).use(name).loader(loader)`
-- Delete plugin: `config.plugins.delete(name)`
-
-## 7. Advanced configuration
-Extend configuration via plugins in `package.json`:
-
-```json
-{
-  "appcdWebpackPlugins": [
-    "my-local-plugin.js"
-  ]
-}
-```
-
-## 8. Global configuration
-Configure Webpack daemon settings in `~/.appcelerator/appcd/config.json`:
-
-```json
-{
-  "webpack": {
-    "inactivityTimeout": 600000
-  }
-}
-```
-
-## 9. Troubleshooting
-
-Build seems stuck: the Webpack daemon may need a restart.
-
-```bash
-appcd exec /webpack/latest/stop
-```
-
-View build logs:
-
-```bash
-appcd logcat "*webpack*"
-```
-
-## 10. Known limitations
-- Hyperloop is not compatible with the Webpack pipeline.
-- Alloy.jmk build hooks are not supported. Use Webpack plugins instead.
-- The first build may be slower due to daemon startup.

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

@@ -1,288 +0,0 @@
-# Accessibility (a11y) deep dive
-
-## 1. Overview
-
-Accessibility makes your app usable for people with visual, hearing, and motor disabilities. Titanium works with Android TalkBack and iOS VoiceOver for spoken feedback.
-
-### Design considerations beyond screen readers
-
-- Motor disabilities often require larger tap targets (minimum 44x44 points on iOS, 48x48 dp on Android). Support alternative input methods and avoid gestures that demand precision or fast timing.
-- Color-blindness means color alone cannot carry meaning. Use text labels, icons, or patterns alongside color indicators. Test the UI in grayscale to check usability.
-- Screen magnifiers are common for low-vision users (iOS Zoom, Android Magnification). Keep layouts functional when magnified and avoid absolute positioning that breaks at large zoom levels.
-
-## 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")                |
-
-> Android note: On Android, `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` are combined (in that order) and mapped to the native `contentDescription`. TalkBack reads them as one string. VoiceOver on iOS reads them as separate announcements.
-
-### 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
-// On iOS, VoiceOver treats the entire container as ONE accessible element,
-// completely blocking access to all children inside it (nameField, emailField, etc.)
-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)
-// VoiceOver treats the container as a single element, making all children unreachable
-const container = Ti.UI.createView({
-  accessibilityLabel: 'Container'  // BLOCKS children on iOS
-});
-```
-
-### Accessibility-first development
-
-When designing complex UIs, plan accessibility at 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. Platform behavior comparison
-
-TalkBack (Android) and VoiceOver (iOS) interpret accessibility properties differently.
-
-| Element                          | TalkBack Response                                 | VoiceOver Response                                      |
-| -------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
-| Button with label "Submit"       | "Submit, button, double-tap to activate"          | "Submit, button"                                        |
-| Slider with value 50%            | "50 percent, slider"                              | "50%, adjustable"                                       |
-| Label with hint                  | Reads label + value + hint as one combined string | Reads label first, then hint as a separate announcement |
-| Checkbox, checked                | "Checked, checkbox, double-tap to toggle"         | "Checked, tick box"                                     |
-| Image with label "Profile photo" | "Profile photo"                                   | "Profile photo, image"                                  |
-
-> On Android, the three accessibility properties are concatenated into `contentDescription`, so they are read as one utterance. On iOS, VoiceOver reads them as distinct pieces with short pauses between them.
-
-## 10. Testing procedures
-
-### Android emulator
-
-The Android emulator has no built-in way to test accessibility. Use a physical device for accurate TalkBack behavior.
-
-### Android device (TalkBack)
-
-1. Open **Settings > Accessibility > TalkBack**
-2. Toggle TalkBack **On**
-3. A confirmation dialog appears; confirm to enable
-
-TalkBack gestures:
-- Tap: Select and hear the element described
-- Double-tap: Activate the selected element
-- Swipe left/right: Navigate to the previous/next element
-- Swipe up/down: Change reading granularity (characters, words, headings)
-
-To disable TalkBack, go to the same setting and toggle it off. You can also set a hardware shortcut (hold both volume keys for 3 seconds) for quick toggling during development.
-
-### iOS simulator (Accessibility Inspector)
-
-Use the Accessibility Inspector to examine elements without enabling VoiceOver.
-
-1. In Xcode, go to **Xcode > Open Developer Tool > Accessibility Inspector**
-2. Select the Simulator as the target device
-3. Hover over or tap elements to inspect their accessibility label, value, hint, and traits
-
-This is the fastest way to verify properties during development.
-
-### iOS device (VoiceOver)
-
-1. Open **Settings > Accessibility > VoiceOver**
-2. Toggle VoiceOver **On**
-
-VoiceOver gestures:
-- Tap: Select and hear the element described
-- Double-tap: Activate the selected element
-- Swipe left/right: Navigate to the previous/next element
-- Three-finger swipe: Scroll content
-- Two-finger tap: Pause/resume speech
-
-To disable VoiceOver, go to the same setting and toggle it off. You can also configure the Accessibility Shortcut (triple-click the side button) for quick toggling.
-
-## 11. 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/)
-
-## 12. Common issues
-
-### Issue: VoiceOver cannot access children
-
-Cause: A container view has accessibility properties set.
-
-Solution: Remove all accessibility properties from container views.
-
-### Issue: TalkBack does not speak text
-
-Cause: `accessibilityLabel` on a Label/Button overrides visible text.
-
-Solution: Do not set `accessibilityLabel` on textual controls unless you are intentionally overriding.
-
-### Issue: Complex custom controls are not accessible
-
-Cause: Custom-drawn views have no accessibility properties.
-
-Solution: Provide `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` for custom controls.
-
-### Issue: State changes are not announced
-
-Cause: `accessibilityValue` is not updated when state changes.
-
-Solution: Update `accessibilityValue` in change event handlers.