purgetss 7.4.0 → 7.5.0

package/README.md

@@ -10,62 +10,18 @@
 
 </div>
 
-**PurgeTSS** is a toolkit for building mobile apps with the [Titanium framework](https://titaniumsdk.com). It adds practical utilities to speed up styling and reduce repeated setup work.
-
-It includes utility classes, icon font support, an Animation module, a simple grid system, and the `shades` command for generating custom colors.
-
-If you build UI-heavy screens, PurgeTSS helps you move faster without hand-writing long TSS files.
+**PurgeTSS** is a toolkit for building mobile apps with the [Titanium framework](https://titaniumsdk.com). It provides utility classes, icon font support, an Animation module, a grid system, and the `shades` command for generating custom colors.
 
 ---
 
-## What's New in v7.3.x
-
-**File rename and improved error handling.** PurgeTSS v7.3 renames `tailwind.tss` to `utilities.tss` to reflect the project's standalone identity, and adds XML syntax validation to catch errors early.
-
-### Breaking changes
-
-- **File rename**: Output file is now `utilities.tss` instead of `tailwind.tss`
-  - Generated file: `purgetss/styles/utilities.tss` (was `purgetss/styles/tailwind.tss`)
-  - Distribution file: `dist/utilities.tss` (was `dist/tailwind.tss`)
-
-### Major improvements
-
-- **XML syntax validation**: Catches common Alloy XML malformations before processing
-  - Detects missing opening `<` brackets (e.g., `Label id=` instead of `<Label id=`)
-  - Shows detailed error messages with line numbers, context preview, and fix suggestions
-  - Saves debugging time by catching errors early in the build process
-
-- **Classic Titanium compatibility**: `deviceInfo()` function now works in both Alloy and Classic projects
-  - Removed dependency on `Alloy.isTablet`/`Alloy.isHandheld`
-  - Uses platform-based detection instead
-
-### Migration guide
-
-If you have references to `tailwind.tss` in your project, update them to `utilities.tss`:
-
-```bash
-# Update any custom scripts or paths
-# From: purgetss/styles/tailwind.tss
-# To:   purgetss/styles/utilities.tss
-```
-
-For most users, upgrading is straightforward:
-```bash
-npm install -g purgetss@latest
-```
-
----
-
-Here are its main functionalities:
-
-- **Utility-First Classes**: PurgeTSS ships with 21,000+ utility classes, so you get a lot of styling options out of the box.
-- **Efficient style management**: It parses all XML files to create a clean `app.tss` containing only the classes used in your project, reducing size and improving performance.
-- **Customization and JIT classes**: You can customize default classes via a config file and use JIT classes for arbitrary values inside views.
-- **Icon fonts integration**: Use icon fonts such as Font Awesome, Material Icons, Material Symbols, and Framework7-Icons in Buttons and Labels.
-- **`fonts.tss` generation**: The `build-fonts` command creates a `fonts.tss` file with class definitions and fontFamily selectors for regular and icon fonts, with simplified options for filenames and icon prefixes.
-- **`shades` command**: Generate custom color shades from a hex color without external tools.
-- **Animation module**: Apply basic 2D matrix animations or transformations to elements or arrays of elements.
-- **Grid system**: A two-dimensional grid system to align and distribute elements within views.
+- 21,000+ utility classes for styling Titanium views
+- Parses XML files to generate a clean `app.tss` with only the classes your project uses
+- Customizable defaults via `config.cjs`, with JIT classes for arbitrary values
+- Icon font support: Font Awesome, Material Icons, Material Symbols, Framework7-Icons
+- `build-fonts` command generates `fonts.tss` with class definitions and fontFamily selectors
+- `shades` command generates color shades from any hex color
+- Animation module for 2D matrix animations on views or arrays of views
+- Grid system for aligning and distributing elements within views
 
 ---
 
@@ -83,13 +39,22 @@ You can use any position, size, color, opacity, or transformation class from `ut
 
 ### Available methods
 
-| Method                                  | Description                                                                                   |
-| --------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `play(views, cb)` / `toggle(views, cb)` | Animate views from current state to the animation state. Toggles `open`/`close` on each call. |
-| `open(views, cb)`                       | Explicitly run the `open` state animation.                                                    |
-| `close(views, cb)`                      | Explicitly run the `close` state animation.                                                   |
-| `apply(views, cb)`                      | Apply properties instantly without animation.                                                 |
-| `draggable(views)`                      | Make a view or array of views draggable inside their parent.                                  |
+| Method                                    | Description                                                                                                                                                                                                                                     |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `play(views, cb)` / `toggle(views, cb)`   | Animate views from current state to the animation state. Toggles `open`/`close` on each call.                                                                                                                                                   |
+| `open(views, cb)`                         | Explicitly run the `open` state animation.                                                                                                                                                                                                      |
+| `close(views, cb)`                        | Explicitly run the `close` state animation.                                                                                                                                                                                                     |
+| `apply(views, cb)`                        | Apply properties instantly without animation.                                                                                                                                                                                                   |
+| `draggable(views)`                        | Make a view or array of views draggable inside their parent.                                                                                                                                                                                    |
+| `undraggable(views)`                      | Remove draggable behavior and clean up all listeners.                                                                                                                                                                                           |
+| `detectCollisions(views, dragCB, dropCB)` | Enable collision detection on draggable views with hover and drop callbacks.                                                                                                                                                                    |
+| `swap(view1, view2)`                      | Animate two views exchanging positions. Auto-normalizes position from margins/right/center via `view.rect`. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                             |
+| `sequence(views, cb)`                     | Animate views one after another. Callback fires after the last view.                                                                                                                                                                            |
+| `shake(view, intensity)`                  | Bidirectional shake animation for error feedback. Inherits `duration`, `delay`; fallback: 400ms. Default intensity: 10px.                                                                                                                       |
+| `pulse(view, count)`                      | Scale-up-and-back pulse animation. Scale from Animation object (default 1.2x). Count: number of pulses (default 1).                                                                                                                             |
+| `snapTo(view, targets)`                   | Snap a view to the nearest target by center distance. Auto-normalizes target position. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                                                  |
+| `reorder(views, newOrder)`                | Animate views to new positions based on index mapping. Auto-normalizes positions. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                                                       |
+| `transition(views, layouts)`              | Multi-view layout transitions using `Matrix2D.translate().rotate().scale()`. Layout properties: `translation`, `rotate`, `scale`, `zIndex`. Compatible with TiDesigner presets. Views without a layout entry fade out; returning views fade in. |
 
 ### Callback event object
 
@@ -144,6 +109,114 @@ $.myAnimation.draggable([$.card1, $.card2])
 
 Use `bounds` to restrict movement, and `drag`/`drop` modifiers for drag-state animations. Use `vertical-constraint` or `horizontal-constraint` classes to limit the drag axis.
 
+### Collision detection
+
+After calling `draggable()`, you can enable collision detection to know when a dragged view overlaps another:
+
+```js
+$.myAnimation.draggable(views)
+$.myAnimation.detectCollisions(views, onHover, onDrop)
+```
+
+**`dragCB(source, target)`** is called during drag:
+- `target` is the view under the drag center, or `null` when leaving all targets
+- Use this to show visual feedback (highlights, borders, scaling)
+
+**`dropCB(source, target)`** is called on drop:
+- `target` is the view where the source was released
+- If no target is found, the source automatically snaps back to its original position with a 200ms animation
+
+### Swap animation
+
+Animate two views exchanging positions:
+
+```js
+$.myAnimation.swap(view1, view2)
+```
+
+- Inherits `duration`, `delay`, and `curve` from the Animation object's classes
+- Falls back to 200ms duration, 0ms delay, and ease-in-out curve if not set
+- Handles iOS transform reset automatically
+- Temporarily raises z-index so views animate above siblings
+- Updates internal `_originLeft`/`_originTop` for subsequent drag operations
+
+### Sequence animation
+
+Animate views one after another (unlike `play(array)` which runs them in parallel):
+
+```js
+$.fadeIn.sequence([$.title, $.subtitle, $.button], () => {
+  console.log('All views animated')
+})
+```
+
+- Each view fully completes before the next starts
+- Callback fires once after the last view
+- Respects `open`/`close` state (set once for the entire sequence)
+
+### Shake animation
+
+Quick horizontal shake for error feedback, using native `autoreverse` + `repeat` for smooth performance:
+
+```js
+$.myAnimation.shake($.loginButton)        // default intensity: 10px
+$.myAnimation.shake($.input, 6)           // subtle: 6px
+$.myAnimation.shake($.errorLabel, 20)     // strong: 20px
+```
+
+### Snap to nearest target
+
+After dragging, snap a view to the closest target by center-to-center distance:
+
+```js
+const matched = $.myAnimation.snapTo(draggedView, slotViews)
+if (matched) {
+  console.log('Snapped to:', matched.id)
+}
+```
+
+### Reorder animation
+
+Animate an array of views to new positions based on index mapping:
+
+```js
+// Reverse order: view[0] goes to position of view[2], view[2] to position of view[0]
+$.myAnimation.reorder(cardViews, [2, 1, 0])
+```
+
+- All views animate simultaneously
+- Captures positions before animating to avoid conflicts
+
+### Removing draggable behavior
+
+Remove draggable behavior and clean up all event listeners:
+
+```js
+$.myAnimation.undraggable(cardViews)
+```
+
+### Property inheritance
+
+The `swap`, `reorder`, `snapTo`, and `shake` methods inherit animation properties from the `<Animation>` object's classes. This means you can configure behavior declaratively in XML:
+
+```xml
+<Animation id="myAnim" module="purgetss.ui" class="curve-animation-ease-out delay-100 duration-150" />
+```
+
+| Property      | `play`/`toggle`/`open`/`close`/`sequence` | `swap`/`reorder`/`snapTo` |       `shake`       |
+| ------------- | :---------------------------------------: | :-----------------------: | :-----------------: |
+| `duration`    |                     ✅                     |             ✅             |       ✅ (÷6)        |
+| `delay`       |                     ✅                     |             ✅             |          ✅          |
+| `curve`       |                     ✅                     |             ✅             | fixed `EASE_IN_OUT` |
+| `autoreverse` |                     ✅                     |             —             |    fixed `true`     |
+| `repeat`      |                     ✅                     |             —             |      fixed `3`      |
+
+Fallback defaults when not set: `swap`/`reorder`/`snapTo` → 200ms; `shake` → 400ms. All animation timing is controlled declaratively via the `<Animation>` object's classes.
+
+- Removes touch and orientation listeners
+- Removes views from collision detection registry
+- Cleans up internal tracking properties
+
 ### Utility classes for animations
 
 | Class pattern                                       | Description                   |
@@ -167,7 +240,57 @@ Use `bounds` to restrict movement, and `drag`/`drop` modifiers for drag-state an
 
 See the full documentation at [purgetss.com/docs/animation-module/introduction](https://purgetss.com/docs/animation-module/introduction).
 
-In short, PurgeTSS keeps styling consistent and removes a lot of repetitive UI setup work.
+---
+
+## Customizing default components
+
+PurgeTSS sets defaults for three components out of the box:
+
+| Component   | Default                                 |
+| ----------- | --------------------------------------- |
+| `Window`    | `backgroundColor: '#FFFFFF'`            |
+| `View`      | `width: Ti.UI.SIZE, height: Ti.UI.SIZE` |
+| `ImageView` | `hires: true` (iOS only)                |
+
+Override or extend them in `config.cjs` with `theme.extend`:
+
+```js
+module.exports = {
+  theme: {
+    extend: {
+      Window: {
+        apply: 'exit-on-close-false bg-surface'
+      }
+    }
+  }
+}
+```
+
+If an applied class sets a property that already exists in the defaults (e.g., `bg-surface` vs `backgroundColor: '#FFFFFF'`), the applied value wins. Array-type properties like `extendEdges` and `orientationModes` use bracket notation (`[ ]`) in the generated output.
+
+### Shorthand and explicit forms
+
+Both are equivalent:
+
+```js
+// Shorthand
+Window: { apply: 'exit-on-close-false' }
+
+// Explicit
+Window: { default: { apply: 'exit-on-close-false' } }
+```
+
+Use the explicit form when you need platform-specific variants:
+
+```js
+Button: {
+  default: { apply: 'text-xl' },
+  ios: { apply: 'font-bold' },
+  android: { apply: 'text-2xl font-semibold', color: 'red' }
+}
+```
+
+---
 
 ### Visit the official documentation site at [purgetss.com](https://purgetss.com) to learn more.
 

package/dist/fontawesome.js

@@ -1,5 +1,5 @@
 /**
- * Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com
+ * Font Awesome Free 7.2.0 by @fontawesome - https://fontawesome.com
  * License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
 */
 
@@ -169,6 +169,7 @@ const icons = {
 	'chartColumn': '\ue0e3',
 	'chartGantt': '\ue0e4',
 	'clapperboard': '\ue131',
+	'closedCaptioningSlash': '\ue135',
 	'clover': '\ue139',
 	'codeCompare': '\ue13a',
 	'codeFork': '\ue13b',
@@ -489,12 +490,25 @@ const icons = {
 	'pentagon': '\ue790',
 	'nonBinary': '\ue807',
 	'spiral': '\ue80a',
+	'pictureInPicture': '\ue80b',
 	'mobileVibrate': '\ue816',
 	'singleQuoteLeft': '\ue81b',
 	'singleQuoteRight': '\ue81c',
 	'busSide': '\ue81d',
 	'septagon': '\ue820',
 	'heptagon': '\ue820',
+	'aquarius': '\ue845',
+	'aries': '\ue846',
+	'cancer': '\ue847',
+	'capricorn': '\ue848',
+	'gemini': '\ue849',
+	'leo': '\ue84a',
+	'libra': '\ue84b',
+	'pisces': '\ue84c',
+	'sagittarius': '\ue84d',
+	'scorpio': '\ue84e',
+	'taurus': '\ue84f',
+	'virgo': '\ue850',
 	'martiniGlassEmpty': '\uf000',
 	'glassMartini': '\uf000',
 	'music': '\uf001',
@@ -1820,6 +1834,8 @@ const icons = {
 	'torah': '\uf6a0',
 	'toriiGate': '\uf6a1',
 	'vihara': '\uf6a7',
+	'volume': '\uf6a8',
+	'volumeMedium': '\uf6a8',
 	'volumeXmark': '\uf6a9',
 	'volumeMute': '\uf6a9',
 	'volumeTimes': '\uf6a9',
@@ -2138,6 +2154,44 @@ const icons = {
 	'squareFigma': '\ue7e4',
 	'tex': '\ue7ff',
 	'duolingo': '\ue812',
+	'supportnow': '\ue833',
+	'torBrowser': '\ue838',
+	'typescript': '\ue840',
+	'squareDeskpro': '\ue844',
+	'circleZulip': '\ue851',
+	'julia': '\ue852',
+	'zulip': '\ue853',
+	'unison': '\ue854',
+	'boardGameGeek': '\ue855',
+	'bgg': '\ue855',
+	'koFi': '\ue856',
+	'kubernetes': '\ue857',
+	'postgresql': '\ue858',
+	'scaleway': '\ue859',
+	'venmo': '\ue85a',
+	'venmoV': '\ue85b',
+	'unrealEngine': '\ue85c',
+	'globaleaks': '\ue85d',
+	'solana': '\ue85e',
+	'threema': '\ue85f',
+	'forgejo': '\ue860',
+	'claude': '\ue861',
+	'gitee': '\ue863',
+	'xmpp': '\ue864',
+	'fediverse': '\ue865',
+	'tailwindCss': '\ue866',
+	'archLinux': '\ue867',
+	'svelte': '\ue868',
+	'huggingFace': '\ue869',
+	'leetcode': '\ue86a',
+	'openstreetmap': '\ue86b',
+	'ultralytics': '\ue86d',
+	'ultralyticsHub': '\ue86e',
+	'ultralyticsYolo': '\ue86f',
+	'obsidian': '\ue879',
+	'zoom': '\ue87b',
+	'vim': '\ue88a',
+	'symfonycasts': '\ue8ab',
 	'squareTwitter': '\uf081',
 	'twitterSquare': '\uf081',
 	'squareFacebook': '\uf082',

package/dist/fontawesome.tss

@@ -1,4 +1,4 @@
-// Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com
+// Font Awesome Free 7.2.0 by @fontawesome - https://fontawesome.com
 // License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
 
 // Font Awesome uses the Unicode Private Use Area (PUA) to ensure screen readers do not read off random characters that represent icons
@@ -145,6 +145,7 @@
 '.fa-chart-column': { text: '\ue0e3', title: '\ue0e3' }
 '.fa-chart-gantt': { text: '\ue0e4', title: '\ue0e4' }
 '.fa-clapperboard': { text: '\ue131', title: '\ue131' }
+'.fa-closed-captioning-slash': { text: '\ue135', title: '\ue135' }
 '.fa-clover': { text: '\ue139', title: '\ue139' }
 '.fa-code-compare': { text: '\ue13a', title: '\ue13a' }
 '.fa-code-fork': { text: '\ue13b', title: '\ue13b' }
@@ -465,12 +466,25 @@
 '.fa-pentagon': { text: '\ue790', title: '\ue790' }
 '.fa-non-binary': { text: '\ue807', title: '\ue807' }
 '.fa-spiral': { text: '\ue80a', title: '\ue80a' }
+'.fa-picture-in-picture': { text: '\ue80b', title: '\ue80b' }
 '.fa-mobile-vibrate': { text: '\ue816', title: '\ue816' }
 '.fa-single-quote-left': { text: '\ue81b', title: '\ue81b' }
 '.fa-single-quote-right': { text: '\ue81c', title: '\ue81c' }
 '.fa-bus-side': { text: '\ue81d', title: '\ue81d' }
 '.fa-septagon': { text: '\ue820', title: '\ue820' }
 '.fa-heptagon': { text: '\ue820', title: '\ue820' }
+'.fa-aquarius': { text: '\ue845', title: '\ue845' }
+'.fa-aries': { text: '\ue846', title: '\ue846' }
+'.fa-cancer': { text: '\ue847', title: '\ue847' }
+'.fa-capricorn': { text: '\ue848', title: '\ue848' }
+'.fa-gemini': { text: '\ue849', title: '\ue849' }
+'.fa-leo': { text: '\ue84a', title: '\ue84a' }
+'.fa-libra': { text: '\ue84b', title: '\ue84b' }
+'.fa-pisces': { text: '\ue84c', title: '\ue84c' }
+'.fa-sagittarius': { text: '\ue84d', title: '\ue84d' }
+'.fa-scorpio': { text: '\ue84e', title: '\ue84e' }
+'.fa-taurus': { text: '\ue84f', title: '\ue84f' }
+'.fa-virgo': { text: '\ue850', title: '\ue850' }
 '.fa-martini-glass-empty': { text: '\uf000', title: '\uf000' }
 '.fa-glass-martini': { text: '\uf000', title: '\uf000' }
 '.fa-music': { text: '\uf001', title: '\uf001' }
@@ -1796,6 +1810,8 @@
 '.fa-torah': { text: '\uf6a0', title: '\uf6a0' }
 '.fa-torii-gate': { text: '\uf6a1', title: '\uf6a1' }
 '.fa-vihara': { text: '\uf6a7', title: '\uf6a7' }
+'.fa-volume': { text: '\uf6a8', title: '\uf6a8' }
+'.fa-volume-medium': { text: '\uf6a8', title: '\uf6a8' }
 '.fa-volume-xmark': { text: '\uf6a9', title: '\uf6a9' }
 '.fa-volume-mute': { text: '\uf6a9', title: '\uf6a9' }
 '.fa-volume-times': { text: '\uf6a9', title: '\uf6a9' }
@@ -2114,6 +2130,44 @@
 '.fa-square-figma': { text: '\ue7e4', title: '\ue7e4' }
 '.fa-tex': { text: '\ue7ff', title: '\ue7ff' }
 '.fa-duolingo': { text: '\ue812', title: '\ue812' }
+'.fa-supportnow': { text: '\ue833', title: '\ue833' }
+'.fa-tor-browser': { text: '\ue838', title: '\ue838' }
+'.fa-typescript': { text: '\ue840', title: '\ue840' }
+'.fa-square-deskpro': { text: '\ue844', title: '\ue844' }
+'.fa-circle-zulip': { text: '\ue851', title: '\ue851' }
+'.fa-julia': { text: '\ue852', title: '\ue852' }
+'.fa-zulip': { text: '\ue853', title: '\ue853' }
+'.fa-unison': { text: '\ue854', title: '\ue854' }
+'.fa-board-game-geek': { text: '\ue855', title: '\ue855' }
+'.fa-bgg': { text: '\ue855', title: '\ue855' }
+'.fa-ko-fi': { text: '\ue856', title: '\ue856' }
+'.fa-kubernetes': { text: '\ue857', title: '\ue857' }
+'.fa-postgresql': { text: '\ue858', title: '\ue858' }
+'.fa-scaleway': { text: '\ue859', title: '\ue859' }
+'.fa-venmo': { text: '\ue85a', title: '\ue85a' }
+'.fa-venmo-v': { text: '\ue85b', title: '\ue85b' }
+'.fa-unreal-engine': { text: '\ue85c', title: '\ue85c' }
+'.fa-globaleaks': { text: '\ue85d', title: '\ue85d' }
+'.fa-solana': { text: '\ue85e', title: '\ue85e' }
+'.fa-threema': { text: '\ue85f', title: '\ue85f' }
+'.fa-forgejo': { text: '\ue860', title: '\ue860' }
+'.fa-claude': { text: '\ue861', title: '\ue861' }
+'.fa-gitee': { text: '\ue863', title: '\ue863' }
+'.fa-xmpp': { text: '\ue864', title: '\ue864' }
+'.fa-fediverse': { text: '\ue865', title: '\ue865' }
+'.fa-tailwind-css': { text: '\ue866', title: '\ue866' }
+'.fa-arch-linux': { text: '\ue867', title: '\ue867' }
+'.fa-svelte': { text: '\ue868', title: '\ue868' }
+'.fa-hugging-face': { text: '\ue869', title: '\ue869' }
+'.fa-leetcode': { text: '\ue86a', title: '\ue86a' }
+'.fa-openstreetmap': { text: '\ue86b', title: '\ue86b' }
+'.fa-ultralytics': { text: '\ue86d', title: '\ue86d' }
+'.fa-ultralytics-hub': { text: '\ue86e', title: '\ue86e' }
+'.fa-ultralytics-yolo': { text: '\ue86f', title: '\ue86f' }
+'.fa-obsidian': { text: '\ue879', title: '\ue879' }
+'.fa-zoom': { text: '\ue87b', title: '\ue87b' }
+'.fa-vim': { text: '\ue88a', title: '\ue88a' }
+'.fa-symfonycasts': { text: '\ue8ab', title: '\ue8ab' }
 '.fa-square-twitter': { text: '\uf081', title: '\uf081' }
 '.fa-twitter-square': { text: '\uf081', title: '\uf081' }
 '.fa-square-facebook': { text: '\uf082', title: '\uf082' }