@pilotiq/tiptap 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @pilotiq/tiptap
 
+## 3.13.0
+
+### Minor Changes
+
+- ded54a8: Ship five built-in **inline content blocks** in every `RichTextField` (free + pro): **FAQ**, **Alert** (info/warning/success/tip), **Summary**, **Key takeaways**, and **Pros & cons**.
+
+  They are **inline editable nodes** — a small label on top, content typed straight into the block in place (no card, no popup, no border/background). Inserted from the slash menu's **Content** group. Each renders read-side to semantic `pilotiq-*` HTML via `renderRichTextToHtml` (consumer owns the CSS). Quote and Table remain the native `blockquote` / table extensions.
+
+  - Nodes live in `extensions/contentBlocks.ts`; registered by default in the editor.
+  - Alert's type is the label (Info/Warning/Success/Tip), chosen from the slash menu.
+  - Pros & cons is two labelled list columns.
+
+  The `Block.make().schema([...])` API (card + side-panel form) stays for **custom** blocks via `RichTextField.blocks([...])`, but no schema block ships as a default. `Block.toMeta()` / `RichTextField.toMeta()` are now `async` so option-fields (Select/Radio/ToggleButtons) resolve correctly inside custom schema blocks.
+
 ## 3.12.0
 
 ### Minor Changes

package/dist/Block.d.ts

@@ -41,7 +41,13 @@ export declare class Block {
     getLabel(): string;
     getIcon(): string | undefined;
     getSchema(): readonly Field[];
-    /** @internal */
-    toMeta(): BlockMeta;
+    /**
+     * @internal
+     * Async because schema fields can be async — `SelectField` / `RadioField` /
+     * `ToggleButtonsField` resolve their options at meta-build time and return a
+     * `Promise<FieldMeta>`. We await every field so the serialized schema never
+     * contains an unresolved Promise (which would JSON-stringify to `{}`).
+     */
+    toMeta(): Promise<BlockMeta>;
 }
 //# sourceMappingURL=Block.d.ts.map

package/dist/Block.js

@@ -43,13 +43,19 @@ export class Block {
     getLabel() { return this._label ?? this._name; }
     getIcon() { return this._icon; }
     getSchema() { return this._schema; }
-    /** @internal */
-    toMeta() {
+    /**
+     * @internal
+     * Async because schema fields can be async — `SelectField` / `RadioField` /
+     * `ToggleButtonsField` resolve their options at meta-build time and return a
+     * `Promise<FieldMeta>`. We await every field so the serialized schema never
+     * contains an unresolved Promise (which would JSON-stringify to `{}`).
+     */
+    async toMeta() {
         return {
             name: this._name,
             label: this._label ?? this._name,
             icon: this._icon,
-            schema: this._schema.map((f) => f.toMeta()),
+            schema: (await Promise.all(this._schema.map((f) => f.toMeta()))),
         };
     }
 }

package/dist/RichTextField.d.ts

@@ -107,6 +107,7 @@ export interface RichTextFieldMeta extends FieldMeta {
  */
 export declare class RichTextField extends Field {
     private _blocks;
+    private _includeDefaultBlocks;
     private _slashCommand;
     /** `undefined` = use default, `null` = hidden, array = explicit override. */
     private _toolbarOverride;
@@ -127,8 +128,22 @@ export declare class RichTextField extends Field {
     private _mentionsUrl?;
     private constructor();
     static make(name: string): RichTextField;
-    /** Custom blocks available via the slash menu. */
+    /** Custom blocks available via the slash menu (merged on top of the defaults). */
     blocks(blocks: Block[]): this;
+    /**
+     * Toggle the built-in default blocks (FAQ, Alert, Summary, Key takeaways,
+     * Pros & cons) for this field. On by default — every field gets them in the
+     * slash menu and the agent block catalog. Pass `false` to ship only the
+     * blocks declared via `.blocks([...])`.
+     */
+    withDefaultBlocks(enabled?: boolean): this;
+    /**
+     * The blocks this field actually exposes — the default set (unless opted
+     * out) merged with the field's own `.blocks([...])`. A field block with the
+     * same name overrides the default. This is what the editor slash menu, the
+     * side panel, and the agent block catalog all consume.
+     */
+    private resolveBlocks;
     /** Toggle the slash menu (`/`) on/off. Defaults to `true`. */
     slashCommand(enabled: boolean): this;
     /**
@@ -281,6 +296,6 @@ export declare class RichTextField extends Field {
      */
     getToolbarGroups(): ToolbarGroups | null;
     isFloatingToolbarEnabled(): boolean;
-    toMeta(ctx?: RenderContext): RichTextFieldMeta;
+    toMeta(ctx?: RenderContext): Promise<RichTextFieldMeta>;
 }
 //# sourceMappingURL=RichTextField.d.ts.map

package/dist/RichTextField.js

@@ -1,4 +1,5 @@
 import { Field } from '@pilotiq/pilotiq';
+import { defaultBlocks } from './blocks/index.js';
 /** Default top-level toolbar groups — mirrors the reference admin's layout. */
 export const DEFAULT_TOOLBAR_GROUPS = [
     ['bold', 'italic', 'underline', 'strike', 'subscript', 'superscript', 'link'],
@@ -59,6 +60,7 @@ export const DEFAULT_HIGHLIGHT_COLORS = [
  */
 export class RichTextField extends Field {
     _blocks = [];
+    _includeDefaultBlocks = true;
     _slashCommand = true;
     /** `undefined` = use default, `null` = hidden, array = explicit override. */
     _toolbarOverride = undefined;
@@ -83,11 +85,37 @@ export class RichTextField extends Field {
     static make(name) {
         return new RichTextField(name);
     }
-    /** Custom blocks available via the slash menu. */
+    /** Custom blocks available via the slash menu (merged on top of the defaults). */
     blocks(blocks) {
         this._blocks = blocks;
         return this;
     }
+    /**
+     * Toggle the built-in default blocks (FAQ, Alert, Summary, Key takeaways,
+     * Pros & cons) for this field. On by default — every field gets them in the
+     * slash menu and the agent block catalog. Pass `false` to ship only the
+     * blocks declared via `.blocks([...])`.
+     */
+    withDefaultBlocks(enabled = true) {
+        this._includeDefaultBlocks = enabled;
+        return this;
+    }
+    /**
+     * The blocks this field actually exposes — the default set (unless opted
+     * out) merged with the field's own `.blocks([...])`. A field block with the
+     * same name overrides the default. This is what the editor slash menu, the
+     * side panel, and the agent block catalog all consume.
+     */
+    resolveBlocks() {
+        const byName = new Map();
+        if (this._includeDefaultBlocks) {
+            for (const b of defaultBlocks)
+                byName.set(b.getName(), b);
+        }
+        for (const b of this._blocks)
+            byName.set(b.getName(), b);
+        return [...byName.values()];
+    }
     /** Toggle the slash menu (`/`) on/off. Defaults to `true`. */
     slashCommand(enabled) {
         this._slashCommand = enabled;
@@ -256,7 +284,7 @@ export class RichTextField extends Field {
         this._mentions = providers;
         return this;
     }
-    getBlocks() { return this._blocks; }
+    getBlocks() { return this.resolveBlocks(); }
     getMergeTags() { return this._mergeTags; }
     getMentionProviders() { return this._mentions; }
     /**
@@ -326,10 +354,13 @@ export class RichTextField extends Field {
     isFloatingToolbarEnabled() {
         return this._floatingToolbar;
     }
-    toMeta(ctx) {
-        // RichTextField has no async resolvers, so the parent always returns
-        // the sync FieldMeta branch — cast away the union for the spread.
-        const base = super.toMeta(ctx);
+    async toMeta(ctx) {
+        // Block fields can be async — Select / Radio / ToggleButtons resolve their
+        // options at meta-build time and return `Promise<FieldMeta>`. So block
+        // metas, and therefore this method, are async. The core resolves every
+        // field via `await field.toMeta(ctx)` (`resolveField`), so returning a
+        // Promise is the supported path.
+        const base = (await Promise.resolve(super.toMeta(ctx)));
         // Strip `attachFiles` server-side when the panel hasn't registered an
         // upload adapter — same posture as `MarkdownField` and the editor
         // chrome stays clean. `uploadUrl` is the wire-side URL for the picker
@@ -342,7 +373,7 @@ export class RichTextField extends Field {
                 .filter(g => g.length > 0) ?? null;
         return {
             ...base,
-            blocks: this._blocks.map((b) => b.toMeta()),
+            blocks: await Promise.all(this.resolveBlocks().map((b) => b.toMeta())),
             slashCommand: this._slashCommand,
             toolbarGroups: filteredGroups,
             floatingToolbar: this._floatingToolbar,

package/dist/blocks/alert.d.ts

@@ -0,0 +1,10 @@
+import { Block } from '../Block.js';
+/**
+ * Default **Alert** (callout) block — a typed notice.
+ *
+ * Wire shape: `{ type: 'info' | 'warning' | 'success' | 'tip'; content: string }`.
+ * Renders read-side as `<div class="pilotiq-alert pilotiq-alert-<type>">`. An
+ * empty / unknown `type` falls back to `info` at render time.
+ */
+export declare const alertBlock: Block;
+//# sourceMappingURL=alert.d.ts.map

package/dist/blocks/alert.js

@@ -0,0 +1,23 @@
+import { SelectField, TextareaField } from '@pilotiq/pilotiq';
+import { Block } from '../Block.js';
+/**
+ * Default **Alert** (callout) block — a typed notice.
+ *
+ * Wire shape: `{ type: 'info' | 'warning' | 'success' | 'tip'; content: string }`.
+ * Renders read-side as `<div class="pilotiq-alert pilotiq-alert-<type>">`. An
+ * empty / unknown `type` falls back to `info` at render time.
+ */
+export const alertBlock = Block.make('alert')
+    .label('Alert')
+    .icon('⚠️')
+    .schema([
+    SelectField.make('type')
+        .label('Type')
+        .options([
+        { value: 'info', label: 'Info' },
+        { value: 'warning', label: 'Warning' },
+        { value: 'success', label: 'Success' },
+        { value: 'tip', label: 'Tip' },
+    ]),
+    TextareaField.make('content').label('Content').placeholder('Alert message…'),
+]);

package/dist/blocks/faq.d.ts

@@ -0,0 +1,9 @@
+import { Block } from '../Block.js';
+/**
+ * Default **FAQ** block — a list of question / answer pairs.
+ *
+ * Wire shape: `{ items: Array<{ question: string; answer: string }> }`.
+ * Renders read-side as a `<div class="pilotiq-faq">` of `<details>` items.
+ */
+export declare const faqBlock: Block;
+//# sourceMappingURL=faq.d.ts.map

package/dist/blocks/faq.js

@@ -0,0 +1,21 @@
+import { Repeater, TextField, TextareaField } from '@pilotiq/pilotiq';
+import { Block } from '../Block.js';
+/**
+ * Default **FAQ** block — a list of question / answer pairs.
+ *
+ * Wire shape: `{ items: Array<{ question: string; answer: string }> }`.
+ * Renders read-side as a `<div class="pilotiq-faq">` of `<details>` items.
+ */
+export const faqBlock = Block.make('faq')
+    .label('FAQ')
+    .icon('❓')
+    .schema([
+    Repeater.make('items')
+        .label('Questions')
+        .schema([
+        TextField.make('question').label('Question').placeholder('What is …?'),
+        TextareaField.make('answer').label('Answer').placeholder('A short, direct answer.'),
+    ])
+        .reorderable()
+        .addActionLabel('Add question'),
+]);

package/dist/blocks/index.d.ts

@@ -0,0 +1,22 @@
+import type { Block } from '../Block.js';
+/**
+ * Schema-form block factories — `Block.make().schema([...])` style, edited via
+ * the right-docked side panel. Kept for **custom / legacy** use via
+ * `RichTextField.blocks([...])`. They are NO LONGER defaults.
+ *
+ * The built-in content blocks — FAQ, Alert, Summary, Key takeaways, Pros & cons
+ * — are now **inline editable nodes** (`extensions/contentBlocks.ts`):
+ * labelled, edited in place, registered directly in the editor + slash menu.
+ */
+export { faqBlock } from './faq.js';
+export { alertBlock } from './alert.js';
+export { summaryBlock } from './summary.js';
+export { keyTakeawaysBlock } from './keyTakeaways.js';
+export { prosConsBlock } from './prosCons.js';
+/**
+ * Schema blocks shipped by default in every `RichTextField`. Empty — the
+ * default content blocks are inline nodes now, not schema-form blocks. A
+ * field's own `.blocks([...])` still merge in via `RichTextField`.
+ */
+export declare const defaultBlocks: readonly Block[];
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/index.js

@@ -0,0 +1,20 @@
+/**
+ * Schema-form block factories — `Block.make().schema([...])` style, edited via
+ * the right-docked side panel. Kept for **custom / legacy** use via
+ * `RichTextField.blocks([...])`. They are NO LONGER defaults.
+ *
+ * The built-in content blocks — FAQ, Alert, Summary, Key takeaways, Pros & cons
+ * — are now **inline editable nodes** (`extensions/contentBlocks.ts`):
+ * labelled, edited in place, registered directly in the editor + slash menu.
+ */
+export { faqBlock } from './faq.js';
+export { alertBlock } from './alert.js';
+export { summaryBlock } from './summary.js';
+export { keyTakeawaysBlock } from './keyTakeaways.js';
+export { prosConsBlock } from './prosCons.js';
+/**
+ * Schema blocks shipped by default in every `RichTextField`. Empty — the
+ * default content blocks are inline nodes now, not schema-form blocks. A
+ * field's own `.blocks([...])` still merge in via `RichTextField`.
+ */
+export const defaultBlocks = [];

package/dist/blocks/keyTakeaways.d.ts

@@ -0,0 +1,10 @@
+import { Block } from '../Block.js';
+/**
+ * Default **Key takeaways** block — a short bulleted list of the article's
+ * main points.
+ *
+ * Wire shape: `{ points: string[] }`. Renders read-side as
+ * `<div class="pilotiq-key-takeaways">` with a label and a `<ul>`.
+ */
+export declare const keyTakeawaysBlock: Block;
+//# sourceMappingURL=keyTakeaways.d.ts.map

package/dist/blocks/keyTakeaways.js

@@ -0,0 +1,15 @@
+import { TagsInput } from '@pilotiq/pilotiq';
+import { Block } from '../Block.js';
+/**
+ * Default **Key takeaways** block — a short bulleted list of the article's
+ * main points.
+ *
+ * Wire shape: `{ points: string[] }`. Renders read-side as
+ * `<div class="pilotiq-key-takeaways">` with a label and a `<ul>`.
+ */
+export const keyTakeawaysBlock = Block.make('key-takeaways')
+    .label('Key takeaways')
+    .icon('🔑')
+    .schema([
+    TagsInput.make('points').label('Key takeaways'),
+]);

package/dist/blocks/prosCons.d.ts

@@ -0,0 +1,9 @@
+import { Block } from '../Block.js';
+/**
+ * Default **Pros & cons** block — two lists, side by side.
+ *
+ * Wire shape: `{ pros: string[]; cons: string[] }`. Renders read-side as
+ * `<div class="pilotiq-pros-cons">` with a `pros` and a `cons` column.
+ */
+export declare const prosConsBlock: Block;
+//# sourceMappingURL=prosCons.d.ts.map

package/dist/blocks/prosCons.js

@@ -0,0 +1,15 @@
+import { TagsInput } from '@pilotiq/pilotiq';
+import { Block } from '../Block.js';
+/**
+ * Default **Pros & cons** block — two lists, side by side.
+ *
+ * Wire shape: `{ pros: string[]; cons: string[] }`. Renders read-side as
+ * `<div class="pilotiq-pros-cons">` with a `pros` and a `cons` column.
+ */
+export const prosConsBlock = Block.make('pros-cons')
+    .label('Pros & cons')
+    .icon('⚖️')
+    .schema([
+    TagsInput.make('pros').label('Pros'),
+    TagsInput.make('cons').label('Cons'),
+]);

package/dist/blocks/summary.d.ts

@@ -0,0 +1,9 @@
+import { Block } from '../Block.js';
+/**
+ * Default **Summary** block — a short, labelled summary of the article.
+ *
+ * Wire shape: `{ content: string }`. Renders read-side as
+ * `<div class="pilotiq-summary">` with a label and the body.
+ */
+export declare const summaryBlock: Block;
+//# sourceMappingURL=summary.d.ts.map

package/dist/blocks/summary.js

@@ -0,0 +1,14 @@
+import { TextareaField } from '@pilotiq/pilotiq';
+import { Block } from '../Block.js';
+/**
+ * Default **Summary** block — a short, labelled summary of the article.
+ *
+ * Wire shape: `{ content: string }`. Renders read-side as
+ * `<div class="pilotiq-summary">` with a label and the body.
+ */
+export const summaryBlock = Block.make('summary')
+    .label('Summary')
+    .icon('📝')
+    .schema([
+    TextareaField.make('content').label('Summary').placeholder('A short summary of the article…'),
+]);

package/dist/extensions/DragHandleExtension.js

@@ -34,11 +34,14 @@ export const DragHandleExtension = Extension.create({
     },
 });
 function createDragHandleView(view) {
-    const handle = document.createElement('button');
-    handle.type = 'button';
+    // A <div> (not <button>): a button grabs DOM focus on click, which yanks
+    // focus out of the editor so a follow-up Backspace/Delete on the selected
+    // block goes nowhere. A div doesn't steal focus, so click-to-select works.
+    const handle = document.createElement('div');
+    handle.setAttribute('role', 'button');
     handle.setAttribute('data-pilotiq-drag-handle', '');
     handle.setAttribute('contenteditable', 'false');
-    handle.setAttribute('aria-label', 'Drag block');
+    handle.setAttribute('aria-label', 'Drag or select block');
     handle.setAttribute('draggable', 'true');
     handle.style.cssText = [
         'position: absolute',
@@ -149,16 +152,30 @@ function createDragHandleView(view) {
     const onDragEnd = () => {
         handle.style.cursor = 'grab';
     };
+    // A plain click (no drag) selects the hovered block as a NodeSelection, so
+    // the whole block can be deleted (Backspace / Delete) or replaced — the only
+    // affordance for removing atom-ish custom blocks (FAQ, callout, grid, …).
+    const onClick = (event) => {
+        event.preventDefault();
+        if (activePos === null)
+            return;
+        if (!view.state.doc.nodeAt(activePos))
+            return;
+        view.dispatch(view.state.tr.setSelection(NodeSelection.create(view.state.doc, activePos)));
+        view.focus();
+    };
     view.dom.addEventListener('mousemove', onMouseMove);
     view.dom.addEventListener('mouseleave', onMouseLeave);
     handle.addEventListener('dragstart', onDragStart);
     handle.addEventListener('dragend', onDragEnd);
+    handle.addEventListener('click', onClick);
     return {
         destroy: () => {
             view.dom.removeEventListener('mousemove', onMouseMove);
             view.dom.removeEventListener('mouseleave', onMouseLeave);
             handle.removeEventListener('dragstart', onDragStart);
             handle.removeEventListener('dragend', onDragEnd);
+            handle.removeEventListener('click', onClick);
             handle.remove();
         },
     };

package/dist/extensions/SlashCommandExtension.js

@@ -137,6 +137,77 @@ export function buildSlashItems(blocks, mergeTags, query, insert) {
             searchKey: 'grid columns layout 3 three split',
             command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setGrid({ columns: 3 }).run(),
         },
+        // Inline content blocks — labelled, editable-in-place regions (nodes in
+        // contentBlocks.ts). Inserted via insertContent; no custom commands.
+        {
+            key: 'key-takeaways', label: 'Key takeaways', icon: '🔑', group: 'Content',
+            searchKey: 'key takeaways points highlights tldr',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({
+                type: 'keyTakeaways',
+                content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }],
+            }).run(),
+        },
+        {
+            key: 'summary', label: 'Summary', icon: '📝', group: 'Content',
+            searchKey: 'summary tldr abstract overview',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'summary', content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'faq', label: 'FAQ', icon: '❓', group: 'Content',
+            searchKey: 'faq questions answers frequently asked',
+            command: ({ editor, range }) => {
+                editor.chain().focus().deleteRange(range).insertContent({
+                    type: 'faq',
+                    content: [
+                        {
+                            type: 'faqItem',
+                            content: [{ type: 'faqQuestion' }, { type: 'faqAnswer', content: [{ type: 'paragraph' }] }],
+                        },
+                    ],
+                }).run();
+                // insertContent leaves the cursor in the answer — move it into the first
+                // question. Resolve the enclosing faqItem and select its question start
+                // (before(faqItem) +1 into the item +1 into the question = +2).
+                const { $from } = editor.state.selection;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqItem') {
+                        editor.chain().setTextSelection($from.before(d) + 2).focus().run();
+                        break;
+                    }
+                }
+            },
+        },
+        {
+            key: 'pros-cons', label: 'Pros & cons', icon: '⚖️', group: 'Content',
+            searchKey: 'pros cons advantages disadvantages comparison',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({
+                type: 'prosCons',
+                content: [
+                    { type: 'prosColumn', content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }] },
+                    { type: 'consColumn', content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }] },
+                ],
+            }).run(),
+        },
+        {
+            key: 'alert-info', label: 'Alert: Info', icon: 'ⓘ', group: 'Content',
+            searchKey: 'alert callout notice info note',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'info' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-warning', label: 'Alert: Warning', icon: '⚠️', group: 'Content',
+            searchKey: 'alert callout notice warning caution danger',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'warning' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-success', label: 'Alert: Success', icon: '✅', group: 'Content',
+            searchKey: 'alert callout notice success ok done',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'success' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-tip', label: 'Alert: Tip', icon: '💡', group: 'Content',
+            searchKey: 'alert callout notice tip hint',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'tip' }, content: [{ type: 'paragraph' }] }).run(),
+        },
         // Image entry shares the toolbar's attach-files dialog; only surfaced
         // when the panel has wired an `UploadAdapter`. Without one, the dialog
         // would post to a missing endpoint — the slash item degrades the same

package/dist/extensions/contentBlocks.d.ts

@@ -0,0 +1,19 @@
+import { Node, Extension } from '@tiptap/core';
+export declare const KeyTakeaways: Node<any, any>;
+export declare const Summary: Node<any, any>;
+export declare const Faq: Node<any, any>;
+export declare const FaqItem: Node<any, any>;
+export declare const FaqQuestion: Node<any, any>;
+export declare const FaqAnswer: Node<any, any>;
+export declare const ALERT_TYPES: readonly ["info", "warning", "success", "tip"];
+export type AlertType = (typeof ALERT_TYPES)[number];
+/** Exported so `render.ts` shares the same coercion at the server boundary. */
+export declare function coerceAlertType(value: unknown): AlertType;
+export declare const Alert: Node<any, any>;
+export declare const ProsCons: Node<any, any>;
+export declare const ProsColumn: Node<any, any>;
+export declare const ConsColumn: Node<any, any>;
+export declare const ContentBlockKeymap: Extension<any, any>;
+/** All inline content-block extensions — registered in the editor's list. */
+export declare const contentBlockNodes: (Node<any, any> | Extension<any, any>)[];
+//# sourceMappingURL=contentBlocks.d.ts.map

package/dist/extensions/contentBlocks.js

@@ -0,0 +1,281 @@
+import { Node, Extension, mergeAttributes } from '@tiptap/core';
+/** A labelled region whose body is ordinary editable content (`block+`). */
+function labeledBlock(spec) {
+    return Node.create({
+        name: spec.name,
+        group: 'block',
+        content: 'block+',
+        defining: true,
+        parseHTML() {
+            return [{ tag: `div[data-type="${spec.name}"]`, contentElement: '.pilotiq-block-body' }];
+        },
+        renderHTML({ HTMLAttributes }) {
+            return [
+                'div',
+                mergeAttributes(HTMLAttributes, { 'data-type': spec.name, class: spec.cssClass }),
+                ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, spec.label],
+                ['div', { class: 'pilotiq-block-body' }, 0],
+            ];
+        },
+    });
+}
+export const KeyTakeaways = labeledBlock({ name: 'keyTakeaways', label: 'Key takeaways', cssClass: 'pilotiq-key-takeaways' });
+export const Summary = labeledBlock({ name: 'summary', label: 'Summary', cssClass: 'pilotiq-summary' });
+// ── FAQ — structured question / answer items ──
+//
+// `faq` > `faqItem+`; each item is a `faqQuestion` (inline text, "Q" marker) +
+// a `faqAnswer` (block+, "A" marker). Authoring: Enter in a question jumps to
+// its answer; Cmd/Ctrl-Enter inside an item adds a new Q&A item below.
+const NEW_FAQ_ITEM = {
+    type: 'faqItem',
+    content: [{ type: 'faqQuestion' }, { type: 'faqAnswer', content: [{ type: 'paragraph' }] }],
+};
+export const Faq = Node.create({
+    name: 'faq',
+    group: 'block',
+    content: 'faqItem+',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faq"]', contentElement: '.pilotiq-block-body' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faq', class: 'pilotiq-faq' }),
+            ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, 'FAQ'],
+            ['div', { class: 'pilotiq-block-body' }, 0],
+        ];
+    },
+    addKeyboardShortcuts() {
+        return {
+            // Enter drives the whole Q&A flow:
+            //   • in a question → jump to its answer;
+            //   • in an answer  → finish it and start a NEW Q&A item below (focus its
+            //     question). Repeatable: question → Enter → answer → Enter → next.
+            // (Shift-Enter still inserts a line break within an answer.)
+            Enter: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty)
+                    return false;
+                for (let d = $from.depth; d > 0; d--) {
+                    const name = $from.node(d).type.name;
+                    if (name === 'faqQuestion') {
+                        return editor.chain().setTextSelection($from.after(d) + 1).focus().run();
+                    }
+                    if (name === 'faqAnswer') {
+                        const after = $from.after(d - 1); // position just after the faqItem
+                        return editor.chain().insertContentAt(after, NEW_FAQ_ITEM).setTextSelection(after + 2).focus().run();
+                    }
+                }
+                return false;
+            },
+            // Cmd/Ctrl-Enter anywhere in an item also adds a new Q&A item below.
+            'Mod-Enter': ({ editor }) => {
+                const { $from } = editor.state.selection;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqItem') {
+                        const after = $from.after(d);
+                        return editor.chain().insertContentAt(after, NEW_FAQ_ITEM).setTextSelection(after + 2).focus().run();
+                    }
+                }
+                return false;
+            },
+            // Backspace in an EMPTY question removes that whole Q&A item (and the
+            // whole FAQ block if it was the only item) — like emptying a list item.
+            Backspace: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty)
+                    return false;
+                let qDepth = -1;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqQuestion') {
+                        qDepth = d;
+                        break;
+                    }
+                }
+                if (qDepth === -1)
+                    return false;
+                if ($from.node(qDepth).content.size > 0)
+                    return false; // question not empty → normal backspace
+                const faqDepth = qDepth - 2;
+                const itemDepth = qDepth - 1;
+                const faq = $from.node(faqDepth);
+                const faqStart = $from.before(faqDepth);
+                if (faq.childCount <= 1) {
+                    // last item → remove the whole FAQ block
+                    return editor.chain().deleteRange({ from: faqStart, to: faqStart + faq.nodeSize }).focus().run();
+                }
+                // remove just this Q&A item; drop the cursor into a neighbouring item
+                const itemStart = $from.before(itemDepth);
+                const itemEnd = itemStart + $from.node(itemDepth).nodeSize;
+                const caret = $from.index(faqDepth) === 0 ? faqStart + 3 : itemStart - 1;
+                return editor.chain().deleteRange({ from: itemStart, to: itemEnd }).setTextSelection(caret).focus().run();
+            },
+        };
+    },
+});
+export const FaqItem = Node.create({
+    name: 'faqItem',
+    group: 'faqItem',
+    content: 'faqQuestion faqAnswer',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqItem"]' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'faqItem', class: 'pilotiq-faq-item' }), 0];
+    },
+});
+export const FaqQuestion = Node.create({
+    name: 'faqQuestion',
+    content: 'inline*',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqQuestion"]', contentElement: '.pilotiq-faq-text' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faqQuestion', class: 'pilotiq-faq-question' }),
+            ['span', { class: 'pilotiq-faq-marker', contenteditable: 'false' }, 'Q'],
+            ['span', { class: 'pilotiq-faq-text' }, 0],
+        ];
+    },
+});
+export const FaqAnswer = Node.create({
+    name: 'faqAnswer',
+    content: 'block+',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqAnswer"]', contentElement: '.pilotiq-faq-body' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faqAnswer', class: 'pilotiq-faq-answer' }),
+            ['span', { class: 'pilotiq-faq-marker', contenteditable: 'false' }, 'A'],
+            ['div', { class: 'pilotiq-faq-body' }, 0],
+        ];
+    },
+});
+// ── Alert — a typed notice; the label IS the type (Info/Warning/Success/Tip) ──
+export const ALERT_TYPES = ['info', 'warning', 'success', 'tip'];
+const ALERT_LABEL = { info: 'Info', warning: 'Warning', success: 'Success', tip: 'Tip' };
+/** Exported so `render.ts` shares the same coercion at the server boundary. */
+export function coerceAlertType(value) {
+    return ALERT_TYPES.includes(String(value)) ? value : 'info';
+}
+export const Alert = Node.create({
+    name: 'alert',
+    group: 'block',
+    content: 'block+',
+    defining: true,
+    addAttributes() {
+        return {
+            type: {
+                default: 'info',
+                parseHTML: (el) => coerceAlertType(el.getAttribute('data-alert-type')),
+                renderHTML: (attrs) => ({ 'data-alert-type': coerceAlertType(attrs['type']) }),
+            },
+        };
+    },
+    parseHTML() {
+        return [{ tag: 'div[data-type="alert"]', contentElement: '.pilotiq-block-body' }];
+    },
+    renderHTML({ node, HTMLAttributes }) {
+        const type = coerceAlertType(node.attrs['type']);
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'alert', class: `pilotiq-alert pilotiq-alert-${type}` }),
+            ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, ALERT_LABEL[type]],
+            ['div', { class: 'pilotiq-block-body' }, 0],
+        ];
+    },
+});
+// ── Pros & cons — two labelled columns (each a `block+` body, list by default) ──
+export const ProsCons = Node.create({
+    name: 'prosCons',
+    group: 'block',
+    content: 'prosColumn consColumn',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="prosCons"]' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'prosCons', class: 'pilotiq-pros-cons' }), 0];
+    },
+});
+function prosConsColumn(name, label, cssClass) {
+    return Node.create({
+        name,
+        group: 'prosConsColumn',
+        content: 'block+',
+        defining: true,
+        parseHTML() {
+            return [{ tag: `div[data-type="${name}"]`, contentElement: '.pilotiq-block-body' }];
+        },
+        renderHTML({ HTMLAttributes }) {
+            return [
+                'div',
+                mergeAttributes(HTMLAttributes, { 'data-type': name, class: cssClass }),
+                ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, label],
+                ['div', { class: 'pilotiq-block-body' }, 0],
+            ];
+        },
+    });
+}
+export const ProsColumn = prosConsColumn('prosColumn', 'Pros', 'pilotiq-pros');
+export const ConsColumn = prosConsColumn('consColumn', 'Cons', 'pilotiq-cons');
+// ── Keyboard: delete a whole content block with Backspace at its start ──
+//
+// Custom blocks have no inline "remove" affordance, and Backspace inside a
+// nested block (FAQ etc.) just deletes characters. So: Backspace at the very
+// start of a content block removes the entire block — the reliable, keyboard
+// way to delete one (the drag handle's click-to-select is the mouse way).
+// faq is excluded — it handles Backspace itself (empty-question → remove item).
+const DELETABLE_BLOCKS = new Set(['summary', 'keyTakeaways', 'alert', 'prosCons']);
+export const ContentBlockKeymap = Extension.create({
+    name: 'pilotiqContentBlockKeymap',
+    addKeyboardShortcuts() {
+        return {
+            Backspace: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty || $from.parentOffset !== 0)
+                    return false;
+                for (let d = 1; d <= $from.depth; d++) {
+                    const node = $from.node(d);
+                    if (!DELETABLE_BLOCKS.has(node.type.name))
+                        continue;
+                    // Only when the cursor is at the block's very start (first child all
+                    // the way down) — otherwise let Backspace delete normally.
+                    let atStart = true;
+                    for (let dd = $from.depth; dd > d; dd--) {
+                        if ($from.index(dd - 1) !== 0) {
+                            atStart = false;
+                            break;
+                        }
+                    }
+                    if (!atStart)
+                        return false;
+                    const start = $from.before(d);
+                    return editor.chain().deleteRange({ from: start, to: start + node.nodeSize }).focus().run();
+                }
+                return false;
+            },
+        };
+    },
+});
+/** All inline content-block extensions — registered in the editor's list. */
+export const contentBlockNodes = [
+    KeyTakeaways,
+    Summary,
+    Faq,
+    FaqItem,
+    FaqQuestion,
+    FaqAnswer,
+    Alert,
+    ProsCons,
+    ProsColumn,
+    ConsColumn,
+    ContentBlockKeymap,
+];

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { RichTextField, DEFAULT_TOOLBAR_GROUPS, DEFAULT_TEXT_COLORS, DEFAULT_HIGHLIGHT_COLORS, type ColorSwatch, type RichTextAttachmentVisibility, type RichTextFieldMeta, type RichTextStorage, type ToolbarButtonId, type ToolbarGroups, } from './RichTextField.js';
 export { Block, type BlockMeta } from './Block.js';
+export { defaultBlocks, faqBlock, alertBlock, summaryBlock, keyTakeawaysBlock, prosConsBlock, } from './blocks/index.js';
 export { MentionProvider, type MentionItem, type MentionProviderMeta, } from './MentionProvider.js';
 export { registerTiptap } from './register.js';
 export { createPlainTextEditor, plainTextOf, plainTextToDoc, type PlainTextEditorOptions, } from './PlainTextEditor.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { RichTextField, DEFAULT_TOOLBAR_GROUPS, DEFAULT_TEXT_COLORS, DEFAULT_HIGHLIGHT_COLORS, } from './RichTextField.js';
 export { Block } from './Block.js';
+export { defaultBlocks, faqBlock, alertBlock, summaryBlock, keyTakeawaysBlock, prosConsBlock, } from './blocks/index.js';
 export { MentionProvider, } from './MentionProvider.js';
 export { registerTiptap } from './register.js';
 export { createPlainTextEditor, plainTextOf, plainTextToDoc, } from './PlainTextEditor.js';

package/dist/react/TiptapEditor.js

@@ -13,6 +13,7 @@ import Image from '@tiptap/extension-image';
 import { Table, TableRow, TableCell, TableHeader } from '@tiptap/extension-table';
 import { Details, DetailsSummary, DetailsContent } from '@tiptap/extension-details';
 import { Grid, GridColumn } from '../extensions/GridExtension.js';
+import { contentBlockNodes } from '../extensions/contentBlocks.js';
 import { Popover } from '@base-ui/react/popover';
 import { useCollabRoom, getCollabExtensions, useRowCoords, parseRowFieldPath } from '@pilotiq/pilotiq/react';
 import { useCollabSeed } from '@rudderjs/sync/react';
@@ -276,6 +277,9 @@ function ClientEditor(props) {
             // `pilotiq-grid-cols-N`.
             Grid,
             GridColumn,
+            // Inline content blocks — labelled, editable-in-place regions:
+            // Key takeaways / Summary / FAQ / Alert / Pros & cons.
+            ...contentBlockNodes,
             Placeholder.configure({ placeholder: placeholder ?? 'Start writing…' }),
             // BlockNodeExtension carries the block registry on its options —
             // NodeViews mount in a separate React tree and can't see context.

package/dist/render.d.ts

@@ -26,8 +26,11 @@
  *           / image.src + alt + title + width + height
  *           / tableCell.colspan + rowspan + colwidth (also tableHeader)
  *           / mergeTag.id / mention.id + label + trigger
- *   custom blocks — render to `<div data-type="..." data-attrs="...">` so
- *           consumers can replay or style by data-type.
+ *   default blocks — the `pilotiqBlock` node's built-in types (faq / alert /
+ *           summary / key-takeaways / pros-cons) render to semantic
+ *           `<div class="pilotiq-...">` markup; consumers own the CSS.
+ *   custom blocks — any other type renders to `<div data-type="..."
+ *           data-attrs="...">` so consumers can replay or style by data-type.
  */
 export interface RenderRichTextOptions {
     /**

package/dist/render.js

@@ -26,8 +26,11 @@
  *           / image.src + alt + title + width + height
  *           / tableCell.colspan + rowspan + colwidth (also tableHeader)
  *           / mergeTag.id / mention.id + label + trigger
- *   custom blocks — render to `<div data-type="..." data-attrs="...">` so
- *           consumers can replay or style by data-type.
+ *   default blocks — the `pilotiqBlock` node's built-in types (faq / alert /
+ *           summary / key-takeaways / pros-cons) render to semantic
+ *           `<div class="pilotiq-...">` markup; consumers own the CSS.
+ *   custom blocks — any other type renders to `<div data-type="..."
+ *           data-attrs="...">` so consumers can replay or style by data-type.
  */
 /**
  * Render Tiptap content to HTML.
@@ -139,9 +142,20 @@ function renderNode(node, opts) {
         case 'detailsContent': return renderChildren(n, opts);
         case 'grid': return renderGrid(n, opts);
         case 'gridColumn': return wrap('div', n, opts);
+        case 'keyTakeaways': return labeledBlockHtml('pilotiq-key-takeaways', 'Key takeaways', n, opts);
+        case 'summary': return labeledBlockHtml('pilotiq-summary', 'Summary', n, opts);
+        case 'faq': return labeledBlockHtml('pilotiq-faq', 'FAQ', n, opts);
+        case 'faqItem': return `<div class="pilotiq-faq-item">${renderChildren(n, opts)}</div>`;
+        case 'faqQuestion': return `<div class="pilotiq-faq-question"><span class="pilotiq-faq-marker">Q</span><span class="pilotiq-faq-text">${renderChildren(n, opts)}</span></div>`;
+        case 'faqAnswer': return `<div class="pilotiq-faq-answer"><span class="pilotiq-faq-marker">A</span><div class="pilotiq-faq-body">${renderChildren(n, opts)}</div></div>`;
+        case 'alert': return renderAlertNode(n, opts);
+        case 'prosCons': return `<div class="pilotiq-pros-cons">${renderChildren(n, opts)}</div>`;
+        case 'prosColumn': return labeledBlockHtml('pilotiq-pros', 'Pros', n, opts);
+        case 'consColumn': return labeledBlockHtml('pilotiq-cons', 'Cons', n, opts);
         case 'mergeTag': return renderMergeTag(n, opts);
         case 'mention': return renderMention(n, opts);
         case 'text': return renderText(n);
+        case 'pilotiqBlock': return renderPilotiqBlock(n, opts);
         default:
             if (opts.renderBlock)
                 return opts.renderBlock(n);
@@ -340,6 +354,28 @@ function clampGridColumnsForRender(raw) {
     const trunc = Math.trunc(n);
     return trunc === 3 ? 3 : 2;
 }
+// ─── Inline content blocks (labelled editable nodes) ─────────────────
+//
+// Mirrors the editor's `renderHTML` (extensions/contentBlocks.ts): a small
+// label above an editable body. Consumer owns the `pilotiq-*` CSS. Covers
+// keyTakeaways / summary / faq / alert / prosCons (+ pros/cons columns).
+function labeledBlockHtml(cssClass, label, n, opts) {
+    return (`<div class="${cssClass}">` +
+        `<div class="pilotiq-block-label">${escapeHtml(label)}</div>` +
+        `<div class="pilotiq-block-body">${renderChildren(n, opts)}</div>` +
+        `</div>`);
+}
+const ALERT_NODE_TYPES = new Set(['info', 'warning', 'success', 'tip']);
+const ALERT_NODE_LABEL = { info: 'Info', warning: 'Warning', success: 'Success', tip: 'Tip' };
+function renderAlertNode(n, opts) {
+    let type = String(n.attrs?.['type'] ?? '').trim().toLowerCase();
+    if (!ALERT_NODE_TYPES.has(type))
+        type = 'info';
+    return (`<div class="pilotiq-alert pilotiq-alert-${type}" role="note">` +
+        `<div class="pilotiq-block-label">${ALERT_NODE_LABEL[type]}</div>` +
+        `<div class="pilotiq-block-body">${renderChildren(n, opts)}</div>` +
+        `</div>`);
+}
 // ─── Merge tags + mentions ───────────────────────────────────────────
 /**
  * Render a `mergeTag` atom — either substitute the value from
@@ -386,6 +422,104 @@ function renderCustomBlock(n) {
     const inner = n.content ? renderChildren(n, {}) : '';
     return `<div data-type="${escapeAttr(type)}"${dataAttrs}>${inner}</div>`;
 }
+// ─── Default blocks (pilotiqBlock node, keyed on attrs.blockType) ─────
+//
+// The custom-block node (`pilotiqBlock`) carries `blockType` + `blockData`.
+// The blocks shipped by default in `RichTextField` (FAQ / Alert / Summary /
+// Key takeaways / Pros & cons) render to semantic HTML here; every other
+// (host-defined) block type falls back to `opts.renderBlock` or the generic
+// `data-attrs` div. Consumers own the CSS for the `pilotiq-*` classes.
+function renderPilotiqBlock(n, opts) {
+    const attrs = (n.attrs ?? {});
+    const blockType = String(attrs['blockType'] ?? '');
+    let data = attrs['blockData'];
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        }
+        catch {
+            data = {};
+        }
+    }
+    const d = (data && typeof data === 'object' ? data : {});
+    switch (blockType) {
+        case 'faq': return renderFaqBlock(d);
+        case 'alert': return renderAlertBlock(d);
+        case 'summary': return renderSummaryBlock(d);
+        case 'key-takeaways': return renderKeyTakeawaysBlock(d);
+        case 'pros-cons': return renderProsConsBlock(d);
+        default:
+            if (opts.renderBlock)
+                return opts.renderBlock(n);
+            return renderCustomBlock(n);
+    }
+}
+/** Escape a plain-text field value and split blank-line-separated paragraphs. */
+function blockParagraphs(raw) {
+    const s = String(raw ?? '').trim();
+    if (s === '')
+        return '';
+    return s
+        .split(/\n{2,}/)
+        .map((p) => `<p>${escapeHtml(p).replace(/\n/g, '<br>')}</p>`)
+        .join('');
+}
+/** Coerce a field value to a clean `string[]` (TagsInput stores an array). */
+function blockStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((x) => String(x ?? '').trim()).filter((s) => s !== '');
+}
+function renderFaqBlock(d) {
+    const items = Array.isArray(d['items']) ? d['items'] : [];
+    const body = items
+        .map((it) => {
+        const q = escapeHtml(String(it['question'] ?? '').trim());
+        if (q === '')
+            return '';
+        const a = blockParagraphs(it['answer']);
+        return `<details class="pilotiq-faq-item"><summary>${q}</summary><div class="pilotiq-faq-answer">${a}</div></details>`;
+    })
+        .join('');
+    if (body === '')
+        return '';
+    return `<div class="pilotiq-faq">${body}</div>`;
+}
+const ALERT_TYPES = new Set(['info', 'warning', 'success', 'tip']);
+function renderAlertBlock(d) {
+    let type = String(d['type'] ?? '').trim().toLowerCase();
+    if (!ALERT_TYPES.has(type))
+        type = 'info';
+    const content = blockParagraphs(d['content']);
+    return `<div class="pilotiq-alert pilotiq-alert-${type}" role="note">${content}</div>`;
+}
+function renderSummaryBlock(d) {
+    const content = blockParagraphs(d['content']);
+    if (content === '')
+        return '';
+    return (`<div class="pilotiq-summary">` +
+        `<div class="pilotiq-summary-label">Summary</div>` +
+        `<div class="pilotiq-summary-body">${content}</div>` +
+        `</div>`);
+}
+function renderKeyTakeawaysBlock(d) {
+    const points = blockStringList(d['points']);
+    if (points.length === 0)
+        return '';
+    const lis = points.map((p) => `<li>${escapeHtml(p)}</li>`).join('');
+    return (`<div class="pilotiq-key-takeaways">` +
+        `<div class="pilotiq-key-takeaways-label">Key takeaways</div>` +
+        `<ul>${lis}</ul>` +
+        `</div>`);
+}
+function renderProsConsBlock(d) {
+    const pros = blockStringList(d['pros']);
+    const cons = blockStringList(d['cons']);
+    if (pros.length === 0 && cons.length === 0)
+        return '';
+    const column = (label, cls, items) => `<div class="pilotiq-${cls}"><h4>${label}</h4><ul>${items.map((i) => `<li>${escapeHtml(i)}</li>`).join('')}</ul></div>`;
+    return `<div class="pilotiq-pros-cons">${column('Pros', 'pros', pros)}${column('Cons', 'cons', cons)}</div>`;
+}
 // ─── Escapers + sanitizers ───────────────────────────────────────────
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, ch => HTML_ESCAPES[ch] ?? ch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/tiptap",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Tiptap rich-text editor adapter for @pilotiq/pilotiq — slash menu, draggable blocks, custom-block API",
   "license": "MIT",
   "repository": {