@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-howtos/references/using-modules.md

@@ -1,181 +1,125 @@
 # Using modules
 
-Guide to obtaining, installing, and using Titanium modules to extend app functionality.
+Based on the [current official guide](https://titaniumsdk.com/docs/build/modules.md). Examples target released SDK 13.4.1; verify the selected SDK before adopting version-specific behavior.
 
-## Obtaining modules
+Two different things get added to a Titanium project and both are called
+dependencies.
 
-### Sources of modules
+A **native module** wraps platform code the core SDK does not expose: Bluetooth,
+maps, barcodes. It ships as a built binary per platform.
 
-Official modules:
-- Enterprise Extensions
-  - InAppBilling (Android)
-  - StoreKit (iOS)
-  - Barcode (iOS/Android)
-  - Compression (iOS/Android)
-  - OpenGL (iOS)
-  - AirPrint (iOS)
+An **npm package** is JavaScript. If it runs without Node's built-ins and
+without a browser, it will probably run here.
 
-Open-source modules:
-- GitHub: tidev
-  - https://github.com/tidev/ti.admob - AdMob ads
-  - https://github.com/tidev/ti.map - Native maps
-  - And more in the org
+## Native modules
 
-Community modules:
-- From Zero To App list: https://fromzerotoapp.com/modules/
-- Curated list of modules maintained by Michael Gangolf
+The [modules directory](https://titaniumsdk.com/modules.md) lists what TiDev maintains. Installing one is
+three steps: unpack it, declare it, require it.
 
-Marketplace: The original Appcelerator Marketplace is no longer available. Find community modules on GitHub and npm. A curated list is at https://fromzerotoapp.com/modules/.
+> [!NOTE]
+> There is no install command yet. `ti module` has one subcommand, `list`, so
+> unpacking is done by hand. `ti module install` and `ti module search` are
+> planned; until they ship, this is the path.
 
-### Pre-installed modules
-Some modules ship with the SDK and do not need separate installation: `ti.map`, `ti.identity`, `ti.webdialog`, `ti.applesignin`.
+Download the release archive for the module and extract it beside `tiapp.xml`, preserving its directory prefix. If it already contains `modules/`, do not create a second `modules/modules` level. The resulting layout is:
 
-## Installing modules
-
-### Single project installation
-1. Copy the module ZIP to your app root folder.
-2. Add the module to `tiapp.xml` (see configuration below).
-3. Build the project. The ZIP is extracted automatically.
-
-### Global installation (all projects)
-Modules install to platform-specific locations:
-
-| Operating system | Path                                     |
-| ---------------- | ---------------------------------------- |
-| macOS            | `~/Library/Application Support/Titanium` |
-| Windows          | `%ProgramData%\Titanium\mobilesdk\win32` |
+```
+modules/
+  android/ti.map/5.7.0/
+  iphone/ti.map/7.3.1/
+```
 
-Show hidden Library folder on macOS:
+That is `modules/<platform>/<id>/<version>/`, and the platform directory is
+`android`, `iphone` or `commonjs` - `iphone` covers iPad and macOS too.
 
-```bash
-# Permanently show
-chflags nohidden ~/Library/
+Check the CLI can see it:
 
-# Open once
-open ~/Library
+```sh
+ti module list
 ```
 
-## Configuring your app
+It reports three scopes - project, configured paths, and global - so the output
+also tells you which copy a build will pick up.
 
-### Updating tiapp.xml
-
-Using Studio/IDE:
-1. Open `tiapp.xml`.
-2. Go to the Overview tab.
-3. Click the plus button in Modules.
-4. Select module and version.
-5. Save.
-
-Manually (XML):
+Then declare it in `tiapp.xml`, per platform:
 
 ```xml
 <modules>
-  <module version="3.0.2" platform="ios">ti.map</module>
-  <module version="5.0.0" platform="android">ti.admob</module>
+  <module platform="android">ti.map</module>
+  <module platform="iphone">ti.map</module>
 </modules>
 ```
 
-Attributes:
-- `version`: must match the module manifest
-- `platform`: "ios" or "android"
-
-### Selecting module versions
-If multiple versions are installed, select specific versions per platform and build type (development/production).
-
-In Studio, double-click the module to open the Module Properties dialog.
+Both steps are needed. A module on disk that `tiapp.xml` does not name is not
+built in, and missing/incompatible modules can fail at build time or during `require`; inspect the actual diagnostic.
 
-### Enable debugger (for native modules)
-Required for debugging native modules:
+Then require it by id:
 
-```xml
-<ti:app>
-  <android xmlns:android="http://schemas.android.com/apk/res/android">
-    <manifest>
-      <application android:debuggable="true">
-      </application>
-    </manifest>
-  </android>
-</ti:app>
+```js
+const Map = require('ti.map');
 ```
 
-## Using a module
-
-### Loading the module (ES5)
+Pin a version when more than one is unpacked and you care which one you get:
 
-```javascript
-const Module = require('module.id');
-// Example: const Map = require('ti.map');
+```xml
+<module platform="android" version="5.7.0">ti.map</module>
 ```
 
-### Loading the module (ES6+)
+Without a version the newest installed copy wins, which means a machine with
+two versions in `modules/` and a colleague's machine with one can produce
+different builds from the same commit.
 
-```javascript
-import Module from 'module.id'
-// Example: import Map from 'ti.map'
-```
+> [!IMPORTANT]
+> A module is native code, so it is built for specific platforms and against a
+> range of SDK versions. A module that has not been rebuilt for a newer Titanium
+> SDK may fail at build time with a linker error rather than anything that names
+> the module. Check the module's own page for the versions it supports.
 
-Important: do not include the `.js` extension in the module ID.
+### Where modules live
 
-### Using module functionality
-After requiring, use the module's API:
+`modules/<platform>/<moduleid>/<version>/` in the project, which is committed
+like any other source. Some teams keep them out of version control and install
+in CI instead; either works, as long as the whole team does the same thing.
 
-```javascript
-// ES6+ example with ti.admob
-const Admob = require('ti.admob');
+Unpacking into the global directory instead makes the module available to every
+project on that machine and to nobody else's, which makes a build depend on the
+machine it runs on. Prefer the project-local copy. On macOS the global one is
+`~/Library/Application Support/Titanium/modules`, and `ti module list` prints
+the full path of everything it finds.
 
-const adview = Admob.createView({
-  top: 0,
-  testing: true,
-  adBackgroundColor: 'black',
-  primaryTextColor: 'blue',
-  publisherId: 'YOUR_PUBLISHER_ID'
-});
+## npm packages
 
-win.add(adview);
-```
-
-### Module patterns
+`package.json` in the project root, and `npm install` as normal:
 
-Singleton pattern:
-```javascript
-const admob = require('ti.admob');
-admob.createView({ ... });
+```sh
+npm install lodash
 ```
 
-Constructor pattern:
-```javascript
-const Map = require('ti.map');
-const view = Map.createView({ ... });
+```js
+const _ = require('lodash');
 ```
 
-Refer to module documentation for its specific API.
+Titanium bundles what is in `node_modules` at build time. Production dependencies are copied from the installed tree. Development dependencies and packages marked `titanium.ignore` or `titanium.type: native-module` are excluded; optional and peer dependencies are included by default. Runtime compatibility still needs checking.
 
-## Troubleshooting
+**What will not work:** anything that needs Node's built-ins (`fs`, `net`,
+`child_process`), anything that needs a DOM, and anything shipping native
+bindings. A package that only touches `Ti.*` and plain JavaScript is fine.
+Check before adopting a large dependency; the failure arrives at runtime as an
+undefined require.
 
-### "Requested module not found"
-Solutions:
-1. Check module ID spelling in `require()`.
-2. Verify the module is added to `tiapp.xml`.
-3. Confirm the module is installed (global or local path).
-4. Remove the `version` attribute to use the latest version.
+Keep `node_modules` out of version control as you would anywhere else.
 
-### Version conflicts
-If multiple versions exist, specify the exact version in `tiapp.xml`, or remove the version attribute to use the latest.
+## Which one do I need
 
-### Platform-specific issues
-- iOS: the module must support the iOS SDK version you are using.
-- Android: the module manifest `platform` must match the target.
+If it talks to hardware, the operating system, or a platform SDK, it is a
+native module and somebody has to have written it. If it is an algorithm, a
+parser, or a client for an HTTP API, it is probably an npm package.
 
-### Clean build
-Sometimes needed after installing modules:
+If neither exists, writing a native module is covered under Extending Titanium.
 
-```bash
-# Clean and rebuild
-ti clean
-```
+## Next
 
-## Best practices
+[Debugging and profiling](https://titaniumsdk.com/docs/build/debugging.md) covers finding out why the
+thing you just added is not working.
 
-1. Pin versions for production.
-2. Check compatibility with your Titanium SDK version.
-3. Test on devices. Some modules behave differently on simulator vs device.
+Contract correction: [released module copier](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/cli/lib/module-copier.js).

package/skills/ti-ui/SKILL.md

@@ -1,159 +1,44 @@
 ---
 name: ti-ui
-description: "Use when working with, reviewing, analyzing, or examining Titanium SDK UI/UX patterns and components — 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). AUTO-DETECT: If tiapp.xml exists, invoke BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
-argument-hint: "[component]"
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
+description: 'Use when working with Titanium SDK native UI layouts, ListView or TableView, app icons and launch screens, navigation, tabs, Android back handling, safe areas, or platform-specific UI conventions in Classic or Alloy projects.'
 ---
 
-# Titanium SDK UI expert
+# Titanium SDK user interface
 
-A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.
+Use the current official UI guides for Titanium Classic and Alloy. Titanium controls are native views; its layout system is shared across platforms and differs from CSS.
 
-> **When "new UI" means new files, run the `ti-reuse-first` skill first.** A new window, panel or dialog is often an existing one that needs a parameter, and a layout computed in JavaScript is often a TSS condition. This guide covers how to build whatever survives that question.
+Before creating new UI files, use `ti-reuse-first` to check existing screens and components.
 
-## Project detection
+## Required workflow
 
-> **️ℹ️ auto-detects titanium projects**
-> This skill detects Titanium projects and provides UI guidance.
->
-> Detection happens automatically. You do not need to run a command.
->
-> Titanium project indicator:
-> - `tiapp.xml` (required for all Titanium projects)
->
-> Applicable to both:
-> - Alloy projects (app/ folder structure)
-> - Classic projects (Resources/ folder)
->
-> Behavior based on detection:
-> - Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
-> - Not detected: State this is for Titanium projects only and skip UI guidance
+1. Confirm the project has `tiapp.xml` and identify its selected SDK.
+2. Open the relevant reference below before giving instructions or editing UI.
+3. Cite the reference used as `[source: references/<file>.md]`. Read the linked release-specific API when a property, event, default or platform restriction matters.
+4. For a topic not covered by these guides, consult `ti-api` and the current official API. Do not reconstruct an unpublished guide from archived recipes or memory. Mark an unverified claim `FROM_MEMORY (unverified):` if it cannot be checked.
+5. Verify the affected layout on its intended platform before claiming visual correctness.
 
-## Quick reference
+## Guide routing
 
-| 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)     |
+| Task | Reference |
+| --- | --- |
+| Native UI model and guide selection | [User interface](references/user-interface.md) |
+| Composite, vertical, horizontal layouts; units, sizing, measurement | [Layout and positioning](references/layouts-and-positioning.md) |
+| ListView templates, sections, items, events; choosing TableView | [Lists and tables](references/listviews-and-performance.md) |
+| iOS and Android app icons, launch screens, app name | [Icons and launch screens](references/icons-and-splash-screens.md) |
+| NavigationWindow, Android activities/back, bars, tabs, safe areas, platform branches | [Platform conventions](references/platform-conventions.md) |
 
-## Critical rules
+## Sources and release scope
 
-### Performance
-- Do not use `Ti.UI.SIZE` in ListViews. It causes jerky scrolling. Use fixed heights.
-- Prefer ListView over TableView for new apps with large datasets.
-- Batch updates with `applyProperties` to reduce bridge overhead.
-- Avoid WebView inside TableView. It kills scrolling performance.
+These references follow the current [official UI documentation](https://titaniumsdk.com/docs/build/ui), maintained in [tidev/titaniumsdk.com](https://github.com/tidev/titaniumsdk.com/tree/main/content/docs/build/ui). Use the pages' `.md` versions when reading them with an agent. The guide corpus identifies SDK 13.4.1; SDK 14-only instructions require its released contracts before use.
 
-### iOS accessibility
-- Do not set accessibility properties on container views. It blocks child interaction.
-- Do not set `accessibilityLabel` on text controls on Android. It overrides visible text.
-
-### Layout
-- Use `dp` units for cross-platform consistency.
-- Android ScrollView is vertical or horizontal, not both. Set `scrollType`.
-
-### Platform-specific properties
-
-> **🚨 critical: platform-specific properties require modifiers**
-> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers will crash cross-platform compilation.
->
-> Example of the damage:
-> ```javascript
-> // Wrong: adds Ti.UI.iOS to an Android build
-> const win = Ti.UI.createWindow({
->   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> })
-> ```
->
-> 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 platform-specific UI patterns, see [platform-ui-ios.md](references/platform-ui-ios.md) and [platform-ui-android.md](references/platform-ui-android.md).
-
-### Event management
-- Remove global listeners (`Ti.App`, `Ti.Gesture`, `Ti.Accelerometer`) on pause to save battery.
-- Input events bubble up. System events do not.
-
-### App architecture
-- Limit tabs to 4 or fewer for better UX across platforms.
-- Use NavigationWindow for iOS hierarchical navigation.
-- Handle `androidback` to prevent unexpected exits.
-
-## Platform differences summary
-
-| Feature                | iOS                          | Android                 |
-| ---------------------- | ---------------------------- | ----------------------- |
-| 3D Matrix              | Full support                 | No support              |
-| 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 or window-based
-2. Pick a layout mode: composite, vertical, or horizontal
-3. Decide sizing: `SIZE` or `FILL` based on component defaults
-4. Plan events: bubbling, app-level events, lifecycle
-5. Optimize performance: templates, batch updates
-6. Apply accessibility per platform
-7. Add motion: animations, 2D/3D transforms, transitions
-
-## Searching references
-
-When you need specific patterns, grep these terms in the 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`
+The [release-specific API](https://titaniumsdk.com/docs/sdk/13.4.1) resolves property and platform details when a guide disagrees. In particular, iOS `Window.extendSafeArea` defaults to `true`; set `false` when content should stay within the safe area. PNG icons are the supported baseline here; do not assume a newer icon format works in SDK 13.4.1.
 
 ## Related skills
 
-For work beyond UI components, use these skills:
-
-| Task                                            | Use this skill |
-| ----------------------------------------------- | -------------- |
-| Project architecture, services, memory cleanup  | `ti-expert`    |
-| Native features (camera, location, push, media) | `ti-howtos`    |
-| Alloy MVC, data binding, widgets                | `alloy-guides` |
+| Task | Skill |
+| --- | --- |
+| Properties, methods, events, accessibility, gestures, animations and other UI API contracts | `ti-api` |
+| Alloy views, styles and data binding | `alloy-guides` |
+| Configuration, SDK setup and distribution | `ti-guides` |
+| Location, media, notifications and other native integrations | `ti-howtos` |
+| Existing component discovery | `ti-reuse-first` |