@maccesar/titools 2.0.0

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

@@ -0,0 +1,100 @@
+# Hello World - Project Creation
+
+Quick guide to creating your first Titanium project.
+
+## Creating a New Project
+
+### Using CLI
+
+```bash
+ti create -t app --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE>
+```
+
+**Example:**
+```bash
+ti create -t app --id com.example.hello -n HelloWorld -p android,ios -d ~/Projects
+```
+
+### Using Studio/VS Code
+
+**File** > **New** > **Mobile App Project**
+
+Choose template:
+- **Alloy** - MVC framework (recommended)
+- **Classic** - No framework
+
+## Project Fields
+
+| Field                  | Description             | Rules                      |
+| ---------------------- | ----------------------- | -------------------------- |
+| **Project name**       | App name shown to users | -                          |
+| **App ID**             | Reverse domain notation | `com.company.appname`      |
+| **Company URL**        | Your website            | -                          |
+| **SDK Version**        | Titanium SDK to use     | Use latest                 |
+| **Deployment Targets** | Platforms to support    | android, ios, ipad, iphone |
+
+### App ID Naming Guidelines
+
+- Use Java Package Name style: `com.yourdomain.yourappname`
+- No spaces or special characters
+- All lowercase (Android issues with uppercase)
+- No Java keywords (`case`, `package`, etc.)
+- Cannot change after publishing
+
+## Project Structure
+
+```
+MyApp/
+├── app/                    # Alloy app source
+│   ├── assets/            # Images, fonts
+│   ├── controllers/       # JS controllers
+│   ├── models/           # Backbone models
+│   ├── views/            # XML views
+│   └── styles/           # TSS styles
+├── platform/              # Platform-specific files
+│   ├── android/
+│   └── ios/
+├── Resources/             # Classic Titanium resources
+├── i18n/                  # Internationalization
+├── tiapp.xml             # App configuration
+├── config.json           # Alloy config
+└── app.js                # Classic entry point
+```
+
+## Running Your App
+
+### iOS Simulator
+```bash
+ti build -p ios -C "iPhone 15"
+```
+
+### Android Emulator
+```bash
+ti build -p android -C "Pixel_4_API_34"
+```
+
+### Physical Device
+```bash
+ti build -p ios -T device
+ti build -p android -T device
+```
+
+## Simulator vs Emulator
+
+- **iOS Simulator**: The software simulates the environment within an iOS device. It's an OS X executable that runs your cross-compiled code.
+- **Android Emulator**: Provides a virtual hardware environment that runs the actual Android OS and platform components.
+
+**CRITICAL**: Neither environment is a perfect representation of a physical device. Always test on real hardware before publishing.
+
+## How Titanium Works (Under the Covers)
+
+1. **Pre-compile**: JavaScript is minified and statically analyzed to build a dependency hierarchy of Titanium APIs used.
+2. **Stub Generation**: A front-end compiler creates native stub files, native project files, and platform-specific code necessary for compilation.
+3. **Native Build**: Titanium calls platform-specific compilers (e.g., `xcodebuild` for iOS, Gradle for Android) to build the final native application.
+4. **Encryption**: JavaScript code is encrypted when building for "production" (release) or for device. Original code is not retrievable in human-readable form.
+
+## Best Practices
+
+1. **Always test on physical devices** - Simulator/emulator isn't perfect
+2. **Use Alloy for new projects** - Better structure and maintainability
+3. **Keep App ID consistent** - Match Bundle ID (iOS) and Package ID (Android)

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

@@ -0,0 +1,62 @@
+# 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.
+- Swift and Objective-C classes can be mixed in the same app
+- Use the same `require()` syntax for Swift classes
+
+## 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 nib = UINib.nibWithNibName_bundle('MyView', NSBundle.mainBundle);
+const objects = nib.instantiateWithOwner_options(null, null);
+```
+
+## 6. Debugging Hyperloop
+
+### 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
+
+### 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
+
+## 7. TiApp Utility Class (iOS)
+The `TiApp` utility class provides access to Titanium's app instance:
+```javascript
+const TiApp = require('TiApp.TiApp');
+const app = TiApp.app();
+```
+
+Useful for accessing the app delegate, key window, and app-level properties.
+
+## 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).

package/skills/ti-guides/references/javascript-primer.md

@@ -0,0 +1,411 @@
+# JavaScript Development Primer
+
+Essential JavaScript concepts, resources, and best practices for Titanium development.
+
+## Table of Contents
+1. [JavaScript Overview](#javascript-overview)
+2. [Learning Resources](#learning-resources)
+3. [Best Practices](#best-practices)
+4. [Common Patterns](#common-patterns)
+
+---
+
+## JavaScript Overview
+
+JavaScript is the language of Titanium. It's a powerful, lightweight, dynamic object-oriented programming language.
+
+**Why JavaScript for Titanium?**
+- One of the most widely deployed languages (every web browser)
+- Large community of developers
+- Dynamic typing with duck typing
+- Functional programming support
+- Convenient object literal notation
+- Closures for encapsulation
+- Small learning curve
+
+**JavaScript in Titanium:**
+- No DOM manipulation (that's web-specific)
+- Access to native APIs via Titanium namespace
+- ECMAScript 5/6 compliant
+- Same JavaScript you use in web, but targeting mobile apps
+
+---
+
+## Learning Resources
+
+### Online Courses
+
+- **[Codecademy](https://www.codecademy.com/learn/introduction-to-javascript)** - Interactive JavaScript tutorials
+- **[Stanford CS101](http://www.stanford.edu/class/cs101/)** - Uses JavaScript, lecture notes and projects available
+- **[edX](https://www.edx.org/learn/javascript)** - Free courses from top universities
+
+### Online Books & References
+
+- **[Eloquent JavaScript](https://eloquentjavascript.net/)** - Excellent learning resource (free online, or buy the book)
+- **[MDN JavaScript Guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide)** - Comprehensive JavaScript documentation
+- **[Douglas Crockford's Resources](http://javascript.crockford.com/)** - From the creator of JSON and JSLint
+- **[JavaScript in 10 Minutes](https://github.com/spencertipping/js-in-ten-minutes)** - Dense advanced guide
+- **[Google JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml)** - Code style guidelines
+- **[Learning Advanced JavaScript](http://ejohn.org/apps/learn/)** - By John Resig (jQuery creator)
+
+### Print Books (Recommended)
+
+- **JavaScript: The Good Parts** (Douglas Crockford) - ESSENTIAL
+- **JavaScript: The Definitive Guide** (David Flanagan) - Complete reference
+- **JavaScript Patterns** (Stoyan Stefanov) - Design patterns
+- **Eloquent JavaScript** (Marijn Haverbeke) - Also available free online
+
+---
+
+## Best Practices
+
+### Don't Pollute the Global Scope
+
+**BAD:** Everything in global scope
+```javascript
+const key = 'value';
+const foo = 'bar';
+
+function helper() {
+    // help out
+}
+
+function info(msg) {
+    helper(msg);
+    Ti.API.info(msg);
+}
+```
+
+**GOOD:** Single namespace
+```javascript
+const myapp = {};  // Only ONE global variable
+
+myapp.key = 'value';
+
+myapp.dosomething = (foo) => {
+    // do something
+};
+
+// Self-closing function for private members
+(() => {
+    function helper() {
+        // Private - not accessible globally
+    }
+
+    myapp.info = (msg) => {
+        helper(msg);
+        Ti.API.info(msg);
+    };
+})();
+
+myapp.info('Hello World');
+```
+
+### Use Strict Equality
+
+**BAD:** `==` converts types
+```javascript
+const testme = '1';
+if (testme == 1) {
+    // Executes! '1' is converted to integer
+}
+```
+
+**GOOD:** `===` checks both type and value
+```javascript
+const testme = '1';
+if (testme === 1) {
+    // Does NOT execute
+}
+```
+
+### Efficient Loops
+
+**BAD:** Checks array.length every iteration
+```javascript
+const names = ['Jeff', 'Nolan', 'Marshall', 'Don'];
+for (let i = 0; i < names.length; i++) {
+    process(names[i]);
+}
+```
+
+**GOOD:** Cache length
+```javascript
+const names = ['Jeff', 'Nolan', 'Marshall', 'Don'];
+for (let i = 0, j = names.length; i < j; i++) {
+    process(names[i]);
+}
+```
+
+**Even better:** ES6 `for...of`
+```javascript
+for (const name of names) {
+    process(name);
+}
+```
+
+### Use var/let/const Correctly
+
+```javascript
+// ES5: Use var (function-scoped)
+var x = 10;
+
+// ES6+: Use let and const (block-scoped)
+let y = 20;        // Can be reassigned
+const z = 30;       // Cannot be reassigned
+```
+
+---
+
+## Common Patterns
+
+### Ternary Operator
+
+Compact conditional assignment:
+
+```javascript
+// Instead of this:
+let xyz;
+if (somecondition === somevalue) {
+    xyz = 'abc';
+} else {
+    xyz = '123';
+}
+
+// Use this:
+const xyz = (somecondition === somevalue) ? 'abc' : '123';
+```
+
+### Multiple Variable Declarations
+
+Use commas instead of multiple `var` statements:
+
+```javascript
+// Instead of this:
+const foo = true;
+const me = 'awesome';
+const great = 42;
+
+// Use this:
+const foo = true,
+    me = 'awesome',
+    great = 42;
+```
+
+### Self-Calling Functions (IIFE)
+
+Encapsulate private variables and functions:
+
+**Ambiguous (not recommended):**
+```javascript
+const myValue = (() => {
+    return someValue;
+})();  // Looks like assigning function, not result
+```
+
+**Clear (recommended):**
+```javascript
+const myValue = (() => {
+    // Private variables here
+    const privateVar = 'secret';
+
+    return someValue;
+})();  // Clearly returns result, not function
+```
+
+### CommonJS Modules
+
+Use `require()` for modular code:
+
+**myModule.js:**
+```javascript
+// Private
+const privateData = 'secret';
+
+function privateHelper() {
+    // Private function
+}
+
+// Public API
+exports.publicMethod = () => {
+    privateHelper();
+    return privateData;
+};
+```
+
+**app.js:**
+```javascript
+const myModule = require('myModule');
+myModule.publicMethod();
+```
+
+---
+
+## ES6+ Features in Titanium
+
+Titanium supports modern JavaScript (ES6/ES7+). Use these features:
+
+**Arrow Functions:**
+```javascript
+// Old
+const self = this;
+someArray.forEach(function(item) {
+    self.process(item);
+});
+
+// New (arrow function preserves 'this')
+someArray.forEach((item) => {
+    this.process(item);
+});
+```
+
+**Template Literals:**
+```javascript
+// Old
+const message = 'Hello ' + name + ', you have ' + count + ' messages';
+
+// New
+const message = `Hello ${name}, you have ${count} messages`;
+```
+
+**Destructuring:**
+```javascript
+// Old
+const width = e.source.size.width;
+const height = e.source.size.height;
+
+// New
+const {width, height} = e.source.size;
+```
+
+**Spread Operator:**
+```javascript
+// Old
+const arr = [1, 2, 3];
+const arr2 = arr.concat([4, 5]);
+
+// New
+var arr2 = [...arr, 4, 5];
+```
+
+**Classes:**
+```javascript
+class Person {
+    constructor(name) {
+        this.name = name;
+    }
+
+    greet() {
+        return `Hello, I'm ${this.name}`;
+    }
+}
+```
+
+---
+
+## Gotchas to Avoid
+
+### Variable Hoisting
+
+**Problem:** Variables are hoisted to function scope
+```javascript
+function test() {
+    console.log(myVar);  // undefined (not error!)
+    var myVar = 'value';
+}
+```
+
+**Solution:** Declare variables at top of function
+```javascript
+function test() {
+    let myVar;  // Declare first
+    console.log(myVar);
+    myVar = 'value';
+}
+```
+
+### Global Variable Accidents
+
+**Problem:** Forgetting `var` creates global variable
+```javascript
+function test() {
+    myVar = 'value';  // Creates GLOBAL variable!
+}
+```
+
+**Solution:** Always use `var`, `let`, or `const`
+```javascript
+function test() {
+    const myVar = 'value';  // Local variable
+}
+```
+
+### The `this` Context
+
+**Problem:** `this` changes in different contexts
+```javascript
+const obj = {
+    value: 42,
+    getValue: function() {
+        setTimeout(function() {
+            console.log(this.value);  // undefined!
+        }, 100);
+    }
+};
+```
+
+**Solution 1:** Store `this`
+```javascript
+const obj = {
+    value: 42,
+    getValue: function() {
+        const self = this;
+        setTimeout(function() {
+            console.log(self.value);  // Works!
+        }, 100);
+    }
+};
+```
+
+**Solution 2:** Arrow function (ES6)
+```javascript
+const obj = {
+    value: 42,
+    getValue() {
+        setTimeout(() => {
+            console.log(this.value);  // Works!
+        }, 100);
+    }
+};
+```
+
+### Semicolon Insertion
+
+JavaScript automatically inserts semicolons, but can cause bugs:
+
+**Dangerous:**
+```javascript
+return
+{
+    name: 'Test'
+};
+// Returns undefined!
+```
+
+**Safe:**
+```javascript
+return {
+    name: 'Test'
+};
+// Or put opening brace on same line
+return { name: 'Test' };
+```
+
+---
+
+## Resources
+
+- **Alloy Framework:** See `alloy-guides` skill
+- **CommonJS Modules:** See `commonjs-advanced.md`
+- **Coding Best Practices:** See `coding-best-practices.md`
+- **Style Guide:** See `style-and-conventions.md`

package/skills/ti-guides/references/reserved-words.md

@@ -0,0 +1,36 @@
+# Reserved Words in Titanium
+
+## ECMAScript Reserved Keywords
+
+These keywords cannot be used as variable, function, method, or object identifiers per the ECMAScript specification:
+
+```
+abstract, boolean, break, byte, case, catch, char, class, const, continue,
+debugger, default, delete, do, double, else, enum, export, extends, finally,
+for, function, goto, if, implements, import, in, instanceof, int, interface,
+let, long, native, new, package, private, protected, public, return, short,
+static, super, switch, synchronized, this, throw, throws, transient, try,
+typeof, var, void, volatile, while, with, yield
+```
+
+## iOS Objective-C Reserved Words
+
+These keywords are exposed from Objective-C and may not be used as identifiers on iOS:
+
+```
+_configure, _destroy, _initProperties, autorelease, deadlock, dealloc,
+description, id, init, release, startup
+```
+
+## Alloy Reserved Words
+
+**Do not use double underscore prefixes** on variables, properties, or function names (e.g., `__foo`). These are reserved for Alloy's internal use.
+
+## Best Practice
+
+Always avoid these reserved words when naming:
+- Variables
+- Functions
+- Methods
+- Object properties
+- Module exports