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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.16.0-next.3",
+  "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/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

@@ -34,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,
@@ -340,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;
@@ -2581,6 +2591,7 @@ function EntryDetail({
   onMove,
   collectionPath,
   folderOptions,
+  history,
   active,
   onActivate,
   onCollapse,
@@ -2603,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.
@@ -2623,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.
@@ -2908,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}
@@ -2923,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
@@ -3970,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}
@@ -4845,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/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

@@ -66,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,