@maccesar/titools 2.0.0

package/skills/alloy-guides/references/PURGETSS.md

@@ -0,0 +1,56 @@
+# PurgeTSS
+
+## Table of Contents
+
+- [PurgeTSS](#purgetss)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Command-Line Interface Usage](#command-line-interface-usage)
+  - [Key Features](#key-features)
+  - [Documentation](#documentation)
+    - [Topics](#topics)
+
+## Overview
+
+**PurgeTSS** is a powerful Alloy addon designed to enhance the process of developing visually captivating mobile applications for Titanium.
+
+It offers a range of tools such as customizable utility classes, support for icon fonts, a user-friendly Animation module, a straightforward grid system, and the added convenience of the `shades` command for crafting personalized colors.
+
+## Command-Line Interface Usage
+
+```bash
+alloy purgetss
+```
+
+## Key Features
+
+- **21,000+ Utility Classes**: Provides more than Tailwind-like utility classes ready to use in your projects
+- **Clean app.tss**: Creates a clean `app.tss` file with only the classes used in your project by parsing all your XML files
+- **Customization**: Customize default classes via config file or create just-in-time classes with arbitrary values
+- **Icon Fonts**: Easily use icon fonts from Font Awesome, Material Icons, Material Symbols, and Framework7-Icons
+- **fonts.tss Generation**: Generates a fonts.tss file with all class definitions and fontFamily selectors
+- **Shades Command**: Generate custom color shades from hex colors
+- **Animation Module**: Apply basic 2D Matrix animations or transform to elements
+- **Grid System**: Simple two-dimensional grid system to align and distribute elements
+
+## Documentation
+
+For complete documentation, visit the official PurgeTSS site at [purgetss.com](https://purgetss.com).
+
+### Topics
+
+- [Installation](https://purgetss.com/docs/installation)
+- [Commands](https://purgetss.com/docs/commands)
+- [Customization](https://purgetss.com/docs/customization)
+  - [Config file](https://purgetss.com/docs/customization/the-config-file)
+  - [Custom rules](https://purgetss.com/docs/customization/custom-rules)
+  - [Apply directive](https://purgetss.com/docs/customization/the-apply-directive)
+  - [Opacity modifier](https://purgetss.com/docs/customization/the-opacity-modifier)
+  - [Arbitrary values in XMLs](https://purgetss.com/docs/customization/arbitrary-values)
+  - [Platform and Device modifiers](https://purgetss.com/docs/customization/platform-and-device-modifiers)
+  - [Icon Fonts Libraries](https://purgetss.com/docs/customization/icon-fonts-libraries)
+- [Animation Module](https://purgetss.com/docs/animation-module)
+  - [Introduction](https://purgetss.com/docs/animation-module/introduction)
+  - [Available utilities](https://purgetss.com/docs/animation-module/available-utilities)
+  - [Complex UI elements](https://purgetss.com/docs/animation-module/complex-ui-elements)
+- [Grid System](https://purgetss.com/docs/grid-system)

package/skills/alloy-guides/references/VIEWS_DYNAMIC.md

@@ -0,0 +1,242 @@
+# Dynamic Styles
+
+## Table of Contents
+
+- [Dynamic Styles](#dynamic-styles)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [Define Class Styles](#define-class-styles)
+  - [Generate a Dynamic Style](#generate-a-dynamic-style)
+    - [Equivalent Code Outside Controller](#equivalent-code-outside-controller)
+  - [Modify TSS Classes](#modify-tss-classes)
+  - [Autostyle](#autostyle)
+    - [Why Autostyle is Needed](#why-autostyle-is-needed)
+
+## Introduction
+
+Since Alloy 1.2.0, Alloy supports changing styles dynamically or during runtime. There are two methods to support dynamic styling in Alloy. You can either generate a dynamic style dictionary that can be passed to `applyProperties` or a create method, or modify TSS class styles to an existing component on the fly.
+
+## Define Class Styles
+
+Before using either method, you need to create class styles in the TSS files, either in the global style file or in the individual TSS files.
+
+**app/styles/app.tss**
+
+```javascript
+".bluetext" : {
+  color: 'blue'
+},
+".orangetext" : {
+  color: 'orange'
+},
+".shadow" : {
+  shadowColor: '#88f',
+  shadowOffset: {x:1,y:3}
+},
+".ldpi" : {
+  font: {fontSize: '9dp', fontWeight: 'normal' }
+},
+".mdpi" : {
+  font: {fontSize: '12dp', fontWeight: 'normal' }
+},
+".hdpi" : {
+  font: {fontSize: '18dp', fontWeight: 'bold' }
+},
+".xhdpi" : {
+  font: {fontSize: '24dp', fontWeight: 'bold' }
+},
+"Label" : {
+  font: {fontSize: '14dp', fontWeight: 'normal' },
+  shadow : {},
+  color : 'black'
+},
+".rude_button" : {
+  title: 'Go Away'
+},
+".nice_button" : {
+  title: 'Please Close'
+},
+"Button" : {
+    width: Ti.UI.SIZE,
+    height: Ti.UI.SIZE
+}
+".tiny_win" : {
+  height: '150dp',
+  width: '200dp',
+  backgroundColor: 'blue'
+},
+".big_win" : {
+  height: '300dp',
+  width: '400dp',
+  backgroundColor: 'red'
+}
+```
+
+The previous style sheet defines various class and markup element styles for labels, buttons and windows. Alloy assigns a priority for each class, based on its order in the TSS file. Styles listed first receive a lower priority than ones listed afterwards. For example, if both the ldpi and hdpi classes are assigned to a label, since hdpi is after ldpi, the label text is 24 dp not 9 dp.
+
+## Generate a Dynamic Style
+
+To generate a dynamic style, use the controller's `createStyle` method by passing it a dictionary with TSS classes. This method returns a dictionary that can be passed to the view object's `applyProperties` method or a create view object method.
+
+You can use the controller's `UI.create` method to create a view component that is dynamically styled.
+
+**app/views/dialog.xml**
+
+```xml
+<Alloy>
+    <Window id="win">
+        <Button id="button" onClick="doClick" />
+    </Window>
+</Alloy>
+```
+
+**app/controllers/dialog.js**
+
+```javascript
+function doClick(e) {
+    $.win.close();
+}
+
+const args = arguments[0] || {};
+if (args.button) {
+    const style = $.createStyle({
+        classes: args.button,
+        apiName: 'Button',
+        color: 'blue'
+    });
+    $.button.applyProperties(style);
+}
+if (args.win) {
+    const style = $.createStyle({
+        classes: args.win,
+        apiName: 'Window',
+        backgroundColor: 'white'
+    });
+    $.win.applyProperties(style);
+}
+if (args.label) {
+    args.label.top = 10
+    const label = $.UI.create("Label", args.label);
+    $.win.add(label);
+}
+```
+
+**app/controllers/index.js**
+
+```javascript
+const args = {};
+args.button = ['rude_button'];
+args.win = ['tiny_win'];
+args.label = {
+    classes: ['hdpi', 'shadow'],
+    text: 'No zombies allowed!'
+};
+Alloy.createController('dialog', args).getView().open();
+```
+
+### Equivalent Code Outside Controller
+
+In this example, the dialog controller code is not necessary. The dialog can be generated and styled outside the view-controller. The following code using only the previous XML markup is equivalent to what the previous two controllers are doing:
+
+**app/controllers/index.js**
+
+```javascript
+const dialog = Alloy.createController('dialog');
+let style = dialog.createStyle({
+    classes: 'rude_button',
+    apiName: 'Button',
+    color: 'blue'
+});
+dialog.button.applyProperties(style);
+style = dialog.createStyle({
+    classes: 'tiny_win',
+    apiName: 'Window',
+    backgroundColor: 'white'
+});
+dialog.win.applyProperties(style);
+style = {
+    top: 10,
+    text: 'No zombies allowed!',
+    classes: 'hdpi shadow'
+}
+const label = dialog.UI.create('Label', style);
+dialog.win.add(label);
+dialog.getView().open();
+```
+
+Note that code outside of the dialog view-controller is using the instance variable name `dialog` to make the API calls with the `createStyle` and `UI.create` methods rather than the `$` variable, which is used when making controller API calls inside its own view-controller.
+
+## Modify TSS Classes
+
+To modify the TSS classes of an object that has already been created, use the controller's `addClass`, `removeClass` and `resetClass` methods, which adds, removes or resets the TSS classes of a view object, respectively.
+
+Pass a reference to the view object as the first parameter, then pass the classes to add or remove as an array or space-separated string as the second parameter. You can optionally specify inline properties as an optional third parameter.
+
+**app/controllers/index.js**
+
+```javascript
+const dialog = Alloy.createController('dialog');
+dialog.addClass(dialog.win, 'tiny_win', {backgroundColor:'white'});
+dialog.addClass(dialog.button, 'rude_button', {color: 'blue'});
+const style = {
+    top: 10,
+    text: 'No zombies allowed!',
+    classes: 'hdpi shadow'
+}
+const label = dialog.UI.create('Label', style);
+dialog.getView().open();
+```
+
+Later on, you can change the classes:
+
+```
+dialog.resetClass(dialog.button, 'nice_button orangetext hdpi');
+```
+
+## Autostyle
+
+A view component with autostyle enabled has its TSS classes stored with the view object. Autostyle is necessary to take full advantage of the `addClass()`, `removeClass()` and `resetClass()` classes to properly update the view as classes are removed and added. There is a small performance overhead for using this feature and should only be enabled on components that use this feature. By default, autostyle is disabled.
+
+To enable autostyle, set the `autoStyle` attribute to `true` either in the XML markup or the `config.json` file.
+
+* To enable autostyle for an individual component, set the `autoStyle` attribute to true on the XML tag: `<View autoStyle="true">`.
+* To enable autostyle for components in a controller, set the `autoStyle` attribute to true on the root `<Alloy/>` tag: `<Alloy autoStyle="true">`.
+* To enable autostyle for all controllers in an Alloy project, set the `autoStyle` field to true in the `config.json` file.
+
+**app/config.json**
+
+```json
+{
+    "autoStyle": true
+}
+```
+
+### Why Autostyle is Needed
+
+Consider the following example without autostyle:
+
+**app/styles/index.tss**
+
+```javascript
+".coloronly" : {
+    color: 'red'
+},
+".colorsize" : {
+    color: 'blue',
+    font: {fontSize: '24dp'}
+},
+"Label" : {
+    color: 'black',
+    font: {fontSize: '12dp'}
+}
+```
+
+**app/controllers/index.js**
+
+```javascript
+$.addClass($.label, "coloronly colorsize"); // --> appears blue and 24dp
+$.removeClass($.label, "colorsize"); // --> appears red and 24dp (font size not updated!)
+$.removeClass($.label, "coloronly"); // --> appears red and 24dp (not black!)
+```
+
+With autostyle enabled, the styles update as expected when classes are added or removed.

package/skills/alloy-guides/references/VIEWS_STYLES.md

@@ -0,0 +1,388 @@
+# Alloy Styles and Themes
+
+## Table of Contents
+
+- [Alloy Styles and Themes](#alloy-styles-and-themes)
+  - [Table of Contents](#table-of-contents)
+  - [Titanium Style Sheets](#titanium-style-sheets)
+  - [Global Styles](#global-styles)
+  - [Platform-Specific Styles](#platform-specific-styles)
+  - [Custom Query Styles](#custom-query-styles)
+    - [Example Using Custom Properties](#example-using-custom-properties)
+    - [Example Using Conditional Statements](#example-using-conditional-statements)
+  - [Themes](#themes)
+  - [Style Priorities](#style-priorities)
+
+## Titanium Style Sheets
+
+The Titanium Style Sheets (TSS) file uses a JSON-like syntax to define the attributes of elements in the XML files. All TSS attributes are the properties of the Titanium object.
+
+Styles are defined at three different levels: markup element, class attribute and the id attribute. When mixed together, the id attribute overrides both the class attribute and markup element, and the class attribute overrides the markup element.
+
+In the TSS file, define attributes as key-value pairs, where the key is the name of the markup element, the class name prefixed with a period (`.`), or the id name prefixed with a hash tag (`#`) and the value is a dictionary of attributes.
+
+You can use the following values and operators in your TSS file:
+
+* JSON values: Strings, Numbers, Objects, Array, Booleans and null
+* `undefined` to unset a property (since Alloy 1.4.0)
+* Titanium SDK constants: `Ti.UI.SIZE`
+* Localization functions: `Ti.Locale.getString()` and `L()`
+* Variables from `Alloy.CFG` or `Alloy.Globals`
+* Bitwise operators: `>>`, `<<`, `>>>`, `&`, `|`, `^` (since Alloy 1.3.0)
+* Single (`//comment`) and multiline comments (`/* comment */`)
+
+::: warning ⚠️ Warning
+Alloy does not support the CSS concept of child or descendent selectors.
+:::
+
+**app/styles/index.tss**
+
+```javascript
+// Applied to any element with class "container"
+".container": {
+  backgroundColor:"white"
+},
+// Applied to all Labels
+"Label": {
+    width: Ti.UI.SIZE,
+    height: Ti.UI.SIZE,
+    color: "#000",
+    transform: Alloy.Globals.rotateLeft
+},
+// Applied only to element with id="label"
+"#label": {
+    color: "#999"
+}
+```
+
+For the Label's `transform` property in the example above, the TSS file is using a function assigned to the `Alloy.Globals` namespace defined in the initializer file:
+
+**app/alloy.js**
+
+```javascript
+Alloy.Globals.rotateLeft = Ti.UI.createMatrix2D().rotate(-90);
+```
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window class="container">
+        <Label id="label" onClick="doClick">Hello, World</Label>
+    </Window>
+</Alloy>
+```
+
+## Global Styles
+
+You can create a global style file, called `app.tss`, which applies all styles defined inside it to all views, but does not override the non-global styles or property attributes in the markup.
+
+**styles/app.tss**
+
+```javascript
+"Window":{
+    backgroundColor: 'white',
+    layout: 'vertical'
+}
+"Label":{
+    color: 'gray',
+    textAlign: Ti.UI.TEXT_ALIGNMENT_LEFT,
+    backgroundColor: 'transparent',
+    font: {
+        fontFamily:'Helvetica',
+        fontSize: '12dp',
+        fontStyle: 'normal',
+        fontWeight: 'normal'
+    }
+}
+```
+
+**styles/index.tss**
+
+```javascript
+"Window":{
+    backgroundColor: 'blue'
+}
+"Label":{
+    top: 20,
+    left: '25dp',
+    right: '25dp'
+}
+"#subtitle":{
+    width: Ti.UI.FILL,
+    textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER,
+    font: {
+        fontSize: '16dp',
+        fontWeight: 'bold'
+    }
+}
+```
+
+**views/index.xml**
+
+```xml
+<Alloy>
+    <Window titleid="story_title" modal="true" exitOnClose="true">
+        <Label id="subtitle" color="orange" textid="story_subtitle" />
+        <Label top="25" color="white" textid="story_content" />
+    </Window>
+</Alloy>
+```
+
+Style priority (lowest to highest): Global Style File → Global Style File in Theme → Platform-Specific Global → View-Controller Style File → View-Controller Style in Theme → Platform-Specific View-Controller → XML Markup → Platform-Specific XML Markup.
+
+## Platform-Specific Styles
+
+:::danger CRITICAL: Platform-Specific Properties Require Modifiers
+**Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS WITHOUT platform modifiers will:**
+
+1. **Add iOS code to Android builds** → compilation failures
+2. **Add Android code to iOS builds** → compilation failures
+
+**Example of the damage:**
+```tss
+// ❌ WRONG - Adds Ti.UI.iOS to Android project
+"#mainWindow": {
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
+}
+```
+
+**CORRECT - Always use platform modifiers:**
+```tss
+// ✅ CORRECT - Only adds to iOS
+"#mainWindow[platform=ios]": {
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+}
+
+// ✅ CORRECT - Only adds to Android
+"#mainWindow[platform=android]": {
+  actionBar: {
+    displayHomeAsUp: true
+  }
+}
+```
+
+**Common platform-specific properties that REQUIRE `[platform=...]` modifiers:**
+- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
+- Android: `actionBar` config, any `Ti.Android.*` constant
+:::
+
+As with views, separate styles may be defined based on the platform and device size.
+
+**To specify platform or device size conditionals:**
+
+1. Place a set of square brackets (`[]`) directly after the name of the markup element, class name or id name in the TSS file.
+2. Inside the brackets:
+   * `platform` attribute: assign a platform (`android`, `ios`). Comma separate to OR values. Prepend with `!` to negate.
+   * `formFactor` attribute: assign a device size (`handheld` or `tablet`).
+
+```
+// Default label
+"Label": {
+    backgroundColor: "#000",
+    text: 'Another platform'
+},
+// iPhone
+"Label[platform=ios formFactor=handheld]": {
+    backgroundColor: "#f00",
+    text: 'iPhone'
+},
+// iPad
+"Label[platform=ios formFactor=tablet]": {
+    backgroundColor: "#0f0",
+    text: 'iPad'
+},
+// Android
+"Label[platform=android]": {
+    backgroundColor: "#00f",
+    text: 'Android'
+}
+```
+
+Alternatively, create subfolders named as the platform in the `styles` directory.
+
+## Custom Query Styles
+
+You can create custom queries to select which styles to apply in both the TSS and XML files.
+
+**To use a custom query:**
+
+1. Define a conditional statement that returns a boolean value, and assign it to a property in `Alloy.Globals` or a local function.
+2. Assign the `if` attribute to an element in the XML or TSS file.
+
+### Example Using Custom Properties
+
+The application can pass custom Boolean properties to the `Alloy.createController()` method. These properties can be accessed by both the XML and TSS files. When calling the `createController()` method, pass the custom Boolean properties in the second argument of the method.
+
+The controller below defines two functions that create and open an instance of the `win2` controller, but each function passes a different property to the controller.
+
+**apps/controllers/index.js**
+
+```javascript
+function openBar (e) {
+  Alloy.createController('win2', {'fooBar': true}).getView().open();
+};
+
+function openBaz (e) {
+    Alloy.createController('win2', {'fooBaz': true}).getView().open();
+};
+```
+
+In the TSS file, add the conditional block and assign the `if` attribute to the property passed to the `createController()` method. Prefix the property name with the `$.args` namespace. Based on the property passed to the method, the application displays a different styled label.
+
+**app/styles/win2.tss**
+
+```javascript
+"#label[if=$.args.fooBar]": {
+  'text' : 'Foobar',
+  'color' : 'blue'
+}
+
+"#label[if=$.args.fooBaz]": {
+    'text' : 'Foobaz',
+    'color' : 'red'
+}
+```
+
+In the XML markup, add the `if` attribute to an element and assign it to the property passed to the `createController()` method. Prefix the property name with the `$.args` namespace. Based on the property passed to the method, the application displays a different label.
+
+**app/views/win2.xml**
+
+```xml
+<Alloy>
+    <Window>
+        <Label if="$.args.fooBar" color="blue">Foobar</Label>
+        <Label if="$.args.fooBaz" color="red">Foobaz</Label>
+    </Window>
+</Alloy>
+```
+
+### Example Using Conditional Statements
+
+In this example, the application defines conditional statements to determine the iPhone device the application is running on. This iPhone application displays a scrolling block of text with a title above it and a caption below it:
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window>
+        <Label id="title" textid="title"/>
+        <ScrollView>
+            <Label id="content" textid="content"/>
+        </ScrollView>
+        <Label id="info">TextViewer by BluthCo</Label>
+    </Window>
+</Alloy>
+```
+
+To take advantage of the various iPhone devices, we need to see if the device is running iOS 7 and above, and whether the iPhone is using the old regular or the latest tall form factor. We can define both of these query statements in the initializer file:
+
+**app/alloy.js**
+
+```javascript
+Alloy.Globals.isIos7Plus = (OS_IOS && parseInt(Ti.Platform.version.split(".")[0]) >= 7);
+Alloy.Globals.iPhoneTall = (OS_IOS && Ti.Platform.osname == "iphone" && Ti.Platform.displayCaps.platformHeight == 568);
+```
+
+In the style file, use these conditional statements to create styles for specific devices. For example, since iOS 7, you can take advantage of the built-in text styles instead of defining all the attributes for a Font object, and since the iPhone 5 (and later) is taller, you need to make the ScrollView longer.
+
+**app/styles/index.tss**
+
+```javascript
+// Default Styles
+"#content": {
+    color: 'gray',
+    top: '25dp',
+    left: '10dp',
+    font: {
+        fontSize: '12dp'
+    }
+},
+"#info": {
+    color: 'gray',
+    bottom: '20dp',
+    font: {
+        fontSize: '9dp'
+    }
+},
+"#title": {
+    color: 'black',
+    top: '15dp',
+    font: {
+        fontSize: '14dp',
+        fontWeight: 'bold'
+    }
+},
+"Window": {
+    layout: 'vertical',
+    backgroundColor: 'white'
+},
+"ScrollView": {
+    height: '415dp'
+},
+// Query styles
+"#info[if=Alloy.Globals.isIos7Plus]": {
+    font: { textStyle : Ti.UI.TEXT_STYLE_FOOTNOTE }
+},
+"#title[if=Alloy.Globals.isIos7Plus]": {
+    top: '25dp', // compensate for the status bar on iOS 7
+    font: { textStyle : Ti.UI.TEXT_STYLE_HEADLINE }
+},
+"#content[if=Alloy.Globals.isIos7Plus]": {
+    font: { textStyle : Ti.UI.TEXT_STYLE_CAPTION1 }
+},
+"ScrollView[if=Alloy.Globals.iPhoneTall]": {
+    height: '500dp'
+}
+```
+
+## Themes
+
+Themes provide a way to overwrite or modify files for a specific brand of your app.
+
+To create a theme, create a folder called `themes` in your Alloy `app` directory. In the `themes` folder, create a folder for your theme.
+
+| Folder or Filename | Merges or Overwrites             |
+| ------------------ | -------------------------------- |
+| config.json        | merges                           |
+| i18n               | merges folders and files         |
+| assets             | merges folders, overwrites files |
+| lib                | merges folders, overwrites files |
+| platform           | merges folders, overwrites files |
+| styles             | merges folders and files         |
+| widgets/\*/assets  | merges folders, overwrites files |
+| widgets/\*/styles  | merges folders and files         |
+
+To use a theme, add it to your `config.json`:
+
+```
+{
+    "global": {
+        "theme":"mytheme"
+    },
+    "os:ios": {
+        "theme":"green"
+    },
+    "os:android": {
+        "theme":"blue"
+    },
+    "dependencies": {}
+}
+```
+
+## Style Priorities
+
+When mixing themes, the global style file, view style files and defining styles inline in the XML markup, Alloy applies the styles in the following order from lowest to highest priority:
+
+| Style Defined in...                                                 | Example                                                       |
+| ------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Global Style File                                                   | `styles/app.tss`                                              |
+| Global Style File in a Theme                                        | `themes/<theme_name>/styles/app.tss`                          |
+| Global Style File with Platform-Specific Styles                     | `styles/<platform>/app.tss`                                   |
+| Global Style File in a Theme with Platform-Specific Styles          | `themes/<theme_name>/styles/<platform>/app.tss`               |
+| View-Controller Style File                                          | `styles/<view_controller>.tss`                                |
+| View-Controller Style File in a Theme                               | `themes/<theme_name>/styles/<view_controller>.tss`            |
+| View-Controller Style File with Platform-Specific Styles            | `styles/<platform>/<view_controller>.tss`                     |
+| View-Controller Style File in a Theme with Platform-Specific Styles | `themes/<theme_name>/styles/<platform>/<view_controller>.tss` |
+| XML Markup                                                          | `views/<view_controller>.xml`                                 |
+| XML Markup with Platform-Specific Styles                            | `views/<platform>/<view_controller>.xml`                      |