wind widgets.instructions.md

Widget conventions (lib/src/widgets/)

Canonical shape (stateless composition widgets)

The default is StatelessWidget + const constructor. Match this shape unless the widget needs lifecycle (focus, controller, overlay, animation):

class WFoo extends StatelessWidget {
  final String? className;
  final Widget? child;
  final List<Widget>? children;
  final Set<String>? states;

  const WFoo({
    super.key,                              // first param
    this.className,
    this.child,
    this.children,
    this.states,
    // ...feature props after the styling props
  }) : assert(child != null || children != null,
              'child XOR children, never both, never neither');
}

• super.key is the first positional, except WText where the required positional data: String precedes it (semantic content dominates).
• child XOR children is a hard invariant. Assert at construction.
• className: String? is the styling API. Parse it via WindParser.parse(className!, context, states: activeStates) inside build. Explicit Dart props (backgroundColor, foregroundColor) override the parsed style.
• states: Set<String>? activates hover: / focus: / disabled: / loading: / selected: / custom prefixed classes. Merge automatic state flags (hover, focus, etc.) into activeStates inside build before passing to the parser.

StatefulWidget exceptions (only when warranted)

• WInput — manages TextEditingController + FocusNode lifecycle.
• WSelect<T> — overlay open/close + filter state.
• WPopover — overlay anchor state.
• WDatePicker — month navigation + range selection.
• WKeyboardActions — overlay toolbar visibility per focus change.
• WindAnimationWrapper — AnimationController + vsync.

WFormInput / WFormSelect / WFormCheckbox / WFormDatePicker extend FormField<T> and delegate build to an internal _W{Form*}Content stateful widget. The outer FormField stays const-constructible; lifecycle lives in _content.