@pagefind/component-ui 1.5.0-alpha.3

package/components/pagefind-summary.ts

@@ -0,0 +1,138 @@
+import { PagefindElement } from "./base-element";
+import { Instance } from "../core/instance";
+import type { PagefindSearchResult, PagefindError } from "../types";
+
+export class PagefindSummary extends PagefindElement {
+  static get observedAttributes(): string[] {
+    return ["default-message"];
+  }
+
+  containerEl: HTMLElement | null = null;
+  term: string = "";
+  defaultMessage: string = "";
+
+  constructor() {
+    super();
+  }
+
+  init(): void {
+    if (this.hasAttribute("default-message")) {
+      this.defaultMessage = this.getAttribute("default-message") || "";
+    }
+
+    this.render();
+  }
+
+  render(): void {
+    this.innerHTML = "";
+
+    if (this.instance?.direction === "rtl") {
+      this.setAttribute("dir", "rtl");
+    } else {
+      this.removeAttribute("dir");
+    }
+
+    this.containerEl = document.createElement("div");
+    this.containerEl.className = "pf-summary";
+    this.containerEl.textContent = this.defaultMessage;
+
+    this.appendChild(this.containerEl);
+  }
+
+  reconcileAria(): void {}
+
+  register(instance: Instance): void {
+    instance.registerSummary(this);
+    instance.on(
+      "search",
+      (term: unknown) => {
+        this.term = term as string;
+      },
+      this,
+    );
+
+    instance.on(
+      "results",
+      (results: unknown) => {
+        if (!this.containerEl || !results) return;
+        const searchResult = results as PagefindSearchResult;
+        const count = searchResult?.results?.length ?? 0;
+
+        if (!this.term) {
+          if (instance.faceted) {
+            const key =
+              count === 0
+                ? "total_zero_results"
+                : count === 1
+                  ? "total_one_result"
+                  : "total_many_results";
+            const text = instance.translate(key, { COUNT: count });
+            this.containerEl.textContent =
+              text || `${count} result${count === 1 ? "" : "s"}`;
+          } else {
+            this.containerEl.textContent = this.defaultMessage;
+          }
+          return;
+        }
+
+        const key =
+          count === 0
+            ? "zero_results"
+            : count === 1
+              ? "one_result"
+              : "many_results";
+        const text = instance.translate(key, {
+          SEARCH_TERM: this.term,
+          COUNT: count,
+        });
+        this.containerEl.textContent =
+          text || `${count} result${count === 1 ? "" : "s"} for ${this.term}`;
+      },
+      this,
+    );
+
+    instance.on(
+      "loading",
+      () => {
+        if (!this.containerEl) return;
+        const text = instance.translate("searching", {
+          SEARCH_TERM: this.term,
+        });
+        this.containerEl.textContent = text || `Searching for ${this.term}...`;
+      },
+      this,
+    );
+
+    instance.on(
+      "error",
+      (error: unknown) => {
+        if (!this.containerEl) return;
+        const err = error as PagefindError;
+        const errorText = instance.translate("error_search") || "Search failed";
+        this.containerEl.textContent = err.message || errorText;
+      },
+      this,
+    );
+
+    instance.on(
+      "translations",
+      () => {
+        this.render();
+      },
+      this,
+    );
+  }
+
+  update(): void {
+    if (this.hasAttribute("default-message")) {
+      this.defaultMessage = this.getAttribute("default-message") || "";
+      if (!this.term && this.containerEl) {
+        this.containerEl.textContent = this.defaultMessage;
+      }
+    }
+  }
+}
+
+if (!customElements.get("pagefind-summary")) {
+  customElements.define("pagefind-summary", PagefindSummary);
+}

package/core/announcer.ts

@@ -0,0 +1,134 @@
+export type AnnouncerPriority = "polite" | "assertive";
+
+interface AnnouncerRegions {
+  polite: [HTMLElement, HTMLElement];
+  assertive: [HTMLElement, HTMLElement];
+}
+
+// Delay before injecting content (Safari/VoiceOver timing)
+const ANNOUNCE_DELAY_MS = 100;
+// Delay before clearing content (enables repeat announcements)
+const CLEAR_DELAY_MS = 350;
+
+/**
+ * Global ARIA live region announcer.
+ *
+ * Creates two pre-rendered live regions (polite + assertive) at document root,
+ * double-buffered for reliable successive announcements.
+ */
+export class Announcer {
+  private regions: AnnouncerRegions | null = null;
+  private politeIndex: 0 | 1 = 0;
+  private assertiveIndex: 0 | 1 = 0;
+  private clearTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private containerId: string;
+  private idGenerator: (prefix: string) => string;
+
+  constructor(idGenerator: (prefix: string) => string) {
+    this.idGenerator = idGenerator;
+    this.containerId = idGenerator("pf-announcer");
+    this.createRegions();
+  }
+
+  private createRegions(): void {
+    if (typeof document === "undefined") return;
+
+    const container = document.createElement("div");
+    container.id = this.containerId;
+    container.setAttribute("data-pagefind-announcer", "");
+
+    const createRegionPair = (
+      priority: AnnouncerPriority,
+    ): [HTMLElement, HTMLElement] => {
+      const regions: HTMLElement[] = [];
+      for (let i = 0; i < 2; i++) {
+        const region = document.createElement("div");
+        region.id = this.idGenerator(`pf-${priority}-region`);
+        region.setAttribute("role", "status");
+        region.setAttribute("aria-live", priority);
+        region.setAttribute("aria-atomic", "true");
+        region.setAttribute("data-pf-sr-hidden", "");
+        container.appendChild(region);
+        regions.push(region);
+      }
+      return regions as [HTMLElement, HTMLElement];
+    };
+
+    this.regions = {
+      polite: createRegionPair("polite"),
+      assertive: createRegionPair("assertive"),
+    };
+
+    document.body.appendChild(container);
+  }
+
+  /**
+   * Announce a message to screen readers.
+   */
+  announce(message: string, priority: AnnouncerPriority = "polite"): void {
+    if (!this.regions || !message) return;
+
+    if (this.clearTimeoutId) {
+      clearTimeout(this.clearTimeoutId);
+      this.clearTimeoutId = null;
+    }
+
+    const currentIndex =
+      priority === "polite" ? this.politeIndex : this.assertiveIndex;
+    const region = this.regions[priority][currentIndex];
+
+    if (priority === "polite") {
+      this.politeIndex = currentIndex === 0 ? 1 : 0;
+    } else {
+      this.assertiveIndex = currentIndex === 0 ? 1 : 0;
+    }
+
+    const nextIndex =
+      priority === "polite" ? this.politeIndex : this.assertiveIndex;
+    this.regions[priority][nextIndex].textContent = "";
+
+    setTimeout(() => {
+      region.textContent = message;
+
+      // Schedule clearing the content to enable repeat announcements of same message
+      this.clearTimeoutId = setTimeout(() => {
+        region.textContent = "";
+        this.clearTimeoutId = null;
+      }, CLEAR_DELAY_MS);
+    }, ANNOUNCE_DELAY_MS);
+  }
+
+  /**
+   * Clear all live regions immediately.
+   */
+  clear(): void {
+    if (!this.regions) return;
+
+    if (this.clearTimeoutId) {
+      clearTimeout(this.clearTimeoutId);
+      this.clearTimeoutId = null;
+    }
+
+    for (const priority of ["polite", "assertive"] as const) {
+      for (const region of this.regions[priority]) {
+        region.textContent = "";
+      }
+    }
+  }
+
+  /**
+   * Remove announcer from DOM.
+   */
+  destroy(): void {
+    this.clear();
+
+    if (typeof document !== "undefined") {
+      const container = document.getElementById(this.containerId);
+      if (container) {
+        container.remove();
+      }
+    }
+
+    this.regions = null;
+  }
+}

package/core/focus-utils.ts

@@ -0,0 +1,89 @@
+const FOCUSABLE_SELECTOR = "a[href], button, input, [tabindex]";
+
+type FocusableElement = HTMLElement & { disabled?: boolean };
+
+/**
+ * Get all tabbable elements in tab order.
+ */
+export function getTabbablesInOrder(
+  container: Document | Element = document,
+): HTMLElement[] {
+  const elements = Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  );
+
+  const tabbable = elements.filter((el): el is FocusableElement => {
+    if (el.tabIndex < 0) return false;
+    if ((el as FocusableElement).disabled) return false;
+    if (el.hasAttribute("hidden")) return false;
+    if (window.getComputedStyle(el).display === "none") return false;
+    return true;
+  });
+
+  const withPositiveTabIndex: HTMLElement[] = [];
+  const withZeroTabIndex: HTMLElement[] = [];
+
+  for (const el of tabbable) {
+    if (el.tabIndex > 0) {
+      withPositiveTabIndex.push(el);
+    } else {
+      withZeroTabIndex.push(el);
+    }
+  }
+
+  withPositiveTabIndex.sort((a, b) => a.tabIndex - b.tabIndex);
+  return [...withPositiveTabIndex, ...withZeroTabIndex];
+}
+
+/**
+ * Given registered components and a starting element, find which component
+ * contains the next tabbable element in tab order.
+ */
+export function findNextComponentInTabOrder(
+  fromElement: Element,
+  components: HTMLElement[],
+): HTMLElement | null {
+  const tabbables = getTabbablesInOrder();
+  const currentIndex = tabbables.indexOf(fromElement as HTMLElement);
+  if (currentIndex === -1) return null;
+
+  const componentsWithTabPos = components
+    .map((component) => {
+      const firstTabbable = tabbables.find((t) => component.contains(t));
+      return {
+        component,
+        tabPos: firstTabbable ? tabbables.indexOf(firstTabbable) : -1,
+      };
+    })
+    .filter((c) => c.tabPos > currentIndex)
+    .sort((a, b) => a.tabPos - b.tabPos);
+
+  return componentsWithTabPos[0]?.component || null;
+}
+
+/**
+ * Given registered components and a starting element, find which component
+ * contains the previous tabbable element in tab order.
+ */
+export function findPreviousComponentInTabOrder(
+  fromElement: Element,
+  components: HTMLElement[],
+): HTMLElement | null {
+  const tabbables = getTabbablesInOrder();
+  const currentIndex = tabbables.indexOf(fromElement as HTMLElement);
+  if (currentIndex === -1) return null;
+
+  const componentsWithTabPos = components
+    .map((component) => {
+      const componentTabbables = tabbables.filter((t) => component.contains(t));
+      const lastTabbable = componentTabbables[componentTabbables.length - 1];
+      return {
+        component,
+        tabPos: lastTabbable ? tabbables.indexOf(lastTabbable) : -1,
+      };
+    })
+    .filter((c) => c.tabPos >= 0 && c.tabPos < currentIndex)
+    .sort((a, b) => b.tabPos - a.tabPos);
+
+  return componentsWithTabPos[0]?.component || null;
+}