Update prop type & documentation for HistoryVisibleBanner and VM. (#31545)

* docs: Update documentation for HistoryVisibleBanner and VM.

* docs: Improve documentation for `HistoryVisibleBanner`, second pass.

* docs: Move documentation to prop types over FC.

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* fix: Simplify type for `HistoryVisibleBannerViewModel` `threadId`.

* docs: Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

src/components/views/composer/HistoryVisibleBanner.tsx

@@ -11,7 +11,17 @@ import { type Room } from "matrix-js-sdk/src/matrix";
 
 import { HistoryVisibleBannerViewModel } from "../../../viewmodels/composer/HistoryVisibleBannerViewModel";
 
-export const HistoryVisibleBanner: React.FC<{ room: Room; threadId?: string | null }> = (props) => {
+/** Wrapper around {@link HistoryVisibleBannerViewModel} for the creation of an auto-disposed view model. */
+export const HistoryVisibleBanner: React.FC<{
+    /** The room instance associated with this banner view model. */
+    room: Room;
+
+    /**
+     * If not null, specifies the ID of the thread currently being viewed in the thread timeline side view,
+     * where the banner view is displayed as a child of the message composer.
+     */
+    threadId: string | null;
+}> = (props) => {
     const vm = useCreateAutoDisposedViewModel(() => new HistoryVisibleBannerViewModel(props));
     return <HistoryVisibleBannerView vm={vm} />;
 };

src/components/views/rooms/MessageComposer.tsx

@@ -675,7 +675,7 @@ export class MessageComposer extends React.Component<IProps, IState> {
 
         return (
             <div className={classes} ref={this.ref} role="region" aria-label={_t("a11y|message_composer")}>
-                <HistoryVisibleBanner room={this.props.room} threadId={threadId} />
+                <HistoryVisibleBanner room={this.props.room} threadId={threadId ?? null} />
                 <div className="mx_MessageComposer_wrapper">
                     <UserIdentityWarning room={this.props.room} key={this.props.room.roomId} />
                     <ReplyPreview

src/viewmodels/composer/HistoryVisibleBannerViewModel.tsx

@@ -16,10 +16,40 @@ import SettingsStore from "../../settings/SettingsStore";
 import { SettingLevel } from "../../settings/SettingLevel";
 
 interface Props {
+    /**
+     * The room instance associated with this banner view model.
+     */
     room: Room;
-    threadId?: string | null;
+
+    /**
+     * If not null, indicates the ID of the thread currently being viewed in the thread
+     * timeline side view, where the banner view is displayed as a child of the message
+     * composer.
+     */
+    threadId: string | null;
 }
 
+/**
+ * View model for the history visible banner, which prompts users that the current room
+ * history may be shared with new invitees, if they have not already acknowledged the
+ * banner.
+ *
+ * The view model operates using a simple 2-case algorithm:
+ *
+ * 1. When a user opens an encrypted room where `history_visibility` is not set to `joined`,
+ *    and the user hasn't previously dismissed it for this particular room, display a banner.
+ *    If the user dismisses the banner, update the client's local store to record that the
+ *    banner has been dismissed.
+ * 2. When the user opens an encrypted room where `history_visibility` is set to `joined`, clear
+ *    the dismissal flag if it was previously set. This ensures that if the room's history
+ *    visibility changes from public to private and back to public, the banner will reappear
+ *    when appropriate.
+ *
+ * This banner is only shown in the regular timeline view, not the thread timeline view, which is
+ * done by conditioning on the presence of `threadId` in the viewmodel's {@link Props}.
+ *
+ * See https://github.com/element-hq/element-meta/issues/2875 for more information.
+ */
 export class HistoryVisibleBannerViewModel
     extends BaseViewModel<HistoryVisibleBannerViewSnapshot, Props>
     implements HistoryVisibleBannerViewModelInterface
@@ -34,6 +64,12 @@ export class HistoryVisibleBannerViewModel
      */
     private readonly acknowledgedWatcher: string;
 
+    /**
+     * Computes the latest banner snapshot given the VM's props.
+     * @param room - The room the banner will be shown in.
+     * @param threadId - The thread ID passed in from the parent {@link MessageComposer}.
+     * @returns The latest snapshot. See {@link HistoryVisibleBannerViewSnapshot}.
+     */
     private static readonly computeSnapshot = (
         room: Room,
         threadId?: string | null,
@@ -51,6 +87,10 @@ export class HistoryVisibleBannerViewModel
         };
     };
 
+    /**
+     * Creates a new view model instance.
+     * @param props - Properties for this view model. See {@link Props}.
+     */
     public constructor(props: Props) {
         super(props, HistoryVisibleBannerViewModel.computeSnapshot(props.room, props.threadId));
 
@@ -69,6 +109,10 @@ export class HistoryVisibleBannerViewModel
         );
     }
 
+    /**
+     * Recompute and update this VM instance's snapshot. This will update the `acknowledgedHistoryVisibility`
+     * store entry if necessary.
+     */
     private setSnapshot(): void {
         const acknowledged = SettingsStore.getValue("acknowledgedHistoryVisibility", this.props.room.roomId);
 
@@ -109,6 +153,9 @@ export class HistoryVisibleBannerViewModel
         );
     }
 
+    /**
+     * Dispose of the viewmodel and its settings listeners.
+     */
     public dispose(): void {
         super.dispose();
         SettingsStore.unwatchSetting(this.featureWatcher);

test/unit-tests/components/viewmodels/composer/HistoryVisibleBannerViewModel-test.tsx

@@ -54,7 +54,7 @@ describe("HistoryVisibleBannerViewModel", () => {
     });
 
     it("should not show the banner in unencrypted rooms", () => {
-        const vm = new HistoryVisibleBannerViewModel({ room });
+        const vm = new HistoryVisibleBannerViewModel({ room, threadId: null });
         expect(vm.getSnapshot().visible).toBe(false);
     });
 
@@ -76,7 +76,7 @@ describe("HistoryVisibleBannerViewModel", () => {
             }),
         ]);
 
-        const vm = new HistoryVisibleBannerViewModel({ room });
+        const vm = new HistoryVisibleBannerViewModel({ room, threadId: null });
         expect(vm.getSnapshot().visible).toBe(false);
     });
 
@@ -99,7 +99,7 @@ describe("HistoryVisibleBannerViewModel", () => {
             }),
         ]);
 
-        const vm = new HistoryVisibleBannerViewModel({ room });
+        const vm = new HistoryVisibleBannerViewModel({ room, threadId: null });
         expect(vm.getSnapshot().visible).toBe(false);
         vm.dispose();
     });
@@ -145,7 +145,7 @@ describe("HistoryVisibleBannerViewModel", () => {
             }),
         ]);
 
-        const vm = new HistoryVisibleBannerViewModel({ room });
+        const vm = new HistoryVisibleBannerViewModel({ room, threadId: null });
         expect(vm.getSnapshot().visible).toBe(true);
         await vm.onClose();
         expect(vm.getSnapshot().visible).toBe(false);