refactor(atomic): create FoldedItemListContextController for Lit migration (#6626)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: alexprudhomme <[email protected]>

Author: Copilot

packages/atomic/src/components/common/item-list/context/folded-item-list-context-controller.spec.ts

@@ -0,0 +1,175 @@
+import {LitElement} from 'lit';
+import {customElement, state} from 'lit/decorators.js';
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {
+  FoldedItemListContextController,
+  MissingParentError,
+} from './folded-item-list-context-controller';
+
+@customElement('test-element')
+class TestElement extends LitElement {
+  @state() error!: Error;
+
+  requestUpdate = vi.fn();
+}
+
+describe('folded-item-list-context', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('#MissingParentError', () => {
+    it('should create error with correct message when provided element name', () => {
+      const error = new MissingParentError('child-element');
+
+      expect(error.message).toBe(
+        'The "child-element" element must be the child of an "atomic-folded-result-list" or "atomic-insight-folded-result-list" element.'
+      );
+    });
+  });
+
+  describe('#FoldedItemListContextController', () => {
+    let mockElement: TestElement;
+    let controller: FoldedItemListContextController;
+
+    beforeEach(() => {
+      mockElement = new TestElement();
+      vi.spyOn(mockElement, 'addController');
+      vi.spyOn(mockElement, 'dispatchEvent');
+    });
+
+    it('should register itself as a controller with the host', () => {
+      controller = new FoldedItemListContextController(mockElement);
+
+      expect(mockElement.addController).toHaveBeenCalledWith(controller);
+    });
+
+    describe('when controller is connected', () => {
+      beforeEach(() => {
+        controller = new FoldedItemListContextController(mockElement);
+      });
+
+      it('should dispatch the resolveFoldedResultList event in #hostConnected', () => {
+        vi.spyOn(mockElement, 'dispatchEvent').mockReturnValue(false);
+
+        controller.hostConnected();
+
+        expect(mockElement.dispatchEvent).toHaveBeenCalledWith(
+          expect.objectContaining({
+            type: 'atomic/resolveFoldedResultList',
+          })
+        );
+      });
+
+      describe('when event is not canceled', () => {
+        beforeEach(() => {
+          vi.spyOn(mockElement, 'dispatchEvent').mockImplementation((event) => {
+            const customEvent = event as CustomEvent;
+            const handler = customEvent.detail;
+            if (typeof handler === 'function') {
+              handler({
+                logShowMoreFoldedResults: vi.fn(),
+                logShowLessFoldedResults: vi.fn(),
+              });
+            }
+            return false;
+          });
+        });
+
+        it('should set folded item list data', () => {
+          controller.hostConnected();
+
+          expect(controller.foldedItemList).toEqual({
+            logShowMoreFoldedResults: expect.any(Function),
+            logShowLessFoldedResults: expect.any(Function),
+          });
+        });
+
+        it('should clear error', () => {
+          controller.hostConnected();
+
+          expect(controller.error).toBeNull();
+          expect(controller.hasError).toBe(false);
+          expect(mockElement.error).toBeUndefined();
+        });
+
+        it('should request update', () => {
+          controller.hostConnected();
+
+          expect(mockElement.requestUpdate).toHaveBeenCalledTimes(1);
+        });
+      });
+
+      describe('when event is canceled', () => {
+        beforeEach(() => {
+          vi.spyOn(mockElement, 'dispatchEvent').mockReturnValue(true);
+          Object.defineProperty(mockElement, 'nodeName', {
+            value: 'TEST-ELEMENT',
+            configurable: true,
+          });
+        });
+
+        it('should set error', () => {
+          controller.hostConnected();
+
+          expect(controller.error).toBeInstanceOf(MissingParentError);
+          expect(controller.hasError).toBe(true);
+          expect(controller.error?.message).toBe(
+            'The "test-element" element must be the child of an "atomic-folded-result-list" or "atomic-insight-folded-result-list" element.'
+          );
+          expect(mockElement.error).toBe(controller.error);
+        });
+
+        it('should clear folded item list data', () => {
+          controller.hostConnected();
+
+          expect(controller.foldedItemList).toBeNull();
+        });
+
+        it('should request update', () => {
+          controller.hostConnected();
+
+          expect(mockElement.requestUpdate).toHaveBeenCalledTimes(2);
+        });
+      });
+
+      describe('#foldedItemList getter', () => {
+        beforeEach(() => {
+          controller = new FoldedItemListContextController(mockElement);
+        });
+
+        it('should return null when there is an error', () => {
+          vi.spyOn(mockElement, 'dispatchEvent').mockReturnValue(true);
+          Object.defineProperty(mockElement, 'nodeName', {
+            value: 'TEST-ELEMENT',
+            configurable: true,
+          });
+
+          controller.hostConnected();
+
+          expect(controller.foldedItemList).toBeNull();
+        });
+
+        it('should return folded item list data when there is no error', () => {
+          const mockFoldedItemList = {
+            logShowMoreFoldedResults: vi.fn(),
+            logShowLessFoldedResults: vi.fn(),
+          };
+
+          vi.spyOn(mockElement, 'dispatchEvent').mockImplementation((event) => {
+            const customEvent = event as CustomEvent;
+            const handler = customEvent.detail;
+            if (typeof handler === 'function') {
+              handler(mockFoldedItemList);
+            }
+            return false;
+          });
+
+          controller.hostConnected();
+
+          expect(controller.foldedItemList).toBe(mockFoldedItemList);
+        });
+      });
+    });
+  });
+});

packages/atomic/src/components/common/item-list/context/folded-item-list-context-controller.ts

@@ -0,0 +1,70 @@
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+import type {LitElementWithError} from '@/src/decorators/types.js';
+import {buildCustomEvent} from '@/src/utils/event-utils';
+
+const foldedItemListContextEventName = 'atomic/resolveFoldedResultList';
+
+export class MissingParentError extends Error {
+  constructor(elementName: string) {
+    super(
+      `The "${elementName}" element must be the child of an "atomic-folded-result-list" or "atomic-insight-folded-result-list" element.`
+    );
+  }
+}
+
+/**
+ * A reactive controller that manages folded item list context data from parent components.
+ * Handles fetching folded item list data via custom events and manages error states.
+ */
+export class FoldedItemListContextController<T = unknown>
+  implements ReactiveController
+{
+  private host: ReactiveControllerHost & LitElementWithError;
+  private _foldedItemList: T | null = null;
+  private _error: MissingParentError | null = null;
+
+  constructor(host: ReactiveControllerHost & LitElementWithError) {
+    this.host = host;
+    host.addController(this);
+  }
+
+  get foldedItemList(): T | null {
+    return this._error ? null : this._foldedItemList;
+  }
+
+  get error(): MissingParentError | null {
+    return this._error;
+  }
+
+  get hasError(): boolean {
+    return this._error !== null;
+  }
+
+  hostConnected(): void {
+    this._resolveFoldedItemListContext();
+  }
+
+  private _resolveFoldedItemListContext(): void {
+    const event = buildCustomEvent(
+      foldedItemListContextEventName,
+      (foldedItemList: T) => {
+        this._foldedItemList = foldedItemList;
+        this.host.requestUpdate();
+      }
+    );
+
+    const canceled = this.host.dispatchEvent(event);
+    if (canceled) {
+      const elementName = (this.host as Element).nodeName.toLowerCase();
+      this._error = new MissingParentError(elementName);
+      this._foldedItemList = null;
+      this.host.error = this._error;
+      this.host.requestUpdate();
+    }
+  }
+}
+
+type FoldedItemListContextEventHandler<T> = (foldedItemList: T) => void;
+export type FoldedItemListContextEvent<T> = CustomEvent<
+  FoldedItemListContextEventHandler<T>
+>;

packages/atomic/src/components/common/item-list/item-list-decorators.tsx

@@ -39,6 +39,7 @@ const foldedItemListStateContextEventName = 'atomic/resolveFoldedResultList';
 /**
  * A [StencilJS property decorator](https://stenciljs.com/) to be used for elements nested within a folded item list.
  * This allows the Stencil component to modify the folded item list rendered levels.
+ * @deprecated use FoldedItemListContextController instead.
  */
 export function FoldedItemListStateContext() {
   return (component: ComponentInterface, foldedListState: string) => {