deprecate

packages/mix/lib/src/modifiers/render_widget_modifier.dart

@@ -17,6 +17,7 @@ import 'transform_widget_modifier.dart';
 import 'visibility_widget_modifier.dart';
 
 // Default order of modifiers and their logic:
+@Deprecated("Use _defaultSpecsOrder instead")
 const _defaultOrder = [
   // 1. VisibilityModifier: Controls overall visibility. If the widget is set to be invisible,
   // none of the subsequent decorations are processed, providing an early exit and optimizing performance.
@@ -70,35 +71,100 @@ const _defaultOrder = [
   OpacityModifierAttribute,
 ];
 
-const _defaultOrderSpecs = [
+const _defaultSpecsOrder = [
+  // 1. VisibilityModifier: Controls overall visibility. If the widget is set to be invisible,
+  // none of the subsequent decorations are processed, providing an early exit and optimizing performance.
   VisibilityModifierSpec,
+
+  // 2. SizedBoxModifier: Explicitly sets the size of the widget before any other transformations are applied.
+  // This ensures that the widget occupies a predetermined space, which is crucial for layouts that require exact dimensions.
   SizedBoxModifierSpec,
+
+  // 3. FractionallySizedBoxModifier: Adjusts the widget's size relative to its parent's size,
+  // allowing for responsive layouts that scale with the parent widget. This modifier is applied after
+  // explicit sizing to refine the widget's dimensions based on available space.
   FractionallySizedBoxModifierSpec,
+
+  // 4. AlignModifier: Aligns the widget within its allocated space, which is especially important
+  // for positioning the widget correctly before applying any transformations that could affect its position.
+  // Alignment is based on the size constraints established by previous modifiers.
   AlignModifierSpec,
+
+  // 5. IntrinsicHeightModifier: Adjusts the widget's height to fit its child's intrinsic height,
+  // ensuring that the widget does not force its children to conform to an unnatural height. This is particularly
+  // useful for widgets that should size themselves based on content.
   IntrinsicHeightModifierSpec,
+
+  // 6. IntrinsicWidthModifier: Similar to the IntrinsicHeightModifier, this adjusts the widget's width
+  // to its child's intrinsic width. This modifier allows for content-driven width adjustments, making it ideal
+  // for widgets that need to wrap their content tightly.
   IntrinsicWidthModifierSpec,
+
+  // 7. AspectRatioModifier: Maintains the widget's aspect ratio after sizing adjustments.
+  // This modifier ensures that the widget scales correctly within its given aspect ratio constraints,
+  // which is critical for preserving the visual integrity of images and other aspect-sensitive content.
   AspectRatioModifierSpec,
+
+  // 9. TransformModifier: Applies arbitrary transformations, such as rotation, scaling, and translation.
+  // Transformations are applied after all sizing and positioning adjustments to modify the widget's appearance
+  // and position in more complex ways without altering the logical layout.
   TransformModifierSpec,
+
+  // 10. Clip Modifiers: Applies clipping in various shapes to the transformed widget, shaping the final appearance.
+  // Clipping is one of the last steps to ensure it is applied to the widget's final size, position, and transformation state.
   ClipOvalModifierSpec,
   ClipRRectModifierSpec,
   ClipPathModifierSpec,
   ClipTriangleModifierSpec,
   ClipRectModifierSpec,
+
+  // 11. OpacityModifier: Modifies the widget's opacity as the final decoration step. Applying opacity last ensures
+  // that it does not influence the layout or transformations, serving purely as a visual effect to alter the transparency
+  // of the widget and its decorations.
   OpacityModifierSpec,
 ];
 
 class RenderModifiers extends StatelessWidget {
   const RenderModifiers({
     required this.child,
-    required this.modifiers,
+    //TODO Should be required in the next version
+    this.modifiers = const <WidgetModifierSpec<dynamic>>{},
+    @Deprecated("Use modifiers parameter") this.mix,
+    @Deprecated("Use modifiers parameter") this.orderOfModifiers,
     super.key,
   });
 
   final Widget child;
+  final MixData? mix;
+  final List<Type>? orderOfModifiers;
   final Set<WidgetModifierSpec<dynamic>> modifiers;
 
+  @Deprecated("Should be removed in the next major version")
+  Widget deprecatedBuild() {
+    final specs = resolveModifierSpecs(orderOfModifiers!, mix!);
+
+    var current = child;
+
+    for (final spec in specs) {
+      current = spec.build(current);
+    }
+
+    return current;
+  }
+
   @override
   Widget build(BuildContext context) {
+    assert(
+      (mix == null) || (modifiers.isEmpty),
+    );
+    assert(
+      (orderOfModifiers?.isEmpty ?? true) || (modifiers.isEmpty),
+    );
+
+    if (mix != null && orderOfModifiers != null) {
+      return deprecatedBuild();
+    }
+
     var current = child;
 
     for (final spec in modifiers) {
@@ -111,16 +177,21 @@ class RenderModifiers extends StatelessWidget {
 
 class RenderAnimatedModifiers extends ImplicitlyAnimatedWidget {
   const RenderAnimatedModifiers({
-    required this.modifiers,
+    //TODO Should be required in the next version
+    this.modifiers = const {},
     required this.child,
     required super.duration,
+    @Deprecated("Use modifiers parameter") this.mix,
+    @Deprecated("Use modifiers parameter")
+    this.orderOfModifiers = const <Type>[],
     super.key,
     super.curve = Curves.linear,
     super.onEnd,
   });
 
   final Widget child;
-
+  final MixData? mix;
+  final List<Type>? orderOfModifiers;
   final Set<WidgetModifierSpec<dynamic>> modifiers;
 
   @override
@@ -133,6 +204,10 @@ class RenderAnimatedModifiersState
 
   @override
   void forEachTween(TweenVisitor<dynamic> visitor) {
+    if (widget.mix != null && widget.orderOfModifiers != null) {
+      deprecatedForEachTween(visitor);
+    }
+
     for (final spec in widget.modifiers) {
       final specType = spec.runtimeType;
       final previousSpec = _specs[specType];
@@ -145,8 +220,32 @@ class RenderAnimatedModifiersState
     }
   }
 
+  @Deprecated('should be deleted in the next major version')
+  void deprecatedForEachTween(TweenVisitor<dynamic> visitor) {
+    final specs = resolveModifierSpecs(widget.orderOfModifiers!, widget.mix!);
+
+    for (final spec in specs) {
+      final specType = spec.runtimeType;
+      final previousSpec = _specs[specType];
+
+      _specs[specType] = visitor(
+        previousSpec,
+        spec,
+        (dynamic value) =>
+            ModifierSpecTween(begin: value as WidgetModifierSpec),
+      ) as ModifierSpecTween;
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
+    assert(
+      (widget.mix == null) || (widget.modifiers.isEmpty),
+    );
+    assert(
+      (widget.orderOfModifiers?.isEmpty ?? true) || (widget.modifiers.isEmpty),
+    );
+
     var current = widget.child;
 
     for (final spec in _specs.keys) {
@@ -158,17 +257,6 @@ class RenderAnimatedModifiersState
   }
 }
 
-Set<WidgetModifierSpec> resolveModifierSpecs(
-  List<Type> orderOfModifiers,
-  MixData mix,
-) {
-  final modifiers = mix.whereType<WidgetModifierAttribute>();
-
-  if (modifiers.isEmpty) return {};
-
-  return orderModifierSpecs(orderOfModifiers, mix, modifiers);
-}
-
 Set<WidgetModifierSpec<dynamic>> orderSpecs(
   List<Type> orderOfModifiers, [
   Set<WidgetModifierSpec<dynamic>> modifiers = const {},
@@ -177,7 +265,7 @@ Set<WidgetModifierSpec<dynamic>> orderSpecs(
     // Prioritize the order of modifiers provided by the user.
     ...orderOfModifiers,
     // Add the default order of modifiers.
-    ..._defaultOrderSpecs,
+    ..._defaultSpecsOrder,
     // Add any remaining modifiers that were not included in the order.
     ...modifiers.map((e) => e.type),
   }).toList();
@@ -194,9 +282,20 @@ Set<WidgetModifierSpec<dynamic>> orderSpecs(
   return specs;
 }
 
-Set<WidgetModifierSpec> orderModifierSpecs(
+Set<WidgetModifierSpec<dynamic>> resolveModifierSpecs(
   List<Type> orderOfModifiers,
   MixData mix,
+) {
+  final modifiers = mix.whereType<WidgetModifierAttribute>();
+
+  if (modifiers.isEmpty) return {};
+  final orderedModifiers = orderModifierSpecs(orderOfModifiers, modifiers);
+
+  return orderedModifiers.map((e) => e.resolve(mix)).toSet();
+}
+
+Iterable<WidgetModifierAttribute> orderModifierSpecs(
+  List<Type> orderOfModifiers,
   Iterable<WidgetModifierAttribute> modifiers,
 ) {
   final modifierMap = AttributeMap<WidgetModifierAttribute>(modifiers).toMap();
@@ -210,16 +309,16 @@ Set<WidgetModifierSpec> orderModifierSpecs(
     ...modifierMap.keys,
   }.toList().reversed;
 
-  final specs = <WidgetModifierSpec>[];
+  final specs = <WidgetModifierAttribute>[];
 
   for (final modifierType in listOfModifiers) {
     // Resolve the modifier and add it to the list of specs.
     final modifier = modifierMap.remove(modifierType);
     if (modifier == null) continue;
-    specs.add(modifier.resolve(mix) as WidgetModifierSpec);
+    specs.add(modifier);
   }
 
-  return specs.toSet();
+  return specs;
 }
 
 class RenderSpecModifiers extends StatelessWidget {

packages/mix/lib/src/specs/box/box_spec.dart

@@ -106,6 +106,7 @@ final class BoxSpec extends Spec<BoxSpec> with _$BoxSpec {
             spec: this,
             duration: animated!.duration,
             curve: animated!.curve,
+            orderOfModifiers: orderOfModifiers,
             child: child,
           )
         : BoxSpecWidget(

packages/mix/lib/src/specs/icon/icon_widget.dart

@@ -12,8 +12,15 @@ class StyledIcon extends StyledWidget {
     super.key,
     super.inherit = true,
     this.textDirection,
-    super.orderOfModifiers = const [],
-  });
+    @Deprecated('Use orderOfModifiers parameter instead')
+    List<Type> modifierOrder = const <Type>[],
+    List<Type> orderOfModifiers = const <Type>[],
+  })  : assert(modifierOrder == const <Type>[] ||
+            orderOfModifiers == const <Type>[]),
+        super(
+          orderOfModifiers:
+              orderOfModifiers == const [] ? modifierOrder : orderOfModifiers,
+        );
 
   final IconData? icon;
   final String? semanticLabel;
@@ -51,8 +58,13 @@ class IconSpecWidget extends StatelessWidget {
     this.semanticLabel,
     super.key,
     this.textDirection,
-    this.orderOfModifiers = const [],
-  });
+    @Deprecated('Use orderOfModifiers parameter instead')
+    List<Type> modifierOrder = const <Type>[],
+    List<Type> orderOfModifiers = const <Type>[],
+  })  : assert(modifierOrder == const <Type>[] ||
+            orderOfModifiers == const <Type>[]),
+        orderOfModifiers =
+            orderOfModifiers == const [] ? modifierOrder : orderOfModifiers;
 
   final IconData? icon;
   final IconSpec? spec;
@@ -90,8 +102,16 @@ class AnimatedStyledIcon extends StyledWidget {
     required this.progress,
     super.inherit,
     this.textDirection,
-    super.orderOfModifiers = const [],
-  });
+    @Deprecated('Use orderOfModifiers parameter instead')
+    List<Type> modifierOrder = const <Type>[],
+    List<Type> orderOfModifiers = const <Type>[],
+  })  : assert(modifierOrder == const <Type>[] ||
+            orderOfModifiers == const <Type>[]),
+        super(
+          orderOfModifiers: orderOfModifiers == const <Type>[]
+              ? modifierOrder
+              : orderOfModifiers,
+        );
 
   final AnimatedIconData icon;
   final String? semanticLabel;
@@ -122,11 +142,17 @@ class AnimatedIconSpecWidget extends ImplicitlyAnimatedWidget {
     super.key,
     this.semanticLabel,
     this.textDirection,
-    this.orderOfModifiers = const [],
-    Curve curve = Curves.linear,
-    required Duration duration,
-    VoidCallback? onEnd,
-  }) : super(curve: curve, duration: duration, onEnd: onEnd);
+    super.curve,
+    required super.duration,
+    super.onEnd,
+    @Deprecated('Use orderOfModifiers parameter instead')
+    List<Type> modifierOrder = const <Type>[],
+    List<Type> orderOfModifiers = const <Type>[],
+  })  : assert(modifierOrder == const <Type>[] ||
+            orderOfModifiers == const <Type>[]),
+        orderOfModifiers = orderOfModifiers == const <Type>[]
+            ? modifierOrder
+            : orderOfModifiers;
 
   final IconData? icon;
   final IconSpec spec;