npm package: @paroicms/quill-delta-to-tiptap-json
Description: Convert Quill Delta to Tiptap JSON
Author: Paroi Team
Latest version: 0.2.12

# @paroicms/quill-delta-to-tiptap-json

A lightweight JavaScript/TypeScript library for converting Quill Delta JSON to Tiptap JSON without any dependency. This package provides naive and fast server-side conversion of Quill Delta operations to Tiptap JSON.

## Installation

```bash
npm install @paroicms/quill-delta-to-tiptap-json
```

## Usage

```typescript
import { convertQuillDeltaToTiptap } from "@paroicms/quill-delta-to-tiptap-json";

const quillDelta = {
  ops: [
    { insert: "Hello World", attributes: { bold: true } },
    { insert: "\n", attributes: { header: 1 } },
    // ...
  ],
};

const { result, issues } = convertQuillDeltaToTiptap(quillDelta);

console.log(JSON.stringify(result, null, 2));
// {
//   "type": "doc",
//   "content": [
//     {
//       "type": "heading",
//       "attrs": { "level": 1 },
//       "content": [
//         { "type": "text", "text": "Hello World", "marks": [{ "type": "bold" }] }
//       ]
//     },
//     // ...
//   ]
// }

// Check for any issues during conversion
if (issues) {
  console.warn("Conversion issues:", issues);
}
```

### Custom Converters

You can extend the converter with custom handlers for inline formats, block formats, and embeds:

```typescript
const { result, issues } = convertQuillDeltaToTiptap(quillDelta, {
  customConverters: {
    // Custom inline format (mark)
    inlineFormats: {
      underline: (value, context) => ({
        type: "underline",
      }),
    },
    // Custom block format
    blockFormats: {
      align: (content, value, context) => ({
        type: "paragraph",
        attrs: { textAlign: value },
        content,
      }),
    },
    // Custom embed type
    embeds: {
      image: (value, context) => ({
        type: "image",
        attrs: {
          src: value,
          alt: null,
          title: null,
        },
      }),
      video: (value, context) => ({
        type: "video",
        attrs: { src: value },
      }),
    },
  },
  // Ignore specific attributes (color and background are ignored by default, set to [] to keep them)
  ignoreAttributes: ["color", "background", "font"],
});
```

### Remapping Built-in Formats

You can use custom converters to remap Quill's built-in formats to different Tiptap marks. For example, to convert Quill's `underline` format to Tiptap's `italic` mark (mapping `<u>` to `<em>`):

```typescript
const { result } = convertQuillDeltaToTiptap(quillDelta, {
  customConverters: {
    inlineFormats: {
      // Map underline to italic/emphasis
      underline: (value) => (value ? { type: "italic" } : undefined),
    },
  },
});
```

This pattern is useful when migrating content and you want to change the semantic meaning of certain formats. The value check ensures that falsy values (like `{ underline: false }`) don't add the mark.

## API

### `convertQuillDeltaToTiptap(input: QuillDelta | string, options?: ConverterOptions): ConversionResult`

Converts a Quill Delta object or JSON string to Tiptap JSON format.

**Parameters:**

- `input`: Quill Delta object
- `options` (optional): Configuration options
  - `customConverters`: Custom converter functions for inline formats, block formats, and embeds
  - `ignoreAttributes`: Array of attribute names to ignore (default: `["color", "background"]`)

**Returns:** `ConversionResult` object containing:

- `result`: The Tiptap JSON document (type `TiptapJsonValue`)
- `issues` (optional): Array of warning messages for skipped or unsupported content

## Supported Quill Delta Features

### Block-Level Formats

- **Headings**: `{ header: 1 }` through `{ header: 6 }` → Tiptap headings with bold marks
- **Paragraphs**: Default block type for regular text
- **Blockquotes**: `{ blockquote: true }`
- **Code blocks**: `{ "code-block": true }` or `{ "code-block": "language" }` (with language)
- **Lists**:
  - Bullet lists: `{ list: "bullet" }`
  - Ordered lists: `{ list: "ordered" }`
  - Nested lists: Supported via `{ indent: level }` attribute

### Inline Formats (Marks)

- **Bold**: `{ bold: true }`
- **Italic**: `{ italic: true }`
- **Strikethrough**: `{ strike: true }`
- **Inline code**: `{ code: true }`
- **Superscript**: `{ script: "super" }` → Converted to `superscript` mark
- **Subscript**: `{ script: "sub" }` → Converted to `subscript` mark
- **Links**: `{ link: "url" }` → Converted with target="_blank" and security attributes

### Embeds

Embeds are handled through the `customConverters.embeds` option. Common embed types include:

- Images: `{ insert: { image: "url" } }`
- Videos: `{ insert: { video: "url" } }`
- Custom embeds: Any object-type insert can be handled with a custom converter

### Special Handling

- **Empty documents**: Returns empty doc with no issues
- **Unsupported attributes**: Logged in `issues` array (except `size` which is silently ignored)
- **Ignored attributes**: Color and background are ignored by default (customizable via options)
- **Malformed JSON**: Returns empty doc with error in `issues`
- **Mixed embeds and text**: Supported on the same line

## Differences from Quill

- **Color/background**: Ignored by default (not standard Tiptap features)

## License

MIT

## Related Packages

This package can be used as a standalone library. It's also part of the ParoiCMS ecosystem. For more information, visit the [ParoiCMS repository](https://gitlab.com/paroi/opensource/paroicms).