@reviewflow/ui 0.0.0-stage → 6.21.0

package/src/components/pull-request-timeline.tsx

@@ -0,0 +1,270 @@
+import type {
+  PullRequestDetailResponse,
+  PullRequestEdit,
+  PullRequestEvent,
+  PullRequestTimelineItem,
+} from "@reviewflow/sdk";
+import { ActionButton, ExternalLinkText, View } from "alouette";
+import type { ReactNode } from "react";
+import { usePullRequestDataSource } from "../dataSource.ts";
+import { errorToMessage } from "../services/errorToMessage.ts";
+import { CommentCard } from "./pull-request-conversation-card.tsx";
+import {
+  Composer,
+  type ComposerDraft,
+  type ConversationEditing,
+  useSendEdit,
+} from "./pull-request-conversation-edit.tsx";
+import { CommitsLine, EventLine } from "./pull-request-conversation-event.tsx";
+import { Thread } from "./pull-request-conversation-thread.tsx";
+import {
+  PullRequestPartError,
+  PullRequestPartPending,
+  PullRequestPartReading,
+} from "./pull-request-part-notice.tsx";
+
+type TimelineEntry =
+  | { kind: "commits"; events: PullRequestEvent[] }
+  | { kind: "item"; item: PullRequestTimelineItem };
+
+const isCommit = (item: PullRequestTimelineItem): item is PullRequestEvent =>
+  item.kind === "event" && item.action === "committed";
+
+/** Consecutive commits of one actor, with nothing between them, are one push. */
+const groupCommits = (timeline: PullRequestTimelineItem[]): TimelineEntry[] => {
+  const entries: TimelineEntry[] = [];
+  for (const item of timeline) {
+    const previous = entries.at(-1);
+    if (
+      isCommit(item) &&
+      previous?.kind === "commits" &&
+      previous.events[0]?.actor?.login === item.actor?.login
+    ) {
+      previous.events.push(item);
+    } else if (isCommit(item)) {
+      entries.push({ kind: "commits", events: [item] });
+    } else {
+      entries.push({ kind: "item", item });
+    }
+  }
+  return entries;
+};
+
+const entryKey = (entry: TimelineEntry, index: number): string => {
+  if (entry.kind === "commits") {
+    return `commits:${entry.events[0]?.createdAt ?? ""}:${String(index)}`;
+  }
+  const { item } = entry;
+  if (item.kind === "event") {
+    return `event:${item.action}:${item.createdAt}:${String(index)}`;
+  }
+  return `${item.kind}:${item.id}`;
+};
+
+interface TimelineEntryViewProps {
+  editing: ConversationEditing;
+  entry: TimelineEntry;
+}
+
+function TimelineEntryView({
+  editing,
+  entry,
+}: TimelineEntryViewProps): ReactNode {
+  if (entry.kind === "commits") return <CommitsLine events={entry.events} />;
+  const { item } = entry;
+  if (item.kind === "event") return <EventLine event={item} />;
+  if (item.kind === "thread") return <Thread editing={editing} thread={item} />;
+  if (item.kind === "review") {
+    return (
+      <CommentCard
+        editing={editing}
+        author={item.author}
+        action="reviewed"
+        verdict={item.state}
+        createdAt={item.createdAt}
+        lastEditedAt={item.lastEditedAt}
+        url={item.url}
+        body={item.body}
+        canEdit={item.viewerCanUpdate}
+        reactable={item}
+        toEdit={(body) => ({
+          kind: "editComment",
+          target: "review",
+          databaseId: item.databaseId,
+          body,
+        })}
+      />
+    );
+  }
+  return (
+    <CommentCard
+      editing={editing}
+      author={item.author}
+      action="commented"
+      createdAt={item.createdAt}
+      lastEditedAt={item.lastEditedAt}
+      url={item.url}
+      body={item.body}
+      canEdit={item.viewerCanUpdate}
+      reactable={item}
+      toEdit={(body) => ({
+        kind: "editComment",
+        target: "issueComment",
+        databaseId: item.databaseId,
+        body,
+      })}
+    />
+  );
+}
+
+interface CloseWithCommentProps {
+  editing: ConversationEditing;
+  draft: ComposerDraft;
+}
+
+/**
+ * Closing requires a comment saying why, posted first so it reads above the
+ * close event. A refused close leaves the comment posted and the box cleared.
+ */
+function CloseWithComment({
+  editing,
+  draft,
+}: CloseWithCommentProps): ReactNode {
+  const { pullRequest } = editing;
+  const sendEdit = useSendEdit(editing);
+  if (!pullRequest.viewerCanUpdate || pullRequest.state !== "open") return null;
+
+  return (
+    <ActionButton
+      text="Close with comment"
+      accent="danger"
+      variant="tonal"
+      size="sm"
+      disabledReason={
+        draft.body.trim() === ""
+          ? "Write a comment saying why it is closed."
+          : null
+      }
+      errorToMessage={errorToMessage}
+      onPress={async () => {
+        await sendEdit({ kind: "comment", body: draft.body });
+        draft.clear();
+        await sendEdit({ kind: "state", state: "closed" });
+      }}
+    />
+  );
+}
+
+export interface PullRequestTimelineProps {
+  detail: PullRequestDetailResponse;
+  /** reads the pull request again once GitHub took a change */
+  onEdited: (edit: PullRequestEdit) => Promise<void>;
+}
+
+/** The description, as GitHub's first comment. */
+export function PullRequestDescription({
+  detail,
+  onEdited,
+}: PullRequestTimelineProps): ReactNode {
+  const { pullRequest } = detail;
+  return (
+    <CommentCard
+      editing={{ pullRequest, onEdited }}
+      author={pullRequest.author}
+      action="opened"
+      createdAt={pullRequest.createdAt}
+      lastEditedAt={pullRequest.lastEditedAt}
+      url={pullRequest.url}
+      body={pullRequest.body}
+      emptyText="No description provided."
+      canEdit={pullRequest.viewerCanUpdate}
+      reactable={pullRequest}
+      toEdit={(body) => ({ kind: "body", body })}
+    />
+  );
+}
+
+const isConversation = (item: PullRequestTimelineItem): boolean =>
+  item.kind !== "event";
+
+/** Comments, reviews and threads only: what a reviewer reads, without the events. */
+export const conversationCount = (
+  timeline: PullRequestTimelineItem[],
+): number => timeline.filter(isConversation).length;
+
+export interface PullRequestTimelineEntriesProps extends PullRequestTimelineProps {
+  /** leaves out commits, label changes and the other events */
+  conversationOnly?: boolean;
+}
+
+/** The timeline part, oldest first, once read. */
+export function PullRequestTimelineEntries({
+  detail,
+  onEdited,
+  conversationOnly = false,
+}: PullRequestTimelineEntriesProps): ReactNode {
+  const { pullRequest } = detail;
+  const { value, error, reading } = usePullRequestDataSource().usePart(
+    pullRequest,
+    "timeline",
+  );
+  const editing: ConversationEditing = { pullRequest, onEdited };
+  if (value === null) {
+    return <PullRequestPartPending error={error} what="the timeline" />;
+  }
+  const items = conversationOnly
+    ? value.timeline.filter(isConversation)
+    : value.timeline;
+  return (
+    <>
+      <PullRequestPartReading reading={reading} />
+      <PullRequestPartError error={error} />
+      {value.timelineTruncated ? (
+        <ExternalLinkText
+          size="sm"
+          href={pullRequest.url}
+          text="Older activity is only on GitHub"
+        />
+      ) : null}
+      {groupCommits(items).map((entry, index) => (
+        <TimelineEntryView
+          key={entryKey(entry, index)}
+          editing={editing}
+          entry={entry}
+        />
+      ))}
+    </>
+  );
+}
+
+/**
+ * The conversation as GitHub's page has it: the description, then comments,
+ * reviews, threads on the code and events oldest first, then a box to comment.
+ */
+export function PullRequestTimeline({
+  detail,
+  onEdited,
+}: PullRequestTimelineProps): ReactNode {
+  const { pullRequest } = detail;
+  const editing: ConversationEditing = { pullRequest, onEdited };
+
+  return (
+    <View className="gap-m">
+      <PullRequestDescription detail={detail} onEdited={onEdited} />
+      <PullRequestTimelineEntries detail={detail} onEdited={onEdited} />
+      <Composer
+        editing={editing}
+        draftKey="comment"
+        title="Add a comment"
+        ariaLabel="New comment"
+        buttonText="Comment"
+        toEdit={(body) => ({ kind: "comment", body })}
+        // a render prop called by the composer, not a component defined here
+        // oxlint-disable-next-line react/no-unstable-nested-components
+        extraActions={(draft) => (
+          <CloseWithComment editing={editing} draft={draft} />
+        )}
+      />
+    </View>
+  );
+}

package/src/components/repository-attachment-banner.tsx

@@ -0,0 +1,42 @@
+import { Text, View, WarningMessage } from "alouette";
+import type { ReactNode } from "react";
+import type { RepositoryAttachment } from "../dataSource.ts";
+import { usePullRequestSlots } from "../slots.tsx";
+
+interface RepositoryAttachmentBannerProps {
+  ownerRepo: string;
+  attachment: RepositoryAttachment;
+  /** overrides the `renderRepositoryAction` slot: where the checkout is configured */
+  action?: ReactNode;
+}
+
+/**
+ * Says up front, on every tab, that the diff of this repository cannot be read
+ * because no local checkout is attached to it, rather than leaving that to be
+ * found in Files changed. An entry that exists but fails its check shows why.
+ * Nothing when the checkout is attached.
+ */
+export function RepositoryAttachmentBanner({
+  ownerRepo,
+  attachment,
+  action,
+}: RepositoryAttachmentBannerProps): ReactNode {
+  const { renderRepositoryAction } = usePullRequestSlots();
+  if (attachment.status === "attached") return null;
+  const shownAction = action ?? renderRepositoryAction?.(ownerRepo);
+  return (
+    <WarningMessage>
+      <View className="gap-xs">
+        <Text className="font-body-bold text-sm">
+          {`${ownerRepo} is not attached to a local checkout: the diff cannot be read.`}
+        </Text>
+        {attachment.status === "invalidPath" ? (
+          <Text className="text-sm">{attachment.detail}</Text>
+        ) : null}
+        {shownAction === null || shownAction === undefined ? null : (
+          <View className="flex-row">{shownAction}</View>
+        )}
+      </View>
+    </WarningMessage>
+  );
+}

package/src/components/scroll-parent.ts

@@ -0,0 +1,50 @@
+/**
+ * The nearest ancestor that scrolls vertically, which only exists on the web
+ * (a DOM element); null when none does. Used to keep a closed file's header in
+ * view under the diff toolbar.
+ */
+export const scrollParentOf = (element: HTMLElement): HTMLElement | null => {
+  for (
+    let parent = element.parentElement;
+    parent !== null;
+    parent = parent.parentElement
+  ) {
+    const { overflowY } = getComputedStyle(parent);
+    if (overflowY === "auto" || overflowY === "scroll") return parent;
+  }
+  return null;
+};
+
+/** A CSS variable as `element` inherits it; "" without a DOM element (native). */
+export const cssVariableOf = (element: unknown, name: string): string =>
+  typeof HTMLElement !== "undefined" && element instanceof HTMLElement
+    ? getComputedStyle(element).getPropertyValue(name).trim()
+    : "";
+
+/** How far `element`'s top is above the `stickyTop` pixels a sticky bar covers; negative below. */
+const hiddenAbove = (
+  element: HTMLElement,
+  container: HTMLElement,
+  stickyTop: number,
+): number =>
+  container.getBoundingClientRect().top +
+  stickyTop -
+  element.getBoundingClientRect().top;
+
+/** Scrolls `element`'s top to just under the `stickyTop` pixels a sticky bar covers. */
+export const scrollToTopOf = (
+  element: HTMLElement,
+  stickyTop: number,
+): void => {
+  const container = scrollParentOf(element);
+  if (container === null) return;
+  container.scrollTop -= hiddenAbove(element, container, stickyTop);
+};
+
+/** As `scrollToTopOf`, only when `element`'s top is hidden above that bar. */
+export const revealTopOf = (element: HTMLElement, stickyTop: number): void => {
+  const container = scrollParentOf(element);
+  if (container === null) return;
+  const hidden = hiddenAbove(element, container, stickyTop);
+  if (hidden > 0) container.scrollTop -= hidden;
+};

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/dataSource.ts

@@ -0,0 +1,242 @@
+import type {
+  DiffImpactsResponse,
+  DiffReadingOrderResponse,
+  DiffRefusal,
+  DiffStep,
+  DiffWhitespace,
+  EditPullRequestResponse,
+  PullRequestCandidatesResponse,
+  PullRequestDiffResponse,
+  PullRequestEdit,
+  PullRequestPart,
+  PullRequestPartResponse,
+  PullRequestRef,
+  PullRequestRevisionsResponse,
+  PullRequestSummary,
+  ReviewflowPrResponse,
+} from "@reviewflow/sdk";
+import { createContext, use } from "react";
+
+/**
+ * Where a read is at, as the components consume it. Every `use*` hook of the
+ * data source answers with this shape.
+ *
+ * - `value`: the newest answer held, `null` until the first one. It carries its
+ *   own age (`fetchedAt`, `checkedAt`) for the parts that are
+ *   `PullRequestRead`s, which is what the screen's "read at" line shows.
+ * - `cached`: `value` is an older read shown while the source reads again, not
+ *   an answer to this request. A source with no cache always says `false`.
+ * - `reading`: the source is reading, for the first time or over `value`, and
+ *   the screen should say so. A source may leave out a re-read over a `value`
+ *   it holds for up to date, one that only confirms what is shown.
+ * - `error`: why the last read failed, as a message; `value` may still hold an
+ *   older answer.
+ */
+export interface PullRequestReadState<T> {
+  value: T | null;
+  cached: boolean;
+  reading: boolean;
+  error: string | null;
+}
+
+/** Why the source did not read the diff at all; defined by the sdk, which the server answers with. */
+export type PullRequestDiffRefusal = DiffRefusal;
+
+/**
+ * Whether the source can read a repository's diff from a local checkout, known
+ * before any diff is asked for. `detail` says which checkout is used, or why
+ * none can be.
+ */
+export interface RepositoryAttachment {
+  status: "attached" | "invalidPath" | "notConfigured";
+  detail: string;
+}
+
+/** The range a diff is read over: two shas, which name it for good. */
+export interface PullRequestDiffRange {
+  head: string;
+  base: string;
+  whitespace: DiffWhitespace;
+}
+
+export interface PullRequestDiffState extends PullRequestReadState<PullRequestDiffResponse> {
+  /**
+   * What the source is waiting on while `reading`: `fetching` the commits into
+   * the checkout, `diffing` them. `null` when it does not know, or is not
+   * reading. A large fetch takes tens of seconds, which a bare spinner hides.
+   */
+  step: DiffStep | null;
+  /** set instead of `value` when the source refused to read, see {@link PullRequestDiffRefusal} */
+  refused: PullRequestDiffRefusal | null;
+}
+
+export interface PullRequestDiffsState extends PullRequestReadState<
+  PullRequestDiffResponse[]
+> {
+  /** the first range the source refused to read, as for the diff */
+  refused: PullRequestDiffRefusal | null;
+}
+
+export interface PullRequestReadingOrderState extends PullRequestReadState<DiffReadingOrderResponse> {
+  /** set instead of `value` when the source refused to read, as for the diff */
+  refused: PullRequestDiffRefusal | null;
+}
+
+export interface PullRequestImpactsState extends PullRequestReadState<DiffImpactsResponse> {
+  /** set instead of `value` when the source refused to read, as for the diff */
+  refused: PullRequestDiffRefusal | null;
+}
+
+/**
+ * What the pull request screen reads and writes through. The app provides one
+ * with {@link PullRequestDataSourceProvider}; the components never reach for a
+ * network or a cache themselves.
+ *
+ * Hooks follow the rules of hooks (called unconditionally, in the same order);
+ * `ref` and the other arguments may change between renders, and the state then
+ * follows them.
+ */
+export interface PullRequestDataSource {
+  /**
+   * What the app already holds of the pull request (a copy from another
+   * source, reviewflow's say), enough to head the screen until the `detail`
+   * part arrives. Optional: without it the screen shows its pending notice
+   * alone. `null` when the app holds nothing for this pull request.
+   */
+  useSummary?: (ref: PullRequestRef) => PullRequestSummary | null;
+
+  /**
+   * One part of the pull request (`detail`, `checks`, `timeline`, `commits`,
+   * `files`). Read when a component showing it mounts, never on a timer.
+   */
+  usePart: <Part extends PullRequestPart>(
+    ref: PullRequestRef,
+    part: Part,
+  ) => PullRequestReadState<PullRequestPartResponse<Part>>;
+
+  /**
+   * Whether the repository has a local checkout the diff can be read from, so
+   * the screen can say so on every tab rather than only once a diff is asked
+   * for. `null` while unknown: no banner. Optional: a source that always has
+   * its checkouts (or reads no diff from one) leaves it out.
+   */
+  useRepositoryAttachment?: (
+    ref: PullRequestRef,
+  ) => RepositoryAttachment | null;
+
+  /**
+   * reviewflow's copy of the pull request: its checks are judged by its rules
+   * (checks allowed to fail, jobs on hold, its own check left out). Optional: a
+   * source without reviewflow leaves it out, and nothing is shown in its place.
+   */
+  useReviewflowPr?: (
+    ref: PullRequestRef,
+  ) => PullRequestReadState<ReviewflowPrResponse>;
+
+  /** What the reviewer, assignee and label editors offer. Not read again by `reload`. */
+  useCandidates: (
+    ref: PullRequestRef,
+  ) => PullRequestReadState<PullRequestCandidatesResponse>;
+
+  /** The edit history of a description, a comment or a review (`subjectId` is its GitHub node id). */
+  useRevisions: (
+    ref: PullRequestRef,
+    subjectId: string,
+  ) => PullRequestReadState<PullRequestRevisionsResponse>;
+
+  /**
+   * The pull request's changes over `range`. `null` reads nothing (a
+   * component that may need a diff later). While a new range loads, the
+   * previous `value` should stay (`cached: true`) so the viewer does not flash.
+   */
+  useDiff: (
+    ref: PullRequestRef,
+    range: PullRequestDiffRange | null,
+  ) => PullRequestDiffState;
+
+  /**
+   * Several ranges' changes, each read and kept as `useDiff` reads it, so a
+   * range read here is not read again there. `value` is every answer in the
+   * order of `ranges`, `null` until the last one arrived. `null` reads
+   * nothing.
+   */
+  useDiffs: (
+    ref: PullRequestRef,
+    ranges: readonly PullRequestDiffRange[] | null,
+  ) => PullRequestDiffsState;
+
+  /**
+   * The files of the range's diff in reading order (experimental). `null`
+   * reads nothing: the reader has not asked for that order. Optional: without
+   * it the diff offers only its order by package.
+   */
+  useReadingOrder?: (
+    ref: PullRequestRef,
+    range: { head: string; base: string } | null,
+  ) => PullRequestReadingOrderState;
+
+  /**
+   * The exports the range's change touches and the files outside the diff that
+   * use them (experimental). `null` reads nothing. Optional: without it the
+   * diff shows no impacts.
+   */
+  useImpacts?: (
+    ref: PullRequestRef,
+    range: { head: string; base: string } | null,
+  ) => PullRequestImpactsState;
+
+  /**
+   * One file at a commit, so the diff can unfold the lines the patch left out.
+   * A promise rather than a hook: it is asked from a press, long after
+   * render. Rejects with a message when the file cannot be read.
+   */
+  readFileAtSha: (
+    ref: PullRequestRef,
+    sha: string,
+    path: string,
+  ) => Promise<string>;
+
+  /**
+   * Writes to GitHub, resolving with the server's answer once GitHub took the
+   * change (`followUpError` is what failed after the write landed) and
+   * rejecting with the reason when it did not. Does not re-read: the screen calls `reload`
+   * with the parts `pullRequestPartsStaleAfter` names. A `viewed` edit stales
+   * nothing, so the source applies it to the `files` it holds
+   * (`withFileViewed`) before resolving.
+   */
+  edit: (
+    ref: PullRequestRef,
+    edit: PullRequestEdit,
+  ) => Promise<EditPullRequestResponse>;
+
+  /**
+   * Reads `parts` again from GitHub, every part when absent, and resolves once
+   * the parts a mounted component shows are read. A failure is held by the
+   * state of the hook (`error`), so this never rejects.
+   */
+  reload: (
+    ref: PullRequestRef,
+    parts?: readonly PullRequestPart[],
+  ) => Promise<void>;
+}
+
+const DataSourceContext = createContext<PullRequestDataSource | null>(null);
+
+/** Provides the data source to every pull request component below it. */
+export const PullRequestDataSourceProvider = DataSourceContext.Provider;
+
+export const usePullRequestDataSource = (): PullRequestDataSource => {
+  const source = use(DataSourceContext);
+  if (source === null) {
+    throw new Error(
+      "usePullRequestDataSource needs a PullRequestDataSourceProvider",
+    );
+  }
+  return source;
+};
+
+/** The shas a diff and a review are pinned to. */
+export interface PullRequestShas {
+  head: string;
+  base: string;
+}