@maccesar/titools 2.9.0 → 2.10.1

package/skills/purgetss/references/semantic-colors.md

@@ -302,6 +302,48 @@ Once the JSON and the `config.cjs` mapping are in place, you use the semantic cl
 
 When the appearance changes — whether from `Appearance.set(...)` or a system-level toggle — Titanium resolves each semantic color name to its `light` or `dark` value automatically. No event listeners, no manual repaint.
 
+### Opacity modifier auto-derivation
+
+As of PurgeTSS v7.9.0, you can apply the `/N` opacity modifier to **any class that resolves to a semantic name** in `semantic.colors.json`, and PurgeTSS will derive a new semantic key with that alpha pre-applied for both `light` and `dark` modes. This works for `bg-*`, `text-*`, `border-*`, and any other color-accepting utility whose class is mapped through `theme.extend.colors` in `config.cjs`.
+
+```xml
+<View class="bg-surface/65" />
+<Label class="text-on-surface/80" text="Subtle" />
+<View class="border border-accent/40" />
+```
+
+On the next `purgetss build` (or plain `purgetss`) run, the toolchain executes a three-step flow:
+
+1. **Detects the mapping** — PurgeTSS sees that, for example, `bg-surface` is mapped to the semantic name `surfaceColor` via `config.cjs`.
+2. **Derives a new key** — it adds `surfaceColor_65` (naming convention: `<originalKey>_<alphaPercent>`, underscore + integer percent) to `semantic.colors.json`, copying the original hex values for both modes and tagging each with `alpha: "65"`:
+
+   ```json
+   "surfaceColor_65": {
+     "light": { "color": "#F9FAFB", "alpha": "65" },
+     "dark":  { "color": "#0f172a", "alpha": "65" }
+   }
+   ```
+
+3. **Emits the rule against the derived key** — for example, `'.bg-surface/65': { backgroundColor: 'surfaceColor_65' }`. Light/Dark switching keeps working because Titanium handles the lookup like any other semantic color. The same flow runs for opacity inside an `apply:` string in `config.cjs`.
+
+#### Idempotency and the `Conflict` error
+
+Re-runs are idempotent: existing derived keys are reused, never duplicated. If you manually edit a derived key with values that disagree with what PurgeTSS would generate (different base color, different alpha, different shape), the next build halts with a `Conflict` error instead of silently overwriting your edits — you have to either revert the manual change or remove the derived key so it can be regenerated cleanly.
+
+> **DANGER**
+>
+> **Native rebuild required for new alpha entries**
+>
+> `semantic.colors.json` is read at **native build time**, not at runtime. The first time a brand-new opacity variant is auto-derived (a class like `bg-surface/65` you've never used before), the running app **will not see it** until the next full Titanium build. Liveview hot-reload alone does **not** refresh `semantic.colors.json` for the running app — only the native binary does.
+>
+> In practice: after introducing a new opacity class, run `purgetss build` once, then start a fresh native build (`appc run` / `ti build`) before resuming your usual Liveview cycle. Subsequent runs of the *same* `/N` value reuse the existing derived key and need no extra rebuild.
+
+#### Constraints
+
+- **Alpha range**: integer `0–100`, matching the standard opacity modifier syntax. Values outside this range are rejected.
+- **Base key must exist**: the semantic name behind the class (`surfaceColor` in the example) must already exist in `semantic.colors.json`. If it doesn't, PurgeTSS emits a warning for direct XML usage or throws an Error for `apply:` directives, with three concrete suggestions in the message.
+- **Naming is fixed**: the derived key is always `<originalKey>_<alphaPercent>` — underscore + integer percent. This mirrors the `/65` you typed and stays quote-free in `config.cjs` if you ever need to reference it manually.
+
 ## Using semantic colors in controllers
 
 Semantic colors also work from JavaScript. Three patterns cover the cases you'll hit.
@@ -368,10 +410,11 @@ A minimal semantic palette that covers most app surfaces:
 | Cards / elevated   | `surfaceHighColor`   | `#FFFFFF` | `#1e293b` | `bg-surface-high`          |
 | Primary text       | `textColor`          | `#111827` | `#f1f5f9` | `text-on-surface`          |
 | Secondary text     | `textSecondaryColor` | `#6B7280` | `#94a3b8` | `text-on-surface-variant`  |
+| Muted text         | `textMutedColor`     | `#9CA3AF` | `#64748b` | `text-muted`               |
 | Borders / dividers | `borderColor`        | `#E5E7EB` | `#334155` | `bg-border`                |
 | Accent             | `accentColor`        | `#3B82F6` | `#60a5fa` | `text-accent`, `bg-accent` |
 
-Start with these 5-6 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
+Start with these 6-7 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
 
 ## Related
 

package/skills/purgetss/references/tikit-components.md

@@ -316,9 +316,7 @@ Colors: `black`, `dark`, `light`, and `white` themes that affect background and
 
 Use this for code examples. Set `copy="true"` to add a copy button.
 
-> **Community-Discovered Pattern — Pro tip**
->
-> For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config.
+**Pro tip — recommended monospace fonts:** For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config. (Source: official tikit docs, `tikit.md` line ~390.)
 
 **Localization:** The copy button uses `L('copy', 'Copy')` for its title and `L('code_copied', 'Code copied!')` for the confirmation message. Add these keys to your `strings.xml` files for translation.
 

package/skills/purgetss/references/values-and-units.md

@@ -0,0 +1,120 @@
+# Values and Units
+
+PurgeTSS writes plain numeric values into your TSS files. **Titanium decides how to interpret them at runtime**, based on `ti.ui.defaultunit` in `tiapp.xml`.
+
+This is a foundational concept worth knowing before you start tweaking spacing scales, custom colors, or arbitrary values — it's the difference between "8 pixels" and "8 dp" being the same number on disk but very different on a high-DPI device.
+
+## The short version
+
+Numeric values produced by PurgeTSS utility classes are **unitless**. When PurgeTSS compiles `rounded-lg` to:
+
+```tss
+'.rounded-lg': { borderRadius: 8 }
+```
+
+the `8` is **not a pixel value**. Titanium reads it at runtime using the unit declared in `tiapp.xml`:
+
+```xml
+<ti:app>
+  <property name="ti.ui.defaultunit" type="string">dp</property>
+</ti:app>
+```
+
+The Alloy project template has used `dp` by default for years, so most PurgeTSS projects are working with **density-independent pixels**, not raw pixels. In practice, `borderRadius: 8` usually means `8dp`, not `8px`.
+
+## Why this matters
+
+Saying `rounded-lg` gives you "8 pixels" is only correct if your `tiapp.xml` explicitly sets `ti.ui.defaultunit` to `px`. Most projects do not.
+
+A more accurate way to describe it is:
+
+> `rounded-lg` applies `borderRadius: 8` — which Titanium interprets as **8 units of `ti.ui.defaultunit`**, defaulting to `dp` on standard Alloy projects.
+
+This applies to every utility class that sets a dimension:
+
+| Category   | Utility classes                                                                              |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| Spacing    | `m-*`, `p-*`, `mt-*`, `mb-*`, `mx-*`, `my-*`, `top-*`, `left-*`, `right-*`, `bottom-*`       |
+| Sizes      | `w-*`, `h-*`, `size-*`, `wh-*`                                                               |
+| Corners    | `rounded-*`, `border-radius-*`                                                               |
+| Borders    | `border-*` (width)                                                                           |
+| Typography | `text-*` (font size), `letter-spacing-*`, `line-spacing-*`                                   |
+| Shadows    | `drop-shadow-*`, `shadow-radius-*`                                                           |
+| Elevation  | `elevation-*`, `max-elevation-*`                                                             |
+| Transforms | `translate-*`, `move-by-*`                                                                   |
+| Offsets    | `x-offset-*`, `y-offset-*`                                                                   |
+
+## Valid values for `ti.ui.defaultunit`
+
+Titanium recognizes these unit identifiers:
+
+| Value    | Meaning                    | Notes                                                                       |
+| -------- | -------------------------- | --------------------------------------------------------------------------- |
+| `dp`     | Density-independent pixels | Alloy template default. Good default for cross-density consistency.         |
+| `dip`    | Alias for `dp`             | Same as `dp`.                                                               |
+| `px`     | Raw pixels                 | Usually a poor fit for UI sizing on high-DPI devices.                       |
+| `mm`     | Millimeters                | Physical measurement.                                                       |
+| `cm`     | Centimeters                | Physical measurement.                                                       |
+| `in`     | Inches                     | Physical measurement.                                                       |
+| `pt`     | Points (1/72 inch)         | Physical measurement.                                                       |
+| `system` | Platform default           | iOS uses points; Android uses pixels. This is inconsistent across platforms. |
+
+## Forcing pixels explicitly
+
+Some PurgeTSS classes use explicit pixel values written as **strings**:
+
+```tss
+'.border-radius-px': { borderRadius: '1px' }
+'.w-px':             { width: '1px' }
+'.h-px':             { height: '1px' }
+```
+
+If a value includes its own suffix, such as `'1px'`, `'2pt'`, or `'4mm'`, Titanium uses that unit directly and **ignores `ti.ui.defaultunit`**.
+
+Use these when you actually need a 1px line or another exact unit (typical case: hairline dividers between rows).
+
+## Percentages are unit-independent
+
+Fractional utility classes produce percentage strings. Titanium resolves those against the **parent size**, not against `ti.ui.defaultunit`:
+
+```tss
+'.w-1/2':  { width: '50%' }
+'.h-full': { height: '100%' }
+```
+
+These behave the same no matter which default unit your app uses.
+
+## Titanium constants are unit-independent
+
+Utility classes that resolve to Titanium layout constants also ignore units:
+
+```tss
+'.w-auto':   { width: Ti.UI.SIZE }
+'.h-screen': { height: Ti.UI.FILL }
+```
+
+`Ti.UI.SIZE` and `Ti.UI.FILL` are layout directives, not numeric dimensions.
+
+## Checking your project's setting
+
+Open `tiapp.xml` and look for:
+
+```xml
+<property name="ti.ui.defaultunit" type="string">dp</property>
+```
+
+If that property is missing, Titanium falls back to `system`. That means iOS and Android can interpret the same number differently, so it is better to set `dp` explicitly.
+
+## Summary
+
+- PurgeTSS writes **unitless numeric values** into `app.tss`.
+- Titanium resolves those values using `ti.ui.defaultunit` in `tiapp.xml`.
+- In most Alloy projects, that unit is `dp`, **not raw pixels**.
+- Values ending in `-px` (written as quoted strings) force raw pixels regardless of the project setting.
+- Percentage-based and `auto`/`screen` utilities are unit-independent.
+
+## Related
+
+- [Arbitrary Values](./arbitrary-values.md) — parentheses notation `(20px)`, `(2rem)`, `(#ff0000)` for one-off values.
+- [Customization Deep Dive](./customization-deep-dive.md) — defining your own spacing scale via `theme.spacing`.
+- [Class Index](./class-index.md) — the full set of generated classes and their numeric vs. percentage vs. constant outputs.