@maccesar/titools 2.0.6 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/{AGENTS-TEMPLATE.md → AGENTS-VERCEL-RESEARCH.md} +16 -18
  2. package/README.md +250 -168
  3. package/agents/{ti-researcher.md → ti-pro.md} +10 -10
  4. package/bin/titools.js +16 -12
  5. package/lib/cleanup.js +95 -0
  6. package/lib/commands/agents.js +146 -70
  7. package/lib/commands/skills.js +349 -0
  8. package/lib/commands/uninstall.js +189 -154
  9. package/lib/commands/update.js +104 -21
  10. package/lib/config.js +26 -20
  11. package/lib/downloader.js +1 -1
  12. package/lib/installer.js +37 -97
  13. package/lib/platform.js +9 -5
  14. package/lib/prompts/checkboxCancel.js +264 -0
  15. package/lib/prompts/selectCancel.js +204 -0
  16. package/lib/symlink.js +19 -7
  17. package/lib/utils.js +21 -31
  18. package/package.json +10 -10
  19. package/skills/alloy-guides/SKILL.md +8 -30
  20. package/skills/alloy-guides/references/CLI_TASKS.md +14 -24
  21. package/skills/alloy-guides/references/CONCEPTS.md +5 -25
  22. package/skills/alloy-guides/references/CONTROLLERS.md +2 -19
  23. package/skills/alloy-guides/references/MODELS.md +40 -10
  24. package/skills/alloy-guides/references/PURGETSS.md +1 -11
  25. package/skills/alloy-guides/references/VIEWS_DYNAMIC.md +8 -14
  26. package/skills/alloy-guides/references/VIEWS_STYLES.md +14 -25
  27. package/skills/alloy-guides/references/VIEWS_WITHOUT_CONTROLLERS.md +2 -8
  28. package/skills/alloy-guides/references/VIEWS_XML.md +29 -40
  29. package/skills/alloy-guides/references/WIDGETS.md +1 -17
  30. package/skills/alloy-howtos/SKILL.md +1 -22
  31. package/skills/alloy-howtos/references/best_practices.md +0 -17
  32. package/skills/alloy-howtos/references/cli_reference.md +1 -23
  33. package/skills/alloy-howtos/references/config_files.md +86 -15
  34. package/skills/alloy-howtos/references/custom_tags.md +14 -13
  35. package/skills/alloy-howtos/references/debugging_troubleshooting.md +3 -22
  36. package/skills/alloy-howtos/references/samples.md +4 -14
  37. package/skills/purgetss/SKILL.md +11 -37
  38. package/skills/purgetss/references/EXAMPLES.md +106 -17
  39. package/skills/purgetss/references/animation-system.md +0 -67
  40. package/skills/purgetss/references/apply-directive.md +0 -18
  41. package/skills/purgetss/references/arbitrary-values.md +0 -25
  42. package/skills/purgetss/references/class-index.md +0 -46
  43. package/skills/purgetss/references/cli-commands.md +0 -41
  44. package/skills/purgetss/references/configurable-properties.md +0 -55
  45. package/skills/purgetss/references/custom-rules.md +0 -14
  46. package/skills/purgetss/references/customization-deep-dive.md +0 -49
  47. package/skills/purgetss/references/dynamic-component-creation.md +56 -37
  48. package/skills/purgetss/references/grid-layout.md +0 -32
  49. package/skills/purgetss/references/icon-fonts.md +0 -50
  50. package/skills/purgetss/references/installation-setup.md +61 -32
  51. package/skills/purgetss/references/migration-guide.md +127 -0
  52. package/skills/purgetss/references/opacity-modifier.md +0 -34
  53. package/skills/purgetss/references/performance-tips.md +261 -0
  54. package/skills/purgetss/references/platform-modifiers.md +0 -46
  55. package/skills/purgetss/references/smart-mappings.md +0 -12
  56. package/skills/purgetss/references/tikit-components.md +393 -0
  57. package/skills/purgetss/references/titanium-resets.md +1 -27
  58. package/skills/purgetss/references/ui-ux-design.md +467 -117
  59. package/skills/{alloy-expert → ti-expert}/SKILL.md +45 -54
  60. package/skills/ti-expert/references/alloy-builtins.md +387 -0
  61. package/skills/{alloy-expert → ti-expert}/references/alloy-structure.md +147 -40
  62. package/skills/ti-expert/references/anti-patterns.md +90 -0
  63. package/skills/ti-expert/references/cli-expert.md +109 -0
  64. package/skills/{alloy-expert → ti-expert}/references/code-conventions.md +182 -49
  65. package/skills/{alloy-expert → ti-expert}/references/controller-patterns.md +103 -93
  66. package/skills/{alloy-expert → ti-expert}/references/error-handling.md +12 -12
  67. package/skills/{alloy-expert → ti-expert}/references/examples.md +144 -85
  68. package/skills/{alloy-expert → ti-expert}/references/migration-patterns.md +38 -36
  69. package/skills/{alloy-expert → ti-expert}/references/patterns.md +8 -8
  70. package/skills/ti-expert/references/performance-listview.md +251 -0
  71. package/skills/{alloy-expert/references/performance-patterns.md → ti-expert/references/performance-optimization.md} +67 -283
  72. package/skills/{alloy-expert/references/security-patterns.md → ti-expert/references/security-device.md} +12 -295
  73. package/skills/ti-expert/references/security-fundamentals.md +284 -0
  74. package/skills/{alloy-expert → ti-expert}/references/state-management.md +10 -10
  75. package/skills/ti-expert/references/testing-e2e-ci.md +432 -0
  76. package/skills/ti-expert/references/testing-unit.md +433 -0
  77. package/skills/ti-expert/references/theming.md +394 -0
  78. package/skills/ti-guides/SKILL.md +1 -14
  79. package/skills/ti-guides/references/advanced-data-and-images.md +126 -10
  80. package/skills/ti-guides/references/app-distribution.md +48 -10
  81. package/skills/ti-guides/references/application-frameworks.md +9 -2
  82. package/skills/ti-guides/references/cli-reference.md +338 -82
  83. package/skills/ti-guides/references/coding-best-practices.md +14 -4
  84. package/skills/ti-guides/references/commonjs-advanced.md +103 -6
  85. package/skills/ti-guides/references/hello-world.md +5 -2
  86. package/skills/ti-guides/references/hyperloop-native-access.md +439 -46
  87. package/skills/ti-guides/references/javascript-primer.md +4 -3
  88. package/skills/ti-guides/references/resources.md +0 -1
  89. package/skills/ti-guides/references/style-and-conventions.md +57 -9
  90. package/skills/ti-guides/references/tiapp-config.md +48 -6
  91. package/skills/ti-howtos/SKILL.md +2 -27
  92. package/skills/ti-howtos/references/android-platform-deep-dives.md +41 -90
  93. package/skills/ti-howtos/references/automation-fastlane-appium.md +15 -14
  94. package/skills/ti-howtos/references/buffer-codec-streams.md +22 -22
  95. package/skills/ti-howtos/references/cross-platform-development.md +68 -37
  96. package/skills/ti-howtos/references/debugging-profiling.md +8 -53
  97. package/skills/ti-howtos/references/extending-titanium.md +12 -51
  98. package/skills/ti-howtos/references/google-maps-v2.md +30 -29
  99. package/skills/ti-howtos/references/ios-map-kit.md +19 -25
  100. package/skills/ti-howtos/references/ios-platform-deep-dives.md +95 -283
  101. package/skills/ti-howtos/references/local-data-sources.md +45 -37
  102. package/skills/ti-howtos/references/location-and-maps.md +47 -28
  103. package/skills/ti-howtos/references/media-apis.md +84 -27
  104. package/skills/ti-howtos/references/notification-services.md +40 -89
  105. package/skills/ti-howtos/references/remote-data-sources.md +21 -36
  106. package/skills/ti-howtos/references/tutorials.md +79 -39
  107. package/skills/ti-howtos/references/using-modules.md +4 -30
  108. package/skills/ti-howtos/references/web-content-integration.md +28 -45
  109. package/skills/ti-howtos/references/webpack-build-pipeline.md +54 -18
  110. package/skills/ti-ui/SKILL.md +1 -21
  111. package/skills/ti-ui/references/accessibility-deep-dive.md +71 -25
  112. package/skills/ti-ui/references/animation-and-matrices.md +0 -47
  113. package/skills/ti-ui/references/application-structures.md +0 -46
  114. package/skills/ti-ui/references/custom-fonts-styling.md +9 -57
  115. package/skills/ti-ui/references/event-handling.md +32 -40
  116. package/skills/ti-ui/references/gestures.md +0 -40
  117. package/skills/ti-ui/references/icons-and-splash-screens.md +21 -44
  118. package/skills/ti-ui/references/layouts-and-positioning.md +47 -39
  119. package/skills/ti-ui/references/listviews-and-performance.md +187 -73
  120. package/skills/ti-ui/references/orientation.md +57 -71
  121. package/skills/ti-ui/references/platform-ui-android.md +114 -48
  122. package/skills/ti-ui/references/platform-ui-ios.md +63 -38
  123. package/skills/ti-ui/references/scrolling-views.md +14 -23
  124. package/skills/ti-ui/references/tableviews.md +6 -56
  125. package/lib/commands/install.js +0 -188
  126. package/skills/alloy-expert/references/anti-patterns.md +0 -133
  127. package/skills/alloy-expert/references/testing.md +0 -872
  128. package/skills/ti-guides/references/alloy-cli-advanced.md +0 -84
  129. package/skills/ti-guides/references/alloy-data-mastery.md +0 -29
  130. package/skills/ti-guides/references/alloy-widgets-and-themes.md +0 -19
  131. /package/skills/{alloy-expert → ti-expert}/assets/ControllerAutoCleanup.js +0 -0
  132. /package/skills/{alloy-expert → ti-expert}/references/contracts.md +0 -0
@@ -1,18 +1,5 @@
1
1
  # Alloy Configuration Files Reference
2
2
 
3
- ## Table of Contents
4
-
5
- - [Alloy Configuration Files Reference](#alloy-configuration-files-reference)
6
- - [Table of Contents](#table-of-contents)
7
- - [Build Configuration File (alloy.jmk)](#build-configuration-file-alloyjmk)
8
- - [Compiler Tasks (Event Names)](#compiler-tasks-event-names)
9
- - [Event Object](#event-object)
10
- - [Logger Object](#logger-object)
11
- - [Objects](#objects)
12
- - [Keys](#keys)
13
-
14
- ---
15
-
16
3
  ## Build Configuration File (alloy.jmk)
17
4
 
18
5
  Alloy provides hooks to customize compilation using a JS Makefile (JMK).
@@ -55,7 +42,64 @@ task('post:compile', (event, logger) => {
55
42
  | `appJSFile` | String | *(compile:app.js only)* Absolute path to `app.js` |
56
43
 
57
44
  ### Logger Object
58
- ...
45
+
46
+ The `logger` object provides methods and properties to control compilation log output.
47
+
48
+ #### Properties
49
+
50
+ | Property | Type | Description |
51
+ | --------------- | ------- | ----------------------------------------------- |
52
+ | `DEBUG` | Number | READONLY. Output all log messages. |
53
+ | `INFO` | Number | READONLY. Output all except debug messages. |
54
+ | `WARN` | Number | READONLY. Output only warning and error. |
55
+ | `ERROR` | Number | READONLY. Output only error messages. |
56
+ | `NONE` | Number | READONLY. Disable log messages. |
57
+ | `logLevel` | Number | Sets which log messages to output. |
58
+ | `showTimestamp` | Boolean | If `true`, outputs timestamp with log messages. |
59
+ | `stripColors` | Boolean | If `true`, suppresses color output. |
60
+
61
+ #### Methods
62
+
63
+ | Method | Description |
64
+ | -------------------- | ------------------------------ |
65
+ | `debug(msg: String)` | Outputs a debug log message. |
66
+ | `info(msg: String)` | Outputs an info log message. |
67
+ | `warn(msg: String)` | Outputs a warning log message. |
68
+ | `error(msg: String)` | Outputs an error log message. |
69
+
70
+ ---
71
+
72
+ ## Global Initializer (alloy.js)
73
+
74
+ **Location:** `app/alloy.js`
75
+
76
+ Executed before any controllers load. Use it to set up globals and singletons.
77
+
78
+ **Common uses:**
79
+ - Creating `Alloy.Collections` (e.g., `Alloy.Collections.myModel = Alloy.createCollection('myModel');`)
80
+ - Setting up `Alloy.Globals` (shared references, utility functions)
81
+ - Initializing singletons (analytics, logging, network managers)
82
+ - Configuring global event listeners
83
+
84
+ **Example:**
85
+ ```javascript
86
+ // app/alloy.js
87
+ Alloy.Globals.loading = Alloy.createWidget('com.example.loading');
88
+ Alloy.Collections.users = Alloy.createCollection('user');
89
+
90
+ // Global utility
91
+ Alloy.Globals.alert = (title, message) => {
92
+ Ti.UI.createAlertDialog({ title, message }).show();
93
+ };
94
+ ```
95
+
96
+ ---
97
+
98
+ ## Project Configuration File (config.json)
99
+
100
+ **Location:** `app/config.json`
101
+
102
+ Alloy uses `config.json` to specify global values, conditional environment and platform values, and widget dependencies.
59
103
  ### Objects
60
104
 
61
105
  | Object | Description |
@@ -71,7 +115,34 @@ task('post:compile', (event, logger) => {
71
115
  | `backbone` | Backbone.js version: `0.9.2` (default), `1.1.2`, or `1.3.3` |
72
116
 
73
117
  **Precedence:** `os` > `env` > `global`. Combinations (e.g., `os:ios env:production`) override single values.
74
- ...
118
+
119
+ **Runtime Access:** Values are accessible at runtime via `Alloy.CFG.<key>`.
120
+
121
+ **Example:**
122
+
123
+ ```json
124
+ {
125
+ "global": { "foo": 1 },
126
+ "env:development": { "foo": 2 },
127
+ "env:test": { "foo": 3 },
128
+ "env:production": { "foo": 4 },
129
+ "os:ios env:production": { "foo": 5 },
130
+ "os:ios env:development": { "foo": 6 },
131
+ "os:ios env:test": { "foo": 7 },
132
+ "os:android": { "foo": 8 },
133
+ "dependencies": {
134
+ "com.foo.widget": "1.0"
135
+ }
136
+ }
137
+ ```
138
+
139
+ Accessing values: `Ti.API.info(Alloy.CFG.foo)` — on iPhone simulator this returns `6`.
140
+
141
+ ---
142
+
143
+ ## Widget Configuration File (widget.json)
144
+
145
+ **Location:** Root directory of the widget. Follows the npm `package.json` format with a few exceptions.
75
146
  ### Keys
76
147
 
77
148
  | Key | Type | Required | Description |
@@ -2,19 +2,6 @@
2
2
 
3
3
  Custom tags allow you to create reusable UI components without the overhead of widgets. They are an incredibly fast way to build a suite of controls that are as easy to use as dropping a file into the `app/lib` folder.
4
4
 
5
- ## Table of Contents
6
-
7
- - [Creating Custom Tags in Titanium with Alloy](#creating-custom-tags-in-titanium-with-alloy)
8
- - [Table of Contents](#table-of-contents)
9
- - [Why Use Custom Tags?](#why-use-custom-tags)
10
- - [Basic Setup](#basic-setup)
11
- - [Robust Example: CheckBox](#robust-example-checkbox)
12
- - [Global Module Override](#global-module-override)
13
- - [Key Points](#key-points)
14
- - [Custom Tags vs Widgets](#custom-tags-vs-widgets)
15
-
16
- ---
17
-
18
5
  ## Why Use Custom Tags?
19
6
 
20
7
  When building cross-platform applications, you often need specific UI controls (like a web-style checkbox) that don't exist natively. You have three main approaches:
@@ -137,6 +124,20 @@ This is powerful for adding default colors or properties (like a black default c
137
124
  | Return value | Must return a `Ti.UI.*` component (View, Button, Label, etc.) |
138
125
  | Arguments | Receives all XML/TSS attributes in a single `args` object |
139
126
 
127
+ ## Using Custom Tags Without Alloy XML
128
+
129
+ You can also use custom tags from plain JavaScript via `require()`:
130
+
131
+ ```javascript
132
+ const checkbox = require("checkbox").createCheckBox({
133
+ caption: "I agree",
134
+ underline: true
135
+ });
136
+ win.add(checkbox);
137
+ ```
138
+
139
+ This works because custom tags are standard CommonJS modules — the `module` attribute in XML is just a convenience.
140
+
140
141
  ## Custom Tags vs Widgets
141
142
 
142
143
  | Custom Tags | Widgets |
@@ -1,24 +1,5 @@
1
1
  # Alloy Debugging and Troubleshooting
2
2
 
3
- ## Table of Contents
4
-
5
- - [Alloy Debugging and Troubleshooting](#alloy-debugging-and-troubleshooting)
6
- - [Table of Contents](#table-of-contents)
7
- - [Overview](#overview)
8
- - [Debugging](#debugging)
9
- - [Compiler Error Messages](#compiler-error-messages)
10
- - [Troubleshooting](#troubleshooting)
11
- - [Error: No app.js Found](#error-no-appjs-found)
12
- - [Android: Images, HTML and Assets Not Displaying](#android-images-html-and-assets-not-displaying)
13
- - [Android Runtime Error: Cannot Call Method of Undefined](#android-runtime-error-cannot-call-method-of-undefined)
14
- - [Android Runtime Error: Alloy is Not Defined](#android-runtime-error-alloy-is-not-defined)
15
- - [iOS Application Error: Invalid Method Passed to UIModule](#ios-application-error-invalid-method-passed-to-uimodule)
16
- - [iOS Application Error: Undefined is Not an Object](#ios-application-error-undefined-is-not-an-object)
17
- - [Getting Help](#getting-help)
18
- - [Submitting a Bug Report](#submitting-a-bug-report)
19
-
20
- ---
21
-
22
3
  ## Overview
23
4
 
24
5
  This guide covers debugging and troubleshooting Alloy applications.
@@ -61,7 +42,7 @@ alloy compile --config platform=<platform>
61
42
 
62
43
  **Error:** `Uncaught ReferenceError: Alloy is not defined`
63
44
 
64
- **Cause:** Non-controller JavaScript files are not automatically wrapped by Alloy.
45
+ **Cause:** Non-controller JavaScript files are not automatically wrapped by Alloy. See [best_practices.md](best_practices.md) for the safe require pattern for non-controller files.
65
46
 
66
47
  **Solution:** Require the 'alloy' module:
67
48
  ```javascript
@@ -86,14 +67,14 @@ const Alloy = require('alloy');
86
67
 
87
68
  ## Getting Help
88
69
 
89
- Use the [Titanium Community Questions and Answers Forum](https://developer.axway.com/develop-apps#DevelopApps_Engage):
70
+ Use the [TiDev Community Slack](https://slack.tidev.io/) or [GitHub Discussions](https://github.com/tidev/titanium-sdk/discussions):
90
71
  - Include 'alloy' as a tag
91
72
  - Include the Alloy version (run `alloy --version`)
92
73
  - Include platform information
93
74
 
94
75
  ## Submitting a Bug Report
95
76
 
96
- Use [GitHub Issues](https://github.com/tidev/alloy/issues):
77
+ Search [existing issues](https://github.com/tidev/alloy/issues) first to avoid duplicates. If none match, create a new issue:
97
78
  - Select 'Alloy' as the component
98
79
  - Include Alloy version (`alloy --version`)
99
80
  - Include environment information
@@ -1,19 +1,5 @@
1
1
  # Alloy Samples
2
2
 
3
- ## Table of Contents
4
-
5
- - [Alloy Samples](#alloy-samples)
6
- - [Table of Contents](#table-of-contents)
7
- - [Kitchen Sink](#kitchen-sink)
8
- - [Controller Sample](#controller-sample)
9
- - [Conditional Statements in Views](#conditional-statements-in-views)
10
- - [The Problem with Traditional Approaches](#the-problem-with-traditional-approaches)
11
- - [The Solution: IF Attributes in XML](#the-solution-if-attributes-in-xml)
12
- - [Conditional Queries in TSS](#conditional-queries-in-tss)
13
- - [Data-Binding with Conditional Queries](#data-binding-with-conditional-queries)
14
-
15
- ---
16
-
17
3
  ## Kitchen Sink
18
4
 
19
5
  See the [KitchenSink-v2 application on GitHub](https://github.com/tidev/kitchensink-v2) for Alloy samples in a real app.
@@ -70,6 +56,10 @@ if (!ENV_PROD) {
70
56
 
71
57
  Alloy separates business logic (controllers) from UI definition (XML/TSS). A common challenge is showing/hiding content based on app state (e.g., login status).
72
58
 
59
+ :::tip TSS DEFAULTS
60
+ The samples below assume some additional TSS: views and windows use a vertical layout, and the `View` tag has a default height and width of `Ti.UI.SIZE`.
61
+ :::
62
+
73
63
  ### The Problem with Traditional Approaches
74
64
 
75
65
  **Approach 1: show/hide (in controller)**
@@ -27,38 +27,6 @@ This skill automatically detects PurgeTSS usage when invoked and provides utilit
27
27
  - **Not detected** → Does NOT suggest PurgeTSS utility classes, does NOT recommend `$.UI.create()`, does NOT reference PurgeTSS-specific patterns
28
28
  :::
29
29
 
30
- ## Table of Contents
31
-
32
- - [PurgeTSS Expert](#purgetss-expert)
33
- - [Project Detection](#project-detection)
34
- - [Table of Contents](#table-of-contents)
35
- - [Core Workflow](#core-workflow)
36
- - [Project Structure](#project-structure)
37
- - [Understanding `app.tss` vs `_app.tss`](#understanding-apptss-vs-_apptss)
38
- - [Checking for Unused/Unsupported Classes](#checking-for-unusedunsupported-classes)
39
- - [How `utilities.tss` Works](#how-utilitiestss-works)
40
- - [Quick Start](#quick-start)
41
- - [Critical Rules (Low Freedom)](#critical-rules-low-freedom)
42
- - [⭐ PREFER `$.UI.create()` for Dynamic Components](#-prefer-uicreate-for-dynamic-components)
43
- - [🚨 RESPECT USER FILES](#-respect-user-files)
44
- - [🚨 NO FLEXBOX - Titanium Doesn't Support It](#-no-flexbox---titanium-doesnt-support-it)
45
- - [🚨 PLATFORM-SPECIFIC PROPERTIES REQUIRE MODIFIERS](#-platform-specific-properties-require-modifiers)
46
- - [Other Mandatory Rules](#other-mandatory-rules)
47
- - [Common Anti-Patterns](#common-anti-patterns)
48
- - [Class Verification Workflow](#class-verification-workflow)
49
- - [Verification Steps](#verification-steps)
50
- - [What HAS Classes vs What DOESN'T](#what-has-classes-vs-what-doesnt)
51
- - [Reference Guides](#reference-guides)
52
- - [Essential References](#essential-references)
53
- - [Setup \& Configuration](#setup--configuration)
54
- - [Customization](#customization)
55
- - [Layout \& Styling](#layout--styling)
56
- - [Fonts \& Animations](#fonts--animations)
57
- - [Examples](#examples)
58
- - [Related Skills](#related-skills)
59
-
60
- ---
61
-
62
30
  ## Core Workflow
63
31
 
64
32
  1. **Setup**: `purgetss create 'name'` or `purgetss init` for existing projects
@@ -229,16 +197,15 @@ When building complex UIs, carefully choose the layout mode for each container:
229
197
 
230
198
  **`composite`** (default) - Absolute positioning with `top`, `left`, etc.:
231
199
  ```xml
232
- <View class="w-screen h-screen">
233
- <View class="absolute top-0 left-0 bg-red-500 wh-12" />
234
- <View class="absolute bottom-0 right-0 bg-blue-500 wh-12" />
200
+ <View class="h-screen w-screen">
201
+ <View class="wh-12 absolute left-0 top-0 bg-red-500" />
202
+ <View class="wh-12 absolute bottom-0 right-0 bg-blue-500" />
235
203
  </View>
236
204
  ```
237
205
 
238
206
  **Common Issue:** If you see elements appearing in unexpected positions (e.g., a header bar "behind" content), check if parent containers have conflicting layout modes. Each container's layout affects its direct children only.
239
207
  :::
240
208
 
241
-
242
209
  ### 🚨 PLATFORM-SPECIFIC PROPERTIES REQUIRE MODIFIERS
243
210
 
244
211
  :::danger CRITICAL: Platform-Specific Properties Require Modifiers
@@ -395,6 +362,7 @@ Load these only when needed:
395
362
  ### Setup & Configuration
396
363
  - [Installation & Setup](references/installation-setup.md) - First run, VS Code, LiveView
397
364
  - [CLI Commands](references/cli-commands.md) - All `purgetss` commands
365
+ - [Migration Guide](references/migration-guide.md) - Migrating existing apps from manual TSS to PurgeTSS
398
366
 
399
367
  ### Customization
400
368
  - [Deep Customization](references/customization-deep-dive.md) - config.cjs, colors, spacing, Ti Elements
@@ -411,6 +379,12 @@ Load these only when needed:
411
379
  - [Opacity Modifier](references/opacity-modifier.md) - Color transparency with /50 syntax
412
380
  - [Titanium Resets](references/titanium-resets.md) - Default styles for Ti elements
413
381
 
382
+ ### Performance
383
+ - [Performance Tips](references/performance-tips.md) - Optimizing PurgeTSS apps (bridge crossings, ListView, animations)
384
+
385
+ ### Components
386
+ - [TiKit UI Components](references/tikit-components.md) - Ready-to-use Alerts, Avatars, Buttons, Cards, Tabs built with PurgeTSS
387
+
414
388
  ### Fonts & Animations
415
389
  - [Icon Fonts](references/icon-fonts.md) - Font Awesome 7, Material Icons, custom icon libraries
416
390
  - [Animation Component](references/animation-system.md) - Declarative `<Animation>` API
@@ -436,7 +410,7 @@ For tasks beyond styling, use these complementary skills:
436
410
 
437
411
  | Task | Use This Skill |
438
412
  | -------------------------------------------- | -------------- |
439
- | Project architecture, services, controllers | `alloy-expert` |
413
+ | Project architecture, services, controllers | `ti-expert` |
440
414
  | Complex UI components, ListViews, gestures | `ti-ui` |
441
415
  | Alloy MVC concepts, data binding, TSS syntax | `alloy-guides` |
442
416
  | Native features (camera, location, push) | `ti-howtos` |
@@ -2,23 +2,6 @@
2
2
 
3
3
  Complete examples of common patterns with anti-patterns and correct implementations.
4
4
 
5
- ## Table of Contents
6
-
7
- - [PurgeTSS Examples - WRONG vs CORRECT](#purgetss-examples---wrong-vs-correct)
8
- - [Table of Contents](#table-of-contents)
9
- - [Titanium Layout Patterns](#titanium-layout-patterns)
10
- - [Horizontal Row with Space Between](#horizontal-row-with-space-between)
11
- - [Centered Content (Vertically and Horizontally)](#centered-content-vertically-and-horizontally)
12
- - [Vertical Stack with Spacing](#vertical-stack-with-spacing)
13
- - [Header with Left/Right Elements](#header-with-leftright-elements)
14
- - [Available Layout Classes](#available-layout-classes)
15
- - [Manual .tss Files Anti-Pattern](#manual-tss-files-anti-pattern)
16
- - [Grid with Percentages](#grid-with-percentages)
17
- - [Gap Usage](#gap-usage)
18
- - [Layout Defaults](#layout-defaults)
19
-
20
- ---
21
-
22
5
  ## Titanium Layout Patterns
23
6
 
24
7
  :::danger NO FLEXBOX IN TITANIUM
@@ -218,6 +201,94 @@ alloy compile
218
201
 
219
202
  ---
220
203
 
204
+ ## Padding on Container Views
205
+
206
+ **❌ WRONG (Padding on Views doesn't work in Titanium):**
207
+ ```xml
208
+ <View class="p-4">
209
+ <Label text="Hello" />
210
+ </View>
211
+ ```
212
+
213
+ **✅ CORRECT (Use margins on children instead):**
214
+ ```xml
215
+ <View>
216
+ <Label class="m-4" text="Hello" />
217
+ </View>
218
+ ```
219
+
220
+ **Why:** Titanium Views don't support padding properties. Use margins on child elements.
221
+
222
+ ---
223
+
224
+ ## `w-full` vs `w-screen`
225
+
226
+ **❌ WRONG (Using percentage-based width):**
227
+ ```xml
228
+ <View class="w-full">
229
+ <Label text="Full width" />
230
+ </View>
231
+ ```
232
+
233
+ **✅ CORRECT (Use Ti.UI.FILL):**
234
+ ```xml
235
+ <View class="w-screen">
236
+ <Label text="Full width" />
237
+ </View>
238
+ ```
239
+
240
+ **Difference:**
241
+ - `w-full` = `width: '100%'` (percentage of parent)
242
+ - `w-screen` = `width: Ti.UI.FILL` (native fill constant)
243
+
244
+ **Use `w-screen` for full-width elements** in Titanium.
245
+
246
+ ---
247
+
248
+ ## `rounded-full` Without Size
249
+
250
+ **❌ WRONG (rounded-full alone doesn't exist):**
251
+ ```xml
252
+ <View class="h-12 w-12 rounded-full" />
253
+ ```
254
+
255
+ **✅ CORRECT (Use rounded-full-XX where XX × 4 = element size):**
256
+ ```xml
257
+ <!-- For 48×48 circle, use rounded-full-12 (12 × 4 = 48) -->
258
+ <View class="rounded-full-12" />
259
+ ```
260
+
261
+ **Note:** `rounded-full-XX` already includes width and height. No need for separate `w-` or `h-` classes.
262
+
263
+ **Examples:**
264
+ - `rounded-full-8` = 32×32 circle
265
+ - `rounded-full-12` = 48×48 circle
266
+ - `rounded-full-16` = 64×64 circle
267
+
268
+ ---
269
+
270
+ ## Square Brackets for Arbitrary Values
271
+
272
+ **❌ WRONG (Using square brackets like Tailwind CSS):**
273
+ ```xml
274
+ <View class="w-[100px] bg-[#ff0000]" />
275
+ ```
276
+
277
+ **✅ CORRECT (PurgeTSS uses parentheses):**
278
+ ```xml
279
+ <View class="w-(100px) bg-(#ff0000)" />
280
+ ```
281
+
282
+ **PurgeTSS syntax for arbitrary values uses `()` not `[]`.**
283
+
284
+ **Examples:**
285
+ - `w-(100px)` - Custom width
286
+ - `bg-(#ff0000)` - Custom background color
287
+ - `mt-(20dp)` - Custom margin top
288
+ - `text-(#333333)` - Custom text color
289
+
290
+ ---
291
+
221
292
  ## Layout Defaults
222
293
 
223
294
  **❌ WRONG (Explicit composite class):**
@@ -245,3 +316,21 @@ alloy compile
245
316
  <!-- Omitting layout defaults to composite -->
246
317
  <View>
247
318
  ```
319
+
320
+ ---
321
+
322
+ ## Quick Reference Table
323
+
324
+ | Anti-Pattern | Why It Fails | Correct Approach |
325
+ | --------------------- | ------------------------ | ----------------------- |
326
+ | `flex-row` | Flexbox not supported | `horizontal` |
327
+ | `flex-col` | Flexbox not supported | `vertical` |
328
+ | `justify-*` | Flexbox not supported | Use margins/positioning |
329
+ | `items-center` | Flexbox not supported | Use `center` class |
330
+ | `p-4` on View | No padding on containers | `m-4` on children |
331
+ | `w-full` | Percentage-based | `w-screen` (Ti.UI.FILL) |
332
+ | `rounded-full` | Needs size suffix | `rounded-full-12` |
333
+ | `composite` class | Already default | Omit it |
334
+ | `w-[100px]` | Wrong syntax | `w-(100px)` |
335
+ | Manual `.tss` | Overwritten by PurgeTSS | Use utility classes |
336
+ | `gap` with `%` widths | Total exceeds 100% | Use explicit margins |
@@ -13,73 +13,6 @@ The Animation object describes the properties of an animation. It represents:
13
13
 
14
14
  When the `play` method is called on a View, the View is animated from its current state to the state described by the `Animation` object. The properties that can be animated include the view's position, size, colors, transformation matrix, and opacity.
15
15
 
16
- ## Table of Contents
17
-
18
- - [PurgeTSS Animation System](#purgetss-animation-system)
19
- - [Table of Contents](#table-of-contents)
20
- - [Installation](#installation)
21
- - [Basic Usage](#basic-usage)
22
- - [Available Methods](#available-methods)
23
- - [The `play` Method](#the-play-method)
24
- - [`play(views, [callback])`](#playviews-callback)
25
- - [Play Example 1](#play-example-1)
26
- - [Play Example 2: Complex Animations with States](#play-example-2-complex-animations-with-states)
27
- - [`toggle(views, [callback])`](#toggleviews-callback)
28
- - [The `open` and `close` Methods](#the-open-and-close-methods)
29
- - [`open(views, [callback])`](#openviews-callback)
30
- - [Open Method Example](#open-method-example)
31
- - [`close(views, [callback])`](#closeviews-callback)
32
- - [Close Method Example](#close-method-example)
33
- - [The `apply` Method](#the-apply-method)
34
- - [`apply(views)`](#applyviews)
35
- - [Apply Example: TikTok-like Interface](#apply-example-tiktok-like-interface)
36
- - [The `draggable` Method](#the-draggable-method)
37
- - [Draggable Example](#draggable-example)
38
- - [`drag` and `drop` Modifiers](#drag-and-drop-modifiers)
39
- - [Drag \& Drop Example](#drag--drop-example)
40
- - [`draggingType` Property](#draggingtype-property)
41
- - [Dragging Type Example](#dragging-type-example)
42
- - [`bounds` Modifier](#bounds-modifier)
43
- - [Bounds Example 1: Local Bounds](#bounds-example-1-local-bounds)
44
- - [Bounds Example 2: Global Bounds](#bounds-example-2-global-bounds)
45
- - [`vertical` and `horizontal` Constraints](#vertical-and-horizontal-constraints)
46
- - [Constraint Example](#constraint-example)
47
- - [State Modifiers](#state-modifiers)
48
- - [`open:` and `close:`](#open-and-close)
49
- - [`complete:` Modifier](#complete-modifier)
50
- - [Complete Example: Wordle Animation](#complete-example-wordle-animation)
51
- - [`children:`](#children)
52
- - [`child:`](#child)
53
- - [Complex UI Elements](#complex-ui-elements)
54
- - [Available Utilities](#available-utilities)
55
- - [anchorPoint](#anchorpoint)
56
- - [autoreverse](#autoreverse)
57
- - [curve](#curve)
58
- - [delay](#delay)
59
- - [duration](#duration)
60
- - [repeat](#repeat)
61
- - [rotate](#rotate)
62
- - [scale](#scale)
63
- - [drag-apply, drag-animate](#drag-apply-drag-animate)
64
- - [opacity-to-\*, toggle-visible](#opacity-to--toggle-visible)
65
- - [zoom-in-*, zoom-out-*](#zoom-in--zoom-out-)
66
- - [Best Practices](#best-practices)
67
- - [1. Use Semantic IDs](#1-use-semantic-ids)
68
- - [2. Combine Methods for Sequences](#2-combine-methods-for-sequences)
69
- - [3. Use `complete:` for Post-Animation State](#3-use-complete-for-post-animation-state)
70
- - [4. Leverage `children:` for Batch Animations](#4-leverage-children-for-batch-animations)
71
- - [5. Use `toggle` for UI States](#5-use-toggle-for-ui-states)
72
- - [Common Patterns](#common-patterns)
73
- - [Modal Fade In/Out](#modal-fade-inout)
74
- - [Slide Up/Down](#slide-updown)
75
- - [Scale on Touch](#scale-on-touch)
76
- - [Draggable Element with Bounds](#draggable-element-with-bounds)
77
- - [Animation Properties Summary](#animation-properties-summary)
78
- - [State Modifiers](#state-modifiers-1)
79
- - [Timing and Special Classes](#timing-and-special-classes)
80
-
81
- ---
82
-
83
16
  ## Installation
84
17
 
85
18
  ```bash
@@ -1,23 +1,5 @@
1
1
  # The `apply` Directive
2
2
 
3
- ## Table of Contents
4
-
5
- - [The `apply` Directive](#the-apply-directive)
6
- - [Table of Contents](#table-of-contents)
7
- - [Create Complex Classes and IDs](#create-complex-classes-and-ids)
8
- - [Set Any ID, Class, or Ti Element](#set-any-id-class-or-ti-element)
9
- - [Use Any of the Default Classes](#use-any-of-the-default-classes)
10
- - [Use Arbitrary Values](#use-arbitrary-values)
11
- - [Use Any Newly Defined Class in config.cjs](#use-any-newly-defined-class-in-configcjs)
12
- - [Set a String of Classes or an Array of Classes](#set-a-string-of-classes-or-an-array-of-classes)
13
- - [Combine with Any Platform, Device, or Conditional-Block Properties](#combine-with-any-platform-device-or-conditional-block-properties)
14
- - [Platform-Specific Classes](#platform-specific-classes)
15
- - [Omitting the Platform Variant](#omitting-the-platform-variant)
16
- - [Complete Example with Platform Variants](#complete-example-with-platform-variants)
17
- - [Composing Component Libraries](#composing-component-libraries)
18
-
19
- ---
20
-
21
3
  ## Create Complex Classes and IDs
22
4
 
23
5
  :::info
@@ -2,31 +2,6 @@
2
2
 
3
3
  Sometimes, you may need a specific value that is not included among the default values, or that you only need to use once in your project and do not want to include in the `config.cjs` file. In these cases, you can use **arbitrary values**.
4
4
 
5
- ## Table of Contents
6
-
7
- - [Arbitrary Values in PurgeTSS](#arbitrary-values-in-purgetss)
8
- - [Table of Contents](#table-of-contents)
9
- - [Parentheses Notation](#parentheses-notation)
10
- - [Color Properties](#color-properties)
11
- - [Example with Generated Output](#example-with-generated-output)
12
- - [Additional Examples](#additional-examples)
13
- - [Complete List of Color Properties](#complete-list-of-color-properties)
14
- - [Spacing Properties](#spacing-properties)
15
- - [Example with Generated Output](#example-with-generated-output-1)
16
- - [Unit Conversion Rules](#unit-conversion-rules)
17
- - [Additional Examples](#additional-examples-1)
18
- - [Complete List of Spacing Properties](#complete-list-of-spacing-properties)
19
- - [Miscellaneous Properties](#miscellaneous-properties)
20
- - [Examples](#examples)
21
- - [Complete List of Miscellaneous Properties](#complete-list-of-miscellaneous-properties)
22
- - [Real-World Examples](#real-world-examples)
23
- - [Credit Card Component](#credit-card-component)
24
- - [Front Cover Example](#front-cover-example)
25
- - [Menu Bar Example](#menu-bar-example)
26
- - [Tips for Using Arbitrary Values](#tips-for-using-arbitrary-values)
27
-
28
- ---
29
-
30
5
  ## Parentheses Notation
31
6
 
32
7
  :::info
@@ -7,52 +7,6 @@ Before suggesting ANY class, verify it exists:
7
7
  grep -E "PATTERN" ./purgetss/styles/utilities.tss
8
8
  ```
9
9
 
10
- ## Table of Contents
11
-
12
- - [PurgeTSS Class Index](#purgetss-class-index)
13
- - [Table of Contents](#table-of-contents)
14
- - [PurgeTSS Naming Conventions](#purgetss-naming-conventions)
15
- - [How Classes Are Generated from Titanium Properties](#how-classes-are-generated-from-titanium-properties)
16
- - [1. Basic Conversion: camelCase → kebab-case](#1-basic-conversion-camelcase--kebab-case)
17
- - [2. Boolean Properties: `property` and `property-false`](#2-boolean-properties-property-and-property-false)
18
- - [3. Color Properties: Special Word Replacements](#3-color-properties-special-word-replacements)
19
- - [4. No kebab-case Conversion](#4-no-kebab-case-conversion)
20
- - [Finding Properties in utilities.tss](#finding-properties-in-utilitiestss)
21
- - [Multiple Properties Grouped Together](#multiple-properties-grouped-together)
22
- - [All 416 Titanium Properties with Classes](#all-416-titanium-properties-with-classes)
23
- - [A-E](#a-e)
24
- - [F-L](#f-l)
25
- - [M-P](#m-p)
26
- - [R-Z](#r-z)
27
- - [Class Categories by Prefix (Complete Inventory)](#class-categories-by-prefix-complete-inventory)
28
- - [Layout \& Structure](#layout--structure)
29
- - [Spacing (Margins \& Padding)](#spacing-margins--padding)
30
- - [Positioning](#positioning)
31
- - [Colors (Background)](#colors-background)
32
- - [Colors (Text \& Foreground)](#colors-text--foreground)
33
- - [Borders \& Radius](#borders--radius)
34
- - [Typography](#typography)
35
- - [Accessibility](#accessibility)
36
- - [Input \& Keyboard](#input--keyboard)
37
- - [Boolean \& State Classes](#boolean--state-classes)
38
- - [Text Transformation](#text-transformation)
39
- - [Opacity](#opacity)
40
- - [Transformation \& Animation](#transformation--animation)
41
- - [Shadows \& Elevation](#shadows--elevation)
42
- - [Z-Index \& Overflow](#z-index--overflow)
43
- - [Status Bar \& Navigation](#status-bar--navigation)
44
- - [UI Component States](#ui-component-states)
45
- - [Display \& Sizing](#display--sizing)
46
- - [Media \& Video](#media--video)
47
- - [Other Special Prefixes](#other-special-prefixes)
48
- - [PROHIBITED: CSS Classes (DO NOT EXIST)](#prohibited-css-classes-do-not-exist)
49
- - [All 364 Unique Prefixes (Alphabetical)](#all-364-unique-prefixes-alphabetical)
50
- - [Quick Verification Commands](#quick-verification-commands)
51
- - [When to Use Direct Properties (No Classes)](#when-to-use-direct-properties-no-classes)
52
- - [Key Insights from Real Data](#key-insights-from-real-data)
53
-
54
- ---
55
-
56
10
  ## PurgeTSS Naming Conventions
57
11
 
58
12
  ### How Classes Are Generated from Titanium Properties