@okta/odyssey-react-mui 1.24.1 → 1.26.0

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.Spacing6,
+}));
+
+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);
+  });
+});

package/src/labs/UiShell/bufferLatest.ts

@@ -0,0 +1,64 @@
+/*!
+ * 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 { createStore } from "./createStore";
+
+/**
+ * Buffers the values passed to a publisher, keeping only the latest value, until the subscriber emits.
+ *
+ * This is useful in restricting publishers from firing events until specific subscribers are active. Once active, the `publish` function reverts to its previous behavior.
+ */
+export const bufferLatest = <Value>({
+  publish,
+  subscribe,
+}: {
+  /**
+   * A function that publishes values to a subscriber, but not the same subscriber as the one passed to this function.
+   *
+   * Only the latest value published by this publisher is kept until the subscriber emits.
+   */
+  publish: (value: Value) => void;
+  /**
+   * A subscription that listens for emissions from a separate publisher.
+   *
+   * When that separate publisher emits, the latest value from the passed-in publish function is emitted as are all future values.
+   */
+  subscribe: (subscriber: () => void) => () => void;
+}) => {
+  const store = createStore<{
+    bufferedValue?: Value;
+    isReactAppReadyForProps: boolean;
+  }>({
+    isReactAppReadyForProps: false,
+  });
+
+  const unsubscribe = subscribe(() => {
+    unsubscribe();
+
+    store.setState("isReactAppReadyForProps", true);
+    store.getState("bufferedValue");
+    if (store.hasState("bufferedValue")) {
+      // If we have a state, then the value in here is what we want. TypeScript expects this to possibly be `undefined` because the type we sent to `createStore` listed `bufferedValue` as optional. TypeScript doesn't seem to have any way of knowing we passed in the value at some point.
+      publish(store.getState("bufferedValue")!);
+    }
+  });
+
+  const publishWhenReady: typeof publish = (value) => {
+    if (store.getState("isReactAppReadyForProps")) {
+      publish(value);
+    } else {
+      store.setState("bufferedValue", value);
+    }
+  };
+
+  return publishWhenReady;
+};

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

@@ -0,0 +1,115 @@
+/*!
+ * 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 { createMessageBus } from "./createMessageBus";
+
+describe("createEventBus", () => {
+  test("messages are not sent once unsubscribed", async () => {
+    const { publish, subscribe } = createMessageBus<null>();
+
+    const subscriber = jest.fn();
+
+    const unsubscribe = subscribe(subscriber);
+
+    unsubscribe();
+    publish(null);
+
+    expect(subscriber).toHaveBeenCalledTimes(0);
+  });
+
+  test("messages are not sent once unsubscribed from multiple subscribers", async () => {
+    const { publish, subscribe } = createMessageBus<null>();
+
+    const subscriber1 = jest.fn();
+    const subscriber2 = jest.fn();
+    const subscriber3 = jest.fn();
+
+    const unsubscribe1 = subscribe(subscriber1);
+    const unsubscribe2 = subscribe(subscriber2);
+    const unsubscribe3 = subscribe(subscriber3);
+
+    unsubscribe1();
+    unsubscribe2();
+    unsubscribe3();
+    publish(null);
+    publish(null);
+
+    expect(subscriber1).toHaveBeenCalledTimes(0);
+    expect(subscriber2).toHaveBeenCalledTimes(0);
+    expect(subscriber3).toHaveBeenCalledTimes(0);
+  });
+
+  test("when publishing message, receives message in a subscriber", async () => {
+    const message = Symbol();
+
+    const { publish, subscribe } = createMessageBus<typeof message>();
+
+    const subscriber = jest.fn();
+
+    const unsubscribe = subscribe(subscriber);
+
+    publish(message);
+    unsubscribe();
+
+    expect(subscriber).toHaveBeenCalledWith(message);
+    expect(subscriber).toHaveBeenCalledTimes(1);
+  });
+
+  test("when publishing 2 messages, receives both messages in a subscriber", async () => {
+    const message1 = Symbol();
+    const message2 = Symbol();
+
+    const { publish, subscribe } = createMessageBus<
+      typeof message1 | typeof message2
+    >();
+
+    const subscriber = jest.fn();
+
+    const unsubscribe = subscribe(subscriber);
+
+    publish(message1);
+    publish(message2);
+    unsubscribe();
+
+    expect(subscriber).toHaveBeenNthCalledWith(1, message1);
+    expect(subscriber).toHaveBeenNthCalledWith(2, message2);
+    expect(subscriber).toHaveBeenCalledTimes(2);
+  });
+
+  test("when subscribing twice, both subscribers receive multiple messages", async () => {
+    const message1 = Symbol();
+    const message2 = Symbol();
+
+    const { publish, subscribe } = createMessageBus<
+      typeof message1 | typeof message2
+    >();
+
+    const subscriber1 = jest.fn();
+    const subscriber2 = jest.fn();
+
+    const unsubscribe1 = subscribe(subscriber1);
+    const unsubscribe2 = subscribe(subscriber2);
+
+    publish(message1);
+    publish(message2);
+    unsubscribe1();
+    unsubscribe2();
+
+    expect(subscriber1).toHaveBeenNthCalledWith(1, message1);
+    expect(subscriber1).toHaveBeenNthCalledWith(2, message2);
+    expect(subscriber1).toHaveBeenCalledTimes(2);
+
+    expect(subscriber2).toHaveBeenNthCalledWith(1, message1);
+    expect(subscriber2).toHaveBeenNthCalledWith(2, message2);
+    expect(subscriber2).toHaveBeenCalledTimes(2);
+  });
+});

package/src/labs/UiShell/createMessageBus.ts

@@ -0,0 +1,53 @@
+/*!
+ * 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 type MessageHandler<Message> = (message: Message) => void;
+
+export type PublishMessage<Message> = MessageHandler<Message>;
+
+export type UnsubscribeMessageSubscription = () => void;
+
+export type MessageSubscription<Message> = (
+  subscriber: MessageHandler<Message>,
+) => UnsubscribeMessageSubscription;
+
+export type MessageBus<Message> = {
+  publish: PublishMessage<Message>;
+  subscribe: MessageSubscription<Message>;
+};
+
+/**
+ * Create a self-contained message bus that allows you to subscribe to events published by the publisher.
+ */
+export const createMessageBus = <Message = void>(): MessageBus<Message> => {
+  const subscribers = new Map<symbol, MessageHandler<Message>>();
+
+  const publish: PublishMessage<Message> = (message) => {
+    Array.from(subscribers.values()).forEach((subscriber) => {
+      subscriber(message);
+    });
+  };
+
+  const subscribe: MessageSubscription<Message> = (subscriber) => {
+    const subscriberId = Symbol();
+    subscribers.set(subscriberId, subscriber);
+
+    return () => {
+      subscribers.delete(subscriberId);
+    };
+  };
+
+  return {
+    publish,
+    subscribe,
+  };
+};

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

@@ -0,0 +1,103 @@
+/*!
+ * 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 { createStore } from "./createStore";
+
+describe("createStore", () => {
+  test("starts with no initial state", async () => {
+    const store = createStore<{
+      value: null;
+    }>();
+
+    expect(store.hasState("value")).toBe(false);
+    expect(store.getState("value")).toBe(undefined);
+  });
+
+  test("changes state when set", async () => {
+    const store = createStore<{
+      value: null;
+    }>();
+
+    store.setState("value", null);
+
+    expect(store.hasState("value")).toBe(true);
+    expect(store.getState("value")).toBe(null);
+  });
+
+  test("reads initial state value", async () => {
+    const store = createStore({
+      value: null,
+    });
+
+    expect(store.hasState("value")).toBe(true);
+    expect(store.getState("value")).toBe(null);
+  });
+
+  test("changes initial state when set", async () => {
+    const store = createStore<{
+      value: boolean;
+    }>({
+      value: false,
+    });
+
+    store.setState("value", true);
+
+    expect(store.hasState("value")).toBe(true);
+    expect(store.getState("value")).toBe(true);
+  });
+
+  test("changes initial state when set", async () => {
+    const store = createStore<{
+      value: boolean;
+    }>({
+      value: false,
+    });
+
+    store.setState("value", true);
+
+    expect(store.hasState("value")).toBe(true);
+    expect(store.getState("value")).toBe(true);
+  });
+
+  test("allows for multiple different states", async () => {
+    const store = createStore<{
+      value1: boolean;
+      value2: number;
+    }>({
+      value1: false,
+      value2: 0,
+    });
+
+    expect(store.hasState("value1")).toBe(true);
+    expect(store.hasState("value2")).toBe(true);
+    expect(store.getState("value1")).toBe(false);
+    expect(store.getState("value2")).toBe(0);
+  });
+
+  test("allows setting multiple states", async () => {
+    const store = createStore<{
+      value1: boolean;
+      value2: number;
+    }>({
+      value1: false,
+      value2: 0,
+    });
+
+    store.setState("value1", true);
+    store.setState("value2", 1);
+
+    expect(store.hasState("value1")).toBe(true);
+    expect(store.hasState("value2")).toBe(true);
+    expect(store.getState("value1")).toBe(true);
+    expect(store.getState("value2")).toBe(1);
+  });
+});

package/src/labs/UiShell/createStore.ts

@@ -0,0 +1,37 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Creates an internal state and gives access to those values via functions.
+ *
+ * It can be optionally given an initial state.
+ */
+export const createStore = <State extends object>(initialState?: State) => {
+  const state = initialState || ({} as Partial<State>);
+
+  const hasState = <Name extends keyof State>(name: Name) => name in state;
+
+  const getState = <Name extends keyof State>(name: Name) => state[name];
+
+  const setState = <Name extends keyof State>(
+    name: Name,
+    value: Required<State>[Name],
+  ) => {
+    state[name] = value;
+  };
+
+  return {
+    getState,
+    hasState,
+    setState,
+  };
+};

package/src/labs/UiShell/index.ts

@@ -0,0 +1,17 @@
+/*!
+ * 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 "./renderUiShell";
+export * from "./useHasUiShell";
+
+export { UiShell, type UiShellProps } from "./UiShell";
+export { type UiShellNavComponentProps } from "./UiShellContent";