feat: create StylePhaseAnimator

[tilucasoli]

Description

Adds a new StylePhaseAnimator widget to orchestrate style transitions through multiple phases and exposes it in the experimental API.

Example

enum HeartAnimationPhases implements PhaseVariant {
  initial,
  pulse;

  @override
  Variant get variant => Variant(name);
}

class HeartAnimation extends StatefulWidget {
  const HeartAnimation({
    super.key,
  });

  @override
  State<HeartAnimation> createState() => _HeartAnimationState();
}

class _HeartAnimationState extends State<HeartAnimation> {
  final matrix = Matrix4.identity()..scale(2.0);

  @override
  Widget build(BuildContext context) {
    final baseStyle = Style(
      $with.transform(Matrix4.identity()..scale(1.5)),
      $text.fontSize(50),
      $text.color.red(),
    );

    return StylePhaseAnimator(
      phases: {
        HeartAnimationPhases.initial: baseStyle,
        HeartAnimationPhases.pulse: Style(
          baseStyle(),
          $with.transform(matrix),
        ),
      },
      animation: (_) => const PhaseAnimationData(
        duration: Duration(milliseconds: 300),
        curve: Curves.easeInOut,
      ),
      builder: (context, style) => const Box(
        inherit: true,
        child: StyledText('♥️'),
      ),
    );
  }
}

Changes

• Introduces PhaseAnimationData, PhaseVariant, and the StylePhaseAnimator widget with a configurable animation sequence.
• Updates the experimental.dart barrel file to export the new animator.
• Adds logic to cycle through style variants on trigger changes with customizable delays and curves.

Review Checklist

• Testing: Have you tested your changes, including unit tests and integration tests for affected code?
• Breaking Changes: Does this change introduce breaking changes affecting existing code or users?
• Documentation Updates: Are all relevant documentation files (e.g. README, API docs) updated to reflect the changes in this PR?
• Website Updates: Is the website containing the updates you make on documentation?

Additional Information (optional)

Is there any additional context or documentation that might be helpful for reviewers?

[docs-page]

To view this pull requests documentation preview, visit the following URL:

docs.page/btwld/mix~620

Documentation is deployed and generated using docs.page.

[Copilot]

Pull Request Overview

Adds a new StylePhaseAnimator widget to orchestrate style transitions through multiple phases and exposes it in the experimental API.

• Introduces PhaseAnimationData, PhaseVariant, and the StylePhaseAnimator widget with a configurable animation sequence.
• Updates the experimental.dart barrel file to export the new animator.
• Adds logic to cycle through style variants on trigger changes with customizable delays and curves.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/mix/lib/src/experiemental/style_phase_animator.dart	New widget and helpers for phase-based style animations
packages/mix/lib/experimental.dart	Export the new style phase animator in the experimental API

Comments suppressed due to low confidence (1)

packages/mix/lib/src/experiemental/style_phase_animator.dart:52

• The constructor doc references a 'child' parameter which no longer exists; it should reference 'builder' instead.

/// The [phases], [animation], [child] and [trigger] parameters must not be null.