@qkix/strapi-plugin-better-blocks 0.23.0 → 0.23.1

package/README.md

@@ -9,10 +9,10 @@
   <a href="https://www.npmjs.com/package/@qkix/strapi-plugin-better-blocks">
     <img alt="npm downloads" src="https://img.shields.io/npm/dm/@qkix/strapi-plugin-better-blocks.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/strapi-plugin-better-blocks.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,8 +33,9 @@
 6. [Custom Color Presets](#custom-color-presets)
 7. [Media Embeds (CSP Configuration)](#media-embeds-csp-configuration)
 8. [Frontend Rendering](#frontend-rendering)
-9. [Contributing](#contributing)
-10. [License](#license)
+9. [Adding Your Own Block Type](#adding-your-own-block-type)
+10. [Contributing](#contributing)
+11. [License](#license)
 
 ---
 
@@ -358,7 +359,7 @@ loop={player.loop} preload={player.preload}>` wrapped in an alignment container
 map to `flex-start`/`center`/`flex-end`; `none` flows full-width). Include fallback text and a download
 link inside `<audio>` for unsupported browsers, and associate the `caption` via `aria-describedby`.
 `file.url` is already backend-prefixed for Media Library assets, and the `title`/`caption` keys are
-omitted when empty. See the full React/Astro renderer contract on [issue #43](https://github.com/qkix/strapi-plugin-better-blocks/issues/43).
+omitted when empty. See the full React/Astro renderer contract on [issue #43](https://github.com/qkix/strapi-plugins/issues/43).
 
 #### Embed JSON shape (for frontend renderers)
 
@@ -709,7 +710,7 @@ const MyComponent = ({ content }) => {
 
 The renderer supports all Better Blocks features including text colors, background highlights, images, and all standard block types.
 
-See the [@qkix/better-blocks-react-renderer](https://github.com/qkix/strapi-plugin-better-blocks/tree/main/packages/better-blocks-react-renderer) documentation for details.
+See the [@qkix/better-blocks-react-renderer](https://github.com/qkix/strapi-plugins/tree/main/packages/better-blocks-react-renderer) documentation for details.
 
 ## Requirements
 
@@ -717,6 +718,78 @@ See the [@qkix/better-blocks-react-renderer](https://github.com/qkix/strapi-plug
 - **Strapi** v5.x
 - **Slate** 0.94.1 (bundled with Strapi)
 
+## Adding Your Own Block Type
+
+Another Strapi plugin — or your own admin customization in
+`src/admin/app.tsx` — can add a block type to the editor. Call `registerBlock`
+from `register()`, which runs before any editor is mounted.
+
+```tsx
+import { registerBlock } from '@qkix/strapi-plugin-better-blocks/strapi-admin';
+import { Transforms } from 'slate';
+
+export default {
+  register() {
+    registerBlock({
+      type: 'key-figure',
+      // What it holds: 'void' (attributes only, the default), 'inline' (text),
+      // or 'blocks' (nested blocks). Slate's void handling follows from this.
+      content: 'void',
+
+      // Needed to be offered in the "+" Insert menu and the slash command. A
+      // block without all three still renders, it just is not offered.
+      icon: KeyFigureIcon,
+      label: 'Key figure',
+      insert: (editor) => {
+        Transforms.insertNodes(editor, {
+          type: 'key-figure',
+          value: '42',
+          // Slate refuses a document whose nodes are not elements, and an
+          // element is something with a children array. A void block saved
+          // without this placeholder takes the whole editor down.
+          children: [{ type: 'text', text: '' }],
+        });
+      },
+
+      renderElement: ({ attributes, children, element }) => (
+        <div {...attributes} contentEditable={false}>
+          {element.value}
+          {children}
+        </div>
+      ),
+    });
+  },
+};
+```
+
+Registering is the only supported way in. Editing this package to add a block is
+how the editor, both renderers and the validator ended up with four separate
+hardcoded lists of block types in the first place.
+
+`registerBlock` throws if the type shadows a built-in or is registered twice —
+either one would otherwise surface much later as a block that mysteriously does
+not appear.
+
+### The rest of the pipeline
+
+The same definition object is understood by the core and both renderers, so a
+package writes `type` and `content` once:
+
+| Where                                           | What it adds                                      |
+| ----------------------------------------------- | ------------------------------------------------- |
+| `registerBlock` here                            | the editor: rendering, Insert menu, slash command |
+| `validateDocument(doc, { blocks })` in the core | `validate`, so the block is not "unknown"         |
+| `migrateDocument(doc, { blocks })` in the core  | `migrate`, called for every node of the type      |
+| `blockPlugins` on either renderer               | `component`, so the front end draws it            |
+
+A renderer given no plugin for a type renders nothing for it — content authored
+with a registered block is not lost, it is simply not drawn until the front end
+knows about it too.
+
+See [`@qkix/better-blocks-core`](https://github.com/qkix/strapi-plugins/tree/main/packages/better-blocks-core#registering-a-block-type)
+for the definition shape, and `examples/strapi-app/src/admin/app.tsx` for a
+working registration.
+
 ## Contributing
 
 Contributions are welcome! This package lives in a monorepo together with the
@@ -724,7 +797,7 @@ React and Astro renderers. The easiest way to get started is with Docker:
 
 ```bash
 # Clone the repository
-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
@@ -777,14 +850,14 @@ pnpm test
 
 ## Community & Support
 
-- [GitHub Issues](https://github.com/qkix/strapi-plugin-better-blocks/issues) &mdash; Bug reports and feature requests
-- [GitHub Discussions](https://github.com/qkix/strapi-plugin-better-blocks/discussions) &mdash; Questions and ideas
+- [GitHub Issues](https://github.com/qkix/strapi-plugins/issues) &mdash; Bug reports and feature requests
+- [GitHub Discussions](https://github.com/qkix/strapi-plugins/discussions) &mdash; Questions and ideas
 
 ## Support this project
 
 This plugin 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>