[IMP] hooks: document useAutofocus

Part-of: odoo/documentation#1557

content/developer/reference/frontend/hooks.rst

@@ -22,6 +22,8 @@ documents the list of hooks provided by the Odoo web framework.
      - Short Description
    * - :ref:`useAssets <frontend/hooks/useassets>`
      - load assets
+   * - :ref:`useAutofocus <frontend/hooks/useAutofocus>`
+     - focus automatically a referenced element
    * - :ref:`useBus <frontend/hooks/usebus>`
      - subscribe and unsubscribe to a bus
    * - :ref:`usePager <frontend/hooks/usepager>`
@@ -45,6 +47,53 @@ Description
 See the section on :ref:`lazy loading assets <frontend/assets/lazy_loading>` for
 more details.
 
+
+.. _frontend/hooks/useAutofocus:
+
+useAutofocus
+============
+
+Location
+--------
+
+`@web/core/utils/hooks`
+
+Description
+-----------
+
+Focus automatically an element referenced by a component after its rendering if
+that element was not already present in the dom. The focus of that element can
+be forced at a future patch if the returning value (a function) of useAutofocus
+is called.
+
+.. code-block:: javascript
+
+    import { useAutofocus } from "@web/core/utils/hooks";
+
+    class Comp {
+      setup() {
+        const focusOnUpdate = useAutofocus("to_focus");
+      }
+      onStateReset() {
+        focusOnUpdate();
+      }
+      static template = "Comp";
+    }
+
+.. code-block:: xml
+
+    <t t-name="Comp" owl="1">
+      <input t-ref="to_focus" type="text"/>
+    </t>
+
+API
+---
+
+.. js:function:: useAutofocus([ref])
+
+    :param string ref: optional. If given, must be a t-ref value. Default is "autofocus"
+    :returns: a function to be called if focus must be forced on next patch.
+
 .. _frontend/hooks/usebus:
 
 useBus