purgetss 7.3.1 → 7.4.0

package/README.md

@@ -67,6 +67,106 @@ Here are its main functionalities:
 - **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.
 
+---
+
+## Animation Module (`purgetss.ui.js`)
+
+Install with `purgetss module` (or `purgetss m`). This places `purgetss.ui.js` in your project's `lib` folder.
+
+### Declaring an Animation object
+
+```xml
+<Animation id="myAnimation" module="purgetss.ui" class="opacity-0 duration-300 ease-in" />
+```
+
+You can use any position, size, color, opacity, or transformation class from `utilities.tss`.
+
+### 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.                                  |
+
+### Callback event object
+
+All callbacks (`play`, `open`, `close`, `apply`) receive an enriched event object:
+
+```js
+{
+  type: String,         // event type ('complete' or 'applied')
+  bubbles: Boolean,
+  cancelBubble: Boolean,
+  action: String,       // 'play' or 'apply'
+  state: String,        // 'open' or 'close'
+  id: String,           // Animation object ID
+  targetId: String,     // ID of the animated view
+  index: Number,        // position in array (0-based)
+  total: Number,        // total views in array
+  getTarget: Function   // returns the animated view object
+}
+```
+
+When animating an **array of views**, the callback is called once per view with the corresponding `index` and `total` values.
+
+```js
+$.myAnimation.play([$.card1, $.card2, $.card3], (e) => {
+  console.log(`Animated ${e.index + 1} of ${e.total}`) // "Animated 1 of 3", etc.
+  if (e.index === e.total - 1) {
+    console.log('All done!')
+  }
+})
+```
+
+### Multi-state animations
+
+Use `open`, `close`, and `complete` modifiers inside `animationProperties` to define different states:
+
+```xml
+<Animation id="fadeToggle" module="purgetss.ui" class="duration-300"
+  animationProperties="{
+    open: { opacity: 1 },
+    close: { opacity: 0 }
+  }"
+/>
+```
+
+### Draggable views
+
+```js
+$.myAnimation.draggable($.myView)
+// or with constraints:
+$.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.
+
+### Utility classes for animations
+
+| Class pattern                                       | Description                   |
+| --------------------------------------------------- | ----------------------------- |
+| `duration-{n}`                                      | Animation duration in ms      |
+| `delay-{n}`                                         | Delay before animation starts |
+| `rotate-{n}`                                        | 2D rotation in degrees        |
+| `scale-{n}`                                         | Scale factor                  |
+| `repeat-{n}`                                        | Number of repeats             |
+| `ease-in`, `ease-out`, `ease-linear`, `ease-in-out` | Timing curve                  |
+| `zoom-in-{n}`, `zoom-out-{n}`                       | Zoom animations               |
+| `drag-apply`, `drag-animate`                        | Drag interaction style        |
+| `vertical-constraint`, `horizontal-constraint`      | Constrain drag axis           |
+
+### Utility functions
+
+| Function                               | Description                                                                                              |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `deviceInfo()`                         | Logs detailed platform and display information to the console. Works in both Alloy and Classic projects. |
+| `saveComponent({ source, directory })` | Saves a view snapshot as PNG to the photo gallery.                                                       |
+
+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.
 
 ### Visit the official documentation site at [purgetss.com](https://purgetss.com) to learn more.

package/dist/purgetss.ui.js

@@ -1,4 +1,4 @@
-// PurgeTSS v7.3.0
+// PurgeTSS v7.3.1
 // Created by César Estrada
 // https://purgetss.com
 

package/lib/templates/purgetss.ui.js.cjs

@@ -299,18 +299,18 @@ function Animation(args = {}) {
         params.playing = false
         if (typeof _cb === 'function') {
           const enrichedEvent = {
-            // Solo propiedades seguras del event original
+            // Safe properties from the original event
             type: event.type,
             bubbles: event.bubbles,
             cancelBubble: event.cancelBubble,
-            // Nuestras propiedades añadidas (solo primitivos)
+            // Added properties (primitives only)
             action,                             // 'play'
             state: params.open ? 'open' : 'close',
             id: params.id,
-            targetId: view.id || 'unknown',     // Solo el ID del view, no el objeto
+            targetId: view.id || 'unknown',     // View ID only, not the object
             index,
             total,
-            // Método helper para obtener el view
+            // Helper method to get the view
             getTarget: () => view
           }
           _cb(enrichedEvent)
@@ -340,14 +340,14 @@ function Animation(args = {}) {
           type: 'applied',
           bubbles: false,
           cancelBubble: false,
-          // Nuestras propiedades (solo primitivos)
+          // Added properties (primitives only)
           action,                             // 'apply'
           state: params.open ? 'open' : 'close',
           id: params.id,
-          targetId: view.id || 'unknown',     // Solo el ID del view
+          targetId: view.id || 'unknown',     // View ID only, not the object
           index,
           total,
-          // Método helper para obtener el view
+          // Helper method to get the view
           getTarget: () => view
         }
         _cb(enrichedEvent)

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.3.1",
+  "version": "7.4.0",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"

package/src/shared/helpers/utils.js

@@ -374,6 +374,26 @@ export function fixInvalidValues(invalidValues, currentValue) {
   return invalidValues[currentValue] || currentValue
 }
 
+/**
+ * Recursively serialize a value for TSS output.
+ * Handles primitives, plain objects, and arrays of objects.
+ * @param {*} val - Value to serialize
+ * @returns {string} TSS-compatible string representation
+ */
+function serializeValue(val) {
+  if (Array.isArray(val)) {
+    const items = val.map(item => serializeValue(item))
+    return `[ ${items.join(', ')} ]`
+  }
+  if (typeof val === 'object' && val !== null) {
+    const entries = Object.entries(val)
+      .map(([k, v]) => `${k}: ${serializeValue(v)}`)
+      .join(', ')
+    return `{ ${entries} }`
+  }
+  return parseValue(val)
+}
+
 /**
  * Generate custom rules for Titanium styles
  * @param {Object} _value - Value object containing rules
@@ -399,27 +419,7 @@ export function customRules(_value, _key, changeToDash = false) {
 
             customProperties += ' {_applyProperties_},'
           } else {
-            customProperties += ` ${theModifier}: {`
-
-            let extraCustomProperties = ''
-
-            _.each(theValue, (extraValue, extraModifier) => {
-              if (typeof (extraValue) === 'object' && extraValue !== null) {
-                customProperties += ` ${extraModifier}: {`
-
-                let moreExtraCustomProperties = ''
-
-                _.each(extraValue, (moreExtraValue, moreModifier) => {
-                  moreExtraCustomProperties += ` ${moreModifier}: ${parseValue(moreExtraValue)},`
-                })
-
-                customProperties += `${removeLastCharacter(moreExtraCustomProperties)} },`
-              } else {
-                extraCustomProperties += ` ${extraModifier}: ${parseValue(extraValue)},`
-              }
-            })
-
-            customProperties += `${removeLastCharacter(extraCustomProperties)} },`
+            customProperties += ` ${theModifier}: ${serializeValue(theValue)},`
           }
         } else {
           if (theModifier === 'apply') {