Migration Guide

0.0.7 to 1.0.0

In our pursuit of API usability and efficiency, we introduced several deprecations in the latest Mix Package versions. When encountering issues not covered by deprecation notices, please open an issue or send a PR to our deprecation file (opens in a new tab).

Deprecations

The major updates are:

Mix evolve to Style

The Mix class is now Style. Several methods in the renamed class, including withVariants, withMaybeVariants among others, are deprecated to boost performance and reduce potential confusion.

Another important change is that the Style doesn't contain generic type anymore. Therefore, in the new version it is no longer possible.

MixContextBuilder was renamed to SpecBuilder

The MixContextBuilder was renamed to SpecBuilder to better reflect its purpose. The MixContextBuilder is now deprecated.

Widget Updates

TextMix and IconMix widgets are deprecated. Use StyledText and StyledIcon respectively.

Short Aliases

To enhance readability, short aliases and shorthand property/method names are replaced with fully named counterparts. You can find the full list of removed aliases in the deprecations file (opens in a new tab)

Modifiers

Modifiers' order was previously determined by their addition sequence. Now, we enforce specific ordering but also allow customizable orders. This might cause behavior changes in rare cases. For details, refer to the modifiers guide (opens in a new tab).

StyledWidgets updates

The new PressableBox

To provide a more consistent way to use the gesture APIs, we developed a new widget that merges the functionalities of Box and Pressable. Thus, the new PressableBox can receive a style like a Box and also accept interactions and its variants, similar to a Pressable. For more information, see the PressableBox guide (opens in a new tab). Keep in mind that the ideia is to reserve the old Pressable to more advanced cases.

Behavior changes

Modifiers

Modifiers cannot be inherited by any children. The reason is that abstract class Attribute has gained a new property, isInheritable, which can be set to false if you want your custom attributes to be non-inheritable, such as Modifiers.

Operators and (&) and or (|)

The operators have been redesigned to allow for concatenation and grouping, enabling the creation of conditions like, (primary | secondary) & onHover. For details, refer to the variants guide (opens in a new tab)

StyledWidgets and Modifiers

A bunch of StyledWidgets are now allow to receive modifiers' attributes, including StyledIcon, StyledFlex and StyledIcon. Additionally, when a modifier is not applied to a Style, a RenderWidgetModifiers will not be present in the widget tree. This simplification makes the widget easier to debug.

Theming

The MixTheme feature has been improved and now offer better API. It can applied to main attributes using the method .of, as shown in the following code:

const primaryColor = ColorToken('primary');
final theme = MixThemeData(
    colors: {
        primaryColor: Colors.blue,
    },
);
 
// ... body method ...
MixTheme(
    data: theme,
    Box(
        key: key,
        style: Style(
            $box.color.ref(primaryColor),
        ),
    )
)

The use of $

In the 1.0.0 version, the $ symbol is now used to access API from the Mix package. This change was made to be easier to identify the utilities provided by Mix. For example, to access the box namespace, you should use $box.

The new Namespaces $on and $with

Two new namespaces were added to the Mix package: $on and $with. The $on namespace is used to access ContextVariants, like $on.hover, $on.focus, and $on.press. While the $with namespace is used to access all the modifiers provided by Mix.

PressableBox(
    onPress: () {},
    style: Style(
        $box.width(200),
        $box.height(200),
        $box.color.blue(),
 
        $with.scale(2), // <-- Modifier
        $with.opacity(0.5),
        
        $on.hover( // <-- ContextVariant
            $box.color.red(),
        ),
        $on.press(
            $box.color.green(),
        ),
    ),
    child: Box(),
)