SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface FormulaInputApi

    What useFormulaInput hands the host input component.

    interface FormulaInputApi {
        canSelectCurrent: boolean;
        dirty: boolean;
        engaged: boolean;
        error: string | null;
        inputProps: {
            onBlur: (e: FocusEvent) => void;
            onChange: (e: ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void;
            onFocus: (e: FocusEvent) => void;
            onKeyDown: (e: KeyboardEvent) => void;
            onMouseDown: (e: MouseEvent) => void;
            onSelect: (e: SyntheticEvent) => void;
            readOnly: boolean;
            ref: (el: HTMLTextAreaElement | HTMLInputElement | null) => void;
            value: string;
        };
        overLength: boolean;
        pointArmed: boolean;
        segments: readonly ReferenceSegmentInfo[];
        text: string;
        tokenBase: number;
        tokens: readonly FormulaToken[]
        | null;
        cancel(): void;
        commit(): void;
        engage(): void;
        evaluateSegment(index: number): Promise<string | null>;
        getRanges(): ICellRanges | null;
        replaceText(next: string, caret?: number): void;
        revert(): void;
        selectCurrent(): void;
        togglePoint(): void;
    }
    Index
    canSelectCurrent dirty engaged error inputProps overLength pointArmed segments text tokenBase tokens
    cancel commit engage evaluateSegment getRanges replaceText revert selectCurrent togglePoint
    canSelectCurrent: boolean

    Whether selectCurrent has a valid landing RIGHT NOW. Always true in 'reference' grammar (the action replaces/appends the whole value). 'formula' grammar: true when the caret sits where a reference can land — on a reference token (re-scope) or where an operand is expected (splice); false mid-token (SU|M), where the chrome should disable the action — without this the selection spliced into random caret spots.

    dirty: boolean

    true when the text differs from the committed value's text.

    engaged: boolean

    true while this field is the reference-mode producer (grid/header/keyboard picks write here).

    error: string | null

    Parse error for the current text (null when valid).

    inputProps: {
        onBlur: (e: FocusEvent) => void;
        onChange: (e: ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void;
        onFocus: (e: FocusEvent) => void;
        onKeyDown: (e: KeyboardEvent) => void;
        onMouseDown: (e: MouseEvent) => void;
        onSelect: (e: SyntheticEvent) => void;
        readOnly: boolean;
        ref: (el: HTMLTextAreaElement | HTMLInputElement | null) => void;
        value: string;
    }

    Spread onto the <input>/<textarea>: value + handlers + element ref.

    Type Declaration

    • onBlur: (e: FocusEvent) => void
    • onChange: (e: ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void
    • onFocus: (e: FocusEvent) => void
    • onKeyDown: (e: KeyboardEvent) => void
    • onMouseDown: (e: MouseEvent) => void
    • onSelect: (e: SyntheticEvent) => void

      Caret/selection moved — re-projects which reference/segment the next pick targets.

    • readOnly: boolean

      true when the text is over the limit (see FormulaInputApi.overLength).

    • ref: (el: HTMLTextAreaElement | HTMLInputElement | null) => void
    • value: string

      What the ELEMENT holds — FormulaInputApi.text until it is FormulaInputApi.overLength, a clamped head of it after. Read text for the whole value.

    overLength: boolean

    true when text is longer than ICalculation.MAX_EXPRESSION_LENGTH.

    A rule's applies-to renders one address per area, so a striped rule reaches millions of characters from ordinary edits. Three things follow, and all three are needed:

    • Text this long is never parsed — not whole, not segment-by-segment — so the chrome has nothing to color (tokens null, segments empty) and the field cannot engage as the reference producer.
    • inputProps.value is clamped, because a single-line input holding millions of characters is what exhausts the renderer even with no parsing and no overlay.
    • The input is read-only, so the clamped view can never be committed back over the whole one.
    pointArmed: boolean

    true while arrow keys PICK (point) rather than move the text caret (caret-edit). F2 remains a manual toggle; a pick always re-arms. Per grammar:

    • 'reference' — armed on engage (RefEdit): a 'live' field stays armed for its whole engagement; a 'done' field drops to caret-edit while typing. Grid MOUSE picks work whenever the field is engaged, regardless.
    • 'formula' — armed by CARET CONTEXT (the cell editor's model): an operand expected at the caret, or the caret on a reference token. Elsewhere (a function name, a number) the caret does text work — and the bus drops to 'show', so the references stay displayed (rectangles still drag-to-re-scope) while fresh grid gestures don't splice into the middle of a token.
    segments: readonly ReferenceSegmentInfo[]

    'reference' grammar: the text split into reference segments (see ReferenceSegmentInfo) — the chrome's coloring/hover model. Empty for blank text, with no workbook, or in 'formula' grammar (color by tokens there).

    text

    text: string

    The live display text, whole — inputProps.value is what the element holds.

    tokenBase: number

    Offset of the first token in the text (1 past a leading =; 0 otherwise).

    tokens: readonly FormulaToken[] | null

    'formula' grammar: the live parse's tokens WHEN they reproduce the text exactly (so span offsets line up 1:1 for a coloring overlay), else null — render plain text. Offsets start at tokenBase. Always null in 'reference' grammar.

    • Explicit cancel (a dialog's Cancel, the adornment ✗). Engaged: cancels the pick session (reverts to the session baseline); idle: reverts to the committed value. Either way the commit channel hears reason: 'cancel'.

      Returns void

    • Explicit accept — the host-driven commit point (a dialog's OK, the adornment ✓). Engaged: ends the pick session through the same path as a done key; idle: delivers the field's current value on the commit channel.

      Returns void

    • Engage the reference-mode bus explicitly (idempotent — a no-op while already engaged): begins the field's pick session exactly as the first focus or keystroke would. For hosts that hand the field focus programmatically: .focus() engages only through the focus EVENT, and a hand-off racing other focus work (a closing menu) may never fire one — leaving the field focused but idle. Does not itself move focus.

      Returns void

    • Evaluate segment index's reference and format it for a hover tip — the formula editor's eval-tip formatting (formatEvalValue: an array literal up to a small cap, else its {rows×cols} shape). Resolves null when the segment is invalid/empty, there is no workbook, or evaluation fails — show no tip. ('reference' grammar; a 'formula' field's chrome evaluates token segments via evalSegmentAt + createFormula directly.)

      Parameters

      • index: number

      Returns Promise<string | null>

    • The last successfully parsed value's references — a convenience over value.getReferences() for hosts that consume ranges (dialogs sizing a table). null when the current value is null or (in 'formula' grammar) when the expression holds no references.

      Returns ICellRanges | null

    • Replace the field's WHOLE text programmatically (an accepted autocomplete row, a host template) and optionally park the caret — runs the same live-parse/emit pipeline as typing, engaging first when idle (the edit starts a session exactly like a keystroke would).

      Parameters

      • next: string
      • Optionalcaret: number

      Returns void

    • Restore the committed value's text (the field-level Escape).

      Returns void

    • Replace the reference with the displayed sheet's current selection (the adornment action).

      Returns void

    • Arm/disarm picking without focus (the adornment toggle).

      Returns void

    Settings
    Member Visibility

    On This Page
    Properties
    Methods