@okta/odyssey-react-mui 0.23.0 → 1.0.0

package/src/Fieldset.tsx

@@ -0,0 +1,106 @@
+/*!
+ * Copyright (c) 2022-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 { Box } from "@mui/material";
+import { memo, ReactElement, useMemo } from "react";
+
+import { Callout } from "./Callout";
+import { FieldsetContext } from "./FieldsetContext";
+import { Legend, Subordinate } from "./Typography";
+import { useOdysseyDesignTokens } from "./OdysseyDesignTokensContext";
+import { useUniqueId } from "./useUniqueId";
+
+export type FieldsetProps = {
+  /**
+   * A Callout indicating a Fieldset-wide error or status update.
+   */
+  alert?: ReactElement<typeof Callout>;
+  /**
+   * The Field components within the Fieldset
+   */
+  children: ReactElement | Array<ReactElement>;
+  /**
+   * A supplementary description
+   */
+  description?: string;
+  /**
+   * Defines a unique identifier (ID) which must be unique in the whole document.
+   */
+  id?: string;
+  /**
+   * Disables the component and any wrapped input fields.
+   */
+  isDisabled?: boolean;
+  /**
+   * The title of the Fieldset
+   */
+  legend: string;
+  /**
+   * The name associated with the group.
+   */
+  name?: string;
+};
+
+const Fieldset = ({
+  alert,
+  children,
+  description,
+  id: idOverride,
+  isDisabled = false,
+  legend,
+  name,
+}: FieldsetProps) => {
+  const odysseyDesignTokens = useOdysseyDesignTokens();
+  const id = useUniqueId(idOverride);
+
+  const fieldsetContextValue = useMemo(
+    () => ({
+      isDisabled,
+    }),
+    [isDisabled]
+  );
+
+  return (
+    <Box
+      component="fieldset"
+      disabled={isDisabled}
+      name={name}
+      id={id}
+      sx={{
+        border: "0",
+        margin: odysseyDesignTokens.Spacing0,
+        marginBlockEnd: odysseyDesignTokens.Spacing6,
+        maxWidth: odysseyDesignTokens.TypographyLineLengthMax,
+        padding: odysseyDesignTokens.Spacing0,
+
+        "&:last-child": {
+          marginBlockEnd: odysseyDesignTokens.Spacing0,
+        },
+      }}
+    >
+      <Legend>{legend}</Legend>
+
+      {description && <Subordinate component="p">{description}</Subordinate>}
+
+      {alert}
+
+      <FieldsetContext.Provider value={fieldsetContextValue}>
+        {children}
+      </FieldsetContext.Provider>
+    </Box>
+  );
+};
+
+const MemoizedFieldset = memo(Fieldset);
+MemoizedFieldset.displayName = "Fieldset";
+
+export { MemoizedFieldset as Fieldset };

package/src/FieldsetContext.tsx

@@ -0,0 +1,23 @@
+/*!
+ * 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 { createContext, useContext } from "react";
+
+export type FieldsetContextValue = {
+  isDisabled: boolean;
+};
+
+export const FieldsetContext = createContext<FieldsetContextValue>({
+  isDisabled: false,
+});
+
+export const useFieldset = () => useContext(FieldsetContext);

package/src/Form.tsx

@@ -0,0 +1,152 @@
+/*!
+ * Copyright (c) 2022-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, ReactElement } from "react";
+
+import { Box } from "@mui/material";
+import { Button } from "./Button";
+import { Callout } from "./Callout";
+import { Heading4, Support } from "./Typography";
+import { useUniqueId } from "./useUniqueId";
+
+export const formEncodingTypeValues = [
+  "application/x-www-form-urlencoded",
+  "application/json",
+  "multipart/form-data",
+  "text/plain",
+] as const;
+export const formAutoCompleteTypeValues = ["on", "off"] as const;
+export const formMethodValues = ["post", "get", "dialog"] as const;
+
+export type FormProps = {
+  /**
+   * A Callout indicating a Form-wide error or status update.
+   */
+  alert?: ReactElement<typeof Callout>;
+  /**
+   * Indicates whether input elements can by default have their values automatically completed by the browser.
+   * `autocomplete` attributes on form elements override it on <form>
+   */
+  autoCompleteType?: (typeof formAutoCompleteTypeValues)[number];
+  /**
+   * The Field or FieldSet components within the Form
+   */
+  children: ReactElement | Array<ReactElement>;
+  /**
+   * A supplementary description
+   */
+  description?: string;
+  /**
+   * If the value of the method attribute is post, enctype is the MIME type of the form submission.
+   * This value can be overridden by formenctype attributes on <button>, <input type="submit">, or <input type="image"> elements.
+   */
+  encodingType?: (typeof formEncodingTypeValues)[number];
+  /**
+   * The Field or FieldGroup components within the Form
+   */
+  formActions?:
+    | ReactElement<typeof Button>
+    | Array<ReactElement<typeof Button>>;
+  /**
+   * Defines a unique identifier (ID) which must be unique in the whole document.
+   */
+  id?: string;
+  /**
+   * The HTTP method to submit the form with.
+   * This value is overridden by formmethod attributes on <button>, <input type="submit">, or <input type="image"> elements.
+   */
+  method?: (typeof formMethodValues)[number];
+  /**
+   * The name of the form. The value must not be the empty string, and must be unique among the form elements in the forms collection that it is in, if any.
+   */
+  name: string;
+  /**
+   * This Boolean attribute indicates that the form shouldn't be validated when submitted.
+   * If this attribute is not set (and therefore the form is validated),
+   * it can be overridden by a formnovalidate attribute on a <button>, <input type="submit">, or <input type="image"> element belonging to the form.
+   */
+  noValidate?: boolean;
+  /**
+   * Indicates where to display the response after submitting the form. It is a name/keyword for a browsing context (for example, tab, window, or iframe).
+   * This value can be overridden by a formtarget attribute on a <button>, <input type="submit">, or <input type="image"> element.
+   */
+  target?: string;
+  /**
+   * The title of the Form
+   */
+  title?: string;
+};
+
+const Form = ({
+  alert,
+  autoCompleteType,
+  children,
+  description,
+  encodingType,
+  formActions,
+  id: idOverride,
+  method,
+  name,
+  noValidate = false,
+  target,
+  title,
+}: FormProps) => {
+  const id = useUniqueId(idOverride);
+
+  return (
+    <Box
+      component="form"
+      autoComplete={autoCompleteType}
+      name={name}
+      encType={encodingType}
+      method={method}
+      noValidate={noValidate}
+      target={target}
+      id={id}
+      sx={{
+        maxWidth: (theme) => theme.mixins.maxWidth,
+        margin: (theme) => theme.spacing(0),
+        padding: (theme) => theme.spacing(0),
+      }}
+    >
+      <Box
+        component="div"
+        sx={{
+          marginBlockEnd: (theme) => theme.spacing(4),
+        }}
+      >
+        {title && <Heading4 component="h1">{title}</Heading4>}
+        {description && <Support>{description}</Support>}
+        {alert}
+      </Box>
+      <Box component="div">{children}</Box>
+      {formActions && (
+        <Box
+          component="div"
+          sx={{
+            display: "flex",
+            justifyContent: "flex-start",
+            gap: (theme) => theme.spacing(1),
+            marginBlockStart: (theme) => theme.spacing(7),
+          }}
+        >
+          {formActions}
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+const MemoizedForm = memo(Form);
+MemoizedForm.displayName = "Form";
+
+export { MemoizedForm as Form };

package/src/Link.tsx

@@ -10,41 +10,61 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import { forwardRef, ReactElement } from "react";
+import { memo, ReactElement } from "react";
+import { ExternalLinkIcon } from "./icons.generated";
 
-import {
-  Link as MuiLink,
-  LinkProps as MuiLinkProps,
-  SvgIcon,
-} from "@mui/material";
+import { Link as MuiLink } from "@mui/material";
+
+export const linkVariantValues = ["default", "monochrome"] as const;
 
 export type LinkProps = {
+  /**
+   * The content within the Link
+   */
   children: React.ReactNode;
+  /**
+   * The Link destination
+   */
   href: string;
+  /**
+   * An optional Icon component at the start of the Link
+   */
   icon?: ReactElement;
+  /**
+   * The HTML `rel` attribute for the Link
+   */
   rel?: string;
-  target?: "_self" | "_blank" | "_parent" | "_top" | string;
-  variant?: MuiLinkProps["variant"];
+  /**
+   * The HTML `target` attribute for the Link
+   */
+  target?:
+    | "_self"
+    | "_blank"
+    | "_parent"
+    | "_top"
+    | (string & NonNullable<unknown>);
+  /**
+   * The visual presentation of the Link (default or monochrome)
+   */
+  variant?: (typeof linkVariantValues)[number];
 };
 
-export const Link = forwardRef<HTMLAnchorElement, LinkProps>((props, ref) => {
-  const { icon, children, target, variant } = props;
-  return (
-    <MuiLink ref={ref} variant={variant} target={target}>
-      {icon && <span className="Link-icon">{icon}</span>}
-      {children}
-      {target === "_blank" && (
-        <span className="Link-indicator" role="presentation">
-          <SvgIcon viewBox="0 0 16 16">
-            <path
-              fillRule="evenodd"
-              clipRule="evenodd"
-              d="M13.2929 2H7.99998V1H14.5C14.7761 1 15 1.22386 15 1.5V8H14V2.70711L6.35353 10.3536L5.64642 9.64645L13.2929 2ZM1.5 4H1V4.5V14.5V15H1.5H11.5H12V14.5V8H11V14H2V5H8V4H1.5Z"
-              fill="currentColor"
-            />
-          </SvgIcon>
-        </span>
-      )}
-    </MuiLink>
-  );
-});
+const Link = ({ children, href, icon, target, rel, variant }: LinkProps) => (
+  <MuiLink href={href} rel={rel} target={target} variant={variant}>
+    {icon && <span className="Link-icon">{icon}</span>}
+
+    {children}
+
+    {target === "_blank" && (
+      <span className="Link-indicator" role="presentation">
+        <ExternalLinkIcon />
+      </span>
+    )}
+  </MuiLink>
+);
+
+const MemoizedLink = memo(Link);
+
+MemoizedLink.displayName = "Link";
+
+export { MemoizedLink as Link };

package/src/MenuButton.tsx

@@ -10,29 +10,27 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {
-  Button,
-  ButtonProps,
-  ChevronDownIcon,
-  Divider,
-  ListSubheader,
-  Menu,
-  MenuItem,
-  useUniqueId,
-} from "./";
-import { memo, MouseEvent, ReactElement, useMemo, useState } from "react";
+import { Button, buttonVariantValues, MenuItem, useUniqueId } from "./";
+import { Divider, ListSubheader, Menu } from "@mui/material";
+import { ChevronDownIcon } from "./icons.generated";
+import { memo, type ReactElement, useCallback, useMemo, useState } from "react";
+
+import { MenuContext, MenuContextType } from "./MenuContext";
+import { NullElement } from "./NullElement";
 
 export type MenuButtonProps = {
   /**
-   * The <MenuItem> components within the Menu.
+   * The ARIA label for the Button
    */
-  children: Array<
-    ReactElement<typeof MenuItem | typeof Divider | typeof ListSubheader>
-  >;
+  ariaLabel?: string;
   /**
-   * The end Icon on the trigggering Button
+   * The ID of the element that labels the Button
+   */
+  ariaLabelledBy?: string;
+  /**
+   * The ID of the element that describes the Button
    */
-  buttonEndIcon?: ReactElement;
+  ariaDescribedBy?: string;
   /**
    * The label on the triggering Button
    */
@@ -40,31 +38,67 @@ export type MenuButtonProps = {
   /**
    * The variant of the triggering Button
    */
-  buttonVariant?: ButtonProps["variant"];
+  buttonVariant?: (typeof buttonVariantValues)[number];
+  /**
+   * The <MenuItem> components within the Menu.
+   */
+  children: Array<
+    ReactElement<
+      typeof MenuItem | typeof Divider | typeof ListSubheader | NullElement
+    >
+  >;
+  /**
+   * The end Icon on the trigggering Button
+   */
+  endIcon?: ReactElement;
   /**
-   * The id of the `input` element.
+   * The id of the Button
    */
   id?: string;
-};
+  /**
+   * The tooltip text for the Button if it's icon-only
+   */
+  tooltipText?: string;
+} & (
+  | {
+      ariaLabel?: string;
+      ariaLabelledBy?: string;
+      buttonLabel: string;
+    }
+  | {
+      ariaLabel: string;
+      ariaLabelledBy?: string;
+      buttonLabel?: undefined | "";
+    }
+  | {
+      ariaLabel?: string;
+      ariaLabelledBy: string;
+      buttonLabel?: undefined | "";
+    }
+);
 
 const MenuButton = ({
+  ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
   buttonLabel = "",
-  children,
-  buttonEndIcon = <ChevronDownIcon />,
   buttonVariant = "secondary",
+  children,
+  endIcon = <ChevronDownIcon />,
   id: idOverride,
+  tooltipText,
 }: MenuButtonProps) => {
   const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null);
 
-  const open = Boolean(anchorEl);
+  const isOpen = Boolean(anchorEl);
 
-  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
-    setAnchorEl(event.currentTarget);
-  };
-
-  const handleClose = () => {
+  const closeMenu = useCallback<MenuContextType["closeMenu"]>(() => {
     setAnchorEl(null);
-  };
+  }, []);
+
+  const openMenu = useCallback<MenuContextType["openMenu"]>((event) => {
+    setAnchorEl(event.currentTarget);
+  }, []);
 
   const uniqueId = useUniqueId(idOverride);
 
@@ -73,31 +107,47 @@ const MenuButton = ({
     [uniqueId]
   );
 
+  const providerValue = useMemo<MenuContextType>(
+    () => ({
+      closeMenu,
+      openMenu,
+    }),
+    [closeMenu, openMenu]
+  );
+
   return (
     <div>
       <Button
-        endIcon={buttonEndIcon}
-        id={`${uniqueId}-button`}
-        aria-controls={open ? `${uniqueId}-menu` : undefined}
+        aria-controls={isOpen ? `${uniqueId}-menu` : undefined}
+        aria-expanded={isOpen ? "true" : undefined}
         aria-haspopup="true"
-        aria-expanded={open ? "true" : undefined}
-        onClick={handleClick}
-        text={buttonLabel}
+        ariaDescribedBy={ariaDescribedBy}
+        ariaLabel={ariaLabel}
+        ariaLabelledBy={ariaLabelledBy}
+        endIcon={endIcon}
+        id={`${uniqueId}-button`}
+        label={buttonLabel}
+        onClick={openMenu}
+        tooltipText={tooltipText}
         variant={buttonVariant}
       />
+
       <Menu
-        id={`${uniqueId}-menu`}
         anchorEl={anchorEl}
-        open={open}
-        onClose={handleClose}
+        id={`${uniqueId}-menu`}
         MenuListProps={menuListProps}
+        onClose={closeMenu}
+        open={isOpen}
       >
-        {children}
+        <MenuContext.Provider value={providerValue}>
+          {children}
+        </MenuContext.Provider>
       </Menu>
     </div>
   );
 };
 
 const MemoizedMenuButton = memo(MenuButton);
+MemoizedMenuButton.displayName = "MenuButton";
 
 export { MemoizedMenuButton as MenuButton };

package/src/MenuContext.ts

@@ -0,0 +1,25 @@
+/*!
+ * 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 { createContext, MouseEventHandler } from "react";
+
+export type MenuContextType = {
+  closeMenu: () => void;
+  openMenu: MouseEventHandler<HTMLElement>;
+};
+
+export const MenuContext = createContext<MenuContextType>({
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  closeMenu: () => {},
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  openMenu: () => {},
+});

package/src/MenuItem.tsx

@@ -10,40 +10,85 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import { memo, forwardRef } from "react";
-import { MenuItem as MuiMenuItem } from "@mui/material";
+import {
+  MenuItem as MuiMenuItem,
+  MenuItemProps as MuiMenuItemProps,
+} from "@mui/material";
 import { menuItemClasses } from "@mui/material/MenuItem";
-import type { MenuItemProps as MuiMenuItemProps } from "@mui/material";
-
-export interface MenuItemProps
-  extends Omit<
-    MuiMenuItemProps,
-    | "component"
-    | "dense"
-    | "disableGutters"
-    | "divider"
-    | "focusVisibleClassName"
-  > {
+import { memo, useCallback, useContext, type ReactNode } from "react";
+
+import { MenuContext } from "./MenuContext";
+
+export type MenuItemProps = {
+  /**
+   * The content of the menu item.
+   */
+  children: ReactNode;
+  /**
+   * If `true`, the menu item will receive focus automatically.
+   */
+  hasInitialFocus?: boolean;
+  /**
+   * If `true`, the menu item will be visually marked as selected.
+   */
+  isSelected?: boolean;
   /**
-   * Toggles whether or not the MenuItem represents a destructive action.
+   * If `true`, the menu item will be visually marked as destructive.
    */
   isDestructive?: boolean;
-}
+  /**
+   * Callback fired when the menu item is clicked.
+   */
+  onClick?: MuiMenuItemProps["onClick"];
+  /**
+   * The value associated with the menu item.
+   */
+  value?: string;
+  /**
+   * The variant of the menu item.
+   * - "default": The default variant.
+   * - "destructive": A variant indicating a destructive action.
+   */
+  variant?: "default" | "destructive";
+};
+
+const MenuItem = ({
+  children,
+  hasInitialFocus,
+  isSelected,
+  onClick: onClickProp,
+  value,
+  variant = "default",
+}: MenuItemProps) => {
+  const { closeMenu } = useContext(MenuContext);
+
+  const onClick = useCallback<NonNullable<MuiMenuItemProps["onClick"]>>(
+    (event) => {
+      onClickProp?.(event);
+      closeMenu();
+    },
+    [onClickProp, closeMenu]
+  );
 
-const MenuItem = forwardRef<HTMLLIElement, MenuItemProps>(
-  ({ isDestructive, ...props }, ref) => (
+  return (
     <MuiMenuItem
-      {...props}
-      ref={ref}
+      /* eslint-disable-next-line jsx-a11y/no-autofocus */
+      autoFocus={hasInitialFocus}
+      selected={isSelected}
+      value={value}
+      onClick={onClick}
       className={
-        isDestructive ? `${menuItemClasses.root}-destructive` : undefined
+        variant === "destructive"
+          ? `${menuItemClasses.root}-destructive`
+          : undefined
       }
     >
-      {props.children}
+      {children}
     </MuiMenuItem>
-  )
-);
+  );
+};
 
 const MemoizedMenuItem = memo(MenuItem);
+MemoizedMenuItem.displayName = "MenuItem";
 
 export { MemoizedMenuItem as MenuItem };