visual-feedback 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.1 (2026-10-12)
+
+- The trigger shows its name as a tooltip. With a `shortcut` set, the tooltip names it too, the way
+  the platform's keyboards do, such as `Send feedback (Option + Shift + F)` on a Mac and
+  `(Alt + Shift + F)` elsewhere (SPEC §3).
+- A `shortcut` with no key, such as `"Alt+"`, now matches nothing: before, a key press whose code
+  was empty, as some virtual keyboards send, could open the widget.
+
 ## 0.3.0 (2026-10-11)
 
 - Breaking: with no `--vf-*` variables set, the widget now matches the site by itself. It takes

package/dist/index.mjs

@@ -1,2 +1,2 @@
 
-export { t as createFeedback, n as discardDraft } from "./widget-DvGTo0B4.mjs";
+export { t as createFeedback, n as discardDraft } from "./widget-Ryu07XUU.mjs";

package/dist/react.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { t as createFeedback } from "./widget-DvGTo0B4.mjs";
+import { t as createFeedback } from "./widget-Ryu07XUU.mjs";
 import { useEffect, useRef } from "react";
 //#region src/react/index.ts
 function Feedback(props) {

package/dist/{widget-DvGTo0B4.mjs → widget-Ryu07XUU.mjs}

@@ -223,6 +223,41 @@ const noop = {
 	update() {},
 	on: () => () => {}
 };
+const MODIFIERS = [
+	"alt",
+	"shift",
+	"control",
+	"meta"
+];
+/** A shortcut's modifiers in lower case and its key as written; undefined when it can match nothing. */
+function parse(shortcut) {
+	const parts = shortcut.split("+");
+	const key = parts.pop() ?? "";
+	const mods = parts.map((part) => part.toLowerCase());
+	return key && mods.every((mod) => MODIFIERS.includes(mod)) ? {
+		mods,
+		key
+	} : void 0;
+}
+/** The shortcut as this platform's keyboards name it, such as "Option + Shift + F" on a Mac. */
+function spoken(shortcut) {
+	const parsed = parse(shortcut);
+	if (!parsed) return void 0;
+	const platform = navigator.platform;
+	const names = /mac|iphone|ipad|ipod/i.test(platform) ? {
+		alt: "Option",
+		shift: "Shift",
+		control: "Control",
+		meta: "Command"
+	} : {
+		alt: "Alt",
+		shift: "Shift",
+		control: "Ctrl",
+		meta: /^win/i.test(platform) ? "Win" : "Super"
+	};
+	const key = parsed.key.charAt(0).toUpperCase() + parsed.key.slice(1);
+	return [...new Set(parsed.mods)].map((mod) => names[mod]).concat(key).join(" + ");
+}
 function createFeedback(options = {}) {
 	if (!supported()) return noop;
 	const tag = options.tagName ?? "visual-feedback";
@@ -259,18 +294,12 @@ function createFeedback(options = {}) {
 	let label;
 	let unlisten;
 	function listen(shortcut) {
-		const parts = shortcut.toLowerCase().split("+");
-		const key = parts.pop();
-		const names = [
-			"alt",
-			"shift",
-			"control",
-			"meta"
-		];
-		const mods = names.map((name) => parts.includes(name)).join();
-		const typing = !/control|meta/.test(shortcut.toLowerCase());
+		const parsed = parse(shortcut);
+		const key = parsed?.key.toLowerCase();
+		const mods = MODIFIERS.map((name) => parsed?.mods.includes(name)).join();
+		const typing = !parsed?.mods.some((mod) => mod === "control" || mod === "meta");
 		const on = (event) => {
-			if (event instanceof KeyboardEvent && state === "idle" && !event.repeat && !event.isComposing && !event.getModifierState("AltGraph") && parts.every((part) => names.includes(part)) && [
+			if (event instanceof KeyboardEvent && state === "idle" && !event.repeat && !event.isComposing && !event.getModifierState("AltGraph") && parsed && [
 				event.altKey,
 				event.shiftKey,
 				event.ctrlKey,
@@ -322,7 +351,10 @@ function createFeedback(options = {}) {
 			trigger.dataset.y = y;
 			trigger.dataset.x = x;
 			const { trigger: name, triggerText } = options.strings ?? {};
-			trigger.setAttribute("aria-label", name || triggerText || "Send feedback");
+			const accessible = name || triggerText || "Send feedback";
+			trigger.setAttribute("aria-label", accessible);
+			const keys = options.shortcut ? spoken(options.shortcut) : void 0;
+			trigger.title = keys ? `${accessible} (${keys})` : accessible;
 			trigger.toggleAttribute("data-icon", !triggerText);
 			if (label) {
 				label.textContent = triggerText ?? "";
@@ -507,7 +539,10 @@ function createFeedback(options = {}) {
 				const mine = session;
 				return pending.then(() => mine === session ? widget.open() : void 0);
 			}
-			if (state !== "idle") return dialog?.reopen(), Promise.resolve();
+			if (state !== "idle") {
+				dialog?.reopen();
+				return Promise.resolve();
+			}
 			if (restore()) return widget.open();
 			state = "opening";
 			pending = show(++session);

package/docs/API.md

@@ -39,7 +39,7 @@ const feedback = createFeedback({
 | `headers` | `Record<string, string>` or `() => Record<string, string>` | – | Extra headers for `endpoint`. A function is called at Send; a throw shows the send error state, using the error's message. |
 | `trigger` | `"button" \| "none"` | `"button"` | `"none"` draws no trigger; the host calls `open()`. A kept draft's bar still shows. |
 | `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Corner of the trigger. |
-| `shortcut` | `string \| false` | `false` | For example `"Alt+Shift+F"`: any of `Alt`, `Shift`, `Control` and `Meta`, then one key, a letter, a digit or a key name such as `F2`, joined by `+`. The modifiers must match exactly, AltGr never matches, and any other modifier name makes it match nothing. Without `Control` or `Meta` it does not fire while focus is in a form field (`input`, `textarea`, `select`) or editable content. It does nothing while the dialog is open or a draft is kept in the draft bar. Opt-in; it is the widget's only listener on `window` or `document`, one `keydown` on `window` (SPEC §9 names what else the widget watches, and what the capture library keeps). |
+| `shortcut` | `string \| false` | `false` | For example `"Alt+Shift+F"`: any of `Alt`, `Shift`, `Control` and `Meta`, then one key, a letter, a digit or a key name such as `F2`, joined by `+`. The modifiers must match exactly, AltGr never matches, and any other modifier name, or no key, makes it match nothing. Without `Control` or `Meta` it does not fire while focus is in a form field (`input`, `textarea`, `select`) or editable content. It does nothing while the dialog is open or a draft is kept in the draft bar. The trigger's tooltip names it (SPEC §3). Opt-in; it is the widget's only listener on `window` or `document`, one `keydown` on `window` (SPEC §9 names what else the widget watches, and what the capture library keeps). |
 | `tools` | `("pen" \| "box" \| "arrow" \| "text" \| "select")[]` | all five | Order is the toolbar order, and the first drawing tool is the one selected at open. Repeats and unknown names are ignored; an empty list, or Select alone, shows no toolbar. The Delete button is there only with Select. |
 | `categories` | `{ id: string; label: string }[]` | none | Shows a category picker. |
 | `requireNote` | `boolean` | `true` | |

package/docs/SPEC.md

@@ -53,6 +53,12 @@ annotating, draft --Cancel (it may ask first, below) / Discard--> idle
   gets that short label beside the icon, as a pill; with only `triggerText` given, that text is
   the name too. A host that sets both keeps `triggerText` inside `trigger`, so
   speech control can say what it sees. It has no badge, and it does not move or pulse.
+- Its tooltip (`title`) is its name, as for the dialog's icon buttons. With a `shortcut` that can
+  match, it is the name and the keys, each modifier once, joined by ` + `, as the platform's
+  keyboards name them: Option, Command, Control and Shift on a Mac, iPhone or iPad
+  (`navigator.platform`), as in `Send feedback (Option + Shift + F)`; Alt, Win, Ctrl and Shift on
+  Windows; Alt, Super, Ctrl and Shift elsewhere. A screen reader then reads the keys as the
+  description.
 - It sits 16 px from the edges by default, and it respects `env(safe-area-inset-*)`.
 - It is hidden while there is a draft, whether the dialog is open or kept in the draft bar.
 - It does not move to keep clear of the page's content. The host moves it off its own content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-feedback",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A small button lets your users screenshot the page, mark it up and write a note. You receive one report and store it where you want.",
   "keywords": [
     "feedback",