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

package/dist/admin/src/blockRegistry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * How another Strapi plugin adds a block type to the Better Blocks editor.
+ *
+ * Unlike the renderers, which take their registrations as a prop, the editor
+ * keeps a module-level registry. That is not an oversight: the Strapi admin is
+ * a single browser application whose plugins register once at boot, exactly
+ * like `app.customFields.register`. There is no second document being edited in
+ * another request to leak into.
+ *
+ * Registering is the *only* supported way in. Adding a block by editing this
+ * package is how the editor, both renderers and the validator ended up with
+ * four separate hardcoded lists of block types in the first place.
+ */
+/// <reference types="react" />
+import type { BlockDefinition } from '@qkix/better-blocks-core';
+import type { Editor } from 'slate';
+import type { MessageDescriptor } from 'react-intl';
+import type { RenderElementProps } from 'slate-react';
+import type { CSSProperties } from 'styled-components';
+/**
+ * A block type contributed by another package.
+ *
+ * Extends the core {@link BlockDefinition}, so a package writes `type` and
+ * `content` once and the same object teaches the validator, the migrator and
+ * both renderers about the block.
+ */
+export type EditorBlockDefinition = BlockDefinition & {
+    /** Draws the block inside the editor. Slate calls this with its element props. */
+    renderElement: (props: RenderElementProps) => React.JSX.Element;
+    /**
+     * Icon for the Insert menu and the slash command. Required to appear in
+     * either — a block with no icon is still rendered, just not offered.
+     */
+    icon?: React.ComponentType;
+    /** Menu label. A plain string is fine; a descriptor gets translated. */
+    label?: MessageDescriptor | string;
+    /**
+     * Inserts an empty block of this type at the selection. Required for the
+     * block to appear in the Insert menu or the slash command, since without it
+     * there is nothing for those to do.
+     */
+    insert?: (editor: Editor) => void;
+    /** Text that converts into this block as you type, e.g. '```mermaid'. */
+    snippets?: string[];
+    /**
+     * Anything `isVoid` cannot express — custom normalization, paste handling,
+     * key bindings. Applied when the editor is created.
+     */
+    withEditor?: (editor: Editor) => Editor;
+    /** Nudges the drag handle down, for blocks whose first line is not text. */
+    dragHandleTopMargin?: CSSProperties['marginTop'];
+};
+/**
+ * Adds a block type to the editor. Call from a Strapi plugin's `register()`.
+ *
+ * Throws on the two mistakes that would otherwise surface much later as a block
+ * that mysteriously does not appear: shadowing a built-in type, and registering
+ * the same type twice.
+ */
+export declare function registerBlock(definition: EditorBlockDefinition): void;
+/** Every registered block, in registration order. */
+export declare function getRegisteredBlocks(): EditorBlockDefinition[];
+/**
+ * Whether the block can be offered in the Insert menu and the slash command.
+ *
+ * All three are needed: something to draw, something to name it, and something
+ * to do when it is picked. A block missing any of them still renders in a
+ * document, it just is not offered as a thing to add.
+ */
+export declare function isOfferedInMenus(definition: EditorBlockDefinition): boolean;
+/**
+ * The block's menu label as react-intl wants it. A plain string becomes the
+ * default message under a generated id, so it shows as written until someone
+ * ships a translation for it.
+ */
+export declare function blockLabelDescriptor(definition: EditorBlockDefinition): MessageDescriptor;
+/** Empties the registry. Exists for tests; the admin never needs it. */
+export declare function clearRegisteredBlocks(): void;
+/**
+ * Teaches Slate about the registered blocks.
+ *
+ * Void-ness is derived from the declared content model rather than asked for
+ * separately: a block that renders from its own attributes is exactly a Slate
+ * void, and getting that wrong is the difference between a working block and an
+ * uneditable one.
+ */
+export declare function withRegisteredBlocks(editor: Editor): Editor;

package/dist/admin/src/components/BlocksInput/BlocksEditor.d.ts

@@ -29,10 +29,18 @@ type NonSelectorBlockKey = 'list-item' | 'link' | 'horizontal-line' | 'table' |
 declare const selectorBlockKeys: readonly ["paragraph", "heading-one", "heading-two", "heading-three", "heading-four", "heading-five", "heading-six", "list-ordered", "list-unordered", "list-todo", "image", "audio", "video", "embed", "quote", "code", "math", "diagram", "callout", "details", "button", "social-embed"];
 type SelectorBlockKey = (typeof selectorBlockKeys)[number];
 declare const isSelectorBlockKey: (key: unknown) => key is "image" | "audio" | "math" | "diagram" | "callout" | "details" | "button" | "social-embed" | "embed" | "video" | "code" | "paragraph" | "heading-one" | "heading-two" | "heading-three" | "heading-four" | "heading-five" | "heading-six" | "list-ordered" | "list-unordered" | "list-todo" | "quote";
+/**
+ * The built-in keys are spelled out so `blocks.paragraph` stays typed, while
+ * the index signature leaves room for the types other packages register — see
+ * `registerBlock`. Without it, every consumer that walks the store would have
+ * to widen at the call site.
+ */
 type BlocksStore = {
     [K in SelectorBlockKey]: SelectorBlock;
 } & {
     [K in NonSelectorBlockKey]: NonSelectorBlock;
+} & {
+    [key: string]: SelectorBlock | NonSelectorBlock;
 };
 interface BlocksEditorContextValue {
     blocks: BlocksStore;

package/dist/admin/src/index.d.ts

@@ -8,3 +8,10 @@ declare const _default: {
     }[]>;
 };
 export default _default;
+/**
+ * The extension surface. Another Strapi plugin adds a block type by calling
+ * `registerBlock` from its own `register()`, which runs before any editor is
+ * mounted.
+ */
+export { registerBlock, getRegisteredBlocks, clearRegisteredBlocks, } from './blockRegistry';
+export type { EditorBlockDefinition } from './blockRegistry';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qkix/strapi-plugin-better-blocks",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "An enhanced Rich Text (Blocks) field for Strapi with inline color picker and more",
   "strapi": {
     "kind": "plugin",
@@ -54,7 +54,8 @@
     "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "shiki": "^4.3.0",
-    "unified": "^11.0.5"
+    "unified": "^11.0.5",
+    "@qkix/better-blocks-core": "^0.2.1"
   },
   "devDependencies": {
     "@strapi/sdk-plugin": "^5.3.2",
@@ -72,8 +73,8 @@
     "styled-components": "^6.1.17",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@qkix/eslint-config": "0.0.0",
-    "@qkix/tsconfig": "0.0.0"
+    "@qkix/tsconfig": "0.0.0",
+    "@qkix/eslint-config": "0.0.0"
   },
   "peerDependencies": {
     "@radix-ui/react-toolbar": "^1.0.0",
@@ -99,13 +100,13 @@
   "author": "qkix",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/qkix/strapi-plugin-better-blocks.git",
+    "url": "git+https://github.com/qkix/strapi-plugins.git",
     "directory": "packages/strapi-plugin-better-blocks"
   },
   "bugs": {
-    "url": "https://github.com/qkix/strapi-plugin-better-blocks/issues"
+    "url": "https://github.com/qkix/strapi-plugins/issues"
   },
-  "homepage": "https://github.com/qkix/strapi-plugin-better-blocks#readme",
+  "homepage": "https://github.com/qkix/strapi-plugins#readme",
   "nx": {
     "tags": [
       "scope:plugin"