0
# Utilities
1

2
Text manipulation utilities and helper functions for textarea operations, markdown formatting, and text selection management.
3

4
## Capabilities
5

6
### Text Area Manipulation
7

8
Classes and functions for direct textarea manipulation and text processing.
9

10
```typescript { .api }
11
/**
12
 * Text manipulation API for textarea elements
13
 */
14
declare class TextAreaTextApi {
15
  constructor(textArea: HTMLTextAreaElement);
16
  
17
  /**
18
   * Replace the currently selected text with new text
19
   * @param text - Text to replace the selection with
20
   * @returns Updated text state after replacement
21
   */
22
  replaceSelection(text: string): TextState;
23
  
24
  /**
25
   * Set the selection range in the textarea
26
   * @param selection - Text range to select
27
   * @returns Updated text state after selection change
28
   */
29
  setSelectionRange(selection: TextRange): TextState;
30
}
31

32
interface TextState {
33
  /** Full text content of the textarea */
34
  text: string;
35
  /** Currently selected text */
36
  selectedText: string;
37
  /** Selection range information */
38
  selection: TextRange;
39
}
40

41
interface TextRange {
42
  /** Start position of the selection */
43
  start: number;
44
  /** End position of the selection */
45
  end: number;
46
}
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
// Basic text manipulation
53
const textArea = document.querySelector('textarea') as HTMLTextAreaElement;
54
const textApi = new TextAreaTextApi(textArea);
55

56
// Replace selection with bold text
57
const state = textApi.getState();
58
if (state.selectedText) {
59
  textApi.replaceSelection(`**${state.selectedText}**`);
60
}
61

62
// Set specific selection range
63
textApi.setSelectionRange({ start: 0, end: 10 });
64
```
65

66
### Text Selection Functions
67

68
Utility functions for intelligent text selection and word boundary detection.
69

70
```typescript { .api }
71
/**
72
 * Select word at the current position with intelligent boundary detection
73
 * @param options - Selection options including text and position
74
 * @returns Text range containing the selected word
75
 */
76
declare function selectWord(options: SelectWordOptions): TextRange;
77

78
interface SelectWordOptions {
79
  text: string;
80
  selection: TextRange;
81
}
82

83
/**
84
 * Select entire line containing the current position
85
 * @param textSection - Text section with selection information
86
 * @returns Text range containing the entire line
87
 */
88
declare function selectLine(textSection: TextSection): TextRange;
89

90
interface TextSection {
91
  text: string;
92
  selection: TextRange;
93
}
94

95
/**
96
 * Get word boundaries around a specific position
97
 * @param text - Full text content
98
 * @param position - Position to find word boundaries around
99
 * @returns Text range of the surrounding word
100
 */
101
declare function getSurroundingWord(text: string, position: number): TextRange;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Select word at cursor position
108
const wordRange = selectWord({
109
  text: "Hello world example",
110
  selection: { start: 8, end: 8 } // Cursor in "world"
111
});
112
// Returns: { start: 6, end: 11 } for "world"
113

114
// Select entire line
115
const lineRange = selectLine({
116
  text: "Line 1\nLine 2\nLine 3",
117
  selection: { start: 8, end: 8 } // Cursor in "Line 2"
118
});
119
// Returns: { start: 7, end: 13 } for "Line 2"
120

121
// Get surrounding word boundaries
122
const wordBounds = getSurroundingWord("Hello world", 8);
123
// Returns: { start: 6, end: 11 } for "world"
124
```
125

126
### Line Manipulation Functions
127

128
Functions for calculating line breaks and modifying text line by line.
129

130
```typescript { .api }
131
/**
132
 * Calculate line breaks needed before a position for proper formatting
133
 * @param text - Full text content
134
 * @param startPosition - Position to check
135
 * @returns Number of line breaks needed before the position
136
 */
137
declare function getBreaksNeededForEmptyLineBefore(text: string, startPosition: number): number;
138

139
/**
140
 * Calculate line breaks needed after a position for proper formatting
141
 * @param text - Full text content
142
 * @param startPosition - Position to check
143
 * @returns Number of line breaks needed after the position
144
 */
145
declare function getBreaksNeededForEmptyLineAfter(text: string, startPosition: number): number;
146

147
/**
148
 * Insert text before each line in the selected text
149
 * @param selectedText - Text to modify
150
 * @param insertBefore - Text to insert before each line
151
 * @returns Object with modified text and insertion length information
152
 */
153
declare function insertBeforeEachLine(
154
  selectedText: string,
155
  insertBefore: string
156
): {
157
  modifiedText: string;
158
  insertionLength: number;
159
};
160
```
161

162
**Usage Examples:**
163

164
```typescript
165
// Calculate needed line breaks
166
const text = "Some text\n\nMore text";
167
const breaksNeeded = getBreaksNeededForEmptyLineBefore(text, 15);
168

169
// Insert prefix before each line (useful for quote blocks, lists)
170
const result = insertBeforeEachLine("Line 1\nLine 2\nLine 3", "> ");
171
// Returns: { modifiedText: "> Line 1\n> Line 2\n> Line 3", insertionLength: 2 }
172

173
// Create quote block
174
const selectedText = "This is a quote\nWith multiple lines";
175
const { modifiedText } = insertBeforeEachLine(selectedText, "> ");
176
textApi.replaceSelection(modifiedText);
177
```
178

179
### Command Execution Functions
180

181
High-level functions for executing text formatting commands and inserting text.
182

183
```typescript { .api }
184
/**
185
 * Execute a text formatting command with proper state management
186
 * @param options - Command execution options
187
 */
188
declare function executeCommand(options: ExecuteCommandOptions): void;
189

190
interface ExecuteCommandOptions {
191
  command: ICommand;
192
  state: ContextStore;
193
  textApi: TextAreaTextApi;
194
  dispatch?: React.Dispatch<ContextStore>;
195
}
196

197
/**
198
 * Insert text at the current cursor position in a textarea
199
 * @param input - Textarea element to insert text into
200
 * @param text - Text to insert
201
 */
202
declare function insertTextAtPosition(input: HTMLTextAreaElement, text: string): void;
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
// Execute a formatting command
209
executeCommand({
210
  command: commands.bold,
211
  state: editorState,
212
  textApi: new TextAreaTextApi(textArea),
213
  dispatch: stateDispatcher
214
});
215

216
// Insert text at cursor
217
const textArea = document.querySelector('textarea') as HTMLTextAreaElement;
218
insertTextAtPosition(textArea, "**Bold text**");
219
```
220

221
### Markdown Utilities Namespace
222

223
Namespace containing all markdown-related utility functions.
224

225
```typescript { .api }
226
/**
227
 * Namespace containing markdown utility functions
228
 */
229
declare namespace MarkdownUtil {
230
  export function selectWord(options: SelectWordOptions): TextRange;
231
  export function selectLine(textSection: TextSection): TextRange;
232
  export function getSurroundingWord(text: string, position: number): TextRange;
233
  export function getBreaksNeededForEmptyLineBefore(text: string, startPosition: number): number;
234
  export function getBreaksNeededForEmptyLineAfter(text: string, startPosition: number): number;
235
  export function insertBeforeEachLine(selectedText: string, insertBefore: string): {
236
    modifiedText: string;
237
    insertionLength: number;
238
  };
239
  export function executeCommand(options: ExecuteCommandOptions): void;
240
  export function insertTextAtPosition(input: HTMLTextAreaElement, text: string): void;
241
}
242
```
243

244
**Usage Example:**
245

246
```typescript
247
import { MarkdownUtil } from "@uiw/react-md-editor";
248

249
// Use utilities through namespace
250
const wordRange = MarkdownUtil.selectWord({
251
  text: "Hello world",
252
  selection: { start: 8, end: 8 }
253
});
254

255
const { modifiedText } = MarkdownUtil.insertBeforeEachLine("Line 1\nLine 2", "- ");
256
```
257

258
### List Operations
259

260
Utility function for creating and managing list formatting in markdown text.
261

262
```typescript { .api }
263
/**
264
 * Apply list formatting to selected text with proper line break handling
265
 * @param state - Current execution state
266
 * @param api - Text API for manipulation
267
 * @param insertBefore - Text to insert before each line or function to transform lines
268
 */
269
declare function makeList(
270
  state: ExecuteState, 
271
  api: TextAreaTextApi, 
272
  insertBefore: string | AlterLineFunction
273
): void;
274

275
type AlterLineFunction = (line: string, index: number) => string;
276
```
277

278
**Usage Examples:**
279

280
```typescript
281
import { makeList } from "@uiw/react-md-editor";
282

283
// Create unordered list
284
makeList(state, textApi, "- ");
285

286
// Create ordered list with function
287
makeList(state, textApi, (line, index) => `${index + 1}. `);
288

289
// Create checklist
290
makeList(state, textApi, "- [ ] ");
291
```
292

293
### Context Management
294

295
State management utilities for the editor context.
296

297
```typescript { .api }
298
/**
299
 * Get current state from textarea element
300
 * @param textArea - Textarea element to extract state from
301
 * @returns Current text state with selection information
302
 */
303
declare function getStateFromTextArea(textArea: HTMLTextAreaElement): TextState;
304

305
/**
306
 * Context reducer for managing editor state
307
 * @param state - Current context state
308
 * @param action - Action containing state updates
309
 * @returns Updated context state
310
 */
311
declare function reducer(state: ContextStore, action: ContextStore): ContextStore;
312
```
313

314
**Usage Examples:**
315

316
```typescript
317
import { getStateFromTextArea, reducer } from "@uiw/react-md-editor";
318

319
// Get current textarea state
320
const textArea = document.querySelector('textarea') as HTMLTextAreaElement;
321
const currentState = getStateFromTextArea(textArea);
322

323
// Use reducer for state management
324
const newState = reducer(currentState, { markdown: "new content" });
325
```