chore(atomic): migrate all commerce facets #5750
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# AtomicCommerceFacet Component Specification ## 📝 Requirements _The `atomic-commerce-facet` component is designed to render a commerce facet that allows end users to filter products by selecting, deselecting, and searching facet values. It supports accessibility, dynamic value loading, and integration with commerce search and product listing._ **Functional Requirements:** - Renders a facet with a label, values, and controls for filtering product results. - Allows users to select/deselect one or multiple facet values (checkbox style). - Supports clearing all selected filters with a clear button. - Provides a search input to filter facet values by text, with support for clearing the search. - Dynamically loads more/less facet values with "Show more" and "Show less" buttons. - Displays the number of active filters and supports collapsing/expanding the facet. - Handles and displays errors if the facet is misconfigured or encounters runtime issues. - Integrates with i18n for all user-facing strings. - Exposes CSS parts for customization and testing. **Constraints:** - Requires a valid `facet` controller instance as a property. - Must be used within a properly initialized commerce bindings context. - Only supports checkbox display for facet values (no radio or link display). ## ♿ Accessibility - Uses ARIA roles and live regions to announce search results and state changes. - All interactive elements (facet values, clear button, show more/less, search input) are keyboard accessible and focusable. - Supports screen reader announcements for search results and errors. - Complies with [WCAG 2.1](https://www.w3.org/TR/WCAG21/) guidelines. ## ⚡ Performance & Security - Subscribes to facet state changes efficiently; unsubscribes on disconnect to avoid memory leaks. - Loads facet values lazily ("Show more"/"Show less") to optimize rendering and data usage. - Sanitizes and localizes all user-facing strings to prevent XSS and ensure proper i18n. - Handles asynchronous operations for search and value loading gracefully. ##⚠️ Risks and Challenges - Incorrect or missing `facet` property will cause the component to error and display an error message. - Large numbers of facet values may impact performance if not paginated or searched efficiently. - Customization via CSS parts must be maintained to avoid breaking visual or functional tests. --- ## ✅ Checklist - [x] 🧪 The component is [unit tested](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.l9yzzrwf1i4k) (`atomic-commerce-facet.spec.ts`) - [x] 🧪 The component includes [E2E tests](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.z9tw07qe1lai) (`atomic-commerce-facet.e2e.ts`) - [x] 🗑️ Old Cypress tests exclusive to the component are removed - [ ] 📖 The component is documented in storybook with an `.mdx` file - [x] ♿ The component complies with the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/). - [x] 🌐 All strings intended for humans or assistive technology are localized with i18n. - [x] 📦 The Lit component is exported in the appropriate `index.ts` and `lazy-index.ts` files. - [x] 🎨 CSS parts are documented and accessible (see JSDoc in `atomic-commerce-facet.ts`). - [x] 🦥 Slotted Content, public methods and properties are documented. - [x] 🔄 The component outputs the same Angular output as before with Stencil. - [x] 🏷️ The component declares the component type in the HTMLElementTagNameMap. --- ## 🔍 QA Review Guidance - **Rendering:** - Ensure the facet renders with a label, values, and all controls (clear, show more/less, search input). - Check that the correct number of facet values is displayed and that values can be selected/deselected. - Verify that the clear button appears only when values are selected and clears all selections when clicked. - Confirm that the search input filters values and that the clear search button works as expected. - Test "Show more" and "Show less" for dynamic value loading. - Validate error handling by removing the `facet` property or simulating errors. - **Accessibility:** - Tab through all interactive elements; ensure focus states are visible and logical. - Use a screen reader to verify ARIA announcements for search results and errors. - Check that all controls are labeled and accessible. - **Localization:** - Change the i18n language and verify that all strings update accordingly. --- https://coveord.atlassian.net/browse/KIT-4059 --------- Co-authored-by: developer-experience-bot[bot] <91079284+developer-experience-bot[bot]@users.noreply.github.com>
https://coveord.atlassian.net/browse/KIT-4493 For the Stencil to Lit migration, please tag the Pull Request with `new-lit-component`. Do not fill out the PR description initially; a template will be automatically generated for you to complete. For all other contributors, please disregard this instruction. --------- Co-authored-by: Alex Prudhomme <[email protected]>
https://coveord.atlassian.net/browse/KIT-4499 For the Stencil to Lit migration, please tag the Pull Request with `new-lit-component`. Do not fill out the PR description initially; a template will be automatically generated for you to complete. For all other contributors, please disregard this instruction.
https://coveord.atlassian.net/browse/KIT-4500 --------- Co-authored-by: Frederic Beaudoin <[email protected]>
https://coveord.atlassian.net/browse/KIT-4497 --------- Co-authored-by: Frederic Beaudoin <[email protected]>
https://coveord.atlassian.net/browse/KIT-4494 For the Stencil to Lit migration, please tag the Pull Request with `new-lit-component`. Do not fill out the PR description initially; a template will be automatically generated for you to complete. For all other contributors, please disregard this instruction.
https://coveord.atlassian.net/browse/KIT-4495 --------- Co-authored-by: Frederic Beaudoin <[email protected]>
https://coveord.atlassian.net/browse/KIT-4502 For the Stencil to Lit migration, please tag the Pull Request with `new-lit-component`. Do not fill out the PR description initially; a template will be automatically generated for you to complete. For all other contributors, please disregard this instruction. --------- Co-authored-by: Frederic Beaudoin <[email protected]>
https://coveord.atlassian.net/browse/KIT-4504 For the Stencil to Lit migration, please tag the Pull Request with `new-lit-component`. Do not fill out the PR description initially; a template will be automatically generated for you to complete. For all other contributors, please disregard this instruction. --------- Co-authored-by: Alex Prudhomme <[email protected]>
https://coveord.atlassian.net/browse/KIT-4503 --------- Co-authored-by: Frederic Beaudoin <[email protected]>
https://coveord.atlassian.net/browse/KIT-4501 --------- Co-authored-by: Frederic Beaudoin <[email protected]>
# Atomic Commerce Numeric Facet Component Specification
## 📝 Requirements
_The `atomic-commerce-numeric-facet` component is designed to render a
commerce facet that allows users to filter products using numeric
ranges._
<!--
Describe the main purpose and functionality of the component and its
specific requirements.
e.g.:
- Functional Requirements: What the component should do.
- Constraints: Any limitations or constraints that must be considered.
-->
- **Range Filtering**: Allow users to filter products by selecting
predefined numeric ranges or entering custom ranges
- **Dynamic Value Display**: Show available numeric ranges with product
counts, hiding ranges with zero results unless selected
- **Manual Range Input**: Provide input fields for users to specify
custom numeric ranges when no predefined ranges are available
- **Price Formatting**: Apply appropriate currency formatting for
price-related fields (ec_price, ec_promo_price)
- **Facet State Management**: Maintain selection state, handle clearing
filters, and support collapse/expand functionality
- **Integration**: Work seamlessly with Coveo Headless commerce engine
and maintain synchronization with search results
## ♿ Accessibility
<!--
Describe accessibility considerations, such as ARIA roles, keyboard
navigation, etc.
Ensure the component is usable by people with disabilities.
-->
- **Focus Management**: Implements `FocusTargetController` to manage
focus restoration after search operations
- **Header Navigation**: Facet header is keyboard accessible with proper
focus management during collapse/expand
- **Semantic Structure**: Uses proper heading levels and semantic HTML
structure for screen reader compatibility
- **Interactive Elements**: All interactive elements (checkboxes, number
inputs, buttons) are keyboard accessible
- **ARIA Labels**: Leverages internationalization (i18n) for accessible
labels and descriptions
- **Screen Reader Support**: Provides meaningful labels for facet values
and state changes
## ⚡ Performance & Security (if applicable)
<!--
Describe performance considerations, such as asynchronous operations,
lazy loading, etc.
Describe security considerations, such as sanitization, preventing XSS
attacks, etc.
-->
- **Input Validation**: Number input handling includes proper validation
and range constraints
- **XSS Prevention**: All user-facing text goes through i18n system and
proper formatting functions
## ⚠️ Risks and Challenges (if applicable)
<!--
Identify potential risks and challenges associated with the component's
implementation and usage.
-->
- **Currency Dependency**: Price formatting relies on context currency
state; inconsistent currency data could cause display issues
- **Manual Range Validation**: Custom range inputs may accept invalid
ranges that could cause search errors
- **Field Type Assumptions**: Component makes assumptions about field
types (price fields) for formatting that may not hold for all use cases
---
## ✅ Checklist
- [x] 🧪 The component is [unit
tested](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.l9yzzrwf1i4k)
- [x] 🧪 The component includes [E2E
tests](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.z9tw07qe1lai)
- [x] 🗑️ Old Cypress tests exclusive to the component are removed
- [x] 📖 The component is documented in storybook with an `.mdx` file
- [x] ♿ The component complies with the [Web Content Accessibility
Guidelines](https://www.w3.org/TR/WCAG21/).
- [x] 🌐 All strings intended for humans or assistive technology must be
localized with i18n.
- [x] 📦 The Lit component is exported in the appropriate `index.ts` and
`lazy-index.ts` files.
- [x] 🎨 CSS parts are documented still accessible.
- [x] 🦥 Slotted Content, public methods and properties are documented
- [x] 🔄 The component outputs the same Angular output as before with
Stencil
- [x] 🏷️ The component declares the component type in the
HTMLElementTagNameMap
https://coveord.atlassian.net/browse/KIT-4376
---------
Co-authored-by: developer-experience-bot[bot] <91079284+developer-experience-bot[bot]@users.noreply.github.com>
Co-authored-by: Frederic Beaudoin <[email protected]>
Co-authored-by: jpmarceau <[email protected]>
# Atomic Commerce Timeframe Facet Component Specification
## 📝 Requirements
_The `atomic-commerce-timeframe-facet` component is designed to display
a facet of search results as date intervals, allowing users to filter
commerce products by time periods._
<!--
Describe the main purpose and functionality of the component and its
specific requirements.
e.g.:
- Functional Requirements: What the component should do.
- Constraints: Any limitations or constraints that must be considered.
-->
- **Date Interval Filtering**: Display predefined date intervals (e.g.,
"past week", "past month") as selectable facet values
- **Custom Date Range Input**: Provide date input fields for users to
specify custom start and end dates
- **Relative Date Support**: Handle and format relative date ranges
using deserialized relative date objects
- **Single Selection Mode**: Support single-select behavior for date
ranges using `toggleSingleSelect`
- **Dynamic Value Display**: Show only date intervals that have results
or are currently selected
- **Collapsible Interface**: Allow expanding/collapsing the facet
section to save screen space
- **Flexible Input Display**: Conditionally show date input fields based
on search state and available values
## ♿ Accessibility
<!--
Describe accessibility considerations, such as ARIA roles, keyboard
navigation, etc.
Ensure the component is usable by people with disabilities.
-->
- **Focus Management**: Uses `FocusTargetController` to manage focus on
the header element and maintain focus flow after user interactions
- **Keyboard Navigation**: Supports full keyboard access for all
interactive elements including facet value links and date input fields
- **Screen Reader Support**: Integrates with `atomic-facet-date-input`
component which provides accessible date input functionality
- **Focus Restoration**: Implements `focusAfterSearch()` to restore
focus appropriately after filter operations
## ⚡ Performance & Security (if applicable)
<!--
Describe performance considerations, such as asynchronous operations,
lazy loading, etc.
Describe security considerations, such as sanitization, preventing XSS
attacks, etc.
-->
## ⚠️ Risks and Challenges (if applicable)
<!--
Identify potential risks and challenges associated with the component's
implementation and usage.
-->
- **Timezone Considerations**: Potential issues with date interpretation
across different timezones, especially for e-commerce applications with
global users
- **Date Input Validation**: Ensuring robust validation for custom date
ranges to prevent invalid or illogical date combinations
---
## ✅ Checklist
- [x] 🧪 The component is [unit
tested](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.l9yzzrwf1i4k)
- [x] 🧪 The component includes [E2E
tests](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.z9tw07qe1lai)
- [x] 🗑️ Old Cypress tests exclusive to the component are removed
- [x] 📖 The component is documented in storybook with an `.mdx` file
- [x] ♿ The component complies with the [Web Content Accessibility
Guidelines](https://www.w3.org/TR/WCAG21/).
- [x] 🌐 All strings intended for humans or assistive technology must be
localized with i18n.
- [x] 📦 The Lit component is exported in the appropriate `index.ts` and
`lazy-index.ts` files.
- [x] 🎨 CSS parts are documented still accessible.
- [x] 🦥 Slotted Content, public methods and properties are documented
- [x] 🔄 The component outputs the same Angular output as before with
Stencil
- [x] 🏷️ The component declares the component type in the
HTMLElementTagNameMap
https://coveord.atlassian.net/browse/KIT-4447
---------
Co-authored-by: developer-experience-bot[bot] <91079284+developer-experience-bot[bot]@users.noreply.github.com>
Co-authored-by: Frederic Beaudoin <[email protected]>
Co-authored-by: Alex Prudhomme <[email protected]>
# Atomic Commerce Category Facet Component Specification
## 📝 Requirements
_The `atomic-commerce-category-facet` component is designed to display a
hierarchical, browsable facet interface for commerce applications that
allows users to filter products by categories in a tree-like structure._
<!--
Describe the main purpose and functionality of the component and its
specific requirements.
e.g.:
- Functional Requirements: What the component should do.
- Constraints: Any limitations or constraints that must be considered.
-->
- **Hierarchical Navigation**: Display category facet values in a
browsable, tree-like structure with parent-child relationships
- **Interactive Selection**: Allow users to select/deselect category
values to filter search results
- **Search Functionality**: Provide a search input to filter through
available category values
- **Collapsible Interface**: Support expanding and collapsing the facet
section
- **Breadcrumb Navigation**: Show selected value ancestry with
navigation back to parent categories
- **Show More/Less**: Handle pagination of category values when there
are many options
## ♿ Accessibility
<!--
Describe accessibility considerations, such as ARIA roles, keyboard
navigation, etc.
Ensure the component is usable by people with disabilities.
-->
- **ARIA Live Regions**: Implements `AriaLiveRegionController` to
announce facet search results to screen readers dynamically
- **Focus Management**: Uses `FocusTargetController` for managing focus
on show more/less buttons, header, and active value interactions
- **Keyboard Navigation**: Supports full keyboard interaction for all
interactive elements including buttons, links, and search input
- **Screen Reader Announcements**: Announces search result counts, facet
state changes, and navigation updates through aria-live regions
- **Focus Restoration**: Maintains proper focus flow when navigating
through the hierarchical structure and after user interactions
- **Localized Labels**: All user-facing text, aria-labels, and
announcements are internationalized for multi-language accessibility
support
## ⚡ Performance & Security (if applicable)
<!--
Describe performance considerations, such as asynchronous operations,
lazy loading, etc.
Describe security considerations, such as sanitization, preventing XSS
attacks, etc.
-->
## ⚠️ Risks and Challenges (if applicable)
<!--
Identify potential risks and challenges associated with the component's
implementation and usage.
-->
- **Deep Category Hierarchies**: Performance considerations when
rendering very deep category trees or large numbers of category values
---
## ✅ Checklist
- [x] 🧪 The component is [unit
tested](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.l9yzzrwf1i4k)
- [x] 🧪 The component includes [E2E
tests](https://docs.google.com/document/d/1lrsHAUROGMkRbsGlor02eYKF2mfrfBa0SOESxHFU3pI/edit?tab=t.0#heading=h.z9tw07qe1lai)
- [x] 🗑️ Old Cypress tests exclusive to the component are removed
- [x] 📖 The component is documented in storybook with an `.mdx` file
- [x] ♿ The component complies with the [Web Content Accessibility
Guidelines](https://www.w3.org/TR/WCAG21/).
- [x] 🌐 All strings intended for humans or assistive technology must be
localized with i18n.
- [x] 📦 The Lit component is exported in the appropriate `index.ts` and
`lazy-index.ts` files.
- [x] 🎨 CSS parts are documented still accessible.
- [x] 🦥 Slotted Content, public methods and properties are documented
- [x] 🔄 The component outputs the same Angular output as before with
Stencil
- [x] 🏷️ The component declares the component type in the
HTMLElementTagNameMap
https://coveord.atlassian.net/browse/KIT-4462
---------
Co-authored-by: developer-experience-bot[bot] <91079284+developer-experience-bot[bot]@users.noreply.github.com>
Co-authored-by: Frederic Beaudoin <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
For the Stencil to Lit migration, please tag the Pull Request with
new-lit-component. Do not fill out the PR description initially; a template will be automatically generated for you to complete.For all other contributors, please disregard this instruction.