Allow clients to configure a way to segment results to option groups.

Previously, search results were set as a single option group. This allows us to bucket search results into distinct option groups.

1) Why do we *really* need this?
We are running into use cases where search results need to be bucketed into option groups. (e.g. agencies vs companies). We feel it's kind of silly to bootstrap our own SearchDataSourceProvider just to support this.

2) Can't we just sort the items and avoid the need for this UX?
No. UX specifically wants to visually bucket the items into distinct groups. OptionGroups are what we need.

PiperOrigin-RevId: 209796557

Author: Googler

lib/model/selection/selection_options.dart

@@ -15,6 +15,9 @@ export 'package:angular_components/src/model/selection/delegating_selection_opti
 part 'package:angular_components/src/model/selection/future_selection_options_impl.dart';
 part 'package:angular_components/src/model/selection/stream_selection_options_impl.dart';
 
+/// An interface for functions that segment [items] into option groups.
+typedef OptionGroupMapper<T> = List<OptionGroup<T>> Function(Iterable<T> items);
+
 /// A collection of options with an optional label.
 class OptionGroup<T> extends LabeledList<T> {
   String get emptyLabel => _emptyLabelFcn != null ? _emptyLabelFcn() : null;
@@ -29,6 +32,8 @@ class OptionGroup<T> extends LabeledList<T> {
       [LabelFunction labelFcn, this._emptyLabelFcn])
       : super.withLabelFunction(items, labelFcn);
 
+  /// An option group with a label is recommended when multiple option groups
+  /// exist in a selection list.
   OptionGroup.withLabel(List<T> items, [String label, String emptyLabel])
       : _emptyLabelFcn = emptyLabel != null ? (() => emptyLabel) : null,
         super.withLabel(items, label);