FED-279: Add improved prop forwarding method

doc/new_boilerplate_migration.md

@@ -781,42 +781,117 @@ UiFactory<FooProps> Foo = uiFunction(
 ); 
 ```
 
-#### With Consumed Props
+#### With Prop Forwarding (fka Consumed Props)
 
-Because functional components have no instance that track consumed props, the syntax for passing unconsumed 
-props changes within functional components.
+Because functional components have no instance that track consumed props, the syntax for forwarding props
+changes within functional components.
 
-`UiProps` exposes a field `staticMeta` that can be used to generate an iterable containing props meta for specific mixins. 
-This is similar to accessing `propsMeta` within a class based component. Using the iterable returned from `staticMeta`'s 
-APIs (such as `forMixins`), we can generate unconsumed props and pass them to a child component.
+`UiProps` exposes 2 APIs `getPropsToForward` & `addPropsToForward` that can be used to forward props
+that have not been used to a child component.
 
-This is done like so:
+##### getPropsToForward
+`getPropsToForward` will return a `Map` of props removing the props found in the `exclude` argument.
+`exclude` is optional and will default to a `Set` with the type that `props` is statically typed as,
+this only works with `mixin .. on UiProps` types. If your function component uses a Props `class` then
+you must include an `exclude` argument.
+
+Component with a single props mixin:
 ```dart
 mixin FooPropsMixin on UiProps {
-  String passedProp;
+  String foo;
 }
 
-mixin BarPropsMixin on UiProps {
-  String nonPassedProp;
+UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  return (Bar()
+    // Filter out props declared in FooPropsMixin
+    // (used as the default for `exclude` since that's what `props` is statically typed as)
+    // when forwarding to Bar.
+    ..addAll(props.getPropsToForward())
+  )();
+});
+```
+
+Component with a more than one props mixin:
+```dart
+mixin FooPropsMixin on UiProps {
+  String foo;
 }
 
-class FooBarProps = UiProps with BarPropsMixin, FooPropsMixin;
+class FooProps = UiProps with BarProps, FooPropsMixin;
 
-UiFactory<FooBarProps> FooBar = uiFunction(
-  (props) {
-    final consumedProps = props.staticMeta.forMixins({BarPropsMixin});
+UiFactory<FooProps> Foo = uiFunction((props) {
+  return (Bar()
+    // Filter out props declared in FooPropsMixin when forwarding to Bar.
+    ..addAll(props.getPropsToForward(exclude: {FooPropsMixin}))
+  )();
+});
+```
 
-    return (Foo()..addUnconsumedProps(props, consumedProps))();
-  },
-  _$FooBarConfig, // ignore: undefined_identifier
-); 
+`domOnly` - to forward DOM props only:
+```dart
+mixin FooPropsMixin on UiProps {
+  String foo;
+}
 
-UiFactory<FooPropsMixin> Foo = uiFunction(
-  (props) {
-    return 'foo: ${props.passedProp}'; 
-  },
-  _$FooConfig, // ignore: undefined_identifier
-); 
+UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  return (Dom.div()
+    // Forward only DOM based props & Filter out props declared in FooPropsMixin
+    // (used as the default for `exclude` since that's what `props` is statically typed as)
+    // when forwarding to Bar.
+    ..addAll(props.getPropsToForward(domOnly: true))
+  )();
+});
+```
+
+##### addPropsToForward
+`addPropsToForward` has the same function signature as `getPropsToForward` but is meant to be used with the `UiProps` method `modifyProps`.
+
+Component with a single props mixin:
+```dart
+mixin FooPropsMixin on UiProps {
+  String foo;
+}
+
+UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  return (Bar()
+    // Filter out props declared in FooPropsMixin
+    // (used as the default for `exclude` since that's what `props` is statically typed as)
+    // when forwarding to Bar.
+    ..modifyProps(props.addPropsToForward())
+  )();
+});
+```
+
+Component with a more than one props mixin:
+```dart
+mixin FooPropsMixin on UiProps {
+  String foo;
+}
+
+class FooProps = UiProps with BarProps, FooPropsMixin;
+
+UiFactory<FooProps> Foo = uiFunction((props) {
+  return (Bar()
+    // Filter out props declared in FooPropsMixin when forwarding to Bar.
+    ..modifyProps(props.addPropsToForward(exclude: {FooPropsMixin}))
+  )();
+});
+```
+
+`domOnly` - to forward DOM props only:
+```dart
+mixin FooPropsMixin on UiProps {
+  String foo;
+}
+
+UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  return (Dom.div()
+    // Forward only DOM based props & Filter out props declared in FooPropsMixin
+    // (used as the default for `exclude` since that's what `props` is statically typed as)
+    // when forwarding to Bar.
+    ..modifyProps(props.addPropsToForward(domOnly: true))
+  )();
+});
 ```
 
 #### With UiProps

doc/props_mixin_component_composition.md

@@ -2,9 +2,9 @@
 
 In our core `UiProps` documentation, the pattern of [composing multiple props mixins into a single component props API](../README.md#with-other-mixins) is introduced.
 
-This example builds on that, showing a lightweight example a common use-case for such composition. 
+This example builds on that, showing a lightweight example a common use-case for such composition.
 
-We'll show three components 
+We'll show three components
 
 1. A `Foo` component that has its own props API - and default rendering behavior when rendered standalone.
 1. A `FooBar` component that has its own props API, in addition to the `Foo` props API. This allows consumers to set props declared in `FooPropsMixin`, which will be forwarded to the `Foo` component it renders.
@@ -16,7 +16,7 @@ import 'package:over_react/over_react.dart';
 
 part 'foo.over_react.g.dart';
 
-UiFactory<FooPropsMixin> Foo = 
+UiFactory<FooPropsMixin> Foo =
     castUiFactory(_$Foo); // ignore: undefined_identifier
 
 mixin FooPropsMixin on UiProps {
@@ -35,7 +35,7 @@ class FooComponent extends UiComponent2<FooPropsMixin> {
       ..modifyProps(addUnconsumedDomProps)
       ..className = (forwardingClassNameBuilder()..add('foo'))
     )(
-      'Qux: ', 
+      'Qux: ',
       props.qux.map((n) => n),
       props.children,
     );
@@ -58,7 +58,7 @@ import 'foo.dart';
 
 part 'foo_bar.over_react.g.dart';
 
-UiFactory<FooBarProps> FooBar = 
+UiFactory<FooBarProps> FooBar =
     castUiFactory(_$FooBar); // ignore: undefined_identifier
 
 mixin BarPropsMixin on UiProps {
@@ -69,7 +69,7 @@ mixin BarPropsMixin on UiProps {
 class FooBarProps = UiProps with BarPropsMixin, FooPropsMixin;
 
 class FooBarComponent extends UiComponent2<FooBarProps> {
-  // Only consume the props found within BarPropsMixin, so that any prop values 
+  // Only consume the props found within BarPropsMixin, so that any prop values
   // found in FooPropsMixin get forwarded to the child Foo component via `addUnconsumedProps`.
   @override
   get consumedProps => propsMeta.forMixins({BarPropsMixin});
@@ -122,7 +122,7 @@ Produces the following HTML:
 <div class="foo foo__bar foo__bar--abc">
   Qux: 234
   <div class="foo__bar__bizzles">
-    Bizzles: 
+    Bizzles:
     <ol>
       <li>a</li>
       <li>b</li>
@@ -150,12 +150,9 @@ class FooBazProps = UiProps with BarPropsMixin, FooPropsMixin;
 
 UiFactory<FooBazProps> FooBaz = uiFunction(
   (props) {
-    // Only consume the props found within BarPropsMixin, so that any prop values 
-    // found in FooPropsMixin get forwarded to the child Foo component via `addUnconsumedProps`.
-    final consumedProps = props.staticMeta.forMixins({BarPropsMixin});
-
     return (Foo()
-      ..addUnconsumedProps(props, consumedProps)
+      // Only forward the props not belonging to BarPropsMixin to the child Foo component.
+      ..addAll(props.getPropsToForward(exclude: {BarPropsMixin}))
       ..className = (forwardingClassNameBuilder()..add('foo__baz'))
     )(
       (Dom.div()..className = 'foo__baz__bizzles')(
@@ -165,7 +162,7 @@ UiFactory<FooBazProps> FooBaz = uiFunction(
         ),
       ),
     );
-    
+
     ReactElement _renderBizzleItem(String bizzle) {
       return (Dom.li()..key = bizzle)(bizzle);
     }
@@ -201,7 +198,7 @@ Produces the following HTML:
 <div class="foo foo__baz foo__baz--abc">
   Qux: 234
   <div class="foo__baz__bizzles">
-    Bizzles: 
+    Bizzles:
     <ol>
       <li>a</li>
       <li>b</li>

example/builder/src/functional_consumed_props.dart

@@ -28,14 +28,12 @@ mixin SharedPropsMixin on UiProps {
 class SomeParentProps = UiProps with ParentOnlyPropsMixin, SharedPropsMixin;
 
 UiFactory<SomeParentProps> SomeParent = uiFunction((props) {
-    final consumedProps = props.staticMeta.forMixins({ParentOnlyPropsMixin});
-
     return (
         Dom.div()(
           Dom.div()(
             'The parent prop is: ${props.aParentProp}',
           ),
-          (SomeChild()..addUnconsumedProps(props, consumedProps))(),
+          (SomeChild()..addAll(props.getPropsToForward(exclude: {ParentOnlyPropsMixin})))(),
         )
     );
   },

example/builder/src/new_class_consumed_props.dart

@@ -32,14 +32,12 @@ class SomeParentProps = UiProps with ParentOnlyPropsMixin, SharedPropsMixin;
 class SomeClassParentComponent extends UiComponent2<SomeParentProps> {
   @override
   render() {
-    final meta = props.staticMeta.forMixins({ParentOnlyPropsMixin});
-
     return (
         Dom.div()(
           Dom.div()(
             'The parent prop is: ${props.aParentProp}',
           ),
-          (SomeClassChild()..addUnconsumedProps(props, meta))(),
+          (SomeClassChild()..modifyProps(props.addPropsToForward(exclude: {ParentOnlyPropsMixin})))(),
         )
     );
   }
@@ -58,4 +56,4 @@ class SomeClassChildComponent extends UiComponent2<SomeChildProps> {
         )
     );
   }
-}
+}

lib/src/component_declaration/builder_helpers.dart

@@ -134,6 +134,123 @@ abstract class UiProps extends component_base.UiProps with GeneratedClass {
   @toBeGenerated PropsMetaCollection get staticMeta => throw UngeneratedError(member: #meta);
 }
 
+/// Helper static extension methods to make forwarding props easier.
+extension PropsToForward<T extends UiProps> on T {
+
+  /// Returns a copy of this instance's props excluding the keys found in [exclude].
+  ///
+  /// [exclude] should be a `Set` of PropsMixin `Type`s.
+  /// If [exclude] is not set, it defaults to using the current instance's Type.
+  ///
+  /// __Example:__
+  ///
+  /// Component with a single props mixin:
+  /// ```dart
+  /// mixin FooPropsMixin on UiProps {
+  ///   String foo;
+  /// }
+  ///
+  /// UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  ///   return (Bar()
+  ///     // Filter out props declared in FooPropsMixin
+  ///     // (used as the default for `exclude` since that's what `props` is statically typed as)
+  ///     // when forwarding to Bar.
+  ///     ..addAll(props.getPropsToForward())
+  ///   )();
+  /// });
+  /// ```
+  ///
+  /// Component with a more than one props mixin:
+  /// ```dart
+  /// mixin FooPropsMixin on UiProps {
+  ///   String foo;
+  /// }
+  /// class FooProps = UiProps with BarProps, FooPropsMixin;
+  ///
+  /// UiFactory<FooProps> Foo = uiFunction((props) {
+  ///   return (Bar()
+  ///     // Filter out props declared in FooPropsMixin when forwarding to Bar.
+  ///     ..addAll(props.getPropsToForward(exclude: {FooPropsMixin}))
+  ///   )();
+  /// });
+  /// ```
+  ///
+  /// To only add DOM props, use the [domOnly] named argument.
+  ///
+  /// Related: `UiComponent2`'s `addUnconsumedProps`
+  Map getPropsToForward({Set<Type> exclude, bool domOnly = false}) {
+    return _propsToForward(exclude: exclude, domOnly: domOnly, propsToUpdate: {});
+  }
+
+  /// A utility function to be used with `modifyProps` to add props excluding the keys found in [exclude].
+  ///
+  /// [exclude] should be a `Set` of PropsMixin `Type`s.
+  /// If [exclude] is not set, it defaults to using the current instance's Type.
+  ///
+  /// __Example:__
+  ///
+  /// Component with a single props mixin:
+  /// ```dart
+  /// mixin FooPropsMixin on UiProps {
+  ///   String foo;
+  /// }
+  ///
+  /// UiFactory<FooPropsMixin> Foo = uiFunction((props) {
+  ///   return (Bar()
+  ///     // Filter out props declared in FooPropsMixin
+  ///     // (used as the default for `exclude` since that's what `props` is statically typed as)
+  ///     // when forwarding to Bar.
+  ///     ..modifyProps(props.addPropsToForward())
+  ///   )();
+  /// });
+  /// ```
+  ///
+  /// Component with a more than one props mixin:
+  /// ```dart
+  /// mixin FooPropsMixin on UiProps {
+  ///   String foo;
+  /// }
+  /// class FooProps = UiProps with BarProps, FooPropsMixin;
+  ///
+  /// UiFactory<FooProp> Foo = uiFunction((props) {
+  ///   return (Bar()
+  ///     // Filter out props declared in FooPropsMixin when forwarding to Bar.
+  ///     ..modifyProps(props.addPropsToForward(exclude: {FooPropsMixin}))
+  ///   )();
+  /// });
+  /// ```
+  ///
+  /// To only add DOM props, use the [domOnly] named argument.
+  ///
+  /// Related: `UiComponent2`'s `addUnconsumedProps`
+  PropsModifier addPropsToForward({Set<Type> exclude, bool domOnly = false}) {
+    return (Map<dynamic, dynamic> props) {
+      _propsToForward(exclude: exclude, domOnly: domOnly, propsToUpdate: props);
+    };
+  }
+
+  Map _propsToForward({Set<Type> exclude, bool domOnly = false, Map propsToUpdate}) {
+    Iterable<PropsMeta> consumedProps = [];
+    try {
+      consumedProps = staticMeta.forMixins(exclude ?? {T}).toList();
+    } catch(_) {
+      // If [domOnly] is `true`, it is alright for the meta lookup to fail, otherwise throw the error.
+      assert(exclude != null, ArgumentError('Could not find props meta for type $T.'
+        ' If this is not a props mixin, you need to specify its mixins as the second argument.  For example:'
+        '\n  ..addAll(props.getPropsToForward(exclude: {${T}Mixin})').message);
+      rethrow;
+    }
+    final consumedPropKeys = consumedProps?.map((consumedProps) => consumedProps.keys);
+    forwardUnconsumedPropsV2(
+      props,
+      propsToUpdate: propsToUpdate,
+      keySetsToOmit: consumedPropKeys,
+      onlyCopyDomProps: domOnly,
+    );
+    return propsToUpdate;
+  }
+}
+
 /// A [dart.collection.MapView]-like class with strongly-typed getters/setters for React state.
 ///
 /// To be used with the over_react builder to generate concrete state implementations