Live Region

---
// src/components/ui/utility/live-region/LiveRegion.astro — headless primitive (see ../../README.md).
// An announcer any application code can push a string into, without holding a reference to anything:
//
//     document.dispatchEvent(new CustomEvent("live-region:announce", { detail: "Draft saved" }));
//     document.dispatchEvent(
//       new CustomEvent("live-region:announce", { detail: { message: "Upload failed", politeness: "assertive" } }),
//     );
//
// RENDER IT ONCE, HIGH IN YOUR LAYOUT, and leave it empty. That is not tidiness — `aria-live` is only
// honoured on a region that was already in the document when its contents changed, so a region created
// in the same tick as its first message announces nothing, on every platform, silently. It is the same
// fact that makes Toaster a component rather than a <div>, and this is the version for the announcements
// that are not toasts.
//
// A second region with `politeness="assertive"` is how you interrupt: a live region cannot be polite
// for one message and assertive for the next, so politeness is a property of the REGION and the event
// picks which one speaks.
//
// It renders visible (and empty, so it occupies nothing). Wrap it in <VisuallyHidden> when the message
// has no business on screen — which is the usual case, and why the two primitives shipped together.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"div"> & {
  politeness?: "polite" | "assertive";
  /** `false` announces only what changed, for a region you append to rather than replace. */
  atomic?: boolean;
};

const { politeness = "polite", atomic = true, class: className, ...rest } = Astro.props;
---

<div
  role={politeness === "assertive" ? "alert" : "status"}
  aria-live={politeness}
  aria-atomic={atomic}
  data-slot="live-region"
  data-politeness={politeness}
  class={className}
  {...rest}
>
</div>

<script>
  // No `onReady` and no per-element wiring: one delegated listener at module scope, the arrangement
  // `_dialog.ts` and `_popover.ts` use. Astro includes this module once however many regions are on
  // the page, and a document-level listener survives a view transition without re-binding — so there
  // is nothing to re-init and no way to bind it twice.

  /** The message, from either shape of `detail` — a bare string or `{ message, politeness }`. */
  function read(detail: unknown): { message: string; politeness: string } {
    if (typeof detail === "string") return { message: detail, politeness: "polite" };
    if (detail && typeof detail === "object") {
      const { message, politeness } = detail as { message?: unknown; politeness?: unknown };
      return {
        message: typeof message === "string" ? message : "",
        politeness: politeness === "assertive" ? "assertive" : "polite",
      };
    }
    return { message: "", politeness: "polite" };
  }

  document.addEventListener("live-region:announce", (event) => {
    const { message, politeness } = read((event as CustomEvent).detail);
    const region = document.querySelector<HTMLElement>(
      `[data-slot="live-region"][data-politeness="${politeness}"]`,
    );
    if (!region) return;

    // CLEAR, THEN SET IN A LATER TASK. Writing the same string twice announces once — the region
    // only speaks when its contents CHANGE, so "Saved" after "Saved" is silence, which is precisely
    // the case a user most needs to hear. Emptying it first makes the second write a change.
    //
    // A timeout and not `requestAnimationFrame`: frames do not run in a background tab, and an
    // announcement queued from a finished upload in a tab nobody is looking at would never land.
    region.textContent = "";
    setTimeout(() => {
      region.textContent = message;
    });
  });
</script>

import LiveRegion from "./LiveRegion.astro";

export { LiveRegion };
export default LiveRegion;