@qaiddev/thumbs-embed 1.2.1 → 1.3.0

package/dist/annotate.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Screenshot annotation / markup editor for the thumbs embed.
+ *
+ * After a screenshot is captured the user can draw on it — rectangles, arrows,
+ * a freehand pen, and a blur/redact box — in a full-screen, focus-trapped,
+ * WCAG 2.2 AA dialog rendered inside the embed's overlay shadow root. On "Done"
+ * the base image and the vector shapes are composited into a fresh WebP data
+ * URL (so downstream code is unchanged); on "Skip"/Escape the original is kept.
+ *
+ * The geometry and compositing are kept as pure-ish exported functions
+ * (`drawShape`, `rectFromPoints`, `compositeAnnotations`) so they can be tested
+ * without a real rendering engine — happy-dom has no raster, so tests assert on
+ * spied canvas-context calls rather than pixels. The {@link AnnotationEditor}
+ * controller keeps the DOM wiring thin and its interactive methods are public
+ * so they can be driven directly in tests.
+ */
+/** The four drawing tools. */
+export type ShapeType = "rect" | "arrow" | "pen" | "blur";
+/** A point in the screenshot's natural-pixel coordinate space. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * A single vector annotation. `rect`, `arrow` and `blur` use `points[0]` as the
+ * drag start and `points[1]` as the drag end; `pen` uses every point in order.
+ */
+export interface Shape {
+    type: ShapeType;
+    color: string;
+    strokeWidth: number;
+    points: Point[];
+}
+/** Human-readable labels for the toolbar / announcements (all overridable). */
+export interface AnnotationLabels {
+    title: string;
+    instructions: string;
+    rectangle: string;
+    arrow: string;
+    pen: string;
+    blur: string;
+    undo: string;
+    skip: string;
+    done: string;
+}
+/**
+ * Normalise two drag corners into a top-left origin plus positive width/height,
+ * regardless of the direction the user dragged.
+ */
+export declare function rectFromPoints(a: Point, b: Point): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Draw a single shape onto a 2D context in the shape's own (natural-pixel)
+ * coordinates. Used both for the live editing preview and for the final
+ * composite, so what the user sees is exactly what is submitted.
+ */
+export declare function drawShape(ctx: CanvasRenderingContext2D, shape: Shape): void;
+/**
+ * Composite the base screenshot and the drawn shapes into a new WebP data URL
+ * at the image's natural size. Falls back to the original data URL if the image
+ * can't be loaded or a 2D context isn't available (so a submission is never
+ * lost). This is intentionally standalone so it can be unit-tested in isolation.
+ */
+export declare function compositeAnnotations(dataUrl: string, shapes: Shape[], opts?: {
+    quality?: number;
+}): Promise<string>;
+/** Options for {@link AnnotationEditor} / {@link openAnnotationEditor}. */
+export interface AnnotationEditorOptions {
+    /** The captured screenshot as a WebP data URL. */
+    dataUrl: string;
+    /** Shadow root (or element) the editor is mounted into. */
+    root: ShadowRoot | HTMLElement;
+    /** WebP quality for the re-encoded composite. */
+    quality?: number;
+    /** Default stroke colour for rectangle/arrow/pen. */
+    color?: string;
+    /** Default stroke width. */
+    strokeWidth?: number;
+    /** Label overrides. */
+    labels?: Partial<AnnotationLabels>;
+    /** Apply the embed's per-instance `--qaid-*` CSS variables to the container. */
+    applyVars?: (el: HTMLElement) => void;
+    /** Announce a message via the embed's live regions. */
+    announce?: (message: string, assertive?: boolean) => void;
+    /** Turn the container into an accessible modal dialog (focus trap + inert). */
+    openDialog?: (container: HTMLElement, opts: {
+        labelledbyId?: string;
+        describedbyId?: string;
+    }) => void;
+    /** Tear down the dialog semantics and restore focus. */
+    closeDialog?: () => void;
+}
+/**
+ * Full-screen screenshot annotation editor. Construct it, call {@link open}
+ * (which returns a promise resolving to the composited WebP, or `null` when the
+ * user skips), and the controller manages its own DOM and teardown.
+ */
+export declare class AnnotationEditor {
+    readonly shapes: Shape[];
+    tool: ShapeType;
+    private readonly opts;
+    private readonly labels;
+    private readonly color;
+    private readonly strokeWidth;
+    private readonly uid;
+    private container;
+    private canvas;
+    private ctx;
+    private toolbar;
+    private undoBtn;
+    private img;
+    private drawing;
+    private current;
+    private settled;
+    private resolveResult;
+    constructor(opts: AnnotationEditorOptions);
+    /** Mount the editor and resolve when the user commits (Done) or skips. */
+    open(): Promise<string | null>;
+    private toolButton;
+    private actionButton;
+    private mount;
+    /** Convert a pointer event's client coordinates into natural image pixels. */
+    private toImageCoords;
+    /** Repaint the display canvas: base image (if loaded) then every shape. */
+    redraw(): void;
+    /** Select the active drawing tool and reflect it on the toolbar. */
+    selectTool(tool: ShapeType): void;
+    private onToolbarClick;
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: () => void;
+    onKeyDown: (e: KeyboardEvent) => void;
+    /** Remove the most recently added shape. */
+    undo(): void;
+    /** Composite the annotations and resolve with the new WebP data URL. */
+    done(): Promise<void>;
+    /** Discard annotations and resolve with `null` (caller keeps the original). */
+    skip(): void;
+    private settle;
+    private teardown;
+}
+/**
+ * Open the annotation editor and resolve with the composited WebP data URL, or
+ * `null` if the user skipped. Thin entry point used by the embed.
+ */
+export declare function openAnnotationEditor(opts: AnnotationEditorOptions): Promise<string | null>;

package/dist/embed.d.ts

@@ -134,6 +134,18 @@ export declare class QaidFeedback {
     private removeTargetingOverlay;
     private showSelectedMarker;
     private hideSelectedMarker;
+    /** Whether to capture the screenshot with the DOM/canvas method (html2canvas)
+     *  instead of the permission-based Screen Capture API. Explicit "dom" wins;
+     *  otherwise DOM is used on touch devices to avoid the getDisplayMedia prompt. */
+    private shouldCaptureViaDom;
+    /**
+     * Open the full-screen annotation editor over the captured screenshot,
+     * reusing the overlay shadow host and the shared dialog a11y helpers.
+     * Resolves with the composited WebP data URL, or null when the user skips
+     * (caller keeps the original). Pointer events on the overlay host are
+     * enabled while the editor is open and restored on close.
+     */
+    private openAnnotationEditor;
     private submitFeedback;
     /**
      * Quest id linked to `type`, or "" when quest launching is disabled

package/dist/icons.d.ts

@@ -4,3 +4,10 @@
 export declare const THUMBS_UP_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M14 10h4.764a2 2 0 011.789 2.894l-3.5 7A2 2 0 0115.263 21h-4.017c-.163 0-.326-.02-.485-.06L7 20m7-10V5a2 2 0 00-2-2h-.095c-.5 0-.905.405-.905.905 0 .714-.211 1.412-.608 2.006L7 11v9m7-10h-2M7 20H5a2 2 0 01-2-2v-6a2 2 0 012-2h2.5\"/>\n</svg>";
 export declare const THUMBS_DOWN_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M10 14H5.236a2 2 0 01-1.789-2.894l3.5-7A2 2 0 018.737 3h4.018a2 2 0 01.485.06l3.76.94m-7 10v5a2 2 0 002 2h.095c.5 0 .905-.405.905-.905 0-.714.211-1.412.608-2.006L17 13V4m-7 10h2m5-10h2a2 2 0 012 2v6a2 2 0 01-2 2h-2.5\"/>\n</svg>";
 export declare const RECORD_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M15.75 10.5l4.72-4.72a.75.75 0 011.28.53v11.38a.75.75 0 01-1.28.53l-4.72-4.72M4.5 18.75h9a2.25 2.25 0 002.25-2.25v-9a2.25 2.25 0 00-2.25-2.25h-9A2.25 2.25 0 002.25 7.5v9a2.25 2.25 0 002.25 2.25z\"/>\n</svg>";
+export declare const RECTANGLE_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <rect x=\"4\" y=\"6\" width=\"16\" height=\"12\" rx=\"1\" stroke-linejoin=\"round\"/>\n</svg>";
+export declare const ARROW_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M5 19L19 5m0 0h-8m8 0v8\"/>\n</svg>";
+export declare const PENCIL_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 20h9M16.5 3.5a2.121 2.121 0 013 3L7 19l-4 1 1-4L16.5 3.5z\"/>\n</svg>";
+export declare const BLUR_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 3s6 6.4 6 10a6 6 0 01-12 0c0-3.6 6-10 6-10z\"/>\n</svg>";
+export declare const UNDO_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 14L4 9l5-5M4 9h11a5 5 0 010 10h-4\"/>\n</svg>";
+export declare const DONE_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M20 6L9 17l-5-5\"/>\n</svg>";
+export declare const SKIP_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M6 6l12 12M18 6L6 18\"/>\n</svg>";

package/dist/index.d.ts

@@ -36,3 +36,5 @@ export { createVideoRecorder, isVideoRecordingSupported, getSupportedMimeType }
 export type { VideoRecorder, VideoRecorderOptions } from "./video-capture";
 export { captureDomScreenshot, isDomScreenshotSupported } from "./screenshot-dom";
 export type { DomScreenshotOptions } from "./screenshot-dom";
+export { openAnnotationEditor, compositeAnnotations, drawShape, rectFromPoints, AnnotationEditor, } from "./annotate";
+export type { Shape, ShapeType, Point, AnnotationLabels, AnnotationEditorOptions, } from "./annotate";