tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
200 lines • 8.96 kB
text/typescript
export default TinyTextRangeEditor;
/**
* A full-featured text range editor for `<input>` and `<textarea>` elements,
* including advanced utilities for BBCode or similar tag-based markup editing.
*/
declare class TinyTextRangeEditor {
/**
* @param {HTMLInputElement | HTMLTextAreaElement} elem - The target editable input or textarea element.
* @param {Object} [settings={}] - Optional tag symbol customization.
* @param {string} [settings.openTag='['] - The character or symbol used to start a tag (e.g., `'['`).
* @param {string} [settings.closeTag=']'] - The character or symbol used to end a tag (e.g., `']'`).
*/
constructor(elem: HTMLInputElement | HTMLTextAreaElement, { openTag, closeTag }?: {
openTag?: string | undefined;
closeTag?: string | undefined;
});
/** @returns {string} The current open tag symbol. */
getOpenTag(): string;
/** @returns {string} The current close tag symbol. */
getCloseTag(): string;
/** @param {string} tag - New open tag symbol to use (e.g., `'['`). */
setOpenTag(tag: string): void;
/** @param {string} tag - New close tag symbol to use (e.g., `']'`). */
setCloseTag(tag: string): void;
/**
* Ensures the element has focus.
* @returns {TinyTextRangeEditor}
*/
ensureFocus(): TinyTextRangeEditor;
/**
* Focus the element.
* @returns {TinyTextRangeEditor}
*/
focus(): TinyTextRangeEditor;
/** @returns {{ start: number, end: number }} The current selection range. */
getSelectionRange(): {
start: number;
end: number;
};
/**
* Sets the current selection range.
* @param {number} start - Start index.
* @param {number} end - End index.
* @param {boolean} [preserveScroll=true] - Whether to preserve scroll position.
* @returns {TinyTextRangeEditor}
*/
setSelectionRange(start: number, end: number, preserveScroll?: boolean): TinyTextRangeEditor;
/** @returns {string} The full current text value. */
getValue(): string;
/**
* Sets the full value of the element.
* @param {string} value - The new value to assign.
* @returns {TinyTextRangeEditor}
*/
setValue(value: string): TinyTextRangeEditor;
/** @returns {string} The currently selected text. */
getSelectedText(): string;
/**
* Inserts text at the current selection, replacing any selected content.
* @param {string} text - The text to insert.
* @param {Object} [settings={}] - Optional auto-spacing behavior.
* @param {'start' | 'end' | 'preserve'} [settings.newCursor='end'] - Controls caret position after insertion.
* @param {boolean} [settings.autoSpacing=false]
* @param {boolean} [settings.autoSpaceLeft=false]
* @param {boolean} [settings.autoSpaceRight=false]
* @returns {TinyTextRangeEditor}
*/
insertText(text: string, { newCursor, autoSpacing, autoSpaceLeft, autoSpaceRight, }?: {
newCursor?: "end" | "start" | "preserve" | undefined;
autoSpacing?: boolean | undefined;
autoSpaceLeft?: boolean | undefined;
autoSpaceRight?: boolean | undefined;
}): TinyTextRangeEditor;
/**
* Deletes the currently selected text.
* @returns {TinyTextRangeEditor}
*/
deleteSelection(): TinyTextRangeEditor;
/**
* Replaces the selection using a transformation function.
* @param {(selected: string) => string} transformer - Function that modifies the selected text.
* @returns {TinyTextRangeEditor}
*/
transformSelection(transformer: (selected: string) => string): TinyTextRangeEditor;
/**
* Surrounds current selection with prefix and suffix.
* @param {string} prefix - Text to insert before.
* @param {string} suffix - Text to insert after.
* @returns {TinyTextRangeEditor}
*/
surroundSelection(prefix: string, suffix: string): TinyTextRangeEditor;
/**
* Moves the caret by a given offset.
* @param {number} offset - Characters to move.
* @returns {TinyTextRangeEditor}
*/
moveCaret(offset: number): TinyTextRangeEditor;
/**
* Selects all content in the field.
* @returns {TinyTextRangeEditor}
*/
selectAll(): TinyTextRangeEditor;
/**
* Expands the current selection by character amounts.
* @param {number} before - Characters to expand to the left.
* @param {number} after - Characters to expand to the right.
* @returns {TinyTextRangeEditor}
*/
expandSelection(before: number, after: number): TinyTextRangeEditor;
/**
* Replaces all regex matches in the content.
* @param {RegExp} regex - Regex to match.
* @param {(match: string) => string} replacer - Replacement function.
* @returns {TinyTextRangeEditor}
*/
replaceAll(regex: RegExp, replacer: (match: string) => string): TinyTextRangeEditor;
/**
* Replaces all regex matches within the currently selected text.
*
* @param {RegExp} regex - Regular expression to match inside selection.
* @param {(match: string) => string} replacer - Function to replace each match.
* @returns {TinyTextRangeEditor}
*/
replaceInSelection(regex: RegExp, replacer: (match: string) => string): TinyTextRangeEditor;
/**
* Toggles a code around the current selection.
* If it's already wrapped, unwraps it.
* @param {string} codeName - The code to toggle.
* @returns {TinyTextRangeEditor}
*/
toggleCode(codeName: string): TinyTextRangeEditor;
/**
* Converts a list of attributes into a string suitable for tag insertion.
*
* This method supports both standard key-value attribute objects (e.g., `{ key: "value" }`)
* and boolean-style attribute arrays (e.g., `[ "disabled", "autofocus" ]`).
*
* - Attributes passed as an array will render as boolean attributes (e.g., `disabled autofocus`)
* - Attributes passed as an object will render as `key="value"` pairs (or just `key` if the value is an empty string)
*
* @param {Record<string, string> | string[]} attributes - The attributes to serialize into a tag string.
* - If an array: treated as a list of boolean-style attributes.
* - If an object: treated as key-value pairs.
*
* @throws {TypeError} If the array contains non-strings, or the object contains non-string values.
* @returns {string} A string of serialized attributes for use inside a tag.
*
* @example
* // Using object attributes
* _insertAttr({ size: "12", color: "red" });
* // Returns: 'size="12" color="red"'
*
* @example
* // Using boolean attributes
* _insertAttr(["disabled", "autofocus"]);
* // Returns: 'disabled autofocus'
*
* @example
* // Using mixed/empty object values
* _insertAttr({ checked: "", class: "btn" });
* // Returns: 'checked class="btn"'
*/
_insertAttr(attributes: Record<string, string> | string[]): string;
/**
* Wraps the current selection with a tag, optionally including attributes.
*
* @param {string} tagName - The tag name (e.g., `b`, `color`, etc.).
* @param {Record<string,string> | string[]} [attributes={}] - Optional attributes for the opening tag.
* - If an object: key-value pairs (e.g., `{ color: "red" }` → `color="red"`).
* - If an array: boolean attributes (e.g., `["disabled", "readonly"]`).
*
* @returns {TinyTextRangeEditor}
*/
wrapWithTag(tagName: string, attributes?: Record<string, string> | string[]): TinyTextRangeEditor;
/**
* Inserts a tag with optional inner content.
* @param {string} tagName - The tag to insert.
* @param {string} [content=''] - Optional content between tags.
* @param {Record<string,string> | string[]} [attributes={}] - Optional attributes or list of empty attributes.
* @returns {TinyTextRangeEditor}
*/
insertTag(tagName: string, content?: string, attributes?: Record<string, string> | string[]): TinyTextRangeEditor;
/**
* Inserts a self-closing tag.
* @param {string} tagName - The tag name.
* @param {Record<string,string> | string[]} [attributes={}] - Optional attributes or list of empty attributes.
* @returns {TinyTextRangeEditor}
*/
insertSelfClosingTag(tagName: string, attributes?: Record<string, string> | string[]): TinyTextRangeEditor;
/**
* Toggles a tag around the current selection.
* Supports tags with attributes. If already wrapped, it unwraps.
* @param {string} tagName - The tag to toggle.
* @param {Record<string,string> | string[]} [attributes={}] - Optional attributes to apply when wrapping.
* @returns {TinyTextRangeEditor}
*/
toggleTag(tagName: string, attributes?: Record<string, string> | string[]): TinyTextRangeEditor;
#private;
}
//# sourceMappingURL=TinyTextRangeEditor.d.mts.map