@orangelogic/design-system 2.0.0-29DUO2-beta-3 → 2.0.0-29IORR-beta-2

package/library/packages/molecules/src/folder-select/folder-select.d.ts

@@ -1,6 +1,8 @@
 import { default as CxIcon } from '../../../atoms/src/components/icon/icon.ts';
 import { default as CxInput } from '../../../atoms/src/components/input/input.ts';
+import { default as CxLineClamp } from '../../../atoms/src/components/line-clamp/line-clamp.ts';
 import { default as CxSelect } from '../../../atoms/src/components/select/select.ts';
+import { default as CxTag } from '../../../atoms/src/components/tag/tag.ts';
 import { default as CortexElement } from '../../../base/src/cortex-element.ts';
 import { Folder, FolderSelectApi, FolderSelectVariant } from '../../../types/src/folder-select';
 import { CSSResultGroup, TemplateResult } from 'lit';
@@ -13,7 +15,9 @@ export default class CxFolderSelect extends CortexElement {
         'cx-folder-select-tree': typeof CxFolderSelectTree;
         'cx-icon': typeof CxIcon;
         'cx-input': typeof CxInput;
+        'cx-line-clamp': typeof CxLineClamp;
         'cx-select': typeof CxSelect;
+        'cx-tag': typeof CxTag;
     };
     private readonly localize;
     selectEl?: CxSelect;
@@ -34,6 +38,7 @@ export default class CxFolderSelect extends CortexElement {
     excludeVirtualFolders: boolean;
     extraFolderId: string;
     extraFolderTitle: string;
+    extraFolderIcon: string;
     firstFetchCallback: ((data: Folder[]) => void) | null;
     searchTerm: string;
     constructor();
@@ -41,10 +46,30 @@ export default class CxFolderSelect extends CortexElement {
     handleSearchTermChange(): void;
     private handleSearchTermInputChange;
     private handleSearchTermSelectChange;
+    private handleSelectClear;
+    /**
+     * cx-select's selectedOptions cache (which drives the tag UI in
+     * `multiple` mode) is only recomputed during its own `selectionChanged`
+     * flow — that flow doesn't run in our setup because we no-op
+     * `selectSetOptionSelected` for multi-select (cx-tree owns selection).
+     * After the tree's selection change propagates through `syncBoxes` and
+     * lands on each tree-item's `.selected`, ask cx-select to re-read its
+     * options so the rendered tag list matches.
+     */
+    private handleTreeSelectedChange;
     selectGetOptionValue(option: HTMLElement): string;
     selectGetOptionLabel(option: HTMLElement): string;
     selectGetOptionSelected(option: HTMLElement): boolean | undefined;
     selectFilterCallback(option: HTMLElement): boolean;
+    /**
+     * Custom tag renderer for cx-select multi mode. Identical visuals to the
+     * default tag, but the X click goes through cx-tree's selection flow
+     * (`option.selected = false` → `cx-selected-change` →
+     * cx-folder-select-tree.handleSelectedChange) rather than
+     * cx-select.toggleOptionSelection (which our `selectSetOptionSelected`
+     * no-ops in multi mode, so the default X click would do nothing).
+     */
+    selectGetTag(option: HTMLElement): TemplateResult;
     selectSetOptionSelected(option: HTMLElement, selected: boolean): void;
     updateFunctionProps(): void;
     handleOpenChange(): void;

package/library/packages/molecules/src/index.d.ts

@@ -33,4 +33,5 @@ export { default as CxStepperWizard } from './stepper-wizard/stepper-wizard';
 export { default as CxStorybook } from './storybook/storybook';
 export { default as CxTimeline } from './timeline/timeline';
 export { default as CxTypeface } from './typeface/typeface';
+export { default as CxVideoFormatPicker } from './video-format-picker/video-format-picker';
 export { default as CxViewAndSort } from './view-and-sort/view-and-sort';

package/library/packages/molecules/src/storybook/storybook.d.ts

@@ -1,56 +1,93 @@
 import { default as CxButton } from '../../../atoms/src/components/button/button.ts';
 import { default as CxCard } from '../../../atoms/src/components/card/card.ts';
 import { default as CxCheckbox } from '../../../atoms/src/components/checkbox/checkbox.ts';
-import { default as CxGrid } from '../../../atoms/src/components/grid/grid.ts';
-import { default as CxGridItem } from '../../../atoms/src/components/grid-item/grid-item.ts';
 import { default as CxIconButton } from '../../../atoms/src/components/icon-button/icon-button.ts';
 import { default as CxInput } from '../../../atoms/src/components/input/input.ts';
 import { default as CxMarkdown } from '../../../atoms/src/components/markdown/markdown.ts';
 import { default as CxMutationObserver } from '../../../atoms/src/components/mutation-observer/mutation-observer.ts';
+import { default as CxOption } from '../../../atoms/src/components/option/option.ts';
 import { default as CxSelect } from '../../../atoms/src/components/select/select.ts';
-import { default as CxSpace } from '../../../atoms/src/components/space/space.ts';
+import { default as CxTextarea } from '../../../atoms/src/components/textarea/textarea.ts';
 import { default as CortexElement } from '../../../base/src/cortex-element.ts';
+import { CxMutationEvent } from '../../../events/src/events.ts';
+import { StorybookPropConfig } from '../../../types/src/storybook';
 import { CSSResultGroup, TemplateResult } from 'lit';
 
+/**
+ * @summary A live playground that introspects a slotted Cortex component and
+ * renders editable controls for its public reactive properties and slots.
+ *
+ * @description Used in `apps/docs` pages to demonstrate components. The
+ * storybook reads `elementProperties` from the slotted target and renders a
+ * checkbox / input / select per property based on its declared `type`. Object
+ * and array properties accept JSON in the input. Function properties are
+ * intentionally **not** rendered — they cannot be expressed as text input and
+ * writing them as attributes corrupts their value (the function gets
+ * serialized to its source code string by `String(fn)`).
+ *
+ * @slot (default) - The component to demo. The first assigned element is
+ *   inspected; pass `element-selector` to drill into a descendant.
+ *
+ * @csspart base - The card wrapper that hosts the demo and the controls.
+ */
 export default class CxStorybook extends CortexElement {
     static readonly styles: CSSResultGroup;
     static readonly dependencies: {
         'cx-button': typeof CxButton;
         'cx-card': typeof CxCard;
         'cx-checkbox': typeof CxCheckbox;
-        'cx-grid': typeof CxGrid;
-        'cx-grid-item': typeof CxGridItem;
         'cx-icon-button': typeof CxIconButton;
         'cx-input': typeof CxInput;
         'cx-markdown': typeof CxMarkdown;
         'cx-mutation-observer': typeof CxMutationObserver;
+        'cx-option': typeof CxOption;
         'cx-select': typeof CxSelect;
-        'cx-space': typeof CxSpace;
+        'cx-textarea': typeof CxTextarea;
     };
     defaultSlot: HTMLSlotElement;
     mutationObserver: CxMutationObserver;
+    /**
+     * CSS selector relative to the first slotted element. When set, the storybook
+     * targets the matching descendant instead of the slotted root element.
+     */
     elementSelector: string;
-    storybookConfig: Record<string, any[]>;
-    config: Record<string, {
-        default: any;
-        type: any;
-    }>;
-    props: Record<string, any>;
+    /**
+     * Per-property metadata used to render richer controls:
+     *
+     * - Array of strings → renders a `cx-select` with each string as an option.
+     * - Special key `slot` → an array of slot names that the user can append.
+     */
+    storybookConfig: Record<string, string[]>;
+    /** Introspected metadata for each editable public property of the target. */
+    config: Record<string, StorybookPropConfig>;
+    /** Live values for each editable property; mirrors the target component. */
+    props: Record<string, unknown>;
+    /** The component instance being demoed (the slotted root or a descendant). */
     target: HTMLElement | null;
+    /** User-authored slot content keyed by slot name; each entry is an HTML string. */
     slots: Record<string, string[]>;
-    constructor();
-    private handleInputChange;
-    private handleAddSlot;
-    private handleSlotInputChange;
-    private getDefaultSlotValues;
-    private getComponentDefaultProps;
-    private updateRenderedComponent;
-    private handleAddSlotButtonClick;
-    private renderControls;
-    private handleAttributeChange;
     connectedCallback(): void;
-    disconnectedCallback(): void;
+    handleElementSelectorChange(): void;
     handleSlotChange(): void;
+    handleAttributeChange(event: CxMutationEvent): void;
+    private resolveTargetFromSlot;
+    private introspectTargetConfig;
+    private collectExistingSlotEntries;
+    private readInitialProps;
+    private normalizePropValue;
+    private applyPropsToTarget;
+    private applyPropToTarget;
+    private syncPropFromAttribute;
+    private handlePropChange;
+    private handleSlotEntryChange;
+    private handleSlotEntryDelete;
+    private handleAddSlotButtonClick;
+    private appendSlotEntry;
+    private rerenderSlotEntries;
+    private renderControl;
+    private formatControlValue;
+    private renderSlotControls;
+    private renderControls;
     render(): TemplateResult;
 }
 declare global {

package/library/packages/molecules/src/timeline/timeline.d.ts

@@ -4,6 +4,7 @@ import { default as CxTab } from '../../../atoms/src/components/tab/tab.ts';
 import { default as CxTabGroup } from '../../../atoms/src/components/tab-group/tab-group.ts';
 import { default as CxTabPanel } from '../../../atoms/src/components/tab-panel/tab-panel.ts';
 import { default as CortexElement } from '../../../base/src/cortex-element.ts';
+import { Transformation } from '../../../types/src/asset-link-format';
 import { TimelineItem } from '../../../types/src/timeline';
 import { CSSResultGroup } from 'lit';
 
@@ -20,6 +21,8 @@ export default class CxTimeline extends CortexElement {
         'cx-tab-panel': typeof CxTabPanel;
     };
     private readonly localize;
+    private apiSearchAssets;
+    private thumbnailRequestVersion;
     tabGroup?: CxTabGroup;
     data: TimelineItem[];
     /**
@@ -42,6 +45,17 @@ export default class CxTimeline extends CortexElement {
      * The minimum width of the tab.
      */
     minTabWidth: number;
+    /**
+     * Asset transformation proxy format key.
+     */
+    format: string;
+    /**
+     * Asset transformations applied to the image.
+     */
+    transformations: Transformation[];
+    /** Proxy URLs resolved from apiSearchAssets, keyed by item.id. */
+    private resolvedThumbnails;
+    handleDataChange(): Promise<void>;
     private handlePreviousClick;
     private handleNextClick;
     render(): import('lit').TemplateResult<1>;

package/library/packages/molecules/src/video-format-picker/video-format-picker.d.ts

@@ -0,0 +1,55 @@
+import { default as CxButton } from '../../../atoms/src/components/button/button.ts';
+import { default as CxIconButton } from '../../../atoms/src/components/icon-button/icon-button.ts';
+import { default as CxInput } from '../../../atoms/src/components/input/input.ts';
+import { default as CxSpace } from '../../../atoms/src/components/space/space.ts';
+import { default as CxTypography } from '../../../atoms/src/components/typography/typography.ts';
+import { default as CortexElement } from '../../../base/src/cortex-element.ts';
+import { VideoFormatValue } from '../../../types/src/video-format-picker';
+import { CSSResultGroup } from 'lit';
+
+/**
+ * @summary The `cx-video-format-picker` component lets users choose and clear a video display format.
+ *
+ * @event cx-video-format-select - Emitted when a video format is selected. Detail is a `VideoFormatValue`.
+ * @event cx-video-format-delete - Emitted when the selected format is cleared.
+ * @event cx-asset-request-status - Emitted when the format request status changes.
+ */
+export default class CxVideoFormatPicker extends CortexElement {
+    static readonly styles: CSSResultGroup;
+    static readonly dependencies: {
+        'cx-button': typeof CxButton;
+        'cx-icon-button': typeof CxIconButton;
+        'cx-input': typeof CxInput;
+        'cx-space': typeof CxSpace;
+        'cx-typography': typeof CxTypography;
+    };
+    private readonly localize;
+    inputEl?: CxInput;
+    /** The currently selected video format value. */
+    value: VideoFormatValue | undefined;
+    /** Form field name. */
+    name: string;
+    /** The encrypted asset ID of the video asset to request formats for. */
+    assetId: string;
+    /** Whether a value is required. */
+    required: boolean;
+    /** Disables the picker. */
+    disabled: boolean;
+    /**
+     * A callback invoked when the user requests to select a video format.
+     * It receives the asset ID and the current value, and should return a
+     * promise that resolves to a `VideoFormatValue` or null when cancelled.
+     */
+    onRequestVideoFormat: ((assetId: string, value?: VideoFormatValue) => Promise<VideoFormatValue | null | undefined>) | undefined;
+    private get hasValue();
+    private handleRequestFormatClick;
+    private handleDeleteClick;
+    handleValueChange(): Promise<void>;
+    private renderFormatDisplay;
+    render(): import('lit').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'cx-video-format-picker': CxVideoFormatPicker;
+    }
+}

package/library/packages/molecules/src/video-format-picker/video-format-picker.styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('lit').CSSResult;
+export default _default;

package/library/packages/organisms/src/asset-link-format/asset-link-format.d.ts

@@ -42,6 +42,10 @@ export default class CxAssetLinkFormat extends CortexElement {
      * @example 'https://qa-latest.orangelogic.com'
      */
     baseUrl: string | undefined;
+    /**
+     * The token used for authentication with the asset service.
+     */
+    token: string | undefined;
     /**
      * The asset to be formatted.
      * This is an object that contains the asset's details such as ID, original URL, image URL, width, and height.
@@ -89,6 +93,10 @@ export default class CxAssetLinkFormat extends CortexElement {
      */
     selectedProxy: string;
     useCustomExtension: boolean;
+    noMetadata: boolean;
+    noCrop: boolean;
+    noResize: boolean;
+    noRotate: boolean;
     lastImageSize: {
         height: number;
         width: number;
@@ -252,7 +260,7 @@ export default class CxAssetLinkFormat extends CortexElement {
     private handleAssetChange;
     private handleProxiesChange;
     handleSelectedProxyChange(oldValue: unknown): Promise<void>;
-    handleLoadingChange(): Promise<void>;
+    handleLoadingChange(): void;
     private handleSelectedFormatChange;
     private handleResizeSizeChange;
     private handleCropSizeChange;

package/library/packages/organisms/src/asset-link-format/components/asset-link-format-rotation/asset-link-format-rotation.d.ts

@@ -41,21 +41,21 @@ export default class CxAssetLinkFormatRotation extends CortexElement {
     /**
      * The value of the defined quality.
      * This value represents the quality of the asset link format, ranging from 1 to 100.
-     * @default 100
+     * @default 0
      */
     value: number;
+    /**
+     * The value of the defined quality.
+     * This value represents the quality of the asset link format, ranging from 1 to 100.
+     * @default 0
+     */
+    defaultValue: number;
     /**
      * The loading state of the component.
      * This is used to indicate that an operation is in progress, such as applying a new rotation value.
      * @default false
      */
     loading: boolean;
-    /**
-     * The invalid value state of the component.
-     * This is used to indicate that the input value is invalid, such as when it is not a number or out of range.
-     * @default false
-     */
-    invalidValue: boolean;
     handleOpenChange(): void;
     private handleRotationChange;
     private handleButtonClick;

package/library/packages/organisms/src/asset-transformation-dialog/asset-transformation-dialog.d.ts

@@ -0,0 +1,95 @@
+import { default as CxButton } from '../../../atoms/src/components/button/button.ts';
+import { default as CxDialog } from '../../../atoms/src/components/dialog/dialog.ts';
+import { default as CxIconButton } from '../../../atoms/src/components/icon-button/icon-button.ts';
+import { default as CxSpace } from '../../../atoms/src/components/space/space.ts';
+import { default as CxSpinner } from '../../../atoms/src/components/spinner/spinner.ts';
+import { default as CxTypography } from '../../../atoms/src/components/typography/typography.ts';
+import { default as CortexElement } from '../../../base/src/cortex-element.ts';
+import { default as CxCropper } from '../../../molecules/src/cropper/cropper.ts';
+import { Transformation } from '../../../types/src/asset-link-format';
+import { default as CxAssetLinkFormat } from '../asset-link-format/asset-link-format';
+
+/**
+ * @summary Dialog that wraps `cx-cropper` and `cx-asset-link-format` side by side,
+ * allowing users to preview and apply image transformations.
+ *
+ * @slot trigger - Opens the dialog on click or keyboard activation. Typically a `cx-button` or
+ *   `cx-icon-button`. Automatically disabled when `asset-id` is not set.
+ *
+ * @event cx-asset-transformation-dialog-cancel - Emitted when the user closes or cancels the dialog.
+ * @event {{ detail: { format: string; transformations: Transformation[] } }} cx-asset-transformation-dialog-confirm - Emitted when the user saves, with the selected proxy id and transformation array.
+ * @event cx-asset-transformation-dialog-delete - Emitted when the user clears the saved transformations via the delete button.
+ */
+export default class CxAssetTransformationDialog extends CortexElement {
+    static readonly styles: import('lit').CSSResult[];
+    static readonly dependencies: {
+        'cx-asset-link-format': typeof CxAssetLinkFormat;
+        'cx-button': typeof CxButton;
+        'cx-cropper': typeof CxCropper;
+        'cx-dialog': typeof CxDialog;
+        'cx-icon-button': typeof CxIconButton;
+        'cx-space': typeof CxSpace;
+        'cx-spinner': typeof CxSpinner;
+        'cx-typography': typeof CxTypography;
+    };
+    private readonly localize;
+    private readonly fetchAssetController;
+    private readonly hasSlotController;
+    private apiGetAvailableProxies;
+    /** Stores the accessible trigger element for focus return and ARIA updates. */
+    private accessibleTrigger;
+    private readonly triggerSlot;
+    private readonly assetLinkFormat;
+    /** Asset ID used to fetch asset data when the dialog opens. */
+    assetId: string;
+    /** Controls dialog open/close state. */
+    open: boolean;
+    /** Boundary element for cx-dialog positioning. */
+    boundary: HTMLElement;
+    baseUrl: string;
+    /** Authentication token passed to the asset service. */
+    token: string;
+    /** Currently selected proxy format, passed back into cx-asset-link-format on reopen. */
+    format: string;
+    /** The transformations applied when the user last saved, passed back into cx-asset-link-format on reopen. */
+    transformations: Transformation[];
+    /** Show stack of layers indicating the transformations will be applied to multiple assets. */
+    multiple: boolean;
+    /** Hide the crop panel inside cx-asset-link-format. */
+    noCrop: boolean;
+    /** Hide the resize panel inside cx-asset-link-format. */
+    noResize: boolean;
+    /** Hide the rotate panel inside cx-asset-link-format. */
+    noRotate: boolean;
+    /** Asset data fetched on cx-show. */
+    private asset;
+    /** Available proxy formats fetched alongside the asset. */
+    private proxies;
+    private get hasTransformations();
+    handleAssetIdChange(): Promise<void>;
+    handleOpenChange(): void;
+    /** Syncs disabled state and ARIA attributes on the slotted trigger element.
+     * For cx-button/cx-icon-button, ARIA is set on the inner <button> so screen readers
+     * announce the correct role/state rather than the custom-element host. */
+    private updateAccessibleTrigger;
+    /** Fetches the asset and its available proxies when the dialog opens.
+     * Guards on `result.id` because `fetchAssetByID` returns `{}` on network error. */
+    private handleDialogShow;
+    private handleTriggerClick;
+    private handleTriggerKeyDown;
+    /** Prevents the default scroll action for Space on keyup (some browsers fire scroll on keyup). */
+    private handleTriggerKeyUp;
+    private handleTriggerSlotChange;
+    private handleClose;
+    private handleDeleteClick;
+    private handleRequestClose;
+    private handleSave;
+    private handleCancel;
+    private handleAssetLinkFormatShow;
+    render(): import('lit').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'cx-asset-transformation-dialog': CxAssetTransformationDialog;
+    }
+}

package/library/packages/organisms/src/asset-transformation-dialog/asset-transformation-dialog.styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('lit').CSSResult;
+export default _default;

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;
+}