@circlehq/block-product-list

An email block that repeats the products of a cart or order. It renders a Liquid loop over event.line_items (name, variant, quantity, price, with a fallback line when there are none). The server fills the loop in when the email is sent.

Repeat for each product (ProductRepeat)

A container block whose children are repeated once per product, so every row is fully editable (Text, Heading, Button, Divider, columns...). Inside it, blocks can use {{ item.title }}, {{ item.variant_title }}, {{ item.sku }}, {{ item.quantity }} and {{ item.price | money }}.

props: childrenIds and emptyText (shown when there are no products; blank shows nothing). style has the same fields as the Container block.

The reader component needs the Reader's document, so it lives in @circlehq/email-builder (ProductRepeat in its dictionary). This package provides the schema (ProductRepeatPropsSchema), the Liquid pieces (PRODUCT_REPEAT_OPEN / _ELSE / _CLOSE), the variables an editor can offer (PRODUCT_ITEM_VARIABLES) and the preview helpers (PRODUCT_SAMPLE_ITEMS, fillSampleItem).

Exports

| Export | Purpose | |---|---| | ProductList | The block component, for a Reader dictionary | | ProductListPropsSchema / ProductListProps | zod schema and type of the block's style and props | | ProductListPreviewContext | Provide true to show example products instead of the loop (editor previews) | | productListLiquid(props) / productListSample(props) | The HTML of each rendering | | PRODUCT_LIST_VARIABLE, DEFAULT_EMPTY_TEXT | The variable path and the default fallback text |

props: showVariant, showQuantity, showPrice (default true) and emptyText. style has the same fields as the Html block.

Adding it to @circlehq/email-builder

1. npm i @circlehq/block-product-list and list it under dependencies.
2. In src/Reader/core, import and register it next to Html and Socials:

import { ProductList, ProductListPropsSchema } from '@circlehq/block-product-list';

const READER_DICTIONARY = buildBlockConfigurationDictionary({
  // ...existing blocks
  ProductList: { schema: ProductListPropsSchema, Component: ProductList },
});

3. Re-export ProductListPreviewContext from the package index so editors can wrap their preview Reader in it.
4. Publish both packages (this one first).

Using it in the webapp

• Editor dictionary (src/emailBuilder/components/documents/editor/core.tsx): schema: ProductListPropsSchema, and a canvas component that renders <ProductListPreviewContext.Provider value={true}><ProductList {...props} /></ProductListPreviewContext.Provider>.
• Preview tab: wrap the Reader in the same provider.
• Sent HTML: renderToStaticMarkup from the package renders the block as the Liquid loop with no extra step.

Develop

npm install
npm test
npm run build