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

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)
 
 ---
 
@@ -93,13 +94,13 @@
 - **To-do Lists** &mdash; Checkbox list items with click-to-toggle and strikethrough on checked items
 - **Tables** &mdash; Insert tables with header row, add/remove rows and columns via hover toolbar
 - **Embeds (generic iframe / URL)** &mdash; Insert any third-party embed from the `+` Insert menu, the `/embed` slash command, or the toolbar's media button. Two modes: **URL** (YouTube, Vimeo, Loom, Wistia, Dailymotion and api.video are converted to an iframe automatically) and **Embed code** (paste any platform's `<iframe>` snippet). The pasted markup is never stored verbatim &mdash; the iframe is _rebuilt_ from an attribute allowlist over an https-only `src`, so scripts, event handlers and unknown attributes cannot survive into your frontend. Live preview in the editor, plus aspect ratio (16:9 / 21:9 / 4:3 / 1:1 / custom), alignment, caption and an accessible title. Supersedes the older YouTube/Vimeo-only **media embed** block, which still renders existing content but is no longer inserted
-- **Video (provider-aware)** &mdash; Insert a video from the `+` Insert menu or the `/video` slash command. Source it from the **Media Library**, a **direct URL**, or a hosting provider &mdash; Mux, api.video and Cloudinary URLs are detected automatically, and a bare **Mux playback ID** fills in the stream URL and poster frame for you. When [`strapi-plugin-mux-video-uploader`](https://github.com/muxinc/strapi-plugin-mux-video-uploader) is installed and configured, a **Mux** button lists and searches your Mux assets inline with thumbnails. Set a poster image, title, caption, WebVTT captions/transcript, alignment, aspect ratio, and player behaviour (controls, autoplay, muted, loop)
+- **Video (provider-aware)** &mdash; Insert a video from the `+` Insert menu or the `/video` slash command. Source it from the **Media Library**, a **direct URL**, or a hosting provider &mdash; Mux, api.video and Cloudinary URLs are detected automatically, and a bare **Mux playback ID** fills in the stream URL and poster frame for you. When [`strapi-plugin-mux-video-uploader`](https://github.com/muxinc/strapi-plugin-mux-video-uploader) is installed and configured, a **Mux** button lists and searches your Mux assets inline with thumbnails. Set a poster image, title, caption, WebVTT captions/transcript, alignment, aspect ratio, and player behavior (controls, autoplay, muted, loop)
 - **Math (LaTeX / KaTeX)** &mdash; Inline and block math rendered with KaTeX; insert from the toolbar, the `/math` slash command, the blocks selector, or by typing `$$ ` (block) / `$…$ ` (inline), then edit in a full-screen modal with a side-by-side source editor and live preview. Block math supports multi-line equations via `\\` and LaTeX environments such as `aligned` and `cases`
 - **Diagrams (Mermaid)** &mdash; Block-level [Mermaid](https://mermaid.js.org/) diagrams (flowcharts, sequence, class, state, ER, pie, and more) rendered to SVG; insert from the blocks selector, the `/mermaid` slash command, or by typing ` ```mermaid ` then a space, then edit the definition in a full-screen modal with live preview and zoom controls. Theme follows Strapi's light/dark mode
 - **Callouts / Admonitions** &mdash; GitHub-style callouts in five variants (`Note`, `Tip`, `Important`, `Warning`, `Caution`) with an optional custom title and nested rich-text content (paragraphs, lists, links). Insert from the blocks selector or the `/note`, `/tip`, `/important`, `/warning`, `/caution` slash commands; switch variant, edit the title, or remove from the header popover. Colors follow Strapi's design tokens and adapt to light/dark mode
 - **Details / Collapsible** &mdash; GitHub-style collapsible `<details>` / `<summary>` sections for managing content density. Insert from the blocks selector or the `/details` slash command; edit the summary label and toggle open/closed-by-default (`defaultOpen`) from the header. Holds full rich-text block content (paragraphs, lists, tables, images) and supports nesting. Admins can set the default summary text and choose a GitHub-minimal (default) or Custom (bordered + background) style. Stored as `{ "type": "details", "summary": "…", "defaultOpen": false, "children": [...] }`
 - **Button (WordPress-style CTA)** &mdash; Insert a styled call-to-action button from the blocks selector or by typing `[button]` then a space. Two modes: **Link** (URL + open-in-new-tab + ARIA label) and **File** (pick any asset from the Media Library to render a download button with optional file size and type icon, and choose direct download or preview-in-new-tab). A full-screen editor with live preview controls alignment, background/text colors (including hover colors), border radius, font size/weight, padding presets, border, and a custom CSS class. One-click **style presets** (Primary / Secondary / Outline / Filled) keep CTAs on-brand. Admins can set default button colors and customize the presets. Stored as `{ "type": "button", "buttonType": "link" | "file", "label": "…", "alignment": "center", "link": {…} | "file": {…}, "style": {…} }`
-- **Audio (HTML5 player)** &mdash; Insert an audio block from the `+` Insert menu, the `/audio` slash command, or by typing `[audio]` then a space. Pick a file from the Media Library (upload included) or paste a direct URL, with a live native `<audio>` preview in the editor. Set an optional title and caption, block alignment (left / center / right / none), and player behaviour: controls, autoplay, loop, and preload (none / metadata / auto). Stored as `{ "type": "audio", "file": {…}, "title": "…", "caption": "…", "player": {…}, "alignment": "center" }`
+- **Audio (HTML5 player)** &mdash; Insert an audio block from the `+` Insert menu, the `/audio` slash command, or by typing `[audio]` then a space. Pick a file from the Media Library (upload included) or paste a direct URL, with a live native `<audio>` preview in the editor. Set an optional title and caption, block alignment (left / center / right / none), and player behavior: controls, autoplay, loop, and preload (none / metadata / auto). Stored as `{ "type": "audio", "file": {…}, "title": "…", "caption": "…", "player": {…}, "alignment": "center" }`
 - **Horizontal Line** &mdash; Insert `<hr>` dividers between content blocks
 - **Text Alignment** &mdash; Per-block left, center, right, and justify alignment
 - **Undo / Redo** &mdash; Toolbar buttons wired to Slate's built-in history
@@ -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>