State Builder Strategy

This chapter explains how StateSlotBuilder fits into the slot-boundary model defined by SlotStatefulWidget.

While slot boundaries define what a widget is allowed to depend on, builders define where and how updates are applied inside that boundary.

---

Two different responsibilities

SimpleAppState provides two Flutter integration tools:

• SlotStatefulWidget — defines state ownership

• StateSlotBuilder — defines localized reactivity

They are designed to work together, not to replace each other.

---

SlotStatefulWidget defines the contract

When a widget extends SlotStatefulWidget, it declares its allowed state dependencies:

class SettingsScreen extends SlotStatefulWidget {
  @override
  List<StateSlot> get slots => [
    settingsSlot,
  ];
}

This tells everyone:

• Which state this screen owns

• What is allowed to influence this screen

• What should trigger rebuilds

This declaration is part of the widget’s design contract.

---

StateSlotBuilder implements local reactions

When extending an existing class, or within a SlotStatefulWidget, it is often useful to rebuild only a small part of the UI.

That is what StateSlotBuilder is for.

StateSlotBuilder(
  slotList: [settingsSlot],
  builder: (context) {
    final settings = settingsSlot.get();
    return Switch(
      value: settings.darkMode,
      onChanged: (v) {
        settingsSlot.update(
          settings.copyWith(darkMode: v),
        );
      },
    );
  },
)

This builder reacts to changes in settingsSlot, but only rebuilds this small subtree.

The surrounding widget structure remains untouched.

---

Builders do not define screen ownership

StateSlotBuilder does not define the overall state boundary of a screen.

If builders are scattered throughout a widget tree, the screen’s true dependencies become difficult to see.

Column(
  children: [
    StateSlotBuilder(slotList: [userSlot], builder: ...),
    StateSlotBuilder(slotList: [settingsSlot], builder: ...),
    StateSlotBuilder(slotList: [themeSlot], builder: ...),
  ],
)

Each builder is simple in isolation, but the screen’s overall state surface is now hidden.

For this reason, StateSlotBuilder is intentionally not a replacement for SlotStatefulWidget.

---

A layered design

The intended structure is:

• SlotStatefulWidget

  • Defines which slots a screen is allowed to use

  • Acts as a design-time boundary

• StateSlotBuilder

  • Applies reactivity inside that boundary

  • Controls which parts of the UI rebuild

This keeps:

• High-level design visible

• Local behavior efficient

• Code reviews meaningful

---

A tool, not a shortcut

StateSlotBuilder exists to solve localized update and performance problems.

It should not be used to bypass slot boundaries or to avoid declaring dependencies at the screen level.

Used correctly, it improves both performance and clarity.

Used incorrectly, it hides dependencies and weakens the design contract.

SimpleAppState intentionally separates these roles so that both design and implementation remain understandable.