feat(atomic): add heading function for lit components (#4861)

* Added `heading` function to replace the `<Heading>` functional
component.
* Renamed `hidden.tsx` function component to `stencil-hidden.tsx` (to be
consistent)

## Usage
### with Stencil
```.tsx
<Heading level={level} class="truncate">
  {label}
</Heading>
```

### with Lit
```ts
html`${heading(
  {level, class: "truncate"},
  label
)}`
```

## Notes
Using
[`unsafeStatic`](https://lit.dev/docs/templates/expressions/#non-literal-statics)
since we need to interpolate non-literal statics.

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

---------

Co-authored-by: Frederic Beaudoin <[email protected]>

packages/atomic/src/components/commerce/atomic-commerce-breadbox/atomic-commerce-breadbox.tsx

@@ -38,7 +38,7 @@ import {
   defaultCurrencyFormatter,
   defaultNumberFormatter,
 } from '../../common/formats/format-common';
-import {Hidden} from '../../common/hidden';
+import {Hidden} from '../../common/stencil-hidden';
 import {CommerceBindings} from '../atomic-commerce-interface/atomic-commerce-interface';
 
 type AnyFacetValue =

packages/atomic/src/components/commerce/atomic-commerce-recommendation-list/atomic-commerce-recommendation-list.tsx

@@ -25,8 +25,6 @@ import {
 import {randomID} from '../../../utils/utils';
 import {ResultsPlaceholdersGuard} from '../../common/atomic-result-placeholder/placeholders';
 import {Carousel} from '../../common/carousel';
-import {Heading} from '../../common/heading';
-import {Hidden} from '../../common/hidden';
 import {createAppLoadedListener} from '../../common/interface/store';
 import {DisplayGrid} from '../../common/item-list/display-grid';
 import {DisplayWrapper} from '../../common/item-list/display-wrapper';
@@ -41,6 +39,8 @@ import {
   ItemDisplayImageSize,
   getItemListDisplayClasses,
 } from '../../common/layout/display-options';
+import {Heading} from '../../common/stencil-heading';
+import {Hidden} from '../../common/stencil-hidden';
 import {CommerceBindings} from '../atomic-commerce-recommendation-interface/atomic-commerce-recommendation-interface';
 import {ProductTemplateProvider} from '../product-list/product-template-provider';
 import {SelectChildProductEventArgs} from '../product-template-components/atomic-product-children/atomic-product-children';

packages/atomic/src/components/commerce/product-template-components/atomic-product-description/atomic-product-description.tsx

@@ -9,7 +9,7 @@ import {
   ExpandableText,
   TruncateAfter,
 } from '../../../common/expandable-text/expandable-text';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {CommerceBindings} from '../../atomic-commerce-interface/atomic-commerce-interface';
 import {ProductContext} from '../product-template-decorators';
 

packages/atomic/src/components/commerce/product-template-components/atomic-product-excerpt/atomic-product-excerpt.tsx

@@ -9,7 +9,7 @@ import {
   ExpandableText,
   TruncateAfter,
 } from '../../../common/expandable-text/expandable-text';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {CommerceBindings} from '../../atomic-commerce-interface/atomic-commerce-interface';
 import {ProductContext} from '../product-template-decorators';
 

packages/atomic/src/components/common/facets/facet-guard.tsx

@@ -1,5 +1,5 @@
 import {Fragment, FunctionalComponent, h} from '@stencil/core';
-import {Hidden} from '../hidden';
+import {Hidden} from '../stencil-hidden';
 
 interface FacetGuardProps {
   hasError: boolean;

packages/atomic/src/components/common/facets/facet-header/facet-header.tsx

@@ -3,8 +3,8 @@ import {i18n} from 'i18next';
 import ArrowBottomIcon from '../../../../images/arrow-bottom-rounded.svg';
 import ArrowTopIcon from '../../../../images/arrow-top-rounded.svg';
 import CloseIcon from '../../../../images/close.svg';
-import {Heading} from '../../heading';
 import {Button} from '../../stencil-button';
+import {Heading} from '../../stencil-heading';
 
 export interface FacetHeaderProps {
   i18n: i18n;

packages/atomic/src/components/common/facets/timeframe-facet-common.tsx

@@ -5,7 +5,7 @@ import {getFieldValueCaption} from '../../../utils/field-utils';
 import {randomID} from '../../../utils/utils';
 import {InsightBindings} from '../../insight/atomic-insight-interface/atomic-insight-interface';
 import {Bindings as SearchBindings} from '../../search/atomic-search-interface/atomic-search-interface';
-import {Hidden} from '../hidden';
+import {Hidden} from '../stencil-hidden';
 import {
   DateFacet,
   DateFacetValue,

packages/atomic/src/components/common/generated-answer/atomic-citation/atomic-citation.tsx

@@ -5,8 +5,8 @@ import {
   Instance as PopperInstance,
 } from '@popperjs/core';
 import {Component, h, State, Prop, Element, Watch} from '@stencil/core';
-import {Heading} from '../../heading';
 import {LinkWithItemAnalytics} from '../../item-link/item-link';
+import {Heading} from '../../stencil-heading';
 
 /**
  * @internal

packages/atomic/src/components/common/generated-answer/generated-answer-common.tsx

@@ -12,8 +12,8 @@ import {
   SafeStorage,
   StorageItems,
 } from '../../../utils/local-storage-utils';
-import {Heading} from '../heading';
 import {AnyBindings} from '../interface/bindings';
+import {Heading} from '../stencil-heading';
 import {Switch} from '../switch';
 import {CopyButton} from './copy-button';
 import {FeedbackButton} from './feedback-button';

packages/atomic/src/components/common/heading.spec.ts

@@ -0,0 +1,71 @@
+import {within} from '@storybook/test';
+import {html, render} from 'lit';
+import {heading, HeadingProps} from './heading';
+
+describe('heading', () => {
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container);
+  });
+
+  const renderHeading = (
+    props: Partial<HeadingProps>,
+    children?: string
+  ): HTMLElement => {
+    render(
+      html`${heading(
+        {
+          ...props,
+          level: props.level ?? 1,
+        },
+        html`${children}`
+      )}`,
+      container
+    );
+    return within(container).getByRole(
+      props.level && props.level > 0 && props.level <= 6 ? 'heading' : 'generic'
+    ) as HTMLElement;
+  };
+
+  it('should render a heading in the document', () => {
+    const props = {level: 1};
+    const headingElement = renderHeading(props);
+    expect(headingElement).toBeInTheDocument();
+  });
+
+  it('should render a heading with the correct level', () => {
+    const props = {level: 2};
+    const headingElement = renderHeading(props);
+    expect(headingElement.tagName.toLowerCase()).toBe('h2');
+  });
+
+  it('should render a div if level is outside the range of 1 to 6', () => {
+    const props = {level: 0};
+    const headingElement = renderHeading(props);
+    expect(headingElement.tagName.toLowerCase()).toBe('div');
+  });
+
+  it('should render a heading with the correct text content', () => {
+    const props = {level: 1};
+    const headingElement = renderHeading(props, 'Test Heading');
+    expect(headingElement.textContent).toContain('Test Heading');
+  });
+
+  it('should apply additional classes', () => {
+    const props = {level: 1, class: 'test-class'};
+    const headingElement = renderHeading(props);
+    expect(headingElement).toHaveClass('test-class');
+  });
+
+  it('should apply part attribute', () => {
+    const props = {level: 1, part: 'heading-part'};
+    const headingElement = renderHeading(props);
+    expect(headingElement.getAttribute('part')).toBe('heading-part');
+  });
+});

packages/atomic/src/components/common/heading.ts

@@ -0,0 +1,31 @@
+import {ifDefined} from 'lit-html/directives/if-defined.js';
+import {html, literal, unsafeStatic} from 'lit/static-html.js';
+
+export interface HeadingProps {
+  /**
+   * The heading level.
+   *
+   * A value outside of the range of 1 to 6 will render a div instead of a heading.
+   */
+  level: number;
+  /**
+   * Additional classes to add to the heading.
+   */
+  class?: string;
+  /**
+   * Additional parts to add to the heading.
+   */
+  part?: string;
+}
+
+export const heading = <T>(
+  {level, class: classname, part}: HeadingProps,
+  children?: T
+) => {
+  const headingTag =
+    level > 0 && level <= 6 ? unsafeStatic(`h${level}`) : literal`div`;
+
+  return html`<${headingTag} class="${ifDefined(classname)}" part="${ifDefined(part)}">
+    ${children}
+  </${headingTag}>`;
+};

packages/atomic/src/components/common/pager/pager-guard.tsx

@@ -1,5 +1,5 @@
 import {FunctionalComponent, h, Fragment} from '@stencil/core';
-import {Hidden} from '../hidden';
+import {Hidden} from '../stencil-hidden';
 
 export interface PagerGuardProps {
   hasError: boolean;

packages/atomic/src/components/common/smart-snippets/atomic-smart-snippet-suggestions/smart-snippet-suggestions-common.tsx

@@ -6,10 +6,10 @@ import {
 import {h} from '@stencil/core';
 import ArrowDown from '../../../../images/arrow-down.svg';
 import ArrowRight from '../../../../images/arrow-right.svg';
-import {Heading} from '../../heading';
-import {Hidden} from '../../hidden';
 import {AnyBindings} from '../../interface/bindings';
 import {Button} from '../../stencil-button';
+import {Heading} from '../../stencil-heading';
+import {Hidden} from '../../stencil-hidden';
 
 interface SmartSnippetSuggestionProps {
   id: string;

packages/atomic/src/components/common/smart-snippets/atomic-smart-snippet/smart-snippet-common.tsx

@@ -1,8 +1,8 @@
 import {SmartSnippetState, SmartSnippet} from '@coveo/headless';
 import {h} from '@stencil/core';
-import {Heading} from '../../heading';
-import {Hidden} from '../../hidden';
 import {AnyBindings} from '../../interface/bindings';
+import {Heading} from '../../stencil-heading';
+import {Hidden} from '../../stencil-hidden';
 import {SmartSnippetFeedbackBanner} from '../atomic-smart-snippet-feedback-banner';
 
 type FeedBackModalElement =

packages/atomic/src/components/common/heading.tsx → packages/atomic/src/components/common/stencil-heading.tsx

@@ -1,17 +1,12 @@
 import {h, FunctionalComponent} from '@stencil/core';
 import {JSXBase} from '@stencil/core/internal';
+import {HeadingProps} from './heading';
 
-export interface HeadingProps {
-  /**
-   * The heading level.
-   *
-   * A value outside of the range of 1 to 6 will render a div instead of a heading.
-   */
-  level: number;
-}
-
+/**
+ * @deprecated Should only be used for Stencil components; for Lit components, use the heading function instead.
+ */
 export const Heading: FunctionalComponent<
-  HeadingProps & JSXBase.HTMLAttributes<HTMLHeadingElement>
+  Pick<HeadingProps, 'level'> & JSXBase.HTMLAttributes<HTMLHeadingElement>
 > = ({level, ...htmlProps}, children) => {
   const HeadingTag = level > 0 && level <= 6 ? `h${level}` : 'div';
   return <HeadingTag {...htmlProps}>{children}</HeadingTag>;

packages/atomic/src/components/common/tab-manager/tab-guard.tsx

@@ -1,6 +1,6 @@
 import {Fragment, FunctionalComponent, h} from '@stencil/core';
 import {shouldDisplayOnCurrentTab} from '../../../utils/tab-utils';
-import {Hidden} from '../hidden';
+import {Hidden} from '../stencil-hidden';
 
 interface TabGuardProps {
   tabsIncluded: string | string[];

packages/atomic/src/components/insight/atomic-insight-refine-modal/atomic-insight-refine-modal.tsx

@@ -13,12 +13,12 @@ import {
   InitializableComponent,
   InitializeBindings,
 } from '../../../utils/initialization-utils';
-import {Hidden} from '../../common/hidden';
 import {
   getClonedFacetElements,
   RefineModal,
 } from '../../common/refine-modal/modal';
 import {Button} from '../../common/stencil-button';
+import {Hidden} from '../../common/stencil-hidden';
 import {InsightBindings} from '../atomic-insight-interface/atomic-insight-interface';
 
 /**

packages/atomic/src/components/ipx/atomic-ipx-recs-list/atomic-recs-list/atomic-ipx-recs-list.tsx

@@ -30,7 +30,6 @@ import {
 import {randomID} from '../../../../utils/utils';
 import {ResultsPlaceholdersGuard} from '../../../common/atomic-result-placeholder/placeholders';
 import {Carousel} from '../../../common/carousel';
-import {Heading} from '../../../common/heading';
 import {createAppLoadedListener} from '../../../common/interface/store';
 import {DisplayGrid} from '../../../common/item-list/display-grid';
 import {DisplayWrapper} from '../../../common/item-list/display-wrapper';
@@ -46,6 +45,7 @@ import {
   ItemDisplayDensity,
   ItemDisplayImageSize,
 } from '../../../common/layout/display-options';
+import {Heading} from '../../../common/stencil-heading';
 import {RecsBindings} from '../../../recommendations/atomic-recs-interface/atomic-recs-interface';
 
 /**

packages/atomic/src/components/ipx/atomic-ipx-refine-modal/atomic-ipx-refine-modal.tsx

@@ -12,12 +12,12 @@ import {
   InitializableComponent,
   InitializeBindings,
 } from '../../../utils/initialization-utils';
-import {Hidden} from '../../common/hidden';
 import {
   getClonedFacetElements,
   RefineModal,
 } from '../../common/refine-modal/modal';
 import {Button} from '../../common/stencil-button';
+import {Hidden} from '../../common/stencil-hidden';
 import {Bindings} from '../../search/atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/recommendations/atomic-recs-list/atomic-recs-list.tsx

@@ -26,7 +26,6 @@ import {
 import {randomID} from '../../../utils/utils';
 import {ResultsPlaceholdersGuard} from '../../common/atomic-result-placeholder/placeholders';
 import {Carousel} from '../../common/carousel';
-import {Heading} from '../../common/heading';
 import {createAppLoadedListener} from '../../common/interface/store';
 import {DisplayGrid} from '../../common/item-list/display-grid';
 import {DisplayWrapper} from '../../common/item-list/display-wrapper';
@@ -42,6 +41,7 @@ import {
   ItemDisplayBasicLayout,
   getItemListDisplayClasses,
 } from '../../common/layout/display-options';
+import {Heading} from '../../common/stencil-heading';
 import {RecsBindings} from '../atomic-recs-interface/atomic-recs-interface';
 
 /**

packages/atomic/src/components/search/atomic-breadbox/atomic-breadbox.tsx

@@ -22,7 +22,7 @@ import {BreadcrumbContent} from '../../common/breadbox/breadcrumb-content';
 import {BreadcrumbShowLess} from '../../common/breadbox/breadcrumb-show-less';
 import {BreadcrumbShowMore} from '../../common/breadbox/breadcrumb-show-more';
 import {Breadcrumb as BreadboxBreadcrumb} from '../../common/breadbox/breadcrumb-types';
-import {Hidden} from '../../common/hidden';
+import {Hidden} from '../../common/stencil-hidden';
 import {Bindings} from '../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/atomic-generated-answer/atomic-generated-answer.tsx

@@ -21,7 +21,7 @@ import {
 import {ArrayProp} from '../../../utils/props-utils';
 import {shouldDisplayOnCurrentTab} from '../../../utils/tab-utils';
 import {GeneratedAnswerCommon} from '../../common/generated-answer/generated-answer-common';
-import {Hidden} from '../../common/hidden';
+import {Hidden} from '../../common/stencil-hidden';
 import {Bindings} from '../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/atomic-notification/atomic-notifications.tsx

@@ -11,8 +11,8 @@ import {
   InitializableComponent,
   InitializeBindings,
 } from '../../../utils/initialization-utils';
-import {Heading} from '../../common/heading';
-import {Hidden} from '../../common/hidden';
+import {Heading} from '../../common/stencil-heading';
+import {Hidden} from '../../common/stencil-hidden';
 import {Bindings} from '../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/facets/atomic-automatic-facet/atomic-automatic-facet.tsx

@@ -12,7 +12,7 @@ import {FacetHeader} from '../../../common/facets/facet-header/facet-header';
 import {FacetValueCheckbox} from '../../../common/facets/facet-value-checkbox/facet-value-checkbox';
 import {FacetValueLabelHighlight} from '../../../common/facets/facet-value-label-highlight/facet-value-label-highlight';
 import {FacetValuesGroup} from '../../../common/facets/facet-values-group/facet-values-group';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {Bindings} from '../../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/facets/atomic-color-facet/atomic-color-facet.tsx

@@ -49,7 +49,7 @@ import {FacetValueBox} from '../../../common/facets/facet-value-box/facet-value-
 import {FacetValueLabelHighlight} from '../../../common/facets/facet-value-label-highlight/facet-value-label-highlight';
 import {FacetValuesGroup} from '../../../common/facets/facet-values-group/facet-values-group';
 import {initializePopover} from '../../../common/facets/popover/popover-type';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {Bindings} from '../../atomic-search-interface/atomic-search-interface';
 import {ColorFacetCheckbox} from '../color-facet-checkbox/color-facet-checkbox';
 

packages/atomic/src/components/search/facets/atomic-popover/atomic-popover.tsx

@@ -20,8 +20,8 @@ import {
   PopoverChildFacet,
   popoverClass,
 } from '../../../common/facets/popover/popover-type';
-import {Hidden} from '../../../common/hidden';
 import {Button} from '../../../common/stencil-button';
+import {Hidden} from '../../../common/stencil-hidden';
 import {Bindings} from '../../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/facets/atomic-rating-facet/atomic-rating-facet.tsx

@@ -37,7 +37,7 @@ import {FacetValueCheckbox} from '../../../common/facets/facet-value-checkbox/fa
 import {FacetValueLink} from '../../../common/facets/facet-value-link/facet-value-link';
 import {FacetValuesGroup} from '../../../common/facets/facet-values-group/facet-values-group';
 import {initializePopover} from '../../../common/facets/popover/popover-type';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {Bindings} from '../../atomic-search-interface/atomic-search-interface';
 
 /**

packages/atomic/src/components/search/facets/atomic-rating-range-facet/atomic-rating-range-facet.tsx

@@ -35,7 +35,7 @@ import {FacetPlaceholder} from '../../../common/facets/facet-placeholder/facet-p
 import {FacetValueLink} from '../../../common/facets/facet-value-link/facet-value-link';
 import {FacetValuesGroup} from '../../../common/facets/facet-values-group/facet-values-group';
 import {initializePopover} from '../../../common/facets/popover/popover-type';
-import {Hidden} from '../../../common/hidden';
+import {Hidden} from '../../../common/stencil-hidden';
 import {Bindings} from '../../atomic-search-interface/atomic-search-interface';
 
 /**