feat(chip): add selection mode and toggle behavior

change/@ni-nimble-components-83f228b7-a387-4f1a-9bfe-2527beb62054.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Adds support for selection-mode on the nimble-chip component to allow for toggleable chips.",
+  "packageName": "@ni/nimble-components",
+  "email": "1458528+fredvisser@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

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

@@ -18,6 +18,7 @@ import './button';
 import './card';
 import './card-button';
 import './checkbox';
+import './chip';
 import './combobox';
 import './dialog';
 import './drawer';

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

@@ -1,4 +1,5 @@
 import { attr, nullableNumberConverter, observable } from '@ni/fast-element';
+import { keyEnter, keyEscape, keySpace } from '@ni/fast-web-utilities';
 import {
     applyMixins,
     DesignSystem,
@@ -10,7 +11,7 @@ import {
 } from '@ni/fast-foundation';
 import { styles } from './styles';
 import { template } from './template';
-import { ChipAppearance } from './types';
+import { ChipAppearance, ChipSelectionMode } from './types';
 import { slotTextContent } from '../utilities/models/slot-text-content';
 import { itemRemoveLabel } from '../label-provider/core/label-tokens';
 
@@ -19,6 +20,10 @@ declare global {
         'nimble-chip': Chip;
     }
 }
+export {
+    ChipSelectionMode,
+    type ChipSelectionMode as ChipSelectionModeType
+} from './types';
 
 export type ChipOptions = FoundationElementDefinition &
     StartOptions &
@@ -34,12 +39,29 @@ export class Chip extends FoundationElement {
     @attr({ mode: 'boolean' })
     public disabled = false;
 
+    @attr({ attribute: 'selection-mode' })
+    public selectionMode: ChipSelectionMode;
+
+    @attr({ mode: 'boolean' })
+    public selected = false;
+
     @attr()
     public appearance: ChipAppearance = ChipAppearance.outline;
 
     @attr({ attribute: 'tabindex', converter: nullableNumberConverter })
     public override tabIndex!: number;
 
+    /**
+     * Indicates whether the remove button is currently in a mousedown state.
+     * Used to prevent the chip's active styling from showing when the remove button is being clicked.
+     *
+     * @internal
+     * @remarks
+     * This attribute is automatically managed by handleRemoveMousedown and should not be set directly.
+     */
+    @attr({ attribute: 'remove-button-active', mode: 'boolean' })
+    public removeButtonActive = false;
+
     /** @internal */
     public readonly content?: HTMLElement[];
 
@@ -60,22 +82,187 @@ export class Chip extends FoundationElement {
     /** @internal */
     public contentSlot!: HTMLSlotElement;
 
+    private managingTabIndex = false;
+    private suppressTabIndexChanged = false;
+    private mouseUpHandler: EventListener | null = null;
+
+    public override connectedCallback(): void {
+        super.connectedCallback();
+        this.updateManagedTabIndex();
+    }
+
+    public override disconnectedCallback(): void {
+        super.disconnectedCallback();
+        if (this.mouseUpHandler) {
+            document.removeEventListener('mouseup', this.mouseUpHandler);
+            this.mouseUpHandler = null;
+        }
+    }
+
+    /** @internal */
+    public clickHandler(e: MouseEvent): boolean {
+        if (this.disabled) {
+            return false;
+        }
+
+        if (this.selectionMode === ChipSelectionMode.single) {
+            e.stopPropagation();
+            this.selected = !this.selected;
+            this.$emit('selected-change');
+            return false;
+        }
+        return true;
+    }
+
+    /** @internal */
+    public keyupHandler(e: KeyboardEvent): boolean {
+        if (this.disabled) {
+            return false;
+        }
+        switch (e.key) {
+            case keySpace:
+                if (this.selectionMode === ChipSelectionMode.single) {
+                    e.stopPropagation();
+                    this.selected = !this.selected;
+                    this.$emit('selected-change');
+                }
+                return true;
+            default:
+                return true;
+        }
+    }
+
     /** @internal */
-    public handleRemoveClick(): void {
+    public keydownHandler(e: KeyboardEvent): boolean {
+        if (this.disabled) {
+            return false;
+        }
+        switch (e.key) {
+            case keySpace:
+                if (this.selectionMode === ChipSelectionMode.single) {
+                    return false;
+                }
+                return true;
+            case keyEnter:
+                if (this.selectionMode === ChipSelectionMode.single) {
+                    e.stopPropagation();
+                    this.selected = !this.selected;
+                    this.$emit('selected-change');
+                    return false;
+                }
+                return true;
+            case keyEscape:
+                if (this.removable) {
+                    e.stopPropagation();
+                    this.$emit('remove');
+                    return false;
+                }
+                return true;
+            default:
+                return true;
+        }
+    }
+
+    /** @internal */
+    public handleRemoveClick(event: MouseEvent): void {
+        event.stopPropagation();
         if (this.removable) {
             this.$emit('remove');
         }
     }
+
+    /**
+     * Handles mousedown events on the remove button.
+     * Sets removeButtonActive to true and registers a document-level mouseup handler to clear it.
+     *
+     * @internal
+     * @remarks
+     * The mouseup listener is added to document to ensure it fires even if the mouse moves
+     * outside the chip before being released. The listener is cleaned up in disconnectedCallback
+     * to prevent memory leaks.
+     */
+    public handleRemoveMousedown(event: MouseEvent): void {
+        event.stopPropagation();
+        this.removeButtonActive = true;
+
+        // Clean up any existing listener first
+        if (this.mouseUpHandler) {
+            document.removeEventListener('mouseup', this.mouseUpHandler);
+        }
+
+        this.mouseUpHandler = (): void => {
+            this.removeButtonActive = false;
+            if (this.mouseUpHandler) {
+                document.removeEventListener('mouseup', this.mouseUpHandler);
+                this.mouseUpHandler = null;
+            }
+        };
+        document.addEventListener('mouseup', this.mouseUpHandler);
+    }
+
+    /** @internal */
+    public handleRemoveKeyup(event: KeyboardEvent): void {
+        event.stopPropagation();
+    }
+
+    protected selectionModeChanged(
+        _oldValue: ChipSelectionMode | undefined,
+        _newValue: ChipSelectionMode | undefined
+    ): void {
+        this.updateManagedTabIndex();
+    }
+
+    protected disabledChanged(_oldValue: boolean, _newValue: boolean): void {
+        this.updateManagedTabIndex();
+    }
+
+    protected tabIndexChanged(): void {
+        if (this.suppressTabIndexChanged) {
+            this.suppressTabIndexChanged = false;
+            return;
+        }
+
+        this.managingTabIndex = false;
+    }
+
+    private updateManagedTabIndex(): void {
+        if (!this.$fastController?.isConnected) {
+            return;
+        }
+
+        const shouldManage = this.selectionMode === ChipSelectionMode.single && !this.disabled;
+
+        if (shouldManage) {
+            if (!this.hasAttribute('tabindex')) {
+                this.setManagedTabIndex(0);
+            }
+        } else {
+            this.removeManagedTabIndex();
+        }
+    }
+
+    private setManagedTabIndex(value: number): void {
+        this.managingTabIndex = true;
+        this.suppressTabIndexChanged = true;
+        this.tabIndex = value;
+    }
+
+    private removeManagedTabIndex(): void {
+        if (!this.managingTabIndex) {
+            return;
+        }
+
+        this.managingTabIndex = false;
+        this.suppressTabIndexChanged = true;
+        this.removeAttribute('tabindex');
+    }
 }
 applyMixins(Chip, StartEnd);
 
 const nimbleChip = Chip.compose<ChipOptions>({
     baseName: 'chip',
     template,
-    styles,
-    shadowOptions: {
-        delegatesFocus: true
-    }
+    styles
 });
 
 DesignSystem.getOrCreate().withPrefix('nimble').register(nimbleChip());

packages/nimble-components/src/chip/specs/README.md

@@ -64,10 +64,13 @@ _The key elements of the component's public API surface:_
     - `removable` - set to show the remove button
     - `appearance` - supports `outline` and `block` appearances
     - `disabled` - styles the chip in the typical Nimble manner, including any user-slotted content (text and icon), and additionally hides the remove button.
+    - `selection-mode` - controls whether the chip can be selected. Values: `'none'` (default) or `'single'`. When `'single'`, the chip acts as a toggle button with `role="button"` and `aria-pressed`.
+    - `selected` - indicates the current selection state when `selection-mode="single"`. When `true`, the chip displays with selected background styling.
 - _Methods_
     - _None_
 - _Events_
-    - `remove` - fired when the chip remove button is pressed.
+    - `remove` - fired when the chip remove button is pressed, or when Escape key is pressed on a removable chip.
+    - `selected-change` - fired when the user toggles the chip's selected state via click or keyboard (Space/Enter). Only emitted when `selection-mode="single"`.
 - _Slots_
     - `start` - icon placed to the left of the chip text
     - (default) - for the primary label text
@@ -145,12 +148,18 @@ We will provide styling for the `disabled` attribute state.
 _Consider the accessibility of the component, including:_
 
 - _Keyboard Navigation and Focus_
-    - when the chip component is removable, the remove button will be focusable, otherwise it will not receive focus (following the `nimble-banner` pattern).
+    - When the chip is selectable (`selection-mode="single"`) and removable:
+        - The chip itself is focusable and receives keyboard events
+        - Space/Enter toggles the selected state
+        - Escape removes the chip (emits `remove` event)
+        - The remove button is **not** focusable (`tabindex="-1"`) to avoid nested interactive controls (violates [WCAG 4.1.2](https://dequeuniversity.com/rules/axe/4.11/nested-interactive))
+    - When the chip is removable but not selectable (`selection-mode="none"`):
+        - The remove button is focusable and can be activated with Space or Enter
 - _Form Input_
     - N/A
 - _Use with Assistive Technology_
+    - When selectable, the chip has `role="button"` and `aria-pressed` to indicate its toggle state
     - a `chip`'s accessible name comes from the element's contents by default
-    - no ARIA `role` seems necessary to define for the chip, as it isn't interactive itself (only the remove button is which has a `role`). The only valid role seemed to be [`status`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role), but that also didn't seem helpful from an accessibility perspective, particularly since it mainly relates to providing helpful information when the content changes (which we don't expect).
     - the remove button will have its content set to provide a label provider token for "Remove".
         - title will not be set, which aligns with decisions for the filterable select clear button and the banner
         - ideally this would include the contents of the chip itself (so a screen reader would announce "Remove <Chip>") but differing word order between
@@ -160,8 +169,6 @@ _Consider the accessibility of the component, including:_
 
 ### Future work
 
-- Make chip selectable (there are already UX designs)
-    - Currently there are no use-cases for chips requiring them to be selectable, but there are many use-cases in the wild where this is needed.
 - Provide error state for the chip (there are already UX designs)
     - Again, there are no current use-cases requiring a chip to present with error information, but it is not unreasonable to expect we may have such a use-case in the future.
 - Create a chip container component that manages chip layout, and removal