@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/edits.tsx

@@ -0,0 +1,165 @@
+import { useRef, useState, type KeyboardEvent } from "react";
+import type { CommentMessage, Member } from "./client.js";
+import { ago } from "./format.js";
+import { MentionTextarea, MessageText, mentionsIn } from "./mentions.js";
+import { versionsOf } from "./thread-model.js";
+
+export { isMine } from "./thread-model.js";
+
+export function MessageTools({
+  message,
+  mine,
+  historyOpen,
+  onHistory,
+  onEdit,
+}: {
+  message: CommentMessage;
+  mine: boolean;
+  historyOpen: boolean;
+  onHistory: () => void;
+  onEdit: () => void;
+}) {
+  const edits = message.revisions?.length ?? 0;
+  if (!edits && !mine) return null;
+  return (
+    <span className="cs-message-tools">
+      {edits ? (
+        <button
+          type="button"
+          className="cs-link"
+          data-cs-ui="message-history"
+          aria-expanded={historyOpen}
+          title={
+            message.editedAt ? `Edited ${new Date(message.editedAt).toLocaleString()}` : undefined
+          }
+          onClick={onHistory}
+        >
+          edited · v{edits + 1}
+        </button>
+      ) : null}
+      {mine ? (
+        <button type="button" className="cs-link" data-cs-ui="message-edit" onClick={onEdit}>
+          Edit
+        </button>
+      ) : null}
+    </span>
+  );
+}
+
+export function MessageHistory({ message }: { message: CommentMessage }) {
+  const versions = versionsOf(message);
+  return (
+    <ol className="cs-history" data-cs-ui="history" aria-label="Edit history">
+      {versions.map((version, index) => (
+        <li
+          key={index}
+          className={index === versions.length - 1 ? "is-current" : undefined}
+          data-cs-ui="history-version"
+        >
+          <div className="cs-history-meta">
+            <strong>v{index + 1}</strong>
+            <time dateTime={version.createdAt} title={new Date(version.createdAt).toLocaleString()}>
+              {ago(version.createdAt)}
+            </time>
+            {index === versions.length - 1 ? <span>current</span> : null}
+          </div>
+          <p className="cs-text">
+            {version.body ? (
+              <MessageText body={version.body} mentions={version.mentions} />
+            ) : (
+              <em>No text</em>
+            )}
+          </p>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function MessageEditor({
+  message,
+  members,
+  selfEmail,
+  allowEmpty,
+  onSave,
+  onCancel,
+}: {
+  message: CommentMessage;
+  members: Member[];
+  selfEmail?: string;
+  allowEmpty: boolean;
+  onSave: (body: string, mentions: string[]) => Promise<unknown>;
+  onCancel: () => void;
+}) {
+  const [text, setText] = useState(message.body);
+  const [busy, setBusy] = useState(false);
+  const picked = useRef(
+    new Map<string, Member>(
+      (message.mentions ?? []).map((mention) => [mention.id, { ...mention, email: "" }]),
+    ),
+  );
+  const caretPlaced = useRef(false);
+  const unchanged = text.trim() === message.body.trim();
+  const canSave = !busy && !unchanged && (allowEmpty || Boolean(text.trim()));
+
+  const save = () => {
+    if (!canSave) return;
+    setBusy(true);
+    onSave(
+      text.trim(),
+      mentionsIn(text, picked.current).map((person) => person.id),
+    ).finally(() => setBusy(false));
+  };
+
+  return (
+    <form
+      className="cs-edit"
+      data-cs-ui="message-editor"
+      onSubmit={(event) => {
+        event.preventDefault();
+        save();
+      }}
+    >
+      <MentionTextarea
+        data-cs-ui="message-editor-body"
+        aria-label="Edit comment"
+        autoFocus
+        value={text}
+        onValueChange={setText}
+        members={members}
+        selfEmail={selfEmail}
+        onMention={(person) => picked.current.set(person.id, person)}
+        onFocus={(event) => {
+          if (caretPlaced.current) return;
+          caretPlaced.current = true;
+          const end = event.currentTarget.value.length;
+          event.currentTarget.setSelectionRange(end, end);
+        }}
+        onKeyDown={(event: KeyboardEvent<HTMLTextAreaElement>) => {
+          if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+            event.preventDefault();
+            save();
+          } else if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopPropagation();
+            onCancel();
+          }
+        }}
+      />
+      <div className="cs-edit-foot">
+        <span className="cs-hint">{busy ? "Saving…" : "⌘↵ to save · Esc to cancel"}</span>
+        <button type="button" className="cs-button" onClick={onCancel}>
+          Cancel
+        </button>
+        <button
+          type="submit"
+          className="cs-button is-primary"
+          data-cs-ui="message-editor-save"
+          disabled={!canSave}
+        >
+          Save
+        </button>
+      </div>
+    </form>
+  );
+}

package/src/runtime/font.ts

@@ -0,0 +1,42 @@
+/**
+ * The toolbar's typeface. It draws inside other people's pages, on every system, so it brings its own font
+ * instead of taking whichever one the system has: Inter's Latin cut, served beside the runtime
+ * (`scripts/build-toolbar.mjs` copies it there). Until it has loaded, the system's interface font stands in
+ * (`styles.ts`).
+ *
+ * The bytes are fetched like every other request to the service and handed to the page's fonts, rather than
+ * named in an `@font-face` rule: a page's Content-Security-Policy already lets the toolbar reach the service
+ * (`connect-src`), and a font built from bytes needs no `font-src` for it (`docs/integration`'s policy has none).
+ */
+export const FONT_FILE = "fonts/inter-latin-wght-normal.woff2";
+export const FONT_FAMILY = "Comment Toolbar Inter";
+
+/** Where the service at `apiUrl` serves the font; null when that is not an address. */
+export function fontUrl(apiUrl: string): string | null {
+  try {
+    return new URL(`${apiUrl.replace(/\/+$/, "")}/v1/toolbar/${FONT_FILE}`).href;
+  } catch {
+    return null;
+  }
+}
+
+let asked = false;
+
+/** Adds the toolbar's font to the page once; a build that replaced this one finds it already there. */
+export function loadFont(apiUrl: string) {
+  const url = fontUrl(apiUrl);
+  if (asked || url === null || typeof FontFace === "undefined" || !document.fonts) return;
+  if ([...document.fonts].some((face) => face.family.replace(/"/g, "") === FONT_FAMILY)) return;
+  asked = true;
+  void fetch(url, { mode: "cors", credentials: "omit" })
+    .then((response) => (response.ok ? response.arrayBuffer() : Promise.reject(response.status)))
+    .then((bytes) => {
+      const face = new FontFace(FONT_FAMILY, bytes, { weight: "100 900", style: "normal" });
+      document.fonts.add(face);
+      return face.load();
+    })
+    .catch(() => {
+      // The system's font stays; the next session may try again.
+      asked = false;
+    });
+}

package/src/runtime/format.ts

@@ -0,0 +1,129 @@
+import type { Anchor } from "../core/index.js";
+import type { Delivery } from "./api.js";
+
+const palette = [
+  "#007aff",
+  "#34c759",
+  "#ff9500",
+  "#af52de",
+  "#ff2d55",
+  "#5ac8fa",
+  "#5856d6",
+  "#a2845e",
+];
+
+export function initials(name: string) {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  const first = parts[0] ?? "?";
+  const last = parts[parts.length - 1] ?? "";
+  const letters = parts.length > 1 ? `${first[0] ?? ""}${last[0] ?? ""}` : first.slice(0, 2);
+  return letters.toUpperCase();
+}
+
+export function colorFor(name: string) {
+  let hash = 0;
+  for (const char of name) hash = (hash * 31 + char.charCodeAt(0)) | 0;
+  return palette[Math.abs(hash) % palette.length];
+}
+
+export function ago(iso: string) {
+  const seconds = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  if (seconds < 60) return "now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  if (seconds < 86400 * 30) return `${Math.floor(seconds / 86400)}d`;
+  return new Date(iso).toLocaleDateString();
+}
+
+export function targetName(anchor: Anchor) {
+  const owner = anchor.component?.name ?? anchor.tag;
+  const label = (anchor.accName || anchor.text || "").trim();
+  return label ? `${owner} › ${label.length > 40 ? `${label.slice(0, 40)}…` : label}` : owner;
+}
+
+/** "pending": on this page, but not looked up yet. */
+export type PlacedStatus =
+  | "pinned"
+  | "drifted"
+  | "hidden"
+  | "ambiguous"
+  | "unavailable"
+  | "resolved"
+  | "pending";
+
+/** Where the open pin card sits. A resolved thread leaves the screen. An open pin uses its
+ * current spot, and one that only lost its box for a moment keeps the last spot. */
+export function openPinCardSpot(
+  thread: { id: string; status: "open" | "resolved" } | undefined,
+  live: { id: string; x: number; y: number } | null,
+  held: { id: string; x: number; y: number } | null,
+) {
+  if (!thread || thread.status === "resolved") return null;
+  if (live?.id === thread.id) return live;
+  if (held?.id === thread.id) return held;
+  return null;
+}
+
+/**
+ * Keep a status the actor just set when a colder thread list still has the previous one.
+ * A list that already shows the painted status drops that pending entry.
+ */
+export function paintThreadStatuses<T extends { id: string; status: "open" | "resolved" }>(
+  threads: readonly T[],
+  pending: ReadonlyMap<string, "open" | "resolved">,
+): { threads: T[]; pending: Map<string, "open" | "resolved"> } {
+  const nextPending = new Map<string, "open" | "resolved">();
+  const painted = threads.map((thread) => {
+    const status = pending.get(thread.id);
+    if (!status || thread.status === status) return thread;
+    nextPending.set(thread.id, status);
+    return { ...thread, status };
+  });
+  return { threads: painted, pending: nextPending };
+}
+
+/** Plain-language reason a thread isn't pinned, or null when there's nothing to explain. */
+export function statusNote(
+  status: PlacedStatus,
+  anchor: Anchor,
+): { text: string; tone: string } | null {
+  switch (status) {
+    case "pinned":
+    case "resolved":
+    case "pending":
+    case "unavailable":
+      return null;
+    case "drifted":
+      return { text: "Text changed", tone: "warn" };
+    case "hidden":
+      return {
+        text: anchor.overlay ? `Inside “${anchor.overlay.name}”` : "Not visible right now",
+        tone: "quiet",
+      };
+    case "ambiguous":
+      return { text: "Matches more than one element", tone: "warn" };
+    default: {
+      const never: never = status;
+      return never;
+    }
+  }
+}
+
+function names(people: Array<{ name: string }>) {
+  const list = people.map((person) => person.name);
+  return list.length > 1 ? `${list.slice(0, -1).join(", ")} and ${list.at(-1)}` : (list[0] ?? "");
+}
+
+/** One quiet line about who was emailed for a message, or null when nobody was mentioned. */
+export function deliveryText(delivery: Delivery | undefined) {
+  if (!delivery) return null;
+  const parts: string[] = [];
+  if (delivery.emailed.length) parts.push(`Emailed ${names(delivery.emailed)}`);
+  const limited = delivery.skipped.filter((item) => item.reason === "rate_limited");
+  if (limited.length) parts.push(`Hourly email limit reached, ${names(limited)} not emailed`);
+  const muted = delivery.skipped.filter((item) => item.reason === "muted");
+  if (muted.length) parts.push(`${names(muted)} turned off mention emails`);
+  if (delivery.skipped.some((item) => item.reason === "disabled"))
+    parts.push("Email isn’t set up for this app");
+  return parts.length ? parts.join(" · ") : null;
+}

package/src/runtime/freshness.ts

@@ -0,0 +1,23 @@
+/** Longest wait between threads refetches while no live socket is open and something on screen needs them. */
+export const MAX_POLL_MS = 60_000;
+
+export type PollState = {
+  /** The live socket is open, so changes are pushed. */
+  live: boolean;
+  visible: boolean;
+  /** Something on screen shows threads: the comments panel, a draft, or this page's pins and count. */
+  wanted: boolean;
+  /** Refetches in a row that changed nothing. */
+  quiet: number;
+  pollMs: number;
+};
+
+/**
+ * Milliseconds until the next threads refetch, or null for none: the live socket pushes changes, the tab is hidden,
+ * or the toolbar is collapsed with nothing on this page to keep current. Each refetch that changed nothing doubles
+ * the wait, up to MAX_POLL_MS (or `pollMs`, if that is longer).
+ */
+export function nextPoll({ live, visible, wanted, quiet, pollMs }: PollState): number | null {
+  if (live || !visible || !wanted) return null;
+  return Math.min(pollMs * 2 ** quiet, Math.max(pollMs, MAX_POLL_MS));
+}

package/src/runtime/handoff.ts

@@ -0,0 +1,76 @@
+const key = "devaccel.comment.handoff";
+const ttl = 30 * 60 * 1000;
+
+export type Handoff = { invite?: string; thread?: string; at: number };
+
+export function readHandoff(): Handoff | null {
+  try {
+    const value = JSON.parse(sessionStorage.getItem(key) ?? "null") as Handoff | null;
+    return value && Date.now() - value.at < ttl ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function write(value: Handoff) {
+  try {
+    if (value.invite || value.thread) sessionStorage.setItem(key, JSON.stringify(value));
+    else sessionStorage.removeItem(key);
+  } catch {
+    // Storage can be unavailable (private mode, sandboxed frames); the link then only works on this load.
+  }
+}
+
+function linkParams() {
+  const url = new URL(window.location.href);
+  const hash = new URLSearchParams(url.hash.slice(1));
+  return {
+    url,
+    hash,
+    invite: url.searchParams.get("cs-invite") ?? hash.get("cs-invite"),
+    thread: url.searchParams.get("cs-thread") ?? hash.get("cs-thread"),
+  };
+}
+
+/**
+ * Saves invite and thread links for this tab before the app's router or sign-in flow rewrites the URL.
+ * Runs when the module loads, which is before hydration, and again when the toolbar mounts.
+ */
+export function captureHandoff() {
+  if (typeof window === "undefined") return;
+  const { invite, thread } = linkParams();
+  if (!invite && !thread) return;
+  write({
+    ...readHandoff(),
+    ...(invite ? { invite } : {}),
+    ...(thread ? { thread } : {}),
+    at: Date.now(),
+  });
+}
+
+export function dropHandoff(part: "invite" | "thread") {
+  const current = readHandoff();
+  if (!current) return;
+  const { [part]: _dropped, ...rest } = current;
+  write(rest);
+}
+
+/** Removes the link params from the address bar once they're saved. */
+export function stripHandoffFromUrl() {
+  const { url, hash } = linkParams();
+  const inQuery = url.searchParams.has("cs-invite") || url.searchParams.has("cs-thread");
+  const inHash = hash.has("cs-invite") || hash.has("cs-thread");
+  if (!inQuery && !inHash) return;
+  url.searchParams.delete("cs-invite");
+  url.searchParams.delete("cs-thread");
+  if (inHash) url.hash = "";
+  history.replaceState(history.state, "", url);
+}
+
+export function linkWith(href: string, name: "cs-invite" | "cs-thread", value: string) {
+  const url = new URL(href, window.location.origin);
+  url.searchParams.delete("cs-invite");
+  url.searchParams.delete("cs-thread");
+  url.hash = `${name}=${encodeURIComponent(value)}`;
+  return url.toString();
+}

package/src/runtime/host-watch.ts

@@ -0,0 +1,64 @@
+/**
+ * When to ask the host app's session route again, so the toolbar follows a sign-in or a sign-out that did not
+ * load a page. The route is only asked when something a person does could have changed who is signed in: the
+ * page comes back into view or gets the focus, the app navigates (its router, the back button, a hash route),
+ * or the browser restores the page from its back-forward cache. Never on a timer, and never more often than
+ * once per `HOST_CHECK_GAP_MS`: a moment inside the gap is answered at its end.
+ */
+
+/** The shortest time between two questions to the host's session route. */
+export const HOST_CHECK_GAP_MS = 10_000;
+
+/** Dispatched on `window` after the app calls `history.pushState` or `history.replaceState`. */
+export const NAVIGATED = "cs-nav";
+const HISTORY_FLAG = "__devaccelCommentHistory";
+
+/** Makes the app's own `pushState` and `replaceState` dispatch `NAVIGATED`. Once per page, whoever asks. */
+export function announceNavigation(): void {
+  if (Reflect.get(window, HISTORY_FLAG)) return;
+  Reflect.set(window, HISTORY_FLAG, true);
+  for (const name of ["pushState", "replaceState"] as const) {
+    const original = history[name].bind(history);
+    history[name] = (...args: Parameters<History["pushState"]>) => {
+      original(...args);
+      window.dispatchEvent(new Event(NAVIGATED));
+    };
+  }
+}
+
+export type HostWatch = {
+  /** Asks now, whatever the gap: the host said its sign-in changed. */
+  now(): void;
+  stop(): void;
+};
+
+/** Calls `check` at the moments above. The first one is a gap after this call: the caller has just asked. */
+export function watchHost(check: () => void, gap = HOST_CHECK_GAP_MS): HostWatch {
+  announceNavigation();
+  const listening = new AbortController();
+  let last = Date.now();
+  let timer = 0;
+  const run = () => {
+    window.clearTimeout(timer);
+    timer = 0;
+    last = Date.now();
+    check();
+  };
+  const soon = (event: Event) => {
+    if (timer || document.visibilityState === "hidden") return;
+    if (event.type === "pageshow" && !(event as PageTransitionEvent).persisted) return;
+    const wait = last + gap - Date.now();
+    if (wait <= 0) run();
+    else timer = window.setTimeout(run, wait);
+  };
+  for (const type of ["focus", "popstate", "hashchange", "pageshow", NAVIGATED])
+    window.addEventListener(type, soon, { signal: listening.signal });
+  document.addEventListener("visibilitychange", soon, { signal: listening.signal });
+  return {
+    now: run,
+    stop() {
+      window.clearTimeout(timer);
+      listening.abort();
+    },
+  };
+}