forui Documentation

In Forui, Controls are abstractions over controllers (like TextEditingController) that define where a widget's state lives. Instead of passing raw controllers directly to widgets, you pass a Control object. This abstraction allows for different patterns of state ownership: either the widget owns the state, or the application logic owns the state.

There are two primary types of controls:

1. Lifted: The widget is "dumb" and only reflects the values passed to it. The state is managed externally by your application logic. This is similar to React's controlled components.
2. Managed: The widget manages its own state. This can happen in two ways:
   • Internal Controller: The widget creates and manages its own controller internally, using provided initial values.
   • External Controller: You pass in an existing controller. In this case, you are responsible for managing the lifecycle (creation and disposal) of that controller.

Forui follows the State Independence Principle when using declarative (lifted) modes:

1. No Implicit Sync: Each value/callback pair is isolated. If you lift multiple related states (e.g., a selected date and the currently displayed month in a calendar), changing one will not automatically update the other. You must wire the synchronization manually in your onChange callbacks.
2. Sensible Defaults for Omitted States: If you omit a specific state pair in .lifted() mode, the widget manages that specific part internally with sensible defaults. For example, in FCalendar, if you omit displayedMonth, the widget will auto-scroll to the selected date. If you provide displayedMonth, the widget will no longer auto-scroll, giving you full control.

// Example: FCalendar behavior with omitted vs provided state

// displayedMonth omitted -> widget auto-scrolls to selected date
FCalendar(control: FCalendarControl.liftedSingle(value: date, onChange: setDate));

// displayedMonth provided -> user controls, no auto-scroll
FCalendar(control: FCalendarControl.liftedSingle(
  value: date,
  onChange: setDate,
  displayedMonth: month,
  onDisplayedMonthChange: setMonth,
));

// Manual sync required if both are lifted
FCalendar(control: FCalendarControl.liftedSingle(
  value: date,
  onChange: (d) {
    setDate(d);
    setMonth(d);  // manual sync
  },
  displayedMonth: month,
  onDisplayedMonthChange: setMonth,
));