@reviewflow/ui 0.0.0-stage → 6.21.0

package/src/services/PullRequestDraftsProvider.tsx

@@ -0,0 +1,179 @@
+import type { PullRequestRef } from "@reviewflow/sdk";
+import type { ReactNode } from "react";
+import {
+  createContext,
+  use,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+
+/**
+ * Where what is being written on a pull request is kept between two visits.
+ * Read synchronously, so an editor opens on its draft rather than flashing
+ * empty: an app without synchronous storage passes none, and drafts then live
+ * as long as the screen.
+ */
+export interface DraftStore {
+  /** how long a draft is kept after its last change, told to the reader */
+  retentionDays: number;
+  /** undefined when nothing is kept under `key`, or it expired */
+  read: (key: string) => unknown;
+  write: (key: string, value: unknown) => void;
+  remove: (key: string) => void;
+}
+
+/**
+ * What every editor of the screen holds, blank and unchanged texts included,
+ * outside the editors themselves: an editor remounted (its diff annotation
+ * moved to another slot) opens on what was typed, and two editors of one key
+ * (a thread's reply box in both tabs) show the same text.
+ */
+interface DraftMemory {
+  get: (key: string) => string | undefined;
+  set: (key: string, text: string) => void;
+  delete: (key: string) => void;
+  subscribe: (key: string, listener: () => void) => () => void;
+}
+
+const createDraftMemory = (): DraftMemory => {
+  const texts = new Map<string, string>();
+  const listeners = new Map<string, Set<() => void>>();
+  const notify = (key: string): void => {
+    for (const listener of listeners.get(key) ?? []) listener();
+  };
+  return {
+    get: (key) => texts.get(key),
+    set: (key, text) => {
+      texts.set(key, text);
+      notify(key);
+    },
+    delete: (key) => {
+      if (texts.delete(key)) notify(key);
+    },
+    subscribe: (key, listener) => {
+      const ofKey = listeners.get(key) ?? new Set();
+      ofKey.add(listener);
+      listeners.set(key, ofKey);
+      return () => {
+        ofKey.delete(listener);
+      };
+    },
+  };
+};
+
+interface DraftsContextValue {
+  /** the store, its keys scoped to the pull request of the provider */
+  store: DraftStore | null;
+  memory: DraftMemory;
+}
+
+const DraftsContext = createContext<DraftsContextValue | null>(null);
+
+interface PullRequestDraftsProviderProps {
+  store: DraftStore | undefined;
+  pullRequest: PullRequestRef;
+  children: ReactNode;
+}
+
+export function PullRequestDraftsProvider({
+  store,
+  pullRequest,
+  children,
+}: PullRequestDraftsProviderProps): ReactNode {
+  const scope = `${pullRequest.ownerRepo}#${String(pullRequest.number)}`;
+  const value = useMemo<DraftsContextValue>(
+    () => ({
+      store:
+        store === undefined
+          ? null
+          : {
+              retentionDays: store.retentionDays,
+              read: (key) => store.read(`${scope}:${key}`),
+              write: (key, text) => {
+                store.write(`${scope}:${key}`, text);
+              },
+              remove: (key) => {
+                store.remove(`${scope}:${key}`);
+              },
+            },
+      memory: createDraftMemory(),
+    }),
+    [store, scope],
+  );
+  return <DraftsContext value={value}>{children}</DraftsContext>;
+}
+
+/** without a provider (a story), the editor keeps its own memory */
+const useDraftsContext = (): DraftsContextValue => {
+  const context = use(DraftsContext);
+  // oxlint-disable-next-line react/hook-use-state -- created once, never set
+  const [own] = useState((): DraftsContextValue => ({
+    store: null,
+    memory: createDraftMemory(),
+  }));
+  return context ?? own;
+};
+
+/** null when the app keeps no draft beyond the screen */
+export const usePullRequestDrafts = (): DraftStore | null =>
+  useDraftsContext().store;
+
+const readKept = (
+  { store, memory }: DraftsContextValue,
+  key: string,
+): string | undefined => {
+  const held = memory.get(key);
+  if (held !== undefined) return held;
+  const stored = store?.read(key);
+  return typeof stored === "string" ? stored : undefined;
+};
+
+/** Whether a text draft is kept under `key`, as of the mount. */
+export const useHasDraftText = (key: string): boolean => {
+  const context = useDraftsContext();
+  // oxlint-disable-next-line react/hook-use-state -- read once, at mount, never set
+  const [exists] = useState(() => readKept(context, key) !== undefined);
+  return exists;
+};
+
+export interface DraftText {
+  text: string;
+  setText: (text: string) => void;
+  /**
+   * Back to `initial`, and forgets the kept draft: on cancel, or on send with
+   * the text sent, kept instead when more was typed while it went out.
+   */
+  discard: (sent?: string) => void;
+}
+
+/**
+ * The text of one editor, kept under `key` while it differs from `initial`
+ * and is not blank. `initial` is read at each render: once discarded, the
+ * editor shows the latest one.
+ */
+export const useDraftText = (key: string, initial = ""): DraftText => {
+  const context = useDraftsContext();
+  const { store, memory } = context;
+  const kept = useSyncExternalStore(
+    (listener) => memory.subscribe(key, listener),
+    () => readKept(context, key),
+  );
+
+  return {
+    text: kept ?? initial,
+    setText: (next) => {
+      memory.set(key, next);
+      if (store === null) return;
+      if (next === initial || next.trim() === "") store.remove(key);
+      else store.write(key, next);
+    },
+    discard: (sent) => {
+      if (sent !== undefined && (readKept(context, key) ?? initial) !== sent) {
+        return;
+      }
+      memory.delete(key);
+      store?.remove(key);
+    },
+  };
+};

package/src/services/PullRequestReviewDraftProvider.tsx

@@ -0,0 +1,178 @@
+import type { PullRequestDraftComment } from "@reviewflow/sdk";
+import type { ReactNode } from "react";
+import { createContext, use, useMemo, useRef, useState } from "react";
+import type { Composer } from "../components/pull-request-diff-lines.ts";
+import type { PullRequestShas } from "../dataSource.ts";
+import { usePullRequestDrafts } from "./PullRequestDraftsProvider.tsx";
+
+export interface PendingComment extends PullRequestDraftComment {
+  /** local only, so a draft can be edited or dropped before the review is sent */
+  key: string;
+}
+
+interface PullRequestReviewDraft {
+  /** the comments that go with the next review, in the order they were written */
+  comments: PendingComment[];
+  add: (comment: PullRequestDraftComment) => void;
+  update: (key: string, body: string) => void;
+  remove: (key: string) => void;
+  /** after the review is sent */
+  clear: () => void;
+  /** the comment being written on the pull request's diff */
+  composer: Composer | null;
+  openComposer: (composer: Composer) => void;
+  closeComposer: () => void;
+  /** the range the diff shows and a review is sent on, null until known */
+  shas: PullRequestShas | null;
+  /** the pull request's own range, which `shas` lags once a push landed */
+  latest: PullRequestShas | null;
+  /** shows `latest`; null while a review is in progress */
+  follow: (() => void) | null;
+}
+
+const ReviewDraftContext = createContext<PullRequestReviewDraft | null>(null);
+
+interface PullRequestReviewDraftProviderProps {
+  /** the pull request's range as last read */
+  latest: PullRequestShas | null;
+  children: ReactNode;
+}
+
+interface ReviewInProgress {
+  comments: PendingComment[];
+  composer: Composer | null;
+}
+
+/** What is kept of a review in progress between two visits. */
+interface StoredReview extends ReviewInProgress {
+  pinned: PullRequestShas;
+}
+
+const storedReviewKey = "review";
+
+const isStoredReview = (value: unknown): value is StoredReview =>
+  typeof value === "object" &&
+  value !== null &&
+  Array.isArray((value as StoredReview).comments) &&
+  typeof (value as StoredReview).pinned?.head === "string";
+
+/**
+ * The review being written on one pull request: comments added from the diff,
+ * sent together with the verdict from the header. Kept by the app's
+ * `DraftStore` when it has one, with the range it was written on, so a
+ * reload reopens it as it was; in memory otherwise.
+ * Mounted per pull request, so drafts never leak from one to the next.
+ *
+ * The range is pinned to the first one known and moves only on `follow`: a
+ * push swapping the diff under the reader would change the code being read
+ * without saying so, move a pending comment's line onto other code, and drop a
+ * comment being typed whose line left the diff. `follow` is withheld while a
+ * comment is pending or being written, so the comments always go out on the
+ * commit they were written on.
+ */
+export function PullRequestReviewDraftProvider({
+  latest,
+  children,
+}: PullRequestReviewDraftProviderProps): ReactNode {
+  const drafts = usePullRequestDrafts();
+  // oxlint-disable-next-line react/hook-use-state -- read once, at mount, never set
+  const [restored] = useState(() => {
+    const stored = drafts?.read(storedReviewKey);
+    return isStoredReview(stored) ? stored : null;
+  });
+  const [review, setReview] = useState<ReviewInProgress>({
+    comments: restored?.comments ?? [],
+    composer: restored?.composer ?? null,
+  });
+  // one press can make two changes ("Start a review" adds, then closes the
+  // composer): each builds on the one before, not on the last render
+  const current = useRef(review);
+  const [pinned, setPinned] = useState<PullRequestShas | null>(
+    restored?.pinned ?? latest,
+  );
+  if (pinned === null && latest !== null) setPinned(latest);
+  const { comments, composer } = review;
+  const inProgress = comments.length > 0 || composer !== null;
+
+  const draft = useMemo<PullRequestReviewDraft>(() => {
+    const change = (
+      edit: (previous: ReviewInProgress) => ReviewInProgress,
+    ): void => {
+      const next = edit(current.current);
+      current.current = next;
+      setReview(next);
+      const range = pinned ?? latest;
+      if (drafts === null) return;
+      if (
+        range === null ||
+        (next.comments.length === 0 && next.composer === null)
+      ) {
+        drafts.remove(storedReviewKey);
+        return;
+      }
+      drafts.write(storedReviewKey, {
+        ...next,
+        pinned: range,
+      } satisfies StoredReview);
+    };
+
+    return {
+      comments,
+      add: (comment) => {
+        change((previous) => ({
+          ...previous,
+          comments: [
+            ...previous.comments,
+            {
+              ...comment,
+              key: `${String(Date.now())}-${String(previous.comments.length)}`,
+            },
+          ],
+        }));
+      },
+      update: (key, body) => {
+        change((previous) => ({
+          ...previous,
+          comments: previous.comments.map((comment) =>
+            comment.key === key ? { ...comment, body } : comment,
+          ),
+        }));
+      },
+      remove: (key) => {
+        change((previous) => ({
+          ...previous,
+          comments: previous.comments.filter((comment) => comment.key !== key),
+        }));
+      },
+      clear: () => {
+        change((previous) => ({ ...previous, comments: [] }));
+      },
+      composer,
+      openComposer: (next) => {
+        change((previous) => ({ ...previous, composer: next }));
+      },
+      closeComposer: () => {
+        change((previous) => ({ ...previous, composer: null }));
+      },
+      shas: pinned ?? latest,
+      latest,
+      follow: inProgress
+        ? null
+        : () => {
+            setPinned(latest);
+          },
+    };
+  }, [comments, composer, pinned, latest, inProgress, drafts]);
+
+  return <ReviewDraftContext value={draft}>{children}</ReviewDraftContext>;
+}
+
+export const usePullRequestReviewDraft = (): PullRequestReviewDraft => {
+  const draft = use(ReviewDraftContext);
+  if (draft === null) {
+    throw new Error(
+      "usePullRequestReviewDraft needs a PullRequestReviewDraftProvider",
+    );
+  }
+  return draft;
+};

package/src/services/PullRequestSuggestionBatchProvider.tsx

@@ -0,0 +1,112 @@
+import type {
+  PullRequestDetail,
+  PullRequestEdit,
+  PullRequestSuggestionRef,
+  SuggestionRange,
+} from "@reviewflow/sdk";
+import { View, WarningMessage } from "alouette";
+import type { ReactNode } from "react";
+import { createContext, use, useMemo, useState } from "react";
+import { usePullRequestDataSource } from "../dataSource.ts";
+
+export type BatchedSuggestion = PullRequestSuggestionRef & SuggestionRange;
+
+export interface SuggestionCommitMessage {
+  headline: string;
+  body: string;
+}
+
+interface PullRequestSuggestionBatch {
+  pullRequest: PullRequestDetail;
+  batch: BatchedSuggestion[];
+  add: (suggestion: BatchedSuggestion) => void;
+  remove: (commentId: string) => void;
+  /** one commit for `suggestions`, then the batch is emptied */
+  commit: (
+    suggestions: PullRequestSuggestionRef[],
+    message: SuggestionCommitMessage,
+  ) => Promise<void>;
+}
+
+const SuggestionBatchContext = createContext<PullRequestSuggestionBatch | null>(
+  null,
+);
+
+interface PullRequestSuggestionBatchProviderProps {
+  pullRequest: PullRequestDetail;
+  onEdited: (edit: PullRequestEdit) => Promise<void>;
+  children: ReactNode;
+}
+
+/**
+ * The suggestions gathered to be committed together, as GitHub's "Add
+ * suggestion to batch". In memory, per pull request: a reload drops the
+ * batch, which commits nothing until pressed.
+ *
+ * The commit lands even when resolving its threads afterwards fails; that
+ * failure is shown here, above the tabs, since the button that committed may
+ * be gone with its thread.
+ */
+export function PullRequestSuggestionBatchProvider({
+  pullRequest,
+  onEdited,
+  children,
+}: PullRequestSuggestionBatchProviderProps): ReactNode {
+  const [batch, setBatch] = useState<BatchedSuggestion[]>([]);
+  const [followUpError, setFollowUpError] = useState<string | null>(null);
+  const { edit: writeEdit } = usePullRequestDataSource();
+
+  const value = useMemo<PullRequestSuggestionBatch>(
+    () => ({
+      pullRequest,
+      batch,
+      add: (suggestion) => {
+        setBatch((previous) => [...previous, suggestion]);
+      },
+      remove: (commentId) => {
+        setBatch((previous) =>
+          previous.filter((suggestion) => suggestion.commentId !== commentId),
+        );
+      },
+      commit: async (suggestions, { headline, body }) => {
+        const edit: PullRequestEdit = {
+          kind: "applySuggestions",
+          expectedHeadSha: pullRequest.headSha,
+          suggestions: suggestions.map(({ threadId, commentId }) => ({
+            threadId,
+            commentId,
+          })),
+          headline,
+          body,
+        };
+        const response = await writeEdit(pullRequest, edit);
+        setBatch([]);
+        setFollowUpError(response.followUpError);
+        await onEdited(edit);
+      },
+    }),
+    [pullRequest, batch, onEdited, writeEdit],
+  );
+
+  return (
+    <SuggestionBatchContext value={value}>
+      <View className="gap-m">
+        {followUpError === null ? null : (
+          <WarningMessage
+            dismissIconAriaLabel="Dismiss"
+            onDismiss={() => {
+              setFollowUpError(null);
+            }}
+          >
+            {followUpError}
+          </WarningMessage>
+        )}
+        {children}
+      </View>
+    </SuggestionBatchContext>
+  );
+}
+
+/** Null outside a pull request screen: its suggestions are not committable there. */
+export const useSuggestionBatch = (): PullRequestSuggestionBatch | null =>
+  use(SuggestionBatchContext);

package/src/services/emojify.ts

@@ -0,0 +1,13 @@
+import { nameToEmoji } from "gemoji";
+
+const shortcode = /:([\w+-]+):/g;
+
+/**
+ * GitHub's `:green_heart:` shortcodes as the emoji GitHub renders them as, with
+ * the same table reviewflow reads (`gemoji`). An unknown name stays as typed.
+ */
+export const emojify = (text: string): string =>
+  text.replaceAll(
+    shortcode,
+    (match, name: string) => nameToEmoji[name] ?? match,
+  );

package/src/services/errorToMessage.ts

@@ -0,0 +1,6 @@
+import { FormValidationError } from "alouette";
+
+export const errorToMessage = (error: unknown): string => {
+  if (error instanceof FormValidationError) return "Fix the errors above.";
+  return error instanceof Error ? error.message : String(error);
+};

package/src/services/expiringDraftStore.ts

@@ -0,0 +1,102 @@
+import type { DraftStore } from "./PullRequestDraftsProvider.tsx";
+
+/** The part of the web `Storage` the store needs, so a test can pass a map. */
+export interface DraftStorage {
+  readonly length: number;
+  key: (index: number) => string | null;
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+}
+
+interface StoredDraft {
+  savedAt: number;
+  value: unknown;
+}
+
+const prefix = "reviewflow:draft:";
+const dayMs = 24 * 60 * 60 * 1000;
+
+const parse = (raw: string | null): StoredDraft | null => {
+  if (raw === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as StoredDraft).savedAt === "number"
+      ? (parsed as StoredDraft)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+export interface ExpiringDraftStoreOptions {
+  storage: DraftStorage;
+  retentionDays: number;
+  now?: () => number;
+}
+
+/**
+ * A {@link DraftStore} over a synchronous key-value storage, each draft
+ * dropped `retentionDays` after its last write. Expired drafts are swept when
+ * the store is created, so a pull request never opened again does not keep
+ * its drafts forever. Every access is guarded: storage that throws (full,
+ * blocked site data) loses the draft, never the editor.
+ */
+export const createExpiringDraftStore = ({
+  storage,
+  retentionDays,
+  now = Date.now,
+}: ExpiringDraftStoreOptions): DraftStore => {
+  const isExpired = (draft: StoredDraft): boolean =>
+    now() - draft.savedAt > retentionDays * dayMs;
+
+  try {
+    const keys = Array.from({ length: storage.length }, (_, index) =>
+      storage.key(index),
+    ).filter((key) => key?.startsWith(prefix) === true) as string[];
+    for (const key of keys) {
+      const draft = parse(storage.getItem(key));
+      if (draft === null || isExpired(draft)) storage.removeItem(key);
+    }
+  } catch {
+    // nothing swept: each read still drops what expired
+  }
+
+  const remove = (key: string): void => {
+    try {
+      storage.removeItem(`${prefix}${key}`);
+    } catch {
+      // already unreadable
+    }
+  };
+
+  return {
+    retentionDays,
+    read: (key) => {
+      try {
+        const draft = parse(storage.getItem(`${prefix}${key}`));
+        if (draft === null) return undefined;
+        if (isExpired(draft)) {
+          remove(key);
+          return undefined;
+        }
+        return draft.value;
+      } catch {
+        return undefined;
+      }
+    },
+    write: (key, value) => {
+      try {
+        storage.setItem(
+          `${prefix}${key}`,
+          JSON.stringify({ savedAt: now(), value } satisfies StoredDraft),
+        );
+      } catch {
+        // the draft lives as long as the screen
+      }
+    },
+    remove,
+  };
+};

package/src/services/formatDataAge.ts

@@ -0,0 +1,12 @@
+import type { IsoDateTime } from "@reviewflow/sdk";
+
+/**
+ * Static on purpose: the line is read when the board is looked at, and a ticking
+ * re-render would cost a timer per button to say the same thing a minute later.
+ */
+export const formatDataAge = (date: IsoDateTime): string => {
+  const then = new Date(date);
+  return then.toDateString() === new Date().toDateString()
+    ? then.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })
+    : then.toLocaleString();
+};

package/src/services/formatRelativeDate.ts

@@ -0,0 +1,56 @@
+/**
+ * A past date the way the operator says it: "today 14:32", "yesterday 09:10",
+ * "last Monday 16:05", then "12 Oct, 14:32" — and the year once it is not this
+ * one. The boards read dates to answer "is this from this morning or last
+ * week", which a full timestamp makes them work out.
+ *
+ * Calendar days in the machine's own time zone, not 24-hour spans: 23:50
+ * yesterday is "yesterday" at 00:10. The time and the month follow the
+ * locale; the words are the app's, which is in English.
+ */
+
+const dayMs = 24 * 60 * 60 * 1000;
+
+/** how many days back the weekday alone still names the day without doubt */
+const weekdayReach = 6;
+
+const startOfDay = (date: Date): number =>
+  new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+
+/** Whole calendar days from `date` to `now`; negative for a future date. */
+const calendarDaysAgo = (date: Date, now: Date): number =>
+  Math.round((startOfDay(now) - startOfDay(date)) / dayMs);
+
+export interface FormatRelativeDateOptions {
+  now?: Date;
+  /** a BCP 47 tag; the runtime's own when absent */
+  locale?: string;
+}
+
+export const formatRelativeDate = (
+  value: Date | string,
+  { now = new Date(), locale }: FormatRelativeDateOptions = {},
+): string => {
+  const date = typeof value === "string" ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) return "unknown date";
+
+  const time = date.toLocaleTimeString(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+  const days = calendarDaysAgo(date, now);
+
+  if (days === 0) return `today ${time}`;
+  if (days === 1) return `yesterday ${time}`;
+  if (days > 1 && days <= weekdayReach) {
+    const weekday = date.toLocaleDateString("en", { weekday: "long" });
+    return `last ${weekday} ${time}`;
+  }
+
+  const day = date.toLocaleDateString(locale, {
+    day: "numeric",
+    month: "short",
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+  });
+  return `${day}, ${time}`;
+};

package/src/services/githubImages.tsx

@@ -0,0 +1,33 @@
+import type { PullRequestImageProxies } from "@reviewflow/sdk";
+import { createContext, use } from "react";
+
+/**
+ * The camo urls of the pull request's bodies, by the url each body wrote:
+ * an image is loaded through GitHub's proxy, so its host never learns who
+ * read the pull request nor when.
+ */
+export const GithubImagesContext = createContext<PullRequestImageProxies>({});
+
+const githubHost = /(?:^|\.)(?:github\.com|githubusercontent\.com)$/;
+
+/**
+ * Where to load an image from: its camo url, or the image itself when GitHub
+ * hosts it (an attachment); null for any other host, whose image is linked
+ * rather than loaded.
+ */
+export const imageSourceOf = (
+  src: string,
+  proxies: PullRequestImageProxies,
+): string | null => {
+  const proxied = proxies[src];
+  if (proxied !== undefined) return proxied;
+  try {
+    const { protocol, hostname } = new URL(src);
+    return protocol === "https:" && githubHost.test(hostname) ? src : null;
+  } catch {
+    return null;
+  }
+};
+
+export const useGithubImages = (): PullRequestImageProxies =>
+  use(GithubImagesContext);