@useinsider/guido 3.0.0 → 3.1.0

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

@@ -0,0 +1,105 @@
+/**
+ * Custom Attribute Element Controls
+ *
+ * Controls for styling custom product attribute elements in recommendation cards.
+ *
+ * Unlike built-in elements (Name, Price, etc.) where all instances share a single
+ * block ID and should be styled uniformly, custom attributes are conceptually
+ * different elements (e.g., "brand" vs "rating_star") that need independent styling.
+ *
+ * Each custom attribute element carries a unique `product-attr` HTML attribute
+ * (e.g., `product-attr="product_attribute.brand"`). The controls below use this
+ * attribute to scope style changes to only the same attribute type across all
+ * product cards — changing "brand" color won't affect "rating_star" color.
+ */
+import { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+/**
+ * Grouped Custom Attribute Controls
+ * Use this object for cleaner imports in extension.ts
+ */
+export declare const CustomAttributeControls: {
+    readonly align: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly color: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly size: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly style: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly fontFamily: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly background: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+    readonly paddings: {
+        new (): {
+            getId(): string;
+            getTargetNodes(root: ImmutableHtmlNode): ImmutableHtmlNode[];
+            getParentControlId(): string;
+            api: import("@stripoinc/ui-editor-extensions").ControlApi;
+            getLabels(): import("@stripoinc/ui-editor-extensions").ControlLabels | undefined;
+            getModificationDescription(): import("@stripoinc/ui-editor-extensions").ModificationDescription | undefined;
+            getAdditionalModifications(_root: ImmutableHtmlNode): import("@stripoinc/ui-editor-extensions").TemplateModifier<import("@stripoinc/ui-editor-extensions").HtmlNodeModifier, import("@stripoinc/ui-editor-extensions").CssNodeModifier> | undefined;
+            isVisible(_node: ImmutableHtmlNode): boolean;
+        };
+    };
+};

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

@@ -9,7 +9,7 @@
  * // Or individual imports
  * import { NameAlignControl, ButtonColorControl } from './controls';
  */
-export { RecommendationBlockControl, CONTROL_BLOCK_ID, AlgorithmControl, ALGORITHM_CONTROL_ID, LocaleControl, LOCALE_CONTROL_ID, CurrencyControl, CURRENCY_CONTROL_ID, ProductLayoutControl, PRODUCT_LAYOUT_CONTROL_ID, FiltersControl, FILTERS_CONTROL_ID, ShuffleControl, SHUFFLE_CONTROL_ID, } from './main';
+export { RecommendationBlockControl, CONTROL_BLOCK_ID, AlgorithmControl, ALGORITHM_CONTROL_ID, LocaleControl, LOCALE_CONTROL_ID, CurrencyControl, CURRENCY_CONTROL_ID, ProductCountControl, PRODUCT_COUNT_CONTROL_ID, ProductLayoutControl, PRODUCT_LAYOUT_CONTROL_ID, FiltersControl, FILTERS_CONTROL_ID, ShuffleControl, SHUFFLE_CONTROL_ID, LayoutOrientationControl, LAYOUT_ORIENTATION_CONTROL_ID, } from './main';
 export * from './main/utils';
 export { NameControls } from './name';
 export { PriceControls } from './price';
@@ -18,7 +18,8 @@ export { OmnibusPriceControls } from './omnibusPrice';
 export { OmnibusDiscountControls } from './omnibusDiscount';
 export { ButtonControls } from './button';
 export { ImageControls } from './image';
+export { CustomAttributeControls } from './customAttribute';
 export { SpacingControl, SPACING_CONTROL_ID } from './spacing';
 export { CardBackgroundColorControl, CARD_BACKGROUND_COLOR_CONTROL_ID } from './cardBackground';
-export { LayoutControl, LAYOUT_CONTROL_ID } from './layout';
 export { RecommendationCardCompositionControl, COMPOSITION_CONTROL_BLOCK_ID } from './cardComposition';
+export { SyncInfoMessageControl, SYNC_INFO_MESSAGE_CONTROL_ID } from './syncInfoMessage';

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

@@ -3,11 +3,13 @@ import { CommonControl } from '../../../common-control';
 import { AlgorithmControl, ALGORITHM_CONTROL_ID } from './algorithm';
 import { CurrencyControl, CURRENCY_CONTROL_ID } from './currency';
 import { FiltersControl, FILTERS_CONTROL_ID } from './filters';
+import { LayoutOrientationControl, LAYOUT_ORIENTATION_CONTROL_ID } from './layoutOrientation';
 import { LocaleControl, LOCALE_CONTROL_ID } from './locale';
+import { ProductCountControl, PRODUCT_COUNT_CONTROL_ID } from './productCount';
 import { ProductLayoutControl, PRODUCT_LAYOUT_CONTROL_ID } from './productLayout';
 import { ShuffleControl, SHUFFLE_CONTROL_ID } from './shuffle';
 export declare const CONTROL_BLOCK_ID = "ui-elements-recommendation-block";
-export { AlgorithmControl, ALGORITHM_CONTROL_ID, LocaleControl, LOCALE_CONTROL_ID, CurrencyControl, CURRENCY_CONTROL_ID, ProductLayoutControl, PRODUCT_LAYOUT_CONTROL_ID, FiltersControl, FILTERS_CONTROL_ID, ShuffleControl, SHUFFLE_CONTROL_ID, };
+export { AlgorithmControl, ALGORITHM_CONTROL_ID, LocaleControl, LOCALE_CONTROL_ID, CurrencyControl, CURRENCY_CONTROL_ID, ProductCountControl, PRODUCT_COUNT_CONTROL_ID, ProductLayoutControl, PRODUCT_LAYOUT_CONTROL_ID, FiltersControl, FILTERS_CONTROL_ID, ShuffleControl, SHUFFLE_CONTROL_ID, LayoutOrientationControl, LAYOUT_ORIENTATION_CONTROL_ID, };
 export * from './utils';
 /**
  * Main recommendation block control that composes all sub-controls
@@ -19,9 +21,11 @@ export declare class RecommendationBlockControl extends CommonControl {
     private algorithmControl;
     private localeControl;
     private currencyControl;
+    private productCountControl;
     private productLayoutControl;
     private filtersControl;
     private shuffleControl;
+    private layoutOrientationControl;
     getId(): string;
     getTemplate(): string;
     onRender(): Promise<void>;

package/dist/src/extensions/Blocks/Recommendation/controls/{layout/index.d.ts → main/layoutOrientation.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Layout Control
+ * Layout Orientation Control
  *
  * Manages recommendation block layout orientation
  * Allows switching between grid and list layouts
@@ -9,12 +9,12 @@
 import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
 import { CommonControl } from '../../../common-control';
 import { type Orientation } from '../../templates';
-export declare const LAYOUT_CONTROL_ID = "recommendation-layout-control";
+export declare const LAYOUT_ORIENTATION_CONTROL_ID = "recommendation-layout-orientation-control";
 /**
  * Control for managing recommendation block layout orientation
  * Allows switching between grid and list layouts
  */
-export declare class LayoutControl extends CommonControl {
+export declare class LayoutOrientationControl extends CommonControl {
     private store;
     private isChangingLayout;
     getId(): string;

package/dist/src/extensions/Blocks/Recommendation/controls/main/productCount.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Product Count Control
+ *
+ * Handles the "Number of Products" setting for the recommendation block.
+ * Extracted from ProductLayoutControl for single-responsibility.
+ *
+ * Changes to product count trigger a product refetch via Pinia store
+ * subscription (handled by the main RecommendationBlockControl coordinator).
+ *
+ * Configuration is stored via node config (persists with template).
+ */
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+import { CommonControl } from '../../../common-control';
+export declare const PRODUCT_COUNT_CONTROL_ID = "recommendation-product-count-control";
+/**
+ * Control for configuring the number of products to display.
+ * Updates node config and triggers product refetch via store subscription.
+ */
+export declare class ProductCountControl extends CommonControl {
+    private store;
+    getId(): string;
+    getTemplate(): string;
+    onRender(): void;
+    onTemplateNodeUpdated(node: ImmutableHtmlNode): void;
+    _setFormValues(): void;
+    _onProductCountChange(value: string): void;
+    _listenToFormUpdates(): void;
+}

package/dist/src/extensions/Blocks/Recommendation/controls/main/productLayout.d.ts

@@ -1,14 +1,17 @@
 /**
  * Product Layout Control
  *
- * Handles product display configuration:
- * - Number of products to show
+ * Handles product grid/row configuration:
  * - Products per row on desktop (hidden for list layout)
- * - Products per row on mobile (hidden for list layout)
+ * - Mobile Layout Optimization toggle (enables/disables mobile-specific layout)
+ * - Products per row on mobile (visible only when mobile layout is enabled)
  * - Triggers product row regeneration on changes
  *
- * Desktop/mobile counters swap visibility based on editor mode
- * (detected via Stripo's EditorStatePropertyType.previewDeviceMode).
+ * When the mobile layout toggle is ON, only one "Products in One Row" counter
+ * is visible at a time — desktop or mobile — based on the editor's current
+ * preview device mode. Both counters are placed above the toggle.
+ *
+ * Note: "Number of Products" is handled by the separate ProductCountControl.
  *
  * Configuration is stored via node config (persists with template).
  */
@@ -16,8 +19,9 @@ import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
 import { CommonControl } from '../../../common-control';
 export declare const PRODUCT_LAYOUT_CONTROL_ID = "recommendation-product-layout-control";
 /**
- * Control for configuring product count and layout density
- * Includes both desktop and mobile "products per row" counters
+ * Control for configuring product layout density.
+ * Includes desktop "products per row" counter, a mobile layout optimization
+ * toggle, and a mobile "products per row" counter (visible when toggle is on).
  */
 export declare class ProductLayoutControl extends CommonControl {
     private store;
@@ -29,24 +33,32 @@ export declare class ProductLayoutControl extends CommonControl {
     onDestroy(): void;
     _setFormValues(): void;
     /**
-     * Checks if the editor is currently in mobile preview mode
-     * using Stripo's EditorStatePropertyType API.
+     * Returns true when the editor preview is in mobile mode.
      */
-    _isMobileMode(): boolean;
+    _isMobilePreview(): boolean;
     /**
-     * Updates counter visibility based on layout orientation and editor mode.
-     * - List layout: hide both counters (products always full-width)
-     * - Grid + desktop mode: show desktop counter, hide mobile counter
-     * - Grid + mobile mode: show mobile counter, hide desktop counter
+     * Updates counter visibility based on layout, mobileLayoutEnabled, and editor preview mode.
+     *
+     * Three mutually exclusive rows exist in the template:
+     *   1. "Products in One Row"            — generic, shown when toggle is OFF
+     *   2. "Products in One Row on Desktop" — shown when toggle is ON + desktop preview
+     *   3. "Products in One Row on Mobile"  — shown when toggle is ON + mobile preview
+     *
+     * Only one row is visible at a time. This avoids setUIEAttribute on hidden
+     * elements, which Stripo does not apply reliably.
      */
     _updateProductsInRowVisibility(): void;
     /**
-     * Subscribes to editor preview mode changes via Stripo API.
-     * When the user switches between desktop/mobile preview, toggles
-     * which "Products in One Row" counter is visible.
+     * Initializes the mobile layout toggle using the same pattern as shuffle.ts.
+     * Sets the initial UI attribute value from the node config.
+     */
+    _initializeMobileLayoutToggle(): void;
+    /**
+     * Handles mobile layout toggle change.
+     * When enabled: opts in to mobile layout, restores previous mobileCardsInRow.
+     * When disabled: snapshots current mobileCardsInRow, resets to 1, opts out.
      */
-    _subscribeToEditorModeChanges(): void;
-    _onProductCountChange(value: string): void;
+    _onMobileLayoutToggleChange(enabled: boolean): void;
     _onProductsInRowChange(value: number): void;
     _onMobileCardsInRowChange(value: number): void;
     _regenerateProductRows(): void;
@@ -54,7 +66,13 @@ export declare class ProductLayoutControl extends CommonControl {
     _listenToFormUpdates(): void;
     /**
      * Subscribe to store changes to update visibility when layout changes
-     * This is still needed because layout changes come from LayoutControl
+     * This is still needed because layout changes come from LayoutOrientationControl
      */
     _listenStateUpdates(): void;
+    /**
+     * Subscribe to editor preview mode changes (desktop ↔ mobile).
+     * When the user switches preview mode and mobile layout is enabled,
+     * we swap which "Products in One Row" counter is visible.
+     */
+    _listenEditorModeChanges(): void;
 }

package/dist/src/extensions/Blocks/Recommendation/controls/main/utils.d.ts

@@ -56,14 +56,18 @@ export interface RegenerateProductRowsOptions {
     products?: RecommendationProduct[];
     /** Optional: pass layout directly to avoid stale DOM reads after setAttribute */
     layout?: Orientation;
+    /** Optional: pass composition directly to avoid stale DOM reads after setAttribute */
+    composition?: string[];
 }
 /**
  * Regenerates only the mobile product container rows.
  * Used when mobile-specific settings change (mobileCardsInRow)
  * or when the desktop container is regenerated (to keep both in sync).
  *
- * For list layout: hides the mobile row entirely (list is inherently responsive).
- * For grid layout: shows the mobile row and populates it.
+ * For list layout: clears the mobile row content (list rows are inherently responsive).
+ * For grid layout with mobileLayoutEnabled OFF: clears the mobile row content.
+ * For grid layout with mobileLayoutEnabled ON: rebuilds the full mobile row
+ *   structure (<td><table>...products...</table></td>) in a single operation.
  */
 export declare function regenerateMobileProductRows(options: Omit<RegenerateProductRowsOptions, 'afterRegenerate'>): void;
 /**

package/dist/src/extensions/Blocks/Recommendation/controls/mobileLayout/cssRules.d.ts

@@ -5,12 +5,23 @@
  * Rules are injected into the document's stylesheet via modifyCss
  * so they appear in the compiled HTML export.
  */
-import type { ImmutableCssNode } from '@stripoinc/ui-editor-extensions';
+import type { ImmutableCssNode, ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
 import { ModificationDescription } from '@stripoinc/ui-editor-extensions';
 /** CSS class for desktop product container */
 export declare const CSS_CLASS_DESKTOP_CONTAINER = "ins-recommendation-desktop-container";
 /** CSS class for mobile product container */
 export declare const CSS_CLASS_MOBILE_CONTAINER = "ins-recommendation-mobile-container";
+/** CSS class that opts a block out of the mobile layout container swap */
+export declare const CSS_CLASS_NO_MOBILE_LAYOUT = "ins-recommendation-no-mobile-layout";
+interface HtmlModifierApi {
+    getDocumentModifier: () => {
+        modifyHtml: (node: ImmutableHtmlNode) => {
+            setClass: (cls: string) => void;
+            removeClass: (cls: string) => void;
+        };
+        apply: (desc: ModificationDescription) => void;
+    };
+}
 interface CssModifierApi {
     getDocumentRootCssNode: () => ImmutableCssNode | null;
     getDocumentModifier: () => {
@@ -26,4 +37,15 @@ interface CssModifierApi {
  * Follows the same pattern as textTrim's _ensureCssRulesExist().
  */
 export declare function ensureMobileCssRulesExist(api: CssModifierApi): void;
+/**
+ * Checks if a block element has the mobile layout opt-out class.
+ * Read-side companion to setMobileLayoutOptOut().
+ */
+export declare function hasMobileLayoutOptOut(blockElement: ImmutableHtmlNode): boolean;
+/**
+ * Adds or removes the mobile layout opt-out class on a block element.
+ * When optOut is true, the block keeps the desktop container visible on mobile.
+ * When optOut is false, the block follows the default mobile container swap.
+ */
+export declare function setMobileLayoutOptOut(api: HtmlModifierApi, blockElement: ImmutableHtmlNode, optOut: boolean): void;
 export {};

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

@@ -5,8 +5,9 @@
  * - 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).
+ * Desktop spacing controls are always visible when applicable (grid layout).
+ * Mobile spacing controls are visible only when mobileLayoutEnabled is true
+ * in the node config (controlled by the Mobile Layout Optimization toggle).
  *
  * Configuration is stored via node config (persists with template).
  * Actual spacing is applied to DOM elements via inline styles.
@@ -18,7 +19,8 @@ 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
+ * - Separate controls for desktop and mobile
+ * - Mobile controls visibility driven by mobileLayoutEnabled config
  */
 export declare class SpacingControl extends CommonControl {
     private store;
@@ -29,18 +31,11 @@ export declare class SpacingControl extends CommonControl {
     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.
+     * Updates spacing control visibility based on layout orientation and mobileLayoutEnabled.
      * - List layout: hide column spacing (products are full-width), hide ALL mobile
      *   spacing controls (list is responsive — single row spacing applies to both views)
-     * - 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)
+     * - Desktop controls: always visible for grid layout (column spacing needs 2+ per row)
+     * - Mobile controls: visible when mobileLayoutEnabled is true (grid only)
      */
     _updateSpacingVisibility(): void;
     /**
@@ -108,9 +103,4 @@ export declare class SpacingControl extends CommonControl {
      * 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/controls/syncInfoMessage.d.ts

@@ -0,0 +1,34 @@
+import { CommonControl } from '../../common-control';
+import { RecommendationControlId } from '../constants';
+export declare const SYNC_INFO_MESSAGE_CONTROL_ID = RecommendationControlId.SYNC_INFO_MESSAGE;
+/**
+ * Static info message control for the product name sub-block settings panel.
+ *
+ * Follows the same pattern as getMigrationBannerHtml:
+ * - Direct HTML template with UIElementType.ICON + text
+ * - CSS-class-based styling (defined in recommendation.css)
+ * - Repositioned above tabs via DOM manipulation in onRender()
+ * - Cleaned up in onDestroy() since the element lives outside Stripo's managed area
+ */
+export declare class SyncInfoMessageControl extends CommonControl {
+    private _repositionedElement;
+    getId(): string;
+    getTemplate(): string;
+    onRender(): void;
+    onDestroy(): void;
+    /**
+     * Moves the info message from inside the Settings tab content
+     * to above the tab bar in the DOM tree.
+     *
+     * DOM structure (Stripo internals):
+     *   ue-control-panel
+     *     div.control-panel-header-wrapper
+     *       div.control-panel-header          ← title bar (X, title, undo)
+     *       ue-tabs-header.control-panel-tabs  ← tab bar (Settings | Styles)
+     *     div.control-panel-content-wrapper    ← tab content (where our control renders)
+     *
+     * We insert the message between the title bar and the tab bar.
+     * The element reference is stored so onDestroy() can remove it.
+     */
+    private _repositionAboveTabs;
+}

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

@@ -13,6 +13,7 @@ interface PerBlockConfigs {
     filters: Filter[];
     id: number;
     language: string;
+    mobileLayoutEnabled: boolean;
     orientation: Orientation;
     productIds: string[];
     recommendedProducts: [];
@@ -22,6 +23,7 @@ interface PerBlockConfigs {
     textTrimming: boolean;
     unresponsive: boolean;
     size: string;
+    customAttributes: string[];
 }
 interface PerBlockState {
     recommendationConfigs: PerBlockConfigs;

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

@@ -1,4 +1,4 @@
-import type { ElementRenderer } from '../utils';
+import { type ElementRenderer } from '../utils';
 /**
  * Grid element renderer
  * Each element returns a `<td>` containing a nested table structure:

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

@@ -1,4 +1,4 @@
-import type { ElementRenderer } from '../utils';
+import { type ElementRenderer } from '../utils';
 /**
  * List element renderer
  * - Image and Button return `<td>` cells for the 3-column layout

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

@@ -1,18 +1,24 @@
 import type { RecommendationProduct } from '@@/Types/recommendation';
 /**
  * Generates a list product card with 3-column layout
- * Uses listElementRenderer to render Image, Info content, and Button
+ * Uses buildElementRenderer to render Image, Info content, and Button
  * Layout: [Image (120px)] [Info table (flexible)] [Button (100px)]
+ *
+ * The info cell rows are built dynamically from the composition array,
+ * supporting both built-in attributes and custom product attributes.
+ * Image and Button are always separate columns (not in the info cell).
  * @param product - The product data
+ * @param composition - Array defining order of card elements
  * @returns HTML string for a single product card row
  */
-export declare function getListProductCard(product: RecommendationProduct): string;
+export declare function getListProductCard(product: RecommendationProduct, composition?: string[]): string;
 /**
  * Prepares list product rows
  * Each product is a full-width row with 3-column layout
  * @param products - Array of products to display
+ * @param composition - Array defining order of card elements
  * @returns HTML string for product rows
  */
-export declare function prepareProductRows(products: RecommendationProduct[]): string;
+export declare function prepareProductRows(products: RecommendationProduct[], composition?: string[]): string;
 export declare function getDefaultTemplate(): string;
-export declare function generateBlockTemplate(products: RecommendationProduct[], title?: string): string;
+export declare function generateBlockTemplate(products: RecommendationProduct[], title?: string, composition?: string[]): string;

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

@@ -1,5 +1,35 @@
 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';
+/**
+ * Converts a snake_case attribute name to Title Case display name.
+ * e.g., "rating_star" → "Rating Star"
+ */
+export declare function toDisplayName(attrName: string): string;
+/**
+ * Callback that generates the cell HTML for a custom product attribute.
+ * Layout-specific: grid returns `<td>…`, list returns `<tr><td>…</td></tr>`.
+ */
+export type CustomCellHtmlGetter = (attrName: string, content: string) => string;
+/**
+ * Symbol key for embedding custom attribute HTML in an ElementRenderer.
+ * Grid and list renderers store their custom-attribute cell template under this key
+ * so that `buildElementRenderer` can read it without a separate callback parameter.
+ *
+ * Using a Symbol avoids conflicts with the string index signature — call sites that
+ * access `renderer[stringKey]` always get `(product) => string` without type narrowing.
+ */
+export declare const CUSTOM_CELL_HTML: unique symbol;
+/**
+ * Extends a base element renderer with custom attribute entries from the composition.
+ * Each `customAttr:<name>` key in the composition gets a renderer closure that calls
+ * the layout-specific custom cell HTML getter stored in `baseRenderer[CUSTOM_CELL_HTML]`.
+ *
+ * This ensures that custom attribute renderers live inside the ElementRenderer object
+ * alongside built-in ones, so template code can use a uniform lookup for all attributes.
+ * @param baseRenderer - The built-in element renderer (grid or list), must include a [CUSTOM_CELL_HTML] entry
+ * @param composition - Array of attribute keys including `customAttr:*` entries
+ */
+export declare function buildElementRenderer(baseRenderer: ElementRenderer, composition: string[]): ElementRenderer;
 export type Orientation = 'list' | 'grid';
 /**
  * Options for prepareProductRows unified function
@@ -13,8 +43,11 @@ export interface PrepareProductRowsOptions {
     composition?: string[];
 }
 /**
- * Element renderer interface for product card elements
- * Keys are ATTR_PRODUCT_* constants for consistent naming
+ * Element renderer interface for product card elements.
+ * Keys are ATTR_PRODUCT_* constants for built-in elements.
+ * The index signature allows dynamic custom attribute keys (e.g., "customAttr:rating_star").
+ * The Symbol-keyed [CUSTOM_CELL_HTML] entry stores the layout-specific HTML template
+ * for custom attributes — used by `buildElementRenderer` to create custom entries.
  */
 export interface ElementRenderer {
     [ATTR_PRODUCT_IMAGE]: (product: RecommendationProduct) => string;
@@ -24,6 +57,8 @@ export interface ElementRenderer {
     [ATTR_PRODUCT_OMNIBUS_PRICE]: (product: RecommendationProduct) => string;
     [ATTR_PRODUCT_OMNIBUS_DISCOUNT]: (product: RecommendationProduct) => string;
     [ATTR_PRODUCT_BUTTON]: (product: RecommendationProduct) => string;
+    [CUSTOM_CELL_HTML]?: CustomCellHtmlGetter;
+    [key: string]: (product: RecommendationProduct) => string;
 }
 /**
  * Product card getter function type

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

@@ -106,6 +106,19 @@ export interface RecommendationNodeConfig {
      * Vertical spacing between product rows in pixels
      */
     rowSpacing: number;
+    /**
+     * Whether mobile layout optimization is enabled
+     * When enabled, shows mobile-specific product row configuration
+     * When disabled, adds opt-out CSS class to prevent mobile container swap
+     * @default false
+     */
+    mobileLayoutEnabled: boolean;
+    /**
+     * Snapshot of mobileCardsInRow before disabling mobile layout
+     * Used to restore the previous value when re-enabling
+     * @default 1
+     */
+    previousMobileCardsInRow: number;
     /**
      * Horizontal spacing between product cards on mobile in pixels (grid layout only)
      */

package/dist/src/extensions/Blocks/common-control.d.ts

@@ -9,7 +9,20 @@ interface TextInputProps {
 interface LabelProps {
     text: string;
     name?: string;
-    position?: 'top' | 'left';
+    hint?: string;
+}
+interface MessageProps {
+    name?: string;
+    type?: string;
+}
+interface InfoMessageProps {
+    name: string;
+    icon?: string;
+    type?: string;
+}
+interface IconProps {
+    src: string;
+    className?: string;
 }
 interface IconButtonProps {
     name: string;
@@ -73,7 +86,20 @@ export declare abstract class CommonControl extends Control {
      * @returns true if block instance changed, false otherwise
      */
     protected handleBlockInstanceChange(updateUI: () => void): boolean;
-    _GuLabel({ text, name }: LabelProps): string;
+    _GuLabel({ text, name, hint }: LabelProps): string;
+    _GuMessage({ name, type }: MessageProps): string;
+    /**
+     * Returns template HTML for an info message with an optional icon.
+     * Use in getTemplate() — the icon is registered in a hidden store so Stripo initializes it.
+     * Pair with _setInfoMessageValue() in onRender() to set the text content.
+     */
+    _GuOnPageMessage({ name, icon, type }: InfoMessageProps): string;
+    /**
+     * Sets the info message value with the pre-registered icon.
+     * Use in onRender() — reads the icon's outerHTML from the hidden store
+     * and combines it with the text in Stripo's alert-message layout.
+     */
+    _setInfoMessageValue(name: string, text: string): void;
     _GuToggle(name: string): string;
     _GuSelectItem({ text, value }: {
         text: string;
@@ -89,6 +115,7 @@ export declare abstract class CommonControl extends Control {
     }): string;
     _GuRadioButton({ name, buttons, id }: RadioButtonProps): string;
     _GuButton({ name, label, id }: ButtonProps): string;
+    _GuIcon({ src, className }: IconProps): string;
     /**
      *
      * @param param0