@mlightcad/mtext-input-box 0.1.1 → 0.1.2

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.
package/README.md CHANGED
@@ -1,13 +1,21 @@
1
- # @mlightcad/mtext-input-box - Three.js Rich Text Editor
1
+ # Three.js Rich Text Editor
2
2
 
3
3
  Three.js-based MTEXT editor component with built-in IME bridge, cursor/selection rendering, and floating toolbar.
4
4
 
5
+ ![MText Editor](../../docs/mtext-editor.webp)
6
+
5
7
  ## Purpose
6
8
 
7
- - MTEXT-style editing in Three.js.
8
- - Keyboard/mouse/IME editing, selection, formatting, undo/redo.
9
- - Built-in toolbar (theme/font list/container/offset configurable).
10
- - Integrates `@mlightcad/mtext-renderer` and `@mlightcad/text-box-cursor`.
9
+ - MTEXT-style editing in Three.js
10
+ - Keyboard/mouse/IME editing, selection, formatting, and undo/redo
11
+ - Built-in toolbar (configurable theme, font list, container, and offset)
12
+ - Integration with `@mlightcad/mtext-renderer` and `@mlightcad/text-box-cursor`
13
+
14
+ ## Technical Details
15
+
16
+ - Medium article: [Building a Three.js Rich Text Editor](https://medium.com/@mlightcad/building-a-three-js-rich-text-editor-b7283126ee97)
17
+
18
+ ![arch diagram](../../docs/architecture.svg)
11
19
 
12
20
  ## Install
13
21
 
@@ -66,16 +74,62 @@ Notes:
66
74
 
67
75
  ## Toolbar
68
76
 
69
- The built-in toolbar is a DOM overlay mounted above the active editor and updated automatically when camera/viewport changes.
77
+ The built-in toolbar is a DOM overlay mounted above the active editor and updated automatically when the camera or viewport changes.
70
78
 
71
79
  `toolbar` options:
72
80
 
73
81
  - `enabled?: boolean` (default `true`)
74
82
  - `theme?: 'light' | 'dark'` (default `dark`)
75
83
  - `fontFamilies?: string[]` (default `['Arial', 'Helvetica', 'Verdana', 'Tahoma', 'Trebuchet MS', 'Times New Roman', 'Georgia', 'Courier New', 'system-ui', 'sans-serif', 'serif', 'monospace']`)
84
+ - `colorPicker?: (context) => { setValue?, setTheme?, dispose? }` (optional custom picker factory)
76
85
  - `container?: HTMLElement` (default `document.body`)
77
86
  - `offsetY?: number` (default `10`)
78
87
 
88
+ Custom color picker factory context:
89
+
90
+ - `container: HTMLElement`: mount point for your UI.
91
+ - `theme: 'light' | 'dark'`: current toolbar theme.
92
+ - `initialColor: '#RRGGBB'`: initial color.
93
+ - `onChange(hexColor)`: call this when user picks a new color.
94
+
95
+ Example (mount a Vue color picker):
96
+
97
+ ```ts
98
+ import { createApp, h, ref } from 'vue';
99
+
100
+ toolbar: {
101
+ colorPicker: ({ container, initialColor, theme, onChange }) => {
102
+ const color = ref(initialColor);
103
+ const app = createApp({
104
+ render() {
105
+ return h(MyVueColorPicker, {
106
+ modelValue: color.value,
107
+ theme,
108
+ 'onUpdate:modelValue': (next: string) => {
109
+ color.value = next;
110
+ onChange(next);
111
+ }
112
+ });
113
+ }
114
+ });
115
+
116
+ app.mount(container);
117
+
118
+ return {
119
+ setValue(next: string) {
120
+ color.value = next;
121
+ },
122
+ setTheme(nextTheme: 'light' | 'dark') {
123
+ // Optional: forward theme into your picker state if needed.
124
+ },
125
+ dispose() {
126
+ app.unmount();
127
+ }
128
+ };
129
+ }
130
+ }
131
+ ```
132
+
79
133
  Public toolbar-related methods:
80
134
 
81
135
  - `setToolbarTheme('light' | 'dark')`
@@ -99,7 +153,7 @@ Public toolbar-related methods:
99
153
  - `boundingBoxStyle?: { color?, opacity?, padding?, zOffset? }`: boundary style overrides.
100
154
  - `workerUrl?: string | URL`: worker URL for renderer initialization.
101
155
  - `cursorStyle` / `selectionStyle`: forwarded to cursor renderer.
102
- - `toolbar`: built-in toolbar options (`enabled`, `theme`, `fontFamilies`, `container`, `offsetY`).
156
+ - `toolbar`: built-in toolbar options (`enabled`, `theme`, `fontFamilies`, `colorPicker`, `container`, `offsetY`).
103
157
 
104
158
  ## Input And Interaction
105
159
 
package/dist/index.d.ts CHANGED
@@ -2,6 +2,6 @@ export { MTextInputBox, MTextEditor, defaultCharFormat, sameFormat } from './vie
2
2
  export { MTextDocument, parseMTextToAst, buildMTextFromAst, insertTextInAst, deleteRangeInAst, replaceRangeInAst } from './model';
3
3
  export { EditorUiAdapter } from './controller';
4
4
  export { MTextToolbar } from './ui';
5
- export type { CharFormat, CharScript, CursorDirection, EditorState, LayoutCharBox, CursorLayoutData, MTextBoundingBoxStyle, MTextInputBoxEvent, MTextInputBoxOptions, MTextToolbarOptions, MTextToolbarTheme, MTextEditorEvent, MTextEditorOptions, MTextRendererOutput, SelectionDirection } from './viewer';
5
+ export type { CharFormat, CharScript, CursorDirection, EditorState, LayoutCharBox, CursorLayoutData, MTextBoundingBoxStyle, MTextInputBoxEvent, MTextInputBoxOptions, MTextToolbarColorPickerContext, MTextToolbarColorPickerFactory, MTextToolbarColorPickerInstance, MTextToolbarOptions, MTextToolbarTheme, MTextEditorEvent, MTextEditorOptions, MTextRendererOutput, SelectionDirection } from './viewer';
6
6
  export type { MTextScript, MTextStyle, MTextAst, MTextAstNode, EditorSelection } from './model';
7
7
  export type { EditorCommand, EditorKeyEventLike } from './controller';
@@ -1,15 +1,16 @@
1
- import type { CharFormat, MTextToolbarTheme } from '../viewer/types';
1
+ import type { CharFormat, MTextToolbarColorPickerFactory, MTextToolbarTheme } from '../viewer/types';
2
2
  export interface ToolbarOptions {
3
3
  anchorElement: HTMLElement;
4
4
  container?: HTMLElement;
5
5
  theme: MTextToolbarTheme;
6
6
  fontFamilies?: string[];
7
+ colorPicker?: MTextToolbarColorPickerFactory;
7
8
  onFormatChange: (partial: Partial<CharFormat>) => void;
8
9
  onToggleStack: () => void;
9
10
  onToggleSuperscript?: () => boolean;
10
11
  onToggleSubscript?: () => boolean;
11
12
  }
12
- export type ToolbarSessionOptions = Omit<ToolbarOptions, 'container' | 'theme' | 'fontFamilies'>;
13
+ export type ToolbarSessionOptions = Omit<ToolbarOptions, 'container' | 'theme' | 'fontFamilies' | 'colorPicker'>;
13
14
  export declare class MTextToolbar {
14
15
  private anchorElement;
15
16
  private readonly root;
@@ -19,6 +20,7 @@ export declare class MTextToolbar {
19
20
  private onToggleSuperscript;
20
21
  private onToggleSubscript;
21
22
  private theme;
23
+ private readonly colorPicker;
22
24
  constructor(options: ToolbarOptions);
23
25
  setTheme(theme: MTextToolbarTheme): void;
24
26
  getTheme(): MTextToolbarTheme;
@@ -31,4 +33,6 @@ export declare class MTextToolbar {
31
33
  private setToggleState;
32
34
  private ensureSelectValue;
33
35
  private bindEvents;
36
+ private createColorPicker;
37
+ private applyColorChange;
34
38
  }
@@ -147,6 +147,14 @@ function hexToColorNumber(hex) {
147
147
  return 0xffffff;
148
148
  return Number.parseInt(hex.slice(1), 16);
149
149
  }
150
+ function normalizeHexColor(hex) {
151
+ const normalized = hex.trim().toLowerCase();
152
+ if (/^#[0-9a-f]{6}$/.test(normalized))
153
+ return normalized;
154
+ if (/^[0-9a-f]{6}$/.test(normalized))
155
+ return `#${normalized}`;
156
+ return null;
157
+ }
150
158
  function createIconButton(title, icon) {
151
159
  const btn = document.createElement('button');
152
160
  btn.type = 'button';
@@ -179,6 +187,7 @@ export class MTextToolbar {
179
187
  onToggleSuperscript;
180
188
  onToggleSubscript;
181
189
  theme;
190
+ colorPicker;
182
191
  constructor(options) {
183
192
  ensureToolbarStyles();
184
193
  this.anchorElement = options.anchorElement;
@@ -205,10 +214,8 @@ export class MTextToolbar {
205
214
  fontSize.min = '1';
206
215
  fontSize.max = '1024';
207
216
  fontSize.step = '1';
208
- const fontColor = document.createElement('input');
209
- fontColor.className = 'ml-mtext-toolbar__color';
210
- fontColor.type = 'color';
211
- typographyGroup.append(fontFamily, fontSize, fontColor);
217
+ this.colorPicker = this.createColorPicker(options.colorPicker);
218
+ typographyGroup.append(fontFamily, fontSize, this.colorPicker.host);
212
219
  const separator1 = document.createElement('div');
213
220
  separator1.className = 'ml-mtext-toolbar__separator';
214
221
  const styleGroup = document.createElement('div');
@@ -226,7 +233,6 @@ export class MTextToolbar {
226
233
  this.controls = {
227
234
  fontFamily,
228
235
  fontSize,
229
- fontColor,
230
236
  boldBtn,
231
237
  italicBtn,
232
238
  underlineBtn,
@@ -243,6 +249,7 @@ export class MTextToolbar {
243
249
  setTheme(theme) {
244
250
  this.theme = theme;
245
251
  this.root.dataset.theme = theme;
252
+ this.colorPicker.setTheme(theme);
246
253
  }
247
254
  getTheme() {
248
255
  return this.theme;
@@ -273,7 +280,7 @@ export class MTextToolbar {
273
280
  this.ensureSelectValue(format.fontFamily);
274
281
  this.controls.fontSize.value = String(Math.max(1, Math.round(format.fontSize)));
275
282
  const color = format.rgb !== null ? format.rgb : 0xffffff;
276
- this.controls.fontColor.value = colorNumberToHex(color);
283
+ this.colorPicker.setValue(colorNumberToHex(color));
277
284
  this.setToggleState(this.controls.boldBtn, format.bold);
278
285
  this.setToggleState(this.controls.italicBtn, format.italic);
279
286
  this.setToggleState(this.controls.underlineBtn, format.underline);
@@ -283,6 +290,7 @@ export class MTextToolbar {
283
290
  this.setToggleState(this.controls.subscriptBtn, format.script === 'subscript');
284
291
  }
285
292
  dispose() {
293
+ this.colorPicker.dispose();
286
294
  this.root.remove();
287
295
  }
288
296
  setStackActive(active) {
@@ -320,12 +328,6 @@ export class MTextToolbar {
320
328
  this.anchorElement.focus({ preventScroll: true });
321
329
  }
322
330
  });
323
- this.controls.fontColor.addEventListener('input', () => {
324
- this.onFormatChange({
325
- aci: null,
326
- rgb: hexToColorNumber(this.controls.fontColor.value)
327
- });
328
- });
329
331
  this.controls.boldBtn.addEventListener('click', () => {
330
332
  this.onFormatChange({ bold: !this.controls.boldBtn.classList.contains('is-active') });
331
333
  });
@@ -360,10 +362,69 @@ export class MTextToolbar {
360
362
  const target = event.target;
361
363
  if (!target)
362
364
  return;
365
+ if (target.closest('[data-ml-mtext-toolbar-interactive="true"]'))
366
+ return;
363
367
  if (target.tagName === 'INPUT' || target.tagName === 'SELECT' || target.tagName === 'OPTION')
364
368
  return;
365
369
  event.preventDefault();
366
370
  this.anchorElement.focus({ preventScroll: true });
367
371
  });
368
372
  }
373
+ createColorPicker(factory) {
374
+ if (!factory) {
375
+ const input = document.createElement('input');
376
+ input.className = 'ml-mtext-toolbar__color';
377
+ input.type = 'color';
378
+ input.dataset.mlMtextToolbarInteractive = 'true';
379
+ input.addEventListener('input', () => {
380
+ this.applyColorChange(input.value);
381
+ });
382
+ return {
383
+ host: input,
384
+ setValue: (hex) => {
385
+ const normalized = normalizeHexColor(hex);
386
+ if (normalized)
387
+ input.value = normalized;
388
+ },
389
+ setTheme: () => { },
390
+ dispose: () => { }
391
+ };
392
+ }
393
+ const host = document.createElement('div');
394
+ host.className = 'ml-mtext-toolbar__color';
395
+ host.dataset.mlMtextToolbarInteractive = 'true';
396
+ const instance = factory({
397
+ container: host,
398
+ theme: this.theme,
399
+ initialColor: '#ffffff',
400
+ onChange: (hex) => {
401
+ this.applyColorChange(hex);
402
+ }
403
+ });
404
+ const typed = (instance ?? {});
405
+ return {
406
+ host,
407
+ setValue: (hex) => {
408
+ const normalized = normalizeHexColor(hex);
409
+ if (!normalized)
410
+ return;
411
+ typed.setValue?.(normalized);
412
+ },
413
+ setTheme: (theme) => {
414
+ typed.setTheme?.(theme);
415
+ },
416
+ dispose: () => {
417
+ typed.dispose?.();
418
+ }
419
+ };
420
+ }
421
+ applyColorChange(hex) {
422
+ const normalized = normalizeHexColor(hex);
423
+ if (!normalized)
424
+ return;
425
+ this.onFormatChange({
426
+ aci: null,
427
+ rgb: hexToColorNumber(normalized)
428
+ });
429
+ }
369
430
  }
@@ -1,2 +1,2 @@
1
1
  export { MTextInputBox, MTextEditor, defaultCharFormat, sameFormat } from './viewer';
2
- export type { CharFormat, CharScript, EditorState, LayoutCharBox, RendererContainerBox, RendererLineInfo, MTextRendererOutput, CursorLayoutData, MTextBoundingBoxStyle, MTextInputBoxOptions, MTextToolbarOptions, MTextToolbarTheme, CursorDirection, SelectionDirection, MTextInputBoxEvent, MTextEditorEvent, MTextEditorOptions } from './types';
2
+ export type { CharFormat, CharScript, EditorState, LayoutCharBox, RendererContainerBox, RendererLineInfo, MTextRendererOutput, CursorLayoutData, MTextBoundingBoxStyle, MTextInputBoxOptions, MTextToolbarColorPickerContext, MTextToolbarColorPickerFactory, MTextToolbarColorPickerInstance, MTextToolbarOptions, MTextToolbarTheme, CursorDirection, SelectionDirection, MTextInputBoxEvent, MTextEditorEvent, MTextEditorOptions } from './types';
@@ -111,6 +111,28 @@ export interface MTextBoundingBoxStyle {
111
111
  }
112
112
  /** Construction options for `MTextInputBox`. */
113
113
  export type MTextToolbarTheme = 'light' | 'dark';
114
+ /** Context passed to custom toolbar color picker factory. */
115
+ export interface MTextToolbarColorPickerContext {
116
+ /** Host element where custom UI should be mounted. */
117
+ container: HTMLElement;
118
+ /** Current toolbar theme. */
119
+ theme: MTextToolbarTheme;
120
+ /** Initial color as hex string (`#RRGGBB`). */
121
+ initialColor: string;
122
+ /** Call when user picks a new color. */
123
+ onChange: (hexColor: string) => void;
124
+ }
125
+ /** Lifecycle hooks for a custom toolbar color picker. */
126
+ export interface MTextToolbarColorPickerInstance {
127
+ /** Sync picker UI when editor format changes. */
128
+ setValue?: (hexColor: string) => void;
129
+ /** Sync picker UI when toolbar theme changes. */
130
+ setTheme?: (theme: MTextToolbarTheme) => void;
131
+ /** Cleanup mounted resources when toolbar is disposed. */
132
+ dispose?: () => void;
133
+ }
134
+ /** Factory used to mount custom toolbar color picker UI (for example a Vue component). */
135
+ export type MTextToolbarColorPickerFactory = (context: MTextToolbarColorPickerContext) => MTextToolbarColorPickerInstance | void;
114
136
  /** Toolbar options for built-in editor toolbar UI. */
115
137
  export interface MTextToolbarOptions {
116
138
  /** Enables the built-in toolbar. Defaults to true. */
@@ -119,6 +141,8 @@ export interface MTextToolbarOptions {
119
141
  theme?: MTextToolbarTheme;
120
142
  /** Available font family options shown in toolbar dropdown. */
121
143
  fontFamilies?: string[];
144
+ /** Custom color picker factory used instead of native `<input type="color">`. */
145
+ colorPicker?: MTextToolbarColorPickerFactory;
122
146
  /** Custom DOM container to mount toolbar. Defaults to document.body. */
123
147
  container?: HTMLElement;
124
148
  /** Vertical offset in pixels above editor top edge. Defaults to 10. */
@@ -11,6 +11,7 @@ export declare class MTextInputBox {
11
11
  private static sharedToolbar;
12
12
  private static sharedToolbarContainer;
13
13
  private static sharedToolbarFontFamiliesKey;
14
+ private static sharedToolbarColorPickerFactory;
14
15
  private static readonly instances;
15
16
  private readonly scene;
16
17
  private readonly camera;
@@ -57,6 +58,7 @@ export declare class MTextInputBox {
57
58
  private toolbarEnabled;
58
59
  private toolbarContainer;
59
60
  private toolbarFontFamilies;
61
+ private toolbarColorPicker;
60
62
  private readonly onImeKeyDown;
61
63
  private readonly onWindowKeyDown;
62
64
  private readonly onImeBeforeInput;
@@ -14,6 +14,7 @@ export class MTextInputBox {
14
14
  static sharedToolbar = null;
15
15
  static sharedToolbarContainer = null;
16
16
  static sharedToolbarFontFamiliesKey = '';
17
+ static sharedToolbarColorPickerFactory = null;
17
18
  static instances = new Set();
18
19
  scene;
19
20
  camera;
@@ -70,6 +71,7 @@ export class MTextInputBox {
70
71
  toolbarEnabled = true;
71
72
  toolbarContainer = null;
72
73
  toolbarFontFamilies = null;
74
+ toolbarColorPicker;
73
75
  onImeKeyDown = (event) => {
74
76
  if (!this.isActiveEditor())
75
77
  return;
@@ -213,6 +215,7 @@ export class MTextInputBox {
213
215
  this.toolbarEnabled = options.toolbar?.enabled ?? true;
214
216
  this.toolbarContainer = options.toolbar?.container ?? null;
215
217
  this.toolbarFontFamilies = options.toolbar?.fontFamilies ?? null;
218
+ this.toolbarColorPicker = options.toolbar?.colorPicker;
216
219
  this.width = Math.max(1, options.width);
217
220
  this.position = options.position?.clone() ?? new THREE.Vector3(0, 0, 0);
218
221
  this.enableWordWrap = options.enableWordWrap ?? true;
@@ -699,6 +702,7 @@ export class MTextInputBox {
699
702
  MTextInputBox.sharedToolbar = null;
700
703
  MTextInputBox.sharedToolbarContainer = null;
701
704
  MTextInputBox.sharedToolbarFontFamiliesKey = '';
705
+ MTextInputBox.sharedToolbarColorPickerFactory = null;
702
706
  MTextInputBox.activeEditor = null;
703
707
  }
704
708
  }
@@ -870,7 +874,8 @@ export class MTextInputBox {
870
874
  const fontFamiliesKey = this.toolbarFontFamilies?.join('\u0000') ?? '';
871
875
  const shouldRecreate = !MTextInputBox.sharedToolbar ||
872
876
  MTextInputBox.sharedToolbarContainer !== container ||
873
- MTextInputBox.sharedToolbarFontFamiliesKey !== fontFamiliesKey;
877
+ MTextInputBox.sharedToolbarFontFamiliesKey !== fontFamiliesKey ||
878
+ MTextInputBox.sharedToolbarColorPickerFactory !== (this.toolbarColorPicker ?? null);
874
879
  if (shouldRecreate) {
875
880
  MTextInputBox.sharedToolbar?.dispose();
876
881
  const toolbarOptions = {
@@ -881,9 +886,13 @@ export class MTextInputBox {
881
886
  if (this.toolbarFontFamilies) {
882
887
  toolbarOptions.fontFamilies = this.toolbarFontFamilies;
883
888
  }
889
+ if (this.toolbarColorPicker) {
890
+ toolbarOptions.colorPicker = this.toolbarColorPicker;
891
+ }
884
892
  MTextInputBox.sharedToolbar = new MTextToolbar(toolbarOptions);
885
893
  MTextInputBox.sharedToolbarContainer = container;
886
894
  MTextInputBox.sharedToolbarFontFamiliesKey = fontFamiliesKey;
895
+ MTextInputBox.sharedToolbarColorPickerFactory = this.toolbarColorPicker ?? null;
887
896
  }
888
897
  const toolbar = MTextInputBox.sharedToolbar;
889
898
  if (!toolbar) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mlightcad/mtext-input-box",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -17,8 +17,8 @@
17
17
  "@mlightcad/text-box-cursor": "0.1.1"
18
18
  },
19
19
  "peerDependencies": {
20
- "@mlightcad/mtext-parser": "^1.3.2",
21
- "@mlightcad/mtext-renderer": "^0.10.1",
20
+ "@mlightcad/mtext-parser": "^1.3.3",
21
+ "@mlightcad/mtext-renderer": "^0.10.2",
22
22
  "three": "^0.172.0"
23
23
  },
24
24
  "devDependencies": {