@eristack/spreadsheet-operator/dist/react/scope.d.ts

Headless spreadsheet keyboard operator — active-grid scope, cell navigation, Excel-like Enter/Tab editing

import { type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent, type ReactNode } from "react";
import { type CellAddress, type GridDescriptor, type GridId, type SpreadsheetCommitEvent, type SpreadsheetOperator, type SpreadsheetOperatorConfig, type SpreadsheetOperatorState } from "../index.js";
export type SpreadsheetCellEditor = {
    focus(): void;
    selectAll?(): void;
    readValue(): string;
    writeValue?(value: string): void;
    onCommit?(value: string): void;
    onCancel?(): void;
};
export type SpreadsheetScopeApi = {
    readonly operator: SpreadsheetOperator;
    readonly state: SpreadsheetOperatorState;
    registerEditor(gridId: GridId, address: CellAddress, editor: SpreadsheetCellEditor): () => void;
};
export declare function useSpreadsheetScope(): SpreadsheetScopeApi;
export declare function useSpreadsheetGridId(): GridId;
export type SpreadsheetGridIdProviderProps = {
    gridId: GridId;
    children: ReactNode;
};
/**
 * Supplies the grid id to `SpreadsheetNavCell` / `useSpreadsheetCellEditor` when you
 * render your own container with `useSpreadsheetGrid` instead of `SpreadsheetTable`.
 */
export declare function SpreadsheetGridIdProvider({ gridId, children }: SpreadsheetGridIdProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<string | null>>;
/** Minimal DOM shape so the guards stay testable without jsdom. */
export type KeyTargetLike = {
    closest(selector: string): {
        getAttribute(name: string): string | null;
    } | null;
    matches?(selector: string): boolean;
    isContentEditable?: boolean;
};
/**
 * True when a keydown came from a text-entry element that does not belong to the
 * active grid (a search box, a header field). The operator must not steal those keys.
 */
export declare function isKeyTargetOutsideActiveGrid(target: KeyTargetLike | null | undefined, activeGridId: GridId): boolean;
/** True when a pointer-down landed outside every registered grid element. */
export declare function isPointerTargetOutsideGrids(target: KeyTargetLike | null | undefined): boolean;
export type SpreadsheetScopeProviderProps = {
    children: ReactNode;
    config?: SpreadsheetOperatorConfig;
    onCommit?: (event: SpreadsheetCommitEvent) => void;
    /**
     * Pointer-down outside every grid commits any edit and deactivates the operator
     * (Excel behaviour). Default `true`. Set `false` when the app owns deactivation.
     */
    deactivateOnOutsidePointerDown?: boolean;
};
export declare function SpreadsheetScopeProvider({ children, config, onCommit, deactivateOnOutsidePointerDown, }: SpreadsheetScopeProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SpreadsheetScopeApi | null>>;
export type UseSpreadsheetGridResult = {
    gridProps: {
        role: "grid";
        "data-spreadsheet-grid": string;
        "data-spreadsheet-active"?: "";
        tabIndex: number;
        onMouseDown: (event: ReactMouseEvent<HTMLElement>) => void;
    };
    activeAddress: CellAddress | null;
    editing: boolean;
    isGridActive: boolean;
};
export declare function useSpreadsheetGrid(descriptor: GridDescriptor): UseSpreadsheetGridResult;
export type SpreadsheetTableProps = {
    descriptor: GridDescriptor;
    children: ReactNode;
    className?: string;
};
export declare function SpreadsheetTable({ descriptor, children, className }: SpreadsheetTableProps): import("react").FunctionComponentElement<import("react").ProviderProps<string | null>>;
export type SpreadsheetNavCellProps = {
    address: CellAddress;
    children?: ReactNode;
    className?: string;
};
export declare function SpreadsheetNavCell({ address, children, className }: SpreadsheetNavCellProps): import("react").DetailedReactHTMLElement<{
    role: "gridcell";
    className: string | undefined;
    "data-spreadsheet-cell": string;
    "data-row": number;
    "data-col": number;
    "data-active": string | undefined;
    "data-editing": string | undefined;
    "aria-selected": boolean;
    tabIndex: number;
}, HTMLElement>;
export type UseSpreadsheetCellEditorOptions = {
    address: CellAddress;
    readValue: () => string;
    writeValue?: (value: string) => void;
    onCommit?: (value: string) => void;
    onCancel?: () => void;
    focus?: () => void;
    selectAll?: () => void;
};
export declare function useSpreadsheetCellEditor(options: UseSpreadsheetCellEditorOptions): {
    editing: boolean;
    seed: string | undefined;
};
export type SpreadsheetTextCellProps = {
    address: CellAddress;
    value: string;
    onCommit: (value: string) => void;
};
export declare function SpreadsheetTextCell({ address, value, onCommit }: SpreadsheetTextCellProps): import("react").DetailedReactHTMLElement<{
    ref: import("react").RefObject<HTMLInputElement | null>;
    defaultValue: string;
    "data-spreadsheet-editor": string;
    onKeyDown: (event: ReactKeyboardEvent<HTMLInputElement>) => void;
    onBlur: () => void;
}, HTMLInputElement> | import("react").ReactElement<{
    "data-spreadsheet-display": string;
}, string | import("react").JSXElementConstructor<any>>;
//# sourceMappingURL=scope.d.ts.map