Skip to content

Commit b99325b

Browse files
authored
[material_ui] Add a README and placeholders for migrating gen_defaults templates (flutter#12714)
Work towards flutter#191088 **Ports over flutter/packages#12220 which landed on the `m3e_migration` feature branch.** ### Original PR description Work towards flutter#187899 * Adds a README on how to migrate the gen_defaults templates, to be used by contributors or agents. * Adds placeholders (referenced in README) for templates to prevent merge conflicts while migrating. ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent e71317b commit b99325b

3 files changed

Lines changed: 394 additions & 1 deletion

File tree

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,98 @@
1212

1313
import 'package:args/args.dart';
1414

15+
// import '../templates/action_chip_template.dart';
1516
import '../templates/app_bar_template.dart';
1617

18+
// import '../templates/badge_template.dart';
19+
// import '../templates/banner_template.dart';
20+
// import '../templates/bottom_app_bar_template.dart';
21+
// import '../templates/bottom_sheet_template.dart';
22+
// import '../templates/button_template.dart';
23+
// import '../templates/card_template.dart';
24+
// import '../templates/checkbox_template.dart';
25+
// import '../templates/chip_template.dart';
26+
// import '../templates/color_scheme_template.dart';
27+
// import '../templates/date_picker_template.dart';
28+
// import '../templates/dialog_template.dart';
29+
// import '../templates/divider_template.dart';
30+
// import '../templates/drawer_template.dart';
31+
// import '../templates/expansion_tile_template.dart';
32+
// import '../templates/fab_template.dart';
33+
// import '../templates/filter_chip_template.dart';
34+
// import '../templates/icon_button_template.dart';
35+
// import '../templates/input_chip_template.dart';
36+
// import '../templates/input_decorator_template.dart';
37+
// import '../templates/list_tile_template.dart';
38+
// import '../templates/menu_template.dart';
39+
// import '../templates/motion_template.dart';
40+
// import '../templates/navigation_bar_template.dart';
41+
// import '../templates/navigation_drawer_template.dart';
42+
// import '../templates/navigation_rail_template.dart';
43+
// import '../templates/popup_menu_template.dart';
44+
// import '../templates/progress_indicator_template.dart';
45+
// import '../templates/radio_template.dart';
46+
// import '../templates/range_slider_template.dart';
47+
// import '../templates/search_bar_template.dart';
48+
// import '../templates/search_view_template.dart';
49+
// import '../templates/segmented_button_template.dart';
50+
// import '../templates/slider_template.dart';
51+
// import '../templates/snackbar_template.dart';
52+
// import '../templates/surface_tint_template.dart';
53+
// import '../templates/switch_template.dart';
54+
// import '../templates/tabs_template.dart';
55+
// import '../templates/text_field_template.dart';
56+
// import '../templates/time_picker_template.dart';
57+
// import '../templates/typography_template.dart';
58+
1759
Future<void> main(List<String> args) async {
1860
// Parse arguments
1961
final parser = ArgParser();
2062
parser.addFlag('verbose', abbr: 'v', help: 'Enable verbose output', negatable: false);
2163
final ArgResults argResults = parser.parse(args);
2264
// TODO(elliette): Add token logger when verbose flag is used.
2365
final verbose = argResults['verbose'] as bool;
66+
67+
// const ActionChipTemplateM3().generateFile(verbose: verbose);
2468
const AppBarTemplateM3().generateFile(verbose: verbose);
69+
// const BadgeTemplateM3().generateFile(verbose: verbose);
70+
// const BannerTemplateM3().generateFile(verbose: verbose);
71+
// const BottomAppBarTemplateM3().generateFile(verbose: verbose);
72+
// const BottomSheetTemplateM3().generateFile(verbose: verbose);
73+
// const ButtonTemplateM3().generateFile(verbose: verbose);
74+
// const CardTemplateM3().generateFile(verbose: verbose);
75+
// const CheckboxTemplateM3().generateFile(verbose: verbose);
76+
// const ChipTemplateM3().generateFile(verbose: verbose);
77+
// const ColorSchemeTemplateM3().generateFile(verbose: verbose);
78+
// const DatePickerTemplateM3().generateFile(verbose: verbose);
79+
// const DialogTemplateM3().generateFile(verbose: verbose);
80+
// const DividerTemplateM3().generateFile(verbose: verbose);
81+
// const DrawerTemplateM3().generateFile(verbose: verbose);
82+
// const ExpansionTileTemplateM3().generateFile(verbose: verbose);
83+
// const FabTemplateM3().generateFile(verbose: verbose);
84+
// const FilterChipTemplateM3().generateFile(verbose: verbose);
85+
// const IconButtonTemplateM3().generateFile(verbose: verbose);
86+
// const InputChipTemplateM3().generateFile(verbose: verbose);
87+
// const InputDecoratorTemplateM3().generateFile(verbose: verbose);
88+
// const ListTileTemplateM3().generateFile(verbose: verbose);
89+
// const MenuTemplateM3().generateFile(verbose: verbose);
90+
// const MotionTemplateM3().generateFile(verbose: verbose);
91+
// const NavigationBarTemplateM3().generateFile(verbose: verbose);
92+
// const NavigationDrawerTemplateM3().generateFile(verbose: verbose);
93+
// const NavigationRailTemplateM3().generateFile(verbose: verbose);
94+
// const PopupMenuTemplateM3().generateFile(verbose: verbose);
95+
// const ProgressIndicatorTemplateM3().generateFile(verbose: verbose);
96+
// const RadioTemplateM3().generateFile(verbose: verbose);
97+
// const RangeSliderTemplateM3().generateFile(verbose: verbose);
98+
// const SearchBarTemplateM3().generateFile(verbose: verbose);
99+
// const SearchViewTemplateM3().generateFile(verbose: verbose);
100+
// const SegmentedButtonTemplateM3().generateFile(verbose: verbose);
101+
// const SliderTemplateM3().generateFile(verbose: verbose);
102+
// const SnackbarTemplateM3().generateFile(verbose: verbose);
103+
// const SurfaceTintTemplateM3().generateFile(verbose: verbose);
104+
// const SwitchTemplateM3().generateFile(verbose: verbose);
105+
// const TabsTemplateM3().generateFile(verbose: verbose);
106+
// const TextFieldTemplateM3().generateFile(verbose: verbose);
107+
// const TimePickerTemplateM3().generateFile(verbose: verbose);
108+
// const TypographyTemplateM3().generateFile(verbose: verbose);
25109
}
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Temporarily Excluded `gen_defaults` Templates and Code
2+
3+
This directory contains the templates and generated code used by the old
4+
`gen_defaults` script in `flutter/flutter`. They are in the process of being
5+
migrated to the new `gen_defaults` script. Please see
6+
https://github.com/flutter/flutter/issues/187899.
7+
8+
## Instructions for migrating
9+
10+
In these instructions, placeholders are used for the component name. Please substitute them as follows, using "Icon Button" as an example:
11+
- `{{COMPONENT_NAME}}`: the snake_case name (e.g., `icon_button`).
12+
- `ComponentName`: the PascalCase name (e.g., `IconButton`).
13+
- `Component Name`: the title case name (e.g., `Icon Button`).
14+
15+
> Currently all `gen_defaults` migration PRs should be branched off of and rebased against the `m3e_migration` branch, not `main`.
16+
17+
> Please only format the files you edit.
18+
19+
1. Select an unmigrated component listed in https://github.com/flutter/flutter/issues/187899.
20+
21+
2. Move the respective template and generated code for that template out of `temporarily_excluded/`:
22+
23+
From the `packages/material_ui` directory, run:
24+
25+
```bash
26+
mv tool/gen_defaults/temporarily_excluded/templates/{{COMPONENT_NAME}}_template.dart tool/gen_defaults/templates/{{COMPONENT_NAME}}_template.dart
27+
mv tool/gen_defaults/temporarily_excluded/generated/{{COMPONENT_NAME}}_defaults.g.dart lib/src/generated/{{COMPONENT_NAME}}_defaults_m3.g.dart
28+
```
29+
30+
3. Commit the file moves. This will allow us to review the changes on the PR.
31+
**Do not skip this step!**
32+
33+
```bash
34+
git add -A
35+
git commit -m "Move template/generated code out of temporarily_excluded directory"
36+
```
37+
38+
4. Locate the respective component file that contains the generated code in `packages/material_ui/lib/src`.
39+
Mark it as the parent file, and delete the generated code.
40+
41+
Add this line after all import statements:
42+
43+
```dart
44+
part 'generated/{{COMPONENT_NAME}}_defaults_m3.g.dart';
45+
```
46+
47+
Delete the generated code, including the headers:
48+
49+
```dart
50+
// BEGIN GENERATED TOKEN PROPERTIES - ComponentName
51+
52+
// Do not edit by hand. The code between the "BEGIN GENERATED" and
53+
// "END GENERATED" comments are generated from data in the Material
54+
// Design token database by the script:
55+
// dev/tools/gen_defaults/bin/gen_defaults.dart.
56+
57+
// dart format off
58+
class _ComponentNameDefaultsM3 {
59+
...
60+
}
61+
// dart format on
62+
63+
// END GENERATED TOKEN PROPERTIES - ComponentName
64+
```
65+
66+
5. Make the necessary changes to `tool/gen_defaults/templates/{{COMPONENT_NAME}}_template.dart`.
67+
68+
These include:
69+
- Template class extends `TokenTemplateM3` instead of `TokenTemplate`
70+
- `String generate` becomes `String generateContents(String className)`
71+
- Use the provided `className` in `generateContents`.
72+
- Delete the `blockName`, `fileName`, and `tokens` super parameters.
73+
- Add the `name` and `parentFilePath` getters:
74+
75+
```dart
76+
@override
77+
String get name => 'Component Name';
78+
79+
@override
80+
String get parentFilePath => 'component_name.dart';
81+
```
82+
83+
> **[Important]** If the original template used a token instead of a
84+
> hard-coded value, then try to locate the equivalent token in
85+
> `tool/gen_defaults/data`. If no appropriate token can be found, please add
86+
> a TODO comment like: `// TODO(username): Using hard-coded value due to
87+
> missing token`. Hard-coded values should only be used as a last resort.
88+
89+
6. Once the template compiles, uncomment it and its respective import in `packages/material_ui/tool/gen_defaults/bin/gen_defaults.dart`:
90+
91+
```dart
92+
import '../templates/{{COMPONENT_NAME}}_template.dart';
93+
94+
const ComponentNameTemplateM3().generateFile(verbose: verbose);
95+
```
96+
97+
7. From `packages/material_ui`, run `gen_defaults` and compare the generated code.
98+
99+
```bash
100+
dart run tool/gen_defaults/bin/gen_defaults.dart
101+
```
102+
103+
8. Fill in the appropriate test case in `packages/material_ui/tool/gen_defaults/test/gen_defaults_test.dart`.

0 commit comments

Comments
 (0)