Select list option groups

change/@ni-nimble-components-278f4b89-b1f8-402d-a3e7-ba0338b1b348.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "List option groups for Select",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/src/all-components.ts

@@ -25,6 +25,7 @@ import './icons/all-icons';
 import './label-provider/core';
 import './label-provider/table';
 import './list-option';
+import './list-option-group';
 import './mapping/empty';
 import './mapping/icon';
 import './mapping/spinner';

packages/nimble-components/src/list-option-group/index.ts

@@ -0,0 +1,100 @@
+import { DesignSystem, FoundationElement } from '@microsoft/fast-foundation';
+import { observable, attr, volatile } from '@microsoft/fast-element';
+import { styles } from './styles';
+import { template } from './template';
+import { ListOption } from '../list-option';
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-list-option-group': ListOptionGroup;
+    }
+}
+
+/**
+ * A nimble-styled HTML listbox option
+ */
+export class ListOptionGroup extends FoundationElement {
+    /**
+     * The label for the group.
+     *
+     * @public
+     * @remarks
+     * If a label is also provided via slotted content, the label attribute
+     * will have precedence.
+     */
+    @attr
+    public label?: string;
+
+    /**
+     * The hidden state of the element.
+     *
+     * @public
+     * @defaultValue - false
+     * @remarks
+     * HTML Attribute: hidden
+     */
+    @attr({ mode: 'boolean' })
+    public override hidden = false;
+
+    /**
+     * @internal
+     * This attribute is required to allow use-cases that offer dynamic filtering
+     * (like the Select) to visually hide groups that are filtered out, but still
+     * allow users to use the native 'hidden' attribute without it being affected
+     * by the filtering process.
+     */
+    @attr({ attribute: 'visually-hidden', mode: 'boolean' })
+    public visuallyHidden = false;
+
+    /** @internal */
+    @observable
+    public hasOverflow = false;
+
+    /** @internal */
+    public labelSlot!: HTMLSlotElement;
+
+    /** @internal */
+    @observable
+    public slottedElements: Element[] = [];
+
+    /** @internal */
+    @volatile
+    public get labelContent(): string {
+        if (this.label || !this.$fastController.isConnected) {
+            return this.label ?? '';
+        }
+
+        const nodes = this.labelSlot.assignedNodes();
+        return nodes.length > 0
+            ? nodes.map(node => node.textContent?.trim()).join(' ')
+            : '';
+    }
+
+    /**
+     * @internal
+     */
+    public clickHandler(e: MouseEvent): void {
+        e.preventDefault();
+        e.stopImmediatePropagation();
+    }
+
+    protected slottedElementsChanged(): void {
+        this.slottedElements.forEach(e => {
+            if (e instanceof ListOption) {
+                e.slot = 'options-slot';
+            }
+        });
+    }
+}
+
+const nimbleListOptionGroup = ListOptionGroup.compose({
+    baseName: 'list-option-group',
+    baseClass: FoundationElement,
+    template,
+    styles
+});
+
+DesignSystem.getOrCreate()
+    .withPrefix('nimble')
+    .register(nimbleListOptionGroup());
+export const listOptionGroupTag = 'nimble-list-option-group';

packages/nimble-components/src/list-option-group/styles.ts

@@ -0,0 +1,38 @@
+import { css } from '@microsoft/fast-element';
+import { display } from '@microsoft/fast-foundation';
+
+import {
+    groupHeaderFont,
+    groupHeaderFontColor,
+    groupHeaderTextTransform,
+    smallPadding
+} from '../theme-provider/design-tokens';
+
+export const styles = css`
+    ${display('flex')}
+
+    :host {
+        cursor: default;
+        justify-content: left;
+        flex-direction: column;
+    }
+
+    :host([visually-hidden]) {
+        display: none;
+    }
+
+    .header {
+        font: ${groupHeaderFont};
+        text-transform: ${groupHeaderTextTransform};
+        color: ${groupHeaderFontColor};
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        margin-left: ${smallPadding};
+        margin-bottom: ${smallPadding};
+    }
+
+    .label-slot {
+        display: none;
+    }
+`;

packages/nimble-components/src/list-option-group/template.ts

@@ -0,0 +1,38 @@
+import { html, ref, slotted } from '@microsoft/fast-element';
+import { isListboxOption } from '@microsoft/fast-foundation';
+import type { ListOptionGroup } from '.';
+import { overflow } from '../utilities/directive/overflow';
+
+const slottedContentFilter = (n: Node): boolean => {
+    const allowed = n instanceof HTMLElement && (isListboxOption(n) || n instanceof Text);
+    return allowed;
+};
+
+// prettier-ignore
+export const template = html<ListOptionGroup>`
+<template
+    role="group"
+    aria-label="${x => x.labelContent}"
+>
+    <span ${overflow('hasOverflow')}
+        class="header"
+        aria-hidden="true"
+        title=${x => (x.hasOverflow && x.labelContent ? x.labelContent : null)}
+        @click="${(x, c) => x.clickHandler(c.event as MouseEvent)}"
+    >
+        ${x => x.labelContent}
+        <slot ${ref('labelSlot')}
+            class="label-slot"
+            ${slotted({
+        filter: (n: Node) => slottedContentFilter(n),
+        flatten: true,
+        property: 'slottedElements',
+    })}
+        >
+        </slot>
+    </span>
+    <span class="content" part="content" role="none">
+        <slot name="options-slot"></slot>
+    </span>
+</template>
+`;

packages/nimble-components/src/list-option-group/tests/list-option-group.spec.ts

@@ -0,0 +1,132 @@
+import { html } from '@microsoft/fast-element';
+import { ListOptionGroup, listOptionGroupTag } from '..';
+import { fixture, type Fixture } from '../../utilities/tests/fixture';
+import { waitForUpdatesAsync } from '../../testing/async-helpers';
+
+describe('ListboxOptionGroup', () => {
+    async function setup(): Promise<Fixture<ListOptionGroup>> {
+        return fixture<ListOptionGroup>(
+            html`<nimble-list-option-group style="width: 200px" label="Group 1">
+            </nimble-list-option-group>`
+        );
+    }
+
+    const getGroupLabelDisplay = (element: ListOptionGroup): string => {
+        return (
+            element.shadowRoot!.querySelector('.header')!.textContent?.trim()
+            ?? ''
+        );
+    };
+
+    it('should export its tag', () => {
+        expect(listOptionGroupTag).toBe('nimble-list-option-group');
+    });
+
+    it('can construct an element instance', () => {
+        expect(
+            document.createElement('nimble-list-option-group')
+        ).toBeInstanceOf(ListOptionGroup);
+    });
+
+    it('if label attribute and slotted label are provided, label attribute is displayed', async () => {
+        const { element, connect, disconnect } = await setup();
+        await connect();
+        const slottedLabel = document.createElement('span');
+        slottedLabel.textContent = 'Slotted Label';
+        element.appendChild(slottedLabel);
+        await waitForUpdatesAsync();
+
+        expect(getGroupLabelDisplay(element)).toBe('Group 1');
+
+        await disconnect();
+    });
+
+    it('if label attribute is not provided, slotted label is displayed', async () => {
+        const { element, connect, disconnect } = await setup();
+        await connect();
+        const slottedLabel = document.createElement('span');
+        slottedLabel.textContent = 'Slotted Label';
+        element.label = undefined;
+        element.appendChild(slottedLabel);
+        await waitForUpdatesAsync();
+
+        expect(getGroupLabelDisplay(element)).toBe('Slotted Label');
+        await disconnect();
+    });
+
+    it('if multiple slotted labels are provided, all are appended to the labelContent', async () => {
+        const { element, connect, disconnect } = await setup();
+        await connect();
+        element.label = undefined;
+        const slottedLabel1 = document.createElement('span');
+        slottedLabel1.textContent = 'Slotted Label 1';
+        element.appendChild(slottedLabel1);
+        const slottedLabel2 = document.createElement('span');
+        slottedLabel2.textContent = 'Slotted Label 2';
+        element.appendChild(slottedLabel2);
+        await waitForUpdatesAsync();
+
+        expect(getGroupLabelDisplay(element)).toBe(
+            'Slotted Label 1 Slotted Label 2'
+        );
+        await disconnect();
+    });
+
+    describe('title overflow', () => {
+        let element: ListOptionGroup;
+        let connect: () => Promise<void>;
+        let disconnect: () => Promise<void>;
+
+        function dispatchEventToListOptionGroup(
+            event: Event
+        ): boolean | undefined {
+            return element
+                .shadowRoot!.querySelector('.header')!
+                .dispatchEvent(event);
+        }
+
+        function getListOptionGroupTitle(): string {
+            return (
+                element
+                    .shadowRoot!.querySelector('.header')!
+                    .getAttribute('title') ?? ''
+            );
+        }
+
+        beforeEach(async () => {
+            ({ element, connect, disconnect } = await setup());
+            await connect();
+        });
+
+        afterEach(async () => {
+            await disconnect();
+        });
+
+        it('sets title when option text is ellipsized', async () => {
+            const optionContent = 'a very long value that should get ellipsized due to not fitting within the allocated width';
+            element.label = optionContent;
+            await waitForUpdatesAsync();
+            dispatchEventToListOptionGroup(new MouseEvent('mouseover'));
+            await waitForUpdatesAsync();
+            expect(getListOptionGroupTitle()).toBe(optionContent);
+        });
+
+        it('does not set title when option text is fully visible', async () => {
+            const optionContent = 'short value';
+            element.label = optionContent;
+            dispatchEventToListOptionGroup(new MouseEvent('mouseover'));
+            await waitForUpdatesAsync();
+            expect(getListOptionGroupTitle()).toBe('');
+        });
+
+        it('removes title on mouseout of option', async () => {
+            const optionContent = 'a very long value that should get ellipsized due to not fitting within the allocated width';
+            element.label = optionContent;
+            dispatchEventToListOptionGroup(new MouseEvent('mouseover'));
+            await waitForUpdatesAsync();
+            dispatchEventToListOptionGroup(new MouseEvent('mouseout'));
+            await waitForUpdatesAsync();
+            expect(getListOptionGroupTitle()).toBe('');
+        });
+    });
+});