wings-plugin-sdk 0.4.0 → 0.5.0

package/README.md

@@ -139,7 +139,7 @@ component mounts, so main answers with what it has. `useBroadcast(listener)` get
 | `FieldGroup` | `label`, `hint`, `error` | Several controls under one label, like checkboxes: a `fieldset` with its `legend`, described by the hint; an error marks each checkbox invalid |
 | `TextInput`, `SearchField`, `Select` | `label`; `Select`: `options`, `value`, `onChange` | Inputs Wings styles; outside a `Field`, `label` names them |
 | `Checkbox` | `checked`, `onChange`, `children` | A checkbox with its label |
-| `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) |
+| `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
 | `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
 | `Disclosure` | `summary` | More behind a line that opens it |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Types, React hooks, UI components and a build command for Wings plugins.",
   "license": "MIT",
   "type": "module",

package/ui.d.ts

@@ -208,6 +208,14 @@ export function Combobox(
     freeText?: boolean;
     /** Open the list when the field gets focus, by default; false opens it on a click, a key or typing only, for a page that puts focus back by id after it renders. */
     openOnFocus?: boolean;
+    /**
+     * When the list is shown. `"auto"` (default): on focus, a click, a key or typing, and Escape, Tab, blur to another
+     * element or a press outside close it. `"whileText"`: the list is shown exactly while the field has text and an
+     * option matches it, whether or not the field has focus. Escape, Tab and a press outside only clear the highlighted
+     * option (`aria-activedescendant`); emptying the text or picking closes it, and there's no `empty` message. A
+     * list left open after the field loses focus is a screen reader caveat, see the README.
+     */
+    open?: "auto" | "whileText";
     filter?: (option: ComboboxOption, query: string) => boolean;
     /** What shows when nothing matches. */
     empty?: ReactNode;

package/ui.js

@@ -363,37 +363,45 @@ function useCloseOutside(open, root, close) {
 /**
  * A text field with `options` under it. Arrows move, Enter picks, Escape and Tab close. With `freeText` the field
  * keeps what you type (`value`, `onInput`) and starts with nothing highlighted; otherwise you type to find an
- * option, the field shows `value` once you've picked, and the list starts on the first option.
+ * option, the field shows `value` once you've picked, and the list starts on the first option. `open="whileText"`
+ * keeps the list shown while the field has text and something matches, which Escape, Tab and a press outside don't close.
  */
-export function Combobox({ label, value, onInput, options, onPick, onEnter, onKeyDown: onKeyDownProp, freeText = false, openOnFocus = true, filter = contains, empty = "No matches.", className, ...rest }) {
+export function Combobox({ label, value, onInput, options, onPick, onEnter, onKeyDown: onKeyDownProp, freeText = false, openOnFocus = true, open: openMode = "auto", filter = contains, empty = "No matches.", className, ...rest }) {
   const field = useFieldProps(rest);
   const generated = useId();
   const id = field.id ?? generated;
-  const [open, setOpen] = useState(false);
+  const [opened, setOpened] = useState(false);
   const [query, setQuery] = useState("");
   const [active, setActive] = useState(-1);
   const root = useRef(null);
   const list = useRef(null);
   const input = useRef(null);
   const first = freeText ? -1 : 0;
-  const shown = open ? options.filter((o) => filter(o, freeText ? value : query)) : [];
+  const text = freeText ? value : query;
+  // "whileText": the list is open exactly while there is text and something matches it, whatever has focus.
+  const whileText = openMode === "whileText";
+  const open = whileText ? text !== "" : opened;
+  const shown = open ? options.filter((o) => filter(o, text)) : [];
+  const visible = whileText ? shown.length > 0 : open;
   const current = Math.min(active, shown.length - 1);
   const optionId = (i) => `${id}-option-${i}`;
 
   const close = () => {
-    setOpen(false);
+    setOpened(false);
     setQuery("");
     setActive(-1);
   };
+  // Escape, Tab and a press outside: a "whileText" list stays, so only the highlight goes.
+  const dismiss = whileText ? () => setActive(-1) : close;
   const openAt = (i) => {
-    setOpen(true);
+    setOpened(true);
     setActive(i);
   };
   const pick = (option) => {
     onPick(option);
     close();
   };
-  useCloseOutside(open, root, close);
+  useCloseOutside(open && !whileText, root, dismiss);
   useLayoutEffect(() => {
     if (current >= 0) list.current?.children[current]?.scrollIntoView({ block: "nearest" });
   }, [current]);
@@ -424,8 +432,8 @@ export function Combobox({ label, value, onInput, options, onPick, onEnter, onKe
       onEnter(e.currentTarget.value);
     } else if (e.key === "Escape" || e.key === "Tab") {
       // An open list takes the Escape, so a form or dialog around it closes on the next one.
-      if (e.key === "Escape" && open) e.preventDefault();
-      close();
+      if (e.key === "Escape" && (whileText ? current >= 0 : open)) e.preventDefault();
+      dismiss();
     }
   };
 
@@ -441,7 +449,7 @@ export function Combobox({ label, value, onInput, options, onPick, onEnter, onKe
       role: "combobox",
       "aria-autocomplete": "list",
       "aria-controls": `${id}-list`,
-      "aria-expanded": open,
+      "aria-expanded": visible,
       "aria-activedescendant": current >= 0 ? optionId(current) : undefined,
       autoComplete: "off",
       spellCheck: false,
@@ -464,13 +472,13 @@ export function Combobox({ label, value, onInput, options, onPick, onEnter, onKe
         openAt(first);
       },
       onBlur: (e) => {
-        if (e.relatedTarget && !root.current.contains(e.relatedTarget)) close();
+        if (e.relatedTarget && !root.current.contains(e.relatedTarget)) dismiss();
       },
       onKeyDown,
     }),
     h(
       "div",
-      { className: "w-listbox", hidden: !open },
+      { className: "w-listbox", hidden: !visible },
       h(
         "ul",
         { id: `${id}-list`, role: "listbox", "aria-label": label, ref: list },
@@ -495,7 +503,7 @@ export function Combobox({ label, value, onInput, options, onPick, onEnter, onKe
           ),
         ),
       ),
-      open && !shown.length ? h("p", { className: "w-option-empty", role: "status" }, empty) : null,
+      open && !whileText && !shown.length ? h("p", { className: "w-option-empty", role: "status" }, empty) : null,
     ),
   );
 }