@qaiddev/thumbs-embed 1.0.16 → 1.1.0

package/dist/a11y.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared accessibility primitives for the qaid embeds.
+ *
+ * These helpers are intentionally framework-free and self-contained (no CSS
+ * dependency) so they can be dropped into any open shadow root. They cover the
+ * cross-cutting WCAG 2.2 AA infrastructure called for in the embed
+ * accessibility plan: live-region announcements, focus management (trap,
+ * save/restore), dialog semantics, and background isolation.
+ */
+/** Host for the live regions: either a shadow root or a plain element. */
+export type AnnounceRoot = ShadowRoot | HTMLElement;
+/** Options accepted by {@link announce}. */
+export interface AnnounceOptions {
+    /** Route the message through the assertive (role="alert") region. */
+    assertive?: boolean;
+}
+/** Options accepted by {@link applyDialog}. */
+export interface ApplyDialogOptions {
+    /** id of the element that labels the dialog (wired via aria-labelledby). */
+    labelledbyId?: string;
+    /** id of the element that describes the dialog (wired via aria-describedby). */
+    describedbyId?: string;
+    /** Fallback accessible name when no labelling element exists. */
+    label?: string;
+}
+/** Handle returned by {@link createFocusTrap}. */
+export interface FocusTrap {
+    /** Remove the trap's key handler and clean up any tabindex it added. */
+    release(): void;
+}
+/**
+ * Announce a message to assistive technology via a visually-hidden live region
+ * mounted inside `root`. The two regions (polite role="status" and assertive
+ * role="alert") are created lazily on first use and reused thereafter.
+ *
+ * The target region is cleared before the new text is written so that repeated
+ * identical messages are re-announced rather than coalesced.
+ */
+export declare function announce(root: AnnounceRoot, message: string, opts?: AnnounceOptions): void;
+/**
+ * Collect the focusable descendants of `container` in DOM order, excluding
+ * disabled controls, elements opted out with tabindex="-1", and elements that
+ * are hidden (via the hidden attribute or an inline display/visibility rule on
+ * themselves or an ancestor up to the document root).
+ */
+export declare function getFocusable(container: HTMLElement): HTMLElement[];
+/**
+ * Trap keyboard focus inside `container`: Tab / Shift+Tab cycle between the
+ * first and last focusable descendants and can never leave the container. On
+ * creation focus moves to the first focusable element, or to the container
+ * itself (made programmatically focusable) when it has no focusable children.
+ *
+ * Call {@link FocusTrap.release} to remove the handler; pair it with
+ * {@link restoreFocus} to return focus to the invoking control.
+ */
+export declare function createFocusTrap(container: HTMLElement): FocusTrap;
+/**
+ * Capture the currently focused element (drilling through shadow roots) so it
+ * can be restored later with {@link restoreFocus}. Returns null when focus is
+ * on nothing focusable.
+ */
+export declare function saveFocus(): HTMLElement | null;
+/**
+ * Restore focus to a previously saved element. Safe to call with null or an
+ * element that has since been detached (a missing/throwing focus is ignored).
+ */
+export declare function restoreFocus(el: HTMLElement | null): void;
+/**
+ * Apply dialog semantics to `el`: role="dialog", aria-modal="true", and the
+ * naming/description wiring described by `opts`. Prefer aria-labelledby /
+ * aria-describedby pointing at visible title/subtitle elements; fall back to
+ * aria-label when no visible label element exists.
+ */
+export declare function applyDialog(el: HTMLElement, opts?: ApplyDialogOptions): void;
+/**
+ * Isolate the background from assistive technology while a dialog is open by
+ * marking every top-level sibling of the dialog inert (with an aria-hidden
+ * fallback). `except` is the open dialog (or any element inside it); the
+ * top-level element that contains it is left interactive.
+ *
+ * Returns a restore function that reverts every attribute this call changed,
+ * leaving elements that were already inert/hidden untouched.
+ */
+export declare function setBackgroundInert(except: HTMLElement): () => void;

package/dist/element-selector.d.ts

@@ -31,3 +31,99 @@ export declare function generateSelector(element: Element): string;
  * Generate complete element info for feedback
  */
 export declare function generateElementInfo(element: Element): ElementInfo;
+/**
+ * Default set of "targetable" elements for keyboard navigation: focusable
+ * controls, ARIA-role'd nodes, common semantic content, and anything already
+ * carrying one of the stable data attributes we key selectors off of.
+ */
+export declare const TARGETABLE_SELECTOR: string;
+/**
+ * Best-effort visibility test used to keep invisible nodes out of the keyboard
+ * candidate list. Deliberately layout-free (no getBoundingClientRect) so it is
+ * stable in headless/test environments: it only rejects nodes that are
+ * explicitly hidden via the `hidden` attribute, `aria-hidden`, or a computed
+ * `display:none` / `visibility:hidden`.
+ */
+export declare function isElementVisible(element: Element): boolean;
+export interface CollectTargetableOptions {
+    /** Where to search for candidates (default `document.body`). */
+    root?: ParentNode;
+    /** CSS selector for candidate elements (default {@link TARGETABLE_SELECTOR}). */
+    selector?: string;
+    /** Return true to drop an element (e.g. the embed's own shadow hosts). */
+    isExcluded?: (element: Element) => boolean;
+    /** Visibility predicate (default {@link isElementVisible}). */
+    isVisible?: (element: Element) => boolean;
+}
+/**
+ * Collect the ordered list of elements a keyboard user can target. Document
+ * order matches the natural Tab order closely enough for feedback targeting.
+ */
+export declare function collectTargetableElements(options?: CollectTargetableOptions): Element[];
+export interface KeyboardTargetingOptions {
+    /**
+     * Explicit candidate list. When omitted, candidates are collected via
+     * {@link collectTargetableElements} using `root` / `selector` / `isExcluded`
+     * / `isVisible`.
+     */
+    candidates?: Element[];
+    /** Passed through to {@link collectTargetableElements} when `candidates` is omitted. */
+    root?: ParentNode;
+    /** Passed through to {@link collectTargetableElements} when `candidates` is omitted. */
+    selector?: string;
+    /** Passed through to {@link collectTargetableElements} when `candidates` is omitted. */
+    isExcluded?: (element: Element) => boolean;
+    /** Passed through to {@link collectTargetableElements} when `candidates` is omitted. */
+    isVisible?: (element: Element) => boolean;
+    /**
+     * Element to start the highlight on. Defaults to `document.activeElement`
+     * when it is one of the candidates, otherwise the first candidate.
+     */
+    initial?: Element | null;
+    /**
+     * Move native focus to the highlighted element (default true). This is what
+     * keeps a screen reader / focus ring on the highlight; non-focusable nodes
+     * get a temporary `tabindex="-1"` that is removed on {@link stop}. The cursor
+     * is never hidden.
+     */
+    moveFocus?: boolean;
+    /** Where the keydown listener is attached (default `document`). */
+    eventTarget?: Document | HTMLElement;
+    /** Fired whenever the highlighted candidate changes (and once on start). */
+    onHighlight?: (element: Element, index: number) => void;
+    /** Fired when the user commits a selection (Enter / Space). Auto-stops first. */
+    onSelect: (element: Element) => void;
+    /** Fired when the user cancels (Escape). Auto-stops first. */
+    onCancel?: () => void;
+}
+export interface KeyboardTargetingController {
+    /** The (frozen) candidate list being navigated. */
+    readonly candidates: readonly Element[];
+    /** Index of the highlighted candidate, or -1 when there are none. */
+    getIndex(): number;
+    /** The highlighted candidate, or null when there are none. */
+    getCurrent(): Element | null;
+    /** Highlight the next candidate (wraps to the first). */
+    next(): void;
+    /** Highlight the previous candidate (wraps to the last). */
+    prev(): void;
+    /** Highlight a specific index (wraps out-of-range values). */
+    moveTo(index: number): void;
+    /** Commit the current candidate (fires onSelect) and stop. */
+    select(): void;
+    /** Cancel (fires onCancel) and stop. */
+    cancel(): void;
+    /**
+     * Handle a keydown. Wired automatically to `eventTarget`; exposed so a host
+     * can forward events from another surface (e.g. the embed's shadow root).
+     */
+    handleKey(event: KeyboardEvent): void;
+    /** Remove the listener and restore any temporary tabindex. Idempotent. */
+    stop(): void;
+}
+/**
+ * Start a keyboard element-targeting session. The returned controller wires its
+ * own capture-phase keydown listener on `eventTarget` and emits the initial
+ * highlight synchronously before returning.
+ */
+export declare function startKeyboardTargeting(options: KeyboardTargetingOptions): KeyboardTargetingController;

package/dist/embed.d.ts

@@ -42,6 +42,13 @@ export declare class QaidFeedback {
     private backdrop;
     private dismissBtn;
     private cssVars;
+    private keyboardController;
+    private activeThumbBtn;
+    private keyboardActivation;
+    private dialogTrigger;
+    private dialogTrap;
+    private dialogRestoreInert;
+    private readonly uid;
     private boundKeyDown;
     private boundMouseMove;
     private boundClick;
@@ -52,6 +59,21 @@ export declare class QaidFeedback {
     private boundBeforeSwap;
     constructor(config: FeedbackConfig);
     private applyVars;
+    /**
+     * Announce a message via the shared visually-hidden live regions.
+     * Prefer the overlay shadow root (which hosts every transient surface and
+     * is never inerted by its own dialogs) so announcements are not suppressed
+     * while a dialog aria-hides the main button host.
+     */
+    private announceMsg;
+    /**
+     * Turn a transient surface into an accessible modal dialog: save the
+     * invoking control, apply dialog semantics, trap focus, and inert the
+     * background. Paired with closeDialogA11y() on every close path.
+     */
+    private openDialogA11y;
+    private closeDialogA11y;
+    private clearActiveThumb;
     private init;
     /**
      * Watch for the shadow hosts being removed from the DOM by framework
@@ -81,6 +103,14 @@ export declare class QaidFeedback {
     private handleThumbClick;
     private submitDirectFeedback;
     private startTargeting;
+    /**
+     * Keyboard-driven targeting. Mirrors startTargeting minus the mouse
+     * plumbing: no `qaid-targeting` body class (keeps the cursor visible for
+     * keyboard users), no mouse reticle, and no document mouse/click listeners.
+     * The KeyboardTargetingController owns Tab/Arrow/Enter/Space/Escape.
+     */
+    private startKeyboardTargetingFlow;
+    private selectKeyboardTarget;
     private createTargetingOverlay;
     private handleKeyDown;
     private handleMouseMove;