carbon-components-angular/table/data-grid-interaction-model.class.d.ts

Next generation components

/**
 *
 * carbon-angular v0.0.0 | data-grid-interaction-model.class.d.ts
 *
 * Copyright 2014, 2024 IBM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0

 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


import { BehaviorSubject, Observable } from "rxjs";
import { TableAdapter } from "./table-adapter.class";
/**
 * The current and previous position in the grid.
 *
 * `current` and `previous` are tuples that follow the `[row, column]` convention.
 */
export interface DataGridPosition {
    current: [number, number];
    previous: [number, number];
}
/**
 * `DataGridInteractionModel` provides centralized control over arbitrary 2d grids, following the w3 specs.
 *
 * Refs:
 *  - https://www.w3.org/TR/wai-aria-practices/examples/grid/dataGrids.html
 *  - https://www.w3.org/TR/wai-aria-practices/#grid
 *
 * Example usage (taken from `table.component`):
```typescript
// a standard HTML table
const table = this.elementRef.nativeElement.querySelector("table") as HTMLTableElement;

// `TableDomAdapter` implements `TableAdapter` and provides a consistent interface to query rows and columns in a table
const tableAdapter = new TableDomAdapter(table);

// the keydown events that we'll use for keyboard navigation of the table
const keydownEventStream = fromEvent<KeyboardEvent>(table, "keydown");

// the click events we'll use to ensure focus is updated correctly on click
const clickEventStream = fromEvent<MouseEvent>(table, "click");

// the `DataGridInteractionModel` instance!
this.interactionModel = new DataGridInteractionModel(keydownEventStream, clickEventStream, tableAdapter);

// subscribe to the combined position updates
this.interactionModel.position.subscribe(event => {
    const [currentRow, currentColumn] = event.current;
    const [previousRow, previousColumn] = event.previous;

    // query the TableAdapter for the cell at the current row and column ...
    const currentElement = tableAdapter.getCell(currentRow, currentColumn);
    // ... and make it focusable it
    Table.setTabIndex(currentElement, 0);

    // if the model has just initialized don't focus or reset anything
    if (previousRow === -1 || previousColumn === -1) { return; }

    // query the TableAdapter for the cell at the previous row and column ...
    const previousElement = tableAdapter.getCell(previousRow, previousColumn);
    // ... and make it unfocusable (now there is only a single focusable cell)
    Table.setTabIndex(previousElement, -1);

    // finally, focus the current cell (skipped during initilzation)
    Table.focus(currentElement);
});
```
 */
export declare class DataGridInteractionModel {
    protected keyboardEventStream: Observable<KeyboardEvent>;
    protected clickEventStream: Observable<MouseEvent>;
    protected tableAdapter: TableAdapter;
    /**
     * An Observable that provides an aggregated view of the `rowIndex` and `columnIndex` Observables
     */
    readonly position: Observable<DataGridPosition>;
    /**
     * An Observable that provides the current and previous row indexes.
     */
    readonly rowIndex: Observable<{
        current: number;
        previous: number;
    }>;
    /**
     * An Observable that provides the current and previous column indexes.
     */
    readonly columnIndex: Observable<{
        current: number;
        previous: number;
    }>;
    /**
     * Internal subject to handle changes in row
     */
    protected rowSubject: BehaviorSubject<{
        current: number;
        previous: number;
    }>;
    /**
     * Internal subject to handle changes in column
     */
    protected columnSubject: BehaviorSubject<{
        current: number;
        previous: number;
    }>;
    /**
     * The latest value emitted by the rowSubject
     */
    protected get currentRow(): number;
    /**
     * The latest value emitted by the columnSubject
     */
    protected get currentColumn(): number;
    /**
     * The last column as reported by the adapter
     */
    protected get lastColumn(): number;
    /**
     * The last row as reported by the adapter
     */
    protected get lastRow(): number;
    /**
     * `DataGridInteractionModel` requires knowledge of events, and a representation of your table/grid to be useful.
     *
     * @param keyboardEventStream an Observable of KeyboardEvents. Should be scoped to the table container.
     * @param clickEventStream an Observable of ClickEvents. should only include clicks that take action on items known by the TableAdapter
     * @param tableAdapter an instance of a concrete class that implements TableAdapter. The standard carbon table uses TableDomAdapter
     */
    constructor(keyboardEventStream: Observable<KeyboardEvent>, clickEventStream: Observable<MouseEvent>, tableAdapter: TableAdapter);
    /**
     * Handles moving the position according to the w3 datagrid navigation specs
     *
     * Refs:
     *  - https://www.w3.org/TR/wai-aria-practices/examples/grid/dataGrids.html
     *  - https://www.w3.org/TR/wai-aria-practices/#grid
     *
     * @param event the KeyboardEvent to handle
     */
    handleKeyboardEvent(event: KeyboardEvent): void;
    /**
     * Handles moving the position to the clicked cell
     *
     * @param event the MouseEvent to handle
     */
    handleClickEvent(event: MouseEvent): void;
    /**
     * Jump to a specific column without changing the row
     *
     * @param index column to jump to
     */
    goToColumn(index: number): void;
    /**
     * Jump to a specific row without changing the column
     *
     * @param index row to jump to
     */
    goToRow(index: number): void;
    /**
     * Jump to the specified row and column
     *
     * @param param0 an object that contains `row` and `column` properties
     */
    goTo({ row, column }: {
        row: any;
        column: any;
    }): void;
    /**
     * Convenience method to reset the tab indexes on a standard carbon table.
     * For custom tables you may want to reset the indexes manually and simply call `.reset()`
     */
    resetTabIndexes(newTabIndex?: number): void;
    /**
     * Resets the models focus position
     */
    reset(): void;
}