@okta/odyssey-react-mui 0.23.0 → 1.0.0

package/src/Callout.tsx

@@ -0,0 +1,62 @@
+/*!
+ * 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, ReactNode } from "react";
+import { Alert, AlertTitle, Box } from "@mui/material";
+import { ScreenReaderText } from "./ScreenReaderText";
+import { useTranslation } from "react-i18next";
+
+export const calloutRoleValues = ["status", "alert"] as const;
+export const calloutSeverityValues = [
+  "success",
+  "info",
+  "warning",
+  "error",
+] as const;
+
+export type CalloutProps = {
+  /**
+   * The contents of the Callout
+   */
+  children: ReactNode;
+  /**
+   * Sets the ARIA role of the Callout
+   * ("status" for something that dynamically updates, "alert" for errors, null for something
+   * unchanging)
+   */
+  role?: (typeof calloutRoleValues)[number];
+  /**
+   * Determine the color and icon of the Callout
+   */
+  severity: (typeof calloutSeverityValues)[number];
+  /**
+   * The title of the Callout
+   */
+  title?: string;
+};
+
+const Callout = ({ children, role, severity, title }: CalloutProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <Alert role={role} severity={severity} variant="callout">
+      <ScreenReaderText>{t(`severity.${severity}`)}: </ScreenReaderText>
+      {title && <AlertTitle>{title}</AlertTitle>}
+      <Box component="div">{children}</Box>
+    </Alert>
+  );
+};
+
+const MemoizedCallout = memo(Callout);
+MemoizedCallout.displayName = "Callout";
+
+export { MemoizedCallout as Callout };

package/src/Checkbox.tsx

@@ -10,53 +10,129 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-import { Checkbox as MuiCheckbox } from "@mui/material";
-import { ChangeEventHandler, memo } from "react";
+import {
+  Checkbox as MuiCheckbox,
+  CheckboxProps as MuiCheckboxProps,
+  FormControlLabel,
+} from "@mui/material";
+import { Typography } from "./Typography";
+import { memo, useCallback, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
 
-import { FormControlLabel } from ".";
+export const checkboxValidityValues = ["valid", "invalid", "inherit"] as const;
 
 export type CheckboxProps = {
+  /**
+   * The ARIA label for the Checkbox
+   */
   ariaLabel?: string;
+  /**
+   * The ID of the element that labels the Checkbox
+   */
   ariaLabelledBy?: string;
-  isChecked?: boolean;
+  /**
+   * Determines whether the Checkbox is checked
+   */
   isDefaultChecked?: boolean;
+  /**
+   * Determines whether the Checkbox is disabled
+   */
   isDisabled?: boolean;
-  hasError?: boolean;
+  /**
+   * Determines whether the Checkbox is in an indeterminate state
+   */
   isIndeterminate?: boolean;
+  /**
+   * Determines whether the Checkbox is required
+   */
+  isRequired?: boolean;
+  /**
+   * The label text for the Checkbox
+   */
   label?: string;
+  /**
+   * The name attribute of the Checkbox
+   */
   name?: string;
-  onChange?: ChangeEventHandler<EventTarget>;
+  /**
+   * The change event handler for the Checkbox
+   */
+  onChange?: MuiCheckboxProps["onChange"];
+  /**
+   * The checkbox validity, if different from its enclosing group. Defaults to "inherit".
+   */
+  validity?: (typeof checkboxValidityValues)[number];
+  /**
+   * The value attribute of the Checkbox
+   */
   value?: string;
 };
 
 const Checkbox = ({
   ariaLabel,
   ariaLabelledBy,
-  isChecked,
-  isDefaultChecked,
+  isDefaultChecked = false,
   isDisabled,
   isIndeterminate,
-  hasError,
-  label,
+  isRequired,
+  label: labelProp,
   name,
-  onChange,
+  onChange: onChangeProp,
+  validity = "inherit",
   value,
-}: CheckboxProps) => (
-  <FormControlLabel
-    aria-label={ariaLabel}
-    aria-labelledby={ariaLabelledBy}
-    checked={isChecked}
-    className={hasError ? "Mui-error" : ""}
-    control={<MuiCheckbox indeterminate={isIndeterminate} />}
-    defaultChecked={isDefaultChecked}
-    disabled={isDisabled}
-    label={label}
-    name={name}
-    onChange={onChange}
-    value={value}
-  />
-);
+}: CheckboxProps) => {
+  const { t } = useTranslation();
+  const [isCheckedValue, setIsCheckedValue] = useState(isDefaultChecked);
+
+  const label = useMemo(() => {
+    if (isRequired) {
+      return (
+        <>
+          {labelProp}{" "}
+          <Typography component="span" color="textSecondary">
+            ({t("fieldlabel.required.text")})
+          </Typography>
+        </>
+      );
+    } else {
+      return <>{labelProp}</>;
+    }
+  }, [isRequired, labelProp, t]);
+
+  const onChange = useCallback(
+    (event, checked) => {
+      setIsCheckedValue(event.target.checked);
+      onChangeProp?.(event, checked);
+    },
+    [onChangeProp]
+  );
+
+  return (
+    <FormControlLabel
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      checked={isCheckedValue}
+      className={
+        validity === "invalid"
+          ? "Mui-error"
+          : validity === "valid"
+          ? "Mui-valid"
+          : ""
+      }
+      control={
+        <MuiCheckbox indeterminate={isIndeterminate} required={isRequired} />
+      }
+      disabled={isDisabled}
+      label={label}
+      name={name}
+      onChange={onChange}
+      value={value}
+      required={isRequired}
+    />
+  );
+};
 
 const MemoizedCheckbox = memo(Checkbox);
+MemoizedCheckbox.displayName = "Checkbox";
 
 export { MemoizedCheckbox as Checkbox };

package/src/CheckboxGroup.tsx

@@ -17,25 +17,45 @@ import { Checkbox } from "./Checkbox";
 import { Field } from "./Field";
 
 export type CheckboxGroupProps = {
+  /**
+   * A single Checkbox element or an array of Checkbox elements
+   */
   children:
     | ReactElement<typeof Checkbox>
     | Array<ReactElement<typeof Checkbox>>;
+  /**
+   * The error message for the CheckboxGroup
+   */
   errorMessage?: string;
+  /**
+   * The hint text for the CheckboxGroup
+   */
   hint?: string;
   /**
    * The id of the `input` element. This will also be the input's `name` field.
    */
   id?: string;
+  /**
+   * If `true`, the CheckboxGroup is disabled
+   */
   isDisabled?: boolean;
+  /**
+   * If `true`, the CheckboxGroup is required
+   */
+  isRequired?: boolean;
+  /**
+   * The label text for the CheckboxGroup
+   */
   label: string;
 };
 
 const CheckboxGroup = ({
   children,
-  isDisabled,
   errorMessage,
   hint,
   id: idOverride,
+  isDisabled,
+  isRequired = false,
   label,
 }: CheckboxGroupProps) => {
   const renderFieldComponent = useCallback(
@@ -51,10 +71,11 @@ const CheckboxGroup = ({
     <Field
       errorMessage={errorMessage}
       fieldType="group"
-      hasVisibleLabel={false}
+      hasVisibleLabel={true}
       hint={hint}
       id={idOverride}
       isDisabled={isDisabled}
+      isOptional={!isRequired}
       label={label}
       renderFieldComponent={renderFieldComponent}
     />
@@ -62,5 +83,6 @@ const CheckboxGroup = ({
 };
 
 const MemoizedCheckboxGroup = memo(CheckboxGroup);
+MemoizedCheckboxGroup.displayName = "CheckboxGroup";
 
 export { MemoizedCheckboxGroup as CheckboxGroup };

package/src/CircularProgress.tsx

@@ -13,12 +13,24 @@
 import { CircularProgress as MuiCircularProgress } from "@mui/material";
 
 export type CircularProgressProps = {
+  /**
+   * The ARIA label for the progress spinner
+   */
+  ariaLabel?: string;
+  /**
+   * The percentage filled the spinner should be, as an integer.
+   * If undefined, the spinner will spin perpetually.
+   */
   value?: number;
 };
 
-export const CircularProgress = ({ value }: CircularProgressProps) => (
+export const CircularProgress = ({
+  ariaLabel,
+  value,
+}: CircularProgressProps) => (
   <MuiCircularProgress
     value={value}
     variant={value ? "determinate" : "indeterminate"}
+    aria-label={ariaLabel}
   />
 );

package/src/Dialog.tsx

@@ -17,7 +17,8 @@ import {
   DialogContentText,
   DialogActions,
 } from "@mui/material";
-import { Button, CloseIcon } from "./";
+import { Button } from "./Button";
+import { CloseIcon } from "./icons.generated";
 import {
   memo,
   ReactNode,
@@ -28,23 +29,46 @@ import {
 } from "react";
 
 export type DialogProps = {
-  callToActionPrimaryComponent?: ReactElement<typeof Button>;
-  callToActionSecondaryComponent?: ReactElement<typeof Button>;
-  callToActionTertiaryComponent?: ReactElement<typeof Button>;
-  children: ReactNode | Array<ReactNode>;
-  onClose: () => void;
+  /**
+   * An optional Button object to be situated in the Dialog footer. Should almost always be of variant `primary`.
+   */
+  callToActionFirstComponent?: ReactElement<typeof Button>;
+  /**
+   * An optional Button object to be situated in the Dialog footer, alongside the `callToActionPrimaryComponent`.
+   */
+  callToActionSecondComponent?: ReactElement<typeof Button>;
+  /**
+   * An optional Button object to be situated in the Dialog footer, alongside the other two `callToAction` components.
+   */
+  callToActionLastComponent?: ReactElement<typeof Button>;
+  /**
+   * The content of the Dialog. May be a `string` or any other `ReactNode` or array of `ReactNode`s.
+   */
+  children: ReactNode;
+  /**
+   * When set to `true`, the Dialog will be visible.
+   */
   isOpen: boolean;
+  /**
+   * Callback that controls what happens when the Dialog is dismissed
+   */
+  onClose: () => void;
+  /**
+   * The title of the Dialog
+   */
   title: string;
+  ariaLabel: string;
 };
 
 const Dialog = ({
-  callToActionPrimaryComponent,
-  callToActionSecondaryComponent,
-  callToActionTertiaryComponent,
+  callToActionFirstComponent,
+  callToActionSecondComponent,
+  callToActionLastComponent,
   children,
   isOpen,
   onClose,
   title,
+  ariaLabel,
 }: DialogProps) => {
   const [isContentScrollable, setIsContentScrollable] = useState(false);
   const dialogContentRef = useRef<HTMLDivElement>(null);
@@ -83,22 +107,25 @@ const Dialog = ({
       <DialogTitle>
         {title}
         <Button
-          variant="floating"
+          ariaLabel={ariaLabel}
+          label=""
           onClick={onClose}
+          size="small"
           startIcon={<CloseIcon />}
+          variant="floating"
         />
       </DialogTitle>
       <DialogContent dividers={isContentScrollable} ref={dialogContentRef}>
         {content}
       </DialogContent>
 
-      {(callToActionPrimaryComponent ||
-        callToActionSecondaryComponent ||
-        callToActionTertiaryComponent) && (
+      {(callToActionFirstComponent ||
+        callToActionSecondComponent ||
+        callToActionLastComponent) && (
         <DialogActions>
-          {callToActionTertiaryComponent}
-          {callToActionSecondaryComponent}
-          {callToActionPrimaryComponent}
+          {callToActionLastComponent}
+          {callToActionSecondComponent}
+          {callToActionFirstComponent}
         </DialogActions>
       )}
     </MuiDialog>
@@ -106,5 +133,6 @@ const Dialog = ({
 };
 
 const MemoizedDialog = memo(Dialog);
+MemoizedDialog.displayName = "Dialog";
 
 export { MemoizedDialog as Dialog };

package/src/Field.tsx

@@ -19,8 +19,13 @@ import {
 import { FieldError } from "./FieldError";
 import { FieldHint } from "./FieldHint";
 import { FieldLabel } from "./FieldLabel";
+import { Typography } from "./Typography";
+import { useFieldset } from "./FieldsetContext";
+import { useTranslation } from "react-i18next";
 import { useUniqueId } from "./useUniqueId";
 
+export const fieldTypeValues = ["single", "group"] as const;
+
 export type FieldProps = {
   /**
    * If `error` is not undefined, the `input` will indicate an error.
@@ -29,7 +34,10 @@ export type FieldProps = {
   /**
    * The field type determines how ARIA components are setup. It's important to use this to denote if you expect only one component (like a text field) or multiple (like a radio group).
    */
-  fieldType: "single" | "group";
+  fieldType: (typeof fieldTypeValues)[number];
+  /**
+   * If `true`, the Field label will be shown
+   */
   hasVisibleLabel: boolean;
   /**
    * The helper text content.
@@ -43,6 +51,10 @@ export type FieldProps = {
    * Important for narrowing down the `fieldset` role to "radiogroup".
    */
   isRadioGroup?: boolean;
+  /**
+   * Important for determining if children inherit error state
+   */
+  isCheckboxGroup?: boolean;
   /**
    * If `true`, the component is disabled.
    */
@@ -55,10 +67,6 @@ export type FieldProps = {
    * The label for the `input` element.
    */
   label: string;
-  /**
-   * The label for the `input` element if the it's not optional
-   */
-  optionalLabel?: string;
   /**
    * The short hint displayed in the `input` before the user enters a value.
    */
@@ -81,13 +89,14 @@ const Field = ({
   hasVisibleLabel,
   hint,
   id: idOverride,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   isRadioGroup = false,
   isOptional = false,
   label,
-  optionalLabel,
   renderFieldComponent,
 }: FieldProps) => {
+  const { t } = useTranslation();
+
   const id = useUniqueId(idOverride);
   const hintId = hint ? `${id}-hint` : undefined;
   const errorId = errorMessage ? `${id}-error` : undefined;
@@ -98,6 +107,13 @@ const Field = ({
     [errorId, hintId]
   );
 
+  const { isDisabled: isFieldsetDisabled } = useFieldset();
+
+  const isDisabled = useMemo(
+    () => isDisabledProp || isFieldsetDisabled,
+    [isDisabledProp, isFieldsetDisabled]
+  );
+
   return (
     <MuiFormControl
       component={fieldType === "group" ? "fieldset" : "div"}
@@ -106,14 +122,20 @@ const Field = ({
       role={isRadioGroup ? "radiogroup" : undefined}
     >
       {fieldType === "group" ? (
-        <MuiFormLabel component="legend">{label}</MuiFormLabel>
+        <MuiFormLabel component="legend">
+          {label}{" "}
+          {isOptional && label && (
+            <Typography component="span" color="textSecondary">
+              ({t("fieldlabel.optional.text")})
+            </Typography>
+          )}
+        </MuiFormLabel>
       ) : (
         <FieldLabel
           hasVisibleLabel={hasVisibleLabel}
           id={labelId}
           inputId={id}
           isOptional={isOptional}
-          optionalText={optionalLabel}
           text={label}
         />
       )}
@@ -131,5 +153,6 @@ const Field = ({
 };
 
 const MemoizedField = memo(Field);
+MemoizedField.displayName = "Field";
 
 export { MemoizedField as Field };

package/src/FieldError.tsx

@@ -12,8 +12,9 @@
 
 import { memo } from "react";
 
-import { FormHelperText } from ".";
+import { FormHelperText } from "@mui/material";
 import { ScreenReaderText } from "./ScreenReaderText";
+import { useTranslation } from "react-i18next";
 
 export type FieldErrorProps = {
   id?: string;
@@ -21,14 +22,19 @@ export type FieldErrorProps = {
 };
 
 const FieldError = ({ id, text }: FieldErrorProps) => {
+  const { t } = useTranslation();
+
   return (
     <FormHelperText error id={id}>
-      <ScreenReaderText>Error:</ScreenReaderText>
+      <ScreenReaderText>{`${t(
+        "fielderror.screenreader.text"
+      )}:`}</ScreenReaderText>
       {text}
     </FormHelperText>
   );
 };
 
 const MemoizedFieldError = memo(FieldError);
+MemoizedFieldError.displayName = "FieldError";
 
 export { MemoizedFieldError as FieldError };

package/src/FieldHint.tsx

@@ -12,7 +12,7 @@
 
 import { memo } from "react";
 
-import { FormHelperText } from "./";
+import { FormHelperText } from "@mui/material";
 
 export type FieldHintProps = {
   id?: string;
@@ -24,5 +24,6 @@ const FieldHint = ({ id, text }: FieldHintProps) => {
 };
 
 const MemoizedFieldHint = memo(FieldHint);
+MemoizedFieldHint.displayName = "FieldHint";
 
 export { MemoizedFieldHint as FieldHint };

package/src/FieldLabel.tsx

@@ -13,15 +13,15 @@
 import { InputLabel as MuiInputLabel } from "@mui/material";
 import { memo, useMemo } from "react";
 
+import { useTranslation } from "react-i18next";
 import { ScreenReaderText } from "./ScreenReaderText";
-import { Typography } from ".";
+import { Subordinate } from "./Typography";
 
 export type FieldLabelProps = {
   hasVisibleLabel: boolean;
   id: string;
   inputId: string;
   isOptional: boolean;
-  optionalText?: string;
   text: string;
 };
 
@@ -30,19 +30,20 @@ const FieldLabel = ({
   id,
   inputId,
   isOptional,
-  optionalText,
   text,
 }: FieldLabelProps) => {
+  const { t } = useTranslation();
+
   const inputLabel = useMemo(
     () => (
       <MuiInputLabel htmlFor={inputId} id={id}>
-        {text}
+        <span>{text}</span>
         {isOptional && (
-          <Typography variant="subtitle1">{optionalText}</Typography>
+          <Subordinate>{t("fieldlabel.optional.text")}</Subordinate>
         )}
       </MuiInputLabel>
     ),
-    [id, inputId, isOptional, optionalText, text]
+    [id, inputId, isOptional, text, t]
   );
 
   return hasVisibleLabel ? (
@@ -53,5 +54,6 @@ const FieldLabel = ({
 };
 
 const MemoizedFieldLabel = memo(FieldLabel);
+MemoizedFieldLabel.displayName = "FieldLabel";
 
 export { MemoizedFieldLabel as FieldLabel };