@maccesar/titools 2.8.0 → 2.9.0

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.