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

package/src/components/ContentBrowser.tsx

@@ -6,7 +6,7 @@ import { Text } from "./Text";
 import { Icon } from "./Icon";
 import { Button, IconButton } from "./Button";
 import { Input } from "./Input";
-import { Avatar, Badge, DiffStat, Divider, SectionLabel } from "./primitives";
+import { Avatar, Badge, CheckBox, DiffStat, Divider, SectionLabel } from "./primitives";
 import { NavRow } from "./NavRow";
 import { AppShell, MobileScreen, Pane, TopBar, ThemeToggle } from "./layout";
 import { Segment, type SegmentItem } from "./Segment";
@@ -23,6 +23,7 @@ import {
   PresenceField,
   PresenceAvatars,
   useCollabRegister,
+  writeCollabValue,
   useCollabMirror,
   useCollabSynced,
   useCollabValue,
@@ -34,6 +35,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,
@@ -112,6 +115,12 @@ export type FieldSlotArgs = {
   // CRDT and publish presence.
   collab?: CollabApi;
   path?: string;
+  // Bumped when the host replaces this field's value outright rather than the
+  // user editing it — restoring it from a past version. A controlled control
+  // needs nothing from this (it already re-renders with the new value), but the
+  // body editor does: in a live session it ignores `value` and mirrors the
+  // shared fragment, so "the value changed" is not a thing it can observe.
+  resetNonce?: number;
 };
 export type RenderField = (args: FieldSlotArgs) => React.ReactNode;
 
@@ -340,6 +349,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;
@@ -757,6 +774,11 @@ type FieldControlProps = {
   // When this number changes, the field programmatically focuses itself (used to
   // jump to a peer's field from its presence avatar).
   focusSignal?: number;
+  // Bumped when this field's value was replaced by the host rather than typed —
+  // restored from a past version. Only the host-supplied body editor needs it
+  // (see FieldSlotArgs.resetNonce); every built-in control is controlled and
+  // re-renders from `value` on its own.
+  resetNonce?: number;
 };
 
 // The scalar type an array's `of` maps to when rendering item controls.
@@ -770,7 +792,7 @@ function ofToType(of?: string): string {
 }
 
 function FieldControl(props: FieldControlProps) {
-  const { field, value, onChange, renderField, readOnly = false, error, hideLabel, onOpenGroup, collab, path, focusSignal } = props;
+  const { field, value, onChange, renderField, readOnly = false, error, hideLabel, onOpenGroup, collab, path, focusSignal, resetNonce } = props;
   const t = useTheme();
   const label = hideLabel ? "" : field.label || field.name;
   // A text field participates in live collaboration when the document has a
@@ -783,7 +805,7 @@ function FieldControl(props: FieldControlProps) {
 
   // Host-supplied control (e.g. the markdown editor) takes precedence.
   if (renderField) {
-    const custom = renderField({ field, value, onChange, readOnly, collab: collabText, path });
+    const custom = renderField({ field, value, onChange, readOnly, collab: collabText, path, resetNonce });
     if (custom != null && custom !== false) {
       return (
         <View style={{ gap: t.space(2) }}>
@@ -2581,6 +2603,7 @@ function EntryDetail({
   onMove,
   collectionPath,
   folderOptions,
+  history,
   active,
   onActivate,
   onCollapse,
@@ -2603,6 +2626,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 +2650,23 @@ function EntryDetail({
   const canRename = !readOnly && !!onRename;
   const canMove = !readOnly && !!onMove && glob.hierarchical;
   const [prompt, setPrompt] = useState<"rename" | "move" | null>(null);
+  // Per-field "your value was replaced" counters, bumped by a restore. Only the
+  // host-supplied body editor reads them (see FieldSlotArgs.resetNonce); every
+  // built-in control is controlled and needs no telling.
+  const [resetNonces, setResetNonces] = useState<Record<string, number>>({});
+
+  // 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.
@@ -2805,6 +2849,112 @@ function EntryDetail({
     [commit],
   );
 
+  // Publish a value map the form did NOT arrive at by typing — a restore from a
+  // past version, or a discard back to the saved document.
+  //
+  // Both used to write local state and stop there, which is only half the job in
+  // a live session. The shared document is the source of truth there: every
+  // collab control prefers its binding to the value handed to it, so a replaced
+  // value was displayed for one frame and then overwritten by the room's
+  // unchanged one, and no peer ever saw it. Anything that replaces values
+  // wholesale has to come through here.
+  //
+  // `names` are the fields whose values were replaced; unchanged ones are left
+  // alone so a replacement never churns the room (or nudges a peer's cursor)
+  // over a value that did not move.
+  const publishReplacement = useCallback(
+    (previous: Record<string, unknown>, next: Record<string, unknown>, names: string[]) => {
+      const moved = names.filter((name) => !sameValue(previous[name], next[name]));
+      if (moved.length === 0) return;
+
+      if (entry.collab) {
+        for (const name of moved) {
+          // A body is a ProseMirror fragment rather than a field binding, so it
+          // is not written here — its editor is told instead, by the nonce below.
+          if (editFields.find((f) => f.name === name)?.source === "body") continue;
+          writeCollabValue(entry.collab, name, previous[name], next[name]);
+        }
+      }
+
+      // Tell the replaced fields their value came from outside. Keyed per field
+      // rather than one counter for the document: the body editor acts on this,
+      // and replacing some unrelated field must not make it rebuild a body a
+      // peer may be mid-sentence in.
+      setResetNonces((prev) => {
+        const bumped = { ...prev };
+        for (const name of moved) bumped[name] = (bumped[name] ?? 0) + 1;
+        return bumped;
+      });
+    },
+    // editFields is derived from entry, captured by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [entry.id, entry.collab],
+  );
+
+  // Values taken from a past version and put back into the form.
+  //
+  // It is an edit like any other: the restored fields land in `values`, the
+  // document goes unsaved, and the author saves it (or discards it) themselves.
+  // Nothing is written to git here — history is a place you read, and rewriting
+  // the document from it should still pass through the same review a typed edit
+  // does.
+  const restoreValues = useCallback(
+    (restored: { fields: Record<string, unknown>; body?: string | null }) => {
+      const previous = valuesRef.current;
+      const next = { ...previous, ...restored.fields };
+      // The body is a field in the form like any other; which one it is comes
+      // from the schema (`source: "body"`), the same mapping buildChange uses in
+      // the other direction. A document whose model has no body field simply
+      // has no body to restore.
+      const bodyField = "body" in restored ? editFields.find((f) => f.source === "body") : undefined;
+      if (bodyField) next[bodyField.name] = restored.body ?? "";
+
+      const replaced = Object.keys(restored.fields);
+      if (bodyField) replaced.push(bodyField.name);
+
+      // Touched under the first restored name so a restore that leaves a
+      // required field empty shows its error immediately, rather than looking
+      // saveable until Save is pressed.
+      //
+      // Committed BEFORE publishing: a collab control observing the room echoes
+      // what it sees back through onChange, and that echo builds its next map by
+      // spreading the current one. Publishing first would have it spread the
+      // pre-restore map.
+      commit(next, replaced[0] ?? SYNTHETIC_BODY);
+      publishReplacement(previous, next, replaced);
+      // Drilled-into groups address the pre-restore shape; a restored group
+      // object can have different children entirely.
+      setGroupPath([]);
+    },
+    // editFields is derived from entry, which commit already captures by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [commit, entry.id, publishReplacement],
+  );
+
+  // Throw away everything unsaved and go back to the document as stored.
+  //
+  // In a live session that is a change to the ROOM, not just to this screen: the
+  // unsaved work is the collective state every client is looking at, and a
+  // discard that only reverted the local form would leave the document it just
+  // claimed to restore sitting in the CRDT, ready to come straight back.
+  const discardEdits = useCallback(() => {
+    const previous = valuesRef.current;
+    const restored = seed();
+    valuesRef.current = restored;
+    setValues(restored);
+    setTouched({});
+    // The preview is rendering the draft being thrown away, and nothing else
+    // will tell it otherwise: it is fed from edits, and a discard is the one
+    // change to a document that produces no edit. Without this the preview
+    // keeps showing work the author just deleted, until they type again.
+    emitDraft(buildChange(entry.id, editFields, restored), entry);
+    discard();
+    publishReplacement(previous, restored, editFields.map((f) => f.name));
+    setGroupPath([]);
+    // seed/editFields derive from entry, captured by id.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entry.id, discard, emitDraft, publishReplacement]);
+
   // A field edit within the active group-drill frame: write the value at the
   // frame's nested path, then commit the whole map (buildChange serializes it).
   const changeInFrame = useCallback(
@@ -2868,19 +3018,7 @@ function EntryDetail({
         {saveHandler && dirty ? (
           <Pressable
             testID="discard-changes"
-            onPress={() => {
-              const restored = seed();
-              valuesRef.current = restored;
-              setValues(restored);
-              setTouched({});
-              // The preview is rendering the draft that is being thrown away,
-              // and nothing else will tell it otherwise: it is fed from edits,
-              // and a discard is the one change to a document that produces no
-              // edit. Without this the preview keeps showing work the author
-              // just deleted, until they type again.
-              emitDraft(buildChange(entry.id, editFields, restored), entry);
-              discard();
-            }}
+            onPress={discardEdits}
             style={{ paddingHorizontal: t.space(2), paddingVertical: t.space(1) }}
           >
             <Text variant="monoSm" color="tertiary">Discard</Text>
@@ -2908,6 +3046,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 +3075,35 @@ 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)}
+          // Restoring needs somewhere for the values to go: a document that is
+          // read-only, or that this host never wired a save for, gets the
+          // history with no selection boxes at all rather than a form it can
+          // dirty and never save. (saveHandler is already undefined when
+          // readOnly, so this covers both.)
+          onRestore={
+            !saveHandler
+              ? undefined
+              : (restored) => {
+                  restoreValues(restored);
+                  // Back to the form, which is where the restored values now
+                  // are and where the decision to keep them is made.
+                  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
@@ -2964,6 +3141,7 @@ function EntryDetail({
               collab={entry.collab}
               path={[...groupPath, f.name].join(".")}
               focusSignal={focusTarget && focusTarget.name === f.name ? focusTarget.nonce : undefined}
+              resetNonce={resetNonces[f.name]}
             />
           ))}
         </ScrollView>
@@ -3043,27 +3221,6 @@ function useMultiSelect(resetKey: string) {
   return { checked, toggle, clear, checkedIds, checkedFolders, toggleFolder, checkedFolderKeys };
 }
 
-// CheckBox is the row-selection control for multi-select.
-function CheckBox({ value, onToggle }: { value: boolean; onToggle: () => void }) {
-  const t = useTheme();
-  return (
-    <Pressable
-      // Stop the press from bubbling to the row's open handler (the checkbox
-      // sits inside the row Pressable) so toggling never also opens the entry.
-      onPress={(e?: { stopPropagation?: () => void }) => { e?.stopPropagation?.(); onToggle(); }}
-      testID="entry-checkbox"
-      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>
-  );
-}
-
 // SelectionBar appears above the entry list when rows are checked; it offers a
 // bulk move and/or delete plus a clear action (each shown only when wired).
 function SelectionBar({ count, onMove, onDelete, onClear }: { count: number; onMove?: () => void; onDelete?: () => void; onClear: () => void }) {
@@ -3206,7 +3363,7 @@ function EntriesList({
             <View style={{ flexDirection: "row", alignItems: "center" }}>
               {showChecks ? (
                 <View style={{ paddingLeft: t.space(4) }}>
-                  <CheckBox value={!!checked?.[e.id]} onToggle={() => onToggleEntry?.(e.id)} />
+                  <CheckBox value={!!checked?.[e.id]} onToggle={() => onToggleEntry?.(e.id)} testID="entry-checkbox" />
                 </View>
               ) : null}
               <View style={{ flex: 1 }}>
@@ -3970,6 +4127,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 +5003,7 @@ function MobileBrowser(props: ContentBrowserProps) {
         <EntryDetail
           entry={entry}
           documentActions={props.documentActions}
+          history={props.history}
           onEntryDraft={props.onEntryDraft}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}