PopoverPrimitive - Add onFocusOut argument (#3571)

dchyun · web-flow · commit 1b6faa74f8e4 · 2026-03-03T10:28:55.000-05:00
diff --git a/.changeset/twenty-rice-retire.md b/.changeset/twenty-rice-retire.md
@@ -0,0 +1,19 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+<!-- START utilities/popover-primitive -->
+`PopoverPrimitive` - Added `@onFocusOut` argument to manage focus for dynamic popover content and prevent the popover from closing when content changes
+<!-- END -->
+
+<!-- START components/dropdown -->
+`Dropdown` - Added `@onFocusOut` argument to manage focus for dynamic dropdown content and prevent the dropdown from closing when content changes
+<!-- END -->
+
+<!-- START components/filter-bar -->
+`FilterBar` - Added `@onFocusOut` argument to the `FiltersDropdown` to help manage focus for dynamic dropdown content and prevent the dropdown from closing when content changes
+<!-- END -->
+
+<!-- START components/rich-tooltip -->
+`RichTooltip` - Added `@onFocusOut` argument to manage focus for dynamic tooltip content and prevent the tooltip from closing when content changes
+<!-- END -->
diff --git a/packages/components/src/components/hds/dropdown/index.hbs b/packages/components/src/components/hds/dropdown/index.hbs
@@ -5,6 +5,7 @@
 <Hds::PopoverPrimitive
   @isOpen={{@isOpen}}
   @onClose={{@onClose}}
+  @onFocusOut={{@onFocusOut}}
   @boundary={{@boundary}}
   @enableClickEvents={{true}}
   as |PP|
diff --git a/packages/components/src/components/hds/dropdown/index.ts b/packages/components/src/components/hds/dropdown/index.ts
@@ -49,6 +49,7 @@ export interface HdsDropdownSignature {
     preserveContentInDom?: boolean;
     matchToggleWidth?: boolean;
     onClose?: HdsPopoverPrimitiveSignature['Args']['onClose'];
+    onFocusOut?: HdsPopoverPrimitiveSignature['Args']['onFocusOut'];
     boundary?: HdsAnchoredPositionOptions['boundary'];
   };
   Blocks: {
diff --git a/packages/components/src/components/hds/filter-bar/actions-dropdown.gts b/packages/components/src/components/hds/filter-bar/actions-dropdown.gts
@@ -20,6 +20,7 @@ export interface HdsFilterBarActionsDropdownSignature {
     | 'height'
     | 'preserveContentInDom'
     | 'onClose'
+    | 'onFocusOut'
   > & {
     toggleButtonText?: HdsDropdownToggleButtonSignature['Args']['text'];
     toggleButtonIcon?: HdsDropdownToggleButtonSignature['Args']['icon'];
@@ -53,6 +54,7 @@ export default class HdsFilterBarActionsDropdown extends Component<HdsFilterBarA
       @height={{@height}}
       @preserveContentInDom={{@preserveContentInDom}}
       @onClose={{@onClose}}
+      @onFocusOut={{@onFocusOut}}
       class="hds-filter-bar__actions-dropdown"
       ...attributes
       as |D|
diff --git a/packages/components/src/components/hds/filter-bar/filters-dropdown.gts b/packages/components/src/components/hds/filter-bar/filters-dropdown.gts
@@ -30,6 +30,7 @@ export interface HdsFilterBarFiltersDropdownSignature {
     isLiveFilter?: boolean;
     height?: string;
     onFilter?: (filters: HdsFilterBarFilters) => void;
+    onFocusOut?: HdsDropdownSignature['Args']['onFocusOut'];
   };
   Blocks: {
     default: [
@@ -138,6 +139,7 @@ export default class HdsFilterBarFiltersDropdown extends Component<HdsFilterBarF
     <HdsDropdown
       @listPosition="bottom-left"
       @width="600px"
+      @onFocusOut={{@onFocusOut}}
       ...attributes
       class="hds-filter-bar__filters-dropdown"
       {{style this.dropdownHeightStyle}}
diff --git a/packages/components/src/components/hds/popover-primitive/index.gts b/packages/components/src/components/hds/popover-primitive/index.gts
@@ -27,6 +27,7 @@ export interface HdsPopoverPrimitiveSignature {
     boundary?: HdsAnchoredPositionOptions['boundary'];
     onOpen?: () => void;
     onClose?: () => void;
+    onFocusOut?: () => void;
   };
   Blocks: {
     default: [
@@ -348,7 +349,12 @@ export default class HdsPopoverPrimitive extends Component<HdsPopoverPrimitiveSi
       }
       // if the target receiving the focus is _not_ part of the disclosed content we close the disclosed container
       if (!isFocusStillInside) {
-        this.hidePopover();
+        const { onFocusOut } = this.args;
+        if (!event.relatedTarget && typeof onFocusOut === 'function') {
+          onFocusOut();
+        } else {
+          this.hidePopover();
+        }
       }
     }
   };
diff --git a/packages/components/src/components/hds/rich-tooltip/index.hbs b/packages/components/src/components/hds/rich-tooltip/index.hbs
@@ -7,6 +7,7 @@
   @isOpen={{@isOpen}}
   @onOpen={{@onOpen}}
   @onClose={{@onClose}}
+  @onFocusOut={{@onFocusOut}}
   @enableSoftEvents={{this.enableSoftEvents}}
   @enableClickEvents={{this.enableClickEvents}}
   as |PP|
diff --git a/showcase/app/components/page-components/filter-bar/code-fragments/with-generic-filters.gts b/showcase/app/components/page-components/filter-bar/code-fragments/with-generic-filters.gts
@@ -208,9 +208,18 @@ export default class CodeFragmentWithGenericContent extends Component<CodeFragme
     }
   }
 
+  onFocusOut = () => {
+    const demoNameInput = document.getElementById(
+      'demo-name-2',
+    ) as HTMLInputElement | null;
+    if (demoNameInput) {
+      demoNameInput.focus();
+    }
+  };
+
   <template>
     <HdsFilterBar @filters={{this.filters}} @onFilter={{this.onFilter}} as |F|>
-      <F.FiltersDropdown as |D|>
+      <F.FiltersDropdown @onFocusOut={{this.onFocusOut}} as |D|>
         <D.FilterGroup
           @key="single"
           @text="Single filter"
@@ -245,6 +254,7 @@ export default class CodeFragmentWithGenericContent extends Component<CodeFragme
               @value={{this.multiFilterName}}
               {{on "input" (fn this.onMultiNameChange G.updateFilter)}}
               name="name-2"
+              id="demo-name-2"
               as |F|
             >
               <F.Label>Name</F.Label>
diff --git a/showcase/app/components/page-utilities/popover-primitive/code-fragments/with-focus-out.gts b/showcase/app/components/page-utilities/popover-primitive/code-fragments/with-focus-out.gts
@@ -0,0 +1,87 @@
+/**
+ * Copyright IBM Corp. 2021, 2025
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { tracked } from '@glimmer/tracking';
+import style from 'ember-style-modifier';
+
+import ShwPlaceholder from 'showcase/components/shw/placeholder';
+
+import { HdsPopoverPrimitive } from '@hashicorp/design-system-components/components';
+import type { HdsAnchoredPositionOptions } from '@hashicorp/design-system-components/modifiers/hds-anchored-position';
+
+export interface CodeFragmentWithFocusOutSignature {
+  Element: HTMLDivElement;
+}
+
+export default class CodeFragmentWithFocusOut extends Component<CodeFragmentWithFocusOutSignature> {
+  @tracked showExtraContent = false;
+
+  private _anchoredPositionOptions: HdsAnchoredPositionOptions = {
+    enableCollisionDetection: false,
+    placement: 'bottom',
+  };
+
+  demoShowContent = () => {
+    this.showExtraContent = true;
+  };
+
+  demoHideContent = () => {
+    this.showExtraContent = false;
+  };
+
+  demoOnFocusOut = () => {
+    console.log('Popover focus out detected');
+    const demoBtn = document.getElementById('demo-btn');
+    demoBtn?.focus();
+  };
+
+  <template>
+    <HdsPopoverPrimitive
+      @enableClickEvents={{true}}
+      @onFocusOut={{this.demoOnFocusOut}}
+      as |PP|
+    >
+      <div
+        class="shw-utilities-popover-primitive-fake-container"
+        {{PP.setupPrimitiveContainer}}
+      >
+        <button
+          type="button"
+          class="shw-utilities-popover-primitive-fake-toggle"
+          {{style marginBottom="150px"}}
+          {{PP.setupPrimitiveToggle}}
+        >Toggle</button>
+        <div
+          class="shw-utilities-popover-primitive-fake-popover"
+          {{PP.setupPrimitivePopover
+            anchoredPositionOptions=this._anchoredPositionOptions
+          }}
+        >
+          <ShwPlaceholder @text="Content" @width="200" @height="40" />
+          <button
+            type="button"
+            id="demo-btn"
+            {{on "click" this.demoShowContent}}
+          >Show extra content</button>
+          {{#if this.showExtraContent}}
+            <div class="shw-utilities-popover-primitive-fake-extra-content">
+              <button
+                type="button"
+                id="demo-btn-2"
+                {{on "click" this.demoHideContent}}
+              >Hide extra content</button>
+              <ShwPlaceholder
+                @text="On click of the button, this content will be removed, and focus will be set back on the previous button. The popover should not close."
+                @height="100"
+                @width="200"
+              />
+            </div>
+          {{/if}}
+        </div>
+      </div>
+    </HdsPopoverPrimitive>
+  </template>
+}
diff --git a/showcase/app/components/page-utilities/popover-primitive/index.gts b/showcase/app/components/page-utilities/popover-primitive/index.gts
@@ -10,6 +10,7 @@ import ShwTextH1 from 'showcase/components/shw/text/h1';
 import SubSectionBase from 'showcase/components/page-utilities/popover-primitive/sub-sections/base';
 import SubSectionInteraction from 'showcase/components/page-utilities/popover-primitive/sub-sections/interaction';
 import SubSectionOptions from 'showcase/components/page-utilities/popover-primitive/sub-sections/options';
+import SubSectionDemos from 'showcase/components/page-utilities/popover-primitive/sub-sections/demos';
 
 const PopoverPrimitiveIndex: TemplateOnlyComponent = <template>
   {{pageTitle "PopoverPrimitive Component"}}
@@ -20,6 +21,7 @@ const PopoverPrimitiveIndex: TemplateOnlyComponent = <template>
     <SubSectionBase />
     <SubSectionOptions />
     <SubSectionInteraction />
+    <SubSectionDemos />
   </section>
 </template>;
 
diff --git a/showcase/app/components/page-utilities/popover-primitive/sub-sections/demos.gts b/showcase/app/components/page-utilities/popover-primitive/sub-sections/demos.gts
@@ -0,0 +1,20 @@
+/**
+ * Copyright IBM Corp. 2021, 2025
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+import ShwTextH2 from 'showcase/components/shw/text/h2';
+import ShwTextH3 from 'showcase/components/shw/text/h3';
+
+import CodeFragmentWithFocusOut from 'showcase/components/page-utilities/popover-primitive/code-fragments/with-focus-out';
+
+const SubSectionBase: TemplateOnlyComponent = <template>
+  <ShwTextH2>Demos</ShwTextH2>
+
+  <ShwTextH3>With onFocusOut</ShwTextH3>
+
+  <CodeFragmentWithFocusOut />
+</template>;
+
+export default SubSectionBase;
diff --git a/showcase/app/components/page-utilities/popover-primitive/sub-sections/interaction.gts b/showcase/app/components/page-utilities/popover-primitive/sub-sections/interaction.gts
@@ -109,6 +109,8 @@ const SubSectionInteraction: TemplateOnlyComponent = <template>
       {{/each}}
     </ShwGrid>
   {{/each}}
+
+  <ShwDivider {{style marginTop="150px"}} />
 </template>;
 
 export default SubSectionInteraction;
diff --git a/showcase/tests/integration/components/hds/dropdown/index-test.gts b/showcase/tests/integration/components/hds/dropdown/index-test.gts
@@ -7,6 +7,7 @@ import { module, test } from 'qunit';
 import { on } from '@ember/modifier';
 import { render, click, find } from '@ember/test-helpers';
 import style from 'ember-style-modifier';
+import { TrackedObject } from 'tracked-built-ins';
 
 import { HdsDropdown } from '@hashicorp/design-system-components/components';
 
@@ -329,4 +330,65 @@ module('Integration | Component | hds/dropdown/index', function (hooks) {
     assert.dom('#test-dropdown ul').hasAttribute('role', 'listbox');
     assert.dom('#test-dropdown ul').hasAttribute('aria-labelledby', buttonId);
   });
+
+  // CALLBACKS
+
+  test('it should invoke the `onClose` callback', async function (assert) {
+    let status;
+    const onClose = () => {
+      status = 'closed';
+    };
+
+    await render(
+      <template>
+        <HdsDropdown @onClose={{onClose}} id="test-dropdown" as |D|>
+          <D.ToggleButton @text="toggle button" id="test-toggle-button" />
+        </HdsDropdown>
+      </template>,
+    );
+    // toggle the visibility
+    await click('button#test-toggle-button');
+    // toggle it again
+    await click('button#test-toggle-button');
+    assert.strictEqual(status, 'closed');
+  });
+
+  test('it should invoke the `onFocusOut` callback', async function (assert) {
+    const context = new TrackedObject({
+      status: '',
+      showButton: true,
+    });
+
+    const onFocusOut = () => {
+      context.status = 'focus-out';
+    };
+
+    const onClickDemoButton = () => {
+      context.showButton = false;
+    };
+
+    await render(
+      <template>
+        <HdsDropdown @onFocusOut={{onFocusOut}} id="test-dropdown" as |D|>
+          <D.ToggleButton @text="toggle button" id="test-toggle-button" />
+          <D.Generic>
+            {{#if context.showButton}}
+              <button
+                type="button"
+                id="test-dropdown-demo-button"
+                {{on "click" onClickDemoButton}}
+              >
+                Hide me
+              </button>
+            {{/if}}
+          </D.Generic>
+        </HdsDropdown>
+      </template>,
+    );
+    // toggle the visibility
+    await click('button#test-toggle-button');
+    // click outside of the dropdown to trigger focus out
+    await click('#test-dropdown-demo-button');
+    assert.strictEqual(context.status, 'focus-out');
+  });
 });
diff --git a/showcase/tests/integration/components/hds/filter-bar/filters-dropdown-test.gts b/showcase/tests/integration/components/hds/filter-bar/filters-dropdown-test.gts
@@ -5,6 +5,7 @@
 
 import { module, test } from 'qunit';
 import { setupRenderingTest } from 'showcase/tests/helpers';
+import { on } from '@ember/modifier';
 import { render, click } from '@ember/test-helpers';
 import { TrackedObject } from 'tracked-built-ins';
 
@@ -187,5 +188,55 @@ module(
       assert.ok(context.isClicked);
       assert.true(Object.keys(context.filters).length === 0);
     });
+
+    // CALLBACKS: ONFOCUSOUT
+
+    test('it should call the onFocusOut callback', async function (assert) {
+      const context = new TrackedObject({
+        status: '',
+        showButton: true,
+      });
+
+      const onFocusOut = () => {
+        context.status = 'focus-out';
+      };
+
+      const onClickDemoButton = () => {
+        context.showButton = false;
+      };
+
+      await render(
+        <template>
+          <HdsFilterBarFiltersDropdown
+            @filters={{EMPTY_FILTERS}}
+            @onFocusOut={{onFocusOut}}
+            id="test-filters-dropdown"
+            as |D|
+          >
+            <D.FilterGroup
+              @key="demo-generic"
+              @type="generic"
+              @text="Generic"
+              as |F|
+            >
+              <F.Generic>
+                {{#if context.showButton}}
+                  <button
+                    type="button"
+                    id="test-filters-dropdown-demo-button"
+                    {{on "click" onClickDemoButton}}
+                  >
+                    Hide me
+                  </button>
+                {{/if}}
+              </F.Generic>
+            </D.FilterGroup>
+          </HdsFilterBarFiltersDropdown>
+        </template>,
+      );
+      await click('.hds-dropdown-toggle-button');
+      await click('#test-filters-dropdown-demo-button');
+      assert.strictEqual(context.status, 'focus-out');
+    });
   },
 );
diff --git a/showcase/tests/integration/components/hds/popover-primitive/index-test.gts b/showcase/tests/integration/components/hds/popover-primitive/index-test.gts
diff --git a/showcase/tests/integration/components/hds/rich-tooltip/index-test.gts b/showcase/tests/integration/components/hds/rich-tooltip/index-test.gts
