Better documentation and change SmartSelectOptionGroupHeaderTheme titleStyle to textStyle

Author: davigmacode

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [1.0.3] - 2019-12-12
+
+* Change SmartSelectOptionGroupHeaderTheme titleStyle to textStyle
+* Better documentation
+
 ## [1.0.2] - 2019-12-12
 
 * Move and rename files for better documentation

README.md

@@ -2,8 +2,6 @@
 
 Smart select allows you to easily convert your usual form selects to dynamic pages with grouped radio or checkbox inputs. This widget is inspired by Smart Select component from [Framework7](https://framework7.io/).
 
-To read more about `smart_select`, see the [documentation](https://pub.dev/documentation/smart_select/latest/).
-
 # Features
 
 * Select single or multiple choice
@@ -14,8 +12,17 @@ To read more about `smart_select`, see the [documentation](https://pub.dev/docum
 * Customizable label, value, and group field
 * Filterable option item
 
+# TODO
+
+* Use chip as option item
+* Support dark mode
+
 # Usage
 
+For a complete usage, please see the [example](https://pub.dev/packages/smart_select#-example-tab-).
+
+To read more about classes and other references used by `smart_select`, see the [documentation](https://pub.dev/documentation/smart_select/latest/).
+
 ## Single Choice
 
 ```
@@ -193,37 +200,13 @@ Widget build(BuildContext context) {
 }
 ```
 
-# Reference
-
-| Name | Type | Description |
-|------|------|-------------|
-| SmartSelect | Class | General usage |
-| SmartSelectTile | Class | Default trigger widget |
-| SmartSelectOption | Class | Configure option |
-| SmartSelectState | Class | Current state |
-| SmartSelectTarget | Enum | Modal type to open option |
-| SmartSelectOnChange | Typedef | Callback to handle change of value widget |
-| SmartSelectBuilder | Typedef | Builder for custom trigger widget |
-| SmartSelectOptionItemBuilder | Typedef | Builder for custom option item |
-| SmartSelectOptionItemOnChange | Typedef | Callback to handle stats of each custom option item |
-| SmartSelectOptionDividerBuilder | Typedef | Builder for custom option divider |
-| SmartSelectOptionGroupHeaderBuilder | Typedef | Builder for custom option group header |
-| SmartSelectOptionConfirmationBuilder | Typedef | Builder for custom confirmation widget |
-| SmartSelectOptionHeaderTheme | Class | Configure option header theme |
-| SmartSelectOptionItemTheme | Class | Configure option item theme |
-| SmartSelectOptionGroupHeaderTheme | Class | Configure option group header theme |
-
 # Thanks
 
 * [Framework7](https://framework7.io/)
 
-# TODO
-
-* Use chip as option item
-* Support dark mode
-
 # License
 
+```
 Copyright (c) 2019 Irfan Vigma Taufik
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -242,4 +225,5 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
+```

example/README.md

@@ -59,7 +59,7 @@ class _FeaturesOptionEverythingState extends State<FeaturesOptionEverything> {
             ),
             groupHeaderTheme: SmartSelectOptionGroupHeaderTheme(
               backgroundColor: Colors.blueGrey[600],
-              titleStyle: TextStyle(color: Colors.white)
+              textStyle: TextStyle(color: Colors.white)
             )
           ),
           onChange: (val) => setState(() => _smartphones = val)

example/lib/features_option/option_everything.dart

@@ -127,7 +127,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "1.0.2"
+    version: "1.0.3"
   source_span:
     dependency: transitive
     description:

example/pubspec.lock

@@ -160,14 +160,14 @@ class SmartSelectChoicesState extends State<SmartSelectChoices> {
             style: Theme.of(context)
                 .textTheme
                 .body2
-                .merge(widget.option.groupHeaderTheme.titleStyle),
+                .merge(widget.option.groupHeaderTheme.textStyle),
           ),
           Text(
             _count.toString(),
             style: Theme.of(context)
                 .textTheme
                 .body2
-                .merge(widget.option.groupHeaderTheme.titleStyle),
+                .merge(widget.option.groupHeaderTheme.textStyle),
           ),
         ],
       ),

lib/src/choices.dart

@@ -1,35 +1,94 @@
 import 'package:flutter/material.dart';
 
+/// A builder for custom confirmation widget
 typedef Widget SmartSelectOptionConfirmationBuilder(
     BuildContext context, Function onConfirm);
+
+/// A builder for custom option group header widget
 typedef Widget SmartSelectOptionGroupHeaderBuilder(String _group, int _count);
+
+/// A builder for custom divider widget between option item
 typedef Widget SmartSelectOptionDividerBuilder(BuildContext context, int index);
+
+/// A builder for custom each option item widget
 typedef Widget SmartSelectOptionItemBuilder(
     Map item, bool checked, SmartSelectOptionItemOnChange onChange);
+
+/// Callback to handle change of each custom option item
 typedef void SmartSelectOptionItemOnChange(dynamic value, bool checked);
 
+/// List of option along with its configuration
 class SmartSelectOption {
+
+  /// The list of object option items
   final List items;
+
+  /// Custom property from each option item
+  /// that represent the label
   final String label;
+
+  /// Custom property from each option item
+  /// that represent the value
   final String value;
+
+  /// Custom property from each option item
+  /// that used to grouped option items
   final String groupBy;
+
+  /// Whether show the options list
+  /// as single choice or multiple choice
   final bool isMultiChoice;
+
+  /// Whether the options list modal use header or not
   final bool useHeader;
+
+  /// Whether the option list is filterable or not
   final bool useFilter;
-  final bool useDivider;
+
+  /// Whether the option list need to confirm
+  /// to return the changed value
   final bool useConfirmation;
+
+  /// Whether the option item use divider or not
+  final bool useDivider;
+
+  /// Modal border shape
+  /// used in popup dialog and bottom sheet
   final ShapeBorder shape;
+
+  /// Modal elevation
+  /// used in popup dialog and bottom sheet
   final double elevation;
+
+  /// Modal background color
   final Color backgroundColor;
+
+  /// Custom color of the glowing indicator
+  /// when overscroll the option list
   final Color glowingOverscrollIndicatorColor;
+
+  /// Configure option header theme
   final SmartSelectOptionHeaderTheme headerTheme;
+
+  /// Configure option item theme
   final SmartSelectOptionItemTheme itemTheme;
+
+  /// Configure option group header theme
   final SmartSelectOptionGroupHeaderTheme groupHeaderTheme;
+
+  /// Builder for each custom option item
   final SmartSelectOptionItemBuilder itemBuilder;
+
+  /// Builder for custom divider widget between option item
   final SmartSelectOptionDividerBuilder dividerBuilder;
+
+  /// Builder for custom confirmation widget
   final SmartSelectOptionConfirmationBuilder confirmationBuilder;
+
+  /// Builder for custom option group header widget
   final SmartSelectOptionGroupHeaderBuilder groupHeaderBuilder;
 
+  /// Create list of option along with its configuration
   SmartSelectOption(
     this.items, {
     this.label = 'label',
@@ -53,6 +112,7 @@ class SmartSelectOption {
     this.groupHeaderBuilder,
   });
 
+  /// return a filtered list of options
   List filteredList(String _query) {
     return _query != null
         ? items.where((_item) => _filterTest(_item, _query)).toList()
@@ -74,27 +134,48 @@ class SmartSelectOption {
         : false;
   }
 
+  /// return a list of group keys
   List groupKeys(List _items) {
     Set _groups = Set();
     _items.forEach((_item) => _groups.add(_item[groupBy]));
     return _groups.toList();
   }
 
+  /// return a list of group items
   List groupItems(List _items, String key) {
     return _items.where((_item) => _item[groupBy] == key).toList();
   }
 }
 
+/// Configure modal option header theme
 class SmartSelectOptionHeaderTheme {
+
+  /// Header border shape
   final ShapeBorder shape;
+
+  /// Header elevation
   final double elevation;
+
+  /// Header background color
   final Color backgroundColor;
+
+  /// Header brightness
   final Brightness brightness;
+
+  /// Whether the header title is centered
   final bool centerTitle;
+
+  /// Header text style
+  /// used by title and search field
   final TextStyle textStyle;
+
+  /// Header icon theme
   final IconThemeData iconTheme;
+
+  /// Header actions icon theme
   final IconThemeData actionsIconTheme;
 
+  /// Create a configuration of modal option header theme
   const SmartSelectOptionHeaderTheme({
     this.shape,
     this.elevation = 0.5,
@@ -107,12 +188,22 @@ class SmartSelectOptionHeaderTheme {
   });
 }
 
+/// Configure option item theme
 class SmartSelectOptionItemTheme {
+
+  /// Checked icon color
   final Color checkColor;
+
+  /// Checkbox or radio active color
   final Color activeColor;
+
+  /// Unselected checkbox or radio color
   final Color unselectedColor;
+
+  /// Option item text style
   final TextStyle titleStyle;
 
+  /// Create a configuration of option item theme
   const SmartSelectOptionItemTheme({
     this.checkColor = Colors.white,
     this.activeColor = Colors.black54,
@@ -121,15 +212,25 @@ class SmartSelectOptionItemTheme {
   });
 }
 
+/// Configure option group header theme
 class SmartSelectOptionGroupHeaderTheme {
+
+  /// Group header background color
   final Color backgroundColor;
-  final TextStyle titleStyle;
+
+  /// Group header text style
+  final TextStyle textStyle;
+
+  /// Group header padding
   final EdgeInsetsGeometry padding;
+
+  /// Group header height
   final double height;
 
+  /// Create a configuration of option group header theme
   const SmartSelectOptionGroupHeaderTheme({
     this.backgroundColor = const Color(0xFFECEFF1),
-    this.titleStyle = const TextStyle(color: Colors.black54),
+    this.textStyle = const TextStyle(color: Colors.black54),
     this.padding = const EdgeInsets.symmetric(horizontal: 16.0),
     this.height = 45.0,
   });

lib/src/option.dart

@@ -1,26 +1,46 @@
 import 'package:flutter/material.dart';
 import './option.dart';
 
+/// Target to open option list
 enum SmartSelectTarget { page, popup, sheet }
+
+/// A function that called when the widget value changed
 typedef void SmartSelectOnChange(dynamic value);
+
+/// Builder for custom trigger widget
 typedef Widget SmartSelectBuilder(
     BuildContext context, SmartSelectState state, Function showOptions);
 
+/// Provide an actual state of the SmartSelect
 class SmartSelectState {
+
+  /// The primary content of the widget.
+  /// Used in trigger widget and header option
   final String title;
+
+  /// The current value of the widget.
   final dynamic value;
+
+  /// List of option along with its configuration
   final SmartSelectOption option;
+
+  /// The text displayed when the value is null
   final String placeholder;
 
+  /// Create an actual state
   SmartSelectState({this.title, this.value, this.option, this.placeholder});
 
+  /// return an object or array of object
+  /// that represent the value
   dynamic get valueObject {
     return option.isMultiChoice
         ? option.items.where((x) => value.contains(x[option.value]))
         : option.items
             .firstWhere((x) => x[option.value] == value, orElse: () => null);
   }
 
+  /// return a string or array of string
+  /// that represent the value
   dynamic get valueLabel {
     return option.isMultiChoice
         ? valueObject != null && valueObject.length > 0
@@ -29,12 +49,15 @@ class SmartSelectState {
         : valueObject != null ? valueObject[option.label] : null;
   }
 
+  /// return a string that can be used as display
+  /// when value is null it will display placeholder
   String get valueDisplay {
     return valueLabel != null
         ? option.isMultiChoice ? valueLabel.join(', ') : valueLabel
         : placeholder ?? placeholderDefault;
   }
 
+  /// return a string that used as default placeholder
   String get placeholderDefault {
     return option.isMultiChoice ? 'Select one or more' : 'Select one';
   }