@okta/odyssey-react-mui 1.24.1 → 1.26.0

package/src/labs/OdysseyPickers/PickerVirtualizationListBox.tsx

@@ -0,0 +1,191 @@
+/*!
+ * Copyright (c) 2023-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 {
+  Children,
+  createContext,
+  forwardRef,
+  memo,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { VariableSizeList, ListChildComponentProps } from "react-window";
+import styled from "@emotion/styled";
+import { AutocompleteProps } from "@mui/material";
+
+type SetItemSize = (size: number) => void;
+
+const ListboxContainer = styled.div({
+  width: "100%",
+  height: "100%",
+});
+
+const Row = ({
+  data,
+  index,
+  setItemSize,
+  style,
+}: ListChildComponentProps & { setItemSize: SetItemSize }) => {
+  const rowRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (rowRef.current) {
+      /**
+       * Checking for child height to workaround a bug where the clientHeight of the row isn't updated correctly
+       * @see here if you need to know more: https://github.com/bvaughn/react-window/issues/582#issuecomment-1883074908
+       */
+      const firstChild = rowRef.current.firstElementChild;
+      const height = firstChild
+        ? firstChild.clientHeight
+        : rowRef.current.clientHeight;
+
+      setItemSize(height);
+    }
+  }, [index, rowRef, setItemSize]);
+
+  const baseOption = data[index];
+  const { key, props } = baseOption;
+
+  /**
+   * react-window calculates the absolute positions of the list items, via an inline style, so
+   * we need to add it to each list item that is being rendered in the viewable list window.
+   * @see here if you need to know more: https://github.com/bvaughn/react-window?tab=readme-ov-file#why-is-my-list-blank-when-i-scroll
+   */
+  const styles = useMemo(
+    () => ({
+      ...style,
+      height: "auto",
+    }),
+    [style],
+  );
+
+  return (
+    <div ref={rowRef}>
+      <li {...props} key={key} style={styles} />
+    </div>
+  );
+};
+
+const OuterListboxContext = createContext({});
+
+const OuterListboxElementType = forwardRef<HTMLDivElement>((props, ref) => {
+  const outerProps = useContext(OuterListboxContext);
+  return <div ref={ref} {...props} {...outerProps} />;
+});
+
+const useResetCache = (length: number) => {
+  const resetCacheRef = useRef<VariableSizeList>(null);
+  useEffect(() => {
+    if (resetCacheRef.current) {
+      resetCacheRef.current.resetAfterIndex(0, true);
+    }
+  }, [length]);
+  return resetCacheRef;
+};
+
+const PickerVirtualizationListBox = forwardRef<
+  HTMLDivElement,
+  AutocompleteProps<undefined, undefined, undefined, undefined>["ListboxProps"]
+>((props = {}, ref) => {
+  const [listHeight, setListHeight] = useState(0);
+
+  const { children, ...other } = props;
+
+  const itemData = Children.toArray(children).flatMap<typeof children>(
+    (child) =>
+      typeof child === "number" || typeof child === "string"
+        ? [child]
+        : [child].concat("children" in child ? Children.toArray(children) : []),
+  );
+
+  const sizeMapRef = useRef<number[]>([]);
+
+  const getListBoxHeight = useCallback(() => {
+    // 8px of padding top/bottom applied by MUI
+    const COMBINED_LISTBOX_PADDING = 16;
+
+    if (itemData.length > OVERSCAN_ROW_COUNT) {
+      // has a max-height of 40vh set in CSS. This is only set because height needs to be a number
+      return 9999;
+    } else {
+      const itemsHeightCalculated = sizeMapRef.current
+        .slice(0, itemData.length - 1)
+        .map((_, index) => sizeMapRef.current[index] || 0)
+        .reduce(
+          (prevItemHeight, nextItemHeight) => prevItemHeight + nextItemHeight,
+          0,
+        );
+      return COMBINED_LISTBOX_PADDING + itemsHeightCalculated;
+    }
+  }, [itemData, sizeMapRef]);
+
+  useEffect(() => {
+    if (sizeMapRef.current.length && itemData.length) {
+      setListHeight(getListBoxHeight());
+    }
+  }, [getListBoxHeight, itemData, sizeMapRef]);
+
+  // The number of items (rows or columns) to render outside of the visible area for performance and scrolling reasons
+  const OVERSCAN_ROW_COUNT = 8;
+
+  const gridRef = useResetCache(itemData.length);
+
+  const setItemSize = useCallback<SetItemSize>(
+    (size) => {
+      gridRef?.current?.resetAfterIndex(0, true);
+      sizeMapRef.current = sizeMapRef.current.concat(size);
+    },
+    [gridRef, sizeMapRef],
+  );
+  const getItemSize = useCallback(
+    // using 45px as a sane default here to avoid a lot of content shift on repaint
+    (index: number) => sizeMapRef.current[index] || 45,
+    [sizeMapRef],
+  );
+
+  return (
+    <ListboxContainer ref={ref}>
+      <OuterListboxContext.Provider value={other}>
+        <VariableSizeList
+          innerElementType="ul"
+          itemData={itemData}
+          itemCount={itemData.length}
+          itemSize={getItemSize}
+          height={listHeight}
+          width="100%"
+          ref={gridRef}
+          outerElementType={OuterListboxElementType}
+          overscanCount={OVERSCAN_ROW_COUNT}
+        >
+          {({ data, index, style }) => (
+            <Row
+              data={data}
+              index={index}
+              style={style}
+              setItemSize={setItemSize}
+            />
+          )}
+        </VariableSizeList>
+      </OuterListboxContext.Provider>
+    </ListboxContainer>
+  );
+});
+
+const MemoizedPickerVirtualizationListBox = memo(PickerVirtualizationListBox);
+
+MemoizedPickerVirtualizationListBox.displayName = "PickerVirtualizationListBox";
+
+export { MemoizedPickerVirtualizationListBox as PickerVirtualizationListBox };

package/src/labs/OdysseyPickers/PickerWithOptionAdornment.tsx

@@ -0,0 +1,429 @@
+/*!
+ * Copyright (c) 2023-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 {
+  HTMLAttributes,
+  memo,
+  ReactElement,
+  ReactNode,
+  useCallback,
+} from "react";
+import styled from "@emotion/styled";
+
+import { Box } from "../../Box";
+import {
+  ComposablePicker,
+  ComposablePickerProps,
+  type AdornmentSize,
+  type BasePickerProps,
+  type BasePickerType,
+} from "./ComposablePicker";
+import {
+  useOdysseyDesignTokens,
+  DesignTokens,
+} from "../../OdysseyDesignTokensContext";
+import {
+  type BaseOptionProps,
+  type LabelDescription,
+  type Metadata,
+  Option,
+  OptionDescriptionComponent,
+  OptionLabelContainer,
+  OptionMetadataComponent,
+  OptionProps,
+} from "./Picker";
+import { Heading6 } from "../../Typography";
+import { Tag } from "../../Tag";
+
+type Adornment = ReactNode | string;
+
+type AdornmentLabelDescription = LabelDescription & {
+  adornment: Adornment;
+};
+
+type AdornmentLabelDescriptionMetadata = AdornmentLabelDescription & Metadata;
+
+export type AdornmentOptionType =
+  | AdornmentLabelDescription
+  | AdornmentLabelDescriptionMetadata;
+
+const OptionAdornmentContainer = styled("div", {
+  shouldForwardProp: (prop) =>
+    prop !== "odysseyDesignTokens" &&
+    prop !== "adornmentSize" &&
+    prop !== "isTagContainer",
+})<{
+  adornmentSize?: AdornmentSize;
+  isTagContainer?: boolean;
+  odysseyDesignTokens: DesignTokens;
+}>(
+  ({
+    adornmentSize = "small",
+    isTagContainer = false,
+    odysseyDesignTokens,
+  }) => ({
+    position: "relative",
+    // push icon up by one px for better visual alignment
+    bottom: "1px",
+    alignSelf: "flex-start",
+    width: odysseyDesignTokens.Spacing5,
+    height: odysseyDesignTokens.Spacing5,
+    overflow: "hidden",
+    marginInlineEnd: odysseyDesignTokens.Spacing3,
+
+    svg: {
+      width: "100%",
+      height: "auto",
+    },
+
+    img: {
+      position: "absolute",
+      top: "50%",
+      left: "50%",
+      width: "100%",
+      transform: "translate(-50%, -50%)",
+    },
+
+    ...(adornmentSize === "large" &&
+      !isTagContainer && {
+        bottom: 0,
+        width: odysseyDesignTokens.Spacing8,
+        height: odysseyDesignTokens.Spacing8,
+      }),
+
+    ...(isTagContainer && {
+      bottom: 0,
+      alignSelf: "center",
+      width: odysseyDesignTokens.Spacing4,
+      height: "auto",
+      maxHeight: odysseyDesignTokens.Spacing4,
+      marginInlineEnd: odysseyDesignTokens.Spacing2,
+
+      svg: {
+        display: "flex",
+        width: "100%",
+        height: "auto",
+      },
+    }),
+  }),
+);
+
+type OptionAdornmentProps = {
+  adornment: Adornment;
+  adornmentSize: AdornmentSize;
+  odysseyDesignTokens: DesignTokens;
+};
+
+const OptionAdornment = ({
+  adornment,
+  adornmentSize,
+  odysseyDesignTokens,
+}: OptionAdornmentProps) => {
+  const isImageAdornment = typeof adornment === "string";
+
+  if (isImageAdornment) {
+    return (
+      <OptionAdornmentContainer
+        adornmentSize={adornmentSize}
+        odysseyDesignTokens={odysseyDesignTokens}
+      >
+        {/* NOTE: Intentionally leaving alt as an empty string here so screen readers will ignore this image */}
+        {/* Image should be suffciently described by the adjacent title and/or description of the option */}
+        <img src={adornment} alt="" role="presentation" />
+      </OptionAdornmentContainer>
+    );
+  } else {
+    return (
+      <OptionAdornmentContainer
+        adornmentSize={adornmentSize}
+        odysseyDesignTokens={odysseyDesignTokens}
+      >
+        {adornment}
+      </OptionAdornmentContainer>
+    );
+  }
+};
+
+const OptionWithLabelDescriptionOnly = <
+  OptionType extends AdornmentLabelDescription,
+>({
+  adornmentSize,
+  muiProps,
+  odysseyDesignTokens,
+  option,
+}: BaseOptionProps &
+  OptionProps<OptionType> & { adornmentSize: AdornmentSize }) => {
+  const { adornment, description, label, value } = option;
+  return (
+    <Option hasAdornment key={value} muiProps={muiProps}>
+      <OptionAdornment
+        adornment={adornment}
+        adornmentSize={adornmentSize}
+        odysseyDesignTokens={odysseyDesignTokens}
+      />
+      <OptionLabelContainer odysseyDesignTokens={odysseyDesignTokens}>
+        <Heading6 component="p">{label}</Heading6>
+        <OptionDescriptionComponent
+          description={description}
+          odysseyDesignTokens={odysseyDesignTokens}
+        />
+      </OptionLabelContainer>
+    </Option>
+  );
+};
+
+const OptionWithLabelDescriptionMetadata = <
+  OptionType extends AdornmentLabelDescriptionMetadata,
+>({
+  adornmentSize,
+  muiProps,
+  odysseyDesignTokens,
+  option,
+}: BaseOptionProps &
+  OptionProps<OptionType> & {
+    adornmentSize: AdornmentSize;
+  }) => {
+  const { adornment, description, label, metaData, value } = option;
+
+  return (
+    <Option hasAdornment key={value} muiProps={muiProps}>
+      <OptionAdornment
+        adornment={adornment}
+        adornmentSize={adornmentSize}
+        odysseyDesignTokens={odysseyDesignTokens}
+      />
+      <div>
+        <OptionLabelContainer odysseyDesignTokens={odysseyDesignTokens}>
+          <Heading6 component="p">{label}</Heading6>
+          <OptionDescriptionComponent
+            description={description}
+            odysseyDesignTokens={odysseyDesignTokens}
+          />
+        </OptionLabelContainer>
+        <OptionMetadataComponent
+          metaData={metaData}
+          odysseyDesignTokens={odysseyDesignTokens}
+        />
+      </div>
+    </Option>
+  );
+};
+
+type TagAdornmentProps = {
+  adornment: Adornment;
+};
+
+const TagAdornment = ({ adornment }: TagAdornmentProps) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+  const isImageAdornment = typeof adornment === "string";
+
+  if (isImageAdornment) {
+    return (
+      <OptionAdornmentContainer
+        isTagContainer
+        odysseyDesignTokens={odysseyDesignTokens}
+      >
+        <img src={adornment} alt="" role="presentation" />
+      </OptionAdornmentContainer>
+    );
+  }
+
+  return (
+    <OptionAdornmentContainer
+      isTagContainer
+      odysseyDesignTokens={odysseyDesignTokens}
+    >
+      {adornment}
+    </OptionAdornmentContainer>
+  );
+};
+
+export type PickerWithOptionAdornmentProps<
+  OptionType extends AdornmentOptionType,
+  HasMultipleChoices extends boolean | undefined,
+  IsCustomValueAllowed extends boolean | undefined,
+> = BasePickerProps<OptionType, HasMultipleChoices, IsCustomValueAllowed> & {
+  adornmentSize?: AdornmentSize;
+};
+
+type PickerWithOptionAdornmentComponentType = {
+  <
+    OptionType extends AdornmentLabelDescription,
+    HasMultipleChoices extends boolean | undefined,
+    IsCustomValueAllowed extends boolean | undefined,
+  >(
+    props: PickerWithOptionAdornmentProps<
+      OptionType,
+      HasMultipleChoices,
+      IsCustomValueAllowed
+    >,
+  ): ReactElement;
+  <
+    OptionType extends AdornmentLabelDescriptionMetadata,
+    HasMultipleChoices extends boolean | undefined,
+    IsCustomValueAllowed extends boolean | undefined,
+  >(
+    props: PickerWithOptionAdornmentProps<
+      OptionType,
+      HasMultipleChoices,
+      IsCustomValueAllowed
+    >,
+  ): ReactElement;
+};
+
+const PickerWithOptionAdornment: PickerWithOptionAdornmentComponentType = <
+  OptionType extends AdornmentOptionType,
+  HasMultipleChoices extends boolean | undefined,
+  IsCustomValueAllowed extends boolean | undefined,
+>({
+  adornmentSize = "small",
+  ariaDescribedBy,
+  defaultValue,
+  errorMessage,
+  errorMessageList,
+  getIsOptionEqualToValue,
+  groupOptionsBy,
+  hasMultipleChoices,
+  id: idOverride,
+  inputValue,
+  isCustomValueAllowed,
+  isDisabled,
+  isFullWidth = false,
+  isLoading,
+  isOptional = false,
+  isReadOnly,
+  isVirtualized: isVirtualizedProp = false,
+  hint,
+  HintLinkComponent,
+  label,
+  name: nameOverride,
+  onBlur,
+  onChange: onChangeProp,
+  onInputChange: onInputChangeProp,
+  onFocus,
+  options,
+  value,
+  testId,
+  translate,
+}: PickerWithOptionAdornmentProps<
+  OptionType,
+  HasMultipleChoices,
+  IsCustomValueAllowed
+>) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+
+  const customTagRender = useCallback<
+    NonNullable<
+      ComposablePickerProps<
+        OptionType,
+        HasMultipleChoices,
+        IsCustomValueAllowed
+      >["renderTags"]
+    >
+  >(
+    (values, getTagProps) =>
+      values.map((value, index) => {
+        const { key, onDelete } = getTagProps({ index });
+        const { adornment, label } = value;
+
+        return (
+          <Box
+            key={key}
+            sx={{
+              margin: odysseyDesignTokens.Spacing1,
+              marginInlineEnd: 0,
+            }}
+          >
+            <Tag
+              icon={<TagAdornment adornment={adornment} />}
+              label={label}
+              onRemove={onDelete}
+            />
+          </Box>
+        );
+      }),
+    [odysseyDesignTokens],
+  );
+
+  const customOptionRender = useCallback<
+    (props: HTMLAttributes<HTMLLIElement>, option: OptionType) => ReactNode
+  >(
+    (muiProps, option) => {
+      const hasMetadata = "metaData" in option && option.metaData;
+
+      if (hasMetadata) {
+        return (
+          <OptionWithLabelDescriptionMetadata
+            adornmentSize={adornmentSize}
+            muiProps={muiProps}
+            odysseyDesignTokens={odysseyDesignTokens}
+            option={option}
+          />
+        );
+      }
+
+      return (
+        <OptionWithLabelDescriptionOnly
+          adornmentSize={adornmentSize}
+          muiProps={muiProps}
+          odysseyDesignTokens={odysseyDesignTokens}
+          option={option}
+        />
+      );
+    },
+    [adornmentSize, odysseyDesignTokens],
+  );
+
+  return (
+    <ComposablePicker<OptionType, HasMultipleChoices, IsCustomValueAllowed>
+      ariaDescribedBy={ariaDescribedBy}
+      defaultValue={defaultValue}
+      errorMessage={errorMessage}
+      errorMessageList={errorMessageList}
+      getIsOptionEqualToValue={getIsOptionEqualToValue}
+      groupOptionsBy={groupOptionsBy}
+      hasMultipleChoices={hasMultipleChoices}
+      id={idOverride}
+      inputValue={inputValue}
+      isCustomValueAllowed={isCustomValueAllowed}
+      isDisabled={isDisabled}
+      isFullWidth={isFullWidth}
+      isLoading={isLoading}
+      isOptional={isOptional}
+      isReadOnly={isReadOnly}
+      isVirtualized={isVirtualizedProp}
+      hint={hint}
+      HintLinkComponent={HintLinkComponent}
+      label={label}
+      name={nameOverride}
+      onBlur={onBlur}
+      onChange={onChangeProp}
+      onInputChange={onInputChangeProp}
+      onFocus={onFocus}
+      options={options}
+      renderOption={customOptionRender}
+      renderTags={customTagRender}
+      value={value}
+      testId={testId}
+      translate={translate}
+    />
+  );
+};
+
+// Need the `as BasePickerType` because generics don't get passed through
+const MemoizedPickerWithOptionAdornment = memo(
+  PickerWithOptionAdornment,
+) as BasePickerType;
+
+MemoizedPickerWithOptionAdornment.displayName = "PickerWithOptionAdornment";
+
+export { MemoizedPickerWithOptionAdornment as PickerWithOptionAdornment };

package/src/labs/OdysseyPickers/index.ts

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) 2023-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 { adornmentSizeValues } from "./ComposablePicker";
+export * from "./Picker";
+export * from "./PickerWithOptionAdornment";

package/src/labs/PageTemplate.tsx

@@ -20,6 +20,7 @@ import {
 import { DocumentationIcon } from "../icons.generated";
 import { Heading4, Subordinate } from "../Typography";
 import { Link } from "../Link";
+import { useHasUiShell } from "./UiShell";
 
 export type PageTemplateProps = {
   /**
@@ -72,16 +73,20 @@ type TemplateContentProps = {
 
 const TemplateContainer = styled("div", {
   shouldForwardProp: (prop) =>
-    prop !== "odysseyDesignTokens" && prop !== "isFullWidth",
+    prop !== "odysseyDesignTokens" &&
+    prop !== "hasUiShell" &&
+    prop !== "isFullWidth",
 })<{
-  odysseyDesignTokens: DesignTokens;
+  hasUiShell: boolean;
   isFullWidth: boolean;
-}>(({ odysseyDesignTokens, isFullWidth }) => ({
+  odysseyDesignTokens: DesignTokens;
+}>(({ hasUiShell, isFullWidth, odysseyDesignTokens }) => ({
   maxWidth: isFullWidth
     ? "100%"
     : `calc(1440px + ${odysseyDesignTokens.Spacing6} + ${odysseyDesignTokens.Spacing6})`,
-  marginInline: isFullWidth ? odysseyDesignTokens.Spacing6 : "auto",
-  padding: odysseyDesignTokens.Spacing6,
+  marginInline:
+    isFullWidth && !hasUiShell ? odysseyDesignTokens.Spacing6 : "auto",
+  padding: hasUiShell ? 0 : odysseyDesignTokens.Spacing6,
 }));
 
 const TemplateHeader = styled("div")(() => ({
@@ -163,24 +168,27 @@ const TemplateContent = styled("div", {
 );
 
 const PageTemplate = ({
-  title,
+  children,
   description,
   documentationLink,
   documentationText,
+  drawer,
+  isFullWidth = false,
   primaryCallToActionComponent,
   secondaryCallToActionComponent,
   tertiaryCallToActionComponent,
-  children,
-  drawer,
-  isFullWidth = false,
+  title,
 }: PageTemplateProps) => {
   const odysseyDesignTokens = useOdysseyDesignTokens();
   const { isOpen: isDrawerOpen, variant: drawerVariant } = drawer?.props ?? {};
 
+  const hasUiShell = useHasUiShell();
+
   return (
     <TemplateContainer
-      odysseyDesignTokens={odysseyDesignTokens}
+      hasUiShell={hasUiShell}
       isFullWidth={isFullWidth}
+      odysseyDesignTokens={odysseyDesignTokens}
     >
       <TemplateHeader>
         <TemplateHeaderPrimaryContent>