feat(mix_generator): generate named-only MixWidget constructors from enum variants

[leoafarias]

Closes #998.

Summary

Adds @MixWidget(variants:), which derives a widget's constructors from an enum-backed NamedVariant domain instead of a factory parameter. The generated wrapper has no unnamed constructor, no public variant: argument, and no public variant field.

enum FortalButtonVariant with EnumVariant { solid, soft, outline }

@MixWidget(target: RemixButton.new, variants: FortalButtonVariant)
BoxStyler fortalButtonStyle({FortalButtonSize size = .size2}) {
  return _base(size).variantsFromEnum(
    FortalButtonVariant.values,
    (variant) => switch (variant) {
      .solid => _solidStyle(),
      .soft => _softStyle(),
      .outline => _outlineStyle(),
    },
  );
}

FortalButton.solid(size: .size2, label: 'Save');
FortalButton.soft(size: .size3, label: 'Save');

Generated output (verified against the real packages, not stubs):

class FortalButton extends StatelessWidget {
  const FortalButton.solid({super.key, this.size = FortalButtonSize.size2, required this.label})
    : _variant = FortalButtonVariant.solid;
  // ...one per value

  final FortalButtonVariant _variant;
  final FortalButtonSize size;
  final String label;

  @override
  Widget build(BuildContext context) => RemixButton(
        key: this.key,
        style: fortalButtonStyle(size: this.size).applyVariant(this._variant),
        label: this.label,
      );
}

The value is stored privately because Dart forbids privately named parameters — that is precisely what makes the widget selectable only through its named constructors.

Design note: explicit annotation instead of a naming convention

The issue proposed discovering the enum by convention (same library, named <WidgetName>Variant). I implemented an explicit variants: field instead, because the convention is not actually opt-in: any existing user who happens to have enum CardVariant with EnumVariant beside cardStyle() would silently lose Card(...) on upgrade — a breaking public-API change with no source change on their side. The convention also forces the enum into the same library as the recipe, which fights the usual separate variants.dart split.

The explicit field costs one annotation parameter and makes "unchanged when it does not apply" true by construction rather than by luck.

Runtime API in mix

• variantsFromEnum(values, builder) — registers a VariantStyle per enum value. The builder must return a style for every value, so a switch expression makes coverage exhaustive at compile time.
• applyVariant(NamedVariant) — applies one variant and throws when none is registered. applyVariants (plural) keeps its silent no-op semantics.

The throw is the load-bearing half of "missing variant-style mappings produce a clear failure" — previously unreachable, since applyVariants returns the base style unchanged when nothing matches. Paired with variantsFromEnum, "unregistered" reliably means "genuinely forgotten". A deliberately unstyled variant registers an empty styler.

Validation

variants: is validated rather than silently skipped. The type must be an enum, mix in EnumVariant, be visible from the annotated library, have at least one reachable value, avoid colliding with generated widget type parameters, and not be combined with a variant factory parameter.

This differs deliberately from the legacy convention, which degrades silently on a type-parameter collision to stay non-breaking. Here, degrading would emit an unnamed-constructor widget — the opposite of what was asked for — so it fails.

Backwards compatibility

The existing variant factory-parameter convention is untouched: unnamed constructor, public field, forwarding to the recipe. Both modes are tested and coexist in one library. A byte-identical-output regression test guards the no-variant path.

Consolidation

• Collapsed the coupled variantParamName + variantConstructors model fields into one nullable WidgetVariantDomain, so the "name is set iff constructors exist" invariant holds by construction. Net field count unchanged; the two modes differ by exactly one documented bit.
• Split discovery from enumeration so both modes share _variantConstructorsFor (two real consumers), while callers decide what a collision means.
• The builder needed only three one-line conditionals.

Verification

• 2760 mix / 354 mix_generator / 14 mix_annotations tests pass; packages/mix analyzes clean.
• Beyond the stub-based generator tests, a throwaway package was built against the real packages and run through build_runner: generated output matched the target exactly, flutter analyze was clean, and widget tests confirmed .solid/.soft render different variants and that a missing mapping throws StateError at build time.

Incidental fix

The shared widget test stub's framework.dart re-exported key.dart without importing it, so Widget.key resolved to InvalidType and every super.key chained through it did too. Existing tests missed this because their stylers declared Key? key directly. It blocked all direct-target fixtures built on the shared stub; the fix is one import.

Note on branch name

The branch is fix/998 as requested, though the change is additive and all three changelog entries are tagged FEAT — feat/998 would match the repo convention. Flagging in case the branch name matters to release tooling.