@maccesar/titools 3.2.0 → 4.0.0

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

@@ -0,0 +1,402 @@
+# JavaScript development primer
+
+Essential JavaScript concepts, resources, and best practices for Titanium development.
+
+## JavaScript overview
+
+JavaScript is the language of Titanium. It is lightweight and dynamic, with object-oriented and functional features.
+
+Why JavaScript for Titanium?
+- Widely deployed (every web browser)
+- Large community
+- 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 is web-specific)
+- Access to native APIs via the Titanium namespace
+- ECMAScript 5/6 compliant
+- Same JavaScript you use on the web, but targeting mobile apps
+
+---
+
+## Learning resources
+
+### Online courses
+
+- Codecademy: https://www.codecademy.com/learn/introduction-to-javascript
+- Stanford CS101: http://www.stanford.edu/class/cs101/
+- edX: https://www.edx.org/learn/javascript
+
+### Online books and references
+
+- Eloquent JavaScript: https://eloquentjavascript.net/
+- MDN JavaScript Guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide
+- Douglas Crockford's resources: http://javascript.crockford.com/
+- JavaScript in 10 Minutes: https://github.com/spencertipping/js-in-ten-minutes
+- Google JavaScript Style Guide: https://google.github.io/styleguide/jsguide.html
+- Learning Advanced JavaScript: http://ejohn.org/apps/learn/
+
+### Print books (recommended)
+
+- JavaScript: The Good Parts (Douglas Crockford)
+- JavaScript: The Definitive Guide (David Flanagan)
+- JavaScript Patterns (Stoyan Stefanov)
+- Eloquent JavaScript (Marijn Haverbeke)
+
+---
+
+## Best practices
+
+### Do not 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]);
+}
+```
+
+This is especially important with Titanium proxy objects, where checking length on each iteration has extra overhead.
+
+Even better: ES6 `for...of`
+```javascript
+for (const name of names) {
+    process(name);
+}
+```
+
+### Prefer `const` and `let` over `var`
+
+`var` is function-scoped and hoisted; `let` and `const` are block-scoped and clearer.
+
+```javascript
+// Avoid: var (function-scoped, can be accidentally hoisted)
+var x = 10;
+
+// Prefer: const for values that do not change
+const MAX_RETRIES = 3;
+const config = { timeout: 5000 };
+
+// Use let only when the binding must be reassigned
+let retryCount = 0;
+retryCount++;
+```
+
+Rule of thumb: reach for `const` first; switch to `let` only when you need to reassign; never use `var` in new code.
+
+---
+
+## Common patterns
+
+### Ternary operator
+
+Compact conditional assignment. Value after `?` is used if the condition is true; value after `:` if false.
+
+```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
+const 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 the top of the function.
+```javascript
+function test() {
+    let myVar;  // Declare first
+    console.log(myVar);
+    myVar = 'value';
+}
+```
+
+### Global variable accidents
+
+Problem: forgetting `var` creates a global variable.
+```javascript
+function test() {
+    myVar = 'value';  // Creates a global variable
+}
+```
+
+Solution: always use `var`, `let`, or `const`.
+```javascript
+function test() {
+    const myVar = 'value';
+}
+```
+
+### 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 and can cause bugs.
+
+Dangerous:
+```javascript
+return
+{
+    name: 'Test'
+};
+// Returns undefined
+```
+
+Safe:
+```javascript
+return {
+    name: 'Test'
+};
+```

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 under 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 should 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 (for example, `__foo`). These are reserved for Alloy's internal use.
+
+## Best practice
+
+Avoid these reserved words when naming:
+- Variables
+- Functions
+- Methods
+- Object properties
+- Module exports

package/skills/ti-guides/references/resources.md

@@ -0,0 +1,172 @@
+# Titanium resources
+
+Community resources, support channels, tools, and learning materials for Titanium developers.
+
+## Developer support
+
+### Official channels
+
+- GitHub Discussions: https://github.com/tidev/titanium-sdk/discussions
+- Slack: https://tidev.slack.com/
+  - Join at: https://tidev.slack.com/
+  - Channels for help, modules, announcements, and more
+
+### Module resources
+
+- Module Search: https://modules.titaniumsdk.com/
+- From Zero to App: https://fromzerotoapp.com/
+
+### Documentation
+
+- Titanium SDK Docs: https://titaniumsdk.com/
+- Alloy Framework Docs: https://titaniumsdk.com/guide/Alloy_Framework/
+- This skill (`ti-guides`): `../SKILL.md`
+
+---
+
+## Example code
+
+### Official repositories
+
+- tidev on GitHub: https://github.com/tidev
+  - titanium-mobile: https://github.com/tidev/titanium-mobile
+  - titanium-cli: https://github.com/tidev/titanium-cli
+  - titanium-code-processor: https://github.com/tidev/titanium-code-processor
+
+### Sample applications
+
+- Ti.Map: https://github.com/tidev/ti.map
+- KitchenSink: https://github.com/tidev/KitchenSink
+
+### Community projects
+
+Search GitHub for "titanium" to find open source modules and apps.
+
+---
+
+## Community modules
+
+### Finding modules
+
+1. Module Search: https://modules.titaniumsdk.com/
+2. npm: https://www.npmjs.com/search?q=titanium
+3. GitHub search: https://github.com/search?q=titanium+module
+
+### Creating modules
+
+See `hyperloop-native-access.md` for native module development:
+- Android modules (Java/Kotlin)
+- iOS modules (Objective-C/Swift)
+- Module packaging and distribution
+
+### Popular modules
+
+- ti.map: native maps (iOS and Android)
+- ti.admob: AdMob ads
+- ti.imagefactory: image processing
+- ti.facebook: Facebook integration
+- ti.media: extended media APIs
+
+---
+
+## Social media
+
+### Official accounts
+
+- Bluesky: https://bsky.app/profile/titaniumsdk.com
+- X (Twitter):
+  - https://x.com/tidevio
+  - https://x.com/TitaniumSDK
+
+### Community
+
+- Reddit: https://www.reddit.com/r/titanium/
+- Stack Overflow: https://stackoverflow.com/questions/tagged/titanium
+
+---
+
+## Learning resources
+
+### Getting started
+
+1. Hello World: see `hello-world.md` in this skill
+2. JavaScript Primer: see `javascript-primer.md` in this skill
+3. Alloy Framework: see the `alloy-guides` skill
+4. Sample apps: clone and study KitchenSink
+
+### Books and guides
+
+- Titanium Up & Running
+- Titanium Pocket Reference
+- Alloy Guides (official Alloy framework documentation)
+
+### Video tutorials
+
+- From Zero to App: https://fromzerotoapp.com/
+- YouTube results: https://www.youtube.com/results?search_query=titanium+mobile
+
+---
+
+## Tools and IDEs
+
+### IDE support
+
+- VS Code: https://code.visualstudio.com/ (with Titanium extensions)
+
+### CLI tools
+
+```bash
+# Create new project
+ti create
+
+# Build for iOS
+ti build -p ios
+
+# Build for Android
+ti build -p android
+
+# Run on device
+ti build -T device
+```
+
+See `cli-reference.md` for complete CLI documentation.
+
+---
+
+## Contributing
+
+### Report bugs
+
+- GitHub Issues: https://github.com/tidev/titanium-sdk/issues
+- JIRA Archive: https://github.com/tidev/jira-archive
+
+### Contribute code
+
+- Pull Request Guide: https://github.com/tidev/titanium-mobile/blob/master/CONTRIBUTING.md
+- Follow coding standards in `style-and-conventions.md`
+
+---
+
+## Best practices for getting help
+
+1. Search first: check docs, GitHub issues, Stack Overflow.
+2. Be specific: include code, error messages, and platform info.
+3. Provide a minimal reproducible example.
+4. Use Slack for quick questions and GitHub Discussions for longer threads.
+5. Give back when you can.
+
+---
+
+## Resource checklist
+
+For new Titanium developers:
+
+- [ ] Install Titanium SDK and CLI
+- [ ] Set up development environment (iOS/Android SDKs)
+- [ ] Read `hello-world.md`
+- [ ] Read `javascript-primer.md`
+- [ ] Complete a sample project
+- [ ] Join Slack community
+- [ ] Explore Alloy framework
+- [ ] Study sample apps on GitHub
+- [ ] Contribute back to community

package/skills/ti-guides/references/style-and-conventions.md

@@ -0,0 +1,104 @@
+# Style and conventions reference
+
+## 1. Naming conventions
+
+- Variables: `nounCategory` (for example, `personName`, `buttonSubmit`).
+- Functions: `verbCategory` (for example, `getPersonName`, `doSync`).
+- Classes/constructors: `PascalCase` (for example, `User`, `NetClient`).
+- Factories: prefix with `create` (for example, `createWidget`).
+- Namespaces: use capitalized words (for example, `App.UI.Widget`, `App.Network.Request`). Avoid lowercase for major namespaces (use `App.UI`, not `app.ui`).
+- Hungarian notation: not supported by the Titanium SDK.
+
+## 2. Language rules
+
+- Semicolons: official SDK guides require semicolons, but the `ti-expert` standard omits them and lets ASI handle it.
+- `this` keyword: use with care. It may not refer to the object you expect.
+
+## 3. Formatting
+
+- Indentation: both K&R/1TBS and Allman styles are acceptable. Consistency matters. Do not mix styles in the same project.
+```javascript
+// K&R/1TBS style
+if (x < 10) {
+  if (y > 10) {
+    // do this
+  }
+} else {
+  // do this
+}
+```
+```javascript
+// Allman style
+if (x < 10)
+{
+  if (y > 10)
+  {
+    // do this
+  }
+}
+else
+{
+  // do this
+}
+```
+- Operators: add a single space around operators.
+```javascript
+const fullName = firstName + ' ' + lastName
+```
+
+Return statement placement:
+Do not put `return` on its own line followed by an object literal. JavaScript will insert a semicolon automatically and return `undefined`.
+```javascript
+// Wrong
+return
+{
+  foo: 'bar'
+}
+
+// Correct
+return {
+  foo: 'bar'
+}
+```
+
+## 4. Control statements
+
+Switch statements should have a single space before the opening parenthesis and a single space after the closing parenthesis. Switch content is indented with one tab; content in each case is indented one tab as well.
+```javascript
+switch (someTest) {
+    case 1:
+        break;
+
+    case 2:
+        break;
+
+    default:
+        break;
+}
+```
+
+## 5. Primitive types
+
+- Avoid using primitive type object constructors (for example, `new String()`).
+- Use template literals or single-space concatenation.
+
+## 6. Comments and documentation
+
+- Single-line comments: required to reduce programmer error. Inline statement comments should be used at a minimum or not at all.
+- JSDoc/block comments: required for documenting functions and classes.
+```javascript
+// Calculate position using initial
+// and offset x coordinates.
+const finalPos = initPosX + offsetPosX;
+
+/**
+ * @param {String} customerName Customer's full name.
+ */
+function getCustomer(customerName) {}
+```
+
+## 7. References
+
+- Douglas Crockford's JavaScript Code Conventions
+- Google's JavaScript Style Guide: https://google.github.io/styleguide/jsguide.html
+- TiDev ESLint Configuration (rules used for SDK-related npm packages and CLI code): https://github.com/tidev/eslint-config-axway