Merge pull request #2593 from plotly/feature/debounce-time

Feature: dcc.Input accepts a number for its debounce argument

Author: KoolADE85

CHANGELOG.md

@@ -2,6 +2,12 @@
 All notable changes to `dash` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## UNRELEASED
+
+## Fixed
+
+- [#2593](https://github.com/plotly/dash/pull/2593) dcc.Input accepts a number for its debounce argument
+
 ## [2.11.1] - 2023-06-29
 
 ## Fixed

components/dash-core-components/.eslintrc

@@ -117,7 +117,7 @@
     }],
     "no-magic-numbers": ["error", {
       "ignoreArrayIndexes": true,
-      "ignore": [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 100, 10, 16, 0.5, 25]
+      "ignore": [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 100, 10, 16, 0.5, 25, 1000]
     }],
     "no-underscore-dangle": ["off"],
     "no-useless-escape": ["off"]

components/dash-core-components/src/components/Input.react.js

@@ -20,18 +20,28 @@ export default class Input extends PureComponent {
     constructor(props) {
         super(props);
 
+        this.state = {
+            pendingEvent: undefined,
+            value: '',
+        };
+
         this.input = React.createRef();
 
         this.onBlur = this.onBlur.bind(this);
         this.onChange = this.onChange.bind(this);
         this.onEvent = this.onEvent.bind(this);
         this.onKeyPress = this.onKeyPress.bind(this);
+        this.debounceEvent = this.debounceEvent.bind(this);
         this.setInputValue = this.setInputValue.bind(this);
         this.setPropValue = this.setPropValue.bind(this);
     }
 
     UNSAFE_componentWillReceiveProps(nextProps) {
         const {value} = this.input.current;
+        if (this.state.pendingEvent) {
+            // avoid updating the input while awaiting a debounced event
+            return;
+        }
         const valueAsNumber = convert(value);
         this.setInputValue(
             isNil(valueAsNumber) ? value : valueAsNumber,
@@ -121,6 +131,21 @@ export default class Input extends PureComponent {
         } else {
             this.props.setProps({value});
         }
+        this.setState({pendingEvent: undefined});
+    }
+
+    debounceEvent(seconds = 0.5) {
+        const {value} = this.input.current;
+
+        window.clearTimeout(this.state?.pendingEvent);
+        const pendingEvent = window.setTimeout(() => {
+            this.onEvent();
+        }, seconds * 1000);
+
+        this.setState({
+            value,
+            pendingEvent,
+        });
     }
 
     onBlur() {
@@ -129,7 +154,7 @@ export default class Input extends PureComponent {
             n_blur_timestamp: Date.now(),
         });
         this.input.current.checkValidity();
-        return this.props.debounce && this.onEvent();
+        return this.props.debounce === true && this.onEvent();
     }
 
     onKeyPress(e) {
@@ -140,14 +165,22 @@ export default class Input extends PureComponent {
             });
             this.input.current.checkValidity();
         }
-        return this.props.debounce && e.key === 'Enter' && this.onEvent();
+        return (
+            this.props.debounce === true && e.key === 'Enter' && this.onEvent()
+        );
     }
 
     onChange() {
-        if (!this.props.debounce) {
+        const {debounce} = this.props;
+        if (debounce) {
+            if (Number.isFinite(debounce)) {
+                this.debounceEvent(debounce);
+            }
+            if (this.props.type !== 'number') {
+                this.setState({value: this.input.current.value});
+            }
+        } else {
             this.onEvent();
-        } else if (this.props.type !== 'number') {
-            this.setState({value: this.input.current.value});
         }
     }
 }
@@ -188,9 +221,11 @@ Input.propTypes = {
 
     /**
      * If true, changes to input will be sent back to the Dash server only on enter or when losing focus.
-     * If it's false, it will sent the value back on every change.
+     * If it's false, it will send the value back on every change.
+     * If a number, it will not send anything back to the Dash server until the user has stopped
+     * typing for that number of seconds.
      */
-    debounce: PropTypes.bool,
+    debounce: PropTypes.oneOfType([PropTypes.bool, PropTypes.number]),
 
     /**
      * A hint to the user of what can be entered in the control . The placeholder text must not contain carriage returns or line-feeds. Note: Do not use the placeholder attribute instead of a <label> element, their purposes are different. The <label> attribute describes the role of the form element (i.e. it indicates what kind of information is expected), and the placeholder attribute is a hint about the format that the content should take. There are cases in which the placeholder attribute is never displayed to the user, so the form must be understandable without it.

components/dash-core-components/tests/integration/input/conftest.py

@@ -57,3 +57,68 @@ def range_out(val):
         return val
 
     yield app
+
+
+@pytest.fixture(scope="module")
+def debounce_text_app():
+    app = Dash(__name__)
+    app.layout = html.Div(
+        [
+            dcc.Input(
+                id="input-slow",
+                debounce=3,
+                placeholder="long wait",
+            ),
+            html.Div(id="div-slow"),
+            dcc.Input(
+                id="input-fast",
+                debounce=0.25,
+                placeholder="short wait",
+            ),
+            html.Div(id="div-fast"),
+        ]
+    )
+
+    @app.callback(
+        [Output("div-slow", "children"), Output("div-fast", "children")],
+        [Input("input-slow", "value"), Input("input-fast", "value")],
+    )
+    def render(slow_val, fast_val):
+        return [slow_val, fast_val]
+
+    yield app
+
+
+@pytest.fixture(scope="module")
+def debounce_number_app():
+    app = Dash(__name__)
+    app.layout = html.Div(
+        [
+            dcc.Input(
+                id="input-slow",
+                debounce=3,
+                type="number",
+                placeholder="long wait",
+            ),
+            html.Div(id="div-slow"),
+            dcc.Input(
+                id="input-fast",
+                debounce=0.25,
+                type="number",
+                min=10,
+                max=10000,
+                step=3,
+                placeholder="short wait",
+            ),
+            html.Div(id="div-fast"),
+        ]
+    )
+
+    @app.callback(
+        [Output("div-slow", "children"), Output("div-fast", "children")],
+        [Input("input-slow", "value"), Input("input-fast", "value")],
+    )
+    def render(slow_val, fast_val):
+        return [slow_val, fast_val]
+
+    yield app

components/dash-core-components/tests/integration/input/test_debounce.py

@@ -0,0 +1,56 @@
+from selenium.common.exceptions import TimeoutException
+from selenium.webdriver.support.wait import WebDriverWait
+from selenium.webdriver.common.by import By
+import pytest
+
+
+def test_debounce_text_by_time(dash_dcc, debounce_text_app):
+    dash_dcc.start_server(debounce_text_app)
+
+    # expect that a long debounce does not call back in a short amount of time
+    elem = dash_dcc.find_element("#input-slow")
+    elem.send_keys("unit test slow")
+    with pytest.raises(TimeoutException):
+        WebDriverWait(dash_dcc.driver, timeout=1).until(
+            lambda d: d.find_element(By.XPATH, "//*[text()='unit test slow']")
+        )
+
+    # but do expect that it is eventually called
+    dash_dcc.wait_for_text_to_equal(
+        "#div-slow", "unit test slow"
+    ), "long debounce is eventually called back"
+
+    # expect that a short debounce calls back within a short amount of time
+    elem = dash_dcc.find_element("#input-fast")
+    elem.send_keys("unit test fast")
+    WebDriverWait(dash_dcc.driver, timeout=1).until(
+        lambda d: d.find_element(By.XPATH, "//*[text()='unit test fast']")
+    )
+
+    assert dash_dcc.get_logs() == []
+
+
+def test_debounce_number_by_time(dash_dcc, debounce_number_app):
+    dash_dcc.start_server(debounce_number_app)
+
+    # expect that a long debounce does not call back in a short amount of time
+    elem = dash_dcc.find_element("#input-slow")
+    elem.send_keys("12345")
+    with pytest.raises(TimeoutException):
+        WebDriverWait(dash_dcc.driver, timeout=1).until(
+            lambda d: d.find_element(By.XPATH, "//*[text()='12345']")
+        )
+
+    # but do expect that it is eventually called
+    dash_dcc.wait_for_text_to_equal(
+        "#div-slow", "12345"
+    ), "long debounce is eventually called back"
+
+    # expect that a short debounce calls back within a short amount of time
+    elem = dash_dcc.find_element("#input-fast")
+    elem.send_keys("10000")
+    WebDriverWait(dash_dcc.driver, timeout=1).until(
+        lambda d: d.find_element(By.XPATH, "//*[text()='10000']")
+    )
+
+    assert dash_dcc.get_logs() == []

components/dash-html-components/scripts/extract-elements.js

@@ -13,7 +13,7 @@ const expectedElCount = 125;
  */
 function extractElements($) {
     const excludeElements = [
-        'html', 'head', 'body', 'style', 'h1–h6', 'input',
+        'html', 'head', 'body', 'style', 'h1–h6', 'input', 'search',
         // out of scope, different namespaces - but Mozilla added these to the
         // above reference page Jan 2021 so we need to exclude them now.
         // see https://github.com/mdn/content/pull/410

requires-all.txt

@@ -2,7 +2,7 @@
 redis>=3.5.3
 celery[redis]>=5.1.2
 # Dependencies used by CI on github.com/plotly/dash
-black==21.6b0
+black==22.3.0
 dash-flow-example==0.0.5
 dash-dangerously-set-inner-html
 flake8==3.9.2

tests/integration/devtools/test_props_check.py

@@ -7,7 +7,7 @@
         "fail": True,
         "name": 'simple "not a boolean" check',
         "component": dcc.Input,
-        "props": {"debounce": 0},
+        "props": {"multiple": 0},
     },
     "missing-required-nested-prop": {
         "fail": True,