matrix-react-sdk
Version:
SDK for matrix.org using React
102 lines (101 loc) • 6.09 kB
TypeScript
import { AllowedMentionAttributes, MappedSuggestion } from "@vector-im/matrix-wysiwyg";
import { SyntheticEvent } from "react";
/**
* Information about the current state of the `useSuggestion` hook.
*/
export type Suggestion = {
mappedSuggestion: MappedSuggestion;
node: Node;
startOffset: number;
endOffset: number;
};
type SuggestionState = Suggestion | null;
/**
* React hook to allow tracking and replacing of mentions and commands in a div element
*
* @param editorRef - a ref to the div that is the composer textbox
* @param setText - setter function to set the content of the composer
* @param isAutoReplaceEmojiEnabled - whether plain text emoticons should be auto replaced with emojis
* @returns
* - `handleMention`: a function that will insert @ or # mentions which are selected from
* the autocomplete into the composer, given an href, the text to display, and any additional attributes
* - `handleCommand`: a function that will replace the content of the composer with the given replacement text.
* Can be used to process autocomplete of slash commands
* - `onSelect`: a selection change listener to be attached to the plain text composer
* - `suggestion`: if the cursor is inside something that could be interpreted as a command or a mention,
* this will be an object representing that command or mention, otherwise it is null
*/
export declare function useSuggestion(editorRef: React.RefObject<HTMLDivElement>, setText: (text?: string) => void, isAutoReplaceEmojiEnabled?: boolean): {
handleMention: (href: string, displayName: string, attributes: AllowedMentionAttributes) => void;
handleAtRoomMention: (attributes: AllowedMentionAttributes) => void;
handleCommand: (text: string) => void;
handleEmojiReplacement: () => void;
onSelect: (event: SyntheticEvent<HTMLDivElement>) => void;
suggestion: MappedSuggestion | null;
};
/**
* When the selection changes inside the current editor, check to see if the cursor is inside
* something that could be a command or a mention and update the suggestion state if so
*
* @param editorRef - ref to the composer
* @param setSuggestionData - the setter for the suggestion state
* @param isAutoReplaceEmojiEnabled - whether plain text emoticons should be auto replaced with emojis
*/
export declare function processSelectionChange(editorRef: React.RefObject<HTMLDivElement>, setSuggestionData: React.Dispatch<React.SetStateAction<SuggestionState>>, isAutoReplaceEmojiEnabled?: boolean): void;
/**
* Replaces the relevant part of the editor text with a link representing a mention after it
* is selected from the autocomplete.
*
* @param href - the href that the inserted link will use
* @param displayName - the text content of the link
* @param attributes - additional attributes to add to the link, can include data-* attributes
* @param suggestionData - representation of the part of the DOM that will be replaced
* @param setSuggestionData - setter function to set the suggestion state
* @param setText - setter function to set the content of the composer
*/
export declare function processMention(href: string, displayName: string, attributes: AllowedMentionAttributes, // these will be used when formatting the link as a pill
suggestionData: SuggestionState, setSuggestionData: React.Dispatch<React.SetStateAction<SuggestionState>>, setText: (text?: string) => void): void;
/**
* Replaces the relevant part of the editor text with the replacement text after a command is selected
* from the autocomplete.
*
* @param replacementText - the text that we will insert into the DOM
* @param suggestionData - representation of the part of the DOM that will be replaced
* @param setSuggestionData - setter function to set the suggestion state
* @param setText - setter function to set the content of the composer
*/
export declare function processCommand(replacementText: string, suggestionData: SuggestionState, setSuggestionData: React.Dispatch<React.SetStateAction<SuggestionState>>, setText: (text?: string) => void): void;
/**
* Replaces the relevant part of the editor text, replacing the plain text emoitcon with the suggested emoji.
*
* @param suggestionData - representation of the part of the DOM that will be replaced
* @param setSuggestionData - setter function to set the suggestion state
* @param setText - setter function to set the content of the composer
*/
export declare function processEmojiReplacement(suggestionData: SuggestionState, setSuggestionData: React.Dispatch<React.SetStateAction<SuggestionState>>, setText: (text?: string) => void): void;
/**
* Given some text content from a node and the cursor position, find the word that the cursor is currently inside
* and then test that word to see if it is a suggestion. Return the `MappedSuggestion` with start and end offsets if
* the cursor is inside a valid suggestion, null otherwise.
*
* @param text - the text content of a node
* @param offset - the current cursor offset position within the node
* @param isFirstTextNode - whether or not the node is the first text node in the editor. Used to determine
* if a command suggestion is found or not
* @param isAutoReplaceEmojiEnabled - whether plain text emoticons should be auto replaced with emojis
* @returns the `MappedSuggestion` along with its start and end offsets if found, otherwise null
*/
export declare function findSuggestionInText(text: string, offset: number, isFirstTextNode: boolean, isAutoReplaceEmojiEnabled?: boolean): {
mappedSuggestion: MappedSuggestion;
startOffset: number;
endOffset: number;
} | null;
/**
* Given a string, return a `MappedSuggestion` if the string contains a suggestion. Otherwise return null.
*
* @param text - string to check for a suggestion
* @param isAutoReplaceEmojiEnabled - whether plain text emoticons should be auto replaced with emojis
* @returns a `MappedSuggestion` if a suggestion is present, null otherwise
*/
export declare function getMappedSuggestion(text: string, isAutoReplaceEmojiEnabled?: boolean): MappedSuggestion | null;
export {};