Add shorthand options support (#894)

* Move options and value to first two positional arguments

* Add shorthand versions for the options parameter

* Add documentation

* Add js tests

* Simplify example output for tests

* Add shorthand example test

* Add python test for positional args

* Add docs to formatting exceptions

* Update version

* Add demo python app for testing

* Remove julia and R examples

* tidy

Co-authored-by: tcbegley <[email protected]>

Author: glsdown

demo/app.py

@@ -0,0 +1,11 @@
+import dash_bootstrap_components as dbc
+from dash import Dash
+
+app = Dash(external_stylesheets=[dbc.themes.BOOTSTRAP])
+
+test_content = dbc.Alert("Use this as a test playground", color="success")
+
+app.layout = dbc.Container(test_content, className="p-5")
+
+if __name__ == "__main__":
+    app.run_server(debug=True)

docs/components_page/components/__tests__/test_input.py

@@ -33,7 +33,7 @@ def check_input_simple_callbacks(runner):
 # --------------------------------
 
 
-def test_r_input_radio_ckeck(dashr):
+def test_r_input_radio_check(dashr):
     r_app = load_r_app((HERE.parent / "input" / "radio_check.R"), "inputs")
     dashr.start_server(r_app)
     check_input_radio_check_callbacks(dashr)

docs/components_page/components/input.md

@@ -73,6 +73,29 @@ Set `inline=True` to make the radio items or checklists fit next to each other o
 
 {{example:components/input/radio_check_inline.py:inline_inputs}}
 
+## Shorthand options for Select, RadioItems and Checklist
+
+In Python, the options in `Select`, `RadioItems` and `Checklist` components can be specified using more compact syntax. The standard structure is an array of dictionaries with defined keys:
+
+```python
+  options=[
+    {
+      "label": "Label 1",
+      "value": "value_1",
+      ...
+    },
+    {
+      "label": "Label 2",
+      "value": "value_2",
+      ...
+    },
+  ]
+```
+
+This structure is required if you wish to use any of the additional `options` properties such as `disabled`. However, if you want to create a simple component, you can make use of the shorthand options below.
+
+{{example:components/input/short_hand.py:short_hand}}
+
 ## Checked item styles
 
 Use the `input_checked_style`, `inputCheckedClassName`, `label_checked_style` and `labelCheckedClassName` arguments to apply different styles to the labels of checked items.

docs/components_page/components/input/short_hand.py

@@ -0,0 +1,73 @@
+import dash_bootstrap_components as dbc
+from dash import Input, Output, html
+
+# `options` is provided as an array of dictionaries
+checklist = html.Div(
+    [
+        dbc.Checklist(
+            [
+                {"label": "Option 1", "value": 1},
+                {"label": "Option B", "value": 2},
+                {"label": "Option III", "value": 3},
+                {"label": "4", "value": 4},
+            ],
+            [3],
+            id="shorthand-checklist",
+        ),
+    ],
+    className="py-2",
+)
+
+# All items in this list will have the value the same as the label
+select = html.Div(
+    dbc.Select(
+        ["Option 1", "Option B", "Option III", 4],
+        "Option III",
+        id="shorthand-select",
+    ),
+    className="py-2",
+)
+
+# `options` is provided as value: label pairs - value must be a string
+radioitems = html.Div(
+    [
+        dbc.RadioItems(
+            {
+                "1": "Option 1",
+                "2": "Option B",
+                "3": "Option III",
+                "4": 4,
+            },
+            "3",
+            id="shorthand-radio",
+        ),
+    ],
+    className="py-2",
+)
+
+short_hand = html.Div(
+    [
+        dbc.Form([checklist, select, radioitems]),
+        html.P(id="shorthand-output"),
+    ]
+)
+
+
+@app.callback(
+    Output("shorthand-output", "children"),
+    [
+        Input("shorthand-checklist", "value"),
+        Input("shorthand-select", "value"),
+        Input("shorthand-radio", "value"),
+    ],
+)
+def on_form_change(checklist_value, select_value, radio_items_value):
+
+    checklist = ", ".join([str(c) for c in checklist_value])
+
+    output = (
+        f"Checklist: [{checklist}], Selected: {select_value}, ",
+        f"Radio: {radio_items_value}",
+    )
+
+    return output

package-lock.json

@@ -19,6 +19,7 @@ exclude =
     docs/components_page/components/input/simple.py,
     docs/components_page/components/input/radio_check_standalone.py,
     docs/components_page/components/input/radio_check.py,
+    docs/components_page/components/input/short_hand.py,
     docs/components_page/components/input/colorpicker.py,
     docs/components_page/components/input_group/button.py,
     docs/components_page/components/input_group/dropdown.py,

setup.cfg

@@ -3,6 +3,8 @@ import PropTypes from 'prop-types';
 import {append, includes, without} from 'ramda';
 import classNames from 'classnames';
 
+import {sanitizeOptions} from '../../private/util';
+
 /**
  * Checklist is a component that encapsulates several checkboxes.
  * The values and labels of the checklist is specified in the `options`
@@ -113,7 +115,8 @@ const Checklist = props => {
       </div>
     );
   };
-  const items = options.map(option => listItem(option));
+
+  const items = sanitizeOptions(options).map(option => listItem(option));
 
   return (
     <div
@@ -132,47 +135,90 @@ const Checklist = props => {
 
 Checklist.propTypes = {
   /**
-   * The ID of this component, used to identify dash components in callbacks.
-   * The ID needs to be unique across all of the components in an app.
-   */
-  id: PropTypes.string,
-
-  /**
-   * An array of options
+   * The options to display as items in the component. This can be an array
+   * or a dictionary as follows:
+   *
+   * \n1. Array of options where the label and the value are the same thing -
+   * [string|number]
+   *
+   * \n2. An array of options
+   * ```
+   * {
+   *   "label": [string|number],
+   *   "value": [string|number],
+   *   "disabled": [bool] (Optional),
+   *   "input_id": [string] (Optional),
+   *   "label_id": [string] (Optional)
+   * }
+   * ```
+   *
+   * \n3. Simpler `options` representation in dictionary format. The order is not
+   * guaranteed. All values and labels will be treated as strings.
+   * ```
+   * {"value1": "label1", "value2": "label2", ... }
+   * ```
+   * which is equal to
+   * ```
+   * [
+   *   {"label": "label1", "value": "value1"},
+   *   {"label": "label2", "value": "value2"}, ...
+   * ]
+   * ```
    */
-  options: PropTypes.arrayOf(
-    PropTypes.exact({
-      /**
-       * The checkbox's label
-       */
-      label: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
-        .isRequired,
-
-      /**
-       * The value of the checkbox. This value corresponds to the items
-       * specified in the `value` property.
-       */
-      value: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
-        .isRequired,
-
-      /**
-       * If true, this checkbox is disabled and can't be clicked on.
-       */
-      disabled: PropTypes.bool,
-
-      /**
-       * id for this option's input, can be used to attach tooltips or apply
-       * CSS styles
-       */
-      input_id: PropTypes.string,
-
-      /**
-       * id for this option's label, can be used to attach tooltips or apply
-       * CSS styles
-       */
-      label_id: PropTypes.string
-    })
-  ),
+  options: PropTypes.oneOfType([
+    /**
+     * Array of options where the label and the value are the same thing -
+     * [string|number]
+     */
+    PropTypes.arrayOf(
+      PropTypes.oneOfType([PropTypes.string, PropTypes.number])
+    ),
+    /**
+     * Simpler `options` representation in dictionary format. The order is not
+     * guaranteed. All values and labels will be treated as strings.
+     * {`value1`: `label1`, `value2`: `label2`, ... }
+     * which is equal to
+     * [{label: `label1`, value: `value1`}, {label: `label2`, value: `value2`}, ...]
+     */
+    PropTypes.object,
+    /**
+     * An array of options {label: [string|number], value: [string|number]},
+     * an optional disabled field can be used for each option
+     */
+    PropTypes.arrayOf(
+      PropTypes.exact({
+        /**
+         * The checkbox's label
+         */
+        label: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
+          .isRequired,
+
+        /**
+         * The value of the checkbox. This value corresponds to the items
+         * specified in the `value` property.
+         */
+        value: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
+          .isRequired,
+
+        /**
+         * If true, this checkbox is disabled and can't be clicked on.
+         */
+        disabled: PropTypes.bool,
+
+        /**
+         * id for this option's input, can be used to attach tooltips or apply
+         * CSS styles
+         */
+        input_id: PropTypes.string,
+
+        /**
+         * id for this option's label, can be used to attach tooltips or apply
+         * CSS styles
+         */
+        label_id: PropTypes.string
+      })
+    )
+  ]),
 
   /**
    * The currently selected value
@@ -181,6 +227,12 @@ Checklist.propTypes = {
     PropTypes.oneOfType([PropTypes.string, PropTypes.number])
   ),
 
+  /**
+   * The ID of this component, used to identify dash components in callbacks.
+   * The ID needs to be unique across all of the components in an app.
+   */
+  id: PropTypes.string,
+
   /**
    * The class of the container (div)
    */