@okta/odyssey-react-mui 1.27.0 → 1.28.1

package/src/labs/SideNav/SideNav.tsx

@@ -301,7 +301,13 @@ const SideNav = ({
   const { t } = useTranslation();
   const [sideNavItemsList, updateSideNavItemsList] = useState(sideNavItems);
 
+  // The default value (sideNavItems) passed to useState is ONLY used by the useState hook for
+  // the very first value. Subsequent updates to the prop (sideNavItems) need to cause the state
+  // to update!
+  useEffect(() => updateSideNavItemsList(sideNavItems), [sideNavItems]);
+
   useEffect(() => {
+    // This is called directly in this effect AND perhaps as a result of the ResizeObserver
     const updateIsContentScrollable = () => {
       if (
         scrollableContentRef.current &&
@@ -381,7 +387,7 @@ const SideNav = ({
       }
       cancelAnimationFrame(resizeObserverDebounceTimer); // Ensure timer is cleared on component unmount
     };
-  }, [sideNavItems]);
+  }, [sideNavItemsList]);
 
   const scrollIntoViewRef = useRef<HTMLLIElement>(null);
   /**
@@ -390,7 +396,7 @@ const SideNav = ({
    * call scrollIntoView in the effect
    */
   const firstSideNavItemIdWithIsSelected = useMemo(() => {
-    const flattenedItems = sideNavItems.flatMap((sideNavItem) =>
+    const flattenedItems = sideNavItemsList.flatMap((sideNavItem) =>
       sideNavItem.nestedNavItems
         ? [sideNavItem, ...sideNavItem.nestedNavItems]
         : sideNavItem,
@@ -399,7 +405,7 @@ const SideNav = ({
       (sideNavItem) => sideNavItem.isSelected,
     );
     return firstItemWithIsSelected?.id;
-  }, [sideNavItems]);
+  }, [sideNavItemsList]);
   /**
    * Once we've rendered and if we have an item to scroll to, do the scroll action.
    * This must rely on checking firstSideNavItemIdWithIsSelected or it will not run
@@ -409,7 +415,7 @@ const SideNav = ({
     if (firstSideNavItemIdWithIsSelected && scrollIntoViewRef.current) {
       scrollIntoViewRef.current.scrollIntoView();
     }
-  }, [firstSideNavItemIdWithIsSelected, scrollIntoViewRef]);
+  }, [firstSideNavItemIdWithIsSelected]);
 
   /**
    * We only want to put a ref on a node iff it is the first selected node.

package/src/labs/TopNav/UserProfile.tsx

@@ -18,6 +18,7 @@ import {
   useOdysseyDesignTokens,
 } from "../../OdysseyDesignTokensContext";
 import { Subordinate } from "../../Typography";
+import { Box } from "../../Box";
 
 const UserProfileContainer = styled("div", {
   shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
@@ -37,6 +38,7 @@ const UserProfileIconContainer = styled("div", {
 const UserProfileInfoContainer = styled("div")(() => ({
   display: "flex",
   flexDirection: "column",
+  textAlign: "left",
 }));
 
 export type UserProfileProps = {
@@ -52,9 +54,18 @@ export type UserProfileProps = {
    * Org name of the logged in user
    */
   orgName: string;
+  /**
+   * The icon element to display after the username
+   */
+  userNameEndIcon?: ReactElement;
 };
 
-const UserProfile = ({ profileIcon, userName, orgName }: UserProfileProps) => {
+const UserProfile = ({
+  profileIcon,
+  userName,
+  orgName,
+  userNameEndIcon,
+}: UserProfileProps) => {
   const odysseyDesignTokens = useOdysseyDesignTokens();
 
   return (
@@ -66,7 +77,20 @@ const UserProfile = ({ profileIcon, userName, orgName }: UserProfileProps) => {
       )}
 
       <UserProfileInfoContainer>
-        <Subordinate color="textPrimary">{userName}</Subordinate>
+        {userNameEndIcon ? (
+          <Box
+            sx={{
+              display: "flex",
+              flexDirection: "row",
+              gap: odysseyDesignTokens.Spacing2,
+            }}
+          >
+            <Subordinate color="textPrimary">{userName}</Subordinate>
+            {userNameEndIcon}
+          </Box>
+        ) : (
+          <Subordinate color="textPrimary">{userName}</Subordinate>
+        )}
         <Subordinate color="textSecondary">{orgName}</Subordinate>
       </UserProfileInfoContainer>
     </UserProfileContainer>

package/src/labs/TopNav/UserProfileMenuButton.tsx

@@ -0,0 +1,57 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { memo } from "react";
+import { UserProfile, UserProfileProps } from "./UserProfile";
+import { ChevronDownIcon } from "../../icons.generated";
+import {
+  AdditionalBaseMenuButtonProps,
+  BaseMenuButton,
+  BaseMenuButtonProps,
+} from "../../Buttons/BaseMenuButton";
+
+export type UserProfileMenuButtonProps = Omit<
+  BaseMenuButtonProps,
+  "endIcon" | "variant"
+> &
+  AdditionalBaseMenuButtonProps &
+  UserProfileProps;
+
+const UserProfileMenuButton = (props: UserProfileMenuButtonProps) => {
+  const {
+    profileIcon,
+    userName,
+    orgName,
+    userNameEndIcon,
+    ...menuButtonProps
+  } = props;
+  return (
+    <BaseMenuButton
+      {...menuButtonProps}
+      buttonVariant="floating"
+      omitEndIcon={true}
+      buttonChildren={
+        <UserProfile
+          profileIcon={profileIcon}
+          userName={userName}
+          orgName={orgName}
+          userNameEndIcon={userNameEndIcon ?? <ChevronDownIcon />}
+        />
+      }
+    />
+  );
+};
+
+const MemoizedUserProfileMenuButton = memo(UserProfileMenuButton);
+MemoizedUserProfileMenuButton.displayName = "UserProfileMenuButton";
+
+export { MemoizedUserProfileMenuButton as UserProfileMenuButton };

package/src/labs/TopNav/index.ts

@@ -12,3 +12,4 @@
 
 export * from "./TopNav";
 export * from "./UserProfile";
+export * from "./UserProfileMenuButton";

package/src/labs/UiShell/UiShell.test.tsx

@@ -10,43 +10,13 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import { render, within } from "@testing-library/react";
+import { render, waitFor, within } from "@testing-library/react";
 
-import { Dialog } from "../../Dialog";
 import { defaultComponentProps, UiShell, UiShellProps } from "./UiShell";
 import { ReactElement } from "react";
 
 describe("UiShell", () => {
-  test("renders `appRootElement`", async () => {
-    const appRootElement = document.createElement("div");
-
-    render(
-      <UiShell
-        appComponent={<div />}
-        appRootElement={appRootElement}
-        onSubscriptionCreated={() => {}}
-        optionalComponents={{
-          sideNavFooter: <div />,
-          topNavLeftSide: <div />,
-          topNavRightSide: (
-            <Dialog
-              children={undefined}
-              title="Hello World!"
-              isOpen
-              onClose={() => {}}
-            />
-          ),
-        }}
-        stylesRootElement={document.createElement("div")}
-        subscribeToPropChanges={() => () => {}}
-      />,
-    );
-
-    expect(Array.from(appRootElement.children)).toHaveLength(1);
-    expect(appRootElement).toHaveTextContent("Hello World!");
-  });
-
-  test("renders `stylesRootElement`", async () => {
+  test("renders `stylesRootElement`", () => {
     const rootElement = document.createElement("div");
 
     // If this isn't appended to the DOM, the React app won't exist because of how Web Components run.
@@ -80,7 +50,7 @@ describe("UiShell", () => {
       />,
     );
 
-    expect(within(container).getByTestId(testId)).toBeInTheDocument();
+    expect(within(container).getByTestId(testId)).toBeVisible();
   });
 
   test("renders always-available `componentSlots`", async () => {
@@ -88,6 +58,19 @@ describe("UiShell", () => {
       keyof Required<UiShellProps>["optionalComponents"]
     > = ["banners", "topNavLeftSide", "topNavRightSide"];
 
+    // This is the subscription we give the component, and then once subscribed, we're going to immediately call it with new props.
+    // TopNav won't render unless we pass something into it.
+    const subscribeToPropChanges: UiShellProps["subscribeToPropChanges"] = (
+      subscriber,
+    ) => {
+      subscriber({
+        ...defaultComponentProps,
+        topNavProps: {},
+      });
+
+      return () => {};
+    };
+
     const { container } = render(
       <UiShell
         appComponent={<div />}
@@ -102,12 +85,14 @@ describe("UiShell", () => {
           ) as Record<keyof UiShellProps["optionalComponents"], ReactElement>
         }
         stylesRootElement={document.createElement("div")}
-        subscribeToPropChanges={() => () => {}}
+        subscribeToPropChanges={subscribeToPropChanges}
       />,
     );
 
-    optionalComponentTestIds.forEach((testId) => {
-      expect(within(container).getByTestId(testId)).toBeInTheDocument();
+    await waitFor(() => {
+      optionalComponentTestIds.forEach((testId) => {
+        expect(within(container).getByTestId(testId)).toBeVisible();
+      });
     });
   });
 
@@ -151,7 +136,7 @@ describe("UiShell", () => {
     );
 
     optionalComponentTestIds.forEach((testId) => {
-      expect(within(container).getByTestId(testId)).toBeInTheDocument();
+      expect(within(container).getByTestId(testId)).toBeVisible();
     });
   });
 
@@ -247,7 +232,7 @@ describe("UiShell", () => {
       />,
     );
 
-    expect(container).toBeInTheDocument();
+    expect(container).toBeVisible();
   });
 
   test("has previous state in prop change subscription", async () => {

package/src/labs/UiShell/UiShell.tsx

@@ -23,11 +23,8 @@ import {
 import { type ReactRootElements } from "../../web-component";
 
 export const defaultComponentProps: UiShellNavComponentProps = {
-  sideNavProps: {
-    appName: "",
-    sideNavItems: [],
-  },
-  topNavProps: {},
+  sideNavProps: undefined,
+  topNavProps: undefined,
 } as const;
 
 export type UiShellProps = {
@@ -49,7 +46,14 @@ export type UiShellProps = {
     ) => void,
   ) => () => void;
 } & Pick<ReactRootElements, "appRootElement" | "stylesRootElement"> &
-  Pick<UiShellContentProps, "appComponent" | "onError" | "optionalComponents">;
+  Pick<
+    UiShellContentProps,
+    | "appBackgroundContrastMode"
+    | "appComponent"
+    | "initialVisibleSections"
+    | "onError"
+    | "optionalComponents"
+  >;
 
 /**
  * Our new Unified Platform UI Shell.
@@ -59,8 +63,10 @@ export type UiShellProps = {
  * If an error occurs, this will revert to only showing the app.
  */
 const UiShell = ({
+  appBackgroundContrastMode,
   appComponent,
   appRootElement,
+  initialVisibleSections,
   onError = console.error,
   onSubscriptionCreated,
   optionalComponents,
@@ -93,7 +99,9 @@ const UiShell = ({
 
           <UiShellContent
             {...componentProps}
+            appBackgroundContrastMode={appBackgroundContrastMode}
             appComponent={appComponent}
+            initialVisibleSections={initialVisibleSections}
             onError={onError}
             optionalComponents={optionalComponents}
           />

package/src/labs/UiShell/UiShellContent.tsx

@@ -14,6 +14,7 @@ import styled from "@emotion/styled";
 import { memo, type ReactElement, type ReactNode } from "react";
 import { ErrorBoundary, ErrorBoundaryProps } from "react-error-boundary";
 
+import { AppSwitcher, type AppSwitcherProps } from "../AppSwitcher";
 import { SideNav, type SideNavProps } from "../SideNav";
 import { TopNav, type TopNavProps } from "../TopNav";
 import {
@@ -21,23 +22,36 @@ import {
   type DesignTokens,
 } from "../../OdysseyDesignTokensContext";
 import { useScrollState } from "./useScrollState";
+import { ContrastMode } from "../../useContrastMode";
+
+const emptySideNavItems = [] satisfies SideNavProps["sideNavItems"];
 
 const StyledAppContainer = styled("div", {
-  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+  shouldForwardProp: (prop) =>
+    prop !== "odysseyDesignTokens" && prop !== "appBackgroundContrastMode",
 })<{
+  appBackgroundContrastMode: ContrastMode;
   odysseyDesignTokens: DesignTokens;
-}>(({ odysseyDesignTokens }) => ({
+}>(({ appBackgroundContrastMode, odysseyDesignTokens }) => ({
   gridArea: "app-content",
   overflowX: "hidden",
   overflowY: "auto",
   paddingBlock: odysseyDesignTokens.Spacing5,
   paddingInline: odysseyDesignTokens.Spacing8,
+  backgroundColor:
+    appBackgroundContrastMode === "highContrast"
+      ? odysseyDesignTokens.HueNeutralWhite
+      : odysseyDesignTokens.HueNeutral50,
 }));
 
 const StyledBannersContainer = styled("div")(() => ({
   gridArea: "banners",
 }));
 
+const StyledAppSwitcherContainer = styled("div")(() => ({
+  gridArea: "app-switcher",
+}));
+
 const StyledSideNavContainer = styled("div")(() => ({
   gridArea: "side-nav",
 }));
@@ -51,11 +65,11 @@ const StyledShellContainer = styled("div", {
   display: "grid",
   gridGap: 0,
   gridTemplateAreas: `
-    "banners banners"
-    "side-nav top-nav"
-    "side-nav app-content"
+    "banners banners banners"
+    "app-switcher side-nav top-nav"
+    "app-switcher side-nav app-content"
   `,
-  gridTemplateColumns: "auto 1fr",
+  gridTemplateColumns: "auto auto 1fr",
   gridTemplateRows: "auto auto 1fr",
   height: "100vh",
   width: "100vw",
@@ -65,7 +79,14 @@ const StyledTopNavContainer = styled("div")(() => ({
   gridArea: "top-nav",
 }));
 
+export const subComponentNames = ["TopNav", "SideNav", "AppSwitcher"] as const;
+export type SubComponentName = (typeof subComponentNames)[number];
+
 export type UiShellNavComponentProps = {
+  /**
+   * Object that gets pass directly to the app switcher component.
+   */
+  appSwitcherProps?: AppSwitcherProps;
   /**
    * Object that gets pass directly to the side nav component.
    */
@@ -73,14 +94,23 @@ export type UiShellNavComponentProps = {
   /**
    * Object that gets pass directly to the top nav component.
    */
-  topNavProps: Omit<TopNavProps, "leftSideComponent" | "rightSideComponent">;
+  topNavProps?: Omit<TopNavProps, "leftSideComponent" | "rightSideComponent">;
 };
 
 export type UiShellContentProps = {
+  /**
+   * Sets the background color for the app content area.
+   */
+  appBackgroundContrastMode?: ContrastMode;
   /**
    * React app component that renders as children in the correct location of the shell.
    */
   appComponent: ReactNode;
+  /**
+   * Which parts of the UI Shell should be visible initially? For example,
+   * if sideNavProps is undefined, should the space for the sidenav be initially visible?
+   */
+  initialVisibleSections?: SubComponentName[];
   /**
    * Notifies when a React rendering error occurs. This could be useful for logging, flagging "p0"s, and recovering UI Shell when errors occur.
    */
@@ -104,9 +134,12 @@ export type UiShellContentProps = {
  * If an error occurs, this will revert to only showing the app.
  */
 const UiShellContent = ({
+  appBackgroundContrastMode = "lowContrast",
   appComponent,
+  initialVisibleSections = ["TopNav", "SideNav", "AppSwitcher"],
   onError = console.error,
   optionalComponents,
+  appSwitcherProps,
   sideNavProps,
   topNavProps,
 }: UiShellContentProps) => {
@@ -119,7 +152,32 @@ const UiShellContent = ({
         {optionalComponents?.banners}
       </StyledBannersContainer>
 
+      <StyledAppSwitcherContainer>
+        {
+          /* If AppSwitcher should be initially visible and we have not yet received props, render AppSwitcher in the loading state */
+          initialVisibleSections?.includes("AppSwitcher") &&
+            !appSwitcherProps && (
+              <ErrorBoundary fallback={null} onError={onError}>
+                <AppSwitcher isLoading appIcons={[]} selectedAppName="" />
+              </ErrorBoundary>
+            )
+        }
+        {appSwitcherProps && (
+          <ErrorBoundary fallback={null} onError={onError}>
+            <AppSwitcher {...appSwitcherProps} />
+          </ErrorBoundary>
+        )}
+      </StyledAppSwitcherContainer>
+
       <StyledSideNavContainer>
+        {
+          /* If SideNav should be initially visible and we have not yet received props, render SideNav with minimal inputs */
+          initialVisibleSections?.includes("SideNav") && !sideNavProps && (
+            <ErrorBoundary fallback={null} onError={onError}>
+              <SideNav isLoading appName="" sideNavItems={emptySideNavItems} />
+            </ErrorBoundary>
+          )
+        }
         {sideNavProps && (
           <ErrorBoundary fallback={null} onError={onError}>
             <SideNav
@@ -143,20 +201,31 @@ const UiShellContent = ({
       </StyledSideNavContainer>
 
       <StyledTopNavContainer>
-        <ErrorBoundary fallback={null} onError={onError}>
-          <TopNav
-            {...topNavProps}
-            isScrolled={isContentScrolled}
-            leftSideComponent={optionalComponents?.topNavLeftSide}
-            rightSideComponent={optionalComponents?.topNavRightSide}
-          />
-        </ErrorBoundary>
+        {
+          /* If TopNav should be initially visible and we have not yet received props, render Topnav with minimal inputs */
+          initialVisibleSections?.includes("TopNav") && !topNavProps && (
+            <ErrorBoundary fallback={null} onError={onError}>
+              <TopNav />
+            </ErrorBoundary>
+          )
+        }
+        {topNavProps && (
+          <ErrorBoundary fallback={null} onError={onError}>
+            <TopNav
+              {...topNavProps}
+              isScrolled={isContentScrolled}
+              leftSideComponent={optionalComponents?.topNavLeftSide}
+              rightSideComponent={optionalComponents?.topNavRightSide}
+            />
+          </ErrorBoundary>
+        )}
       </StyledTopNavContainer>
 
       <StyledAppContainer
         odysseyDesignTokens={odysseyDesignTokens}
-        tabIndex={0}
+        appBackgroundContrastMode={appBackgroundContrastMode}
         ref={scrollableContentRef}
+        tabIndex={0}
       >
         {appComponent}
       </StyledAppContainer>

package/src/labs/UiShell/renderUiShell.test.tsx

@@ -10,7 +10,7 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import { act } from "@testing-library/react";
+import { act, waitFor } from "@testing-library/react";
 
 import { renderUiShell } from "./renderUiShell";
 import {
@@ -126,9 +126,11 @@ describe("renderUiShell", () => {
       });
     });
 
-    expect(
-      rootElement.querySelector(reactWebComponentElementName)!.shadowRoot,
-    ).toHaveTextContent(appName);
+    await waitFor(() => {
+      expect(
+        rootElement.querySelector(reactWebComponentElementName)!.shadowRoot,
+      ).toHaveTextContent(appName);
+    });
   });
 
   test("renders `UiShell` with immediately updated props", async () => {
@@ -153,9 +155,11 @@ describe("renderUiShell", () => {
       });
     });
 
-    expect(
-      rootElement.querySelector(reactWebComponentElementName)!.shadowRoot,
-    ).toHaveTextContent(appName);
+    await waitFor(() => {
+      expect(
+        rootElement.querySelector(reactWebComponentElementName)!.shadowRoot,
+      ).toHaveTextContent(appName);
+    });
   });
 
   test("renders `<slot>` in the event of an error", async () => {
@@ -184,14 +188,16 @@ describe("renderUiShell", () => {
       );
     });
 
-    consoleErrorSpy.mockRestore();
+    await waitFor(() => {
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(consoleError).toHaveBeenCalledTimes(1);
+      expect(
+        rootElement
+          .querySelector(reactWebComponentElementName)!
+          .shadowRoot?.querySelector("slot"),
+      ).toBeInstanceOf(HTMLSlotElement);
+    });
 
-    expect(onError).toHaveBeenCalledTimes(1);
-    expect(consoleError).toHaveBeenCalledTimes(1);
-    expect(
-      rootElement
-        .querySelector(reactWebComponentElementName)!
-        .shadowRoot?.querySelector("slot"),
-    ).toBeInstanceOf(HTMLSlotElement);
+    consoleErrorSpy.mockRestore();
   });
 });

package/src/labs/UiShell/renderUiShell.tsx

@@ -41,7 +41,9 @@ export const optionalComponentSlotNames: Record<
  * It also provides you with other elements fitted to slots in the web component. **In React, you can portal to these components.**
  */
 export const renderUiShell = ({
+  appBackgroundContrastMode,
   appRootElement: explicitAppRootElement,
+  initialVisibleSections,
   onError = console.error,
   uiShellRootElement,
 }: {
@@ -57,7 +59,10 @@ export const renderUiShell = ({
    * HTML element used as the root for UI Shell.
    */
   uiShellRootElement: HTMLElement;
-}) => {
+} & Pick<
+  UiShellProps,
+  "appBackgroundContrastMode" | "initialVisibleSections"
+>) => {
   const appRootElement =
     explicitAppRootElement || document.createElement("div");
 
@@ -101,8 +106,10 @@ export const renderUiShell = ({
     getReactComponent: (reactRootElements) => (
       <ErrorBoundary fallback={appComponent} onError={onError}>
         <UiShell
+          appBackgroundContrastMode={appBackgroundContrastMode}
           appComponent={appComponent}
           appRootElement={reactRootElements.appRootElement}
+          initialVisibleSections={initialVisibleSections}
           onError={onError}
           onSubscriptionCreated={publishSubscriptionCreated}
           // `optionalComponents` doesn't need to be memoized because gets passed in once.

package/src/labs/index.ts

@@ -40,6 +40,7 @@ export {
   type GroupPickerProps,
 } from "./GroupPicker";
 
+export * from "./AppSwitcher";
 export * from "./SideNav/NavAccordion";
 export * from "./SideNav";
 export * from "./TopNav";