docs(Expandable section, file upload, modal, pagination): add compone…

packages/react-core/src/components/ExpandableSection/ExpandableSection.tsx

@@ -10,42 +10,53 @@ export enum ExpandableSectionVariant {
   truncate = 'truncate'
 }
 
+/** The main expandable section component. */
+
 export interface ExpandableSectionProps extends React.HTMLProps<HTMLDivElement> {
   /** Content rendered inside the expandable section. */
   children?: React.ReactNode;
   /** Additional classes added to the expandable section. */
   className?: string;
-  /** Flag to indicate if the content is expanded */
-  isExpanded?: boolean;
-  /** Text that appears in the attached toggle */
-  toggleText?: string;
-  /** Text that appears in the attached toggle when expanded (will override toggleText if both are specified; used for uncontrolled expandable with dynamic toggle text) */
-  toggleTextExpanded?: string;
-  /** Text that appears in the attached toggle when collapsed (will override toggleText if both are specified; used for uncontrolled expandable with dynamic toggle text) */
-  toggleTextCollapsed?: string;
-  /** React node that appears in the attached toggle in place of toggle text */
-  toggleContent?: React.ReactNode;
-  /** Callback function to toggle the expandable section. Detached expandable sections should use the onToggle property of the expandable section toggle sub-component. */
-  onToggle?: (isExpanded: boolean) => void;
-  /** Forces active state */
-  isActive?: boolean;
-  /** Indicates the expandable section has a detached toggle */
-  isDetached?: boolean;
-  /** ID of the content of the expandable section */
+  /** Id of the content of the expandable section. When passing in the isDetached property, this
+   * property's value should match the contenId property of the expandable section toggle sub-component.
+   */
   contentId?: string;
-  /** Display size variant. Set to large for disclosure styling. */
+  /** Display size variant. Set to "large" for disclosure styling. */
   displaySize?: 'default' | 'large';
-  /** Flag to indicate the width of the component is limited. Set to true for disclosure styling. */
-  isWidthLimited?: boolean;
-  /** Flag to indicate if the content is indented */
+  /** Forces active state. */
+  isActive?: boolean;
+  /** Indicates the expandable section has a detached toggle. */
+  isDetached?: boolean;
+  /** Flag to indicate if the content is expanded. */
+  isExpanded?: boolean;
+  /** Flag to indicate if the content is indented. */
   isIndented?: boolean;
+  /** Flag to indicate the width of the component is limited. Set to "true" for disclosure styling. */
+  isWidthLimited?: boolean;
+  /** Callback function to toggle the expandable section. Detached expandable sections should
+   * use the onToggle property of the expandable section toggle sub-component.
+   */
+  onToggle?: (isExpanded: boolean) => void;
+  /** React node that appears in the attached toggle in place of the toggleText property. */
+  toggleContent?: React.ReactNode;
+  /** Text that appears in the attached toggle. */
+  toggleText?: string;
+  /** Text that appears in the attached toggle when collapsed (will override toggleText if
+   * both are specified; used for uncontrolled expandable with dynamic toggle text).
+   */
+  toggleTextCollapsed?: string;
+  /** Text that appears in the attached toggle when expanded (will override toggleText if
+   * both are specified; used for uncontrolled expandable with dynamic toggle text).
+   */
+  toggleTextExpanded?: string;
+  /** @beta Truncates the expandable content to the specified number of lines when using the
+   * "truncate" variant.
+   */
+  truncateMaxLines?: number;
   /** @beta Determines the variant of the expandable section. When passing in "truncate" as the
    * variant, the expandable content will be truncated after 3 lines by default.
    */
   variant?: 'default' | 'truncate';
-  /** @beta Truncates the expandable content to the specified number of lines when using the
-   * "truncate" variant. */
-  truncateMaxLines?: number;
 }
 
 interface ExpandableSectionState {

packages/react-core/src/components/ExpandableSection/ExpandableSectionToggle.tsx

@@ -3,21 +3,27 @@ import styles from '@patternfly/react-styles/css/components/ExpandableSection/ex
 import { css } from '@patternfly/react-styles';
 import AngleRightIcon from '@patternfly/react-icons/dist/esm/icons/angle-right-icon';
 
+/** Acts as the toggle sub-component when the main expandable section component has the isDetached
+ * property passed in. Allows for more custom control over the expandable section's toggle.
+ */
+
 export interface ExpandableSectionToggleProps extends React.HTMLProps<HTMLDivElement> {
   /** Content rendered inside the expandable toggle. */
   children?: React.ReactNode;
   /** Additional classes added to the expandable toggle. */
   className?: string;
-  /** Flag indicating if the expandable section is expanded. */
-  isExpanded?: boolean;
-  /** Callback function to toggle the expandable content. */
-  onToggle?: (isExpanded: boolean) => void;
-  /** ID of the toggle's respective expandable section content. */
+  /** Id of the toggle's respective expandable section content. The value passed into this
+   * property should match the contentId property of the main expandable section component.
+   */
   contentId?: string;
   /** Direction the toggle arrow should point when the expandable section is expanded. */
   direction?: 'up' | 'down';
   /** @beta Flag to determine toggle styling when the expandable content is truncated. */
   hasTruncatedContent?: boolean;
+  /** Flag indicating if the expandable section is expanded. */
+  isExpanded?: boolean;
+  /** Callback function to toggle the expandable content. */
+  onToggle?: (isExpanded: boolean) => void;
 }
 
 export const ExpandableSectionToggle: React.FunctionComponent<ExpandableSectionToggleProps> = ({

packages/react-core/src/components/FileUpload/FileUpload.tsx

@@ -8,22 +8,48 @@ interface DropzoneInputPropsWithRef extends DropzoneInputProps {
   ref: React.RefCallback<HTMLInputElement>; // Working around an issue in react-dropzone 9.0.0's types. Should not be necessary in later versions.
 }
 
+/** The main file upload component with drag and drop functionality built in by default. */
+
 export interface FileUploadProps
   extends Omit<
     FileUploadFieldProps,
     'children' | 'onBrowseButtonClick' | 'onClearButtonClick' | 'isDragActive' | 'containerRef'
   > {
-  /** Unique id for the TextArea, also used to generate ids for accessible labels. */
-  id: string;
-  /** What type of file. Determines what is is passed to `onChange` and expected by `value`
-   * (a string for 'text' and 'dataURL', or a File object otherwise. */
-  type?: 'text' | 'dataURL';
-  /** Value of the file's contents
-   * (string if text file, File object otherwise) */
-  value?: string | File;
+  /** Flag to allow editing of a text file's contents after it is selected from disk. */
+  allowEditingUploadedText?: boolean;
+  /** Aria-label for the text area. */
+  'aria-label'?: string;
+  /** Text for the browse button. */
+  browseButtonText?: string;
+  /** Additional children to render after (or instead of) the file preview. */
+  children?: React.ReactNode;
+  /** Additional classes added to the file upload container element. */
+  className?: string;
+  /** Text for the clear button. */
+  clearButtonText?: string;
   /** Value to be shown in the read-only filename field. */
   filename?: string;
-  /** @deprecated A callback for when the file contents change. Please instead use onFileInputChange, onTextChange, onDataChange, onClearClick individually.  */
+  /** Aria-label for the read-only filename field. */
+  filenameAriaLabel?: string;
+  /** Placeholder string to display in the empty filename field. */
+  filenamePlaceholder?: string;
+  /** Flag to hide the built-in preview of the file (where available). If true, you can use
+   * the children property to render an alternate preview.
+   */
+  hideDefaultPreview?: boolean;
+  /** Unique id for the text area. Also used to generate ids for accessible labels. */
+  id: string;
+  /** Flag to show if the field is disabled. */
+  isDisabled?: boolean;
+  /** Flag to show if a file is being loaded. */
+  isLoading?: boolean;
+  /** Flag to show if the field is read only. */
+  isReadOnly?: boolean;
+  /** Flag to show if the field is required. */
+  isRequired?: boolean;
+  /** @deprecated A callback for when the file contents changes. Please instead use
+   * onFileInputChange, onTextChange, onDataChange, and onClearClick individually.
+   */
   onChange?: (
     value: string | File,
     filename: string,
@@ -32,61 +58,42 @@ export interface FileUploadProps
       | React.DragEvent<HTMLElement> // User dragged/dropped a file
       | React.ChangeEvent<HTMLElement> // User typed in the TextArea
   ) => void;
+  /** Callback for clicking on the file upload field text area. By default, prevents a click
+   * in the text area from opening file dialog.
+   */
+  onClick?: (event: React.MouseEvent) => void;
   /** Change event emitted from the hidden \<input type="file" \> field associated with the component  */
   onFileInputChange?: (event: React.ChangeEvent<HTMLInputElement> | React.DragEvent<HTMLElement>, file: File) => void;
-  /** Callback for clicking on the FileUploadField text area. By default, prevents a click in the text area from opening file dialog. */
-  onClick?: (event: React.MouseEvent) => void;
-  /** Additional classes added to the FileUpload container element. */
-  className?: string;
-  /** Flag to show if the field is disabled. */
-  isDisabled?: boolean;
-  /** Flag to show if the field is read only. */
-  isReadOnly?: boolean;
-  /** Flag to show if a file is being loaded. */
-  isLoading?: boolean;
-  /** Aria-valuetext for the loading spinner */
+  /** Aria-valuetext for the loading spinner. */
   spinnerAriaValueText?: string;
-  /** Flag to show if the field is required. */
-  isRequired?: boolean;
+  /** What type of file. Determines what is passed to the onChange property and what is
+   * expected by the value property (a string for 'text' and 'dataURL', or a File object otherwise.
+   */
+  type?: 'text' | 'dataURL';
   /** Value to indicate if the field is modified to show that validation state.
    * If set to success, field will be modified to indicate valid state.
-   * If set to error,  field will be modified to indicate error state.
+   * If set to error, field will be modified to indicate error state.
    */
   validated?: 'success' | 'error' | 'default';
-  /** Aria-label for the TextArea. */
-  'aria-label'?: string;
-  /** Placeholder string to display in the empty filename field */
-  filenamePlaceholder?: string;
-  /** Aria-label for the read-only filename field */
-  filenameAriaLabel?: string;
-  /** Text for the Browse button */
-  browseButtonText?: string;
-  /** Text for the Clear button */
-  clearButtonText?: string;
-  /** Flag to hide the built-in preview of the file (where available).
-   * If true, you can use children to render an alternate preview. */
-  hideDefaultPreview?: boolean;
-  /** Flag to allow editing of a text file's contents after it is selected from disk */
-  allowEditingUploadedText?: boolean;
-  /** Additional children to render after (or instead of) the file preview. */
-  children?: React.ReactNode;
+  /** Value of the file's contents (string if text file, File object otherwise). */
+  value?: string | File;
 
   // Props available in FileUpload but not FileUploadField:
 
-  /** A callback for when a selected file starts loading */
-  onReadStarted?: (fileHandle: File) => void;
-  /** A callback for when a selected file finishes loading */
-  onReadFinished?: (fileHandle: File) => void;
-  /** A callback for when the FileReader API fails */
-  onReadFailed?: (error: DOMException, fileHandle: File) => void;
   /** Optional extra props to customize react-dropzone. */
   dropzoneProps?: DropzoneProps;
-  /** Clear button was clicked */
+  /** Clear button was clicked. */
   onClearClick?: React.MouseEventHandler<HTMLButtonElement>;
-  /** Text area text changed */
-  onTextChange?: (text: string) => void;
   /** On data changed - if type='text' or type='dataURL' and file was loaded it will call this method */
   onDataChange?: (data: string) => void;
+  /** A callback for when the FileReader API fails. */
+  onReadFailed?: (error: DOMException, fileHandle: File) => void;
+  /** A callback for when a selected file finishes loading. */
+  onReadFinished?: (fileHandle: File) => void;
+  /** A callback for when a selected file starts loading. */
+  onReadStarted?: (fileHandle: File) => void;
+  /** Text area text changed. */
+  onTextChange?: (text: string) => void;
 }
 
 export const FileUpload: React.FunctionComponent<FileUploadProps> = ({

packages/react-core/src/components/FileUpload/FileUploadField.tsx

@@ -8,79 +8,85 @@ import { TextArea, TextAreResizeOrientation } from '../TextArea';
 import { Spinner, spinnerSize } from '../Spinner';
 import { fileReaderType } from '../../helpers/fileUtils';
 
+/** A more customizable file upload component for implementing custom logic. Drag and drop
+ * functionality is not built in by default.
+ */
+
 export interface FileUploadFieldProps extends Omit<React.HTMLProps<HTMLDivElement>, 'value' | 'onChange'> {
-  /** Unique id for the TextArea, also used to generate ids for accessible labels */
-  id: string;
-  /** What type of file. Determines what is is expected by `value`
-   * (a string for 'text' and 'dataURL', or a File object otherwise). */
-  type?: 'text' | 'dataURL';
-  /** Value of the file's contents
-   * (string if text file, File object otherwise) */
-  value?: string | File;
+  /** Flag to allow editing of a text file's contents after it is selected from disk. */
+  allowEditingUploadedText?: boolean;
+  /** Aria-label for the text area. */
+  'aria-label'?: string;
+  /** Text for the browse button. */
+  browseButtonText?: string;
+  /** Additional children to render after (or instead of) the file preview. */
+  children?: React.ReactNode;
+  /** Additional classes added to the file upload field container element. */
+  className?: string;
+  /** Text for the clear button. */
+  clearButtonText?: string;
   /** Value to be shown in the read-only filename field. */
   filename?: string;
-  /** A callback for when the TextArea value changes. */
+  /** Aria-label for the read-only filename field. */
+  filenameAriaLabel?: string;
+  /** Placeholder string to display in the empty filename field. */
+  filenamePlaceholder?: string;
+  /** Flag to hide the built-in preview of the file (where available). If true, you can use
+   * the children property to render an alternate preview.
+   */
+  hideDefaultPreview?: boolean;
+  /** Unique id for the text area. Also used to generate ids for accessible labels. */
+  id: string;
+  /** Flag to disable the clear button. */
+  isClearButtonDisabled?: boolean;
+  /** Flag to show if the field is disabled. */
+  isDisabled?: boolean;
+  /** Flag to show if a file is being loaded. */
+  isLoading?: boolean;
+  /** Flag to show if the field is read only. */
+  isReadOnly?: boolean;
+  /** Flag to show if the field is required. */
+  isRequired?: boolean;
+  /** A callback for when the text area value changes. */
   onChange?: (
     value: string,
     filename: string,
     event:
       | React.ChangeEvent<HTMLTextAreaElement> // User typed in the TextArea
       | React.MouseEvent<HTMLButtonElement, MouseEvent> // User clicked Clear button
   ) => void;
-  /** Additional classes added to the FileUploadField container element. */
-  className?: string;
-  /** Flag to show if the field is disabled. */
-  isDisabled?: boolean;
-  /** Flag to show if the field is read only. */
-  isReadOnly?: boolean;
-  /** Flag to show if a file is being loaded. */
-  isLoading?: boolean;
-  /** Aria-valuetext for the loading spinner */
+  /** Aria-valuetext for the loading spinner. */
   spinnerAriaValueText?: string;
-  /** Flag to show if the field is required. */
-  isRequired?: boolean;
+  /** What type of file. Determines what is is expected by the value property (a string for
+   * 'text' and 'dataURL', or a File object otherwise).
+   */
+  type?: 'text' | 'dataURL';
   /** Value to indicate if the field is modified to show that validation state.
    * If set to success, field will be modified to indicate valid state.
    * If set to error,  field will be modified to indicate error state.
    */
   validated?: 'success' | 'error' | 'default';
-  /** Aria-label for the TextArea. */
-  'aria-label'?: string;
-  /** Placeholder string to display in the empty filename field */
-  filenamePlaceholder?: string;
-  /** Aria-label for the read-only filename field */
-  filenameAriaLabel?: string;
-  /** Text for the Browse button */
-  browseButtonText?: string;
-  /** Text for the Clear button */
-  clearButtonText?: string;
-  /** Flag to disable the Clear button */
-  isClearButtonDisabled?: boolean;
-  /** Flag to hide the built-in preview of the file (where available).
-   * If true, you can use children to render an alternate preview. */
-  hideDefaultPreview?: boolean;
-  /** Flag to allow editing of a text file's contents after it is selected from disk */
-  allowEditingUploadedText?: boolean;
-  /** Additional children to render after (or instead of) the file preview. */
-  children?: React.ReactNode;
+  /** Value of the file's contents (string if text file, File object otherwise). */
+  value?: string | File;
 
   // Props available in FileUploadField but not FileUpload:
 
-  /** A callback for when the Browse button is clicked. */
+  /** A reference object to attach to the file upload field container element. */
+  containerRef?: React.Ref<HTMLDivElement>;
+  /** Flag to show if a file is being dragged over the file upload field. */
+  isDragActive?: boolean;
+  /** A callback for when the browse button is clicked. */
   onBrowseButtonClick?: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
-  /** A callback for when the Clear button is clicked. */
+  /** A callback for when the clear button is clicked. */
   onClearButtonClick?: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
-  /** A callback from when the text area is clicked. Can also be set via the onClick property of FileUpload. */
+  /** Callback for when focus is lost on the text area field. */
+  onTextAreaBlur?: (event?: any) => void;
+  /** A callback for when the text area is clicked. Can also be set via the onClick property
+   * of the file upload component. */
   onTextAreaClick?: (event: React.MouseEvent<HTMLTextAreaElement, MouseEvent>) => void;
-  /** Flag to show if a file is being dragged over the field */
-  isDragActive?: boolean;
-  /** A reference object to attach to the FileUploadField container element. */
-  containerRef?: React.Ref<HTMLDivElement>;
-  /** Text area text changed */
+  /** Text area text changed. */
   onTextChange?: (text: string) => void;
-  /** Callback for when focus is lost on the text area field */
-  onTextAreaBlur?: (event?: any) => void;
-  /** Placeholder string to display in the empty text area field */
+  /** Placeholder string to display in the empty text area field. */
   textAreaPlaceholder?: string;
 }