@domternal/react 0.11.1 → 0.11.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 +70 -29
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,42 +3,83 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@domternal/react)
|
|
4
4
|
[](https://github.com/domternal/domternal/blob/main/LICENSE)
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
React components and hooks for the [Domternal](https://domternal.dev) editor. Wraps the headless
|
|
7
|
+
[`@domternal/core`](https://www.npmjs.com/package/@domternal/core) editor with React-native APIs: a composable
|
|
8
|
+
`Domternal` component with namespaced subcomponents, a `useEditor` hook for full control, an `EditorProvider`
|
|
9
|
+
context, and `ReactNodeViewRenderer` for writing custom node views as React components. Works with React 18
|
|
10
|
+
and React 19.
|
|
8
11
|
|
|
9
12
|
## Links
|
|
10
13
|
|
|
11
|
-
<u>[Website](https://domternal.dev)</u> • <u>[Documentation](https://domternal.dev/v1/
|
|
12
|
-
<u>[StackBlitz (Angular)](https://stackblitz.com/edit/domternal-angular-full-example)</u> • <u>[StackBlitz (React)](https://stackblitz.com/edit/domternal-react-full-example)</u> • <u>[StackBlitz (Vue)](https://stackblitz.com/edit/domternal-vue-full-example)</u> • <u>[StackBlitz (Vanilla TS)](https://stackblitz.com/edit/domternal-vanilla-full-example)</u>
|
|
14
|
+
<u>[Website](https://domternal.dev)</u> • <u>[Documentation](https://domternal.dev/v1/guides/react)</u> • <u>[Live examples](https://domternal.dev/examples)</u>
|
|
13
15
|
|
|
14
|
-
##
|
|
16
|
+
## Install
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
```bash
|
|
19
|
+
pnpm add @domternal/react @domternal/core react react-dom
|
|
20
|
+
```
|
|
17
21
|
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
- **React components** - composable `Domternal` component, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (React 18+)
|
|
21
|
-
- **Vue components** - composable `Domternal` component, `useEditor`/`useEditorState` composables, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (Vue 3.3+)
|
|
22
|
-
- **Vanilla wrapper** - framework-free class-based API for Astro, Svelte, Solid, plain HTML, and Web Components - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker
|
|
23
|
-
- **Notion-style block UX** - drag-to-reorder, block context menu, slash command, smart paste, keyboard reorder, floating Table of Contents
|
|
24
|
-
- **70+ extensions across 16 packages** - nodes, marks, and behavior extensions
|
|
25
|
-
- **125+ chainable commands** - `editor.chain().focus().toggleBold().run()`
|
|
26
|
-
- **Full table support** - cell merging, column resize, row/column controls, cell toolbar, all free and MIT licensed
|
|
27
|
-
- **Tree-shakeable** - import only what you use, your bundler strips the rest
|
|
28
|
-
- **~44 KB gzipped** (own code), <u>[see Packages](https://domternal.dev/v1/packages)</u> for full bundle breakdown with ProseMirror
|
|
29
|
-
- **TypeScript first** - 100% typed, zero `any`
|
|
30
|
-
- **15,000+ tests** - 4,000+ unit and 11,000+ E2E across 230+ Playwright specs and 4 demo apps
|
|
31
|
-
- **Light and dark theme** - 120+ CSS custom properties for full visual control
|
|
32
|
-
- **Inline styles export** - `getHTML({ styled: true })` produces inline CSS ready for email clients, CMS, and Google Docs
|
|
33
|
-
- **SSR helpers** - `generateHTML`, `generateJSON`, `generateText` for server-side rendering
|
|
22
|
+
`react` (>=18), `react-dom` (>=18), and `@domternal/core` (>=0.11) are peer dependencies. Import the theme
|
|
23
|
+
([`@domternal/theme`](https://www.npmjs.com/package/@domternal/theme)) in your entry CSS for default styling:
|
|
34
24
|
|
|
35
|
-
|
|
25
|
+
```css
|
|
26
|
+
@import '@domternal/theme';
|
|
27
|
+
```
|
|
36
28
|
|
|
37
|
-
|
|
38
|
-
- <u>[Introduction](https://domternal.dev/v1/introduction)</u> - core concepts, architecture, and design decisions
|
|
39
|
-
- <u>[Packages & Bundle Size](https://domternal.dev/v1/packages)</u> - what each package includes and bundle size breakdown
|
|
40
|
-
- <u>[Blog](https://domternal.dev/blog)</u>
|
|
29
|
+
## Usage
|
|
41
30
|
|
|
42
|
-
|
|
31
|
+
The recommended pattern uses the composable `Domternal` component. It creates the editor and provides it
|
|
32
|
+
to every subcomponent via context, so no `editor` prop needs to be passed down:
|
|
43
33
|
|
|
44
|
-
|
|
34
|
+
```tsx
|
|
35
|
+
import { Domternal } from '@domternal/react';
|
|
36
|
+
import { StarterKit, BubbleMenu } from '@domternal/core';
|
|
37
|
+
|
|
38
|
+
export default function Editor() {
|
|
39
|
+
return (
|
|
40
|
+
<Domternal
|
|
41
|
+
extensions={[StarterKit, BubbleMenu]}
|
|
42
|
+
content="<p>Hello from React!</p>"
|
|
43
|
+
>
|
|
44
|
+
<Domternal.Toolbar />
|
|
45
|
+
<Domternal.Content />
|
|
46
|
+
<Domternal.BubbleMenu contexts={{ text: ['bold', 'italic', 'underline'] }} />
|
|
47
|
+
</Domternal>
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Need direct access to the editor instance? Use the `useEditor` hook and mount the view yourself:
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
import { useEditor, EditorProvider, DomternalToolbar } from '@domternal/react';
|
|
56
|
+
import { StarterKit } from '@domternal/core';
|
|
57
|
+
|
|
58
|
+
export default function Editor() {
|
|
59
|
+
const { editor, editorRef } = useEditor({
|
|
60
|
+
extensions: [StarterKit],
|
|
61
|
+
content: '<p>Hello</p>',
|
|
62
|
+
onUpdate: ({ editor }) => console.log(editor.getHTML()),
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
return (
|
|
66
|
+
<EditorProvider editor={editor}>
|
|
67
|
+
{editor && <DomternalToolbar />}
|
|
68
|
+
<div className="dm-editor">
|
|
69
|
+
<div ref={editorRef} />
|
|
70
|
+
</div>
|
|
71
|
+
</EditorProvider>
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Exports
|
|
77
|
+
|
|
78
|
+
- **Hooks**: `useEditor`, `useEditorState` (full state or a granular selector), `useCurrentEditor`
|
|
79
|
+
- **Constants**: `DEFAULT_EXTENSIONS`
|
|
80
|
+
- **Composable component**: `Domternal` with `Domternal.Toolbar`, `Domternal.Content`, `Domternal.BubbleMenu`,
|
|
81
|
+
`Domternal.FloatingMenu`, `Domternal.EmojiPicker`, `Domternal.Loading`
|
|
82
|
+
- **Components**: `DomternalEditor`, `EditorContent`, `DomternalToolbar`, `DomternalBubbleMenu`,
|
|
83
|
+
`DomternalFloatingMenu`, `DomternalEmojiPicker`, `DomternalNotionColorPicker`, `EditorProvider`
|
|
84
|
+
- **Node views**: `ReactNodeViewRenderer`, `NodeViewWrapper`, `NodeViewContent`, `useReactNodeView`
|
|
85
|
+
- **SSR helpers** (re-exported from core, work without an editor instance): `generateHTML`, `generateJSON`, `generateText`
|