@bitvea/feedback-toolbar 0.0.1

package/dist/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,19 @@
+import { type ToolbarClient, type ToolbarSession } from "./client.js";
+export type ToolbarSessionPhase = {
+    kind: "loading";
+} | {
+    kind: "error";
+    message: string;
+} | {
+    kind: "session";
+    session: ToolbarSession;
+};
+export interface UseToolbarSession {
+    phase: ToolbarSessionPhase;
+    /** The project the caller may act on, or null. Drives the pin layer. */
+    readyProjectId: string | null;
+    /** Re-resolve, e.g. after the reviewer follows their magic link. */
+    reload: () => void;
+}
+export declare function useToolbarSession(client: ToolbarClient, projectUrl: string): UseToolbarSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAYA,OAAO,EAAmB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,wEAAwE;IACxE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oEAAoE;IACpE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,MAAM,GACjB,iBAAiB,CA4BnB"}

package/dist/session.js

@@ -0,0 +1,36 @@
+"use client";
+// Who the visitor is and whether they can act on this project, resolved once
+// per page rather than once per surface.
+//
+// This lives outside the panel because the pin layer needs the answer too, and
+// it needs it before anybody opens the panel: existing pins have to be on the
+// page as soon as it loads, or a reviewer opens the toolbar to report a bug a
+// colleague already reported. Resolving it in the panel made the pins depend
+// on the panel being open, which is the wrong dependency.
+import { useCallback, useEffect, useState } from "react";
+import { ToolbarApiError } from "./client.js";
+export function useToolbarSession(client, projectUrl) {
+    const [phase, setPhase] = useState({ kind: "loading" });
+    const load = useCallback(async () => {
+        setPhase({ kind: "loading" });
+        try {
+            setPhase({ kind: "session", session: await client.session(projectUrl) });
+        }
+        catch (err) {
+            setPhase({
+                kind: "error",
+                message: err instanceof ToolbarApiError && err.code === "network_error"
+                    ? "Could not reach the feedback service."
+                    : "Something went wrong loading your session.",
+            });
+        }
+    }, [client, projectUrl]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    const readyProjectId = phase.kind === "session" && phase.session.state === "ready"
+        ? (phase.session.project?.id ?? null)
+        : null;
+    return { phase, readyProjectId, reload: () => void load() };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,6EAA6E;AAC7E,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,0DAA0D;AAC1D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAAE,eAAe,EAA2C,MAAM,UAAU,CAAC;AAepF,MAAM,UAAU,iBAAiB,CAC/B,MAAqB,EACrB,UAAkB;IAElB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAsB,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAE7E,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QAClC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC;YACH,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC;gBACP,IAAI,EAAE,OAAO;gBACb,OAAO,EACL,GAAG,YAAY,eAAe,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe;oBAC5D,CAAC,CAAC,uCAAuC;oBACzC,CAAC,CAAC,4CAA4C;aACnD,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEzB,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,IAAI,EAAE,CAAC;IACd,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,MAAM,cAAc,GAClB,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,KAAK,OAAO;QACzD,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC;QACrC,CAAC,CAAC,IAAI,CAAC;IAEX,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;AAC9D,CAAC"}

package/dist/shortcut.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A chord: a primary modifier, zero or more keys held down with it, and the
+ * key whose keydown fires it.
+ *
+ * `holdKeys` and `triggerKey` are `KeyboardEvent.key` values, lowercased -
+ * the LOGICAL key rather than the physical position. `event.code` would be
+ * wrong here: on AZERTY the key printed `F` is not `KeyF`, so a reviewer told
+ * to press F would have to press something else, and the tooltip and the
+ * behaviour would disagree for exactly the people least able to diagnose it.
+ */
+export interface ShortcutChord {
+    /** Cmd on macOS, Ctrl everywhere else. The platform split is at match time. */
+    primaryModifier: boolean;
+    /** Keys held down when the trigger is pressed. Order is not significant. */
+    holdKeys: string[];
+    /** The key whose keydown fires the chord. */
+    triggerKey: string;
+}
+/**
+ * The default binding. The single definition the matcher, the host override
+ * and the tooltip hint all resolve back to.
+ */
+export declare const DEFAULT_PIN_SHORTCUT: ShortcutChord;
+/**
+ * What a host may say about the chord: replace it, or `null` to switch it off
+ * entirely. Off means no listener at all rather than a listener that declines
+ * - a disabled shortcut must not observe a single keystroke.
+ */
+export type PinShortcutSetting = ShortcutChord | null;
+/** Whether this platform spells the primary modifier Cmd rather than Ctrl. */
+export declare function isApplePlatform(navigatorLike: {
+    platform?: string;
+    userAgent?: string;
+} | undefined): boolean;
+/**
+ * Whether a keystroke aimed at this element belongs to the host page.
+ *
+ * Walks up rather than testing the target alone, because a `contenteditable`
+ * region's keystrokes are delivered to whatever inner node holds the caret -
+ * a `<b>`, a `<div>`, a text node's parent - and testing only the target
+ * would leave every rich-text editor on the web unprotected.
+ *
+ * `readOnly` inputs are deliberately still treated as editable: they take
+ * focus and a reviewer may be selecting text in one, and being wrong in this
+ * direction costs a shortcut press while being wrong in the other costs
+ * somebody's typing.
+ */
+export declare function isEditableTarget(target: EventTarget | null): boolean;
+/**
+ * Whether this keydown, with these keys already held, is the chord.
+ *
+ * Modifier discipline is strict in one direction only: Shift and Alt must NOT
+ * be held, because `Cmd+Shift+F` is a different gesture the reviewer may mean
+ * for something else, and treating it as this chord would make the toolbar
+ * answer for a keystroke it was not given. The primary modifier is checked
+ * against the platform's spelling.
+ */
+export declare function matchesChord(chord: ShortcutChord, event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey">, held: ReadonlySet<string>, apple: boolean): boolean;
+/**
+ * The set of non-modifier keys currently held down.
+ *
+ * A LOST KEYUP IS THE FAILURE MODE THIS EXISTS TO SURVIVE. Hold Space, switch
+ * tab or trigger Spotlight, release it somewhere this document never hears
+ * about, and the set says Space is still down for the rest of the page's life
+ * - so a later lone `F` fires the chord and arms picking out of nowhere. Blur
+ * and a visibility change both clear it, because both mean the same thing:
+ * this document is no longer receiving the reviewer's keystrokes and cannot
+ * know what they let go of.
+ */
+export declare class ChordWatcher {
+    private readonly held;
+    /** Record a key going down. Modifiers are not tracked; they ride the event. */
+    down(key: string): void;
+    up(key: string): void;
+    /** Everything is released, because we can no longer observe releases. */
+    clear(): void;
+    keys(): ReadonlySet<string>;
+}
+/**
+ * The chord as a reviewer's own platform writes it: `⌘ Space F` on a Mac,
+ * `Ctrl Space F` elsewhere.
+ *
+ * Derived from the chord rather than written beside it, so a host override
+ * changes what the tooltip teaches. A hardcoded string here would rot silently
+ * into advice that does nothing.
+ */
+export declare function formatChord(chord: ShortcutChord, apple: boolean): string;
+//# sourceMappingURL=shortcut.d.ts.map

package/dist/shortcut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut.d.ts","sourceRoot":"","sources":["../src/shortcut.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,eAAe,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAIjC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,IAAI,CAAC;AAEtD,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,aAAa,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACnE,OAAO,CAIT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAMpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,IAAI,CACT,aAAa,EACb,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CACtD,EACD,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,OAAO,GACb,OAAO,CAcT;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAE1C,+EAA+E;IAC/E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIrB,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,WAAW,CAAC,MAAM,CAAC;CAG5B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAMxE"}

package/dist/shortcut.js

@@ -0,0 +1,149 @@
+// The one keyboard chord this package claims, and the rules that keep it from
+// being a keystroke stolen from somebody else's application.
+//
+// WHY THIS IS A MODULE AND NOT A `useEffect`. Three things have to agree about
+// the chord and they are written in three different places: the matcher that
+// decides whether a keydown is it, the host override that may replace it, and
+// the hint the pin button's tooltip shows. Three copies of one truth is how a
+// tooltip ends up confidently teaching a keystroke that does nothing, so the
+// chord is DEFINED ONCE here and those three read it. That single definition
+// is also the whole basis on which the chord was chosen: changing it later is
+// a one-line edit rather than a hunt, which is what makes the collisions below
+// an acceptable risk rather than a permanent mistake.
+//
+// THE CHORD IS `Cmd+Space+F` ON macOS AND `Ctrl+Space+F` ELSEWHERE, and two
+// things about that are load-bearing rather than incidental:
+//
+//   - `Space` IS NOT A MODIFIER. A conventional shortcut is one keydown read
+//     together with `event.metaKey`/`ctrlKey`/`shiftKey`, and this one cannot
+//     be: the browser reports no "spaceKey" flag. It needs the set of keys
+//     currently held, tracked across keydown and keyup, which is what
+//     `ChordWatcher` below is. That set is state living outside React for the
+//     same reason the preference store is - it is updated by events that must
+//     not re-render anything.
+//   - IT COLLIDES, KNOWINGLY. `Cmd+Space` is Spotlight on macOS and is handled
+//     by the operating system before the browser sees it, so page JavaScript
+//     cannot cancel it; on Windows and Linux `Ctrl+Space` is commonly taken by
+//     input method editors and by an application's own autocomplete. The
+//     remedy is the host override in config.ts, which is why that override is
+//     part of the feature rather than a courtesy - see `PIN_SHORTCUT` there.
+//
+// WHAT THIS FILE WILL NOT DO. It never reports a match while the reviewer is
+// typing into the host's own page. That is not politeness: a review tool that
+// eats a character out of somebody's form field is a review tool that gets
+// removed, and it outranks the convenience the chord exists to provide.
+/**
+ * The default binding. The single definition the matcher, the host override
+ * and the tooltip hint all resolve back to.
+ */
+export const DEFAULT_PIN_SHORTCUT = Object.freeze({
+    primaryModifier: true,
+    holdKeys: Object.freeze([" "]),
+    triggerKey: "f",
+});
+/** Whether this platform spells the primary modifier Cmd rather than Ctrl. */
+export function isApplePlatform(navigatorLike) {
+    if (navigatorLike === undefined)
+        return false;
+    const haystack = `${navigatorLike.platform ?? ""} ${navigatorLike.userAgent ?? ""}`;
+    return /mac|iphone|ipad|ipod/i.test(haystack);
+}
+/**
+ * Whether a keystroke aimed at this element belongs to the host page.
+ *
+ * Walks up rather than testing the target alone, because a `contenteditable`
+ * region's keystrokes are delivered to whatever inner node holds the caret -
+ * a `<b>`, a `<div>`, a text node's parent - and testing only the target
+ * would leave every rich-text editor on the web unprotected.
+ *
+ * `readOnly` inputs are deliberately still treated as editable: they take
+ * focus and a reviewer may be selecting text in one, and being wrong in this
+ * direction costs a shortcut press while being wrong in the other costs
+ * somebody's typing.
+ */
+export function isEditableTarget(target) {
+    if (target === null || !(target instanceof Element))
+        return false;
+    const el = target.closest("input, textarea, select, [contenteditable]:not([contenteditable='false'])");
+    return el !== null;
+}
+/**
+ * Whether this keydown, with these keys already held, is the chord.
+ *
+ * Modifier discipline is strict in one direction only: Shift and Alt must NOT
+ * be held, because `Cmd+Shift+F` is a different gesture the reviewer may mean
+ * for something else, and treating it as this chord would make the toolbar
+ * answer for a keystroke it was not given. The primary modifier is checked
+ * against the platform's spelling.
+ */
+export function matchesChord(chord, event, held, apple) {
+    if (event.key.toLowerCase() !== chord.triggerKey)
+        return false;
+    if (event.shiftKey || event.altKey)
+        return false;
+    if (chord.primaryModifier) {
+        const primary = apple ? event.metaKey : event.ctrlKey;
+        if (!primary)
+            return false;
+        // The other one must be absent, or Ctrl+Cmd+Space+F on a Mac would match
+        // a chord the reviewer did not press.
+        const secondary = apple ? event.ctrlKey : event.metaKey;
+        if (secondary)
+            return false;
+    }
+    else if (event.metaKey || event.ctrlKey) {
+        return false;
+    }
+    return chord.holdKeys.every((key) => held.has(key));
+}
+/**
+ * The set of non-modifier keys currently held down.
+ *
+ * A LOST KEYUP IS THE FAILURE MODE THIS EXISTS TO SURVIVE. Hold Space, switch
+ * tab or trigger Spotlight, release it somewhere this document never hears
+ * about, and the set says Space is still down for the rest of the page's life
+ * - so a later lone `F` fires the chord and arms picking out of nowhere. Blur
+ * and a visibility change both clear it, because both mean the same thing:
+ * this document is no longer receiving the reviewer's keystrokes and cannot
+ * know what they let go of.
+ */
+export class ChordWatcher {
+    held = new Set();
+    /** Record a key going down. Modifiers are not tracked; they ride the event. */
+    down(key) {
+        this.held.add(key.toLowerCase());
+    }
+    up(key) {
+        this.held.delete(key.toLowerCase());
+    }
+    /** Everything is released, because we can no longer observe releases. */
+    clear() {
+        this.held.clear();
+    }
+    keys() {
+        return this.held;
+    }
+}
+/**
+ * The chord as a reviewer's own platform writes it: `⌘ Space F` on a Mac,
+ * `Ctrl Space F` elsewhere.
+ *
+ * Derived from the chord rather than written beside it, so a host override
+ * changes what the tooltip teaches. A hardcoded string here would rot silently
+ * into advice that does nothing.
+ */
+export function formatChord(chord, apple) {
+    const parts = [];
+    if (chord.primaryModifier)
+        parts.push(apple ? "⌘" : "Ctrl");
+    for (const key of chord.holdKeys)
+        parts.push(labelForKey(key));
+    parts.push(labelForKey(chord.triggerKey));
+    return parts.join(apple ? " " : "+");
+}
+function labelForKey(key) {
+    if (key === " ")
+        return "Space";
+    return key.length === 1 ? key.toUpperCase() : key;
+}
+//# sourceMappingURL=shortcut.js.map

package/dist/shortcut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut.js","sourceRoot":"","sources":["../src/shortcut.ts"],"names":[],"mappings":"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"}