feat: Add UAP directional controls and tooltips to drag/resize handles (#356)

Co-authored-by: Johannes Weber <[email protected]>

Author: johannes-weber

pages/shared/i18n.ts

@@ -61,6 +61,8 @@ export const boardItemI18nStrings: BoardItemProps.I18nStrings = {
   resizeHandleAriaLabel: "Resize handle",
   resizeHandleAriaDescription:
     "Use Space or Enter to activate resize, arrow keys to move, Space or Enter to submit, or Escape to discard. Be sure to temporarily disable any screen reader navigation feature that may interfere with the functionality of the arrow keys.",
+  dragHandleTooltipText: "Drag or select to move",
+  resizeHandleTooltipText: "Drag or select to resize",
 };
 
 export const itemsPaletteI18nStrings: ItemsPaletteProps.I18nStrings<ItemData> = {

src/__tests__/__snapshots__/documenter.test.ts.snap

@@ -201,7 +201,9 @@ ARIA labels:
 * \`dragHandleAriaLabel\` (string) - the ARIA label for the drag handle.
 * \`dragHandleAriaDescription\` (string, optional) - the ARIA description for the drag handle.
 * \`resizeHandleAriaLabel\` (string) - the ARIA label for the resize handle.
-* \`resizeHandleAriaDescription\` (string, optional) - the ARIA description for the resize handle.",
+* \`resizeHandleAriaDescription\` (string, optional) - the ARIA description for the resize handle.
+* \`dragHandleTooltipText\` (string, optional) - the ARIA description for the resize handle.
+* \`resizeHandleTooltipText\` (string, optional) - the Text for the resize handle Tooltip.",
       "inlineType": {
         "name": "BoardItemProps.I18nStrings",
         "properties": [
@@ -215,6 +217,11 @@ ARIA labels:
             "optional": false,
             "type": "string",
           },
+          {
+            "name": "dragHandleTooltipText",
+            "optional": true,
+            "type": "string",
+          },
           {
             "name": "resizeHandleAriaDescription",
             "optional": true,
@@ -225,6 +232,11 @@ ARIA labels:
             "optional": false,
             "type": "string",
           },
+          {
+            "name": "resizeHandleTooltipText",
+            "optional": true,
+            "type": "string",
+          },
         ],
         "type": "object",
       },

src/board-item/__tests__/board-item-wrapper.tsx

@@ -9,16 +9,19 @@ export function ItemContextWrapper({ children }: { children: ReactNode }) {
     <ItemContext.Provider
       value={{
         isActive: false,
+        isHidden: false,
         dragHandle: {
           ref: { current: null },
           onPointerDown: () => {},
           onKeyDown: () => {},
-          isActive: false,
+          activeState: null,
+          onDirectionClick: () => {},
         },
         resizeHandle: {
           onPointerDown: () => {},
           onKeyDown: () => {},
-          isActive: false,
+          activeState: null,
+          onDirectionClick: () => {},
         },
       }}
     >

src/board-item/__tests__/board-item.test.tsx

@@ -2,13 +2,15 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { ReactElement } from "react";
-import { cleanup, render as libRender } from "@testing-library/react";
+import { cleanup, fireEvent, render as libRender } from "@testing-library/react";
 import { afterEach, describe, expect, test } from "vitest";
 
 import Button from "@cloudscape-design/components/button";
 import Container from "@cloudscape-design/components/container";
 import ExpandableSection from "@cloudscape-design/components/expandable-section";
 import Header from "@cloudscape-design/components/header";
+import DragHandleWrapper from "@cloudscape-design/components/test-utils/dom/internal/drag-handle";
+import TooltipWrapper from "@cloudscape-design/components/test-utils/dom/internal/tooltip";
 
 import "@cloudscape-design/components/test-utils/dom";
 import BoardItem from "../../../lib/components/board-item";
@@ -18,6 +20,8 @@ import { ItemContextWrapper } from "./board-item-wrapper";
 const i18nStrings = {
   dragHandleAriaLabel: "Drag handle",
   resizeHandleAriaLabel: "Resize handle",
+  dragHandleTooltipText: "Drag or select to move",
+  resizeHandleTooltipText: "Drag or select to resize",
 };
 
 function render(jsx: ReactElement) {
@@ -61,4 +65,72 @@ describe("WidgetContainer", () => {
     expect(getByLabelText("Drag handle")).toBeDefined();
     expect(getByLabelText("Resize handle")).toBeDefined();
   });
+
+  test("renders drag handle tooltip text if provided", () => {
+    render(<BoardItem i18nStrings={i18nStrings} />);
+    const wrapper = createWrapper();
+    const dragHandleEl = wrapper.findBoardItem()!.findDragHandle().getElement();
+
+    fireEvent(dragHandleEl, new MouseEvent("pointerover", { bubbles: true }));
+    const tooltipEl = wrapper.findByClassName(TooltipWrapper.rootSelector)!.getElement();
+    expect(tooltipEl.textContent).toBe("Drag or select to move");
+  });
+
+  test("does not render drag handle tooltip text if not provided", () => {
+    render(<BoardItem i18nStrings={{ ...i18nStrings, dragHandleTooltipText: undefined }} />);
+    const wrapper = createWrapper();
+    const dragHandleEl = wrapper.findBoardItem()!.findDragHandle().getElement();
+
+    fireEvent(dragHandleEl, new MouseEvent("pointerover", { bubbles: true }));
+    expect(wrapper.findByClassName(TooltipWrapper.rootSelector)).toBeNull();
+  });
+
+  test("renders drag handle UAP actions on handle click", () => {
+    render(<BoardItem i18nStrings={i18nStrings} />);
+    const dragHandleEl = createWrapper().findBoardItem()!.findDragHandle()!.getElement();
+
+    fireEvent(dragHandleEl, new MouseEvent("pointerdown", { bubbles: true }));
+    fireEvent(dragHandleEl, new MouseEvent("pointerup", { bubbles: true }));
+
+    const dragHandleWrapper = new DragHandleWrapper(document.body);
+    expect(dragHandleWrapper.findAllVisibleDirectionButtons()).toHaveLength(4);
+    expect(dragHandleWrapper.findVisibleDirectionButtonBlockStart()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonBlockEnd()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonInlineStart()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonInlineEnd()).toBeDefined();
+  });
+
+  test("renders resize handle tooltip text", () => {
+    render(<BoardItem i18nStrings={i18nStrings} />);
+    const wrapper = createWrapper();
+    const resizeHandleEl = wrapper.findBoardItem()!.findResizeHandle()!.getElement();
+
+    fireEvent(resizeHandleEl, new MouseEvent("pointerover", { bubbles: true }));
+    const tooltipEl = wrapper.findByClassName(TooltipWrapper.rootSelector)!.getElement();
+    expect(tooltipEl.textContent).toBe("Drag or select to resize");
+  });
+
+  test("does not render resize handle tooltip text if not provided", () => {
+    render(<BoardItem i18nStrings={{ ...i18nStrings, resizeHandleTooltipText: undefined }} />);
+    const wrapper = createWrapper();
+    const resizeHandleEl = wrapper.findBoardItem()!.findResizeHandle()!.getElement();
+
+    fireEvent(resizeHandleEl, new MouseEvent("pointerover", { bubbles: true }));
+    expect(wrapper.findByClassName(TooltipWrapper.rootSelector)).toBeNull();
+  });
+
+  test("renders resize handle UAP actions on handle click", () => {
+    render(<BoardItem i18nStrings={i18nStrings} />);
+    const resizeHandleEl = createWrapper().findBoardItem()!.findResizeHandle()!.getElement();
+
+    fireEvent(resizeHandleEl, new MouseEvent("pointerdown", { bubbles: true }));
+    fireEvent(resizeHandleEl, new MouseEvent("pointerup", { bubbles: true }));
+
+    const dragHandleWrapper = new DragHandleWrapper(document.body);
+    expect(dragHandleWrapper.findAllVisibleDirectionButtons()).toHaveLength(4);
+    expect(dragHandleWrapper.findVisibleDirectionButtonBlockStart()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonBlockEnd()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonInlineStart()).toBeDefined();
+    expect(dragHandleWrapper.findVisibleDirectionButtonInlineEnd()).toBeDefined();
+  });
 });

src/board-item/interfaces.ts

@@ -37,6 +37,8 @@ export interface BoardItemProps {
    * * `dragHandleAriaDescription` (string, optional) - the ARIA description for the drag handle.
    * * `resizeHandleAriaLabel` (string) - the ARIA label for the resize handle.
    * * `resizeHandleAriaDescription` (string, optional) - the ARIA description for the resize handle.
+   * * `dragHandleTooltipText` (string, optional) - the ARIA description for the resize handle.
+   * * `resizeHandleTooltipText` (string, optional) - the Text for the resize handle Tooltip.
    */
   i18nStrings: BoardItemProps.I18nStrings;
 }
@@ -47,5 +49,7 @@ export namespace BoardItemProps {
     dragHandleAriaDescription?: string;
     resizeHandleAriaLabel: string;
     resizeHandleAriaDescription?: string;
+    dragHandleTooltipText?: string;
+    resizeHandleTooltipText?: string;
   }
 }

src/board-item/internal.tsx

@@ -4,10 +4,12 @@ import { useId } from "react";
 import clsx from "clsx";
 
 import Container from "@cloudscape-design/components/container";
+import { InternalDragHandleProps } from "@cloudscape-design/components/internal/do-not-use/drag-handle";
 
 import { getDataAttributes } from "../internal/base-component/get-data-attributes";
 import { InternalBaseComponentProps } from "../internal/base-component/use-base-component";
 import DragHandle from "../internal/drag-handle";
+import { Direction } from "../internal/interfaces";
 import { useItemContext } from "../internal/item-container";
 import ResizeHandle from "../internal/resize-handle";
 import ScreenreaderOnly from "../internal/screenreader-only";
@@ -16,6 +18,16 @@ import type { BoardItemProps } from "./interfaces";
 
 import styles from "./styles.css.js";
 
+const mapToKeyboardDirection = (direction: InternalDragHandleProps.Direction) => {
+  const directionMap: Record<InternalDragHandleProps.Direction, Direction> = {
+    "inline-start": "left",
+    "inline-end": "right",
+    "block-start": "up",
+    "block-end": "down",
+  };
+  return directionMap[direction];
+};
+
 export function InternalBoardItem({
   children,
   header,
@@ -26,14 +38,20 @@ export function InternalBoardItem({
   __internalRootRef,
   ...rest
 }: BoardItemProps & InternalBaseComponentProps) {
-  const { dragHandle, resizeHandle, isActive } = useItemContext();
+  const { dragHandle, resizeHandle, isActive, isHidden } = useItemContext();
 
   const dragHandleAriaLabelledBy = useId();
   const dragHandleAriaDescribedBy = useId();
 
   const resizeHandleAriaLabelledBy = useId();
   const resizeHandleAriaDescribedBy = useId();
 
+  // A board item is hidden while moving a board item from the palette to the board via keyboard or UAP.
+  // The wrapping container is set to invisible, so we don't need to render anything.
+  if (isHidden) {
+    return null;
+  }
+
   return (
     <div ref={__internalRootRef} className={styles.root} {...getDataAttributes(rest)}>
       <Container
@@ -48,7 +66,10 @@ export function InternalBoardItem({
                 ariaDescribedBy={dragHandleAriaDescribedBy}
                 onPointerDown={dragHandle.onPointerDown}
                 onKeyDown={dragHandle.onKeyDown}
-                isActive={dragHandle.isActive}
+                activeState={dragHandle.activeState}
+                initialShowButtons={dragHandle.initialShowButtons}
+                onDirectionClick={(direction) => dragHandle.onDirectionClick(mapToKeyboardDirection(direction), "drag")}
+                dragHandleTooltipText={i18nStrings.dragHandleTooltipText}
               />
             }
             settings={settings}
@@ -69,7 +90,11 @@ export function InternalBoardItem({
             ariaDescribedBy={resizeHandleAriaDescribedBy}
             onPointerDown={resizeHandle.onPointerDown}
             onKeyDown={resizeHandle.onKeyDown}
-            isActive={resizeHandle.isActive}
+            activeState={resizeHandle.activeState}
+            onDirectionClick={(direction) => {
+              resizeHandle.onDirectionClick(mapToKeyboardDirection(direction), "resize");
+            }}
+            resizeHandleTooltipText={i18nStrings.resizeHandleTooltipText}
           />
         </div>
       )}

src/board-item/styles.scss

@@ -13,9 +13,7 @@
 .container-override.active {
   box-shadow: cs.$shadow-container-active;
 
-  :global([data-awsui-focus-visible]) & {
-    @include shared.focus-highlight(0px, cs.$border-radius-container);
-  }
+  @include shared.focus-highlight(0px, cs.$border-radius-container);
 }
 
 .header {