@useinsider/guido 2.0.0-beta.a4f9fa2 → 2.0.0-beta.a7d687e

package/dist/src/extensions/Blocks/Recommendation/store/recommendation.d.ts

@@ -1,5 +1,6 @@
 import type { Orientation, Languages, Currency, NumericSeparator, FiltersResponse, Filter, RecommendationProduct } from '@@/Types/recommendation';
 interface StoreState {
+    /** Maps campaign URLs for recommendation blocks. Used by templateLibraryApi when saving templates. */
     recommendationCampaignUrls: Record<string, string>;
     recommendationConfigs: {
         cardsInRow: number;
@@ -18,8 +19,8 @@ interface StoreState {
         orientation: Orientation;
         productIds: string[];
         recommendedProducts: [];
-        sendProductRequestFlag: false;
-        shuffleProducts: false;
+        sendProductRequestFlag: boolean;
+        shuffleProducts: boolean;
         strategy: string;
         textTrimming: boolean;
         unresponsive: boolean;
@@ -65,8 +66,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -134,8 +135,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -203,8 +204,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -275,8 +276,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -347,8 +348,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -419,8 +420,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;
@@ -492,8 +493,8 @@ export declare const useRecommendationExtensionStore: import("pinia").StoreDefin
             orientation: Orientation;
             productIds: string[];
             recommendedProducts: [];
-            sendProductRequestFlag: false;
-            shuffleProducts: false;
+            sendProductRequestFlag: boolean;
+            shuffleProducts: boolean;
             strategy: string;
             textTrimming: boolean;
             unresponsive: boolean;

package/dist/src/extensions/Blocks/Recommendation/templates/horizontal/elementRenderer.d.ts

@@ -0,0 +1,8 @@
+import type { ElementRenderer } from '../utils';
+/**
+ * Horizontal element renderer
+ * - Image and Button return `<td>` cells for the 3-column layout
+ * - Name and Prices return `<tr><td>` rows for the info cell table
+ * All elements have esd-block-* classes for Stripo selection
+ */
+export declare const horizontalElementRenderer: ElementRenderer;

package/dist/src/extensions/Blocks/Recommendation/templates/horizontal/migration.d.ts

@@ -0,0 +1,25 @@
+import type { RecommendationProduct } from '@@/Types/recommendation';
+import { DEFAULTS, getDefaultProducts } from '../utils';
+/**
+ * Migration template for horizontal layout
+ * Used when migrating old recommendation blocks to horizontal format
+ */
+declare const migrationTemplate = "\n    <td\n        align=\"left\"\n        esd-extension-block-id=\"recommendation-block\"\n        esd-handler-name=\"esd-extension-RecommendationBlock\"\n        class=\"ins-recommendation-v3-block-v2 esd-block-recommendation-v3-block esd-extension-block es-p20\"\n        data-layout=\"horizontal\"\n    >\n        <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n            <tr>\n                <td align=\"center\">\n                    <table\n                        class=\"container\"\n                        width=\"100%\"\n                        cellpadding=\"0\"\n                        cellspacing=\"0\"\n                        border=\"0\">\n                        <tbody>\n                            <tr>\n                                <td>\n                                    <table\n                                        width=\"100%\"\n                                        cellpadding=\"0\"\n                                        cellspacing=\"0\"\n                                        border=\"0\">\n                                        <tbody>\n                                            <tr>\n                                                {-{-TITLE-}-}\n                                            </tr>\n                                        </tbody>\n                                    </table>\n                                </td>\n                            </tr>\n                            <tr>\n                                <td class=\"spacer\" style=\"height: 20px;\"></td>\n                            </tr>\n                            <tr>\n                                <td>\n                                    <table\n                                        class=\"ins-recommendation-product-container\"\n                                        width=\"100%\"\n                                        cellpadding=\"0\"\n                                        cellspacing=\"0\"\n                                        border=\"0\"\n                                    >\n                                        {-{-PRODUCT_ROWS-}-}\n                                    </table>\n                                </td>\n                            </tr>\n                        </tbody>\n                    </table>\n                </td>\n            </tr>\n        </table>\n    </td>\n";
+export declare function getMigrationTemplate(): string;
+/**
+ * Generates a custom horizontal migration template with specified products
+ * @param products - Array of products to display
+ * @param title - Optional title for the block
+ * @param composition - Optional array defining order of card elements
+ * @returns Complete HTML template
+ */
+export declare function generateMigrationTemplate(products: RecommendationProduct[], title?: string, composition?: string[]): string;
+/**
+ * Prepares horizontal product rows for migration
+ * @param products - Array of products to display
+ * @param composition - Optional array defining order of card elements
+ * @returns HTML string for product rows
+ */
+export declare function prepareProductRows(products: RecommendationProduct[], composition?: string[]): string;
+export { DEFAULTS, getDefaultProducts };
+export default migrationTemplate;

package/dist/src/extensions/Blocks/Recommendation/templates/horizontal/template.d.ts

@@ -0,0 +1,18 @@
+import type { RecommendationProduct } from '@@/Types/recommendation';
+/**
+ * Generates a horizontal product card with 3-column layout
+ * Uses horizontalElementRenderer to render Image, Info content, and Button
+ * Layout: [Image (120px)] [Info table (flexible)] [Button (100px)]
+ * @param product - The product data
+ * @returns HTML string for a single product card row
+ */
+export declare function getHorizontalProductCard(product: RecommendationProduct): string;
+/**
+ * Prepares horizontal product rows
+ * Each product is a full-width row with 3-column layout
+ * @param products - Array of products to display
+ * @returns HTML string for product rows
+ */
+export declare function prepareProductRows(products: RecommendationProduct[]): string;
+export declare function getDefaultTemplate(): string;
+export declare function generateBlockTemplate(products: RecommendationProduct[], title?: string): string;

package/dist/src/extensions/Blocks/Recommendation/templates/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Unified Template API for Recommendation Block
+ *
+ * This module provides a single entry point for working with recommendation
+ * block templates, abstracting away the layout-specific implementations.
+ */
+import type { RecommendationProduct } from '@@/Types/recommendation';
+import { type Orientation, type PrepareProductRowsOptions } from './utils';
+export { DEFAULTS, DEFAULT_CARD_COMPOSITION, DEFAULT_CARD_VISIBILITY, getDefaultProducts, spacer, sanitizeImageUrl, createBlockTemplate, type Orientation, type PrepareProductRowsOptions, type ElementRenderer, type ProductCardGetter, } from './utils';
+/**
+ * Unified function to prepare product rows for any layout.
+ * Delegates to the appropriate layout-specific implementation.
+ * @example
+ * // Horizontal layout (full-width rows)
+ * prepareProductRows(products, 'horizontal');
+ * @example
+ * // Vertical layout (grid)
+ * prepareProductRows(products, 'vertical', { productsPerRow: 3 });
+ * @param products - Array of products to display
+ * @param layout - The layout orientation ('horizontal' or 'vertical')
+ * @param options - Layout-specific options
+ * @returns HTML string for product rows
+ */
+export declare function prepareProductRows(products: RecommendationProduct[], layout: Orientation, options?: PrepareProductRowsOptions): string;
+/**
+ * Generates the default template for a given layout.
+ * @param layout - The layout orientation ('horizontal' or 'vertical')
+ * @returns Complete HTML template with default products
+ */
+export declare function getDefaultTemplate(layout?: Orientation): string;
+/**
+ * Generates a complete block template with custom products.
+ * @param products - Array of products to display
+ * @param layout - The layout orientation ('horizontal' or 'vertical')
+ * @param title - Title for the block
+ * @param options - Layout-specific options
+ * @returns Complete HTML template
+ */
+export declare function generateBlockTemplate(products: RecommendationProduct[], layout: Orientation, title?: string, options?: PrepareProductRowsOptions): string;

package/dist/src/extensions/Blocks/Recommendation/templates/utils.d.ts

@@ -0,0 +1,54 @@
+import type { RecommendationProduct } from '@@/Types/recommendation';
+import { ATTR_PRODUCT_IMAGE, ATTR_PRODUCT_NAME, ATTR_PRODUCT_PRICE, ATTR_PRODUCT_OLD_PRICE, ATTR_PRODUCT_OMNIBUS_PRICE, ATTR_PRODUCT_OMNIBUS_DISCOUNT, ATTR_PRODUCT_BUTTON } from '../constants';
+export type Orientation = 'horizontal' | 'vertical';
+/**
+ * Options for prepareProductRows unified function
+ */
+export interface PrepareProductRowsOptions {
+    /** Number of products per row (only for vertical layout, defaults to 3) */
+    productsPerRow?: number;
+    /** Array defining order of card elements */
+    composition?: string[];
+}
+/**
+ * Element renderer interface for product card elements
+ * Keys are ATTR_PRODUCT_* constants for consistent naming
+ */
+export interface ElementRenderer {
+    [ATTR_PRODUCT_IMAGE]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_NAME]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_PRICE]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_OLD_PRICE]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_OMNIBUS_PRICE]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_OMNIBUS_DISCOUNT]: (product: RecommendationProduct) => string;
+    [ATTR_PRODUCT_BUTTON]: (product: RecommendationProduct) => string;
+}
+/**
+ * Product card getter function type
+ * Used by prepareProductRows to generate individual product cards
+ */
+export type ProductCardGetter = (product: RecommendationProduct, composition?: string[]) => string;
+export declare const DEFAULTS: {
+    TITLE: string;
+    DESCRIPTION: string;
+};
+export declare const DEFAULT_CARD_COMPOSITION: string[];
+export declare const DEFAULT_CARD_VISIBILITY: Record<string, boolean>;
+export declare const spacer = "\n    <tr>\n        <td class=\"spacer\" style=\"height: 10px;\"></td>\n    </tr>\n";
+export declare const PLACEHOLDER_IMAGE = "https://email-static.useinsider.com/stripo/modules/email-recommendation-v3/assets/images/image-placeholder.png";
+/**
+ * Sanitizes product image URLs for consistent rendering
+ * - Converts http:// to https:// to avoid mixed content issues
+ * - Returns placeholder for invalid/empty URLs
+ * @param url - The image URL to sanitize
+ * @returns Sanitized HTTPS URL or placeholder
+ */
+export declare function sanitizeImageUrl(url: string | undefined | null): string;
+export declare function getDefaultProducts(): RecommendationProduct[];
+/**
+ * Creates the block template wrapper HTML for recommendation blocks.
+ * The template includes title placeholder and product container.
+ * @param layout - The layout orientation ('horizontal' or 'vertical')
+ * @returns HTML template string with {-{-TITLE-}-} and {-{-PRODUCT_ROWS-}-} placeholders
+ */
+export declare function createBlockTemplate(layout?: Orientation): string;

package/dist/src/extensions/Blocks/Recommendation/templates/vertical/elementRenderer.d.ts

@@ -0,0 +1,20 @@
+import type { ElementRenderer } from '../utils';
+/**
+ * Vertical element renderer
+ * Each element returns a `<td>` containing a nested table structure:
+ * - Outer `<td>` has padding for column spacing
+ * - Inner `<table class="product-card-segment">` supports background color
+ * - Content is inside the inner table
+ *
+ * This structure allows:
+ * 1. Row-based alignment (all same attributes in one row)
+ * 2. Per-card background color via inner table
+ * 3. Column spacing via outer cell padding
+ */
+export declare const DEFAULT_CELL_PADDING = "0 5px";
+/**
+ * Class name for outer cells in attribute rows
+ * Used by controls to reliably select direct children for spacing adjustments
+ */
+export declare const ATTRIBUTE_CELL_CLASS = "attribute-cell";
+export declare const verticalElementRenderer: ElementRenderer;

package/dist/src/extensions/Blocks/Recommendation/templates/{migrationTemplate.d.ts → vertical/migration.d.ts}

@@ -1,9 +1,17 @@
 import type { RecommendationProduct } from '@@/Types/recommendation';
-import { DEFAULTS, getDefaultProducts } from './templateUtils';
+import { DEFAULTS, getDefaultProducts, DEFAULT_CARD_COMPOSITION, DEFAULT_CARD_VISIBILITY } from '../utils';
 declare const migrationTemplate = "\n    <td\n        align=\"left\"\n        esd-extension-block-id=\"recommendation-block\"\n        esd-handler-name=\"esd-extension-RecommendationBlock\"\n        class=\"ins-recommendation-v3-block-v2 esd-block-recommendation-v3-block esd-extension-block es-p20\"\n    >\n        <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n            <tr>\n                <td align=\"center\">\n                    <table\n                        class=\"container\"\n                        width=\"100%\"\n                        cellpadding=\"0\"\n                        cellspacing=\"0\"\n                        border=\"0\">\n                        <tbody>\n                            <tr>\n                                <td>\n                                    <table\n                                        width=\"100%\"\n                                        cellpadding=\"0\"\n                                        cellspacing=\"0\"\n                                        border=\"0\">\n                                        <tbody>\n                                            <tr>\n                                                {-{-TITLE-}-}\n                                            </tr>\n                                        </tbody>\n                                    </table>\n                                </td>\n                            </tr>\n                            <tr>\n                                <td class=\"spacer\" style=\"height: 20px;\"></td>\n                            </tr>\n                            <tr>\n                                <td>\n                                    <table\n                                        class=\"ins-recommendation-product-container\"\n                                        width=\"100%\"\n                                        cellpadding=\"0\"\n                                        cellspacing=\"0\"\n                                        border=\"0\"\n                                    >\n                                        {-{-PRODUCT_ROWS-}-}\n                                    </table>\n                                </td>\n                            </tr>\n                        </tbody>\n                    </table>\n                </td>\n            </tr>\n        </table>\n    </td>\n";
+/**
+ * Prepares migration product rows with attribute-aligned structure.
+ * @param products - Array of products to display
+ * @param productsPerRow - Number of products per row
+ * @param composition - Array defining element order
+ * @returns HTML string for product rows
+ */
+export declare function prepareProductRows(products: RecommendationProduct[], productsPerRow: number, composition?: string[]): string;
 export declare function getMigrationTemplate(): string;
 /**
- * Generates a custom migration template with specified products and layout
+ * Generates a custom migration template with specified products and layout.
  * @param products - Array of products to display
  * @param productsPerRow - Number of products per row
  * @param title - Optional title for the block
@@ -11,6 +19,5 @@ export declare function getMigrationTemplate(): string;
  * @returns Complete HTML template
  */
 export declare function generateMigrationTemplate(products: RecommendationProduct[], productsPerRow: number, title?: string, composition?: string[]): string;
-export declare function prepareProductRows(products: RecommendationProduct[], productsPerRow: number, composition?: string[]): string;
-export { DEFAULTS, getDefaultProducts };
+export { DEFAULTS, DEFAULT_CARD_COMPOSITION, DEFAULT_CARD_VISIBILITY, getDefaultProducts, };
 export default migrationTemplate;

package/dist/src/extensions/Blocks/Recommendation/templates/vertical/template.d.ts

@@ -0,0 +1,33 @@
+import type { RecommendationProduct } from '@@/Types/recommendation';
+import { type ElementRenderer } from '../utils';
+/**
+ * Generates attribute-aligned product rows for vertical layout.
+ * Creates rows where each row contains one attribute type from all products.
+ * @param products - Array of products in this row group
+ * @param productsPerRow - Number of products per row (for column width calculation)
+ * @param elementRenderer - Object mapping attribute types to render functions
+ * @param composition - Array defining order of card elements
+ * @returns HTML string for attribute-aligned rows
+ */
+export declare function prepareVerticalAttributeRows(products: RecommendationProduct[], productsPerRow: number, elementRenderer: ElementRenderer, composition?: string[]): string;
+/**
+ * Prepares vertical product rows with attribute-aligned structure
+ * Groups products into rows, then generates attribute-aligned HTML for each group
+ * @param products - Array of products to display
+ * @param productsPerRow - Number of products per row
+ * @param elementRenderer - Object mapping attribute types to render functions
+ * @param composition - Array defining order of card elements
+ * @returns HTML string for all product rows
+ */
+export declare function prepareVerticalProductRows(products: RecommendationProduct[], productsPerRow: number, elementRenderer: ElementRenderer, composition?: string[]): string;
+/**
+ * Prepares vertical product rows with attribute-aligned structure.
+ * Uses row-based rendering where each attribute type forms a single row across all products.
+ * @param products - Array of products to display
+ * @param productsPerRow - Number of products per row
+ * @param composition - Array defining element order
+ * @returns HTML string for product rows
+ */
+export declare function prepareProductRows(products: RecommendationProduct[], productsPerRow: number, composition?: string[]): string;
+export declare function getDefaultTemplate(): string;
+export declare function generateBlockTemplate(products: RecommendationProduct[], productsPerRow: number, title?: string, composition?: string[]): string;

package/dist/src/extensions/Blocks/Recommendation/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recommendation Extension Types
+ *
+ * This module re-exports all type definitions for the Recommendation extension.
+ */
+export type { RecommendationNodeConfig, CurrencyConfig, OmnibusTextConfig, PartialNodeConfig, DeepPartialNodeConfig, } from './nodeConfig';
+export { isValidNodeConfig, hasMinimalConfig, } from './nodeConfig';

package/dist/src/extensions/Blocks/Recommendation/types/nodeConfig.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Node Configuration Types for Recommendation Block
+ *
+ * This module defines the TypeScript interfaces for configuration data
+ * stored via Stripo's `setNodeConfig`/`getNodeConfig` APIs.
+ *
+ * The configuration persists with the template HTML, solving:
+ * - Configuration loss on save/reload
+ * - Multi-block independence
+ * - Undo/redo integration
+ * @see https://plugin.stripo.email/extensions/reference/blocks/Block
+ */
+import type { Filter } from '@@/Types/recommendation';
+/**
+ * Currency display and formatting settings
+ */
+export interface CurrencyConfig {
+    /** Currency code (e.g., 'USD', 'EUR', 'TRY') */
+    code: string;
+    /** Currency symbol (e.g., '$', '€', '₺') */
+    symbol: string;
+    /** Symbol position relative to price */
+    alignment: 'before' | 'after';
+    /** Number of decimal places (-1 for no formatting) */
+    decimalCount: number;
+    /** Character used for decimal separation */
+    decimalSeparator: '.' | ',';
+    /** Character used for thousands separation */
+    thousandSeparator: '.' | ',' | ' ' | '';
+}
+/**
+ * Configuration for omnibus price/discount text wrappers
+ * Used to display EU Omnibus Directive compliant pricing
+ */
+export interface OmnibusTextConfig {
+    /** Text to prepend (e.g., 'Lowest 30-day price: ') */
+    textBefore: string;
+    /** Text to append */
+    textAfter: string;
+}
+/**
+ * Complete configuration schema for Recommendation Block
+ *
+ * This interface combines:
+ * - Legacy `esd-dev-product-config` structure patterns
+ * - Current data-attribute based settings
+ * - Campaign data that was previously in Pinia store
+ *
+ * All properties are persisted with the template via `setNodeConfig`.
+ */
+export interface RecommendationNodeConfig {
+    /**
+     * Recommendation algorithm/strategy
+     * @example 'mostPopular', 'complementaryItems', 'manualMerchandising'
+     */
+    strategy: string;
+    /**
+     * Product IDs for manual merchandising strategy
+     * Only used when strategy === 'manualMerchandising'
+     */
+    productIds: string[];
+    /**
+     * Number of products to fetch from API
+     * Stored as string for consistency with API params
+     */
+    size: string;
+    /**
+     * Whether to randomize product order on each load
+     */
+    shuffleProducts: boolean;
+    /**
+     * Locale/language for product data
+     * @example 'en_US', 'tr_TR', 'de_DE'
+     */
+    language: string;
+    /**
+     * Currency display and formatting configuration
+     */
+    currency: CurrencyConfig;
+    /**
+     * Product filters for narrowing recommendations
+     * Uses existing Filter interface from recommendation types
+     */
+    filters: Filter[];
+    /**
+     * Layout orientation
+     * - 'vertical': Products in a grid, attributes aligned across products
+     * - 'horizontal': Products in rows, each product is a full-width card
+     */
+    layout: 'vertical' | 'horizontal';
+    /**
+     * Number of products per row (vertical layout only)
+     */
+    cardsInRow: number;
+    /**
+     * Horizontal spacing between product cards in pixels (vertical layout only)
+     */
+    columnSpacing: number;
+    /**
+     * Vertical spacing between product rows in pixels
+     */
+    rowSpacing: number;
+    /**
+     * Order of card elements from top to bottom
+     * Array of ATTR_PRODUCT_* constants
+     * @example ['productImage', 'productName', 'productPrice', 'productButton']
+     */
+    composition: string[];
+    /**
+     * Visibility flags for each card element
+     * Keys are ATTR_PRODUCT_* constants
+     */
+    visibility: Record<string, boolean>;
+    /**
+     * Omnibus price text configuration
+     * For EU Omnibus Directive compliance
+     */
+    omnibusPrice: OmnibusTextConfig;
+    /**
+     * Omnibus discount text configuration
+     * For EU Omnibus Directive compliance
+     */
+    omnibusDiscount: OmnibusTextConfig;
+    /**
+     * Whether to trim long product names with ellipsis
+     */
+    textTrimming: boolean;
+    /**
+     * Configuration version for future migrations
+     * Increment when making breaking changes to schema
+     */
+    configVersion: number;
+}
+/**
+ * Partial configuration for updates
+ * All fields are optional to support partial updates via `updateConfig`
+ */
+export type PartialNodeConfig = Partial<RecommendationNodeConfig>;
+/**
+ * Deep partial for nested objects
+ */
+export type DeepPartialNodeConfig = {
+    [K in keyof RecommendationNodeConfig]?: RecommendationNodeConfig[K] extends object ? Partial<RecommendationNodeConfig[K]> : RecommendationNodeConfig[K];
+};
+/**
+ * Check if an object is a valid RecommendationNodeConfig
+ * Used for migration detection and validation
+ */
+export declare function isValidNodeConfig(obj: unknown): obj is RecommendationNodeConfig;
+/**
+ * Check if a node config has the minimum required fields
+ * Used to detect legacy templates that need migration
+ */
+export declare function hasMinimalConfig(obj: unknown): boolean;

package/dist/src/extensions/Blocks/Recommendation/utils/preserveTextStyles.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility for preserving text styling when updating innerHTML
+ */
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+/**
+ * Preserves existing style tags when updating text content
+ *
+ * When users apply text styles (bold, italic, etc.) in Stripo, the editor wraps
+ * content in tags like <strong>, <em>, <u>, <s>. This function extracts those
+ * style tags from the original HTML and re-applies them to the new text content.
+ * @example
+ * // Original: <span class="omnibus-text-before"><strong>Lowest price: </strong></span>
+ * // After calling preserveTextStyles(element, 'Best price: ')
+ * // Result: <strong>Best price: </strong>
+ * @param element - The DOM element or ImmutableHtmlNode containing the styled text
+ * @param newText - The new text content to insert
+ * @returns The new text wrapped in the original style tags
+ */
+export declare function preserveTextStyles(element: ImmutableHtmlNode | Element, newText: string): string;

package/dist/src/extensions/Blocks/Recommendation/utils/priceFormatter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Price Formatting Utilities
+ *
+ * Provides functions for formatting prices according to currency settings.
+ * Used to format prices displayed in recommendation product cards.
+ */
+import type { CurrencyConfig } from '../types/nodeConfig';
+/**
+ * Options for formatting a price
+ */
+export interface FormatPriceOptions {
+    /** The numeric price value */
+    price: number;
+    /** Currency configuration */
+    currency: CurrencyConfig;
+}
+/**
+ * Formats a numeric price according to currency settings
+ * @example
+ * // Returns: "$ 1,999.99"
+ * formatPrice({ price: 1999.99, currency: currencyConfig })
+ * @param options - Formatting options
+ * @returns Formatted price string
+ */
+export declare function formatPrice(options: FormatPriceOptions): string;
+/**
+ * Parses a formatted price string back to a number
+ * Useful for extracting numeric values from formatted price displays
+ * @param formattedPrice - The formatted price string
+ * @param currency - Currency configuration for parsing
+ * @returns Parsed numeric value or NaN if parsing fails
+ */
+export declare function parseFormattedPrice(formattedPrice: string, currency: CurrencyConfig): number;

package/dist/src/extensions/Blocks/Recommendation/utils/stylePreserver.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Style Preserver Utility
+ *
+ * Captures and restores element styles during block regeneration.
+ * This ensures user styling is preserved when:
+ * - Layout changes (vertical <-> horizontal)
+ * - Cards per row changes
+ * - Composition order changes
+ *
+ * Works with the node config system to provide complete style persistence.
+ */
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+import { ModificationDescription } from '@stripoinc/ui-editor-extensions';
+/**
+ * Style properties that can be captured for text elements
+ */
+export interface TextElementStyles {
+    fontSize?: string;
+    fontFamily?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    color?: string;
+    textAlign?: string;
+    lineHeight?: string;
+    textDecoration?: string;
+}
+/**
+ * Style properties for button elements
+ */
+export interface ButtonElementStyles extends TextElementStyles {
+    backgroundColor?: string;
+    borderRadius?: string;
+    border?: string;
+    padding?: string;
+}
+/**
+ * Style properties for image elements
+ */
+export interface ImageElementStyles {
+    width?: string;
+    height?: string;
+    maxWidth?: string;
+}
+/**
+ * Complete captured styles for a recommendation block
+ */
+export interface CapturedStyles {
+    /** Product name text styles */
+    name: TextElementStyles;
+    /** Current price text styles */
+    price: TextElementStyles;
+    /** Original/old price text styles */
+    oldPrice: TextElementStyles;
+    /** Omnibus price text styles */
+    omnibusPrice: TextElementStyles;
+    /** Omnibus discount text styles */
+    omnibusDiscount: TextElementStyles;
+    /** CTA button styles */
+    button: ButtonElementStyles;
+    /** Product image styles */
+    image: ImageElementStyles;
+    /** Card background color */
+    cardBackgroundColor: string | null;
+    /** Column spacing in pixels */
+    columnSpacing: number;
+    /** Row spacing in pixels */
+    rowSpacing: number;
+    /** Element composition order */
+    composition: string[];
+    /** Element visibility flags */
+    visibility: Record<string, boolean>;
+}
+type DocumentModifier = {
+    modifyHtml: (node: ImmutableHtmlNode) => {
+        setStyle: (prop: string, value: string) => DocumentModifier;
+    };
+    apply: (description: ModificationDescription) => void;
+};
+/**
+ * Capture all styles from a recommendation block
+ *
+ * Call this BEFORE any operation that regenerates the block HTML.
+ * The captured styles can then be restored after regeneration.
+ * @example
+ * // Before layout change
+ * const styles = captureStyles(this.currentNode);
+ *
+ * // ... regenerate block HTML ...
+ *
+ * // After regeneration
+ * restoreStyles(this.currentNode, this.api.getDocumentModifier(), styles);
+ * @param node - The block node to capture styles from
+ * @returns Complete captured styles object
+ */
+export declare function captureStyles(node: ImmutableHtmlNode | null | undefined): CapturedStyles;
+/**
+ * Restore captured styles to a regenerated block
+ *
+ * Call this AFTER regenerating block HTML to reapply user styling.
+ * @example
+ * restoreStyles(this.currentNode, this.api.getDocumentModifier(), capturedStyles);
+ * @param node - The block node to restore styles to
+ * @param modifier - Document modifier for applying changes
+ * @param styles - Previously captured styles
+ */
+export declare function restoreStyles(node: ImmutableHtmlNode | null | undefined, modifier: DocumentModifier, styles: CapturedStyles): void;
+/**
+ * Check if styles have meaningful content worth restoring
+ * @param styles - Captured styles to check
+ * @returns True if styles contain restorable content
+ */
+export declare function hasRestorableStyles(styles: CapturedStyles): boolean;
+export {};