docs: document recommended state/controller registration pattern for consumer apps#18
Merged
anilcancakir merged 2 commits intomainfrom Apr 4, 2026
Merged
Conversation
…consumer apps Add architecture reference (doc/architecture/controllers.md) covering the lazy singleton pattern, MagicController + MagicStateMixin usage, controller lifecycle, view binding, and a decision tree for eager vs lazy vs per-view registration. Add practical getting-started guide (doc/guides/state-management.md) with end-to-end examples. Update scaffolded app_service_provider.stub with state registration guidance comments. Add cross-references in service-provider.md. Closes #17
There was a problem hiding this comment.
Pull request overview
Adds new documentation to standardize how consumer apps should register and use Magic Framework controllers/state in apps built on top of Magic Starter, plus small cross-references and stub guidance to reduce inconsistent patterns across projects.
Changes:
- Added architecture + guide docs covering the recommended lazy singleton controller pattern (
Magic.findOrPut), view binding patterns, and testing. - Updated installation stub (
app_service_provider.stub) with guidance on when to register state eagerly inboot(). - Added cross-links in existing docs and surfaced the new docs in README + CHANGELOG.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds new documentation links for controller/state registration and state management guidance |
| doc/guides/state-management.md | New end-to-end guide with patterns + example controller/view/test snippets |
| doc/architecture/service-provider.md | Adds a TIP + related link to the new controller/state registration doc |
| doc/architecture/controllers.md | New architecture reference describing controller patterns, lifecycle, view binding, and testing |
| CHANGELOG.md | Notes the newly added documentation and stub guidance under Unreleased |
| assets/stubs/install/app_service_provider.stub | Adds scaffold comments explaining recommended state registration strategy |
- controllers.md: clarify MagicStateMixin<bool> is most common, not universal (Newsletter/OTP use untyped); qualify NavigatesRoutes usage; note NotificationsListView as MagicStatefulView exception; fix views-and-layouts Related URL (architecture → basics) - state-management.md: fix "five-state" → "four-state"; fix _isSubmitting → _isLoading consistency; fix flutter/widgets.dart → flutter/material.dart for Icons.* usage; rename Pattern B section to "Manual Access" matching actual content - README.md: use hosted doc URLs instead of repo-relative paths - stub: replace local doc path with generic package docs reference
4 tasks
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
doc/architecture/controllers.md— architecture reference covering lazy singleton pattern (Magic.findOrPut),MagicController+MagicStateMixinusage, controller lifecycle, view binding, and consumer app registration decision treedoc/guides/state-management.md— practical getting-started guide with end-to-end examples (state class + view + test) for consumer app developersassets/stubs/install/app_service_provider.stubwith state registration guidance commentsdoc/architecture/service-provider.md(TIP callout + Related link)Closes #17
Test plan
doc/architecture/controllers.mdrenders correctly and TOC anchors link to sectionsdoc/guides/state-management.mdcode examples are complete and match actual APIapp_service_provider.stubcomment indentation matches surrounding code (8 spaces)service-provider.mdresolve correctlyflutter analyze --no-fatal-infos— no new warnings from stub change