@acusti/dropdown 1.0.0 → 1.1.1

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,10 @@ 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 that appears in the body with no form or in the
+     * trigger.
      */
     keepOpenOnSubmit?: boolean;
     /**
@@ -714,6 +718,54 @@ 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. Once it is open, Enter in a textarea or an editable element
+used as the trigger adds a line break there. Enter in a single-line input
+used as the trigger is a submit, whether or not a form owns it: the
+dropdown takes the key, so a form around the trigger isn’t submitted from
+that input while the dropdown is open.
+
+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, either one in the
+body that no form owns or one used as the trigger:
+
+```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 such an input, in the body or the trigger, 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 +1314,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)
@@ -1280,6 +1336,13 @@ highlight into it.
   input, or one inside a custom trigger), where they move the caret instead
 - **Type characters**: Jump to the best-matching item in the current level
 
+While text is being composed with an IME, in a searchable dropdown’s input
+or a text field in a custom trigger, the dropdown ignores every keydown
+that the browser reports as part of the composition. With a Japanese IME,
+the Enter that commits the text doesn’t submit (the next Enter is an
+ordinary one), and the arrow keys and Escape don’t move the highlight or
+close the dropdown. Other IMEs can report their keys differently.
+
 For accessibility, the component focuses on semantic HTML structure and
 keyboard navigation. It works best when you use appropriate HTML elements
 in your dropdown content (like `<ul>` and `<li>` for lists, `<button>`

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,10 @@ 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 that appears in the body with no form or in the
+     * trigger.
      */
     keepOpenOnSubmit?: boolean;
     /**