refactor: breaking changes for v4-rc

CHANGELOG.md

@@ -3,6 +3,30 @@
 > [!IMPORTANT]  
 > See the [Migration Guides](https://amoshuke.github.io/flutter_tilt_book/en/docs/migration-guides/) for the details of breaking changes between versions.
 
+## 4.0.0-rc (Unreleased)
+
+**Breaking changes**
+
+Migration Guides: [Migrate to v4.0.0](#)
+
+- `Tilt` widget now only manages gesture state, sensor state, and animation state...
+- Replace `Tilt.TiltStreamController` with `Tilt.TiltController` to unify input stream management.
+- The previous `Tilt.lightShadowMode` parameter has been split into the independent widgets `TiltBaseContainer` and `TiltProjectorContainer`.
+  To reproduce the previous style, you need to compose them inside the `Tilt` widget,
+  or use `Tilt.base` and `Tilt.projector` directly.
+- `ShadowConfig` has been split into `ShadowBaseConfig` and `ShadowProjectorConfig`.
+- Rename `TiltParallax` parameter `size` to `offset`.
+
+**Deprecations**
+
+- The `lightConfig` of `TiltProjectorContainer` is now deprecated.
+  Because the current simulated light effect is not suitable for Projector,
+  it is now disabled by default and will be removed in a future release.
+
+**New features**
+
+- Add `TiltAnimatedBuilder` to help implement custom tilt logic.
+
 ## 3.3.4
 
 **Improvements**

example/android/app/build.gradle.kts

@@ -8,15 +8,15 @@ plugins {
 android {
     namespace = "com.example.flutter_tilt_example"
     compileSdk = flutter.compileSdkVersion
-    ndkVersion = "27.0.12077973" // flutter.ndkVersion
+    ndkVersion = flutter.ndkVersion
 
     compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
     }
 
     kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_11.toString()
+        jvmTarget = JavaVersion.VERSION_17.toString()
     }
 
     defaultConfig {

example/android/settings.gradle.kts

@@ -20,7 +20,7 @@ pluginManagement {
 plugins {
     id("dev.flutter.flutter-plugin-loader") version "1.0.0"
     id("com.android.application") version "8.9.1" apply false
-    id("org.jetbrains.kotlin.android") version "2.1.0" apply false
+    id("org.jetbrains.kotlin.android") version "2.1.21" apply false
 }
 
 include(":app")

example/example.md

@@ -21,7 +21,6 @@ class MyApp extends StatelessWidget {
     return MaterialApp(
       title: 'Flutter Tilt Example',
       theme: ThemeData(
-        useMaterial3: true,
         colorScheme: ColorScheme.fromSwatch(primarySwatch: Colors.brown),
         appBarTheme: const AppBarTheme(
           backgroundColor: Colors.brown,
@@ -42,15 +41,17 @@ class TiltExample extends StatelessWidget {
     for (var i = 1; i <= 10; i++) {
       innerBox.add(
         TiltParallax(
-          size: Offset(-20.0 * i, -30.0 * i),
-          child: Container(
+          offset: Offset(-20.0 * i, -30.0 * i),
+          child: SizedBox(
             width: 200 * (1 - i * 0.05),
             height: 200 * (1 - i * 0.05),
-            decoration: BoxDecoration(
-              shape: BoxShape.circle,
-              border: Border.all(
-                width: 4 * (1 - i * 0.05),
-                color: Colors.white.withValues(alpha: 1 - (i - 1) * 0.1),
+            child: DecoratedBox(
+              decoration: BoxDecoration(
+                shape: BoxShape.circle,
+                border: Border.all(
+                  width: 4 * (1 - i * 0.05),
+                  color: Colors.white.withValues(alpha: 1 - (i - 1) * 0.1),
+                ),
               ),
             ),
           ),
@@ -61,15 +62,15 @@ class TiltExample extends StatelessWidget {
     return Scaffold(
       backgroundColor: const Color(0xFFFFFFFF),
       body: Center(
-        child: Tilt(
+        child: Tilt.base(
           borderRadius: BorderRadius.circular(24.0),
           tiltConfig: const TiltConfig(
             angle: 20,
             leaveCurve: Curves.easeInOutCubicEmphasized,
             leaveDuration: Duration(milliseconds: 1200),
           ),
           lightConfig: const LightConfig(disable: true),
-          shadowConfig: const ShadowConfig(disable: true),
+          shadowConfig: const ShadowBaseConfig(disable: true),
           childLayout: ChildLayout(
             inner: [
               ...innerBox,
@@ -109,10 +110,12 @@ class TiltExample extends StatelessWidget {
               ),
             ],
           ),
-          child: Container(
+          child: SizedBox(
             width: 300,
             height: 500,
-            decoration: const BoxDecoration(color: Colors.black),
+            child: DecoratedBox(
+              decoration: const BoxDecoration(color: Colors.black),
+            ),
           ),
         ),
       ),

example/lib/main.dart

@@ -34,15 +34,17 @@ class TiltExample extends StatelessWidget {
     for (var i = 1; i <= 10; i++) {
       innerBox.add(
         TiltParallax(
-          size: Offset(-20.0 * i, -30.0 * i),
-          child: Container(
+          offset: Offset(-20.0 * i, -30.0 * i),
+          child: SizedBox(
             width: 200 * (1 - i * 0.05),
             height: 200 * (1 - i * 0.05),
-            decoration: BoxDecoration(
-              shape: BoxShape.circle,
-              border: Border.all(
-                width: 4 * (1 - i * 0.05),
-                color: Colors.white.withValues(alpha: 1 - (i - 1) * 0.1),
+            child: DecoratedBox(
+              decoration: BoxDecoration(
+                shape: BoxShape.circle,
+                border: Border.all(
+                  width: 4 * (1 - i * 0.05),
+                  color: Colors.white.withValues(alpha: 1 - (i - 1) * 0.1),
+                ),
               ),
             ),
           ),
@@ -53,15 +55,15 @@ class TiltExample extends StatelessWidget {
     return Scaffold(
       backgroundColor: const Color(0xFFFFFFFF),
       body: Center(
-        child: Tilt(
+        child: Tilt.base(
           borderRadius: BorderRadius.circular(24.0),
           tiltConfig: const TiltConfig(
             angle: 20,
             leaveCurve: Curves.easeInOutCubicEmphasized,
             leaveDuration: Duration(milliseconds: 1200),
           ),
           lightConfig: const LightConfig(disable: true),
-          shadowConfig: const ShadowConfig(disable: true),
+          shadowConfig: const ShadowBaseConfig(disable: true),
           childLayout: ChildLayout(
             inner: [
               ...innerBox,
@@ -101,10 +103,12 @@ class TiltExample extends StatelessWidget {
               ),
             ],
           ),
-          child: Container(
+          child: SizedBox(
             width: 300,
             height: 500,
-            decoration: const BoxDecoration(color: Colors.black),
+            child: DecoratedBox(
+              decoration: const BoxDecoration(color: Colors.black),
+            ),
           ),
         ),
       ),

lib/flutter_tilt.dart

@@ -1,15 +1,33 @@
 /// Easily apply tilt parallax hover effects for Flutter,
 /// which supports tilt, light, shadow effects, gyroscope sensors and many custom parameters.
 
+// ignore_for_file: directives_ordering
 // ignore: unnecessary_library_name
 library flutter_tilt;
 
+/// Configurations
 export 'src/config/tilt_config.dart';
 export 'src/config/tilt_light_config.dart';
 export 'src/config/tilt_shadow_config.dart';
 export 'src/enums.dart';
+
+/// Controllers
+export 'src/controllers/tilt_controller.dart' show TiltController;
+
+/// Data Models
 export 'src/models/tilt_data_model.dart' show TiltDataModel;
 export 'src/models/tilt_stream_model.dart' show TiltStreamModel;
-export 'src/tilt.dart';
-export 'src/widgets/tilt_light.dart';
-export 'src/widgets/tilt_shadow.dart';
+
+/// Main Widgets
+export 'src/tilt.dart' show Tilt, TiltParallax;
+export 'src/widgets/containers/tilt_base_container.dart' show TiltBaseContainer;
+export 'src/widgets/containers/tilt_projector_container.dart'
+    show TiltProjectorContainer;
+
+/// Core Widgets
+export 'src/widgets/core/tilt_animated_builder.dart' show TiltAnimatedBuilder;
+
+/// Effects
+export 'src/widgets/effects/tilt_light.dart' show TiltLight;
+export 'src/widgets/effects/tilt_shadow.dart'
+    show TiltShadowBase, TiltShadowProjector;

lib/src/config/tilt_config.dart

@@ -23,7 +23,6 @@ class TiltConfig {
     this.angle = 10.0,
     this.direction,
     this.enableReverse = false,
-    this.filterQuality,
     this.enableGestureSensors = true,
     this.sensorFactor = 10.0,
     this.enableSensorRevert = true,
@@ -132,9 +131,6 @@ class TiltConfig {
   ///
   final bool enableReverse;
 
-  /// FilterQuality
-  final FilterQuality? filterQuality;
-
   /// Gyroscope sensor triggered tilt.
   ///
   /// Only the following gestures:
@@ -435,7 +431,6 @@ class TiltConfig {
     double? angle,
     List<TiltDirection>? direction,
     bool? enableReverse,
-    FilterQuality? filterQuality,
     bool? enableGestureSensors,
     double? sensorFactor,
     bool? enableSensorRevert,
@@ -461,7 +456,6 @@ class TiltConfig {
       angle: angle ?? this.angle,
       direction: direction ?? this.direction,
       enableReverse: enableReverse ?? this.enableReverse,
-      filterQuality: filterQuality ?? this.filterQuality,
       enableGestureSensors: enableGestureSensors ?? this.enableGestureSensors,
       sensorFactor: sensorFactor ?? this.sensorFactor,
       enableSensorRevert: enableSensorRevert ?? this.enableSensorRevert,
@@ -501,7 +495,6 @@ class TiltConfig {
         Object.hashAll(other.direction ?? []) ==
             Object.hashAll(direction ?? []) &&
         other.enableReverse == enableReverse &&
-        other.filterQuality == filterQuality &&
         other.enableGestureSensors == enableGestureSensors &&
         other.sensorFactor == sensorFactor &&
         other.enableSensorRevert == enableSensorRevert &&
@@ -530,7 +523,6 @@ class TiltConfig {
       angle,
       Object.hashAll(direction ?? []),
       enableReverse,
-      filterQuality,
       enableGestureSensors,
       sensorFactor,
       enableSensorRevert,