@artymclabin/qa-review 0.3.8 → 0.3.10

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.10 - 2026-09-19
+
+- OUTSIDE TAP MINIMIZES THE PANEL, ON MOBILE: the only way to collapse the
+  card used to be the small minimize button in its header, and hitting a
+  small target on a phone is real friction. A pointerdown anywhere outside
+  the card now minimizes it too, scoped to mobile-width viewports (desktop
+  keeps the explicit button only, since a stray click outside a small
+  floating panel on a mouse is far more likely incidental than intentional).
+  Uses a capture-phase listener plus a contains() check against the card, so
+  dragging the card by its header (which also starts with a pointerdown,
+  from inside the card) is unaffected.
+
+## 0.3.9 - 2026-09-13
+
+- PICKED FORM CONTROLS ARE NAMED BY LABEL, NOT BY TAG: a form control has no
+  textContent, so the element picker fell through to `tagName.toLowerCase()`
+  for every input, textarea and select. Picking the seven link fields on the
+  GameReady pitch page produced seven identical `<input>` references, with
+  no way for the reviewer to say which row they meant. The picker now reads
+  the name a human would: own text, accessible name (aria-label /
+  aria-labelledby), the associated `<label>` (including a wrapping label),
+  placeholder, alt, title, current value, name attribute, and only then the
+  tag.
+
 ## 0.3.8 - 2026-08-09
 
 - BACK TO REVIEW IS AN UNDO, NOT A RESTART: the finish panel's "Back to review"

package/dist/client/QAReviewOverlay.d.ts

@@ -4,7 +4,31 @@ import { type QAJourneyConfig } from "./journey.js";
 /** Was the pointer gesture a click (vs a drag)? Exported for tests. */
 export declare function isClickGesture(dx: number, dy: number): boolean;
 /** Note-reference text for a picked element: « label » (truncated) or tag. */
-export declare function pickedElementRef(textContent: string | null, tagName: string): string;
+export interface PickedElementDescriptor {
+    textContent?: string | null;
+    tagName: string;
+    /** aria-label, or the aria-labelledby target's text. */
+    ariaLabel?: string | null;
+    /** Text of an associated <label>, whether wrapping or `for=`-linked. */
+    labelText?: string | null;
+    placeholder?: string | null;
+    alt?: string | null;
+    title?: string | null;
+    /** Current value, for a control the reviewer has already filled in. */
+    value?: string | null;
+    name?: string | null;
+}
+/**
+ * 🚨 A form control has no `textContent`, so reading only that made every input,
+ * textarea and select come out as its bare tag name: a reviewer picking seven link
+ * fields got seven « input » refs with no way to say which row they meant. The
+ * order below is "what a human would call it" - its own text, then the accessible
+ * name, then the label a designer wrote, then what it holds - and the tag name only
+ * when the element genuinely has no name at all.
+ */
+export declare function pickedElementRef(el: PickedElementDescriptor): string;
+/** Read a live DOM element into the descriptor above. */
+export declare function describePickedElement(el: Element): PickedElementDescriptor;
 /**
  * Element-pick mode semantics (0.3.1): LEFT click picks and exits the mode;
  * RIGHT click picks and STAYS for multi-select (context menu suppressed).

package/dist/client/QAReviewOverlay.js

@@ -52,11 +52,63 @@ const CLICK_DRAG_THRESHOLD_PX = 6;
 export function isClickGesture(dx, dy) {
     return Math.hypot(dx, dy) < CLICK_DRAG_THRESHOLD_PX;
 }
-/** Note-reference text for a picked element: « label » (truncated) or tag. */
-export function pickedElementRef(textContent, tagName) {
-    const label = (textContent || "").replace(/\s+/g, " ").trim().slice(0, 48) || tagName.toLowerCase();
+/**
+ * 🚨 A form control has no `textContent`, so reading only that made every input,
+ * textarea and select come out as its bare tag name: a reviewer picking seven link
+ * fields got seven « input » refs with no way to say which row they meant. The
+ * order below is "what a human would call it" - its own text, then the accessible
+ * name, then the label a designer wrote, then what it holds - and the tag name only
+ * when the element genuinely has no name at all.
+ */
+export function pickedElementRef(el) {
+    const clean = (v) => (v || "").replace(/\s+/g, " ").trim();
+    const label = [
+        clean(el.textContent),
+        clean(el.ariaLabel),
+        clean(el.labelText),
+        clean(el.placeholder),
+        clean(el.alt),
+        clean(el.title),
+        clean(el.value),
+        clean(el.name),
+    ]
+        .find((c) => c.length > 0)
+        ?.slice(0, 48) || el.tagName.toLowerCase();
     return ` «${label}» `;
 }
+/** Read a live DOM element into the descriptor above. */
+export function describePickedElement(el) {
+    const labelledBy = el.getAttribute("aria-labelledby");
+    const labelledByText = labelledBy
+        ? labelledBy
+            .split(/\s+/)
+            .map((id) => el.ownerDocument?.getElementById(id)?.textContent ?? "")
+            .join(" ")
+        : null;
+    // A control's label is either an ancestor <label> or one pointing at its id.
+    let labelText = null;
+    const id = el.getAttribute("id");
+    if (id) {
+        const escaped = id.replace(/["\\]/g, "\\$&");
+        labelText = el.ownerDocument?.querySelector(`label[for="${escaped}"]`)?.textContent ?? null;
+    }
+    if (!labelText)
+        labelText = el.closest("label")?.textContent ?? null;
+    const isControl = ["INPUT", "TEXTAREA", "SELECT"].includes(el.tagName);
+    return {
+        // A control's own textContent is empty anyway; skipping it explicitly keeps the
+        // intent readable rather than relying on that emptiness.
+        textContent: isControl ? null : el.textContent,
+        tagName: el.tagName,
+        ariaLabel: el.getAttribute("aria-label") || labelledByText,
+        labelText,
+        placeholder: el.getAttribute("placeholder"),
+        alt: el.getAttribute("alt"),
+        title: el.getAttribute("title"),
+        value: isControl ? (el.value ?? null) : null,
+        name: el.getAttribute("name"),
+    };
+}
 /**
  * Element-pick mode semantics (0.3.1): LEFT click picks and exits the mode;
  * RIGHT click picks and STAYS for multi-select (context menu suppressed).
@@ -239,6 +291,31 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
         mq.addEventListener("change", onChange);
         return () => mq.removeEventListener("change", onChange);
     }, []);
+    // OUTSIDE TAP TO MINIMIZE (mobile only): pixel-hunting for the small
+    // minimize button is real friction on a phone, so a tap anywhere outside
+    // the card collapses it to the bubble - same result as the button, far
+    // cheaper to hit. Scoped to mobile width: on desktop a stray click outside
+    // a small floating panel is much more likely incidental than intentional.
+    // Capture phase + native listener so it fires ahead of (and regardless of)
+    // any stopPropagation on the underlying page, and a pointerdown that starts
+    // INSIDE the card (e.g. dragging the header) is excluded by the contains()
+    // check, so dragging is unaffected.
+    React.useEffect(() => {
+        if (typeof window.matchMedia !== "function")
+            return;
+        if (!active || finished || minimized || mobilePreview)
+            return;
+        const onPointerDown = (e) => {
+            if (!window.matchMedia(`(max-width: ${AUTO_BUBBLE_MAX_WIDTH_PX}px)`).matches)
+                return;
+            const target = e.target;
+            if (cardRef.current && target && !cardRef.current.contains(target)) {
+                setMinimized(true);
+            }
+        };
+        document.addEventListener("pointerdown", onPointerDown, true);
+        return () => document.removeEventListener("pointerdown", onPointerDown, true);
+    }, [active, finished, minimized, mobilePreview]);
     // Hydrate verdicts and LAND on the first outstanding item. The DURABLE
     // server ledger is the source of truth; localStorage is only a fast cache.
     // 🚨 The store NEVER pre-approves (no seed). The round derives from
@@ -378,7 +455,7 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                 return; // ignore the panel itself
             e.preventDefault();
             e.stopPropagation();
-            const ref = pickedElementRef(el.textContent, el.tagName);
+            const ref = pickedElementRef(describePickedElement(el));
             const ta = noteRef.current;
             if (ta) {
                 const s = ta.selectionStart ?? note.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artymclabin/qa-review",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Interactive on-page QA review overlay (spotlight walkthrough, approve/reject verdict ledger) with a framework-agnostic server handler factory and a self-provisioning Postgres store.",
   "license": "MIT",
   "repository": {