helldots 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -191,42 +191,104 @@ export interface SerializedComment {
   reactions: Record<string, string[]> | null;
 }
 
+/**
+ * Who caused a change.
+ *
+ * `"user"` is somebody acting inside the widget — a marker, the thread
+ * popover, the inbox. `"host"` is the app's own code calling a method.
+ *
+ * The distinction exists for multi-user apps. Applying a change that arrived
+ * over a socket means calling the same method the UI calls, so without this
+ * every host has to wrap its own writes in a flag to avoid echoing them
+ * straight back to the server. `if (meta.origin === "host") return;` is that
+ * flag, and it is now the library's job to provide it.
+ */
+export type ChangeOrigin = "user" | "host";
+
+/** Which part of the widget a reported failure came from. */
+export type ErrorContext =
+  /** A screenshot render failed; the comment saves without one. */
+  | "capture"
+  /** localStorage could not be written; this browser's copy now diverges. */
+  | "storage"
+  /** A record handed to loadComments was malformed and was skipped. */
+  | "load"
+  /** An `onCommentRequested` handler threw or rejected. */
+  | "link"
+  /** A `transformScreenshot` handler failed; the data URL was kept. */
+  | "transform";
+
+/**
+ * What every change carries, whatever its type. Delivered as one trailing
+ * argument to the specific callbacks, and flattened onto the `onChange`
+ * event next to `comment`/`reply`/`id`.
+ */
+export interface ChangeMeta {
+  origin: ChangeOrigin;
+}
+
+/** `comment:status-changed` — both ends of the move along the lifecycle. */
+export interface StatusChangeMeta extends ChangeMeta {
+  from: CommentStatus;
+  to: CommentStatus;
+}
+
+/**
+ * `comment:updated` — which of the three fields moved, and both ends of the
+ * move. Discriminated on `field`, so narrowing gives you correctly typed
+ * `from`/`to` for each.
+ */
+export type UpdateMeta = ChangeMeta &
+  (
+    | { field: "type"; from: CommentType | null; to: CommentType | null }
+    | {
+        field: "priority";
+        from: CommentPriority | null;
+        to: CommentPriority | null;
+      }
+    | { field: "tags"; from: string[]; to: string[] }
+  );
+
 /**
  * Everything that can change, as one discriminated union. Switch on `type`
  * and TypeScript narrows the rest of the fields for you.
  *
  * The ten specific callbacks below carry exactly the same events at
- * exactly the same moments; subscribe either way, or both.
+ * exactly the same moments, with the same metadata; subscribe either way,
+ * or both.
  */
 export type ChangeEvent =
-  | { type: "comment:created"; comment: SerializedComment }
-  | { type: "comment:edited"; comment: SerializedComment }
-  | { type: "comment:deleted"; id: CommentId }
-  | { type: "comment:status-changed"; comment: SerializedComment }
-  /** Type, priority or tags changed. */
-  | { type: "comment:updated"; comment: SerializedComment }
-  | { type: "comment:anchor-lost"; comment: SerializedComment }
-  | {
+  | ({ type: "comment:created"; comment: SerializedComment } & ChangeMeta)
+  | ({ type: "comment:edited"; comment: SerializedComment } & ChangeMeta)
+  | ({ type: "comment:deleted"; id: CommentId } & ChangeMeta)
+  | ({
+      type: "comment:status-changed";
+      comment: SerializedComment;
+    } & StatusChangeMeta)
+  /** Type, priority or tags changed; `field` says which. */
+  | ({ type: "comment:updated"; comment: SerializedComment } & UpdateMeta)
+  | ({ type: "comment:anchor-lost"; comment: SerializedComment } & ChangeMeta)
+  | ({
       type: "reply:added";
       comment: SerializedComment;
       reply: CommentReply;
-    }
-  | {
+    } & ChangeMeta)
+  | ({
       type: "reply:deleted";
       comment: SerializedComment;
       reply: CommentReply;
-    }
-  | {
+    } & ChangeMeta)
+  | ({
       type: "reply:edited";
       comment: SerializedComment;
       reply: CommentReply;
-    }
+    } & ChangeMeta)
   /** `reply` is null when the reaction is on the root comment. */
-  | {
+  | ({
       type: "reaction:toggled";
       comment: SerializedComment;
       reply: CommentReply | null;
-    };
+    } & ChangeMeta);
 
 export interface CommentOverlayOptions {
   shortcutKey?: string;
@@ -293,39 +355,155 @@ export interface CommentOverlayOptions {
    * `notifyNavigation()` call from the router's hook. Default: false.
    */
   autoDetectNavigation?: boolean;
+  /**
+   * Called once the widget has mounted and every method on it is safe to
+   * drive. Receives the instance, because when the document is already
+   * parsed the mount happens inside the constructor — before
+   * `createCommentOverlay()` has returned anything to assign.
+   *
+   * This is the right place to `loadComments()`: a call made earlier is held
+   * and replayed here, but it can only return zeroes until then.
+   */
+  onReady?: (overlay: CommentOverlay) => void;
+  /**
+   * Called when something the widget survived nonetheless went wrong: a
+   * screenshot that failed to render, a localStorage write that could not be
+   * made, a malformed record skipped on load, a rejected
+   * `onCommentRequested`. Each of these already warns on the console and the
+   * widget carries on regardless — this is how they reach the host's own
+   * logging instead of only a devtools panel nobody has open.
+   */
+  onError?: (error: unknown, context: ErrorContext) => void;
+  /**
+   * Called when a "Copy link" URL points at a comment the widget does not
+   * hold — once per id, not once per attempt.
+   *
+   * This is what makes lazy loading work: fetch that one comment and hand it
+   * to `loadComments()`, and the inbox opens on it. Return a promise and the
+   * link is retried once it settles. Without a handler the inbox still opens
+   * and says the comment was not found.
+   */
+  onCommentRequested?: (id: CommentId) => void | Promise<unknown>;
+  /**
+   * Called for every image the widget acquires — the automatic viewport
+   * capture, a drag-crop region, and anything attached through the file
+   * picker. Return the string to store in its place, typically a URL into
+   * your own object storage.
+   *
+   * Without it, a ~33KB base64 data URL travels inside every comment: into
+   * localStorage, where it is the first thing shed under quota pressure, and
+   * into whatever your backend persists.
+   *
+   * Everything on a comment is transformed as the comment is saved; an
+   * attachment on a *reply* is transformed when the file is picked, because
+   * `addReply()` is synchronous. Either way the record may never arrive —
+   * an abandoned reply draft, or a comment box dismissed while its upload is
+   * in flight — so treat a URL you hand back as an upload, not as a record,
+   * and sweep for unreferenced blobs.
+   *
+   * `kind` separates the automatic capture ("context" — disposable and
+   * regenerable) from something a person chose to include ("attachment"), so
+   * the two can go to different buckets with different retention. It does
+   * not distinguish the two moments above: both arrive as "attachment".
+   * `commentId` is the comment the image will belong to — for an attachment
+   * on a reply, the parent comment.
+   *
+   * Fail-open: a rejection, a throw, or a resolved value that is not a
+   * non-empty string leaves the original data URL in place and reports
+   * `onError(error, "transform")`. Losing the user's comment would be worse
+   * than sending you a large one.
+   *
+   * Not called for records passed to `loadComments()`, nor for screenshots
+   * you hand to `addReply()` yourself — in both cases the strings are
+   * already yours.
+   */
+  transformScreenshot?: (
+    dataUrl: string,
+    info: { kind: "context" | "attachment"; commentId: CommentId }
+  ) => Promise<string>;
+  /**
+   * Called whenever comment mode turns on or off, however it was flipped —
+   * the toolbar button, the keyboard shortcut, the inbox empty state, or the
+   * automatic switch-off after a comment is saved.
+   *
+   * The shortcut is the reason this exists: the host never sees that
+   * keystroke, so an app that needs to stand down while the user is picking
+   * an element — pause a carousel, disable its own drag-and-drop, dim a
+   * layer — has no other way to know.
+   */
+  onCommentModeChanged?: (active: boolean) => void;
+  /**
+   * Called when somebody opens a comment's full thread, from its marker or
+   * from the inbox detail — the only two places the replies are readable.
+   *
+   * This is what an unread count is built on. HellDots keeps no read state
+   * of its own: whose "read" it is depends on an identity only the host can
+   * persist.
+   */
+  onCommentOpened?: (comment: SerializedComment) => void;
   /**
    * Single subscription point: fires for every change, alongside whichever
    * specific callback below carries the same event. Handy when a host syncs
    * everything to one endpoint instead of wiring nine functions. A handler
    * that throws is caught and warned about — it never rolls back the
    * mutation that emitted it.
+   *
+   * The event carries `origin` (and, where there is one, the transition that
+   * caused it) flattened onto it — see `ChangeMeta`.
    */
   onChange?: (event: ChangeEvent) => void;
   /** Fired after a new comment is saved. */
-  onCommentCreated?: (comment: SerializedComment) => void;
+  onCommentCreated?: (comment: SerializedComment, meta: ChangeMeta) => void;
   /** Fired after a reply is added to any comment. */
-  onReplyAdded?: (comment: SerializedComment, reply: CommentReply) => void;
+  onReplyAdded?: (
+    comment: SerializedComment,
+    reply: CommentReply,
+    meta: ChangeMeta
+  ) => void;
   /** Fired after deleteReply removes a reply. */
-  onReplyDeleted?: (comment: SerializedComment, reply: CommentReply) => void;
+  onReplyDeleted?: (
+    comment: SerializedComment,
+    reply: CommentReply,
+    meta: ChangeMeta
+  ) => void;
   /** Fired after editComment rewrites a comment's text. */
-  onCommentEdited?: (comment: SerializedComment) => void;
+  onCommentEdited?: (comment: SerializedComment, meta: ChangeMeta) => void;
   /** Fired after editReply rewrites a reply's text. */
-  onReplyEdited?: (comment: SerializedComment, reply: CommentReply) => void;
-  /** Fired for each comment that could not be re-anchored by loadComments. */
-  onAnchorLost?: (comment: SerializedComment) => void;
+  onReplyEdited?: (
+    comment: SerializedComment,
+    reply: CommentReply,
+    meta: ChangeMeta
+  ) => void;
+  /**
+   * Fired for each comment that could not be re-anchored — by loadComments,
+   * and again by every notifyNavigation that lands somewhere its element
+   * does not exist. Those repeats always carry `origin: "host"`.
+   */
+  onAnchorLost?: (comment: SerializedComment, meta: ChangeMeta) => void;
   /** Fired after deleteComment removes a comment. */
-  onCommentDeleted?: (id: CommentId) => void;
-  /** Fired after setCommentStatus changes a comment's lifecycle state. */
-  onCommentStatusChanged?: (comment: SerializedComment) => void;
-  /** Fired after type, priority or tags change on any comment. */
-  onCommentUpdated?: (comment: SerializedComment) => void;
+  onCommentDeleted?: (id: CommentId, meta: ChangeMeta) => void;
+  /**
+   * Fired after setCommentStatus changes a comment's lifecycle state.
+   * `meta.from`/`meta.to` are both ends of the move, so "reopened" and
+   * "resolved" are told apart without diffing against a previous copy.
+   */
+  onCommentStatusChanged?: (
+    comment: SerializedComment,
+    meta: StatusChangeMeta
+  ) => void;
+  /**
+   * Fired after type, priority or tags change on any comment. `meta.field`
+   * says which one moved, and narrows `meta.from`/`meta.to` with it.
+   */
+  onCommentUpdated?: (comment: SerializedComment, meta: UpdateMeta) => void;
   /**
    * Fired after a reaction is added to or removed from a comment or a reply.
    * `reply` is null when the reaction is on the root comment.
    */
   onReactionToggled?: (
     comment: SerializedComment,
-    reply: CommentReply | null
+    reply: CommentReply | null,
+    meta: ChangeMeta
   ) => void;
 }
 
@@ -451,6 +629,12 @@ export declare class CommentOverlay {
   /** The shareable URL for a comment, or null when the id is unknown. */
   commentLink(id: CommentId): string | null;
   serializeComments(): SerializedComment[];
+  /**
+   * Called before the widget has mounted — possible when a fetch resolves
+   * while the document is still parsing — the data is held and applied at
+   * mount, and the counts come back as zeroes because nothing has been
+   * resolved yet. Load from `onReady` when the counts matter.
+   */
   loadComments(data: SerializedComment[]): {
     anchored: number;
     orphaned: number;
@@ -481,21 +665,40 @@ export declare class CommentOverlay {
    */
   getMetrics(): CommentMetrics;
   /**
-   * Downloads the corpus as CSV, one row per comment. Screenshots and the
-   * automatic context capture stay out. Defaults to every comment.
+   * Downloads the corpus as CSV, one row per comment, and returns the same
+   * text. Screenshots and the automatic context capture stay out. Defaults
+   * to every comment.
+   *
+   * The return value is for a host that wanted to POST those rows somewhere
+   * or attach them to a message: a browser download is a dead end, and
+   * building the CSV a second time is the only alternative.
    */
-  exportCommentsCsv(comments?: SerializedComment[]): void;
+  exportCommentsCsv(comments?: SerializedComment[]): string;
   /**
    * Downloads the aggregate figures as CSV in long format — `section, key,
-   * value` — so the column count does not change with the corpus.
+   * value` — so the column count does not change with the corpus. Returns
+   * the same text, for the same reason as above.
    */
-  exportMetricsCsv(comments?: SerializedComment[]): void;
+  exportMetricsCsv(comments?: SerializedComment[]): string;
   /**
    * Opens the browser's print dialog on a report of the figures, which is
    * where "save as PDF" lives. The report is built in its own document, so
    * what prints is the report rather than the host page.
    */
   printMetricsReport(comments?: SerializedComment[], scope?: string): void;
+  /**
+   * Replaces the identity new comments, replies and reactions are attributed
+   * to. Everything already recorded keeps the author it was written with.
+   *
+   * For the common case where identity resolves after the widget mounts, or
+   * where the user switches account or workspace — the alternative was
+   * `cleanup()` and a rebuild, which throws away every loaded comment and
+   * whatever panel was open. `null` returns to the anonymous author.
+   *
+   * Returns false, changing nothing, for anything that is neither null nor
+   * an object with a non-blank `name`.
+   */
+  setUser(user: { name: string; id?: string } | null): boolean;
   setCommentStatus(id: CommentId, status: CommentStatus): boolean;
   setCommentType(id: CommentId, type: CommentType | null): boolean;
   setCommentPriority(id: CommentId, priority: CommentPriority | null): boolean;
@@ -530,4 +733,22 @@ export declare function createCommentOverlay(
   options: CommentOverlayOptions & { autoInit: false }
 ): () => CommentOverlay;
 
+/**
+ * Default name of the query parameter carrying a comment id in "Copy link"
+ * URLs. Exported so a host reading the id itself — before the widget is up,
+ * to fetch just that comment — does not have to hardcode a second copy of
+ * it. Override it per instance with the `linkParam` option.
+ */
+export declare const DEFAULT_LINK_PARAM: string;
+
+/**
+ * The comment id the given URL asks for, or null. Pass the same `param` the
+ * widget was configured with; both default to `DEFAULT_LINK_PARAM`. A
+ * malformed URL yields null rather than throwing.
+ */
+export declare function readCommentLinkParam(
+  param?: string,
+  href?: string
+): string | null;
+
 export default createCommentOverlay;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helldots",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Drop-in comment overlay for web apps — click anywhere to leave a comment anchored to that element, with an automatic screenshot and environment capture",
   "keywords": [
     "comments",