oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-mobile/resources/screen-template.dart

@@ -0,0 +1,331 @@
+/**
+ * Screen Template for Mobile Agent (Flutter)
+ *
+ * Demonstrates the stack's canonical screen patterns:
+ *   - A `@riverpod` codegen notifier (StreamNotifier) consuming a repository
+ *     interface — never a hand-written global FutureProvider with an inline API call.
+ *   - GoRouter typed-route navigation (`GoRouteData` subclass `.push(context)`),
+ *     never Navigator 1.0 named routes (`pushNamed` / `static routeName`).
+ *   - AsyncValue.when → loading / data / empty / error(retry) states.
+ *   - Controller lifecycle (create in field/initState, dispose in dispose()).
+ *   - Dark-mode-safe colors via `Theme.of(context).colorScheme` and
+ *     `withValues(alpha:)` (NOT the deprecated `withOpacity`).
+ *
+ * This is a reference: the notifier, repository, and routes normally live in
+ * separate files (see variants/flutter/snippets.md §2/§3/§4/§6). Shown together
+ * here for readability; the `part` directive pulls in build_runner output.
+ */
+
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'example_screen.g.dart';
+
+// ---------------------------------------------------------------------------
+// DOMAIN — entity + repository interface (normally under features/example/domain/)
+// ---------------------------------------------------------------------------
+
+/// Minimal domain entity. In a real feature use freezed (see snippets §3a).
+class Example {
+  const Example({required this.id, required this.title, this.description});
+  final int id;
+  final String title;
+  final String? description;
+}
+
+/// The presentation layer depends on this interface, never on a concrete impl.
+/// Swap the offline-first impl, a stub, or a mock behind this seam.
+abstract interface class ExampleRepository {
+  /// Emits warm cached data immediately; cold loads await network and surface errors.
+  Stream<List<Example>> watchAll();
+  /// Force a network refresh, bypass TTL, and propagate failures.
+  Future<void> refresh();
+}
+
+/// DI seam. Override this in `ProviderScope(overrides: [...])` (or a codegen
+/// provider that returns the real `ExampleRepositoryImpl`) at app startup.
+@riverpod
+ExampleRepository exampleRepository(Ref ref) =>
+    throw UnimplementedError('Override exampleRepositoryProvider with a real impl.');
+
+// ---------------------------------------------------------------------------
+// STATE — @riverpod StreamNotifier consuming the repository (features/example/presentation/)
+// ---------------------------------------------------------------------------
+
+/// Exposes the example list as `AsyncValue<List<Example>>`.
+///
+/// Riverpod converts the repository's `Stream` into an `AsyncValue`: loading on
+/// first subscription, data(cachedList) on the first emission, then data(freshList)
+/// after revalidation — no loading flicker when the cache is warm.
+@riverpod
+class ExamplesNotifier extends _$ExamplesNotifier {
+  @override
+  Stream<List<Example>> build() {
+    final repo = ref.watch(exampleRepositoryProvider);
+    return repo.watchAll();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// NAVIGATION — typed routes (features/example/... registered on the app router)
+// ---------------------------------------------------------------------------
+
+/// Typed detail route. `go_router_builder` generates the `.push()` / `.go()`
+/// helpers from `@TypedGoRoute`; the annotation and `GoRouteData` come from
+/// `package:go_router/go_router.dart`. Navigate with:
+///   `const ExampleDetailRoute(id: 42).push(context);`
+@TypedGoRoute<ExampleDetailRoute>(path: '/examples/:id')
+class ExampleDetailRoute extends GoRouteData with $ExampleDetailRoute {
+  const ExampleDetailRoute({required this.id});
+  final int id;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      // Replace with the real detail screen.
+      Scaffold(appBar: AppBar(title: Text('Example $id')));
+}
+
+// ---------------------------------------------------------------------------
+// SCREEN
+// ---------------------------------------------------------------------------
+
+/// Example screen demonstrating common patterns.
+class ExampleScreen extends ConsumerStatefulWidget {
+  const ExampleScreen({super.key});
+
+  @override
+  ConsumerState<ExampleScreen> createState() => _ExampleScreenState();
+}
+
+class _ExampleScreenState extends ConsumerState<ExampleScreen> {
+  // Local UI state and controllers.
+  final _scrollController = ScrollController();
+  bool _showScrollToTop = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _setupScrollListener();
+  }
+
+  @override
+  void dispose() {
+    _scrollController.dispose(); // always dispose controllers
+    super.dispose();
+  }
+
+  void _setupScrollListener() {
+    _scrollController.addListener(() {
+      final shouldShow = _scrollController.offset > 200;
+      if (shouldShow != _showScrollToTop) {
+        setState(() => _showScrollToTop = shouldShow);
+      }
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // Watch the notifier — rebuilds on every AsyncValue transition.
+    final examplesAsync = ref.watch(examplesNotifierProvider);
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Example Screen'),
+        actions: [
+          IconButton(
+            icon: const Icon(Icons.refresh),
+            onPressed: () async {
+              try {
+                await ref.read(exampleRepositoryProvider).refresh();
+              } catch (error) {
+                if (!context.mounted) return;
+                ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Refresh failed: $error')));
+              }
+            },
+            tooltip: 'Refresh',
+          ),
+          IconButton(
+            icon: const Icon(Icons.settings),
+            // GoRouter imperative push; prefer a typed route when the
+            // destination is in the typed route graph.
+            onPressed: () => context.push('/settings'),
+            tooltip: 'Settings',
+          ),
+        ],
+      ),
+      body: examplesAsync.when(
+        // Warm cache renders immediately; a background revalidation does not
+        // re-show the spinner (skipLoadingOnRefresh is on by default).
+        data: (items) =>
+            items.isEmpty ? _buildEmptyState() : _buildContent(items),
+        loading: () => const Center(child: CircularProgressIndicator()),
+        error: (error, _) => _buildErrorState(error),
+      ),
+      floatingActionButton: _showScrollToTop
+          ? FloatingActionButton(
+              onPressed: _scrollToTop,
+              tooltip: 'Scroll to top',
+              child: const Icon(Icons.arrow_upward),
+            )
+          : null,
+    );
+  }
+
+  /// Builds main content.
+  Widget _buildContent(List<Example> items) {
+    return RefreshIndicator(
+      onRefresh: () async {
+        try {
+          await ref.read(exampleRepositoryProvider).refresh();
+        } catch (error) {
+          if (!context.mounted) return;
+          ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Refresh failed: $error')));
+        }
+      },
+      child: CustomScrollView(
+        controller: _scrollController,
+        slivers: [
+          SliverToBoxAdapter(
+            child: Padding(
+              padding: const EdgeInsets.all(16),
+              child: Text(
+                '${items.length} Items',
+                style: Theme.of(context).textTheme.titleMedium,
+              ),
+            ),
+          ),
+          SliverList(
+            delegate: SliverChildBuilderDelegate(
+              (context, index) => _buildListItem(items[index], index),
+              childCount: items.length,
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  /// Builds an individual list item.
+  Widget _buildListItem(Example item, int index) {
+    return Card(
+      margin: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+      child: ListTile(
+        leading: CircleAvatar(child: Text('${index + 1}')),
+        title: Text(item.title),
+        subtitle: item.description != null ? Text(item.description!) : null,
+        trailing: const Icon(Icons.chevron_right),
+        // Typed-route navigation — no Navigator.pushNamed.
+        onTap: () => ExampleDetailRoute(id: item.id).push(context),
+      ),
+    );
+  }
+
+  /// Builds the empty state.
+  Widget _buildEmptyState() {
+    final theme = Theme.of(context);
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: [
+          Icon(Icons.inbox, size: 64, color: theme.colorScheme.secondary),
+          const SizedBox(height: 16),
+          Text('No items yet', style: theme.textTheme.titleLarge),
+          const SizedBox(height: 8),
+          Text(
+            'Add your first item to get started',
+            style: theme.textTheme.bodyMedium?.copyWith(
+              color: theme.colorScheme.onSurface.withValues(alpha: 0.6),
+            ),
+          ),
+          const SizedBox(height: 24),
+          FilledButton.icon(
+            onPressed: _showAddDialog,
+            icon: const Icon(Icons.add),
+            label: const Text('Add Item'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  /// Builds the error state with a retry affordance.
+  Widget _buildErrorState(Object error) {
+    final theme = Theme.of(context);
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            Icon(Icons.error_outline, size: 64, color: theme.colorScheme.error),
+            const SizedBox(height: 16),
+            Text(
+              'Oops! Something went wrong',
+              style: theme.textTheme.titleLarge,
+              textAlign: TextAlign.center,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              error.toString(),
+              style: theme.textTheme.bodyMedium?.copyWith(
+                color: theme.colorScheme.onSurface.withValues(alpha: 0.6),
+              ),
+              textAlign: TextAlign.center,
+            ),
+            const SizedBox(height: 24),
+            FilledButton.icon(
+              onPressed: () => ref.invalidate(examplesNotifierProvider),
+              icon: const Icon(Icons.refresh),
+              label: const Text('Try Again'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  // Event handlers
+
+  void _scrollToTop() {
+    _scrollController.animateTo(
+      0,
+      duration: const Duration(milliseconds: 500),
+      curve: Curves.easeOut,
+    );
+  }
+
+  void _showAddDialog() {
+    // Controller is local to the dialog and disposed when it closes.
+    final controller = TextEditingController();
+    showDialog<void>(
+      context: context,
+      builder: (ctx) => AlertDialog(
+        title: const Text('Add Item'),
+        content: TextField(
+          controller: controller,
+          autofocus: true,
+          decoration: const InputDecoration(
+            labelText: 'Title',
+            hintText: 'Enter title',
+          ),
+          onSubmitted: (_) => Navigator.of(ctx).pop(),
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(ctx).pop(),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () {
+              // In a real screen: await ref.read(examplesNotifierProvider.notifier).create(...)
+              Navigator.of(ctx).pop();
+            },
+            child: const Text('Add'),
+          ),
+        ],
+      ),
+    ).whenComplete(controller.dispose);
+  }
+}

package/skills/oma-mobile/resources/screen-template.swift

@@ -0,0 +1,239 @@
+/**
+ * Screen Template for Mobile Agent (Swift iOS Native)
+ *
+ * Demonstrates best practices for SwiftUI screens:
+ *   - @Observable view model with explicit loading/error/empty/data states
+ *   - .task modifier for async data loading (auto-cancelled on disappear)
+ *   - Retry action wired to the view model
+ *   - NavigationStack integration
+ *   - iOS HIG-aligned layout
+ */
+
+import SwiftUI
+import Observation
+
+// MARK: - View Model
+
+/// All possible display states for the example screen.
+enum ExampleViewState {
+    case idle
+    case loading
+    case loaded([ExampleItem])
+    case empty
+    case error(String)
+}
+
+/// A plain value type representing one row in the list.
+struct ExampleItem: Identifiable {
+    let id: String
+    let title: String
+    let subtitle: String
+}
+
+/// Protocol-backed so the view model is testable with a mock service.
+/// A real conformer is a Repository over the generated `swift-openapi-generator`
+/// `Client` fronted by a `ResponseCache` (read-through, stale-while-revalidate) —
+/// see variants/swift-ios/snippets.md §10 and variants/swift-ios/api-template.swift.
+/// Never hand-roll `URLRequest`/`JSONDecoder` for endpoints in the OpenAPI spec.
+protocol ExampleServiceProtocol {
+    func fetchItems() async throws -> [ExampleItem]
+}
+
+@MainActor
+@Observable
+final class ExampleViewModel {
+    // MARK: - State observed by the View
+
+    /// Current display state. The View switches on this value.
+    var viewState: ExampleViewState = .idle
+
+    // MARK: - Private
+
+    private let service: ExampleServiceProtocol
+    /// Retained so a new load or view disappearance can cancel active work.
+    /// Tests await load() directly.
+    private(set) var loadTask: Task<Void, Never>?
+
+    init(service: ExampleServiceProtocol) {
+        self.service = service
+    }
+
+    // MARK: - Intents (called by the View)
+
+    /// Starts (or restarts) data loading. Safe to call multiple times.
+    func load() async {
+        // Cancel any in-flight request before starting a fresh one.
+        loadTask?.cancel()
+        viewState = .loading
+
+        let task = Task { [weak self] in
+            guard let self else { return }
+            do {
+                let items = try await service.fetchItems()
+                guard !Task.isCancelled else { return }
+                viewState = items.isEmpty ? .empty : .loaded(items)
+            } catch is CancellationError {
+                // Ignore — another load is replacing this one.
+            } catch {
+                guard !Task.isCancelled else { return }
+                viewState = .error(error.localizedDescription)
+            }
+        }
+        loadTask = task
+        await withTaskCancellationHandler {
+            await task.value
+        } onCancel: {
+            task.cancel()
+        }
+    }
+
+    /// Convenience retry; identical to load() but named for the error-state button.
+    func retry() async { await load() }
+
+    /// Cancels button/retry loads too; awaited .task forwards caller cancellation.
+    func cancelLoad() { loadTask?.cancel() }
+
+}
+
+// MARK: - View
+
+struct ExampleScreen: View {
+    // The View owns the view model via @State so it is scoped to this screen.
+    @State private var viewModel: ExampleViewModel
+
+    init(service: ExampleServiceProtocol) {
+        // State owns the instance lifetime; Observation tracks accessed properties.
+        _viewModel = State(wrappedValue: ExampleViewModel(service: service))
+    }
+
+    var body: some View {
+        // The router owns the enclosing NavigationStack(path:); a feature view
+        // assumes it is already inside one and never wraps itself in a stack.
+        content
+            .navigationTitle("Example")
+            .toolbar {
+                // .topBarTrailing (iOS 17+) replaces .navigationBarTrailing, which
+                // is formally deprecated at iOS 27.
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button {
+                        Task { await viewModel.load() }
+                    } label: {
+                        Label("Refresh", systemImage: "arrow.clockwise")
+                    }
+                    // Disable the button while a load is in progress.
+                    .disabled({
+                        if case .loading = viewModel.viewState { return true }
+                        return false
+                    }())
+                }
+            }
+            // .task is preferred over .onAppear for async work:
+            // it creates a structured Task that is cancelled when the View disappears.
+            .task { await viewModel.load() }
+            .onDisappear { viewModel.cancelLoad() }
+    }
+
+    // MARK: - Content switch
+
+    /// Switches over the view model's state and renders the appropriate sub-view.
+    @ViewBuilder
+    private var content: some View {
+        switch viewModel.viewState {
+        case .idle, .loading:
+            loadingView
+
+        case .loaded(let items):
+            listView(items)
+
+        case .empty:
+            emptyView
+
+        case .error(let message):
+            errorView(message: message)
+        }
+    }
+
+    // MARK: - State sub-views
+
+    /// Shown while the first load is in progress.
+    private var loadingView: some View {
+        ProgressView("Loading…")
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    /// Shown when data is available.
+    private func listView(_ items: [ExampleItem]) -> some View {
+        List(items) { item in
+            // Value-based navigation: push a route value, not an inline destination.
+            // The route layer registers the destination for `ExampleItem.ID` via
+            // `swipeBackDestination(for:)` on the router's NavigationStack — see
+            // variants/swift-ios/snippets.md §9.
+            NavigationLink(value: item.id) {
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(item.title)
+                        .font(.headline)
+                    Text(item.subtitle)
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                }
+                .padding(.vertical, 4)
+            }
+        }
+        // Pull-to-refresh triggers a fresh load.
+        .refreshable { await viewModel.load() }
+    }
+
+    /// Shown when the API returns an empty collection.
+    private var emptyView: some View {
+        ContentUnavailableView(
+            "Nothing Here",
+            systemImage: "tray",
+            description: Text("There are no items yet. Create one to get started.")
+        )
+    }
+
+    /// Shown when the load fails. Includes a labelled retry button.
+    private func errorView(message: String) -> some View {
+        VStack(spacing: 20) {
+            Image(systemName: "exclamationmark.triangle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.red)
+
+            Text("Something went wrong")
+                .font(.title2)
+                .bold()
+
+            Text(message)
+                .font(.body)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 32)
+
+            Button {
+                Task { await viewModel.retry() }
+            } label: {
+                Label("Try Again", systemImage: "arrow.clockwise")
+                    .padding(.horizontal, 8)
+            }
+            .buttonStyle(.borderedProminent)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .padding()
+    }
+}
+
+// MARK: - Preview
+
+#Preview {
+    // Provide a lightweight stub for canvas previews.
+    struct PreviewService: ExampleServiceProtocol {
+        func fetchItems() async throws -> [ExampleItem] {
+            try? await Task.sleep(nanoseconds: 500_000_000)
+            return [
+                ExampleItem(id: "1", title: "First Item",  subtitle: "Detail about the first item"),
+                ExampleItem(id: "2", title: "Second Item", subtitle: "Detail about the second item"),
+            ]
+        }
+    }
+    return ExampleScreen(service: PreviewService())
+}