pr feedback

Author: kmcfaul

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

@@ -13,6 +13,7 @@ propComponents:
     'DataListItemRow',
     'DataListToggle',
     'DataListContent',
+    'DataListDragButton',
     'DataListControl',
   ]
 ---
@@ -83,6 +84,17 @@ import global_BorderWidth_sm from '@patternfly/react-tokens/dist/esm/global_Bord
 
 ```
 
+### Draggable
+
+Note: There is a new recommended drag and drop implementation that has full keyboard functionality. Examples and details may be located [here](/components/drag-and-drop/react-next).
+
+Draggable data lists used to have their own HTML5-based API for drag and drop, which wasn't able to fulfill requirements such as custom styling on items being dragged. So we wrote generic `DragDrop`, `Draggable`, and `Droppable` components for this purpose. Use those new components instead of the deprecated (and buggy!) HTML5-based API. Keyboard accessibility and screen reader accessibility for the `DragDrop` component are still in development.
+
+```ts isBeta file="./DataListDraggable.tsx"
+
+```
+
+
 ### Small grid breakpoint
 
 ```ts file="./DataListSmGridBreakpoint.tsx"

packages/react-core/src/components/DataList/examples/DataListDraggable.tsx

@@ -0,0 +1,105 @@
+import React from 'react';
+import {
+  DataList,
+  DataListItem,
+  DataListCell,
+  DataListItemRow,
+  DataListCheck,
+  DataListControl,
+  DataListDragButton,
+  DataListItemCells,
+  DragDrop,
+  Draggable,
+  Droppable,
+  getUniqueId
+} from '@patternfly/react-core';
+
+interface ItemType {
+  id: string;
+  content: string;
+}
+
+const getItems = (count: number) =>
+  Array.from({ length: count }, (_, idx) => idx).map((idx) => ({
+    id: `draggable-item-${idx}`,
+    content: `item ${idx} `.repeat(idx === 4 ? 20 : 1)
+  }));
+
+const reorder = (list: ItemType[], startIndex: number, endIndex: number) => {
+  const result = list;
+  const [removed] = result.splice(startIndex, 1);
+  result.splice(endIndex, 0, removed);
+  return result;
+};
+
+export const DataListDraggable: React.FunctionComponent = () => {
+  const [items, setItems] = React.useState(getItems(10));
+  const [liveText, setLiveText] = React.useState('');
+
+  function onDrag(source) {
+    setLiveText(`Started dragging ${items[source.index].content}`);
+    // Return true to allow drag
+    return true;
+  }
+
+  function onDragMove(source, dest) {
+    const newText = dest ? `Move ${items[source.index].content} to ${items[dest.index].content}` : 'Invalid drop zone';
+    if (newText !== liveText) {
+      setLiveText(newText);
+    }
+  }
+
+  function onDrop(source, dest) {
+    if (dest) {
+      const newItems = reorder(items, source.index, dest.index);
+      setItems(newItems);
+
+      setLiveText('Dragging finished.');
+      return true; // Signal that this is a valid drop and not to animate the item returning home.
+    } else {
+      setLiveText('Dragging cancelled. List unchanged.');
+    }
+  }
+
+  const uniqueId = getUniqueId();
+
+  return (
+    <DragDrop onDrag={onDrag} onDragMove={onDragMove} onDrop={onDrop}>
+      <Droppable hasNoWrapper>
+        <DataList aria-label="draggable data list example" isCompact>
+          {items.map(({ id, content }) => (
+            <Draggable key={id} hasNoWrapper>
+              <DataListItem aria-labelledby={`draggable-${id}`} ref={React.createRef()}>
+                <DataListItemRow>
+                  <DataListControl>
+                    <DataListDragButton
+                      aria-label="Reorder"
+                      aria-labelledby={`draggable-${id}`}
+                      aria-describedby={`description-${uniqueId}`}
+                      aria-pressed="false"
+                    />
+                    <DataListCheck aria-labelledby={`draggable-${id}`} name={id} otherControls />
+                  </DataListControl>
+                  <DataListItemCells
+                    dataListCells={[
+                      <DataListCell key={id}>
+                        <span id={`draggable-${id}`}>{content}</span>
+                      </DataListCell>
+                    ]}
+                  />
+                </DataListItemRow>
+              </DataListItem>
+            </Draggable>
+          ))}
+        </DataList>
+      </Droppable>
+      <div className="pf-v5-screen-reader" aria-live="assertive">
+        {liveText}
+      </div>
+      <div className="pf-v5-screen-reader" id={`description-${uniqueId}`}>
+        Press space or enter to begin dragging, and use the arrow keys to navigate up or down. Press enter to confirm
+        the drag, or any other key to cancel the drag operation.
+      </div>
+    </DragDrop>
+  );
+};

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

@@ -85,6 +85,28 @@ The dual list selector can also be built in a composable manner to make customiz
 
 ```
 
+### Composable with drag and drop
+
+Note: There is a new recommended drag and drop implementation that has full keyboard functionality. Examples and details may be located [here](/components/drag-and-drop/react-next).
+
+This example only allows reordering the contents of the "chosen" pane with drag and drop. To make a pane able to be reordered:
+
+- wrap the `DualListSelectorPane` in a `DragDrop` component
+- wrap the `DualListSelectorList` in a `Droppable` component
+- wrap the `DualListSelectorListItem` components in a `Draggable` component
+- define an `onDrop` callback which reorders the sortable options.
+  - The `onDrop` function provides the starting location and destination location for a dragged item. It should return
+    true to enable the 'drop' animation in the new location and false to enable the 'drop' animation back to the item's
+    old position.
+  - define an `onDrag` callback which ensures that the drag event will not cross hairs with the `onOptionSelect` click
+    event set on the option. Note: the `ignoreNextOptionSelect` state value is used to prevent selection while dragging.
+
+Keyboard accessibility and screen reader accessibility for the `DragDrop` component are still in development.
+
+```ts file="DualListSelectorComposableDragDrop.tsx"
+
+```
+
 ### Composable with tree
 
 ```ts file="DualListSelectorComposableTree.tsx"

packages/react-drag-drop/src/components/DragDrop/DragDropSort.tsx

@@ -27,6 +27,9 @@ import styles from '@patternfly/react-styles/css/components/DragDrop/drag-drop';
 export type DragDropSortDragEndEvent = DragEndEvent;
 export type DragDropSortDragStartEvent = DragStartEvent;
 
+/**
+ * DragDropSortProps extends dnd-kit's props which may be viewed at https://docs.dndkit.com/api-documentation/context-provider#props.
+ */
 export interface DragDropSortProps extends DndContextProps {
   /** Custom defined content wrapper for draggable items. By default, draggable items are wrapped in a styled div.
    * Intended to be a 'DataList' or 'DualListSelectorList' without children. */

packages/react-drag-drop/src/components/DragDrop/Draggable.tsx

@@ -12,9 +12,9 @@ export interface DraggableProps extends React.HTMLProps<HTMLDivElement> {
   hasNoWrapper?: boolean;
   /** Class to add to outer div */
   className?: string;
-  /** */
+  /** @hide Id of the sortable context. */
   id?: string;
-  /** */
+  /** Flag indicating the draggable element should include a drag button. */
   useDragButton?: boolean;
 }
 

packages/react-drag-drop/src/components/DragDrop/DraggableDataListItem.tsx

@@ -19,7 +19,7 @@ export interface DraggableDataListItemProps extends React.HTMLProps<HTMLLIElemen
   hasNoWrapper?: boolean;
   /** Class to add to outer div */
   className?: string;
-  /** */
+  /** @hide Id of the sortable context. */
   id?: string;
 }
 

packages/react-drag-drop/src/components/DragDrop/DraggableDualListSelectorListItem.tsx

@@ -14,7 +14,7 @@ export interface DraggableDualListSelectorListItemProps extends React.HTMLProps<
   hasNoWrapper?: boolean;
   /** Class to add to outer div */
   className?: string;
-  /** */
+  /** @hide Id of the sortable context */
   id?: string;
   /** Flag indicating the list item is currently selected. */
   isSelected?: boolean;

packages/react-drag-drop/src/components/DragDrop/examples/DragDrop.md

@@ -7,7 +7,7 @@ hideNavItem: true
 beta: true
 ---
 
-Note: DragDrop lives in its own package at @patternfly/react-drag-drop!'
+Note: This drag and drop implementation lives in its own package at [@patternfly/react-drag-drop](https://www.npmjs.com/package/@patternfly/react-drag-drop)!
 
 import AngleDoubleLeftIcon from '@patternfly/react-icons/dist/esm/icons/angle-double-left-icon';
 import AngleLeftIcon from '@patternfly/react-icons/dist/esm/icons/angle-left-icon';