Skip to content

Commit cd99c3d

Browse files
authored
[material_ui] Add Material motion springs (flutter#13338)
Adds `Springs`, a set of `SpringDescription` constants created from the Material 3 Expressive motion tokens (`md.sys.motion.spring.*`). Material spring tokens define a stiffness and a damping ratio, but no mass. Each constant uses a mass of 1.0, so it's the same as `SpringDescription.withDampingRatio` with the token's values. They're generated by a new `MotionTemplateM3E` in `gen_defaults`. This PR doesn't change any component. Fixes flutter/flutter#184932 ## Pre-Review Checklist
1 parent 249f37d commit cd99c3d

7 files changed

Lines changed: 372 additions & 0 deletions

File tree

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
// Do not edit by hand. The code is generated from data in the Material
6+
// Design token database by the script:
7+
// packages/material_ui/tool/gen_defaults/bin/gen_defaults.dart.
8+
part of '../motion.dart';
9+
10+
/// The set of springs in the Material specification.
11+
///
12+
/// Material 3 Expressive motion uses springs, grouped into two motion schemes.
13+
/// The standard scheme eases into place with minimal bounce, and suits more
14+
/// utilitarian products. The expressive scheme overshoots and bounces into
15+
/// place, and suits hero moments and key interactions.
16+
///
17+
/// Each scheme has springs for two types of motion, in three speeds: default,
18+
/// fast, and slow.
19+
///
20+
/// * Spatial springs animate movement, such as position, size, rotation, and
21+
/// corner radius.
22+
/// * Effects springs animate properties that shouldn't overshoot, such as
23+
/// color and opacity.
24+
///
25+
/// Most motion should use the default speed. Smaller elements can use the fast
26+
/// speed, and larger elements can use the slow speed.
27+
///
28+
/// Material spring tokens define a stiffness and a damping ratio, but no
29+
/// mass. The Material token named `damping` is the damping ratio (ζ), not
30+
/// [SpringDescription.damping]. Each constant is the same as
31+
/// [SpringDescription.withDampingRatio] with a mass of 1.0 and the token's
32+
/// stiffness and damping ratio, so its damping is
33+
/// `ratio * 2.0 * sqrt(stiffness)`. For example, [standardDefaultSpatial] has
34+
/// a damping of `0.9 * 2.0 * sqrt(700.0)`, about 47.62.
35+
///
36+
/// Use them with a `SpringSimulation`, for example through
37+
/// [AnimationController.animateWith].
38+
///
39+
/// See also:
40+
///
41+
/// * [Durations] and [Easing], which are the Material tokens for curve-based
42+
/// animations.
43+
/// * [M3 guidelines: Motion physics system](https://m3.material.io/styles/motion/overview/how-it-works)
44+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
45+
abstract final class Springs {
46+
/// The standard default spatial spring in the Material specification.
47+
///
48+
/// It has a stiffness of 700.0 and a damping ratio of 0.9.
49+
///
50+
/// See also:
51+
///
52+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
53+
static const SpringDescription standardDefaultSpatial = SpringDescription(
54+
mass: 1.0,
55+
stiffness: 700.0,
56+
damping: 47.62352359916263,
57+
);
58+
59+
/// The standard fast spatial spring in the Material specification.
60+
///
61+
/// It has a stiffness of 1400.0 and a damping ratio of 0.9.
62+
///
63+
/// See also:
64+
///
65+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
66+
static const SpringDescription standardFastSpatial = SpringDescription(
67+
mass: 1.0,
68+
stiffness: 1400.0,
69+
damping: 67.34983296193096,
70+
);
71+
72+
/// The standard slow spatial spring in the Material specification.
73+
///
74+
/// It has a stiffness of 300.0 and a damping ratio of 0.9.
75+
///
76+
/// See also:
77+
///
78+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
79+
static const SpringDescription standardSlowSpatial = SpringDescription(
80+
mass: 1.0,
81+
stiffness: 300.0,
82+
damping: 31.176914536239796,
83+
);
84+
85+
/// The standard default effects spring in the Material specification.
86+
///
87+
/// It has a stiffness of 1600.0 and a damping ratio of 1.0.
88+
///
89+
/// See also:
90+
///
91+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
92+
static const SpringDescription standardDefaultEffects = SpringDescription(
93+
mass: 1.0,
94+
stiffness: 1600.0,
95+
damping: 80.0,
96+
);
97+
98+
/// The standard fast effects spring in the Material specification.
99+
///
100+
/// It has a stiffness of 3800.0 and a damping ratio of 1.0.
101+
///
102+
/// See also:
103+
///
104+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
105+
static const SpringDescription standardFastEffects = SpringDescription(
106+
mass: 1.0,
107+
stiffness: 3800.0,
108+
damping: 123.28828005937953,
109+
);
110+
111+
/// The standard slow effects spring in the Material specification.
112+
///
113+
/// It has a stiffness of 800.0 and a damping ratio of 1.0.
114+
///
115+
/// See also:
116+
///
117+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
118+
static const SpringDescription standardSlowEffects = SpringDescription(
119+
mass: 1.0,
120+
stiffness: 800.0,
121+
damping: 56.568542494923804,
122+
);
123+
124+
/// The expressive default spatial spring in the Material specification.
125+
///
126+
/// It has a stiffness of 380.0 and a damping ratio of 0.8.
127+
///
128+
/// See also:
129+
///
130+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
131+
static const SpringDescription expressiveDefaultSpatial = SpringDescription(
132+
mass: 1.0,
133+
stiffness: 380.0,
134+
damping: 31.189741903388683,
135+
);
136+
137+
/// The expressive fast spatial spring in the Material specification.
138+
///
139+
/// It has a stiffness of 800.0 and a damping ratio of 0.6.
140+
///
141+
/// See also:
142+
///
143+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
144+
static const SpringDescription expressiveFastSpatial = SpringDescription(
145+
mass: 1.0,
146+
stiffness: 800.0,
147+
damping: 33.94112549695428,
148+
);
149+
150+
/// The expressive slow spatial spring in the Material specification.
151+
///
152+
/// It has a stiffness of 200.0 and a damping ratio of 0.8.
153+
///
154+
/// See also:
155+
///
156+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
157+
static const SpringDescription expressiveSlowSpatial = SpringDescription(
158+
mass: 1.0,
159+
stiffness: 200.0,
160+
damping: 22.627416997969522,
161+
);
162+
163+
/// The expressive default effects spring in the Material specification.
164+
///
165+
/// It has a stiffness of 1600.0 and a damping ratio of 1.0.
166+
///
167+
/// See also:
168+
///
169+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
170+
static const SpringDescription expressiveDefaultEffects = SpringDescription(
171+
mass: 1.0,
172+
stiffness: 1600.0,
173+
damping: 80.0,
174+
);
175+
176+
/// The expressive fast effects spring in the Material specification.
177+
///
178+
/// It has a stiffness of 3800.0 and a damping ratio of 1.0.
179+
///
180+
/// See also:
181+
///
182+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
183+
static const SpringDescription expressiveFastEffects = SpringDescription(
184+
mass: 1.0,
185+
stiffness: 3800.0,
186+
damping: 123.28828005937953,
187+
);
188+
189+
/// The expressive slow effects spring in the Material specification.
190+
///
191+
/// It has a stiffness of 800.0 and a damping ratio of 1.0.
192+
///
193+
/// See also:
194+
///
195+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
196+
static const SpringDescription expressiveSlowEffects = SpringDescription(
197+
mass: 1.0,
198+
stiffness: 800.0,
199+
damping: 56.568542494923804,
200+
);
201+
}

‎packages/material_ui/lib/src/motion.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@
55
import 'package:flutter/animation.dart';
66

77
part 'generated/motion_defaults_m3.g.dart';
8+
part 'generated/motion_defaults_m3e.g.dart';
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds `Springs`, the Material 3 Expressive spring tokens for the standard and expressive motion schemes.
3+
version: minor
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'dart:math' as math;
6+
7+
import 'package:flutter_test/flutter_test.dart';
8+
import 'package:material_ui/material_ui.dart';
9+
10+
void main() {
11+
test('Springs exposes standard spring tokens', () {
12+
expect(Springs.standardDefaultSpatial, _springDescription(stiffness: 700.0, dampingRatio: 0.9));
13+
expect(Springs.standardFastSpatial, _springDescription(stiffness: 1400.0, dampingRatio: 0.9));
14+
expect(Springs.standardSlowSpatial, _springDescription(stiffness: 300.0, dampingRatio: 0.9));
15+
expect(
16+
Springs.standardDefaultEffects,
17+
_springDescription(stiffness: 1600.0, dampingRatio: 1.0),
18+
);
19+
expect(Springs.standardFastEffects, _springDescription(stiffness: 3800.0, dampingRatio: 1.0));
20+
expect(Springs.standardSlowEffects, _springDescription(stiffness: 800.0, dampingRatio: 1.0));
21+
});
22+
23+
test('Springs exposes expressive spring tokens', () {
24+
expect(
25+
Springs.expressiveDefaultSpatial,
26+
_springDescription(stiffness: 380.0, dampingRatio: 0.8),
27+
);
28+
expect(Springs.expressiveFastSpatial, _springDescription(stiffness: 800.0, dampingRatio: 0.6));
29+
expect(Springs.expressiveSlowSpatial, _springDescription(stiffness: 200.0, dampingRatio: 0.8));
30+
expect(
31+
Springs.expressiveDefaultEffects,
32+
_springDescription(stiffness: 1600.0, dampingRatio: 1.0),
33+
);
34+
expect(Springs.expressiveFastEffects, _springDescription(stiffness: 3800.0, dampingRatio: 1.0));
35+
expect(Springs.expressiveSlowEffects, _springDescription(stiffness: 800.0, dampingRatio: 1.0));
36+
});
37+
}
38+
39+
Matcher _springDescription({required double stiffness, required double dampingRatio}) {
40+
return isA<SpringDescription>()
41+
.having((SpringDescription spring) => spring.mass, 'mass', 1.0)
42+
.having((SpringDescription spring) => spring.stiffness, 'stiffness', stiffness)
43+
.having(
44+
(SpringDescription spring) => spring.damping,
45+
'damping',
46+
moreOrLessEquals(2 * dampingRatio * math.sqrt(stiffness)),
47+
);
48+
}

‎packages/material_ui/tool/gen_defaults/bin/gen_defaults.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ Future<void> main(List<String> args) async {
101101
const ListTileTemplateM3().generateFile(verbose: verbose);
102102
const MenuTemplateM3().generateFile(verbose: verbose);
103103
const MotionTemplateM3().generateFile(verbose: verbose);
104+
const MotionTemplateM3E().generateFile(verbose: verbose);
104105
const NavigationBarTemplateM3().generateFile(verbose: verbose);
105106
const NavigationDrawerTemplateM3().generateFile(verbose: verbose);
106107
const NavigationRailTemplateM3().generateFile(verbose: verbose);

‎packages/material_ui/tool/gen_defaults/templates/motion_template.dart‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22
// Use of this source code is governed by a BSD-style license that can be
33
// found in the LICENSE file.
44

5+
import 'dart:math' as math;
6+
57
import '../data/cubic_struct.dart';
68
import '../data/motion.dart';
9+
import '../data/motion_expressive.dart';
710
import 'template.dart';
811

912
class MotionTemplateM3 extends TokenTemplateM3 {
@@ -92,3 +95,97 @@ ${_easingCurveTokenString('legacy', TokenMotion.easingLegacy).trimRight()}
9295
}
9396
''';
9497
}
98+
99+
class MotionTemplateM3E extends TokenTemplateM3E {
100+
const MotionTemplateM3E();
101+
102+
@override
103+
String get name => 'Motion';
104+
105+
@override
106+
String get parentFilePath => 'motion.dart';
107+
108+
@override
109+
String get className => '';
110+
111+
// The same as SpringDescription.withDampingRatio with a mass of 1.0. That
112+
// constructor isn't const, so the generated constants store the result.
113+
double _damping(double dampingRatio, double stiffness) =>
114+
dampingRatio * 2.0 * math.sqrt(stiffness);
115+
116+
String _springDescriptionTokenString({
117+
required String tokenName,
118+
required double dampingRatio,
119+
required double stiffness,
120+
}) {
121+
final String tokenDescription = tokenName.replaceAllMapped(
122+
RegExp('[A-Z]'),
123+
(Match match) => ' ${match.group(0)!.toLowerCase()}',
124+
);
125+
final double damping = _damping(dampingRatio, stiffness);
126+
return '''
127+
/// The $tokenDescription spring in the Material specification.
128+
///
129+
/// It has a stiffness of $stiffness and a damping ratio of $dampingRatio.
130+
///
131+
/// See also:
132+
///
133+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
134+
static const SpringDescription $tokenName = SpringDescription(mass: 1.0, stiffness: $stiffness, damping: $damping);
135+
''';
136+
}
137+
138+
@override
139+
String generateContents(String className) =>
140+
'''
141+
/// The set of springs in the Material specification.
142+
///
143+
/// Material 3 Expressive motion uses springs, grouped into two motion schemes.
144+
/// The standard scheme eases into place with minimal bounce, and suits more
145+
/// utilitarian products. The expressive scheme overshoots and bounces into
146+
/// place, and suits hero moments and key interactions.
147+
///
148+
/// Each scheme has springs for two types of motion, in three speeds: default,
149+
/// fast, and slow.
150+
///
151+
/// * Spatial springs animate movement, such as position, size, rotation, and
152+
/// corner radius.
153+
/// * Effects springs animate properties that shouldn't overshoot, such as
154+
/// color and opacity.
155+
///
156+
/// Most motion should use the default speed. Smaller elements can use the fast
157+
/// speed, and larger elements can use the slow speed.
158+
///
159+
/// Material spring tokens define a stiffness and a damping ratio, but no
160+
/// mass. The Material token named `damping` is the damping ratio (ζ), not
161+
/// [SpringDescription.damping]. Each constant is the same as
162+
/// [SpringDescription.withDampingRatio] with a mass of 1.0 and the token's
163+
/// stiffness and damping ratio, so its damping is
164+
/// `ratio * 2.0 * sqrt(stiffness)`. For example, [standardDefaultSpatial] has
165+
/// a damping of `${TokenMotion.springDefaultSpatialDamping} * 2.0 * sqrt(${TokenMotion.springDefaultSpatialStiffness})`, about ${_damping(TokenMotion.springDefaultSpatialDamping, TokenMotion.springDefaultSpatialStiffness).toStringAsFixed(2)}.
166+
///
167+
/// Use them with a `SpringSimulation`, for example through
168+
/// [AnimationController.animateWith].
169+
///
170+
/// See also:
171+
///
172+
/// * [Durations] and [Easing], which are the Material tokens for curve-based
173+
/// animations.
174+
/// * [M3 guidelines: Motion physics system](https://m3.material.io/styles/motion/overview/how-it-works)
175+
/// * [M3 guidelines: Spring tokens](https://m3.material.io/styles/motion/overview/specs)
176+
abstract final class Springs {
177+
${_springDescriptionTokenString(tokenName: 'standardDefaultSpatial', dampingRatio: TokenMotion.springDefaultSpatialDamping, stiffness: TokenMotion.springDefaultSpatialStiffness)}
178+
${_springDescriptionTokenString(tokenName: 'standardFastSpatial', dampingRatio: TokenMotion.springFastSpatialDamping, stiffness: TokenMotion.springFastSpatialStiffness)}
179+
${_springDescriptionTokenString(tokenName: 'standardSlowSpatial', dampingRatio: TokenMotion.springSlowSpatialDamping, stiffness: TokenMotion.springSlowSpatialStiffness)}
180+
${_springDescriptionTokenString(tokenName: 'standardDefaultEffects', dampingRatio: TokenMotion.springDefaultEffectsDamping, stiffness: TokenMotion.springDefaultEffectsStiffness)}
181+
${_springDescriptionTokenString(tokenName: 'standardFastEffects', dampingRatio: TokenMotion.springFastEffectsDamping, stiffness: TokenMotion.springFastEffectsStiffness)}
182+
${_springDescriptionTokenString(tokenName: 'standardSlowEffects', dampingRatio: TokenMotion.springSlowEffectsDamping, stiffness: TokenMotion.springSlowEffectsStiffness)}
183+
${_springDescriptionTokenString(tokenName: 'expressiveDefaultSpatial', dampingRatio: TokenMotionExpressive.springDefaultSpatialDamping, stiffness: TokenMotionExpressive.springDefaultSpatialStiffness)}
184+
${_springDescriptionTokenString(tokenName: 'expressiveFastSpatial', dampingRatio: TokenMotionExpressive.springFastSpatialDamping, stiffness: TokenMotionExpressive.springFastSpatialStiffness)}
185+
${_springDescriptionTokenString(tokenName: 'expressiveSlowSpatial', dampingRatio: TokenMotionExpressive.springSlowSpatialDamping, stiffness: TokenMotionExpressive.springSlowSpatialStiffness)}
186+
${_springDescriptionTokenString(tokenName: 'expressiveDefaultEffects', dampingRatio: TokenMotionExpressive.springDefaultEffectsDamping, stiffness: TokenMotionExpressive.springDefaultEffectsStiffness)}
187+
${_springDescriptionTokenString(tokenName: 'expressiveFastEffects', dampingRatio: TokenMotionExpressive.springFastEffectsDamping, stiffness: TokenMotionExpressive.springFastEffectsStiffness)}
188+
${_springDescriptionTokenString(tokenName: 'expressiveSlowEffects', dampingRatio: TokenMotionExpressive.springSlowEffectsDamping, stiffness: TokenMotionExpressive.springSlowEffectsStiffness).trimRight()}
189+
}
190+
''';
191+
}

0 commit comments

Comments
 (0)