@tiptap/suggestion 3.26.1 → 3.27.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Middleware, AutoUpdateOptions } from '@floating-ui/dom';
 import { Range, Editor } from '@tiptap/core';
 import { PluginKey, Transaction, EditorState, Plugin } from '@tiptap/pm/state';
 import { EditorView } from '@tiptap/pm/view';
@@ -18,6 +19,56 @@ type SuggestionMatch = {
 } | null;
 declare function findSuggestionMatch(config: Trigger): SuggestionMatch;
 
+type SuggestionPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
+type SuggestionFloatingUiOptions = {
+    strategy?: 'absolute' | 'fixed';
+    middleware?: Middleware[];
+};
+type SuggestionFloatingUiConfig = {
+    placement: SuggestionPlacement;
+    strategy: 'absolute' | 'fixed';
+    middleware: Middleware[];
+};
+/**
+ * The computed position handed to a custom `onPosition` callback when using
+ * managed positioning via {@link SuggestionProps.mount}.
+ */
+type SuggestionPositionData = {
+    x: number;
+    y: number;
+    placement: SuggestionPlacement;
+    strategy: 'absolute' | 'fixed';
+};
+/**
+ * Options for managed mounting + positioning via {@link SuggestionProps.mount}.
+ */
+type SuggestionMountOptions = {
+    /**
+     * Override how the computed position is applied to the element.
+     * When provided, the plugin stops writing `style.left`/`style.top` itself and
+     * hands you the computed coordinates so you can apply them however you want
+     * (custom transforms, animation, writing to a framework ref, etc.).
+     */
+    onPosition?: (data: SuggestionPositionData) => void;
+    /**
+     * Options forwarded to Floating UI's `autoUpdate`. Use this to opt into
+     * `animationFrame` polling for anchors that move inside transformed or
+     * animated containers, or to disable specific observers.
+     * @see https://floating-ui.com/docs/autoUpdate
+     */
+    autoUpdate?: AutoUpdateOptions;
+};
+/**
+ * Mounts a floating element and takes over its positioning. The plugin appends
+ * the element into the configured `container` (default `document.body`), keeps
+ * it anchored to the suggestion's cursor rect, and automatically repositions it
+ * on scroll, resize, and layout shifts via Floating UI's `autoUpdate` — no
+ * manual listeners required.
+ *
+ * Returns an `unmount` function that tears down the listeners and removes the
+ * element (when the plugin mounted it). Call it from `onExit`.
+ */
+type SuggestionMount = (element: HTMLElement, options?: SuggestionMountOptions) => () => void;
 interface SuggestionOptions<I = any, TSelected = any> {
     /**
      * The plugin key for the suggestion plugin.
@@ -128,6 +179,67 @@ interface SuggestionOptions<I = any, TSelected = any> {
         range: Range;
         props: TSelected;
     }) => void;
+    /**
+     * Minimum query length before `items()` is called.
+     * When the query is shorter, empty items are passed to the renderer.
+     * @default 0 (no filter, same as before)
+     * @example 2
+     */
+    minQueryLength?: number;
+    /**
+     * Debounce in milliseconds. When set, `items()` will only be called
+     * after the user stops typing for this duration.
+     * @default 0 (no debounce, same as before)
+     * @example 300
+     */
+    debounce?: number;
+    /**
+     * Items shown immediately when the suggestion popup opens,
+     * before the async `items()` call resolves.
+     * Useful for showing recent or popular items while loading.
+     * @default undefined (no pre-populated items)
+     */
+    initialItems?: I[];
+    /**
+     * Placement of the popup relative to the cursor.
+     * Consumers can read this from `SuggestionProps` to configure their positioning library.
+     * @default 'bottom-start'
+     */
+    placement?: SuggestionPlacement;
+    /**
+     * Offset of the popup in pixels.
+     * Consumers can read this from `SuggestionProps` to configure their positioning library.
+     * @default { mainAxis: 4, crossAxis: 0 }
+     */
+    offset?: {
+        mainAxis?: number;
+        crossAxis?: number;
+    };
+    /**
+     * CSS selector or element that defines the containment context for the popup.
+     * Consumers can read this from `SuggestionProps` when rendering inside modals or dialogs.
+     * @default undefined (no containment)
+     */
+    container?: string | HTMLElement;
+    /**
+     * Whether the popup should automatically flip when there isn't enough space.
+     * Consumers can read this from `SuggestionProps` to configure their positioning library.
+     * @default true
+     */
+    flip?: boolean;
+    /**
+     * Additional Floating UI options and middleware passed through to the renderer.
+     * The plugin keeps ownership of the anchor and placement, but consumers can
+     * append custom middleware here.
+     */
+    floatingUi?: SuggestionFloatingUiOptions;
+    /**
+     * Dismiss the suggestion when the user interacts outside both the popup and
+     * the editor. Only applies when using managed mounting via
+     * {@link SuggestionProps.mount} (the plugin needs to know the popup element).
+     * @default true
+     */
+    dismissOnOutsideClick?: boolean;
     /**
      * A function that returns the suggestion items in form of an array.
      * @param props The props object.
@@ -139,6 +251,7 @@ interface SuggestionOptions<I = any, TSelected = any> {
     items?: (props: {
         query: string;
         editor: Editor;
+        signal: AbortSignal;
     }) => I[] | Promise<I[]>;
     /**
      * The render function for the suggestion.
@@ -165,6 +278,9 @@ interface SuggestionOptions<I = any, TSelected = any> {
     }) => boolean;
     findSuggestionMatch?: typeof findSuggestionMatch;
 }
+/**
+ * The props passed to the suggestion's render functions (onStart, onUpdate, onExit).
+ */
 interface SuggestionProps<I = any, TSelected = any> {
     /**
      * The editor instance.
@@ -203,18 +319,93 @@ interface SuggestionProps<I = any, TSelected = any> {
      * @example () => new DOMRect(0, 0, 0, 0)
      */
     clientRect?: (() => DOMRect | null) | null;
+    /**
+     * Placement of the popup relative to the cursor.
+     * @default 'bottom-start'
+     */
+    placement: SuggestionPlacement;
+    /**
+     * Offset of the popup in pixels.
+     * @default { mainAxis: 4, crossAxis: 0 }
+     */
+    offset: {
+        mainAxis: number;
+        crossAxis: number;
+    };
+    /**
+     * CSS selector or element that defines the containment context for the popup.
+     * @default undefined
+     */
+    container?: string | HTMLElement;
+    /**
+     * Whether the popup should automatically flip when there isn't enough space.
+     * @default true
+     */
+    flip: boolean;
+    /**
+     * Resolved Floating UI config for direct use with `computePosition()`.
+     * This is the escape hatch: reach for it only when you mount the element
+     * yourself and want to run the positioning loop manually instead of using
+     * {@link SuggestionProps.mount}.
+     */
+    floatingUi: SuggestionFloatingUiConfig;
+    /**
+     * Mounts your floating element and takes over positioning — the recommended,
+     * default way to render a suggestion popup.
+     *
+     * Pass the element you rendered (e.g. from `ReactRenderer`/`VueRenderer`). The
+     * plugin appends it into the configured `container` (default `document.body`),
+     * keeps it anchored to the cursor, and repositions it on scroll, resize, and
+     * layout shifts — no manual listeners required. Returns an `unmount` function
+     * that tears everything down; call it in `onExit`.
+     *
+     * Escape hatch: mount the element yourself and skip this, then run your own
+     * positioning loop with {@link SuggestionProps.floatingUi} +
+     * {@link SuggestionProps.clientRect}.
+     *
+     * @example
+     * ```ts
+     * onStart: props => {
+     *   component = new ReactRenderer(DropdownList, { props, editor: props.editor })
+     *   unmount = props.mount(component.element)
+     * },
+     * onExit: () => unmount?.(),
+     * ```
+     */
+    mount: SuggestionMount;
+    /**
+     * Whether the items are currently being loaded.
+     * `true` before the async `items()` call resolves.
+     * Useful for showing a loading spinner or skeleton.
+     * @default false
+     */
+    loading: boolean;
 }
+/**
+ * The props passed to the suggestion's onKeyDown render function
+ */
 interface SuggestionKeyDownProps {
     view: EditorView;
     event: KeyboardEvent;
     range: Range;
 }
+/** @internal Internal state shape for the suggestion plugin. */
+interface SuggestionPluginState {
+    active: boolean;
+    range: Range;
+    query: null | string;
+    text: null | string;
+    composing: boolean;
+    decorationId?: string | null;
+    dismissedRange: Range | null;
+}
+
 declare const SuggestionPluginKey: PluginKey<any>;
 /**
  * This utility allows you to create suggestions.
  * @see https://tiptap.dev/api/utilities/suggestion
  */
-declare function Suggestion<I = any, TSelected = any>({ pluginKey, editor, char, allowSpaces, allowToIncludeChar, allowedPrefixes, startOfLine, decorationTag, decorationClass, decorationContent, decorationEmptyClass, command, items, render, allow, findSuggestionMatch, shouldShow, shouldResetDismissed, }: SuggestionOptions<I, TSelected>): Plugin<any>;
+declare function Suggestion<I = any, TSelected = any>({ pluginKey, editor, char, allowSpaces, allowToIncludeChar, allowedPrefixes, startOfLine, decorationTag, decorationClass, decorationContent, decorationEmptyClass, command, items, minQueryLength, debounce, initialItems, placement, offset: offsetOption, container, flip, floatingUi, dismissOnOutsideClick, render, allow, findSuggestionMatch, shouldShow, shouldResetDismissed, }: SuggestionOptions<I, TSelected>): Plugin<SuggestionPluginState>;
 /**
  * Programmatically exit a suggestion plugin by dispatching a metadata-only
  * transaction. This is the safe, recommended API to remove suggestion
@@ -222,4 +413,4 @@ declare function Suggestion<I = any, TSelected = any>({ pluginKey, editor, char,
  */
 declare function exitSuggestion(view: EditorView, pluginKeyRef?: PluginKey): void;
 
-export { Suggestion, type SuggestionKeyDownProps, type SuggestionMatch, type SuggestionOptions, SuggestionPluginKey, type SuggestionProps, type Trigger, Suggestion as default, exitSuggestion, findSuggestionMatch };
+export { Suggestion, type SuggestionFloatingUiConfig, type SuggestionFloatingUiOptions, type SuggestionKeyDownProps, type SuggestionMatch, type SuggestionMount, type SuggestionMountOptions, type SuggestionOptions, type SuggestionPlacement, SuggestionPluginKey, type SuggestionPositionData, type SuggestionProps, type Trigger, Suggestion as default, exitSuggestion, findSuggestionMatch };