@acusti/dropdown 1.0.0-rc.5 → 1.1.0

package/README.md

@@ -294,8 +294,9 @@ type Props = {
      * Whether the body is a list of selectable items (the default) or
      * arbitrary interactive content such as a form. hasItems={false} turns
      * off item selection and item keyboard navigation, gives the popup
-     * role="dialog" (unless isSearchable), and keeps it open on clicks
-     * inside the body. Defaults to true and isn’t inferred from the children.
+     * role="dialog" (unless isSearchable), keeps it open on clicks inside
+     * the body, and leaves Space and Enter pressed in the body to the
+     * controls there. Defaults to true and isn’t inferred from the children.
      */
     hasItems?: boolean;
     /**
@@ -322,7 +323,9 @@ type Props = {
     /**
      * Whether the dropdown stays open after an item is submitted, e.g. for a
      * multi-select. Defaults to !hasItems: a menu closes on submit, while a
-     * hasItems={false} dialog stays open.
+     * hasItems={false} dialog stays open. In a hasItems={false} dropdown, a
+     * submit is a form in the body being submitted, or Enter in a
+     * single-line input there that no form owns.
      */
     keepOpenOnSubmit?: boolean;
     /**
@@ -714,6 +717,49 @@ function InteractiveDropdown() {
 }
 ```
 
+The body’s controls keep their own keys while the dropdown is open: Space
+and Enter go to whatever has focus there. Space types a space into a text
+field, toggles a checkbox, and presses a button; Enter adds a line break to
+a textarea, submits the form around a text input, presses a button, and
+follows a link. The same goes for whatever keeps focus outside the dropdown
+while it’s open, as when it opened on hover. Escape closes the dropdown
+unless focus is in a text field (a text input, a textarea, or an editable
+element). On the trigger, Space and Enter open the dropdown and, unless
+focus is in a text field or a checkbox there, close it again, as a click
+there does.
+
+A `hasItems={false}` dropdown stays open until it is dismissed. Pass
+`keepOpenOnSubmit={false}` to close it when its content is submitted. A
+submit is a form in the body being submitted, by Enter in one of its inputs
+or by its submit button, or Enter in a single-line input that no form owns:
+
+```tsx
+<Dropdown hasItems={false} keepOpenOnSubmit={false}>
+    Rename
+    <form onSubmit={handleSubmit}>
+        <label>
+            Name <input name="name" required />
+        </label>
+        <button type="submit">Save</button>
+    </form>
+</Dropdown>
+```
+
+Unless the form opts out of validation (`noValidate`, or a submit button
+with `formNoValidate`), its `submit` event doesn’t fire until the browser’s
+validation passes, so the dropdown stays open while a required field is
+empty. To keep it open after a submit that your own checks reject, call
+`event.stopPropagation()` in the form’s `onSubmit` before it returns. A
+check that finishes later, such as a server round trip or a form library
+that validates asynchronously, can’t keep it open.
+
+Enter in an input that no form owns counts the way a form would count it:
+not when a handler has prevented the key, as a combobox does to pick an
+option, and not when it commits an IME composition.
+
+When a submit closes the dropdown while focus is in its body, focus returns
+to the trigger, as it does on Escape.
+
 ### Placement Customization with CSS Variables
 
 Placement is best customized in CSS instead of props. The component exposes
@@ -1262,7 +1308,11 @@ intent delay while the highlight stays on the parent, and only → moves the
 highlight into it.
 
 - **Enter/Space**: Open the dropdown; with an item highlighted, select it
-  (leaf items) or open its submenu (parent items)
+  (leaf items) or open its submenu (parent items). In the body of a
+  `hasItems={false}` dropdown, they go to
+  [the control that has focus](#dropdown-with-interactive-content) instead,
+  and on its open trigger, outside a text field or a checkbox, they close
+  it
 - **Escape**: Close the dropdown entirely — including any open submenus —
   and return focus to the trigger (macOS-style; use ← to back out one level
   at a time)

package/dist/Dropdown.d.ts

@@ -70,8 +70,9 @@ export type Props = {
      * Whether the body is a list of selectable items (the default) or
      * arbitrary interactive content such as a form. hasItems={false} turns
      * off item selection and item keyboard navigation, gives the popup
-     * role="dialog" (unless isSearchable), and keeps it open on clicks
-     * inside the body. Defaults to true and isn’t inferred from the children.
+     * role="dialog" (unless isSearchable), keeps it open on clicks inside
+     * the body, and leaves Space and Enter pressed in the body to the
+     * controls there. Defaults to true and isn’t inferred from the children.
      */
     hasItems?: boolean;
     /**
@@ -98,7 +99,9 @@ export type Props = {
     /**
      * Whether the dropdown stays open after an item is submitted, e.g. for a
      * multi-select. Defaults to !hasItems: a menu closes on submit, while a
-     * hasItems={false} dialog stays open.
+     * hasItems={false} dialog stays open. In a hasItems={false} dropdown, a
+     * submit is a form in the body being submitted, or Enter in a
+     * single-line input there that no form owns.
      */
     keepOpenOnSubmit?: boolean;
     /**