visual-comments 0.1.0 → 0.2.0

package/dist/visual-comments.svelte.js

@@ -17,8 +17,10 @@ export class VisualComments {
     api;
     store;
     options = $state.raw();
-    /** Comment mode: the list is shown, and clicking a surface starts a thread. Pins always show. */
+    /** Comment mode: clicking a surface starts a thread. Pins always show. */
     active = $state(false);
+    /** Hide the list while keeping comment mode active. */
+    panelCollapsed = $state(false);
     /** The thread whose conversation is open. */
     openId = $state();
     draft = $state();
@@ -37,6 +39,12 @@ export class VisualComments {
     cursor = $state.raw();
     /** Opening a thread scrolls its element into view once it is found. */
     revealing = $state();
+    /** An agent's request to join, from `#vc-connect=<id>`, while the dialog to approve it is shown. */
+    connecting = $state();
+    /** The reply field of the open thread is being written in. */
+    typing = $state(false);
+    /** Where the host says the viewer is, for others to see. */
+    whereabouts = $state.raw({});
     doc;
     host;
     app;
@@ -51,11 +59,13 @@ export class VisualComments {
     cursorSheet = new CSSStyleSheet();
     focusDraftHandler;
     linked;
+    typingTimer;
+    presenceTimer;
     constructor(options, doc = document) {
         this.options = options;
         this.doc = doc;
         this.api = new Api(options.endpoint ?? '/_comments');
-        this.store = new Threads(this.api);
+        this.store = new Threads(this.api, options.viewer);
         this.host = doc.createElement('visual-comments');
         this.host.setAttribute('data-vc-ignore', '');
         this.host.style.cssText = 'position:fixed;inset:0;z-index:2147483600;pointer-events:none;display:block;';
@@ -69,6 +79,19 @@ export class VisualComments {
     get open() {
         return this.store.threads.find((thread) => thread.id === this.openId);
     }
+    /** Everyone present in the space: people's tabs, this one included, and agents' tasks. Empty when signed out. */
+    get participants() { return this.store.participants; }
+    /** This tab's connection to the server's event stream, as in `Participant.id`, while it is open. */
+    get connection() { return this.store.connection; }
+    /** What this tab tells others: the host's location, the open thread, and whether its reply is being written. */
+    get ownPresence() {
+        return {
+            state: this.typing && this.openId !== undefined ? 'typing' : 'viewing',
+            page: this.whereabouts.page ?? (this.page || undefined),
+            surface: this.whereabouts.surface,
+            thread: this.openId
+        };
+    }
     /** Threads shown as pins: on this page, unresolved unless resolved ones are shown or it is open. */
     get pinned() {
         return this.store.threads.filter((thread) => thread.page === this.page
@@ -106,6 +129,8 @@ export class VisualComments {
     }
     toggle(on = !this.active) {
         this.active = on;
+        if (!on)
+            this.panelCollapsed = false;
         this.cursor = undefined;
         this.aim = undefined;
         if (!on) {
@@ -116,6 +141,8 @@ export class VisualComments {
         this.updateAim();
     }
     openThread(id) {
+        if (id !== this.openId)
+            this.stopTyping();
         this.openId = id;
         const thread = this.open;
         if (thread?.unread)
@@ -130,7 +157,11 @@ export class VisualComments {
         if (this.options.show?.(thread))
             return;
         if (thread.page !== this.page) {
-            location.assign(this.linkOf(thread));
+            const url = this.linkOf(thread);
+            if (this.options.navigate)
+                this.options.navigate(url, thread);
+            else
+                location.assign(url);
             return;
         }
         const surface = this.surface(thread.surface);
@@ -152,6 +183,33 @@ export class VisualComments {
         reveal(element);
         this.revealing = undefined;
     }
+    /**
+     * Tells others where the viewer is: the page, by default the page key, and
+     * the surface, e.g. the frame on screen. Each call replaces the last.
+     */
+    setPresence(update) {
+        const current = untrack(() => this.whereabouts);
+        if (current.page === update.page && current.surface === update.surface)
+            return;
+        this.whereabouts = { page: update.page, surface: update.surface };
+    }
+    /** Called by the UI as the viewer writes in the open thread; they stop typing 5 seconds after the last key. */
+    noteTyping() {
+        if (this.openId === undefined)
+            return;
+        this.typing = true;
+        clearTimeout(this.typingTimer);
+        this.typingTimer = setTimeout(() => this.stopTyping(), 5000);
+    }
+    stopTyping() {
+        clearTimeout(this.typingTimer);
+        this.typing = false;
+    }
+    /** Closes the dialog for an agent's request and takes it out of the address. */
+    endConnect() {
+        this.connecting = undefined;
+        dropFromHash('vc-connect');
+    }
     /** Leaves for the site's sign-in, and comes back to this address. */
     signIn() {
         const auth = this.options.auth ?? '/auth';
@@ -181,7 +239,8 @@ export class VisualComments {
     subscribe(listener) {
         return $effect.root(() => {
             $effect(() => {
-                void [this.active, this.openId, this.unreadCount, this.viewer, this.store.threads.length, this.loading];
+                void [this.active, this.openId, this.unreadCount, this.viewer, this.store.threads.length, this.loading,
+                    this.store.participants, this.store.connection];
                 listener(this);
             });
         });
@@ -191,6 +250,8 @@ export class VisualComments {
             stop();
         for (const stop of this.frames.values())
             stop();
+        clearTimeout(this.typingTimer);
+        clearTimeout(this.presenceTimer);
         this.frames.clear();
         for (const app of this.slots.values())
             void unmount(app);
@@ -218,12 +279,13 @@ export class VisualComments {
         doc.documentElement.appendChild(this.host);
         this.app = mount(App, { target: shadow, props: { vc: this } });
         this.cleanup.push(this.store.start());
-        const hash = /(?:^#|&)vc=(\d+)/.exec(location.hash);
-        if (hash) {
-            this.linked = Number(hash[1]);
-            const rest = location.hash.slice(1).split('&').filter((part) => !part.startsWith('vc=')).join('&');
-            history.replaceState(history.state, '', `${location.pathname}${location.search}${rest ? `#${rest}` : ''}`);
+        const linked = hashPart('vc');
+        if (linked && /^\d+$/.test(linked)) {
+            this.linked = Number(linked);
+            dropFromHash('vc');
         }
+        // The hash stays until the request is answered, so it survives signing in first.
+        this.connecting = hashPart('vc-connect') || undefined;
         this.cleanup.push($effect.root(() => {
             // Open a linked thread once threads have loaded.
             $effect(() => {
@@ -238,6 +300,19 @@ export class VisualComments {
                     this.focus(thread);
                 }
             });
+            // Others see what this tab is doing: where it is, the open thread, and whether its reply is being written.
+            $effect(() => {
+                const presence = this.ownPresence;
+                clearTimeout(this.presenceTimer);
+                this.presenceTimer = setTimeout(() => this.store.setPresence(presence), 150);
+            });
+            // The server lets typing lapse unless it hears it again.
+            $effect(() => {
+                if (!this.typing)
+                    return;
+                const timer = setInterval(() => this.store.setPresence(untrack(() => this.ownPresence), true), 3000);
+                return () => clearInterval(timer);
+            });
             // Buttons the host marked with data-vc-toggle say whether comment mode is on and if anything is unread.
             $effect(() => {
                 const unread = this.unreadCount > 0 && !this.active;
@@ -264,9 +339,34 @@ export class VisualComments {
         on(view, 'click', (event) => this.onClick(event), capture);
         for (const type of ['dblclick', 'auxclick', 'contextmenu'])
             on(view, type, (event) => this.onOtherClick(event), capture);
+        // Escape closes the comments' own things before the page's (an open dialog) sees it; in the
+        // comment UI, after the UI's own handlers.
+        on(view, 'keydown', (event) => { if (!this.fromUs(event))
+            this.onEscape(event); }, capture);
         on(view, 'keydown', (event) => this.onKey(event));
         on(view, 'keyup', (event) => this.onKey(event));
+        // What happens in the comment UI is not the page's: a modal's focus trap (bits-ui, focus-trap, …)
+        // would take focus back from it, and a press or key in it would close the modal or work its
+        // shortcuts. Focus is stopped before any trap sees it, the rest where it leaves the UI.
+        on(view, 'focusin', (event) => { if (this.fromUs(event))
+            event.stopImmediatePropagation(); }, capture);
+        for (const type of ['keydown', 'keyup', 'pointerdown', 'pointerup', 'mousedown', 'mouseup', 'click', 'touchstart', 'touchend', 'focusout']) {
+            const keep = (event) => {
+                if (event instanceof KeyboardEvent) {
+                    this.onEscape(event);
+                    this.onKey(event);
+                }
+                event.stopPropagation();
+            };
+            this.host.addEventListener(type, keep);
+            this.cleanup.push(() => this.host.removeEventListener(type, keep));
+        }
         on(view, 'resize', () => this.schedule());
+        on(view, 'hashchange', () => {
+            const id = hashPart('vc-connect');
+            if (id)
+                this.connecting = id;
+        });
         on(doc, 'scroll', () => this.schedule(), { capture: true, passive: true });
         const leave = () => this.move(undefined);
         doc.documentElement.addEventListener('pointerleave', leave);
@@ -299,7 +399,10 @@ export class VisualComments {
         if (!view || this.frames.has(frame))
             return;
         const schedule = () => this.schedule();
-        const key = (event) => this.onKey(event);
+        const key = (event) => {
+            this.onEscape(event);
+            this.onKey(event);
+        };
         const observer = new MutationObserver(schedule);
         observer.observe(frame.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
         frame.addEventListener('scroll', schedule, { capture: true, passive: true });
@@ -329,9 +432,12 @@ export class VisualComments {
         const doc = this.doc;
         this.surfaces = discover(doc, { ours: this.ours, documentOf: this.options.documentOf });
         this.page = pageOf(this.options.page);
-        // A new comment on a surface that has gone, like a frame the viewer left, goes with it.
+        // A new comment on a surface that has gone, like a frame the viewer left, goes with it; an
+        // empty one also with its element, like a dialog's that closed.
         if (this.draft && !this.surface(this.draft.surface))
             this.draft = undefined;
+        if (this.draft?.target && !this.draft.target.element.isConnected && !this.draftHasContent)
+            this.draft = undefined;
         const docs = new Set(this.surfaces.map((surface) => surface.doc).filter((d) => Boolean(d) && d !== doc));
         for (const frame of docs)
             this.watchFrame(frame);
@@ -360,6 +466,10 @@ export class VisualComments {
                 continue;
             const shadow = element.attachShadow({ mode: 'open' });
             addStyles(shadow);
+            // In the host's toolbar the button takes the toolbar's colour and type, not the comments' ink.
+            const own = this.doc.createElement('style');
+            own.textContent = ':host{color:inherit;font-family:inherit;font-size:inherit}';
+            shadow.appendChild(own);
             this.slots.set(element, mount(Account, { target: shadow, props: { vc: this, slot: true } }));
         }
         for (const [element, app] of this.slots) {
@@ -503,31 +613,46 @@ export class VisualComments {
             this.updateAim();
             return;
         }
-        if (event.type !== 'keydown' || event.defaultPrevented)
-            return;
-        const target = event.composedPath()[0];
-        if (editable(target))
+        if (event.type !== 'keydown' || event.defaultPrevented || !this.ownsKey(event))
             return;
-        if (event.key === 'Escape') {
-            if (this.host.shadowRoot?.querySelector(':popover-open') || this.doc.querySelector(':popover-open'))
-                return;
-            if (this.draft)
-                this.draft = undefined;
-            else if (this.openId !== undefined)
-                this.openThread(undefined);
-            else if (this.active)
-                this.toggle(false);
-            else
-                return;
-            event.preventDefault();
-            return;
-        }
         const shortcut = this.options.shortcut ?? 'c';
         if (shortcut && event.key.toLowerCase() === shortcut && !event.metaKey && !event.ctrlKey && !event.altKey) {
             event.preventDefault();
             this.toggle();
         }
     }
+    /** Escape drops the new comment, else closes the open thread, else leaves comment mode. */
+    onEscape(event) {
+        if (event.type !== 'keydown' || event.key !== 'Escape' || event.defaultPrevented || !this.ownsKey(event))
+            return;
+        if (this.host.shadowRoot?.querySelector(':popover-open') || this.doc.querySelector(':popover-open'))
+            return;
+        if (this.draft)
+            this.draft = undefined;
+        else if (this.openId !== undefined)
+            this.openThread(undefined);
+        else if (this.active)
+            this.toggle(false);
+        else
+            return;
+        stop(event);
+    }
+    /** Whether a key is the comments' to act on: not typed into a field, nor into the dialog to approve an agent. */
+    ownsKey(event) {
+        return !this.host.shadowRoot?.querySelector('dialog:modal') && !editable(event.composedPath()[0]);
+    }
+}
+/** A `name=value` part of the address's fragment, whose parts are joined by `&`. */
+function hashPart(name) {
+    const part = location.hash.slice(1).split('&').find((p) => p.startsWith(`${name}=`));
+    return part?.slice(name.length + 1);
+}
+function dropFromHash(name) {
+    const parts = location.hash.slice(1).split('&');
+    const rest = parts.filter((part) => part && !part.startsWith(`${name}=`)).join('&');
+    if (rest === parts.join('&'))
+        return;
+    history.replaceState(history.state, '', `${location.pathname}${location.search}${rest ? `#${rest}` : ''}`);
 }
 function stop(event) {
     event.preventDefault();

package/dist/vite/index.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'vite';
+export interface VisualCommentsPluginOptions {
+    /**
+     * Whether the comments are in the build. Default: under the dev server, and
+     * in a build only with `VISUAL_COMMENTS_BUILD=true` in its environment.
+     */
+    include?: boolean;
+}
+/**
+ * Puts the comments in development and in the builds that ask for them, and
+ * leaves them out of every other build:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { visualComments } from 'visual-comments/vite';
+ *
+ * export default defineConfig({ plugins: [visualComments(), sveltekit()] });
+ * ```
+ */
+export declare function visualComments(options?: VisualCommentsPluginOptions): Plugin;

package/dist/vite/index.js

@@ -0,0 +1,78 @@
+// A Vite plugin that leaves the comments out of a build altogether: for builds
+// that must not carry a review tool, such as production's, whatever the
+// variables say when they run. The site's code stays as it is: `<Comments>`
+// of `visual-comments/sveltekit` renders only what it wraps, `<Toolbar>` only
+// the app's own tools (or nothing), and `commentsFromEnv` of
+// `visual-comments/server` is always off, so the comments' client, the proxy
+// and their sign-in are not in the build. The variables are still declared,
+// so the same `src/env.ts` serves both.
+/** This package's `dist/`, as Vite writes module ids. */
+const dist = (() => {
+    const path = decodeURIComponent(new URL('../', import.meta.url).pathname);
+    return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+})();
+const COMMENTS = `<script>
+	// Left out of this build (visual-comments/vite): renders what it wraps.
+	let { comments = $bindable(), children } = $props();
+</script>
+
+{@render children?.()}
+`;
+const COMMENT_TOOLS = `<script>
+	// Left out of this build (visual-comments/vite).
+	let { divider } = $props();
+</script>
+`;
+const ENV = `// Left out of this build (visual-comments/vite): comments are off, whatever the variables say.
+export { commentsVariables } from './variables.js';
+
+let warned = false;
+
+export function commentsFromEnv(env) {
+	if (!warned && env?.VISUAL_COMMENTS_ENABLED === 'true') {
+		warned = true;
+		console.warn('[visual-comments] VISUAL_COMMENTS_ENABLED is true, but this build leaves the comments out (visual-comments/vite).');
+	}
+	return {
+		enabled: false,
+		client: null,
+		load: async () => null,
+		handle: async () => undefined,
+		sveltekit: () => ({ event, resolve }) => Promise.resolve(resolve(event))
+	};
+}
+`;
+const STUBS = {
+    [`${dist}sveltekit/Comments.svelte`]: COMMENTS,
+    [`${dist}sveltekit/CommentTools.svelte`]: COMMENT_TOOLS,
+    [`${dist}server/env.js`]: ENV
+};
+function environment(name) {
+    return globalThis.process?.env?.[name];
+}
+/**
+ * Puts the comments in development and in the builds that ask for them, and
+ * leaves them out of every other build:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { visualComments } from 'visual-comments/vite';
+ *
+ * export default defineConfig({ plugins: [visualComments(), sveltekit()] });
+ * ```
+ */
+export function visualComments(options = {}) {
+    let include = true;
+    return {
+        name: 'visual-comments',
+        enforce: 'pre',
+        config(_, { command }) {
+            include = options.include ?? (command === 'serve' || environment('VISUAL_COMMENTS_BUILD') === 'true');
+            // Bundled into the server too, where it would otherwise be loaded from node_modules as it is.
+            return include ? undefined : { ssr: { noExternal: ['visual-comments'] } };
+        },
+        load(id) {
+            return include ? undefined : STUBS[id];
+        }
+    };
+}