tessl/npm-tiptap--extension-gapcursor

Gapcursor extension for Tiptap that enables cursor placement in positions where no content is present, such as between nodes or after tables

—

Pending

Overview

Eval results

Files

Tiptap Extension: Gapcursor

Name: tessl/npm-tiptap--extension-gapcursor
Author: tessl

The @tiptap/extension-gapcursor package provides a gapcursor extension for Tiptap editors that enables cursor placement in positions where no content is present, such as between nodes or after tables at the end of a document. This extension wraps the ProseMirror Gapcursor plugin and integrates it seamlessly with Tiptap's extension system.

Package Information

Package Name: @tiptap/extension-gapcursor
Package Type: npm
Language: TypeScript
Installation: npm install @tiptap/extension-gapcursor
Status: Deprecated (use @tiptap/extensions instead)

Core Imports

import { Gapcursor } from "@tiptap/extension-gapcursor";

Default import:

import Gapcursor from "@tiptap/extension-gapcursor";

For CommonJS:

const { Gapcursor } = require("@tiptap/extension-gapcursor");

Basic Usage

import { Editor } from "@tiptap/core";
import { Gapcursor } from "@tiptap/extension-gapcursor";

// Add the gapcursor extension to your editor
const editor = new Editor({
  extensions: [
    Gapcursor,
    // ... other extensions
  ],
  content: '<p>Your content here</p>',
});

Advanced usage with configuration:

import { Editor } from "@tiptap/core";
import { Gapcursor } from "@tiptap/extension-gapcursor";

const editor = new Editor({
  extensions: [
    Gapcursor.configure({
      // Configuration options if needed
    }),
    // ... other extensions
  ],
  content: '<p>Your content</p>',
});

Architecture

The extension follows Tiptap's standard extension architecture:

Extension Class: Extends the base Tiptap Extension class with name 'gapCursor'
ProseMirror Integration: Adds the ProseMirror gapcursor plugin via addProseMirrorPlugins() using gapCursor() from prosemirror-gapcursor
Schema Extension: Extends node schemas with allowGapCursor property through extendNodeSchema()
Re-export Pattern: This package is a simple wrapper that re-exports from @tiptap/extensions
Dependencies: Built on top of ProseMirror's prosemirror-gapcursor plugin

Capabilities

Gapcursor Extension

The main extension class that provides gap cursor functionality for Tiptap editors.

/**
 * Gapcursor extension that enables cursor placement where no content is present
 * Extends the base Tiptap Extension class with name 'gapCursor'
 * @see https://tiptap.dev/api/extensions/gapcursor
 */
export const Gapcursor: Extension<{}, {}>;

/**
 * Default export of the Gapcursor extension
 */
export default Gapcursor;

Extension Configuration

The Gapcursor extension can be configured using the standard Tiptap extension configuration pattern.

/**
 * Configure the Gapcursor extension with options
 * @param options - Configuration options (currently accepts empty object)
 * @returns Configured Gapcursor extension instance
 */
Gapcursor.configure(options?: {}): Extension<{}, {}>;

/**
 * Extend the Gapcursor extension with additional configuration
 * @param config - Extension configuration or function returning configuration
 * @returns Extended Gapcursor extension instance
 */
Gapcursor.extend<ExtendedOptions, ExtendedStorage>(
  config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
): Extension<ExtendedOptions, ExtendedStorage>;

Node Schema Extension

The extension adds support for the allowGapCursor property to node configurations.

/**
 * Node configuration property for controlling gap cursor behavior
 * Added to NodeConfig interface via module augmentation
 */
interface NodeConfig<Options, Storage> {
  /**
   * A function to determine whether the gap cursor is allowed at the current position. Must return `true` or `false`.
   * @default null
   */
  allowGapCursor?:
    | boolean
    | null
    | ((this: {
        name: string
        options: Options
        storage: Storage
        parent: ParentConfig<NodeConfig<Options>>['allowGapCursor']
      }) => boolean | null)
}

Extension Methods

addProseMirrorPlugins

/**
 * Adds ProseMirror plugins to the editor
 * @returns Array containing the ProseMirror gapcursor plugin from prosemirror-gapcursor
 */
addProseMirrorPlugins(): ProseMirrorPlugin[];

extendNodeSchema

/**
 * Extends node schema with gap cursor configuration
 * @param extension - The extension instance
 * @returns Schema extension object with allowGapCursor property
 */
extendNodeSchema(extension: Extension): {
  allowGapCursor: boolean | null;
};

Types

/**
 * Base Extension class from @tiptap/core
 * All Tiptap extensions extend this class
 */
declare class Extension<Options = any, Storage = any> {
  type: 'extension';
  static create<O = any, S = any>(
    config?: Partial<ExtensionConfig<O, S>>
  ): Extension<O, S>;
  configure(options?: Partial<Options>): Extension<Options, Storage>;
  extend<ExtendedOptions, ExtendedStorage>(
    config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
  ): Extension<ExtendedOptions, ExtendedStorage>;
}

/**
 * Extension configuration interface
 */
interface ExtensionConfig<Options = any, Storage = any> {
  name?: string;
  priority?: number;
  defaultOptions?: Options;
  addStorage?: () => Storage;
  addProseMirrorPlugins?: () => ProseMirrorPlugin[];
  extendNodeSchema?: (extension: Extension) => Record<string, any>;
}

/**
 * Parent configuration context for nested extension configurations
 */
interface ParentConfig<T> {
  allowGapCursor?: T;
}

/**
 * ProseMirror Plugin interface
 */
interface ProseMirrorPlugin {
  // Plugin implementation details
}

Error Handling

The Gapcursor extension generally operates transparently and does not throw specific errors. Error handling typically occurs at the editor level. Common issues:

Import Errors: Ensure @tiptap/extension-gapcursor is installed and imported correctly
Configuration Errors: Verify extension configuration syntax matches Tiptap standards
Plugin Conflicts: Some ProseMirror plugins may conflict; check for plugin compatibility

Migration Notes

This package is deprecated in favor of using @tiptap/extensions directly:

// Deprecated approach (re-exports from @tiptap/extensions)
import { Gapcursor } from "@tiptap/extension-gapcursor";

// Recommended approach (direct import from consolidated package)
import { Gapcursor } from "@tiptap/extensions";

// You can also import from specific subpath
import { Gapcursor } from "@tiptap/extensions/gap-cursor";

Both approaches provide identical functionality, but the consolidated package reduces dependency overhead. The deprecated package is simply a wrapper that re-exports the same Gapcursor extension from @tiptap/extensions.

Install with Tessl CLI

npx tessl i tessl/npm-tiptap--extension-gapcursor

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/@tiptap/extension-gapcursor@3.4.x
Badge