Platform-independent frontend slots

extension/data/frontends/index.tsx

@@ -0,0 +1,162 @@
+// Defines a system of "slots" which modules can use to render interface
+// elements within the page. Slot locations are standardized for consumers (e.g.
+// a module says it wants to display a button next to comment author usernames)
+// and their actual position in the DOM is controlled by platform-specific
+// observers responding to changes in the page and dynamically creating React
+// roots which this code then populates with the appropriate contents.
+
+// TODO: this file probably needs to be explained a lot better im in
+//       functionality hyperfocus mode not documentation hyperfocus mode
+
+import {type ComponentType} from 'react';
+
+import {currentPlatform, RedditPlatform} from '../util/platform';
+import {reactRenderer} from '../util/ui_interop';
+
+import modmailObserver from './modmail';
+import newRedditObserver from './newreddit';
+import oldRedditObserver from './oldreddit';
+import shredditObserver from './shreddit';
+
+// FIXME: document all of these
+interface PlatformSlotDetailsSubreddit {
+    fullname?: string;
+    name: string;
+}
+
+export type PlatformSlotDetailsUser = {
+    deleted: true;
+} | {
+    deleted: false;
+    fullname?: string;
+    name: string;
+};
+
+interface PlatformSlotDetailsSubmission {
+    fullname: string;
+}
+
+interface PlatformSlotDetailsComment {
+    fullname: string;
+}
+
+// Slot names and the type of associated contextual information
+// FIXME: document
+export interface PlatformSlotDetails {
+    submissionAuthor: {
+        user: PlatformSlotDetailsUser;
+        submission?: PlatformSlotDetailsSubmission;
+        subreddit: PlatformSlotDetailsSubreddit;
+        // distinguishType: null | 'moderator' | 'employee' | 'alumnus';
+        // stickied: boolean;
+    };
+    commentAuthor: {
+        user: PlatformSlotDetailsUser;
+        comment: PlatformSlotDetailsComment;
+        submission?: PlatformSlotDetailsSubmission;
+        subreddit: PlatformSlotDetailsSubreddit;
+        // distinguished: boolean;
+        // stickied: boolean;
+    };
+    modmailAuthor: {
+        user: PlatformSlotDetailsUser;
+        subreddit: PlatformSlotDetailsSubreddit;
+        thread: {fullname: string};
+        message: {fullname: string};
+        // authorIsModerator: boolean;
+        // repliedAsSubreddit: boolean;
+    };
+    userHovercard: {
+        user: PlatformSlotDetailsUser;
+        subreddit: PlatformSlotDetailsSubreddit;
+        contextFullname?: string;
+    };
+}
+export type PlatformSlotLocation = keyof PlatformSlotDetails;
+
+// Consumer code (used by toolbox modules)
+
+// A consumer of a particular slot location which gets appropriate context and
+// returns React content to be rendered in the slot
+export type PlatformSlotContent<Location extends keyof PlatformSlotDetails> = ComponentType<{
+    details: PlatformSlotDetails[Location];
+    location: Location;
+}>;
+
+// Map of slot locations to consumers of the slot
+const slotConsumers: {
+    [K in keyof PlatformSlotDetails]?: PlatformSlotContent<K>[];
+} = Object.create(null);
+
+// FIXME: document
+export function renderInSlots<K extends keyof PlatformSlotDetails> (locations: K[], render: PlatformSlotContent<K>) {
+    if (!Array.isArray(locations)) {
+        locations = [];
+    }
+    for (const location of locations) {
+        if (!slotConsumers[location]) {
+            slotConsumers[location] = [];
+        }
+        slotConsumers[location]?.push(render);
+    }
+}
+
+// Observer code (used by platform-specific observers in this directory)
+
+// FIXME: document
+export type PlatformObserver = (
+    /**
+     * Creates a React root for a slot which will be populated with the
+     * appropriate contents. Observers are responsible for calling this function
+     * and inserting the resulting element into the DOM wherever the slot should
+     * be rendered.
+     */
+    createRenderer: <Location extends keyof PlatformSlotDetails>(
+        location: Location,
+        details: PlatformSlotDetails[Location],
+    ) => HTMLElement,
+) => void;
+
+// the actual `createRenderer` function observers get - returns a new react root
+// which will contain all the contents different modules have registered for the
+// given slot location
+// NOTE: Exported because tbui builders need to manually emit their own slots.
+//       Should we just import this from the platform-specific bits instead of
+//       passing this function in to them?
+export const createRenderer = <K extends keyof PlatformSlotDetails>(location: K, details: PlatformSlotDetails[K]) =>
+    reactRenderer(
+        <div
+            className='tb-platform-slot'
+            style={{display: 'inline-flex'}} // FIXME: do this in CSS
+            data-location={location}
+        >
+            {/* TODO: Do we want to do anything more sophisticated here? */}
+            {slotConsumers[location]?.map((Component, i) => (
+                <Component
+                    key={i}
+                    details={details}
+                    location={location}
+                />
+            ))}
+        </div>,
+    );
+
+// Initialize the appropriate observer for the platform we've loaded into
+let observers = {
+    [RedditPlatform.OLD]: oldRedditObserver,
+    [RedditPlatform.NEW]: newRedditObserver,
+    [RedditPlatform.SHREDDIT]: shredditObserver,
+    [RedditPlatform.MODMAIL]: modmailObserver,
+};
+
+/**
+ * Start the platform observer, which will cause slots to be identified and
+ * populated. To be called as part of the init process after all slot consumers
+ * have been registered via {@linkcode renderInSlots}.
+ */
+export function initializeObserver () {
+    if (currentPlatform == null) {
+        return;
+    }
+    observers[currentPlatform](createRenderer);
+}

extension/data/frontends/modmail.ts

@@ -0,0 +1,96 @@
+import {getThingInfo} from '../tbcore';
+import {PlatformObserver} from '.';
+
+const MESSAGE_SEEN_CLASS = 'tb-observer-modmail-message-seen';
+
+const SIDEBAR_SEEN_CLASS = 'tb-observer-modmail-sidebar-seen';
+
+export default (createRenderer => {
+    function newModmailConversationAuthors () {
+        const $body = $('body');
+        const subreddit = $body.find('.ThreadTitle__community').text();
+        $body.find(`.Thread__message:not(.${MESSAGE_SEEN_CLASS})`).each(function () {
+            const $this = $(this);
+            this.classList.add(MESSAGE_SEEN_CLASS);
+
+            // Get information
+            const authorHref = $this.find('.Message__header .Message__author').attr('href');
+            const idDetails = $this.find('.m-link').attr('href')!.match(/\/mail\/.*?\/(.*?)\/(.*?)$/i)!;
+
+            this.querySelector('.Message__divider')?.after(createRenderer('modmailAuthor', {
+                user: authorHref === undefined
+                    ? {deleted: true}
+                    : {deleted: false, name: authorHref.replace(/.*\/user\/([^/]+).*/, '$1')},
+                subreddit: {
+                    name: subreddit,
+                },
+                thread: {
+                    fullname: idDetails[1],
+                },
+                message: {
+                    fullname: idDetails[2],
+                },
+            }));
+        });
+    }
+
+    /**
+     * Makes sure to fire a jsAPI `TBuserHovercard` event for new modmail sidebar instances.
+     * @function
+     */
+    function newModmailSidebar () {
+        const $body = $('body');
+        if ($body.find('.ThreadViewer').length) {
+            const $modmailSidebar = $body.find(
+                `:is(.ThreadViewer__infobar, .ThreadViewerHeader__infobar, .InfoBar__idCard):not(.${SIDEBAR_SEEN_CLASS})`,
+            );
+            const jsApiPlaceHolder = `
+                <div class="tb-jsapi-container tb-modmail-sidebar-container">
+                    <div class="InfoBar__recentsTitle">Toolbox functions:</div>
+                    <span data-name="toolbox"></span>
+                </div>
+            `;
+            $modmailSidebar.each(function () {
+                getThingInfo(this, true).then(info => {
+                    this.classList.add(SIDEBAR_SEEN_CLASS);
+
+                    const $jsApiThingPlaceholder = $(jsApiPlaceHolder).appendTo(this);
+                    const jsApiThingPlaceholder = $jsApiThingPlaceholder[0];
+
+                    jsApiThingPlaceholder.appendChild(createRenderer('userHovercard', {
+                        user: (info.user && info.user !== '[deleted]')
+                            ? {deleted: false, name: info.user}
+                            : {deleted: true},
+                        subreddit: {
+                            name: info.subreddit,
+                        },
+                    }));
+                });
+            });
+        }
+    }
+
+    const $body = $('body');
+
+    $body.on('click', '.icon-user', () => {
+        setTimeout(() => {
+            newModmailSidebar();
+        }, 500);
+    });
+
+    $body.on('click', '.Thread__grouped', () => {
+        setTimeout(() => {
+            newModmailConversationAuthors();
+        }, 500);
+    });
+
+    window.addEventListener('TBNewPage', event => {
+        // TODO: augh
+        if ((event as any).detail.pageType === 'modmailConversation') {
+            setTimeout(() => {
+                newModmailSidebar();
+                newModmailConversationAuthors();
+            }, 500);
+        }
+    });
+}) satisfies PlatformObserver;