@young1lin/dsh-ui-gitworkbench 0.1.5 → 0.1.7

package/src/client/ImageView.tsx

@@ -0,0 +1,120 @@
+/**
+ * The picture, once the host has confirmed the bytes are one.
+ *
+ * Rendering goes through `<img>` pointed at a blob URL, and that choice is
+ * doing two jobs at once.
+ *
+ * It is the SAFETY boundary. The HTML specification defines the document
+ * inside an `<img>` as a non-scripted context: script elements do not run,
+ * event-handler attributes do not fire, external references do not load. That
+ * is what lets an SVG — which is an XML document and can contain all three —
+ * be shown here without a sanitiser standing in front of it. Inlining the same
+ * markup into the page would give up every one of those guarantees, so it is
+ * never done, however convenient it would be for styling.
+ *
+ * It is also the second half of the VERIFICATION. The host's signature check
+ * says the bytes claim to be a PNG; the browser's decoder is the only thing
+ * that can say they really are one. A file that passes the first gate and
+ * fails the second lands on `onError`, and the view says so plainly rather
+ * than leaving an empty frame that reads as a slow load.
+ *
+ * A blob URL rather than a `data:` URI because the DOM then holds a short
+ * string instead of a megabytes-long attribute — and because a blob URL can be
+ * revoked, which is what keeps switching between fifty screenshots from
+ * retaining all fifty.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/ImageView
+ */
+
+import { useEffect, useState, type ReactNode } from 'react'
+
+import css from './GitWorkbenchPanel.module.css'
+import { imageCaption } from './image-view.ts'
+import type { Translate } from './GitWorkbenchPanel.tsx'
+
+/** A verified picture, from wherever its bytes came from: the host's own read
+ *  for a binary file, or the text already in hand for an SVG. */
+export interface Picture {
+  readonly bytes: Uint8Array<ArrayBuffer>
+  /** MIME type to label the blob with. */
+  readonly mime: string
+  /** Short label for the caption — 'PNG', 'SVG'. */
+  readonly kind: string
+}
+
+/** What the browser measured once it had decoded the file. */
+interface Natural {
+  readonly width: number
+  readonly height: number
+}
+
+export function ImageView({ picture, path, t }: {
+  picture: Picture
+  /** Repo-relative path, used as the alt text: a screen reader hearing the
+   *  file's own name is told more than it would be by "image". */
+  path: string
+  t: Translate
+}): ReactNode {
+  const [url, setUrl] = useState<string | null>(null)
+  const [natural, setNatural] = useState<Natural | null>(null)
+  /** The browser refused the bytes the host accepted. */
+  const [broken, setBroken] = useState(false)
+  /** Showing pixel-for-pixel rather than scaled down to fit the pane. */
+  const [actual, setActual] = useState(false)
+
+  const { bytes, mime } = picture
+  useEffect(() => {
+    setNatural(null)
+    setBroken(false)
+    setActual(false)
+    let made: string | null = null
+    try {
+      made = URL.createObjectURL(new Blob([bytes], { type: mime }))
+    } catch {
+      // Nothing to point at, so the frame below says so instead of hanging
+      // on a load event that will never fire.
+      setBroken(true)
+    }
+    setUrl(made)
+    // Revoked on the way out, not merely dropped: an unrevoked blob URL pins
+    // its bytes for the lifetime of the document, so browsing a directory of
+    // screenshots would retain every one of them.
+    return () => { if (made !== null) URL.revokeObjectURL(made) }
+  }, [bytes, mime])
+
+  if (broken || url === null) {
+    return <div className={css.empty}>{t('imageBroken')}</div>
+  }
+  return (
+    <div className={css.imgPane}>
+      <div className={css.imgStage} data-actual={actual ? '' : undefined}>
+        <img
+          className={css.imgShot}
+          src={url}
+          alt={path}
+          onLoad={event => {
+            setNatural({
+              width: event.currentTarget.naturalWidth,
+              height: event.currentTarget.naturalHeight,
+            })
+          }}
+          onError={() => { setBroken(true) }}
+        />
+      </div>
+      <div className={css.imgCaption}>
+        <span>{imageCaption(picture.kind, picture.bytes.length, natural)}</span>
+        {/* Offered only when the two views would differ. A toggle that does
+            nothing visible is a toggle the reader presses twice and then
+            distrusts. */}
+        {natural !== null && natural.width > 0 ? (
+          <button
+            type="button"
+            className={css.blockBtn}
+            aria-pressed={actual}
+            onClick={() => { setActual(on => !on) }}
+          >{t(actual ? 'imageFit' : 'imageActual')}</button>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/src/client/blame-gutter.ts

@@ -0,0 +1,108 @@
+/**
+ * Blame as a CodeMirror gutter.
+ *
+ * The side-by-side pane could render blame as one more column of its CSS grid,
+ * because there the file is a grid of rows the pane itself lays out. In the
+ * file browser the file IS the editor — CodeMirror owns the lines, renders
+ * only the viewport, and re-renders it on every scroll — so the annotation has
+ * to live where the line numbers live: in a gutter.
+ *
+ * The wording is {@link blameLabel} and {@link blameTitle}, the same pure
+ * functions the diff pane used, so both views abbreviate a sha and format a
+ * date identically and only one of them is worth testing.
+ *
+ * The gutter sits in a {@link blameCompartment} so it can be added and removed
+ * from a live view: an always-installed gutter returning no markers still
+ * reserves its column, and a blank strip beside the code is exactly what the
+ * toggle exists to avoid.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/blame-gutter
+ */
+
+import { Compartment, StateEffect, StateField, type Extension } from '@codemirror/state'
+import { gutter, GutterMarker } from '@codemirror/view'
+
+import { blameLabel, blameRunStart, blameTitle } from './blame-view.ts'
+import type { BlameLine } from './GitWorkbenchPanel.tsx'
+
+/** Carries a fetched blame — or null for "not showing" — into the view. */
+export const setBlame = StateEffect.define<readonly BlameLine[] | null>()
+
+/**
+ * The blame the gutter reads. Held in state rather than in a closure so a
+ * marker can be computed from a transaction alone, which is what CodeMirror
+ * hands the gutter when it re-renders a scrolled viewport.
+ */
+export const blameField = StateField.define<readonly BlameLine[] | null>({
+  create: () => null,
+  update(held, tr) {
+    for (const effect of tr.effects) {
+      if (effect.is(setBlame)) return effect.value
+    }
+    return held
+  },
+})
+
+/** Swaps the gutter itself in and out; the field above stays installed. */
+export const blameCompartment = new Compartment()
+
+/** One line's annotation. */
+class BlameMarker extends GutterMarker {
+  constructor(private readonly text: string, private readonly hover: string) {
+    super()
+  }
+
+  /** CodeMirror reuses a marker's DOM when this says the two are the same. */
+  override eq(other: BlameMarker): boolean {
+    return other.text === this.text && other.hover === this.hover
+  }
+
+  override toDOM(): HTMLElement {
+    const span = document.createElement('span')
+    span.className = 'cm-gwBlameCell'
+    span.textContent = this.text
+    if (this.hover.length > 0) span.title = this.hover
+    return span
+  }
+}
+
+/** Reserves the column's width so the code does not shift as lines scroll by.
+ *  Names have no fixed width, so this is a plausible one and the cell's CSS
+ *  ellipsises anything longer — a gutter that resized itself as the viewport
+ *  scrolled past a long name would shift the code under the reader. */
+const SPACER = new BlameMarker('nnnnnnnnnnnn', '')
+
+/**
+ * The gutter extension.
+ * @param notCommitted - the drawer's own wording for a line with no commit
+ *                       behind it; git's English is never passed through.
+ * @param onPick - called with the 1-based line number the reader clicked.
+ */
+export function blameGutter(notCommitted: string, onPick: (line: number) => void): Extension {
+  return gutter({
+    class: 'cm-gwBlameGutter',
+    domEventHandlers: {
+      // Picking a line is how the commit behind it is reached: the gutter
+      // shows the person, and the hash, the timestamp and the subject belong
+      // to the moment the reader has decided this is the line they care about.
+      click(view, line) {
+        onPick(view.state.doc.lineAt(line.from).number)
+        return true
+      },
+    },
+    lineMarker(view, line) {
+      const lines = view.state.field(blameField, false)
+      if (lines === null || lines === undefined) return null
+      const number = view.state.doc.lineAt(line.from).number
+      const entry = lines[number - 1]
+      // A marker for EVERY line, even where it shows nothing: CodeMirror does
+      // not create a gutter element for a line with no marker, and a run's
+      // unlabelled lines have to stay clickable and hoverable. The label
+      // appears only at the run's top; the title is on all of them, so
+      // hovering the fortieth line of a run still names its commit.
+      const text = blameRunStart(lines, number) ? blameLabel(entry, notCommitted) : ''
+      return new BlameMarker(text, blameTitle(entry, notCommitted))
+    },
+    initialSpacer: () => SPACER,
+  })
+}

package/src/client/blame-view.ts

@@ -0,0 +1,104 @@
+/**
+ * How one blame entry reads in the gutter, and in the detail strip a click
+ * opens.
+ *
+ * The gutter carries the PERSON. A commit hash is an identifier, not an
+ * answer: reading down a file, the question is who wrote this, and a column of
+ * hex says nothing until you look each one up. So the gutter is names, and the
+ * commit — its hash, its full timestamp, what it said it was doing — appears
+ * when the reader picks a line, which is the point at which they have decided
+ * this line is the one they care about.
+ *
+ * Dates are rendered from the parts of a local `Date` rather than through
+ * `toLocaleDateString`, because the drawer's language is its own setting and
+ * not the browser's: the same drawer showing English must not switch to the
+ * machine's date order. `YYYY-MM-DD` reads the same in both dictionaries.
+ *
+ * Pure: no React, no DOM, no git. `tests/blame-view.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/blame-view
+ */
+
+import type { BlameLine } from './GitWorkbenchPanel.tsx'
+
+/** How many hex digits of a sha the gutter shows. git's own default. */
+export const SHORT_HASH = 7
+
+/** The gutter's abbreviation of a commit; '' when there is no commit. */
+export function shortHash(hash: string): string {
+  return /^[0-9a-f]{7,}$/.test(hash) ? hash.slice(0, SHORT_HASH) : ''
+}
+
+/**
+ * `YYYY-MM-DD` in the reader's own timezone, or '' when git gave no time.
+ * @param time - unix seconds.
+ */
+export function blameDate(time: number): string {
+  if (!Number.isFinite(time) || time <= 0) return ''
+  const at = new Date(time * 1000)
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`
+}
+
+/**
+ * The one line the gutter shows: who last changed it.
+ *
+ * @param entry - the line's provenance, or undefined for a line the blame did
+ *                not cover (a truncated file, a line added since the fetch).
+ * @param notCommitted - the drawer's own wording for a line with no commit
+ *                       behind it; git's English is not passed through.
+ * @returns the author's name, '' when there is nothing to say.
+ */
+export function blameLabel(entry: BlameLine | undefined, notCommitted: string): string {
+  if (entry === undefined) return ''
+  if (entry.uncommitted) return notCommitted
+  return entry.author
+}
+
+/**
+ * `YYYY-MM-DD HH:MM` in the reader's own timezone, or '' when git gave no
+ * time. The detail strip shows the clock time as well as the day: two commits
+ * on one afternoon are a common thing to be telling apart.
+ * @param time - unix seconds.
+ */
+export function blameWhen(time: number): string {
+  const date = blameDate(time)
+  if (date === '') return ''
+  const at = new Date(time * 1000)
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${date} ${pad(at.getHours())}:${pad(at.getMinutes())}`
+}
+
+/**
+ * Whether this line STARTS a run — the first line of a stretch that one commit
+ * is responsible for.
+ *
+ * A gutter that repeats the same name down forty lines is forty copies of one
+ * fact, and it buries the boundaries, which are the only thing the column is
+ * really reporting: where authorship changes. IDEA labels a run once, at its
+ * top, and leaves the rest blank. Runs are keyed on the COMMIT rather than the
+ * author, so two commits by one person still read as two runs.
+ *
+ * @param lines - the whole file's provenance, indexed from 0.
+ * @param number - 1-based line number.
+ */
+export function blameRunStart(lines: readonly BlameLine[], number: number): boolean {
+  const entry = lines[number - 1]
+  if (entry === undefined) return false
+  const previous = lines[number - 2]
+  // Line 1 always starts a run; so does the first line after a gap the blame
+  // did not cover, which is a boundary whether or not the commits match.
+  if (previous === undefined) return true
+  return previous.hash !== entry.hash
+}
+
+/**
+ * The hover text: who, when, and what the commit said it was doing.
+ * Empty when there is nothing more than the gutter already shows.
+ */
+export function blameTitle(entry: BlameLine | undefined, notCommitted: string): string {
+  if (entry === undefined) return ''
+  if (entry.uncommitted) return notCommitted
+  const parts = [entry.author, blameDate(entry.time), entry.summary].filter(part => part.length > 0)
+  return parts.join(' · ')
+}

package/src/client/cm-diff.ts

@@ -0,0 +1,108 @@
+/**
+ * Which lines of the editor's buffer differ from the side it is being edited
+ * against — recomputed as the reader types.
+ *
+ * Arming the editor used to take the diff colours away: the buffer rendered as
+ * one undifferentiated block, because the pane's add/delete tints come from
+ * git's diff and git has not seen a keystroke. That is the wrong trade. The
+ * reason to edit inside a diff view at all is to watch the change take shape,
+ * and a view that goes blank the moment you touch it is a view you have to
+ * leave to check your work.
+ *
+ * So the tint is recomputed client-side from the text on both sides. This is
+ * NOT the diff any git operation uses — the block actions still send line
+ * indices against the host's own `diffSha`-stamped patch, and nothing here
+ * reaches git. It is a reading aid, and it is allowed to be approximate at the
+ * exact moment a keystroke lands.
+ *
+ * The diff itself is CodeMirror's (`presentableDiff`, already aligned to line
+ * boundaries); this module is the arithmetic from its character offsets to
+ * line numbers.
+ *
+ * Pure: no React, no DOM, no git. `tests/cm-diff.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/cm-diff
+ */
+
+import { presentableDiff } from '@codemirror/merge'
+
+/** Which of the buffer's lines the reader has changed, 1-based as an editor
+ *  counts them. */
+export interface BufferDiff {
+  /** Lines carrying text that is not on the other side: added or rewritten. */
+  readonly changed: readonly number[]
+  /** Lines that text was removed just BEFORE. A pure deletion leaves nothing
+   *  in the buffer to tint, so the marker goes on the line that closed over
+   *  the gap — which is where a reader looks for what went missing. */
+  readonly deletedBefore: readonly number[]
+}
+
+/** Offsets at which each line of `text` starts. */
+function lineStarts(text: string): number[] {
+  const starts = [0]
+  for (let at = text.indexOf('\n'); at !== -1; at = text.indexOf('\n', at + 1)) {
+    starts.push(at + 1)
+  }
+  return starts
+}
+
+/** 1-based line number containing `offset`, by binary search. */
+function lineAt(starts: readonly number[], offset: number): number {
+  let low = 0
+  let high = starts.length - 1
+  while (low < high) {
+    const mid = (low + high + 1) >> 1
+    if (starts[mid]! <= offset) low = mid
+    else high = mid - 1
+  }
+  return low + 1
+}
+
+/**
+ * Compare the buffer against the side it is edited against.
+ *
+ * @param original - the other side's whole text (the index side, for the
+ *                   unstaged layer this editor lives on).
+ * @param doc - the editor's buffer.
+ * @returns the buffer's changed lines and its deletion points. Both are
+ *          ascending and free of duplicates, which is what a decoration set
+ *          wants and what makes two calls comparable.
+ */
+export function bufferDiff(original: string, doc: string): BufferDiff {
+  if (original === doc) return { changed: [], deletedBefore: [] }
+  const lines = doc.split('\n')
+  const starts = lineStarts(doc)
+  const changed = new Set<number>()
+  const deletedBefore = new Set<number>()
+
+  for (const change of presentableDiff(original, doc)) {
+    if (change.fromB === change.toB) {
+      // Nothing was INSERTED — but that does not mean a line disappeared. A
+      // line the reader shortened (`example.com/taskqueue` to `example.com`)
+      // is a pure deletion too, and it is still on screen, changed. Reading
+      // every empty insertion as a vanished line is what left a shortened
+      // line untinted until the next keystroke happened to add a character.
+      const line = lineAt(starts, change.fromB)
+      const removed = original.slice(change.fromA, change.toA)
+      // Whole lines went only if the removed text both starts at a line
+      // boundary and takes its newline with it.
+      const wholeLines = removed.endsWith('\n')
+        && (change.fromA === 0 || original[change.fromA - 1] === '\n')
+      // An emptied line has nothing left to tint either way, so it reads as a
+      // gap rather than as a coloured blank.
+      if (wholeLines || (lines[line - 1] ?? '').length === 0) deletedBefore.add(line)
+      else changed.add(line)
+      continue
+    }
+    const first = lineAt(starts, change.fromB)
+    // `toB` is exclusive. A change ending exactly at a line start stopped at
+    // the previous line's newline and does not reach into the line after it.
+    const last = lineAt(starts, Math.max(change.fromB, change.toB - 1))
+    for (let line = first; line <= last; line += 1) changed.add(line)
+  }
+
+  return {
+    changed: [...changed].sort((a, b) => a - b),
+    deletedBefore: [...deletedBefore].filter(line => !changed.has(line)).sort((a, b) => a - b),
+  }
+}

package/src/client/cm-tokens.ts

@@ -0,0 +1,79 @@
+/**
+ * Shiki's per-line tokens, restated as absolute document ranges CodeMirror can
+ * decorate.
+ *
+ * The editor does not carry a second syntax engine. `highlightFile` already
+ * lexes this file for the diff columns, and re-lexing the same text with a
+ * different grammar would cost another engine in the bundle AND paint the
+ * editor in colours the diff beside it does not use. So the editor borrows the
+ * tokens the pane already computed; this module is the arithmetic between the
+ * two — per-line runs in, absolute offsets out.
+ *
+ * Only runs that actually PAINT something become ranges. A plain run inherits
+ * the editor's own colour, and a decoration that changes nothing still costs a
+ * DOM element per token, which for a whole file is most of them.
+ *
+ * Pure: no CodeMirror, no React, no DOM. `tests/cm-tokens.test.ts` loads it
+ * directly, and the CodeMirror glue turns these into `Decoration.mark`s.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/cm-tokens
+ */
+
+import type { HighlightRun } from './highlight.ts'
+
+/** One painted span, in absolute offsets from the start of the document. */
+export interface TokenRange {
+  readonly from: number
+  readonly to: number
+  readonly color?: string
+  readonly italic?: boolean
+}
+
+/** Whether a run paints anything the editor's own style does not already. */
+function paints(run: HighlightRun): boolean {
+  return run.color !== undefined || run.italic === true
+}
+
+/**
+ * Turn per-line highlight runs into document ranges.
+ *
+ * @param lines - the document's lines, exactly as it was split on LF. Their
+ *                lengths are what convert a line-relative offset to an
+ *                absolute one, so they must be the SAME lines the runs
+ *                describe.
+ * @param runs - `highlightFile`'s answer, or undefined while a grammar is
+ *               still loading — which yields no ranges rather than throwing,
+ *               the same contract the diff columns read it under.
+ * @returns painted ranges in document order, ready to sort into a range set.
+ *          A run whose text runs past the end of its line is clipped there: a
+ *          decoration crossing a line boundary is an error CodeMirror throws
+ *          on, and the honest answer to disagreeing inputs is less paint, not
+ *          a crash in the editor.
+ */
+export function tokenRanges(
+  lines: readonly string[],
+  runs: readonly (readonly HighlightRun[])[] | undefined,
+): TokenRange[] {
+  if (runs === undefined) return []
+  const out: TokenRange[] = []
+  let lineStart = 0
+  lines.forEach((line, index) => {
+    const lineRuns = runs[index]
+    if (lineRuns !== undefined) {
+      let at = 0
+      for (const run of lineRuns) {
+        const from = lineStart + at
+        at += run.text.length
+        const to = Math.min(lineStart + at, lineStart + line.length)
+        if (to > from && paints(run)) {
+          out.push({ from, to, color: run.color, italic: run.italic })
+        }
+        if (at >= line.length) break
+      }
+    }
+    // +1 for the LF that `split('\n')` removed. The last line has none, but
+    // nothing reads past it either.
+    lineStart += line.length + 1
+  })
+  return out
+}