@orangelogic/design-system 2.95.0 → 2.97.0

package/library/packages/organisms/src/bento-grid/bento-grid.d.ts

@@ -4,26 +4,41 @@ import { default as CxGalleryItem } from '../../../molecules/src/gallery-item/ga
 import { Easing } from '../../../types/src/index.ts';
 import { Filler, FillerMode } from '../../../types/src/bento-grid';
 import { GalleryItem, GalleryItemContentPosition, GalleryItemContentVariant, GalleryItemEffect, GalleryItemShowContentType, GalleryItemTextRevealStyle, GalleryItemZoomStyle } from '../../../types/src/gallery-item';
-import { CSSResultGroup } from 'lit';
+import { CSSResultGroup, PropertyValues } from 'lit';
 import { StaticValue } from 'lit/static-html.js';
 
 /**
- * @summary CxBentoGrid - A responsive bento grid component with fixed cell height & responsive breakpoints
+ * @summary CxBentoGrid - A responsive bento grid component with fixed cell height & responsive breakpoints.
+ * Renders only the items visible in the viewport (scroll-based virtualization).
  *
  * @cssproperty [--item-height=200px] - The height of each grid item.
  *
  * @csspart base - The bento grid container
  * @csspart item - The item part of the bento grid
  *
- * @event {{ currentColumnCount }} cx-bento-resize - Emitted when the grid layout recalculates
+ * @event {{ currentColumnCount: number }} cx-bento-resize - Emitted when the grid layout recalculates
+ * @event {{ first: number; last: number }} cx-bento-range-change - Emitted when the visible item range changes due to scroll or layout update
  */
 export default class CxBentoGrid extends CortexElement {
     static readonly styles: CSSResultGroup;
+    /** Minimum scroll delta (px) required to trigger a virtual range update. */
+    private static readonly SCROLL_THRESHOLD;
     static readonly dependencies: {
         'cx-gallery-item': typeof CxGalleryItem;
         'cx-tooltip': typeof CxTooltip;
     };
     private readonly localize;
+    /** Pure layout calculator — computes absolute pixel positions. */
+    private readonly bentoLayout;
+    /** RAF gate for scroll handler to avoid layout thrash. */
+    private _scrollRaf;
+    /** Cached viewport height — updated on resize only, not on every scroll. */
+    private _viewportHeight;
+    /** Watches the host element for size changes so the grid reflows when its container resizes. */
+    private _resizeObserver;
+    /** Tracks the last emitted range to avoid firing cx-bento-range-change when the range hasn't changed. */
+    private _lastEmittedFirst;
+    private _lastEmittedLast;
     /**
      * References the main container element of the bento grid.
      * This element is used to calculate the grid width and apply
@@ -76,6 +91,13 @@ export default class CxBentoGrid extends CortexElement {
      * The maximum number of rows to show.
      */
     maxRows: number;
+    /**
+     * Total number of items in the dataset, including those not yet loaded.
+     * When set, the scroll container height is extended to reflect the full dataset
+     * size so the scrollbar is accurate from the first render.
+     * Unloaded slots are approximated as 1×1 items.
+     */
+    totalItems: number;
     /**
      * The show content type.
      */
@@ -140,14 +162,8 @@ export default class CxBentoGrid extends CortexElement {
      * Specifies the easing function to use when changing slides.
      */
     easing: Easing;
-    /**
-     * Internal state that holds the computed CSS styles for the grid container.
-     */
+    /** CSS styles applied to the grid container element. */
     private containerStyles;
-    /**
-     * Tracks the computed styles for the grid container.
-     */
-    private computedStyles;
     /**
      * Tracks the previous column count to detect when the grid layout recalculates
      * prevents unnecessary grid updates when the column count hasn't changed.
@@ -158,6 +174,14 @@ export default class CxBentoGrid extends CortexElement {
      * Tracks the currently hovered item.
      */
     private hoveredItemId;
+    /** Total scroll height in px — drives the container height for an accurate scrollbar. */
+    private scrollSize;
+    /** Current scroll offset in pixels from the top of the container. */
+    private scrollOffset;
+    /** Inclusive index of the first item in the rendered virtual window. */
+    private virtualFirst;
+    /** Inclusive index of the last item in the rendered virtual window. */
+    private virtualLast;
     private isTooltipShown;
     protected galleryItemTag: string;
     /**
@@ -177,6 +201,16 @@ export default class CxBentoGrid extends CortexElement {
     constructor();
     runConnectedCallback(): void;
     disconnectedCallback(): void;
+    runFirstUpdated(): void;
+    /**
+     * Returns the visible viewport height for virtualization.
+     *
+     * `containerEl.clientHeight` is unsafe here because, once `containerStyles.height`
+     * is set to the laid-out `scrollSize`, the container height equals the entire
+     * grid. We walk up to the nearest scrollable ancestor (or fall back to the
+     * window) to keep `getActiveRange()` honest.
+     */
+    private measureViewportHeight;
     private showTooltip;
     private hideTooltip;
     /**
@@ -190,23 +224,26 @@ export default class CxBentoGrid extends CortexElement {
     private getItemSize;
     /**
      * Determines the number of columns for the grid based on the current
-     * container width and breakpoints.
+     * container width and breakpoints. Also builds filledData when filler is active.
      */
     private setupGrid;
     /**
-     * Calculates the optimal positioning for each bento grid item within the grid layout.
-     * @internal Pass calculated total columns and styles values to avoid recalculating in resize and watches
+     * Runs BentoLayout.compute() then updates scrollSize and active virtual range.
      */
-    private updateGrid;
+    private computeLayout;
+    /** Recalculates which items fall within the current scroll viewport. */
+    private updateActiveRange;
     /**
-     * Debounced event handler that responds to container resize events.
+     * Returns the index of the last item whose rowStart is within maxRows.
      */
-    private handleResize;
+    private maxRowsLastIndex;
     /**
-     * Watch max columns change & update grid
+     * Debounced event handler that responds to container resize events.
      */
-    handleGridChange(): void;
-    handleEasingChange(): void;
+    private handleResize;
+    /** RAF-gated scroll handler — updates scroll offset and rerenders visible range. */
+    private handleScroll;
+    willUpdate(changed: PropertyValues): void;
     /**
      * Get content position based on the size of the item.
      */
@@ -222,13 +259,7 @@ export default class CxBentoGrid extends CortexElement {
     private handleBlur;
     private computeBentoItemEffectStyles;
     renderGalleryItem(galleryItem: {
-        computedStyles: {
-            gridColumnEnd: number;
-            gridColumnStart: number;
-            gridRowEnd: number;
-            gridRowStart: number;
-            height: string;
-        } | undefined;
+        actualIndex: number;
         index: number;
         item: GalleryItem;
     }): import('lit').TemplateResult;

package/library/packages/organisms/src/bento-grid/bento-layout.d.ts

@@ -0,0 +1,44 @@
+import { BentoActiveRange, BentoItemPosition, BentoLayoutParams } from '../../../types/src/bento-grid';
+import { GalleryItem } from '../../../types/src/gallery-item';
+
+/**
+ * Pure layout calculator for a bento grid.
+ * Computes absolute pixel positions for items that can span multiple
+ * columns and rows. Call `compute()` after data or layout config changes,
+ * then `getActiveRange()` on every scroll event to know which items to render.
+ */
+export declare class BentoLayout {
+    private _positions;
+    /**
+     * Sorted array of each item's `top` pixel value (index matches item index).
+     * Non-strictly increasing (items in the same row share the same `top`).
+     * Used for O(log N) binary search inside getActiveRange().
+     */
+    private _topPositions;
+    private _scrollSize;
+    /** Total scrollable height in pixels after the last compute() call. */
+    get scrollSize(): number;
+    /** Returns the pixel position for item at `idx`, or undefined if not yet computed. */
+    getPosition(idx: number): BentoItemPosition | undefined;
+    /**
+     * Runs the bin-packing algorithm and populates pixel positions for all items.
+     * Synchronous — completes in < 1 ms for typical datasets (≤ 10 000 items).
+     */
+    compute(items: GalleryItem[], params: BentoLayoutParams): void;
+    /**
+     * Returns the inclusive [first, last] item index range that overlaps the
+     * visible window [scrollTop − overhang, scrollTop + viewportHeight + overhang].
+     * O(log N) via binary search on the sorted _topPositions array.
+     */
+    getActiveRange(scrollTop: number, viewportHeight: number, overhang?: number): BentoActiveRange;
+    /**
+     * Returns the smallest index i such that _topPositions[i] >= value.
+     * Returns n if all values are < value.
+     */
+    private lowerBound;
+    /**
+     * Returns the smallest index i such that _topPositions[i] > value.
+     * Returns n if all values are <= value.
+     */
+    private upperBound;
+}

package/library/packages/organisms/src/carousel/carousel.d.ts

@@ -239,6 +239,8 @@ export default class CxCarousel extends CortexElement {
     private readonly localize;
     private readonly instantScrollGap;
     private isTooltipShown;
+    /** Stores the requested index when goToSlide returns early due to an out-of-chunk request, so it can be retried after the chunk loads. */
+    private pendingNavigationIndex;
     protected isProgrammaticFocus: boolean;
     private mutationObserver;
     get easeCSSVariable(): string;
@@ -318,7 +320,7 @@ export default class CxCarousel extends CortexElement {
     handleOrientationChange(): void;
     handleAutoplayChange(): void;
     handleDataChanges(): Promise<void>;
-    handleChunkChange(): void;
+    handleChunkChange(): Promise<void>;
     handleChunkLoopChange(): Promise<void>;
     /**
      * Move the carousel backward by `slides-per-move` slides.

package/library/packages/organisms/src/content-builder/components/block-picker/block-picker.d.ts

@@ -98,6 +98,13 @@ export default class CxBlockPicker extends CortexElement {
     forceSelectingTemplate: boolean;
     limitedBlocks: string[];
     addIndex: number | undefined;
+    /**
+     * Whether to expose asset format / transformation / download-format /
+     * asset-format-picker controls for image, video, gallery, carousel,
+     * and timeline blocks. Forwarded from `cx-content-builder`.
+     * @default false
+     */
+    enableAssetFormatControls: boolean;
     selectedComponent: Component | undefined;
     /**
      * The boundary property of the confirm popover's dropdown/dialog popup.

package/library/packages/organisms/src/content-builder/components/config-form/config-form-controller.d.ts

@@ -6,8 +6,12 @@ import { TabType } from './config-form';
 export declare class ConfigFormController implements ReactiveController {
     host: ReactiveControllerHost & CxConfigForm;
     private readonly localize;
+    private apiSearchAssets;
+    private readonly searchToken;
+    private readonly pendingGalleryPickerSaves;
     constructor(host: ReactiveControllerHost & CxConfigForm);
     hostConnected(): void;
+    private resolveAssetFormatSrc;
     private handleStyleChange;
     private handleAttributeChange;
     private handlePropertyChange;

package/library/packages/organisms/src/content-builder/components/config-form/config-form.d.ts

@@ -28,6 +28,7 @@ import { default as CxTypography } from '../../../../../atoms/src/components/typ
 import { default as CxVisuallyHidden } from '../../../../../atoms/src/components/visually-hidden/visually-hidden.ts';
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
 import { CxIconPicker } from '../../../../../molecules/src/index.ts';
+import { default as CxAssetFormatPicker } from '../../../../../molecules/src/asset-format-picker/asset-format-picker.ts';
 import { default as CxAssetPicker } from '../../../../../molecules/src/asset-picker/asset-picker.ts';
 import { default as CxBicolorPicker } from '../../../../../molecules/src/bicolor-picker/bicolor-picker.ts';
 import { default as CxBorderInputGroup } from '../../../../../molecules/src/border-input-group/border-input-group.ts';
@@ -40,6 +41,8 @@ import { default as CxPaddingInputGroup } from '../../../../../molecules/src/pad
 import { default as CxPositionPicker } from '../../../../../molecules/src/position-picker/position-picker.ts';
 import { default as CxShadowInputGroup } from '../../../../../molecules/src/shadow-input-group/shadow-input-group.ts';
 import { default as CxSizeInputGroup } from '../../../../../molecules/src/size-input-group/size-input-group.ts';
+import { default as CxAssetTransformationDialog } from '../../../asset-transformation-dialog/asset-transformation-dialog.ts';
+import { AssetFormatValue } from '../../../../../types/src/asset-format-picker';
 import { Asset, AssetTypeString, EditorMode, PropertyConfig } from '../../../../../types/src/content-builder';
 import { StyleProps } from 'grapesjs';
 import { CxColorSwatchPicker } from '../color-swatch-picker';
@@ -72,7 +75,9 @@ export declare enum TabType {
 export default class CxConfigForm extends CortexElement {
     static readonly styles: import('lit').CSSResult[];
     static readonly dependencies: {
+        'cx-asset-format-picker': typeof CxAssetFormatPicker;
         'cx-asset-picker': typeof CxAssetPicker;
+        'cx-asset-transformation-dialog': typeof CxAssetTransformationDialog;
         'cx-bicolor-picker': typeof CxBicolorPicker;
         'cx-border-input-group': typeof CxBorderInputGroup;
         'cx-button': typeof CxButton;
@@ -192,6 +197,10 @@ export default class CxConfigForm extends CortexElement {
      * @returns A promise that resolves to an Asset object.
      * @default undefined
      */
+    /** Base URL passed through to cx-asset-transformation-dialog for asset fetching. */
+    baseUrl: string;
+    /** Auth token passed through to cx-asset-transformation-dialog for asset fetching. */
+    token: string;
     onRequestAsset: ((type: AssetTypeString, multiple?: boolean, accepts?: string[]) => Promise<Asset | Record<string, Asset>>) | undefined;
     /**
      * Function to request a download format.
@@ -202,6 +211,8 @@ export default class CxConfigForm extends CortexElement {
      * @default undefined
      */
     onRequestDownloadFormat: ((assetIds: string[], formats?: Record<string, string[]>) => Promise<Record<string, string[]>>) | undefined;
+    /** Callback invoked when an asset format needs to be selected via an external popup. */
+    onRequestAssetFormat: ((assetId: string, value?: AssetFormatValue) => Promise<AssetFormatValue | null | undefined>) | undefined;
     /**
      * The attributes of the component.
      * This is used to store the attributes of the block being configured.

package/library/packages/organisms/src/content-builder/components/config-manager/config-manager.d.ts

@@ -1,5 +1,6 @@
 import { default as CxTypography } from '../../../../../atoms/src/components/typography/typography.ts';
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
+import { AssetFormatValue } from '../../../../../types/src/asset-format-picker';
 import { Asset, AssetTypeString, EditorMode, PropertyConfig } from '../../../../../types/src/content-builder';
 import { Component, DataRecord, StyleProps } from 'grapesjs';
 import { CxConfigForm } from '../config-form';
@@ -53,6 +54,13 @@ export default class CxConfigManager extends CortexElement {
      * @default EditorMode.Template
      */
     mode: EditorMode;
+    /**
+     * Whether to expose asset format / transformation / download-format /
+     * asset-format-picker controls for image, video, gallery, carousel,
+     * and timeline blocks.
+     * @default false
+     */
+    enableAssetFormatControls: boolean;
     /**
      * A list of properties that are not shown in the configuration manager if mode is EditorMode.Content.
      * @default []
@@ -100,6 +108,8 @@ export default class CxConfigManager extends CortexElement {
      * @default undefined
      */
     onRequestDownloadFormat: ((assetIds: string[]) => Promise<Asset[]>) | undefined;
+    /** Callback forwarded to `cx-config-form` → `cx-asset-format-picker` for asset format selection. */
+    onRequestAssetFormat: ((assetId: string, value?: AssetFormatValue) => Promise<AssetFormatValue | null | undefined>) | undefined;
     /**
      * The attributes of the component.
      * This is used to store the attributes of the block being configured.

package/library/packages/organisms/src/content-builder/components/gallery-picker/gallery-picker.d.ts

@@ -51,6 +51,10 @@ export default class CxGalleryPicker extends CortexElement implements CortexForm
      * Specifies the id of the src of the carousel. This is only used when the variant is set to 'api'.
      */
     src: string;
+    /**
+     * The asset format code used to resolve image src URLs when fetching records by ID.
+     */
+    format: string;
     /**
      * The boundary property of the confirm popover's dropdown/dialog popup.
      */
@@ -115,6 +119,8 @@ export default class CxGalleryPicker extends CortexElement implements CortexForm
     fetchImagesInFolderBySlide(): Promise<void>;
     handleSourceVariantChange(): void;
     fetchImagesByIDs(oldValue: unknown, newValue: unknown): Promise<void>;
+    handleFormatChange(): Promise<void>;
+    private doFetchByIds;
     private get maxMasonryHeight();
     private get hasMore();
     private handleAddItem;

package/library/packages/organisms/src/content-builder/configs/carousel.d.ts

@@ -1,5 +1,5 @@
 import { Easing, TransitionType } from '../../../../types/src/index.ts';
-import { PropertyConfig } from '../../../../types/src/content-builder';
+import { ConfigsOptions, PropertyConfig } from '../../../../types/src/content-builder';
 import { ContentType, SourceVariant } from '../../../../types/src/gallery';
 import { GalleryItemCardType, GalleryItemContentPosition, GalleryItemContentVariant, GalleryItemEffect, GalleryItemTextRevealStyle, GalleryItemZoomStyle } from '../../../../types/src/gallery-item';
 import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
@@ -17,8 +17,10 @@ type Attributes = {
     'content-variant': GalleryItemContentVariant;
     'data-constraints': boolean;
     'details-source-field': string;
+    'download-format': string;
     easing: Easing;
     effect: GalleryItemEffect;
+    format: string;
     'header-source-field': string;
     'highlight-border': boolean;
     'highlight-color-overlay': boolean;
@@ -34,12 +36,14 @@ type Attributes = {
     'source-variant': SourceVariant;
     src: string;
     'text-reveal-style': GalleryItemTextRevealStyle;
+    'transformation-record-id': string;
+    transformations: string;
     'transition-type': TransitionType;
     variant: string;
     'zoom-style': GalleryItemZoomStyle;
 };
 declare const _default: {
-    configs: (localize: LocalizeController) => Array<PropertyConfig<Attributes>>;
+    configs: (localize: LocalizeController, options?: ConfigsOptions) => Array<PropertyConfig<Attributes>>;
     defaultValue: Partial<Attributes>;
     stylable: string[];
 };

package/library/packages/organisms/src/content-builder/configs/gallery.d.ts

@@ -1,5 +1,5 @@
 import { Easing, Orientation } from '../../../../types/src/index.ts';
-import { PropertyConfig } from '../../../../types/src/content-builder';
+import { ConfigsOptions, PropertyConfig } from '../../../../types/src/content-builder';
 import { ContentType, GalleryVariant, OverflowBehavior, SourceVariant } from '../../../../types/src/gallery';
 import { GalleryItemCardType, GalleryItemContentPosition, GalleryItemContentVariant, GalleryItemEffect, GalleryItemShowContentType, GalleryItemTextRevealStyle, GalleryItemZoomStyle } from '../../../../types/src/gallery-item';
 import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
@@ -17,8 +17,10 @@ type Attribute = {
     'content-type': ContentType;
     'content-variant': GalleryItemContentVariant;
     'details-source-field': string;
+    'download-format': string;
     easing: Easing;
     effect: GalleryItemEffect;
+    format: string;
     'header-source-field': string;
     'highlight-background': boolean;
     'highlight-border': boolean;
@@ -40,11 +42,13 @@ type Attribute = {
     'source-variant': SourceVariant;
     src: string;
     'text-reveal-style': GalleryItemTextRevealStyle;
+    'transformation-record-id': string;
+    transformations: string;
     variant: GalleryVariant;
     'zoom-style': GalleryItemZoomStyle;
 };
 declare const _default: {
-    configs: (localize: LocalizeController) => Array<PropertyConfig<Attribute>>;
+    configs: (localize: LocalizeController, options?: ConfigsOptions) => Array<PropertyConfig<Attribute>>;
     defaultValue: Partial<Attribute>;
     stylable: string[];
 };

package/library/packages/organisms/src/content-builder/configs/image.d.ts

@@ -1,4 +1,4 @@
-import { PropertyConfig } from '../../../../types/src/content-builder';
+import { ConfigsOptions, PropertyConfig } from '../../../../types/src/content-builder';
 import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
 import { default as CxImage } from '../blocks/image/image';
 
@@ -21,8 +21,10 @@ type Attribute = {
     'download-id'?: CxImage['downloadId'];
     'download-names'?: CxImage['downloadNames'];
     'download-src'?: CxImage['downloadSrc'];
-    easing?: CxImage['easing'];
-    effect?: CxImage['effect'];
+    easing: CxImage['easing'];
+    effect: CxImage['effect'];
+    format: CxImage['format'];
+    'format-dark-mode': CxImage['formatDarkMode'];
     'header-source-field': CxImage['headerSourceField'];
     height: CxImage['height'];
     'height-mode': CxImage['heightMode'];
@@ -41,12 +43,13 @@ type Attribute = {
     src: CxImage['src'];
     'src-dark-mode': CxImage['srcDarkMode'];
     'text-reveal-style'?: CxImage['textRevealStyle'];
+    transformations: string;
     'transition-type'?: string;
     width: CxImage['width'];
     'zoom-style'?: CxImage['zoomStyle'];
 };
 declare const _default: {
-    configs: (localize: LocalizeController) => Array<PropertyConfig<Attribute>>;
+    configs: (localize: LocalizeController, options?: ConfigsOptions) => Array<PropertyConfig<Attribute>>;
     defaultValue: Attribute;
     stylable: string[];
 };

package/library/packages/organisms/src/content-builder/configs/timeline.d.ts

@@ -1,16 +1,19 @@
-import { PropertyConfig } from '../../../../types/src/content-builder';
+import { ConfigsOptions, PropertyConfig } from '../../../../types/src/content-builder';
 import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
 
 type Attributes = {
     data: string;
+    format: string;
     'min-tab-width': string;
     'multi-language': boolean;
     'navigation-arrows': boolean;
     'show-thumbnails': boolean;
     'tabs-per-page': number;
+    'transformation-record-id': string;
+    transformations: string;
 };
 declare const _default: {
-    configs: (localize: LocalizeController) => Array<PropertyConfig<Attributes>>;
+    configs: (localize: LocalizeController, options?: ConfigsOptions) => Array<PropertyConfig<Attributes>>;
     defaultValue: Attributes;
     stylable: string[];
 };

package/library/packages/organisms/src/content-builder/configs/video.d.ts

@@ -1,10 +1,12 @@
 import { ClickAction } from '../../../../types/src/asset-click-action';
-import { PropertyConfig } from '../../../../types/src/content-builder';
+import { AssetVersion } from '../../../../types/src/asset-format-picker';
+import { ConfigsOptions, PropertyConfig } from '../../../../types/src/content-builder';
 import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
 import { default as CxVideo } from '../blocks/video/video';
 
 type Attribute = {
     'additional-fields': string;
+    'asset-version': AssetVersion;
     autoplay: CxVideo['autoplay'];
     'click-action': ClickAction;
     'click-link'?: CxVideo['clickLink'];
@@ -22,6 +24,9 @@ type Attribute = {
     'download-id'?: CxVideo['downloadId'];
     'download-names'?: CxVideo['downloadNames'];
     'download-src'?: CxVideo['downloadSrc'];
+    'format': string;
+    'format-label'?: string;
+    'format-src': string;
     'header-source-field': CxVideo['headerSourceField'];
     height: CxVideo['height'];
     'height-mode': CxVideo['heightMode'];
@@ -38,10 +43,14 @@ type Attribute = {
     'share-src'?: CxVideo['shareSrc'];
     'show-controls': CxVideo['showControls'];
     src: CxVideo['src'];
+    'thumbnail-format'?: string;
+    'thumbnail-record-id'?: string;
+    'thumbnail-transformations'?: string;
+    'version-label'?: string;
     width: CxVideo['width'];
 };
 declare const _default: {
-    configs: (localize: LocalizeController) => Array<PropertyConfig<Attribute>>;
+    configs: (localize: LocalizeController, options?: ConfigsOptions) => Array<PropertyConfig<Attribute>>;
     defaultValue: Partial<Attribute>;
     stylable: string[];
 };