@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/static/js/code-folds.js

@@ -1,10 +1,45 @@
 // @ts-check
 // Rows a reviewer can hide: the canvas folds the model named, and the folds the diff renderer
 // marked (import-only and whitespace-only changes, and moved blocks). Both open again when a
-// deep link lands inside them.
+// deep link lands inside them. Every model fold is wired once, when the diff is drawn; the
+// reader's level only decides which of them are active, so changing it never rebuilds the table
+// and an open composer or an expanded fold survives. The renderer's own folds hide in every mode.
 import { findRow } from './anchors.js'
+import { foldsForLevel } from './fold-levels.js'
 
 /** @typedef {import('./contract-types.js').CodeFold} CodeFold */
+/** @typedef {import('./contract-types.js').FoldLevel} FoldLevel */
+
+/** Rows that keep their code open at every level. */
+const PINNED = '[data-decoration="point"], [data-decoration="thread"]'
+/** Annotation band rows and the note row under them; only an aggressive fold may hide these. */
+const ANNOTATED = '.ann, [data-decoration="note"]'
+
+/**
+ * One model fold on a drawn table. `rows` are fixed when the diff is drawn; `hiddenBefore` is how
+ * each row looked before any fold touched it, so a fold the level turns off gives it back.
+ * @typedef {{
+ *   fold: CodeFold,
+ *   rows: HTMLTableRowElement[],
+ *   hiddenBefore: boolean[],
+ *   summaries: Set<HTMLTableRowElement>,
+ *   header: HTMLTableRowElement,
+ *   toggle: HTMLButtonElement,
+ *   active: boolean,
+ *   expanded: boolean,
+ * }} WiredFold
+ */
+
+/** The folds wired on each drawn diff. A redraw builds a new diff, so it starts a new list. */
+const wiredFolds = /** @type {WeakMap<Element, WiredFold[]>} */ (new WeakMap())
+
+/**
+ * The drawn diff of a card, one table per hunk, or null before it draws.
+ * @param {HTMLElement} card
+ */
+function drawnDiff(card) {
+  return card.querySelector('.diff-wrap')
+}
 
 /**
  * @param {Element | null} summary
@@ -27,7 +62,8 @@ function coveredFoldSummary(summary, rows) {
 }
 
 /**
- * Finds the rows between both anchors. A decorated or overlapping range stays open.
+ * Finds the rows between both anchors. A range holding an attention point or a discussion stays
+ * open at every level; a range holding an annotation stays open unless the fold is aggressive.
  * @param {HTMLElement} card
  * @param {string} key
  * @param {CodeFold} fold
@@ -47,18 +83,30 @@ function foldRows(card, key, fold) {
 
   const siblings = Array.from(first.parentElement.children)
   const from = siblings.indexOf(first)
-  const to = siblings.indexOf(last)
+  let to = siblings.indexOf(last)
 
   if (to < from) {
     return []
   }
 
-  const rows = siblings.slice(from, to + 1).filter(row => row instanceof HTMLTableRowElement)
-  const hasDiscussion = rows.some(row => row.matches('.ann, [data-decoration], [data-code-fold], .code-fold'))
+  const aggressive = fold.level === 'aggressive'
 
-  const hasThread = Boolean(first.closest('table')?.querySelector('[data-decoration="thread"]'))
+  // An annotation's note row sits under the last line it covers, so an aggressive fold that ends
+  // on that line takes the note with it rather than leaving it stranded above open code.
+  if (aggressive) {
+    while (siblings[to + 1]?.matches('[data-decoration="note"]') === true) {
+      to++
+    }
+  }
 
-  if (hasDiscussion || hasThread || last.nextElementSibling?.matches('[data-decoration]')) {
+  const rows = siblings.slice(from, to + 1).filter(row => row instanceof HTMLTableRowElement)
+  const trailing = siblings[to + 1]
+  const blocked =
+    rows.some(row => row.matches(PINNED)) ||
+    (!aggressive && rows.some(row => row.matches(ANNOTATED))) ||
+    trailing?.matches(aggressive ? PINNED : '[data-decoration]') === true
+
+  if (blocked) {
     return []
   }
 
@@ -70,6 +118,20 @@ function foldRows(card, key, fold) {
   return rows
 }
 
+/**
+ * What the toggle says. An aggressive fold that hides an annotation shows the annotation instead
+ * of its own title, so the reader still reads the explanation of the code it replaces. The
+ * validator lets such a fold cover one whole annotation at most, so there is one note to show.
+ * @param {readonly HTMLTableRowElement[]} rows
+ * @param {CodeFold} fold
+ * @returns {string}
+ */
+function foldLabel(rows, fold) {
+  const note = rows.find(row => row.matches('[data-decoration="note"]'))
+  const text = note?.querySelector('.prose')?.textContent?.trim()
+  return text === undefined || text === '' ? fold.title : text
+}
+
 /**
  * Inserts the fold's title above its first row.
  * @param {HTMLTableRowElement} first
@@ -91,63 +153,128 @@ function createToggle(first, title) {
   header.appendChild(cell)
   first.before(header)
 
-  return toggle
+  return { header, toggle }
 }
 
 /**
- * Keeps the original rows in the DOM so comments and deep links retain their anchors.
- * @param {HTMLTableRowElement} first
- * @param {HTMLTableRowElement[]} rows
- * @param {string} title
+ * Draws one fold as the level and the reader left it. An inactive fold gives its rows back as
+ * they were; an active one hides them behind its title until the reader expands it.
+ * @param {WiredFold} wired
  */
-function wireFold(first, rows, title) {
-  const toggle = createToggle(first, title)
-  const table = first.closest('table')
-  const foldSummaries = new Set(rows.filter(row => coveredFoldSummary(row, rows)))
-  toggle.setAttribute(
-    'aria-controls',
-    rows
-      .map(row => row.id)
-      .filter(Boolean)
-      .join(' ')
-  )
-
-  const setExpanded = (/** @type {boolean} */ expanded) => {
-    toggle.setAttribute('aria-expanded', String(expanded))
-
-    for (const row of rows) {
-      row.hidden = !expanded || foldSummaries.has(row)
+function paintFold(wired) {
+  wired.header.hidden = !wired.active
+  wired.toggle.setAttribute('aria-expanded', String(wired.active && wired.expanded))
+  for (const [index, row] of wired.rows.entries()) {
+    if (wired.active) {
+      row.hidden = !wired.expanded || wired.summaries.has(row)
       row.setAttribute('data-code-fold', '')
+    } else {
+      row.hidden = wired.hiddenBefore[index] === true
+      row.removeAttribute('data-code-fold')
     }
   }
+}
 
-  toggle.addEventListener('click', () => setExpanded(toggle.getAttribute('aria-expanded') !== 'true'))
+/**
+ * Points a drawn card's folds at a level: the outermost folds that hide at it become active and
+ * start folded, and the rest give their rows back. A fold that stays active keeps whatever the
+ * reader did with it. A card with a thread or a pending draft keeps all of its code open, so none
+ * is active. Inactive
+ * folds paint first, so a row shared with an active outer or inner fold ends up as the active
+ * one says.
+ * @param {HTMLElement} card
+ * @param {FoldLevel} level
+ * @param {boolean} discussed whether a thread or a pending draft sits in the card's chunks
+ */
+export function setCodeFoldLevel(card, level, discussed) {
+  const diff = drawnDiff(card)
+  const wired = diff === null ? [] : (wiredFolds.get(diff) ?? [])
+  const active = new Set(
+    discussed
+      ? []
+      : foldsForLevel(
+          wired.map(w => w.fold),
+          level
+        )
+  )
 
-  table?.addEventListener('reveal-code', event => {
-    const target = event.target
-    if (target instanceof Node && (target === table || rows.some(row => row.contains(target)))) {
-      setExpanded(true)
+  for (const w of wired) {
+    const now = active.has(w.fold)
+    if (now && !w.active) {
+      w.expanded = false
     }
-  })
-
-  setExpanded(false)
+    w.active = now
+  }
+  const inactive = wired.filter(w => !w.active)
+  for (const w of [...inactive, ...wired.filter(fold => fold.active)]) {
+    paintFold(w)
+  }
 }
 
 /**
- * Adds title-only folds; ranges with annotations, attention points, or discussions stay open.
+ * Wires every model fold of a freshly drawn diff, then applies the reader's level. The rows of
+ * every fold are found before any title row goes in, so nested folds each see only diff rows.
+ * Ranges with attention points stay open, and so do ranges with annotations unless the fold is
+ * aggressive. A second call on the same diff does nothing.
  * @param {HTMLElement} card
  * @param {string} key
  * @param {readonly CodeFold[]} folds
+ * @param {FoldLevel} level the reader's level
+ * @param {boolean} discussed whether a thread or a pending draft sits in the card's chunks
  */
-export function applyCodeFolds(card, key, folds) {
-  for (const fold of folds) {
-    const rows = foldRows(card, key, fold)
-    const first = rows[0]
+export function applyCodeFolds(card, key, folds, level, discussed) {
+  const diff = drawnDiff(card)
+  if (diff === null || wiredFolds.has(diff)) {
+    return
+  }
 
-    if (first !== undefined) {
-      wireFold(first, rows, fold.title)
+  const found = folds.map(fold => ({ fold, rows: foldRows(card, key, fold) }))
+  /** @type {WiredFold[]} */
+  const wired = []
+  for (const { fold, rows } of found) {
+    const first = rows[0]
+    if (first === undefined) {
+      continue
     }
+    const { header, toggle } = createToggle(first, foldLabel(rows, fold))
+    toggle.setAttribute(
+      'aria-controls',
+      rows
+        .map(row => row.id)
+        .filter(Boolean)
+        .join(' ')
+    )
+    const w = {
+      fold,
+      rows,
+      hiddenBefore: rows.map(row => row.hidden),
+      summaries: new Set(rows.filter(row => coveredFoldSummary(row, rows))),
+      header,
+      toggle,
+      active: false,
+      expanded: false,
+    }
+    toggle.addEventListener('click', () => {
+      w.expanded = !w.expanded
+      paintFold(w)
+    })
+    const table = first.closest('table')
+    table?.addEventListener('reveal-code', event => {
+      const target = event.target
+      if (
+        w.active &&
+        target instanceof Node &&
+        (target === table || rows.some(row => row.contains(target)))
+      ) {
+        w.expanded = true
+        paintFold(w)
+      }
+    })
+    wired.push(w)
   }
+
+  wiredFolds.set(diff, wired)
+  setCodeFoldLevel(card, level, discussed)
 }
 
 /**

package/static/js/composer.js

@@ -20,6 +20,8 @@ import { noPostingTitle, postToLabel } from './host.js'
  *   inReplyToId?: number,
  *   pointFingerprint?: string,
  *   body?: string,
+ *   pendingActive?: boolean,
+ *   pendingId?: string,
  * }} ComposerOptions
  */
 
@@ -33,6 +35,8 @@ function dataAttributes(opts) {
     ['data-start-line', opts.startLine],
     ['data-in-reply-to', opts.inReplyToId],
     ['data-fingerprint', opts.pointFingerprint],
+    ['data-pending-id', opts.pendingId],
+    ['data-pending-active', opts.pendingActive === true ? '1' : '0'],
   ]
   return pairs
     .filter(([, value]) => value !== undefined)
@@ -41,7 +45,57 @@ function dataAttributes(opts) {
 }
 
 /**
- * The box itself. The textarea carries the draft; the two commands act on the nearest
+ * The commands under the box, which are the ones the forge's own page offers.
+ *
+ * With no review open, a comment on a diff line can go either way: into a review it starts, or
+ * straight out on its own. Once a review is open it can only join it. Posting one comment on its
+ * own would publish it while the rest of the review is still held back, so that way is closed for
+ * as long as something is waiting, and the drafts are submitted together.
+ *
+ * A draft being edited has neither: it is already in the review, so it is only saved.
+ * @param {ComposerOptions} opts
+ */
+function commandsHtml(opts) {
+  const cancel = '<button class="cmd" type="button" data-act="composer-cancel">cancel</button>'
+  if (opts.pendingId !== undefined) {
+    return `<button class="cmd fill" type="button" data-act="pending-save">save</button>${cancel}`
+  }
+  const post = (lead = false) =>
+    `<button class="cmd${lead ? ' fill' : ''}" type="button" data-act="composer-post" data-needs-post>${postToLabel()}</button>`
+  if (opts.kind !== 'inline') {
+    return `${post(true)}${cancel}`
+  }
+  if (opts.pendingActive === true) {
+    return `<button class="cmd fill" type="button" data-act="composer-queue">add review comment</button>${cancel}`
+  }
+  return (
+    `<button class="cmd fill" type="button" data-act="composer-queue">start a review</button>` +
+    post() +
+    cancel
+  )
+}
+
+/** Keep an open inline composer's commands in step when another action starts a review.
+ * @param {ParentNode} root
+ * @param {boolean} active
+ */
+export function refreshComposerCommands(root, active) {
+  for (const box of root.querySelectorAll('.composer-box[data-kind="inline"]')) {
+    if (
+      box.hasAttribute('data-pending-id') ||
+      box.hasAttribute('data-posting') ||
+      (box.getAttribute('data-pending-active') === '1') === active
+    )
+      continue
+    const actions = box.querySelector('.composer-actions')
+    if (actions !== null)
+      actions.innerHTML = commandsHtml({ id: box.id, label: '', kind: 'inline', pendingActive: active })
+    box.setAttribute('data-pending-active', active ? '1' : '0')
+  }
+}
+
+/**
+ * The box itself. The textarea carries the draft; the commands act on the nearest
  * `.composer-box` ancestor.
  * @param {ComposerOptions} opts
  */
@@ -51,8 +105,7 @@ export function composerHtml(opts) {
     `<label class="sr" for="${esc(opts.id)}-t">${esc(opts.label)}</label>` +
     previewControlsHtml() +
     `<textarea id="${esc(opts.id)}-t" rows="3" placeholder="${esc(opts.label)}">${esc(opts.body ?? '')}</textarea>` +
-    `<div class="composer-actions"><button class="cmd fill" type="button" data-act="composer-post" data-needs-post>${postToLabel()}</button>` +
-    '<button class="cmd" type="button" data-act="composer-cancel">cancel</button></div></div>'
+    `<div class="composer-actions">${commandsHtml(opts)}</div></div>`
   )
 }
 
@@ -81,6 +134,24 @@ export function composerBody(box) {
   return textarea instanceof HTMLTextAreaElement ? textarea.value.trim() : ''
 }
 
+/**
+ * What this composer would add to the pending review, or null when it is empty or is not a
+ * comment on a diff line. Only inline comments can wait: a reply and a PR-level comment have
+ * no place in a forge review's comment list.
+ * @param {Element} box
+ * @returns {Omit<import('./contract-types.js').AddPendingInput, 'headSha'> | null}
+ */
+export function composerPendingInput(box) {
+  const input = composerInput(box)
+  return input === null || input.kind !== 'inline' ? null : stripKind(input)
+}
+
+/** @param {Extract<PostCommentInput, { kind: 'inline' }>} input */
+function stripKind(input) {
+  const { kind: _kind, ...rest } = input
+  return rest
+}
+
 /**
  * The request that posts what this composer holds.
  * @param {Element} box
@@ -131,8 +202,41 @@ export function focusComposer(root, id) {
   return textarea
 }
 
+/** What a composer stands in for is marked with this while the box is open. */
+const CONCEALED = 'data-composer-concealed'
+
+/** The parts of a concealed host that the box stands in for. */
+const CONCEALED_PARTS = ':scope > .prose, :scope > .tbtns'
+
+/**
+ * Hides what a composer edits while the box is open, so the reader sees one of the two rather
+ * than the draft and its editor at once. The mark is what lets any close put it back.
+ * @param {Element} host the element the composer was appended to
+ */
+export function concealForComposer(host) {
+  host.setAttribute(CONCEALED, '')
+  for (const part of Array.from(host.querySelectorAll(CONCEALED_PARTS))) {
+    part.setAttribute('hidden', '')
+  }
+}
+
+/**
+ * Puts back everything a composer was concealing. Closing is the only way a box goes away, so
+ * doing this here covers cancel, Escape, and opening another box alike.
+ * @param {ParentNode} root
+ */
+export function revealConcealed(root) {
+  for (const host of Array.from(root.querySelectorAll(`[${CONCEALED}]`))) {
+    host.removeAttribute(CONCEALED)
+    for (const part of Array.from(host.querySelectorAll(CONCEALED_PARTS))) {
+      part.removeAttribute('hidden')
+    }
+  }
+}
+
 /**
- * Removes every open composer under `root`, so only one is open at a time.
+ * Removes every open composer under `root`, so only one is open at a time, and reveals whatever
+ * they were standing in for.
  * @param {ParentNode} root
  */
 export function closeComposers(root) {
@@ -142,6 +246,7 @@ export function closeComposers(root) {
     ;(row ?? box).remove()
     closed++
   }
+  revealConcealed(root)
   return closed
 }
 

package/static/js/contract-types.d.ts

@@ -13,6 +13,7 @@ export type {
   PrBundle,
   PublicHost,
   ReviewBodyResponse,
+  ReviewBootstrap,
   ReviewSummary,
   SharedCanvasFetchResponse,
   SharedCanvasInfo,
@@ -37,6 +38,7 @@ export type {
   CodeFold,
   Diagram,
   FileEntry,
+  FoldLevel,
   Hunk,
   Layer,
   LayerFile,
@@ -60,3 +62,5 @@ export type {
   Theme,
 } from '../../src/contract/settings.js'
 export type { PrState } from '../../src/contract/state.js'
+export type { AddPendingInput, PendingComment } from '../../src/contract/pending.js'
+export type { ReviewEvent } from '../../src/contract/reviews.js'

package/static/js/diff-decorations.js

@@ -9,6 +9,7 @@ import { findRow, nearestRow } from './anchors.js'
 import { viewCommentHtml } from './comment-link.js'
 import { esc, fragment, avatarHtml, timeAgo } from './dom.js'
 import { renderMarkdown } from './markdown.js'
+import { pendingRowHtml } from './pending.js'
 import { pointRowHtml } from './points.js'
 
 const DECORATION = 'data-decoration'
@@ -146,6 +147,66 @@ export function insertThreadRow(card, key, t, opts) {
   return true
 }
 
+/**
+ * The drafts of one file, drawn under the lines they comment on. A draft whose line is not on the
+ * page (a fold, or a file drawn short) goes under the nearest row, like every other decoration.
+ * @param {HTMLElement} card
+ * @param {string} key
+ * @param {ReadonlyArray<import('./contract-types.js').PendingComment>} drafts
+ * @param {Date} now
+ * @returns {{ placed: number, missed: number }}
+ */
+export function insertPendingRows(card, key, drafts, now) {
+  let placed = 0
+  let missed = 0
+  for (const draft of drafts) {
+    const near = nearestRow(card, key, draft.side, draft.line)
+    if (near === null) {
+      missed++
+      continue
+    }
+    const row = firstRow(pendingRowHtml([draft], now))
+    row.setAttribute(DECORATION, 'pending')
+    row.dataset['pendingId'] = draft.id
+    row.dataset['pendingBody'] = draft.body
+    if (near.approx) row.classList.add('is-approx')
+    let after = near.row
+    while (
+      after.nextElementSibling instanceof HTMLTableRowElement &&
+      after.nextElementSibling.getAttribute(DECORATION) === 'pending'
+    ) {
+      after = after.nextElementSibling
+    }
+    after.insertAdjacentElement('afterend', row)
+    placed++
+  }
+  return { placed, missed }
+}
+
+/** Update draft rows without replacing thread replies, annotations, or active editors.
+ * @param {HTMLElement} card
+ * @param {string} key
+ * @param {ReadonlyArray<import('./contract-types.js').PendingComment>} drafts
+ * @param {Date} now
+ */
+export function refreshPendingRows(card, key, drafts, now) {
+  const remaining = new Map(drafts.map(p => [p.id, p]))
+  for (const row of card.querySelectorAll('tr[data-decoration="pending"]')) {
+    const draft = remaining.get(row.getAttribute('data-pending-id') ?? '')
+    if (draft === undefined) {
+      row.remove()
+      continue
+    }
+    remaining.delete(draft.id)
+    if (row.getAttribute('data-pending-body') !== draft.body) {
+      const prose = row.querySelector('.pending-cmt > .prose')
+      if (prose !== null) prose.innerHTML = renderMarkdown(draft.body, { github: true })
+      row.setAttribute('data-pending-body', draft.body)
+    }
+  }
+  insertPendingRows(card, key, [...remaining.values()], now)
+}
+
 /**
  * @param {string} html
  * @returns {HTMLTableRowElement}
@@ -166,7 +227,7 @@ function firstRow(html) {
  * right after the anchor row, so they are added in reverse).
  * @param {HTMLElement} card
  * @param {string} key
- * @param {{ annotations: ReadonlyArray<Annotation>, points: ReadonlyArray<Point>, threads: ReadonlyArray<Thread>, paths: ReadonlySet<string>, now: Date, state?: import('./contract-types.js').PrState, posted?: ReadonlyMap<string, string>, hiddenThreads?: ReadonlySet<number> }} data
+ * @param {{ annotations: ReadonlyArray<Annotation>, points: ReadonlyArray<Point>, threads: ReadonlyArray<Thread>, pending?: ReadonlyArray<import('./contract-types.js').PendingComment>, paths: ReadonlySet<string>, now: Date, state?: import('./contract-types.js').PrState, posted?: ReadonlyMap<string, string>, hiddenThreads?: ReadonlySet<number> }} data
  * @returns {{ placed: number, missed: number }}
  */
 export function applyDecorations(card, key, data) {
@@ -185,6 +246,11 @@ export function applyDecorations(card, key, data) {
       missed++
     }
   }
+  // Drafts are added before the threads, so under one line they end up after them: the comment
+  // that is already on the forge reads first, the one still being written reads last.
+  const drafts = insertPendingRows(card, key, data.pending ?? [], data.now)
+  placed += drafts.placed
+  missed += drafts.missed
   for (const t of [...data.threads].reverse()) {
     count(
       insertThreadRow(card, key, t, { now: data.now, hidden: data.hiddenThreads?.has(t.root.id) ?? false })

package/static/js/empty-state.js

@@ -208,6 +208,23 @@ export function carriedOverBarHtml(carried) {
   )
 }
 
+/**
+ * The note above a canvas that some of the reviewer's progress followed onto. Without it, the
+ * already-ticked layers look like a bug. The sha is the canvas the marks were made on, which may
+ * be several generations back when the reviewer marked nothing on the canvases in between.
+ * @param {string} markedCanvasSha
+ * @returns {string}
+ */
+export function marksCarriedBarHtml(markedCanvasSha) {
+  return (
+    '<div class="stale-bar carried-over-bar" role="status"><strong>Review progress carried over.</strong> ' +
+    esc(
+      `You marked these on the canvas of ${markedCanvasSha.slice(0, 7)}; a file whose diff has not changed since keeps its mark, and a layer keeps its own when it still holds exactly those files.`
+    ) +
+    '</div>'
+  )
+}
+
 /**
  * The `stale` screen: the same card as the empty state, plus the two ways forward.
  * @param {PrBundle} bundle