feat: Add UAP directional controls and tooltips to drag/resize handles

This commit enhances the accessibility of board items by adding UAP (Universally Accessible Post-click/tap actions) controls and tooltips to drag and resize handles. UAPs allows drag/resize movements to be operated by a single pointer without dragging.

As part of that change: Show blue border around items when they are active: Before this change, the "active" borders have been shown only when interacting with keyboard. Now they will be shown on pointer interactions (drag or resize) as well.

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,10 @@ 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.
+* \`dragHandleTooltipText\` (string, optional) - the Text for the drag handle Tooltip.
+* \`resizeHandleTooltipText\` (string, optional) - the Text for the resize handle Tooltip.",
       "inlineType": {
         "name": "BoardItemProps.I18nStrings",
         "properties": [
@@ -215,6 +218,11 @@ ARIA labels:
             "optional": false,
             "type": "string",
           },
+          {
+            "name": "dragHandleTooltipText",
+            "optional": true,
+            "type": "string",
+          },
           {
             "name": "resizeHandleAriaDescription",
             "optional": true,
@@ -225,6 +233,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,21 @@ export function ItemContextWrapper({ children }: { children: ReactNode }) {
     <ItemContext.Provider
       value={{
         isActive: false,
+        isHidden: false,
         dragHandle: {
           ref: { current: null },
           onPointerDown: () => {},
           onKeyDown: () => {},
-          isActive: false,
+          isActivePointer: false,
+          isActiveUap: false,
+          onDirectionClick: () => {},
         },
         resizeHandle: {
           onPointerDown: () => {},
           onKeyDown: () => {},
-          isActive: false,
+          isActivePointer: false,
+          isActiveUap: false,
+          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,9 @@ 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.
+   * * `dragHandleTooltipText` (string, optional) - the Text for the drag handle Tooltip.
+   * * `resizeHandleTooltipText` (string, optional) - the Text for the resize handle Tooltip.
    */
   i18nStrings: BoardItemProps.I18nStrings;
 }
@@ -47,5 +50,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,7 +38,7 @@ export function InternalBoardItem({
   __internalRootRef,
   ...rest
 }: BoardItemProps & InternalBaseComponentProps) {
-  const { dragHandle, resizeHandle, isActive } = useItemContext();
+  const { dragHandle, resizeHandle, isActive, isHidden } = useItemContext();
 
   const dragHandleAriaLabelledBy = useId();
   const dragHandleAriaDescribedBy = useId();
@@ -42,14 +54,24 @@ export function InternalBoardItem({
         header={
           <WidgetContainerHeader
             handle={
-              <DragHandle
-                ref={dragHandle.ref}
-                ariaLabelledBy={dragHandleAriaLabelledBy}
-                ariaDescribedBy={dragHandleAriaDescribedBy}
-                onPointerDown={dragHandle.onPointerDown}
-                onKeyDown={dragHandle.onKeyDown}
-                isActive={dragHandle.isActive}
-              />
+              <>
+                {!isHidden && (
+                  <DragHandle
+                    ref={dragHandle.ref}
+                    ariaLabelledBy={dragHandleAriaLabelledBy}
+                    ariaDescribedBy={dragHandleAriaDescribedBy}
+                    onPointerDown={dragHandle.onPointerDown}
+                    onKeyDown={dragHandle.onKeyDown}
+                    isActivePointer={dragHandle.isActivePointer}
+                    isActiveUap={dragHandle.isActiveUap}
+                    initialShowButtons={dragHandle.initialShowButtons}
+                    onDirectionClick={(direction) =>
+                      dragHandle.onDirectionClick(mapToKeyboardDirection(direction), "drag")
+                    }
+                    dragHandleTooltipText={i18nStrings.dragHandleTooltipText}
+                  />
+                )}
+              </>
             }
             settings={settings}
           >
@@ -62,14 +84,19 @@ export function InternalBoardItem({
       >
         {children}
       </Container>
-      {resizeHandle && (
+      {resizeHandle && !isHidden && (
         <div className={styles.resizer}>
           <ResizeHandle
             ariaLabelledBy={resizeHandleAriaLabelledBy}
             ariaDescribedBy={resizeHandleAriaDescribedBy}
             onPointerDown={resizeHandle.onPointerDown}
             onKeyDown={resizeHandle.onKeyDown}
-            isActive={resizeHandle.isActive}
+            isActivePointer={resizeHandle.isActivePointer}
+            isActiveUap={resizeHandle.isActiveUap}
+            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 {