widget-composition

Widget Composition

Build every screen from many small, const, single-purpose widget classes. A widget that does one thing rebuilds cheaply, reads clearly, tests in isolation, and can be lifted into a shared component library. The View is dumb: it watches one ViewModel and renders; logic lives in the Notifier, state in immutable value objects, layout in directional structural primitives. Applies to any screen, list, card, or shared component.

Read the reference for the task at hand:

• references/rebuild-mechanics.md — why a class beats a method (Element.updateChild), const canonicalization, the full key policy, and .select for narrowed rebuilds.
• references/structural-layout.md — edge-to-edge background vs SafeArea content, computed cell sizing, the GridView cross/main-axis trap, directional insets, and IME/resizeToAvoidBottomInset.
• references/widget-and-data-selection.md — cheapest-widget table, data-class decision table (drift row vs record vs hand-written vs freezed), and gesture→fallback rules.

Run scripts/check-widget-composition.sh before a PR.

Non-negotiable rules

1. Extract a Widget class, never a Widget-returning method. Widget _buildHeader() is not a widget — its subtree has no Element of its own, so Element.updateChild never gets to compare old vs. new and short-circuit; it rebuilds with the parent, cannot be const, cannot take a Key, and find.byType cannot reach it in a test.
2. const everywhere it is legal, every field final. const constructors canonicalize identical widgets to the same object, letting Flutter prune the subtree rebuild. Turn on prefer_const_constructors + prefer_const_constructors_in_immutables. Budget zero minutes hand-tuning const — let dart fix --apply write it; never restructure a tree to make something const-able.
3. Keep build() small and shallow. Past the complexity limits owned by dart3-idioms-and-coding-standards (build() ≤ 80 lines; widget build nesting ≤ 5 — the deeper-nesting exception that table states for widget trees vs. logic ≤ 3), extract child widget classes. A build() you must scroll to read is too big.
4. One responsibility per widget. A component renders one thing; it does not also fetch data, format values, read a clock, hold app state, or schedule side effects.
5. No I/O, formatting, or domain math in build(). build() can run 60×/second — no repository/DAO call, no DateTime.now(), no NumberFormat, no sorting. The Notifier precomputes a ready-to-render UI-state value; the widget only paints it.
6. The View is dumb and watches exactly one ViewModel. A ConsumerWidget does ref.watch(oneNotifierProvider) and renders; intents go back via ref.read(...notifier). It never reaches a repository or DAO directly and never mutates persisted state.
7. StatelessWidget/ConsumerWidget by default. Use StatefulWidget/ConsumerStatefulWidget only for genuinely local, ephemeral UI state (AnimationController, TextEditingController, ScrollController, FocusNode). App/domain/session state lives in the Notifier.
8. Always dispose() controllers created in State. Leaked AnimationController/TextEditingController/ScrollController/FocusNode/subscriptions retain memory and fire after teardown. cancel_subscriptions/close_sinks are errors.
9. Lists are lazy. Use ListView.builder/SliverList for variable/long lists. Never ListView(children: items.map(...).toList()) for unbounded data — it builds every row eagerly.
10. Resolve identity, not content, in callbacks. A tap closure captures the stable id (onTap: () => onSelect(item.id)), never a captured content value — a re-tap after an edit must not act on a stale capture.
11. Every gesture needs a visible, focusable fallback. Any behaviour reachable by touch must also be reachable by a labelled focusable control. A drag-only or long-press-only action is unreachable to switch-access and screen-reader users.
12. Style from theme/tokens and logical directions. Colors/text styles come from Theme.of(context) or a ThemeExtension, never literal hex. Use EdgeInsetsDirectional/AlignmentDirectional (start/end), never hardcoded left/right, so RTL mirrors by construction.