@aquera/nile-elements 1.7.2 → 1.7.3

package/src/nile-combobox/nile-combobox.ts

@@ -38,12 +38,14 @@ import type {
   ComboboxTagLayout,
   ComboboxSize,
   ComboboxPlacement,
+  ComboboxRow,
   NileRemoveEvent,
 } from './types.js';
 import { ComboboxSelectionManager } from './selection-manager.js';
 import { ComboboxSearchManager } from './search-manager.js';
 import { ComboboxRenderer } from './renderer.js';
 import { ComboboxPortalManager } from './portal-manager.js';
+import { hasGroups, flattenRows, filterRows, getOptionRows } from './group-utils.js';
 import { VisibilityManager } from '../utilities/visibility-manager.js';
 
 /**
@@ -149,6 +151,15 @@ export class NileCombobox extends NileElement implements NileFormControl {
   /** The items displayed after filtering. Renderer reads from this. */
   @state() filteredData: any[] = [];
 
+  /**
+   * Mixed (header + option) row list, only populated when `data` contains
+   * group entries (`type: 'group'`). When non-empty, the listbox renders from
+   * this instead of `filteredData`. `filteredData` stays in sync as the
+   * option-only projection so existing select-all / strict-match / etc. logic
+   * keeps working unchanged.
+   */
+  @state() private filteredRows: ComboboxRow[] = [];
+
   /** The complete unfiltered dataset (preserved for re-filtering). */
   @state() private originalData: any[] = [];
 
@@ -159,6 +170,13 @@ export class NileCombobox extends NileElement implements NileFormControl {
   @state() private selectAllChecked = false;
   @state() private selectAllIndeterminate = false;
 
+  /**
+   * Index into `filteredRows` of the group header that should be pinned at
+   * the top of the (virtualized) listbox right now. -1 means none.
+   * Recomputed on scroll.
+   */
+  @state() private stickyHeaderIndex = -1;
+
   // ── Public properties ──
 
   @property() name = '';
@@ -230,6 +248,14 @@ export class NileCombobox extends NileElement implements NileFormControl {
    */
   @property({ type: Boolean, reflect: true, attribute: 'select-all-enabled' }) selectAllEnabled = false;
 
+  /**
+   * When true (default), data-driven group headers stick to the top of the
+   * listbox while scrolling through that group's options (Atlassian-style).
+   * Works in both plain and virtualized rendering modes. Set to false for
+   * inline-only headers that scroll away with their options.
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'sticky-group-header' }) stickyGroupHeader = true;
+
   @property({ type: Boolean, reflect: true }) portal = false;
 
   @property({ type: Boolean }) hoist = false;
@@ -359,6 +385,48 @@ export class NileCombobox extends NileElement implements NileFormControl {
     return this.gridRows > 0 && this.gridColumns <= 1;
   }
 
+  /** True when the source data contains at least one group entry. */
+  private get hasGroupedData(): boolean {
+    const base = this.originalData.length > 0 ? this.originalData : this.data;
+    return hasGroups(base);
+  }
+
+  /**
+   * Walk filteredRows and find the index of the deepest group header whose
+   * virtual position is at or above `scrollTop`. That's the header that
+   * should be pinned at the top of the listbox right now.
+   */
+  private updateStickyHeader(scrollTop: number): void {
+    if (!this.stickyGroupHeader || !this.hasGroupedData) {
+      if (this.stickyHeaderIndex !== -1) this.stickyHeaderIndex = -1;
+      return;
+    }
+    let offset = 0;
+    let stuck = -1;
+    for (let i = 0; i < this.filteredRows.length; i++) {
+      const row = this.filteredRows[i];
+      const size = row.kind === 'header' ? 32 : 38;
+      if (offset > scrollTop) break;
+      if (row.kind === 'header') stuck = i;
+      offset += size;
+    }
+    if (stuck !== this.stickyHeaderIndex) this.stickyHeaderIndex = stuck;
+  }
+
+  /** Recursively keep only options whose value is in `selectedSet`; drop empty groups. */
+  private pruneTreeBySelection(items: any[], selectedSet: Set<string>): any[] {
+    const out: any[] = [];
+    for (const item of items) {
+      if (item && typeof item === 'object' && item.type === 'group' && Array.isArray(item.options)) {
+        const kept = this.pruneTreeBySelection(item.options, selectedSet);
+        if (kept.length > 0) out.push({ ...item, options: kept });
+      } else if (selectedSet.has(String(this.getItemValue(item)))) {
+        out.push(item);
+      }
+    }
+    return out;
+  }
+
   private get hasActiveFilter(): boolean {
     return !!this.searchValue || this.showSelectedOnly;
   }
@@ -378,6 +446,9 @@ export class NileCombobox extends NileElement implements NileFormControl {
     if (this.gridColumns > 1) {
       return Math.ceil(this.filteredData.length / this.gridColumns);
     }
+    if (this.hasGroupedData) {
+      return this.filteredRows.length;
+    }
     return this.filteredData.length;
   }
 
@@ -400,16 +471,26 @@ export class NileCombobox extends NileElement implements NileFormControl {
     } else {
       const virtualizer = this.virtualizerCtrl.getVirtualizer();
       const count = this.virtualRowCount;
-      if (virtualizer.options.count !== count) {
+      const grouped = this.hasGroupedData;
+      const countChanged = virtualizer.options.count !== count;
+      const modeChanged = this.lastVirtualizerGrouped !== grouped;
+      if (countChanged || modeChanged) {
+        const estimateSize = grouped
+          ? (index: number) => (this.filteredRows[index]?.kind === 'header' ? 32 : 38)
+          : () => 38;
         virtualizer.setOptions({
           ...virtualizer.options,
           count,
+          estimateSize,
         });
         virtualizer.measure();
+        this.lastVirtualizerGrouped = grouped;
       }
     }
   }
 
+  private lastVirtualizerGrouped = false;
+
   // ── Data helpers ──
 
   private getDisplayText(item: any): string {
@@ -442,7 +523,10 @@ export class NileCombobox extends NileElement implements NileFormControl {
   // ── Selection ──
 
   private syncSelection(): void {
-    const items = this.originalData.length > 0 ? this.originalData : this.data;
+    const baseData = this.originalData.length > 0 ? this.originalData : this.data;
+    const items = this.hasGroupedData
+      ? getOptionRows(flattenRows(baseData)).map(r => r.item)
+      : baseData;
     this.selectedOptions = ComboboxSelectionManager.createOptionsFromValues(
       this.value,
       items,
@@ -785,19 +869,38 @@ export class NileCombobox extends NileElement implements NileFormControl {
 
   private filterOptions(search: string, preserveScroll = false): void {
     const baseData = this.originalData.length > 0 ? this.originalData : this.data;
-    let source = baseData;
-    if (this.showSelectedOnly) {
-      const selectedValues = Array.isArray(this.value) ? this.value : [this.value];
-      const selectedSet = new Set(selectedValues.map(v => String(v)));
-      source = baseData.filter((item: any) => selectedSet.has(String(this.getItemValue(item))));
+
+    if (this.hasGroupedData) {
+      // Grouped path: filter the tree, derive options-only projection.
+      let tree = baseData;
+      if (this.showSelectedOnly) {
+        const selectedValues = Array.isArray(this.value) ? this.value : [this.value];
+        const selectedSet = new Set(selectedValues.map(v => String(v)));
+        tree = this.pruneTreeBySelection(baseData, selectedSet);
+      }
+      const { rows } = filterRows(tree, search, this.getSearchText.bind(this));
+      this.filteredRows = rows;
+      this.filteredData = getOptionRows(rows).map(r => r.item);
+      this.showNoResults = this.filteredData.length === 0;
+      // Recompute sticky header at current scroll (defaults to top on filter).
+      const st = this.scrollElementRef.value?.scrollTop ?? 0;
+      this.updateStickyHeader(st);
+    } else {
+      let source = baseData;
+      if (this.showSelectedOnly) {
+        const selectedValues = Array.isArray(this.value) ? this.value : [this.value];
+        const selectedSet = new Set(selectedValues.map(v => String(v)));
+        source = baseData.filter((item: any) => selectedSet.has(String(this.getItemValue(item))));
+      }
+      const { filteredItems, showNoResults } = this.searchManager.filter(
+        search,
+        source,
+        this.getSearchText.bind(this),
+      );
+      this.filteredData = filteredItems;
+      this.filteredRows = [];
+      this.showNoResults = showNoResults;
     }
-    const { filteredItems, showNoResults } = this.searchManager.filter(
-      search,
-      source,
-      this.getSearchText.bind(this),
-    );
-    this.filteredData = filteredItems;
-    this.showNoResults = showNoResults;
 
     this.portalManager.resetMeasuredHeight();
     if (!preserveScroll) {
@@ -829,7 +932,10 @@ export class NileCombobox extends NileElement implements NileFormControl {
 
     if (!this.multiple) {
       if (this.strict) {
-        const allItems = this.originalData.length > 0 ? this.originalData : this.data;
+        const baseData = this.originalData.length > 0 ? this.originalData : this.data;
+        const allItems = this.hasGroupedData
+          ? getOptionRows(flattenRows(baseData)).map(r => r.item)
+          : baseData;
         const match = allItems.find(
           (item: any) => this.getDisplayText(item).toLowerCase() === this.searchValue.toLowerCase(),
         );
@@ -975,28 +1081,14 @@ export class NileCombobox extends NileElement implements NileFormControl {
     if (this.selectedOptions.length === 0) return;
 
     this.showSelectedOnly = !this.showSelectedOnly;
-
-    if (this.showSelectedOnly) {
-      this.searchValue = '';
-      const selectedValues = Array.isArray(this.value) ? this.value : [this.value];
-      this.filteredData = this.originalData.filter((item: any) => {
-        const iv = this.getItemValue(item);
-        return selectedValues.some(val => String(val) === String(iv));
-      });
-    } else {
-      this.filteredData = [...this.originalData];
-    }
-
-    this.portalManager.resetMeasuredHeight();
-    this.resetScrollPosition();
-    this.updateSelectAllState();
-    this.requestUpdate();
+    if (this.showSelectedOnly) this.searchValue = '';
+    this.filterOptions(this.searchValue);
   }
 
   private clearAll(): void {
     this.showSelectedOnly = false;
     this.value = this.multiple ? [] : '';
-    this.filteredData = [...this.originalData];
+    this.filterOptions('');
     this.syncSelection();
     this.emit('nile-change', { value: this.value, name: this.name });
     this.emit('nile-clear', { value: this.value, name: this.name });
@@ -1006,8 +1098,9 @@ export class NileCombobox extends NileElement implements NileFormControl {
   // ── Scroll ──
 
   private onScroll(e: Event): void {
-    if (this.showSelectedOnly) return;
     const target = e.target as HTMLElement;
+    this.updateStickyHeader(target.scrollTop);
+    if (this.showSelectedOnly) return;
 
     this.emit('nile-scroll', { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, name: this.name });
 
@@ -1067,8 +1160,13 @@ export class NileCombobox extends NileElement implements NileFormControl {
     if (this.originalData.length === 0 && this.data.length > 0) {
       this.originalData = [...this.data];
     }
-    this.filteredData = [...(this.originalData.length > 0 ? this.originalData : this.data)];
-    this.showNoResults = this.filteredData.length === 0;
+    if (this.hasGroupedData) {
+      this.filterOptions(this.searchValue);
+    } else {
+      this.filteredData = [...(this.originalData.length > 0 ? this.originalData : this.data)];
+      this.filteredRows = [];
+      this.showNoResults = this.filteredData.length === 0;
+    }
 
     await stopAnimations(this);
 
@@ -1137,7 +1235,12 @@ export class NileCombobox extends NileElement implements NileFormControl {
     if (this.data.length > 0 && !this.showSelectedOnly) {
       this.originalData = [...this.data];
     }
-    this.filteredData = [...this.data];
+    if (this.hasGroupedData) {
+      this.filterOptions(this.searchValue);
+    } else {
+      this.filteredData = [...this.data];
+      this.filteredRows = [];
+    }
     this.syncSelection();
     this.updateSelectAllState();
 
@@ -1404,6 +1507,19 @@ export class NileCombobox extends NileElement implements NileFormControl {
     `;
   }
 
+  private renderStickyHeaderOverlay(grouped: boolean, useVirtual: boolean): TemplateResult {
+    if (!this.stickyGroupHeader || !grouped || !useVirtual) return html``;
+    const idx = this.stickyHeaderIndex;
+    if (idx < 0 || idx >= this.filteredRows.length) return html``;
+    const row = this.filteredRows[idx];
+    if (row.kind !== 'header') return html``;
+    return html`
+      <div class="combobox__group-sticky-overlay">
+        ${ComboboxRenderer.renderGroupHeader(row)}
+      </div>
+    `;
+  }
+
   private renderListbox(): TemplateResult {
     const showAddOption = this.allowCustomValue
       && this.searchValue.trim()
@@ -1421,7 +1537,10 @@ export class NileCombobox extends NileElement implements NileFormControl {
     }
 
     const isGrid = this.gridColumns > 1 || this.isBidirectionalGrid;
-    const useVirtual = ComboboxRenderer.shouldUseVirtualizer(this.filteredData, this.gridColumns);
+    const grouped = this.hasGroupedData && !isGrid;
+    const useVirtual = grouped
+      ? this.filteredRows.length >= 5
+      : ComboboxRenderer.shouldUseVirtualizer(this.filteredData, this.gridColumns);
     const virtualizer = this.virtualizerCtrl.getVirtualizer();
     const virtualItems = (useVirtual || isGrid) ? virtualizer.getVirtualItems() : [];
     const totalSize = (useVirtual || isGrid) ? virtualizer.getTotalSize() : 0;
@@ -1443,6 +1562,7 @@ export class NileCombobox extends NileElement implements NileFormControl {
       >
         ${this.renderLoader()}
         ${this.renderSelectAll()}
+        ${this.renderStickyHeaderOverlay(grouped, useVirtual)}
         ${this.showNoResults && !this.optionsLoading && !this.loading
           ? this.renderEmptyState()
           : isGrid
@@ -1462,39 +1582,72 @@ export class NileCombobox extends NileElement implements NileFormControl {
                 this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
                 this.isBidirectionalGrid ? this.gridColumnWidth : undefined,
               )
-            : useVirtual
-              ? ComboboxRenderer.renderVirtualizedOptions(
-                  virtualItems,
-                  totalSize,
-                  this.filteredData,
-                  this.value,
-                  this.multiple,
-                  this.getDisplayText.bind(this),
-                  this.getItemValue.bind(this),
-                  this.optionsLoading || this.loading,
-                  this.allowHtmlLabel,
-                  virtualizer.measureElement,
-                  this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
-                  this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
-                  this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
-                )
-              : ComboboxRenderer.renderPlainOptions(
-                  this.filteredData,
-                  this.value,
-                  this.multiple,
-                  this.getDisplayText.bind(this),
-                  this.getItemValue.bind(this),
-                  this.showNoResults,
-                  this.noResultsMessage,
-                  this.optionsLoading || this.loading,
-                  this.onScroll.bind(this),
-                  this.allowHtmlLabel,
-                  this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
-                  this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
-                  this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
-                  undefined,
-                  this.hasActiveFilter ? this.noResultsSubtitle : undefined,
-                )
+            : grouped
+              ? (useVirtual
+                  ? ComboboxRenderer.renderRowsVirtualized(
+                      virtualItems,
+                      totalSize,
+                      this.filteredRows,
+                      this.value,
+                      this.multiple,
+                      this.getDisplayText.bind(this),
+                      this.getItemValue.bind(this),
+                      this.optionsLoading || this.loading,
+                      this.allowHtmlLabel,
+                      this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
+                      this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
+                      this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
+                    )
+                  : ComboboxRenderer.renderRowsPlain(
+                      this.filteredRows,
+                      this.value,
+                      this.multiple,
+                      this.getDisplayText.bind(this),
+                      this.getItemValue.bind(this),
+                      this.showNoResults,
+                      this.noResultsMessage,
+                      this.optionsLoading || this.loading,
+                      this.onScroll.bind(this),
+                      this.allowHtmlLabel,
+                      this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
+                      this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
+                      this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
+                      undefined,
+                      this.hasActiveFilter ? this.noResultsSubtitle : undefined,
+                    ))
+              : useVirtual
+                ? ComboboxRenderer.renderVirtualizedOptions(
+                    virtualItems,
+                    totalSize,
+                    this.filteredData,
+                    this.value,
+                    this.multiple,
+                    this.getDisplayText.bind(this),
+                    this.getItemValue.bind(this),
+                    this.optionsLoading || this.loading,
+                    this.allowHtmlLabel,
+                    virtualizer.measureElement,
+                    this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
+                    this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
+                    this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
+                  )
+                : ComboboxRenderer.renderPlainOptions(
+                    this.filteredData,
+                    this.value,
+                    this.multiple,
+                    this.getDisplayText.bind(this),
+                    this.getItemValue.bind(this),
+                    this.showNoResults,
+                    this.noResultsMessage,
+                    this.optionsLoading || this.loading,
+                    this.onScroll.bind(this),
+                    this.allowHtmlLabel,
+                    this.renderItemConfig?.getDescription ? this.getItemDescription.bind(this) : undefined,
+                    this.renderItemConfig?.getPrefix ? this.getItemPrefix.bind(this) : undefined,
+                    this.renderItemConfig?.getSuffix ? this.getItemSuffix.bind(this) : undefined,
+                    undefined,
+                    this.hasActiveFilter ? this.noResultsSubtitle : undefined,
+                  )
         }
         ${showAddOption ? html`
           <div @mouseup=${(e: MouseEvent) => { e.stopPropagation(); this.addCustomValue(this.searchValue.trim()); }}>

package/src/nile-combobox/renderer.ts

@@ -10,9 +10,127 @@ import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { repeat } from 'lit/directives/repeat.js';
 import type { VirtualItem } from '@tanstack/virtual-core';
+import type { ComboboxRow, ComboboxHeaderRow } from './types';
 
 export class ComboboxRenderer {
 
+  static renderGroupHeader(row: ComboboxHeaderRow): TemplateResult {
+    return html`
+      <div
+        part="group-header"
+        class="combobox__group-header"
+        role="presentation"
+        data-group-id=${row.id}
+        style=${`--group-depth:${row.depth}`}
+      >
+        ${row.prefix
+          ? html`<nile-icon
+              class="combobox__group-prefix"
+              name=${row.prefix}
+              size="14"
+              method="fill"
+            ></nile-icon>`
+          : ''}
+        <span class="combobox__group-label">${row.label}</span>
+      </div>
+    `;
+  }
+
+  static renderRowsPlain(
+    rows: ComboboxRow[],
+    value: string | string[],
+    multiple: boolean,
+    getDisplayText: (item: any) => string,
+    getItemValue: (item: any) => string,
+    showNoResults: boolean,
+    noResultsMessage: string,
+    isLoading: boolean,
+    onScroll: (e: Event) => void,
+    allowHtmlLabel: boolean,
+    getItemDescription?: (item: any) => string,
+    getItemPrefix?: (item: any) => string,
+    getItemSuffix?: (item: any) => string,
+    enableDescription?: boolean,
+    noResultsSubtitle?: string,
+  ): TemplateResult {
+    if (showNoResults && !isLoading && rows.length === 0) {
+      return ComboboxRenderer.renderNoResults(noResultsMessage, noResultsSubtitle);
+    }
+
+    return html`
+      <div
+        part="select-options"
+        class="combobox__options ${isLoading ? 'loading' : ''}"
+      >
+        <div class="combobox__options-plain" @scroll=${onScroll}>
+          ${rows.map((row) =>
+            row.kind === 'header'
+              ? ComboboxRenderer.renderGroupHeader(row)
+              : ComboboxRenderer.renderItem(
+                  row.item, value, multiple, getDisplayText, getItemValue,
+                  allowHtmlLabel, getItemDescription, getItemPrefix,
+                  getItemSuffix, enableDescription,
+                ),
+          )}
+        </div>
+      </div>
+    `;
+  }
+
+  static renderRowsVirtualized(
+    virtualItems: VirtualItem[],
+    totalSize: number,
+    rows: ComboboxRow[],
+    value: string | string[],
+    multiple: boolean,
+    getDisplayText: (item: any) => string,
+    getItemValue: (item: any) => string,
+    isLoading: boolean,
+    allowHtmlLabel: boolean,
+    getItemDescription?: (item: any) => string,
+    getItemPrefix?: (item: any) => string,
+    getItemSuffix?: (item: any) => string,
+    enableDescription?: boolean,
+  ): TemplateResult {
+    return html`
+      <div
+        part="select-options"
+        class="combobox__options ${isLoading ? 'loading' : ''}"
+      >
+        <div style="position:relative;height:${totalSize}px;width:100%;">
+          ${repeat(
+            virtualItems,
+            (vItem) => vItem.key,
+            (vItem) => {
+              const row = rows[vItem.index];
+              if (!row) return html``;
+              const posStyle =
+                `position:absolute;top:0;left:0;right:0;` +
+                `transform:translateY(${vItem.start}px);` +
+                `height:${vItem.size}px;`;
+              if (row.kind === 'header') {
+                return html`
+                  <div style=${posStyle} class="combobox__group-header-slot">
+                    ${ComboboxRenderer.renderGroupHeader(row)}
+                  </div>
+                `;
+              }
+              return html`
+                <div style=${posStyle}>
+                  ${ComboboxRenderer.renderItem(
+                    row.item, value, multiple, getDisplayText, getItemValue,
+                    allowHtmlLabel, getItemDescription, getItemPrefix,
+                    getItemSuffix, enableDescription,
+                  )}
+                </div>
+              `;
+            },
+          )}
+        </div>
+      </div>
+    `;
+  }
+
   static renderVirtualizedOptions(
     virtualItems: VirtualItem[],
     totalSize: number,
@@ -45,7 +163,7 @@ export class ComboboxRenderer {
                 const item = data[vItem.index];
                 return ComboboxRenderer.renderMeasuredItem(
                   item, vItem.index, value, multiple, getDisplayText, getItemValue,
-                  allowHtmlLabel, measureElement, getItemDescription, getItemPrefix,
+                  allowHtmlLabel, getItemDescription, getItemPrefix,
                   getItemSuffix, enableDescription,
                 );
               },
@@ -130,7 +248,6 @@ export class ComboboxRenderer {
     getDisplayText: (item: any) => string,
     getItemValue: (item: any) => string,
     allowHtmlLabel: boolean,
-    measureElement: (el: Element | null) => void,
     getItemDescription?: (item: any) => string,
     getItemPrefix?: (item: any) => string,
     getItemSuffix?: (item: any) => string,

package/src/nile-combobox/types.ts

@@ -25,3 +25,39 @@ export interface ComboboxRenderItemConfig {
 export type ComboboxTagLayout = 'single-line' | 'wrap' | 'fixed-height';
 export type ComboboxSize = 'small' | 'medium' | 'large';
 export type ComboboxPlacement = 'top' | 'bottom';
+
+export interface ComboboxGroupItem {
+  type: 'group';
+  id: string;
+  label: string;
+  prefix?: string;
+  options: ComboboxDataItem[];
+  collapsible?: boolean;
+}
+
+export interface ComboboxOptionItem {
+  type?: 'option';
+  value: string;
+  label?: string;
+  [key: string]: any;
+}
+
+export type ComboboxDataItem = ComboboxGroupItem | ComboboxOptionItem;
+
+export interface ComboboxHeaderRow {
+  kind: 'header';
+  id: string;
+  label: string;
+  prefix?: string;
+  depth: number;
+  optionCount: number;
+}
+
+export interface ComboboxOptionRow {
+  kind: 'option';
+  item: ComboboxOptionItem;
+  depth: number;
+  parentIds: string[];
+}
+
+export type ComboboxRow = ComboboxHeaderRow | ComboboxOptionRow;