@touchcastllc/napster-companion-api-dev 2.0.0-alpha.12 → 2.0.0-alpha.13

package/lib/utils/InactiveOverlayManager.d.ts

@@ -43,6 +43,10 @@ export declare class InactiveOverlayManager {
     private isVisible;
     private readonly mountElement;
     private pipTarget;
+    /** Where keyboard focus was when the overlay took it (CA-1139). */
+    private returnFocusTo;
+    /** Switches back on what the overlay covers (CA-1139 review). */
+    private restoreCovered;
     private readonly callbacks;
     constructor(mountElement: HTMLElement, callbacks?: InactiveOverlayCallbacks);
     /**
@@ -55,6 +59,12 @@ export declare class InactiveOverlayManager {
      * This is the single entry point for hiding the overlay
      */
     hide(): void;
+    /**
+     * restoreFocus is false when the session is ending (countdown run out,
+     * teardown): destroyInstance() moves focus once, to the entry point or
+     * mount — restoring here first would move it twice (Serhii's review).
+     */
+    private hideOverlay;
     /**
      * Check if overlay is currently visible
      */

package/lib/utils/announcer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The widget's one screen-reader announcer (CA-1139).
+ *
+ * A single visually hidden `aria-live="polite"` region per root, shared by
+ * everything that needs to speak — several regions would talk over each
+ * other. The PiP document gets its own, since a live region only speaks for
+ * the document it lives in. Styled in App.css.
+ */
+/**
+ * Text is written this long after the region is cleared. Screen readers
+ * announce a *change* to a region that already exists; clearing and writing
+ * in the same tick is no change at all, and a region created in the same tick
+ * as its text is often not read.
+ */
+export declare const ANNOUNCE_DELAY_MS = 100;
+/**
+ * Adds the announcer to a root, or returns the one it has. Call this when the
+ * root is created, so the region already exists by the time anything speaks.
+ */
+export declare function createAnnouncer(root: HTMLElement): HTMLElement;
+/**
+ * Reads `text` out through the announcer of the root `from` belongs to.
+ * `from` may be inside the root (main page) or contain it (the PiP body,
+ * which holds the PiP stage).
+ */
+export declare function announce(from: HTMLElement, text: string): void;

package/lib/utils/focus.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Focuses an element that may not be focusable on its own — a container the
+ * widget was in, or the widget root — so focus has somewhere sensible to land
+ * instead of <body> (CA-1139). A plain <div> gets a temporary tabindex="-1",
+ * dropped again once focus moves on; a tabindex the host set is left as is.
+ * <body> is skipped: focus is already there, and it must not gain a tabindex.
+ */
+export declare function focusWithTemporaryTabindex(el: HTMLElement): void;

package/lib/utils/hostLanguage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The widget's own texts are English and the SDK root says so (`lang="en"`,
+ * CA-1148). Texts the integrator supplies through the config (button label
+ * and description, disclaimer) are written in the host page's language
+ * instead, so they carry the page's `lang` — otherwise a screen reader would
+ * read, say, a German label with the English voice.
+ */
+/** The host page's declared language, or "" when it declares none. */
+export declare function hostLanguage(): string;
+/**
+ * Marks an element holding integrator text with the host page's language.
+ * With no page language there is nothing to mark it with: the attribute is
+ * removed and the element inherits the root's English.
+ */
+export declare function applyHostLanguage(el: HTMLElement): void;

package/lib/utils/inertSiblings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Makes everything next to `el` inert — not focusable, not read by screen
+ * readers — and returns a function that undoes it. Used while an overlay
+ * covers its siblings, so Tab cannot reach a control hidden under it
+ * (CA-1139). Not `aria-modal`: that would claim the whole host page.
+ *
+ * A sibling holding the widget's announcer is not made inert itself — inert
+ * content is not read out, so the warning would go silent (the PiP stage
+ * holds both the announcer and the controls). Its other children are, instead.
+ * Elements that were already inert are left out, so the undo keeps them so.
+ */
+export declare function makeSiblingsInert(el: HTMLElement): () => void;

package/lib/utils/widgetRoot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The widget root `from` belongs to: the root around it on the main page, or
+ * the stage inside it when `from` is the PiP body. Falls back to `from`.
+ */
+export declare function findWidgetRoot(from: HTMLElement): HTMLElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.13",
   "keywords": [
     "napster",
     "companion-api",