feat(list-item): Add dragSelected property and calciteListItemDragHandleChange event (#8524)

**Related Issue:** #8523

## Summary

- Depends on #8484
- Add dragSelected property 
- Add calciteListItemDragHandleChange event
- Add test

Author: driskull

packages/calcite-components/src/components.d.ts

@@ -313,7 +313,7 @@ export namespace Components {
     }
     interface CalciteActionBar {
         /**
-          * Specifies the accessible label for the last action-group.
+          * Specifies the accessible label for the last `calcite-action-group`.
          */
         "actionsEndGroupLabel": string;
         /**
@@ -325,7 +325,7 @@ export namespace Components {
          */
         "expanded": boolean;
         /**
-          * The layout direction of the actions.
+          * Specifies the layout direction of the actions.
          */
         "layout": Extract<"horizontal" | "vertical", Layout>;
         /**
@@ -367,7 +367,7 @@ export namespace Components {
          */
         "expanded": boolean;
         /**
-          * Specifies the label of the component. Required for accessibility.
+          * Accessible name for the component.
          */
         "label": string;
         /**
@@ -440,7 +440,7 @@ export namespace Components {
     }
     interface CalciteActionPad {
         /**
-          * Specifies the accessible label for the last action-group.
+          * Specifies the accessible label for the last `calcite-action-group`.
          */
         "actionsEndGroupLabel": string;
         /**
@@ -478,11 +478,11 @@ export namespace Components {
     }
     interface CalciteAlert {
         /**
-          * When `true`, the component closes automatically (recommended for passive, non-blocking alerts).
+          * When `true`, the component closes automatically. Recommended for passive, non-blocking alerts.
          */
         "autoClose": boolean;
         /**
-          * Specifies the duration before the component automatically closes (only use with `autoClose`).
+          * Specifies the duration before the component automatically closes - only use with `autoClose`.
          */
         "autoCloseDuration": AlertDuration;
         /**
@@ -494,7 +494,7 @@ export namespace Components {
          */
         "iconFlipRtl": boolean;
         /**
-          * Specifies the kind of the component (will apply to top border and icon).
+          * Specifies the kind of the component, which will apply to top border and icon.
          */
         "kind": Extract<
     "brand" | "danger" | "info" | "success" | "warning",
@@ -521,15 +521,15 @@ export namespace Components {
          */
         "open": boolean;
         /**
-          * Specifies the placement of the component
+          * Specifies the placement of the component.
          */
         "placement": MenuPlacement;
         /**
           * Specifies the size of the component.
          */
         "scale": Scale;
         /**
-          * Sets focus on the component's "close" button (the first focusable item).
+          * Sets focus on the component's "close" button, the first focusable item.
          */
         "setFocus": () => Promise<void>;
         /**
@@ -1768,10 +1768,6 @@ export namespace Components {
         "min": number;
     }
     interface CalciteHandle {
-        /**
-          * When `true`, disables unselecting the component when blurred.
-         */
-        "blurUnselectDisabled": boolean;
         /**
           * When `true`, disables unselecting the component when blurred.
          */
@@ -2845,6 +2841,10 @@ export namespace Components {
           * When `true`, the component displays a draggable button.
          */
         "dragHandle": boolean;
+        /**
+          * When `true`, the component's drag handle is selected.
+         */
+        "dragSelected": boolean;
         /**
           * The label text of the component. Displays above the description text.
          */
@@ -6379,6 +6379,7 @@ declare global {
     interface HTMLCalciteListItemElementEventMap {
         "calciteListItemSelect": void;
         "calciteListItemClose": void;
+        "calciteListItemDragHandleChange": void;
         "calciteListItemToggle": void;
         "calciteInternalListItemSelect": void;
         "calciteInternalListItemSelectMultiple": {
@@ -7525,7 +7526,7 @@ declare namespace LocalJSX {
     }
     interface CalciteActionBar {
         /**
-          * Specifies the accessible label for the last action-group.
+          * Specifies the accessible label for the last `calcite-action-group`.
          */
         "actionsEndGroupLabel"?: string;
         /**
@@ -7537,7 +7538,7 @@ declare namespace LocalJSX {
          */
         "expanded"?: boolean;
         /**
-          * The layout direction of the actions.
+          * Specifies the layout direction of the actions.
          */
         "layout"?: Extract<"horizontal" | "vertical", Layout>;
         /**
@@ -7575,7 +7576,7 @@ declare namespace LocalJSX {
          */
         "expanded"?: boolean;
         /**
-          * Specifies the label of the component. Required for accessibility.
+          * Accessible name for the component.
          */
         "label"?: string;
         /**
@@ -7644,7 +7645,7 @@ declare namespace LocalJSX {
     }
     interface CalciteActionPad {
         /**
-          * Specifies the accessible label for the last action-group.
+          * Specifies the accessible label for the last `calcite-action-group`.
          */
         "actionsEndGroupLabel"?: string;
         /**
@@ -7682,11 +7683,11 @@ declare namespace LocalJSX {
     }
     interface CalciteAlert {
         /**
-          * When `true`, the component closes automatically (recommended for passive, non-blocking alerts).
+          * When `true`, the component closes automatically. Recommended for passive, non-blocking alerts.
          */
         "autoClose"?: boolean;
         /**
-          * Specifies the duration before the component automatically closes (only use with `autoClose`).
+          * Specifies the duration before the component automatically closes - only use with `autoClose`.
          */
         "autoCloseDuration"?: AlertDuration;
         /**
@@ -7698,7 +7699,7 @@ declare namespace LocalJSX {
          */
         "iconFlipRtl"?: boolean;
         /**
-          * Specifies the kind of the component (will apply to top border and icon).
+          * Specifies the kind of the component, which will apply to top border and icon.
          */
         "kind"?: Extract<
     "brand" | "danger" | "info" | "success" | "warning",
@@ -7749,7 +7750,7 @@ declare namespace LocalJSX {
          */
         "open"?: boolean;
         /**
-          * Specifies the placement of the component
+          * Specifies the placement of the component.
          */
         "placement"?: MenuPlacement;
         /**
@@ -9074,10 +9075,6 @@ declare namespace LocalJSX {
         "min": number;
     }
     interface CalciteHandle {
-        /**
-          * When `true`, disables unselecting the component when blurred.
-         */
-        "blurUnselectDisabled"?: boolean;
         /**
           * When `true`, disables unselecting the component when blurred.
          */
@@ -10217,6 +10214,10 @@ declare namespace LocalJSX {
           * When `true`, the component displays a draggable button.
          */
         "dragHandle"?: boolean;
+        /**
+          * When `true`, the component's drag handle is selected.
+         */
+        "dragSelected"?: boolean;
         /**
           * The label text of the component. Displays above the description text.
          */
@@ -10244,6 +10245,10 @@ declare namespace LocalJSX {
           * Fires when the close button is clicked.
          */
         "onCalciteListItemClose"?: (event: CalciteListItemCustomEvent<void>) => void;
+        /**
+          * Fires when the drag handle is selected.
+         */
+        "onCalciteListItemDragHandleChange"?: (event: CalciteListItemCustomEvent<void>) => void;
         /**
           * Emits when the item's content is selected.
          */

packages/calcite-components/src/components/list-item/list-item.e2e.ts

@@ -48,6 +48,10 @@ describe("calcite-list-item", () => {
         propertyName: "dragHandle",
         defaultValue: false,
       },
+      {
+        propertyName: "dragSelected",
+        defaultValue: false,
+      },
     ]);
   });
 
@@ -300,4 +304,29 @@ describe("calcite-list-item", () => {
     expect(await listItem.getProperty("open")).toBe(false);
     expect(calciteListItemToggle).toHaveReceivedEventTimes(2);
   });
+
+  it("should fire calciteListItemDragHandleChange event when drag handle is clicked", async () => {
+    const page = await newE2EPage({
+      html: html`<calcite-list-item drag-handle></calcite-list-item>`,
+    });
+
+    const listItem = await page.find("calcite-list-item");
+    const calciteListItemDragHandleChange = await page.spyOnEvent("calciteListItemDragHandleChange", "window");
+
+    expect(await listItem.getProperty("dragSelected")).toBe(false);
+
+    const dragHandle = await page.find(`calcite-list-item >>> calcite-handle`);
+    await dragHandle.callMethod("setFocus");
+    await page.waitForChanges();
+
+    await dragHandle.press("Space");
+    await page.waitForChanges();
+    expect(await listItem.getProperty("dragSelected")).toBe(true);
+    expect(calciteListItemDragHandleChange).toHaveReceivedEventTimes(1);
+
+    await dragHandle.press("Space");
+    await page.waitForChanges();
+    expect(await listItem.getProperty("dragSelected")).toBe(false);
+    expect(calciteListItemDragHandleChange).toHaveReceivedEventTimes(2);
+  });
 });

packages/calcite-components/src/components/list-item/list-item.tsx

@@ -137,6 +137,11 @@ export class ListItem
    */
   @Prop() dragHandle = false;
 
+  /**
+   * When `true`, the component's drag handle is selected.
+   */
+  @Prop({ mutable: true, reflect: true }) dragSelected = false;
+
   /**
    * The label text of the component. Displays above the description text.
    */
@@ -233,6 +238,11 @@ export class ListItem
    */
   @Event({ cancelable: false }) calciteListItemClose: EventEmitter<void>;
 
+  /**
+   * Fires when the drag handle is selected.
+   */
+  @Event({ cancelable: false }) calciteListItemDragHandleChange: EventEmitter<void>;
+
   /**
    * Fires when the open button is clicked.
    */
@@ -429,7 +439,7 @@ export class ListItem
   }
 
   renderDragHandle(): VNode {
-    const { label, dragHandle, dragDisabled, setPosition, setSize } = this;
+    const { label, dragHandle, dragSelected, dragDisabled, setPosition, setSize } = this;
 
     return dragHandle ? (
       <td
@@ -444,6 +454,8 @@ export class ListItem
         <calcite-handle
           disabled={dragDisabled}
           label={label}
+          onCalciteHandleChange={this.dragHandleSelectedChangeHandler}
+          selected={dragSelected}
           setPosition={setPosition}
           setSize={setSize}
         />
@@ -690,6 +702,12 @@ export class ListItem
   //
   // --------------------------------------------------------------------------
 
+  private dragHandleSelectedChangeHandler = (event: CustomEvent): void => {
+    this.dragSelected = (event.target as HTMLCalciteHandleElement).selected;
+    this.calciteListItemDragHandleChange.emit();
+    event.stopPropagation();
+  };
+
   private emitInternalListItemActive = (): void => {
     this.calciteInternalListItemActive.emit();
   };