wow-backup/docs/plans/feature-2-configuration.md

Feature 2: Configuration Screen

Context

The configuration screen is the primary setup interface. It appears automatically on first run (when config is incomplete) and is accessible anytime via the tray menu. All backup behavior depends on the values set here.

Dependencies

• Depends on: Feature 0 (ConfigManager, AppConfig), Feature 1 (screen routing, tray menu)
• Depended on by: Feature 3 (Backup — uses all config values), Feature 4 (Status — shows config warnings)

Layout

Single scrollable form with section headers. All options visible on one page.

File Dialogs

Native OS dialogs via java.awt.FileDialog (preferred on macOS) or javax.swing.JFileChooser (Windows fallback). Folder-selection mode.

Implementation Steps

Step 1: Native file/folder picker utility

Files to create:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/ui/components/NativeFolderPicker.kt

A utility function that opens a native folder-selection dialog and returns File?:

• macOS: Use java.awt.FileDialog with System.setProperty("apple.awt.fileDialogForDirectories", "true") to enable folder mode
• Windows/Linux: Use JFileChooser with DIRECTORIES_ONLY mode
• Runs on the AWT event thread to avoid threading issues

Step 2: Create the ConfigViewModel

Files to create:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/ui/config/ConfigViewModel.kt

Responsibilities:

• Holds a mutable copy of AppConfig as UI state
• Validates inputs (e.g., paths exist, time is valid)
• save() — writes to ConfigManager
• detectWoWLocation() — calls WoWLocations.findWoWInstall() and pre-fills if found
• Exposes validation errors per field

Step 3: Build the ConfigScreen composable

Files to create:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/ui/config/ConfigScreen.kt

Single scrollable Column with these sections:

Section: WoW Installation

• WoW install location: Text field (read-only) + "Browse" button (opens native folder picker)
• "Auto-detect" button that scans default locations
• Validation: show error if path doesn't exist or doesn't look like a WoW install

Section: Backup Settings

• Backup destination: Text field (read-only) + "Browse" button
• Backup schedule: Time picker for daily backup time (hour:minute)
• Backup history: Dropdown/spinner for how many backups to keep (1-30, default 5)
• Force backup: Checkbox "Allow backup while WoW is running"
  • When toggled ON, show a confirmation dialog warning that backing up while WoW runs may capture inconsistent state

Section: Folders to Backup

• WTF folder: Checkbox (default on) + description text: "Contains account settings, keybinds, macros, and addon saved variables."
• Interface folder: Checkbox (default on) + description text: "Contains installed addons and their configuration."

Section: Options

• Compression: Checkbox + description text: "Compress backups to save disk space. Slightly slower backup/restore."
• Notifications: Checkbox "Show system notifications for backup events."
• Run at startup: Checkbox "Launch WoW Backup automatically when you log in."

Footer

• Save button (primary) — validates, saves config, shows success feedback
• Cancel button — reverts changes, closes window (or navigates to status if first-time setup is incomplete, stays on config)

Step 4: Time picker component

Files to create:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/ui/components/TimePicker.kt

Simple hour:minute selector. Two dropdowns (0-23 hours, 0-59 minutes in 15-min increments) or a pair of number fields. Keep it minimal.

Step 5: Confirmation dialog for "Force backup"

Files to create:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/ui/components/ConfirmationDialog.kt

Reusable Material3 AlertDialog component. Used here for the force-backup warning, and later by the Restore feature (Feature 5).

Step 6: Wire into App.kt routing

Files to modify:

• composeApp/src/jvmMain/kotlin/com/rukira/wowbackup/App.kt

Replace config placeholder with ConfigScreen(viewModel, onNavigateToStatus).

Step 7: Run-at-startup implementation (deferred)

This is platform-specific and non-trivial:

• macOS: LaunchAgent plist in ~/Library/LaunchAgents/
• Windows: Registry key or Start Menu shortcut in Startup folder

This will be implemented as a sub-task within this feature, but the checkbox should be present and functional. The actual OS integration can be a follow-up if it proves complex.

Validation Rules

• WoW path: must exist, must contain WTF/ or Interface/ or a WoW executable
• Backup path: must exist and be writable
• At least one folder (WTF or Interface) must be selected
• Backup history count: 1-30

Verification

1. Config screen renders with all sections
2. "Browse" buttons open native OS folder picker
3. "Auto-detect" finds WoW if installed in default location
4. Toggling "Force backup" shows confirmation dialog
5. "Save" persists to config.json, "Cancel" reverts
6. Validation errors display inline for invalid paths
7. On first run, config screen opens automatically
8. After saving valid config, navigates to status screen