fix(ui): DocumentTitleManager for predictable sentry document titles (#103150)

Right now, every instance of `<SentryDocumentTitle>` computes a title,
applies it to the `document.title` and stores its value in context, so
that the next `<SentryDocumentTitle>` can pick that up and “revert” to
that state.

However, there are situations where this doesn’t work so well because
the unmount effect that attempts to clean things up might run after the
next component has rendered, leading to wrong titles in some situations
where the title just resets to `Sentry`:


https://github.com/user-attachments/assets/016c4e36-16d0-4a86-86fc-b27f7800db22

The reason why it mostly works is because we have additional re-renders
thanks to `useLocation()` at the top of most pages, which will restore
the correct title. But this is brittle and as shown, doesn’t work in all
cases.

This PR re-writes takes a different approach to applying document
titles. Instead of writing to the title on each level in render (which
can also lead to flickering), we just register with a global
`DocumentTitleManager` in an effect. To make sure we have the right
order, we compute a timestamp once during render (in `useState`) when
the component mounts and pass that along the text we want to the
manager.

The `DocumentTitleManager` itself then just knows all the registered
titles, and displays the one we want (the last one, and optionally add
the default title to it. This also gives us the possibility to do
“compound titles” like in breadcrumbs if we want to). To get the last
item, it uses the insertion order that was calculated during render, so
the fact that `useEffect` runs bottom-up doesn’t matter.

Note that we can’t just `reverse()` the array because data fetching
might mean some effects run sooner than others. For example, let’s say
we add two titles, then fetch, then add two more. rendering goes like
this:

```
1 -- 2 -- ...fetching... -- 3 -- 4
```

but effects will run like this (bottom up, for reach committed group
individually):

```
2 -- 1 -- ...fetching... -- 4 -- 3
```

yielding a result order of `2,1,3,4`, which isn’t reversible. The
timestamp computed on mount resolves this issue, because we have
something stable to sort by.

For cleanup, when a component unmounts, it just removes itself (by id)
from the manager, which will automatically lead to the “previously
registered” title to show up. This can go over an arbitrary number of
layers, while the previous solution was limited to one parent.

---

after:


https://github.com/user-attachments/assets/a278fc4a-7753-4ce3-a8ca-a4b9a2a9ae58

Author: TkDodo

static/app/bootstrap/processInitQueue.tsx

@@ -5,6 +5,7 @@ import throttle from 'lodash/throttle';
 
 import {exportedGlobals} from 'sentry/bootstrap/exportGlobals';
 import {CommandPaletteProvider} from 'sentry/components/commandPalette/context';
+import {DocumentTitleManager} from 'sentry/components/sentryDocumentTitle/documentTitleManager';
 import {ThemeAndStyleProvider} from 'sentry/components/themeAndStyleProvider';
 import {ScrapsProviders} from 'sentry/scrapsProviders';
 import type {OnSentryInitConfiguration} from 'sentry/types/system';
@@ -111,17 +112,19 @@ async function processItem(initConfig: OnSentryInitConfiguration) {
            * and so we dont know which theme to pick.
            */
           <QueryClientProvider client={queryClient}>
-            <ThemeAndStyleProvider>
-              <CommandPaletteProvider>
-                <SimpleRouter
-                  element={
-                    <ScrapsProviders>
-                      <Component {...props} />
-                    </ScrapsProviders>
-                  }
-                />
-              </CommandPaletteProvider>
-            </ThemeAndStyleProvider>
+            <DocumentTitleManager>
+              <ThemeAndStyleProvider>
+                <CommandPaletteProvider>
+                  <SimpleRouter
+                    element={
+                      <ScrapsProviders>
+                        <Component {...props} />
+                      </ScrapsProviders>
+                    }
+                  />
+                </CommandPaletteProvider>
+              </ThemeAndStyleProvider>
+            </DocumentTitleManager>
           </QueryClientProvider>
         ),
         initConfig.container,

static/app/components/sentryDocumentTitle.spec.tsx

@@ -0,0 +1,69 @@
+import React, {createContext, useContext, useEffect, useMemo, useState} from 'react';
+
+const DEFAULT_PAGE_TITLE = 'Sentry';
+const SEPARATOR = ' — ';
+
+interface TitleEntry {
+  id: string;
+  noSuffix: boolean;
+  order: number;
+  text: string;
+}
+
+interface DocumentTitleManager {
+  register: (id: string, text: string, order: number, noSuffix: boolean) => void;
+  unregister: (id: string) => void;
+}
+
+const DocumentTitleContext = createContext<DocumentTitleManager>({
+  register: () => {},
+  unregister: () => {},
+});
+
+export const useDocumentTitleManager = () => useContext(DocumentTitleContext);
+
+export function DocumentTitleManager({children}: React.PropsWithChildren) {
+  const [entries, setEntries] = useState<TitleEntry[]>([]);
+
+  const [manager] = useState<DocumentTitleManager>(() => ({
+    register: (id, text, order, noSuffix) => {
+      setEntries(prev => {
+        // update for same id
+        if (prev.some(e => e.id === id)) {
+          return prev.map(e => (e.id === id ? {...e, text, noSuffix} : e));
+        }
+        return [...prev, {id, text, noSuffix, order}];
+      });
+    },
+    unregister: id => {
+      setEntries(prev => prev.filter(e => e.id !== id));
+    },
+  }));
+
+  const fullTitle = useMemo(() => {
+    const entry = entries
+      .filter(e => e.text.trim() !== '')
+      .sort((a, b) => b.order - a.order)
+      .at(0);
+
+    const parts = entry ? [entry.text] : [];
+
+    if (!entry?.noSuffix) {
+      parts.push(DEFAULT_PAGE_TITLE);
+    }
+    return [...new Set([...parts])].join(SEPARATOR);
+  }, [entries]);
+
+  // write to the DOM title
+  useEffect(() => {
+    if (fullTitle.length > 0) {
+      document.title = fullTitle;
+    }
+  }, [fullTitle]);
+
+  return (
+    <DocumentTitleContext.Provider value={manager}>
+      {children}
+    </DocumentTitleContext.Provider>
+  );
+}

static/app/components/sentryDocumentTitle.tsx

@@ -0,0 +1,71 @@
+import {render} from 'sentry-test/reactTestingLibrary';
+
+import {DocumentTitleManager} from './documentTitleManager';
+import SentryDocumentTitle from '.';
+
+describe('SentryDocumentTitle', () => {
+  it('sets the document title', () => {
+    render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle title="This is a test" />
+      </DocumentTitleManager>
+    );
+    expect(document.title).toBe('This is a test — Sentry');
+  });
+
+  it('adds a organization slug', () => {
+    render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle orgSlug="org" title="This is a test" />
+      </DocumentTitleManager>
+    );
+    expect(document.title).toBe('This is a test — org — Sentry');
+  });
+
+  it('adds a project slug', () => {
+    render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle projectSlug="project" title="This is a test" />
+      </DocumentTitleManager>
+    );
+    expect(document.title).toBe('This is a test — project — Sentry');
+  });
+
+  it('adds a organization and project slug', () => {
+    render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle orgSlug="org" projectSlug="project" title="This is a test" />
+      </DocumentTitleManager>
+    );
+    expect(document.title).toBe('This is a test — org — project — Sentry');
+  });
+
+  it('sets the title without suffix', () => {
+    render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle title="This is a test" noSuffix />
+      </DocumentTitleManager>
+    );
+    expect(document.title).toBe('This is a test');
+  });
+
+  it('reverts to the parent title', () => {
+    const {rerender} = render(
+      <DocumentTitleManager>
+        <SentryDocumentTitle title="This is a test">
+          <SentryDocumentTitle title="child title">Content</SentryDocumentTitle>
+        </SentryDocumentTitle>
+      </DocumentTitleManager>
+    );
+
+    expect(document.title).toBe('child title — Sentry');
+
+    rerender(
+      <DocumentTitleManager>
+        <SentryDocumentTitle title="This is a test">new Content</SentryDocumentTitle>
+      </DocumentTitleManager>
+    );
+
+    expect(document.title).toBe('This is a test — Sentry');
+  });
+});

static/app/components/sentryDocumentTitle/documentTitleManager.tsx

@@ -0,0 +1,69 @@
+import {useEffect, useId, useMemo, useState} from 'react';
+
+import {useDocumentTitleManager} from './documentTitleManager';
+
+type Props = {
+  children?: React.ReactNode;
+  /**
+   * Should the ` - Sentry` suffix be excluded?
+   */
+  noSuffix?: boolean;
+  /**
+   * The organization slug to show in the title
+   */
+  orgSlug?: string;
+  /**
+   * The project slug to show in the title.
+   */
+  projectSlug?: string;
+
+  /**
+   * This string will be shown at the very front of the title
+   */
+  title?: string;
+};
+
+function SentryDocumentTitle({
+  title = '',
+  orgSlug,
+  projectSlug,
+  noSuffix,
+  children,
+}: Props) {
+  const titleManager = useDocumentTitleManager();
+  const id = useId();
+  // compute order once on mount because effects run bottom-up
+  const [order] = useState(() => performance.now());
+
+  const pageTitle = useMemo(() => {
+    if (orgSlug && projectSlug) {
+      return `${title} — ${orgSlug} — ${projectSlug}`;
+    }
+
+    if (orgSlug) {
+      return `${title} — ${orgSlug}`;
+    }
+
+    if (projectSlug) {
+      return `${title} — ${projectSlug}`;
+    }
+
+    return title;
+  }, [orgSlug, projectSlug, title]);
+
+  // create or update title entry
+  useEffect(() => {
+    titleManager.register(id, pageTitle, order, !!noSuffix);
+  }, [titleManager, id, pageTitle, order, noSuffix]);
+
+  // cleanup on unmount
+  useEffect(() => {
+    return () => {
+      titleManager.unregister(id);
+    };
+  }, [titleManager, id]);
+
+  return children;
+}
+
+export default SentryDocumentTitle;