Merge pull request #486 from Workiva/new_boilerplate_wip

RM-68469 RM-68468 Release over_react 3.5.0
Workiva · Apr 15, 2020 · dc7b136 · dc7b136
2 parents d8195eb + 08cea05
commit dc7b136
Show file tree

Hide file tree

Showing 596 changed files with 34,373 additions and 10,142 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -8,6 +8,7 @@ before_script:
   - pub run build_runner build --delete-conflicting-outputs
   - git diff --exit-code
   - pub run dart_dev analyze
+  - pub run dart_dev format --check
   - pub run dependency_validator --no-fatal-pins -i analyzer,build_runner,build_web_compilers,built_value_generator,front_end
 
 script:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # OverReact Changelog
 
+## [3.5.0](https://github.com/Workiva/over_react/compare/3.4.1...3.5.0)
+- Introduce new and improved component boilerplate syntax 🎉
+
+    ![side-by-side comparison of old and new boilerplate for a simple component](doc/new-boilerplate-side-by-side.png)
+
+    See our [migration guide](https://github.com/Workiva/over_react/blob/master/doc/new_boilerplate_migration.md) for more information around these changes, including why we made them and how to convert existing components to use thew new syntax.
+
+    The existing boilerplate syntax will be deprecated in a future release. 
+
+- [#469] Throw helpful error when `connect`, `connectFlux`, and `forwardRef` are passed an invalid component. 
+
 ## [3.4.1](https://github.com/Workiva/over_react/compare/3.4.0...3.4.1)
 - [#468] Allow redux.dart version 4
 

diff --git a/README.md b/README.md
@@ -32,7 +32,6 @@
 * __[Building custom components](#building-custom-components)__
     * __[Component Boilerplates](#component-boilerplate-templates)__
     * __[Component Best Practices](#component-best-practices)__
-    * __[Common Pitfalls](#common-pitfalls)__
 * __[Contributing](#contributing)__
 
 [](#__START_EMBEDDED_README__)
@@ -47,6 +46,7 @@ To further document APIs that can be found in OverReact, the [doc](doc) director
 - Migration guides from older versions of over_react:
     - [Dart2 Migration](doc/dart2_migration.md): Documentation on the Dart 2 builder updates and how to transition componentry to Dart 2.
     - [UiComponent2 Transition](doc/ui_component2_transition.md): A document discussing the changes between `UiComponent` and `UiComponent2`, as well as how to migrate.
+    - [New Boilerplate Migration](doc/new_boilerplate_migration.md): Documentation on the changes to the component boilerplate, as well as how to migrate to the new boilerplate.
 
 ## Using it in your project
 
@@ -99,9 +99,6 @@ mount / render it into the HTML element you created in step 3.
     import 'package:over_react/over_react.dart';
 
     main() {
-      // Initialize React within our Dart app
-      setClientConfiguration();
-
       // Mount / render your component.
       react_dom.render(Foo()(), querySelector('#react_mount_point'));
     }
@@ -170,7 +167,6 @@ __`UiFactory` is a function__ that returns a new instance of a
 [`UiComponent`](#uicomponent2)’s [`UiProps`](#uiprops) class.
 
 ```dart
-@Factory()
 UiFactory<FooProps> Foo = _$Foo;
 ```
 
@@ -186,30 +182,42 @@ __`UiProps` is a Map class__ that adds statically-typed getters and setters for
 It can also be invoked as a function, serving as a builder for its analogous component.
 
 ```dart
-@Props()
-class _$FooProps extends UiProps {
+mixin FooProps on UiProps {
+  // ...
+}
+```
+* Note: The [builder] will make the concrete getters and setters available in a generated class. To mix props classes together, the mixin class should be used rather than the generated props class. See [With other mixins](#with-other-mixins) below for more information.
+
+&nbsp;
+
+#### With other mixins
+
+__To compose props mixin classes__, create a class alias that uses `UiProps` as the base and mix in props mixins. The generated props implementation will then use it as the base class and implement the generated version of those props mixins.
+```dart
+UiFactory<FooProps> Foo = _$Foo;
+
+mixin FooPropsMixin on UiProps {
+  // ...
+}
+
+class FooProps = UiProps with FooPropsMixin, BarPropsMixin;
+
+class FooComponent extends UiComponent2<FooProps> {
   // ...
 }
 ```
-* Note: The [builder] will make the concrete getters and setters available in a generated class which has the same name
-as the class annotated with `@Props()`, but without the `_$` prefix (which would be `FooProps` in the above code).
-The generated class will also have the same API. So, consumers who wish to extend the functionality of `_$FooProps` should
-extend the generated version, `FooProps`.
 
 &nbsp;
 
 #### UiProps as a Map
 
 ```dart
-@Factory()
 UiFactory<FooProps> Foo = _$Foo;
 
-@Props()
-class _$FooProps extends UiProps {
+mixin FooProps on UiProps {
   String color;
 }
 
-@Component2()
 class FooComponent extends UiComponent2<FooProps> {
   // ...
 }
@@ -239,11 +247,9 @@ void baz() {
 #### UiProps as a builder
 
 ```dart
-@Factory()
 UiFactory<FooProps> Foo = _$Foo;
 
-@Props()
-class _$FooProps extends UiProps {
+mixin FooProps on UiProps {
   String color;
 }
 
@@ -285,17 +291,13 @@ __`UiState` is a Map class__ _(just like `UiProps`)_ that adds statically-typed
 for each React component state property.
 
 ```dart
-@State()
-class _$FooState extends UiState {
+mixin FooState on UiState {
   // ...
 }
 ```
 
 > UiState is optional, and won’t be used for every component.
-* Note: The [builder] will make the concrete getters and setters available in a generated class which has the same name
-as the class annotated with `@State()`, but without the `_$` prefix (which would be `FooState` in the above code).
-The generated class will also have the same API. So, consumers who wish to extend the functionality of `_$FooState` should
-use the generated version, `FooState`.
+* Note: The [builder] will make the concrete getters and setters available in a generated class. To mix state classes together, the mixin class should be used rather than the generated state class. See [With other mixins](#with-other-mixins) above for  more information.
 
 &nbsp;
 
@@ -306,7 +308,6 @@ __`UiComponent2` is a subclass of [`react.Component2`]__, containing lifecycle m
 and rendering logic for components.
 
 ```dart
-@Component2()
 class FooComponent extends UiComponent2<FooProps> {
   // ...
 }
@@ -328,7 +329,6 @@ They are instances of `UiProps` and `UiState`, __which means you don’t need St
 * `typedPropsFactory()` and `typedStateFactory()` are also exposed to conveniently create typed `props` / `state` objects out of any provided backing map.
 
 ```dart
-@Component2()
 class FooComponent extends UiStatefulComponent2<FooProps, FooState> {
   @override
   get defaultProps => (newProps()
@@ -703,17 +703,14 @@ that you get for free from OverReact, you're ready to start building your own cu
     import 'package:over_react/over_react.dart';
     part 'foo_component.over_react.g.dart';
 
-    @Factory()
     UiFactory<FooProps> Foo = _$Foo;
 
-    @Props()
-    class _$FooProps extends UiProps {
+    mixin FooProps on UiProps {
       // Props go here, declared as fields:
       bool isDisabled;
       Iterable<String> items;
     }
 
-    @Component2()
     class FooComponent extends UiComponent2<FooProps> {
       @override
       get defaultProps => (newProps()
@@ -737,23 +734,19 @@ that you get for free from OverReact, you're ready to start building your own cu
     import 'package:over_react/over_react.dart';
     part 'foo_component.over_react.g.dart';
 
-    @Factory()
     UiFactory<BarProps> Bar = _$Bar;
 
-    @Props()
-    class _$BarProps extends UiProps {
+    mixin BarProps on UiProps {
       // Props go here, declared as fields:
       bool isDisabled;
       Iterable<String> items;
     }
 
-    @State()
-    class _$BarState extends UiState {
+    mixin BarState on UiState {
       // State goes here, declared as fields:
       bool isShown;
     }
 
-    @Component2()
     class BarComponent extends UiStatefulComponent2<BarProps, BarState> {
       @override
       get defaultProps => (newProps()
@@ -783,16 +776,15 @@ that you get for free from OverReact, you're ready to start building your own cu
     import 'package:over_react/over_react.dart';
     part 'foo_component.over_react.g.dart';
 
-    @Factory()
     UiFactory<BazProps> Baz = _$Baz;
 
-    @Props()
-    class _$BazProps extends FluxUiProps<BazActions, BazStore> {
+    mixin BazPropsMixin on UiProps {
       // Props go here, declared as fields.
       // `actions` and `store` are already defined for you!
     }
 
-    @Component2()
+    class BazProps = UiProps with FluxUiPropsMixin<BazActions, BazStore>, BazPropsMixin;
+
     class BazComponent extends FluxUiComponent2<BazProps> {
       @override
       get defaultProps => (newProps()
@@ -815,21 +807,21 @@ that you get for free from OverReact, you're ready to start building your own cu
     import 'package:over_react/over_react.dart';
     part 'foo_component.over_react.g.dart';
 
-    @Factory()
     UiFactory<BazProps> Baz = _$Baz;
 
-    @Props()
-    class _$BazProps extends FluxUiProps<BazActions, BazStore> {
+  
+    mixin BazPropsMixin on UiProps {
       // Props go here, declared as fields.
       // `actions` and `store` are already defined for you!
     }
 
-    @State()
-    class _$BazState extends UiState {
+    class BazProps = UiProps with FluxUiPropsMixin<BazActions, BazStore>, BazPropsMixin;
+
+
+    mixin BazState on UiState {
       // State goes here, declared as fields.
     }
 
-    @Component2()
     class BazComponent extends FluxUiStatefulComponent2<BazProps, BazState> {
       @override
       get defaultProps => (newProps()
@@ -869,14 +861,12 @@ another component.
     /// * Similar to [SplitButton].
     ///
     /// See: <https://link-to-any-relevant-documentation>.
-    @Factory()
     UiFactory<DropdownButtonProps> DropdownButton = _$DropdownButton;
     ```
 
   _Bad:_
     ```dart
     /// Component Factory for a dropdown button component.
-    @Factory()
     UiFactory<DropdownButtonProps> DropdownButton = _$DropdownButton;
     ```
 
@@ -891,8 +881,7 @@ and document that value in a comment.
 
   _Good:_
     ```dart
-    @Props()
-    _$DropdownButtonProps extends UiProps {
+    mixin DropdownButtonProps on UiProps {
       /// Whether the [DropdownButton] appears disabled.
       ///
       /// Default: `false`
@@ -907,15 +896,13 @@ and document that value in a comment.
       bool initiallyOpen;
     }
 
-    @State()
-    _$DropdownButtonState extends UiState {
+    mixin DropdownButtonState on UiState {
       /// Whether the [DropdownButton]'s child [DropdownMenu] is open.
       ///
       /// Initial: [DropdownButtonProps.initiallyOpen]
       bool isOpen;
     }
 
-    @Component2()
     DropdownButtonComponent
         extends UiStatefulComponent2<DropdownButtonProps, DropdownButtonState> {
       @override
@@ -933,18 +920,15 @@ and document that value in a comment.
 
   _Bad:_
     ```dart
-    @Props()
-    _$DropdownButtonProps extends UiProps {
+    mixin DropdownButtonProps on UiProps {
       bool isDisabled;
       bool initiallyOpen;
     }
 
-    @State()
-    _$DropdownButtonState extends UiState {
+    mixin DropdownButtonState on UiState {
       bool isOpen;
     }
 
-    @Component2()
     DropdownButtonComponent
         extends UiStatefulComponent2<DropdownButtonProps, DropdownButtonState> {
       // Confusing stuff is gonna happen in here with
@@ -959,8 +943,7 @@ an informative comment.
 
   _Good:_
     ```dart
-    @Props()
-    _$DropdownButtonProps extends UiProps {
+    mixin DropdownButtonProps on UiProps {
       /// Whether the [DropdownButton] appears disabled.
       ///
       /// Default: `false`
@@ -975,8 +958,7 @@ an informative comment.
       bool initiallyOpen;
     }
 
-    @State()
-    _$DropdownButtonState extends UiState {
+    mixin DropdownButtonState on UiState {
       /// Whether the [DropdownButton]'s child [DropdownMenu] is open.
       ///
       /// Initial: [DropdownButtonProps.initiallyOpen]
@@ -986,20 +968,34 @@ an informative comment.
 
   _Bad:_
     ```dart
-    @Props()
-    _$DropdownButtonProps extends UiProps {
+    mixin DropdownButtonProps on UiProps {
       bool isDisabled;
       bool initiallyOpen;
     }
 
-    @State()
-    _$DropdownButtonState extends UiState {
+    mixin DropdownButtonState on UiState {
       bool isOpen;
     }
     ```
 
 &nbsp;
 
+#### Ignore Ungenerated Warnings Project-Wide
+
+To avoid having to add `// ignore: uri_has_not_been_generated` to each 
+component library on the part/import that references generated code, 
+ignore this warning globally within analysis_options.yaml:
+
+```yaml
+ analyzer:
+   errors:
+     uri_has_not_been_generated: ignore 
+```
+
+Alternatively, `include` [workiva_analysis_options](https://github.com/Workiva/workiva_analysis_options)
+which ignores this warning by default.
+
+&nbsp;
 
 ## Contributing
 

diff --git a/analysis_options.yaml b/analysis_options.yaml
@@ -5,6 +5,9 @@ analyzer:
     - _site/**
     - test_fixtures/**
     - app/**
+  errors:
+    missing_required_param: error
+    must_call_super: error
 linter:
   rules:
     # -------------------