@easy-cms/richtext 1.29.0 → 1.30.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/dist/index.d.ts CHANGED
@@ -14,9 +14,31 @@ type RichTextInput = RichTextNode | {
14
14
  readonly type: string;
15
15
  readonly content?: readonly unknown[];
16
16
  };
17
- interface RenderOptions {
17
+ /**
18
+ * A block between paragraphs (#328): `{ type: 'block', attrs: { blockType, id, fields } }` in the
19
+ * document. `RichTextBlocks<typeof config, 'posts', 'body'>` from `@easy-cms/core` types them.
20
+ */
21
+ interface BlockData {
22
+ readonly blockType: string;
23
+ readonly id: string;
24
+ readonly fields: Readonly<Record<string, unknown>>;
25
+ }
26
+ /**
27
+ * How each kind of block renders, by `blockType`: its fields (populated at `depth ≥ 1`) and the
28
+ * block. The result is used as is: escape text with `escapeHtml`. Blocks without one are left out.
29
+ */
30
+ type BlockRenderers<B extends BlockData = BlockData> = {
31
+ readonly [K in B['blockType']]?: (fields: Extract<B, {
32
+ blockType: K;
33
+ }>['fields'], block: Extract<B, {
34
+ blockType: K;
35
+ }>) => string;
36
+ };
37
+ interface RenderOptions<B extends BlockData = BlockData> {
18
38
  /** Override or add node renderers. Receives the node and its rendered children. */
19
39
  nodes?: Record<string, (node: RichTextNode, children: string) => string>;
40
+ /** Renderers of blocks between paragraphs, by `blockType`. */
41
+ blocks?: BlockRenderers<B>;
20
42
  /** Attributes added to every link. Default adds `rel="noopener noreferrer"` to external links. */
21
43
  linkAttributes?: (href: string) => Record<string, string>;
22
44
  }
@@ -25,18 +47,20 @@ declare function escapeHtml(text: string): string;
25
47
  /** Allows http(s), mailto, tel, relative URLs and fragments. Everything else (javascript:, data:, …) is dropped. */
26
48
  declare function safeUrl(value: unknown): string | undefined;
27
49
  /** Renders a rich text document to HTML. Text is escaped and unsafe URLs are removed. */
28
- declare function renderRichText(doc: RichTextInput | null | undefined, options?: RenderOptions): string;
50
+ declare function renderRichText<B extends BlockData = BlockData>(doc: RichTextInput | null | undefined, options?: RenderOptions<B>): string;
29
51
  /** Plain text of a document, e.g. for excerpts or search. Blocks are separated by newlines. */
30
52
  declare function richTextToPlainText(doc: RichTextInput | null | undefined): string;
31
- interface MarkdownOptions {
53
+ interface MarkdownOptions<B extends BlockData = BlockData> {
32
54
  /** Override or add node renderers. Receives the node and its rendered children. */
33
55
  nodes?: Record<string, (node: RichTextNode, children: string) => string>;
56
+ /** Markdown of blocks between paragraphs, by `blockType`; blocks without one are left out. */
57
+ blocks?: BlockRenderers<B>;
34
58
  }
35
59
  /**
36
60
  * Renders a rich text document to Markdown, e.g. for `llms.txt` or `.md` versions of pages.
37
61
  * Text that looks like Markdown is escaped, and unsafe URLs are removed.
38
62
  */
39
- declare function renderMarkdown(doc: RichTextInput | null | undefined, options?: MarkdownOptions): string;
63
+ declare function renderMarkdown<B extends BlockData = BlockData>(doc: RichTextInput | null | undefined, options?: MarkdownOptions<B>): string;
40
64
 
41
65
  export { escapeHtml, renderMarkdown, renderRichText, richTextToPlainText, safeUrl };
42
- export type { MarkdownOptions, RenderOptions, RichTextInput, RichTextNode };
66
+ export type { BlockData, BlockRenderers, MarkdownOptions, RenderOptions, RichTextInput, RichTextNode };
package/dist/index.js CHANGED
@@ -52,9 +52,25 @@ function renderMarks(text, marks, options) {
52
52
  }
53
53
  return html;
54
54
  }
55
+ function blockData(node) {
56
+ const attrs = node.attrs ?? {};
57
+ if (typeof attrs.blockType !== "string") return void 0;
58
+ const fields = attrs.fields;
59
+ return {
60
+ blockType: attrs.blockType,
61
+ id: typeof attrs.id === "string" ? attrs.id : "",
62
+ fields: fields && typeof fields === "object" && !Array.isArray(fields) ? fields : {}
63
+ };
64
+ }
65
+ function renderBlock(node, blocks) {
66
+ const block = blockData(node);
67
+ const render = block ? blocks?.[block.blockType] : void 0;
68
+ return block && render ? render(block.fields, block) : "";
69
+ }
55
70
  function renderNode(node, options) {
56
71
  if (!node || typeof node !== "object") return "";
57
72
  if (node.type === "text") return renderMarks(String(node.text ?? ""), node.marks, options);
73
+ if (node.type === "block") return renderBlock(node, options.blocks);
58
74
  const children = (Array.isArray(node.content) ? node.content : []).map((c) => renderNode(c, options)).join("");
59
75
  const custom = options.nodes?.[node.type];
60
76
  if (custom) return custom(node, children);
@@ -126,6 +142,23 @@ function renderRichText(doc, options = {}) {
126
142
  if (!doc) return "";
127
143
  return renderNode(doc, options);
128
144
  }
145
+ function blockText(node) {
146
+ const out = [];
147
+ const walk = (value, depth) => {
148
+ if (depth > 10) return;
149
+ if (typeof value === "string") {
150
+ if (value.trim() !== "") out.push(value);
151
+ } else if (Array.isArray(value)) {
152
+ for (const item of value) walk(item, depth + 1);
153
+ } else if (value && typeof value === "object") {
154
+ const object = value;
155
+ if ("relationTo" in object || "createdAt" in object) return;
156
+ for (const [key, inner] of Object.entries(object)) if (key !== "id") walk(inner, depth + 1);
157
+ }
158
+ };
159
+ walk(blockData(node)?.fields, 0);
160
+ return out.join("\n");
161
+ }
129
162
  function richTextToPlainText(doc) {
130
163
  if (!doc) return "";
131
164
  const blocks = /* @__PURE__ */ new Set([
@@ -140,6 +173,8 @@ function richTextToPlainText(doc) {
140
173
  const walk = (node) => {
141
174
  if (node.type === "text") return String(node.text ?? "");
142
175
  if (node.type === "hardBreak") return "\n";
176
+ if (node.type === "block") return `${blockText(node)}
177
+ `;
143
178
  const inner = (node.content ?? []).map(walk).join("");
144
179
  return blocks.has(node.type) ? `${inner}
145
180
  ` : inner;
@@ -187,6 +222,7 @@ ${by}`);
187
222
  function markdownNode(node, options) {
188
223
  if (!node || typeof node !== "object") return "";
189
224
  if (node.type === "text") return markdownMarks(String(node.text ?? ""), node.marks);
225
+ if (node.type === "block") return renderBlock(node, options.blocks);
190
226
  const content = Array.isArray(node.content) ? node.content : [];
191
227
  const inline = () => content.map((c) => markdownNode(c, options)).join("");
192
228
  const blocks = () => content.map((c) => markdownNode(c, options)).filter((b) => b.trim() !== "").join("\n\n");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@easy-cms/richtext",
3
- "version": "1.29.0",
3
+ "version": "1.30.0",
4
4
  "description": "Render Easy CMS rich text (Tiptap JSON) to safe HTML",
5
5
  "license": "MIT",
6
6
  "type": "module",