@maccesar/titools 2.8.0 → 2.10.0

package/skills/purgetss/references/grid-layout.md

@@ -2,9 +2,6 @@
 
 The grid system is a small layout tool that lets you build rows and columns with utility classes.
 
-> **WARNING**
-> PurgeTSS grid is not CSS Grid. It is a Titanium-oriented layout helper built around horizontal and vertical layout behavior.
-
 The snippet below shows the simplest layout. From there, you can mix columns and rows as needed.
 
 ```xml
@@ -85,10 +82,25 @@ These are the available utilities to control the grid.
 
 Control horizontal alignment of elements within a row:
 
-| Class | Effect | Use case |
-| --- | --- | --- |
-| `start` | Align to the start of the row | Left-aligned content |
-| `end` | Align to the end of the row | Right-aligned buttons or labels |
-| `center` | Align to the center of the row | Centered content blocks |
+| Class | Effect |
+| --- | --- |
+| `start` | Align to the start of the row |
+| `end` | Align to the end of the row |
+| `center` | Align to the center of the row |
 
 These apply to child views inside a `grid-cols-*` container and control horizontal placement within the grid cell.
+
+## Community-Discovered Patterns
+
+The following notes come from community experience using the PurgeTSS grid system in Titanium projects. They clarify how the grid relates to Titanium's layout engine (not CSS Grid) and offer common use cases for row placement.
+
+> **WARNING**
+> PurgeTSS grid is not CSS Grid. It is a Titanium-oriented layout helper built around horizontal and vertical layout behavior.
+
+### Common Use Cases for Row Placement
+
+| Class | Use case |
+| --- | --- |
+| `start` | Left-aligned content |
+| `end` | Right-aligned buttons or labels |
+| `center` | Centered content blocks |

package/skills/purgetss/references/icon-fonts.md

@@ -166,5 +166,9 @@ exports.icons = icons;
 > **DANGER**
 > Make sure the new prefix remains unique to avoid conflicts with other class prefixes.
 
+## Community-Discovered Patterns
+
+The following note reflects community experience working with icon fonts that depend on multiple glyphs per icon.
+
 > **Font Awesome Duotone**
 > Titanium cannot render Font Awesome duotone icons correctly because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.

package/skills/purgetss/references/installation-setup.md

@@ -12,16 +12,11 @@ Install PurgeTSS globally on your machine using [NPM](https://www.npmjs.com/).
 > Node.js 20+ required.
 > PurgeTSS requires Node 20.0.0 or higher.
 
-## Upgrade Notes
+## XML Validation
 
-- `utilities.tss` is the generated utilities file. Update any scripts or docs that still use the previous output filename.
-- `deviceInfo()` now works in Alloy and Classic Titanium projects.
-- If an upgrade behaves unexpectedly, a clean reinstall is the recommended recovery step:
+PurgeTSS v7.5.3 added XML validation that flags any `--` (double-dash) sequence inside XML comments. Titanium's XML parser treats `--` in comments as invalid, and PurgeTSS now detects those sequences before they break the compile step.
 
-```bash
-npm uninstall -g purgetss
-npm install -g purgetss
-```
+If you see a validation warning from PurgeTSS pointing at a view file, replace the offending comment with an alternative marker (for example, `//` or `==`) and re-run the build.
 
 ## Run PurgeTSS the First Time
 

package/skills/purgetss/references/ios-large-titles.md

@@ -0,0 +1,141 @@
+# iOS Large Titles
+
+Enabling Large Titles on a Window is not a single-property change. When you pair `largeTitleEnabled` with a `ScrollView` inside a `NavigationWindow` or `TabGroup`, **three interdependent iOS Window properties** must work together — otherwise you get either content hidden behind the nav bar or a visible rendering delay when the window opens.
+
+| Property | Value | Why it matters |
+| --- | --- | --- |
+| `autoAdjustScrollViewInsets` | `true` | iOS automatically adjusts the ScrollView content insets so content starts below the nav bar instead of behind it. |
+| `extendEdges` | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends under the nav/tab bars, producing the translucent blur effect Large Titles depend on. |
+| `largeTitleEnabled` | `true` | Shows the large title that collapses to the standard nav bar title as the user scrolls. |
+
+Using only `largeTitleEnabled` causes the nav bar region to render empty for a moment before the title draws. Using `extendEdges` without `autoAdjustScrollViewInsets` pushes content behind the nav bar without compensating the ScrollView insets. All three must be present.
+
+## iOS-only — use the `ios:` modifier
+
+Large Title properties are iOS-only. On Android they either do nothing or raise compile-time errors. Always scope them with the `ios:` platform block in `config.cjs`, not as defaults that leak to Android.
+
+## Global defaults in `config.cjs`
+
+Rather than repeating the three classes on every `Window`, set them once at the Ti Element level so every iOS Window inherits the base behavior:
+
+`./purgetss/config.cjs`
+```js
+module.exports = {
+  theme: {
+    Window: {
+      ios: {
+        apply: 'auto-adjust-scroll-view-insets extend-edges-all large-title-enabled'
+      }
+    }
+  }
+};
+```
+
+Generated style in `./purgetss/styles/utilities.tss`:
+
+```tss
+'Window[platform=ios]': { autoAdjustScrollViewInsets: true, extendEdges: [ Ti.UI.EXTEND_EDGE_ALL ], largeTitleEnabled: true }
+```
+
+Individual windows now only need to override `largeTitleDisplayMode` when they want different collapse behavior (e.g. detail windows).
+
+> **Why an `ios:` block and not an inline `ios:` prefix?** `auto-adjust-scroll-view-insets` and `extend-edges-all` are platform-specific classes — they only exist with `[platform=ios]` suffix in `utilities.tss`. The `ios:` block ensures PurgeTSS resolves the platform-suffixed version. See [apply-directive.md](apply-directive.md) → "Platform-Specific Classes".
+
+## NavigationWindow example
+
+`./app/views/index.xml`
+```xml
+<Alloy>
+  <NavigationWindow id="navWin">
+    <Window title="Home">
+      <ScrollView class="vertical content-w-screen content-h-auto">
+        <!-- Content starts below the nav bar automatically -->
+      </ScrollView>
+    </Window>
+  </NavigationWindow>
+</Alloy>
+```
+
+The Window inherits `auto-adjust-scroll-view-insets`, `extend-edges-all`, and `large-title-enabled` from the `theme.Window.ios.apply` defaults above.
+
+## TabGroup example
+
+On iOS, `TabGroup` wraps each `Tab`'s Window in an **implicit NavigationWindow**. You do not declare the inner `NavigationWindow` yourself — iOS adds it. The three-property pattern applies identically:
+
+`./app/views/index.xml`
+```xml
+<Alloy>
+  <TabGroup>
+    <Tab title="Home">
+      <Window title="Home">
+        <ScrollView class="vertical content-w-screen content-h-auto">
+          <!-- Each tab gets its own implicit NavigationWindow -->
+        </ScrollView>
+      </Window>
+    </Tab>
+  </TabGroup>
+</Alloy>
+```
+
+## Controlling the collapse behavior: `largeTitleDisplayMode`
+
+`largeTitleDisplayMode` controls how the title behaves in the navigation stack:
+
+| Mode | Constant | Behavior |
+| --- | --- | --- |
+| Automatic | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` | Inherits from previous window; collapses on scroll. |
+| Always | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS` | Title stays large regardless of scroll position. |
+| Never | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER` | Always uses the standard (small) title size. |
+
+### Detail windows: use `large-title-display-mode-never`
+
+Detail windows typically should not show a large title — it looks oversized for a secondary screen. PurgeTSS ships a utility class for this:
+
+```xml
+<Window class="large-title-display-mode-never" title="Detail">
+  <!-- Standard nav bar title, regardless of global largeTitleEnabled default -->
+</Window>
+```
+
+This overrides only the display mode, so the window still benefits from the inherited `autoAdjustScrollViewInsets` and `extendEdges` defaults.
+
+## ScrollView pairing: `content-w-screen content-h-auto`
+
+When Large Titles are active, the paired ScrollView needs its content area sized so iOS can shrink/grow the title as the user scrolls. The canonical pattern:
+
+```xml
+<ScrollView class="vertical content-w-screen content-h-auto">
+  <!-- children -->
+</ScrollView>
+```
+
+- `content-w-screen` → `contentWidth: Ti.UI.FILL`
+- `content-h-auto` → `contentHeight: Ti.UI.SIZE`
+
+Sizing the content height to `Ti.UI.SIZE` is what lets iOS determine whether there is enough content to allow the large title to collapse on scroll.
+
+## Quick reference — class to property map
+
+| Class | Property | Value |
+| --- | --- | --- |
+| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | `true` |
+| `extend-edges-all` | `extendEdges` | `[Ti.UI.EXTEND_EDGE_ALL]` |
+| `large-title-enabled` | `largeTitleEnabled` | `true` |
+| `large-title-enabled-false` | `largeTitleEnabled` | `false` |
+| `large-title-display-mode-never` | `largeTitleDisplayMode` | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER` |
+| `content-w-screen` | `contentWidth` | `Ti.UI.FILL` |
+| `content-h-auto` | `contentHeight` | `Ti.UI.SIZE` |
+
+## Community-Discovered Patterns
+
+### TabGroup implicit-NavigationWindow wrapping
+
+A recurring source of confusion: iOS `TabGroup` already wraps each `Tab` in an implicit `NavigationWindow`. Manually nesting a `NavigationWindow` inside a `Tab` can produce a double nav bar or break `openWindow()` push transitions. Keep the markup flat — `Tab > Window` — and rely on the implicit wrapper.
+
+### Detail windows should opt out, not opt in
+
+When `theme.Window.ios.apply` sets `large-title-enabled` as a default, every pushed window inherits it. Apply `large-title-display-mode-never` on detail windows pushed via `openWindow()` so the parent keeps the collapse animation while detail screens render with a standard title. This mirrors Apple's own first-party app conventions (Settings, Mail).
+
+### Cross-reference
+
+The three-property pairing (`autoAdjustScrollViewInsets` + `extendEdges` + `largeTitleEnabled`) is also documented as a reusable global-defaults recipe in [apply-directive.md](apply-directive.md) under *Community-Discovered Patterns → Global Window defaults for Large Titles + ScrollView (iOS)*. Prefer that recipe over per-window repetition whenever the whole app uses Large Titles.

package/skills/purgetss/references/migration-guide.md

@@ -1,52 +1,138 @@
 # Migration Guide
 
-This guide is based on the PurgeTSS changelog sections in the official `README.md`. It covers the documented upgrade changes for recent versions.
+This guide mirrors the official PurgeTSS changelog (see the project `README.md` / `docs/index.md`). It walks through the upgrade-relevant changes from v7.2.6 through v7.6.0, flags breaking changes, and links each section to the reference files that cover the new surface area in depth.
 
-## Upgrade to v7.4.0
+Changelog source of truth: [https://github.com/macCesar/purgeTSS](https://github.com/macCesar/purgeTSS).
+
+---
+
+## Upgrade to v7.6.0
+
+v7.6.0 introduces three new CLI commands for app-asset generation plus two new `config.cjs` sections. None of the additions are breaking — existing projects continue to work untouched, and the new config sections are auto-injected on first run.
+
+### New CLI commands
+
+- **`brand` command** — generates the complete Titanium branding set (launcher icons, adaptive icons, iOS 18+ Dark and Tinted variants, marketplace artwork, optional notification and splash images) from logos auto-discovered in `./purgetss/brand/`. Works on both Alloy and Classic projects.
+- **`images` command** — generates multi-density UI images (Android `res-*` densities plus iPhone `@1x` / `@2x` / `@3x` scales) from sources dropped into `./purgetss/images/`. Subdirectories are preserved, and short-path scope targeting lets you re-process individual files.
+- **`semantic` command** — generates Titanium semantic colors (Light/Dark mode) into `app/assets/semantic.colors.json`. Two dispatch modes:
+  - **Tonal palette** (default): one base hex → 11 shades with mirror inversion and auto config mapping.
+  - **Single purpose-based color** (`--single`): explicit per-mode hex plus optional alpha; writes both the JSON entry AND a class mapping in `config.cjs` in one shot. Class name is auto-derived by stripping the `Color` suffix (e.g. `surfaceColor` → class `surface`). Smart in-place updates when a single name matches an existing palette shade.
+
+### New `config.cjs` sections
+
+- **`brand:` section** — configures padding percentages, background colors, and platform targets for the `brand` command.
+- **`images:` section** — configures scale factors and output density mapping for the `images` command.
+
+Percentages can be written as self-documenting strings (e.g. `'15%'`) or plain numbers. Both are accepted. These sections are auto-injected into older `config.cjs` files on the first run of v7.6.0.
+
+### What to review
+
+- If you previously generated app icons or multi-density images manually (or with third-party tooling), plan a migration session to replace that workflow with `brand` and `images`.
+- If you maintain a `semantic.colors.json` by hand, back it up before running `semantic` — the command does smart in-place updates, but a backup is cheap insurance.
+
+### Cross-references
+
+- [`app-branding.md`](./app-branding.md) — full walkthrough of the `brand` command and the `./purgetss/brand/` convention.
+- [`multi-density-images.md`](./multi-density-images.md) — `images` command, density mapping, and subdirectory behavior.
+- [`semantic-colors.md`](./semantic-colors.md) — palette vs single-color modes, alpha handling, and config mapping.
+- [`cli-commands.md#brand-command`](./cli-commands.md#brand-command)
+- [`cli-commands.md#images-command`](./cli-commands.md#images-command)
+- [`cli-commands.md#semantic-command`](./cli-commands.md#semantic-command)
+
+---
+
+## Upgrade to v7.5.3
+
+v7.5.3 is a feature-and-polish release. No breaking changes.
 
-PurgeTSS v7.4.0 includes a bug fix and documentation improvements.
+### Added
+
+- **Appearance module** — a new `Appearance` export for Light/Dark/System mode switching with persistence. Exposed methods: `init()`, `set(mode)`, `get()`, `toggle()`.
+- **Default font family classes** — `font-sans`, `font-serif`, and `font-mono` are generated automatically with platform-appropriate values (system sans, serif, and monospace stacks for iOS and Android).
+- **XML validation** — the pre-validation pass now detects illegal `--` sequences inside XML comments, which previously produced cryptic downstream errors.
+
+### What to review
+
+- If you want runtime theme switching, wire up `Appearance.init()` at app boot and use `Appearance.toggle()` or `Appearance.set('dark')` where the UI exposes the control.
+- If you had custom `font-sans` / `font-serif` / `font-mono` classes in `config.cjs`, check for collisions with the new auto-generated ones.
+
+### Cross-references
+
+- [`appearance-module.md`](./appearance-module.md) — full `Appearance` API, persistence behavior, and integration patterns.
+
+---
+
+## Upgrade to v7.5.0
+
+v7.5.0 adds `extend` support for component defaults and improves how `apply` directives are normalized. It also bumps Font Awesome. No breaking changes.
+
+### Added
+
+- **`extend` support for Window, View, and ImageView** — customize component defaults from `theme.extend` in `config.cjs`. Previously only a subset of components supported `extend`.
+- **Shorthand `apply`** — `{ apply: '...' }` is automatically normalized, so the `default:` wrapper is now optional.
+- **Property deduplication** — values pulled in via `apply` now win over static defaults instead of producing duplicate property entries in the generated TSS.
+- **Automatic platform resolution** — classes referenced inside `ios:` / `android:` blocks automatically find their platform-specific version instead of requiring explicit disambiguation.
+- **Font Awesome 7.2.0** bundled.
 
 ### Fixed
 
-- `backgroundGradient.colors` serialization now correctly handles arrays of objects in custom rules.
+- `extend.Window` was silently ignored in earlier versions — now honored.
+- Duplicate `font` properties in generated output.
+- Array-type properties generating output without `[ ]` notation.
 
-Before the fix, a config such as:
+### What to review
 
-```javascript
-colors: [
-  { color: '#132C50', offset: 0 },
-  { color: '#0A1529', offset: 1 }
-]
-```
+- If you previously worked around the `extend.Window` bug with manual TSS overrides, you can remove those now.
+- If you previously wrote `{ default: { apply: '...' } }`, the shorter `{ apply: '...' }` form is equivalent.
+- Diff your generated `utilities.tss` against the pre-upgrade version: property deduplication and the array-notation fix may produce cleaner output, which is expected.
+
+### Cross-references
 
-could produce broken output in `utilities.tss`.
+- [`customization-deep-dive.md`](./customization-deep-dive.md) — `theme.extend` patterns for Window, View, and ImageView defaults.
+- [`apply-directive.md`](./apply-directive.md) — shorthand `apply` syntax and deduplication behavior.
 
-Now it serializes correctly.
+---
 
-### What to Review
+## Upgrade to v7.4.0
 
-- Re-test any custom classes that define `backgroundGradient.colors` with `{ color, offset }` objects.
-- Rebuild and inspect `utilities.tss` if you previously worked around this bug manually.
+v7.4.0 is the **Animation module expansion**. Nine new methods bring the Animation module to 15 total.
+
+### Added
+
+- **New methods**: `transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions`.
+- **New utility classes**: `snap-back`, `snap-center`, `snap-magnet`, `keep-z-index`.
+- **Delta-based drag for transformed views** — drag math now works correctly when the view already has a 2D transform applied.
+- **Position normalization** and **property inheritance** from the Animation object — reduces boilerplate when sequencing multiple animations on the same view.
+
+### What to review
+
+- If you previously hand-rolled sequential animations with `Ti.UI.createAnimation` callbacks, consider porting them to `sequence` for readability.
+- If you implemented ad-hoc drag/snap logic, compare it with `snapTo` + `detectCollisions` — the new pipeline handles z-index, collision detection, and snap-back without manual bookkeeping.
+
+### Cross-references
+
+- [`animation-system.md`](./animation-system.md) — full Animation module reference including all 15 methods and the snap / drag / collision utilities.
+
+---
 
 ## Upgrade to v7.3.x
 
-PurgeTSS v7.3 introduced a file rename and improved error handling.
+v7.3.0 introduced a **breaking file rename** plus XML validation and Classic Titanium compatibility improvements.
 
 ### Breaking Changes
 
-- The generated utilities output is now `utilities.tss`.
+- **`tailwind.tss` → `utilities.tss`** — the generated utilities output was renamed to reflect that PurgeTSS is a standalone toolkit, not a Tailwind port.
   - Generated file: `purgetss/styles/utilities.tss`
   - Distribution file: `dist/utilities.tss`
 
 ### Major Improvements
 
-- XML syntax validation now catches malformed Alloy XML before processing.
-- `deviceInfo()` now works in both Alloy and Classic Titanium projects.
-- The dependency on `Alloy.isTablet` and `Alloy.isHandheld` was removed.
+- **XML syntax validation** — pre-validation now catches malformed Alloy XML before processing, with line numbers and fix suggestions.
+- **Classic Titanium compatibility** — `deviceInfo()` now works in both Alloy and Classic projects. The dependency on `Alloy.isTablet` and `Alloy.isHandheld` was removed.
 
 ### Required Actions
 
-1. Update any scripts, docs, or project references that still point to the previous output filename.
+1. Update any scripts, docs, or project references that still point to the previous `tailwind.tss` filename.
 2. Ensure your environment is running Node.js 20 or higher.
 3. If you use Font Awesome 7, verify the project after upgrade so PurgeTSS can handle the new `--fa:` properties.
 
@@ -55,7 +141,7 @@ PurgeTSS v7.3 introduced a file rename and improved error handling.
 purgetss/styles/utilities.tss
 ```
 
-### Recommended Upgrade Command
+### Recommended upgrade command
 
 ```bash
 npm install -g purgetss@latest
@@ -68,9 +154,60 @@ npm uninstall -g purgetss
 npm install -g purgetss
 ```
 
+---
+
+## Upgrade to v7.2.7
+
+v7.2.7 is a security and maintenance release.
+
+### Added / Updated
+
+- **Security fixes** — command injection in `glob`, prototype pollution in `js-yaml`.
+- **Dependency cleanup** — reduces installation size by ~45MB, removed unused packages.
+- **Titanium SDK 13.1.0.GA** — new utility classes for `navBarColor`, `forceBottomPosition`, `multipleWindows`.
+
+### What to review
+
+- If you pinned PurgeTSS to a pre-7.2.7 version for reproducibility, plan the bump: the security advisories affect any environment that resolves transitive `glob` or `js-yaml`.
+
+---
+
+## Upgrade to v7.2.6
+
+v7.2.6 is a minor refresh release.
+
+### Updated
+
+- Font Awesome bumped to version 7.1.0.
+- Simplified flag property names in `utilities.tss`.
+
+---
+
+## Community-Discovered Patterns
+
+Issues reported and patched outside the official changelog. These are documented here so users upgrading through multiple versions know to re-test the affected surface area. **Needs confirmation** — the version in which each fix shipped has not been verified against the official changelog at time of writing.
+
+### `backgroundGradient.colors` serialization with arrays of objects
+
+Certain versions of PurgeTSS could produce broken output in `utilities.tss` when a custom rule defined `backgroundGradient.colors` as an array of `{ color, offset }` objects, for example:
+
+```javascript
+const colors = [
+  { color: '#132C50', offset: 0 },
+  { color: '#0A1529', offset: 1 },
+];
+```
+
+If you previously worked around this by inlining the gradient directly in TSS, re-test after upgrading: current versions serialize the array correctly. The exact version in which this was patched is not called out in the official changelog — treat this as a user-observed fix until confirmed.
+
+---
+
 ## Quick Checklist
 
-- Replace every legacy utilities filename reference with `utilities.tss`.
-- Verify Node.js 20+ before upgrading.
+- Replace every legacy `tailwind.tss` reference with `utilities.tss`.
+- Verify Node.js 20+ before upgrading past v7.3.0.
 - Rebuild after updating `config.cjs` or custom gradient rules.
 - Re-test any Classic Titanium code that depends on `deviceInfo()`.
+- After v7.5.0: diff generated `utilities.tss` to confirm property deduplication produces the expected output.
+- After v7.5.3: consider wiring `Appearance.init()` at app boot if you want runtime Light/Dark switching.
+- After v7.6.0: run `brand`, `images`, and `semantic` once in a scratch project before pointing them at production assets, so you can preview the output layout.