@okta/odyssey-react-mui 1.25.0 → 1.26.0

package/src/labs/TopNav/TopNavListItem.tsx

@@ -0,0 +1,209 @@
+/*!
+ * 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 styled from "@emotion/styled";
+import {
+  memo,
+  useCallback,
+  KeyboardEventHandler,
+  MouseEventHandler,
+} from "react";
+
+import { Link } from "../../Link";
+import {
+  DesignTokens,
+  useOdysseyDesignTokens,
+} from "../../OdysseyDesignTokensContext";
+
+const StyledTopNavItemLabelContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})<{
+  odysseyDesignTokens: DesignTokens;
+}>(({ odysseyDesignTokens }) => ({
+  alignItems: "center",
+  display: "flex",
+  flexWrap: "wrap",
+  fontSize: odysseyDesignTokens.TypographyScale0,
+  fontWeight: odysseyDesignTokens.TypographyWeightHeading,
+}));
+
+const StyledTopNavListItem = styled("li", {
+  shouldForwardProp: (prop) =>
+    prop !== "odysseyDesignTokens" && prop !== "isDisabled",
+})<{
+  odysseyDesignTokens: DesignTokens;
+  isDisabled?: boolean;
+}>(({ odysseyDesignTokens, isDisabled }) => ({
+  alignItems: "center",
+  color: `${isDisabled ? odysseyDesignTokens.TypographyColorDisabled : odysseyDesignTokens.TypographyColorHeading} !important`,
+  cursor: isDisabled ? "default" : "pointer",
+  display: "flex",
+  pointerEvents: isDisabled ? "none" : "auto",
+
+  a: {
+    alignItems: "center",
+    color: `${odysseyDesignTokens.TypographyColorHeading} !important`,
+    display: "flex",
+    paddingBlock: odysseyDesignTokens.Spacing2,
+    paddingInline: odysseyDesignTokens.Spacing4,
+
+    "&:hover": {
+      backgroundColor: !isDisabled
+        ? odysseyDesignTokens.HueNeutral50
+        : "inherit",
+      textDecoration: "none",
+    },
+
+    "&:focus-visible": {
+      backgroundColor: !isDisabled
+        ? odysseyDesignTokens.HueNeutral50
+        : "inherit",
+      borderRadius: 0,
+      outlineOffset: 0,
+      outlineWidth: odysseyDesignTokens.FocusOutlineWidthMain,
+    },
+  },
+
+  "div[role='button']:hover": {
+    backgroundColor: !isDisabled ? odysseyDesignTokens.HueNeutral50 : "inherit",
+  },
+}));
+
+const StyledNavItemContentClickContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})<{
+  odysseyDesignTokens: DesignTokens;
+}>(({ odysseyDesignTokens }) => ({
+  alignItems: "center",
+  display: "flex",
+  paddingBlock: odysseyDesignTokens.Spacing2,
+  paddingInline: odysseyDesignTokens.Spacing4,
+  width: "100%",
+
+  "&:focus-visible": {
+    backgroundColor: odysseyDesignTokens.HueNeutral50,
+    borderRadius: 0,
+    outlineColor: odysseyDesignTokens.FocusOutlineColorPrimary,
+    outlineStyle: odysseyDesignTokens.FocusOutlineStyle,
+    outlineWidth: odysseyDesignTokens.FocusOutlineWidthMain,
+    textDecoration: "none",
+  },
+}));
+
+export type TopNavListItemProps = {
+  /**
+   * Without a hyperlink reference, `onClick` functionality will not function.
+   * If `undefined`, static text will be displayed.
+   */
+  href?: string;
+  /**
+   * HTML `id` attribute.
+   */
+  id: string;
+  /**
+   * Determines whether the link item is disabled.
+   */
+  isDisabled?: boolean;
+  /**
+   * Display text for the link.
+   */
+  label: string;
+  /**
+   * Handles both mouse and keyboard interactions.
+   */
+  onClick?: MouseEventHandler<HTMLAnchorElement> &
+    MouseEventHandler<HTMLDivElement> &
+    KeyboardEventHandler<HTMLDivElement>;
+  /**
+   * Where to display the linked URL.
+   */
+  target?: string;
+};
+
+const TopNavListItem = ({
+  href,
+  id,
+  isDisabled,
+  label,
+  onClick,
+  target,
+}: TopNavListItemProps) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+
+  const topNavItemContentKeyHandler = useCallback<
+    KeyboardEventHandler<HTMLDivElement>
+  >(
+    (event) => {
+      if (event?.key === "Enter") {
+        event.preventDefault();
+        event.stopPropagation();
+        onClick?.(event);
+      }
+    },
+    [onClick],
+  );
+
+  return (
+    <StyledTopNavListItem
+      aria-disabled={isDisabled}
+      id={id}
+      isDisabled={isDisabled}
+      odysseyDesignTokens={odysseyDesignTokens}
+    >
+      {
+        // Use Link for nav items with links and div for disabled or non-link items
+        isDisabled && (
+          <StyledNavItemContentClickContainer
+            odysseyDesignTokens={odysseyDesignTokens}
+          >
+            <StyledTopNavItemLabelContainer
+              odysseyDesignTokens={odysseyDesignTokens}
+            >
+              {label}
+            </StyledTopNavItemLabelContainer>
+          </StyledNavItemContentClickContainer>
+        )
+      }
+
+      {!isDisabled && href && (
+        <Link href={href} onClick={onClick} target={target}>
+          <StyledTopNavItemLabelContainer
+            odysseyDesignTokens={odysseyDesignTokens}
+          >
+            {label}
+          </StyledTopNavItemLabelContainer>
+        </Link>
+      )}
+
+      {!isDisabled && !href && (
+        <StyledNavItemContentClickContainer
+          odysseyDesignTokens={odysseyDesignTokens}
+          onClick={onClick}
+          onKeyDown={topNavItemContentKeyHandler}
+          role="button"
+          tabIndex={0}
+        >
+          <StyledTopNavItemLabelContainer
+            odysseyDesignTokens={odysseyDesignTokens}
+          >
+            {label}
+          </StyledTopNavItemLabelContainer>
+        </StyledNavItemContentClickContainer>
+      )}
+    </StyledTopNavListItem>
+  );
+};
+
+const MemoizedTopNavListItem = memo(TopNavListItem);
+MemoizedTopNavListItem.displayName = "TopNavListItem";
+
+export { MemoizedTopNavListItem as TopNavListItem };

package/src/labs/TopNav/UserProfile.tsx

@@ -0,0 +1,79 @@
+/*!
+ * 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 styled from "@emotion/styled";
+import { memo, type ReactElement } from "react";
+
+import {
+  DesignTokens,
+  useOdysseyDesignTokens,
+} from "../../OdysseyDesignTokensContext";
+import { Subordinate } from "../../Typography";
+
+const UserProfileContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})(({ odysseyDesignTokens }: { odysseyDesignTokens: DesignTokens }) => ({
+  display: "flex",
+  alignItems: "center",
+  paddingInlineEnd: odysseyDesignTokens.Spacing4,
+}));
+
+const UserProfileIconContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})(({ odysseyDesignTokens }: { odysseyDesignTokens: DesignTokens }) => ({
+  display: "flex",
+  paddingInlineEnd: odysseyDesignTokens.Spacing2,
+}));
+
+const UserProfileInfoContainer = styled("div")(() => ({
+  display: "flex",
+  flexDirection: "column",
+}));
+
+export type UserProfileProps = {
+  /**
+   * Logged in user profile icon to be displayed in the top nav
+   */
+  profileIcon?: ReactElement;
+  /**
+   * Logged in user info to be displayed in the top nav
+   */
+  userName: string;
+  /**
+   * Org name of the logged in user
+   */
+  orgName: string;
+};
+
+const UserProfile = ({ profileIcon, userName, orgName }: UserProfileProps) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+
+  return (
+    <UserProfileContainer odysseyDesignTokens={odysseyDesignTokens}>
+      {profileIcon && (
+        <UserProfileIconContainer odysseyDesignTokens={odysseyDesignTokens}>
+          {profileIcon}
+        </UserProfileIconContainer>
+      )}
+
+      <UserProfileInfoContainer>
+        <Subordinate color="textPrimary">{userName}</Subordinate>
+        <Subordinate color="textSecondary">{orgName}</Subordinate>
+      </UserProfileInfoContainer>
+    </UserProfileContainer>
+  );
+};
+
+const MemoizedUserProfile = memo(UserProfile);
+MemoizedUserProfile.displayName = "UserProfile";
+
+export { MemoizedUserProfile as UserProfile };

package/src/labs/TopNav/index.ts

@@ -0,0 +1,14 @@
+/*!
+ * 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.
+ */
+
+export * from "./TopNav";
+export * from "./UserProfile";

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

@@ -0,0 +1,284 @@
+/*!
+ * 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 { render, 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 () => {
+    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.
+    document.body.append(rootElement);
+
+    const stylesRootElement = document.createElement("div");
+
+    render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={stylesRootElement}
+        subscribeToPropChanges={() => () => {}}
+      />,
+    );
+
+    expect(Array.from(stylesRootElement.children).length).toBeGreaterThan(0);
+  });
+
+  test("renders `appComponent`", async () => {
+    const testId = "app-component";
+
+    const { container } = render(
+      <UiShell
+        appComponent={<div data-testid={testId} />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={() => () => {}}
+      />,
+    );
+
+    expect(within(container).getByTestId(testId)).toBeInTheDocument();
+  });
+
+  test("renders always-available `componentSlots`", async () => {
+    const optionalComponentTestIds: Array<
+      keyof Required<UiShellProps>["optionalComponents"]
+    > = ["banners", "topNavLeftSide", "topNavRightSide"];
+
+    const { container } = render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        optionalComponents={
+          Object.fromEntries(
+            optionalComponentTestIds.map((testId) => [
+              testId,
+              <div data-testid={testId} />,
+            ]),
+          ) as Record<keyof UiShellProps["optionalComponents"], ReactElement>
+        }
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={() => () => {}}
+      />,
+    );
+
+    optionalComponentTestIds.forEach((testId) => {
+      expect(within(container).getByTestId(testId)).toBeInTheDocument();
+    });
+  });
+
+  test("renders optionally-available `componentSlots`", async () => {
+    const optionalComponentTestIds: Array<
+      keyof Required<UiShellProps>["optionalComponents"]
+    > = ["sideNavFooter"];
+
+    // This is the subscription we give the component, and then once subscribed, we're going to immediately call it with new props.
+    const subscribeToPropChanges: UiShellProps["subscribeToPropChanges"] = (
+      subscriber,
+    ) => {
+      subscriber({
+        ...defaultComponentProps,
+        sideNavProps: {
+          appName: "",
+          hasCustomFooter: true,
+          sideNavItems: [],
+        },
+      });
+
+      return () => {};
+    };
+
+    const { container } = render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        optionalComponents={
+          Object.fromEntries(
+            optionalComponentTestIds.map((testId) => [
+              testId,
+              <div data-testid={testId} />,
+            ]),
+          ) as Record<keyof UiShellProps["optionalComponents"], ReactElement>
+        }
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={subscribeToPropChanges}
+      />,
+    );
+
+    optionalComponentTestIds.forEach((testId) => {
+      expect(within(container).getByTestId(testId)).toBeInTheDocument();
+    });
+  });
+
+  test("unsubscribes from prop changes when unmounted", async () => {
+    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.
+    document.body.append(rootElement);
+
+    const unsubscribeFromPropChanges = jest.fn();
+    const subscribeToPropChanges = jest.fn(() => unsubscribeFromPropChanges);
+
+    const { unmount } = render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={subscribeToPropChanges}
+      />,
+    );
+
+    unmount();
+
+    expect(subscribeToPropChanges).toHaveBeenCalledTimes(1);
+    expect(unsubscribeFromPropChanges).toHaveBeenCalledTimes(1);
+  });
+
+  test("allows changing props through the subscription", async () => {
+    const rootElement = document.createElement("div");
+    const sideNavItemText = "Add New Folder";
+
+    // If this isn't appended to the DOM, the React app won't exist because of how Web Components run.
+    document.body.append(rootElement);
+
+    // This is the subscription we give the component, and then once subscribed, we're going to immediately call it with new props.
+    const subscribeToPropChanges: UiShellProps["subscribeToPropChanges"] = (
+      subscriber,
+    ) => {
+      subscriber({
+        ...defaultComponentProps,
+        sideNavProps: {
+          appName: "",
+          sideNavItems: [
+            {
+              id: "AddNewFolder",
+              label: sideNavItemText,
+              onClick: () => {},
+            },
+          ],
+        },
+      });
+
+      return () => {};
+    };
+
+    const { container } = render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={subscribeToPropChanges}
+      />,
+    );
+
+    expect(container).toHaveTextContent(sideNavItemText);
+  });
+
+  test("uses default props if no value passed to subscription", async () => {
+    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.
+    document.body.append(rootElement);
+
+    // This is the subscription we give the component, and then once subscribed, we're going to immediately call it with new props.
+    const subscribeToPropChanges: UiShellProps["subscribeToPropChanges"] = (
+      subscriber,
+    ) => {
+      // @ts-expect-error This unit test is checking what happens when we don't pass a value.
+      subscriber();
+
+      return () => {};
+    };
+
+    const { container } = render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={subscribeToPropChanges}
+      />,
+    );
+
+    expect(container).toBeInTheDocument();
+  });
+
+  test("has previous state in prop change subscription", async () => {
+    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.
+    document.body.append(rootElement);
+
+    // This passed to React's state setter. The return value here prevents a test error. It wouldn't be required otherwise as this test could care less what's returned.
+    const stateUpdater = jest.fn(() => defaultComponentProps);
+
+    // This is the subscription we give the component, and then once subscribed, we're going to immediately call it to see if it passes us the previous state.
+    const subscribeToPropChanges: UiShellProps["subscribeToPropChanges"] = (
+      subscriber,
+    ) => {
+      subscriber(stateUpdater);
+
+      return () => {};
+    };
+
+    render(
+      <UiShell
+        appComponent={<div />}
+        appRootElement={document.createElement("div")}
+        onSubscriptionCreated={() => {}}
+        stylesRootElement={document.createElement("div")}
+        subscribeToPropChanges={subscribeToPropChanges}
+      />,
+    );
+
+    expect(stateUpdater).toHaveBeenCalledWith(defaultComponentProps);
+    expect(stateUpdater).toHaveBeenCalledTimes(1);
+  });
+});

package/src/labs/UiShell/UiShell.tsx

@@ -0,0 +1,109 @@
+/*!
+ * 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, useEffect, useState, type SetStateAction } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+
+import { CssBaseline } from "../../CssBaseline";
+import { OdysseyProvider } from "../../OdysseyProvider";
+import {
+  UiShellContent,
+  type UiShellContentProps,
+  type UiShellNavComponentProps,
+} from "./UiShellContent";
+import { type ReactRootElements } from "../../web-component";
+
+export const defaultComponentProps: UiShellNavComponentProps = {
+  sideNavProps: {
+    appName: "",
+    sideNavItems: [],
+  },
+  topNavProps: {},
+} as const;
+
+export type UiShellProps = {
+  /**
+   * Notifies when subscribed to prop changes.
+   *
+   * UI Shell listens to prop updates, and it won't subscribe synchronously. Because of that, this callback notifies when that subscription is ready.
+   */
+  onSubscriptionCreated: () => void;
+  /**
+   * This is a callback that provides a subscriber callback to listen for changes to state.
+   * It allows UI Shell to listen for state changes.
+   *
+   * The props coming in this callback go directly to a React state; therefore, it shares the same signature and provides a previous state.
+   */
+  subscribeToPropChanges: (
+    subscriber: (
+      componentProps: SetStateAction<UiShellNavComponentProps>,
+    ) => void,
+  ) => () => void;
+} & Pick<ReactRootElements, "appRootElement" | "stylesRootElement"> &
+  Pick<UiShellContentProps, "appComponent" | "onError" | "optionalComponents">;
+
+/**
+ * Our new Unified Platform UI Shell.
+ *
+ * This includes the top and side navigation as well as the footer and provides a spot for your app to render into.
+ *
+ * If an error occurs, this will revert to only showing the app.
+ */
+const UiShell = ({
+  appComponent,
+  appRootElement,
+  onError = console.error,
+  onSubscriptionCreated,
+  optionalComponents,
+  stylesRootElement,
+  subscribeToPropChanges,
+}: UiShellProps) => {
+  const [componentProps, setComponentProps] = useState(defaultComponentProps);
+
+  useEffect(() => {
+    const unsubscribe = subscribeToPropChanges((componentProps) => {
+      // If for some reason nothing is passed as `componentProps`, we fallback on `defaultComponentProps` as a safety mechanism to ensure nothing breaks.
+      setComponentProps(componentProps || defaultComponentProps);
+    });
+
+    onSubscriptionCreated();
+
+    return () => {
+      unsubscribe();
+    };
+  }, [onSubscriptionCreated, subscribeToPropChanges]);
+
+  return (
+    <ErrorBoundary fallback={appComponent} onError={onError}>
+      <OdysseyProvider
+        emotionRootElement={stylesRootElement}
+        shadowRootElement={appRootElement}
+      >
+        <ErrorBoundary fallback={appComponent} onError={onError}>
+          <CssBaseline />
+
+          <UiShellContent
+            {...componentProps}
+            appComponent={appComponent}
+            onError={onError}
+            optionalComponents={optionalComponents}
+          />
+        </ErrorBoundary>
+      </OdysseyProvider>
+    </ErrorBoundary>
+  );
+};
+
+const MemoizedUiShell = memo(UiShell);
+MemoizedUiShell.displayName = "UiShell";
+
+export { MemoizedUiShell as UiShell };