feat(core): introduce tag layout options and patterns

coryrylan · coryrylan · commit c961584f3602 · 2026-05-28T10:45:43.000-05:00
- Added `tagLayout` property to manage inline tag rendering, supporting values 'hidden' and 'wrap'.
- Deprecated the `notags` attribute, recommending the use of `tag-layout="hidden"` instead.
- Updated styles for handling multiple overflow states with new tag layout options.
- Enhanced examples and tests to demonstrate new functionality and ensure accessibility compliance.

Signed-off-by: Cory Rylan &lt;crylan@nvidia.com&gt;
diff --git a/projects/core/src/combobox/combobox.css b/projects/core/src/combobox/combobox.css
@@ -48,13 +48,13 @@
   pointer-events: none;
 }
 
-:host(:state(multiple-overflow)) .tags {
+:host(:state(multiple-overflow):not([tag-layout='wrap'])) .tags {
   opacity: 0;
   pointer-events: none;
   position: absolute;
 }
 
-:host(:state(multiple-overflow)) .tags-label {
+:host(:state(multiple-overflow):not([tag-layout='wrap'])) .tags-label {
   display: flex;
 }
 
@@ -156,3 +156,17 @@ nve-menu-item[part='create-option'] {
     text-transform: uppercase;
   }
 }
+
+:host([tag-layout='wrap']:state(multiple-overflow)) {
+  [input] {
+    min-height: var(--height);
+    height: fit-content;
+    flex-direction: column;
+    width: 100%;
+  }
+
+  .tags {
+    padding-block-start: var(--nve-ref-size-50);
+    flex-wrap: wrap;
+  }
+}
diff --git a/projects/core/src/combobox/combobox.examples.ts b/projects/core/src/combobox/combobox.examples.ts
@@ -238,6 +238,42 @@ export const MultiSelect = () => {
   `
 };
 
+/**
+ * @summary Multi-select that reorders selected options before unselected options after the combobox closes. Use when long filter lists need selected values to stay easy to review.
+ */
+export const SelectedFirst = () => {
+  return html`
+  <nve-combobox id="combobox-selected-first" style="width: 500px; --scroll-height: 220px">
+    <label>label</label>
+    <input type="search">
+    <select multiple>
+      <option value="status"></option>
+      <option value="priority"></option>
+      <option value="date"></option>
+      <option value="session"></option>
+      <option value="configuration"></option>
+      <option value="contains"></option>
+      <option value="includes"></option>
+      <option value="user"></option>
+      <option value="progress"></option>
+    </select>
+    <nve-control-message>message</nve-control-message>
+  </nve-combobox>
+  <script type="module">
+    const combobox = document.querySelector('#combobox-selected-first');
+    const select = combobox.querySelector('select');
+    const optionOrder = new Map([...select.options].map((option, index) => [option, index]));
+    combobox.addEventListener('open', () => {
+      const selectedOrder = new Map([...select.selectedOptions].map((option, index) => [option, index]));
+      Array.from(select.options).sort((a, b) =>
+        Number(b.selected) - Number(a.selected) ||
+        a.selected && b.selected ? selectedOrder.get(a) - selectedOrder.get(b) : optionOrder.get(a) - optionOrder.get(b)
+      ).forEach(option => select.append(option));
+    });
+  </script>
+  `
+};
+
 /**
  * @summary Combobox with an empty initial value using a disabled placeholder option. Use when no default selection exists and the user must make an explicit choice.
  */
@@ -324,6 +360,28 @@ export const Overflow = () => {
   `
 };
 
+/**
+ * @summary Combobox with option to wrap tags when the parent container is too narrow. Input will span below the tags.
+ * @tags test-case
+ */
+export const OverflowWrap = () => {
+  return html`
+  <nve-combobox tag-layout="wrap" style="width: 400px">
+    <label>label</label>
+    <input type="search">
+    <select multiple>
+      <option selected value="status"></option>
+      <option selected value="priority"></option>
+      <option selected value="date"></option>
+      <option selected value="session"></option>
+      <option selected value="configuration"></option>
+      <option selected value="contains"></option>
+    </select>
+    <nve-control-message>message</nve-control-message>
+  </nve-combobox>
+  `
+};
+
 /**
  * @summary Combobox handling of long option text in constrained width containers.
  * @tags test-case
@@ -461,8 +519,8 @@ export const DisabledOptions = () => {
  */
 export const NoTags = () => {
   return html`
-  <form id="notags" nve-layout="column gap:lg align:stretch">
-    <nve-combobox notags>
+  <form id="hidden-tags" nve-layout="column gap:lg align:stretch">
+    <nve-combobox tag-layout="hidden">
       <label>label</label>
       <input type="search">
       <select multiple>
@@ -478,7 +536,7 @@ export const NoTags = () => {
     </div>
   </form>
   <script type="module">
-    const form = document.querySelector('#notags');
+    const form = document.querySelector('#hidden-tags');
     const select = form.querySelector('select');
     const tags = form.querySelector('#tags');
     updateTags();
diff --git a/projects/core/src/combobox/combobox.test.axe.ts b/projects/core/src/combobox/combobox.test.axe.ts
@@ -74,9 +74,9 @@ describe(Combobox.metadata.tag, () => {
     removeFixture(multiFixture);
   });
 
-  it('should pass axe check with notags multi select', async () => {
-    const notagsFixture = await createFixture(html`
-      <nve-combobox notags>
+  it('should pass axe check with hidden tag layout multi select', async () => {
+    const hiddenTagsFixture = await createFixture(html`
+      <nve-combobox tag-layout="hidden">
         <label>combobox</label>
         <input type="search" />
         <select multiple>
@@ -86,9 +86,9 @@ describe(Combobox.metadata.tag, () => {
         </select>
       </nve-combobox>
     `);
-    await elementIsStable(notagsFixture.querySelector(Combobox.metadata.tag));
+    await elementIsStable(hiddenTagsFixture.querySelector(Combobox.metadata.tag));
     const results = await runAxe([Combobox.metadata.tag]);
     expect(results.violations.length).toBe(0);
-    removeFixture(notagsFixture);
+    removeFixture(hiddenTagsFixture);
   });
 });
diff --git a/projects/core/src/combobox/combobox.test.ts b/projects/core/src/combobox/combobox.test.ts
@@ -725,6 +725,36 @@ describe(`${Combobox.metadata.tag}: multi select`, () => {
     expect(select.selectedOptions.length).toBe(1);
   });
 
+  it('should not open dropdown when tags are pressed without wrap layout', async () => {
+    const dropdown = element.shadowRoot.querySelector<Dropdown>(Dropdown.metadata.tag);
+    const tags = element.shadowRoot.querySelector<HTMLElement>('.tags');
+
+    expect(dropdown.matches(':popover-open')).toBe(false);
+    tags.dispatchEvent(new Event('pointerup', { bubbles: true }));
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    await elementIsStable(element);
+
+    expect(dropdown.matches(':popover-open')).toBe(false);
+  });
+
+  it('should focus input and open dropdown when wrap layout tags are pressed', async () => {
+    element.tagLayout = 'wrap';
+    await elementIsStable(element);
+
+    const dropdown = element.shadowRoot.querySelector<Dropdown>(Dropdown.metadata.tag);
+    const tags = element.shadowRoot.querySelector<HTMLElement>('.tags');
+
+    expect(dropdown.matches(':popover-open')).toBe(false);
+    tags.dispatchEvent(new Event('pointerup', { bubbles: true }));
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    await elementIsStable(element);
+
+    expect(document.activeElement).toBe(input);
+    expect(dropdown.matches(':popover-open')).toBe(true);
+  });
+
   it('should hide tags and display label when multiple is used and tags overflow container', async () => {
     expect(element.matches(':state(multiple-overflow)')).toBe(false);
     element.style.setProperty('--width', '100px');
@@ -740,13 +770,40 @@ describe(`${Combobox.metadata.tag}: multi select`, () => {
     expect(element.matches(':state(multiple-overflow)')).toBe(true);
   });
 
-  it('should not render inline tags when notags is used', async () => {
+  it('should keep tags visible when wrap layout is used with overflow state', async () => {
+    element.tagLayout = 'wrap';
+    element._internals.states.add('multiple-overflow');
+    await elementIsStable(element);
+
+    const tags = element.shadowRoot.querySelector<HTMLElement>('.tags');
+    const tagsLabel = element.shadowRoot.querySelector<HTMLElement>('.tags-label');
+
+    expect(element.matches(':state(multiple-overflow)')).toBe(true);
+    expect(getComputedStyle(tags).opacity).toBe('1');
+    expect(getComputedStyle(tags).position).toBe('static');
+    expect(getComputedStyle(tags).flexWrap).toBe('wrap');
+    expect(getComputedStyle(tagsLabel).display).toBe('none');
+  });
+
+  it('should not render inline tags when hidden tag layout is used', async () => {
+    element.tagLayout = 'hidden';
+    select.multiple = true;
+    select.options[0].selected = true;
+    select.options[1].selected = true;
+    select.options[2].selected = true;
+    await elementIsStable(element);
+    expect(element.shadowRoot.querySelectorAll(Tag.metadata.tag).length).toBe(0);
+  });
+
+  it('should support deprecated notags alias', async () => {
     element.notags = true;
     select.multiple = true;
     select.options[0].selected = true;
     select.options[1].selected = true;
     select.options[2].selected = true;
+
     await elementIsStable(element);
+
     expect(element.shadowRoot.querySelectorAll(Tag.metadata.tag).length).toBe(0);
   });
 
@@ -1379,6 +1436,66 @@ describe(`${Combobox.metadata.tag}: notags property reflection`, () => {
   });
 });
 
+describe(`${Combobox.metadata.tag}: tag-layout property reflection`, () => {
+  let fixture: HTMLElement;
+  let element: Combobox;
+
+  beforeEach(async () => {
+    fixture = await createFixture(html`
+      <nve-combobox>
+        <label>combobox</label>
+        <input type="search" />
+        <select multiple>
+          <option value="1">Option 1</option>
+        </select>
+      </nve-combobox>
+    `);
+    element = fixture.querySelector(Combobox.metadata.tag);
+    await elementIsStable(element);
+  });
+
+  afterEach(() => {
+    removeFixture(fixture);
+  });
+
+  it('should have undefined tagLayout by default', async () => {
+    expect(element.tagLayout).toBe(undefined);
+    expect(element.hasAttribute('tag-layout')).toBe(false);
+  });
+
+  it('should reflect tag-layout attribute when set via attribute', async () => {
+    element.setAttribute('tag-layout', 'wrap');
+    await elementIsStable(element);
+
+    expect(element.tagLayout).toBe('wrap');
+    expect(element.getAttribute('tag-layout')).toBe('wrap');
+  });
+
+  it('should reflect hidden tag-layout attribute when set via attribute', async () => {
+    element.setAttribute('tag-layout', 'hidden');
+    await elementIsStable(element);
+
+    expect(element.tagLayout).toBe('hidden');
+    expect(element.getAttribute('tag-layout')).toBe('hidden');
+  });
+
+  it('should reflect tag-layout attribute when set via property', async () => {
+    element.tagLayout = 'wrap';
+    await elementIsStable(element);
+
+    expect(element.tagLayout).toBe('wrap');
+    expect(element.getAttribute('tag-layout')).toBe('wrap');
+  });
+
+  it('should reflect hidden tag-layout attribute when set via property', async () => {
+    element.tagLayout = 'hidden';
+    await elementIsStable(element);
+
+    expect(element.tagLayout).toBe('hidden');
+    expect(element.getAttribute('tag-layout')).toBe('hidden');
+  });
+});
+
 describe(`${Combobox.metadata.tag}: disabled input`, () => {
   let fixture: HTMLElement;
   let element: Combobox;
diff --git a/projects/core/src/combobox/combobox.ts b/projects/core/src/combobox/combobox.ts
@@ -65,9 +65,16 @@ export class Combobox extends Control implements ContainerElement {
    */
   @property({ type: String, reflect: true }) container: 'flat';
 
-  /** Disable rendering of inline tags for many-item select */
+  /**
+   * @deprecated Use `tagLayout = 'hidden'` or `tag-layout="hidden"` instead.
+   *
+   * Disable rendering of inline tags for many-item select
+   */
   @property({ type: Boolean, reflect: true }) notags: boolean;
 
+  /** Manage inline tag rendering for many-item select */
+  @property({ type: String, reflect: true, attribute: 'tag-layout' }) tagLayout: 'hidden' | 'wrap';
+
   /** Enable creation of new options when the input value doesn't match any existing option. Dispatches a `create` event with `{ value }` detail. */
   @property({ type: Boolean, reflect: true, attribute: 'behavior-create' }) behaviorCreate: boolean;
 
@@ -168,7 +175,7 @@ export class Combobox extends Control implements ContainerElement {
   protected _associateDatalist = false;
 
   protected get prefixContent() {
-    return this.#select?.multiple && !this.notags
+    return this.#select?.multiple && !this.#tagLayoutIsHidden
       ? html`
     <div class="tags-label" aria-hidden="true">${this.#select.selectedOptions.length} ${this.i18n.selected}</div>
     <div class="tags">
@@ -180,6 +187,10 @@ export class Combobox extends Control implements ContainerElement {
       : html`<slot name="prefix-icon"></slot>`;
   }
 
+  get #tagLayoutIsHidden() {
+    return this.notags || this.tagLayout === 'hidden';
+  }
+
   get #largeOptionsList() {
     return (this.#datalist?.options?.length ?? 0) > 50;
   }
@@ -422,6 +433,12 @@ export class Combobox extends Control implements ContainerElement {
   }
 
   #setupOpenKeyEvents() {
+    this.#tags?.addEventListener('pointerup', () => {
+      if (this.tagLayout !== 'wrap') return;
+      this.input.focus();
+      setTimeout(() => this.#openListBox(), 0);
+    });
+
     this.input.addEventListener('pointerdown', () => {
       this.#openListBox();
     });
@@ -544,7 +561,7 @@ export class Combobox extends Control implements ContainerElement {
   }
 
   #setupOverflowListener() {
-    if (this.#select?.multiple && !this.notags) {
+    if (this.#select?.multiple && !this.#tagLayoutIsHidden) {
       if (this.#select.selectedOptions.length > 1) {
         // only calculate initial overflow if many tags exist
         this.#updateMultipleOverflow(this.#tags!.getBoundingClientRect().width);
diff --git a/projects/site/src/docs/about/migration.md b/projects/site/src/docs/about/migration.md
@@ -121,6 +121,22 @@ Before native HTML popovers, popovers required `behaviorTrigger` or `behavior-tr
 
 {% endbefore-after %}
 
+### Combobox No Tags <nve-badge status="warning">deprecated</nve-badge>
+
+Elements deprecates the `notags` attribute. Use `tag-layout="hidden"` instead so all tag layout modes use the same attribute.
+
+{% before-after %}
+
+```html
+<nve-combobox notags></nve-combobox>
+```
+
+```html
+<nve-combobox tag-layout="hidden"></nve-combobox>
+```
+
+{% endbefore-after %}
+
 ### Layout Full <nve-badge status="warning">deprecated</nve-badge>
 
 The `grow` property now uses `full` instead to avoid confusion with flexbox grow behavior.
diff --git a/projects/site/src/docs/elements/combobox.md b/projects/site/src/docs/elements/combobox.md
