@mzeahmed/rich-editor 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,278 @@
1
+ /**
2
+ * Standalone rich text editor.
3
+ * Automatically replaces <textarea> elements with an enhanced contenteditable editor.
4
+ *
5
+ * ─────────────────────────────────────────────────────────────────────────────
6
+ * BASIC USAGE
7
+ * ─────────────────────────────────────────────────────────────────────────────
8
+ *
9
+ * 1) Every <textarea> on the page
10
+ * Editor.init();
11
+ *
12
+ * 2) Targeted CSS selector
13
+ * Editor.init({ selector: '.richtext' });
14
+ *
15
+ * 3) Exclude some textareas
16
+ * Editor.init({ exclude: '.no-editor' });
17
+ *
18
+ * 4) Mount on a specific element (dynamic DOM)
19
+ * Editor.mount('#my-textarea');
20
+ * Editor.mount(textareaElement);
21
+ *
22
+ * ─────────────────────────────────────────────────────────────────────────────
23
+ * TOOLBAR OPTIONS
24
+ * ─────────────────────────────────────────────────────────────────────────────
25
+ *
26
+ * toolbar: 'always' → toolbar always visible (default)
27
+ * Editor.init({ toolbar: 'always' });
28
+ *
29
+ * toolbar: 'focus' → toolbar shown only while the field is focused
30
+ * Editor.init({ toolbar: 'focus' });
31
+ *
32
+ * toolbar: 'toggle' → a "Formatting" button shows/hides the toolbar
33
+ * Editor.init({ toolbar: 'toggle' });
34
+ *
35
+ * toolbar: 'never' → no toolbar (plain rich input field)
36
+ * Editor.init({ toolbar: 'never' });
37
+ *
38
+ * Per-textarea override through a data attribute:
39
+ * <textarea data-mzre-toolbar="focus"></textarea>
40
+ *
41
+ * ─────────────────────────────────────────────────────────────────────────────
42
+ * FOOTER (character counter + HTML / Clear / Copy buttons)
43
+ * ─────────────────────────────────────────────────────────────────────────────
44
+ *
45
+ * Hide the footer (useful for embedded fields, e.g. messaging):
46
+ * Editor.mount('#msg-textarea', { footer: false });
47
+ *
48
+ * ─────────────────────────────────────────────────────────────────────────────
49
+ * HEIGHT OF THE WRITING AREA
50
+ * ─────────────────────────────────────────────────────────────────────────────
51
+ *
52
+ * Through the JS options:
53
+ * Editor.mount('#my-textarea', { minHeight: '80px', maxHeight: '300px' });
54
+ *
55
+ * Through data attributes on the <textarea> (they take precedence over the JS options):
56
+ * <textarea data-mzre-min-height="60px" data-mzre-max-height="200px"></textarea>
57
+ *
58
+ * When maxHeight is set, overflow-y: auto is enabled automatically.
59
+ *
60
+ * ─────────────────────────────────────────────────────────────────────────────
61
+ * EMOJI
62
+ * ─────────────────────────────────────────────────────────────────────────────
63
+ *
64
+ * Adds an inline 😊 button to the writing area. The picker is provided by the package
65
+ * (no modal to prepare); its data is loaded on first open.
66
+ *
67
+ * Editor.mount('#editor', { emoji: true });
68
+ *
69
+ * Combined with no toolbar (post/comment field style):
70
+ * Editor.mount('#post-textarea', {
71
+ * toolbar: 'never',
72
+ * footer: false,
73
+ * emoji: true,
74
+ * });
75
+ *
76
+ * ─────────────────────────────────────────────────────────────────────────────
77
+ * MENTIONS
78
+ * ─────────────────────────────────────────────────────────────────────────────
79
+ *
80
+ * Enables assisted @user mentions (requires integrations.mentions):
81
+ * · Typing @ → user search bubble (integrations.mentions.searchUsers)
82
+ * · Selection → inserts <a class="mention" href="/profile" data-user-id="…">First Last</a>
83
+ * · Closes on Space / Escape / Enter, with the cross, or by clicking outside
84
+ *
85
+ * Simple activation:
86
+ * Editor.mount('#editor', { mention: true }, { mentions: … });
87
+ *
88
+ * Full combination (publishing form style), with a "publish" button disabled
89
+ * while the field is empty (onChange is also called once at mount):
90
+ * Editor.mount('#post-textarea', {
91
+ * toolbar: 'never',
92
+ * footer: false,
93
+ * emoji: true,
94
+ * mention: true,
95
+ * onChange: ({ isEmpty }) => { publishButton.disabled = isEmpty; },
96
+ * }, { mentions: … });
97
+ *
98
+ * Comment combination:
99
+ * Editor.mount('#comment-textarea', {
100
+ * toolbar: 'never',
101
+ * footer: false,
102
+ * emoji: true,
103
+ * mention: true,
104
+ * });
105
+ *
106
+ * ─────────────────────────────────────────────────────────────────────────────
107
+ * LANGUAGE
108
+ * ─────────────────────────────────────────────────────────────────────────────
109
+ *
110
+ * Interface and emojis in English by default; { locale: 'fr' } (or setEditorLocale('fr')) for
111
+ * French. A text can be overridden: integrations.messages = { close: 'Dismiss' }.
112
+ *
113
+ * ─────────────────────────────────────────────────────────────────────────────
114
+ * COMPLETE USE CASES
115
+ * ─────────────────────────────────────────────────────────────────────────────
116
+ *
117
+ * A) Rich content editor (article, long description)
118
+ * Editor.init({
119
+ * selector: 'textarea.rich-content',
120
+ * toolbar: 'always',
121
+ * minHeight: '300px',
122
+ * });
123
+ *
124
+ * B) Compact comment editor (toolbar on focus)
125
+ * Editor.init({
126
+ * selector: 'textarea.comment',
127
+ * toolbar: 'focus',
128
+ * minHeight: '80px',
129
+ * maxHeight: '200px',
130
+ * footer: false,
131
+ * });
132
+ *
133
+ * C) Messaging input field (no toolbar, no footer, fixed height)
134
+ * Editor.mount('#messaging-textarea', {
135
+ * toolbar: 'never',
136
+ * footer: false,
137
+ * minHeight: '40px',
138
+ * maxHeight: '120px',
139
+ * });
140
+ *
141
+ * D) Editor with an optional toolbar behind a toggle button
142
+ * Editor.mount('#post-content', { toolbar: 'toggle' });
143
+ *
144
+ * E) Mounting on a dynamically added element (e.g. an opened modal)
145
+ * modal.addEventListener('shown', () => { // your modal's open event
146
+ * Editor.mount('#modal-textarea', { toolbar: 'focus', minHeight: '120px' });
147
+ * });
148
+ *
149
+ * F) Per-textarea override (data attributes, no extra JS)
150
+ * <textarea
151
+ * data-mzre-toolbar="toggle"
152
+ * data-mzre-min-height="100px"
153
+ * data-mzre-max-height="400px"
154
+ * ></textarea>
155
+ * then: Editor.init(); ← the data attributes take precedence
156
+ *
157
+ * ─────────────────────────────────────────────────────────────────────────────
158
+ * CHAINING
159
+ * ─────────────────────────────────────────────────────────────────────────────
160
+ *
161
+ * init() and mount() return the class, so calls can be chained:
162
+ * Editor
163
+ * .init({ selector: '.rich', toolbar: 'always' })
164
+ * .mount('#extra-field', { toolbar: 'never', footer: false });
165
+ */
166
+ import type { StyleOptions } from './styles.js';
167
+ import type { EditorLocale } from './messages.js';
168
+ import type { EditorIntegrations } from './types.js';
169
+ /** Content state, passed to `onChange` on every change and once at mount. */
170
+ export interface EditorChange {
171
+ html: string;
172
+ text: string;
173
+ isEmpty: boolean;
174
+ }
175
+ export interface EditorOptions {
176
+ selector?: string;
177
+ exclude?: string;
178
+ /** 'always' | 'toggle' | 'focus' | 'never' — default: 'always' */
179
+ toolbar?: 'always' | 'toggle' | 'focus' | 'never';
180
+ /** Show or hide the footer (counter + buttons) — default: true */
181
+ footer?: boolean;
182
+ /** Minimum height of the writing area (e.g. '80px', '4rem') — default: '160px' */
183
+ minHeight?: string;
184
+ /** Maximum height of the writing area before it scrolls (e.g. '400px') */
185
+ maxHeight?: string;
186
+ /** Adds an inline emoji button to the writing area */
187
+ emoji?: boolean;
188
+ /** Enables @mentions (requires `integrations.mentions`) */
189
+ mention?: boolean;
190
+ /** Language of the interface and of the emojis: 'en' (default) or 'fr'. Page-wide setting. */
191
+ locale?: EditorLocale;
192
+ /**
193
+ * Style injection (page-wide setting): `{inject: false}` to load
194
+ * `@mzeahmed/rich-editor/style.css` yourself, `{nonce}` for a nonce-based CSP. See `setEditorStyles()`.
195
+ */
196
+ styles?: StyleOptions;
197
+ /**
198
+ * Called on every content change (typing, toolbar, mention) and once at
199
+ * mount: handy to enable or disable a "publish" button depending on whether the field is empty.
200
+ */
201
+ onChange?: (change: EditorChange) => void;
202
+ }
203
+ export default class Editor {
204
+ private static injectStyles;
205
+ private static buildEditorHTML;
206
+ private static mountEditor;
207
+ private static _addEmojiInEditor;
208
+ private static _saveSelection;
209
+ private static _showEmojiPicker;
210
+ private static _setupMentions;
211
+ /**
212
+ * The "@term" that ends at the caret: an "@" at the start of a word (not inside an e-mail
213
+ * address) followed by characters with no space. `index` is the position of the "@".
214
+ */
215
+ private static _findMentionTrigger;
216
+ private static _handleMentionSearch;
217
+ /**
218
+ * Creates the bubble on document.body with fixed positioning — works around the overflow:hidden of
219
+ * .mzre-editor-wrap, same pattern as the emoji picker. Placed below the writing area,
220
+ * shifted upward if needed.
221
+ *
222
+ * Its structure is built once: a header with the cross, an announcement area for screen
223
+ * readers (present before it changes, otherwise nothing is read) and a results area. It stays
224
+ * hidden while there is nothing to show.
225
+ */
226
+ private static _showMentionDropdown;
227
+ private static _positionDropdown;
228
+ /**
229
+ * Closes the bubble as soon as the user presses (mouse or finger) anywhere but on it, including in the text
230
+ * of the editor. The listener is added on open and removed by _closeMentionDropdown().
231
+ */
232
+ private static _closeOnOutsidePointer;
233
+ private static _closeMentionDropdown;
234
+ private static _performMentionSearch;
235
+ private static _renderMentionResults;
236
+ /** Options shown in the bubble (empty until it has results). */
237
+ private static _mentionOptions;
238
+ /** Chooses an option with the keyboard: `aria-selected` on the option, `aria-activedescendant` on the writing area. */
239
+ private static _setActiveMention;
240
+ /**
241
+ * Keyboard, while the bubble is open. Focus never leaves the writing area:
242
+ * · Escape → closes the bubble without touching the text (and without closing a host modal)
243
+ * · Up/Down arrows, Home/End → choose a suggestion (Home/End only once
244
+ * a suggestion is chosen; otherwise they move the caret as usual)
245
+ * · Enter or Tab → insert the chosen suggestion; with no choice, they keep their usual role
246
+ */
247
+ private static _handleMentionKeydown;
248
+ /** A member's row in the bubble; empty string if their profile URL is unusable. */
249
+ private static _mentionItemHtml;
250
+ private static _insertMention;
251
+ /**
252
+ * Initializes the editor on every textarea matching the selector.
253
+ *
254
+ * @param options.selector CSS selector to target (default: 'textarea')
255
+ * @param options.exclude CSS selector to exclude
256
+ * @param options.toolbar Toolbar mode: 'always' | 'toggle' | 'focus' | 'never'
257
+ * @param options.footer Show the footer — default: true
258
+ * @param options.minHeight Minimum height of the writing area (e.g. '160px')
259
+ * @param options.maxHeight Maximum height before it scrolls (e.g. '400px')
260
+ *
261
+ * The data-mzre-* attributes on each textarea take precedence over the JS options.
262
+ * See the documentation block at the top of the file for detailed use cases.
263
+ *
264
+ * @returns Editor (chainable)
265
+ */
266
+ static init(options?: EditorOptions, integrations?: EditorIntegrations): typeof Editor;
267
+ /**
268
+ * Mounts the editor on a specific textarea.
269
+ * Ideal for elements added dynamically to the DOM (modals, ajax widgets…).
270
+ *
271
+ * @param target HTMLTextAreaElement element or CSS selector
272
+ * @param options Same options as init()
273
+ *
274
+ * @param integrations
275
+ * @returns Editor (chainable)
276
+ */
277
+ static mount(target: HTMLTextAreaElement | string, options?: EditorOptions, integrations?: EditorIntegrations): typeof Editor;
278
+ }