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

package/src/runtime/dock.ts

@@ -0,0 +1,108 @@
+/**
+ * Where the comment toolbar sits after someone drags it.
+ *
+ * Same gesture as React Grab's toolbar: a press that moves less than `dockSlop` is still a click,
+ * a longer press follows the pointer, and release snaps to the nearest screen edge. A flick is
+ * projected `dockFlickMs` ahead so the bar lands on the edge it was heading toward. An equal
+ * distance prefers top, then left, then right, then bottom.
+ */
+export type DockEdge = "top" | "right" | "bottom" | "left";
+export type Dock = { edge: DockEdge; ratio: number };
+export type DockPoint = { x: number; y: number };
+export type DockSize = { width: number; height: number };
+export type DockBounds = { width: number; height: number };
+
+/** Inset from the screen edge once the bar has snapped, in px. */
+export const dockMargin = 12;
+/** Movement below this, in px, stays a click on a tool. */
+export const dockSlop = 4;
+/** How far ahead a flick is projected, in ms. */
+export const dockFlickMs = 150;
+
+const edges = ["top", "right", "bottom", "left"] as const;
+
+export function readDock(value: unknown): Dock | undefined {
+  if (!value || typeof value !== "object") return;
+  const dock = value as { edge?: unknown; ratio?: unknown };
+  if (!edges.includes(dock.edge as DockEdge)) return;
+  if (typeof dock.ratio !== "number" || !Number.isFinite(dock.ratio)) return;
+  return { edge: dock.edge as DockEdge, ratio: clamp(dock.ratio, 0, 1) };
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function span(length: number, size: number, margin: number) {
+  return Math.max(0, length - size - margin * 2);
+}
+
+/** `ratio` is 0 at the start of the edge and 1 at the end. */
+export function placeDock(
+  dock: Dock,
+  bounds: DockBounds,
+  size: DockSize,
+  margin = dockMargin,
+): DockPoint {
+  const ratio = clamp(dock.ratio, 0, 1);
+  if (dock.edge === "top" || dock.edge === "bottom") {
+    return {
+      x: margin + span(bounds.width, size.width, margin) * ratio,
+      y: dock.edge === "top" ? margin : Math.max(margin, bounds.height - size.height - margin),
+    };
+  }
+  return {
+    x: dock.edge === "left" ? margin : Math.max(margin, bounds.width - size.width - margin),
+    y: margin + span(bounds.height, size.height, margin) * ratio,
+  };
+}
+
+function ratioOn(
+  edge: DockEdge,
+  point: DockPoint,
+  bounds: DockBounds,
+  size: DockSize,
+  margin: number,
+) {
+  if (edge === "top" || edge === "bottom") {
+    const room = span(bounds.width, size.width, margin);
+    return room <= 0 ? 0.5 : clamp((point.x - margin) / room, 0, 1);
+  }
+  const room = span(bounds.height, size.height, margin);
+  return room <= 0 ? 0.5 : clamp((point.y - margin) / room, 0, 1);
+}
+
+/** Keep the whole bar on screen while it follows the pointer. */
+export function clampBar(point: DockPoint, bounds: DockBounds, size: DockSize): DockPoint {
+  return {
+    x: clamp(point.x, 0, Math.max(0, bounds.width - size.width)),
+    y: clamp(point.y, 0, Math.max(0, bounds.height - size.height)),
+  };
+}
+
+/** `velocity` is px/ms. The returned point is the snapped top-left. */
+export function snapDock(
+  origin: DockPoint,
+  velocity: DockPoint,
+  bounds: DockBounds,
+  size: DockSize,
+  margin = dockMargin,
+): Dock & DockPoint {
+  const x = origin.x + velocity.x * dockFlickMs;
+  const y = origin.y + velocity.y * dockFlickMs;
+  const centerX = x + size.width / 2;
+  const centerY = y + size.height / 2;
+  const top = centerY;
+  const bottom = bounds.height - centerY;
+  const left = centerX;
+  const right = bounds.width - centerX;
+  const nearest = Math.min(top, bottom, left, right);
+  const edge: DockEdge =
+    nearest === top ? "top" : nearest === left ? "left" : nearest === right ? "right" : "bottom";
+  const along = {
+    x: clamp(x, margin, Math.max(margin, bounds.width - size.width - margin)),
+    y: clamp(y, margin, Math.max(margin, bounds.height - size.height - margin)),
+  };
+  const ratio = ratioOn(edge, along, bounds, size, margin);
+  return { edge, ratio, ...placeDock({ edge, ratio }, bounds, size, margin) };
+}

package/src/runtime/draft-dock.tsx

@@ -0,0 +1,124 @@
+import * as Icon from "./icons.js";
+
+export type DraftDockMode = "collecting" | "resume";
+
+/**
+ * Which dock stands in for the bar, if any. An open page draft shows only while it is minimised to collect
+ * captures; with no page draft open, a draft found in storage offers to resume.
+ */
+export function draftDockMode(state: {
+  readonly signedIn: boolean;
+  readonly pageDraft: boolean;
+  readonly collecting: boolean;
+  readonly stored: boolean;
+}): DraftDockMode | null {
+  if (!state.signedIn) return null;
+  if (state.pageDraft) return state.collecting ? "collecting" : null;
+  return state.stored ? "resume" : null;
+}
+
+function ago(at: number | null) {
+  if (!at) return "Saving…";
+  const seconds = Math.max(0, Math.round((Date.now() - at) / 1000));
+  if (seconds < 8) return "Saved just now";
+  if (seconds < 60) return `Saved ${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  return `Saved ${minutes} min ago`;
+}
+
+/**
+ * The draft, minimised over the live app: a chip in the bar's place (the bar hides) that says what it holds and
+ * takes more captures.
+ * In `resume` mode it offers a draft found in storage after a reload (or from another visit) instead.
+ */
+export function DraftDock({
+  title,
+  pictures,
+  clips,
+  savedAt,
+  mode,
+  note,
+  recording,
+  confirmDiscard,
+  onCapture,
+  onRecord,
+  onOpen,
+  onDiscard,
+}: {
+  title: string;
+  pictures: number;
+  clips: number;
+  savedAt: number | null;
+  mode: DraftDockMode;
+  /** Something the person should know about this draft (a recording cut short by a reload). */
+  note?: string | undefined;
+  recording: boolean;
+  /** The first Discard press asks; this is true until the second one, or until it times out. */
+  confirmDiscard: boolean;
+  onCapture: () => void;
+  onRecord: () => void;
+  onOpen: () => void;
+  onDiscard: () => void;
+}) {
+  const parts = [
+    pictures ? `${pictures} picture${pictures === 1 ? "" : "s"}` : null,
+    clips ? `${clips} clip${clips === 1 ? "" : "s"}` : null,
+  ].filter(Boolean);
+  const what = parts.length ? parts.join(" · ") : "nothing captured yet";
+  return (
+    <div className="cs-draft-dock cs-hit" data-cs-ui="draft-dock" data-mode={mode} role="status">
+      <span className="cs-draft-dot" aria-hidden="true" />
+      <span className="cs-draft-text">
+        <strong>{mode === "resume" ? "Pick up your draft?" : `Draft · ${title}`}</strong>
+        <small>
+          {mode === "resume"
+            ? `${title} · ${what} · kept on this device`
+            : `${ago(savedAt)} · ${what}`}
+        </small>
+        {note ? <small className="cs-draft-note">{note}</small> : null}
+      </span>
+      {mode === "collecting" ? (
+        <>
+          <button
+            className="cs-button"
+            type="button"
+            data-cs-ui="draft-capture"
+            title="Take a picture of this page into the draft (S)"
+            onClick={onCapture}
+          >
+            <Icon.Camera />
+            Capture
+          </button>
+          <button
+            className={`cs-button cs-draft-record${recording ? " is-on" : ""}`}
+            type="button"
+            data-cs-ui="draft-record"
+            title={recording ? "Recording…" : "Record this tab into the draft (R)"}
+            disabled={recording}
+            onClick={onRecord}
+          >
+            <Icon.Record />
+            {recording ? "Recording…" : "Record"}
+          </button>
+        </>
+      ) : null}
+      <button
+        className="cs-button is-primary"
+        type="button"
+        data-cs-ui="draft-open"
+        onClick={onOpen}
+      >
+        {mode === "resume" ? "Resume" : "Open draft"}
+      </button>
+      <button
+        className={`cs-button cs-draft-discard${confirmDiscard ? " is-danger" : ""}`}
+        type="button"
+        data-cs-ui="draft-discard"
+        title="Throw this draft away"
+        onClick={onDiscard}
+      >
+        {confirmDiscard ? "Discard?" : <Icon.Trash />}
+      </button>
+    </div>
+  );
+}

package/src/runtime/draft-model.ts

@@ -0,0 +1,251 @@
+/**
+ * The draft model and store, without a storage engine: the web toolbar keeps drafts in IndexedDB
+ * (`./draft-store.ts`), native clients in files. DOM-free.
+ */
+import type { Anchor } from "../core/index.js";
+import type { Capture, Details } from "./api.js";
+import { readClarityHold, type ClarityHold } from "./clarity-model.js";
+import { readReportKind, type ReportKind } from "./kind-model.js";
+import type { MarkupShape } from "./markup-model.js";
+import type { ReplayEvent } from "./replay-model.js";
+import type { TicketValues } from "./ticket-form-model.js";
+
+/**
+ * A draft that follows the person around the app until it is sent: everything in it is written here as it
+ * changes, so a reload, a crash, a closed laptop or another tab can offer to pick it up. Pictures and clips are
+ * kept as blobs; the browser's own storage (IndexedDB) holds them, and nothing leaves the device from here.
+ */
+
+export type StoredCapture = {
+  key: string;
+  name: string;
+  type: string;
+  blob: Blob;
+  capture?: Capture | undefined;
+  /** The unmarked original and the shapes flattened into `blob`, when the picture was marked up. */
+  markup?: { blob: Blob; name: string; shapes: MarkupShape[] } | undefined;
+  /** Shapes drawn since the last flatten (or ever), so a reload loses no stroke. */
+  shapes: MarkupShape[];
+};
+
+export type StoredDraft = {
+  v: 1;
+  id: string;
+  createdAt: number;
+  updatedAt: number;
+  /** The page the draft was started on; the comment is filed against it. */
+  href: string;
+  route: string;
+  anchor: Anchor;
+  body: string;
+  details: Details;
+  /** The kind the person chose, when they did. */
+  kind?: ReportKind;
+  ticket: TicketValues;
+  captures: StoredCapture[];
+  /** The capture open on the stage. */
+  selected: string | null;
+  /** Something the person should know when they pick the draft up (a recording cut short by a reload). */
+  note?: string;
+  /** The clarity check's open questions and the answers typed so far, when Send was held for them. */
+  clarity?: ClarityHold;
+};
+
+/**
+ * A recording while it runs: every chunk so far and what happened on the page, written as they land, so a
+ * reload or a crash mid-take keeps the part that was filmed.
+ */
+export type StoredRecording = {
+  v: 1;
+  draftId: string;
+  mime: string;
+  startedAt: number;
+  url: string;
+  chunks: Blob[];
+  events: ReplayEvent[];
+};
+
+/** Where drafts are kept: the browser's IndexedDB on the web, files on native, a map in tests. */
+export type DraftBackend = {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown): Promise<void>;
+  remove(key: string): Promise<void>;
+};
+
+/** Matches the composer's file cap so a recovered clip is not the row a resume drops. */
+export const MAX_DRAFT_CAPTURES = 5;
+export const MAX_DRAFT_BYTES = 50 * 1024 * 1024;
+
+export function memoryBackend(): DraftBackend {
+  const map = new Map<string, unknown>();
+  return {
+    get: async (key) => map.get(key),
+    put: async (key, value) => {
+      map.set(key, value);
+    },
+    remove: async (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+/** A stored record's fields, read one by one and checked before use: storage holds whatever an older build wrote. */
+type UnknownFields = { readonly [field: string]: unknown };
+
+function isRecord(value: unknown): value is UnknownFields {
+  return typeof value === "object" && value !== null;
+}
+
+/** `value` as a draft, or null when it isn't one this build can read. A broken record is never resumed. */
+function readStoredRecording(value: unknown): StoredRecording | null {
+  if (!isRecord(value) || value["v"] !== 1) return null;
+  if (typeof value["draftId"] !== "string" || typeof value["mime"] !== "string") return null;
+  if (!Array.isArray(value["chunks"])) return null;
+  const chunks = value["chunks"].filter((chunk): chunk is Blob => chunk instanceof Blob);
+  if (!chunks.length) return null;
+  return {
+    v: 1,
+    draftId: value["draftId"],
+    mime: value["mime"],
+    startedAt: typeof value["startedAt"] === "number" ? value["startedAt"] : Date.now(),
+    url: typeof value["url"] === "string" ? value["url"] : "",
+    chunks,
+    events: Array.isArray(value["events"]) ? (value["events"] as ReplayEvent[]) : [],
+  };
+}
+
+export function readStoredDraft(value: unknown): StoredDraft | null {
+  if (!isRecord(value) || value["v"] !== 1) return null;
+  if (typeof value["id"] !== "string" || typeof value["href"] !== "string") return null;
+  if (!isRecord(value["anchor"]) || !Array.isArray(value["captures"])) return null;
+  const captures: StoredCapture[] = [];
+  for (const item of value["captures"]) {
+    if (!isRecord(item) || typeof item["key"] !== "string" || !(item["blob"] instanceof Blob))
+      continue;
+    captures.push({
+      key: item["key"],
+      name: typeof item["name"] === "string" ? item["name"] : "capture",
+      type: typeof item["type"] === "string" ? item["type"] : item["blob"].type,
+      blob: item["blob"],
+      capture: isRecord(item["capture"]) ? (item["capture"] as Capture) : undefined,
+      markup:
+        isRecord(item["markup"]) && item["markup"]["blob"] instanceof Blob
+          ? {
+              blob: item["markup"]["blob"],
+              name: typeof item["markup"]["name"] === "string" ? item["markup"]["name"] : "capture",
+              shapes: Array.isArray(item["markup"]["shapes"])
+                ? (item["markup"]["shapes"] as MarkupShape[])
+                : [],
+            }
+          : undefined,
+      shapes: Array.isArray(item["shapes"]) ? (item["shapes"] as MarkupShape[]) : [],
+    });
+  }
+  // Questions that do not read whole are left out; the draft itself is still resumed.
+  const clarity = readClarityHold(value["clarity"]);
+  const kind = readReportKind(value["kind"]);
+  return {
+    v: 1,
+    id: value["id"],
+    createdAt: typeof value["createdAt"] === "number" ? value["createdAt"] : Date.now(),
+    updatedAt: typeof value["updatedAt"] === "number" ? value["updatedAt"] : Date.now(),
+    href: value["href"],
+    route: typeof value["route"] === "string" ? value["route"] : "/",
+    anchor: value["anchor"] as Anchor,
+    body: typeof value["body"] === "string" ? value["body"] : "",
+    details: isRecord(value["details"])
+      ? (value["details"] as Details)
+      : ({ role: null, fields: {} } as Details),
+    ...(kind ? { kind } : {}),
+    ticket: isRecord(value["ticket"]) ? (value["ticket"] as TicketValues) : {},
+    captures,
+    selected: typeof value["selected"] === "string" ? value["selected"] : null,
+    ...(typeof value["note"] === "string" && value["note"] ? { note: value["note"] } : {}),
+    ...(clarity ? { clarity } : {}),
+  };
+}
+
+/** What the dock and the resume offer say about a draft. */
+export function describeDraft(draft: { body: string; captures: Array<{ type: string }> }) {
+  const pictures = draft.captures.filter((item) => item.type.startsWith("image/")).length;
+  const clips = draft.captures.filter((item) => item.type.startsWith("video/")).length;
+  const firstLine =
+    draft.body
+      .split("\n")
+      .find((line) => line.trim())
+      ?.trim() ?? "";
+  const title = firstLine.length > 48 ? `${firstLine.slice(0, 48)}…` : firstLine;
+  return { pictures, clips, title: title || "Untitled draft" };
+}
+
+export type DraftStore = {
+  /** False when the browser has no IndexedDB, so a reload will not see this write. */
+  readonly durable: boolean;
+  load(): Promise<StoredDraft | null>;
+  save(draft: StoredDraft): Promise<void>;
+  clear(): Promise<void>;
+  loadRecording(): Promise<StoredRecording | null>;
+  saveRecording(recording: StoredRecording): Promise<void>;
+  clearRecording(): Promise<void>;
+};
+
+function draftBytes(draft: StoredDraft) {
+  return draft.captures.reduce(
+    (sum, item) => sum + item.blob.size + (item.markup?.blob.size ?? 0),
+    0,
+  );
+}
+
+/**
+ * One draft per `scope` (API, environment, project, and member). Saves are serialised so a fast burst can't
+ * land out of order. A draft or recording over the byte cap throws; other save failures reject too, and the
+ * toolbar tries again on the next change.
+ */
+export function createDraftStore(scope: string, backend: DraftBackend | null): DraftStore {
+  const key = `draft:${scope}`;
+  const recordingKey = `recording:${scope}`;
+  const durable = backend !== null;
+  const store = backend ?? memoryBackend();
+  let chain: Promise<unknown> = Promise.resolve();
+  const queue = <T>(task: () => Promise<T>): Promise<T> => {
+    const next = chain.then(task, task);
+    chain = next.catch(() => {});
+    return next;
+  };
+  return {
+    durable,
+    load: () =>
+      queue(async () => {
+        try {
+          return readStoredDraft(await store.get(key));
+        } catch {
+          return null;
+        }
+      }),
+    save: (draft) =>
+      queue(async () => {
+        if (draftBytes(draft) > MAX_DRAFT_BYTES) {
+          throw new Error("This draft is too large to keep on this device.");
+        }
+        await store.put(key, draft);
+      }),
+    clear: () => queue(() => store.remove(key)),
+    loadRecording: () =>
+      queue(async () => {
+        try {
+          return readStoredRecording(await store.get(recordingKey));
+        } catch {
+          return null;
+        }
+      }),
+    saveRecording: (recording) =>
+      queue(async () => {
+        const bytes = recording.chunks.reduce((sum, chunk) => sum + chunk.size, 0);
+        if (bytes > MAX_DRAFT_BYTES) {
+          throw new Error("This recording is too large to keep on this device.");
+        }
+        await store.put(recordingKey, recording);
+      }),
+    clearRecording: () => queue(() => store.remove(recordingKey)),
+  };
+}

package/src/runtime/draft-store.ts

@@ -0,0 +1,149 @@
+import { attachmentStamp } from "./attachment-model.js";
+import {
+  createDraftStore as storeIn,
+  MAX_DRAFT_CAPTURES,
+  type DraftBackend,
+  type DraftStore,
+  type StoredCapture,
+  type StoredDraft,
+  type StoredRecording,
+} from "./draft-model.js";
+
+// Everything but `createDraftStore`, which this file wraps with the browser's IndexedDB backend.
+export {
+  MAX_DRAFT_BYTES,
+  MAX_DRAFT_CAPTURES,
+  describeDraft,
+  memoryBackend,
+  readStoredDraft,
+} from "./draft-model.js";
+export type {
+  DraftBackend,
+  DraftStore,
+  StoredCapture,
+  StoredDraft,
+  StoredRecording,
+} from "./draft-model.js";
+
+/** IndexedDB names. */
+const DB_NAME = "cs-toolbar";
+const STORE = "drafts";
+
+function request<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB request failed"));
+  });
+}
+
+/** IndexedDB, or null where the browser has none (or refuses it, as in some private windows). */
+export function idbBackend(
+  factory: IDBFactory | undefined = globalThis.indexedDB,
+): DraftBackend | null {
+  if (!factory) return null;
+  let opened: Promise<IDBDatabase> | null = null;
+  const db = () => {
+    opened ??= new Promise<IDBDatabase>((resolve, reject) => {
+      let req: IDBOpenDBRequest;
+      try {
+        req = factory.open(DB_NAME, 1);
+      } catch (caught) {
+        reject(caught);
+        return;
+      }
+      req.onupgradeneeded = () => {
+        if (!req.result.objectStoreNames.contains(STORE)) req.result.createObjectStore(STORE);
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error ?? new Error("IndexedDB open failed"));
+      req.onblocked = () => reject(new Error("IndexedDB open blocked"));
+    });
+    return opened;
+  };
+  const run = async <T>(
+    mode: IDBTransactionMode,
+    act: (store: IDBObjectStore) => IDBRequest<T>,
+  ) => {
+    const database = await db();
+    const tx = database.transaction(STORE, mode);
+    // Listened for before the request is made: a transaction that finishes first would otherwise never be heard.
+    const done = new Promise<void>((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error("IndexedDB transaction failed"));
+      tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+    });
+    const result = await request(act(tx.objectStore(STORE)));
+    await done;
+    return result;
+  };
+  return {
+    get: (key) => run("readonly", (store) => store.get(key)),
+    put: async (key, value) => {
+      await run("readwrite", (store) => store.put(value, key));
+    },
+    remove: async (key) => {
+      await run("readwrite", (store) => store.delete(key));
+    },
+  };
+}
+
+/**
+ * `draft` with a recording that was cut off (by a reload, a crash) put in as a clip, with its replay beside it,
+ * and a note saying so. Nothing changes when the recording belongs to another draft.
+ */
+export function recoverRecording(draft: StoredDraft, recording: StoredRecording): StoredDraft {
+  if (recording.draftId !== draft.id) return draft;
+  const when = attachmentStamp(recording.startedAt);
+  const extension = recording.mime === "video/mp4" ? "mp4" : "webm";
+  const name = `recording-${when}.cut.${extension}`;
+  if (draft.captures.some((item) => item.name === name)) return draft;
+  const last = recording.events.at(-1)?.t ?? recording.startedAt;
+  const durationMs = Math.max(1000, last - recording.startedAt, recording.chunks.length * 1000);
+  const added = recording.events.length ? 2 : 1;
+  const kept = draft.captures.slice(
+    Math.max(0, draft.captures.length - (MAX_DRAFT_CAPTURES - added)),
+  );
+  const captures: StoredCapture[] = [
+    ...kept,
+    {
+      key: `cut-${recording.startedAt}`,
+      name,
+      type: recording.mime,
+      blob: new Blob(recording.chunks, { type: recording.mime }),
+      shapes: [],
+    },
+  ];
+  if (recording.events.length) {
+    const replay = {
+      v: 1,
+      kind: "instant-replay",
+      url: recording.url,
+      events: recording.events,
+      clip: { name, startedAt: recording.startedAt, durationMs },
+    };
+    captures.push({
+      key: `cut-replay-${recording.startedAt}`,
+      name: `replay-${when}.cut.json`,
+      type: "application/json",
+      blob: new Blob([JSON.stringify(replay)], { type: "application/json" }),
+      shapes: [],
+    });
+  }
+  return {
+    ...draft,
+    updatedAt: Date.now(),
+    captures,
+    note: "A recording was cut short by a reload. What was filmed is in the draft; record again to go on.",
+  };
+}
+
+/**
+ * One draft per `scope` (API, environment, project, and member), in this browser's IndexedDB, or in memory
+ * where there is none.
+ */
+export function createDraftStore(
+  scope: string,
+  backend: DraftBackend | null = idbBackend(),
+): DraftStore {
+  return storeIn(scope, backend);
+}