@substrate-system/actor-typeahead 0.0.2 → 0.0.4

package/README.md

@@ -29,6 +29,7 @@ rewritten in TypeScript, and rendering in light DOM only. See
   * [ESM](#esm)
   * [Common JS](#common-js)
   * [Attributes](#attributes)
+  * [Properties](#properties)
   * [Events](#events)
 - [CSS](#css)
   * [Import CSS](#import-css)
@@ -56,7 +57,7 @@ Wrap an `<input>` with `<actor-typeahead>`, and import the JS and CSS.
 
 ```html
 <actor-typeahead>
-    <input>
+    <input />
 </actor-typeahead>
 ```
 
@@ -69,6 +70,11 @@ Typing in the input shows a Suggestion list of matching accounts.
 Choosing one, with the arrow keys and Enter or with the pointer, fills in
 the input with the account's handle.
 
+Enter and Escape are left alone when the component has nothing to do
+with them. Enter with no highlighted Suggestion submits a surrounding
+form, and Escape with the Suggestion list closed reaches a surrounding
+`<dialog>`.
+
 ## API
 
 This exposes ESM and common JS via
@@ -95,17 +101,39 @@ it more than once is safe.
 
 ```html
 <actor-typeahead host="https://public.api.bsky.app" rows="3">
-    <input>
+    <input />
 </actor-typeahead>
 ```
 
 Both are reflected as properties, so `el.rows = '3'` works too.
 
+### Properties
+
+* `announce` -- A function `(count:number) => string` that returns the
+  text screen readers hear when a Typeahead request settles. `count` is
+  the number of Suggestions, and is 0 when nothing matched the Query.
+  The default is English, "No Suggestions", "1 Suggestion available" or
+  "N Suggestions available". Replace it to translate; your function
+  handles plurals and 0. It is read each time a request settles, so you
+  can set it at any time. There is no matching attribute.
+
+```ts
+const el = document.querySelector('actor-typeahead')!
+el.announce = count => {
+    if (count === 0) return 'Sin sugerencias'
+    return count === 1 ?
+        '1 sugerencia disponible' :
+        `${count} sugerencias disponibles`
+}
+```
+
+A request that fails is not announced.
+
 ### Events
 
 Events are namespaced by the tag name.
 
-* `actor-typeahead:select` -- A result was chosen. The event `detail` is
+* `actor-typeahead:select` -- A result was chosen. The event's `detail` is
   `{ handle, avatar? }`.
 
 ```ts
@@ -138,7 +166,7 @@ import '@substrate-system/actor-typeahead/min/css'
 ```css
 actor-typeahead {
     --color-background: #fff;
-    --color-border: #0002;
+    --color-border: #0007;
     --color-shadow: #000;
     --color-hover: #0001;
     --color-avatar-fallback: #0002;
@@ -158,21 +186,27 @@ of it. The Suggestion list markup is:
     <input role="combobox" aria-autocomplete="list" aria-expanded="true"
         aria-controls="actor-typeahead-1-list"
         aria-activedescendant="actor-typeahead-1-option-0">
-    <ul class="suggestion-list" id="actor-typeahead-1-list"
+    <div class="suggestion-list" id="actor-typeahead-1-list"
         role="listbox">
-        <li class="suggestion" id="actor-typeahead-1-option-0"
-            role="option" aria-selected="true">
+        <button type="button" class="suggestion"
+            id="actor-typeahead-1-option-0" role="option"
+            tabindex="-1" aria-selected="true">
             <div class="avatar"><img class="img" alt=""></div>
             <span class="handle"></span>
-        </li>
-    </ul>
+        </button>
+    </div>
+    <!-- visually hidden, announces how many Suggestions arrived -->
+    <div class="suggestion-count" role="status"></div>
 </actor-typeahead>
 ```
 
 `aria-selected="true"` marks the Suggestion highlighted with the
 keyboard. The input also gets `autocomplete="off"` unless you set
-`autocomplete` yourself. If the input has a `<label>` with an `id`, the
-Suggestion list is labelled by it.
+`autocomplete` yourself. The Suggestion list gets the same name as the
+input, from the input's `aria-labelledby`, its `aria-label`, or its
+`<label>`s, in that order. Your labels do not need an `id`: when any
+label lacks one, the list gets the label text as its `aria-label`. The
+component never writes attributes on your labels.
 
 ### Avoid a flash of undefined content
 

package/dist/custom-elements.json

@@ -64,6 +64,15 @@
                 "text": "string|null"
               }
             },
+            {
+              "kind": "field",
+              "name": "announce",
+              "type": {
+                "text": "(count:number) => string"
+              },
+              "default": "defaultAnnounce",
+              "description": "Returns the text announced when a Typeahead request settles with\n`count` Suggestions, including 0 when nothing matched the Query.\nDefaults to English. Replace it to translate; the replacement\nhandles plurals and 0. Read at announce time, so it can be set\nafter connect."
+            },
             {
               "kind": "field",
               "name": "#id",
@@ -90,7 +99,25 @@
             },
             {
               "kind": "field",
-              "name": "#pressed",
+              "name": "#suggestionList",
+              "privacy": "private",
+              "type": {
+                "text": "HTMLDivElement|null"
+              },
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "#suggestionCount",
+              "privacy": "private",
+              "type": {
+                "text": "HTMLDivElement|null"
+              },
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "#nbsp",
               "privacy": "private",
               "type": {
                 "text": "boolean"
@@ -99,10 +126,18 @@
             },
             {
               "kind": "field",
-              "name": "#suggestionList",
+              "name": "#timer",
               "privacy": "private",
               "type": {
-                "text": "HTMLUListElement|null"
+                "text": "ReturnType<typeof setTimeout>|undefined"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "#controller",
+              "privacy": "private",
+              "type": {
+                "text": "AbortController|null"
               },
               "default": "null"
             },
@@ -153,14 +188,50 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "#request",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "query",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "#announce",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Write the Suggestion count. A trailing no-break space alternates\nbetween writes, so screen readers re-read an identical count."
+            },
             {
               "kind": "method",
               "name": "#onfocusout",
-              "privacy": "private"
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "evt",
+                  "type": {
+                    "text": "FocusEvent"
+                  }
+                }
+              ],
+              "description": "Close only when focus leaves the host. Some assistive technology\nfocuses a Suggestion before it sends the click that selects it."
             },
             {
               "kind": "method",
-              "name": "#onpointerup",
+              "name": "#onclick",
               "privacy": "private",
               "parameters": [
                 {
@@ -184,6 +255,12 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "#cancel",
+              "privacy": "private",
+              "description": "Stop any pending Typeahead request: the debounce timer, and the\nrequest in flight, whose response is then dropped."
+            },
             {
               "kind": "method",
               "name": "#clear",
@@ -192,7 +269,7 @@
             {
               "kind": "method",
               "name": "render",
-              "description": "Render into light DOM, next to the authored `<input>`. Only the\nSuggestion list is rebuilt, so the input element, and anything the\nconsumer attached to it, is never replaced. On the input, only the\nARIA combobox attributes are written, plus `autocomplete=\"off\"`\nwhen the page did not set `autocomplete`."
+              "description": "Render into light DOM. Only the suggestion list is rebuilt,\nso the input element, and anything the consumer attached to it,\nis never replaced. On the input, only the\nARIA combobox attributes are written, plus `autocomplete=\"off\"`\nwhen the page did not set `autocomplete`."
             },
             {
               "kind": "method",

package/dist/index.cjs

@@ -25,6 +25,7 @@ module.exports = __toCommonJS(index_exports);
 var import_web_component = require("@substrate-system/web-component");
 const DEFAULT_HOST = "https://public.api.bsky.app";
 const DEFAULT_ROWS = 5;
+const DEBOUNCE_MS = 150;
 const ANCHORED = typeof CSS !== "undefined" && CSS.supports("anchor-scope: --a");
 let instances = 0;
 class ActorTypeahead extends import_web_component.WebComponent.create("actor-typeahead") {
@@ -32,17 +33,35 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
     __name(this, "ActorTypeahead");
   }
   static reflectedStringAttributes = ["host", "rows"];
+  /**
+   * Returns the text announced when a Typeahead request settles with
+   * `count` Suggestions, including 0 when nothing matched the Query.
+   * Defaults to English. Replace it to translate; the replacement
+   * handles plurals and 0. Read at announce time, so it can be set
+   * after connect.
+   */
+  announce = defaultAnnounce;
   #id = `actor-typeahead-${++instances}`;
   #actors = [];
   #index = -1;
-  #pressed = false;
   #suggestionList = null;
+  #suggestionCount = null;
+  #nbsp = false;
+  #timer;
+  #controller = null;
   constructor() {
     super();
     this.addEventListener("input", this);
     this.addEventListener("focusout", this);
     this.addEventListener("keydown", this);
   }
+  /**
+   * Stop any pending Typeahead request. The Suggestion list is left as
+   * is; the next Query rebuilds it.
+   */
+  disconnectedCallback() {
+    this.#cancel();
+  }
   get #limit() {
     const rows = Number.parseInt(this.rows ?? "");
     return Number.isNaN(rows) ? DEFAULT_ROWS : rows;
@@ -56,18 +75,23 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
         if (evt instanceof KeyboardEvent) this.#onkeydown(evt);
         break;
       case "focusout":
-        this.#onfocusout();
+        if (evt instanceof FocusEvent) this.#onfocusout(evt);
         break;
-      case "pointerdown":
-        this.#pressed = true;
+      case "mousedown":
+        evt.preventDefault();
         break;
-      case "pointerup":
-        this.#onpointerup(evt);
+      case "click":
+        this.#onclick(evt);
         break;
     }
   }
   #onkeydown(evt) {
     const last = this.#actors.length - 1;
+    const moves = ["ArrowDown", "ArrowUp", "PageDown", "PageUp"];
+    if (last < 0 && moves.includes(evt.key)) {
+      evt.preventDefault();
+      return;
+    }
     switch (evt.key) {
       case "ArrowDown":
         evt.preventDefault();
@@ -81,7 +105,7 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
         break;
       case "ArrowUp":
         evt.preventDefault();
-        this.#index = Math.max(this.#index - 1, 0);
+        this.#index = this.#index < 0 ? last : this.#index - 1;
         this.render();
         break;
       case "PageUp":
@@ -90,45 +114,78 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
         this.render();
         break;
       case "Escape":
-        evt.preventDefault();
+        if (this.#actors.length) evt.preventDefault();
         this.#clear();
         break;
       case "Enter":
+        if (!this.#actors[this.#index]) {
+          this.#cancel();
+          break;
+        }
         evt.preventDefault();
         this.#select(this.#index);
         break;
     }
   }
-  async #oninput(evt) {
+  #oninput(evt) {
     if (!(evt.target instanceof HTMLInputElement)) return;
     const query = evt.target.value;
     if (!query) {
       this.#clear();
       return;
     }
+    this.#cancel();
+    this.#timer = setTimeout(() => this.#request(query), DEBOUNCE_MS);
+  }
+  async #request(query) {
+    this.#timer = void 0;
     const url = new URL(
       "xrpc/app.bsky.actor.searchActorsTypeahead",
       this.host ?? DEFAULT_HOST
     );
     url.searchParams.set("q", query);
     url.searchParams.set("limit", String(this.#limit));
-    const res = await fetch(url);
-    const json = await res.json();
+    const controller = new AbortController();
+    this.#controller = controller;
+    const { signal } = controller;
+    let json;
+    try {
+      const res = await fetch(url, { signal });
+      if (signal.aborted) return;
+      if (!res.ok) throw new Error(`status ${res.status}`);
+      json = await res.json();
+    } catch (err) {
+      if (isAbortError(err)) return;
+      this.#clear();
+      return;
+    }
+    if (signal.aborted) return;
     this.#actors = parseActors(json);
     this.#index = -1;
     this.render();
+    this.#announce(this.#actors.length);
+  }
+  /**
+   * Write the Suggestion count. A trailing no-break space alternates
+   * between writes, so screen readers re-read an identical count.
+   */
+  #announce(count) {
+    if (!this.#suggestionCount) return;
+    this.#nbsp = !this.#nbsp;
+    this.#suggestionCount.textContent = this.announce(count) + (this.#nbsp ? "\xA0" : "");
   }
-  #onfocusout() {
-    if (this.#pressed) return;
+  /**
+   * Close only when focus leaves the host. Some assistive technology
+   * focuses a Suggestion before it sends the click that selects it.
+   */
+  #onfocusout(evt) {
+    const next = evt.relatedTarget;
+    if (next instanceof Node && this.contains(next)) return;
     this.#clear();
   }
-  #onpointerup(evt) {
-    this.#pressed = false;
+  #onclick(evt) {
     const option = evt.target instanceof Element ? evt.target.closest('[role="option"]') : null;
-    if (!option) {
-      this.qs("input")?.focus();
-      return;
-    }
+    if (!option) return;
     this.#select(Number(option.dataset.index));
   }
   #select(index) {
@@ -140,30 +197,49 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
     this.#clear();
     this.emit("select", { detail: actor });
   }
+  /**
+   * Stop any pending Typeahead request: the debounce timer, and the
+   * request in flight, whose response is then dropped.
+   */
+  #cancel() {
+    clearTimeout(this.#timer);
+    this.#timer = void 0;
+    this.#controller?.abort();
+    this.#controller = null;
+  }
   #clear() {
+    this.#cancel();
     this.#actors = [];
     this.#index = -1;
     this.render();
   }
   /**
-   * Render into light DOM, next to the authored `<input>`. Only the
-   * Suggestion list is rebuilt, so the input element, and anything the
-   * consumer attached to it, is never replaced. On the input, only the
+   * Render into light DOM. Only the suggestion list is rebuilt,
+   * so the input element, and anything the consumer attached to it,
+   * is never replaced. On the input, only the
    * ARIA combobox attributes are written, plus `autocomplete="off"`
    * when the page did not set `autocomplete`.
    */
   render() {
     if (!this.#suggestionList) {
-      this.#suggestionList = document.createElement("ul");
+      this.#suggestionList = document.createElement("div");
       this.#suggestionList.className = "suggestion-list";
       this.#suggestionList.id = `${this.#id}-list`;
       this.#suggestionList.setAttribute("role", "listbox");
       if (ANCHORED) this.#suggestionList.popover = "manual";
-      this.#suggestionList.addEventListener("pointerdown", this);
-      this.#suggestionList.addEventListener("pointerup", this);
+      this.#suggestionList.addEventListener("mousedown", this);
+      this.#suggestionList.addEventListener("click", this);
     }
     const list = this.#suggestionList;
     if (list.parentNode !== this) this.append(list);
+    if (!this.#suggestionCount) {
+      this.#suggestionCount = document.createElement("div");
+      this.#suggestionCount.className = "suggestion-count";
+      this.#suggestionCount.setAttribute("role", "status");
+    }
+    const count = this.#suggestionCount;
+    if (count.parentNode !== this) this.append(count);
+    if (!this.#actors.length) count.textContent = "";
     list.replaceChildren(...this.#actors.map((actor, i) => {
       const option = suggestion(actor, i, i === this.#index);
       option.id = this.#optionId(i);
@@ -179,11 +255,11 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
       }
       input.setAttribute("aria-controls", list.id);
       input.setAttribute("aria-expanded", String(open));
-      const labels = [...input.labels ?? []].map((label) => label.id).filter(Boolean);
-      if (labels.length) {
-        list.setAttribute("aria-labelledby", labels.join(" "));
-      } else {
-        list.removeAttribute("aria-labelledby");
+      const name = nameSource(input, this);
+      for (const attr of ["aria-labelledby", "aria-label"]) {
+        const value = name[attr];
+        if (value) list.setAttribute(attr, value);
+        else list.removeAttribute(attr);
       }
       if (this.#actors[this.#index]) {
         input.setAttribute(
@@ -215,12 +291,14 @@ class ActorTypeahead extends import_web_component.WebComponent.create("actor-typ
 }
 ActorTypeahead.define();
 function suggestion(actor, index, active) {
-  const li = document.createElement("li");
-  li.className = "suggestion";
-  li.setAttribute("role", "option");
-  li.setAttribute("aria-selected", String(active));
-  li.dataset.index = String(index);
-  li.dataset.handle = actor.handle;
+  const button = document.createElement("button");
+  button.type = "button";
+  button.tabIndex = -1;
+  button.className = "suggestion";
+  button.setAttribute("role", "option");
+  button.setAttribute("aria-selected", String(active));
+  button.dataset.index = String(index);
+  button.dataset.handle = actor.handle;
   const avatar = document.createElement("div");
   avatar.className = "avatar";
   const img = document.createElement("img");
@@ -231,10 +309,40 @@ function suggestion(actor, index, active) {
   handle.className = "handle";
   handle.textContent = actor.handle;
   avatar.append(img);
-  li.append(avatar, handle);
-  return li;
+  button.append(avatar, handle);
+  return button;
 }
 __name(suggestion, "suggestion");
+function nameSource(input, host) {
+  const labelledby = input.getAttribute("aria-labelledby");
+  if (labelledby) return { "aria-labelledby": labelledby };
+  const label = input.getAttribute("aria-label");
+  if (label) return { "aria-label": label };
+  const labels = [...input.labels ?? []];
+  if (!labels.length) return {};
+  if (labels.every((label2) => label2.id)) {
+    return {
+      "aria-labelledby": labels.map((label2) => label2.id).join(" ")
+    };
+  }
+  const text = labels.map((label2) => labelText(label2, host).trim()).filter(Boolean).join(" ");
+  return text ? { "aria-label": text } : {};
+}
+__name(nameSource, "nameSource");
+function labelText(label, host) {
+  const walker = document.createTreeWalker(label, NodeFilter.SHOW_TEXT, {
+    acceptNode: /* @__PURE__ */ __name((node) => host.contains(node) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT, "acceptNode")
+  });
+  let text = "";
+  while (walker.nextNode()) text += walker.currentNode.nodeValue;
+  return text;
+}
+__name(labelText, "labelText");
+function defaultAnnounce(count) {
+  if (count === 0) return "No Suggestions";
+  return count === 1 ? "1 Suggestion available" : `${count} Suggestions available`;
+}
+__name(defaultAnnounce, "defaultAnnounce");
 function parseActors(json) {
   if (!isRecord(json) || !Array.isArray(json.actors)) return [];
   return json.actors.flatMap((actor) => {
@@ -243,6 +351,10 @@ function parseActors(json) {
   });
 }
 __name(parseActors, "parseActors");
+function isAbortError(err) {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+__name(isAbortError, "isAbortError");
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }