Merge remote-tracking branch 'origin/main' into COMPASS-9674

Author: johnjackweir

THIRD-PARTY-NOTICES.md

@@ -1,5 +1,5 @@
 The following third-party software is used by and included in **Mongodb Compass**.
-This document was automatically generated on Mon Sep 22 2025.
+This document was automatically generated on Tue Sep 23 2025.
 
 ## List of dependencies
 

docs/tracking-plan.md

@@ -6,7 +6,7 @@
 > the tracking plan for the specific Compass version you can use the following
 > URL: `https://github.com/mongodb-js/compass/blob/<compass version>/docs/tracking-plan.md`
 
-Generated on Mon, Sep 22, 2025
+Generated on Tue, Sep 23, 2025
 
 ## Table of Contents
 

packages/compass-assistant/src/compass-assistant-drawer.tsx

@@ -35,9 +35,10 @@ const assistantTitleTextStyles = css({
  * it's within an AssistantProvider.
  */
 export const CompassAssistantDrawer: React.FunctionComponent<{
+  appName: string;
   autoOpen?: boolean;
   hasNonGenuineConnections?: boolean;
-}> = ({ autoOpen, hasNonGenuineConnections = false }) => {
+}> = ({ appName, autoOpen, hasNonGenuineConnections = false }) => {
   const chat = useContext(AssistantContext);
   const { clearChat } = useContext(AssistantActionsContext);
 
@@ -92,6 +93,14 @@ export const CompassAssistantDrawer: React.FunctionComponent<{
       label="MongoDB Assistant"
       glyph="Sparkle"
       autoOpen={autoOpen}
+      guideCue={{
+        cueId: 'assistant-drawer',
+        title: 'Introducing MongoDB Assistant',
+        description: `AI-powered assistant to intelligently guide you through your database tasks. Get expert MongoDB help and streamline your workflow directly within ${appName}.`,
+        buttonText: 'Got it',
+        tooltipAlign: 'left',
+        tooltipJustify: 'start',
+      }}
     >
       <AssistantChat
         chat={chat}

packages/compass-assistant/src/compass-assistant-provider.spec.tsx

@@ -89,6 +89,7 @@ const TestComponent: React.FunctionComponent<{
         <DrawerAnchor>
           <div data-testid="provider-children">Provider children</div>
           <CompassAssistantDrawer
+            appName="Compass"
             autoOpen={autoOpen}
             hasNonGenuineConnections={hasNonGenuineConnections}
           />

packages/compass-components/src/components/drawer-portal.spec.tsx

@@ -16,7 +16,7 @@ import { expect } from 'chai';
 
 describe('DrawerSection', function () {
   it('renders DrawerSection in the portal and updates the content when it updates', async function () {
-    let setCount;
+    let setCount: React.Dispatch<React.SetStateAction<number>> = () => {};
 
     function TestDrawer() {
       const [count, _setCount] = useState(0);
@@ -228,4 +228,40 @@ describe('DrawerSection', function () {
       expect(screen.queryByText('This is the controlled section')).not.to.exist;
     });
   });
+
+  it('renders guide cue when passed in props', async function () {
+    localStorage.compass_guide_cues = '[]';
+    function TestDrawer() {
+      return (
+        <DrawerContentProvider>
+          <DrawerAnchor>
+            <DrawerSection
+              id="test-section"
+              label="Test section"
+              title={`Test section`}
+              glyph="Trash"
+              guideCue={{
+                cueId: 'test-drawer',
+                title: 'Introducing this new test drawer',
+                description: 'Does all the things',
+                buttonText: 'ok',
+                tooltipAlign: 'bottom',
+                tooltipJustify: 'end',
+              }}
+              autoOpen
+            >
+              This is a test section
+            </DrawerSection>
+          </DrawerAnchor>
+        </DrawerContentProvider>
+      );
+    }
+
+    render(<TestDrawer></TestDrawer>);
+
+    await waitFor(() => {
+      expect(screen.getByText('Introducing this new test drawer')).to.be
+        .visible;
+    });
+  });
 });

packages/compass-components/src/components/drawer-portal.tsx

@@ -16,6 +16,7 @@ import {
 import { css, cx } from '@leafygreen-ui/emotion';
 import { isEqual } from 'lodash';
 import { rafraf } from '../utils/rafraf';
+import { GuideCue, type GuideCueProps } from './guide-cue/guide-cue';
 import { BaseFontSize, fontWeights } from '@leafygreen-ui/tokens';
 
 type ToolbarData = Required<DrawerLayoutProps>['toolbarData'];
@@ -37,6 +38,7 @@ type DrawerSectionProps = Omit<SectionData, 'content' | 'onClick'> & {
    * provided will stay unordered at the bottom of the list
    */
   order?: number;
+  guideCue?: GuideCueProps<HTMLButtonElement>;
 };
 
 type DrawerOpenStateContextValue = boolean;
@@ -271,21 +273,96 @@ export const DrawerAnchor: React.FunctionComponent = ({ children }) => {
         return orderB < orderA ? 1 : orderB > orderA ? -1 : 0;
       });
   }, [drawerSectionItems]);
+
+  const [toolbarIconNodes, setToolbarIconNodes] = useState<
+    Record<string, HTMLButtonElement | undefined>
+  >({});
+
+  useLayoutEffect(
+    function () {
+      const drawerEl = document.querySelector('.compass-drawer-anchor');
+      if (!drawerEl) {
+        throw new Error(
+          'Can not use DrawerSection without DrawerAnchor being mounted on the page'
+        );
+      }
+
+      function check() {
+        if (!drawerEl) {
+          return;
+        }
+        const nodes: Record<string, HTMLButtonElement | undefined> = {};
+        for (const item of toolbarData) {
+          if (!item.guideCue) {
+            continue;
+          }
+
+          const button = drawerEl.querySelector<HTMLButtonElement>(
+            `button[aria-label="${item.label}"]`
+          );
+          if (button) {
+            nodes[item.id] = button;
+          }
+        }
+
+        setToolbarIconNodes((oldNodes) => {
+          // account for removed nodes by checking all keys of both old and new
+          for (const id of Object.keys({ ...oldNodes, ...nodes })) {
+            if (nodes[id] !== oldNodes[id]) {
+              return nodes;
+            }
+          }
+          return oldNodes;
+        });
+      }
+      check();
+
+      const mutationObserver = new MutationObserver(() => {
+        check();
+      });
+
+      // use a mutation observer because at least in unit tests the button
+      // elements don't exist immediately
+      mutationObserver.observe(drawerEl, {
+        subtree: true,
+        childList: true,
+      });
+      return () => {
+        mutationObserver.disconnect();
+      };
+    },
+    [toolbarData]
+  );
+
   return (
-    <DrawerLayout
-      displayMode={DrawerDisplayMode.Embedded}
-      resizable
-      toolbarData={toolbarData}
-      className={cx(
-        drawerLayoutFixesStyles,
-        toolbarData.length === 0 && emptyDrawerLayoutFixesStyles,
-        // classname is the only property leafygreen passes over to the drawer
-        // wrapper component that would allow us to target it
-        'compass-drawer-anchor'
-      )}
-    >
-      <DrawerContextGrabber>{children}</DrawerContextGrabber>
-    </DrawerLayout>
+    <>
+      {toolbarData.map((item) => {
+        return (
+          toolbarIconNodes[item.id] &&
+          item.guideCue && (
+            <GuideCue<HTMLButtonElement>
+              key={item.id}
+              {...item.guideCue}
+              triggerNode={toolbarIconNodes[item.id]}
+            />
+          )
+        );
+      })}
+      <DrawerLayout
+        displayMode={DrawerDisplayMode.Embedded}
+        resizable
+        toolbarData={toolbarData}
+        className={cx(
+          drawerLayoutFixesStyles,
+          toolbarData.length === 0 && emptyDrawerLayoutFixesStyles,
+          // classname is the only property leafygreen passes over to the drawer
+          // wrapper component that would allow us to target it
+          'compass-drawer-anchor'
+        )}
+      >
+        <DrawerContextGrabber>{children}</DrawerContextGrabber>
+      </DrawerLayout>
+    </>
   );
 };
 

packages/compass-components/src/components/guide-cue/guide-cue.tsx

@@ -89,13 +89,15 @@ export type GuideCueProps<T> = Omit<
   GroupAndStep & {
     cueId: string;
     description: React.ReactChild;
-    trigger: ({ ref }: { ref: React.Ref<T> }) => React.ReactElement;
+    triggerNode?: T;
+    trigger?: ({ ref }: { ref: React.Ref<T> }) => React.ReactElement;
     onOpenChange?: (isOpen: boolean) => void;
   };
 
 export const GuideCue = <T extends HTMLElement>({
   description,
   trigger,
+  triggerNode,
   cueId,
   groupId,
   step,
@@ -106,7 +108,7 @@ export const GuideCue = <T extends HTMLElement>({
 }: GuideCueProps<T>) => {
   const [isCueOpen, setIsCueOpen] = useState(false);
   const [isIntersecting, setIsIntersecting] = useState(true);
-  const refEl = useRef<T>(null);
+  const refEl = useRef<T>(triggerNode ?? null);
   const [readyToRender, setReadyToRender] = useState(false);
   const context = useContext(GuideCueContext);
 
@@ -276,7 +278,7 @@ export const GuideCue = <T extends HTMLElement>({
           {description}
         </LGGuideCue>
       )}
-      {trigger({ ref: refEl })}
+      {trigger?.({ ref: refEl })}
     </>
   );
 };

packages/compass-web/src/compass-assistant-drawer.tsx

@@ -6,7 +6,11 @@ import { CompassAssistantDrawer } from '@mongodb-js/compass-assistant';
 // TODO(COMPASS-7830): This is a temporary solution to pass the
 // hasNonGenuineConnections prop to the CompassAssistantDrawer as otherwise
 // we end up with a circular dependency.
-export function CompassAssistantDrawerWithConnections() {
+export function CompassAssistantDrawerWithConnections({
+  appName,
+}: {
+  appName: string;
+}) {
   // Check for non-genuine connections
   const activeConnectionIds = useConnectionIds(
     (conn) =>
@@ -15,6 +19,7 @@ export function CompassAssistantDrawerWithConnections() {
   );
   return (
     <CompassAssistantDrawer
+      appName={appName}
       hasNonGenuineConnections={activeConnectionIds.length > 0}
     />
   );

packages/compass-web/src/entrypoint.tsx

@@ -305,7 +305,7 @@ function CompassWorkspace({
                   <CreateNamespacePlugin></CreateNamespacePlugin>
                   <DropNamespacePlugin></DropNamespacePlugin>
                   <RenameCollectionPlugin></RenameCollectionPlugin>
-                  <CompassAssistantDrawerWithConnections />
+                  <CompassAssistantDrawerWithConnections appName="Data Explorer" />
                 </>
               );
             }}

packages/compass/src/app/components/compass-assistant-drawer.tsx

@@ -6,7 +6,11 @@ import { CompassAssistantDrawer } from '@mongodb-js/compass-assistant';
 // TODO(COMPASS-7830): This is a temporary solution to pass the
 // hasNonGenuineConnections prop to the CompassAssistantDrawer as otherwise
 // we end up with a circular dependency.
-export function CompassAssistantDrawerWithConnections() {
+export function CompassAssistantDrawerWithConnections({
+  appName,
+}: {
+  appName: string;
+}) {
   // Check for non-genuine connections
   const activeConnectionIds = useConnectionIds(
     (conn) =>
@@ -15,6 +19,7 @@ export function CompassAssistantDrawerWithConnections() {
   );
   return (
     <CompassAssistantDrawer
+      appName={appName}
       hasNonGenuineConnections={activeConnectionIds.length > 0}
     />
   );