Skip to content

Commit 422bc4e

Browse files
authored
feat: add API docs for grid cell focus event (#2081)
* feat: add API docs for grid cell focus event Added API docs and type definitions for the cell-focus event. Also corrected type definitions for `EventContextMixin.getEventContext` to always return a `GridEventContext` with all props being optional. Related to: #337 * Align JSDoc with TS definitions
1 parent b9b07bf commit 422bc4e

7 files changed

Lines changed: 25 additions & 3 deletions

File tree

‎packages/vaadin-grid/src/interfaces.d.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ export interface GridFilter {
4141
}
4242

4343
export interface GridEventContext<TItem> {
44-
section: 'body' | 'header' | 'footer' | 'details';
44+
section?: 'body' | 'header' | 'footer' | 'details';
4545
item?: TItem;
4646
column?: GridColumnElement<TItem>;
4747
index?: number;

‎packages/vaadin-grid/src/vaadin-grid-event-context-mixin.d.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ interface EventContextMixin<TItem> {
2727
* This may be the case eg. if the event is fired on the `<vaadin-grid>` element and not any deeper in the DOM, or if
2828
* the event targets the empty part of the grid body.
2929
*/
30-
getEventContext(event: Event): GridEventContext<TItem> | object | null;
30+
getEventContext(event: Event): GridEventContext<TItem>;
3131
}
3232

3333
export { EventContextMixin, EventContextMixinConstructor };

‎packages/vaadin-grid/src/vaadin-grid-event-context-mixin.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ export const EventContextMixin = (superClass) =>
2828
* the event targets the empty part of the grid body.
2929
*
3030
* @param {!Event} event
31-
* @return {GridEventContext | object}
31+
* @return {GridEventContext}
3232
*/
3333
getEventContext(event) {
3434
const context = {};

‎packages/vaadin-grid/src/vaadin-grid-keyboard-navigation-mixin.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -727,4 +727,12 @@ export const KeyboardNavigationMixin = (superClass) =>
727727
if (focusTargetCell === this._footerFocusable) return this.$.footer;
728728
return null;
729729
}
730+
731+
/**
732+
* Fired when a cell is focused with click or keyboard navigation.
733+
*
734+
* Use {@see GridElement#getEventContext} to get detailed information about the event.
735+
*
736+
* @event cell-focus
737+
*/
730738
};

‎packages/vaadin-grid/src/vaadin-grid.d.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ export type GridActiveItemChangedEvent<TItem> = CustomEvent<{ value: TItem }>;
4848
*/
4949
export type GridCellActivateEvent<TItem> = CustomEvent<{ model: GridItemModel<TItem> }>;
5050

51+
/**
52+
* Fired when a cell is focused with click or keyboard navigation.
53+
*/
54+
export type GridCellFocusEvent = CustomEvent;
55+
5156
/**
5257
* Fired when the columns in the grid are reordered.
5358
*/
@@ -96,6 +101,8 @@ export interface GridElementEventMap<TItem> {
96101

97102
'cell-activate': GridCellActivateEvent<TItem>;
98103

104+
'cell-focus': GridCellFocusEvent;
105+
99106
'column-reorder': GridColumnReorderEvent<TItem>;
100107

101108
'column-resize': GridColumnResizeEvent<TItem>;
@@ -330,6 +337,7 @@ export interface GridEventMap<TItem> extends HTMLElementEventMap, GridElementEve
330337
*
331338
* @fires {CustomEvent} active-item-changed - Fired when the `activeItem` property changes.
332339
* @fires {CustomEvent} cell-activate - Fired when the cell is activated with click or keyboard.
340+
* @fires {CustomEvent} cell-focus - Fired when a cell is focused with click or keyboard navigation.
333341
* @fires {CustomEvent} column-reorder - Fired when the columns in the grid are reordered.
334342
* @fires {CustomEvent} column-resize - Fired when the grid column resize is finished.
335343
* @fires {CustomEvent} expanded-items-changed - Fired when the `expandedItems` property changes.

‎packages/vaadin-grid/src/vaadin-grid.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@ const TOUCH_DEVICE = (() => {
253253
*
254254
* @fires {CustomEvent} active-item-changed - Fired when the `activeItem` property changes.
255255
* @fires {CustomEvent} cell-activate - Fired when the cell is activated with click or keyboard.
256+
* @fires {CustomEvent} cell-focus - Fired when a cell is focused with click or keyboard navigation.
256257
* @fires {CustomEvent} column-reorder - Fired when the columns in the grid are reordered.
257258
* @fires {CustomEvent} column-resize - Fired when the grid column resize is finished.
258259
* @fires {CustomEvent} expanded-items-changed - Fired when the `expandedItems` property changes.

‎packages/vaadin-grid/test/typings/grid.types.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ import {
3131
ColumnBaseMixin,
3232
GridActiveItemChangedEvent,
3333
GridCellActivateEvent,
34+
GridCellFocusEvent,
3435
GridColumnElement,
3536
GridColumnReorderEvent,
3637
GridColumnResizeEvent,
@@ -85,6 +86,10 @@ narrowedGrid.addEventListener('cell-activate', (event) => {
8586
assertType<GridItemModel<TestGridItem>>(event.detail.model);
8687
});
8788

89+
narrowedGrid.addEventListener('cell-focus', (event) => {
90+
assertType<GridCellFocusEvent>(event);
91+
});
92+
8893
narrowedGrid.addEventListener('column-reorder', (event) => {
8994
assertType<GridColumnReorderEvent<TestGridItem>>(event);
9095
assertType<GridColumnElement<TestGridItem>[]>(event.detail.columns);

0 commit comments

Comments
 (0)