WIP

Author: stephl3

packages/drawer/package.json

@@ -48,6 +48,7 @@
   "devDependencies": {
     "@faker-js/faker": "^8.0.2",
     "@storybook/test": "8.5.3",
+    "@leafygreen-ui/guide-cue": "workspace:^",
     "@lg-tools/build": "workspace:^"
   },
   "peerDependencies": {

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayout.spec.tsx

@@ -259,4 +259,38 @@ describe('packages/DrawerToolbarLayout', () => {
 
     expect(isOpen()).toBe(false);
   });
+
+  test('passes ref correctly to ToolbarIconButton instances', () => {
+    const codeButtonRef = React.createRef<HTMLButtonElement>();
+    const code2ButtonRef = React.createRef<HTMLButtonElement>();
+
+    const dataWithRefs: DrawerLayoutProps['toolbarData'] = [
+      {
+        id: 'Code',
+        label: 'Code',
+        content: 'Drawer Content',
+        title: `Drawer Title`,
+        glyph: 'Code',
+        ref: codeButtonRef,
+      },
+      {
+        id: 'Code2',
+        label: 'Code2',
+        content: 'Drawer Content2',
+        title: `Drawer Title2`,
+        glyph: 'Code',
+        ref: code2ButtonRef,
+      },
+    ];
+
+    render(<Component data={dataWithRefs} />);
+
+    // Verify that refs are properly assigned to DOM elements
+    expect(codeButtonRef.current).toBeInstanceOf(HTMLButtonElement);
+    expect(code2ButtonRef.current).toBeInstanceOf(HTMLButtonElement);
+
+    // Verify the elements have the correct labels
+    expect(codeButtonRef.current).toHaveAttribute('aria-label', 'Code');
+    expect(code2ButtonRef.current).toHaveAttribute('aria-label', 'Code2');
+  });
 });

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayout.stories.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import {
   storybookArgTypes,
   storybookExcludedControlParams,
@@ -8,6 +8,8 @@ import { StoryFn, StoryObj } from '@storybook/react';
 
 import Button from '@leafygreen-ui/button';
 import { css } from '@leafygreen-ui/emotion';
+import { GuideCue } from '@leafygreen-ui/guide-cue';
+import { usePrevious } from '@leafygreen-ui/hooks';
 import { palette } from '@leafygreen-ui/palette';
 import { spacing } from '@leafygreen-ui/tokens';
 
@@ -444,3 +446,131 @@ export const EmbeddedDynamic: StoryObj<DrawerLayoutProps> = {
     },
   },
 };
+
+interface MainContentProps {
+  setGuideCueKey: React.Dispatch<React.SetStateAction<number>>;
+  setGuideCueOpen: (open: boolean) => void;
+}
+
+const MainContent: React.FC<MainContentProps> = ({
+  setGuideCueKey,
+  setGuideCueOpen,
+}) => {
+  const { isDrawerOpen } = useDrawerToolbarContext();
+  const prevIsDrawerOpen = usePrevious(isDrawerOpen);
+
+  // Force GuideCue rerender when drawer state changes for immediate repositioning
+  useEffect(() => {
+    if (prevIsDrawerOpen !== undefined && prevIsDrawerOpen !== isDrawerOpen) {
+      setGuideCueKey((prev: number) => prev + 1);
+    }
+  }, [isDrawerOpen, prevIsDrawerOpen, setGuideCueKey]);
+
+  return (
+    <main
+      className={css`
+        padding: ${spacing[400]}px;
+      `}
+    >
+      <div
+        className={css`
+          display: flex;
+          flex-direction: column;
+          align-items: flex-start;
+          gap: ${spacing[200]}px;
+        `}
+      >
+        <Button onClick={() => setGuideCueOpen(true)}>
+          Show GuideCue on Dashboard Button
+        </Button>
+        <p>
+          This example demonstrates how to use refs in toolbarData to attach a
+          GuideCue to a toolbar icon button. The button tooltip is
+          automatically disabled while the GuideCue is visible to prevent
+          conflicts between the two overlays.
+        </p>
+      </div>
+      <LongContent />
+    </main>
+  );
+};
+
+const WithGuideCueComponent: StoryFn<DrawerLayoutProps> = ({
+  displayMode,
+}: DrawerLayoutProps) => {
+  const dashboardButtonRef = useRef<HTMLButtonElement>(null);
+  const [guideCueOpen, setGuideCueOpen] = useState(false);
+  const [guideCueKey, setGuideCueKey] = useState(0);
+
+  // Use useMemo to make toolbar data reactive to guideCueOpen state changes
+  const DRAWER_TOOLBAR_DATA: DrawerLayoutProps['toolbarData'] = useMemo(
+    () => [
+      {
+        id: 'Code',
+        label: 'Code',
+        content: <LongContent />,
+        title: 'Code',
+        glyph: 'Code',
+      },
+      {
+        id: 'Dashboard',
+        label: 'Dashboard',
+        content: <LongContent />,
+        title: 'Dashboard',
+        glyph: 'Dashboard',
+        ref: dashboardButtonRef, // This ref is passed to the ToolbarIconButton
+        tooltipEnabled: !guideCueOpen, // Disable tooltip when guide cue is open
+      },
+      {
+        id: 'Apps',
+        label: 'Apps',
+        content: <LongContent />,
+        title: 'Apps',
+        glyph: 'Apps',
+      },
+    ],
+    [guideCueOpen],
+  ); // Re-compute when guideCueOpen changes
+
+  return (
+    <div
+      className={css`
+        height: 90vh;
+        width: 100%;
+      `}
+    >
+      <DrawerLayout displayMode={displayMode} toolbarData={DRAWER_TOOLBAR_DATA}>
+        <MainContent
+          setGuideCueKey={setGuideCueKey}
+          setGuideCueOpen={setGuideCueOpen}
+        />
+      </DrawerLayout>
+
+      <GuideCue
+        key={`guide-cue-${guideCueKey}`} // Force rerender on drawer state changes
+        open={guideCueOpen} // Always show when toggled
+        setOpen={setGuideCueOpen}
+        title="Dashboard Feature"
+        refEl={dashboardButtonRef}
+        numberOfSteps={1}
+        onPrimaryButtonClick={() => setGuideCueOpen(false)}
+        tooltipAlign="left"
+        tooltipJustify="start"
+      >
+        Click here to access your dashboard with analytics and insights!
+      </GuideCue>
+    </div>
+  );
+};
+
+export const WithGuideCue: StoryObj<DrawerLayoutProps> = {
+  render: WithGuideCueComponent,
+  args: {
+    displayMode: DisplayMode.Overlay,
+  },
+  parameters: {
+    controls: {
+      exclude: toolbarExcludedControls,
+    },
+  },
+};

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayout.types.ts

@@ -5,7 +5,7 @@ import { ToolbarIconButtonProps } from '@leafygreen-ui/toolbar';
 
 type PickedRequiredToolbarIconButtonProps = Pick<
   ToolbarIconButtonProps,
-  'glyph' | 'label' | 'onClick' | 'disabled'
+  'glyph' | 'label' | 'onClick' | 'disabled' | 'tooltipEnabled'
 >;
 
 interface LayoutBase extends PickedRequiredToolbarIconButtonProps {
@@ -19,6 +19,11 @@ interface LayoutBase extends PickedRequiredToolbarIconButtonProps {
    * @defaultValue true
    */
   visible?: boolean;
+
+  /**
+   * Optional ref to be passed to the ToolbarIconButton instance.
+   */
+  ref?: React.RefObject<HTMLButtonElement>;
 }
 
 interface LayoutWithContent extends LayoutBase {

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayoutContent.tsx

@@ -120,6 +120,8 @@ export const DrawerToolbarLayoutContent = forwardRef<
               }}
               active={toolbarItem.id === id}
               disabled={toolbarItem.disabled}
+              ref={toolbarItem.ref}
+              tooltipEnabled={toolbarItem.tooltipEnabled}
             />
           ))}
         </Toolbar>

packages/drawer/tsconfig.json

@@ -23,6 +23,9 @@
     {
       "path": "../emotion"
     },
+    {
+      "path": "../guide-cue"
+    },
     {
       "path": "../hooks"
     },

packages/toolbar/src/ToolbarIconButton/ToolbarIconButton.spec.tsx

@@ -1,5 +1,6 @@
 import React, { createRef } from 'react';
 import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
 
 import { Toolbar } from '../Toolbar';
@@ -35,6 +36,48 @@ describe('packages/toolbar-icon-button', () => {
     expect(ref.current).toBeDefined();
     expect(ref.current).toBeInstanceOf(HTMLButtonElement);
   });
+
+  test('shows tooltip on hover when tooltipEnabled is true', async () => {
+    const { getByRole, findByRole } = render(
+      <Toolbar>
+        <ToolbarIconButton
+          glyph="Code"
+          label="Code Tooltip"
+          tooltipEnabled={true}
+        />
+      </Toolbar>,
+    );
+
+    const button = getByRole('button');
+    userEvent.hover(button);
+
+    // Tooltip should appear
+    const tooltip = await findByRole('tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(tooltip).toHaveTextContent('Code Tooltip');
+  });
+
+  test('does not show tooltip on hover when tooltipEnabled is false', async () => {
+    const { getByRole, queryByRole } = render(
+      <Toolbar>
+        <ToolbarIconButton
+          glyph="Code"
+          label="Code Tooltip"
+          tooltipEnabled={false}
+        />
+      </Toolbar>,
+    );
+
+    const button = getByRole('button');
+    userEvent.hover(button);
+
+    // Wait a bit to ensure tooltip would have appeared if enabled
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Tooltip should not appear
+    const tooltip = queryByRole('tooltip');
+    expect(tooltip).not.toBeInTheDocument();
+  });
 });
 
 /* eslint-disable jest/no-disabled-tests */

packages/toolbar/src/ToolbarIconButton/ToolbarIconButton.tsx

@@ -24,6 +24,7 @@ export const ToolbarIconButton = React.forwardRef<
       glyph,
       disabled = false,
       active = false,
+      tooltipEnabled = true,
       'aria-label': ariaLabel,
       ...rest
     }: ToolbarIconButtonProps,
@@ -60,6 +61,7 @@ export const ToolbarIconButton = React.forwardRef<
         data-testid={`${lgIds.iconButtonTooltip}-${index}`}
         data-lgid={`${lgIds.iconButtonTooltip}-${index}`}
         align={Align.Left}
+        enabled={tooltipEnabled}
         trigger={
           <div className={triggerStyles}>
             <IconButton

packages/toolbar/src/ToolbarIconButton/ToolbarIconButton.types.ts

@@ -28,4 +28,11 @@ export interface ToolbarIconButtonProps extends ButtonProps {
    *  Callback fired when the ToolbarIconButton is clicked
    */
   onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * Enables the tooltip to trigger based on hover events.
+   * When false, the tooltip will not show on hover.
+   * @default true
+   */
+  tooltipEnabled?: boolean;
 }