/********************************************************************************
 * Copyright (c) 2026 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * https://www.eclipse.org/legal/epl-2.0
 *
 * SPDX-License-Identifier: EPL-2.0
 ********************************************************************************/
import { FocusEvent, KeyboardEvent, RefCallback, RefObject } from 'react';
/** Linear cursor steps in reading order, for driving the cursor from outside the grid. */
export type GridStep = 'next' | 'previous';
export interface GridCursorOptions {
    /** Show the cursor ring on the active item (sets `data-cursor-visible` on the container). */
    cursorVisible?: boolean;
    /** Called when ArrowUp is pressed on the first row (e.g. to hand focus back to a search field). */
    onExitTop?: () => void;
}
export interface GridContainerProps {
    ref: RefObject<HTMLElement>;
    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
    onFocus: (event: FocusEvent<HTMLElement>) => void;
    'data-cursor-visible'?: string;
}
export interface GridItemProps {
    ref: RefCallback<HTMLElement>;
    tabIndex: number;
    'data-active'?: string;
}
export interface GridCursor {
    /** Spread onto the CSS grid container. */
    containerProps: GridContainerProps;
    /** Spread onto the focusable element of the item at `index`. */
    itemProps: (index: number) => GridItemProps;
    /** Step the cursor one item in reading order without moving focus (e.g. while a search field keeps focus). */
    move: (step: GridStep) => void;
    /** Click the item under the cursor. */
    openActive: () => void;
    /** Put the cursor back on the first item (e.g. when the list is replaced). */
    reset: () => void;
}
/**
 * Cursor for a CSS grid of focusable items.
 *
 * The active item is both the visible cursor (`data-active`, styled while the
 * container has `data-cursor-visible`) and the grid's only tab stop (roving
 * tabindex). It moves two ways: arrow keys inside the grid move real focus
 * across both axes, while `move()` steps the cursor one item at a time in
 * reading order with focus staying wherever it is. The column count is read
 * from the container's computed grid tracks, so it adapts to viewport width.
 */
export declare function useGridCursor(itemCount: number, options?: GridCursorOptions): GridCursor;
//# sourceMappingURL=use-grid-cursor.d.ts.map