refactor(atomic): migrate atomic-insight-facet from Stencil to Lit

[Copilot]

✅ Checklist

• 🧪 The component is unit tested
• 🧪 The component includes E2E tests
• 🗑️ Old Cypress tests exclusive to the component are removed
• 📖 The component is documented in storybook with an .mdx file
• ♿ The component complies with the Web Content Accessibility Guidelines.
• 🌐 All strings intended for humans or assistive technology must be localized with i18n.
• 📦 The Lit component is exported in the appropriate index.ts and lazy-index.ts files.
• 🎨 CSS parts are documented still accessible.
• 🦥 Slotted Content, public methods and properties are documented
• 🔄 The component outputs the same Angular output as before with Stencil
• 🏷️ The component declares the component type in the HTMLElementTagNameMap

https://coveord.atlassian.net/browse/KIT-4853

Description

Migrates atomic-insight-facet from Stencil to Lit with complete test coverage, Storybook documentation, and accessibility compliance.

Changes

Component Migration

• Converted to Lit with @customElement, @bindings(), @withTailwindStyles decorators
• Replaced Stencil lifecycle with Lit patterns (willUpdate, render, disconnectedCallback)
• Converted JSX templates to Lit html template literals
• Used when() directive for conditional rendering instead of FacetGuard
• All imports use @/src/ path aliases (no relative ../ imports except parent interface)
• Added HTMLElementTagNameMap declaration for type safety
• Removed @internal tag from JSDoc to make component publicly documented and Storybook-compatible
• Prop validation schema as private static readonly class member following best practices
• Validation logs warnings only (not errors) to match original Stencil behavior
• Fixed TypeScript errors:
  • Moved FacetResultsMustMatch import from @coveo/headless/insight to @coveo/headless
  • Fixed FocusTargetController constructor calls to include required name parameter
  • Fixed functional component rendering patterns (removed extra invocations)
  • Fixed AriaLiveRegionController usage to use .message property instead of .announce() method
  • Fixed callback type signatures for headerRef and setRef
• Deleted old Stencil files (atomic-insight-facet.tsx, atomic-insight-facet.pcss)

Unit Tests

• Comprehensive Vitest suite covering initialization, controller integration, user interactions
• Tests all display modes (checkbox, link, box), show more/less, exclusion, collapse
• Validates prop validation with console.warn checks (matches original Stencil behavior of no validation)
• Tests verify warning messages for invalid props without causing component failure
• Tests accessibility (ARIA live regions)
• Created missing Insight test fixtures (facet-controller.ts, facet-conditions-manager.ts)

Storybook Stories

• Created atomic-insight-facet.new.stories.tsx with MSW API mocking
• Includes stories for: Default, Low Facet Values, As Link, As Box, With Exclusion
• Uses MockInsightApi for proper API response mocking
• Uses wrapInInsightInterface for proper Insight interface context
• Removed @internal tag to enable Storybook documentation

E2E Tests

• Created comprehensive Playwright E2E test suite in e2e/ directory:
  • fixture.ts - Test fixture with InsightFacet page object
  • page-object.ts - Page object with locators for facet elements (expand buttons, facet values, show more/less, clear button)
  • atomic-insight-facet.e2e.ts - E2E tests covering:
    • Show more/less functionality
    • Clear button when values are selected
    • Display modes (checkbox, link, box)
    • Exclusion feature
    • Sort criteria (alphanumeric, alphanumericDescending, alphanumericNatural, alphanumericNaturalDescending, occurrences, automatic)
    • Accessibility (ARIA snapshot testing)

MDX Documentation

• Created atomic-insight-facet.mdx with comprehensive documentation:
  • Component description and usage in Insight interface
  • Display options (checkbox, link, box)
  • Exclusion feature explanation
  • Common use cases and UX best practices
  • Reference to facet design article

Cypress Tests

• Verified no Cypress tests exist for atomic-insight-facet (no tests to remove)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>KIT-4853: Migrate atomic-insight-facet from Stencil to Lit</issue_title>
<issue_description>### Task Description

Migrate atomic-insight-facet from Stencil to Lit.

See the already migrated atomic/src/components/search/atomic-facet component. Patterns (including test patterns) should be very similar.

Acceptance Criteria

• atomic-insight-facet has been migrated from Stencil to Lit
• Unit tests have been added (atomic-insight-facet.spec.ts)
• Stories have been added
• Stories use MSW for mocking network calls
• Happy path Playwright e2e tests have been added
• There are no more Cypress tests for the atomic-insight-facet
• The project builds without error
• All tests pass

Technical Notes

No response

Jira Ticket

https://coveord.atlassian.net/browse/KIT-4853</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: StencilToLitMigrationV1
Specialized agent for migrating Atomic Stencil code to Lit (components, functional components, and utils)

• Fixes KIT-4853: Migrate atomic-insight-facet from Stencil to Lit #6971

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[fbeaudoincoveo]

@copilot @coveo/atomic#build:stencil-lit is failing:

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:6:8
           Module '"@coveo/headless/insight"' has no exported
           member 'FacetResultsMustMatch'.

      L5:  buildSearchStatus as buildInsightSearchStatus,
      L6:  type FacetResultsMustMatch,
      L7:  type CategoryFacetValueRequest as InsightCategoryFacet
ValueRequest,

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:238:28
           Expected 2 arguments, but got 1.

    L237:  if (!this.showLessFocus) {
    L238:    this.showLessFocus = new FocusTargetController(this)
    L239:  }

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:280:19
           This expression is not callable.No constituent of
           type 'unique symbol | TemplateResult' is callable.

    L279:  private renderFacetHeader() {
    L280:    return html`${renderFacetHeader({                   
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                                                                 
                                                             
    L281:      props: {

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:294:9
           Type '(el: HTMLElement) => Promise<void>' is not
           assignable to type '(element?: HTMLButtonElement |
           undefined) => void'.Types of parameters 'el' and
           'element' are incompatible.Type 'HTMLButtonElement |
           undefined' is not assignable to type
           'HTMLElement'.Type 'undefined' is not assignable to
           type 'HTMLElement'.

    L293:    },
    L294:    headerRef: (el: HTMLElement) => this.focusTargets.he
    L295:  },

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:340:11
           Type '(btn: HTMLElement) => void' is not assignable
           to type '(btn?: Element | undefined) => void'.Types
           of parameters 'btn' and 'btn' are incompatible.Type
           'Element | undefined' is not assignable to type
           'HTMLElement'.Type 'undefined' is not assignable to
           type 'HTMLElement'.

    L339:  facetState: value.state,
    L340:  setRef: (btn: HTMLElement) => {
    L341:    if (shouldFocusOnShowLessAfterInteraction) {

[ ERROR ]  TypeScript: src/components/insight/atomic-insight-face
t/atomic-insight-facet.ts:403:51
           Property 'announce' does not exist on type
           'AriaLiveRegionController'.

    L402:  this.label,
    L403:  ) => this.facetSearchAriaLiveController.announce(msg),
    L404:  this.bindings.i18n

[ WARN  ]  Build Warn: src/components/common/atomic-suggestion-re
nderer/atomic-suggestion-renderer.tsx:20:18
           The @Prop() name "id" is a reserved public name.
           Please rename the "id" prop so it does not conflict
           with an existing standardized prototype member.
           Reusing prop names that are already defined on the
           element's prototype may cause unexpected runtime
           errors or user-interface issues on various browsers,
           so it's best to avoid them entirely.

     L19:  @Prop() public i18n!: i18n;
     L20:  @Prop() public id!: string;
     L21:  @Prop() public suggestion!: SearchBoxSuggestionElement
;

[ WARN  ]  Build Warn: src/components/common/atomic-suggestion-re
nderer/atomic-suggestion-renderer.tsx:27:18
           The @Prop() name "onClick" looks like an event.
           Please use the "@Event()" decorator to expose events
           instead, not properties or methods.

     L26:  @Prop() public isDoubleList!: boolean;
     L27:  @Prop() public onClick?: (e: Event) => void;
     L28:  @Prop() public onMouseOver?: (e: Event) => void;

[ WARN  ]  Build Warn: src/components/common/atomic-suggestion-re
nderer/atomic-suggestion-renderer.tsx:28:18
           The @Prop() name "onMouseOver" looks like an event.
           Please use the "@Event()" decorator to expose events
           instead, not properties or methods.

     L27:    @Prop() public onClick?: (e: Event) => void;
     L28:    @Prop() public onMouseOver?: (e: Event) => void;

[08:08.2]  build failed in 5.33 s

 ELIFECYCLE  Command failed with exit code 1.
command finished with error: command (/Users/fbeaudoin/Projects/u
i-kit/packages/atomic) /Users/fbeaudoin/.nvm/versions/node/v22.17
.1/bin/pnpm run build:stencil-lit exited (1)
└─ @coveo/atomic#build:stencil-lit ──
@coveo/atomic#build:stencil-lit: command (/Users/fbeaudoin/Projects/ui-kit/packages/atomic) /Users/fbeaudoin/.nvm/versions/node/v22.17.1/bin/pnpm run build:stencil-lit exited (1)

 Tasks:    21 successful, 22 total
Cached:    20 cached, 22 total
  Time:    8.804s 
Failed:    @coveo/atomic#build:stencil-lit

There are several ts errors in atomic-insight-facet.ts.

Also atomic-insight-facet.tsx has not been deleted, nor has atomic-insight-facet.pcss. This should be done. For the pcss file, double check to ensure that the static styles property in the migrated component is fully equivalent.

Once the old files have been deleted, and the necessary adjustments have been made to make the build pass, continue to the next step (creating Storybook stories).

[Copilot]

@copilot @coveo/atomic#build:stencil-lit is failing:

Fixed in commit 37b563e:

TypeScript errors fixed:

• Moved FacetResultsMustMatch import from @coveo/headless/insight to @coveo/headless
• Fixed FocusTargetController constructor calls to include required name parameter
• Fixed renderFacetHeader call (removed extra () invocation)
• Fixed AriaLiveRegionController usage to use .message property instead of .announce() method
• Fixed callback signatures for headerRef and setRef to match expected types

Old files deleted:

• Removed atomic-insight-facet.tsx (Stencil component)
• Removed atomic-insight-facet.pcss (styles now in Lit component's static styles)

The build now passes successfully. Proceeding to create Storybook stories next.

[SimonMilord]

👌

[Copilot]

Pull request overview

Migrates atomic-insight-facet from the legacy Stencil implementation to a Lit-based implementation and wires it into Atomic’s Insight exports, Storybook, and test infrastructure.

Changes:

• Replaced the Stencil atomic-insight-facet with a new Lit implementation (Tailwind styles, bindings, lifecycle updates).
• Added Vitest unit tests, Playwright E2E coverage scaffolding, and Storybook stories + MDX docs for the migrated component.
• Updated Insight exports/lazy loading, custom element tag registry, and Storybook Insight mock response data; removed the old Stencil files and Stencil-generated type entries.

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/atomic/vitest-utils/testing-helpers/fixtures/headless/insight/facet-controller.ts	Adds a fake Insight facet controller fixture used by the new unit tests.
packages/atomic/vitest-utils/testing-helpers/fixtures/headless/insight/facet-conditions-manager.ts	Adds a fake Insight facet conditions manager fixture for unit tests.
packages/atomic/storybook-utils/api/insight/search-response.ts	Extends the Insight mock search response with an objecttype facet for stories/tests.
packages/atomic/src/utils/custom-element-tags.ts	Registers atomic-insight-facet in the custom element tag set.
packages/atomic/src/components/insight/lazy-index.ts	Adds lazy-loading entry for atomic-insight-facet.
packages/atomic/src/components/insight/index.ts	Exports the Lit AtomicInsightFacet class from the Insight index.
packages/atomic/src/components/insight/atomic-insight-facet/e2e/page-object.ts	Introduces a Playwright page object for the component’s E2E tests.
packages/atomic/src/components/insight/atomic-insight-facet/e2e/fixture.ts	Adds a Playwright fixture wiring the page object.
packages/atomic/src/components/insight/atomic-insight-facet/e2e/atomic-insight-facet.e2e.ts	Adds initial Playwright E2E tests for the component.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.tsx	Removes the old Stencil implementation.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.ts	Adds the new Lit implementation of atomic-insight-facet.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.spec.ts	Adds Vitest unit tests for the new Lit component.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.pcss	Removes the old Stencil/PostCSS styles.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.new.stories.tsx	Adds Storybook stories for the migrated component.
packages/atomic/src/components/insight/atomic-insight-facet/atomic-insight-facet.mdx	Adds Storybook MDX documentation for the component.
packages/atomic/src/components.d.ts	Removes Stencil-generated typings for atomic-insight-facet (now Lit-based).
.claude/skills/creating-stories/SKILL.md	Updates internal Storybook/story creation guidance documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.