components/select/select.ts

Functions

Imports

It imports components/listbox/listbox.ts, components/popover/popover.ts. Imported by components/select/select.react.tsx.

Source

1// The select's behaviour: a real <select class="cap-select"> stays in the page (its options
2// are the HTML, it submits with the form, it works with no script); this module hides it and
3// puts a button (role="combobox") and a popup in its place, built from the shared listbox
4// (options, groups, check, typeahead, keyboard) and the shared popover (surface, placement,
5// open and close, focus return). Choosing writes the value back to the native select and
6// fires `input` and `change` on it, so a form, the field's checks and an app's own handlers
7// see what they always saw.
8//
9// Markup: <div class="cap-select-wrap" data-cap="select"><select class="cap-select">...</select></div>.
10// Add `data-native` to the wrapper to keep the browser's own select (a phone, say).
11
12import { createListbox, nextTypeahead, type Listbox, type TypeaheadState, TYPEAHEAD_MS } from "../listbox/listbox.ts";
13import { attach, close } from "../popover/popover.ts";
14
15const SVG = "http://www.w3.org/2000/svg";
16let serial = 0;
17
18export interface SelectItem {
19  kind: "option";
20  value: string;
21  label: string;
22  disabled: boolean;
23  selected: boolean;
24}
25export interface SelectGroup {
26  kind: "group";
27  label: string;
28  disabled: boolean;
29  items: SelectItem[];
30}
31
32// The native select's options and groups as plain data (the popup is built from it).
33export function readOptions(select: HTMLSelectElement): Array<SelectItem | SelectGroup> {
34  const item = (o: HTMLOptionElement): SelectItem => ({ kind: "option", value: o.value, label: (o.label || o.textContent || "").trim(), disabled: o.matches(":disabled"), selected: o.selected });
35  const out: Array<SelectItem | SelectGroup> = [];
36  for (const child of Array.from(select.children)) {
37    if (child instanceof HTMLOptGroupElement) {
38      out.push({ kind: "group", label: child.label, disabled: child.disabled, items: Array.from(child.querySelectorAll("option")).filter((o) => !o.hidden).map(item) });
39    } else if (child instanceof HTMLOptionElement && !child.hidden) out.push(item(child));
40  }
41  return out;
42}
43
44// The words the trigger shows: the chosen option's label, or the placeholder (the empty
45// option's label) when the value is empty.
46export function triggerText(select: HTMLSelectElement): { text: string; placeholder: boolean } {
47  const o = select.selectedOptions[0];
48  if (!o) return { text: "", placeholder: true };
49  return { text: (o.label || o.textContent || "").trim(), placeholder: o.value === "" };
50}
51
52function chevron(): SVGSVGElement {
53  const svg = document.createElementNS(SVG, "svg");
54  svg.setAttribute("viewBox", "0 0 16 16");
55  svg.setAttribute("aria-hidden", "true");
56  svg.setAttribute("focusable", "false");
57  svg.classList.add("cap-select-icon");
58  const path = document.createElementNS(SVG, "path");
59  path.setAttribute("d", "M4 6l4 4 4-4");
60  path.setAttribute("fill", "none");
61  path.setAttribute("stroke", "currentColor");
62  path.setAttribute("stroke-width", "1.5");
63  path.setAttribute("stroke-linecap", "round");
64  path.setAttribute("stroke-linejoin", "round");
65  svg.append(path);
66  return svg;
67}
68
69function check(): HTMLSpanElement {
70  const span = document.createElement("span");
71  span.className = "cap-option-indicator";
72  span.setAttribute("aria-hidden", "true");
73  const svg = document.createElementNS(SVG, "svg");
74  svg.setAttribute("viewBox", "0 0 16 16");
75  svg.setAttribute("width", "16");
76  svg.setAttribute("height", "16");
77  svg.setAttribute("focusable", "false");
78  const path = document.createElementNS(SVG, "path");
79  path.setAttribute("d", "M3.5 8.5l3 3 6-6.5");
80  path.setAttribute("fill", "none");
81  path.setAttribute("stroke", "currentColor");
82  path.setAttribute("stroke-width", "1.75");
83  path.setAttribute("stroke-linecap", "round");
84  path.setAttribute("stroke-linejoin", "round");
85  svg.append(path);
86  span.append(svg);
87  return span;
88}
89
90export interface SelectControl {
91  readonly select: HTMLSelectElement;
92  readonly trigger: HTMLButtonElement;
93  readonly popup: HTMLElement;
94  // Re-reads the native select (its value, its options, disabled) into the trigger and the popup.
95  sync(): void;
96  open(): void;
97  close(): void;
98  detach(): void;
99}
100
101const controls = new WeakMap<HTMLSelectElement, SelectControl>();
102
103export function selectControlFor(select: Element | null): SelectControl | undefined {
104  return select instanceof HTMLSelectElement ? controls.get(select) : undefined;
105}
106
107// Builds the trigger and the popup for one native select and wires them.
108export function createSelect(wrap: HTMLElement, select: HTMLSelectElement): SelectControl {
109  const n = ++serial;
110  const nativeId = select.id;
111  const label = (nativeId ? document.querySelector<HTMLElement>(`label[for="${CSS.escape(nativeId)}"]`) : null) ?? select.closest("label");
112  const triggerId = nativeId || `cap-select-${n}`;
113  const popupId = `${triggerId}-popup`;
114  const listId = `${triggerId}-list`;
115
116  // The trigger takes the select's id, so its label (for="...") points at it.
117  const trigger = document.createElement("button");
118  trigger.type = "button";
119  trigger.className = "cap-select-trigger";
120  trigger.setAttribute("role", "combobox");
121  trigger.setAttribute("aria-haspopup", "listbox");
122  trigger.setAttribute("aria-expanded", "false");
123  trigger.setAttribute("aria-controls", listId);
124  trigger.id = triggerId;
125  if (select.dataset.size) trigger.dataset.size = select.dataset.size;
126  // The specimen hook for a forced hover carries over.
127  if (select.dataset.force) trigger.dataset.force = select.dataset.force;
128  if (label) {
129    if (!label.id) label.id = `${triggerId}-label`;
130    trigger.setAttribute("aria-labelledby", label.id);
131  } else if (select.getAttribute("aria-label")) trigger.setAttribute("aria-label", select.getAttribute("aria-label") as string);
132  else if (select.getAttribute("aria-labelledby")) trigger.setAttribute("aria-labelledby", select.getAttribute("aria-labelledby") as string);
133  const value = document.createElement("span");
134  value.className = "cap-select-value";
135  trigger.append(value, chevron());
136
137  const popup = document.createElement("div");
138  popup.className = "cap-popover cap-select-popup";
139  popup.id = popupId;
140  popup.setAttribute("popover", "auto");
141  popup.setAttribute("role", "presentation");
142  popup.dataset.size = "auto";
143  popup.dataset.flush = "";
144  popup.dataset.side = "bottom";
145  popup.dataset.align = "start";
146  const list = document.createElement("div");
147  list.className = "cap-listbox";
148  list.id = listId;
149  list.setAttribute("role", "listbox");
150  if (label) list.setAttribute("aria-labelledby", label.id);
151  else if (trigger.getAttribute("aria-label")) list.setAttribute("aria-label", trigger.getAttribute("aria-label") as string);
152  popup.append(list);
153
154  // The native select steps aside: out of the page, the tab order and the tree.
155  select.id = `${triggerId}-native`;
156  select.hidden = true;
157  select.tabIndex = -1;
158  select.setAttribute("aria-hidden", "true");
159  wrap.dataset.enhanced = "";
160  select.after(trigger, popup);
161  // A check that wants to focus the select (the field's first-error focus) lands on the trigger.
162  select.focus = (o?: FocusOptions) => trigger.focus(o);
163
164  let lb: Listbox | null = null;
165
166  const buildList = () => {
167    lb?.detach();
168    list.replaceChildren();
169    let k = 0;
170    const optionEl = (it: SelectItem): HTMLElement => {
171      const el = document.createElement("div");
172      el.className = "cap-option";
173      el.id = `${listId}-${++k}`;
174      el.setAttribute("role", "option");
175      el.dataset.value = it.value;
176      el.setAttribute("aria-selected", String(it.selected));
177      if (it.disabled) el.setAttribute("aria-disabled", "true");
178      const text = document.createElement("span");
179      text.className = "cap-option-label";
180      text.textContent = it.label;
181      el.append(text, check());
182      return el;
183    };
184    for (const entry of readOptions(select)) {
185      if (entry.kind === "option") list.append(optionEl(entry));
186      else {
187        const g = document.createElement("div");
188        g.className = "cap-listbox-group";
189        g.setAttribute("role", "group");
190        const gl = document.createElement("div");
191        gl.className = "cap-listbox-label";
192        gl.id = `${listId}-g${++k}`;
193        gl.setAttribute("role", "presentation");
194        gl.textContent = entry.label;
195        g.setAttribute("aria-labelledby", gl.id);
196        g.append(gl, ...entry.items.map((i) => optionEl(i)));
197        list.append(g);
198      }
199    }
200    delete list.dataset.capReady;
201    lb = createListbox(list, { mode: "descendant", selection: "single", hideWhenEmpty: false });
202  };
203
204  const sync = () => {
205    const t = triggerText(select);
206    value.textContent = t.text;
207    if (t.placeholder) trigger.dataset.placeholder = "";
208    else delete trigger.dataset.placeholder;
209    trigger.disabled = select.disabled;
210    if (select.required) trigger.setAttribute("aria-required", "true");
211    else trigger.removeAttribute("aria-required");
212    for (const a of ["aria-invalid", "aria-describedby"]) {
213      const v = select.getAttribute(a);
214      if (v === null) trigger.removeAttribute(a);
215      else trigger.setAttribute(a, v);
216    }
217    lb?.setValue(select.value);
218  };
219  const rebuild = () => {
220    buildList();
221    sync();
222  };
223
224  // Choosing: write the value back and tell the world what a native select would.
225  const choose = (v: string) => {
226    if (select.value !== v) {
227      select.value = v;
228      select.dispatchEvent(new Event("input", { bubbles: true }));
229      select.dispatchEvent(new Event("change", { bubbles: true }));
230    }
231    sync();
232  };
233  const onSelect = (e: Event) => {
234    const d = (e as CustomEvent<{ value: string }>).detail;
235    choose(d.value);
236    close(popup);
237  };
238  list.addEventListener("cap:option-select", onSelect);
239
240  const detachPopover = attach(trigger, popup);
241  // attach() names the popup a generic popup; this one is a listbox.
242  trigger.setAttribute("aria-haspopup", "listbox");
243
244  // Open: the popup is as wide as the trigger at least, the chosen option is current and in view.
245  const fit = () => popup.style.setProperty("--cap-select-min", `${Math.ceil(trigger.getBoundingClientRect().width)}px`);
246  const onBefore = (e: Event) => {
247    if ((e as ToggleEvent).newState === "open") fit();
248  };
249  const onResize = () => {
250    if (popup.matches(":popover-open")) fit();
251  };
252  window.addEventListener("resize", onResize);
253  const onToggle = (e: Event) => {
254    if ((e as ToggleEvent).newState !== "open") return;
255    const selected = list.querySelector<HTMLElement>("[role='option'][aria-selected='true']:not([aria-disabled='true'])");
256    const first = list.querySelector<HTMLElement>("[role='option']:not([aria-disabled='true'])");
257    lb?.setActive(selected ?? first);
258    list.focus({ preventScroll: true });
259  };
260  popup.addEventListener("beforetoggle", onBefore);
261  popup.addEventListener("toggle", onToggle);
262
263  // Closed: arrows open the list; letters choose the matching option without opening (a
264  // native select's own typeahead).
265  let typed: TypeaheadState = { buffer: "", at: 0 };
266  const onKey = (e: KeyboardEvent) => {
267    if (e.defaultPrevented || e.ctrlKey || e.metaKey || e.altKey || trigger.disabled) return;
268    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
269      e.preventDefault();
270      popup.showPopover();
271    } else if (e.key.length === 1 && (e.key !== " " || (typed.buffer !== "" && Date.now() - typed.at <= TYPEAHEAD_MS))) {
272      const items = readOptions(select).flatMap((x) => (x.kind === "option" ? [x] : x.items));
273      const current = items.findIndex((i) => i.selected);
274      const r = nextTypeahead(typed, e.key, Date.now(), items.map((i) => (i.disabled ? null : i.label)), current);
275      typed = r.state;
276      e.preventDefault();
277      const hit = items[r.index];
278      if (hit) choose(hit.value);
279    }
280  };
281  trigger.addEventListener("keydown", onKey);
282
283  // Keep the trigger true when the app or the form changes the select.
284  const onChange = () => sync();
285  select.addEventListener("change", onChange);
286  const form = select.form;
287  const onReset = () => setTimeout(sync, 0);
288  form?.addEventListener("reset", onReset);
289  // The select's own attributes only re-read the trigger; a change to its options or groups
290  // rebuilds the list.
291  const mo = new MutationObserver((records) => {
292    if (records.every((r) => r.target === select && r.type === "attributes")) sync();
293    else rebuild();
294  });
295  mo.observe(select, { childList: true, subtree: true, characterData: true, attributes: true, attributeFilter: ["disabled", "required", "aria-invalid", "aria-describedby", "label", "hidden", "selected"] });
296
297  rebuild();
298
299  const control: SelectControl = {
300    select,
301    trigger,
302    popup,
303    sync,
304    open: () => popup.showPopover(),
305    close: () => close(popup),
306    detach() {
307      mo.disconnect();
308      lb?.detach();
309      detachPopover();
310      list.removeEventListener("cap:option-select", onSelect);
311      window.removeEventListener("resize", onResize);
312      popup.removeEventListener("beforetoggle", onBefore);
313      popup.removeEventListener("toggle", onToggle);
314      trigger.removeEventListener("keydown", onKey);
315      select.removeEventListener("change", onChange);
316      form?.removeEventListener("reset", onReset);
317      delete (select as { focus?: unknown }).focus;
318      trigger.remove();
319      popup.remove();
320      select.hidden = false;
321      select.removeAttribute("aria-hidden");
322      select.removeAttribute("tabindex");
323      select.id = nativeId;
324      delete wrap.dataset.enhanced;
325      delete wrap.dataset.capReady;
326      controls.delete(select);
327    },
328  };
329  controls.set(select, control);
330  return control;
331}
332
333// Attaches to every [data-cap="select"] under root not yet attached (and not data-native).
334// Returns a function that detaches them all.
335export function enhance(root: ParentNode = document): () => void {
336  const undo: Array<() => void> = [];
337  for (const wrap of root.querySelectorAll<HTMLElement>("[data-cap='select']:not([data-cap-ready])")) {
338    const select = wrap.querySelector<HTMLSelectElement>("select.cap-select");
339    if (!select || wrap.dataset.native !== undefined || typeof HTMLElement.prototype.showPopover !== "function") continue;
340    wrap.dataset.capReady = "";
341    undo.push(createSelect(wrap, select).detach);
342  }
343  return () => undo.forEach((f) => f());
344}