@maccesar/titools 3.2.0 → 4.0.0

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

@@ -0,0 +1,292 @@
+# Custom Fonts
+
+Use the `purgetss/fonts/` folder and the `build-fonts` command to register any font in your Titanium app: brand typefaces, custom icon fonts, or community icon libraries that PurgeTSS no longer bundles.
+
+For the 4 official icon families that ship with PurgeTSS (Font Awesome 7, Material Icons, Material Symbols, Framework7), see [Icon Fonts](./icon-fonts.md) — they use the `icon-library` command and do **not** require `build-fonts`.
+
+## The `fonts` folder
+
+Place `.ttf` or `.otf` files in `./purgetss/fonts/`. For icon fonts, also include the `.css` file that ships with the library. PurgeTSS reads it to extract the Unicode characters for each icon class.
+
+This example uses [Bevan and Dancing Script](https://fonts.google.com/share?selection.family=Bevan:ital@0;1%7CDancing%20Script:wght@400;500;600;700) from Google Fonts:
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   ├─ Bevan-Italic.ttf
+   ├─ Bevan-Regular.ttf
+   ├─ DancingScript-Bold.ttf
+   ├─ DancingScript-Medium.ttf
+   ├─ DancingScript-Regular.ttf
+   └─ DancingScript-SemiBold.ttf
+```
+
+### Organizing the fonts folder
+
+If you prefer to keep things tidy, group each family in a subfolder. The output is the same.
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ bevan
+      ├─ Bevan-Italic.ttf
+      └─ Bevan-Regular.ttf
+   └─ dancing-script
+      ├─ DancingScript-Bold.ttf
+      ├─ DancingScript-Medium.ttf
+      ├─ DancingScript-Regular.ttf
+      └─ DancingScript-SemiBold.ttf
+```
+
+## The `build-fonts` command
+
+```bash
+$ purgetss build-fonts [-m] [-f]
+
+# alias:
+$ purgetss bf [-m] [-f]
+```
+
+What it does:
+
+1. Creates `./purgetss/styles/fonts.tss` with one `fontFamily` class per file.
+2. Copies the font files into `./app/assets/fonts/`, renamed to their PostScript names so they work on both iOS and Android.
+
+> ℹ️ **INFO — How this differs from the official icon fonts**
+> Unlike the [official icon fonts](./icon-fonts.md), which PurgeTSS resolves automatically from its own bundled files and need no `.tss` in your project, custom fonts **do** generate `./purgetss/styles/fonts.tss`. That file is then folded into the generated `app/styles/app.tss` when you run `purgetss` (or compile your app) — that is where the final classes used by Alloy live.
+
+After running `purgetss build-fonts` with the Bevan and Dancing Script example above:
+
+`./purgetss/styles/fonts.tss`
+```css
+// Fonts TSS file generated with PurgeTSS
+// https://purgetss.com/docs/customization/custom-fonts
+
+'.bevan-italic': { font: { fontFamily: 'Bevan-Italic' } }
+'.bevan-regular': { font: { fontFamily: 'Bevan-Regular' } }
+
+'.dancingscript-bold': { font: { fontFamily: 'DancingScript-Bold' } }
+'.dancingscript-medium': { font: { fontFamily: 'DancingScript-Medium' } }
+'.dancingscript-regular': { font: { fontFamily: 'DancingScript-Regular' } }
+'.dancingscript-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
+```
+
+You can now use these classes on any Titanium component with a `font` property: Labels, Buttons, TextFields, TextAreas, ListItems, TableViewRows, and ActivityIndicators.
+
+### Renaming the class
+
+To use a shorter or different class name, rename the font file. For example:
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ dancing-script
+      ├─ Script-Bold.ttf
+      ├─ Script-Medium.ttf
+      ├─ Script-Regular.ttf
+      └─ Script-SemiBold.ttf
+```
+
+Running `build-fonts` produces:
+
+`./purgetss/styles/fonts.tss`
+```css
+'.script-bold': { font: { fontFamily: 'DancingScript-Bold' } }
+'.script-medium': { font: { fontFamily: 'DancingScript-Medium' } }
+'.script-regular': { font: { fontFamily: 'DancingScript-Regular' } }
+'.script-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
+```
+
+The class name changes, but the actual `fontFamily` value (the PostScript name) stays the same.
+
+## Adding icon fonts
+
+Any icon font that ships a `.ttf` (or `.otf`) plus a `.css` file with Unicode characters works the same way.
+
+This example uses [map-icons](http://map-icons.com) and [microns](https://www.s-ings.com/projects/microns-icon-font/):
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ bevan
+   └─ dancing-script
+   └─ map-icons
+      ├─ map-icons.css
+      └─ map-icons.ttf
+   └─ microns
+      ├─ microns.css
+      └─ microns.ttf
+```
+
+After `purgetss build-fonts`, the generated `fonts.tss` includes the family classes and one class per icon:
+
+`./purgetss/styles/fonts.tss`
+```css
+// Fonts TSS file generated with PurgeTSS
+// https://purgetss.com/docs/customization/custom-fonts
+
+'.map-icons': { font: { fontFamily: 'map-icons' } }
+'.microns': { font: { fontFamily: 'microns' } }
+
+/* Unicode Characters */
+/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+
+/* map-icons/map-icons.css */
+'.map-icon-abseiling': { text: '\ue800', title: '\ue800' }
+'.map-icon-accounting': { text: '\ue801', title: '\ue801' }
+'.map-icon-airport': { text: '\ue802', title: '\ue802' }
+'.map-icon-amusement-park': { text: '\ue803', title: '\ue803' }
+'.map-icon-aquarium': { text: '\ue804', title: '\ue804' }
+/* ... */
+
+/* microns/microns.css */
+'.mu-arrow-left': { text: '\ue700', title: '\ue700' }
+'.mu-arrow-right': { text: '\ue701', title: '\ue701' }
+'.mu-arrow-up': { text: '\ue702', title: '\ue702' }
+'.mu-arrow-down': { text: '\ue703', title: '\ue703' }
+'.mu-left': { text: '\ue704', title: '\ue704' }
+/* ... */
+```
+
+## Options
+
+Two optional flags adjust what `build-fonts` generates:
+
+- `-m, --module`: generates a CommonJS module in `./app/lib/purgetss.fonts.js` that exposes each icon's Unicode string to JavaScript. Handy when you set `label.text` from a controller.
+- `-f, --font-class-from-filename`: uses the font's filename as the font class name and icon prefix instead of the font family name. Useful when you want shorter prefixes. Replaces the old `-p` flag.
+
+### Using `--module`
+
+```bash
+$ purgetss build-fonts --module
+
+# alias:
+$ purgetss bf -m
+```
+
+To avoid prefix conflicts between libraries, each icon keeps its prefix as a nested object. Both `icons` and `families` are exported:
+
+`./app/lib/purgetss.fonts.js`
+```javascript
+const icons = {
+  // map-icons/map-icons.css
+  'mapIcon': {
+    'abseiling': '\ue800',
+    'accounting': '\ue801',
+    'airport': '\ue802',
+    'amusementPark': '\ue803',
+    // ...
+  },
+  // microns/microns.css
+  'mu': {
+    'arrowLeft': '\ue700',
+    'arrowRight': '\ue701',
+    'arrowUp': '\ue702',
+    'arrowDown': '\ue703',
+    // ...
+  }
+};
+exports.icons = icons;
+
+const families = {
+  // map-icons/map-icons.css
+  'mapIcon': 'map-icons',
+  // microns/microns.css
+  'mu': 'microns'
+};
+exports.families = families;
+```
+
+### Using `--font-class-from-filename`
+
+When you want the class name and the icon prefix to come from the **filename** of the `.ttf` and `.css` instead of the font family, use `-f`.
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ map-icons
+      ├─ map.ttf
+      └─ mp.css
+   └─ microns
+      ├─ mic.ttf
+      └─ mc.css
+```
+
+`./purgetss/styles/fonts.tss`
+```css
+/* "fontFamily" classes use the font's filename */
+'.map': { font: { fontFamily: 'map-icons' } }
+'.mic': { font: { fontFamily: 'microns' } }
+
+/* map-icons/mp.css */
+'.mp-abseiling': { text: '\ue800', title: '\ue800' }
+'.mp-accounting': { text: '\ue801', title: '\ue801' }
+'.mp-airport': { text: '\ue802', title: '\ue802' }
+'.mp-amusement-park': { text: '\ue803', title: '\ue803' }
+'.mp-aquarium': { text: '\ue804', title: '\ue804' }
+/* ... */
+
+/* microns/mc.css */
+'.mc-arrow-left': { text: '\ue700', title: '\ue700' }
+'.mc-arrow-right': { text: '\ue701', title: '\ue701' }
+'.mc-arrow-up': { text: '\ue702', title: '\ue702' }
+'.mc-arrow-down': { text: '\ue703', title: '\ue703' }
+'.mc-left': { text: '\ue704', title: '\ue704' }
+/* ... */
+```
+
+`./app/lib/purgetss.fonts.js`
+```javascript
+const icons = {
+  // map-icons/mp.css
+  'mp': {
+    'abseiling': '\ue800',
+    'accounting': '\ue801',
+    'airport': '\ue802',
+    'amusementPark': '\ue803',
+    // ...
+  },
+  // microns/mc.css
+  'mc': {
+    'arrowLeft': '\ue700',
+    'arrowRight': '\ue701',
+    'arrowUp': '\ue702',
+    'arrowDown': '\ue703',
+    // ...
+  }
+};
+exports.icons = icons;
+
+const families = {
+  // map-icons/mp.css
+  'mp': 'map-icons',
+  // microns/mc.css
+  'mc': 'microns'
+};
+exports.families = families;
+```
+
+> 🛑 **DANGER**
+> Make sure the new prefix is unique and does not conflict with other class prefixes. A duplicate prefix will silently overwrite earlier rules in the generated `fonts.tss`, leaving you with icons that render the wrong glyph at runtime.
+
+## Custom proprietary icon fonts
+
+If your design system ships its own icon font, treat it like any other icon library: drop the `.ttf` + `.css` pair into `./purgetss/fonts/<name>/` and run `build-fonts`. The classes are then available in your TSS.
+
+## Community-Discovered Patterns
+
+The following notes reflect community experience with `build-fonts` against real-world Titanium projects.
+
+> **💡 PostScript renaming**
+> `build-fonts` copies `.ttf`/`.otf` files into `./app/assets/fonts/` renamed to their **PostScript names**. iOS reads PostScript names while Android tolerates filenames; by renaming both platforms work from the same `fontFamily` value.
+
+> **🛑 Font Awesome Duotone**
+> Titanium cannot render Font Awesome duotone icons because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.
+
+> **💡 Use `--module` to set `text`/`title` from JavaScript**
+> Hardcoding `` in a controller is brittle. The `-m` flag generates a `purgetss.fonts.js` you can `require()` and reference by friendly name: `label.text = icons.fa.home`. Combine with `families` to set `font.fontFamily` programmatically.

package/skills/purgetss/references/custom-rules.md

@@ -16,7 +16,7 @@ Whether you want to style a Ti Element (a markup element such as `Label`), a cus
 
 > **CAUTION — Migrating from PurgeTSS v4 or v5 to v7+**
 >
-> If your project started on PurgeTSS v5 or earlier and you are now on 7.x.x or later, the class-naming convention changed (`camelCase` -> `kebab-case`) and the config moved to ESM-style `config.cjs`. The recommended upgrade path is:
+> If your project started on PurgeTSS v5 or earlier and you are now on 7.x.x or later, the class-naming convention changed (`camelCase` -> `kebab-case`) and the config moved to CommonJS-style `config.cjs`. The recommended upgrade path is:
 >
 > 1. **Audit current usage.** Set `purge.options.missing` to `true` in `config.cjs`. PurgeTSS will append a list of missing classes at the end of `app.tss` after the next compile — every entry is a class name you still need to migrate.
 > 2. **Rename selectors.** Convert every `.myCustomClassName` to `.my-custom-class-name` in both XML markup and `config.cjs`. The old camelCase names will not match anymore.

package/skills/purgetss/references/customization-deep-dive.md

@@ -57,9 +57,11 @@ module.exports = {
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
+    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files (v7.11.0)
     quality: 85,             // JPEG/WebP/AVIF quality (0-100)
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
-    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+    files: []                // per-file overrides: [{ filename, width, height? }] (v7.11.0)
     // Note: --width (v7.8.0) and --opacity / --padding / --output (v7.10.0) are CLI-only
     //       by design — those decisions are per-asset, not project-wide.
   },
@@ -270,6 +272,37 @@ module.exports = {
 };
 ```
 
+### Config Syntax Validation (v7.11.0)
+
+Since v7.11.0, PurgeTSS validates known fields in `config.cjs` at load time. On a type mismatch it prints a formatted `Config Syntax Error` block — file, JSON path, context, issue, and a fix snippet — instead of crashing downstream with a cryptic message like `rule.startsWith is not a function`.
+
+The validator runs on every config load and covers the case that trips up developers coming from Tailwind: `fontFamily` values must be a **string**, not a Tailwind-style array. It currently validates:
+
+- `theme.fontFamily.*` — expected a string.
+- `theme.extend.fontFamily.*` — expected a string.
+
+```javascript
+// ✗ Tailwind-style array — triggers a Config Syntax Error
+theme: {
+  extend: {
+    fontFamily: {
+      sans: ['Inter', 'sans-serif']
+    }
+  }
+}
+
+// ✓ Single font family per element (Titanium accepts one)
+theme: {
+  extend: {
+    fontFamily: {
+      sans: 'Inter-Regular'
+    }
+  }
+}
+```
+
+The scope is defined by the `FIELD_RULES` array in `src/shared/validation/config-validator.js`; additional fields can be added there. Today only the two `fontFamily` paths are validated.
+
 ## Overriding and Extending Properties
 
 By default, your project inherits values from the default theme. You have two options depending on your goal.
@@ -396,6 +429,36 @@ module.exports = {
 
 The nested keys are combined with the parent key to form class names like `bg-tahiti-400` or `text-tahiti-400`.
 
+### Nesting beyond one level
+
+Since v7.10.0, `theme` and `theme.extend` values are walked recursively, so you can group categories more than one level deep. Each level flattens into a kebab-case suffix on the generated class names:
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary: {
+            500: '#0ea5e9',
+            900: '#0c4a6e'
+          },
+          accent: '#f97316'
+        }
+      }
+    }
+  }
+};
+```
+
+```tss
+'.bg-brand-primary-500': { backgroundColor: '#0ea5e9' }
+'.bg-brand-primary-900': { backgroundColor: '#0c4a6e' }
+'.bg-brand-accent': { backgroundColor: '#f97316' }
+```
+
+Default modifier keys (`default`, `global`, `DEFAULT`) collapse without contributing to the suffix. The same flattening applies to other property categories that accept nested objects, including `backgroundGradient` and `backgroundSelectedGradient`. One-level configs behave exactly as before.
+
 ### Override a Default Color
 
 If you want to override one of the default colors but keep the rest, provide the new values in `theme.extend.colors`.