Merge branch 'feat/improved-docs' of https://github.com/conceptadev/mix…

… into feat/improved-docs

# Conflicts:
#	lib/src/specs/container/box_widget.dart

lib/exports.dart

@@ -37,7 +37,6 @@ export 'src/decorators/widget_decorators_util.dart';
 export 'src/deprecations.dart';
 export 'src/factory/mix_provider.dart';
 export 'src/factory/mix_provider_data.dart';
-export 'src/factory/style_group.dart';
 export 'src/factory/style_mix.dart';
 export 'src/factory/style_mix_ext.dart';
 export 'src/specs/container/box_attribute.dart';

lib/src/deprecations.dart

@@ -5,34 +5,37 @@ import '../mix.dart';
 const kShortAliasDeprecation =
     'Short aliases will be deprecated, you can create your own. Example: final p = padding;';
 
+@Deprecated('Use Style instead')
+typedef Mix = Style;
+
 extension DeprecatedMixExtension<T extends Attribute> on Style {
   /// Adds an Attribute to a Mix.
   @Deprecated('Simplifying the mix API to avoid confusion. Use apply instead')
   SpreadFunctionParams<T, Style> get mix => SpreadFunctionParams(addAttributes);
 
-  @Deprecated('Use selectVariants now')
+  @Deprecated('Use variantList(value:) instead')
   Style withVariants(List<Variant> variants) => withManyVariants(variants);
 
+  @Deprecated('Use variantList(value:) instead')
+  Style withManyVariants(Iterable<Variant> variants) => variantList(variants);
+
   @Deprecated(
-    'Use merge() or mergeMany() now. You might have to turn into a Mix first. firstMixFactory.merge(secondMix)',
+    'Use merge() or mergeMany() instead. You might have to turn into a Mix first. firstMixFactory.merge(secondMix)',
   )
   Style addAttributes(Iterable<Attribute> attributes) =>
       merge(Style.create(attributes));
 
-  @Deprecated('Use selectVariants now')
-  Style withManyVariants(Iterable<Variant> variants) => variantList(variants);
-
   @Deprecated('Use merge() or mergeMany() instead')
   SpreadFunctionParams<Style, Style> get apply =>
       const SpreadFunctionParams(Style.combine);
 
-  @Deprecated('Use selectVariant now')
+  @Deprecated('Use variant(value:) instead')
   Style withVariant(Variant value) => variant(value);
 
-  @Deprecated('Use combine now')
+  @Deprecated('Use combine instead')
   Style combineAll(List<Style> mixes) => Style.combine(mixes);
 
-  @Deprecated('Use selectVariant now')
+  @Deprecated('Use variant(value:) instead')
   Style withMaybeVariant(Variant? variant) {
     if (variant == null) return this;
 
@@ -444,8 +447,29 @@ final borderVertical = border.vertical;
 @Deprecated('use border.all instead')
 final borderAll = border.all;
 
-@Deprecated('Use StyledText now')
-typedef TextMix = StyledText;
+@Deprecated('Use StyledText instead')
+class TextMix extends StyledText {
+  const TextMix(
+    super.text, {
+    super.semanticsLabel,
+    Mix? mix,
+    super.key,
+    super.inherit = true,
+    super.locale,
+  }) : super(style: mix);
+}
+
+@Deprecated('Use StyledIcon instead')
+class IconMix extends StyledIcon {
+  const IconMix(
+    super.icon, {
+    super.semanticLabel,
+    required Mix mix,
+    super.key,
+    super.inherit = true,
+    super.textDirection,
+  });
+}
 
 @Deprecated('Use text.style instead')
 final textStyle = text.style;
@@ -473,6 +497,15 @@ final mainAxisSize = flex.mainAxisSize;
 @Deprecated('use text.style.bold() instead')
 final bold = text.style.bold;
 
+@Deprecated('use flex.gap(value) instead')
+final gap = flex.gap;
+
+@Deprecated('use icon.size instead')
+final iconSize = icon.size;
+
+@Deprecated('use icon.color instead')
+final iconColor = icon.color;
+
 // @Deprecated('Use box.maxHeight instead')
 // final maxHeight = box.maxHeight;
 

lib/src/factory/style_mix.dart

@@ -15,8 +15,6 @@ import '../specs/text/text_attribute.dart';
 import '../utils/helper_util.dart';
 import '../variants/variant.dart';
 
-typedef Mix = Style;
-
 /// A utility class for managing a collection of styling attributes and variants.
 ///
 /// The `Style` class is used to encapsulate a set of styling attributes and
@@ -223,11 +221,11 @@ class Style with Comparable {
   /// If a null value is provided for any of the parameters, it is ignored.
   ///
   /// This method combines the visual and variant attributes of this mix and the provided [mix].
-  Style merge(Style? mix) {
-    if (mix == null) return this;
+  Style merge(Style? style) {
+    if (style == null) return this;
 
-    final mergedStyles = styles.merge(mix.styles);
-    final mergedVariants = variants.merge(mix.variants);
+    final mergedStyles = styles.merge(style.styles);
+    final mergedVariants = variants.merge(style.variants);
 
     return copyWith(styles: mergedStyles, variants: mergedVariants);
   }
@@ -339,6 +337,7 @@ class Style with Comparable {
   ///
   /// Note:
   /// The attributes `attr1` and `attr2` from the initial `Style` are ignored, and only the attributes within the specified variants are picked and applied to the new `Style`.
+  @visibleForTesting
   Style pickVariants(
     List<Variant> pickedVariants, {
     bool isRecursive = false,

lib/src/specs/container/box_widget.dart

@@ -1,11 +1,6 @@
 import 'package:flutter/material.dart';
 
-import '../../core/styled_widget.dart';
-import '../../decorators/widget_decorator_widget.dart';
-import '../../factory/mix_provider.dart';
-import '../../factory/mix_provider_data.dart';
-import 'box_attribute.dart';
-import 'box_spec.dart';
+import '../../../mix.dart';
 
 typedef StyledContainer = Box;
 typedef StyledAnimatedContainer = AnimatedBox;
@@ -16,11 +11,13 @@ typedef StyledAnimatedContainer = AnimatedBox;
 /// This widget serves as a convenient way to apply consistent styles to its child widget
 /// using the `MixData` obtained from `StyledWidget`.
 class Box extends StyledWidget {
-  /// Creates a `Box` widget.
-  ///
-  /// The [style], [key], and [inherit] parameters are passed to `StyledWidget`.
-  /// The [child] is the widget to which the styling will be applied.
-  const Box({super.style, super.key, super.inherit, this.child});
+  const Box({
+    @Deprecated('Use the the style parameter instead') Mix? mix,
+    super.style,
+    super.key,
+    super.inherit,
+    this.child,
+  });
 
   /// The child widget that will receive the styles.
   final Widget? child;

lib/src/specs/flex/flex_widget.dart

@@ -1,8 +1,10 @@
 import 'package:flutter/widgets.dart';
 
 import '../../core/styled_widget.dart';
+import '../../deprecations.dart';
 import '../../factory/mix_provider.dart';
 import '../../factory/mix_provider_data.dart';
+import '../../factory/style_mix.dart';
 import '../../widgets/gap_widget.dart';
 import '../container/box_widget.dart';
 import 'flex_spec.dart';
@@ -191,11 +193,15 @@ class FlexBox extends StyledWidget {
 /// ```
 class HBox extends FlexBox {
   const HBox({
-    super.style,
+    Style? style,
+    @Deprecated('Use the the style parameter instead') Mix? mix,
     super.key,
     super.inherit,
     super.children = const <Widget>[],
-  }) : super(direction: Axis.horizontal);
+  }) : super(
+          style: style ?? mix,
+          direction: Axis.horizontal,
+        );
 }
 
 /// A vertical flex container that uses `Style` for streamlined styling.
@@ -216,11 +222,15 @@ class HBox extends FlexBox {
 /// ```
 class VBox extends FlexBox {
   const VBox({
-    super.style,
+    Style? style,
+    @Deprecated('Use the the style parameter instead') Mix? mix,
     super.key,
     super.inherit,
     super.children = const <Widget>[],
-  }) : super(direction: Axis.vertical);
+  }) : super(
+          style: style ?? mix,
+          direction: Axis.vertical,
+        );
 }
 
 const _defaultFlex = Flex(direction: Axis.horizontal, children: <Widget>[]);

test/src/factory/style_mix_ext_test.dart

@@ -90,13 +90,13 @@ void main() {
           children: [
             style.hbox(children: [const SizedBox()], key: keyOne),
             HBox(
-              key: keyTwo,
               style: style,
+              key: keyTwo,
               children: const [SizedBox()],
             ),
             HBox(
-              key: keyThree,
               style: const Style.empty(),
+              key: keyThree,
               children: const [SizedBox()],
             ),
           ],
@@ -190,13 +190,13 @@ void main() {
           children: [
             style.vbox(children: [const SizedBox()], key: keyOne),
             VBox(
-              key: keyTwo,
               style: style,
+              key: keyTwo,
               children: const [SizedBox()],
             ),
             VBox(
-              key: keyThree,
               style: const Style.empty(),
+              key: keyThree,
               children: const [SizedBox()],
             ),
           ],