@3kles/kles-richtext-editor 0.0.0-stage → 1.1.0
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,3 +1,120 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Angular rich text editor
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Use `items`, `config`, and `buttonTemplate` to choose, order, hide, disable, and customize toolbar controls. Use `refreshKey` or `refresh()` when command availability depends on state outside the editor. The toolbar, editor, and preview accept `locale` and `messages`. The `provideRichTextToolbar` and `provideRichTextI18n` providers set defaults for an injection scope. The shipped catalogs support English and French, including accessible names. The default toolbar uses the built-in controls and the French catalog. Try the demo at `/?view=toolbar`. [Configuration and examples](../../docs/toolbar-customization.md) · [Performance results](../../docs/toolbar-mount-optimization.md)
|
|
4
|
+
|
|
5
|
+
`@3kles/kles-richtext-editor` follows the Angular Package Format and the 3KLES `src/lib` and `src/public-api.ts` layout. It exposes three standalone OnPush components, `RichTextEditorComponent` (`kles-richtext-editor`), `RichTextToolbarComponent` (`kles-richtext-toolbar`), and `RichTextDocumentPreviewComponent`, a read-only JSON preview.
|
|
6
|
+
|
|
7
|
+
## Toolbar icons
|
|
8
|
+
|
|
9
|
+
Use `{ id: 'undo', icon: 'undo' }` for an icon-only Undo button. The `undo` and `redo` icon names use Material Icons by default. For other Material ligatures, set `iconType: 'material'`, for example `{ id: 'bold', icon: 'format_bold', iconType: 'material' }`. Use `iconType: 'text'` to display a literal string.
|
|
10
|
+
|
|
11
|
+
Set `label: ''` on a built-in button with an icon to hide its visible text explicitly. The button keeps its translated accessible name and tooltip. Set a nonempty `label` or `labelKey` to show text beside a Material icon.
|
|
12
|
+
|
|
13
|
+
Set `iconOnly: true` in `provideRichTextToolbar()` or `[config]` to hide the visible text of every configured button that has an icon, including custom commands with a translated label. In this mode the link field uses Material icons for Apply and Remove. The URL field keeps its visible label. Tooltips and accessible names use the active i18n catalog and its overrides.
|
|
14
|
+
|
|
15
|
+
The host loads the Material Icons font. The Dynamic Forms demo serves it locally. Set `--kles-richtext-toolbar-material-icon-font` to the name of a compatible icon font already loaded by your application. [Material Icons setup](https://developers.google.com/fonts/docs/material_icons#icon_font_for_the_web)
|
|
16
|
+
|
|
17
|
+
## Angular Forms
|
|
18
|
+
|
|
19
|
+
The editor implements `ControlValueAccessor` and `Validator`. It works with `[formControl]`, `formControlName`, and `ngModel` when the host imports the corresponding Forms module.
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import { Component } from '@angular/core';
|
|
23
|
+
import { FormControl, ReactiveFormsModule } from '@angular/forms';
|
|
24
|
+
import { RichTextEditorComponent, RichTextToolbarComponent } from '@3kles/kles-richtext-editor';
|
|
25
|
+
import type { DocumentNode } from '@3kles/richtext-core';
|
|
26
|
+
|
|
27
|
+
@Component({
|
|
28
|
+
selector: 'document-form',
|
|
29
|
+
standalone: true,
|
|
30
|
+
imports: [ReactiveFormsModule, RichTextEditorComponent, RichTextToolbarComponent],
|
|
31
|
+
template: `
|
|
32
|
+
<kles-richtext-editor
|
|
33
|
+
#editor
|
|
34
|
+
[formControl]="control"
|
|
35
|
+
[required]="true"
|
|
36
|
+
[invalid]="control.invalid && (control.touched || control.dirty)"
|
|
37
|
+
label="Document"
|
|
38
|
+
/>
|
|
39
|
+
<kles-richtext-toolbar [editor]="editor" />
|
|
40
|
+
`,
|
|
41
|
+
})
|
|
42
|
+
export class DocumentFormComponent {
|
|
43
|
+
readonly control = new FormControl<DocumentNode | null>(null, { updateOn: 'blur' });
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The form value is the native `DocumentNode` AST. Passing `null`, including through `reset()`, displays a canonical empty document. The core validates and copies external values. If a value is invalid, the editor keeps displaying the previous document and reports `richtextDocument` with schema diagnostics. Convert HTML or serialized JSON explicitly before writing it to a form control.
|
|
48
|
+
|
|
49
|
+
An external write received during a native notification takes precedence over the remaining events from that edit. If the write is invalid, the editor preserves its error and the control value until notification completes. The earlier `documentChange` cannot overwrite it through `onChange`. A newer valid write supersedes the rejected write, and a subsequent edit can correct the invalid value.
|
|
50
|
+
|
|
51
|
+
Forms owns the value as soon as it calls `writeValue` or registers its change callback. The editor then ignores updates to the legacy `[document]` input. Load form values through `control.setValue(document)`, `patchValue`, or `reset`.
|
|
52
|
+
|
|
53
|
+
The CVA `onChange` callback receives actual document edits from input, commands, paste, undo, and redo. External writes, loads, selection changes, and access changes preserve the control's pristine or dirty state. Angular manages `pristine/dirty`, `touched/untouched`, `updateOn`, reset, and the exclusion of disabled controls from `form.value`.
|
|
54
|
+
|
|
55
|
+
## Inputs, signals, and outputs
|
|
56
|
+
|
|
57
|
+
| Contract | Behavior |
|
|
58
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
59
|
+
| `document: DocumentNode` | Legacy input for use outside Forms. Loading it does not emit `documentChange`. |
|
|
60
|
+
| `readOnly: boolean` | Blocks editing and allows focus, selection, and copying. |
|
|
61
|
+
| `disabled: boolean` | Disables the surface and removes it from tab navigation if this input or Forms disables the control. |
|
|
62
|
+
| `required: boolean` | Requires nonempty document text after trimming whitespace. |
|
|
63
|
+
| `invalid: boolean` | Optional visual state from the host. Control validators operate independently. |
|
|
64
|
+
| `label: string` | Accessible name of the surface. |
|
|
65
|
+
| `describedBy: string` | Consumer-owned instruction IDs to include alongside internal error descriptions. |
|
|
66
|
+
| `documentChange` | Canonical document after an edit, as in the original contract. |
|
|
67
|
+
| `stateChange` | Current native state, including selection and metadata. |
|
|
68
|
+
| `editorEvent` | Typed native events, including content diagnostics. |
|
|
69
|
+
| `validationChange` | Schema or required-content errors in the view. |
|
|
70
|
+
|
|
71
|
+
The four boolean inputs accept boolean bindings or HTML attributes through `booleanAttribute`. Use the public signals `state()`, `composing()`, `focused()`, `effectiveDisabled()`, `editable()`, and `validationError()` to observe state without accessing the native instance. `state()` is `undefined` before mounting and after destruction. The surface exposes its name, access, required status, and validation state through ARIA attributes. Pass external Forms status through `[invalid]` to avoid circular `NgControl` injection.
|
|
72
|
+
|
|
73
|
+
The legacy input and output bindings also work outside Forms.
|
|
74
|
+
|
|
75
|
+
```html
|
|
76
|
+
<kles-richtext-editor
|
|
77
|
+
[document]="document()"
|
|
78
|
+
[readOnly]="readOnly()"
|
|
79
|
+
(documentChange)="document.set($event)"
|
|
80
|
+
label="Document content"
|
|
81
|
+
/>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Validation
|
|
85
|
+
|
|
86
|
+
The `NG_VALIDATORS` provider always applies the native schema. `required` also checks for text in paragraphs, headings, lists, blockquotes, and code blocks. Empty paragraphs, line breaks alone, and whitespace-only text count as empty. Use the rich-text validator to enforce this rule, since `Validators.required` alone treats any AST object as present.
|
|
87
|
+
|
|
88
|
+
You can use `richTextDocumentValidator(control)` and `richTextRequiredValidator(control)` as explicit validators. `validateRichTextValue(value)` returns a typed validation result and interprets `null` as an empty document. Errors have the shape `{ richtextDocument: { diagnostics } }` or `{ required: true }`. Invalid values produce schema errors.
|
|
89
|
+
|
|
90
|
+
Validation runs immediately. A pristine control displays its required error after an edit, a move outside the shared focus region, or submission. The editor reports schema errors in external values immediately. Each displayed error has a visible message associated through `aria-describedby`. `[invalid]` can display an error from the host's business rules. `describedBy="document-help"` includes host instructions alongside the error message. `writeValue` resets presentation tied to the previous interaction. Internal IDs are scoped to the Angular application. Set distinct `APP_ID` values when several applications share the page. [Accessibility checks and limits](../../docs/accessibility.md)
|
|
91
|
+
|
|
92
|
+
## Focus, touched state, and composition
|
|
93
|
+
|
|
94
|
+
The surface and toolbar controls share a focus region. `onTouched` fires when focus leaves that region after an interaction. Moving from the surface to a button, the heading selector, or the link field stays inside it. A custom toolbar can join the region with `registerFocusRegion(element)`, which returns a cleanup function. Programmatic focus alone, value writes, and disabling the surface preserve the control's touched state.
|
|
95
|
+
|
|
96
|
+
An IME uses native pre-edit text within a block. If focus leaves during composition, processing waits for the session to resolve. The editor sends the final document to `onChange` before `onTouched`, so `updateOn: 'blur'` receives the final value. The editor defers external writes during composition and applies the last valid one when the session ends. A pending external write suppresses intermediate composition updates to Forms and `documentChange` to protect the write. An invalid external value cancels the previous deferred write and any pre-edit started before it. The last valid AST stays visible, the schema error stays present, and `onChange` leaves the rejected external value intact. If the engine is publishing events, cancellation runs in the next microtask. New input can then correct the control value.
|
|
97
|
+
|
|
98
|
+
With `updateOn: 'submit'`, the component listens for submission on the ancestor form during capture. If `compositionend` has already arrived, it finishes the composition synchronously before Angular processes the form. This lets a `requestSubmit()` in the same turn receive the confirmed document. If the pre-edit is unconfirmed or a native notification prevents resolution, the component calls `preventDefault` and `stopImmediatePropagation` to stop submission without publishing pre-edit text. Submit again after composition or the current notification finishes. The listener is browser-only and is removed on destruction.
|
|
99
|
+
|
|
100
|
+
The component defers `readOnly` until composition ends. `disabled` immediately blocks the surface and cancels the pre-edit session in the model without committing it. When a native notification is in progress, metadata updates run in the next microtask. This behavior applies to the editor model, while the operating system manages its IME panel. The loaded document remains available in read-only mode. A disabled control follows standard Angular Forms rules.
|
|
101
|
+
|
|
102
|
+
## Commands and conversions
|
|
103
|
+
|
|
104
|
+
`execute(command)` returns a typed action result. It returns `undefined` before mounting, after destruction, or while the component is disabled. The `focus()`, `getDocument()`, `canUndo()`, `canRedo()`, `isActive(mark)`, `can(command)`, and `isActiveCommand(command)` methods support custom toolbars. The built-in toolbar uses those capabilities and preserves the canonical selection during link editing. [Command contracts](../../docs/rich-text-commands.md)
|
|
105
|
+
|
|
106
|
+
`loadHtml(html, emitChange = false)`, `insertHtml(html)`, and `getHtml()` expose sanitized conversion and diagnostics. Loading replaces the document, resets history, and works in read-only mode. The legacy `emitChange` option requests a `documentChange` output without calling the Forms `onChange` callback. Insertion is an undoable edit. `editorEvent` also reports paste diagnostics as `contentDiagnostics`. To load HTML into a form, convert it to an AST and write that value to the control.
|
|
107
|
+
|
|
108
|
+
The toolbar and `setLink` accept complete template destinations such as `${context.url}`. The editor and preview keep these destinations inert. `loadHtml()` and `getHtml()` preserve the literal variable in `href`, ready for the consuming application's template rendering.
|
|
109
|
+
|
|
110
|
+
## Configuration and lifecycle
|
|
111
|
+
|
|
112
|
+
`RICHTEXT_EDITOR_EXTENSIONS` configures instances within its injection scope. Without a provider, the editor installs the native preset. An empty array preserves basic editing and existing documents. The editor captures the configuration at mount time and rejects collisions before modifying the surface.
|
|
113
|
+
|
|
114
|
+
The component creates the native instance once after initializing the browser view. Ordinary Angular changes, form values, and access settings reuse that instance. Server rendering preserves declarative elements and attributes. Destruction releases subscriptions, focus regions, callbacks, and DOM references, and deactivates deferred writes.
|
|
115
|
+
|
|
116
|
+
The peer dependencies are `@angular/common`, `@angular/core`, and `@angular/forms`, all at `^22.2.6`. The underlying engine is independent of Angular and zone.js. The wrapper uses the native editor engine.
|
|
117
|
+
|
|
118
|
+
The workspace Angular and browser suites verify Forms, the toolbar, and consumption from an external package. The phase reports document limits for cross-platform composition, Firefox and WebKit, screen readers, and performance.
|
|
119
|
+
|
|
120
|
+
The Dynamic Forms example shows how to pass toolbar and translation providers to one `RichTextDynamicFieldComponent` through its field configuration. [Dynamic Forms integration example](../../src/app/dynamicforms-demo/README.md)
|