@maccesar/titools 4.4.0 → 4.4.2

package/skills/ti-expert/references/feedback-migration.md

@@ -1,7 +1,6 @@
 # Migrating feedback surfaces
 
-Migrate semantics, not proxy names. Replacing every native dialog with the same
-custom modal preserves the original design problem.
+Migrate semantics, not proxy names. Replacing every native dialog with the same custom modal preserves the original design problem.
 
 ## Contents
 
@@ -21,9 +20,7 @@ Search the application for:
 rg -n "createAlertDialog|createOptionDialog|createNotification|Toast|toast|snackbar|overlay" app/
 ```
 
-Also inspect helpers that wrap these calls, XML overlays, controller timers,
-global events, and callbacks that can present UI indirectly. Record for every
-occurrence:
+Also inspect helpers that wrap these calls, XML overlays, controller timers, global events, and callbacks that can present UI indirectly. Record for every occurrence:
 
 - trigger and current message;
 - success, information, warning, error, confirmation, or choice;
@@ -33,8 +30,7 @@ occurrence:
 - callback side effects and cancellation behavior;
 - owning window and cleanup path.
 
-Do not implement the replacement until every occurrence has a semantic target
-from `feedback-surfaces.md`.
+Do not implement the replacement until every occurrence has a semantic target from `feedback-surfaces.md`.
 
 ## Classify before replacing
 
@@ -47,13 +43,9 @@ Use these defaults:
 - uncommon irreversible decision → destructive Dialog;
 - several related actions or app-data choices → Bottom Sheet;
 - long structured content → scrollable sheet or dedicated screen;
-- OS permission, picker, share, date/time, biometric, or purchase flow → keep the
-  system surface.
+- OS permission, picker, share, date/time, biometric, or purchase flow → keep the system surface.
 
-Preserve domain behavior separately from presentation. Services return results
-or errors; the window/controller that owns visible context chooses the surface.
-Do not let a service create app-owned UI, especially before the root window
-exists.
+Preserve domain behavior separately from presentation. Services return results or errors; the window/controller that owns visible context chooses the surface. Do not let a service create app-owned UI, especially before the root window exists.
 
 ## Migrate one window at a time
 
@@ -62,19 +54,15 @@ exists.
 3. Attach modal Widgets after the window exists.
 4. Route each old result to its classified surface.
 5. Call Widget `destroy()` from the window close cleanup.
-6. Exercise success, failure, cancel, Back, backdrop, double tap, and consecutive
-   presentation paths.
-7. Remove the old dialog, local overlay, helper, timer, and listener after the
-   migrated window passes verification.
+6. Exercise success, failure, cancel, Back, backdrop, double tap, and consecutive presentation paths.
+7. Remove the old dialog, local overlay, helper, timer, and listener after the migrated window passes verification.
 8. Commit the completed vertical slice before moving to the next window.
 
-Do not keep commented legacy implementations. Version control is the rollback
-mechanism; commented duplicates hide incomplete migrations and stale callbacks.
+Do not keep commented legacy implementations. Version control is the rollback mechanism; commented duplicates hide incomplete migrations and stale callbacks.
 
 ## Deliberate silence
 
-Cancellation or an unknowable result can be a complete, intentional outcome.
-Model it explicitly and do not infer a message from falsy values.
+Cancellation or an unknowable result can be a complete, intentional outcome. Model it explicitly and do not infer a message from falsy values.
 
 Example contract for an exported file:
 
@@ -103,9 +91,7 @@ function handleSaveResult(error, result) {
 }
 ```
 
-Do not add "Cancelled" for `saved === false`. Do not claim success for
-`saved === null`. Cover both branches with tests so a future fallback does not
-erase the intended silence.
+Do not add "Cancelled" for `saved === false`. Do not claim success for `saved === null`. Cover both branches with tests so a future fallback does not erase the intended silence.
 
 ## Contract tests
 
@@ -114,8 +100,7 @@ Add repository-appropriate static or unit tests for:
 - all Widget folders, manifests, XML views, controllers, and dependency entries;
 - each public method documented in `feedback-widget-contracts.md`;
 - the expected Widget declared in every migrated window;
-- absence of app-owned `Ti.UI.createAlertDialog` and
-  `Ti.UI.createOptionDialog` defaults;
+- absence of app-owned `Ti.UI.createAlertDialog` and `Ti.UI.createOptionDialog` defaults;
 - removal of the previous local Snackbar/overlay and timer;
 - Snackbar replacement and timer reset;
 - Dialog and Bottom Sheet FIFO ordering;
@@ -124,18 +109,15 @@ Add repository-appropriate static or unit tests for:
 - cleanup of active and queued presentations;
 - explicit silence for cancel and indeterminate save results.
 
-Do not enforce blanket bans on native system surfaces. A remaining native call
-must be tied to an OS-owned interaction or documented fallback.
+Do not enforce blanket bans on native system surfaces. A remaining native call must be tied to an OS-owned interaction or documented fallback.
 
 ## Delivery verification
 
-Run the project's real commands rather than assuming names. A complete migration
-normally includes:
+Run the project's real commands rather than assuming names. A complete migration normally includes:
 
 1. lint with zero errors and no new warnings;
 2. unit and contract tests with no new failures;
-3. PurgeTSS generation when detected, followed by inspection of unused or
-   unsupported classes at the end of `app.tss`;
+3. PurgeTSS generation when detected, followed by inspection of unused or unsupported classes at the end of `app.tss`;
 4. Alloy compilation for Android and iOS;
 5. native builds for every supported platform;
 6. manual checks in light, dark, and system appearance;
@@ -144,9 +126,7 @@ normally includes:
 9. VoiceOver and TalkBack focus/traversal checks;
 10. consecutive presentation and window-close cleanup checks.
 
-Record pre-existing failures before migration and require the final run to add
-none. Build artifacts are not proof of usable modal behavior; perform the manual
-interaction checks on device or simulator.
+Record pre-existing failures before migration and require the final run to add none. Build artifacts are not proof of usable modal behavior; perform the manual interaction checks on device or simulator.
 
 ## When to share Widgets between apps
 
@@ -157,9 +137,7 @@ Extract or copy a Widget into another app only when:
 - appearance depends on a documented semantic-token contract;
 - platform and minimum Titanium/Alloy versions are declared;
 - lifecycle and accessibility tests travel with it;
-- at least two apps need the same behavior, or one app has a clear portability
-  requirement.
+- at least two apps need the same behavior, or one app has a clear portability requirement.
 
-Do not extract merely because a view appeared three times. Extract because the
-boundary is independently understandable, testable, and maintainable.
+Do not extract merely because a view appeared three times. Extract because the boundary is independently understandable, testable, and maintainable.
 

package/skills/ti-expert/references/feedback-surfaces.md

@@ -1,7 +1,6 @@
 # Feedback surfaces and app-owned UI
 
-Use this guide before choosing a Titanium proxy or drawing a component. The
-surface follows the meaning of the event: style comes afterwards.
+Use this guide before choosing a Titanium proxy or drawing a component. The surface follows the meaning of the event: style comes afterwards.
 
 ## Contents
 
@@ -21,12 +20,9 @@ Classify the event in this order:
 3. **Recovery**: is the action reversible or is data at risk?
 4. **Location**: does the message belong to a field, a screen, or the whole app?
 5. **Persistence**: is it transient, persistent until state changes, or modal?
-6. **Choice shape**: is there one acknowledgement, a binary decision, or a list
-   of related actions?
+6. **Choice shape**: is there one acknowledgement, a binary decision, or a list of related actions?
 
-Do not begin with "which native dialog can display this string?" That turns
-different meanings into the same interruption and makes the app feel visually
-inconsistent.
+Do not begin with "which native dialog can display this string?" That turns different meanings into the same interruption and makes the app feel visually inconsistent.
 
 ## Feedback scale
 
@@ -46,20 +42,13 @@ inconsistent.
 | No content yet | Empty State inside the screen | This is screen state, not transient feedback |
 | Initial or blocking work | Loading/Progress state in context | Communicates progress without inventing a message |
 
-Reserve Dialogs for critical information. Do not use them merely because they
-are easy to create. If an action is common and undoable, prefer immediate
-execution plus Undo over confirmation.
+Reserve Dialogs for critical information. Do not use them merely because they are easy to create. If an action is common and undoable, prefer immediate execution plus Undo over confirmation.
 
 ### Snackbar versus Toast
 
-For app-owned foreground feedback, standardize on Snackbar. It supports the
-app's semantic colors, accessibility, safe-area positioning, duration policy,
-and one optional recovery action. Do not maintain both a custom Toast and a
-Snackbar for the same job.
+For app-owned foreground feedback, standardize on Snackbar. It supports the app's semantic colors, accessibility, safe-area positioning, duration policy, and one optional recovery action. Do not maintain both a custom Toast and a Snackbar for the same job.
 
-A platform Toast can remain only when the operating system owns the behavior or
-when a documented platform fallback is necessary. It is not the default design
-surface.
+A platform Toast can remain only when the operating system owns the behavior or when a documented platform fallback is necessary. It is not the default design surface.
 
 ### Banner versus Snackbar
 
@@ -69,17 +58,13 @@ surface.
 
 ### Bottom Sheet versus Dialog
 
-- Use Bottom Sheet for related choices: sorting, exporting, selecting a category,
-  or choosing an action for an item.
+- Use Bottom Sheet for related choices: sorting, exporting, selecting a category, or choosing an action for an item.
 - Use Dialog for acknowledgement or a consequential confirm/cancel decision.
-- Move long prose, structured data, search, or complex input into a sheet or
-  dedicated screen.
+- Move long prose, structured data, search, or complex input into a sheet or dedicated screen.
 
 ## App-owned versus system-owned
 
-Recreate and brand a surface only when the app owns its content and behavior.
-Keep the platform UI when the system owns trust, permissions, identity, files,
-or another protected workflow.
+Recreate and brand a surface only when the app owns its content and behavior. Keep the platform UI when the system owns trust, permissions, identity, files, or another protected workflow.
 
 | Keep native/system-owned | May be app-owned and styled |
 | --- | --- |
@@ -91,43 +76,29 @@ or another protected workflow.
 | Biometric authentication prompt | Banners and inline validation |
 | Keyboard, autofill, purchases, notifications, and OS settings | App-specific onboarding or education |
 
-An app may explain why a system surface is about to appear, but it must not
-imitate the trusted system prompt. Use the official Titanium API or native module
-for the system-owned part.
+An app may explain why a system surface is about to appear, but it must not imitate the trusted system prompt. Use the official Titanium API or native module for the system-owned part.
 
-Cancellation is often a normal system outcome. Do not turn every cancellation
-into an error, a "Cancelled" message, or an unsupported success claim. Document
-silence explicitly at the call site when it is meaningful.
+Cancellation is often a normal system outcome. Do not turn every cancellation into an error, a "Cancelled" message, or an unsupported success claim. Document silence explicitly at the call site when it is meaningful.
 
 ## What to standardize next
 
 After Snackbar, Dialog, and Bottom Sheet, the highest-value shared patterns are:
 
 1. **Banner / Inline Notice** for persistent app state.
-2. **Loading / Progress wrapper** that uses the native activity indicator but
-   standardizes placement, text, blocking behavior, and cleanup.
+2. **Loading / Progress wrapper** that uses the native activity indicator but standardizes placement, text, blocking behavior, and cleanup.
 3. **Empty / Error State** for consistent screen-level recovery.
 4. **Field Validation** for message placement, focus, accessibility, and colors.
 
-Standardize buttons, cards, badges, chips, skeletons, and coach marks only when
-real product repetition exposes a stable contract. A visual resemblance alone
-does not justify a Widget.
+Standardize buttons, cards, badges, chips, skeletons, and coach marks only when real product repetition exposes a stable contract. A visual resemblance alone does not justify a Widget.
 
 ## Phone, tablet, and accessibility
 
-- On phones, present contextual choices from the bottom and keep touch targets
-  reachable.
-- On tablets and large screens, use a centered, width-limited action surface or
-  a platform-appropriate anchored presentation; do not stretch phone geometry
-  edge to edge.
-- Respect safe areas, bottom navigation, orientation, split screen, text scaling,
-  and localized strings.
-- Announce transient feedback appropriately and move accessibility focus into a
-  modal surface when it opens.
-- While a modal is active, prevent interaction with and accessibility traversal
-  into the underlying content. Restore the exact previous state on close.
-- Back, backdrop, Cancel, and destructive actions must have predictable semantics
-  and must never execute callbacks more than once.
+- On phones, present contextual choices from the bottom and keep touch targets reachable.
+- On tablets and large screens, use a centered, width-limited action surface or a platform-appropriate anchored presentation; do not stretch phone geometry edge to edge.
+- Respect safe areas, bottom navigation, orientation, split screen, text scaling, and localized strings.
+- Announce transient feedback appropriately and move accessibility focus into a modal surface when it opens.
+- While a modal is active, prevent interaction with and accessibility traversal into the underlying content. Restore the exact previous state on close.
+- Back, backdrop, Cancel, and destructive actions must have predictable semantics and must never execute callbacks more than once.
 
 ## References
 

package/skills/ti-expert/references/feedback-widget-contracts.md

@@ -1,7 +1,6 @@
 # Contracts for feedback Widgets
 
-Use these contracts for app-owned Snackbar, Dialog, and Bottom Sheet surfaces in
-Alloy. Namespaces and visual tokens belong to each app; behavior stays stable.
+Use these contracts for app-owned Snackbar, Dialog, and Bottom Sheet surfaces in Alloy. Namespaces and visual tokens belong to each app; behavior stays stable.
 
 ## Contents
 
@@ -15,12 +14,7 @@ Alloy. Namespaces and visual tokens belong to each app; behavior stays stable.
 
 ## Boundary and registration
 
-Implement each surface as an independent Alloy Widget under `app/widgets/`.
-Each Widget owns its XML, controller, optional styles, assets, state, listeners,
-timers, and `widget.json`. Keep them independent from any third-party component
-library — including TiKit, the Alloy/PurgeTSS component set. A feedback surface
-must not require one to work, and must not be folded into one: its value comes
-from being installable and testable on its own.
+Implement each surface as an independent Alloy Widget under `app/widgets/`. Each Widget owns its XML, controller, optional styles, assets, state, listeners, timers, and `widget.json`. Keep them independent from any third-party component library — including TiKit, the Alloy/PurgeTSS component set. A feedback surface must not require one to work, and must not be folded into one: its value comes from being installable and testable on its own.
 
 Register every Widget in `app/config.json`:
 
@@ -34,11 +28,9 @@ Register every Widget in `app/config.json`:
 }
 ```
 
-Use the app's reverse-domain namespace. The dependency key must match the `id`
-in that Widget's `widget.json`.
+Use the app's reverse-domain namespace. The dependency key must match the `id` in that Widget's `widget.json`.
 
-Declare Widgets in XML, normally as the last visual children of the owning
-window so overlays render above screen content:
+Declare Widgets in XML, normally as the last visual children of the owning window so overlays render above screen content:
 
 ```xml
 <Widget id="snackbar" src="com.example.ui.snackbar" />
@@ -46,8 +38,7 @@ window so overlays render above screen content:
 <Widget id="bottomSheet" src="com.example.ui.bottomsheet" />
 ```
 
-Build the stable proxy tree in XML. JavaScript may update properties and supply
-`ListView` data; it must not reconstruct the complete surface imperatively.
+Build the stable proxy tree in XML. JavaScript may update properties and supply `ListView` data; it must not reconstruct the complete surface imperatively.
 
 ## Snackbar
 
@@ -68,12 +59,10 @@ $.snackbar.destroy()
 Contract:
 
 - A new message replaces the visible message and restarts the timer.
-- Default `duration` is 4500 ms; `duration: 0` remains visible until an action,
-  `dismiss()`, replacement, or destruction.
+- Default `duration` is 4500 ms; `duration: 0` remains visible until an action, `dismiss()`, replacement, or destruction.
 - Allow at most one text action, such as Undo.
 - Invoke `onAction` once, then close the Snackbar.
-- Invoke `onDismiss` once with the reason `timeout`, `action`, `replaced`,
-  `programmatic`, or `destroy`.
+- Invoke `onDismiss` once with the reason `timeout`, `action`, `replaced`, `programmatic`, or `destroy`.
 - Clear the old timer before replacement and on every close path.
 - Position above bottom navigation and inside the current safe area.
 - Queueing Snackbars is not the default. The newest relevant message wins.
@@ -100,20 +89,15 @@ $.dialog.destroy()
 
 Contract:
 
-- Without `cancelTitle`, present an acknowledgement. With it, present a
-  confirmation.
+- Without `cancelTitle`, present an acknowledgement. With it, present a confirmation.
 - Enqueue additional `show()` calls FIFO. Never stack two Dialogs visually.
 - Disable both buttons on the first accepted tap.
 - Invoke `onConfirm` or `onCancel` at most once; never both.
-- Cancel button, Android Back, or allowed backdrop dismissal invokes `onCancel`.
-  Android Back closes an acknowledgement as its single dismissal action.
+- Cancel button, Android Back, or allowed backdrop dismissal invokes `onCancel`. Android Back closes an acknowledgement as its single dismissal action.
 - A destructive confirmation must not close from a backdrop tap.
-- `dismiss('programmatic')` closes without treating the operation as a user
-  confirmation or cancellation.
-- `destroy()` clears the active request and queue without running business
-  callbacks.
-- Use platform-familiar safe/cancel ordering and a distinct destructive role;
-  do not hard-code one platform's button order for both.
+- `dismiss('programmatic')` closes without treating the operation as a user confirmation or cancellation.
+- `destroy()` clears the active request and queue without running business callbacks.
+- Use platform-familiar safe/cancel ordering and a distinct destructive role; do not hard-code one platform's button order for both.
 
 ## Bottom Sheet
 
@@ -142,60 +126,40 @@ $.bottomSheet.destroy()
 
 Contract:
 
-- Render items with a fixed `ListView` template and data objects. Support long
-  lists, disabled rows, optional subtitles/icons, and a selected marker.
+- Render items with a fixed `ListView` template and data objects. Support long lists, disabled rows, optional subtitles/icons, and a selected marker.
 - Enqueue additional `show()` calls FIFO. Never stack sheets.
-- Accept the first enabled selection only, invoke `onSelect(item)` once, and
-  close.
+- Accept the first enabled selection only, invoke `onSelect(item)` once, and close.
 - Backdrop, Android Back, Cancel, or `dismiss('cancel')` invokes `onCancel` once.
-- Other programmatic dismissal and `destroy()` do not imply cancellation and do
-  not execute business callbacks.
-- Present from the bottom on phones. On tablets and large screens, use a centered,
-  width-limited action surface. Reserve `anchor` for a future anchored variant;
-  do not expose behavior that is not implemented.
+- Other programmatic dismissal and `destroy()` do not imply cancellation and do not execute business callbacks.
+- Present from the bottom on phones. On tablets and large screens, use a centered, width-limited action surface. Reserve `anchor` for a future anchored variant; do not expose behavior that is not implemented.
 
 ## Shared lifecycle contract
 
-- Prefer one instance of each needed Widget per window. Add a global coordinator
-  only after real cross-window requirements exist.
-- Call `attach(window)` after the host window/controller exists. Call `destroy()`
-  from the host's close cleanup.
-- Make `destroy()` idempotent. Remove listeners, clear timers, cancel pending
-  animation callbacks, clear queues, and release callback references.
-- Guard every asynchronous completion with the current presentation generation
-  so a stale timer or animation cannot dismiss a newer request.
+- Prefer one instance of each needed Widget per window. Add a global coordinator only after real cross-window requirements exist.
+- Call `attach(window)` after the host window/controller exists. Call `destroy()` from the host's close cleanup.
+- Make `destroy()` idempotent. Remove listeners, clear timers, cancel pending animation callbacks, clear queues, and release callback references.
+- Guard every asynchronous completion with the current presentation generation so a stale timer or animation cannot dismiss a newer request.
 - Consume backdrop events and prevent them from bubbling to underlying controls.
-- Save the host's previous accessibility state, exclude underlying content while
-  modal, move focus to the surface, and restore the saved state on close.
-- Keep localized copy outside the Widget. Pass strings and business callbacks in
-  the public API.
-- Keep business logic out of the Widget. It reports a choice; the host performs
-  domain work.
-- Verify every callback path for exactly-once behavior: action, confirm, cancel,
-  Back, backdrop, timeout, replacement, programmatic dismissal, and destruction.
+- Save the host's previous accessibility state, exclude underlying content while modal, move focus to the surface, and restore the saved state on close.
+- Keep localized copy outside the Widget. Pass strings and business callbacks in the public API.
+- Keep business logic out of the Widget. It reports a choice; the host performs domain work.
+- Verify every callback path for exactly-once behavior: action, confirm, cancel, Back, backdrop, timeout, replacement, programmatic dismissal, and destruction.
 
 ## PurgeTSS integration
 
-When `purgetss/` or `purgetss/config.cjs` exists, load the `purgetss` skill before
-writing styles. `ti-expert` decides the component boundary; `purgetss` decides
-the verified utilities and configuration.
+When `purgetss/` or `purgetss/config.cjs` exists, load the `purgetss` skill before writing styles. `ti-expert` decides the component boundary; `purgetss` decides the verified utilities and configuration.
 
 Apply these architectural rules:
 
 - Set PurgeTSS `options.widgets` to `true` so Widget XML is scanned.
 - Express stable anatomy and utility classes in Widget XML.
-- Use semantic color names for surfaces, text, borders, accent, overlay, success,
-  warning, and error. Let Titanium resolve light/dark variants.
+- Use semantic color names for surfaces, text, borders, accent, overlay, success, warning, and error. Let Titanium resolve light/dark variants.
 - Do not edit generated `app/styles/app.tss`.
-- Use `widget.tss` only for properties that have no verified utility or that are
-  inherently specific to the Widget.
-- Declare animations as XML `Animation` proxies using `purgetss.ui`. Use explicit
-  `open()` and `close()` calls instead of toggle behavior.
-- After generation, inspect the final `app.tss` section for unused or unsupported
-  classes and resolve every new entry.
+- Use `widget.tss` only for properties that have no verified utility or that are inherently specific to the Widget.
+- Declare animations as XML `Animation` proxies using `purgetss.ui`. Use explicit `open()` and `close()` calls instead of toggle behavior.
+- After generation, inspect the final `app.tss` section for unused or unsupported classes and resolve every new entry.
 
-Do not copy class inventories into this skill and do not guess Tailwind-like
-names. The installed PurgeTSS skill remains the source of truth.
+Do not copy class inventories into this skill and do not guess Tailwind-like names. The installed PurgeTSS skill remains the source of truth.
 
 ## Widget, Require, state, or native UI
 
@@ -207,7 +171,5 @@ names. The installed PurgeTSS skill remains the source of truth.
 | TSS or PurgeTSS utilities | Repeated visual treatment has no behavior, state, or lifecycle |
 | Native/system UI | The operating system owns permissions, trust, files, sharing, identity, purchases, or another protected flow |
 
-Usage count is evidence, not a threshold. A component can deserve a Widget on
-its first use if it has a stable portable API and non-trivial lifecycle; three
-similar labels still do not deserve one.
+Usage count is evidence, not a threshold. A component can deserve a Widget on its first use if it has a stable portable API and non-trivial lifecycle; three similar labels still do not deserve one.