Merge branch 'main' into refactor/remix-theme

.github/workflows/widgetbook.yml

@@ -0,0 +1,56 @@
+name: "Widgetbook"
+
+on: push
+
+jobs:
+  production:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install FVM
+        shell: bash
+        run: |
+          curl -fsSL https://fvm.app/install.sh | bash
+          fvm use ${{ inputs.flutter-version }} --force
+
+      - uses: kuhnroyal/flutter-fvm-config-action@v2
+        id: fvm-config-action
+
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: ${{ steps.fvm-config-action.outputs.FLUTTER_VERSION }}
+          channel: ${{ steps.fvm-config-action.outputs.FLUTTER_CHANNEL }}
+
+      - name: Flutter version
+        shell: bash
+        run: flutter --version
+
+      - name: Setup Melos
+        uses: bluefireteam/melos-action@v3
+
+      - name: Bootstrap App
+        shell: bash
+        run: |
+          flutter pub get
+
+      - name: Bootstrap Widgetbook
+        working-directory: packages/remix/demo
+        shell: bash
+        run: |
+          flutter pub get
+          dart run build_runner build -d
+
+      - name: Build Widgetbook
+        working-directory: packages/remix/demo
+        shell: bash
+        run: |
+          flutter build web
+
+      - name: Install Widgetbook CLI
+        run: dart pub global activate widgetbook_cli
+
+      - name: Upload Widgetbook
+        working-directory: packages/remix/demo
+        run: widgetbook cloud build push --api-key ${{ secrets.WIDGETBOOK_API_KEY }}

packages/mix/lib/src/theme/tokens/breakpoints_token.dart

@@ -77,13 +77,13 @@ class BreakpointToken extends MixToken<Breakpoint> {
   }
 }
 
-/// A resolver for breakpoint tokens.
+/// {@macro mix.token.resolver}
 @immutable
 class BreakpointResolver extends Breakpoint with WithTokenResolver<Breakpoint> {
   @override
   final BuildContextResolver<Breakpoint> resolve;
 
-  /// Creates a new breakpoint resolver with the given [resolve] function.
+  /// {@macro mix.token.resolver}
   const BreakpointResolver(this.resolve);
 }
 

packages/mix/lib/src/theme/tokens/color_token.dart

@@ -102,15 +102,20 @@ class ColorSwatchToken<T> extends ColorToken {
   }
 }
 
-/// A color resolver that allows dynamic resolution of a color value.
+/// {@template mix.token.resolver}
+/// A resolver that allows dynamic resolution of a token value.
 ///
-/// This is useful when the color value is dependent on the current [BuildContext],
+/// This is useful when the token value is dependent on the current [BuildContext],
 /// and cannot be resolved statically.
+///
+/// For more information, see [Dynamic Themes](https://www.fluttermix.com/docs/guides/design-token#dynamic-themes).
+/// {@endtemplate}
 class ColorResolver extends Color with WithTokenResolver<Color> {
   /// The function used to resolve the color value dynamically.
   @override
   final BuildContextResolver<Color> resolve;
 
+  /// {@macro mix.token.resolver}
   const ColorResolver(this.resolve) : super(0);
 }
 

packages/mix/lib/src/theme/tokens/radius_token.dart

@@ -26,11 +26,13 @@ class RadiusToken extends MixToken<Radius> {
   }
 }
 
+/// {@macro mix.token.resolver}
 @immutable
 class RadiusResolver extends Radius with WithTokenResolver<Radius> {
   @override
   final BuildContextResolver<Radius> resolve;
 
+  /// {@macro mix.token.resolver}
   const RadiusResolver(this.resolve) : super.circular(0);
 }
 

packages/mix/lib/src/theme/tokens/text_style_token.dart

@@ -26,6 +26,7 @@ class TextStyleToken extends MixToken<TextStyle> {
   }
 }
 
+/// {@macro mix.token.resolver}
 @immutable
 class TextStyleResolver extends TextStyle with WithTokenResolver<TextStyle> {
   @override

website/pages/docs/guides/design-token.mdx

@@ -43,18 +43,66 @@ MixTheme(
 
 `MixThemeData` is a class that defines the values for the design tokens that will be used throughout the application. It has five properties related to Design Tokens: `colors`, `textStyles`, `spaces`, `radii`, and `breakpoints`. Each property is a map that contains the tokens and their values.
 
+```dart {1-4}
+const primary = ColorToken('primary');
+const h1 = TextStyleToken('h1');
+const radiusMedium = RadiusToken('radiusMedium');
+const spaceMedium = SpaceToken('spaceMedium');
+
+final docTheme = MixThemeData(
+  colors: {
+    primary: Colors.lightBlue,
+  },
+  textStyles: {
+    h1: const TextStyle(
+      fontSize: 24,
+      fontWeight: FontWeight.bold,
+    ),
+  },
+  radii: {
+    radiusMedium: const Radius.circular(10),
+  },
+  spaces: {
+    spaceMedium: 10,
+  },
+);
+```
+
 Also, `MixThemeData` has an additional property called `defaultOrderOfModifiers`, which is used to override the default order of modifiers. Therefore, if you prefer to use a different order of modifiers, you can set it in the `defaultOrderOfModifiers` instead of using the `orderOfModifiers` property in each `StyledWidget`. To set your own order of modifiers, you just need to pass a list of types that extends `WidgetModifierSpec`. For instance:
 
-```dart {3-5}
-final overrideOrderTheme = MixThemeData(
-  defaultOrderOfModifiers: [
+```dart
+final docTheme = MixThemeData(
+
+  // ...
+  defaultOrderOfModifiers: const [
     SizedBoxModifierSpec,
     ClipRectModifierSpec,
     TransformModifierSpec,
   ],
 );
 ```
 
+### Dynamic Themes
+
+Mix allows you to define dynamic themes, which means that the values of the design tokens can be resolved dynamically using a [BuildContext](https://api.flutter.dev/flutter/widgets/BuildContext-class.html). To do this, you need to use the `ColorResolver`, `TextStyleResolver`, `RadiusResolver` and `BreakpointResolver` classes. These classes are used to resolve the values of the design tokens based on the current `BuildContext`.
+
+As an example, let's say you want to define a `surface` color token that changes based on the platform brightness. You can do this by using the `ColorResolver` class:
+
+```dart
+final surface = ColorToken('surface');
+
+final docTheme = MixThemeData(
+  colors: {
+    surface: ColorResolver((context) {
+      if (MediaQuery.of(context).platformBrightness == Brightness.dark) {
+        return Colors.black;
+      }
+      return Colors.white;
+    }),
+  },
+);
+```
+
 ## Applying design tokens
 
 After defining the design tokens, you can use them in your application to style your widgets. All attributes that accept a token as a value have a `ref` method that allows you to access the token value. For instance: