@domternal/core 0.15.0 → 1.0.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.
Files changed (9) hide show
  1. package/README.md +48 -6
  2. package/THIRD-PARTY-LICENSES.md +16 -0
  3. package/dist/index.cjs +578 -221
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +488 -225
  6. package/dist/index.d.ts +488 -225
  7. package/dist/index.js +567 -222
  8. package/dist/index.js.map +1 -1
  9. package/package.json +5 -5
package/README.md CHANGED
@@ -21,13 +21,29 @@ Every export is tree-shakeable, so unused extensions are stripped from your bund
21
21
  pnpm add @domternal/core
22
22
  ```
23
23
 
24
- `linkedom` is an optional peer dependency: install it only if you call the SSR
25
- helpers (`generateHTML`, `generateJSON`, `generateText`) outside a browser.
24
+ `linkedom` is an optional peer dependency: install it only if you call `generateHTML` or
25
+ `generateJSON` outside a browser. `generateText` reads the document model and never touches
26
+ the DOM, so it runs anywhere without it.
26
27
 
27
28
  ```bash
28
29
  pnpm add linkedom
29
30
  ```
30
31
 
32
+ ### One copy of the core, and of ProseMirror
33
+
34
+ ProseMirror compares classes by identity, and so does this package. Two copies of
35
+ `@domternal/core` give two `Extension` base classes, two schemas and two `Gapcursor`s
36
+ under a single plugin key; two copies of `prosemirror-model` make `Fragment.from` reject a
37
+ fragment the editor itself produced. Neither is a size problem, and nothing warns at
38
+ install time.
39
+
40
+ The core detects both at runtime. Building an editor beside a second copy of
41
+ `prosemirror-model`, `prosemirror-state`, `prosemirror-view`, `prosemirror-transform` or of
42
+ `@domternal/core` itself warns on the console, naming both packages and the fix. Handing an
43
+ editor an extension that another copy of the core built throws, because that can never
44
+ work. The dedupe recipe per package manager and bundler:
45
+ https://domternal.dev/v1/guides/single-prosemirror-copy/
46
+
31
47
  ## Usage
32
48
 
33
49
  ```ts
@@ -56,13 +72,16 @@ editor.destroy();
56
72
  The engine ships no styles. Import [`@domternal/theme`](https://www.npmjs.com/package/@domternal/theme) for ready-made light/dark editor styling, or supply your own CSS.
57
73
 
58
74
  `StarterKit` bundles the common nodes, marks, and behaviors; each entry can be
59
- configured or disabled individually.
75
+ configured or disabled individually. Every entry is on by default except `listIndent`,
76
+ which ships off because its Tab keymap also captures Tab on a paragraph that merely
77
+ follows a list. Pass `true` to switch it on.
60
78
 
61
79
  ```ts
62
80
  StarterKit.configure({
63
81
  codeBlock: false, // disable an extension
64
82
  heading: { levels: [1, 2, 3] }, // configure an extension
65
83
  link: { openOnClick: false },
84
+ listIndent: true, // opt in: Tab indents a block under the previous list
66
85
  });
67
86
  ```
68
87
 
@@ -116,8 +135,18 @@ editor.commands.printDocument();
116
135
 
117
136
  The hiding itself is CSS, and it lives in
118
137
  [`@domternal/theme`](https://www.npmjs.com/package/@domternal/theme), whose paper layer also
119
- applies to the reader's own Ctrl/Cmd+P with no code involved. Set `isolateNativePrint: true` to
120
- give that shortcut the same isolation as the command.
138
+ applies to the reader's own Ctrl/Cmd+P with no code involved.
139
+
140
+ Adding `Print` also registers a printer toolbar button, which stays live in a read-only
141
+ editor, and binds `Mod-P` to `printDocument` while the caret is in the editor.
142
+
143
+ `Print.configure({ ... })` accepts:
144
+
145
+ - `toolbar` (default `true`) - show the toolbar button
146
+ - `root` (default `null`) - `(editor) => HTMLElement | null` choosing what to print; unset
147
+ prints the editor's `.dm-editor` wrapper, falling back to the ProseMirror element
148
+ - `isolateNativePrint` (default `false`) - give the reader's own Ctrl/Cmd+P the same
149
+ isolation as the command
121
150
 
122
151
  ## SSR
123
152
 
@@ -133,4 +162,17 @@ const html = generateHTML(
133
162
  );
134
163
  ```
135
164
 
136
- `generateJSON(html, extensions)` does the reverse (HTML to doc JSON) and `generateText` extracts plain text.
165
+ `generateJSON(html, extensions)` does the reverse (HTML to doc JSON), and
166
+ `generateText(content, extensions, options)` extracts plain text, separating blocks with a
167
+ blank line unless `blockSeparator` overrides it.
168
+
169
+ Outside a browser, `generateHTML` and `generateJSON` need a DOM and load `linkedom` through
170
+ `require`, which only resolves under CommonJS. From an ES module server, installing
171
+ `linkedom` is not enough: pass the document yourself.
172
+
173
+ ```ts
174
+ import { parseHTML } from 'linkedom';
175
+
176
+ const { document } = parseHTML('<!DOCTYPE html><html><body></body></html>');
177
+ const html = generateHTML(content, [StarterKit], { document });
178
+ ```
package/THIRD-PARTY-LICENSES.md ADDED
@@ -0,0 +1,16 @@
1
+ # Third-party licenses
2
+
3
+ The icons inlined in this package's source (`src/icons/phosphor.ts`,
4
+ shipped inside `dist/`) are from, or drawn after, Phosphor Icons
5
+ (https://github.com/phosphor-icons/core), Copyright (c) 2023 Phosphor
6
+ Icons, MIT License:
7
+
8
+ MIT License
9
+
10
+ Copyright (c) 2023 Phosphor Icons
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.