Skip to content

AI-native design editor. Open-source Figma alternative.

6.3 KB
Raw Blame
import type { CommentThread, SceneGraph } from '@open-pencil/scene-graph'
import {
  byCreatedAt,
  commentPosition,
  commentTimestamp as now,
  createCommentReply,
  createCommentThread,
  deleteCommentThread,
  editCommentThread,
  findLiveCommentThread,
  liveReplies,
  readComments,
  replyToCommentThread,
  resolveCommentThread,
  takesPartInThread,
  writeComments,
  type CommentAuthor
} from '@open-pencil/scene-graph/comments'
import type { Vector } from '@open-pencil/scene-graph/primitives'

import { nodeOf, type NodeRef } from './behaviours'

/** Who scripts and agents comment as when they give no name. */
export const DEFAULT_COMMENT_AUTHOR = 'Agent'

export interface CommentFilter {
  /** true for resolved threads only, false for open ones; both when left out. */
  resolved?: boolean
  /** Only threads on this page. */
  page?: NodeRef
  /** Only threads this person started or replied to. */
  author?: string
}

export interface NewComment {
  /** Pin the comment on this layer; it follows the top-level layer it lands on. */
  node?: NodeRef
  /** The page to comment on without a layer; the current page by default. */
  page?: NodeRef
  /** Canvas position on the page, or offset from the layer's top-left corner. */
  x?: number
  y?: number
  author?: string
}

function author(name: string | undefined): CommentAuthor {
  return { name: name?.trim() || DEFAULT_COMMENT_AUTHOR }
}

function pageOf(graph: SceneGraph, nodeId: string): string {
  const page = graph.pageOf(nodeId)
  if (page === null) throw new Error(`${graph.getNode(nodeId)?.name ?? nodeId} is not on a page`)
  return page
}

/**
 * A comment thread as scripts read and answer it, in the style of the Figma API: properties
 * read the thread as the document holds it now, and every change is written at once, where
 * the editor and collaborators see it.
 */
export class CommentHandle {
  constructor(
    private readonly graph: SceneGraph,
    readonly id: string
  ) {}

  private get thread(): CommentThread {
    const thread = findLiveCommentThread(readComments(this.graph), this.id)
    if (!thread) throw new Error(`Comment ${this.id} was deleted`)
    return thread
  }

  private edit(change: (thread: CommentThread) => CommentThread): this {
    const threads = readComments(this.graph)
    if (!findLiveCommentThread(threads, this.id)) throw new Error(`Comment ${this.id} was deleted`)
    writeComments(this.graph, editCommentThread(threads, this.id, now(), change))
    return this
  }

  get text(): string {
    return this.thread.text
  }

  get author(): string {
    return this.thread.author
  }

  get createdAt(): string {
    return this.thread.createdAt
  }

  get resolved(): boolean {
    return this.thread.resolved
  }

  /** The page the comment is on. */
  get page(): { id: string; name: string } {
    const { pageId, pageName } = this.thread
    return { id: pageId, name: this.graph.getNode(pageId)?.name ?? pageName ?? '' }
  }

  /** The top-level layer the comment is pinned to, while it exists. */
  get node(): { id: string; name: string } | null {
    const { nodeId } = this.thread
    const node = nodeId ? this.graph.getNode(nodeId) : undefined
    return node ? { id: node.id, name: node.name } : null
  }

  /** Where the pin is on the page's canvas. */
  get position(): Vector {
    return commentPosition(this.graph, this.thread)
  }

  get replies(): { id: string; author: string; text: string; createdAt: string }[] {
    return liveReplies(this.thread).map(({ id, author, text, createdAt }) => ({
      id,
      author,
      text,
      createdAt
    }))
  }

  /** Answer the thread, which reopens it if it was resolved. */
  reply(text: string, options: { author?: string } = {}): this {
    const body = text.trim()
    if (!body) throw new Error('A reply needs text')
    const entry = createCommentReply(author(options.author), body, now())
    return this.edit((thread) => replyToCommentThread(thread, entry))
  }

  resolve(): this {
    return this.edit((thread) => resolveCommentThread(thread, true, now()))
  }

  reopen(): this {
    return this.edit((thread) => resolveCommentThread(thread, false, now()))
  }

  /** Delete the thread and its replies for everyone. */
  remove(): void {
    this.edit(deleteCommentThread)
  }

  toJSON() {
    return {
      id: this.id,
      text: this.text,
      author: this.author,
      createdAt: this.createdAt,
      resolved: this.resolved,
      page: this.page,
      node: this.node,
      position: this.position,
      replies: this.replies
    }
  }
}

/** The document's live threads, oldest first, narrowed by `filter`. */
export function getComments(graph: SceneGraph, filter: CommentFilter = {}): CommentHandle[] {
  const pageId = filter.page === undefined ? undefined : nodeOf(graph, filter.page).id
  return readComments(graph)
    .filter(
      (thread) =>
        !thread.deleted &&
        (filter.resolved === undefined || thread.resolved === filter.resolved) &&
        (pageId === undefined || thread.pageId === pageId) &&
        (filter.author === undefined || takesPartInThread(thread, filter.author))
    )
    .sort(byCreatedAt)
    .map((thread) => new CommentHandle(graph, thread.id))
}

export function getComment(graph: SceneGraph, id: string): CommentHandle | null {
  return findLiveCommentThread(readComments(graph), id) ? new CommentHandle(graph, id) : null
}

/** Leave a comment on a layer, or at a point of a page. */
export function addComment(
  graph: SceneGraph,
  currentPageId: string,
  text: string,
  options: NewComment = {}
): CommentHandle {
  const body = text.trim()
  if (!body) throw new Error('A comment needs text')
  const dx = options.x ?? 0
  const dy = options.y ?? 0
  let pageId: string
  let at: Vector
  const node = options.node === undefined ? undefined : nodeOf(graph, options.node)
  if (node) {
    pageId = pageOf(graph, node.id)
    const abs = graph.getAbsolutePosition(node.id)
    at = { x: abs.x + dx, y: abs.y + dy }
  } else {
    pageId = options.page === undefined ? currentPageId : nodeOf(graph, options.page).id
    if (graph.getNode(pageId)?.type !== 'CANVAS') throw new Error(`${pageId} is not a page`)
    at = { x: dx, y: dy }
  }
  const thread = createCommentThread(graph, {
    pageId,
    at,
    node,
    author: author(options.author),
    text: body,
    now: now()
  })
  writeComments(graph, [...readComments(graph), thread])
  return new CommentHandle(graph, thread.id)
}