refactor(combo): overhaul selection, data pipeline, and component architecture (#2164)

* refactor(combo): overhaul selection, data pipeline, and component architecture

Major refactoring of the `IgcComboComponent` and its supporting infrastructure
to improve maintainability, correctness, and adherence to project conventions.

- `combo.ts`
- Inherits from `IgcBaseComboBoxComponent` instead of bare `LitElement`, sharing
  open/close lifecycle (`_show`, `_hide`) with picker components.
- Removed the `SelectionController` — selection state (`_selected: Set<T>`) is now
  managed directly inside the component for a simpler, single-source-of-truth model.
- Replaced `@watch('open')` decorator with `willUpdate()` lifecycle hook.
- Replaced `@queryAssignedElements` with `addSlotController` / `setSlots` for slot
  detection (no more `inputPrefix` / `inputSuffix` public properties).
- Form value serialization moved into the `setFormValue` transformer on
  `createFormValueState` — removes the separate `_setFormValue()` override.
- `_setDefaultValue` now handles invalid JSON gracefully instead of throwing.
- `firstUpdated` removed; initialization is handled by `willUpdate` / `willUpdate`
  data-sync guard for the delayed-data scenario.
- Added `_syncSelectionFromValue()` (value → Set) and `_syncValueFromSelection()`
  (Set → form value) for explicit one-way data flow.
- Added `_resolveItems()`, `_resolveItemValue()`, `_getValues()` private helpers.
- All internal render helpers and event handlers renamed to `_camelCase` convention
  (e.g., `renderMainInput` → `_renderMainInput`, `handleMainInput` → `_handleMainInput`).
- `groupKey` / `groupSorting` setters removed — now simple `@property` declarations;
  pipeline invalidation driven by `willUpdate`.
- `filteringOptions` and `disableFiltering` setters simplified.
- `label` and `placeholder` changed from `!` non-null asserted to optional (`?`).
- `placeholderSearch` setter typed as `string | undefined`.
- Added `Iterator.from` usage for lazy mapping/filtering of selections.

- `controllers/data.ts` — `DataController` → `DataState`
- Introduced a **dirty flag** pattern: `invalidate()` marks state as dirty and
  `hostUpdate()` runs the pipeline lazily before each render, batching multiple
  property changes into a single pipeline execution.
- Locale-aware `Intl.Collator` initialized from host locale; updated via
  `updateLocale(locale)`.
- `dataState` is now a read-only accessor.
- Added `invalidate()` and `updateLocale()` as explicit public API.
- Internal pipeline methods prefixed with `_`.

- `controllers/navigation.ts`
- Removed all `// @ts-expect-error: protected access` hacks.
- Added `interactions` config object to decouple `hide`, `show`, `toggleSelection`,
  `select`, and `clearSelection` callbacks — the navigation controller no longer
  reaches into the combo's protected methods directly.
- `_active` field is now public (`active`) so it can be read without casting.
- `_getNearestItem` rewritten with a `for` loop (was `while` with off-by-one risk).
- Navigation mutations now call `requestUpdate('_activeIndex', previous)` with the
  old value so Lit schedules targeted updates.
- Keybinding setup moved to the constructor body (was at the end).

- `controllers/selection.ts`
- **Deleted.** All selection logic inlined into `combo.ts`.

- `combo-item.ts`
- `renderCheckbox` renamed to `_renderCheckbox`.
- Switched from `nothing` conditional to Lit's `cache()` directive to preserve the
  checkbox DOM subtree when `hideCheckbox` toggles.
- `connectedCallback` marked `@internal`.
- Missing `@attr` / `@default` JSDoc tags added.

- `combo-list.ts` / `combo-header.ts`
- Added explicit `void` return type to `register()` methods.

- `common/mixins/combo-box.ts`
- `IgcBaseComboBoxLikeComponent` renamed to `IgcBaseComboBoxComponent` (core open/
  close behaviour only: `open`, `_show`, `_hide`, `_handleAnchorClick`, events).
- `IgcComboBoxBaseLikeComponent` extracted as a new subclass that adds
  `keepOpenOnSelect` and `keepOpenOnOutsideClick` — used by Dropdown, Select,
  DatePicker, and DateRangePicker.
- Protected event helpers renamed: `emitClosing` → `_emitClosing`, etc.
- `handleAnchorClick` → `_handleAnchorClick`.
- Utility functions (`getItems`, `getActiveItems`, etc.) given explicit return types.
- `setInitialSelectionState` simplified using `last()` and direct assignment.

- `common/util.ts`
- `findElementFromEventPath` renamed to `getElementFromPath` with full JSDoc.
- New `stopPropagation(event)` utility function extracted (used in combo template).
- `asArray` now uses `value == null` instead of `isDefined(value)`.

- Cross-component rename: `findElementFromEventPath` → `getElementFromPath`
Updated all callers: `button-group`, `calendar`, `carousel`, `drag`, `key-bindings`,
`root-click`, `date-picker`, `date-range-picker`, `dropdown`, `resize-controller`,
`select`, `stepper`, `tabs`, `tile`, `tree-item`.

---

- Added test: *"should handle invalid JSON in value attribute gracefully"*.
- Removed `await list.layoutComplete` from keyboard-selection test (no longer needed).

Author: rkaraivanov

src/components/button-group/button-group.ts

@@ -10,7 +10,7 @@ import { watch } from '../common/decorators/watch.js';
 import { registerComponent } from '../common/definitions/register.js';
 import type { Constructor } from '../common/mixins/constructor.js';
 import { EventEmitterMixin } from '../common/mixins/event-emitter.js';
-import { findElementFromEventPath, last } from '../common/util.js';
+import { getElementFromPath, last } from '../common/util.js';
 import type { ButtonGroupSelection, ContentOrientation } from '../types.js';
 import { styles } from './themes/group.base.css.js';
 import { all } from './themes/group.js';
@@ -167,10 +167,7 @@ export default class IgcButtonGroupComponent extends EventEmitterMixin<
   }
 
   private handleClick(event: MouseEvent) {
-    const button = findElementFromEventPath(
-      IgcToggleButtonComponent.tagName,
-      event
-    );
+    const button = getElementFromPath(IgcToggleButtonComponent.tagName, event);
 
     if (button) {
       this.isMultiple

src/components/calendar/calendar.ts

@@ -22,9 +22,9 @@ import { EventEmitterMixin } from '../common/mixins/event-emitter.js';
 import { partMap } from '../common/part-map.js';
 import {
   clamp,
-  findElementFromEventPath,
   first,
   formatString,
+  getElementFromPath,
   last,
 } from '../common/util.js';
 import IgcIconComponent from '../icon/icon.js';
@@ -267,7 +267,7 @@ export default class IgcCalendarComponent extends EventEmitterMixin<
   //#region Keyboard event handlers
 
   private _shouldSkipKeyboardEvent(_: Element, event: KeyboardEvent): boolean {
-    return !findElementFromEventPath(
+    return !getElementFromPath(
       `${IgcDaysViewComponent.tagName}, ${IgcMonthsViewComponent.tagName}, ${IgcYearsViewComponent.tagName}`,
       event
     );

src/components/calendar/helpers.ts

@@ -1,7 +1,7 @@
 import {
   asNumber,
-  findElementFromEventPath,
   first,
+  getElementFromPath,
   isString,
   last,
   modulo,
@@ -154,7 +154,7 @@ export function convertToDates(
  * Returns the value of the selected/activated element (day/month/year) in the calendar view.
  */
 export function getViewElement(event: Event): number {
-  const element = findElementFromEventPath<HTMLElement>('[data-value]', event);
+  const element = getElementFromPath<HTMLElement>('[data-value]', event);
   return element ? asNumber(element.dataset.value, -1) : -1;
 }
 

src/components/carousel/carousel.ts

@@ -42,9 +42,9 @@ import { partMap } from '../common/part-map.js';
 import {
   addSafeEventListener,
   asNumber,
-  findElementFromEventPath,
   first,
   formatString,
+  getElementFromPath,
   isEmpty,
   isLTR,
   last,
@@ -501,7 +501,7 @@ export default class IgcCarouselComponent extends EventEmitterMixin<
   }
 
   private async _handleIndicatorClick(event: PointerEvent): Promise<void> {
-    const indicator = findElementFromEventPath(
+    const indicator = getElementFromPath(
       IgcCarouselIndicatorComponent.tagName,
       event
     )!;

src/components/combo/combo-header.ts

@@ -12,7 +12,7 @@ export default class IgcComboHeaderComponent extends LitElement {
   public static override styles = [styles, shared];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcComboHeaderComponent);
   }
 

src/components/combo/combo-item.ts

@@ -1,5 +1,6 @@
 import { html, LitElement, nothing, type PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
+import { cache } from 'lit/directives/cache.js';
 import { addThemingController } from '../../theming/theming-controller.js';
 import IgcCheckboxComponent from '../checkbox/checkbox.js';
 import { addInternalsController } from '../common/controllers/internals.js';
@@ -38,13 +39,16 @@ export default class IgcComboItemComponent extends LitElement {
 
   /**
    * Determines whether the item is active.
+   * @attr active
+   * @default false
    */
   @property({ type: Boolean, reflect: true })
   public active = false;
 
   /**
    * Determines whether the item is active.
    * @attr hide-checkbox
+   * @default false
    */
   @property({ type: Boolean, attribute: 'hide-checkbox' })
   public hideCheckbox = false;
@@ -54,18 +58,19 @@ export default class IgcComboItemComponent extends LitElement {
     addThemingController(this, all);
   }
 
-  public override connectedCallback() {
+  /** @internal */
+  public override connectedCallback(): void {
     super.connectedCallback();
     this.role = 'option';
   }
 
-  protected override willUpdate(changedProperties: PropertyValues<this>): void {
-    if (changedProperties.has('selected')) {
+  protected override willUpdate(props: PropertyValues<this>): void {
+    if (props.has('selected')) {
       this._internals.setARIA({ ariaSelected: this.selected.toString() });
     }
   }
 
-  private renderCheckbox() {
+  private _renderCheckbox() {
     return html`
       <section part="prefix">
         <igc-checkbox
@@ -79,7 +84,7 @@ export default class IgcComboItemComponent extends LitElement {
 
   protected override render() {
     return html`
-      ${!this.hideCheckbox ? this.renderCheckbox() : nothing}
+      ${cache(this.hideCheckbox ? nothing : this._renderCheckbox())}
       <section id="content" part="content">
         <slot></slot>
       </section>

src/components/combo/combo-list.ts

@@ -1,5 +1,4 @@
 import { LitVirtualizer } from '@lit-labs/virtualizer/LitVirtualizer.js';
-
 import { registerComponent } from '../common/definitions/register.js';
 
 /* blazorSuppress */
@@ -9,7 +8,7 @@ export default class IgcComboListComponent extends LitVirtualizer {
   public override scroller = true;
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcComboListComponent);
   }
 }

src/components/combo/combo.spec.ts

@@ -1028,7 +1028,6 @@ describe('Combo', () => {
       simulateKeyboard(options, spaceBar);
 
       await elementUpdated(combo);
-      await list.layoutComplete;
 
       expect(items(combo)[1].selected).to.be.false;
       expect(items(combo)[2].selected).to.be.true;
@@ -1518,6 +1517,26 @@ describe('Combo', () => {
       spec.assertSubmitHasValue('US01');
     });
 
+    it('should handle invalid JSON in value attribute gracefully', () => {
+      const defaultValue = spec.element.defaultValue;
+
+      spec.setAttributes({ value: 'invalid' });
+      expect(spec.element.value).to.be.empty;
+      expect(spec.element.defaultValue).to.equal(defaultValue);
+    });
+
+    it('should handle empty string in value attribute gracefully', () => {
+      spec.setAttributes({ value: '' });
+      expect(spec.element.value).to.be.empty;
+      expect(spec.element.defaultValue).to.be.empty;
+    });
+
+    it('should handle null in value attribute gracefully', () => {
+      spec.setAttributes({ value: null as any });
+      expect(spec.element.value).to.be.empty;
+      expect(spec.element.defaultValue).to.be.empty;
+    });
+
     it('reflects disabled ancestor state', () => {
       spec.setAncestorDisabledState(true);
       expect(spec.element.disabled).to.be.true;