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

package/src/components/DocumentHistory.tsx

@@ -0,0 +1,408 @@
+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 { Button } from "./Button";
+import { BODY_FIELD, 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;
+  /**
+   * Put a past version's values for the chosen fields back into the editor.
+   *
+   * It restores into the FORM, not into git and not straight to a save: the
+   * document becomes unsaved with those fields rolled back, and the author
+   * reviews and saves it like any other edit. Reading history and rewriting the
+   * document are two different acts, and only one of them should be one click
+   * from a list you are still browsing.
+   *
+   * `body` is present only when the body was among the chosen fields — null is
+   * a real restorable value (a document that had no body), so its absence has
+   * to be expressed by the key being missing rather than by null.
+   *
+   * Omitted (a read-only document) → no boxes and no restore bar, only reading.
+   */
+  onRestore?: (restored: { fields: Record<string, unknown>; body?: string | null }) => 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, onRestore }: 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);
+  // Which fields the reader has picked to take from this version. Cleared on
+  // every version change below: a tick means "restore THIS value", so carrying
+  // it to another version would silently repoint it at a different one.
+  const [picked, setPicked] = useState<readonly string[]>([]);
+  const togglePick = useCallback(
+    (name: string) => setPicked((p) => (p.includes(name) ? p.filter((n) => n !== name) : [...p, name])),
+    [],
+  );
+
+  // 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);
+    setPicked([]);
+    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(() => {
+    // A tick names a value, not a field: it means "take THIS version's title".
+    // Carrying the selection to the next version would keep the ticks while
+    // silently repointing them at different values.
+    setPicked([]);
+    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]);
+
+  // Restore is offered only for a document the caller can write AND a version
+  // that differs from it: a version identical to the current document has no
+  // field whose old value is anything but the value already there.
+  const canRestore = !!onRestore && !!detail && detail.status !== "U";
+
+  const restore = useCallback(() => {
+    if (!onRestore || !detail) return;
+    const chosen = new Set(picked);
+    const fields: Record<string, unknown> = {};
+    for (const f of detail.fields) {
+      if (!chosen.has(f.name)) continue;
+      // `before` is this version's value, which is the whole point — and it is
+      // undefined for a field the version did not have. Restoring that has to
+      // mean "clear it", so it is written as undefined rather than skipped.
+      fields[f.name] = f.before;
+    }
+    const restored: { fields: Record<string, unknown>; body?: string | null } = { fields };
+    // The key is present only when the body was picked: null is a real value to
+    // restore (a document that had no body), so absence cannot be spelled null.
+    if (chosen.has(BODY_FIELD)) restored.body = detail.bodyBefore ?? null;
+    onRestore(restored);
+  }, [onRestore, detail, picked]);
+
+  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"}
+            selectedFields={picked}
+            onToggleField={canRestore ? togglePick : undefined}
+          />
+        )}
+        {canRestore ? <RestoreBar count={picked.length} onRestore={restore} onClear={() => setPicked([])} /> : null}
+      </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>
+  );
+}
+
+/**
+ * The restore action, docked under the diff.
+ *
+ * Always mounted while a writable version is selected, rather than appearing
+ * once something is ticked: a bar that materialises on the first tick shifts
+ * the diff under the hand that just ticked it, and the disabled button is what
+ * tells you the boxes are for something in the first place.
+ */
+function RestoreBar({
+  count,
+  onRestore,
+  onClear,
+}: {
+  count: number;
+  onRestore: () => void;
+  onClear: () => void;
+}) {
+  const t = useTheme();
+  return (
+    <View
+      testID="restore-bar"
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: t.space(2),
+        paddingHorizontal: t.space(4),
+        paddingVertical: t.space(2),
+        borderTopWidth: 1,
+        borderTopColor: t.color.borderSubtle,
+        backgroundColor: t.color.surfaceSunken,
+      }}
+    >
+      <Text variant="monoSm" color="tertiary" style={{ flex: 1 }}>
+        {count === 0
+          ? "Tick a field to take its earlier value"
+          : count === 1
+            ? "1 field selected"
+            : `${count} fields selected`}
+      </Text>
+      {count > 0 ? (
+        <Pressable onPress={onClear} testID="restore-clear" style={{ paddingHorizontal: t.space(2), paddingVertical: t.space(1) }}>
+          <Text variant="monoSm" color="tertiary">Clear</Text>
+        </Pressable>
+      ) : null}
+      <Button
+        testID="restore-apply"
+        // Named for what it does to the thing in front of you. It does not write
+        // to git and does not save — it puts the values back in the form, and
+        // the author still has to save them.
+        title={count > 1 ? `Restore ${count} fields` : "Restore field"}
+        size="sm"
+        variant={count > 0 ? "primary" : "default"}
+        disabled={count === 0}
+        onPress={onRestore}
+        style={{ alignSelf: "center" }}
+      />
+    </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/primitives.tsx

@@ -1,7 +1,8 @@
 import React from "react";
-import { View, StyleProp, ViewStyle } from "react-native";
+import { View, Pressable, StyleProp, ViewStyle } from "react-native";
 import { useTheme } from "../ThemeProvider";
 import { Text } from "./Text";
+import { Icon } from "./Icon";
 
 /** Bordered surface card — defined by a hairline border, never a shadow. */
 export function Card({
@@ -141,3 +142,47 @@ export function SectionLabel({ children, style }: { children: React.ReactNode; s
     </View>
   );
 }
+
+/**
+ * A square check box: filled and ticked when on, an empty hairline box when
+ * off.
+ *
+ * Lives here rather than beside its first caller because two surfaces select
+ * things now — entry rows in the browser, and the fields of a past version in
+ * the history diff — and they have to look like the same control. The press
+ * stops propagating: every current caller puts this inside a larger Pressable
+ * (a list row, a field block), and a tick that also opened the row would be
+ * unusable.
+ */
+export function CheckBox({
+  value,
+  onToggle,
+  testID = "check-box",
+}: {
+  value: boolean;
+  onToggle: () => void;
+  testID?: string;
+}) {
+  const t = useTheme();
+  return (
+    <Pressable
+      onPress={(e?: { stopPropagation?: () => void }) => {
+        e?.stopPropagation?.();
+        onToggle();
+      }}
+      testID={testID}
+      style={{
+        width: 18,
+        height: 18,
+        borderRadius: t.radius.sm,
+        borderWidth: 1,
+        borderColor: value ? t.color.borderStrong : t.color.borderDefault,
+        backgroundColor: value ? t.color.surfaceInverted : t.color.surfaceRaised,
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      {value ? <Icon name="check" size={12} color={t.color.textInverted} /> : null}
+    </Pressable>
+  );
+}

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

@@ -65,7 +65,11 @@ export type {
 } from "./components/ChangeRequestSummary";
 
 // Changes surface: one document's diff between a branch and its base
-export { ChangeDetail } from "./components/ChangeDetail";
+export { ChangeDetail, BODY_FIELD } 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,