Improve the material auto suggest input api:

cissyshi · nshahan · commit db3b7c2e8778 · 2018-09-25T11:20:00.000-07:00
- Allow `selection` input to take selected value for single selection in addition to SelectionModel.
- Expose `selection` output to emit selected value(s) on selection changes.
- Add new example for the simplest case.

PiperOrigin-RevId: 213941461
diff --git a/angular_components/lib/material_input/material_auto_suggest_input.dart b/angular_components/lib/material_input/material_auto_suggest_input.dart
@@ -220,6 +220,8 @@ class MaterialAutoSuggestInputComponent extends MaterialSelectBase
   /// Listener for selection options changes.
   StreamSubscription _optionsListener;
 
+  StreamController _selectionChangeController;
+
   /// Direction of popup scaling.
   ///
   /// Valid values are `x`, `y`, or `null`.
@@ -347,12 +349,37 @@ class MaterialAutoSuggestInputComponent extends MaterialSelectBase
     }
   }
 
-  /// If set, auto suggest will use the supplied observable [SelectionModel]
-  /// object.
+  /// Emits the selected value(s) whenever selection changes.
   ///
-  /// Uses a single selection model by default.
+  /// For single select, it will either be the selected value or null.
+  /// For multi select, it will a list of selected values or an empty list.
+  @Output()
+  Stream get selectionChange {
+    if (_selectionChangeController == null) {
+      _selectionChangeController = new StreamController();
+    }
+    return _selectionChangeController.stream;
+  }
+
+  /// Sets the selected value or selection model for the input.
+  ///
+  /// Accepts either a [SelectionModel], a selected value or null.
+  @Input('selection')
+  set selectionInput(dynamic value) {
+    if (value is SelectionModel) {
+      selection = value;
+    } else if (value == null) {
+      selection.clear();
+    } else {
+      assert(
+          isSingleSelect,
+          'Passing selected value through `selection` input is only supported '
+          'for single select.');
+      selection.select(value);
+    }
+  }
+
   @override
-  @Input()
   set selection(SelectionModel selection) {
     super.selection = selection;
 
@@ -379,6 +406,15 @@ class MaterialAutoSuggestInputComponent extends MaterialSelectBase
               _lastSelectedItem != null ? itemRenderer(_lastSelectedItem) : '';
         }
       }
+      if (_selectionChangeController != null) {
+        if (isSingleSelect) {
+          _selectionChangeController.add(selection.selectedValues.isNotEmpty
+              ? selection.selectedValues.first
+              : null);
+        } else {
+          _selectionChangeController.add(selection.selectedValues);
+        }
+      }
     });
   }
 
diff --git a/angular_components/lib/material_input/material_auto_suggest_input.md b/angular_components/lib/material_input/material_auto_suggest_input.md
@@ -0,0 +1,65 @@
+# Overview
+
+Most selection widgets care about two data points: what is selectable and what is selected.
+
+In ACX selection widgets, what is selectable is represented by the [`SelectionOptions`](https://github.com/dart-lang/angular_components/blob/master/angular_components/lib/model/selection/selection_options.dart) interface, while what is selected is represented by the [`SelectionModel`](https://github.com/dart-lang/angular_components/blob/master/angular_components/lib/model/selection/selection_model.dart)  interface. Material auto select input uses these two interfaces via the `selectionOptions` and `selection` inputs, but additionally it has `inputText` which presents the text the user has entered.
+
+Which input combinations to use for Material Auto Suggest Input depends on your use case.
+
+If you are using the component to accept user entered content, and the list of options is used to assist content entry, you want to use `selectionOptions` and `inputText`. Together with the `inputTextChange` output, you can setup two-way binding for the input text.
+
+HTML:
+```
+<material-auto-suggest-input
+    [selectionOptions]="myOptions"
+    [(inputText)]="myInput"
+    ...>
+</material-auto-suggest-input>
+```
+
+Dart:
+```
+class MyView {
+  final myOptions = ['Foo', 'Bar', 'Baz'];
+  String myInput = 'Bar';
+}
+```
+
+If you are using the component to select one or more items from a list of options, and the input is used for filtering, you want to use `selectionOptions` and `selection`. Together with the `selectionChange` output, you can setup two-way binding for the selected value.
+
+HTML:
+```
+<material-auto-suggest-input
+    [selectionOptions]="myOptions"
+    [(selection)]="mySelection"
+    ...>
+</material-auto-suggest-input>
+```
+
+Dart:
+```
+class MyView {
+  final myOptions = [1, 2, 3];
+  int mySelection = 2;
+}
+```
+
+# The selectionOptions input
+
+The `selectionOptions` input accepts either a `SelectionOptions` class or a generic `List`.
+
+If a `List` is passed, a [`StringSelectionOptions`](https://github.com/dart-lang/angular_components/blob/master/angular_components/lib/model/selection/string_selection_options.dart) will be created with the list and the `ItemRenderer` if specified to support basic filtering.
+
+If you need more advanced features, like grouped options, custom filtering or async search, you could also pass an implementation of `SelectionOptions`.
+
+# The selection input & output
+
+The `selection` input accepts either a `SelectionModel`, a selected value or null.
+
+By default Material Auto Suggest Input uses [`SingleSelectionModel`](https://github.com/dart-lang/angular_components/blob/master/angular_components/lib/src/model/selection/single_selection_model_impl.dart). If a selected value is passed to the `selection` input, this value will be selected by the default selection model. If a null value is passed to the input, the default selection model will clear the selection.
+
+If you need to use a `MultiSelectionModel` or a custom implementation of `SelectionModel`, you could also use the same input.
+
+The `selectionChange` output emits the selected value(s) whenever selection changes. For single select, it will either be the selected value or null. For multi select, it will a list of selected values or an empty list.
+
+For simpler single select use cases, you can use the `[(selection)]` syntax to setup two-way binding for your selected value.
diff --git a/examples/material_input_example/lib/gallery_section_config.dart b/examples/material_input_example/lib/gallery_section_config.dart
@@ -8,7 +8,8 @@ import 'package:angular_components/material_input/material_number_accessor.dart'
 import 'package:angular_components/material_input/material_percent_directive.dart';
 import 'package:angular_gallery_section/annotation/gallery_section_config.dart';
 
-import 'material_auto_suggest_input_demo.dart';
+import 'material_auto_suggest_input_full_demo.dart';
+import 'material_auto_suggest_input_simple_demo.dart';
 import 'material_input_demo.dart';
 import 'material_input_mixins.dart';
 import 'material_input_number_value_accessor_demo.dart';
@@ -19,16 +20,31 @@ import 'material_percent_input_demo.dart';
   docs: [
     MaterialInputComponent,
     MaterialMultilineInputComponent,
+    'package:angular_components/material_input/material_auto_suggest_input.md',
     MaterialAutoSuggestInputComponent,
     MaterialNumberValueAccessor,
     MaterialPercentInputDirective,
   ],
   demos: [
     MaterialInputDemoComponent,
-    MaterialAutoSuggestInputDemoComponent,
+    MaterialAutoSuggestInputSimpleDemoComponent,
+    MaterialAutoSuggestInputFullDemoComponent,
     MaterialPercentInputDemoComponent,
     MaterialInputMixinDemoComponent,
     MaterialInputNumberValueAccessorDemoComponent,
   ],
 )
 class MaterialInputGallerySection {}
+
+@GallerySectionConfig(
+  displayName: 'Material Auto Suggest Input',
+  docs: [
+    'package:angular_components/material_input/material_auto_suggest_input.md',
+    MaterialAutoSuggestInputComponent
+  ],
+  demos: [
+    MaterialAutoSuggestInputSimpleDemoComponent,
+    MaterialAutoSuggestInputFullDemoComponent
+  ],
+)
+class MaterialAutoSuggestInputGallerySection {}
diff --git a/examples/material_input_example/lib/material_auto_suggest_input_full_demo.dart b/examples/material_input_example/lib/material_auto_suggest_input_full_demo.dart
@@ -16,9 +16,8 @@ import 'package:angular_components/model/selection/selection_model.dart';
 import 'package:angular_components/model/selection/selection_options.dart';
 import 'package:angular_components/model/selection/string_selection_options.dart';
 import 'package:angular_components/model/ui/has_factory.dart';
-import 'package:angular_gallery_section/annotation/gallery_section_config.dart';
 
-import 'material_auto_suggest_input_demo.template.dart' as demo;
+import 'material_auto_suggest_input_full_demo.template.dart' as demo;
 
 List<String> _numberNames = <String>[
   'one',
@@ -63,13 +62,8 @@ List<OptionGroup<List<int>>> _optionGroups = <OptionGroup<List<int>>>[
   ], "Even less than 20")
 ];
 
-@GallerySectionConfig(
-  displayName: 'Material Auto Suggest Input',
-  docs: [MaterialAutoSuggestInputComponent],
-  demos: [MaterialAutoSuggestInputDemoComponent],
-)
 @Component(
-  selector: 'material-auto-suggest-input-demo',
+  selector: 'material-auto-suggest-input-full-demo',
   directives: [
     formDirectives,
     MaterialAutoSuggestInputComponent,
@@ -80,11 +74,11 @@ List<OptionGroup<List<int>>> _optionGroups = <OptionGroup<List<int>>>[
     NgFor,
     NgIf,
   ],
-  templateUrl: 'material_auto_suggest_input_demo.html',
+  templateUrl: 'material_auto_suggest_input_full_demo.html',
   styleUrls: ['material_auto_suggest_input_demo.scss.css'],
   preserveWhitespace: true,
 )
-class MaterialAutoSuggestInputDemoComponent {
+class MaterialAutoSuggestInputFullDemoComponent {
   static const _popupPositionsAboveInput = [
     RelativePosition.AdjacentTopLeft,
     RelativePosition.AdjacentTopRight,
diff --git a/examples/material_input_example/lib/material_auto_suggest_input_full_demo.html b/examples/material_input_example/lib/material_auto_suggest_input_full_demo.html
diff --git a/examples/material_input_example/lib/material_auto_suggest_input_simple_demo.dart b/examples/material_input_example/lib/material_auto_suggest_input_simple_demo.dart
@@ -0,0 +1,17 @@
+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:angular/angular.dart';
+import 'package:angular_components/material_input/material_auto_suggest_input.dart';
+
+@Component(
+  selector: 'material-auto-suggest-input-simple-demo',
+  directives: [MaterialAutoSuggestInputComponent],
+  templateUrl: 'material_auto_suggest_input_simple_demo.html',
+  styleUrls: ['material_auto_suggest_input_demo.scss.css'],
+)
+class MaterialAutoSuggestInputSimpleDemoComponent {
+  final values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+  int selectedValue = 1;
+}
diff --git a/examples/material_input_example/lib/material_auto_suggest_input_simple_demo.html b/examples/material_input_example/lib/material_auto_suggest_input_simple_demo.html
@@ -0,0 +1,13 @@
+<!--
+ Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+ for details. All rights reserved. Use of this source code is governed by a
+ BSD-style license that can be found in the LICENSE file.
+-->
+<div class="example">
+  <h2>Simple single selection</h2>
+  <material-auto-suggest-input
+      [(selection)]="selectedValue"
+      [selectionOptions]="values">
+  </material-auto-suggest-input>
+  <div>Selected value: {{selectedValue}}</div>
+</div>
