@lowdefy/blocks-tiptap 5.6.0 → 6.1.0

package/dist/blocks/TiptapMentionInput/suggestion.js

@@ -50,27 +50,67 @@ function suggestion({ methods, char = '@', allowSpaces = true, limit = 5 }) {
         render: ()=>{
             let component;
             let popup;
-            return {
-                onStart: (props)=>{
-                    component = new ReactRenderer(MentionList, {
-                        props: {
-                            ...props,
-                            methods
-                        },
-                        editor: props.editor
-                    });
-                    if (!props.clientRect) return;
-                    popup = tippy('body', {
-                        getReferenceClientRect: props.clientRect,
-                        appendTo: ()=>document.body,
-                        content: component.element,
-                        showOnCreate: true,
-                        interactive: true,
-                        trigger: 'manual',
-                        placement: 'bottom-start'
+            let current;
+            const start = (props)=>{
+                current = {
+                    from: props.range.from,
+                    query: props.query
+                };
+                component = new ReactRenderer(MentionList, {
+                    props: {
+                        ...props,
+                        methods
+                    },
+                    editor: props.editor
+                });
+                if (!props.clientRect) return;
+                popup = tippy('body', {
+                    getReferenceClientRect: props.clientRect,
+                    appendTo: ()=>document.body,
+                    content: component.element,
+                    showOnCreate: true,
+                    interactive: true,
+                    trigger: 'manual',
+                    placement: 'bottom-start'
+                });
+            };
+            const exit = ()=>{
+                // Tear down in this order — React portal first, tippy popup after —
+                // to avoid "NotFoundError: Failed to execute 'removeChild'" when the
+                // user navigates away (e.g. clicks another item) while the mention
+                // popup is open. MentionList is rendered as a React portal into
+                // component.element, which tippy relocates into document.body.
+                // Destroying tippy first detaches that container out from under
+                // React's portal teardown; destroying the component first lets React
+                // remove the MentionList DOM cleanly while the container is still
+                // attached. The tippy teardown is then deferred to a microtask so it
+                // never runs synchronously inside React's own unmount commit.
+                component?.destroy();
+                component = undefined;
+                const instance = popup?.[0];
+                popup = undefined;
+                if (instance && !instance.state.isDestroyed) {
+                    queueMicrotask(()=>{
+                        if (!instance.state.isDestroyed) instance.destroy();
                     });
-                },
+                }
+            };
+            return {
+                onStart: start,
                 onUpdate (props) {
+                    // A suggestion that moves to a new trigger with a new query (e.g. a
+                    // second "@" typed while the first was open) restarted in TipTap v2,
+                    // which also showed a popup that an outside click had hidden. v3
+                    // reports it as an update, so restart it here.
+                    if (props.range.from !== current?.from && props.query !== current?.query) {
+                        exit();
+                        start(props);
+                        return;
+                    }
+                    current = {
+                        from: props.range.from,
+                        query: props.query
+                    };
                     component?.updateProps(props);
                     if (!props.clientRect) return;
                     popup?.[0]?.setProps({
@@ -84,27 +124,7 @@ function suggestion({ methods, char = '@', allowSpaces = true, limit = 5 }) {
                     }
                     return component?.ref?.onKeyDown(props) ?? false;
                 },
-                onExit () {
-                    // Tear down in this order — React portal first, tippy popup after —
-                    // to avoid "NotFoundError: Failed to execute 'removeChild'" when the
-                    // user navigates away (e.g. clicks another item) while the mention
-                    // popup is open. MentionList is rendered as a React portal into
-                    // component.element, which tippy relocates into document.body.
-                    // Destroying tippy first detaches that container out from under
-                    // React's portal teardown; destroying the component first lets React
-                    // remove the MentionList DOM cleanly while the container is still
-                    // attached. The tippy teardown is then deferred to a microtask so it
-                    // never runs synchronously inside React's own unmount commit.
-                    component?.destroy();
-                    component = undefined;
-                    const instance = popup?.[0];
-                    popup = undefined;
-                    if (instance && !instance.state.isDestroyed) {
-                        queueMicrotask(()=>{
-                            if (!instance.state.isDestroyed) instance.destroy();
-                        });
-                    }
-                }
+                onExit: exit
             };
         }
     };

package/dist/blocks/TiptapMentionInput/tests/TiptapMentionInput.e2e.yaml

@@ -0,0 +1,140 @@
+# Copyright 2020-2026 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+id: tiptap-mention-input
+type: Box
+
+events:
+  onMount:
+    - id: seed_content
+      type: SetState
+      params:
+        tiptap_mention_with_value:
+          html: '<p>Hi <span class="tiptap-mention">@Alice</span>.</p>'
+        tiptap_mention_disabled:
+          html: '<p>Disabled mention editor.</p>'
+        # Saved html round-trip: a mention node comes back with a STRING id
+        # (data-id) and its label in data-label.
+        tiptap_mention_saved:
+          html: '<p>Ping <span data-type="mention" class="tiptap-mention" data-id="user_9" data-label="Zed" data-mention-suggestion-char="@">@Zed</span> please.</p>'
+
+blocks:
+  - id: tiptap_mention_empty
+    type: TiptapMentionInput
+
+  - id: tiptap_mention_placeholder
+    type: TiptapMentionInput
+    properties:
+      placeholder: 'Type @ to mention...'
+
+  - id: tiptap_mention_with_value
+    type: TiptapMentionInput
+
+  - id: tiptap_mention_disabled
+    type: TiptapMentionInput
+    properties:
+      disabled: true
+
+  - id: tiptap_mention_options
+    type: TiptapMentionInput
+    properties:
+      placeholder: 'Try @A'
+      mentions:
+        options:
+          - label: Alice
+            value:
+              _id: user_1
+          - label: Bob
+            value:
+              _id: user_2
+
+  - id: tiptap_mention_saved
+    type: TiptapMentionInput
+
+  # Options whose value has no scalar identity (the shape an app passes when
+  # the whole contact record is the value) — data-id must be omitted, never
+  # "[object Object]".
+  - id: tiptap_mention_object_values
+    type: TiptapMentionInput
+    properties:
+      placeholder: 'Try @C'
+      mentions:
+        options:
+          - label: Carol
+            value:
+              contact_id: c_1
+              name: Carol
+              email: carol@example.com
+
+  - id: tiptap_mention_groups
+    type: TiptapMentionInput
+    properties:
+      title: Group mentions playground
+      placeholder: 'Type @ — People + Roles sections, group chips, hover members'
+      mentions:
+        limit: 3
+        groupMembers:
+          finance:
+            - name: Jane Doe
+              email: jane@example.com
+            - name: John Smith
+              email: john@example.com
+          devs:
+            - name: Ada Lovelace
+              email: ada@example.com
+            - name: Alan Turing
+              email: alan@example.com
+        # people carry value.href → <a>; groups omit it → nullish → <span>
+        getHref:
+          _function:
+            __args: 0.value.href
+        options:
+          - label: Alice
+            value:
+              name: Alice
+              href: '/contacts?_id=user_1'
+            tag:
+              section: People
+          - label: Amir
+            value:
+              name: Amir
+              href: '/contacts?_id=user_2'
+            tag:
+              section: People
+          - label: Anna
+            value:
+              name: Anna
+              href: '/contacts?_id=user_3'
+            tag:
+              section: People
+          - label: Aaron
+            value:
+              name: Aaron
+              href: '/contacts?_id=user_4'
+            tag:
+              section: People
+          - label: Finance
+            value:
+              role: finance-admin
+            tag:
+              section: Roles
+              group: finance
+              color: '#722ed1'
+          - label: Developers
+            value:
+              role: developer
+            tag:
+              section: Roles
+              group: devs
+              color: '#13c2c2'

package/dist/blocks/TiptapMentionInput/tests.yaml

@@ -0,0 +1,90 @@
+# Copyright 2020-2026 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+- id: default
+  type: TiptapMentionInput
+- id: properties.placeholder
+  type: TiptapMentionInput
+  properties:
+    placeholder: 'Type @ to mention...'
+- id: properties.disabled
+  type: TiptapMentionInput
+  properties:
+    disabled: true
+- id: properties.mentions.options
+  type: TiptapMentionInput
+  properties:
+    mentions:
+      options:
+        - label: Alice
+          value:
+            _id: user_1
+        - label: Bob
+          value:
+            _id: user_2
+- id: properties.mentions.char = '#'
+  type: TiptapMentionInput
+  properties:
+    placeholder: 'Type # to tag'
+    mentions:
+      char: '#'
+      options:
+        - label: bug
+          value:
+            _id: tag_bug
+- id: properties.mentions.limit with sections
+  type: TiptapMentionInput
+  properties:
+    mentions:
+      limit: 2
+      options:
+        - label: Alice
+          value:
+            _id: user_1
+          tag:
+            section: People
+        - label: Bob
+          value:
+            _id: user_2
+          tag:
+            section: People
+        - label: Finance
+          value:
+            _id: role_finance
+          tag:
+            section: Roles
+- id: properties.mentions group chips with tag.color
+  type: TiptapMentionInput
+  properties:
+    mentions:
+      options:
+        - label: Alice
+          value:
+            _id: user_1
+          tag:
+            section: People
+        - label: Finance
+          value:
+            role: finance-admin
+          tag:
+            section: Roles
+            group: finance
+            color: '#722ed1'
+        - label: Developers
+          value:
+            role: developer
+          tag:
+            section: Roles
+            group: devs
+            color: '#13c2c2'

package/dist/blocks/TiptapMentionInput/useTiptapMentionState.js

@@ -14,10 +14,10 @@
   limitations under the License.
 */ import { useRef } from 'react';
 import TurndownService from 'turndown';
-import s3FileUpload from '../utils/s3FileUpload.js';
+import fileUpload from '../utils/fileUpload.js';
 // Ref-tracked controller for the mention editor's value. Mirrors TiptapInput's
 // useTiptapState but also extracts mentions from the document.
-function useTiptapMentionState({ value, methods }) {
+function useTiptapMentionState({ value, methods, hasDownloadRequest }) {
     const valueRef = useRef(value);
     valueRef.current = value;
     const turndownService = new TurndownService();
@@ -60,9 +60,10 @@ function useTiptapMentionState({ value, methods }) {
         });
     };
     const insertImage = async (editor, file, pos)=>{
-        const url = await s3FileUpload({
+        const url = await fileUpload({
             file,
-            methods
+            methods,
+            hasDownloadRequest
         });
         // The upload is async: bail if the editor was torn down meanwhile (e.g. the
         // surrounding page navigated away before the upload resolved), otherwise the

package/dist/blocks/utils/PopoverMenu.js

@@ -35,36 +35,69 @@ const HIGHLIGHT_SWATCHES = [
         fill: 'rgba(170, 0, 255, 0.5)'
     }
 ];
+// Placement of the TipTap v2 (tippy.js) bubble menu: 10px above the selection,
+// flipping below when that would leave less than 5px to the viewport edge, and
+// kept 5px from the sides. v3 positions the menu with Floating UI and applies
+// the offset after flip, so flip's padding includes the offset.
+const FLOATING_OPTIONS = {
+    placement: 'top',
+    offset: 10,
+    flip: {
+        padding: 15
+    },
+    shift: {
+        padding: 5
+    }
+};
 function hasExt(editor, name) {
     return editor.extensionManager.extensions.some((ext)=>ext.name === name);
 }
+function createMenuElements() {
+    if (typeof document === 'undefined') return null;
+    // `root` is the element the plugin positions and mounts, like tippy's root
+    // in v2 (same z-index). `content` is the styled menu the buttons render into.
+    // The root is absolute from the start so the plugin measures its final size
+    // the first time it positions it.
+    const root = document.createElement('div');
+    root.style.position = 'absolute';
+    root.style.visibility = 'hidden';
+    root.style.zIndex = '9999';
+    const content = document.createElement('div');
+    content.className = 'tiptap-popover';
+    root.appendChild(content);
+    return {
+        root,
+        content
+    };
+}
 // Custom bubble menu built on tiptap's BubbleMenuPlugin instead of the
-// `<BubbleMenu>` React wrapper. The wrapper renders its menu element with
-// React and then the plugin calls `element.remove()` on it (bubble-menu-plugin
-// detaches the menu from the DOM on construction). When the editor block later
-// unmounts — e.g. the surrounding page navigates away, or `disabled` flips and
-// unmounts this menu — React tries to removeChild an element that is no longer
-// where it rendered it, throwing "NotFoundError: Failed to execute
-// 'removeChild' on 'Node'".
+// `<BubbleMenu>` React wrapper. The plugin moves its menu element in and out of
+// the DOM itself. When the editor block later unmounts — e.g. the surrounding
+// page navigates away, or `disabled` flips and unmounts this menu — React
+// would try to removeChild an element that is no longer where it rendered it,
+// throwing "NotFoundError: Failed to execute 'removeChild' on 'Node'".
 //
-// Here we own the container element ourselves and render the buttons into it
-// with a portal. React only ever removes the buttons from our container (always
-// their parent), never the plugin-detached element, so the teardown race is
-// gone.
+// Here we own the menu elements ourselves and render the buttons into them
+// with a portal. React only ever removes the buttons from our content element
+// (always their parent), never the plugin-managed root, so the teardown race
+// is gone.
 const PopoverMenu = ({ editor })=>{
-    const [container] = useState(()=>typeof document === 'undefined' ? null : document.createElement('div'));
+    const [menu] = useState(createMenuElements);
     const showBold = hasExt(editor, 'bold');
     const showItalic = hasExt(editor, 'italic');
     const showStrike = hasExt(editor, 'strike');
     const showHighlight = hasExt(editor, 'highlight');
     const hasTools = showBold || showItalic || showStrike || showHighlight;
     useEffect(()=>{
-        if (!container || !editor || editor.isDestroyed || !hasTools) return undefined;
-        container.className = 'tiptap-popover';
+        if (!menu || !editor || editor.isDestroyed || !hasTools) return undefined;
         const plugin = BubbleMenuPlugin({
             pluginKey: 'bubbleMenu',
             editor,
-            element: container,
+            element: menu.root,
+            // v2 mounted the menu beside the editor wrapper; v3 defaults to inside it.
+            // `options.element` is the EditorContent wrapper once it has mounted.
+            appendTo: ()=>editor.options.element?.parentElement,
+            options: FLOATING_OPTIONS,
             shouldShow: ({ editor: menuEditor, view, state, from, to })=>{
                 if (menuEditor.isActive('image')) return false;
                 const { selection } = state;
@@ -79,19 +112,19 @@ const PopoverMenu = ({ editor })=>{
         });
         editor.registerPlugin(plugin);
         return ()=>{
-            // Tear the plugin (and its tippy instance) down first. React then
-            // unmounts the portal, removing the buttons from our still-intact
-            // container.
+            // Tear the plugin down first (it removes the root from the DOM). React
+            // then unmounts the portal, removing the buttons from our still-intact
+            // content element.
             if (!editor.isDestroyed) {
                 editor.unregisterPlugin('bubbleMenu');
             }
         };
     }, [
         editor,
-        container,
+        menu,
         hasTools
     ]);
-    if (!container || !hasTools) return null;
+    if (!menu || !hasTools) return null;
     return /*#__PURE__*/ createPortal(/*#__PURE__*/ React.createElement(React.Fragment, null, showBold && /*#__PURE__*/ React.createElement(AiOutlineBold, {
         className: "tiptap-icon",
         onClick: ()=>editor.chain().focus().toggleBold().run()
@@ -110,6 +143,6 @@ const PopoverMenu = ({ editor })=>{
             onClick: ()=>editor.chain().focus().toggleHighlight({
                     color: fill
                 }).run()
-        }))), container);
+        }))), menu.content);
 };
 export default PopoverMenu;

package/dist/blocks/utils/buildExtensions.js

@@ -15,14 +15,11 @@
 */ import FileHandler from '@tiptap/extension-file-handler';
 import Highlight from '@tiptap/extension-highlight';
 import Image from '@tiptap/extension-image';
-import Placeholder from '@tiptap/extension-placeholder';
-import StarterKit from '@tiptap/starter-kit';
+import { Placeholder } from '@tiptap/extensions';
 import LinkExtension from '@tiptap/extension-link';
-import Table from '@tiptap/extension-table';
-import TableCell from '@tiptap/extension-table-cell';
-import TableHeader from '@tiptap/extension-table-header';
-import TableRow from '@tiptap/extension-table-row';
+import { Table, TableCell, TableHeader, TableRow } from '@tiptap/extension-table';
 import { type } from '@lowdefy/helpers';
+import buildStarterKit from './buildStarterKit.js';
 const DEFAULT_IMAGE_MIME_TYPES = [
     'image/jpeg',
     'image/png',
@@ -58,15 +55,14 @@ function merge(defaults, overrides) {
         ...overrides
     };
 }
-function buildExtensions({ properties, insertImage, mentionExtension, uploadEnabled }) {
+function buildExtensions({ properties, getPlaceholder, insertImage, mentionExtension, uploadEnabled }) {
     const image = merge(DEFAULTS.image, properties.image);
     const table = merge(DEFAULTS.table, properties.table);
     const link = merge(DEFAULTS.link, properties.link);
     const highlight = merge(DEFAULTS.highlight, properties.highlight);
-    const starterKitOptions = type.isObject(properties.starterKit) ? properties.starterKit : {};
     const allowedMimeTypes = type.isArray(properties.allowedMimeTypes) ? properties.allowedMimeTypes : DEFAULT_IMAGE_MIME_TYPES;
     const extensions = [
-        StarterKit.configure(starterKitOptions)
+        buildStarterKit(properties.starterKit)
     ];
     if (!table.disabled) {
         extensions.push(Table.configure({
@@ -84,9 +80,8 @@ function buildExtensions({ properties, insertImage, mentionExtension, uploadEnab
         }));
     }
     extensions.push(Placeholder.configure({
-        placeholder: ()=>properties.placeholder ?? '',
-        showOnlyWhenEditable: false,
-        considerAnyAsEmpty: true
+        placeholder: getPlaceholder,
+        showOnlyWhenEditable: false
     }));
     if (!highlight.disabled) {
         extensions.push(Highlight.configure({
@@ -101,7 +96,10 @@ function buildExtensions({ properties, insertImage, mentionExtension, uploadEnab
             autolink: link.autolink,
             linkOnPaste: link.linkOnPaste,
             openOnClick: link.openOnClick,
-            defaultProtocol: link.defaultProtocol
+            defaultProtocol: link.defaultProtocol,
+            // TipTap v2's default. v3's default also skips bare IP addresses and hosts without a TLD
+            // (e.g. localhost:3000), and applies to pasted URLs too.
+            shouldAutoLink: (url)=>!!url
         }));
     }
     if (mentionExtension) {

package/dist/blocks/utils/buildStarterKit.js

@@ -0,0 +1,48 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import StarterKit from '@tiptap/starter-kit';
+import { type } from '@lowdefy/helpers';
+// TipTap v3's StarterKit bundles extensions the v2 kit did not. They default to off so the
+// editor keeps its v2 extension set: Underline would keep <u> in the saved html, TrailingNode
+// appends an empty paragraph after a final table or image, and ListKeymap changes Backspace and
+// Delete in lists.
+const V3_KIT_DEFAULTS = {
+    listKeymap: false,
+    trailingNode: false,
+    underline: false
+};
+// Builds the StarterKit from the block's `starterKit` property, which is written against the v2
+// kit, so that it enables the same extensions as v2 did.
+function buildStarterKit(starterKit) {
+    const { history, ...options } = type.isObject(starterKit) ? starterKit : {};
+    // v3 renamed the History extension to UndoRedo.
+    if (!type.isUndefined(history) && type.isUndefined(options.undoRedo)) {
+        options.undoRedo = history;
+    }
+    // v3 CodeBlock inserts a paragraph above a code block at the top of the document on ArrowUp.
+    if (options.codeBlock !== false) {
+        options.codeBlock = {
+            exitOnArrowUp: false,
+            ...type.isObject(options.codeBlock) ? options.codeBlock : {}
+        };
+    }
+    return StarterKit.configure({
+        ...V3_KIT_DEFAULTS,
+        ...options,
+        // The Link extension is added by buildExtensions from the block's `link` property.
+        link: false
+    });
+}
+export default buildStarterKit;

package/dist/blocks/utils/fileUpload.js

@@ -0,0 +1,63 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import getLegacyObjectUrl from '@lowdefy/blocks-files/utils/getLegacyObjectUrl.js';
+import getUploadPolicy from '@lowdefy/blocks-files/utils/getUploadPolicy.js';
+import uploadFile from '@lowdefy/blocks-files/utils/uploadFile.js';
+// Uploads a file through the app's upload-policy request (any storage
+// provider) and resolves a display URL for the inline image. Inline images
+// persist in saved markdown, so they must be public assets: the upload
+// request should set the provider's public-read acl, and the download request
+// should set public: true to return a stable, non-expiring URL. Without a
+// download request the legacy unsigned object URL is used (S3-shaped,
+// deprecated).
+async function fileUpload({ file, methods, hasDownloadRequest }) {
+    if (type.isNone(file)) {
+        return;
+    }
+    const descriptor = await getUploadPolicy({
+        methods,
+        file
+    });
+    file.bucket = descriptor.bucket;
+    file.key = descriptor.key;
+    await uploadFile({
+        descriptor,
+        file
+    });
+    if (hasDownloadRequest) {
+        const response = await methods.triggerEvent({
+            name: '__getDownloadPolicy',
+            event: {
+                file: {
+                    bucket: descriptor.bucket,
+                    key: descriptor.key,
+                    name: file.name,
+                    type: file.type
+                }
+            }
+        });
+        if (response.success !== true) {
+            throw new Error('Download policy request error.');
+        }
+        file.url = response.responses.__getDownloadPolicy.response[0];
+        return file.url;
+    }
+    file.url = getLegacyObjectUrl({
+        descriptor
+    });
+    return file.url;
+}
+export default fileUpload;

package/dist/blocks/utils/statusClass.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */ // Map validation.status → wrapper class. Matches the visual behavior of
 // passing status="error" | "warning" to an antd <Input />, but rendered
-// with our own CSS (see utils/style.module.css) because antd v6 uses
+// with our own CSS (see utils/style.css) because antd v6 uses
 // CSS-in-JS, so the .ant-input-status-* classes are not global.
 function statusClass(status) {
     if (status === 'error') return 'tiptap-wrapper-error';