@maccesar/titools 2.0.6 → 2.2.0

package/skills/ti-guides/references/commonjs-advanced.md

@@ -1,5 +1,14 @@
 # CommonJS Advanced Patterns
 
+> For more on CommonJS in Titanium, see the official CommonJS Modules guide in the Titanium SDK documentation.
+
+## Definitions
+
+- **Module** - Any CommonJS-compliant module consumed in a Titanium SDK application. This can be a JavaScript file included with the app, or a native extension to Titanium which exposes a JavaScript API.
+- **Resources** - The Resources directory of a Titanium application, where user source code lives before processing by the build system. **Note**: For Alloy, CommonJS modules are placed in `app/lib`.
+- **`exports`** - A free variable within a module, to which multiple properties may be added to create a public interface.
+- **`module.exports`** - An object within a module, which may be REPLACED by an object representing the public interface to the module.
+
 ## 1. Stateful Modules (Singleton Pattern)
 
 Modules in Titanium are created once per JavaScript context and then passed by reference on subsequent `require()` calls. This makes them ideal for maintaining application state.
@@ -27,7 +36,49 @@ exports.reset = () => {
 ### Critical Note
 A module is created once **per Titanium JavaScript context**. Additional contexts create new module instances.
 
-## 2. Caching Behavior
+## 2. Native/Compiled Modules
+
+When `require()` is called, Titanium first checks for a native/compiled module before looking for a JavaScript module. Native modules take priority.
+
+Native modules are identified by a single string and configured in `tiapp.xml`:
+
+```xml
+<modules>
+  <module version="1.0">ti.paypal</module>
+</modules>
+```
+
+```javascript
+const paypal = require('ti.paypal')
+```
+
+Titanium loads `ti.paypal` as a native module and will NOT look for a JavaScript file in Resources. Only if no native module matches does Titanium fall back to JavaScript module resolution.
+
+## 3. Module Path Resolution
+
+The string passed to `require()` is treated as a path to a JavaScript file, minus the `.js` extension.
+
+**Resolution rules:**
+- **No prefix** (`require('app/lib/myModule')`) - resolved relative to the `Resources` directory (or `app/lib` in Alloy)
+- **`/` prefix** (`require('/app/lib/myModule')`) - also resolved relative to the `Resources` directory
+- **`./` or `../` prefix** (`require('./widgets/SomeView')`) - resolved relative to the current module file
+
+**Example with relative paths:**
+
+Given these files:
+- `Resources/app/ui/SomeCustomView.js`
+- `Resources/app/ui/widgets/SomeOtherCustomView.js`
+- `Resources/app/lib/myModule.js`
+
+Inside `SomeCustomView.js`:
+```javascript
+const myModule = require('../lib/myModule')
+const SomeOtherCustomView = require('./widgets/SomeOtherCustomView')
+```
+
+The `.js` extension is always omitted in `require()` calls.
+
+## 4. Caching Behavior
 
 Titanium caches the object returned by `require()` and provides the same reference without re-evaluating the code.
 
@@ -42,7 +93,7 @@ exports.createView = (args) => {
 // Bad - expecting re-evaluation
 ```
 
-## 3. ES6+ Support (SDK 7.1.0+)
+## 5. ES6+ Support (SDK 7.1.0+)
 
 Since Titanium SDK 7.1.0, you can use ES6+ module syntax. Code is transpiled to ES5 for all platforms.
 
@@ -63,7 +114,7 @@ import MyClass from 'MyClass'
 const instance = new MyClass('World')
 ```
 
-## 4. Module Composition Patterns
+## 6. Module Composition Patterns
 
 ### Exports Object Pattern
 ```javascript
@@ -90,7 +141,53 @@ class Person {
 module.exports = Person
 ```
 
-## 5. Antipatterns to Avoid
+### Utility Library Pattern
+```javascript
+// app/lib/logger.js
+exports.info = (str) => {
+  Ti.API.info(`${new Date()}: ${str}`)
+}
+
+exports.debug = (str) => {
+  Ti.API.debug(`${new Date()}: ${str}`)
+}
+```
+
+**Usage:**
+```javascript
+const logger = require('logger')
+logger.info('some log statement with a timestamp')
+```
+
+## 7. Inter-Module State Sharing
+
+When a module assigns a primitive value to `exports`, the consumer gets a **copy**, not a live reference. Subsequent changes to the internal variable are NOT reflected in the exported property.
+
+```javascript
+// app/lib/statefulModule.js
+let _stepVal = 5
+
+exports.setPointStep = (value) => {
+  _stepVal = value
+}
+
+exports.getPointStep = () => {
+  return _stepVal
+}
+
+exports.stepVal = _stepVal // This is a COPY of _stepVal (value: 5)
+```
+
+```javascript
+const stateful = require('statefulModule')
+stateful.setPointStep(10)
+Ti.API.info(stateful.getPointStep()) // 10 - correct, uses getter
+Ti.API.info(stateful.stepVal)        // 5  - still the original copy!
+```
+
+**Rule**: Always use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
+
+## 8. Antipatterns to Avoid
 
 ### Don't Assign Directly to exports
 ```javascript
@@ -114,7 +211,7 @@ exports.foo = 'bar'
 ### No Global Variables Across Modules
 Any data a module needs must be passed during construction or initialization. Never rely on globals shared across modules.
 
-## 6. Security and Scope
+## 9. Security and Scope
 
 All modules have private scope. Variables declared within the module are private unless added to `exports`.
 
@@ -127,7 +224,7 @@ exports.publicMethod = () => {
 }
 ```
 
-## 7. Node.js Compatibility
+## 10. Node.js Compatibility
 
 Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.
 

package/skills/ti-guides/references/hello-world.md

@@ -40,6 +40,7 @@ Choose template:
 - All lowercase (Android issues with uppercase)
 - No Java keywords (`case`, `package`, etc.)
 - Cannot change after publishing
+- **Platform Relationship**: On iOS, the App ID must match the Bundle Identifier; on Android, it serves as the Application Package Name
 
 ## Project Structure
 
@@ -54,11 +55,13 @@ MyApp/
 ├── platform/              # Platform-specific files
 │   ├── android/
 │   └── ios/
-├── Resources/             # Classic Titanium resources
+├── Resources/             # Code files and graphics with platform-specific subdirectories
+│   ├── android/          # Android-specific assets
+│   └── iphone/           # iOS-specific assets
 ├── i18n/                  # Internationalization
 ├── tiapp.xml             # App configuration
 ├── config.json           # Alloy config
-└── app.js                # Classic entry point
+└── app.js                # Bootstrap file loaded first when app launches
 ```
 
 ## Running Your App

package/skills/ti-guides/references/hyperloop-native-access.md

@@ -1,62 +1,455 @@
 # Hyperloop: Native API Access
 
-Hyperloop allows you to access 100% of native APIs (iOS Objective-C/Swift and Android Java/Kotlin) directly from JavaScript.
-
-## 1. Core Syntax
-- **`require('Framework/Class')`**: Access the native class.
-- **Instantiation**: Use `new Class()` or `Class.alloc().init()`.
-
-## 2. iOS (Objective-C)
-- **Method Concatenation**: Selector `addAttribute:value:range:` becomes `addAttributeValueRange(a, v, r)`.
-- **Casting**: Use `UIView.cast(proxy)` to convert a Titanium proxy to a native view.
-- **Blocks**: Pass a JavaScript function where a native block is expected.
-
-## 3. Android (Java)
-- **Activity Context**: Often required for view constructors.
-  ```javascript
-  const Activity = require('android.app.Activity');
-  const activity = new Activity(Ti.Android.currentActivity);
-  ```
-- **Interfaces**: Pass a JS object with methods matching the interface.
-- **Gradle**: Add dependencies in `app/platform/android/build.gradle`.
-- **Method Overloading**: Hyperloop automatically selects the matching overload based on parameter types.
-
-## 4. Swift Support (iOS)
-Hyperloop supports Swift classes alongside Objective-C. You can directly access Swift classes from JavaScript.
+Hyperloop allows you to access 100% of native APIs (iOS Objective-C/Swift and Android Java/Kotlin) directly from JavaScript. It is pre-packaged with the Titanium SDK and works as a native module.
+
+## 1. Requirements
+
+- **Titanium SDK**: 9.0.0+
+- **Titanium CLI**: 7.0.0+
+- **Alloy** (optional): 1.8.0+
+- **CocoaPods** (optional, iOS only): 1.0.0+
+- **Xcode location**: Must be at `/Applications/Xcode.app` -- Hyperloop uses a bundled library from Xcode to inspect available native APIs. Having Xcode in a non-default location (via `xcode-select` or Xcode preferences) while another installation exists in the default folder can cause metadata errors.
+
+## 2. Enabling Hyperloop
+
+Add the Hyperloop module to your `tiapp.xml`:
+
+```xml
+<modules>
+  <module>hyperloop</module>
+</modules>
+```
+
+The `run-on-main-thread` property should already be in `tiapp.xml` by default:
+```xml
+<property name="run-on-main-thread" type="bool">true</property>
+```
+
+> Do NOT name your app "Hyperloop" in tiapp.xml -- it is a reserved word and will cause build failures.
+
+## 3. Framework Namespace Conventions
+
+Each platform uses different `require()` conventions:
+
+**iOS** -- use `Framework/Class` with a forward slash:
+```javascript
+const UIView = require('UIKit/UIView');
+const NSBundle = require('Foundation/NSBundle');
+const UIColor = require('UIKit/UIColor');
+```
+
+**Android** -- use the full Java package with dots:
+```javascript
+const View = require('android.view.View');
+const Activity = require('android.app.Activity');
+const Context = require('android.content.Context');
+```
+
+## 4. iOS (Objective-C)
+
+### Instantiation: `new` vs `alloc().init()`
+
+- **`new Class()`**: Equivalent to `alloc().init()`. Only calls the **default** initializer (`init`).
+- **`Class.alloc().initWith*()`**: Use when you need a **special initializer** with arguments.
+
+```javascript
+const UIView = require('UIKit/UIView');
+
+// Default initializer (both are equivalent)
+const view1 = new UIView();
+const view2 = UIView.alloc().init();
+
+// Special initializer with arguments -- must use alloc().init*()
+const CGRectMake = require('CoreGraphics').CGRectMake;
+const view3 = UIView.alloc().initWithFrame(CGRectMake(0, 0, 100, 100));
+```
+
+### Named Methods (Selector Concatenation)
+
+Selectors with multiple parameters are camel-cased and colons are removed. Arguments are passed in the same order as in Objective-C.
+
+Selector `addAttribute:value:range:` becomes `addAttributeValueRange(attr, val, range)`.
+
+```javascript
+// Objective-C: [myView insertSubview:anotherView atIndex:0]
+myView.insertSubviewAtIndex(anotherView, 0);
+
+// Objective-C: [UIView animateWithDuration:1.0 animations:^{} completion:^(BOOL){}]
+UIView.animateWithDurationAnimationsCompletion(1.0, () => {
+  view.layer.opacity = 0.0;
+}, (finished) => {
+  // Animation completed
+});
+```
+
+### Properties
+
+Objective-C properties map directly to JavaScript property accessors. Auto-generated setters are also available:
+```javascript
+view.backgroundColor = UIColor.redColor;
+// or
+view.setBackgroundColor(UIColor.redColor);
+```
+
+### Casting
+
+Use `Class.cast(object)` to convert a generic return type (`NSObject` / `id`) or a Titanium proxy to a native view:
+```javascript
+const UIView = require('UIKit/UIView');
+
+// Cast a generic object
+const view = UIView.cast(someObject);
+
+// Cast a Titanium view to its native equivalent
+const tiView = Ti.UI.createView({ backgroundColor: 'red' });
+const nativeView = UIView.cast(tiView);
+```
+
+> Be careful with casting: casting to the wrong type will cause a crash.
+
+### Blocks
+
+Blocks are translated to JavaScript callback functions:
+```javascript
+const UIView = require('UIKit/UIView');
+
+UIView.animateWithDurationAnimationsCompletion(1.0, () => {
+  view.layer.opacity = 0.0;
+}, (done) => {
+  // Animation completed
+});
+```
+
+### Constants, Enumerations, and Functions
+
+Framework-level constants and enums are accessed by requiring the framework itself:
+```javascript
+const UIKit = require('UIKit');
+const unspecified = UIKit.UISemanticContentAttributeUnspecified;
+view.semanticContentAttribute = unspecified;
+```
+
+### TiApp Utility Class
+
+Access Titanium's app instance for the app delegate, key window, and app-level properties:
+```javascript
+const TiApp = require('TiApp/TiApp');
+const app = TiApp.app();
+```
+
+## 5. iOS: Creating Custom Classes
+
+Use `Hyperloop.defineClass()` to create Objective-C classes at runtime:
+
+```javascript
+// defineClass(className, superClass, protocolsArray)
+const MyView = Hyperloop.defineClass('MyView', 'UIView', ['UIAppearance']);
+```
+
+Add methods with `addMethod()`:
+```javascript
+MyView.addMethod({
+  selector: 'drawRect:',
+  instance: true,
+  arguments: ['CGRect'],
+  callback: function(rect) {
+    // Called when drawRect: is invoked
+  }
+});
+```
+
+Methods with multiple arguments and return types:
+```javascript
+MyView.addMethod({
+  selector: 'foo:bar:hello:',
+  instance: true,
+  returnType: 'void',
+  arguments: ['int', 'float', 'id'],
+  callback: function(a, b, c) {
+    // Invoked when the method is called
+  }
+});
+```
+
+`addMethod` properties:
+- **`selector`**: The Objective-C selector string
+- **`instance`**: `true` for instance methods, `false` for class methods
+- **`arguments`**: Array or String of argument types (Objective-C encoding types or general types like `float`, `int`, `id`)
+- **`returnType`**: String return type. Omit for `void`.
+- **`callback`**: The JavaScript function implementation
+
+Instantiate the custom class normally:
+```javascript
+const myView = new MyView();
+```
+
+## 6. iOS: CocoaPods Support
+
+### Installation
+
+Install CocoaPods if not already installed:
+```bash
+sudo gem install cocoapods
+```
+
+### Podfile Configuration
+
+Create a `Podfile` in your Titanium project root:
+```ruby
+# Required for CocoaPods 1.x
+install! 'cocoapods',
+         :integrate_targets => false
+
+platform :ios, '12.0'
+target 'YourProjectName' do
+    pod 'SomeLibrary'
+end
+```
+
+Replace `YourProjectName` with your actual Titanium project name.
+
+### Using the Pod
+
+```javascript
+const JBBarChartView = require('JBChartView/JBBarChartView');
+const chart = new JBBarChartView();
+chart.minimumValue = 1;
+chart.maximumValue = 100;
+```
+
+### Bitcode Handling for Ad-Hoc Builds
+
+If your build fails due to mixed Bitcode frameworks, disable Bitcode in your Podfile:
+```ruby
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    target.build_configurations.each do |config|
+      config.build_settings['ENABLE_BITCODE'] = 'NO'
+    end
+  end
+end
+```
+
+### Custom Frameworks (without CocoaPods)
+
+Drop native iOS frameworks (static or dynamic) into `app/platform/ios` (Alloy) or `platform/ios` (Classic). They will be automatically detected and linked.
+
+## 7. iOS: Swift Support
+
+Hyperloop supports Swift classes alongside Objective-C:
 - Swift and Objective-C classes can be mixed in the same app
 - Use the same `require()` syntax for Swift classes
+- For Swift frameworks via CocoaPods, use the `use_frameworks!` flag in your Podfile
+
+## 8. iOS: XIB and Storyboards
+
+XIB files and Storyboards must be programmatically loaded. Place them in `app/assets/iphone` (Alloy) or `Resources/iphone` (Classic) and they will be compiled automatically.
 
-## 5. XIB and Storyboards (iOS)
-XIB files and Storyboards are supported but must be programmatically loaded:
 ```javascript
-// Load XIB example
-const NSBundle = require('Foundation.NSBundle');
-const UINib = require('UIKit.UINib');
+const NSBundle = require('Foundation/NSBundle');
+const UINib = require('UIKit/UINib');
 
-const nib = UINib.nibWithNibName_bundle('MyView', NSBundle.mainBundle);
-const objects = nib.instantiateWithOwner_options(null, null);
+const nib = UINib.nibWithNibNameBundle('MyView', NSBundle.mainBundle);
+const objects = nib.instantiateWithOwnerOptions(null, null);
 ```
 
-## 6. Debugging Hyperloop
+The following resources are compiled automatically: `*.storyboard`, `*.xcdatamodel`, `*.xcdatamodeld`, `*.xcmappingmodel`, `*.xib`.
+
+## 9. iOS: Customizing the Xcode Build
+
+Use `appc.js` in the project root to pass custom flags to `xcodebuild`:
+```javascript
+module.exports = {
+  hyperloop: {
+    ios: {
+      xcodebuild: {
+        flags: {
+          GCC_PREPROCESSOR_DEFINITIONS: 'foo=bar'
+        }
+      }
+    }
+  }
+};
+```
 
-### Limitations
-- Studio debugging capabilities are limited for Hyperloop code
-- Hyperloop modifies source files during build, which throws debuggers off track
-- Breakpoints may not hit correctly in main listview click events
+## 10. Android (Java)
 
-### Workarounds
-- **iOS**: Use Safari Web Inspector for debugging up to the native transition point
-- **Android**: Use Chrome DevTools (SDK 7.0.0+)
-- Note: No source maps available for processed Alloy controllers
+### Activity Context
 
-## 7. TiApp Utility Class (iOS)
-The `TiApp` utility class provides access to Titanium's app instance:
+Most Android view constructors require an Activity context:
 ```javascript
-const TiApp = require('TiApp.TiApp');
-const app = TiApp.app();
+const Activity = require('android.app.Activity');
+const activity = new Activity(Ti.Android.currentActivity);
+```
+
+### Methods and Fields
+
+Java methods map to JavaScript functions. Java fields map to JavaScript property accessors. Static methods and constants are attached to the class type:
+```javascript
+const View = require('android.view.View');
+const generatedId = View.generateViewId(); // static method
+```
+
+### Method Overloading
+
+Hyperloop automatically selects the matching overload based on parameter types. It is slightly more liberal with numeric primitives due to JavaScript Number conversion.
+
+### Casting
+
+Pass the object to the constructor of the target type:
+```javascript
+const View = require('android.view.View');
+
+// Cast a generic Object to a View
+const view = new View(someObject);
+
+// Cast a Titanium view to native
+const tiView = Ti.UI.createView({ backgroundColor: 'red' });
+const nativeView = new View(tiView);
+```
+
+### Interfaces
+
+Implement Java interfaces by passing a JavaScript object with matching method names:
+```javascript
+const OnTouchListener = require('android.view.View.OnTouchListener');
+const listener = new OnTouchListener({
+  onTouch: (v, event) => {
+    // Handle touch
+    return true;
+  }
+});
+```
+
+### Creating Custom Classes (Android)
+
+Use `.extend()` on the class to subclass, passing an object with method overrides:
+```javascript
+const Activity = require('android.app.Activity');
+const View = require('android.view.View');
+const activity = new Activity(Ti.Android.currentActivity);
+
+const MyView = View.extend({
+  onDraw: function(canvas) {
+    this.super.onDraw(canvas);
+    // Custom drawing implementation
+  }
+});
+const customView = new MyView(activity);
+```
+
+## 11. Android: Native XML Layouts
+
+### Creating the Layout
+
+Place XML layout files in `app/platform/android/res/layout/` (Alloy) or `platform/android/res/layout/` (Classic).
+
+Example `main_content.xml`:
+```xml
+<androidx.coordinatorlayout.widget.CoordinatorLayout
+    android:id="@+id/main_content"
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <ListView
+        android:id="@+id/lvToDoList"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+
+    <com.google.android.material.floatingactionbutton.FloatingActionButton
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_gravity="bottom|right"
+        android:layout_margin="16dp" />
+</androidx.coordinatorlayout.widget.CoordinatorLayout>
 ```
 
-Useful for accessing the app delegate, key window, and app-level properties.
+### Inflating the Layout
+
+```javascript
+const Activity = require('android.app.Activity');
+const Context = require('android.content.Context');
+const Inflater = require('android.view.LayoutInflater');
+
+const activity = new Activity(Ti.Android.currentActivity);
+const inflater = Inflater.cast(
+  activity.getApplicationContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
+);
+
+// getIdentifier(name, defType, defPackage) retrieves the R.layout.* ID
+const resId = activity.getResources().getIdentifier('main_content', 'layout', activity.getPackageName());
+const view = inflater.inflate(resId, null);
+
+// Add to a Titanium view
+$.myView.add(view);
+```
+
+`getIdentifier()` also works for other resource types: `R.color.*`, `R.string.*`, `R.drawable.*`, etc.
+
+## 12. Android: Third-Party Libraries
+
+### AndroidX Requirement
+
+As of Titanium SDK 9.0.0, you must use **AndroidX** libraries. Google's deprecated Support libraries (`android.support.*`) are no longer supported.
+
+### Gradle Dependencies (Preferred)
+
+Add a `build.gradle` file to `app/platform/android/` (Alloy) or `platform/android/` (Classic):
+
+```groovy
+dependencies {
+    implementation 'com.google.android.material:material:1.1.0'
+}
+```
+
+### Local JAR/AAR Dependencies
+
+Place JAR and AAR files directly in `app/platform/android/` (Alloy) or `platform/android/` (Classic). Hyperloop will automatically:
+- Load Java classes and generate bindings
+- For AARs: extract resources, assets, `*.so` libraries, and merge `AndroidManifest.xml`
+
+### Third-Party Library Example
+
+```javascript
+// After adding the AAR to app/platform/android/
+const Activity = require('android.app.Activity');
+const ParkedTextView = require('com.goka.parkedtextview.ParkedTextView');
+
+const activity = new Activity(Ti.Android.currentActivity);
+const parkedView = new ParkedTextView(activity);
+parkedView.setParkedText('.slack.com');
+parkedView.setHintText('your-team');
+
+// Listen to events via interfaces
+const TextWatcher = require('android.text.TextWatcher');
+const watcher = new TextWatcher({
+  onTextChanged: () => { console.log('Changed'); },
+  afterTextChanged: (s) => { console.log('After:', s); },
+  beforeTextChanged: () => { console.log('Before'); }
+});
+parkedView.addTextChangedListener(watcher);
+
+$.myView.add(parkedView);
+```
+
+## 13. Debugging Hyperloop
+
+- **iOS**: Use **Safari Web Inspector** to debug Hyperloop code up to the native transition point
+- **Android**: Use **Chrome DevTools** for JavaScript debugging
+- Breakpoints may not hit correctly in all cases because Hyperloop modifies source files during the build process
+- No source maps are available for processed Alloy controllers
+
+## 14. Performance Tips
+
+- Do NOT use Hyperloop for things Titanium already does well
+- Use it for specialized APIs: custom UI components, hardware access not covered by modules, or native third-party library integration
+- Existing Titanium modules (Java for Android, Objective-C for iOS) continue to be fully supported alongside Hyperloop
+
+## 15. Sample Projects
+
+The official cross-platform example app demonstrates native APIs for iOS and Android, including CocoaPods, Android AAR packages, UICollectionView, Beacons, BottomNavigationView, native XML layouts, Storyboards, XIBs, and more:
 
-## 8. Performance Tip
-Don't use Hyperloop for things Titanium already does well. Use it for specialized APIs (e.g., custom UI components or hardware access not covered by modules).
+- **Repository**: `https://github.com/tidev/hyperloop-examples`
+- **Community modules**: `https://github.com/hyperloop-modules` -- JavaScript wrappers around native APIs (Speech, Mapbox, Snackbar, etc.)