declare module 'xterm' {
  /**
   * The class that represents an xterm.js terminal.
   */
  export class Terminal implements IDisposable {
    /**
     * (EXPERIMENTAL) Get the parser interface to register
     * custom escape sequence handlers.
     */
    readonly parser: IParser;

    /**
     * Attaches a custom key event handler which is run before keys are
     * processed, giving consumers of xterm.js ultimate control as to what keys
     * should be processed by the terminal and what keys should not.
     * @param customKeyEventHandler The custom KeyboardEvent handler to attach.
     * This is a function that takes a KeyboardEvent, allowing consumers to stop
     * propagation and/or prevent the default action. The function returns
     * whether the event should be processed by xterm.js.
     */
    attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;

    /**
     * (EXPERIMENTAL) Registers a link matcher, allowing custom link patterns to
     * be matched and handled.
     * @deprecated The link matcher API is now deprecated in favor of the link
     * provider API, see `registerLinkProvider`.
     * @param regex The regular expression to search for, specifically this
     * searches the textContent of the rows. You will want to use \s to match a
     * space ' ' character for example.
     * @param handler The callback when the link is called.
     * @param options Options for the link matcher.
     * @return The ID of the new matcher, this can be used to deregister.
     */
    registerLinkMatcher(regex: RegExp, handler: (event: MouseEvent, uri: string) => void, options?: ILinkMatcherOptions): number;

    /**
     * (EXPERIMENTAL) Deregisters a link matcher if it has been registered.
     * @deprecated The link matcher API is now deprecated in favor of the link
     * provider API, see `registerLinkProvider`.
     * @param matcherId The link matcher's ID (returned after register)
     */
    deregisterLinkMatcher(matcherId: number): void;

    /**
     * (EXPERIMENTAL) Registers a link provider, allowing a custom parser to
     * be used to match and handle links. Multiple link providers can be used,
     * they will be asked in the order in which they are registered.
     * @param linkProvider The link provider to use to detect links.
     */
    registerLinkProvider(linkProvider: ILinkProvider): IDisposable;

    /**
     * (EXPERIMENTAL) Registers a character joiner, allowing custom sequences of
     * characters to be rendered as a single unit. This is useful in particular
     * for rendering ligatures and graphemes, among other things.
     *
     * Each registered character joiner is called with a string of text
     * representing a portion of a line in the terminal that can be rendered as
     * a single unit. The joiner must return a sorted array, where each entry is
     * itself an array of length two, containing the start (inclusive) and end
     * (exclusive) index of a substring of the input that should be rendered as
     * a single unit. When multiple joiners are provided, the results of each
     * are collected. If there are any overlapping substrings between them, they
     * are combined into one larger unit that is drawn together.
     *
     * All character joiners that are registered get called every time a line is
     * rendered in the terminal, so it is essential for the handler function to
     * run as quickly as possible to avoid slowdowns when rendering. Similarly,
     * joiners should strive to return the smallest possible substrings to
     * render together, since they aren't drawn as optimally as individual
     * characters.
     *
     * NOTE: character joiners are only used by the canvas renderer.
     *
     * @param handler The function that determines character joins. It is called
     * with a string of text that is eligible for joining and returns an array
     * where each entry is an array containing the start (inclusive) and end
     * (exclusive) indexes of ranges that should be rendered as a single unit.
     * @return The ID of the new joiner, this can be used to deregister
     */
    registerCharacterJoiner(handler: (text: string) => [number, number][]): number;

    /**
     * (EXPERIMENTAL) Deregisters the character joiner if one was registered.
     * NOTE: character joiners are only used by the canvas renderer.
     * @param joinerId The character joiner's ID (returned after register)
     */
    deregisterCharacterJoiner(joinerId: number): void;

    /**
     * (EXPERIMENTAL) Adds a marker to the normal buffer and returns it. If the
     * alt buffer is active, undefined is returned.
     * @param cursorYOffset The y position offset of the marker from the cursor.
     * @returns The new marker or undefined.
     */
    registerMarker(cursorYOffset: number): IMarker | undefined;

    /**
     * @deprecated use `registerMarker` instead.
     */
    addMarker(cursorYOffset: number): IMarker | undefined;

    /**
     * Writes data to the terminal, followed by a break line character (\n).
     * @param data The data to write to the terminal. This can either be raw
     * bytes given as Uint8Array from the pty or a string. Raw bytes will always
     * be treated as UTF-8 encoded, string data as UTF-16.
     * @param callback Optional callback that fires when the data was processed
     * by the parser.
     */
    writeln(data: string | Uint8Array, callback?: () => void): void;

    /**
     * Write UTF8 data to the terminal.
     * @param data The data to write to the terminal.
     * @param callback Optional callback when data was processed.
     * @deprecated use `write` instead
     */
    writeUtf8(data: Uint8Array, callback?: () => void): void;

    /**
     * Retrieves an option's value from the terminal.
     * @param key The option key.
     */
    getOption(key: 'bellSound' | 'bellStyle' | 'cursorStyle' | 'fontFamily' | 'fontWeight' | 'fontWeightBold' | 'logLevel' | 'rendererType' | 'termName' | 'wordSeparator'): string;
    /**
     * Retrieves an option's value from the terminal.
     * @param key The option key.
     */
    getOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'visualBell' | 'windowsMode'): boolean;
    /**
     * Retrieves an option's value from the terminal.
     * @param key The option key.
     */
    getOption(key: 'cols' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'rows' | 'tabStopWidth' | 'scrollback'): number;
    /**
     * Retrieves an option's value from the terminal.
     * @param key The option key.
     */
    getOption(key: string): any;

    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'fontFamily' | 'termName' | 'bellSound' | 'wordSeparator', value: string): void;
    /**
    * Sets an option on the terminal.
    * @param key The option key.
    * @param value The option value.
    */
    setOption(key: 'fontWeight' | 'fontWeightBold', value: null | 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'): void;
    /**
    * Sets an option on the terminal.
    * @param key The option key.
    * @param value The option value.
    */
    setOption(key: 'logLevel', value: LogLevel): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'bellStyle', value: null | 'none' | 'visual' | 'sound' | 'both'): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'cursorStyle', value: null | 'block' | 'underline' | 'bar'): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'popOnBell' | 'rightClickSelectsWord' | 'visualBell' | 'windowsMode', value: boolean): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'fontSize' | 'letterSpacing' | 'lineHeight' | 'tabStopWidth' | 'scrollback', value: number): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'theme', value: ITheme): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: 'cols' | 'rows', value: number): void;
    /**
     * Sets an option on the terminal.
     * @param key The option key.
     * @param value The option value.
     */
    setOption(key: string, value: any): void;
  }

  /**
   * A custom link provider.
   */
  interface ILinkProvider {
    /**
     * Provides a link a buffer position
     * @param bufferLineNumber The y position of the buffer to check for links
     * within.
     * @param callback The callback to be fired when ready with the resulting
     * link(s) for the line or `undefined`.
     */
    provideLinks(bufferLineNumber: number, callback: (links: ILink[] | undefined) => void): void;
  }

  /**
   * A link within the terminal.
   */
  interface ILink {
    /**
     * The buffer range of the link.
     */
    range: IBufferRange;

    /**
     * The text of the link.
     */
    text: string;

    /**
     * What link decorations to show when hovering the link, this property is tracked and changes
     * made after the link is provided will trigger changes. If not set, all decroations will be
     * enabled.
     */
    decorations?: ILinkDecorations;

    /**
     * Calls when the link is activated.
     * @param event The mouse event triggering the callback.
     * @param text The text of the link.
     */
    activate(event: MouseEvent, text: string): void;

    /**
     * Called when the mouse hovers the link. To use this to create a DOM-based hover tooltip,
     * create the hover element within `Terminal.element` and add the `xterm-hover` class to it,
     * that will cause mouse events to not fall through and activate other links.
     * @param event The mouse event triggering the callback.
     * @param text The text of the link.
     */
    hover?(event: MouseEvent, text: string): void;

    /**
     * Called when the mouse leaves the link.
     * @param event The mouse event triggering the callback.
     * @param text The text of the link.
     */
    leave?(event: MouseEvent, text: string): void;
  }

  /**
   * A set of decorations that can be applied to links.
   */
  interface ILinkDecorations {
    /**
     * Whether the cursor is set to pointer.
     */
    pointerCursor: boolean;

    /**
     * Whether the underline is visible
     */
    underline: boolean;
  }

  /**
   * A range within a buffer.
   */
  interface IBufferRange {
    /**
     * The start position of the range.
     */
    start: IBufferCellPosition;

    /**
     * The end position of the range.
     */
    end: IBufferCellPosition;
  }

  /**
   * A position within a buffer.
   */
  interface IBufferCellPosition {
    /**
     * The x position within the buffer.
     */
    x: number;

    /**
     * The y position within the buffer.
     */
    y: number;
  }

  /**
   * Data type to register a CSI, DCS or ESC callback in the parser
   * in the form:
   *    ESC I..I F
   *    CSI Prefix P..P I..I F
   *    DCS Prefix P..P I..I F data_bytes ST
   *
   * with these rules/restrictions:
   * - prefix can only be used with CSI and DCS
   * - only one leading prefix byte is recognized by the parser
   *   before any other parameter bytes (P..P)
   * - intermediate bytes are recognized up to 2
   *
   * For custom sequences make sure to read ECMA-48 and the resources at
   * vt100.net to not clash with existing sequences or reserved address space.
   * General recommendations:
   * - use private address space (see ECMA-48)
   * - use max one intermediate byte (technically not limited by the spec,
   *   in practice there are no sequences with more than one intermediate byte,
   *   thus parsers might get confused with more intermediates)
   * - test against other common emulators to check whether they escape/ignore
   *   the sequence correctly
   *
   * Notes: OSC command registration is handled differently (see addOscHandler)
   *        APC, PM or SOS is currently not supported.
   */
  export interface IFunctionIdentifier {
    /**
     * Optional prefix byte, must be in range \x3c .. \x3f.
     * Usable in CSI and DCS.
     */
    prefix?: string;
    /**
     * Optional intermediate bytes, must be in range \x20 .. \x2f.
     * Usable in CSI, DCS and ESC.
     */
    intermediates?: string;
    /**
     * Final byte, must be in range \x40 .. \x7e for CSI and DCS,
     * \x30 .. \x7e for ESC.
     */
    final: string;
  }

  /**
   * Allows hooking into the parser for custom handling of escape sequences.
   */
  export interface IParser {
    /**
     * Adds a handler for CSI escape sequences.
     * @param id Specifies the function identifier under which the callback
     * gets registered, e.g. {final: 'm'} for SGR.
     * @param callback The function to handle the sequence. The callback is
     * called with the numerical params. If the sequence has subparams the
     * array will contain subarrays with their numercial values.
     * Return true if the sequence was handled; false if we should try
     * a previous handler (set by addCsiHandler or setCsiHandler).
     * The most recently added handler is tried first.
     * @return An IDisposable you can call to remove this handler.
     */
    registerCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean): IDisposable;

    /**
     * Adds a handler for DCS escape sequences.
     * @param id Specifies the function identifier under which the callback
     * gets registered, e.g. {intermediates: '$' final: 'q'} for DECRQSS.
     * @param callback The function to handle the sequence. Note that the
     * function will only be called once if the sequence finished sucessfully.
     * There is currently no way to intercept smaller data chunks, data chunks
     * will be stored up until the sequence is finished. Since DCS sequences
     * are not limited by the amount of data this might impose a problem for
     * big payloads. Currently xterm.js limits DCS payload to 10 MB
     * which should give enough room for most use cases.
     * The function gets the payload and numerical parameters as arguments.
     * Return true if the sequence was handled; false if we should try
     * a previous handler (set by addDcsHandler or setDcsHandler).
     * The most recently added handler is tried first.
     * @return An IDisposable you can call to remove this handler.
     */
    registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean): IDisposable;

    /**
     * Adds a handler for ESC escape sequences.
     * @param id Specifies the function identifier under which the callback
     * gets registered, e.g. {intermediates: '%' final: 'G'} for
     * default charset selection.
     * @param callback The function to handle the sequence.
     * Return true if the sequence was handled; false if we should try
     * a previous handler (set by addEscHandler or setEscHandler).
     * The most recently added handler is tried first.
     * @return An IDisposable you can call to remove this handler.
     */
    registerEscHandler(id: IFunctionIdentifier, handler: () => boolean): IDisposable;

    /**
     * Adds a handler for OSC escape sequences.
     * @param ident The number (first parameter) of the sequence.
     * @param callback The function to handle the sequence. Note that the
     * function will only be called once if the sequence finished sucessfully.
     * There is currently no way to intercept smaller data chunks, data chunks
     * will be stored up until the sequence is finished. Since OSC sequences
     * are not limited by the amount of data this might impose a problem for
     * big payloads. Currently xterm.js limits OSC payload to 10 MB
     * which should give enough room for most use cases.
     * The callback is called with OSC data string.
     * Return true if the sequence was handled; false if we should try
     * a previous handler (set by addOscHandler or setOscHandler).
     * The most recently added handler is tried first.
     * @return An IDisposable you can call to remove this handler.
     */
    registerOscHandler(ident: number, callback: (data: string) => boolean): IDisposable;
  }
}