### ProductHighlightText Example Values

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/types.md

Example values demonstrating different configurations for the ProductHighlightText component, including basic text, template text with blockClass, links, and markers for Site Editor.

```typescript
// Basic text only
{ message: '{highlightName}' }
```

```typescript
// With template text
{ message: 'New: {highlightName}', blockClass: 'new-badge' }
```

```typescript
// With link
{ message: '{highlightName}', link: '/collection/{highlightId}' }
```

```typescript
// With markers for Site Editor
{
  message: '{highlightName}',
  markers: ['highlight-marker-1', 'highlight-marker-2']
}
```

--------------------------------

### ProductHighlights Usage Examples

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

Demonstrates how to use the ProductHighlights component to display different types of product highlights. Includes examples for collection, promotion, and teaser types, with filtering options.

```typescript
import ProductHighlights from 'product-highlights/ProductHighlights'
import ProductHighlightText from 'product-highlights/ProductHighlightText'

// Display all collection highlights
<ProductHighlights type="collection">
  <ProductHighlightText message="New: {highlightName}" />
</ProductHighlights>

// Display only specific promotion highlights
<ProductHighlights 
  type="promotion"
  filter={{
    type: 'show',
    highlightNames: ['10% Off', '20% Off']
  }}
>
  <ProductHighlightText message="Promotion: {highlightName}" />
</ProductHighlights>

// Hide unwanted teasers
<ProductHighlights 
  type="teaser"
  filter={{
    type: 'hide',
    highlightNames: ['Coming Soon']
  }}
>
  <ProductHighlightWrapper>
    <ProductHighlightText message="{highlightName}" />
  </ProductHighlightWrapper>
</ProductHighlights>
```

--------------------------------

### Filter Examples

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/types.md

Examples demonstrating how to configure the Filter interface for hiding specific highlights, showing only specific highlights, showing all, or showing none.

```typescript
// Hide specific highlights
const hideFilter: Filter = {
  type: 'hide',
  highlightNames: ['Coming Soon', 'Discontinued']
}
```

```typescript
// Show only specific highlights
const showFilter: Filter = {
  type: 'show',
  highlightNames: ['Hot Sale', '20% Off']
}
```

```typescript
// Show all highlights (default)
const allFilter: Filter = {
  type: 'hide',
  highlightNames: []
}
```

```typescript
// Show nothing
const noneFilter: Filter = {
  type: 'show',
  highlightNames: []
}
```

--------------------------------

### Product Highlight with Wrapper and Icon

Source: https://github.com/vtex-apps/product-highlights/blob/master/docs/README.md

Example demonstrating the use of `product-highlight-wrapper` to include an icon and `product-highlight-text` alongside the highlight name.

```jsonc
{
  "vtex.product-highlights@2.x:product-highlights": {
    "children": ["product-highlight-wrapper"]
  },
  "product-highlight-wrapper": {
    "children": [
      "icon-star", 
      "product-highlight-text"
    ]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}"
    }
  }
}
```

--------------------------------

### Example Teaser Data

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Provides sample JSON data representing different teaser highlights.

```json
[
  {
    "name": "Subscribe & Save - 15% Off"
  },
  {
    "id": "teaser-001",
    "name": "First-Time Customer Discount"
  },
  {
    "name": "Premium Member Exclusive - 20% Off"
  }
]
```

--------------------------------

### ProductHighlights Configuration Example: Collection Type

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Configures the ProductHighlights block to display collections. This is the default type.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "collection"
    },
    "children": ["product-highlight-text"]
  }
}
```

--------------------------------

### ProductHighlights Configuration Example: Promotion Type with Filter

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Configures the ProductHighlights block to display promotions, filtering by specific highlight names.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["10% Boleto", "Summer Sale"]
      }
    },
    "children": ["product-highlight-text"]
  }
}
```

--------------------------------

### Example Promotion Highlight Data

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Illustrates the JSON format for an array of promotion highlights, showing variations with and without promotion IDs.

```json
[
  {
    "name": "10% Boleto Discount"
  },
  {
    "id": "promo-789",
    "name": "Weekend Sale"
  },
  {
    "name": "Flash Deal - Limited Time"
  }
]
```

--------------------------------

### Testing with Mock Context

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Provides an example of how to test components using 'useHighlight' by mocking the 'ProductHighlightContext' with a test provider.

```typescript
import { render } from '@testing-library/react'
import { ProductHighlightContext } from 'product-highlights/ProductHighlights'

const mockContext = {
  highlight: { name: 'Test Highlight', id: 'test-123' },
  type: 'collection' as const,
}

const TestComponent = () => {
  const context = useHighlight()
  return <div>{context?.highlight.name}</div>
}

it('renders highlight name', () => {
  const { getByText } = render(
    <ProductHighlightContext.Provider value={mockContext}>
      <TestComponent />
    </ProductHighlightContext.Provider>
  )

  expect(getByText('Test Highlight')).toBeInTheDocument()
})
```

--------------------------------

### ProductHighlights Configuration Example: Teaser Type with Filter

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Configures the ProductHighlights block to display teasers, hiding specific highlight names.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "teaser",
      "filter": {
        "type": "hide",
        "highlightNames": ["Coming Soon"]
      }
    },
    "children": ["product-highlight-wrapper"]
  }
}
```

--------------------------------

### Example Collection Highlight Data

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Illustrates the JSON format for collection highlights, showing sample IDs and names.

```json
[
  {
    "id": "cluster-123",
    "name": "Top Sellers"
  },
  {
    "id": "cluster-456",
    "name": "New Arrivals"
  }
]
```

--------------------------------

### Product Highlight Block Configuration

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Example of how to configure the product-highlight-text block to apply a specific CSS class for custom styling.

```json
{
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}",
      "blockClass": "premium"
    }
  }
}
```

--------------------------------

### ProductHighlightWrapper Usage Examples

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

Demonstrates how to use ProductHighlightWrapper with different configurations, including simple text, multiple children, and for styling purposes. Ensure ProductHighlightText is imported when displaying highlight messages.

```typescript
import ProductHighlightWrapper from 'product-highlights/ProductHighlightWrapper'
import ProductHighlightText from 'product-highlights/ProductHighlightText'

// Simple wrapper with text
<ProductHighlightWrapper>
  <ProductHighlightText message="{highlightName}" />
</ProductHighlightWrapper>
```

```typescript
// Wrapper with multiple children (e.g., icon + text)
<ProductHighlightWrapper blockClass="premium">
  <img src="/star-icon.svg" alt="" />
  <ProductHighlightText message="{highlightName}" />
</ProductHighlightWrapper>
```

```typescript
// Wrapper for styling only
<ProductHighlightWrapper blockClass="sale-highlight">
  {/* Multiple components, custom content */}
</ProductHighlightWrapper>
```

--------------------------------

### Compose Custom Layout with Icon and Text

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

Use product-highlight-wrapper to compose custom highlight layouts. This example shows how to combine an icon and text for a badge-like appearance.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "collection"
    },
    "children": ["product-highlight-wrapper"]
  },
  "product-highlight-wrapper": {
    "props": {
      "blockClass": "badge"
    },
    "children": ["icon-badge", "product-highlight-text"]
  },
  "icon-badge": {
    "props": {
      "imageUrl": "https://example.com/badge.svg",
      "size": 20
    }
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}"
    }
  }
}
```

```css
.productHighlightWrapper--badge {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 4px 8px;
  background: #f5f5f5;
  border-radius: 4px;
}
```

--------------------------------

### Styled Promotion Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

Display promotion highlights with custom styling applied via a block class. This example includes CSS for styling.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "promotion"
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "💰 {highlightName}",
      "blockClass": "promotion"
    }
  }
}
```

```css
.productHighlightText--promotion {
  display: inline-block;
  background: #fff3e0;
  color: #e65100;
  padding: 4px 8px;
  border-radius: 3px;
  font-weight: bold;
  font-size: 12px;
}
```

--------------------------------

### Product Highlights CSS Customization

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Provides global and conditional CSS styling examples for the product highlight text and wrapper components. Includes styling for different highlight types (collection, promotion) and block-specific overrides.

```css
/* Global styling for all highlights */
.productHighlightText {
  display: inline-block;
  padding: 4px 8px;
  border-radius: 3px;
  font-size: 12px;
  font-weight: 600;
}

/* Collection highlights */
.productHighlightText[data-highlight-type="collection"] {
  background: #e0f2f1;
  color: #00695c;
}

/* Promotion highlights */
.productHighlightText[data-highlight-type="promotion"] {
  background: #fff3e0;
  color: #e65100;
}

/* Block-specific customization */
.productHighlightText--premium {
  background: #ffd700;
  color: #333;
}

/* Wrapper styling */
.productHighlightWrapper {
  display: flex;
  align-items: center;
  gap: 8px;
}

.productHighlightWrapper--premium {
  border-left: 3px solid gold;
  padding-left: 8px;
}
```

--------------------------------

### Responsive Highlight Layout

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

Configures different product highlight displays for mobile and desktop using resolution breakpoints. This setup uses flex-layout to conditionally render desktop or mobile components based on screen size.

```json
{
  "flex-layout.row#highlights": {
    "children": ["flex-layout.col#highlights-desktop", "flex-layout.col#highlights-mobile"]
  },
  "flex-layout.col#highlights-desktop": {
    "props": {
      "colSpan": 12,
      "preventHorizontalStretch": true,
      "preventVerticalStretch": true
    },
    "children": ["product-highlights#desktop"]
  },
  "flex-layout.col#highlights-mobile": {
    "props": {
      "colSpan": 12,
      "preventHorizontalStretch": true,
      "preventVerticalStretch": true
    },
    "children": ["product-highlights#mobile"]
  },
  "product-highlights#desktop": {
    "props": {
      "type": "collection"
    },
    "children": ["product-highlight-wrapper#desktop"]
  },
  "product-highlights#mobile": {
    "props": {
      "type": "collection"
    },
    "children": ["product-highlight-text#mobile"]
  },
  "product-highlight-wrapper#desktop": {
    "props": {
      "blockClass": "desktop"
    },
    "children": ["product-highlight-text#desktop"]
  },
  "product-highlight-text#desktop": {
    "props": {
      "message": "📌 {highlightName}",
      "blockClass": "desktop"
    }
  },
  "product-highlight-text#mobile": {
    "props": {
      "message": "{highlightName}",
      "blockClass": "mobile"
    }
  }
}
```

```css
/* Desktop: full wrapper with icon */
.productHighlightWrapper--desktop {
  display: none;
}

.productHighlightText--desktop {
  display: none;
}

/* Mobile: simple text */
.productHighlightText--mobile {
  display: block;
  background: #667eea;
  color: white;
  padding: 8px;
  text-align: center;
  font-weight: bold;
  font-size: 14px;
  margin: 8px 0;
}

@media (min-width: 768px) {
  .productHighlightWrapper--desktop {
    display: flex;
  }

  .productHighlightText--desktop {
    display: inline;
  }

  .productHighlightText--mobile {
    display: none;
  }
}
```

--------------------------------

### Multiple Product Highlights Blocks

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Use multiple ProductHighlights blocks with different filters when exceeding the maximum of 5 highlight names per filter. This example demonstrates grouping highlights into two separate blocks.

```json
{
  "flex-layout.row#all-highlights": {
    "children": ["product-highlights#group1", "product-highlights#group2"]
  },
  "product-highlights#group1": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["Discount 1", "Discount 2", "Discount 3"]
      }
    },
    "children": ["product-highlight-text"]
  },
  "product-highlights#group2": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["Discount 4", "Discount 5", "Discount 6"]
      }
    },
    "children": ["product-highlight-text"]
  }
}
```

--------------------------------

### Get Seller Information

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Retrieves seller information based on the selected SKU. Returns null if no `selectedSku` is available.

```typescript
const seller = selectedSku ? getSeller(selectedSku) : null
```

--------------------------------

### Example Usage of useHighlight Hook

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

Demonstrates how to use the useHighlight hook within a React component to access and display product highlight information. Ensure this component is rendered within a ProductHighlights provider.

```typescript
import { useHighlight } from 'product-highlights/ProductHighlights'

function CustomHighlightComponent() {
  const context = useHighlight()

  if (!context) {
    return null // Not inside a ProductHighlights provider
  }

  const { highlight, type } = context

  return (
    <div>
      <h3>{highlight.name}</h3>
      <p>Type: {type}</p>
      {highlight.id && <p>ID: {highlight.id}</p>}
    </div>
  )
}
```

--------------------------------

### CSS Selectors for Product Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Examples of CSS selectors targeting product highlights based on their data attributes. Use these to apply specific styles to different types or names of highlights.

```css
/* Target all collection highlights */
[data-highlight-type="collection"] {
  background: #e0f2f1;
}
```

```css
/* Target specific highlight by name */
[data-highlight-name="Top Seller"] {
  color: #d32f2f;
}
```

```css
/* Target highlights with IDs */
[data-highlight-id] {
  font-weight: bold;
}
```

```css
/* Target promotion highlights only */
[data-highlight-type="promotion"] {
  background: #fff3e0;
}
```

--------------------------------

### Get Seller from Product Item

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/utilities.md

Retrieves the appropriate seller from a product item. Prioritizes the default seller. Use this when you need to access seller-specific data like discounts or teasers from a product item.

```typescript
import { getSeller } from 'product-highlights/modules/seller'

// Inside a component with access to product item
const item = product.items[0]
const seller = getSeller(item)

if (seller) {
  const discountHighlights = seller.commertialOffer?.discountHighlights
  console.log('Highlights:', discountHighlights)
}

// Used internally by ProductHighlights
const { product, selectedItem } = useProduct() ?? {}
const selectedSku = selectedItem ?? product?.items?.[0]
const seller = selectedSku ? getSeller(selectedSku) : null
```

--------------------------------

### Get Default or First Seller from SKU

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Selects a seller from an SKU, prioritizing the default seller if marked, otherwise falling back to the first seller. Returns undefined if no sellers are found.

```typescript
function getSeller(item: ProductTypes.Item): ProductTypes.Seller | undefined {
  const defaultSeller = item?.sellers?.find((seller) => seller.sellerDefault)
  
  if (!defaultSeller) {
    return item?.sellers?.[0]
  }
  
  return defaultSeller
}
```

--------------------------------

### Simple Product Highlight Configuration

Source: https://github.com/vtex-apps/product-highlights/blob/master/docs/README.md

A basic configuration for the product-highlights block, rendering a highlight name using `product-highlight-text`.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}"
    }
  }
}
```

--------------------------------

### Implement ProductHighlightContextProvider

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Provides the Product Highlight context to its children. It memoizes the context value to optimize performance, re-creating it only when highlight or type changes.

```typescript
const ProductHighlightContextProvider: FC<ProductHighlightContextProviderProps> = ({
  highlight,
  type,
  children,
}) => {
  const contextValue = useMemo(
    () => ({
      highlight,
      type,
    }),
    [highlight, type]
  )

  return (
    <ProductHighlightContext.Provider value={contextValue}>
      {children}
    </ProductHighlightContext.Provider>
  )
}
```

--------------------------------

### Product Highlight Teaser Configuration

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

This JSON configures a product highlight of type 'teaser' and defines its message and link. The link dynamically includes highlight information.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "teaser"
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "⏰ Limited offer: {highlightName}",
      "link": "/promotions?teaser={highlightId}",
      "blockClass": "teaser"
    }
  }
}
```

--------------------------------

### Filtering Promotion Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Demonstrates how to filter promotion highlights from a seller's commercial offer based on a filter configuration. Requires helper functions 'getSeller' and 'createFilterHighlight'.

```typescript
const seller = getSeller(selectedSku)
const discountHighlights = seller?.commertialOffer?.discountHighlights ?? []
const filterHighlight = createFilterHighlight(filter)
return discountHighlights.filter(filterHighlight)
```

--------------------------------

### Make Product Highlights Clickable with Links

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

Configure product highlights to be clickable links, directing users to promotion or collection pages. Custom CSS can be applied for styling.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "promotion"
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "🎯 {highlightName}",
      "link": "/promotion/{highlightId}",
      "blockClass": "clickable"
    }
  }
}
```

```css
.productHighlightText--clickable {
  cursor: pointer;
  text-decoration: none;
  color: #0066cc;
}

.productHighlightText--clickable:hover {
  text-decoration: underline;
}
```

--------------------------------

### Product Highlight Text Element Example

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

This HTML structure shows a span element with data attributes used for product highlights. These attributes help in styling and selecting elements via JavaScript.

```html
<span
  data-highlight-name="Top Seller"
  data-highlight-id="collection-123"
  data-highlight-type="collection"
  class="productHighlightText"
>
  Top Seller
</span>
```

--------------------------------

### Product Highlight with Link Configuration

Source: https://github.com/vtex-apps/product-highlights/blob/master/docs/README.md

Configure a product highlight to link to a collection page using the `link` prop in `product-highlight-text`.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}",
      "link": "/collection/{highlightId}"
    }
  }
}
```

--------------------------------

### Add Product Highlights Dependency to manifest.json

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Declare the vtex.product-highlights app as a dependency in your theme's manifest.json file to make its blocks available.

```json
{
  "dependencies": {
    "vtex.product-highlights": "2.x"
  }
}
```

--------------------------------

### Import Components and Hook

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/INDEX.md

Import necessary components and the useHighlight hook from the product-highlights library. Ensure these imports are correctly placed at the beginning of your TypeScript files.

```typescript
// Components
import ProductHighlights from 'product-highlights/ProductHighlights'
import ProductHighlightText from 'product-highlights/ProductHighlightText'
import ProductHighlightWrapper from 'product-highlights/ProductHighlightWrapper'

// Hook
import { useHighlight } from 'product-highlights/ProductHighlights'

// Utilities
import { getSeller } from 'product-highlights/modules/seller'
```

--------------------------------

### Promotion Highlight with Link

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Create a clickable promotion highlight that links to a specific promotion URL. The highlightId is used to construct the link.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "promotion"
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "💰 {highlightName}",
      "link": "/promotion/{highlightId}"
    }
  }
}
```

--------------------------------

### Configure Search Results Layout with Product Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

This JSON configures the search results layout to include product highlights. It specifies how to query products and which product summary components to render, including the `product-highlights#search` block.

```json
{
  "search-result-layout.customQuery#search": {
    "props": {
      "querySchema": {
        "orderByField": "OrderByScore",
        "hideUnavailableItems": false,
        "queryField": "ft"
      }
    },
    "blocks": ["search-result-layout.desktop#search", "search-result-layout.mobile#search"]
  },
  "search-result-layout.desktop#search": {
    "children": ["flex-layout.row#search-results"]
  },
  "flex-layout.row#search-results": {
    "children": ["product-summary.shelf"]
  },
  "product-summary.shelf": {
    "children": [
      "product-summary-image",
      "product-summary-name",
      "product-highlights#search",
      "product-summary-price",
      "product-summary-buy-button"
    ]
  },
  "product-highlights#search": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["Sale", "New"]
      }
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}",
      "blockClass": "search-badge"
    }
  }
}
```

--------------------------------

### Query Product Context with useProduct

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Fetches product and selected item context. Ensure `useProduct` hook is available in the component scope.

```typescript
const { product, selectedItem } = useProduct()
```

--------------------------------

### Add Product Highlights to Theme Dependencies

Source: https://github.com/vtex-apps/product-highlights/blob/master/docs/README.md

Add the Product Highlights app to your theme's manifest.json dependencies to enable its usage.

```diff
"dependencies": {
+  "vtex.product-highlights": "2.x"
}
```

--------------------------------

### Filtering Teaser Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Demonstrates how to filter teaser highlights based on a seller's commercial offer and a provided filter. Assumes the existence of `getSeller` and `createFilterHighlight` functions.

```typescript
const seller = getSeller(selectedSku)
const teasers = seller?.commertialOffer?.teasers ?? []
const filterHighlight = createFilterHighlight(filter)
return teasers.filter(filterHighlight)
```

--------------------------------

### Product Highlights App Structure

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/overview.md

Overview of the directory structure for the Product Highlights VTEX app, including React components, utilities, fixtures, mocks, store definitions, messages, and metadata.

```treeview
react/
  ProductHighlights.tsx          — Provider component and context
  ProductHighlightText.tsx       — Text rendering component
  ProductHighlightWrapper.tsx    — Container component
  modules/
    seller.ts                    — Seller selection utility
  __fixtures__/
    tankTop.ts                   — Test data
  __mocks__/
    vtex.css-handles.tsx         — Mock for CSS handles
    vtex.native-types.tsx        — Mock for native types
    vtex.product-context.ts      — Mock for product context
store/
  interfaces.json                — Block definitions
messages/
  en.json, de.json               — Localized messages
manifest.json                    — VTEX app metadata
package.json                     — Dependencies and scripts
```

--------------------------------

### Rendering Pattern for ProductHighlightContextProvider

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Illustrates how `ProductHighlightContextProvider` is rendered for each filtered highlight. This ensures each child component tree receives its own context value.

```typescript
{highlights.map((highlight, index) => (
  <ProductHighlightContextProvider
    key={index}
    type={type}
    highlight={highlight}
  >
    {children}
  </ProductHighlightContextProvider>
))}
```

--------------------------------

### Access ProductHighlightContext with useHighlight Hook

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Demonstrates how to access the Product Highlight context using the `useHighlight` custom hook. It includes a check for the context's existence before accessing its properties.

```typescript
import { useHighlight } from 'product-highlights/ProductHighlights'

const context = useHighlight()
if (context) {
  console.log(context.highlight.name)
  console.log(context.type)
}
```

--------------------------------

### Render Each Highlight with Context Provider

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Maps over the filtered highlights to render each one within a `ProductHighlightContextProvider`. The `children` prop is passed down to the context provider.

```typescript
filtered.map((highlight) => (
  <ProductHighlightContextProvider highlight={highlight} type={type}>
    {children}
  </ProductHighlightContextProvider>
))
```

--------------------------------

### Using Outside a Provider

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Illustrates the behavior of 'useHighlight' when called outside of a 'ProductHighlights' provider, resulting in a null context.

```typescript
function OrphanComponent() {
  const context = useHighlight()
  // context is null
  return context ? <div>{context.highlight.name}</div> : <span>No highlight</span>
}
```

--------------------------------

### Memoize Highlights Calculation

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Memoizes the calculation of highlights using `useMemo` to optimize performance. The dependencies array ensures recalculation only when necessary.

```typescript
const highlights = useMemo(() => {
  // ... selection and filtering logic
}, [
  filter,
  product?.clusterHighlights,
  seller?.commertialOffer?.discountHighlights,
  seller?.commertialOffer?.teasers,
  type,
])
```

--------------------------------

### Full Product Page Integration with Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/template-examples.md

This JSON defines the structure of a product page, integrating product highlights as collection badges and featured promotions. It specifies the placement and configuration of highlight blocks within the page layout.

```json
{
  "store.product": {
    "children": [
      "breadcrumb",
      "flex-layout.row#product-main",
      "product-highlights#featured"
    ]
  },
  "flex-layout.row#product-main": {
    "children": ["flex-layout.col#product-images", "flex-layout.col#product-info"]
  },
  "flex-layout.col#product-images": {
    "children": ["product-images"]
  },
  "flex-layout.col#product-info": {
    "children": [
      "product-name",
      "product-rating",
      "product-highlights#badges",
      "product-price",
      "product-quantity",
      "add-to-cart"
    ]
  },
  "product-highlights#badges": {
    "props": {
      "type": "collection"
    },
    "children": ["product-highlight-wrapper"]
  },
  "product-highlight-wrapper": {
    "props": {
      "blockClass": "badge"
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "✨ {highlightName}",
      "blockClass": "badge"
    }
  },
  "product-highlights#featured": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["Hot Sale", "Limited Time"]
      }
    },
    "children": ["product-highlight-text#featured"]
  },
  "product-highlight-text#featured": {
    "props": {
      "message": "🎉 {highlightName}",
      "blockClass": "featured"
    }
  }
}
```

--------------------------------

### Block Class for Premium Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Configure a block class to apply specific styles to highlights, such as 'premium'. This allows for distinct visual treatments for different highlight categories.

```json
{
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}",
      "blockClass": "premium"
    }
  }
}
```

```css
.productHighlightText--premium {
  background: gold;
  color: #333;
  border: 2px solid #ffd700;
  font-weight: bold;
}
```

--------------------------------

### ProductHighlightText Component

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

A default exported component designed for rendering the text of a product highlight.

```APIDOC
## ProductHighlightText

### Description
Renders the textual content of a product highlight. This component is typically used within the context provided by `ProductHighlights`.

### Type
Component (default)

### Source
`ProductHighlightText.tsx`

### Usage
Render highlight text
```

--------------------------------

### useHighlight Hook

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

A named exported hook to access the product highlight context within your components.

```APIDOC
## useHighlight

### Description
Allows components to access and utilize the context provided by `ProductHighlights`, enabling them to display or interact with product highlight data.

### Type
Hook (named)

### Source
`ProductHighlights.tsx`

### Usage
Access highlight context
```

--------------------------------

### Product Highlight with Filter and Type Props

Source: https://github.com/vtex-apps/product-highlights/blob/master/docs/README.md

Configuration using `filter` and `type` props on the `product-highlights` block to conditionally display specific highlights like '10% Boleto'.

```jsonc
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "teaser",
      "filter": {
        "type": "show",
        "highlightNames": ["10% Boleto"]
      }
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}",
      "blockClass": "boleto"
    }
  }
}
```

--------------------------------

### Create Custom Highlight Component with useHighlight

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Develop a custom React component that utilizes the `useHighlight` hook to access and display highlight data. Register the component in `store/interfaces.json` and use it within the `ProductHighlights` block.

```typescript
// components/CustomHighlight.tsx
import { FC } from 'react'
import { useHighlight } from 'vtex.product-highlights'

const CustomHighlight: FC = () => {
  const context = useHighlight()

  if (!context) {
    return null
  }

  const { highlight, type } = context

  return (
    <div className="custom-highlight" data-type={type}>
      <div className="highlight-badge">
        {type === 'collection' && '📦'}
        {type === 'promotion' && '💰'}
        {type === 'teaser' && '⏰'}
      </div>
      <span className="highlight-name">{highlight.name}</span>
    </div>
  )
}

export default CustomHighlight
```

```json
{
  "custom-highlight": {
    "component": "CustomHighlight"
  }
}
```

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "children": ["custom-highlight"]
  }
}
```

--------------------------------

### Multiple Levels of Nesting

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Explains that 'useHighlight' accesses the context from the nearest 'ProductHighlights' provider when components are nested.

```jsx
<ProductHighlights type="collection">
  <ProductHighlightWrapper>
    <MyCustomComponent />  {/* useHighlight() returns first ProductHighlights' context */}
  </ProductHighlightWrapper>
</ProductHighlights>
```

--------------------------------

### Declare ProductHighlightContext

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Declares the React Context object for storing highlight data and type information. It is initialized with null.

```typescript
const ProductHighlightContext = React.createContext<ProductHighlightContextProviderProps | null>(null)
```

--------------------------------

### Conditional Rendering by Type

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Shows how to conditionally render different components based on the 'type' property of the highlight context.

```typescript
function TypeAwareHighlight() {
  const context = useHighlight()

  if (!context) {
    return null
  }

  if (context.type === 'collection') {
    return <CollectionHighlight name={context.highlight.name} />
  }

  if (context.type === 'promotion') {
    return <PromotionHighlight name={context.highlight.name} />
  }

  if (context.type === 'teaser') {
    return <TeaserHighlight name={context.highlight.name} />
  }

  return null
}
```

--------------------------------

### Product Highlights Block Definitions

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/block-schema.md

Defines the available blocks for the Product Highlights app: ProductHighlights, ProductHighlightWrapper, and ProductHighlightText.

```json
{
  "product-highlights": {
    "component": "ProductHighlights",
    "composition": "children"
  },
  "product-highlight-wrapper": {
    "component": "ProductHighlightWrapper",
    "composition": "children"
  },
  "product-highlight-text": {
    "component": "ProductHighlightText"
  }
}
```

--------------------------------

### Integration with Other Hooks

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Shows how to use the 'useHighlight' hook in conjunction with other VTEX hooks like 'useCssHandles' and 'useIntl'.

```typescript
import { useHighlight } from 'product-highlights/ProductHighlights'
import { useCssHandles } from 'vtex.css-handles'
import { useIntl } from 'react-intl'

function CustomHighlight() {
  const context = useHighlight()
  const handles = useCssHandles(['customHighlight'])
  const intl = useIntl()

  if (!context) {
    return null
  }

  // Use all three pieces of data together
  return (
    <div className={handles.customHighlight}>
      {context.highlight.name}
    </div>
  )
}
```

--------------------------------

### getSeller

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/utilities.md

Retrieves the appropriate seller from a product item, prioritizing the default seller.

```APIDOC
## getSeller

### Description
A utility function that retrieves the appropriate seller from a product item, prioritizing the default seller.

### Signature
```typescript
function getSeller(item: ProductTypes.Item): ProductTypes.Seller | undefined
```

### Parameters
#### Path Parameters
- `item` (ProductTypes.Item) - Required - A product item object from the VTEX product context. Expects the item to have a `sellers` array.

### Returns
`ProductTypes.Seller | undefined` — Returns the default seller if one is marked with `sellerDefault: true`. If no default seller exists, returns the first seller in the array. Returns undefined if the item has no sellers array or the sellers array is empty.

### Behavior
1. Searches the `item.sellers` array for a seller with `sellerDefault === true`
2. If a default seller is found, returns it
3. If no default seller exists, returns the first seller in the array (index 0)
4. Returns undefined if the sellers array is missing or empty

### Example Usage
```typescript
import { getSeller } from 'product-highlights/modules/seller'

// Inside a component with access to product item
const item = product.items[0]
const seller = getSeller(item)

if (seller) {
  const discountHighlights = seller.commertialOffer?.discountHighlights
  console.log('Highlights:', discountHighlights)
}

// Used internally by ProductHighlights
const { product, selectedItem } = useProduct() ?? {}
const selectedSku = selectedItem ?? product?.items?.[0]
const seller = selectedSku ? getSeller(selectedSku) : null
```

### Type Dependencies
Depends on types from `vtex.product-context`:

- `ProductTypes.Item` — A product SKU/item with sellers and commercial offer data
- `ProductTypes.Seller` — A seller object with default flag and commercial offer details

### Notes
- This function assumes the sellers array is a stable array (not mutating during the function call)
- Used internally by `ProductHighlights` to access discount highlights and teasers
- Useful in custom components that need to access seller-specific highlight data
```

--------------------------------

### useHighlight Hook Implementation

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

The core implementation of the useHighlight hook, utilizing React's useContext to read from ProductHighlightContext.

```typescript
export const useHighlight = () => {
  const group = useContext(ProductHighlightContext)
  return group
}
```

--------------------------------

### Filtering Collection Highlights

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Demonstrates how to filter product cluster highlights based on a provided filter object. Ensure the 'createFilterHighlight' function is available in the scope.

```typescript
const clusterHighlights = product?.clusterHighlights ?? []
const filterHighlight = createFilterHighlight(filter)
return clusterHighlights.filter(filterHighlight)
```

--------------------------------

### Highlight Interface Definition

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Defines the structure for promotion highlights, including optional ID and required name.

```typescript
interface Highlight {
  id?: string         // Promotion ID (may be absent)
  name: string        // Promotion display name
}
```

--------------------------------

### Component Attachment: ProductHighlights Schema

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

The ProductHighlights component has a static schema property for admin configuration. This is not an export for direct import but a configuration attachment.

```typescript
ProductHighlights.schema = {
  title: 'Product Highlights',
  type: 'object',
  properties: { /* ... */ }
}
```

--------------------------------

### ProductHighlightText: Admin Site Editor Customization with Markers

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

Enables dynamic message editing via the Admin Site Editor by providing marker IDs. Use the 'markers' prop to pass an array of marker IDs.

```typescript
import ProductHighlightText from 'product-highlights/ProductHighlightText'

// With markers for Admin Site Editor
<ProductHighlightText 
  message="{highlightName}"
  markers={['highlight-text-marker-1']}
/>
```

--------------------------------

### ProductHighlights Component Signature

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

The main provider component that queries highlights from the product context and distributes them to child components via React Context.

```typescript
function ProductHighlights(props: ProductHighlightsProps): JSX.Element | null
```

--------------------------------

### Simple Read in Child Component

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Demonstrates a basic usage pattern for reading highlight context within a child component. Ensures context is available before rendering.

```typescript
function MyHighlightComponent() {
  const context = useHighlight()

  if (!context) {
    return null
  }

  return <div>{context.highlight.name}</div>
}
```

--------------------------------

### ProductHighlightText: Simple Text Display

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/components.md

Renders the highlight name as plain text. Ensure the 'message' prop is set to '{highlightName}'.

```typescript
import ProductHighlightText from 'product-highlights/ProductHighlightText'

// Simple text display
<ProductHighlightText message="{highlightName}" />
```

--------------------------------

### Product Highlights Block Names

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/INDEX.md

List of block names for the product-highlights app, used for referencing components within VTEX's Store Framework.

```plaintext
vtex.product-highlights@2.x:product-highlights
vtex.product-highlights@2.x:product-highlight-text
vtex.product-highlights@2.x:product-highlight-wrapper
```

--------------------------------

### Access Highlight Data in Existing Components

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Integrate the `useHighlight` hook into existing components within the `ProductHighlights` tree to access highlight context. This allows for dynamic rendering based on highlight data.

```typescript
import { FC } from 'react'
import { useHighlight } from 'vtex.product-highlights'
import { useCssHandles } from 'vtex.css-handles'

const MyExistingComponent: FC = () => {
  const context = useHighlight()
  const handles = useCssHandles(['container'])

  if (!context) {
    return null
  }

  return (
    <div className={handles.container}>
      <h3>{context.highlight.name}</h3>
      <p>Type: {context.type}</p>
    </div>
  )
}

export default MyExistingComponent
```

--------------------------------

### Conditional Rendering with Context Check

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Demonstrates conditional rendering logic that includes a check for the existence of the highlight context before attempting to render content.

```typescript
function ConditionalHighlight() {
  const shouldRender = true
  const context = useHighlight()

  if (!shouldRender || !context) {
    return null
  }

  return <div>{context.highlight.name}</div>
}
```

--------------------------------

### ProductHighlightWrapper Component

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

A default exported component used to wrap product highlight content, potentially for styling or layout purposes.

```APIDOC
## ProductHighlightWrapper

### Description
Wraps product highlight content, providing a structural element that can be used for applying styles, layout adjustments, or other container-specific logic.

### Type
Component (default)

### Source
`ProductHighlightWrapper.tsx`

### Usage
Wrap highlight content
```

--------------------------------

### Access in Custom Hook

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/context-and-hooks.md

Demonstrates creating a custom hook 'useHighlightData' that encapsulates logic for accessing and transforming highlight context properties.

```typescript
function useHighlightData() {
  const context = useHighlight()

  if (!context) {
    return null
  }

  return {
    name: context.highlight.name,
    id: context.highlight.id ?? null,
    type: context.type,
    isCollection: context.type === 'collection',
    isPromotion: context.type === 'promotion',
    isTeaser: context.type === 'teaser',
  }
}

// In component:
function MyComponent() {
  const data = useHighlightData()
  // ...
}
```

--------------------------------

### Inferring ProductHighlights Props Type

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

Demonstrates how to infer the type for ProductHighlightsProps from the component itself, as direct import may not always work.

```typescript
import type { ProductHighlightsProps } from 'product-highlights' // May not work
// Instead, infer the type from the component:
import ProductHighlights from 'product-highlights/ProductHighlights'
type Props = React.ComponentProps<typeof ProductHighlights>
```

--------------------------------

### ProductHighlights Component

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

The default exported component that acts as a block provider for product highlight features.

```APIDOC
## ProductHighlights

### Description
Provides the context and functionality for product highlights on the storefront. It should be used as a block provider.

### Type
Component (default)

### Source
`ProductHighlights.tsx`

### Usage
Block provider
```

--------------------------------

### Filtered Highlights: Show Specific Promotions

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/integration-guide.md

Configure the product-highlights block to display only a specified list of promotion highlights by name. Use the 'show' filter type.

```json
{
  "vtex.product-highlights@2.x:product-highlights": {
    "props": {
      "type": "promotion",
      "filter": {
        "type": "show",
        "highlightNames": ["10% Off", "20% Off", "Hot Sale"]
      }
    },
    "children": ["product-highlight-text"]
  },
  "product-highlight-text": {
    "props": {
      "message": "{highlightName}"
    }
  }
}
```

--------------------------------

### Select SKU from Product or Selected Item

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/highlights-data-structure.md

Selects the SKU, prioritizing the `selectedItem` if available, otherwise falling back to the first item in the product's `items` array. Handles cases where `product.items` might be empty or undefined.

```typescript
const selectedSku = selectedItem ?? product?.items?.[0]
```

--------------------------------

### Define CSS Handles for ProductHighlightWrapper

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

Defines the CSS handles for the ProductHighlightWrapper component using the `useCssHandles` hook. These handles are used internally for styling.

```typescript
const CSS_HANDLES = ['productHighlightWrapper'] as const
```

--------------------------------

### Inferring ProductHighlightText Props Type

Source: https://github.com/vtex-apps/product-highlights/blob/master/_autodocs/imports-and-exports.md

Shows how to infer the Props type for ProductHighlightText by importing the component.

```typescript
import ProductHighlightText from 'product-highlights/ProductHighlightText'
type Props = React.ComponentProps<typeof ProductHighlightText>
```