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. If you encounter 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 evolved 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 no longer contains a generic type. 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 their fully named counterparts. You can find the full list of removed aliases in the deprecations file (opens in a new tab)

Modifiers

The order of modifiers was previously determined by their addition sequence. Now, we enforce a 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 idea is to reserve the old Pressable for more advanced cases.

Behavior changes

Modifiers

Modifiers cannot be inherited by any children. The reason is that the 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 now allow receiving 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 offers a better API. It can be 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 version 1.0.0, the $ symbol is now used to access the API from the Mix package. This change was made to make it 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, such as $on.hover, $on.focus, and $on.press. Meanwhile, 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(),
)