@maccesar/titools 4.3.0 → 4.4.2

package/skills/ti-expert/references/anti-patterns.md

@@ -1,46 +1,35 @@
 # Titanium Alloy anti-patterns
 
 ## 1. Inline styling instead of TSS
-**Symptom:** Using inline attributes like `backgroundColor="#fff"` directly in XML views.
-**Problem:** Inline attributes make theme changes impossible and scatter visual definitions across views.
-**Solution:** Define styles in TSS files using IDs or class selectors.
+**Symptom:** Using inline attributes like `backgroundColor="#fff"` directly in XML views. **Problem:** Inline attributes make theme changes impossible and scatter visual definitions across views. **Solution:** Define styles in TSS files using IDs or class selectors.
 
 ## 2. Fat controllers
-**Symptom:** Controllers with 100+ lines handling logic, API, and UI.
-**Solution:** Delegate business logic to `lib/services/` and API calls to `lib/api/`.
+**Symptom:** Controllers with 100+ lines handling logic, API, and UI. **Solution:** Delegate business logic to `lib/services/` and API calls to `lib/api/`.
 
 ## 3. Memory leaks (Missing Cleanup)
-**Symptom:** Adding `Ti.App` or `Alloy.Collections` listeners without a `cleanup()` function.
-**Solution:** Always implement `$.cleanup = cleanup` and remove listeners there.
+**Symptom:** Adding `Ti.App` or `Alloy.Collections` listeners without a `cleanup()` function. **Solution:** Always implement `$.cleanup = cleanup` and remove listeners there.
 
 ## 4. Direct native module calls
-**Symptom:** Calling `require('ti.module')` directly in a controller.
-**Solution:** Wrap it in a service in `lib/services/` (e.g., `audioService.js`).
+**Symptom:** Calling `require('ti.module')` directly in a controller. **Solution:** Wrap it in a service in `lib/services/` (e.g., `audioService.js`).
 
 ## 5. Direct controller navigation
-**Symptom:** `Alloy.createController('name').getView().open()`.
-**Solution:** Use a Navigation Service to centralize `open/close` and trigger the `cleanup()` function automatically.
+**Symptom:** `Alloy.createController('name').getView().open()`. **Solution:** Use a Navigation Service to centralize `open/close` and trigger the `cleanup()` function automatically.
 
 ## 6. Complex matrix animations
-**Symptom:** Manual use of `Ti.UI.create2DMatrix()` for simple animations.
-**Solution:** Use `Ti.UI.createAnimation()` for opacity, transform, and duration-based animations. Reserve 2D Matrix for complex multi-property transforms.
+**Symptom:** Manual use of `Ti.UI.create2DMatrix()` for simple animations. **Solution:** Use `Ti.UI.createAnimation()` for opacity, transform, and duration-based animations. Reserve 2D Matrix for complex multi-property transforms.
 
 ## 7. Hardcoded strings & missing a11y
-**Symptom:** `text="Login"` instead of `text="L('login')"`, or missing `accessibilityLabel`.
-**Solution:** Always use i18n and accessibility properties.
+**Symptom:** `text="Login"` instead of `text="L('login')"`, or missing `accessibilityLabel`. **Solution:** Always use i18n and accessibility properties.
 
 ## 8. Logic in TSS
-**Symptom:** Using conditionals or calculations inside TSS.
-**Solution:** Keep styling declarative in TSS files.
+**Symptom:** Using conditionals or calculations inside TSS. **Solution:** Keep styling declarative in TSS files.
 
 ---
 
 ## Titanium layout anti-patterns
 
 ## 9. Padding on container views
-**Symptom:** Setting `padding` on View, Window, ScrollView, or TableView.
-**Problem:** Base container elements don't support padding in Titanium.
-**Solution:** Use margins on children instead:
+**Symptom:** Setting `padding` on View, Window, ScrollView, or TableView. **Problem:** Base container elements don't support padding in Titanium. **Solution:** Use margins on children instead:
 ```tss
 /* WRONG */
 "#container": { padding: 16 }
@@ -50,31 +39,21 @@
 ```
 
 ## 10. Redundant composite layout
-**Symptom:** Adding `layout: 'composite'` to Views.
-**Problem:** Composite (absolute positioning) is the DEFAULT layout. Setting it is redundant.
-**Solution:** Omit `layout` for composite, only specify `layout: 'horizontal'` or `layout: 'vertical'` when needed.
+**Symptom:** Adding `layout: 'composite'` to Views. **Problem:** Composite (absolute positioning) is the DEFAULT layout. Setting it is redundant. **Solution:** Omit `layout` for composite, only specify `layout: 'horizontal'` or `layout: 'vertical'` when needed.
 
 ## 11. Using `lib/` prefix in require statements
-**Symptom:** `const service = require('lib/services/picsum')`
-**Problem:** Alloy flattens the `lib/` folder during build. Files in `app/lib/services/` become `Resources/iphone/services/`.
-**Solution:** Omit the `lib/` prefix: `const service = require('services/picsum')`
+**Symptom:** `const service = require('lib/services/picsum')` **Problem:** Alloy flattens the `lib/` folder during build. Files in `app/lib/services/` become `Resources/iphone/services/`. **Solution:** Omit the `lib/` prefix: `const service = require('services/picsum')`
 
 ## 12. Wrong window ID in controller
-**Symptom:** Using `$.index.open()` when the Window has `id="mainWindow"`.
-**Problem:** Alloy generates `$` references from XML IDs. If Window is `id="mainWindow"`, `$.index` doesn't exist.
-**Solution:** Match the ID: `$.mainWindow.open()`
+**Symptom:** Using `$.index.open()` when the Window has `id="mainWindow"`. **Problem:** Alloy generates `$` references from XML IDs. If Window is `id="mainWindow"`, `$.index` doesn't exist. **Solution:** Match the ID: `$.mainWindow.open()`
 
 ## 13. Using `Ti.UI.createNotification`
-**Symptom:** `Ti.UI.createNotification({ message: 'Hi' }).show()`
-**Problem:** This API doesn't exist in Titanium. Causes "invalid method" error.
-**Solution:** Use `Ti.UI.createAlertDialog` for simple messages, or create custom toast views.
+**Symptom:** `Ti.UI.createNotification({ message: 'Hi' }).show()` **Problem:** This API doesn't exist in Titanium. Causes "invalid method" error. **Solution:** Classify the feedback before choosing UI. Use the app's Snackbar Widget for transient foreground feedback, inline/Banner state for persistent conditions, and an app-owned Dialog only for blocking or critical information. Use the supported platform notification APIs only for actual OS notifications. See [Feedback Surfaces](feedback-surfaces.md).
 
 ## 14. Using nonexistent iOS share APIs
-**Symptom:** `Ti.UI.iOS.createActivityPopover` or `alloy/social` with wrong methods.
-**Problem:** These APIs either don't exist or have changed. Causes runtime errors.
-**Solution:**
-- iOS: Use `Ti.UI.iOS.createDocumentViewer` for files, or simple `Ti.UI.createOptionDialog` + `Ti.UI.Clipboard` for links
-- Android: Use `Ti.Android.createIntent` with ACTION_SEND
+**Symptom:** `Ti.UI.iOS.createActivityPopover` or `alloy/social` with wrong methods. **Problem:** These APIs either don't exist or have changed. Causes runtime errors. **Solution:**
+- Keep sharing system-owned. Use the currently supported Titanium share/document API or native module for the target platform and verify its current contract with the `ti-api` skill.
+- Do not imitate a share sheet with an app-owned `OptionDialog`. A Bottom Sheet may choose an app action such as an export format, but the OS share surface owns the final destination.
 
 ## Community-Discovered Patterns
 
@@ -117,8 +96,8 @@ This applies to Windows inside both standalone NavigationWindow and TabGroup (wh
 | ----------------------- | ------------------------ | --------------------- |
 | `padding` on View       | No padding on containers | Margins on children   |
 | `layout: 'composite'`   | Already default          | Omit it               |
-| Inline style attributes | Scattered styling        | Define in TSS files   |
+| Inline style attributes | Scattered styling        | PurgeTSS utilities when detected; otherwise TSS |
 | `lib/` prefix           | lib/ is flattened        | Use path without lib/ |
 | `$.index.open()`        | Wrong ID reference       | Use actual Window ID  |
-| `createNotification`    | API doesn't exist        | `createAlertDialog`   |
+| `createNotification`    | API doesn't exist        | Classify feedback; Snackbar is the transient default |
 | `extendEdges` alone     | Content behind nav bar   | Add `autoAdjustScrollViewInsets: true` |

package/skills/ti-expert/references/code-conventions.md

@@ -54,9 +54,11 @@ const name = user.name
 
 ## Styling with TSS
 
+First detect `purgetss/` or `purgetss/config.cjs`. If present, invoke the `purgetss` skill, use verified utilities, and do not edit generated `app/styles/app.tss`. The manual TSS organization below applies when PurgeTSS is not present or to specific properties for which that skill confirms no utility.
+
 ### TSS file organization
 
-Every controller can have a matching TSS file. Alloy also supports a global `app.tss`.
+Every controller can have a matching TSS file. Standard Alloy also supports a manually maintained global `app.tss`.
 
 ```
 app/styles/
@@ -95,7 +97,7 @@ app/styles/
 | Selector            | Use for                     | Example                |
 | ------------------- | --------------------------- | ---------------------- |
 | Element (`"Label"`) | App-wide defaults           | Base font, color       |
-| Class (`".card"`)   | Reusable patterns (3+ uses) | Cards, buttons, inputs |
+| Class (`".card"`)   | Reusable visual pattern     | Cards, buttons, inputs |
 | ID (`"#name"`)      | Unique element positioning  | Specific layout needs  |
 
 ### Class selectors in XML
@@ -127,7 +129,7 @@ When an element has both an ID and classes, properties merge with ID taking prio
 <Button id="saveButton" class="btn-primary" title="L('save')" />
 ```
 
-### Building a design system in app.tss
+### Building a standard Alloy design system in app.tss
 
 Define reusable style classes for consistency:
 

package/skills/ti-expert/references/controller-patterns.md

@@ -281,43 +281,40 @@ async function loadData() {
 
 ## Modal and dialog patterns
 
+Declare the app-owned `dialog` and `bottomSheet` Widgets in the window XML. Attach them after the host exists and destroy them from the controller cleanup. Keep a modal Window for a distinct multi-step task, not for ordinary feedback.
+
 ```javascript
-// AlertDialog
+function attachFeedback(hostWindow) {
+  $.dialog.attach(hostWindow)
+  $.bottomSheet.attach(hostWindow)
+}
+
+// Critical, irreversible confirmation
 function showConfirmDelete(itemName) {
-  const dialog = Ti.UI.createAlertDialog({
+  $.dialog.show({
     title: L('confirm_delete'),
     message: String.format(L('delete_message'), itemName),
-    buttonNames: [L('cancel'), L('delete')],
-    cancel: 0,
-    destructive: 1 // iOS: red button
-  })
-
-  dialog.addEventListener('click', (e) => {
-    if (e.index === 1) {
-      performDelete()
-    }
+    cancelTitle: L('cancel'),
+    confirmTitle: L('delete'),
+    destructive: true,
+    tone: 'warning',
+    onConfirm: performDelete
   })
-
-  dialog.show()
 }
 
-// OptionDialog (Action Sheet)
+// Contextual choices
 function showSortOptions() {
-  const options = [L('sort_name'), L('sort_date'), L('sort_price')]
+  const items = [
+    { id: 'name', title: L('sort_name') },
+    { id: 'date', title: L('sort_date') },
+    { id: 'price', title: L('sort_price') }
+  ]
 
-  const dialog = Ti.UI.createOptionDialog({
+  $.bottomSheet.show({
     title: L('sort_by'),
-    options: [...options, L('cancel')],
-    cancel: options.length
-  })
-
-  dialog.addEventListener('click', (e) => {
-    if (e.index < options.length) {
-      applySortOption(e.index)
-    }
+    items,
+    onSelect: item => applySortOption(item.id)
   })
-
-  dialog.show()
 }
 
 // Modal Window
@@ -341,6 +338,14 @@ function openModal(route, params) {
 
   return controller
 }
+
+function cleanup() {
+  $.dialog.destroy()
+  $.bottomSheet.destroy()
+  $.destroy()
+}
+
+$.cleanup = cleanup
 ```
 
 ## Tabgroup pattern

package/skills/ti-expert/references/examples.md

@@ -3,6 +3,7 @@
 <!-- TOC-START -->
 ## Contents
 
+- [Reading these examples](#reading-these-examples)
 - [API client service](#api-client-service)
 - [Native module wrapper service](#native-module-wrapper-service)
 - [i18n helper](#i18n-helper)
@@ -17,6 +18,12 @@
 
 <!-- TOC-END -->
 
+## Reading these examples
+
+Snippets that call `$.dialog`, `$.bottomSheet`, or `$.snackbar` expect the app to own those surfaces as Alloy Widgets under `app/widgets/`. Their public API, queueing, and cleanup rules live in [Feedback Widget Contracts](feedback-widget-contracts.md); [Feedback Surfaces](feedback-surfaces.md) covers which surface a given event deserves. The `<Widget>` declaration alone will not compile until those Widgets exist and are registered in `app/config.json`.
+
+Styles below carry literal hex values so each example reads on its own. Production code should name semantic color roles instead, so light and dark resolve without a second code path — see [Theming and dark mode](theming.md).
+
 ## API client service
 Standard logic for network requests.
 
@@ -350,6 +357,8 @@ $.cleanup = cleanup
       <ImageView id="emptyIcon" image="/images/search.png" />
       <Label id="emptyLabel" text="L('no_results')" />
     </View>
+
+    <Widget id="bottomSheet" src="com.example.ui.bottomsheet" />
   </Window>
 </Alloy>
 ```
@@ -375,6 +384,7 @@ let searchQuery = ''
 let debounceTimer = null
 
 function init() {
+  $.bottomSheet.attach($.contactsWindow)
   loadData()
 
   $.searchBar.addEventListener('cancel', clearSearch)
@@ -395,21 +405,23 @@ function clearSearch() {
 }
 
 function showFilters() {
-  const dialog = Ti.UI.createOptionDialog({
+  const items = [
+    { id: 'all', title: L('all') },
+    { id: 'work', title: L('work') },
+    { id: 'personal', title: L('personal') },
+    { id: 'family', title: L('family') }
+  ]
+
+  $.bottomSheet.show({
     title: L('filter_by_category'),
-    options: ['All', 'Work', 'Personal', 'Family', L('cancel')],
-    cancel: 4
-  })
-
-  dialog.addEventListener('click', (e) => {
-    if (e.index < 4) {
-      activeFilters.category = e.index === 0 ? null : ['work', 'personal', 'family'][e.index - 1]
+    items,
+    selectedId: activeFilters.category || 'all',
+    onSelect: item => {
+      activeFilters.category = item.id === 'all' ? null : item.id
       updateFilterTags()
       applyFilters()
     }
   })
-
-  dialog.show()
 }
 
 function applyFilters() {
@@ -465,6 +477,7 @@ function createFilterTag(label, onRemove) {
 
 function cleanup() {
   clearTimeout(debounceTimer)
+  $.bottomSheet.destroy()
   $.searchBar.removeEventListener('change', onSearchChange)
   $.destroy()
 }
@@ -530,6 +543,7 @@ $.cleanup = cleanup
           <Switch id="termsSwitch" />
           <Label id="termsLabel" text="L('accept_terms')" />
         </View>
+        <Label id="termsError" />
 
         <!-- Register Button -->
         <Button id="registerBtn"
@@ -544,6 +558,8 @@ $.cleanup = cleanup
         </View>
       </View>
     </ScrollView>
+
+    <Widget id="dialog" src="com.example.ui.dialog" />
   </Window>
 </Alloy>
 ```
@@ -570,6 +586,7 @@ $.cleanup = cleanup
 "#termsRow": { layout: 'horizontal', left: 16, right: 16, top: 24, width: Ti.UI.FILL }
 "#termsSwitch": { width: 48 }
 "#termsLabel": { left: 8 }
+"#termsError": { left: 16, right: 16, top: 4, font: { fontSize: 12 }, color: '#ef4444', visible: false }
 "#registerBtn": { left: 16, right: 16, top: 24, height: 56, borderRadius: 12, backgroundColor: '#2563eb', color: '#fff', font: { fontWeight: 'bold' } }
 "#loginRow": { layout: 'horizontal', top: 16 }
 "#haveAccountLabel": { font: { fontSize: 14 }, color: '#4b5563' }
@@ -611,6 +628,8 @@ const validators = {
 }
 
 function init() {
+  $.dialog.attach($.registerWindow)
+
   // Field navigation
   $.nameField.addEventListener('return', () => $.emailField.focus())
   $.emailField.addEventListener('return', () => $.passwordField.focus())
@@ -658,16 +677,14 @@ function validateAll() {
   const emailValid = validateField('email')
   const passwordValid = validateField('password')
   const confirmValid = validateField('confirm')
+  const termsValid = $.termsSwitch.value
 
-  if (!$.termsSwitch.value) {
-    Ti.UI.createAlertDialog({
-      title: L('error'),
-      message: L('error_accept_terms')
-    }).show()
-    return false
-  }
+  $.termsError.applyProperties({
+    text: termsValid ? '' : L('error_accept_terms'),
+    visible: !termsValid
+  })
 
-  return nameValid && emailValid && passwordValid && confirmValid
+  return nameValid && emailValid && passwordValid && confirmValid && termsValid
 }
 
 async function onRegister() {
@@ -686,10 +703,12 @@ async function onRegister() {
     Navigation.replace('main')
 
   } catch (error) {
-    Ti.UI.createAlertDialog({
+    $.dialog.show({
       title: L('error'),
-      message: error.message
-    }).show()
+      message: error.message,
+      tone: 'error',
+      confirmTitle: L('close')
+    })
   } finally {
     setLoading(false)
   }
@@ -707,6 +726,7 @@ function goToLogin() {
 }
 
 function cleanup() {
+  $.dialog.destroy()
   $.destroy()
 }
 

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

@@ -0,0 +1,143 @@
+# Migrating feedback surfaces
+
+Migrate semantics, not proxy names. Replacing every native dialog with the same custom modal preserves the original design problem.
+
+## Contents
+
+- [Inventory](#inventory)
+- [Classify before replacing](#classify-before-replacing)
+- [Migrate one window at a time](#migrate-one-window-at-a-time)
+- [Deliberate silence](#deliberate-silence)
+- [Contract tests](#contract-tests)
+- [Delivery verification](#delivery-verification)
+- [When to share Widgets between apps](#when-to-share-widgets-between-apps)
+
+## Inventory
+
+Search the application for:
+
+```bash
+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:
+
+- trigger and current message;
+- success, information, warning, error, confirmation, or choice;
+- blocking versus non-blocking;
+- reversible versus irreversible;
+- app-owned versus system-owned;
+- 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`.
+
+## Classify before replacing
+
+Use these defaults:
+
+- ordinary success and undoable actions → Snackbar;
+- recoverable field validation → inline validation;
+- persistent app condition → Banner or inline notice;
+- blocking failure or required acknowledgement → Dialog;
+- 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.
+
+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
+
+1. Register the required Widget dependencies in `app/config.json`.
+2. Add the Widgets as the final visual children of the window XML.
+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.
+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.
+
+## 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.
+
+Example contract for an exported file:
+
+```javascript
+function handleSaveResult(error, result) {
+  if (error) {
+    $.dialog.show({
+      title: L('error'),
+      message: error.message,
+      tone: 'error',
+      confirmTitle: L('close')
+    })
+    return
+  }
+
+  if (result.saved === true) {
+    $.snackbar.show({
+      message: L('file_saved'),
+      tone: 'success'
+    })
+  }
+
+  // saved === false: Android picker was cancelled; the internal original remains.
+  // saved === null: iOS does not report whether the person completed the save.
+  // Both outcomes are deliberately silent.
+}
+```
+
+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
+
+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;
+- removal of the previous local Snackbar/overlay and timer;
+- Snackbar replacement and timer reset;
+- Dialog and Bottom Sheet FIFO ordering;
+- exactly-once callbacks under double taps and competing close paths;
+- Android Back and backdrop policy;
+- 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.
+
+## Delivery verification
+
+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`;
+4. Alloy compilation for Android and iOS;
+5. native builds for every supported platform;
+6. manual checks in light, dark, and system appearance;
+7. phone and tablet/large-screen checks;
+8. Back, backdrop, cancel, double tap, long list, and long localized text checks;
+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.
+
+## When to share Widgets between apps
+
+Extract or copy a Widget into another app only when:
+
+- its API is stable and contains no business rules;
+- localized strings and callbacks are supplied by the host;
+- 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.
+
+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

@@ -0,0 +1,111 @@
+# 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.
+
+## Contents
+
+- [Decision sequence](#decision-sequence)
+- [Feedback scale](#feedback-scale)
+- [App-owned versus system-owned](#app-owned-versus-system-owned)
+- [What to standardize next](#what-to-standardize-next)
+- [Phone, tablet, and accessibility](#phone-tablet-and-accessibility)
+- [References](#references)
+
+## Decision sequence
+
+Classify the event in this order:
+
+1. **Owner**: does the app own the interaction, or does the operating system?
+2. **Blocking**: can the person continue safely without acknowledging it?
+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?
+
+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
+
+| Situation | Preferred surface | Why |
+| --- | --- | --- |
+| Ordinary success or confirmation | Snackbar | Visible without interrupting the task |
+| Undoable action | Snackbar with one Undo action | Keeps recovery close to the event |
+| Non-blocking warning | Warning Snackbar | Calls attention without forcing acknowledgement |
+| Invalid value in one field | Inline validation next to that field | Preserves context and identifies the fix |
+| Form-wide recoverable validation | Inline summary; Snackbar only if no single field owns it | Avoids a modal loop |
+| Persistent connectivity, sync, or account state | Banner or inline notice | Remains visible while the condition remains true |
+| Blocking error or required acknowledgement | Dialog | The task cannot continue safely |
+| Uncommon irreversible action | Destructive confirmation Dialog | Provides a safe escape before data loss |
+| Several actions related to the current context | Bottom Sheet | Presents a compact choice without pretending it is an error |
+| Long, searchable, or multi-select options | Bottom Sheet, sheet, or dedicated screen with `ListView` | A dialog is too constrained |
+| Multi-step task or complex form | Sheet or dedicated screen | The interaction has its own workflow |
+| 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.
+
+### 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.
+
+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
+
+- Use Snackbar when the event has happened and the message can disappear.
+- Use Banner or inline notice while an ongoing condition remains relevant.
+- Never keep a Snackbar indefinitely to simulate persistent screen state.
+
+### Bottom Sheet versus Dialog
+
+- 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.
+
+## 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.
+
+| Keep native/system-owned | May be app-owned and styled |
+| --- | --- |
+| Permission prompts | Success, warning, and error feedback |
+| File and document pickers | Destructive confirmations |
+| Share sheets and activity views | Contextual action lists |
+| Date/time pickers when the platform interaction is desired | Category and app-data selectors |
+| Camera and media authorization UI | Loading, empty, and error states |
+| 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.
+
+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.
+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.
+
+## 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.
+
+## References
+
+- [Titanium Alloy Widgets](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Widgets.html)
+- [Apple Human Interface Guidelines: Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+- [Apple Human Interface Guidelines: Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+- [Material Design 3: Snackbar](https://m3.material.io/components/snackbar/overview)
+- [Material Design 3: Dialogs](https://m3.material.io/components/dialogs/overview)
+- [Material Design 3: Bottom sheets](https://m3.material.io/components/bottom-sheets/overview)
+