refactor(atomic): migrate atomic-timeframe-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 file.
• 🎨 CSS parts are documented and 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-4960

Description

Migrates atomic-timeframe-facet from Stencil to Lit framework, aligning with the ongoing modernization effort across the Atomic package. The component has been refactored to leverage the TimeframeFacetCommon helper class for improved code reuse and maintainability.

Component Changes

• Converted Stencil component to Lit using TimeframeFacetCommon helper
• Preserved all functionality: date range facets, date picker, dependency management, tab filtering, custom timeframes
• Applied Lit decorators (@customElement, @bindings, @withTailwindStyles, @bindStateToController)
• Replaced Stencil lifecycle with Lit equivalents (disconnectedCallback for cleanup)
• Updated all imports to use @/* path aliases
• Improved prop validation with regex patterns for min/max date format (YYYY-MM-DD)
• Reduced code duplication by ~300 lines through use of TimeframeFacetCommon
• Moved component from /facets/atomic-timeframe-facet/ to /search/atomic-timeframe-facet/
• Deleted legacy Stencil files (stencil-atomic-timeframe-facet.tsx and atomic-timeframe-facet.pcss)

Testing

• Unit tests (~290 lines): Refactored to focus on component initialization, integration with TimeframeFacetCommon, props validation, controller initialization, event handling, and lifecycle management
• Test structure follows Atomic testing guidelines with no superfluous describe wrappers
• Storybook stories: Added MSW API mocking for 6 scenarios (default, selected value, date picker, depends-on, collapsed, no results)
• E2E tests: Comprehensive Playwright tests covering date picker, min/max constraints, depends-on, breadbox integration
• Removed Cypress tests (4 files) - all scenarios covered by unit/E2E tests

Test Refactoring

Tests were refactored to align with the component's new architecture using TimeframeFacetCommon and Atomic testing guidelines:

Test Structure:

• Removed all superfluous describe wrappers (single-test blocks)
• Flattened test hierarchy to appropriate nesting levels (1-2 levels max)
• Conditions expressed in it() statements rather than nested describe blocks
• Follows guideline: use describe blocks only when tests share setup logic or test multiple aspects of the same condition

What's Tested:

• Component initialization and TimeframeFacetCommon creation
• Props validation (injectionDepth, headingLevel, min/max format with regex, sortCriteria)
• Integration: correct options passed to TimeframeFacetCommon
• Rendering delegation to TimeframeFacetCommon
• Lifecycle management (disconnectedCallback)
• Controller initialization (SearchStatus, TabManager)
• Event handling (date input apply)
• State management (isCollapsed toggle)

What's Not Tested (Delegated to TimeframeFacetCommon):

• Facet value rendering
• Date formatting logic
• Date range calculations
• Breadbox integration details
• Store registration specifics

This approach reduces test duplication (~645 lines to ~290 lines) and ensures tests focus on the component's actual responsibilities rather than logic handled by the shared helper.

Documentation

• MDX documentation (135 lines): Usage examples, custom ranges/labels, date picker configuration, dependent facets, best practices

Key Improvements

Use of TimeframeFacetCommon Helper

The component now delegates all facet logic to the TimeframeFacetCommon helper class, which provides:

• Centralized facet initialization and lifecycle management
• Consistent rendering logic across search and insight interfaces
• Simplified component code focusing on Lit-specific concerns
• Better separation of concerns and testability

Enhanced Validation

Min/max properties now validate the YYYY-MM-DD format with regex patterns and provide helpful error messages when validation fails.

Example Usage

import {AtomicTimeframeFacet} from '@coveo/atomic';

// Component now uses Lit patterns with TimeframeFacetCommon
<atomic-timeframe-facet 
  field="date" 
  label="Date" 
  with-date-picker
  min="2020-01-01"
  max="2025-12-31">
  <atomic-timeframe unit="month"></atomic-timeframe>
  <atomic-timeframe unit="year"></atomic-timeframe>
</atomic-timeframe-facet>

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Migrate atomic-timeframe-facet</issue_title>
<issue_description>

Jira Issue: KIT-4960

Type: User Story
Status: New
Priority: Medium
Components: Atomic

---

<agent_instructions>For e2e testing / storybook MSW mocking, I suggest you look at patterns in atomic-color-facet. Not quite the same, but similar. The e2e "happy path" for timeframe facet should be relatively similar, i.e., the facet renders, selecting a value works, facet search works. I don't think we need to cover show more / show less for atomic-timeframe-facet.

For the component itself, you can look at patterns in the commerce equivalent (atomic-commerce-timeframe-facet).

For unit tests, again you should look at patterns in atomic-color-facet (e.g., you'll see how we do / test prop validation, how we mock the console, etc.)</agent_instructions>

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 Migrate atomic-timeframe-facet #6399

---

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

[fbeaudoincoveo]

@copilot Can you update the tests now?

[Copilot]

@copilot Can you update the tests now?

Updated in commit 35d8294. The tests have been refactored to work with the new TimeframeFacetCommon-based architecture. The tests now focus on:

• Component initialization and integration with TimeframeFacetCommon
• Props validation (with regex validation for min/max)
• Rendering delegation
• Controller initialization
• Event handling
• Lifecycle management

Tests for facet-specific logic (value rendering, date formatting, etc.) are now handled by TimeframeFacetCommon's own test suite, eliminating duplication and reducing the test file from ~645 lines to ~330 lines.

[fbeaudoincoveo]

@copilot please get rid of the superfluous describe wrappers.

See .github/instructions/tests-atomic.instructions.md

in particular:

**Nested describe blocks:** Use `describe` blocks to group related tests that share:
- **Same condition/state:** `describe('when <condition>', () => {...})` - Groups tests that share common setup or state
- **Same lifecycle callback:** `describe('#connectedCallback (when added to the DOM)', () => {...})` - Tests for component lifecycle methods
- **Same public method:** `describe('#methodName', () => {...})` - Tests for public methods or properties

**When to use nested describe:**
- Tests share setup logic (e.g., same `beforeEach` mock configuration)
- Multiple tests verify different aspects of the same condition
- Testing a method with multiple scenarios or edge cases

**When NOT to use nested describe:**
- Single test for a condition - include condition in `it()` statement instead
- Tests are unrelated despite similar names
- Over-nesting (avoid more than 2-3 levels deep)

Apply to the entire spec file.

[Copilot]

Updated in commit 514ae6a. Removed all superfluous describe wrappers following the testing guidelines:

• Removed single-test describe blocks (field, facetId, sortCriteria, injectionDepth, headingLevel)
• Flattened min/max prop tests (previously had 2 tests each in describe blocks)
• Removed #controllers, #interactions, and isCollapsed describe wrappers
• Flattened disconnectedCallback test to main level

All tests now follow the pattern: single test conditions are in the it() statement, not nested describe blocks. The test file structure is now cleaner with appropriate nesting (1-2 levels max).