@okta/odyssey-react-mui 1.25.0 → 1.27.0

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 };

package/src/labs/UiShell/UiShellContent.tsx

@@ -0,0 +1,170 @@
+/*!
+ * 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, type ReactNode } from "react";
+import { ErrorBoundary, ErrorBoundaryProps } from "react-error-boundary";
+
+import { SideNav, type SideNavProps } from "../SideNav";
+import { TopNav, type TopNavProps } from "../TopNav";
+import {
+  useOdysseyDesignTokens,
+  type DesignTokens,
+} from "../../OdysseyDesignTokensContext";
+import { useScrollState } from "./useScrollState";
+
+const StyledAppContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})<{
+  odysseyDesignTokens: DesignTokens;
+}>(({ odysseyDesignTokens }) => ({
+  gridArea: "app-content",
+  overflowX: "hidden",
+  overflowY: "auto",
+  paddingBlock: odysseyDesignTokens.Spacing5,
+  paddingInline: odysseyDesignTokens.Spacing8,
+}));
+
+const StyledBannersContainer = styled("div")(() => ({
+  gridArea: "banners",
+}));
+
+const StyledSideNavContainer = styled("div")(() => ({
+  gridArea: "side-nav",
+}));
+
+const StyledShellContainer = styled("div", {
+  shouldForwardProp: (prop) => prop !== "odysseyDesignTokens",
+})<{
+  odysseyDesignTokens: DesignTokens;
+}>(({ odysseyDesignTokens }) => ({
+  backgroundColor: odysseyDesignTokens.HueNeutral50,
+  display: "grid",
+  gridGap: 0,
+  gridTemplateAreas: `
+    "banners banners"
+    "side-nav top-nav"
+    "side-nav app-content"
+  `,
+  gridTemplateColumns: "auto 1fr",
+  gridTemplateRows: "auto auto 1fr",
+  height: "100vh",
+  width: "100vw",
+}));
+
+const StyledTopNavContainer = styled("div")(() => ({
+  gridArea: "top-nav",
+}));
+
+export type UiShellNavComponentProps = {
+  /**
+   * Object that gets pass directly to the side nav component.
+   */
+  sideNavProps?: Omit<SideNavProps, "footerComponent">;
+  /**
+   * Object that gets pass directly to the top nav component.
+   */
+  topNavProps: Omit<TopNavProps, "leftSideComponent" | "rightSideComponent">;
+};
+
+export type UiShellContentProps = {
+  /**
+   * React app component that renders as children in the correct location of the shell.
+   */
+  appComponent: ReactNode;
+  /**
+   * Notifies when a React rendering error occurs. This could be useful for logging, flagging "p0"s, and recovering UI Shell when errors occur.
+   */
+  onError?: ErrorBoundaryProps["onError"];
+  /**
+   * Components that will render as children of various other components such as the top nav or side nav.
+   */
+  optionalComponents?: {
+    banners?: ReactElement;
+    sideNavFooter?: SideNavProps["footerComponent"];
+    topNavLeftSide?: TopNavProps["leftSideComponent"];
+    topNavRightSide?: TopNavProps["rightSideComponent"];
+  };
+} & UiShellNavComponentProps;
+
+/**
+ * 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 UiShellContent = ({
+  appComponent,
+  onError = console.error,
+  optionalComponents,
+  sideNavProps,
+  topNavProps,
+}: UiShellContentProps) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+  const { isContentScrolled, scrollableContentRef } = useScrollState();
+
+  return (
+    <StyledShellContainer odysseyDesignTokens={odysseyDesignTokens}>
+      <StyledBannersContainer>
+        {optionalComponents?.banners}
+      </StyledBannersContainer>
+
+      <StyledSideNavContainer>
+        {sideNavProps && (
+          <ErrorBoundary fallback={null} onError={onError}>
+            <SideNav
+              {...{
+                ...sideNavProps,
+                ...(sideNavProps.hasCustomFooter &&
+                optionalComponents?.sideNavFooter
+                  ? {
+                      footerComponent: optionalComponents.sideNavFooter,
+                      footerItems: undefined,
+                      hasCustomFooter: sideNavProps.hasCustomFooter,
+                    }
+                  : {
+                      footerItems: sideNavProps.footerItems,
+                      hasCustomFooter: false,
+                    }),
+              }}
+            />
+          </ErrorBoundary>
+        )}
+      </StyledSideNavContainer>
+
+      <StyledTopNavContainer>
+        <ErrorBoundary fallback={null} onError={onError}>
+          <TopNav
+            {...topNavProps}
+            isScrolled={isContentScrolled}
+            leftSideComponent={optionalComponents?.topNavLeftSide}
+            rightSideComponent={optionalComponents?.topNavRightSide}
+          />
+        </ErrorBoundary>
+      </StyledTopNavContainer>
+
+      <StyledAppContainer
+        odysseyDesignTokens={odysseyDesignTokens}
+        tabIndex={0}
+        ref={scrollableContentRef}
+      >
+        {appComponent}
+      </StyledAppContainer>
+    </StyledShellContainer>
+  );
+};
+
+const MemoizedUiShellContent = memo(UiShellContent);
+MemoizedUiShellContent.displayName = "UiShellContent";
+
+export { MemoizedUiShellContent as UiShellContent };

package/src/labs/UiShell/bufferLatest.test.ts

@@ -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 { bufferLatest } from "./bufferLatest";
+import { createMessageBus } from "./createMessageBus";
+
+describe("bufferLatest", () => {
+  test("calls subscriber after ready", async () => {
+    const { publish: publish1, subscribe: subscribe1 } = createMessageBus();
+
+    const { publish: publish2, subscribe: subscribe2 } = createMessageBus();
+
+    const subscriber = jest.fn();
+
+    subscribe1(subscriber);
+
+    const bufferedPublish1 = bufferLatest({
+      publish: publish1,
+      subscribe: subscribe2,
+    });
+
+    publish2();
+    bufferedPublish1();
+
+    expect(subscriber).toHaveBeenCalledTimes(1);
+  });
+
+  test("calls subscriber before ready", async () => {
+    const { publish: publish1, subscribe: subscribe1 } = createMessageBus();
+
+    const { publish: publish2, subscribe: subscribe2 } = createMessageBus();
+
+    const subscriber = jest.fn();
+
+    subscribe1(subscriber);
+
+    const bufferedPublish1 = bufferLatest({
+      publish: publish1,
+      subscribe: subscribe2,
+    });
+
+    bufferedPublish1();
+    publish2();
+
+    expect(subscriber).toHaveBeenCalledTimes(1);
+  });
+
+  test("keeps only the last value passed when ready", async () => {
+    const { publish: publish1, subscribe: subscribe1 } =
+      createMessageBus<string>();
+
+    const { publish: publish2, subscribe: subscribe2 } = createMessageBus();
+
+    const subscriber = jest.fn();
+
+    subscribe1(subscriber);
+
+    const bufferedPublish1 = bufferLatest({
+      publish: publish1,
+      subscribe: subscribe2,
+    });
+
+    bufferedPublish1("a");
+    bufferedPublish1("b");
+    publish2();
+
+    expect(subscriber).toHaveBeenCalledWith("b");
+    expect(subscriber).toHaveBeenCalledTimes(1);
+  });
+});