@opositatest/markdown-text-editor 1.0.5 → 1.0.6-canary.037a9b8
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 +159 -54
- package/dist/editor.css +1 -1
- package/dist/editor.js +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,14 +1,67 @@
|
|
|
1
1
|
# @opositatest/markdown-text-editor
|
|
2
2
|
|
|
3
|
+
[](https://github.com/opositatest/opo-markdown-input/actions/workflows/lint.yml)
|
|
4
|
+
[](https://github.com/opositatest/opo-markdown-input/actions/workflows/typecheck.yml)
|
|
5
|
+
[](https://www.npmjs.com/package/@opositatest/markdown-text-editor)
|
|
6
|
+
[](https://www.jsdelivr.com/package/npm/@opositatest/markdown-text-editor)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
|
|
9
|
+
[](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
|
|
10
|
+
[](https://react.dev/)
|
|
11
|
+
|
|
3
12
|
Rich-text editor that serializes content as Markdown. Ships as a self-contained Web Component and as a React component.
|
|
4
13
|
|
|
14
|
+
## Demo
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<img src="./docs/demo-slash-menu.png" alt="Markdown Text Editor slash menu" width="720" />
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
## Supported content
|
|
21
|
+
|
|
22
|
+
The editor currently focuses on text-first rich content that serializes cleanly to Markdown.
|
|
23
|
+
|
|
24
|
+
- Paragraphs
|
|
25
|
+
- Headings (`H1`, `H2`, `H3`)
|
|
26
|
+
- Bullet lists
|
|
27
|
+
- Numbered lists
|
|
28
|
+
- Checklists
|
|
29
|
+
- Toggle lists
|
|
30
|
+
- Block quotes
|
|
31
|
+
- Code blocks
|
|
32
|
+
- Links
|
|
33
|
+
- Inline styles: bold, italic, underline, strikethrough, and inline code
|
|
34
|
+
- Display math blocks written in LaTeX
|
|
35
|
+
|
|
36
|
+
### Math / LaTeX blocks
|
|
37
|
+
|
|
38
|
+
The package includes a custom math block on top of the default BlockNote schema. It renders display formulas with KaTeX and stores them as fenced display-math blocks in Markdown:
|
|
39
|
+
|
|
40
|
+
```md
|
|
41
|
+
$$
|
|
42
|
+
\int_0^1 x^2 dx = \frac{1}{3}
|
|
43
|
+
$$
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
In the editor UI, the math block is available from the slash menu and can be found with queries such as `/math`, `/latex`, `/katex`, or `/formula`.
|
|
47
|
+
|
|
48
|
+
### Scope note
|
|
49
|
+
|
|
50
|
+
This package documents and supports the text-oriented authoring experience above, including the custom math block. Advanced upstream BlockNote media and table flows are not currently part of the documented surface of this package.
|
|
51
|
+
|
|
5
52
|
## Web Component
|
|
6
53
|
|
|
7
54
|
Load via CDN (no build step required):
|
|
8
55
|
|
|
9
56
|
```html
|
|
10
|
-
<link
|
|
11
|
-
|
|
57
|
+
<link
|
|
58
|
+
rel="stylesheet"
|
|
59
|
+
href="https://cdn.jsdelivr.net/npm/@opositatest/markdown-text-editor/dist/editor.css"
|
|
60
|
+
/>
|
|
61
|
+
<script
|
|
62
|
+
type="module"
|
|
63
|
+
src="https://cdn.jsdelivr.net/npm/@opositatest/markdown-text-editor/dist/editor.js"
|
|
64
|
+
></script>
|
|
12
65
|
```
|
|
13
66
|
|
|
14
67
|
### Usage
|
|
@@ -28,44 +81,44 @@ Load via CDN (no build step required):
|
|
|
28
81
|
|
|
29
82
|
### Attributes
|
|
30
83
|
|
|
31
|
-
| Attribute | Type | Description
|
|
32
|
-
|
|
33
|
-
| `name` | string | Field name for form submission
|
|
34
|
-
| `value` | string | Initial Markdown value
|
|
35
|
-
| `placeholder` | string | Placeholder text shown when empty
|
|
36
|
-
| `width` | string | CSS width for the editor container
|
|
37
|
-
| `height` | string | CSS height for the editor container
|
|
38
|
-
| `disabled` | boolean | Disables the editor
|
|
39
|
-
| `readonly` | boolean | Makes the editor read-only
|
|
40
|
-
| `required` | boolean | Participates in native form validation
|
|
84
|
+
| Attribute | Type | Description |
|
|
85
|
+
| ------------- | ------- | -------------------------------------- |
|
|
86
|
+
| `name` | string | Field name for form submission |
|
|
87
|
+
| `value` | string | Initial Markdown value |
|
|
88
|
+
| `placeholder` | string | Placeholder text shown when empty |
|
|
89
|
+
| `width` | string | CSS width for the editor container |
|
|
90
|
+
| `height` | string | CSS height for the editor container |
|
|
91
|
+
| `disabled` | boolean | Disables the editor |
|
|
92
|
+
| `readonly` | boolean | Makes the editor read-only |
|
|
93
|
+
| `required` | boolean | Participates in native form validation |
|
|
41
94
|
|
|
42
95
|
`width` and `height` accept any valid CSS size, such as `320px`, `40rem`, or `100%`.
|
|
43
96
|
|
|
44
97
|
### Properties
|
|
45
98
|
|
|
46
|
-
| Property
|
|
47
|
-
|
|
48
|
-
| `element.value`
|
|
49
|
-
| `element.width`
|
|
50
|
-
| `element.height`
|
|
51
|
-
| `element.disabled`
|
|
52
|
-
| `element.readOnly`
|
|
99
|
+
| Property | Type | Description |
|
|
100
|
+
| ------------------ | ------- | --------------------------- |
|
|
101
|
+
| `element.value` | string | Get or set Markdown content |
|
|
102
|
+
| `element.width` | string | Get or set CSS width |
|
|
103
|
+
| `element.height` | string | Get or set CSS height |
|
|
104
|
+
| `element.disabled` | boolean | Get or set disabled state |
|
|
105
|
+
| `element.readOnly` | boolean | Get or set read-only state |
|
|
53
106
|
|
|
54
107
|
### Methods
|
|
55
108
|
|
|
56
|
-
| Method
|
|
57
|
-
|
|
58
|
-
| `focus()`
|
|
59
|
-
| `getMarkdown()`
|
|
60
|
-
| `setMarkdown(value)`
|
|
109
|
+
| Method | Description |
|
|
110
|
+
| -------------------- | ----------------------------------- |
|
|
111
|
+
| `focus()` | Focus the editor |
|
|
112
|
+
| `getMarkdown()` | Returns current content as Markdown |
|
|
113
|
+
| `setMarkdown(value)` | Replaces editor content |
|
|
61
114
|
|
|
62
115
|
### Events
|
|
63
116
|
|
|
64
|
-
| Event
|
|
65
|
-
|
|
66
|
-
| `input`
|
|
67
|
-
| `change
|
|
68
|
-
| `ready`
|
|
117
|
+
| Event | Fires when |
|
|
118
|
+
| -------- | ------------------------------------ |
|
|
119
|
+
| `input` | On every content change (keystroke) |
|
|
120
|
+
| `change` | On blur if value changed since focus |
|
|
121
|
+
| `ready` | Once the editor has initialized |
|
|
69
122
|
|
|
70
123
|
### Form integration
|
|
71
124
|
|
|
@@ -80,26 +133,26 @@ npm install @opositatest/markdown-text-editor
|
|
|
80
133
|
```
|
|
81
134
|
|
|
82
135
|
```tsx
|
|
83
|
-
import { MarkdownTextEditor } from
|
|
84
|
-
import
|
|
136
|
+
import { MarkdownTextEditor } from "@opositatest/markdown-text-editor";
|
|
137
|
+
import "@opositatest/markdown-text-editor/style";
|
|
85
138
|
|
|
86
|
-
<MarkdownTextEditor defaultValue="Hello" width="100%" height="320px"
|
|
139
|
+
<MarkdownTextEditor defaultValue="Hello" width="100%" height="320px" />;
|
|
87
140
|
```
|
|
88
141
|
|
|
89
142
|
### Props
|
|
90
143
|
|
|
91
|
-
| Prop | Type
|
|
92
|
-
|
|
93
|
-
| `value` | `string`
|
|
94
|
-
| `defaultValue` | `string`
|
|
95
|
-
| `onChange` | `(value: string) => void`
|
|
96
|
-
| `onReady` | `(handle: MarkdownTextEditorHandle) => void
|
|
97
|
-
| `placeholder` | `string`
|
|
98
|
-
| `width` | `string`
|
|
99
|
-
| `height` | `string`
|
|
100
|
-
| `disabled` | `boolean`
|
|
101
|
-
| `readonly` | `boolean`
|
|
102
|
-
| `className` | `string`
|
|
144
|
+
| Prop | Type | Description |
|
|
145
|
+
| -------------- | -------------------------------------------- | -------------------------------------------- |
|
|
146
|
+
| `value` | `string` | Controlled Markdown value |
|
|
147
|
+
| `defaultValue` | `string` | Uncontrolled initial value |
|
|
148
|
+
| `onChange` | `(value: string) => void` | Called on every content change |
|
|
149
|
+
| `onReady` | `(handle: MarkdownTextEditorHandle) => void` | Called once editor has initialized |
|
|
150
|
+
| `placeholder` | `string` | Placeholder text shown when empty |
|
|
151
|
+
| `width` | `string` | CSS width for the editor container |
|
|
152
|
+
| `height` | `string` | CSS height for the editor container |
|
|
153
|
+
| `disabled` | `boolean` | Disables the editor |
|
|
154
|
+
| `readonly` | `boolean` | Makes the editor read-only |
|
|
155
|
+
| `className` | `string` | Additional CSS class on the editor container |
|
|
103
156
|
|
|
104
157
|
`width` and `height` accept any valid CSS size, such as `320px`, `40rem`, or `100%`.
|
|
105
158
|
|
|
@@ -114,21 +167,73 @@ const ref = useRef<TMarkdownTextEditorHandle>(null)
|
|
|
114
167
|
<MarkdownTextEditor ref={ref} defaultValue="Hello" onChange={setValue} />
|
|
115
168
|
```
|
|
116
169
|
|
|
117
|
-
| Method
|
|
118
|
-
|
|
119
|
-
| `ref.focus()`
|
|
120
|
-
| `ref.getMarkdown()`
|
|
121
|
-
| `ref.setMarkdown(v)`
|
|
170
|
+
| Method | Description |
|
|
171
|
+
| -------------------- | ----------------------------------- |
|
|
172
|
+
| `ref.focus()` | Focus the editor |
|
|
173
|
+
| `ref.getMarkdown()` | Returns current content as Markdown |
|
|
174
|
+
| `ref.setMarkdown(v)` | Replaces editor content |
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Styling
|
|
179
|
+
|
|
180
|
+
The component does **not** use Shadow DOM, so all its elements are part of the regular DOM and can be targeted freely from the host page's CSS.
|
|
181
|
+
|
|
182
|
+
### CSS custom properties
|
|
183
|
+
|
|
184
|
+
These properties are defined on the `markdown-text-editor` element and can be overridden at any level:
|
|
185
|
+
|
|
186
|
+
| Property | Default | Description |
|
|
187
|
+
| ----------------- | -------------------------- | ---------------------------------- |
|
|
188
|
+
| `--border-color` | `rgba(15, 23, 42, 0.09)` | Border of the editor field |
|
|
189
|
+
| `--heading-color` | `#0f172a` | Text color inside the editor |
|
|
190
|
+
|
|
191
|
+
```css
|
|
192
|
+
/* Override for all instances */
|
|
193
|
+
markdown-text-editor {
|
|
194
|
+
--border-color: #d1d5db;
|
|
195
|
+
--heading-color: #1f2937;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/* Override for a specific instance */
|
|
199
|
+
#my-editor {
|
|
200
|
+
--border-color: #6366f1;
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Targeting component classes
|
|
205
|
+
|
|
206
|
+
Use these stable class names to override layout, size, fonts, or other visual properties:
|
|
207
|
+
|
|
208
|
+
| Selector | Description |
|
|
209
|
+
| ------------------------------------- | ----------------------------------- |
|
|
210
|
+
| `.markdown-text-editor__field` | Editor container (border, radius, background) |
|
|
211
|
+
| `.markdown-text-editor__field .bn-editor` | Inner editing area (padding, min-height, font-size) |
|
|
212
|
+
| `.bn-container .bn-editor` | BlockNote root (font-family, line-height) |
|
|
213
|
+
|
|
214
|
+
```css
|
|
215
|
+
/* Adjust editor size and typography */
|
|
216
|
+
.markdown-text-editor__field .bn-editor {
|
|
217
|
+
min-height: 400px;
|
|
218
|
+
font-size: 15px;
|
|
219
|
+
line-height: 1.6;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/* Remove border radius */
|
|
223
|
+
.markdown-text-editor__field {
|
|
224
|
+
border-radius: 0.25rem;
|
|
225
|
+
}
|
|
226
|
+
```
|
|
122
227
|
|
|
123
228
|
---
|
|
124
229
|
|
|
125
230
|
## Package exports
|
|
126
231
|
|
|
127
|
-
| Export
|
|
128
|
-
|
|
129
|
-
| `@opositatest/markdown-text-editor`
|
|
130
|
-
| `@opositatest/markdown-text-editor/input
|
|
131
|
-
| `@opositatest/markdown-text-editor/style
|
|
232
|
+
| Export | Description |
|
|
233
|
+
| ----------------------------------------- | ----------------------------------- |
|
|
234
|
+
| `@opositatest/markdown-text-editor` | React component + types |
|
|
235
|
+
| `@opositatest/markdown-text-editor/input` | Self-contained Web Component bundle |
|
|
236
|
+
| `@opositatest/markdown-text-editor/style` | CSS stylesheet |
|
|
132
237
|
|
|
133
238
|
## Browser support
|
|
134
239
|
|