components/chips/chips.ts

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1// Filter chips' behaviour: a chip toggles aria-pressed; Clear shows while any chip is
2// pressed and releases them all; the pressed values go into the address
3// (?status=blocked,running) with history.replaceState, so a reload or a shared link keeps
4// the filter; and every change dispatches `cap:filter-change` with { param, values }. The
5// app filters, then writes the count with setCount.
6
7export const EVENT = "cap:filter-change";
8
9export interface FilterChangeDetail {
10  // The address parameter, from data-param, or null when the group keeps out of the address.
11  param: string | null;
12  values: string[];
13}
14
15function chips(group: Element): HTMLButtonElement[] {
16  return [...group.querySelectorAll<HTMLButtonElement>(".cap-chip")];
17}
18
19export function valueOf(chip: HTMLElement): string {
20  return chip.dataset.value ?? chip.textContent?.trim().toLowerCase() ?? "";
21}
22
23export function pressedValues(group: Element): string[] {
24  return chips(group)
25    .filter((c) => c.getAttribute("aria-pressed") === "true")
26    .map(valueOf);
27}
28
29// Shows Clear while any chip is pressed.
30export function syncClear(group: Element): void {
31  const clear = group.querySelector<HTMLElement>("[data-cap-part='clear']");
32  if (clear) clear.hidden = pressedValues(group).length === 0;
33}
34
35// A value from the address that no chip carries still shows, pressed, after the last chip.
36// Without it a filter in a shared link would narrow the list with nothing on the page to
37// say so or to release (the Portal's NsChips does the same with a namespace its list does
38// not carry).
39export function ensureChips(group: Element, values: string[]): void {
40  const have = new Set(chips(group).map(valueOf));
41  for (const v of values) {
42    if (have.has(v)) continue;
43    have.add(v);
44    const chip = document.createElement("button");
45    chip.type = "button";
46    chip.className = "cap-chip";
47    chip.dataset.value = v;
48    chip.setAttribute("aria-pressed", "true");
49    chip.textContent = v;
50    const last = chips(group).at(-1);
51    const clear = group.querySelector("[data-cap-part='clear']");
52    if (last) last.after(chip);
53    else if (clear) clear.before(chip);
54    else group.append(chip);
55  }
56}
57
58export function setPressed(group: Element, values: string[]): void {
59  for (const c of chips(group)) c.setAttribute("aria-pressed", String(values.includes(valueOf(c))));
60  syncClear(group);
61}
62
63// The values in an address's search string, or null when the parameter is absent.
64export function readParam(search: string, param: string): string[] | null {
65  const raw = new URLSearchParams(search).get(param);
66  return raw === null ? null : raw.split(",").filter(Boolean);
67}
68
69// The address with the parameter set to the values, comma-separated and readable
70// (?status=blocked,running), or removed when there are none. Values must not hold commas.
71export function writeParam(href: string, param: string, values: string[]): string {
72  const url = new URL(href);
73  if (values.length > 0) url.searchParams.set(param, values.join(","));
74  else url.searchParams.delete(param);
75  url.search = url.searchParams.toString().replace(/%2C/gi, ",");
76  return url.toString();
77}
78
79// Writes the result count into the group's live region: "3 of 14 jobs".
80export function setCount(group: Element, text: string): void {
81  const count = group.querySelector<HTMLElement>(".cap-chips-count");
82  if (count && count.textContent !== text) count.textContent = text;
83}
84
85function changed(group: HTMLElement): void {
86  syncClear(group);
87  const param = group.dataset.param ?? null;
88  const values = pressedValues(group);
89  if (param) {
90    try {
91      history.replaceState(history.state, "", writeParam(location.href, param, values));
92    } catch {
93      // A sandboxed frame may refuse; the filter still works, it is just not in the address.
94    }
95  }
96  group.dispatchEvent(new CustomEvent<FilterChangeDetail>(EVENT, { bubbles: true, detail: { param, values } }));
97}
98
99// Presses or releases one chip, as a click does.
100export function toggle(group: HTMLElement, chip: HTMLElement): void {
101  chip.setAttribute("aria-pressed", String(chip.getAttribute("aria-pressed") !== "true"));
102  changed(group);
103}
104
105// Releases every chip, as Clear does. Clear hides itself, so focus goes to the first chip
106// rather than being lost. An empty result's own Clear button calls this too.
107export function clearAll(group: HTMLElement): void {
108  setPressed(group, []);
109  chips(group)[0]?.focus();
110  changed(group);
111}
112
113// Attaches to every [data-cap="chips"] under root that is not attached yet. With
114// data-param, the group reads its starting state from the address and writes it back.
115// Returns a function that detaches them all.
116export function enhance(root: ParentNode = document): () => void {
117  const undo: Array<() => void> = [];
118  for (const group of root.querySelectorAll<HTMLElement>("[data-cap='chips']:not([data-cap-ready])")) {
119    group.dataset.capReady = "";
120    const param = group.dataset.param;
121    const fromAddress = param ? readParam(location.search, param) : null;
122    if (fromAddress) {
123      ensureChips(group, fromAddress);
124      setPressed(group, fromAddress);
125    } else syncClear(group);
126
127    const onClick = (e: MouseEvent) => {
128      const target = e.target as Element;
129      const chip = target.closest<HTMLButtonElement>(".cap-chip");
130      if (chip && group.contains(chip)) {
131        toggle(group, chip);
132        return;
133      }
134      const clear = target.closest<HTMLElement>("[data-cap-part='clear']");
135      if (clear && group.contains(clear)) clearAll(group);
136    };
137    // Arrow keys, Home and End move focus between the chips without pressing one; every chip
138    // stays a tab stop, so Tab works as it does for any run of buttons.
139    const onKey = (e: KeyboardEvent) => {
140      if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
141      const all = chips(group).filter((c) => !c.matches(":disabled, [aria-disabled='true']"));
142      const at = all.indexOf(document.activeElement as HTMLButtonElement);
143      if (at < 0) return;
144      const next = e.key === "ArrowRight" || e.key === "ArrowDown" ? all[(at + 1) % all.length] : e.key === "ArrowLeft" || e.key === "ArrowUp" ? all[(at - 1 + all.length) % all.length] : e.key === "Home" ? all[0] : e.key === "End" ? all.at(-1) : undefined;
145      if (!next) return;
146      e.preventDefault();
147      next.focus();
148    };
149    group.addEventListener("click", onClick);
150    group.addEventListener("keydown", onKey);
151    undo.push(() => {
152      group.removeEventListener("click", onClick);
153      group.removeEventListener("keydown", onKey);
154      delete group.dataset.capReady;
155    });
156  }
157  return () => undo.forEach((f) => f());
158}