purgetss 7.3.0 → 7.4.0

package/README.md

@@ -56,62 +56,116 @@ npm install -g purgetss@latest
 
 ---
 
-## What's New in v7.2.x
+Here are its main functionalities:
 
-FontAwesome 7 support and major internal cleanup. PurgeTSS v7.2 adds full support for FontAwesome 7, including the new CSS custom properties format. It also reduces installation size and reorganizes the codebase for better performance and maintainability.
+- **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.
 
-### Breaking changes
+---
 
-- Node.js 20+ required (due to the `inquirer` v13 upgrade)
-- Removed deprecated commands:
-  - `copy-fonts` (use `icon-library` instead)
-  - `build-legacy` (legacy Tailwind build removed)
-- Complete legacy mode removal:
-  - All legacy-related code and conditional checks eliminated
-  - Legacy mode no longer supported anywhere in the codebase
+## Animation Module (`purgetss.ui.js`)
 
-### Major improvements
+Install with `purgetss module` (or `purgetss m`). This places `purgetss.ui.js` in your project's `lib` folder.
 
-- FontAwesome 7 support: Works with the new `--fa:` custom properties while staying compatible with version 6.
-- Reduced installation size: About 45MB smaller by moving non-essential assets to dev dependencies.
-- Improved Unicode extraction: Better handling of short hex codes, ASCII symbols, and direct character mappings.
-- Optimized internal structure: Codebase split into focused modules for readability and speed.
-- Enhanced CLI experience: Commands grouped by purpose, with better error handling and smarter suggestions.
+### Declaring an Animation object
 
-### Command improvements
+```xml
+<Animation id="myAnimation" module="purgetss.ui" class="opacity-0 duration-300 ease-in" />
+```
 
-- `build-fonts` simplified:
-  - Automatically detects and handles both FontAwesome 6 and 7 formats.
-  - The `-f` flag now controls both font class names and icon prefixes using filenames.
-- `tailwind init`: Removed redundant flags for a cleaner initialization process.
-- `shades` command: Better precision when generating custom color shades.
-- CLI categories: Commands grouped by purpose: Setup, Development, Assets, Utilities, and Maintenance.
+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
+}
+```
 
-### Migration guide
+When animating an **array of views**, the callback is called once per view with the corresponding `index` and `total` values.
 
-For most users, upgrading is straightforward:
-```bash
-npm install -g purgetss@latest
+```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!')
+  }
+})
 ```
 
-Key changes to note:
-- Node.js 20 or higher is now required.
-- FontAwesome 7: If you use FA7, PurgeTSS will automatically handle the new `--fa:` properties.
-- VS Code extension: We recommend `KevinYouu.tailwind-raw-reorder-tw4` for better compatibility with modern Tailwind versions and XML reordering.
-- Clean reinstall: If you run into issues, try `npm uninstall -g purgetss && npm install -g purgetss`.
+### Multi-state animations
 
----
+Use `open`, `close`, and `complete` modifiers inside `animationProperties` to define different states:
 
-Here are its main functionalities:
+```xml
+<Animation id="fadeToggle" module="purgetss.ui" class="duration-300"
+  animationProperties="{
+    open: { opacity: 1 },
+    close: { opacity: 0 }
+  }"
+/>
+```
 
-- **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.
+### 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.
 

package/dist/fontawesome.tss

@@ -7,16 +7,16 @@
 '.fa':{ font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fas': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.far': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fab': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fab': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fa-solid': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fa-regular': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fa-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fa-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fontawesome': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fontawesome-solid': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fontawesome-regular': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fontawesome-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fontawesome-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 // Font Sizes
 '.fa-lg': { font: { fontSize: 21 } }

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/fontawesome/beta-reset.tss

@@ -4,20 +4,20 @@
 '.fas': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fal': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.far': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fab': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fab': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fa-thin': { font: { fontFamily: 'FontAwesome6Pro-Thin' } }
 '.fa-solid': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fa-light': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.fa-regular': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fa-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fa-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fontawesome': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fontawesome-thin': { font: { fontFamily: 'FontAwesome6Pro-Thin' } }
 '.fontawesome-solid': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fontawesome-light': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.fontawesome-regular': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fontawesome-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fontawesome-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 // Font Sizes
 '.fa-1x': { font: { fontSize: 16 } }

package/lib/templates/fontawesome/free-reset.tss

@@ -2,16 +2,16 @@
 '.fa':{ font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fas': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.far': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fab': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fab': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fa-solid': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fa-regular': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fa-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fa-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fontawesome': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fontawesome-solid': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
 '.fontawesome-regular': { font: { fontFamily: 'FontAwesome7Free-Regular' } }
-'.fontawesome-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fontawesome-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 // Font Sizes
 '.fa-lg': { font: { fontSize: 21 } }

package/lib/templates/fontawesome/pro-reset.tss

@@ -4,20 +4,20 @@
 '.fas': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fal': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.far': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fab': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fab': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fa-thin': { font: { fontFamily: 'FontAwesome6Pro-Thin' } }
 '.fa-solid': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fa-light': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.fa-regular': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fa-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fa-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 '.fontawesome': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fontawesome-thin': { font: { fontFamily: 'FontAwesome6Pro-Thin' } }
 '.fontawesome-solid': { font: { fontFamily: 'FontAwesome6Pro-Solid' } }
 '.fontawesome-light': { font: { fontFamily: 'FontAwesome6Pro-Light' } }
 '.fontawesome-regular': { font: { fontFamily: 'FontAwesome6Pro-Regular' } }
-'.fontawesome-brands': { font: { fontFamily: 'FontAwesome6Brands-Regular' } }
+'.fontawesome-brands': { font: { fontFamily: 'FontAwesome7Brands-Regular' } }
 
 // Font Sizes
 '.fa-lg': { font: { fontSize: 21 } }

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.0",
+  "version": "7.4.0",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"

package/src/cli/commands/dependencies.js

@@ -59,7 +59,7 @@ export function dependencies(options) {
 
   // Install Tailwind CSS
   logger.info(`Installing ${chalk.green('Tailwind CSS')}`)
-  execSync(`cd "${cwd}" && npm i -D tailwindcss && npx tailwindcss init`)
+  execSync(`cd "${cwd}" && npm i -D tailwindcss@3 && npx tailwindcss init`)
 
   logger.info('The dependencies and config files have been installed successfully!')
 

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') {