@reviewflow/ui 0.0.0-stage → 6.21.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Christophe Hurpeau <302891+christophehurpeau@users.noreply.github.com> (https://christophe.hurpeau.com)
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted, provided that the
+above copyright notice and this permission notice appear in all
+copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
+PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @reviewflow/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native pull request screens from the
+[reviewflow](https://github.com/christophehurpeau/reviewflow) local app:
+conversation, checks, commits, files and diff, review and edits, plus the pull
+request board. Built on [alouette](https://github.com/christophehurpeau/alouette)
+(nativewind / tailwind), web first.
+
+## Install
+
+```sh
+npm install @reviewflow/ui @reviewflow/sdk
+```
+
+Peer dependencies your app provides: `alouette` `^25.0.0` (and what it
+requires: `alouette-icons`, `nativewind`, `tailwindcss`, `react-native-svg`),
+`react` `^19.2.3` and `react-native`. On web, `react-dom` too.
+
+## Shipped as sources
+
+There is no build: every export resolves to a `.ts` / `.tsx` file under `src/`,
+transformed by your bundler like your own files.
+
+| Import                            | What                                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `@reviewflow/ui`                  | `PullRequestScreen`, its panels, the board, editors, data source and slot providers          |
+| `@reviewflow/ui/diff-worker-pool` | `DiffWorkerPool`: shiki highlighting in web workers (`browser` condition), a no-op elsewhere |
+
+- **Metro** (Expo): nothing to configure beyond alouette's own
+  `withAlouetteConfig`; metro transforms TypeScript in `node_modules` and bundles
+  the diff worker from its `new Worker(new URL(...))` call.
+- **Tailwind**: classes are only emitted for files tailwind scans. Add this
+  package's sources to your css entry, next to alouette's:
+
+  ```css
+  @import "alouette/core.css";
+  @source "../node_modules/@reviewflow/ui/src/**/*.{ts,tsx}";
+  ```
+
+  The path is relative to the css file; adjust it to where `node_modules` is.
+
+- **TypeScript**: the sources import with a `.ts` extension, so set
+  `"allowImportingTsExtensions": true`. Your app's own ambient types must
+  cover what the sources rely on: `react-native-css/types` (`className` on
+  React Native components, which the nativewind setup already adds) and a
+  `declare module "*.css";`.
+- `sideEffects` lists `*.css`: the editors import their stylesheet, and a
+  tree-shaking bundler must keep it.
+
+## Wiring
+
+The screens read nothing on their own: you provide a data source.
+
+```tsx
+import { AlouetteProvider } from "alouette";
+import type { PullRequestDataSource } from "@reviewflow/ui";
+import {
+  PullRequestDataSourceProvider,
+  PullRequestScreen,
+} from "@reviewflow/ui";
+
+const dataSource: PullRequestDataSource = {
+  usePart, // detail, checks, timeline, commits, files: a read state per part
+  useCandidates,
+  useRevisions,
+  useDiff,
+  useDiffs,
+  readFileAtSha,
+  edit,
+  reload,
+  // optional: useSummary, useRepositoryAttachment, useReviewflowPr, useReadingOrder, useImpacts
+};
+
+<AlouetteProvider themeVariables={themeVariables}>
+  <PullRequestDataSourceProvider value={dataSource}>
+    <PullRequestScreen
+      ownerRepo="octocat/hello-world"
+      number={1}
+      tab={tab}
+      onTabChange={setTab}
+    />
+  </PullRequestDataSourceProvider>
+</AlouetteProvider>;
+```
+
+Every hook answers with a `PullRequestReadState` (`value`, `cached`,
+`reading`, `error`); the payload types come from `@reviewflow/sdk`, so a
+source is usually `fetchPullRequestPart` and `readPullRequestDiff` from the sdk
+behind your own cache and server. The board takes a `BoardDataSource`
+(`useBoard`, `useReviewflowStatus`, `refresh`) through
+`BoardDataSourceProvider`. `PullRequestSlotsProvider` (or the `slots` prop)
+replaces the markdown editor or adds an action to the "no checkout" notice.
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@reviewflow/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "6.21.0",
+  "description": "react-native pull request screen components. Consumed as SOURCES (no build): exports resolve `default` to ./src/index.ts, which metro transforms like the app's own files; the consuming app's css must @source this package's src so tailwind keeps its classes.",
+  "keywords": [
+    "alouette",
+    "code-review",
+    "expo",
+    "github",
+    "pull-request",
+    "react-native",
+    "reviewflow"
+  ],
+  "homepage": "https://github.com/christophehurpeau/reviewflow",
+  "bugs": {
+    "url": "https://github.com/christophehurpeau/reviewflow/issues"
+  },
+  "license": "ISC",
+  "author": "Christophe Hurpeau <302891+christophehurpeau@users.noreply.github.com> (https://christophe.hurpeau.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/christophehurpeau/reviewflow.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.stories.tsx",
+    "!src/stories",
+    "!src/board/fixtures.ts",
+    "!src/board/mockDataSource.tsx"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./diff-worker-pool": {
+      "types": "./src/components/branch-diff/diff-worker-pool.tsx",
+      "browser": "./src/components/branch-diff/diff-worker-pool.web.tsx",
+      "default": "./src/components/branch-diff/diff-worker-pool.tsx"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "pnpm run lint:oxlint && pnpm run lint:eslint",
+    "lint:eslint": "pnpm --dir '../..' exec eslint --quiet 'packages/ui'",
+    "lint:oxlint": "pnpm --dir '../..' exec oxlint --quiet 'packages/ui'",
+    "tsc": "tsc"
+  },
+  "dependencies": {
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.11.1",
+    "@codemirror/lang-css": "6.3.1",
+    "@codemirror/lang-html": "6.4.12",
+    "@codemirror/lang-javascript": "6.2.5",
+    "@codemirror/lang-json": "6.0.2",
+    "@codemirror/lang-markdown": "6.5.2",
+    "@codemirror/lang-yaml": "6.1.3",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/search": "6.7.2",
+    "@codemirror/state": "6.7.5",
+    "@codemirror/view": "6.43.12",
+    "@lezer/common": "1.5.2",
+    "@lezer/highlight": "1.2.3",
+    "@lezer/markdown": "1.7.2",
+    "@pierre/diffs": "1.5.2",
+    "@reviewflow/sdk": "workspace:*",
+    "@tanstack/markdown": "0.0.13",
+    "alouette-icons": "12.0.0",
+    "gemoji": "8.1.0",
+    "htmlparser2": "12.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react-native": "10.6.0",
+    "@types/react": "19.2.18",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "alouette": "25.0.1",
+    "react": "19.2.8",
+    "react-native": "0.86.2",
+    "react-native-safe-area-context": "5.8.0",
+    "react-native-svg": "15.15.5",
+    "storybook": "10.6.5",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  },
+  "peerDependencies": {
+    "alouette": "^25.0.0",
+    "react": "^19.2.3",
+    "react-native": "*",
+    "react-native-svg": "*"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

package/src/board/bucket-section.tsx

@@ -0,0 +1,94 @@
+import type { PullRequestRef, ReviewflowBoardBucket } from "@reviewflow/sdk";
+import type { Accent, SVGIconElement } from "alouette";
+import { SectionTitle, Text, View } from "alouette";
+import { ArrowsClockwiseRegularIcon } from "alouette-icons/phosphor-icons/ArrowsClockwise";
+import { ChatCircleTextRegularIcon } from "alouette-icons/phosphor-icons/ChatCircleText";
+import { EyeRegularIcon } from "alouette-icons/phosphor-icons/Eye";
+import { GitMergeRegularIcon } from "alouette-icons/phosphor-icons/GitMerge";
+import { GitPullRequestRegularIcon } from "alouette-icons/phosphor-icons/GitPullRequest";
+import { PencilSimpleLineRegularIcon } from "alouette-icons/phosphor-icons/PencilSimpleLine";
+import { UserPlusRegularIcon } from "alouette-icons/phosphor-icons/UserPlus";
+import { UsersRegularIcon } from "alouette-icons/phosphor-icons/Users";
+import type { ReactNode } from "react";
+import type { BoardRowInfo } from "./pull-request-row.tsx";
+import { PullRequestRow } from "./pull-request-row.tsx";
+
+/**
+ * Glyphs and accents for the buckets reviewflow ships today, in the pull
+ * request badge's colours where they mean the same thing. A bucket it adds
+ * later gets the generic glyph and no accent — its title is still reviewflow's.
+ */
+const icons: Partial<Record<string, SVGIconElement>> = {
+  "re-requested-reviews": <ArrowsClockwiseRegularIcon />,
+  "requested-reviews": <EyeRegularIcon />,
+  "ready-to-merge": <GitMergeRegularIcon />,
+  "changes-requested": <ChatCircleTextRegularIcon />,
+  "opened-missing-review-request": <UserPlusRegularIcon />,
+  drafts: <PencilSimpleLineRegularIcon />,
+  "waiting-for-review": <UsersRegularIcon />,
+};
+
+const accents: Partial<Record<string, Accent>> = {
+  "re-requested-reviews": "warning",
+  "requested-reviews": "warning",
+  "ready-to-merge": "success",
+  "changes-requested": "danger",
+  "opened-missing-review-request": "warning",
+  "waiting-for-review": "info",
+};
+
+export interface BoardBucketSectionProps {
+  bucket: ReviewflowBoardBucket;
+  groupKey: string;
+  viewer: string | null;
+  onOpenPullRequest: (ref: PullRequestRef) => void;
+  renderRowExtra?: (row: BoardRowInfo) => ReactNode;
+  /** Replaces the glyph looked up from a reviewflow bucket key: an app's own section has none. */
+  icon?: SVGIconElement;
+  /** Replaces the accent looked up from a reviewflow bucket key. */
+  accent?: Accent;
+}
+
+/**
+ * One reviewflow bucket on the screen ground: its title, its rows, and its size
+ * in reviewflow when the pages read stop short of it.
+ */
+export function BoardBucketSection({
+  bucket,
+  groupKey,
+  viewer,
+  onOpenPullRequest,
+  renderRowExtra,
+  icon,
+  accent,
+}: BoardBucketSectionProps): ReactNode {
+  const shown = bucket.prs.length;
+
+  return (
+    <View className="gap-xs">
+      <SectionTitle
+        level={3}
+        icon={icon ?? icons[bucket.key] ?? <GitPullRequestRegularIcon />}
+        accent={accent ?? accents[bucket.key]}
+      >
+        {bucket.title}
+      </SectionTitle>
+      <View className="gap-xs">
+        {bucket.prs.map((pr) => (
+          <PullRequestRow
+            key={pr.id}
+            row={{ pr, bucketKey: bucket.key, groupKey }}
+            viewer={viewer}
+            renderRowExtra={renderRowExtra}
+            onOpenPullRequest={onOpenPullRequest}
+          />
+        ))}
+      </View>
+      {bucket.total > shown ? (
+        <Text className="text-sm text-muted">
+          {`Showing ${String(shown)} of ${String(bucket.total)}`}
+        </Text>
+      ) : null}
+    </View>
+  );
+}

package/src/board/dataSource.ts

@@ -0,0 +1,44 @@
+import type {
+  ReviewflowBoardResponse,
+  ReviewflowConnectionStatus,
+} from "@reviewflow/sdk";
+import { createContext, use } from "react";
+
+/**
+ * Where a read is at: `value` is the newest answer held, `null` until the
+ * first; `cached` says it is older than the request being answered; `reading`
+ * that the source is reading now; `error` why the last read failed (`value`
+ * may still hold an older answer).
+ */
+export interface BoardReadState<T> {
+  value: T | null;
+  reading: boolean;
+  error: string | null;
+  cached?: boolean;
+}
+
+/**
+ * What the board reads through. The app provides one with
+ * {@link BoardDataSourceProvider}; the components never reach for a network or
+ * a cache themselves. Hooks follow the rules of hooks.
+ */
+export interface BoardDataSource {
+  /** The board; the source keeps it current (live events) and re-renders on change. */
+  useBoard: () => BoardReadState<ReviewflowBoardResponse>;
+  /** Whether a reviewflow token is configured. `value` is null until known. */
+  useReviewflowStatus: () => BoardReadState<ReviewflowConnectionStatus>;
+  /** Reads the board from reviewflow again; never rejects, a failure is `useBoard().error`. */
+  refresh: () => Promise<void>;
+}
+
+const BoardDataSourceContext = createContext<BoardDataSource | null>(null);
+
+export const BoardDataSourceProvider = BoardDataSourceContext.Provider;
+
+export const useBoardDataSource = (): BoardDataSource => {
+  const source = use(BoardDataSourceContext);
+  if (source === null) {
+    throw new Error("useBoardDataSource needs a BoardDataSourceProvider");
+  }
+  return source;
+};

package/src/board/facts.ts

@@ -0,0 +1,183 @@
+import type { ReviewflowBoardPr, ReviewflowPrChanges } from "@reviewflow/sdk";
+import type { FormatRelativeDateOptions } from "../services/formatRelativeDate.ts";
+import { formatRelativeDate } from "../services/formatRelativeDate.ts";
+
+/**
+ * What reviewflow's own board row says about a pull request, in its wording so
+ * the two boards read the same. The status line comes in three parts by how
+ * loudly each is shown: what blocks the merge, changes requested, the rest.
+ */
+
+export const maxFailedCheckNames = 9;
+
+/** Where a row is shown, which decides what it leaves to its bucket's title. */
+export interface ReviewflowRowContext {
+  bucketKey: string;
+  groupKey: string;
+  /** the token's login, named "you" */
+  viewer: string | null;
+}
+
+/** the buckets whose title already says whether the checks pass */
+const bucketsSilentOnPassedChecks = new Set(["changes-requested", "drafts"]);
+/** the bucket whose title already says every reviewer was asked again */
+const reRequestedBucket = "re-requested-reviews";
+/** someone else's pull request requests a review, the operator's awaits one */
+const requestingAttentionGroup = "requesting-attention";
+
+const counted = (count: number, one: string, many: string): string =>
+  `${String(count)} ${count === 1 ? one : many}`;
+
+const people = (logins: string[], viewer: string | null): string =>
+  logins.map((login) => (login === viewer ? "you" : `@${login}`)).join(", ");
+
+const failedChecksText = ({
+  checksConclusion,
+  failedChecks,
+}: Pick<ReviewflowBoardPr, "checksConclusion" | "failedChecks">):
+  | string
+  | null => {
+  if (failedChecks.length === 0) {
+    return checksConclusion === "failed" ? "checks failed" : null;
+  }
+  const names = failedChecks.slice(0, maxFailedCheckNames).join(", ");
+  const remaining = failedChecks.length - maxFailedCheckNames;
+  const more = remaining > 0 ? ` +${String(remaining)}` : "";
+  return `${failedChecks.length === 1 ? "check" : "checks"} failed: ${names}${more}`;
+};
+
+/**
+ * Failing checks (after reviewflow's allowed-to-fail rules, by name), a failed
+ * pr lint and a merge conflict; null when nothing blocks.
+ */
+export const reviewflowPrFailure = (
+  pr: Pick<
+    ReviewflowBoardPr,
+    "checksConclusion" | "failedChecks" | "lintFailed" | "mergeable"
+  >,
+): string | null => {
+  const parts = [
+    failedChecksText(pr),
+    pr.lintFailed ? "pr lint failed" : null,
+    pr.mergeable === "conflicting" ? "conflicts" : null,
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" · ");
+};
+
+export const reviewflowPrChangesRequested = (
+  { changesRequestedBy }: Pick<ReviewflowBoardPr, "changesRequestedBy">,
+  viewer: string | null,
+): string | null =>
+  changesRequestedBy.length === 0
+    ? null
+    : `changes requested by ${people(changesRequestedBy, viewer)}`;
+
+const checksProgressText = (
+  {
+    checksConclusion,
+    checksRunning,
+  }: Pick<ReviewflowBoardPr, "checksConclusion" | "checksRunning">,
+  bucketKey: string,
+): string | null => {
+  if (checksRunning > 0) {
+    return `${counted(checksRunning, "check", "checks")} running`;
+  }
+  return checksConclusion === "passed" &&
+    !bucketsSilentOnPassedChecks.has(bucketKey)
+    ? "checks passed"
+    : null;
+};
+
+const awaitedText = (
+  {
+    requestedReviewers,
+    reRequestedReviewers,
+    requestedTeams,
+  }: Pick<
+    ReviewflowBoardPr,
+    "requestedReviewers" | "requestedTeams" | "reRequestedReviewers"
+  >,
+  { bucketKey, groupKey, viewer }: ReviewflowRowContext,
+): string | null => {
+  const reviewers = [
+    ...requestedReviewers,
+    ...(bucketKey === reRequestedBucket ? [] : reRequestedReviewers),
+  ];
+  if (reviewers.length === 0 && requestedTeams.length === 0) return null;
+  const verb = groupKey === requestingAttentionGroup ? "requested" : "awaiting";
+  const awaited = [
+    ...(reviewers.length === 0 ? [] : [people(reviewers, viewer)]),
+    ...requestedTeams.map((team) => `#${team}`),
+  ];
+  return `${verb} ${awaited.join(", ")}`;
+};
+
+/** running or passed checks, approvals, open threads, awaited reviewers */
+export const reviewflowPrProgress = (
+  pr: Pick<
+    ReviewflowBoardPr,
+    | "approvedBy"
+    | "checksConclusion"
+    | "checksRunning"
+    | "requestedReviewers"
+    | "requestedTeams"
+    | "reRequestedReviewers"
+    | "unresolvedThreads"
+  >,
+  context: ReviewflowRowContext,
+): string | null => {
+  const parts = [
+    checksProgressText(pr, context.bucketKey),
+    pr.approvedBy.length === 0
+      ? null
+      : `approved by ${people(pr.approvedBy, context.viewer)}`,
+    pr.unresolvedThreads
+      ? counted(pr.unresolvedThreads, "unresolved thread", "unresolved threads")
+      : null,
+    awaitedText(pr, context),
+  ].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" · ");
+};
+
+/**
+ * "by @author", "assigned to @a", or both. An author who is their own only
+ * assignee is a byline, not an assignment; a pull request whose only person is
+ * the viewer names nobody.
+ */
+export const reviewflowPrOwners = (
+  { author, assignees }: Pick<ReviewflowBoardPr, "assignees" | "author">,
+  viewer: string | null,
+): string | null => {
+  const named = [...(author === null ? [] : [author]), ...assignees];
+  if (named.length === 0) return null;
+  if (viewer !== null && named.every((login) => login === viewer)) return null;
+
+  const byline = author === null ? null : `by ${people([author], viewer)}`;
+  if (assignees.length === 0) return byline;
+  const assignment = `assigned to ${people(assignees, viewer)}`;
+
+  if (author === null || !assignees.includes(author)) {
+    return byline === null ? assignment : `${byline} · ${assignment}`;
+  }
+  // naming every assignee already names the author among them
+  return assignees.length === 1 ? byline : assignment;
+};
+
+export const reviewflowPrFlowDate = (
+  { openedAt, approvedAt }: Pick<ReviewflowBoardPr, "approvedAt" | "openedAt">,
+  options?: FormatRelativeDateOptions,
+): string | null => {
+  if (approvedAt !== null) {
+    return `approved ${formatRelativeDate(approvedAt, options)}`;
+  }
+  return openedAt === null
+    ? null
+    : `opened ${formatRelativeDate(openedAt, options)}`;
+};
+
+export const formatPrChanges = ({
+  changedFiles,
+  additions,
+  deletions,
+}: ReviewflowPrChanges): string =>
+  `${counted(changedFiles, "file", "files")} +${String(additions)} −${String(deletions)}`;

package/src/board/index.ts

@@ -0,0 +1,12 @@
+export type { BoardDataSource, BoardReadState } from "./dataSource.ts";
+export { BoardDataSourceProvider, useBoardDataSource } from "./dataSource.ts";
+export type {
+  PullRequestBoardExtraSection,
+  PullRequestBoardProps,
+} from "./pull-request-board.tsx";
+export {
+  PullRequestBoard,
+  extraSectionGroupKey,
+} from "./pull-request-board.tsx";
+export type { BoardRowInfo, PullRequestRowProps } from "./pull-request-row.tsx";
+export { PullRequestRow } from "./pull-request-row.tsx";