ng-virtual-list 19.7.21 → 19.7.23

package/README.md

@@ -115,7 +115,7 @@ items = Array.from({ length: 100000 }, (_, i) => ({ id: i, name: `Item #${i}` })
 
 Template:
 ```html
-<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="50"
+<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="5" [maxBufferSize]="20"
     [itemRenderer]="horizontalItemRenderer" [itemSize]="64" [methodForSelecting]="'select'"
     [selectedIds]="2" (onSelect)="onSelect($event)" (onItemClick)="onItemClick($event)"></ng-virtual-list>
 
@@ -166,8 +166,8 @@ export class AppComponent {
 Template:
 ```html
 <ng-virtual-list class="list" direction="horizontal" [items]="horizontalGroupItems" [itemRenderer]="horizontalGroupItemRenderer"
-    [bufferSize]="50" [itemConfigMap]="horizontalGroupItemConfigMap" [itemSize]="54" [snap]="true" [methodForSelecting]="'multi-select'"
-    [selectedIds]="[3,2]" (onSelect)="onSelect($event)" (onItemClick)="onItemClick($event)"></ng-virtual-list>
+    [bufferSize]="5" [maxBufferSize]="20" [itemConfigMap]="horizontalGroupItemConfigMap" [itemSize]="54" [snap]="true"
+    methodForSelecting="multi-select" [selectedIds]="[3,2]" (onSelect)="onSelect($event)" (onItemClick)="onItemClick($event)"></ng-virtual-list>
 
 <ng-template #horizontalGroupItemRenderer let-data="data" let-config="config">
   @if (data) {
@@ -239,7 +239,7 @@ export class AppComponent {
 
 Template:
 ```html
-<ng-virtual-list class="list simple" [items]="items" [bufferSize]="50" [itemRenderer]="itemRenderer"
+<ng-virtual-list class="list simple" [items]="items" [bufferSize]="5" [maxBufferSize]="20" [itemRenderer]="itemRenderer"
   [itemSize]="40"></ng-virtual-list>
 
 <ng-template #itemRenderer let-data="data">
@@ -280,7 +280,7 @@ export class AppComponent {
 
 Template:
 ```html
-<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="50" [itemRenderer]="groupItemRenderer"
+<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="5" [maxBufferSize]="20" [itemRenderer]="groupItemRenderer"
     [itemConfigMap]="groupItemConfigMap" [itemSize]="40" [snap]="false"></ng-virtual-list>
 
 <ng-template #groupItemRenderer let-data="data">
@@ -307,7 +307,7 @@ Template:
 
 Template (with snapping):
 ```html
-<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="50" [itemRenderer]="groupItemRenderer"
+<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="5" [maxBufferSize]="20" [itemRenderer]="groupItemRenderer"
     [itemConfigMap]="groupItemConfigMap" [itemSize]="40" [snap]="true"></ng-virtual-list>
 
 <ng-template #groupItemRenderer let-data="data">
@@ -372,7 +372,7 @@ Template
   <button class="scroll-to__button" (click)="onButtonScrollToIdClickHandler($event)">Scroll</button>
 </div>
 
-<ng-virtual-list #virtualList class="list" [items]="items" [itemRenderer]="itemRenderer" [bufferSize]="50"
+<ng-virtual-list #virtualList class="list" [items]="items" [itemRenderer]="itemRenderer" [bufferSize]="5" [maxBufferSize]="20"
   [itemSize]="40"></ng-virtual-list>
 
 <ng-template #itemRenderer let-data="data">
@@ -426,7 +426,7 @@ Virtual list with height-adjustable elements.
 
 Template
 ```html
-<ng-virtual-list #dynamicList class="list" [items]="groupDynamicItems" [itemRenderer]="groupItemRenderer" [bufferSize]="10"
+<ng-virtual-list #dynamicList class="list" [items]="groupDynamicItems" [itemRenderer]="groupItemRenderer" [bufferSize]="5" [maxBufferSize]="20"
       [itemConfigMap]="groupDynamicItemConfigMap" [dynamicSize]="true" [snap]="true"></ng-virtual-list>
 
 <ng-template #groupItemRenderer let-data="data">
@@ -565,7 +565,7 @@ List items are encapsulated in shadowDOM, so to override default styles you need
 Selecting even elements:
 
 ```html
-<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="5"
+<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="5" [maxBufferSize]="20"
   [itemRenderer]="horizontalItemRenderer" [itemSize]="54"></ng-virtual-list>
 
 <ng-template #horizontalItemRenderer let-data="data" let-config="config">
@@ -589,7 +589,7 @@ Selecting even elements:
 
 ## 📚 API
 
-[NgVirtualListComponent](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/ng-virtual-list.component.ts)
+### [NgVirtualListComponent](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/ng-virtual-list.component.ts)
 
 Inputs
 
@@ -630,9 +630,6 @@ Outputs
 | onScrollReachStart | void | Fires when the scroll reaches the start. |
 | onScrollReachEnd | void | Fires when the scroll reaches the end. |
 
-
-<br/>
-
 Methods
 
 | Method | Type | Description |
@@ -640,6 +637,25 @@ Methods
 | scrollTo | (id: [Id](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/types/id.ts), behavior: ScrollBehavior = 'auto') => number | The method scrolls the list to the element with the given id and returns the value of the scrolled area. Behavior accepts the values ​​"auto", "instant" and "smooth". |
 | scrollToEnd | (behavior?: ScrollBehavior) => void | Scrolls the scroll area to the desired element with the specified ID. |
 | getItemBounds | (id: [Id](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/types/id.ts), behavior?: ScrollBehavior) => void | Returns the bounds of an element with a given id |
+| focus | [Id](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/types/id.ts), align: [FocusAlignment](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/types/focus-alignment.ts) = [FocusAlignments.NONE](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/enums/focus-alignments.ts) | Focus an list item by a given id. |
+
+<br/>
+
+### Template API
+
+```html
+<ng-template #itemRenderer let-data="data" let-config="config" let-measures="measures">
+  <!-- content -->
+</ng-template>
+```
+
+Properties
+
+| Property | Type | Description |
+|--|--|--|
+| data | {\[id: [Id](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/types/id.ts) \], [otherProps: string]: any;} | Collection item data. |
+| config | [IDisplayObjectConfig](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/models/display-object-config.model.ts) | Display object configuration. A set of `select`, `collapse`, and `focus` methods are also provided. |
+| measures | [IDisplayObjectMeasures](https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/models/display-object-measures.model.ts) \| undefined | Display object metrics. |
 
 <br/>
 

package/fesm2022/ng-virtual-list.mjs

@@ -2,9 +2,9 @@ import * as i1 from '@angular/common';
 import { CommonModule } from '@angular/common';
 import * as i0 from '@angular/core';
 import { Injectable, inject, signal, ElementRef, ChangeDetectionStrategy, Component, viewChild, output, input, ViewContainerRef, ViewChild, ViewEncapsulation } from '@angular/core';
-import { Subject, tap, fromEvent, combineLatest, map, filter, distinctUntilChanged, switchMap, of } from 'rxjs';
-import { BehaviorSubject } from 'rxjs/internal/BehaviorSubject';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
+import { BehaviorSubject } from 'rxjs/internal/BehaviorSubject';
+import { Subject, tap, fromEvent, combineLatest, map, filter, distinctUntilChanged, switchMap, of } from 'rxjs';
 
 /**
  * Action modes for collection elements.
@@ -82,6 +82,20 @@ var SnappingMethods;
     SnappingMethods["ADVANCED"] = "advanced";
 })(SnappingMethods || (SnappingMethods = {}));
 
+/**
+ * Focus Alignments.
+ * @link https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/enums/focus-alignments.ts
+ * @author Evgenii Grebennikov
+ * @email djonnyx@gmail.com
+ */
+var FocusAlignments;
+(function (FocusAlignments) {
+    FocusAlignments["NONE"] = "none";
+    FocusAlignments["START"] = "start";
+    FocusAlignments["CENTER"] = "center";
+    FocusAlignments["END"] = "end";
+})(FocusAlignments || (FocusAlignments = {}));
+
 const DEFAULT_ITEM_SIZE = 24;
 const DEFAULT_BUFFER_SIZE = 2;
 const DEFAULT_MAX_BUFFER_SIZE = 10;
@@ -327,11 +341,11 @@ class NgVirtualListService {
         }
     }
     itemToFocus;
-    focus(element) {
+    focus(element, align = FocusAlignments.CENTER) {
         element.focus({ preventScroll: true });
         if (element.parentElement) {
             const pos = parseFloat(element.parentElement?.getAttribute('position') ?? '0');
-            this.itemToFocus?.(element, pos);
+            this.itemToFocus?.(element, pos, align);
         }
     }
     areaFocus(id) {
@@ -410,7 +424,7 @@ const validateFunction = (value, undefinable = false, nullable = false) => {
     return (undefinable && isUndefinable(value)) || (nullable && isNullable(value)) || typeof value === 'function';
 };
 
-const ATTR_AREA_SELECTED = 'area-selected', TABINDEX = 'ng-vl-index', KEY_SPACE = " ", KEY_ARR_LEFT = "ArrowLeft", KEY_ARR_UP = "ArrowUp", KEY_ARR_RIGHT = "ArrowRight", KEY_ARR_DOWN = "ArrowDown", EVENT_FOCUS_IN = 'focusin', EVENT_FOCUS_OUT = 'focusout', EVENT_KEY_DOWN = 'keydown';
+const ATTR_AREA_SELECTED = 'area-selected', TABINDEX = 'ng-vl-index', POSITION = 'position', POSITION_ZERO = '0', ID = 'item-id', KEY_SPACE = " ", KEY_ARR_LEFT = "ArrowLeft", KEY_ARR_UP = "ArrowUp", KEY_ARR_RIGHT = "ArrowRight", KEY_ARR_DOWN = "ArrowDown", EVENT_FOCUS_IN = 'focusin', EVENT_FOCUS_OUT = 'focusout', EVENT_KEY_DOWN = 'keydown';
 const getElementByIndex = (index) => {
     return `[${TABINDEX}="${index}"]`;
 };
@@ -430,7 +444,7 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
     _isCollapsed = false;
     config = signal({});
     measures = signal(undefined);
-    focus = signal(false);
+    focused = signal(false);
     part = signal(PART_DEFAULT_ITEM);
     regular = false;
     data = signal(undefined);
@@ -494,21 +508,28 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
         }
         this._service.collapse(data, collapsed);
     };
+    _focusHandler = () => 
+    /**
+    * Focus a list item
+    */
+    (align = FocusAlignments.CENTER) => {
+        this.focus(align);
+    };
     constructor() {
         super();
         this._id = this._service.generateComponentId();
         this._elementRef.nativeElement.setAttribute('id', String(this._id));
-        const $data = toObservable(this.data), $focus = toObservable(this.focus);
-        $focus.pipe(takeUntilDestroyed(), tap(v => {
+        const $data = toObservable(this.data), $focused = toObservable(this.focused);
+        $focused.pipe(takeUntilDestroyed(), tap(v => {
             this._service.areaFocus(v ? this._id : this._service.focusedId === this._id ? null : this._service.focusedId);
         })).subscribe();
         fromEvent(this.element, EVENT_FOCUS_IN).pipe(takeUntilDestroyed(), tap(e => {
-            this.focus.set(true);
+            this.focused.set(true);
             this.updateConfig(this._data);
             this.updatePartStr(this._data, this._isSelected, this._isCollapsed);
         })).subscribe(),
             fromEvent(this.element, EVENT_FOCUS_OUT).pipe(takeUntilDestroyed(), tap(e => {
-                this.focus.set(false);
+                this.focused.set(false);
                 this.updateConfig(this._data);
                 this.updatePartStr(this._data, this._isSelected, this._isCollapsed);
             })).subscribe(),
@@ -611,23 +632,34 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
             }
         }
     }
+    focus(align = FocusAlignments.CENTER) {
+        if (this._service.listElement) {
+            const tabIndex = this._data?.config?.tabIndex ?? 0;
+            let index = tabIndex;
+            const el = this._service.listElement.querySelector(getElementByIndex(index));
+            if (el) {
+                this._service.focus(el, align);
+            }
+        }
+    }
     updateMeasures(v) {
         this.measures.set(v?.measures ? { ...v.measures } : undefined);
     }
     updateConfig(v) {
         this.config.set({
-            ...v?.config || {}, selected: this._isSelected, collapsed: this._isCollapsed, focus: this.focus(),
-            collapse: this._collapseHandler(v), select: this._selectHandler(v)
+            ...v?.config || {}, selected: this._isSelected, collapsed: this._isCollapsed, focused: this.focused(),
+            collapse: this._collapseHandler(v), select: this._selectHandler(v), focus: this._focusHandler(),
         });
     }
     update() {
         const data = this._data, regular = this.regular, length = this._regularLength;
         if (data) {
+            this._elementRef.nativeElement.setAttribute(ID, `${data.id}`);
             const styles = this._elementRef.nativeElement.style;
             styles.zIndex = data.config.zIndex;
             if (data.config.snapped) {
-                this._elementRef.nativeElement.setAttribute('position', data.config.sticky === 1 ? '0' : `${data.config.isVertical ? data.measures.y : data.measures.x}`);
-                styles.transform = data.config.sticky === 1 ? ZEROS_TRANSLATE_3D : `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.x}${PX}, ${data.config.isVertical ? data.measures.y : 0}${PX} , 0)`;
+                this._elementRef.nativeElement.setAttribute(POSITION, data.config.sticky === 1 ? POSITION_ZERO : `${data.config.isVertical ? data.measures.y : data.measures.x}`);
+                styles.transform = data.config.sticky === 1 ? ZEROS_TRANSLATE_3D : `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.x}${PX}, ${data.config.isVertical ? data.measures.y : 0}${PX}, ${POSITION_ZERO})`;
                 ;
                 if (!data.config.isSnappingMethodAdvanced) {
                     styles.position = POSITION_STICKY;
@@ -636,17 +668,20 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
             else {
                 styles.position = POSITION_ABSOLUTE;
                 if (regular) {
-                    this._elementRef.nativeElement.setAttribute('position', '0');
-                    styles.transform = `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.delta}${PX}, ${data.config.isVertical ? data.measures.delta : 0}${PX} , 0)`;
+                    this._elementRef.nativeElement.setAttribute(POSITION, POSITION_ZERO);
+                    styles.transform = `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.delta}${PX}, ${data.config.isVertical ? data.measures.delta : 0}${PX}, ${POSITION_ZERO})`;
                 }
                 else {
-                    this._elementRef.nativeElement.setAttribute('position', `${data.config.isVertical ? data.measures.y : data.measures.x}`);
-                    styles.transform = `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.x}${PX}, ${data.config.isVertical ? data.measures.y : 0}${PX} , 0)`;
+                    this._elementRef.nativeElement.setAttribute(POSITION, `${data.config.isVertical ? data.measures.y : data.measures.x}`);
+                    styles.transform = `${TRANSLATE_3D}(${data.config.isVertical ? 0 : data.measures.x}${PX}, ${data.config.isVertical ? data.measures.y : 0}${PX}, ${POSITION_ZERO})`;
                 }
             }
             styles.height = data.config.isVertical ? data.config.dynamic ? SIZE_AUTO : `${data.measures.height}${PX}` : regular ? length : SIZE_100_PERSENT;
             styles.width = data.config.isVertical ? regular ? length : SIZE_100_PERSENT : data.config.dynamic ? SIZE_AUTO : `${data.measures.width}${PX}`;
         }
+        else {
+            this._elementRef.nativeElement.removeAttribute(ID);
+        }
     }
     updatePartStr(v, isSelected, isCollapsed) {
         let odd = false;
@@ -667,7 +702,7 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
         if (v ? v.config.new : false) {
             part += PART_ITEM_NEW;
         }
-        if (this.focus()) {
+        if (this.focused()) {
             part += PART_ITEM_FOCUSED;
         }
         this.part.set(part);
@@ -714,14 +749,14 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
         this._service.itemClick(this._data);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.14", ngImport: i0, type: NgVirtualListItemComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.14", type: NgVirtualListItemComponent, isStandalone: true, selector: "ng-virtual-list-item", host: { attributes: { "role": "listitem" }, classAttribute: "ngvl__item" }, usesInheritance: true, ngImport: i0, template: "@let item = data();\r\n@let _config = config();\r\n@let _part = part();\r\n@let _measures = measures();\r\n@let renderer = itemRenderer();\r\n\r\n@if (item) {\r\n    <div #listItem [part]=\"_part\" [attr.ng-vl-index]=\"_config.tabIndex || -1\" tabindex=\"0\" class=\"ngvl-item__container\"\r\n        [ngClass]=\"{'snapped': item.config.snapped, 'snapped-out': item.config.snappedOut, 'focus': focus()}\" (click)=\"onClickHandler()\">\r\n        @if (renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data, measures: _measures, config: _config}\" />\r\n        }\r\n    </div>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit;box-sizing:border-box}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.14", type: NgVirtualListItemComponent, isStandalone: true, selector: "ng-virtual-list-item", host: { attributes: { "role": "listitem" }, classAttribute: "ngvl__item" }, usesInheritance: true, ngImport: i0, template: "@let item = data();\r\n@let _config = config();\r\n@let _part = part();\r\n@let _measures = measures();\r\n@let renderer = itemRenderer();\r\n\r\n@if (item) {\r\n    <div #listItem [part]=\"_part\" [attr.ng-vl-index]=\"_config.tabIndex || -1\" tabindex=\"0\" class=\"ngvl-item__container\"\r\n        [ngClass]=\"{'snapped': item.config.snapped, 'snapped-out': item.config.snappedOut, 'focus': focused()}\" (click)=\"onClickHandler()\">\r\n        @if (renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data, measures: _measures, config: _config}\" />\r\n        }\r\n    </div>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit;box-sizing:border-box}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.14", ngImport: i0, type: NgVirtualListItemComponent, decorators: [{
             type: Component,
             args: [{ selector: 'ng-virtual-list-item', imports: [CommonModule], host: {
                         'class': 'ngvl__item',
                         'role': 'listitem',
-                    }, changeDetection: ChangeDetectionStrategy.OnPush, template: "@let item = data();\r\n@let _config = config();\r\n@let _part = part();\r\n@let _measures = measures();\r\n@let renderer = itemRenderer();\r\n\r\n@if (item) {\r\n    <div #listItem [part]=\"_part\" [attr.ng-vl-index]=\"_config.tabIndex || -1\" tabindex=\"0\" class=\"ngvl-item__container\"\r\n        [ngClass]=\"{'snapped': item.config.snapped, 'snapped-out': item.config.snappedOut, 'focus': focus()}\" (click)=\"onClickHandler()\">\r\n        @if (renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data, measures: _measures, config: _config}\" />\r\n        }\r\n    </div>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit;box-sizing:border-box}\n"] }]
+                    }, changeDetection: ChangeDetectionStrategy.OnPush, template: "@let item = data();\r\n@let _config = config();\r\n@let _part = part();\r\n@let _measures = measures();\r\n@let renderer = itemRenderer();\r\n\r\n@if (item) {\r\n    <div #listItem [part]=\"_part\" [attr.ng-vl-index]=\"_config.tabIndex || -1\" tabindex=\"0\" class=\"ngvl-item__container\"\r\n        [ngClass]=\"{'snapped': item.config.snapped, 'snapped-out': item.config.snappedOut, 'focus': focused()}\" (click)=\"onClickHandler()\">\r\n        @if (renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data, measures: _measures, config: _config}\" />\r\n        }\r\n    </div>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit;box-sizing:border-box}\n"] }]
         }], ctorParameters: () => [] });
 
 /**
@@ -2161,7 +2196,7 @@ const isCollectionMode = (src, expected) => {
     return NORMAL_ALIASES.includes(src);
 };
 
-const ROLE_LIST = 'list', ROLE_LIST_BOX = 'listbox';
+const ROLE_LIST = 'list', ROLE_LIST_BOX = 'listbox', ITEM_ID = 'item-id', ITEM_CONTAINER = 'ngvl-item__container';
 const validateScrollIteration = (value) => {
     return Number.isNaN(value) || (value < 0) ? 0 : value > MAX_SCROLL_TO_ITERATIONS ? MAX_SCROLL_TO_ITERATIONS : value;
 }, validateId = (id) => {
@@ -2179,6 +2214,11 @@ const validateScrollIteration = (value) => {
     if (!valid) {
         throw Error('The "iteration" parameter must be of type `number`.');
     }
+}, validateFocusAlignment = (align) => {
+    const valid = validateString(align) && (align === 'none' || align === 'start' || align === 'center' || align === 'end');
+    if (!valid) {
+        throw Error('The "align" parameter must have the value `none`, `start`, `center` or `end`.');
+    }
 };
 /**
  * Virtual list component.
@@ -2643,12 +2683,33 @@ class NgVirtualListComponent {
             this._scrollSize.set(actualScrollSize);
         }
     };
-    itemToFocus = (element, position) => {
+    itemToFocus = (element, position, align = FocusAlignments.CENTER) => {
         const container = this._container()?.nativeElement;
         if (container) {
-            const { width, height } = this._bounds(), { width: elementWidth, height: elementHeight } = element.getBoundingClientRect(), isVertical = this._isVertical, pos = isVertical ? position - (height - elementHeight) * .5 : position - (width - elementWidth) * .5;
-            const params = { [this._isVertical ? TOP_PROP_NAME : LEFT_PROP_NAME]: pos, behavior: 'instant' };
-            container.scrollTo(params);
+            const { width, height } = this._bounds(), { width: elementWidth, height: elementHeight } = element.getBoundingClientRect(), isVertical = this._isVertical;
+            let pos = Number.NaN;
+            switch (align) {
+                case FocusAlignments.START: {
+                    pos = isVertical ? position : position;
+                    break;
+                }
+                case FocusAlignments.CENTER: {
+                    pos = isVertical ? position - (height - elementHeight) * .5 : position - (width - elementWidth) * .5;
+                    break;
+                }
+                case FocusAlignments.END: {
+                    pos = isVertical ? position - (height - elementHeight) : position - (width - elementWidth);
+                    break;
+                }
+                case FocusAlignments.NONE:
+                default: {
+                    break;
+                }
+            }
+            if (!Number.isNaN(pos)) {
+                const params = { [this._isVertical ? TOP_PROP_NAME : LEFT_PROP_NAME]: pos, behavior: 'instant' };
+                container.scrollTo(params);
+            }
         }
     };
     _elementRef = inject((ElementRef));
@@ -2974,6 +3035,20 @@ class NgVirtualListComponent {
         validateId(id);
         return this._trackBox.getItemBounds(id);
     }
+    /**
+     * Focus an list item by a given id.
+     */
+    focus(id, align = FocusAlignments.NONE) {
+        validateId(id);
+        validateFocusAlignment(align);
+        const el = this._list()?.nativeElement.querySelector(`[${ITEM_ID}="${id}"]`);
+        if (el) {
+            const focusedEl = el.querySelector(`.${ITEM_CONTAINER}`);
+            if (focusedEl) {
+                this._service.focus(focusedEl, align);
+            }
+        }
+    }
     /**
      * The method scrolls the list to the element with the given id and returns the value of the scrolled area.
      * Behavior accepts the values ​​"auto", "instant" and "smooth".
@@ -3158,5 +3233,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.14", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { CollectionModes, Directions, MethodsForSelecting, NgVirtualListComponent, NgVirtualListItemComponent, ScrollEvent, SnappingMethods, debounce, toggleClassName };
+export { CollectionModes, Directions, FocusAlignments, MethodsForSelecting, NgVirtualListComponent, NgVirtualListItemComponent, ScrollEvent, SnappingMethods, debounce, toggleClassName };
 //# sourceMappingURL=ng-virtual-list.mjs.map