@qkix/better-blocks-react-renderer 0.18.0 → 0.18.1

package/README.md

@@ -9,10 +9,10 @@
   <a href="https://www.npmjs.com/package/@qkix/better-blocks-react-renderer">
     <img alt="npm downloads" src="https://img.shields.io/npm/dm/@qkix/better-blocks-react-renderer.svg" />
   </a>
-  <a href="https://github.com/qkix/strapi-plugin-better-blocks/blob/main/LICENSE">
+  <a href="https://github.com/qkix/strapi-plugins/blob/main/LICENSE">
     <img alt="license" src="https://img.shields.io/npm/l/@qkix/better-blocks-react-renderer.svg" />
   </a>
-  <a href="https://buymeacoffee.com/k11k">
+  <a href="https://buymeacoffee.com/qkix">
     <img alt="Buy Me a Coffee" src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-FFDD00?logo=buymeacoffee&logoColor=black" />
   </a>
 </p>
@@ -33,16 +33,17 @@
 6. [Supported Blocks](#supported-blocks)
 7. [Supported Modifiers](#supported-modifiers)
 8. [Custom Renderers](#custom-renderers)
-9. [TypeScript](#typescript)
-10. [Contributing](#contributing)
-11. [Support this project](#support-this-project)
-12. [License](#license)
+9. [Registered Block Types](#registered-block-types)
+10. [TypeScript](#typescript)
+11. [Contributing](#contributing)
+12. [Support this project](#support-this-project)
+13. [License](#license)
 
 ---
 
 ## Why?
 
-The official [`@strapi/blocks-react-renderer`](https://github.com/strapi/blocks-react-renderer) doesn't support the features that the [Better Blocks](https://github.com/qkix/strapi-plugin-better-blocks) plugin adds to the Strapi editor &mdash; color marks, text alignment, to-do lists, tables, media embeds, and more.
+The official [`@strapi/blocks-react-renderer`](https://github.com/strapi/blocks-react-renderer) doesn't support the features that the [Better Blocks](https://github.com/qkix/strapi-plugins) plugin adds to the Strapi editor &mdash; color marks, text alignment, to-do lists, tables, media embeds, and more.
 
 This package is a **drop-in replacement** that renders all Better Blocks features out of the box &mdash; no configuration needed.
 
@@ -333,7 +334,7 @@ The markup is wrapped in a `<figure className="bb-embed align-{alignment}">` (al
 
 > **Trust boundary.** `embedHtml` is injected with `dangerouslySetInnerHTML`. The plugin sanitizes it at author time &mdash; the iframe is rebuilt from an attribute allowlist over an **https-only** `src`, with scripts, event handlers, inline styles and unknown attributes stripped, and `allow` filtered to a safe permission set &mdash; so treat your CMS content as trusted. If you accept `embed` blocks from untrusted authors, sanitize on the server before storing, or override the block (below) and render the parsed parts instead of the HTML.
 
-Consumers need to allow the embed hosts in their `frame-src` (and `img-src` for thumbnails) CSP directives &mdash; see the [plugin README](https://github.com/qkix/strapi-plugin-better-blocks#embed-json-shape-for-frontend-renderers) for the host list.
+Consumers need to allow the embed hosts in their `frame-src` (and `img-src` for thumbnails) CSP directives &mdash; see the [plugin README](https://github.com/qkix/strapi-plugins#embed-json-shape-for-frontend-renderers) for the host list.
 
 Baseline appearance ships as inline styles plus one small stylesheet (injected only when a default embed renders, since inline styles can't reach into injected markup). Every element carries a stable `bb-embed*` class:
 
@@ -540,7 +541,7 @@ Cell `children` go through the same inline renderer as paragraphs, so marks (`bo
 
 These three blocks ship with GitHub-flavored defaults out of the box &mdash; no stylesheet to import. Each carries a stable `bb-*` class, and the styles are injected as a `<style>` tag only when the block actually appears in the content (and skipped entirely when you override the block). Everything is rethemable through CSS custom properties, so you can restyle without replacing any markup.
 
-The same classes and custom properties are used by the [Astro renderer](https://github.com/qkix/strapi-plugin-better-blocks/tree/main/packages/better-blocks-astro-renderer), so one shared theme covers both.
+The same classes and custom properties are used by the [Astro renderer](https://github.com/qkix/strapi-plugins/tree/main/packages/better-blocks-astro-renderer), so one shared theme covers both.
 
 | Block   | Default element                 | Custom properties                                                                        |
 | ------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
@@ -849,6 +850,42 @@ Override any text modifier with your own component:
 />
 ```
 
+## Registered Block Types
+
+`blocks` overrides how a **known** block is drawn. `blockPlugins` adds a block
+type this renderer has never heard of — one owned by another package, such as a
+chart.
+
+```tsx
+import { BlocksRenderer } from '@qkix/better-blocks-react-renderer';
+import type { BlockPlugin } from '@qkix/better-blocks-react-renderer';
+
+const chart: BlockPlugin = {
+  type: 'chart',
+  // 'void' (attributes only, the default), 'inline' (text), or 'blocks' (nested blocks).
+  content: 'void',
+  component: ({ node }) => <MyChart spec={node.spec} />,
+};
+
+<BlocksRenderer content={content} blockPlugins={[chart]} />;
+```
+
+The component receives the whole `node` — this renderer does not know what
+attributes the block has, which is the point — and, when the content model is
+`inline` or `blocks`, its rendered `children`. A registered block works at any
+depth, including inside a callout or a details.
+
+A `BlockPlugin` is a core `BlockDefinition` plus `component`, so the same object
+that teaches `validateDocument` and `migrateDocument` about the block also
+teaches this renderer to draw it. See
+[`@qkix/better-blocks-core`](../better-blocks-core#registering-a-block-type).
+
+Passing plugins explicitly, rather than registering them into a global, is
+deliberate: this renderer runs on servers handling concurrent requests, where
+mutable module state leaks one page's registrations into another's.
+
+A block type nobody registered renders nothing, exactly as before.
+
 ## TypeScript
 
 All types are exported:
@@ -902,12 +939,12 @@ import type {
 ## Contributing
 
 Contributions are welcome! This package lives in the
-[strapi-plugin-better-blocks](https://github.com/qkix/strapi-plugin-better-blocks)
+[strapi-plugin-better-blocks](https://github.com/qkix/strapi-plugins)
 monorepo, next to the Strapi plugin and the Astro renderer. The easiest way to
 get started is with Docker:
 
 ```bash
-git clone https://github.com/qkix/strapi-plugin-better-blocks.git
+git clone https://github.com/qkix/strapi-plugins.git
 cd strapi-plugin-better-blocks
 
 docker compose up --build
@@ -948,13 +985,13 @@ pnpm --filter @qkix/better-blocks-react-renderer test   # just this one
 
 ## Community & Support
 
-- [GitHub Issues](https://github.com/qkix/strapi-plugin-better-blocks/issues) &mdash; Bug reports and feature requests
+- [GitHub Issues](https://github.com/qkix/strapi-plugins/issues) &mdash; Bug reports and feature requests
 
 ## Support this project
 
 This package is built and maintained in my free time, and it's free for everyone. If it has saved you time on a project, you can help keep it caffeinated and actively developed:
 
-<a href="https://buymeacoffee.com/k11k">
+<a href="https://buymeacoffee.com/qkix">
   <img alt="Buy Me a Coffee" src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-FFDD00?logo=buymeacoffee&logoColor=black&style=for-the-badge" />
 </a>
 
@@ -962,7 +999,7 @@ Every coffee goes toward fixing bugs, reviewing PRs, writing docs, and shipping
 
 ## Related
 
-- [@qkix/strapi-plugin-better-blocks](https://github.com/qkix/strapi-plugin-better-blocks) &mdash; Strapi plugin that extends the Blocks editor with colors, tables, to-do lists, media embeds, and more
+- [@qkix/strapi-plugin-better-blocks](https://github.com/qkix/strapi-plugins) &mdash; Strapi plugin that extends the Blocks editor with colors, tables, to-do lists, media embeds, and more
 - [@strapi/blocks-react-renderer](https://github.com/strapi/blocks-react-renderer) &mdash; Official Strapi renderer (standard blocks only)
 
 ## License

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType, CSSProperties } from 'react';
-import { BlocksContent, TableCellAlign, CalloutVariant, ButtonAlignment, ButtonLink, ButtonFile, ButtonStyle, SocialPlatform, SocialEmbedOembed, SocialEmbedAlignment, AudioFile, AudioPlayer, AudioAlignment, EmbedProvider, AspectRatio, MediaAlignment, VideoProvider, VideoFile, VideoPlayer } from '@qkix/better-blocks-core';
+import { BlocksContent, ExtendedBlocksContent, TableCellAlign, CalloutVariant, ButtonAlignment, ButtonLink, ButtonFile, ButtonStyle, SocialPlatform, SocialEmbedOembed, SocialEmbedAlignment, AudioFile, AudioPlayer, AudioAlignment, EmbedProvider, AspectRatio, MediaAlignment, VideoProvider, VideoFile, VideoPlayer, BlockDefinition, CustomBlockNode } from '@qkix/better-blocks-core';
 export { AspectRatio, AudioAlignment, AudioFile, AudioNode, AudioPlayer, AudioPreload, BlockNode, BlocksContent, ButtonAlignment, ButtonElement, ButtonFile, ButtonLink, ButtonStyle, CalloutNode, CalloutVariant, CodeNode, DetailsNode, DiagramNode, EmbedNode, EmbedProvider, HeadingNode, HorizontalLineNode, ImageNode, InlineNode, LinkNode, ListItemNode, ListNode, MathNode, MediaAlignment, MediaEmbedNode, ParagraphNode, QuoteNode, SocialEmbedAlignment, SocialEmbedNode, SocialEmbedOembed, SocialPlatform, TableCellAlign, TableCellNode, TableHeaderCellNode, TableNode, TableRowNode, TextAlign, TextNode, VideoFile, VideoNode, VideoPlayer, VideoProvider } from '@qkix/better-blocks-core';
 
 type ModifierProps = {
@@ -166,10 +166,44 @@ type CustomModifiersConfig = Partial<{
     fontFamily: ComponentType<FontFamilyModifierProps>;
     fontSize: ComponentType<FontSizeModifierProps>;
 }>;
+/**
+ * Props handed to a registered block's component.
+ *
+ * The whole node is passed rather than spread attributes, because this renderer
+ * does not know what attributes the block has — that is the point of it being
+ * registered elsewhere.
+ */
+type CustomBlockProps = {
+    node: CustomBlockNode;
+    /**
+     * The rendered children, for a block whose content model is `inline` or
+     * `blocks`. Undefined for a `void` block, whose children are only the empty
+     * placeholder Slate requires.
+     */
+    children?: ReactNode;
+};
+/**
+ * A block type from another package, plus how React draws it.
+ *
+ * Extends the core {@link BlockDefinition} so one object serves validation,
+ * migration and rendering: a package publishes its definition once and adds
+ * `component` here.
+ */
+type BlockPlugin = BlockDefinition & {
+    component: ComponentType<CustomBlockProps>;
+};
 type BlocksRendererProps = {
-    content: BlocksContent;
+    content: BlocksContent | ExtendedBlocksContent;
     blocks?: CustomBlocksConfig;
     modifiers?: CustomModifiersConfig;
+    /**
+     * Block types this renderer does not ship, supplied by another package.
+     * Passed explicitly rather than read from a global, so a server rendering
+     * concurrent requests cannot leak one page's registrations into another's.
+     *
+     * An unregistered block type renders nothing, exactly as before.
+     */
+    blockPlugins?: readonly BlockPlugin[];
     /**
      * Shiki theme for the default `code` block highlighting. Any bundled Shiki
      * theme name (e.g. `github-dark`, `github-light`, `dracula`, `nord`).
@@ -184,6 +218,6 @@ type BlocksRendererProps = {
     codeCopyButton?: boolean;
 };
 
-declare function BlocksRenderer({ content, blocks, modifiers, codeTheme, codeCopyButton, }: BlocksRendererProps): ReactNode;
+declare function BlocksRenderer({ content, blocks, modifiers, blockPlugins, codeTheme, codeCopyButton, }: BlocksRendererProps): ReactNode;
 
 export { type BackgroundColorModifierProps, type BlockComponentProps, BlocksRenderer, type BlocksRendererProps, type ColorModifierProps, type CustomBlocksConfig, type CustomModifiersConfig, type FontFamilyModifierProps, type FontSizeModifierProps, type ModifierProps, type TableCellRenderProps };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType, CSSProperties } from 'react';
-import { BlocksContent, TableCellAlign, CalloutVariant, ButtonAlignment, ButtonLink, ButtonFile, ButtonStyle, SocialPlatform, SocialEmbedOembed, SocialEmbedAlignment, AudioFile, AudioPlayer, AudioAlignment, EmbedProvider, AspectRatio, MediaAlignment, VideoProvider, VideoFile, VideoPlayer } from '@qkix/better-blocks-core';
+import { BlocksContent, ExtendedBlocksContent, TableCellAlign, CalloutVariant, ButtonAlignment, ButtonLink, ButtonFile, ButtonStyle, SocialPlatform, SocialEmbedOembed, SocialEmbedAlignment, AudioFile, AudioPlayer, AudioAlignment, EmbedProvider, AspectRatio, MediaAlignment, VideoProvider, VideoFile, VideoPlayer, BlockDefinition, CustomBlockNode } from '@qkix/better-blocks-core';
 export { AspectRatio, AudioAlignment, AudioFile, AudioNode, AudioPlayer, AudioPreload, BlockNode, BlocksContent, ButtonAlignment, ButtonElement, ButtonFile, ButtonLink, ButtonStyle, CalloutNode, CalloutVariant, CodeNode, DetailsNode, DiagramNode, EmbedNode, EmbedProvider, HeadingNode, HorizontalLineNode, ImageNode, InlineNode, LinkNode, ListItemNode, ListNode, MathNode, MediaAlignment, MediaEmbedNode, ParagraphNode, QuoteNode, SocialEmbedAlignment, SocialEmbedNode, SocialEmbedOembed, SocialPlatform, TableCellAlign, TableCellNode, TableHeaderCellNode, TableNode, TableRowNode, TextAlign, TextNode, VideoFile, VideoNode, VideoPlayer, VideoProvider } from '@qkix/better-blocks-core';
 
 type ModifierProps = {
@@ -166,10 +166,44 @@ type CustomModifiersConfig = Partial<{
     fontFamily: ComponentType<FontFamilyModifierProps>;
     fontSize: ComponentType<FontSizeModifierProps>;
 }>;
+/**
+ * Props handed to a registered block's component.
+ *
+ * The whole node is passed rather than spread attributes, because this renderer
+ * does not know what attributes the block has — that is the point of it being
+ * registered elsewhere.
+ */
+type CustomBlockProps = {
+    node: CustomBlockNode;
+    /**
+     * The rendered children, for a block whose content model is `inline` or
+     * `blocks`. Undefined for a `void` block, whose children are only the empty
+     * placeholder Slate requires.
+     */
+    children?: ReactNode;
+};
+/**
+ * A block type from another package, plus how React draws it.
+ *
+ * Extends the core {@link BlockDefinition} so one object serves validation,
+ * migration and rendering: a package publishes its definition once and adds
+ * `component` here.
+ */
+type BlockPlugin = BlockDefinition & {
+    component: ComponentType<CustomBlockProps>;
+};
 type BlocksRendererProps = {
-    content: BlocksContent;
+    content: BlocksContent | ExtendedBlocksContent;
     blocks?: CustomBlocksConfig;
     modifiers?: CustomModifiersConfig;
+    /**
+     * Block types this renderer does not ship, supplied by another package.
+     * Passed explicitly rather than read from a global, so a server rendering
+     * concurrent requests cannot leak one page's registrations into another's.
+     *
+     * An unregistered block type renders nothing, exactly as before.
+     */
+    blockPlugins?: readonly BlockPlugin[];
     /**
      * Shiki theme for the default `code` block highlighting. Any bundled Shiki
      * theme name (e.g. `github-dark`, `github-light`, `dracula`, `nord`).
@@ -184,6 +218,6 @@ type BlocksRendererProps = {
     codeCopyButton?: boolean;
 };
 
-declare function BlocksRenderer({ content, blocks, modifiers, codeTheme, codeCopyButton, }: BlocksRendererProps): ReactNode;
+declare function BlocksRenderer({ content, blocks, modifiers, blockPlugins, codeTheme, codeCopyButton, }: BlocksRendererProps): ReactNode;
 
 export { type BackgroundColorModifierProps, type BlockComponentProps, BlocksRenderer, type BlocksRendererProps, type ColorModifierProps, type CustomBlocksConfig, type CustomModifiersConfig, type FontFamilyModifierProps, type FontSizeModifierProps, type ModifierProps, type TableCellRenderProps };

package/dist/index.js

@@ -642,44 +642,63 @@ function renderTable(block, key, blocks, modifiers) {
 function isHeaderRow(row) {
   return !!row && row.children.length > 0 && row.children.every((c) => c.type === "table-header-cell");
 }
+function renderCustomBlock(plugin, block, key, blocks, modifiers, options) {
+  const { component: Component, content = "void" } = plugin;
+  const children = Array.isArray(block.children) ? block.children : [];
+  if (content === "blocks") {
+    return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Component, { node: block, children: children.map(
+      (child, index) => renderBlock(child, index, blocks, modifiers, options)
+    ) }, key);
+  }
+  if (content === "inline") {
+    return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Component, { node: block, children: renderInlineContent(children, blocks, modifiers) }, key);
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Component, { node: block }, key);
+}
 function renderBlock(block, key, blocks, modifiers, options) {
-  switch (block.type) {
+  var _a;
+  const plugin = (_a = options == null ? void 0 : options.plugins) == null ? void 0 : _a.get(block.type);
+  if (plugin) {
+    return renderCustomBlock(plugin, block, key, blocks, modifiers, options);
+  }
+  const builtIn = block;
+  switch (builtIn.type) {
     case "paragraph":
-      return renderParagraph(block, key, blocks, modifiers);
+      return renderParagraph(builtIn, key, blocks, modifiers);
     case "heading":
-      return renderHeading(block, key, blocks, modifiers);
+      return renderHeading(builtIn, key, blocks, modifiers);
     case "list":
-      return renderList(block, key, blocks, modifiers);
+      return renderList(builtIn, key, blocks, modifiers);
     case "quote":
-      return renderQuote(block, key, blocks, modifiers);
+      return renderQuote(builtIn, key, blocks, modifiers);
     case "code":
-      return renderCode(block, key, blocks, options);
+      return renderCode(builtIn, key, blocks, options);
     case "image":
-      return renderImage(block, key, blocks);
+      return renderImage(builtIn, key, blocks);
     case "horizontal-line":
-      return renderHorizontalLine(block, key, blocks);
+      return renderHorizontalLine(builtIn, key, blocks);
     case "table":
-      return renderTable(block, key, blocks, modifiers);
+      return renderTable(builtIn, key, blocks, modifiers);
     case "media-embed":
-      return renderMediaEmbed(block, key, blocks);
+      return renderMediaEmbed(builtIn, key, blocks);
     case "embed":
-      return renderEmbed(block, key, blocks);
+      return renderEmbed(builtIn, key, blocks);
     case "video":
-      return renderVideo(block, key, blocks);
+      return renderVideo(builtIn, key, blocks);
     case "math":
-      return renderMath(block, key, blocks);
+      return renderMath(builtIn, key, blocks);
     case "diagram":
-      return renderDiagram(block, key, blocks);
+      return renderDiagram(builtIn, key, blocks);
     case "callout":
-      return renderCallout(block, key, blocks, modifiers, options);
+      return renderCallout(builtIn, key, blocks, modifiers, options);
     case "details":
-      return renderDetails(block, key, blocks, modifiers, options);
+      return renderDetails(builtIn, key, blocks, modifiers, options);
     case "button":
-      return renderButton(block, key, blocks);
+      return renderButton(builtIn, key, blocks);
     case "social-embed":
-      return renderSocialEmbed(block, key, blocks);
+      return renderSocialEmbed(builtIn, key, blocks);
     case "audio":
-      return renderAudio(block, key, blocks);
+      return renderAudio(builtIn, key, blocks);
     default:
       return null;
   }
@@ -1260,6 +1279,7 @@ function BlocksRenderer({
   content,
   blocks,
   modifiers,
+  blockPlugins,
   codeTheme = DEFAULT_CODE_THEME,
   codeCopyButton = false
 }) {
@@ -1271,7 +1291,11 @@ function BlocksRenderer({
   const needsTableCss = !(blocks == null ? void 0 : blocks.table) && contentHasBlock(content, "table");
   const needsQuoteCss = !(blocks == null ? void 0 : blocks.quote) && contentHasBlock(content, "quote");
   const needsCodeCss = !(blocks == null ? void 0 : blocks.code) && contentHasBlock(content, "code");
-  const options = { codeTheme, codeCopyButton };
+  const options = {
+    codeTheme,
+    codeCopyButton,
+    plugins: (blockPlugins == null ? void 0 : blockPlugins.length) ? new Map(blockPlugins.map((plugin) => [plugin.type, plugin])) : void 0
+  };
   return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
     needsButtonCss && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("style", { children: BUTTON_HOVER_CSS }),
     needsEmbedCss && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("style", { children: EMBED_FRAME_CSS }),