@gogitcms/design-system 0.16.0-next.2 → 0.16.0-next.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.16.0-next.2",
+  "version": "0.16.0-next.4",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "// exports": "The root entry is the react-native source the SPAs, desktop app and mobile app consume. ./web is the plain-DOM build for server-rendered surfaces (the Astro docs site) that don't run react-native-web, and ./css ships the tokens as custom properties. The trailing wildcard keeps deep paths resolvable — plugin bundling and the Vite aliases reach into src/ directly.",

package/src/__tests__/ContentBrowser.history.test.tsx

@@ -0,0 +1,179 @@
+import React from "react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection } from "../components/ContentBrowser";
+import type { DocumentVersion, HistoryApi } from "../history";
+import type { DocumentChange } from "../components/ChangeDetail";
+
+// Force the desktop layout (jsdom reports width 0 → mobile otherwise).
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "posts", label: "Posts", icon: "newspaper" }] },
+];
+
+const entry: CmsEntry = {
+  id: "doc-1",
+  path: "posts/hello.md",
+  title: "Hello",
+  body: "",
+  fields: [{ name: "title", type: "string", value: "Hello" }],
+};
+
+const published: DocumentVersion = {
+  sha: "9f2c1abcdef",
+  shortSha: "9f2c1ab",
+  message: "Publish the post\n\nA body the list has no room for.",
+  authorName: "Ada",
+  authoredAt: "2026-03-01T12:00:00Z",
+  url: "https://github.com/acme/site/commit/9f2c1ab",
+  filesChanged: 3,
+};
+
+const drafted: DocumentVersion = {
+  sha: "3b7de1098877",
+  shortSha: "3b7de10",
+  message: "Draft the post",
+  authorName: "Ada",
+  authoredAt: "2026-02-01T12:00:00Z",
+  url: "https://github.com/acme/site/commit/3b7de10",
+  filesChanged: 1,
+};
+
+const draftedDetail: DocumentChange = {
+  path: "posts/hello.md",
+  status: "M",
+  label: "Hello",
+  added: 1,
+  removed: 1,
+  fields: [{ name: "status", kind: "changed", before: "draft", after: "published" }],
+};
+
+function makeApi(over: Partial<HistoryApi> = {}): HistoryApi {
+  return {
+    list: jest.fn(async () => [published, drafted]),
+    get: jest.fn(async () => draftedDetail),
+    ...over,
+  };
+}
+
+function renderBrowser(history?: HistoryApi) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="posts"
+        onSelectNav={jest.fn()}
+        entries={[entry]}
+        selectedEntryId={entry.id}
+        onSelectEntry={jest.fn()}
+        userInitials="ED"
+        history={history}
+      />,
+    ),
+  );
+}
+
+// The affordance only exists where history does. A deployment with no provider
+// should show no button at all rather than one that errors when pressed.
+test("no history seam means no history button", () => {
+  renderBrowser(undefined);
+  expect(screen.queryByTestId("document-history-toggle")).not.toBeInTheDocument();
+});
+
+test("the history button gives the document's column over to the version browser", async () => {
+  renderBrowser(makeApi());
+
+  // The editor form is what a column shows until history is asked for.
+  expect(screen.getByTestId("column-scroll")).toBeInTheDocument();
+  expect(screen.queryByTestId("document-history")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  expect(await screen.findByTestId("document-history")).toBeInTheDocument();
+  // The form is gone — history takes the column's body, not a slice of it.
+  expect(screen.queryByTestId("column-scroll")).not.toBeInTheDocument();
+});
+
+test("the version list shows each commit's subject, author, sha and file count", async () => {
+  renderBrowser(makeApi());
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  expect(await screen.findByTestId("version-9f2c1ab")).toBeInTheDocument();
+  expect(screen.getByTestId("version-3b7de10")).toBeInTheDocument();
+
+  // The subject only — the message body would push every other row off screen.
+  expect(screen.getByText("Publish the post")).toBeInTheDocument();
+  expect(screen.queryByText(/A body the list has no room for/)).not.toBeInTheDocument();
+
+  expect(screen.getByText("3 files")).toBeInTheDocument();
+  // Singular, because "1 files" is the kind of thing people notice.
+  expect(screen.getByText("1 file")).toBeInTheDocument();
+});
+
+// An empty diff beside a full list is a second click for nothing.
+test("opening history selects the newest version and loads its diff", async () => {
+  const api = makeApi();
+  renderBrowser(api);
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  await waitFor(() => expect(api.get).toHaveBeenCalledWith({ documentId: "doc-1", sha: published.sha }));
+  expect(await screen.findByTestId("change-detail")).toBeInTheDocument();
+});
+
+test("selecting a version loads that version's document and diff", async () => {
+  const api = makeApi();
+  renderBrowser(api);
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  fireEvent.click(await screen.findByTestId("version-3b7de10"));
+
+  await waitFor(() => expect(api.get).toHaveBeenCalledWith({ documentId: "doc-1", sha: drafted.sha }));
+  // The version's value on the left of the diff, the current one on the right.
+  expect(await screen.findByText("draft")).toBeInTheDocument();
+  expect(screen.getByText("published")).toBeInTheDocument();
+});
+
+// A document with no commits is a real and common state — one created in the
+// CMS and not yet exported. It must not read as a failure.
+test("a document with no commits explains itself", async () => {
+  renderBrowser(makeApi({ list: jest.fn(async () => []) }));
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  expect(await screen.findByTestId("history-empty")).toBeInTheDocument();
+  expect(screen.queryByTestId("history-error")).not.toBeInTheDocument();
+});
+
+test("a failed history says so rather than showing an empty list", async () => {
+  renderBrowser(makeApi({ list: jest.fn(async () => { throw new Error("GitHub is unreachable"); }) }));
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  expect(await screen.findByText("GitHub is unreachable")).toBeInTheDocument();
+  expect(screen.queryByTestId("history-empty")).not.toBeInTheDocument();
+});
+
+test("the button toggles back, returning the column to the editor", async () => {
+  renderBrowser(makeApi());
+  const toggle = screen.getByTestId("document-history-toggle");
+
+  fireEvent.click(toggle);
+  expect(await screen.findByTestId("document-history")).toBeInTheDocument();
+
+  fireEvent.click(toggle);
+  expect(screen.queryByTestId("document-history")).not.toBeInTheDocument();
+  expect(screen.getByTestId("column-scroll")).toBeInTheDocument();
+});
+
+test("the pane's own close control leaves history too", async () => {
+  renderBrowser(makeApi());
+  fireEvent.click(screen.getByTestId("document-history-toggle"));
+
+  fireEvent.click(await screen.findByTestId("history-close"));
+  expect(screen.queryByTestId("document-history")).not.toBeInTheDocument();
+});

package/src/__tests__/ProtectedBranchModal.test.tsx

@@ -0,0 +1,68 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ProtectedBranchModal } from "../components/ProtectedBranchModal";
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+const base = { branch: "main", onCreate: () => {}, onCancel: () => {} };
+
+test("it names the branch, the document, and offers the one remedy", () => {
+  render(wrap(<ProtectedBranchModal {...base} documentLabel="Hello world" />));
+
+  const modal = screen.getByTestId("protected-branch-modal");
+  expect(modal).toHaveTextContent("This branch is protected");
+  expect(modal).toHaveTextContent("main");
+  expect(modal).toHaveTextContent("Hello world");
+  expect(modal).toHaveTextContent("Branched from main");
+  expect(screen.getByTestId("protected-branch-submit")).toHaveTextContent("Create branch and save");
+});
+
+test("the suggested name prefills the field and submits", () => {
+  const onCreate = jest.fn();
+  render(wrap(<ProtectedBranchModal {...base} suggestedName="edit/hello" onCreate={onCreate} />));
+
+  expect(screen.getByTestId("protected-branch-name")).toHaveValue("edit/hello");
+  fireEvent.click(screen.getByTestId("protected-branch-submit"));
+  expect(onCreate).toHaveBeenCalledWith("edit/hello");
+});
+
+// The author's own name wins: a suggestion arriving late (the host resolves the
+// document a render after the modal opens) must not overwrite what they typed.
+test("a late suggestion does not overwrite a typed name", () => {
+  const { rerender } = render(wrap(<ProtectedBranchModal {...base} />));
+  fireEvent.change(screen.getByTestId("protected-branch-name"), { target: { value: "mine" } });
+  rerender(wrap(<ProtectedBranchModal {...base} suggestedName="edit/hello" />));
+  expect(screen.getByTestId("protected-branch-name")).toHaveValue("mine");
+});
+
+test("an empty name cannot be submitted", () => {
+  const onCreate = jest.fn();
+  render(wrap(<ProtectedBranchModal {...base} onCreate={onCreate} />));
+  fireEvent.click(screen.getByTestId("protected-branch-submit"));
+  expect(onCreate).not.toHaveBeenCalled();
+});
+
+// While the branch is being created there is no way out but forward: cancelling
+// mid-flight would abandon a save whose branch may already exist.
+test("busy disables both actions and hides the close control", () => {
+  const onCreate = jest.fn();
+  render(wrap(<ProtectedBranchModal {...base} suggestedName="edit/hello" busy onCreate={onCreate} />));
+
+  expect(screen.getByTestId("protected-branch-submit")).toHaveTextContent("Creating…");
+  expect(screen.queryByTestId("protected-branch-close")).not.toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("protected-branch-submit"));
+  expect(onCreate).not.toHaveBeenCalled();
+});
+
+test("the server's message is shown so a rejected name can be corrected", () => {
+  render(wrap(<ProtectedBranchModal {...base} error={`branch "edit/hello" already exists`} />));
+  expect(screen.getByTestId("protected-branch-error")).toHaveTextContent("already exists");
+});
+
+test("cancel dismisses", () => {
+  const onCancel = jest.fn();
+  render(wrap(<ProtectedBranchModal {...base} onCancel={onCancel} />));
+  fireEvent.click(screen.getByTestId("protected-branch-cancel"));
+  expect(onCancel).toHaveBeenCalledTimes(1);
+});

package/src/components/ChangeDetail.tsx

@@ -38,7 +38,15 @@ export type DocumentChange = {
   path: string;
   /** The base branch's path, for a rename. */
   previousPath?: string;
-  status: "A" | "M" | "D" | "R";
+  /**
+   * A/M/D/R are git's letters, so a branch comparison renders them untranslated.
+   * "U" (unchanged) has no place in a diff of two branches — an unchanged
+   * document is not a change — but it is a real answer for a document version:
+   * the newest commit in a document's history is usually still what the document
+   * is, and saying "Unchanged" is more useful than an empty diff with no
+   * explanation.
+   */
+  status: "A" | "M" | "D" | "R" | "U";
   label: string;
   /** Ordered to match the content model's schema, so it reads like the editor. */
   fields: FieldChange[];
@@ -86,6 +94,7 @@ const STATUS_LABEL: Record<DocumentChange["status"], string> = {
   M: "Modified",
   D: "Deleted",
   R: "Renamed",
+  U: "Unchanged",
 };
 
 /** Renders a field value the way the editor would show it, not as raw JSON. */

package/src/components/ContentBrowser.tsx

@@ -15,6 +15,7 @@ import { BranchMenu, type BranchRef } from "./BranchMenu";
 import { ProjectMenu, type ProjectRef } from "./ProjectMenu";
 import { ChangeDetail, type DocumentChange, type FieldConflict, type ConflictChoice } from "./ChangeDetail";
 import { ApplyChangesModal, type MergeProgress } from "./ApplyChangesModal";
+import { ProtectedBranchModal } from "./ProtectedBranchModal";
 import { NotificationBell, type NotificationItem } from "./Notifications";
 import {
   CollabInput,
@@ -33,6 +34,8 @@ import { MediaField, MediaProvider, DocumentPathProvider } from "./MediaField";
 import { MediaBrowser } from "./MediaBrowser";
 import { FormsBrowser } from "./FormsBrowser";
 import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, type FormsApi } from "../forms";
+import { type HistoryApi } from "../history";
+import { DocumentHistory } from "./DocumentHistory";
 import {
   MEDIA_NAV_KEY,
   mediaNavKey,
@@ -339,6 +342,14 @@ export type ContentBrowserProps = {
   // Forms data seam, the same split (docs/forms.md §10.2). Omitted → the Forms
   // surface never renders, which is what a config declaring no forms looks like.
   forms?: FormsApi;
+
+  // Document-history data seam, the same split again: the DS owns the version
+  // browser and its ephemeral state, the host owns fetching. Provided → an open
+  // document's header gains a history button, and pressing it gives that
+  // column's body over to the version browser. Omitted → no affordance at all,
+  // which is what a deployment with no provider (local mode, desktop) gets: a
+  // feature the user never sees beats one that errors when clicked.
+  history?: HistoryApi;
   // The selected submission's id, and the reporter for taps — bound to the URL
   // by the host exactly as document selection is.
   selectedSubmissionId?: string | null;
@@ -478,6 +489,19 @@ export type ContentBrowserProps = {
   changeRequestOpen?: boolean;
   changeRequestUrl?: string;
   creatingChangeRequest?: boolean;
+
+  // Protected-branch save prompt. The server refuses a save to a branch the
+  // provider protects; the host catches that, sets protectedBranch to the branch
+  // name, and this modal offers the one thing that resolves it — a branch to put
+  // the edit on. onCreateBranchAndSave receives the name; the host creates the
+  // branch and applies the pending edit to it in one server call.
+  protectedBranch?: string;
+  protectedBranchDocument?: string;
+  protectedBranchSuggestedName?: string;
+  creatingProtectedBranch?: boolean;
+  protectedBranchError?: string | null;
+  onCreateBranchAndSave?: (name: string) => void;
+  onCancelProtectedSave?: () => void;
   onCreateChangeRequest?: (explanation: string) => void;
   onViewChangeRequest?: () => void;
 
@@ -2567,6 +2591,7 @@ function EntryDetail({
   onMove,
   collectionPath,
   folderOptions,
+  history,
   active,
   onActivate,
   onCollapse,
@@ -2589,6 +2614,10 @@ function EntryDetail({
   collectionPath?: string;
   // Existing folders (relative to the glob base) offered by the move autocomplete.
   folderOptions?: string[];
+  // The document-history seam. Provided → a history button appears in this
+  // document's header and its column can show the version browser. Omitted →
+  // the header renders exactly as it did before history existed.
+  history?: HistoryApi;
   // Desktop columns: `active` marks the focused column (accent + header press
   // activates it via onActivate); onCollapse/onClose add the header rail/close
   // controls. All omitted on mobile → unchanged single-detail behavior.
@@ -2609,6 +2638,18 @@ function EntryDetail({
   const canRename = !readOnly && !!onRename;
   const canMove = !readOnly && !!onMove && glob.hierarchical;
   const [prompt, setPrompt] = useState<"rename" | "move" | null>(null);
+  // Whether this column is showing the version browser instead of the form.
+  // Deliberately per-column and ephemeral: history is something you open, read
+  // and close, so it lives and dies with the column rather than in the URL.
+  const [showHistory, setShowHistory] = useState(false);
+  // A column reused for another document (the "preview tab" behavior) must not
+  // carry the previous document's history view onto it — you asked to see that
+  // document, not this one's past.
+  const historyFor = useRef(entry.id);
+  if (historyFor.current !== entry.id) {
+    historyFor.current = entry.id;
+    if (showHistory) setShowHistory(false);
+  }
 
   // Both branches share one value map. The title+body branch is modeled as a
   // single body-source field so autosave logic is uniform.
@@ -2894,6 +2935,20 @@ function EntryDetail({
             document's own actions, while the menu holds the destructive and
             path-changing ones that should stay one level down. */}
         {documentActions?.(entry)}
+        {/* History is a read of this document, not a change to it, so it sits
+            out here with the other non-destructive actions rather than in the
+            menu beside Delete. It toggles: pressing it again returns the column
+            to the form. */}
+        {history ? (
+          <IconButton
+            name="history"
+            size="sm"
+            active={showHistory}
+            label={showHistory ? "Close history" : "Document history"}
+            onPress={() => setShowHistory((v) => !v)}
+            testID="document-history-toggle"
+          />
+        ) : null}
         {canRename || canMove || (canDelete && onDeleteEntry) ? (
           <DetailMenu
             onRename={canRename ? () => setPrompt("rename") : undefined}
@@ -2909,10 +2964,20 @@ function EntryDetail({
         ) : null}
       </View>
 
-      {/* Keyed by entry.id so controls (incl. the markdown editor) remount with
+      {/* History takes over the column's body, keeping its header: the header
+          is what says which document you are looking at, and it carries the
+          control that got you here and gets you back. */}
+      {showHistory && history ? (
+        <DocumentHistory
+          documentId={entry.id}
+          documentPath={entry.path}
+          history={history}
+          onClose={() => setShowHistory(false)}
+        />
+      ) : /* Keyed by entry.id so controls (incl. the markdown editor) remount with
           fresh initial values (and the scroll resets to top) when the selected
-          document changes. The header above stays put; only the body scrolls. */}
-      {hasFields ? (
+          document changes. The header above stays put; only the body scrolls. */
+      hasFields ? (
         // The document's path reaches media fields at any nesting depth through
         // context: a picker inside a group or a list item needs it to interpret
         // relative references, and drilling it through every level would touch
@@ -3567,9 +3632,28 @@ function ReadOnlyBanner({ notice, actionLabel, onAction }: { notice?: string; ac
   );
 }
 
-// ApplyModalOverlay renders the apply-changes / change-request modal as a
-// full-screen overlay. Shared by both layouts so the modal (and its "learn more"
-// change-request link) is reachable on mobile too.
+// ModalOverlays renders the browser's full-screen modals — apply changes /
+// change request, and the protected-branch save prompt. Shared by both layouts
+// so every modal is reachable on mobile too.
+function ModalOverlays(props: ContentBrowserProps) {
+  return (
+    <>
+      <ApplyModalOverlay {...props} />
+      {props.protectedBranch ? (
+        <ProtectedBranchModal
+          branch={props.protectedBranch}
+          documentLabel={props.protectedBranchDocument}
+          suggestedName={props.protectedBranchSuggestedName}
+          busy={props.creatingProtectedBranch}
+          error={props.protectedBranchError}
+          onCreate={props.onCreateBranchAndSave ?? (() => {})}
+          onCancel={props.onCancelProtectedSave ?? (() => {})}
+        />
+      ) : null}
+    </>
+  );
+}
+
 function ApplyModalOverlay(props: ContentBrowserProps) {
   if (!props.applyOpen) return null;
   return (
@@ -3937,6 +4021,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         <EntryDetail
           entry={col.entry}
           documentActions={props.documentActions}
+          history={props.history}
           onEntryDraft={props.onEntryDraft}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}
@@ -4066,7 +4151,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
   const readOnlyBanner = (
     <ReadOnlyBanner notice={props.readOnlyNotice} actionLabel={props.readOnlyNoticeActionLabel} onAction={props.onReadOnlyNoticeAction} />
   );
-  const applyModal = <ApplyModalOverlay {...props} />;
+  const modalOverlays = <ModalOverlays {...props} />;
 
   // The changes surface reuses the same three-pane model as Edit, so switching
   // between them doesn't relayout the screen — only what each pane contains
@@ -4119,7 +4204,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           conflicts={props.selectedConflicts}
           onResolveConflict={props.onResolveConflict}
         />
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4134,7 +4219,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         <Pane flex={1} testID="pane-plugin" scroll={false}>
           {props.contentSlot}
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4174,7 +4259,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: t.space(6) }}>
             <Text variant="body" color="tertiary" testID="forms-empty">Select a form</Text>
           </View>
-          {applyModal}
+          {modalOverlays}
         </AppShell>
       );
     }
@@ -4192,7 +4277,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             variant="desktop"
           />
         </Pane>
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4219,7 +4304,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
             <Text variant="body" color="tertiary" testID="media-sets-empty">Select a media collection</Text>
           </View>
         )}
-        {applyModal}
+        {modalOverlays}
       </AppShell>
     );
   }
@@ -4420,7 +4505,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           onClose={() => setMovePrompt(false)}
         />
       ) : null}
-      {applyModal}
+      {modalOverlays}
     </AppShell>
   );
 }
@@ -4496,7 +4581,7 @@ function MobileBrowser(props: ContentBrowserProps) {
   const readOnlyBanner = (
     <ReadOnlyBanner notice={props.readOnlyNotice} actionLabel={props.readOnlyNoticeActionLabel} onAction={props.onReadOnlyNoticeAction} />
   );
-  const applyModal = <ApplyModalOverlay {...props} />;
+  const modalOverlays = <ModalOverlays {...props} />;
 
   // Media drills the same way a collection does — nav → list → detail — so the
   // back arrow means the same thing at every level. Pressing Media lists the
@@ -4622,7 +4707,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         testID="mobile-shell"
         header={header}
         title={props.surface === "changes" ? "Changes" : "Content"}
-        overlay={applyModal}
+        overlay={modalOverlays}
       >
         {/* Edit / Changes surface toggle (fits its content) with the Apply button
             to its right on the changes surface. The read-only notice sits below. */}
@@ -4703,7 +4788,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         testID="mobile-entries"
         scroll={false}
         banner={readOnlyBanner}
-        overlay={applyModal}
+        overlay={modalOverlays}
         header={
           search.open ? (
             <SearchHeaderBar search={search} showFilter={facetFields.length > 0} />
@@ -4784,7 +4869,7 @@ function MobileBrowser(props: ContentBrowserProps) {
     <MobileScreen
       testID="mobile-entry"
       banner={readOnlyBanner}
-      overlay={applyModal}
+      overlay={modalOverlays}
       header={
         <>
           <IconButton name="chevronLeft" onPress={backToEntries} size="md" label="Back" />
@@ -4812,6 +4897,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         <EntryDetail
           entry={entry}
           documentActions={props.documentActions}
+          history={props.history}
           onEntryDraft={props.onEntryDraft}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}

package/src/components/DocumentHistory.tsx

@@ -0,0 +1,292 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { View, FlatList, Pressable, ActivityIndicator } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+import { Icon } from "./Icon";
+import { Badge } from "./primitives";
+import { ChangeDetail, type DocumentChange } from "./ChangeDetail";
+import { firstLine, relativeTime, type DocumentVersion, type HistoryApi } from "../history";
+
+/** How many versions a page holds. One page is one provider request. */
+const PAGE = 20;
+
+export type DocumentHistoryProps = {
+  /** The document whose past is being read. */
+  documentId: string;
+  /** Shown above the list, so a narrow column still says what it is looking at. */
+  documentPath: string;
+  history: HistoryApi;
+  /** Leaves history and returns the column to the editor. */
+  onClose: () => void;
+};
+
+/**
+ * DocumentHistory is the version browser that takes over a document's column:
+ * the versions on the right, and on the left the document as it was at the
+ * selected one, diffed against what it is now.
+ *
+ * It owns its own state — which version is selected, the pages loaded so far —
+ * because that state is ephemeral by design: history is a thing you open, read
+ * and close, not a place the editor navigates to. Nothing here survives closing
+ * the pane, and nothing about it is in the URL.
+ */
+export function DocumentHistory({ documentId, documentPath, history, onClose }: DocumentHistoryProps) {
+  const t = useTheme();
+
+  const [versions, setVersions] = useState<DocumentVersion[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [exhausted, setExhausted] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const [selected, setSelected] = useState<string | null>(null);
+  const [detail, setDetail] = useState<DocumentChange | undefined>(undefined);
+  const [loadingDetail, setLoadingDetail] = useState(false);
+  const [detailError, setDetailError] = useState<string | null>(null);
+
+  // Guards every async result against a document switch or an unmount: the pane
+  // is inside a column whose document can change under it, and a page that
+  // arrives after that would otherwise be listed as this document's history.
+  const liveFor = useRef(documentId);
+  useEffect(() => {
+    liveFor.current = documentId;
+    return () => {
+      liveFor.current = "";
+    };
+  }, [documentId]);
+
+  // First page. Selecting its newest version immediately is what makes the pane
+  // useful on open — an empty diff beside a full list is a second click for
+  // nothing.
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setVersions([]);
+    setExhausted(false);
+    setSelected(null);
+    setDetail(undefined);
+    history
+      .list({ documentId, limit: PAGE, offset: 0 })
+      .then((page) => {
+        if (cancelled || liveFor.current !== documentId) return;
+        setVersions(page);
+        setExhausted(page.length < PAGE);
+        if (page.length > 0) setSelected(page[0].sha);
+      })
+      .catch((e: unknown) => {
+        if (cancelled || liveFor.current !== documentId) return;
+        setError(messageOf(e));
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [documentId, history]);
+
+  const loadMore = useCallback(() => {
+    if (loading || loadingMore || exhausted) return;
+    setLoadingMore(true);
+    const offset = versions.length;
+    history
+      .list({ documentId, limit: PAGE, offset })
+      .then((page) => {
+        if (liveFor.current !== documentId) return;
+        // Offsets can overlap when the branch moves under a paging read, so
+        // fold by sha rather than appending blindly — a repeated version would
+        // otherwise be a duplicate React key and a second identical row.
+        setVersions((prev) => mergeBySha(prev, page));
+        setExhausted(page.length < PAGE);
+      })
+      .catch(() => {
+        // A failed page is not a failed history: what is already listed stays
+        // readable, and the end-of-list footer stops offering more.
+        setExhausted(true);
+      })
+      .finally(() => setLoadingMore(false));
+  }, [documentId, history, loading, loadingMore, exhausted, versions.length]);
+
+  // The selected version's document + diff.
+  useEffect(() => {
+    if (!selected) {
+      setDetail(undefined);
+      return;
+    }
+    let cancelled = false;
+    setLoadingDetail(true);
+    setDetailError(null);
+    history
+      .get({ documentId, sha: selected })
+      .then((d) => {
+        if (cancelled || liveFor.current !== documentId) return;
+        setDetail(d ?? undefined);
+        if (!d) setDetailError("This version could not be read.");
+      })
+      .catch((e: unknown) => {
+        if (cancelled || liveFor.current !== documentId) return;
+        setDetail(undefined);
+        setDetailError(messageOf(e));
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingDetail(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [documentId, history, selected]);
+
+  return (
+    <View testID="document-history" style={{ flex: 1, minHeight: 0, flexDirection: "row" }}>
+      {/* Left: the document at the selected version, annotated with what has
+          changed since. ChangeDetail is the changes surface's pane, used
+          unchanged — a version diff and a branch diff are the same question
+          asked of different pairs. */}
+      <View style={{ flex: 1, minWidth: 0 }}>
+        {detailError && !loadingDetail ? (
+          <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: t.space(6) }}>
+            <Text variant="body" color="tertiary" testID="history-detail-error">{detailError}</Text>
+          </View>
+        ) : (
+          <ChangeDetail
+            change={detail}
+            loading={loadingDetail}
+            emptyMessage={loading ? "Loading history…" : "Select a version"}
+          />
+        )}
+      </View>
+
+      {/* Right: the versions. */}
+      <View
+        style={{
+          width: 264,
+          borderLeftWidth: 1,
+          borderLeftColor: t.color.borderSubtle,
+          backgroundColor: t.color.surfaceSunken,
+          minHeight: 0,
+        }}
+      >
+        <View
+          style={{
+            height: t.layout.topbar,
+            paddingHorizontal: t.space(3),
+            flexDirection: "row",
+            alignItems: "center",
+            gap: t.space(2),
+            borderBottomWidth: 1,
+            borderBottomColor: t.color.borderSubtle,
+          }}
+        >
+          <Icon name="history" size={15} color={t.color.textSecondary} />
+          <Text variant="monoSm" numberOfLines={1} style={{ flex: 1 }}>History</Text>
+          <Pressable onPress={onClose} testID="history-close" hitSlop={8} style={{ padding: t.space(1) }}>
+            <Icon name="x" size={15} color={t.color.textTertiary} />
+          </Pressable>
+        </View>
+
+        {loading ? (
+          <View style={{ padding: t.space(4), alignItems: "center" }}>
+            <ActivityIndicator testID="history-loading" />
+          </View>
+        ) : error ? (
+          <View style={{ padding: t.space(4), gap: t.space(2) }}>
+            <Text variant="monoSm" color={t.color.diffDelFg} testID="history-error">{error}</Text>
+          </View>
+        ) : versions.length === 0 ? (
+          <View style={{ padding: t.space(4) }}>
+            <Text variant="monoSm" color="tertiary" testID="history-empty">
+              No commits yet for {documentPath}. A document saved in the CMS appears here once it has been pushed to git.
+            </Text>
+          </View>
+        ) : (
+          <FlatList
+            testID="history-list"
+            data={versions}
+            keyExtractor={(v) => v.sha}
+            style={{ flex: 1, minHeight: 0 }}
+            onEndReached={loadMore}
+            onEndReachedThreshold={0.4}
+            renderItem={({ item }) => (
+              <VersionRow
+                version={item}
+                selected={item.sha === selected}
+                onPress={() => setSelected(item.sha)}
+              />
+            )}
+            ListFooterComponent={
+              loadingMore ? (
+                <View style={{ padding: t.space(3), alignItems: "center" }}>
+                  <ActivityIndicator testID="history-loading-more" />
+                </View>
+              ) : exhausted ? (
+                // Why the list ends matters here: GitHub's commits API cannot
+                // follow a rename, so "that's all" can mean "that is where this
+                // path began" rather than "that is where the document began".
+                <View style={{ padding: t.space(3) }}>
+                  <Text variant="monoSm" color="tertiary" testID="history-end">
+                    End of history for this path. Commits from before a rename are not listed.
+                  </Text>
+                </View>
+              ) : null
+            }
+          />
+        )}
+      </View>
+    </View>
+  );
+}
+
+function VersionRow({
+  version,
+  selected,
+  onPress,
+}: {
+  version: DocumentVersion;
+  selected: boolean;
+  onPress: () => void;
+}) {
+  const t = useTheme();
+  return (
+    <Pressable
+      testID={`version-${version.shortSha}`}
+      onPress={onPress}
+      style={{
+        paddingHorizontal: t.space(3),
+        paddingVertical: t.space(3),
+        gap: t.space(1),
+        borderBottomWidth: 1,
+        borderBottomColor: t.color.borderSubtle,
+        backgroundColor: selected ? t.color.surfaceRaised : "transparent",
+        borderLeftWidth: 2,
+        borderLeftColor: selected ? t.color.borderActive : "transparent",
+      }}
+    >
+      <Text variant="sm" numberOfLines={2} weight={selected ? "medium" : undefined}>
+        {firstLine(version.message)}
+      </Text>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        <Text variant="monoSm" color="tertiary" numberOfLines={1} style={{ flex: 1 }}>
+          {version.authorName} · {relativeTime(version.authoredAt)}
+        </Text>
+      </View>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        <Badge label={version.shortSha} tone="neutral" />
+        <Text variant="monoSm" color="tertiary">
+          {version.filesChanged === 1 ? "1 file" : `${version.filesChanged} files`}
+        </Text>
+      </View>
+    </Pressable>
+  );
+}
+
+/** mergeBySha appends a page, dropping versions already listed. */
+function mergeBySha(prev: DocumentVersion[], page: DocumentVersion[]): DocumentVersion[] {
+  const seen = new Set(prev.map((v) => v.sha));
+  return [...prev, ...page.filter((v) => !seen.has(v.sha))];
+}
+
+function messageOf(e: unknown): string {
+  const err = e as { graphQLErrors?: { message?: string }[]; message?: string } | undefined;
+  return err?.graphQLErrors?.[0]?.message || err?.message || "Couldn’t load this document’s history.";
+}

package/src/components/ProtectedBranchModal.tsx

@@ -0,0 +1,136 @@
+import React, { useEffect, useState } from "react";
+import { View, Pressable } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+import { Icon } from "./Icon";
+import { Input } from "./Input";
+import { Button } from "./Button";
+
+export type ProtectedBranchModalProps = {
+  /** The protected branch the save was refused on. */
+  branch: string;
+  /** The document that could not be saved, for naming what is at stake. */
+  documentLabel?: string;
+  /** Prefills the field — the host derives it from the document. */
+  suggestedName?: string;
+  /** True while the branch is being created and the save applied. */
+  busy?: boolean;
+  /** The server's message, when the attempt failed. */
+  error?: string | null;
+  /** Create `name` from `branch` and save the pending edit onto it. */
+  onCreate: (name: string) => void;
+  /** Dismiss. The edit stays as an unsaved draft on the protected branch. */
+  onCancel: () => void;
+};
+
+/**
+ * Shown when a save is refused because the branch is protected.
+ *
+ * It is a prompt rather than an error banner because the refusal has exactly one
+ * remedy and the editor knows what it is: the work is intact, it just needs
+ * somewhere it can land. Presenting that as "here is a message, now go find the
+ * branch menu" would make the author reconstruct a plan the product already has.
+ *
+ * The draft is deliberately NOT discarded on cancel — a protected branch is
+ * often noticed mid-thought, and the author may want to keep writing and pick a
+ * branch name later. It stays in storage exactly as any other unsaved work does.
+ */
+export function ProtectedBranchModal({
+  branch, documentLabel, suggestedName, busy, error, onCreate, onCancel,
+}: ProtectedBranchModalProps) {
+  const t = useTheme();
+  const [name, setName] = useState(suggestedName ?? "");
+  // The suggestion is derived from the document, which the host may resolve a
+  // render after the modal opens. Adopted only while the field is untouched.
+  const [touched, setTouched] = useState(false);
+  useEffect(() => {
+    if (!touched && suggestedName) setName(suggestedName);
+  }, [suggestedName, touched]);
+
+  const trimmed = name.trim();
+  const submit = () => {
+    if (!trimmed || busy) return;
+    onCreate(trimmed);
+  };
+
+  return (
+    <View
+      testID="protected-branch-modal"
+      style={{
+        position: "absolute", top: 0, left: 0, right: 0, bottom: 0, zIndex: 50,
+        alignItems: "center", justifyContent: "center", padding: t.space(4),
+        backgroundColor: "rgba(0,0,0,0.45)",
+      }}
+    >
+      <View
+        style={{
+          width: 460, maxWidth: "100%", gap: t.space(4), padding: t.space(5),
+          borderRadius: t.radius.lg, borderWidth: 1, borderColor: t.color.borderDefault,
+          backgroundColor: t.color.surfaceRaised,
+        }}
+      >
+        <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between" }}>
+          <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+            <Icon name="lock" size={16} color={t.color.textSecondary} />
+            <Text variant="h3" weight="semibold">This branch is protected</Text>
+          </View>
+          {busy ? null : (
+            <Pressable
+              testID="protected-branch-close"
+              accessibilityRole="button"
+              accessibilityLabel="Cancel"
+              onPress={onCancel}
+              style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}
+            >
+              <Icon name="x" size={18} color={t.color.textSecondary} />
+            </Pressable>
+          )}
+        </View>
+
+        <Text variant="body" color="secondary">
+          {documentLabel
+            ? `${branch} doesn’t accept changes directly, so “${documentLabel}” can’t be saved to it. Name a branch to save it to instead — your edit lands there.`
+            : `${branch} doesn’t accept changes directly. Name a branch to save your edit to instead.`}
+        </Text>
+
+        <Input
+          label="New branch"
+          value={name}
+          onChangeText={(v) => { setTouched(true); setName(v); }}
+          onSubmitEditing={submit}
+          placeholder="feat/my-change"
+          autoCapitalize="none"
+          autoFocus
+          mono
+          editable={!busy}
+          error={!!error}
+          testID="protected-branch-name"
+        />
+        <Text variant="monoSm" color="tertiary">{`Branched from ${branch}`}</Text>
+
+        {error ? (
+          <Text testID="protected-branch-error" variant="monoSm" color={t.color.diffDelFg}>{error}</Text>
+        ) : null}
+
+        <View style={{ flexDirection: "row", justifyContent: "flex-end", gap: t.space(2) }}>
+          <Button
+            title="Cancel"
+            variant="ghost"
+            size="md"
+            disabled={busy}
+            onPress={onCancel}
+            testID="protected-branch-cancel"
+          />
+          <Button
+            title={busy ? "Creating…" : "Create branch and save"}
+            variant="primary"
+            size="md"
+            disabled={busy || trimmed === ""}
+            onPress={submit}
+            testID="protected-branch-submit"
+          />
+        </View>
+      </View>
+    </View>
+  );
+}

package/src/history.ts

@@ -0,0 +1,82 @@
+import type { DocumentChange } from "./components/ChangeDetail";
+
+/**
+ * One commit in a document's history — a row in the version list.
+ *
+ * This is the provider's history for the document's CURRENT path. GitHub's
+ * commits API has no equivalent of `git log --follow`, so a renamed document's
+ * history stops at the rename; the list says so at its end rather than letting
+ * the absence read as "this is where the document began".
+ */
+export type DocumentVersion = {
+  sha: string;
+  /** First 7 characters — an identity without the noise. */
+  shortSha: string;
+  /** The full commit message; the list shows its first line. */
+  message: string;
+  authorName: string;
+  authorEmail?: string | null;
+  /** ISO 8601, in UTC. */
+  authoredAt: string;
+  /** The commit's page on the provider. */
+  url: string;
+  /** How many files the commit touched — this document is one of them. */
+  filesChanged: number;
+};
+
+/**
+ * HistoryApi is the data seam between the design system and its host, the same
+ * split MediaApi and FormsApi use: the DS owns the version browser's UI and its
+ * (ephemeral) open/selected state, the host owns fetching. Omitting it from
+ * ContentBrowser hides the history affordance entirely, which is what a
+ * deployment with no provider — local mode, the desktop app — should look like.
+ */
+export interface HistoryApi {
+  /**
+   * One page of a document's versions, newest first. The DS pages as the list
+   * scrolls; a short page (fewer than `limit`) ends it.
+   */
+  list: (params: { documentId: string; limit: number; offset: number }) => Promise<DocumentVersion[]>;
+  /**
+   * The document as it was at one commit, diffed against what it is now:
+   * `before` on each field is the value at that version, `after` its current
+   * value. Unchanged fields are included, which is what makes the result a
+   * readable preview of the whole document rather than a list of differences.
+   *
+   * Null when the version can't be read (a commit that has gone away under a
+   * force push, say) — the pane says so instead of showing an empty document.
+   */
+  get: (params: { documentId: string; sha: string }) => Promise<DocumentChange | null>;
+}
+
+/**
+ * firstLine is the summary a version row shows. A commit message's first line is
+ * its subject by convention, and the body below it is prose that would push
+ * every other row off the screen.
+ */
+export function firstLine(message: string): string {
+  const line = message.split("\n", 1)[0].trim();
+  return line || "(no commit message)";
+}
+
+/**
+ * relativeTime renders a commit's age the way a history reads — "3d ago" —
+ * falling back to the date once "ago" stops being informative.
+ *
+ * `now` is injectable so a test can assert a fixed string rather than race the
+ * clock.
+ */
+export function relativeTime(iso: string, now: Date = new Date()): string {
+  const then = new Date(iso);
+  const seconds = Math.round((now.getTime() - then.getTime()) / 1000);
+  if (!Number.isFinite(seconds)) return "";
+  if (seconds < 60) return "just now";
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  // Past a month, "5 weeks ago" is harder to place than the date itself.
+  return then.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}

package/src/index.ts

@@ -55,6 +55,8 @@ export type {
 } from "./components/ApplyChangesModal";
 
 // Change-request summary surface (developer escalation)
+export { ProtectedBranchModal } from "./components/ProtectedBranchModal";
+export type { ProtectedBranchModalProps } from "./components/ProtectedBranchModal";
 export { ChangeRequestSummary } from "./components/ChangeRequestSummary";
 export type {
   ChangeRequestSummaryProps,
@@ -64,6 +66,10 @@ export type {
 
 // Changes surface: one document's diff between a branch and its base
 export { ChangeDetail } from "./components/ChangeDetail";
+export { DocumentHistory } from "./components/DocumentHistory";
+export type { DocumentHistoryProps } from "./components/DocumentHistory";
+export { firstLine, relativeTime } from "./history";
+export type { DocumentVersion, HistoryApi } from "./history";
 export type {
   ChangeDetailProps,
   DocumentChange,