Align positioning behavior of rich-text mention listbox, combobox, select, and menu button

change/@ni-nimble-components-f4992b1c-b7f0-46e1-a684-b5afff8683f6.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Align positioning behavior of rich-text mention listbox, combobox, select, and menu button",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/src/anchored-region/index.ts

@@ -1,7 +1,9 @@
+import { observable } from '@ni/fast-element';
 import {
     DesignSystem,
     AnchoredRegion as FoundationAnchoredRegion,
-    anchoredRegionTemplate as template
+    anchoredRegionTemplate as template,
+    type AnchoredRegionPositionLabel
 } from '@ni/fast-foundation';
 import { styles } from './styles';
 
@@ -22,7 +24,11 @@ declare global {
 /**
  * A nimble-styled anchored region control.
  */
-export class AnchoredRegion extends FoundationAnchoredRegion {}
+export class AnchoredRegion extends FoundationAnchoredRegion {
+    /* @internal */
+    @observable
+    public override verticalPosition: AnchoredRegionPositionLabel | undefined;
+}
 
 const nimbleAnchoredRegion = AnchoredRegion.compose({
     baseName: 'anchored-region',

packages/nimble-components/src/combobox/index.ts

@@ -1,9 +1,16 @@
-import { DOM, Observable, attr, html, observable, ref } from '@ni/fast-element';
+import {
+    attr,
+    DOM,
+    html,
+    observable,
+    Observable,
+    ref,
+    type Notifier
+} from '@ni/fast-element';
 import {
     DesignSystem,
     type ComboboxOptions,
     ComboboxAutocomplete,
-    SelectPosition,
     ListboxOption,
     DelegatesARIACombobox,
     applyMixins,
@@ -28,8 +35,10 @@ import { styles } from './styles';
 import { mixinErrorPattern } from '../patterns/error/types';
 import {
     DropdownAppearance,
+    DropdownPosition,
     type DropdownPattern
 } from '../patterns/dropdown/types';
+import { anchoredRegionPositionToDropdownPosition } from '../patterns/dropdown/utility';
 import type { AnchoredRegion } from '../anchored-region';
 import { template } from './template';
 import { FormAssociatedCombobox } from './models/combobox-form-associated';
@@ -69,7 +78,7 @@ export class Combobox
      * The placement for the listbox when the combobox is open.
      */
     @attr({ attribute: 'position' })
-    public positionAttribute?: SelectPosition;
+    public positionAttribute?: DropdownPosition;
 
     /**
      * The open attribute.
@@ -92,7 +101,7 @@ export class Combobox
      * @public
      */
     @observable
-    public position?: SelectPosition;
+    public position?: DropdownPosition;
 
     /**
      * @internal
@@ -206,11 +215,7 @@ export class Combobox
     private valueBeforeTextUpdate?: string;
     private _value = '';
     private filter = '';
-
-    /**
-     * The initial state of the position attribute.
-     */
-    private forcedPosition = false;
+    private anchoredRegionNotifier?: Notifier;
 
     private get isAutocompleteInline(): boolean {
         return (
@@ -245,11 +250,10 @@ export class Combobox
 
     public override connectedCallback(): void {
         super.connectedCallback();
-        this.forcedPosition = !!this.positionAttribute;
         if (this.value) {
             this.initialValue = this.value;
         }
-        this.setPositioning();
+        this.updateAvailableViewportHeight();
         this.updateInputAriaLabel();
     }
 
@@ -620,35 +624,14 @@ export class Combobox
         }
     }
 
-    /**
-     * @internal
-     */
-    public setPositioning(): void {
-        // Workaround for https://github.com/microsoft/fast/issues/5123
-        if (!this.$fastController.isConnected) {
-            // Don't call setPositioning() until we're connected,
-            // since this.forcedPosition isn't initialized yet.
-            return;
-        }
-        const currentBox = this.getBoundingClientRect();
-        const viewportHeight = window.innerHeight;
-        const availableBottom = viewportHeight - currentBox.bottom;
-
-        if (this.forcedPosition) {
-            this.position = this.positionAttribute;
-        } else if (currentBox.top > availableBottom) {
-            this.position = SelectPosition.above;
-        } else {
-            this.position = SelectPosition.below;
+    /* @internal */
+    public override handleChange(source: unknown, propertyName: string): void {
+        super.handleChange(source, propertyName);
+        if (propertyName === 'verticalPosition') {
+            this.position = anchoredRegionPositionToDropdownPosition(
+                this.region?.verticalPosition
+            );
         }
-
-        this.positionAttribute = this.forcedPosition
-            ? this.positionAttribute
-            : this.position;
-
-        this.availableViewportHeight = this.position === SelectPosition.above
-            ? Math.trunc(currentBox.top)
-            : Math.trunc(availableBottom);
     }
 
     /**
@@ -678,7 +661,7 @@ export class Combobox
             this.ariaControls = this.listboxId;
             this.ariaExpanded = 'true';
 
-            this.setPositioning();
+            this.updateAvailableViewportHeight();
             this.focusAndScrollOptionIntoView();
 
             // focus is directed to the element when `open` is changed programmatically
@@ -729,19 +712,24 @@ export class Combobox
     }
 
     protected positionChanged(
-        _: SelectPosition | undefined,
-        next: SelectPosition | undefined
+        _prev: DropdownPosition | undefined,
+        _next: DropdownPosition | undefined
     ): void {
-        this.positionAttribute = next;
-        this.setPositioning();
+        this.updateAvailableViewportHeight();
     }
 
     private regionChanged(
         _prev: AnchoredRegion | undefined,
         _next: AnchoredRegion | undefined
     ): void {
+        if (this.anchoredRegionNotifier) {
+            this.anchoredRegionNotifier?.unsubscribe(this, 'verticalPosition');
+            this.anchoredRegionNotifier = undefined;
+        }
         if (this.region && this.controlWrapper) {
             this.region.anchorElement = this.controlWrapper;
+            this.anchoredRegionNotifier = Observable.getNotifier(this.region);
+            this.anchoredRegionNotifier.subscribe(this, 'verticalPosition');
         }
     }
 
@@ -759,6 +747,29 @@ export class Combobox
         this.updateInputAriaLabel();
     }
 
+    private updateAvailableViewportHeight(): void {
+        const currentBox = this.getBoundingClientRect();
+        const viewportHeight = document.documentElement.getBoundingClientRect().height;
+        const availableSpaceAbove = Math.trunc(currentBox.top);
+        const availableSpaceBelow = Math.trunc(
+            viewportHeight - currentBox.bottom
+        );
+
+        switch (this.positionAttribute) {
+            case DropdownPosition.above:
+                this.availableViewportHeight = availableSpaceAbove;
+                break;
+            case DropdownPosition.below:
+                this.availableViewportHeight = availableSpaceBelow;
+                break;
+            default:
+                this.availableViewportHeight = Math.max(
+                    availableSpaceAbove,
+                    availableSpaceBelow
+                );
+        }
+    }
+
     /**
      * Sets the value and to match the first selected option.
      */

packages/nimble-components/src/combobox/template.ts

@@ -70,7 +70,7 @@ ComboboxOptions
         </div>
         <${anchoredRegionTag}
             ${ref('region')}
-            class="anchored-region"
+            class="anchored-region confined-to-view"
             fixed-placement
             auto-update-mode="auto"
             vertical-default-position="${x => (x.positionAttribute === DropdownPosition.above ? 'top' : 'bottom')}"

packages/nimble-components/src/combobox/testing/combobox.pageobject.ts

@@ -3,8 +3,8 @@ import type { Combobox } from '..';
 import { listOptionTag } from '../../list-option';
 import { waitForUpdatesAsync } from '../../testing/async-helpers';
 import {
-    waitForEvent,
-    waitAnimationFrame
+    waitAnimationFrame,
+    waitPredicate
 } from '../../utilities/testing/component';
 import { slotTextContent } from '../../utilities/models/slot-text-content';
 
@@ -13,11 +13,6 @@ import { slotTextContent } from '../../utilities/models/slot-text-content';
  * of querying and interacting with the component during tests.
  */
 export class ComboboxPageObject {
-    private readonly regionLoadedListener = waitForEvent(
-        this.comboboxElement,
-        'loaded'
-    );
-
     public constructor(protected readonly comboboxElement: Combobox) {}
 
     /**
@@ -31,7 +26,7 @@ export class ComboboxPageObject {
      * Sets the input text and commits the value by pressing Enter. Will emit a 'change' event.
      */
     public async commitValue(text: string): Promise<void> {
-        await this.waitForAnchoredRegionLoaded();
+        await this.waitForListboxPositioned();
         this.setInputText(text);
         this.pressEnterKey();
     }
@@ -76,7 +71,7 @@ export class ComboboxPageObject {
      */
     public async clickAndWaitForOpen(): Promise<void> {
         this.clickCombobox();
-        await this.waitForAnchoredRegionLoaded();
+        await this.waitForListboxPositioned();
         await waitForUpdatesAsync();
         await waitAnimationFrame(); // necessary because scrolling is queued with requestAnimationFrame
     }
@@ -95,7 +90,7 @@ export class ComboboxPageObject {
      */
     public async clickDropdownButtonAndWaitForOpen(): Promise<void> {
         this.clickDropdownButton();
-        await this.waitForAnchoredRegionLoaded();
+        await this.waitForListboxPositioned();
         await waitAnimationFrame(); // necessary because scrolling is queued with requestAnimationFrame
     }
 
@@ -219,7 +214,14 @@ export class ComboboxPageObject {
         );
     }
 
-    private async waitForAnchoredRegionLoaded(): Promise<void> {
-        await this.regionLoadedListener;
+    /**
+     * @internal
+     */
+    public async waitForListboxPositioned(): Promise<void> {
+        await waitPredicate(
+            () => this.comboboxElement.region?.classList.contains(
+                'horizontal-center'
+            ) === true
+        );
     }
 }

packages/nimble-components/src/combobox/tests/combobox.spec.ts

@@ -508,7 +508,7 @@ describe('Combobox', () => {
         it('should set classes based on open, disabled, and position', async () => {
             const { element, connect, disconnect } = await setup();
             await connect();
-            await waitForUpdatesAsync();
+            await new ComboboxPageObject(element).waitForListboxPositioned();
 
             expect(element.classList.contains('open')).toBeTrue();
             expect(element.classList.contains('disabled')).toBeTrue();

packages/nimble-components/src/patterns/dropdown/styles.ts

@@ -202,12 +202,9 @@ export const styles = css`
         margin-inline-start: auto;
     }
 
-    :host([open][position='above']) .anchored-region {
-        padding-bottom: ${smallPadding};
-    }
-
-    :host([open][position='below']) .anchored-region {
+    :host([open]) .anchored-region {
         padding-top: ${smallPadding};
+        padding-bottom: ${smallPadding};
     }
 
     .listbox {
@@ -219,23 +216,28 @@ export const styles = css`
         --ni-private-listbox-padding: ${smallPadding};
         --ni-private-listbox-filter-height: 0px;
         --ni-private-listbox-loading-indicator-height: 0px;
+        --ni-private-listbox-ideal-height: calc(
+            var(--ni-private-listbox-anchor-element-gap) + 
+            2 * ${borderWidth} + 
+            var(--ni-private-listbox-padding) +
+            ${controlHeight} * var(--ni-private-listbox-visible-option-count) +
+            var(--ni-private-listbox-filter-height) +
+            var(--ni-private-listbox-loading-indicator-height)
+        );
+        max-height: var(--ni-private-listbox-ideal-height);
+        box-shadow: ${elevation2BoxShadow};
+        border: ${borderWidth} solid ${popupBorderColor};
+        background-color: ${applicationBackgroundColor};
+    }
+
+    .anchored-region.confined-to-view .listbox {
         max-height: min(
-            calc(
-                var(--ni-private-listbox-anchor-element-gap) + 
-                2 * ${borderWidth} + 
-                var(--ni-private-listbox-padding) +
-                ${controlHeight} * var(--ni-private-listbox-visible-option-count) +
-                var(--ni-private-listbox-filter-height) +
-                var(--ni-private-listbox-loading-indicator-height)
-            ),
+            var(--ni-private-listbox-ideal-height),
             calc(
                 var(--ni-private-listbox-available-viewport-height) - 
                 var(--ni-private-listbox-anchor-element-gap)
             )
         );
-        box-shadow: ${elevation2BoxShadow};
-        border: ${borderWidth} solid ${popupBorderColor};
-        background-color: ${applicationBackgroundColor};
     }
 
     .listbox:has(.filter-field) {
@@ -246,12 +248,12 @@ export const styles = css`
         --ni-private-listbox-loading-indicator-height: ${controlHeight};
     }
 
-    :host([open][position='above']) .listbox {
+    :host([open]) .listbox.top{
         border-bottom-left-radius: 0;
         border-bottom-right-radius: 0;
     }
 
-    :host([open][position='below']) .listbox {
+    :host([open]) .listbox.bottom{
         border-top-left-radius: 0;
         border-top-right-radius: 0;
     }

packages/nimble-components/src/patterns/dropdown/utility.ts

@@ -0,0 +1,10 @@
+import type { AnchoredRegionPositionLabel } from '@ni/fast-foundation';
+import { DropdownPosition } from './types';
+
+export function anchoredRegionPositionToDropdownPosition(
+    anchoredRegionPosition?: AnchoredRegionPositionLabel
+): DropdownPosition {
+    return anchoredRegionPosition === 'start'
+        ? DropdownPosition.above
+        : DropdownPosition.below;
+}