feat: setup wizard for new databases (discussion #523)#544
Merged
Conversation
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces a new multi-step Setup Wizard to replace the legacy name-only onboarding for new databases, with a Settings re-entry route (“Setup assistant”). The wizard supports fresh-start configuration (profile, units, appearance, backups/sync) and existing-data acquisition paths (restore backup, cloud sync pull, open existing folder), and shares wizard UI primitives with the import wizard.
Changes:
- Add
setup_wizardfeature (draft state + step computation, step widgets, and apply service) and wire it into routing (/welcome) plus Settings re-entry (/settings/setup-assistant). - Move/introduce shared wizard UI components (
WizardStepDef,WizardStepIndicator) and update import-wizard references/tests to use the shared location. - Add/replace localization keys across locales and update user/developer docs to reflect the new first-run flow.
Reviewed changes
Copilot reviewed 75 out of 78 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| test/features/setup_wizard/presentation/widgets/steps/units_step_test.dart | Widget tests for unit preset + fine-tuning behavior |
| test/features/setup_wizard/presentation/widgets/steps/finish_step_test.dart | Widget test for applying draft and navigating to dashboard |
| test/features/setup_wizard/presentation/widgets/steps/existing_data_steps_test.dart | Widget test for existing-data choice updating draft |
| test/features/setup_wizard/presentation/widgets/steps/backup_sync_step_test.dart | Widget tests for backup toggles and provider-card gating |
| test/features/setup_wizard/presentation/widgets/steps/appearance_step_test.dart | Widget test for theme/map/language draft updates + preview |
| test/features/setup_wizard/presentation/providers/setup_wizard_providers_test.dart | Unit tests for notifier draft mutations and step computation |
| test/features/setup_wizard/presentation/pages/setup_wizard_page_test.dart | Flow tests for first-run and settings-mode wizard navigation |
| test/features/setup_wizard/presentation/pages/first_run_redirect_test.dart | Router redirect test to wizard when no divers exist |
| test/features/setup_wizard/domain/unit_preset_detector_test.dart | Tests for locale→unit preset mapping |
| test/features/setup_wizard/domain/setup_wizard_models_test.dart | Tests for step computation and unit-preset application |
| test/features/setup_wizard/data/setup_apply_service_test.dart | Tests for first-run/settings-mode apply ordering and persistence |
| test/features/import_wizard/presentation/widgets/wizard_step_indicator_test.dart | Update import path to shared wizard indicator |
| test/features/import_wizard/presentation/widgets/review_step_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/presentation/widgets/review_step_pending_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/presentation/widgets/import_summary_step_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/presentation/widgets/import_progress_step_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/presentation/pages/unified_import_wizard_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/domain/services/step_skip_calculator_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/domain/models/wizard_step_def_test.dart | Update import path to shared WizardStepDef |
| test/features/import_wizard/domain/adapters/import_source_adapter_test.dart | Update import path to shared WizardStepDef |
| lib/shared/widgets/wizard/wizard_step_indicator.dart | New shared step indicator widget |
| lib/shared/widgets/wizard/wizard_step_def.dart | New shared step definition model |
| lib/l10n/arb/app_zh.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_pt.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_nl.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_it.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_hu.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_he.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_fr.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_es.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_de.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_ar.arb | Add setup wizard/manage setup assistant strings; remove onboarding welcome keys |
| lib/l10n/arb/app_localizations_zh.dart | Generated localization updates for setup wizard strings |
| lib/l10n/arb/app_localizations_pt.dart | Generated localization updates for setup wizard strings |
| lib/l10n/arb/app_localizations_nl.dart | Generated localization updates for setup wizard strings |
| lib/l10n/arb/app_localizations_en.dart | Generated localization updates for setup wizard strings |
| lib/features/setup_wizard/presentation/widgets/steps/welcome_fork_step.dart | New welcome fork step (fresh vs existing vs skip) |
| lib/features/setup_wizard/presentation/widgets/steps/profile_step.dart | New profile (name) step wiring into draft |
| lib/features/setup_wizard/presentation/widgets/steps/units_step.dart | New units preset + per-unit override step |
| lib/features/setup_wizard/presentation/widgets/steps/appearance_step.dart | New appearance step including live locale preview |
| lib/features/setup_wizard/presentation/widgets/steps/backup_sync_step.dart | New backup schedule + sync provider connect step |
| lib/features/setup_wizard/presentation/widgets/steps/sync_connect_step.dart | Existing-data sync connect + pull flow step |
| lib/features/setup_wizard/presentation/widgets/steps/restore_step.dart | Existing-data restore-from-file flow step |
| lib/features/setup_wizard/presentation/widgets/steps/open_folder_step.dart | Existing-data “open folder / adopt DB” flow step |
| lib/features/setup_wizard/presentation/widgets/steps/existing_choice_step.dart | Existing-data source selection step |
| lib/features/setup_wizard/presentation/widgets/steps/finish_step.dart | Finish/apply step + feature discovery actions |
| lib/features/setup_wizard/presentation/providers/setup_wizard_providers.dart | Draft state + notifier (mode-keyed) + preview locale provider |
| lib/features/setup_wizard/presentation/pages/setup_wizard_page.dart | Wizard shell: PageView navigation + step indicator + bottom bar |
| lib/features/setup_wizard/domain/unit_preset_detector.dart | Locale-based unit preset detector |
| lib/features/setup_wizard/domain/setup_wizard_models.dart | Draft model + step computation |
| lib/features/setup_wizard/data/setup_apply_service.dart | Service to persist the wizard draft (first-run + settings mode) |
| lib/features/settings/presentation/pages/settings_page.dart | Add Settings → Manage tile to launch setup assistant |
| lib/features/onboarding/presentation/pages/welcome_page.dart | Remove legacy onboarding welcome page |
| lib/features/import_wizard/presentation/pages/unified_import_wizard.dart | Update imports to shared wizard widgets |
| lib/features/import_wizard/domain/services/step_skip_calculator.dart | Update import to shared WizardStepDef |
| lib/features/import_wizard/domain/adapters/import_source_adapter.dart | Update import to shared WizardStepDef |
| lib/features/import_wizard/data/adapters/universal_adapter.dart | Update import to shared WizardStepDef |
| lib/features/import_wizard/data/adapters/healthkit_adapter.dart | Update import to shared WizardStepDef |
| lib/features/import_wizard/data/adapters/dive_computer_adapter.dart | Update import to shared WizardStepDef |
| lib/core/router/app_router.dart | Route /welcome → setup wizard; add /settings/setup-assistant |
| lib/app.dart | Add preview-locale override hook for live language preview |
| docs/guide/README.md | Update guide to describe setup wizard as first-run step |
| docs/guide/first-dive.md | Update first-dive guide to match wizard-based onboarding |
| docs/FEATURE_ROADMAP.md | Mark setup wizard as completed |
| docs/developer/navigation.md | Document new routes and updated first-run redirect behavior |
| docs/developer/architecture.md | Update feature directory listing to setup_wizard |
| docs/ARCHITECTURE.md | Update architecture overview to reflect setup_wizard |
Addresses device-testing feedback on the wizard: - S3 sync no longer bounces to the fork. context.push to /settings/cloud-sync/s3-config hit the router's zero-divers onboarding redirect (no diver exists until Finish) and resolved to /welcome. S3 config now opens on the root navigator, bypassing go_router. - Every step past the fork is reversible. The existing-data steps (Bring your data, Restore, Connect cloud sync, Open folder) had no bottom bar and no back affordance; they now show a top back bar. Form-zone steps keep their bottom-bar Back. - Removed the Appearance step from the fresh path (theme/map/language stay in Settings), and the now-orphaned previewLocale hook.
…-backup toggle, PageController resync - Settings re-entry now seeds the draft's backup schedule, cloud-backup flag, and active cloud provider from live state, so pressing Finish without touching the backup step no longer disables an existing schedule. - _applyBackupChoices applies the cloud-copy flag in both directions (previously only ever enabled it, so it could never be turned off). - The cloud-copy toggle now shows whenever a provider is connected (keying on the draft, which settings mode seeds) instead of only when connected in-session; the manage-in-settings link shows in re-entry mode. - SetupWizardPage resyncs the PageController post-frame when the step list shrinks (adopt pivot), preventing a blank/out-of-range PageView frame. - units_step_test pins the UI locale to English so it no longer depends on the de_DE device locale (used only for preset detection) rendering English.
Adds fake-driven widget tests for the previously-untested existing-data steps (open folder, restore, cloud-sync pull) and the wizard shell's existing-data navigation, plus per-unit control, finish error, and connected-provider paths. Injects restore_step's file-picker behind a default-real seam (mirroring storage's chooser param) so the restore result flow is exercisable. Patch coverage on changed lines: ~90.4%.
_startPull could throw (peerSyncFiles lists cloud files; performSync runs a network sync) and crash the wizard or strand it on the spinner. Wrap the flow in try/catch: on failure, return to the connect UI and surface the error via the localized snackbar. (PR review.)
…ssage Two more PR review points: - _startPull now checks SyncState.status after performSync(): a captured sync error (not thrown) previously fell through to the misleading 'No library found' screen; it now returns to the connect UI with the error. - On Apple platforms where iCloud is unsupported (signed out or a build without the entitlement), show a disabled iCloud tile explaining why, using the previously-unused setup_sync_icloudUnavailable string, instead of silently hiding it.
…/stats->/statistics) The finish-screen feature links used /gear and /stats, which don't exist (they 404'd to the Page Not Found screen). Point them at the real routes (/equipment, /statistics). The five feature routes are now a public const (kSetupFinishFeatureRoutes) guarded by a router test asserting each resolves in the app route tree, so a bad link can't ship again.
…ting Once a provider connected, the connected status replaced the provider cards with no way to disconnect, so a user whose pull failed (or who picked the wrong backend) was stuck. First-run mode now shows a 'Change provider' action that clears the in-wizard selection and restores the cards; settings mode keeps its 'Manage in Settings' link.
…zard # Conflicts: # lib/features/import_wizard/data/adapters/universal_adapter.dart
The merge accidentally recorded the submodule at its stale checked-out branch tip (7e8fd9a, pre-Perdix-3) instead of main's pinned commit (150672e). That regressed the descriptor set, failing the native test_descriptor_match_integration 'Perdix 3' assertion. Restore the gitlink to match origin/main. Verified: all 7 C wrapper tests pass locally.
github-project-automation
Bot
moved this from In review
to Done
in Submersion Release Tracker
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the name-only welcome page with a multi-step setup wizard for new databases, per discussion #523. First run now offers a fork: set up a fresh logbook (profile, units, appearance, backups, cloud sync) or bring existing Submersion data (restore a backup file, connect cloud sync and pull the library, or open a folder that already contains a database). The same wizard is re-runnable from Settings -> Manage -> Setup assistant with data-sensitive steps hidden.
Design spec:
docs/superpowers/specs/2026-07-10-setup-wizard-design.mdImplementation plan:
docs/superpowers/plans/2026-07-10-setup-wizard.mdChanges
lib/features/setup_wizard/feature: pure-function step computation (computeSteps), immutable draft +SetupWizardNotifier,SetupApplyService, PageView shell, and step widgets (fork, profile, units, appearance, backup & sync, finish, existing-choice, restore, sync pull, open folder)DiverSettingsrow seeded bycreateDiveris overwritten with the draft BEFOREsetCurrentDiver, so the unawaitedSettingsNotifierreload loads the drafted values instead of clobbering thempreviewLocaleProvider+ 2-lineapp.darthook)backupSettingsProvider(schedule + cloud copy) and mirrorsCloudSyncPage's provider activation contract (iCloud gated by availability, Dropbox by app key, S3 via the existing config page); cross-path pivots for "library found" / "no library found"restoreFromFilePath->RestoreCompletePage->restartApp()), sync pull (performSync+ active-diver realignment), and storage adoption (switchToExistingDatabase+ restart)WizardStepDef/WizardStepIndicatormoved tolib/shared/widgets/wizard/(shared with the import wizard; its shell untouched)/welcomerenders the wizard; new/settings/setup-assistantroute + Manage-section tile;WelcomePageand theonboarding_welcome_*l10n keys removedsetup_*l10n keys translated in all 11 localesTest Plan
flutter testpasses (targeted suites: setup_wizard 27, import_wizard 627, core/router 35, settings 36, divers 100, backup 230 - 1055 total)flutter analyzepasses (whole project, no issues)