@propeller-commerce/propeller-v2-react-ui 0.4.6

package/dist/pure.d.cts

@@ -0,0 +1,556 @@
+import * as React from 'react';
+import { Category, Cluster, Product, ProductInventory, OrderItem, Order, ProductPrice, Contact, Customer, PaginatedMediaDocumentResponse, ClusterOption, PaginatedMediaVideoResponse } from '@propeller-commerce/propeller-sdk-v2';
+import * as _propeller_commerce_propeller_v2_core_ui from '@propeller-commerce/propeller-v2-core-ui';
+import { JsonLdContext } from '@propeller-commerce/propeller-v2-core-ui';
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface BreadcrumbsProps {
+    /**
+     * The category path from the category, product or cluster response.
+     * Obtain from `category.categoryPath` or `product.category.categoryPath`.
+     */
+    categoryPath: Category[];
+    /**
+     * When true (default), the last item in the path is displayed as the
+     * current page (non-clickable, aria-current="page").
+     * When false, the last item is omitted.
+     * Ignored when `currentLabel` is provided — the extra crumb becomes
+     * the current page instead.
+     */
+    showCurrent?: boolean;
+    /**
+     * The category of the current page. When provided and not already
+     * the last item in `categoryPath`, it is appended automatically so
+     * the trail always ends at the current category. This makes the
+     * component correct whether the API's categoryPath includes the
+     * current category or only its ancestors.
+     */
+    currentCategory?: Category;
+    /**
+     * Optional trailing crumb appended after the category path — typically
+     * the name of the current product or cluster on a detail page.
+     * When provided, this crumb is marked as the current page and the
+     * last category becomes a normal link.
+     */
+    currentLabel?: string;
+    /**
+     * Optional URL for the trailing `currentLabel` crumb. When omitted,
+     * the crumb is rendered as a non-link `<span>`.
+     */
+    currentUrl?: string;
+    /**
+     * When true (default), a "Home" link is prepended to the trail.
+     */
+    showHome?: boolean;
+    /**
+     * URL for the Home link. Defaults to '/'.
+     */
+    homeUrl?: string;
+    /**
+     * Language code used to resolve localised category names and slugs.
+     * Defaults to 'NL'.
+     */
+    language?: string;
+    /**
+     * Custom URL builder for category links.
+     * Receives the Category object and its zero-based index in the path.
+     * When omitted, URLs default to `/category/{categoryId}/{slug}`.
+     */
+    getUrl?: (category: Category, index: number) => string;
+    /**
+     * Override any UI string.
+     * Available keys: home, separator
+     */
+    labels?: Record<string, string>;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+    /** Configuration object passed to the component */
+    configuration?: any;
+}
+/**
+ * Renders a breadcrumb trail from a category path, with an optional Home link
+ * and an optional trailing crumb for the current product/cluster page.
+ */
+declare function Breadcrumbs(props: BreadcrumbsProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads.
+ *
+ * Emits a `<script type="application/ld+json">` with a schema.org Product
+ * payload representing the cluster (clusters use `@type: "Product"` — schema.org
+ * has no Cluster type; the cluster's `defaultProduct` supplies brand/SKU/price/image).
+ * Returns `null` when the cluster has no usable name AND no URL.
+ */
+
+interface ClusterJsonLdProps {
+    /** The cluster to describe. */
+    cluster: Cluster;
+    /** Per-request context: siteUrl, language, currency, portalMode, user, URL builders. */
+    context: JsonLdContext;
+}
+declare function ClusterJsonLd(props: ClusterJsonLdProps): React.JSX.Element | null;
+declare const _default$3: React.MemoExoticComponent<typeof ClusterJsonLd>;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads.
+ *
+ * Emits a single `<script type="application/ld+json">` containing a schema.org
+ * `ItemList` of `Product` items, one per element in the `products` array.
+ * Scope is intentionally first-page only — caller passes whatever array is
+ * present in the initial SSR HTML; client-side filter/sort/page navigation
+ * does NOT update the script tag (crawlers only see the SSR snapshot anyway).
+ *
+ * Clusters in the response are unwrapped to their `defaultProduct` for the
+ * embedded Product node, but the ListItem URL points to the cluster page.
+ * Returns `null` when the list is empty.
+ */
+
+interface ItemListJsonLdProps {
+    /** First-page products (from server-side fetch). */
+    products: ReadonlyArray<Product>;
+    /** Per-request context: siteUrl, language, currency, portalMode, user, URL builders. */
+    context: JsonLdContext;
+}
+declare function ItemListJsonLd(props: ItemListJsonLdProps): React.JSX.Element | null;
+declare const _default$2: React.MemoExoticComponent<typeof ItemListJsonLd>;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ *
+ * Emits a single `<script type="application/ld+json">` with the schema.org
+ * Product payload built from the SDK `Product`. Returns `null` (no DOM) when
+ * the input has no usable name AND no URL. Offers are gated by portal mode
+ * (semi-closed + anonymous → no `offers` block).
+ */
+
+interface ProductJsonLdProps {
+    /** The product to describe. */
+    product: Product;
+    /** Per-request context: siteUrl, language, currency, portalMode, user, URL builders. */
+    context: JsonLdContext;
+}
+declare function ProductJsonLd(props: ProductJsonLdProps): React.JSX.Element | null;
+declare const _default$1: React.MemoExoticComponent<typeof ProductJsonLd>;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface CategoryShortDescriptionProps {
+    /**
+     * Language code used to resolve the correct localised short description
+     * from `category.shortDescription`.
+     */
+    language: string;
+    /**
+     * Propeller Category object.
+     * The component reads `category.shortDescription` (an array of LocalizedString)
+     * and renders the matching language entry as HTML.
+     */
+    category?: Category;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a category's localised HTML short description.
+ */
+declare function CategoryShortDescription(props: CategoryShortDescriptionProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface GridTitleProps {
+    /**
+     * The main heading text to display.
+     * Typically the category name, search term, or brand name.
+     */
+    title: string;
+    /**
+     * Language code for the content.
+     * Defaults to 'NL'. Resolved from `<PropellerProvider>` when not passed explicitly.
+     */
+    language?: string;
+    /**
+     * Override the heading tag level.
+     * Defaults to 'h1'. Use 'h2' when the grid is embedded inside
+     * a page that already has an h1.
+     */
+    headingLevel?: string;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders the heading for a product grid page (category, search or brand
+ * name), with a configurable heading level.
+ */
+declare function GridTitle(props: GridTitleProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ItemStockProps {
+    /**
+     * Product inventory to display stock and availability for.
+     * Required — drives all stock calculations and display logic.
+     */
+    inventory: ProductInventory;
+    /**
+     * Shows whether the product is available or not available.
+     * Defaults to true.
+     */
+    showAvailability?: boolean;
+    /**
+     * Shows the actual stock quantity (`inventory.totalQuantity`).
+     * Defaults to true.
+     */
+    showStock?: boolean;
+    /**
+     * UI string overrides.
+     * Available keys: inStock, outOfStock, lowStock, available, notAvailable, pieces
+     */
+    labels?: Record<string, string>;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders stock badges for a product: an availability indicator and/or a
+ * stock-status badge (in stock / low stock / out of stock) with quantity.
+ */
+declare function ItemStock(props: ItemStockProps): React.JSX.Element;
+declare const _default: React.MemoExoticComponent<typeof ItemStock>;
+
+interface OrderItemCardProps {
+    /** The order item to display */
+    orderItem: OrderItem;
+    /** Child order items (rendered as indented sub-rows beneath the parent) */
+    childItems?: OrderItem[];
+    /** Should the item title be a link to the PDP */
+    titleLinkable?: boolean;
+    /** Display a small thumbnail of the order item */
+    showImage?: boolean;
+    /** Should stock info be displayed */
+    showStockComponent?: boolean;
+    /** Display the SKU of the order item beneath the item name */
+    showSku?: boolean;
+    /** Display the quantity of the order item */
+    showQuantity?: boolean;
+    /** Display the price of the order item */
+    showPrice?: boolean;
+    /** Display the discount column */
+    showDiscount?: boolean;
+    /** Should the order item notes field be displayed */
+    showItemNotes?: boolean;
+    /** Render as a child/sub-item (indented, no image) */
+    isChildItem?: boolean;
+    /** Custom price formatting function */
+    formatPrice?: (price: number) => string;
+    /** Currency symbol used by the default formatter. Default: `'€'`. */
+    currency?: string;
+    /** Translated labels keyed by the slugs used inside the component (see
+     * `getLabel` calls). Missing keys fall back to the English defaults. */
+    labels?: Record<string, string>;
+    priceComponent?: React.ComponentType<_propeller_commerce_propeller_v2_core_ui.PriceComponentProps>;
+    stockComponent?: React.ComponentType<_propeller_commerce_propeller_v2_core_ui.StockComponentProps>;
+}
+/**
+ * Renders a single order line item as a table row (with optional indented
+ * child-item rows), showing image, SKU, quantity, discount and price.
+ */
+declare function OrderItemCard(props: OrderItemCardProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface OrderSummaryProps {
+    /** The order object from propeller-sdk-v2 */
+    order: any;
+    /** The CSS class for the order summary container */
+    orderSummaryContainerClass?: string;
+    /** Title of the order summary */
+    title?: string;
+    /** Show the order number */
+    showOrderNumber?: boolean;
+    /** Show the order date */
+    showOrderDate?: boolean;
+    /** Show the order status */
+    showOrderStatus?: boolean;
+    /** Show the order total */
+    showOrderTotal?: boolean;
+    /** Custom price formatting function */
+    formatPrice?: (price: number) => string;
+    /** Show the invoice address */
+    showInvoiceAddress?: boolean;
+    /** Show the delivery address */
+    showDeliveryAddress?: boolean;
+    /** Show payment, carrier, and delivery date info */
+    showDeliveryInfo?: boolean;
+    /** Show order remarks and reference */
+    showRemarks?: boolean;
+    /** Custom date formatting function */
+    formatDate?: (dateString: string) => string;
+    /** Labels for the component */
+    labels?: Record<string, string>;
+    /** List of countries for resolving codes to names [{code: 'NL', name: 'Netherlands'}, ...] */
+    countries?: {
+        code: string;
+        name: string;
+    }[];
+    /** Currency symbol used by the default formatter. Default: `'€'`. */
+    currency?: string;
+}
+/**
+ * Renders a read-only summary of an order: meta fields (number, date, status,
+ * total), invoice/delivery addresses, delivery info and remarks.
+ */
+declare function OrderSummary(props: OrderSummaryProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface OrderTotalsProps {
+    /** The order/quote used to populate the summary data */
+    order: Order;
+    /** Order summary block title */
+    title?: string;
+    /** Labels for the component */
+    labels?: Record<string, string>;
+    /** Display the subtotal of the order/quote */
+    showSubtotal?: boolean;
+    /** Display the total discount of the order/quote */
+    showDiscount?: boolean;
+    /** Display the shipping costs of the order/quote */
+    showShippingCosts?: boolean;
+    /** Display all VATs of the order/quote */
+    showVATs?: boolean;
+    /** Display the total of the order/quote excluding the VAT */
+    showTotalExclVat?: boolean;
+    /** Display the total VAT of the order/quote */
+    showTotalVat?: boolean;
+    /** Custom price formatting function */
+    formatPrice?: (price: number) => string;
+    /** Currency symbol used by the default formatter. Default: `'€'`. */
+    currency?: string;
+}
+/**
+ * Renders the price breakdown for an order or quote: subtotal, discount,
+ * transaction and shipping costs, per-rate VAT lines and the grand total.
+ */
+declare function OrderTotals(props: OrderTotalsProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ProductBulkPricesProps {
+    /**
+     * Bulk price tiers from the product.
+     * Obtain from `product.bulkPrices`.
+     */
+    bulkPrices: ProductPrice[];
+    /**
+     * When true, net price (incl. tax) is the leading price.
+     * Defaults to false — gross (excl. VAT) is shown.
+     * Note: in the Propeller SDK `price.gross` = excl. VAT, `price.net` = incl. VAT.
+     */
+    includeTax?: boolean;
+    /**
+     * Controls portal visibility mode.
+     * 'semi-closed' — component is hidden for anonymous users.
+     * Defaults to 'open'.
+     */
+    portalMode?: string;
+    /** Authenticated user — used for semi-closed visibility. */
+    user?: Contact | Customer | null;
+    /** Tax zone code. Defaults to 'NL'. */
+    taxZone?: string;
+    /** Currency symbol for prices. Defaults to '€'. */
+    currency?: string;
+    /**
+     * Override any UI string.
+     * Available keys: title, quantityFrom, price, inclTax, exclTax
+     */
+    labels?: Record<string, string>;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a product's volume/quantity-tier pricing as a table, filtering out
+ * expired or list-price tiers and showing incl./excl. VAT prices.
+ */
+declare function ProductBulkPrices(props: ProductBulkPricesProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ProductDownloadsProps {
+    /**
+     * Media documents for the product.
+     * Obtain from `product.media.documents`.
+     */
+    downloads: PaginatedMediaDocumentResponse;
+    /**
+     * Language code used to resolve the correct localised document URL and label.
+     */
+    language: string;
+    /**
+     * Override any UI string.
+     * Available keys: title, download, empty
+     */
+    labels?: Record<string, string>;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a product's downloadable media documents as a list of localised
+ * download links, or an empty-state message when there are none.
+ */
+declare function ProductDownloads(props: ProductDownloadsProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ProductPriceProps {
+    /**
+     * ProductPrice object from the product.
+     * Obtain from `product.price`.
+     */
+    price: ProductPrice;
+    /** Currency symbol to display. Defaults to '€'. */
+    currency?: string;
+    /**
+     * Controls portal visibility mode.
+     * 'open'        — full e-commerce; price is always visible.
+     * 'semi-closed' — catalog-only; price is hidden for anonymous users.
+     * Defaults to 'open'.
+     */
+    portalMode?: string;
+    /** Authenticated user — used for semi-closed visibility. */
+    user?: Contact | Customer | null;
+    /**
+     * When true, net price (incl. tax) is the leading price.
+     * When false (default), gross price (excl. tax) is the leading price.
+     * Note: in the Propeller SDK `price.gross` = excl. VAT, `price.net` = incl. VAT.
+     */
+    includeTax?: boolean;
+    /** Tax zone code. Defaults to 'NL'. */
+    taxZone?: string;
+    /** Cluster options (cluster.options). Required option default prices are added even without an active selection. */
+    options?: ClusterOption[];
+    /** Active option product selections — pass Object.values(selectedOptionProducts). Price updates on every change. */
+    selectedOptionProducts?: Product[];
+    /**
+     * Override any UI string.
+     * Available keys: inclTax, exclTax, loginToSeePrices
+     */
+    labels?: Record<string, string>;
+    /** Tailwind text-size class for the leading price. Defaults to 'text-3xl'. */
+    priceSize?: string;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a product's price with a leading incl./excl.-VAT amount and a
+ * secondary line for the other tax mode, adding selected cluster-option prices.
+ */
+declare function ProductPriceDisplay(props: ProductPriceProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. The legacy `'use client'` header was
+ * removed in C0 once verified pure. Renders directly
+ * from props and can be imported into a React Server Component.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ProductShortDescriptionProps {
+    /**
+     * Product or Cluster object.
+     * The component reads `product.shortDescriptions` (an array of LocalizedString)
+     * and renders the matching language entry as HTML.
+     */
+    product: Product | Cluster;
+    /**
+     * Language code used to resolve the correct localised short description.
+     * Defaults to 'NL'.
+     */
+    language?: string;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a product's localised short description as HTML.
+ */
+declare function ProductShortDescription(props: ProductShortDescriptionProps): React.JSX.Element;
+
+/**
+ * @rsc-safe — Pure display component. No React hooks, no event handlers, no
+ * browser APIs, no context reads. Renders directly from props and can be
+ * imported into a React Server Component without a 'use client' boundary.
+ * Verified C0.2 (2026-05-20).
+ */
+
+interface ProductVideosProps {
+    /**
+     * Media videos for the product.
+     * Obtain from `product.media.videos`.
+     */
+    videos: PaginatedMediaVideoResponse;
+    /**
+     * Language code used to resolve the correct localised video URI.
+     */
+    language: string;
+    /**
+     * Override any UI string.
+     * Available keys: title, empty
+     */
+    labels?: Record<string, string>;
+    /** Extra CSS class applied to the root element. */
+    className?: string;
+}
+/**
+ * Renders a product's media videos, embedding YouTube/Vimeo URLs in an iframe
+ * and other URLs in a native `<video>` player.
+ */
+declare function ProductVideos(props: ProductVideosProps): React.JSX.Element;
+
+export { Breadcrumbs, type BreadcrumbsProps, CategoryShortDescription, type CategoryShortDescriptionProps, _default$3 as ClusterJsonLd, type ClusterJsonLdProps, GridTitle, type GridTitleProps, _default$2 as ItemListJsonLd, type ItemListJsonLdProps, _default as ItemStock, type ItemStockProps, OrderItemCard, type OrderItemCardProps, OrderSummary, type OrderSummaryProps, OrderTotals, type OrderTotalsProps, ProductBulkPrices, type ProductBulkPricesProps, ProductDownloads, type ProductDownloadsProps, _default$1 as ProductJsonLd, type ProductJsonLdProps, ProductPriceDisplay as ProductPrice, type ProductPriceProps, ProductShortDescription, type ProductShortDescriptionProps, ProductVideos, type ProductVideosProps };