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

package/src/runtime/sync.ts

@@ -0,0 +1,300 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ApiError, listThreads, openLive } from "./client.js";
+import { nextPoll } from "./freshness.js";
+import {
+  KEEPALIVE_MS,
+  MAX_QUICK_RETRIES,
+  OPEN_WAIT_MS,
+  parseLiveMessage,
+  PUSH_BATCH_MS,
+  RETRY_LATER_MS,
+} from "./live-model.js";
+import type { Session } from "./session.js";
+import { announceBuild } from "./update.js";
+
+export type ThreadsPayload = Awaited<ReturnType<typeof listThreads>>;
+
+export { parseLiveMessage, type LiveMessage } from "./live-model.js";
+
+/** A tab hidden this long closes its live socket. Showing it again reconnects, and the reconnect catches up. */
+const HIDDEN_CLOSE_MS = 60_000;
+/** After navigating, a refetch waits until the address has settled. */
+const NAVIGATION_SETTLE_MS = 1_000;
+
+export function usePageVisible() {
+  const [visible, setVisible] = useState(() => document.visibilityState !== "hidden");
+  useEffect(() => {
+    const sync = () => setVisible(document.visibilityState !== "hidden");
+    document.addEventListener("visibilitychange", sync);
+    return () => document.removeEventListener("visibilitychange", sync);
+  }, []);
+  return visible;
+}
+
+/**
+ * Keeps threads current with as few requests as possible. The live socket pushes "changed" and each push batch
+ * refetches once; nothing is fetched while the tab is hidden. Without a socket, threads are polled only while the
+ * tab is visible and something on screen shows them (`wanted`), backing off while nothing changes. A refetch that
+ * returns what is already shown doesn't touch state.
+ */
+export function useThreadsSync({
+  session,
+  member,
+  pollMs,
+  wanted,
+  href,
+  onThreads,
+  onUnauthorized,
+  onDisabled,
+}: {
+  session: Session | null;
+  member: string | null;
+  pollMs: number;
+  wanted: boolean;
+  href: string;
+  onThreads: (next: ThreadsPayload) => void;
+  onUnauthorized: () => void;
+  /** The project turned comments off. The sign-in is kept, so turning them back on needs nothing from anyone. */
+  onDisabled?: () => void;
+}) {
+  const [live, setLive] = useState(false);
+  const visible = usePageVisible();
+  const current = useRef({ session, member, onThreads, onUnauthorized, onDisabled });
+  useEffect(() => {
+    current.current = { session, member, onThreads, onUnauthorized, onDisabled };
+  }, [member, onDisabled, onThreads, onUnauthorized, session]);
+  const shown = useRef("");
+  const lastFetch = useRef(0);
+  const quiet = useRef(0);
+  const inflight = useRef<Promise<boolean> | null>(null);
+  const again = useRef(false);
+  /** A live socket is open or on its way (connecting, or reconnecting after a drop); its opening catches up. */
+  const socketUp = useRef(false);
+
+  useEffect(() => {
+    const signedOut = session === null || member === null;
+    shown.current = signedOut ? "" : "";
+    lastFetch.current = 0;
+    quiet.current = 0;
+  }, [member, session]);
+
+  /** Fetches threads; resolves true when what's shown changed. Calls during a fetch queue exactly one more. */
+  const refresh = useCallback(function refresh(): Promise<boolean> {
+    const { session: activeSession, member: token } = current.current;
+    if (!activeSession || !token) return Promise.resolve(false);
+    if (inflight.current) {
+      again.current = true;
+      return inflight.current;
+    }
+    lastFetch.current = Date.now();
+    const run = listThreads(activeSession, token)
+      .then((next) => {
+        if (current.current.member !== token) return false;
+        const text = JSON.stringify(next);
+        if (text === shown.current) return false;
+        shown.current = text;
+        current.current.onThreads(next);
+        return true;
+      })
+      .catch((caught) => {
+        if (caught instanceof ApiError && caught.status === 401 && current.current.member === token)
+          current.current.onUnauthorized();
+        if (
+          caught instanceof ApiError &&
+          caught.status === 403 &&
+          caught.code === "module_disabled" &&
+          current.current.member === token
+        ) {
+          shown.current = "";
+          current.current.onDisabled?.();
+        }
+        return false;
+      })
+      .finally(() => {
+        inflight.current = null;
+      })
+      .then((changed) => {
+        if (!again.current) return changed;
+        again.current = false;
+        return refresh();
+      });
+    inflight.current = run;
+    return run;
+  }, []);
+
+  useEffect(() => {
+    if (!session || !member) return;
+    if (typeof WebSocket === "undefined") {
+      void refresh();
+      return;
+    }
+    let socket: WebSocket | null = null;
+    let stopped = false;
+    let failures = 0;
+    let stale = false;
+    let opened = false;
+    let retry = 0;
+    let batch = 0;
+    let openWait = 0;
+    let closeHidden = 0;
+    const hidden = () => document.visibilityState === "hidden";
+    const fireBatch = () => {
+      void refresh();
+    };
+    const changed = () => {
+      if (hidden()) {
+        stale = true;
+        return;
+      }
+      window.clearTimeout(batch);
+      batch = window.setTimeout(fireBatch, PUSH_BATCH_MS);
+    };
+    const fireOpenWait = () => {
+      if (!opened) changed();
+    };
+    const armOpenWait = () => {
+      window.clearTimeout(openWait);
+      openWait = window.setTimeout(fireOpenWait, OPEN_WAIT_MS);
+    };
+    const fireCloseHidden = () => {
+      socket?.close();
+    };
+    let connect: () => void = () => {};
+    const armRetry = (delay: number) => {
+      window.clearTimeout(retry);
+      retry = window.setTimeout(connect, delay);
+    };
+    connect = () => {
+      window.clearTimeout(retry);
+      let opening: WebSocket;
+      try {
+        opening = openLive(session, member);
+      } catch {
+        changed();
+        return;
+      }
+      socket = opening;
+      socketUp.current = true;
+      opened = false;
+      armOpenWait();
+      opening.onopen = () => {
+        opened = true;
+        failures = 0;
+        stale = false;
+        window.clearTimeout(openWait);
+        setLive(true);
+        changed();
+      };
+      opening.onmessage = (event) => {
+        const message = parseLiveMessage(event.data);
+        if (message.type === "build") announceBuild(message.build);
+        else if (message.type === "changed") changed();
+      };
+      opening.onclose = () => {
+        window.clearTimeout(openWait);
+        if (socket === opening) socket = null;
+        setLive(false);
+        if (stopped || hidden()) {
+          socketUp.current = false;
+          return;
+        }
+        if (!opened) {
+          socketUp.current = false;
+          failures += 1;
+          if (failures === 1) changed();
+        }
+        armRetry(failures > MAX_QUICK_RETRIES ? RETRY_LATER_MS : 1_000 * 2 ** failures);
+      };
+    };
+    const onVisibility = () => {
+      if (hidden()) {
+        window.clearTimeout(closeHidden);
+        closeHidden = window.setTimeout(fireCloseHidden, HIDDEN_CLOSE_MS);
+        return;
+      }
+      window.clearTimeout(closeHidden);
+      if (!socket) {
+        failures = 0;
+        connect();
+      } else if (stale) {
+        stale = false;
+        changed();
+      }
+    };
+    const keepAlive = window.setInterval(() => {
+      if (socket?.readyState === WebSocket.OPEN) socket.send("ping");
+    }, KEEPALIVE_MS);
+    if (!hidden()) connect();
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+      stopped = true;
+      socketUp.current = false;
+      window.clearTimeout(retry);
+      window.clearTimeout(batch);
+      window.clearTimeout(openWait);
+      window.clearTimeout(closeHidden);
+      window.clearInterval(keepAlive);
+      document.removeEventListener("visibilitychange", onVisibility);
+      socket?.close();
+      setLive(false);
+    };
+  }, [member, refresh, session]);
+
+  useEffect(() => {
+    if (!session || !member) return;
+    const delay = nextPoll({ live, visible, wanted, quiet: quiet.current, pollMs });
+    if (delay === null) return;
+    let stopped = false;
+    let timer = 0;
+    let wait = delay;
+    function afterWait() {
+      void refresh().then((changed) => {
+        quiet.current = changed ? 0 : quiet.current + 1;
+        if (stopped) return;
+        wait = nextPoll({ live, visible, wanted, quiet: quiet.current, pollMs }) ?? pollMs;
+        tick();
+      });
+    }
+    function tick() {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(afterWait, wait);
+    }
+    timer = window.setTimeout(afterWait, delay);
+    return () => {
+      stopped = true;
+      window.clearTimeout(timer);
+    };
+  }, [live, member, pollMs, refresh, session, visible, wanted]);
+
+  // Opening the panel or coming back to the tab catches up at once when no socket will.
+  useEffect(() => {
+    if (
+      !session ||
+      !member ||
+      live ||
+      socketUp.current ||
+      !visible ||
+      !wanted ||
+      !lastFetch.current
+    )
+      return;
+    if (Date.now() - lastFetch.current < pollMs) return;
+    quiet.current = 0;
+    void refresh();
+  }, [live, member, pollMs, refresh, session, visible, wanted]);
+
+  const lastHref = useRef(href);
+  useEffect(() => {
+    if (href === lastHref.current) return;
+    lastHref.current = href;
+    if (!session || !member || live || socketUp.current || !lastFetch.current) return;
+    const timer = window.setTimeout(() => {
+      if (Date.now() - lastFetch.current < pollMs) return;
+      quiet.current = 0;
+      void refresh();
+    }, NAVIGATION_SETTLE_MS);
+    return () => window.clearTimeout(timer);
+  }, [href, live, member, pollMs, refresh, session]);
+
+  return { live, refresh, visible };
+}

package/src/runtime/thread-model.ts

@@ -0,0 +1,71 @@
+/** Who wrote, who is named, and how a thread reads in lists. DOM-free, so native clients share it. */
+import type { CommentMessage, Thread } from "./api.js";
+import { ago } from "./format.js";
+
+/** Whether the signed-in member wrote `message` (author id when stored, else the name). */
+export function isMine(message: CommentMessage, memberId: string | undefined, memberName: string) {
+  return message.authorId ? message.authorId === memberId : message.author === memberName;
+}
+
+/** Every version of a message, oldest first; the last is the current body. */
+export function versionsOf(message: CommentMessage) {
+  return [
+    ...(message.revisions ?? []),
+    {
+      body: message.body,
+      mentions: message.mentions,
+      createdAt: message.editedAt ?? message.createdAt,
+    },
+  ];
+}
+
+/** `ago` as a phrase: "just now", "5 min ago". */
+export function agoPhrase(iso: string) {
+  const text = ago(iso);
+  return text === "now" ? "just now" : `${text} ago`;
+}
+
+/** A message's first sentence when it is a readable length, else the whole trimmed text. */
+export function leadSentence(body: string) {
+  const text = body.trim();
+  const split = text.search(/[.!?]\s/);
+  if (split > 24 && split < 96) return text.slice(0, split + 1);
+  return text;
+}
+
+/** Whether `name` started the thread or wrote in it. */
+export function involved(thread: Thread, name: string) {
+  return thread.createdBy === name || thread.messages.some((message) => message.author === name);
+}
+
+/** Whether a message @mentions the signed-in member (by id, else by name). */
+export function namesYou(
+  message: CommentMessage,
+  memberId: string | undefined,
+  memberName: string,
+) {
+  return (message.mentions ?? []).some(
+    (mention) =>
+      (memberId !== undefined && memberId !== null && mention.id === memberId) ||
+      (memberName !== "" && mention.name === memberName),
+  );
+}
+
+/** Whether the signed-in member wrote a message (by id, else by name). */
+export function fromYou(message: CommentMessage, memberId: string | undefined, memberName: string) {
+  return (
+    (memberId !== undefined && memberId !== null && message.authorId === memberId) ||
+    (memberName !== "" && message.author === memberName)
+  );
+}
+
+/** Latest message from someone else that @mentions the signed-in member. */
+export function mentionOfYou(thread: Thread, memberId: string | undefined, memberName: string) {
+  let hit: CommentMessage | null = null;
+  for (const message of thread.messages) {
+    if (fromYou(message, memberId, memberName) || !namesYou(message, memberId, memberName))
+      continue;
+    hit = message;
+  }
+  return hit;
+}

package/src/runtime/ticket-form-model.ts

@@ -0,0 +1,128 @@
+/**
+ * The tracker's ticket form a tester fills while commenting (`GET /v1/ticket-form`). The comment
+ * supplies the subject, description and files; the tester picks the Type (defect, enhancement…), the
+ * Priority and the project's other fields. The answers are saved with the comment, and "Create ticket"
+ * in a connection's inbox starts from them.
+ *
+ * Mirrors the connection's own ticket form type; the toolbar bundle doesn't import it.
+ * A field is visible when it has no condition, or its controller (always earlier in the form) is visible
+ * and holds one of the condition's values. That is one forward pass in form order.
+ */
+export interface TicketFormCondition {
+  readonly fieldKey: string;
+  readonly equalsAnyOf: readonly string[];
+}
+
+export interface TicketFormField {
+  readonly key: string;
+  readonly kind:
+    | "short_text"
+    | "long_text"
+    | "email"
+    | "phone"
+    | "url"
+    | "number"
+    | "select_single"
+    | "select_multi"
+    | "checkbox"
+    | "date"
+    | "datetime"
+    | "rating";
+  readonly label: string;
+  readonly required: boolean;
+  readonly helpText?: string;
+  readonly options?: readonly {
+    readonly value: string;
+    readonly label: string;
+    readonly when?: TicketFormCondition;
+  }[];
+  readonly min?: number;
+  readonly max?: number;
+  readonly scale?: 5 | 10;
+  readonly visibleWhen?: TicketFormCondition;
+}
+
+export interface TicketForm {
+  readonly formVersionId: string;
+  readonly fields: readonly TicketFormField[];
+}
+
+export type TicketValue = string | number | boolean | readonly string[];
+export type TicketValues = Readonly<Record<string, TicketValue>>;
+
+/** What `POST /v1/threads` takes as `ticket`. */
+export interface TicketDraft {
+  readonly formVersionId: string;
+  readonly values: TicketValues;
+}
+
+/** Up to this many options show as chips; more become a dropdown. */
+export const CHIP_OPTIONS_MAX = 6;
+
+function matchesCondition(condition: TicketFormCondition, value: TicketValue | undefined) {
+  if (value === undefined) return false;
+  if (typeof value === "boolean") return condition.equalsAnyOf.includes(value ? "true" : "false");
+  if (Array.isArray(value)) return value.some((entry) => condition.equalsAnyOf.includes(entry));
+  return condition.equalsAnyOf.includes(String(value));
+}
+
+/** Field key → visible, for the values so far. */
+export function ticketFieldVisibility(
+  form: TicketForm,
+  values: TicketValues,
+): ReadonlyMap<string, boolean> {
+  const visible = new Map<string, boolean>();
+  for (const field of form.fields) {
+    const condition = field.visibleWhen;
+    visible.set(
+      field.key,
+      condition === undefined ||
+        (visible.get(condition.fieldKey) !== false &&
+          matchesCondition(condition, values[condition.fieldKey])),
+    );
+  }
+  return visible;
+}
+
+/** Whether a ticket answer holds something (a checked box, a non-blank text, a picked option). */
+export function ticketValueFilled(value: TicketValue | undefined) {
+  if (value === undefined) return false;
+  if (typeof value === "string") return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+/** Labels of required fields that are visible and still empty. */
+export function missingTicketFields(form: TicketForm, values: TicketValues): readonly string[] {
+  const visible = ticketFieldVisibility(form, values);
+  return form.fields
+    .filter(
+      (field) =>
+        field.required &&
+        field.kind !== "checkbox" &&
+        visible.get(field.key) !== false &&
+        !ticketValueFilled(values[field.key]),
+    )
+    .map((field) => field.label);
+}
+
+/** The answers to send: visible, filled fields only. */
+export function ticketDraftPayload(form: TicketForm, values: TicketValues): TicketDraft | null {
+  const visible = ticketFieldVisibility(form, values);
+  const kept: Record<string, TicketValue> = {};
+  for (const field of form.fields) {
+    const value = values[field.key];
+    if (visible.get(field.key) !== false && ticketValueFilled(value)) kept[field.key] = value!;
+  }
+  return Object.keys(kept).length === 0
+    ? null
+    : { formVersionId: form.formVersionId, values: kept };
+}
+
+/** The field's options that apply to the values so far. */
+export function ticketFieldOptions(field: TicketFormField, values: TicketValues) {
+  return (field.options ?? []).filter(
+    (option) =>
+      option.when === undefined || matchesCondition(option.when, values[option.when.fieldKey]),
+  );
+}