feat: add focus options support

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

@@ -112,12 +112,18 @@ export class AccordionItem extends LitElement {
 
   // #region Public Methods
 
-  /** Sets focus on the component. */
+  /**
+   * Sets focus on the component.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.headerEl;
-    });
+    }, options);
   }
 
   // #endregion

packages/calcite-components/src/components/action-bar/action-bar.tsx

@@ -172,12 +172,18 @@ export class ActionBar extends LitElement {
     this.resize({ width: this.el.clientWidth, height: this.el.clientHeight });
   }
 
-  /** Sets focus on the component's first focusable element. */
+  /**
+   * Sets focus on the component's first focusable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/action-group/action-group.tsx

@@ -98,12 +98,18 @@ export class ActionGroup extends LitElement {
 
   //#region Public Methods
 
-  /** Sets focus on the component's first focusable element. */
+  /**
+   * Sets focus on the component's first focusable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/action-menu/action-menu.tsx

@@ -180,12 +180,18 @@ export class ActionMenu extends LitElement {
 
   // #region Public Methods
 
-  /** Sets focus on the component. */
+  /**
+   * Sets focus on the component.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.menuButtonEl;
-    });
+    }, options);
   }
 
   // #endregion

packages/calcite-components/src/components/action-pad/action-pad.tsx

@@ -100,12 +100,18 @@ export class ActionPad extends LitElement {
 
   //#region Public Methods
 
-  /** Sets focus on the component's first focusable element. */
+  /**
+   * Sets focus on the component's first focusable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/action/action.e2e.ts

@@ -1,6 +1,17 @@
 import { newE2EPage } from "@arcgis/lumina-compiler/puppeteerTesting";
 import { describe, expect, it } from "vitest";
-import { accessible, disabled, hidden, renders, slots, t9n, defaults, themed, reflects } from "../../tests/commonTests";
+import {
+  accessible,
+  disabled,
+  hidden,
+  renders,
+  slots,
+  t9n,
+  defaults,
+  themed,
+  reflects,
+  focusable,
+} from "../../tests/commonTests";
 import { html } from "../../../support/formatting";
 import { CSS, SLOTS } from "./resources";
 
@@ -111,6 +122,10 @@ describe("calcite-action", () => {
     disabled("calcite-action");
   });
 
+  describe("focusable", () => {
+    focusable("calcite-action");
+  });
+
   describe("slots", () => {
     slots("calcite-action", SLOTS);
   });

packages/calcite-components/src/components/action/action.tsx

@@ -134,12 +134,18 @@ export class Action extends LitElement implements InteractiveComponent {
 
   //#region Public Methods
 
-  /** Sets focus on the component. */
+  /**
+   * Sets focus on the component.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.buttonEl.value;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/alert/alert.tsx

@@ -168,13 +168,17 @@ export class Alert extends LitElement implements OpenCloseComponent {
   /**
    * Sets focus on the component's "close" button, the first focusable item.
    *
-   *     `@returns` {Promise<void>}
+   * `@returns` {Promise<void>}
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
    */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/autocomplete/autocomplete.tsx

@@ -366,7 +366,7 @@ export class Autocomplete
    *   top: 0, // Specifies the number of pixels along the Y axis to scroll the window or element
    *   behavior: "auto" // Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto, the default value).
    * });
-   * @param options - allows specific coordinates to be defined.
+   * @param options
    * @returns - promise that resolves once the content is scrolled to.
    */
   @method()
@@ -387,13 +387,16 @@ export class Autocomplete
   /**
    * Sets focus on the component's first focusable element.
    *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
    * @returns {Promise<void>}
    */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.referenceEl;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/block-group/block-group.tsx

@@ -113,13 +113,16 @@ export class BlockGroup extends LitElement implements InteractiveComponent, Sort
   /**
    * Sets focus on the component's first focusable element.
    *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
    * @returns {Promise<void>}
    */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   // #endregion

packages/calcite-components/src/components/block-section/block-section.tsx

@@ -96,12 +96,18 @@ export class BlockSection extends LitElement {
 
   //#region Public Methods
 
-  /** Sets focus on the component's first tabbable element. */
+  /**
+   * Sets focus on the component's first tabbable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/block/block.tsx

@@ -202,12 +202,18 @@ export class Block extends LitElement implements InteractiveComponent, OpenClose
 
   //#region Public Methods
 
-  /** Sets focus on the component's first tabbable element. */
+  /**
+   * Sets focus on the component's first tabbable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.el;
-    });
+    }, options);
   }
 
   //#endregion

packages/calcite-components/src/components/button/button.e2e.ts

@@ -1,7 +1,17 @@
 // @ts-strict-ignore
 import { newE2EPage, E2EElement } from "@arcgis/lumina-compiler/puppeteerTesting";
 import { describe, expect, it } from "vitest";
-import { accessible, defaults, disabled, hidden, HYDRATED_ATTR, labelable, t9n, themed } from "../../tests/commonTests";
+import {
+  accessible,
+  defaults,
+  disabled,
+  focusable,
+  hidden,
+  HYDRATED_ATTR,
+  labelable,
+  t9n,
+  themed,
+} from "../../tests/commonTests";
 import { GlobalTestProps } from "../../tests/utils/puppeteer";
 import { html } from "../../../support/formatting";
 import { CSS } from "./resources";
@@ -172,6 +182,10 @@ describe("calcite-button", () => {
     disabled("calcite-button");
   });
 
+  describe("focusable", () => {
+    focusable("calcite-button");
+  });
+
   it("should have aria-live attribute set to polite by default", async () => {
     const page = await newE2EPage();
     await page.setContent(`<calcite-button>Continue</calcite-button>`);

packages/calcite-components/src/components/button/button.tsx

@@ -190,10 +190,16 @@ export class Button
 
   //#region Public Methods
 
-  /** Sets focus on the component. */
+  /**
+   * Sets focus on the component.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
-    return this.focusSetter(() => this.childEl);
+  async setFocus(options?: FocusOptions): Promise<void> {
+    return this.focusSetter(() => this.childEl, options);
   }
 
   //#endregion

packages/calcite-components/src/components/card-group/card-group.e2e.ts

@@ -2,7 +2,7 @@
 import { newE2EPage } from "@arcgis/lumina-compiler/puppeteerTesting";
 import { describe, expect, it } from "vitest";
 import { html } from "../../../support/formatting";
-import { accessible, renders, hidden, disabled, themed } from "../../tests/commonTests";
+import { accessible, renders, hidden, disabled, themed, focusable } from "../../tests/commonTests";
 import { createSelectedItemsAsserter } from "../../tests/utils/puppeteer";
 import { CSS } from "./resources";
 
@@ -21,6 +21,18 @@ describe("calcite-card-group", () => {
     disabled("<calcite-card-group><calcite-card></calcite-card></calcite-card-group>", { focusTarget: "none" });
   });
 
+  describe("focusable", () => {
+    focusable(
+      html` <calcite-card-group>
+        <calcite-card label="test-label"><span slot="heading">Heading</span></calcite-card>
+        <calcite-card label="test-label-2"><span slot="heading">Heading</span></calcite-card>
+      </calcite-card-group>`,
+      {
+        focusTargetSelector: "calcite-card:first-of-type",
+      },
+    );
+  });
+
   describe("is accessible in selection mode none (default)", () => {
     accessible(
       html`<calcite-card-group label="test-label-group">
@@ -32,7 +44,7 @@ describe("calcite-card-group", () => {
 
   describe("is accessible in selection mode single", () => {
     accessible(
-      html` <calcite-card-group label="test-label-group" selection-mode="single">
+      html`<calcite-card-group label="test-label-group" selection-mode="single">
         <calcite-card label="test-label"><span slot="heading">Heading</span></calcite-card>
         <calcite-card label="test-label-2"><span slot="heading">Heading</span></calcite-card>
       </calcite-card-group>`,

packages/calcite-components/src/components/card-group/card-group.tsx

@@ -67,12 +67,18 @@ export class CardGroup extends LitElement implements InteractiveComponent {
 
   // #region Public Methods
 
-  /** Sets focus on the component's first focusable element. */
+  /**
+   * Sets focus on the component's first focusable element.
+   *
+   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
+   *
+   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
+   */
   @method()
-  async setFocus(): Promise<void> {
+  async setFocus(options?: FocusOptions): Promise<void> {
     return this.focusSetter(() => {
       return this.items[0];
-    });
+    }, options);
   }
 
   // #endregion