@portabletext/block-tools 0.0.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.
Files changed (31) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -0
  3. package/lib/index.cjs +1056 -0
  4. package/lib/index.cjs.map +1 -0
  5. package/lib/index.d.cts +172 -0
  6. package/lib/index.d.ts +172 -0
  7. package/lib/index.js +1056 -0
  8. package/lib/index.js.map +1 -0
  9. package/package.json +71 -0
  10. package/src/HtmlDeserializer/helpers.ts +363 -0
  11. package/src/HtmlDeserializer/index.ts +313 -0
  12. package/src/HtmlDeserializer/preprocessors/gdocs.ts +86 -0
  13. package/src/HtmlDeserializer/preprocessors/html.ts +57 -0
  14. package/src/HtmlDeserializer/preprocessors/index.ts +13 -0
  15. package/src/HtmlDeserializer/preprocessors/notion.ts +25 -0
  16. package/src/HtmlDeserializer/preprocessors/whitespace.ts +31 -0
  17. package/src/HtmlDeserializer/preprocessors/word.ts +92 -0
  18. package/src/HtmlDeserializer/preprocessors/xpathResult.ts +13 -0
  19. package/src/HtmlDeserializer/rules/gdocs.ts +183 -0
  20. package/src/HtmlDeserializer/rules/html.ts +264 -0
  21. package/src/HtmlDeserializer/rules/index.ts +18 -0
  22. package/src/HtmlDeserializer/rules/notion.ts +60 -0
  23. package/src/HtmlDeserializer/rules/word.ts +59 -0
  24. package/src/constants.ts +104 -0
  25. package/src/index.ts +52 -0
  26. package/src/types.ts +139 -0
  27. package/src/util/blockContentTypeFeatures.ts +141 -0
  28. package/src/util/findBlockType.ts +13 -0
  29. package/src/util/normalizeBlock.ts +142 -0
  30. package/src/util/randomKey.ts +26 -0
  31. package/src/util/resolveJsType.ts +44 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2016 - 2024 Sanity.io
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,226 @@
1
+ # `@portabletext/block-tools`
2
+
3
+ > Various tools for processing Portable Text.
4
+
5
+ **NOTE:** To use `@portabletext/block-tools` in a Node.js script, you will need to provide a `parseHtml` method - generally using `JSDOM`. [Read more](#jsdom-example).
6
+
7
+ ## Example
8
+
9
+ Let's start with a complete example:
10
+
11
+ ```js
12
+ import {getBlockContentFeatures, htmlToBlocks} from '@portabletext/block-tools'
13
+ import {Schema} from '@sanity/schema'
14
+
15
+ // Start with compiling a schema we can work against
16
+ const defaultSchema = Schema.compile({
17
+ name: 'myBlog',
18
+ types: [
19
+ {
20
+ type: 'object',
21
+ name: 'blogPost',
22
+ fields: [
23
+ {
24
+ title: 'Title',
25
+ type: 'string',
26
+ name: 'title',
27
+ },
28
+ {
29
+ title: 'Body',
30
+ name: 'body',
31
+ type: 'array',
32
+ of: [{type: 'block'}],
33
+ },
34
+ ],
35
+ },
36
+ ],
37
+ })
38
+
39
+ // The compiled schema type for the content type that holds the block array
40
+ const blockContentType = defaultSchema
41
+ .get('blogPost')
42
+ .fields.find((field) => field.name === 'body').type
43
+
44
+ // Convert HTML to block array
45
+ const blocks = htmlToBlocks(
46
+ '<html><body><h1>Hello world!</h1><body></html>',
47
+ blockContentType,
48
+ )
49
+ // Outputs
50
+ //
51
+ // {
52
+ // _type: 'block',
53
+ // style: 'h1'
54
+ // children: [
55
+ // {
56
+ // _type: 'span'
57
+ // text: 'Hello world!'
58
+ // }
59
+ // ]
60
+ // }
61
+
62
+ // Get the feature-set of a blockContentType
63
+ const features = getBlockContentFeatures(blockContentType)
64
+ ```
65
+
66
+ ## Methods
67
+
68
+ ### `htmlToBlocks(html, blockContentType, options)` (html deserializer)
69
+
70
+ This will deserialize the input html (string) into blocks.
71
+
72
+ #### Params
73
+
74
+ ##### `html`
75
+
76
+ The stringified version of the HTML you are importing
77
+
78
+ ##### `blockContentType`
79
+
80
+ A compiled version of the block content schema type.
81
+
82
+ The deserializer will respect the schema when deserializing the HTML elements to blocks.
83
+
84
+ It only supports a subset of HTML tags. Any HTML tag not in the block-tools [whitelist](https://github.com/sanity-io/sanity/blob/243b4a5686a1293a8a977574a5cabc768ec01725/packages/%40sanity/block-tools/src/constants.ts#L24-L78) will be deserialized to normal blocks/spans.
85
+
86
+ For instance, if the schema doesn't allow H2 styles, all H2 HTML elements will be output like this:
87
+
88
+ ```js
89
+ {
90
+ _type: 'block',
91
+ style: 'normal'
92
+ children: [
93
+ {
94
+ _type: 'span'
95
+ text: 'Hello world!'
96
+ }
97
+ ]
98
+ }
99
+ ```
100
+
101
+ ##### `options` (optional)
102
+
103
+ ###### `parseHtml`
104
+
105
+ The HTML-deserialization is done by default by the browser's native DOMParser.
106
+ On the server side you can give the function `parseHtml`
107
+ that parses the html into a DOMParser compatible model / API.
108
+
109
+ ###### JSDOM example
110
+
111
+ ```js
112
+ const {JSDOM} = require('jsdom')
113
+ const {htmlToBlocks} = require('@portabletext/block-tools')
114
+
115
+ const blocks = htmlToBlocks(
116
+ '<html><body><h1>Hello world!</h1><body></html>',
117
+ blockContentType,
118
+ {
119
+ parseHtml: (html) => new JSDOM(html).window.document,
120
+ },
121
+ )
122
+ ```
123
+
124
+ ##### `rules`
125
+
126
+ You may add your own rules to deal with special HTML cases.
127
+
128
+ ```js
129
+ htmlToBlocks(
130
+ '<html><body><pre><code>const foo = "bar"</code></pre></body></html>',
131
+ blockContentType,
132
+ {
133
+ parseHtml: (html) => new JSDOM(html),
134
+ rules: [
135
+ // Special rule for code blocks
136
+ {
137
+ deserialize(el, next, block) {
138
+ if (el.tagName.toLowerCase() != 'pre') {
139
+ return undefined
140
+ }
141
+ const code = el.children[0]
142
+ const childNodes =
143
+ code && code.tagName.toLowerCase() === 'code'
144
+ ? code.childNodes
145
+ : el.childNodes
146
+ let text = ''
147
+ childNodes.forEach((node) => {
148
+ text += node.textContent
149
+ })
150
+ // Return this as an own block (via block helper function), instead of appending it to a default block's children
151
+ return block({
152
+ _type: 'code',
153
+ language: 'javascript',
154
+ text: text,
155
+ })
156
+ },
157
+ },
158
+ ],
159
+ },
160
+ )
161
+ ```
162
+
163
+ ### `normalizeBlock(block, [options={}])`
164
+
165
+ Normalize a block object structure to make sure it has what it needs.
166
+
167
+ ```js
168
+ import {normalizeBlock} from '@portabletext/block-tools'
169
+
170
+ const partialBlock = {
171
+ _type: 'block',
172
+ children: [
173
+ {
174
+ _type: 'span',
175
+ text: 'Foobar',
176
+ marks: ['strong', 'df324e2qwe'],
177
+ },
178
+ ],
179
+ }
180
+ normalizeBlock(partialBlock, {allowedDecorators: ['strong']})
181
+ ```
182
+
183
+ Will produce
184
+
185
+ ```
186
+ {
187
+ _key: 'randomKey0',
188
+ _type: 'block',
189
+ children: [
190
+ {
191
+ _key: 'randomKey00',
192
+ _type: 'span',
193
+ marks: ['strong'],
194
+ text: 'Foobar'
195
+ }
196
+ ],
197
+ markDefs: []
198
+ }
199
+ ```
200
+
201
+ ### `getBlockContentFeatures(blockContentType)`
202
+
203
+ Will return an object with the features enabled for the input block content type.
204
+
205
+ ```js
206
+ {
207
+ annotations: [{title: 'Link', value: 'link'}],
208
+ decorators: [
209
+ {title: 'Strong', value: 'strong'},
210
+ {title: 'Emphasis', value: 'em'},
211
+ {title: 'Code', value: 'code'},
212
+ {title: 'Underline', value: 'underline'},
213
+ {title: 'Strike', value: 'strike-through'}
214
+ ],
215
+ styles: [
216
+ {title: 'Normal', value: 'normal'},
217
+ {title: 'Heading 1', value: 'h1'},
218
+ {title: 'H2', value: 'h2'},
219
+ {title: 'H3', value: 'h3'},
220
+ {title: 'H4', value: 'h4'},
221
+ {title: 'H5', value: 'h5'},
222
+ {title: 'H6', value: 'h6'},
223
+ {title: 'Quote', value: 'blockquote'}
224
+ ]
225
+ }
226
+ ```