chore(DualListSelector/MultipleFileUpload): add composable structure and component descriptions

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

@@ -20,6 +20,10 @@ import { DualListSelectorControlsWrapper } from './DualListSelectorControlsWrapp
 import { DualListSelectorControl } from './DualListSelectorControl';
 import { DualListSelectorContext } from './DualListSelectorContext';
 
+/** Acts as a container for all other DualListSelector sub-components when using a
+ * composable dual list selector.
+ */
+
 export interface DualListSelectorProps {
   /** Additional classes applied to the dual list selector. */
   className?: string;

packages/react-core/src/components/DualListSelector/DualListSelectorControl.tsx

@@ -3,6 +3,10 @@ import { css } from '@patternfly/react-styles';
 import { Button, ButtonVariant } from '../Button';
 import { Tooltip } from '../Tooltip';
 
+/** Renders an individual control button for moving selected options between each
+ * dual list selector pane.
+ */
+
 export interface DualListSelectorControlProps extends Omit<React.HTMLProps<HTMLDivElement>, 'onClick'> {
   /** Content to be rendered in the dual list selector control. */
   children?: React.ReactNode;

packages/react-core/src/components/DualListSelector/DualListSelectorControlsWrapper.tsx

@@ -3,6 +3,8 @@ import styles from '@patternfly/react-styles/css/components/DualListSelector/dua
 import { css } from '@patternfly/react-styles';
 import { handleArrows } from '../../helpers';
 
+/** Acts as the container for the DualListSelectorControl sub-components. */
+
 export interface DualListSelectorControlsWrapperProps extends React.HTMLProps<HTMLDivElement> {
   /** Anything that can be rendered inside of the wrapper. */
   children?: React.ReactNode;

packages/react-core/src/components/DualListSelector/DualListSelectorList.tsx

@@ -4,6 +4,8 @@ import { DualListSelectorListItem } from './DualListSelectorListItem';
 import * as React from 'react';
 import { DualListSelectorListContext } from './DualListSelectorContext';
 
+/** Acts as the container for DualListSelectorListItem sub-components. */
+
 export interface DualListSelectorListProps extends React.HTMLProps<HTMLUListElement> {
   /** Content rendered inside the dual list selector list */
   children?: React.ReactNode;

packages/react-core/src/components/DualListSelector/DualListSelectorListItem.tsx

@@ -6,6 +6,10 @@ import GripVerticalIcon from '@patternfly/react-icons/dist/esm/icons/grip-vertic
 import { Button, ButtonVariant } from '../Button';
 import { DualListSelectorListContext } from './DualListSelectorContext';
 
+/** Creates an individual option that can be selected and moved between the
+ * dual list selector panes. This is contained within the DualListSelectorList sub-component.
+ */
+
 export interface DualListSelectorListItemProps extends React.HTMLProps<HTMLLIElement> {
   /** Content rendered inside the dual list selector. */
   children?: React.ReactNode;

packages/react-core/src/components/DualListSelector/DualListSelectorPane.tsx

@@ -8,6 +8,11 @@ import { DualListSelectorListWrapper } from './DualListSelectorListWrapper';
 import { DualListSelectorContext, DualListSelectorPaneContext } from './DualListSelectorContext';
 import { DualListSelectorList } from './DualListSelectorList';
 
+/** Acts as the container for a list of options that are either available or chosen,
+ * depending on the pane type (available or chosen). A search input and other actions,
+ * such as sorting, can also be passed into this sub-component.
+ */
+
 export interface DualListSelectorPaneProps {
   /** Additional classes applied to the dual list selector pane. */
   className?: string;

packages/react-core/src/components/DualListSelector/DualListSelectorTree.tsx

@@ -35,6 +35,10 @@ export interface DualListSelectorTreeItemData {
   isDisabled?: boolean;
 }
 
+/** Used in place of the DualListSelectorListItem sub-component when building a
+ * composable dual list selector with a tree.
+ */
+
 export interface DualListSelectorTreeProps extends Omit<React.HTMLProps<HTMLUListElement>, 'data'> {
   /** Data of the tree view */
   data: DualListSelectorTreeItemData[] | (() => DualListSelectorTreeItemData[]);

packages/react-core/src/components/DualListSelector/examples/DualListSelector.md

@@ -6,10 +6,10 @@ propComponents:
   [
     'DualListSelector',
     'DualListSelectorPane',
-    'DualListSelectorControl',
-    'DualListSelectorControlsWrapper',
     'DualListSelectorList',
     'DualListSelectorListItem',
+    'DualListSelectorControlsWrapper',
+    'DualListSelectorControl',
     'DualListSelectorTree',
     'DualListSelectorTreeItemData',
   ]
@@ -49,9 +49,9 @@ import PficonSortCommonAscIcon from '@patternfly/react-icons/dist/esm/icons/pfic
 ```ts file="./DualListSelectorTreeExample.tsx"
 ```
 
-### Composable dual list selector
+## Composable structure
 
-For more flexibility, a dual list selector can be built using sub components. When doing so, the intended component relationships are arranged as follows:
+The dual list selector can also be built in a composable manner to make customization easier. The standard sub-component relationships are arranged as follows:
 
 ```noLive
 <DualListSelector>
@@ -62,7 +62,7 @@ For more flexibility, a dual list selector can be built using sub components. Wh
   </DualListSelectorPane>
 
   <DualListSelectorControlsWrapper>
-    <DualListSelectorControl /> /* The standard Dual list selector has 4 controls */
+    <DualListSelectorControl /> /* A standard Dual list selector has 4 controls */
   </DualListSelectorControlsWrapper>
 
   <DualListSelectorPane isChosen>
@@ -73,10 +73,12 @@ For more flexibility, a dual list selector can be built using sub components. Wh
 </DualListSelector>
 ```
 
+### Composable dual list selector
+
 ```ts file="./DualListSelectorComposable.tsx"
 ```
 
-### Composable dual list selector with drag and drop
+### Composable with drag and drop
 
 This example only allows reordering the contents of the "chosen" pane with drag and drop. To make a pane able to be reordered:
 
@@ -95,7 +97,7 @@ Note: Keyboard accessibility and screen reader accessibility for the `DragDrop`
 ```ts file="DualListSelectorComposableDragDrop.tsx"
 ```
 
-### Composable dual list selector with tree
+### Composable with tree
 
 ```ts file="DualListSelectorComposableTree.tsx"
 ```

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

@@ -3,6 +3,11 @@ import Dropzone, { DropzoneProps, DropFileEventHandler } from 'react-dropzone';
 import styles from '@patternfly/react-styles/css/components/MultipleFileUpload/multiple-file-upload';
 import { css } from '@patternfly/react-styles';
 
+/** Acts as a container for all other MultipleFileUpload sub-components. This sub-component
+ * also provides the functionality for file uploads, and access to the uploaded files via
+ * a callback.
+ */
+
 export interface MultipleFileUploadProps extends Omit<React.HTMLProps<HTMLDivElement>, 'value'> {
   /** Content rendered inside the multi upload field */
   children?: React.ReactNode;

packages/react-core/src/components/MultipleFileUpload/MultipleFileUploadMain.tsx

@@ -5,6 +5,9 @@ import { MultipleFileUploadTitle } from './MultipleFileUploadTitle';
 import { MultipleFileUploadButton } from './MultipleFileUploadButton';
 import { MultipleFileUploadInfo } from './MultipleFileUploadInfo';
 
+/** Creates the visual upload interface, including the area to drag and drop files,
+ * an optional upload button, and descriptive instructions.
+ */
 export interface MultipleFileUploadMainProps extends React.HTMLProps<HTMLDivElement> {
   /** Class to add to outer div */
   className?: string;

packages/react-core/src/components/MultipleFileUpload/MultipleFileUploadStatus.tsx

@@ -6,6 +6,12 @@ import InProgressIcon from '@patternfly/react-icons/dist/esm/icons/in-progress-i
 import CheckCircleIcon from '@patternfly/react-icons/dist/esm/icons/check-circle-icon';
 import TimesCircleIcon from '@patternfly/react-icons/dist/esm/icons/times-circle-icon';
 
+/** Acts as an expandable container for all uploaded file statuses.
+ * An optional text and/or icon can also be passed into this sub-component.
+ * This sub-component can be conditionally rendered when at least 1 file has been
+ * attempted to be uploaded.
+ */
+
 export interface MultipleFileUploadStatusProps extends React.HTMLProps<HTMLDivElement> {
   /** Content rendered inside multi file upload status list */
   children?: React.ReactNode;

packages/react-core/src/components/MultipleFileUpload/MultipleFileUploadStatusItem.tsx

@@ -6,6 +6,11 @@ import { Button } from '../Button';
 import FileIcon from '@patternfly/react-icons/dist/esm/icons/file-icon';
 import TimesCircleIcon from '@patternfly/react-icons/dist/esm/icons/times-circle-icon';
 
+/** Automatically reads an uploaded file to render a visual representation of it, including
+ * its name, size, and read status. This sub-component also allows custom reading of files
+ * via various callbacks which will override the automatic reading behavior.
+ */
+
 export interface MultipleFileUploadStatusItemProps extends React.HTMLProps<HTMLLIElement> {
   /** Class to add to outer div */
   className?: string;

packages/react-core/src/components/MultipleFileUpload/examples/MultipleFileUpload.md

@@ -3,12 +3,7 @@ id: File upload - multiple
 section: components
 cssPrefix: pf-c-multiple-file-upload
 propComponents:
-  [
-    'MultipleFileUpload',
-    'MultipleFileUploadMain',
-    'MultipleFileUploadStatus',
-    'MultipleFileUploadStatusItem',
-  ]
+  ['MultipleFileUpload', 'MultipleFileUploadMain', 'MultipleFileUploadStatus', 'MultipleFileUploadStatusItem']
 beta: true
 ---
 
@@ -31,6 +26,19 @@ As with singular file upload, any [props accepted by react-dropzone's Dropzone c
 
 Restricting file sizes and types in this way is for user convenience only, and it cannot prevent a malicious user from submitting anything to your server. As with any user input, your application should also validate, sanitize and/or reject restricted files on the server side.
 
+## Composable structure
+
+File upload - multiple is designed in a composable manner to make customization easier. The standard sub-component relationships are arranged as follows:
+
+```noLive
+<MultipleFileUpload>
+  <MultipleFileUploadMain />
+  <MultipleFileUploadStatus>
+    <MultipleFileUploadStatusItem />
+  </MultipleFileUploadStatus>
+</MultipleFileUpload>
+```
+
 ## Examples
 
 ### Basic