@maccesar/titools 2.0.0

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

@@ -0,0 +1,469 @@
+# PurgeTSS & Code Conventions
+
+## Module System: CommonJS (NOT ES6 modules)
+
+Titanium uses **CommonJS** for modules. Do NOT use ES6 `import`/`export`:
+
+```javascript
+// CORRECT - CommonJS
+const { Navigation } = require('lib/services/navigation')
+exports.Navigation = { /* ... */ }
+
+// WRONG - ES6 modules (won't work in Titanium)
+import { Navigation } from 'lib/services/navigation'
+export const Navigation = { /* ... */ }
+```
+
+## ES6+ Features (Non-Module)
+
+Use `const`, `let`, destructuring, and template literals. Prefer arrow functions for callbacks and traditional functions for main logic.
+
+```javascript
+const loadUserData = (userId) => {
+  const user = fetchUser(userId)
+  return { ...user, loadedAt: Date.now() }
+}
+```
+
+## No Semicolons
+Omit semicolons at the end of lines (ASI handles it).
+
+```javascript
+const users = fetchUsers()
+const name = user.name
+```
+
+## Styling with PurgeTSS (Utility-First)
+Use utility classes for layout, colors, typography, and spacing. Avoid manual TSS files.
+
+```xml
+<!-- GOOD: PurgeTSS Utility Classes -->
+<View class="vertical h-auto w-screen bg-gray-100">
+  <Label class="m-4 text-xl font-bold text-blue-600" text="L('welcome')" />
+</View>
+```
+
+**Critical PurgeTSS Rules:**
+- NO `flex-row`/`flex-col` → Use `horizontal`/`vertical`
+- NO `w-full` → Use `w-screen`
+- NO `p-*` on Views → Use `m-*` on children
+- NO `justify-*`/`items-center` → Use margins/positioning
+
+## Platform & Device Modifiers
+Leverage PurgeTSS modifiers instead of writing conditional logic in controllers.
+
+```xml
+<View class="ios:mt-10 tablet:mt-20 mt-5" />
+```
+
+## applyProperties() Pattern
+Use `applyProperties()` to batch UI updates and minimize bridge crossings for properties not managed by classes.
+
+```javascript
+$.nameLabel.applyProperties({
+  text: user.name,
+  opacity: 1
+})
+```
+
+## ListView Templates
+Always use templates for performance. Never create views dynamically inside list rows.
+
+```javascript
+function renderUsers(users) {
+  const data = users.map(user => ({
+    name: { text: user.name },
+    template: 'userTemplate'
+  }))
+  $.section.items = data
+}
+```
+
+## Memory Cleanup
+Always remove listeners to avoid memory leaks. Implement a `cleanup` function.
+
+```javascript
+function cleanup() {
+  $.destroy()
+  // Remove Ti.App listeners here
+}
+```
+
+## i18n and Accessibility (a11y)
+Use `L()` for all text and always include `accessibilityLabel` for interactive elements.
+
+```xml
+<Label text="L('welcome_message')" accessibilityLabel="Welcome Header" />
+<ImageView class="fa-solid fa-user" accessibilityLabel="User Profile Picture" />
+```
+
+## Icon Fonts (PurgeTSS Workflow)
+Integrate icons using classes generated by `purgetss build-fonts`. Classes are mapped to both `text` and `title` properties.
+
+```xml
+<Label class="fa-solid fa-envelope mr-2 text-gray-400" />
+<Button class="fas fa-play" title="L('play')" />
+```
+
+## Grid System
+Use PurgeTSS percentage-based grid for alignments.
+
+```xml
+<View class="horizontal w-screen">
+  <View class="w-8/12 bg-red-500" />
+  <View class="w-4/12 bg-blue-500" />
+</View>
+```
+
+For true grid layouts, use the Grid component:
+```xml
+<View class="grid-cols-3 gap-2">
+  <View class="bg-red-500" />
+  <View class="bg-blue-500" />
+  <View class="bg-green-500" />
+</View>
+```
+
+## Animation Component
+PurgeTSS includes an Animation component (`purgetss.ui`) for 2D Matrix transformations.
+
+```xml
+<Animation id="myAnim" module="purgetss.ui" class="close:opacity-0 duration-500 open:opacity-100" />
+```
+
+## Naming Conventions
+
+### Files and Folders
+```
+app/
+├── controllers/
+│   ├── index.js              # camelCase for files
+│   ├── user/                 # lowercase folders
+│   │   ├── profile.js        # feature-based grouping
+│   │   └── settings.js
+├── lib/
+│   ├── api/
+│   │   └── userApi.js        # suffixed with type (Api, Service)
+│   ├── services/
+│   │   └── authService.js
+│   └── helpers/
+│       └── dateHelper.js
+├── views/
+│   └── user/
+│       └── profile.xml       # match controller path exactly
+```
+
+### Variables and Functions
+```javascript
+// Constants: UPPER_SNAKE_CASE
+const API_BASE_URL = 'https://api.example.com'
+const MAX_RETRY_COUNT = 3
+const DEFAULT_TIMEOUT = 5000
+
+// Variables: camelCase
+const userId = $.args.userId
+const isLoading = false
+let currentPage = 1
+
+// Functions: camelCase, verb prefix for actions
+function loadUserData() { /* ... */ }
+function handleLoginClick() { /* ... */ }
+function validateEmail(email) { /* ... */ }
+
+// Boolean variables: is/has/should prefix
+const isAuthenticated = true
+const hasPermission = false
+const shouldRefresh = true
+
+// Event handlers: on + Event
+function onItemClick(e) { /* ... */ }
+function onRefresh() { /* ... */ }
+function onSearchChange(e) { /* ... */ }
+
+// Private functions: underscore prefix (optional)
+function _calculateTotal(items) { /* ... */ }
+```
+
+### Classes and Services
+```javascript
+// Classes: PascalCase
+class UserService {
+  constructor() { /* ... */ }
+}
+
+// Singleton exports: camelCase instance
+exports.userService = new UserService()
+
+// Factory functions: create prefix
+function createHTTPClient(config) { /* ... */ }
+function createAnimationController() { /* ... */ }
+```
+
+### Events and Constants
+```javascript
+// Event names: namespace:action format
+const Events = {
+  USER_LOGGED_IN: 'user:loggedIn',
+  USER_LOGGED_OUT: 'user:loggedOut',
+  CART_UPDATED: 'cart:updated',
+  NETWORK_ONLINE: 'network:online'
+}
+
+// Error codes: UPPER_SNAKE_CASE
+const ErrorCodes = {
+  AUTH_ERROR: 'AUTH_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  VALIDATION_ERROR: 'VALIDATION_ERROR'
+}
+```
+
+## Import/Export Patterns
+
+### Named Exports (Preferred)
+```javascript
+// lib/api/userApi.js
+exports.getUser = async function(id) { /* ... */ }
+exports.updateUser = async function(id, data) { /* ... */ }
+exports.deleteUser = async function(id) { /* ... */ }
+
+// Usage
+const { getUser, updateUser } = require('lib/api/userApi')
+```
+
+### Default Export (For Classes/Singletons)
+```javascript
+// lib/services/logger.js
+class Logger {
+  debug(tag, message) { /* ... */ }
+  info(tag, message) { /* ... */ }
+  error(tag, message) { /* ... */ }
+}
+
+module.exports = new Logger()
+
+// Usage
+const logger = require('lib/services/logger')
+```
+
+### Mixed Exports
+```javascript
+// lib/services/eventBus.js
+const _ = require('alloy/underscore')._
+const Backbone = require('alloy/backbone')
+
+const EventBus = _.clone(Backbone.Events)
+
+// Named export for event constants
+exports.Events = {
+  USER_UPDATED: 'user:updated',
+  SYNC_COMPLETE: 'sync:complete'
+}
+
+// Default export for the bus itself
+module.exports = EventBus
+
+// Usage
+const EventBus = require('lib/services/eventBus')
+const { Events } = EventBus
+```
+
+### Re-exports (Barrel Files)
+```javascript
+// lib/api/index.js - Barrel file
+exports.userApi = require('./userApi').userApi
+exports.productApi = require('./productApi').productApi
+exports.orderApi = require('./orderApi').orderApi
+
+// Usage - cleaner imports
+const { userApi, productApi } = require('lib/api')
+```
+
+### CommonJS Compatibility
+```javascript
+// When using native modules that use require()
+const SomeNativeModule = require('ti.somemodule')
+
+// Wrap in ES6 service
+exports.nativeService = {
+  doSomething() {
+    return SomeNativeModule.performAction()
+  }
+}
+```
+
+## Async/Promise Patterns
+
+### Async/Await (Preferred)
+```javascript
+// Service layer - always async
+exports.fetchUserProfile = async function(userId) {
+  const user = await userApi.getById(userId)
+  const preferences = await preferencesApi.getByUser(userId)
+
+  return {
+    ...user,
+    preferences
+  }
+}
+
+// Controller - with error handling
+async function loadData() {
+  setLoading(true)
+
+  try {
+    const data = await service.fetchData()
+    renderData(data)
+  } catch (error) {
+    handleError(error)
+  } finally {
+    setLoading(false)
+  }
+}
+```
+
+### Parallel Requests
+```javascript
+// When requests are independent - run in parallel
+async function loadDashboard() {
+  const [user, stats, notifications] = await Promise.all([
+    userService.getCurrentUser(),
+    statsService.getDashboardStats(),
+    notificationService.getUnread()
+  ])
+
+  renderDashboard({ user, stats, notifications })
+}
+```
+
+### Sequential with Dependencies
+```javascript
+// When each request depends on the previous
+async function processOrder(cartId) {
+  // 1. Get cart (needed for order)
+  const cart = await cartService.getById(cartId)
+
+  // 2. Create order (needs cart data)
+  const order = await orderService.create(cart)
+
+  // 3. Process payment (needs order)
+  const payment = await paymentService.process(order.id)
+
+  return { order, payment }
+}
+```
+
+### Error Handling with Specific Catches
+```javascript
+async function login(email, password) {
+  try {
+    const result = await authService.login(email, password)
+    return result
+
+  } catch (error) {
+    // Handle specific error types differently
+    if (error.code === 'AUTH_ERROR') {
+      showMessage(L('invalid_credentials'))
+    } else if (error.code === 'NETWORK_ERROR') {
+      showMessage(L('check_connection'))
+    } else {
+      showMessage(L('unknown_error'))
+      logger.error('Login', 'Unexpected error', { error: error.message })
+    }
+
+    throw error // Re-throw for caller to handle if needed
+  }
+}
+```
+
+### Converting Callbacks to Promises
+```javascript
+// Wrap Ti.Network.createHTTPClient in Promise
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    const client = Ti.Network.createHTTPClient({
+      onload: function() {
+        try {
+          resolve(JSON.parse(this.responseText))
+        } catch (e) {
+          reject(new Error('Invalid JSON response'))
+        }
+      },
+      onerror: function(e) {
+        reject(new Error(e.error || 'Request failed'))
+      },
+      timeout: 10000
+    })
+
+    client.open('GET', url)
+    client.send()
+  })
+}
+
+// Wrap Ti.Media.showCamera in Promise
+function takePhoto() {
+  return new Promise((resolve, reject) => {
+    Ti.Media.showCamera({
+      success: (e) => resolve(e.media),
+      cancel: () => reject(new Error('User cancelled')),
+      error: (e) => reject(new Error(e.error))
+    })
+  })
+}
+```
+
+### Debouncing Async Operations
+```javascript
+// Useful for search, auto-save, etc.
+let searchTimeout = null
+
+function onSearchChange(e) {
+  clearTimeout(searchTimeout)
+
+  searchTimeout = setTimeout(async () => {
+    const query = e.value.trim()
+
+    if (query.length < 2) {
+      return renderResults([])
+    }
+
+    try {
+      const results = await searchService.search(query)
+      renderResults(results)
+    } catch (error) {
+      // Ignore errors for outdated searches
+      logger.debug('Search', 'Search failed', { query })
+    }
+  }, 300)
+}
+
+function cleanup() {
+  clearTimeout(searchTimeout)
+  $.destroy()
+}
+```
+
+### Retry Pattern
+```javascript
+async function fetchWithRetry(fn, maxRetries = 3) {
+  let lastError
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+
+      // Exponential backoff
+      const delay = Math.pow(2, i) * 1000
+      await new Promise(resolve => setTimeout(resolve, delay))
+
+      logger.warn('Retry', `Attempt ${i + 1} failed`, { error: error.message })
+    }
+  }
+
+  throw lastError
+}
+
+// Usage
+const data = await fetchWithRetry(() => api.getData())
+```