@useinsider/guido 2.0.0-beta.1c331b8 → 2.0.0-beta.1f72712

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/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 {};

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

@@ -0,0 +1,77 @@
+/**
+ * Node Type Guards and Tag Name Utilities
+ *
+ * Provides type-safe utilities for working with ImmutableHtmlNode.
+ * Handles both standard DOM properties and Stripo's custom methods.
+ */
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+/** Interface for nodes with standard tagName property */
+interface NodeWithTagName {
+    tagName: string;
+}
+/** Interface for nodes with getStyle method */
+export interface NodeWithGetStyle {
+    getStyle: (property: string) => string | null | undefined;
+}
+/** Interface for nodes with parent method */
+export interface NodeWithParent {
+    parent: () => ImmutableHtmlNode | null;
+}
+/**
+ * Type guard to check if a node has getStyle method
+ * @param node - The node to check
+ */
+export declare function hasGetStyle(node: unknown): node is NodeWithGetStyle;
+/**
+ * Type guard to check if a node has parent method
+ * @param node - The node to check
+ */
+export declare function hasParent(node: unknown): node is NodeWithParent;
+/**
+ * Type guard to check if a node is a TD element
+ * @param node - The node to check
+ */
+export declare function isTdNode(node: unknown): node is ImmutableHtmlNode & NodeWithTagName;
+/**
+ * Safely retrieves a style value from a node
+ * @param node - The node to get the style from
+ * @param property - The CSS property name
+ * @returns The style value or null if not accessible
+ */
+export declare function safeGetStyle(node: ImmutableHtmlNode | null, property: string): string | null | undefined;
+/**
+ * Safely retrieves the parent element of a node
+ * @param node - The node to get the parent from
+ * @returns The parent node or null if not accessible
+ */
+export declare function safeGetParent(node: ImmutableHtmlNode | null): ImmutableHtmlNode | null;
+/**
+ * Safely retrieves the tag name from a node.
+ * Handles both standard DOM tagName property and Stripo's getTagName() method.
+ * @param node - The node to get the tag name from
+ * @param defaultValue - Default value if tag name cannot be determined (default: 'UNKNOWN')
+ * @returns The uppercase tag name
+ */
+export declare function getTagName(node: ImmutableHtmlNode | null | undefined, defaultValue?: string): string;
+/**
+ * Checks if a tag name represents a table cell element.
+ * Includes standard TD and Stripo's custom block types (BLOCK_IMAGE, BLOCK_BUTTON).
+ * @param tagName - The tag name to check (case-insensitive)
+ * @returns True if the tag represents a table cell
+ */
+export declare function isTableCellTag(tagName: string): boolean;
+/**
+ * Checks if a node is a table cell element.
+ * Combines getTagName and isTableCellTag for convenience.
+ * @param node - The node to check
+ * @returns True if the node is a table cell element
+ */
+export declare function isTableCellNode(node: ImmutableHtmlNode | null | undefined): boolean;
+/**
+ * Gets the appropriate CSS display value for showing a table element.
+ * Table cells use 'table-cell', table rows use 'table-row'.
+ * @param node - The table element node
+ * @returns The CSS display value ('table-cell' or 'table-row')
+ */
+export declare function getTableDisplayValue(node: ImmutableHtmlNode | null | undefined): 'table-cell' | 'table-row';
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinsider/guido",
-  "version": "2.0.0-beta.1c331b8",
+  "version": "2.0.0-beta.1f72712",
   "description": "Guido is a Vue + TypeScript wrapper for Email Plugin. Easily embed the email editor in your Vue applications.",
   "main": "./dist/guido.umd.cjs",
   "module": "./dist/library.js",