Wino-Mail/.github/copilot-instructions.md

Copilot Instructions for Wino-Mail Project

ViewModels Development Guidelines

Observable Properties

• ALWAYS use public partial observable properties in ViewModels
• NEVER use private fields with [ObservableProperty] attribute
• Correct Pattern:

  [ObservableProperty]
  public partial string SearchQuery { get; set; } = string.Empty;
  

• Incorrect Pattern:

  [ObservableProperty]
  private string searchQuery = string.Empty;
  

ViewModels Structure

• All ViewModels should inherit from appropriate base classes (MailBaseViewModel, CoreBaseViewModel, etc.)
• Use [RelayCommand] for command methods
• Follow the existing dependency injection patterns
• Use IMailDialogService for Mail-related dialogs, IDialogServiceBase for core dialogs

Strings and Localization

• All strings should be added in English to en-US.json file and used via Translator class.
• Avoid hardcoding strings in the codebase.
• Use Translator.{TranslationKey} with property to retrieve string in view models.
• Use Translator as well in the XAML files with x:Bind. Always use OneTime mode.

Dialog Services

• Use InfoBarMessage() method for simple notifications
• Use ShowConfirmationDialogAsync() for confirmation dialogs
• Use PickFilesAsync() for file selection
• Always check for null/empty results from dialog operations

File Structure

• Place ViewModels in appropriate projects (Wino.Mail.ViewModels, Wino.Core.ViewModels, etc.)
• Create abstract page classes in Views/Abstract folders
• Follow the existing naming conventions
• NEVER edit files in the old Wino.Mail project folder - it's UWP and deprecated
• ALWAYS work with WinUI projects (Wino.Mail.WinUI, Wino.Core.WinUI) for UI components

Error Handling

• Always wrap async operations in try-catch blocks
• Use InfoBar messages for user-friendly error notifications
• Log errors appropriately but don't expose technical details to users

Collection Management

• Use ObservableCollection for UI-bound collections
• Implement proper filtering and search functionality
• Use virtualization for large datasets (ListView, ItemsView)

Contact Management Specific

• Respect IsRootContact property - root contacts cannot be deleted
• Check IsOverridden property during synchronization
• Always validate contact data before operations
• Use PersonPicture controls for contact avatars
• Support multiple selection where appropriate

UI Data Binding and Converters

• NEVER create IValueConverter classes or add them to Converters.xaml
• NEVER use BoolToVisibilityConverter - boolean values are automatically converted to Visibility by the WinUI 3 SDK
• ALWAYS use XamlHelpers static methods for data transformations when needed
• Use XamlHelpers methods with x:Bind syntax: {x:Bind helpers:XamlHelpers.ReverseBoolToVisibilityConverter(PropertyName), Mode=OneWay}
• Available XamlHelpers methods include: ReverseBoolToVisibilityConverter, CountToBooleanConverter, BoolToSelectionMode, Base64ToBitmapImage, etc.
• If a helper method doesn't exist, add it to XamlHelpers.cs instead of creating a converter
• For boolean to Visibility binding, use direct binding: Visibility="{x:Bind BooleanProperty, Mode=OneWay}"

Code Style

• Use var where type is obvious
• Use string interpolation over string.Format where simple
• Keep methods focused and single-responsibility
• Use meaningful variable names
• Add XML documentation for public APIs