@useinsider/guido 2.1.0-beta.e2d48fe → 2.1.0-beta.e4c3fa1

package/dist/src/extensions/Blocks/Recommendation/controls/spacing/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Spacing Control
+ *
+ * Manages spacing between product cards:
+ * - Column spacing: horizontal gap between cards in the same row
+ * - Row spacing: vertical gap between different rows
+ *
+ * Desktop and mobile have independent spacing controls that toggle
+ * visibility based on Stripo's editor preview mode (desktop/mobile).
+ *
+ * Configuration is stored via node config (persists with template).
+ * Actual spacing is applied to DOM elements via inline styles.
+ */
+import { type ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+import { CommonControl } from '../../../common-control';
+export declare const SPACING_CONTROL_ID = "recommendation-spacing-control";
+/**
+ * Control for managing spacing between product cards
+ * - Column spacing: horizontal gap between cards in the same row
+ * - Row spacing: vertical gap between different rows
+ * - Separate controls for desktop and mobile with device-mode toggling
+ */
+export declare class SpacingControl extends CommonControl {
+    private store;
+    private unsubscribeOrientation;
+    getId(): string;
+    getTemplate(): string;
+    onRender(): void;
+    onTemplateNodeUpdated(node: ImmutableHtmlNode): void;
+    onDestroy(): void;
+    /**
+     * Checks if the editor is currently in mobile preview mode
+     * using Stripo's EditorStatePropertyType API.
+     */
+    _isMobileMode(): boolean;
+    /**
+     * Updates spacing control visibility based on layout orientation, editor mode,
+     * and products-per-row count.
+     * - List layout: hide column spacing (products are full-width)
+     * - Desktop mode: show desktop spacing, hide mobile spacing
+     * - Mobile mode: show mobile spacing, hide desktop spacing
+     * - 1 product per row: hide column spacing (no gap between single column)
+     */
+    _updateSpacingVisibility(): void;
+    /**
+     * Reads spacing values from node config first, falls back to DOM styles.
+     * DOM fallback is only used for legacy templates that lack node config.
+     */
+    _setFormValues(): void;
+    /**
+     * Gets stored column spacing from the first attribute row cell's padding.
+     * Scoped to the desktop container for accurate readings.
+     * For grid layout: cells inside .recommendation-attribute-row have padding applied.
+     * For list layout: the parent of .product-card-wrapper has the padding.
+     * The padding is applied as "0 {halfSpacing}px", so we extract and multiply by 2.
+     */
+    _getStoredColumnSpacing(): number;
+    /**
+     * Gets stored row spacing from the first spacer element's height style
+     * Scoped to the desktop container for accurate readings.
+     */
+    _getStoredRowSpacing(): number;
+    /**
+     * Handles column spacing changes for desktop.
+     * Applies horizontal padding only to the desktop container elements.
+     */
+    _onColumnSpacingChange(spacing: number): void;
+    /**
+     * Handles row spacing changes for desktop.
+     * Applies height only to spacer elements in the desktop container.
+     */
+    _onRowSpacingChange(spacing: number): void;
+    /**
+     * Handles column spacing changes for mobile.
+     * Applies horizontal padding only to the mobile container elements.
+     */
+    _onMobileColumnSpacingChange(spacing: number): void;
+    /**
+     * Handles row spacing changes for mobile.
+     * Applies height only to spacer elements in the mobile container.
+     */
+    _onMobileRowSpacingChange(spacing: number): void;
+    /**
+     * Stores a spacing value as a data attribute on the block root element
+     */
+    _storeDataAttribute(attr: string, spacing: number): void;
+    _listenToFormUpdates(): void;
+    /**
+     * Debounced version of _onColumnSpacingChange
+     * Prevents excessive DOM updates when user rapidly adjusts the counter
+     */
+    _debouncedOnColumnSpacingChange: import("@vueuse/shared").PromisifyFn<(spacing: number) => void>;
+    /**
+     * Debounced version of _onRowSpacingChange
+     */
+    _debouncedOnRowSpacingChange: import("@vueuse/shared").PromisifyFn<(spacing: number) => void>;
+    /**
+     * Debounced version of _onMobileColumnSpacingChange
+     */
+    _debouncedOnMobileColumnSpacingChange: import("@vueuse/shared").PromisifyFn<(spacing: number) => void>;
+    /**
+     * Debounced version of _onMobileRowSpacingChange
+     */
+    _debouncedOnMobileRowSpacingChange: import("@vueuse/shared").PromisifyFn<(spacing: number) => void>;
+    /**
+     * Subscribe to store orientation changes
+     * Updates spacing visibility when layout changes via the layout control
+     */
+    _subscribeToOrientationChanges(): void;
+    /**
+     * Subscribes to editor preview mode changes via Stripo API.
+     * Toggles which spacing controls (desktop/mobile) are visible.
+     */
+    _subscribeToEditorModeChanges(): void;
+}

package/dist/src/extensions/Blocks/Recommendation/extension.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Recommendation Block Extension
+ *
+ * This extension provides a product recommendation block for email templates.
+ * Controls are organized by element type in the ./controls directory.
+ */
+/**
+ * Build and export the Recommendation extension
+ */
 declare const _default: import("@stripoinc/ui-editor-extensions").Extension;
 export default _default;

package/dist/src/extensions/Blocks/Recommendation/services/configService.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Recommendation Config Service
+ *
+ * Service for managing Recommendation block configuration via Stripo's node config API.
+ * This replaces the Pinia store for persistent configuration data.
+ *
+ * Key features:
+ * - Reads/writes config to/from node using `getNodeConfig`/`setNodeConfig`
+ * - Configuration persists with the template HTML
+ * - Each block has independent configuration (no global state)
+ * - Integrates with Stripo's undo/redo via `ModificationDescription`
+ *
+ * Usage pattern similar to legacy `blockConfigurationService`:
+ * @example
+ * // Read config
+ * const config = RecommendationConfigService.getConfig(node);
+ * // Update config
+ * RecommendationConfigService.updateConfig(api, node, { strategy: 'mostPopular' }, 'Changed algorithm');
+ * @see https://plugin.stripo.email/extensions/reference/blocks/Block
+ */
+import type { RecommendationNodeConfig, PartialNodeConfig } from '../types/nodeConfig';
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+import { ModificationDescription } from '@stripoinc/ui-editor-extensions';
+/**
+ * Stripo Extension API interface for document modifications
+ * Extracted to allow type-safe usage without importing full Stripo types
+ */
+interface DocumentModifier {
+    modifyHtml: (node: ImmutableHtmlNode) => {
+        setNodeConfig: (config: Record<string, unknown>) => DocumentModifier;
+        setAttribute: (name: string, value: string) => DocumentModifier;
+        setStyle: (prop: string, value: string) => DocumentModifier;
+        setInnerHtml: (html: string) => DocumentModifier;
+    };
+    apply: (desc: ModificationDescription) => void;
+}
+interface DocumentModifierApi {
+    getDocumentModifier: () => DocumentModifier;
+}
+/**
+ * Service for managing Recommendation block configuration
+ *
+ * All methods are static for easy usage without instantiation.
+ * The service follows the same patterns as the legacy `blockConfigurationService`.
+ */
+export declare class RecommendationConfigService {
+    /**
+     * Get configuration from a node, with defaults for missing values
+     *
+     * This is the primary way to read configuration from a block.
+     * Always returns a complete config object with defaults merged in.
+     * @example
+     * const config = RecommendationConfigService.getConfig(this.currentNode);
+     * console.log(config.strategy); // 'mostPopular'
+     * @param node - The immutable HTML node to read config from
+     * @returns Complete configuration with defaults for missing values
+     */
+    static getConfig(node: ImmutableHtmlNode | null | undefined): RecommendationNodeConfig;
+    /**
+     * Check if a node has valid configuration stored
+     *
+     * Used for migration detection - returns false for legacy templates
+     * that need their configuration migrated.
+     * @param node - The immutable HTML node to check
+     * @returns True if node has valid config with version number
+     */
+    static hasConfig(node: ImmutableHtmlNode | null | undefined): boolean;
+    /**
+     * Get the configuration version from a node
+     * @param node - The immutable HTML node to check
+     * @returns Config version number, or 0 if no config exists
+     */
+    static getConfigVersion(node: ImmutableHtmlNode | null | undefined): number;
+    /**
+     * Update specific configuration values
+     *
+     * Merges the updates with existing config and persists to node.
+     * This is the primary way to update configuration from controls.
+     * @example
+     * RecommendationConfigService.updateConfig(
+     *   this.api,
+     *   this.currentNode,
+     *   { strategy: 'complementaryItems' },
+     *   'Changed recommendation algorithm'
+     * );
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to update
+     * @param updates - Partial config with values to update
+     * @param description - Human-readable description for undo/redo
+     * @returns The new complete configuration
+     */
+    static updateConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, updates: PartialNodeConfig, description: string): RecommendationNodeConfig;
+    /**
+     * Initialize configuration for a new block
+     *
+     * Called when a block is first created (dropped into template).
+     * Can optionally merge in partial config from migration.
+     * @example
+     * // In Block.onCreated lifecycle
+     * RecommendationConfigService.initializeConfig(this.api, node);
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to initialize
+     * @param partialConfig - Optional partial config to merge with defaults
+     * @returns The initialized configuration
+     */
+    static initializeConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, partialConfig?: PartialNodeConfig): RecommendationNodeConfig;
+    /**
+     * Save complete configuration to a node
+     *
+     * Low-level method - prefer `updateConfig` or `initializeConfig` in most cases.
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to save to
+     * @param config - Complete configuration to save
+     * @param description - Human-readable description for undo/redo
+     */
+    static saveConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, config: RecommendationNodeConfig, description: string): void;
+    /**
+     * Migrate configuration from legacy data-attributes
+     *
+     * Reads existing data-attributes and creates a proper node config.
+     * Used when loading templates created before node config was implemented.
+     * @param api - Stripo extension API with document modifier
+     * @param node - The block node to migrate
+     * @returns The migrated configuration
+     */
+    static migrateFromDataAttributes(api: DocumentModifierApi, node: ImmutableHtmlNode): RecommendationNodeConfig;
+    /**
+     * Check if configuration needs migration
+     * @param node - The block node to check
+     * @returns True if migration is needed
+     */
+    static needsMigration(node: ImmutableHtmlNode | null | undefined): boolean;
+    /**
+     * Clone default config to avoid mutations
+     */
+    private static cloneDefaults;
+    /**
+     * Merge partial config with defaults
+     *
+     * Deep merges nested objects like currency, omnibus settings.
+     */
+    private static mergeWithDefaults;
+    /**
+     * Deep merge for nested objects
+     *
+     * Recursively merges source into target, preserving existing values
+     * that aren't explicitly overwritten.
+     */
+    private static deepMerge;
+}
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Recommendation Extension Services
+ *
+ * This module re-exports all services for the Recommendation extension.
+ */
+export { RecommendationConfigService } from './configService';