{"_id":"@buddhima_a/tiptap-diff-suggestions","name":"@buddhima_a/tiptap-diff-suggestions","dist-tags":{"beta":"0.1.0-beta","latest":"0.1.0-beta"},"versions":{"0.1.0-beta":{"name":"@buddhima_a/tiptap-diff-suggestions","version":"0.1.0-beta","description":"A TipTap extension for actionable inline content suggestions, comparisons, and diff review workflows","type":"module","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","dev":"rollup -c -w","type-check":"tsc --noEmit","clean":"rimraf dist"},"keywords":["tiptap","extension","diff","suggestions","editor","prosemirror","inline editing","collaborative review","content suggestions"],"author":{"name":"Buddhima Amarathunga"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bsachinthana/tiptap-diff-suggestions.git"},"peerDependencies":{"@tiptap/core":"^2.0.0","@tiptap/pm":"^2.0.0"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-typescript":"^11.1.5","@tiptap/core":"^2.26.1","@tiptap/pm":"^2.26.1","@types/node":"^20.10.5","rimraf":"^5.0.5","rollup":"^4.9.1","rollup-plugin-postcss":"^4.0.2","tslib":"^2.6.2","typescript":"^5.3.3"},"_id":"@buddhima_a/tiptap-diff-suggestions@0.1.0-beta","gitHead":"1e32a8918ac01ccd67954aa70696c82a71889eb2","bugs":{"url":"https://github.com/bsachinthana/tiptap-diff-suggestions/issues"},"homepage":"https://github.com/bsachinthana/tiptap-diff-suggestions#readme","_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-gxCuuSGk4XbTThIOBaNpjEGOQkTxE8mZvh04oc4OlbEevcJZ4lFkAWCL86Q1pwy9+A4mtltwhB/8vjMnXc9MuQ==","shasum":"f4fb1bfce23e209b92f28888bbf2d9631207fcd0","tarball":"https://registry.npmjs.org/@buddhima_a/tiptap-diff-suggestions/-/tiptap-diff-suggestions-0.1.0-beta.tgz","fileCount":18,"unpackedSize":82543,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/OuY52E1U3rJDD9457R4dPQSiXrEDIOvw+/K+QYHpVAIhAK6WIc+Z+PnMWnTxXUlVVha+GnRmFdWn940xQABbwOU2"}]},"_npmUser":{"name":"buddhima_a","email":"budd.amarathunga@gmail.com"},"directories":{},"maintainers":[{"name":"buddhima_a","email":"budd.amarathunga@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tiptap-diff-suggestions_0.1.0-beta_1752368511762_0.9972560956388818"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-13T01:01:51.694Z","0.1.0-beta":"2025-07-13T01:01:51.957Z","modified":"2025-07-13T01:01:52.217Z"},"maintainers":[{"name":"buddhima_a","email":"budd.amarathunga@gmail.com"}],"description":"A TipTap extension for actionable inline content suggestions, comparisons, and diff review workflows","homepage":"https://github.com/bsachinthana/tiptap-diff-suggestions#readme","keywords":["tiptap","extension","diff","suggestions","editor","prosemirror","inline editing","collaborative review","content suggestions"],"repository":{"type":"git","url":"git+https://github.com/bsachinthana/tiptap-diff-suggestions.git"},"author":{"name":"Buddhima Amarathunga"},"bugs":{"url":"https://github.com/bsachinthana/tiptap-diff-suggestions/issues"},"license":"MIT","readme":"# TipTap Diff Suggestions Extension\n\nA TipTap extension for inline comparison of content with suggested revisions, including interactive controls.\n\n## Idea/Goal\n\nThis extension provides a way to visualize and interact with suggested changes within a TipTap editor. It bridges the gap between static diff viewers and actionable content editing, allowing users to evaluate, accept, or reject suggestions directly in the editor.\n\n> ## Content\n> - [Use Cases](#use-cases)\n> - [Features](#features)\n> - [HTML Element Structure](#html-structure)\n> - [Installation](#installation)\n> - [Usage](#usage)\n>    - [Basic Setup](#basic-setup)\n>    - [Inserting diff Suggestions](#inserting-diff-suggestions)\n>    - [Set editor content with diff Suggestions](#setting-editor-content-with-diff-suggestion-html)\n>   - [Advanced Configuration with Side-effects](#advanced-configuration-with-side-effects)\n>   - [Custom Action Override](#custom-behavior-override)\n>\n> - [API Reference](#api-reference)\n> - [Styling](#styling)\n> - [Examples](#examples)\n> - [Development](#development)\n> - [Contributing](#contributing)\n>\n\n\n\n## Use Cases\n\n- **AI-Powered Writing Assistance**: Displaying and managing suggestions from AI writing tools.\n- **Collaborative Content Review**: Facilitating editorial suggestions and peer review workflows.\n- **Translation and Localization**: Presenting and integrating translation suggestions.\n\n## Features\n\n- 📝 **Interactive Diff Visualization**: Inline comparison with accept/reject controls\n- 🎯 **Customizable Actions**: From simple buttons to complex approval workflows  \n- 💬 **Contextual Comments**: Add explanations and reasoning to suggestions\n- 🎨 **Headless Design**: No built-in styles - from quick prototyping to fully branded experiences\n- 🔧 **Extensible Toolbar**: Custom action panels and interactive elements\n- 🎭 **CSS Variables**: Themeable styling system with dark mode support\n- 🚀 **Framework Agnostic**: Leverages TipTap's framework-agnostic architecture\n- 📦 **TypeScript Ready**: Full type definitions for better developer experience\n- ⚡ **Side-effect Hooks**: Integrate with external systems and workflows\n\n## HTML Structure\n\nThe extension generates the following HTML structure:\n\n```html\n<span data-diff-suggestion data-diff-suggestion-id=\"unique-id\" data-diff-suggestion-comment=\"reason for suggestion\">\n  <span data-diff-suggestion-old>Original text</span>\n  <span data-diff-suggestion-new>Suggested text</span>\n</span>\n```\n\n## Installation\n\n```bash\nnpm install @buddhima_a/tiptap-diff-suggestions\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport { Editor } from '@tiptap/core';\nimport { DiffSuggestion } from '@buddhima_a/tiptap-diff-suggestions';\n\nconst editor = new Editor({\n  extensions: [\n    DiffSuggestion,\n    // ... other extensions\n  ],\n});\n```\n> #### ⚠️ Headless Architecture\n> Following TipTap's headless architecture, this extension includes no built-in styling. \n> For rapid prototyping, use the included sample CSS. For production, leverage CSS variables and custom styling. Refer [styling](#styling) for more information\n\n\n### Inserting Diff Suggestions\n\n```typescript\neditor.commands.insertDiffSuggestion({\n  id: 'unique-suggestion-123',\n  comment: 'Suggested improvement for clarity'\n});\n```\n\n### Setting Editor Content with Diff Suggestion HTML\n\n```typescript\neditor.commands.setContent(`\n  <p> This is some random text before suggestion\n  <span data-diff-suggestion data-diff-suggestion-id=\"unique-suggestion-123\" data-diff-suggestion-comment=\"Suggested improvement for clarity\">\n    <span data-diff-suggestion-old>The old text</span>\n    <span data-diff-suggestion-new>The improved text</span>\n  </span> the text follows suggestions.\n`);\n```\n\n### Advanced Configuration with Side-effects\n\n```typescript\nimport { DiffSuggestion } from '@buddhima_a/tiptap-diff-suggestions';\n\nconst editor = new Editor({\n  extensions: [\n    DiffSuggestion.configure({\n      HTMLAttributes: {\n        class: 'my-custom-diff',\n      },\n      className: 'custom-diff-wrapper',\n      showButtons: true,\n      buttons: {\n        accept: 'Accept',\n        reject: 'Reject',\n      },\n      // Side-effect callbacks\n      onAccept: (meta) => {\n        console.log('Accepted suggestion:', meta);\n        sidebar.highlight(meta.id);\n      },\n      onReject: (meta) => {\n        console.log('Rejected suggestion:', meta);\n        sidebar.remove(meta.id);\n      },\n    }),\n  ],\n});\n```\n\n### Custom Behavior Override\n\n```typescript\nDiffSuggestion.configure({\n  // Full logic override\n  handleAccept: ({ tr, dispatch }) => {\n    dispatch(tr.insertText(\"Custom Accept Logic\"));\n    return true;\n  },\n  handleReject: ({ tr, dispatch }) => {\n    dispatch(tr.insertText(\"Custom Reject Logic\"));\n    return true;\n  },\n});\n```\n\n## API Reference\n\n### Commands\n\n- `insertDiffSuggestion(options)` - Insert a diff suggestion\n- `acceptDiffSuggestion(id?)` - Accept a specific suggestion (or current selection)\n- `rejectDiffSuggestion(id?)` - Reject a specific suggestion (or current selection)\n- `acceptAllDiffSuggestions()` - Accept all suggestions in the document\n- `rejectAllDiffSuggestions()` - Reject all suggestions in the document\n\n### Options\n\n```typescript\ninterface DiffSuggestionOptions {\n  HTMLAttributes: Record<string, any>;\n  className?: string;\n  showButtons?: boolean;\n  buttons?: {\n    accept?: string;\n    reject?: string;\n  };\n  onAccept?: (meta: DiffSuggestionMeta) => void;\n  onReject?: (meta: DiffSuggestionMeta) => void;\n  handleAccept?: Command;\n  handleReject?: Command;\n}\n```\n\n### Attributes\n\n```typescript\ninterface DiffSuggestionAttributes {\n  id: string;\n  comment?: string;\n}\n```\n\n### Meta Object\n\nWhen using side-effect callbacks, you receive a meta object:\n\n```typescript\ninterface DiffSuggestionMeta {\n  id: string;\n  comment?: string;\n  accepted: boolean;\n  originalText: string;\n  suggestedText: string;\n}\n```\n\n## Styling\n\nThe extension follows TipTap's headless approach - no styles are included by default, giving you complete control over the appearance.\n\n### Quick Start with Sample Styles\n\nFor rapid prototyping and development:\n\n```html\n<link rel=\"stylesheet\" href=\"node_modules/@buddhima_a/tiptap-diff-suggestions/sample.css\">\n```\n\n### CSS Variables\n\nThe sample CSS includes CSS variables for easy theming:\n\n```css\n:root {\n  --diff-suggestion-border: #3b82f6;\n  --diff-suggestion-bg: rgba(59, 130, 246, 0.1);\n  --diff-old-bg: rgba(239, 68, 68, 0.2);\n  --diff-new-bg: rgba(34, 197, 94, 0.2);\n  --diff-accept-btn: #10b981;\n  --diff-reject-btn: #ef4444;\n  --diff-toolbar-bg: white;\n  --diff-toolbar-shadow: rgba(0, 0, 0, 0.1);\n}\n\n/* Dark mode variables are also included */\n[data-theme=\"dark\"] {\n  --diff-toolbar-bg: #1f2937;\n  --diff-toolbar-shadow: rgba(0, 0, 0, 0.3);\n  /* ... more dark mode variables */\n}\n```\n\n### Key CSS Selectors\n\nTarget these selectors for custom styling:\n\n- `span[data-diff-suggestion]` - Main container\n- `span[data-diff-suggestion-old]` - Original text styling  \n- `span[data-diff-suggestion-new]` - Suggested text styling\n- `.diff-suggestion-action-container` - Action buttons container\n- `[data-diff-suggestion-toolbar-accept]` - Accept button\n- `[data-diff-suggestion-toolbar-reject]` - Reject button\n\n### Custom Styling Example\n\n```css\nspan[data-diff-suggestion] {\n  border: 2px solid var(--diff-suggestion-border, #3b82f6);\n  border-radius: 8px;\n  padding: 4px 8px;\n  background: var(--diff-suggestion-bg, rgba(59, 130, 246, 0.1));\n}\n\n[data-diff-suggestion-toolbar-accept] {\n  background-color: var(--diff-accept-btn, #10b981);\n  color: white;\n  padding: 4px 8px;\n  border-radius: 4px;\n  border: none;\n  cursor: pointer;\n}\n```\n\n## Examples\n\n### Working with Raw HTML\n\nSince the extension expects HTML in the specified structure, you can work with it directly:\n\n```typescript\n// Assuming you have diff HTML from your diff algorithm\nconst diffHTML = `\n  <span data-diff-suggestion data-diff-suggestion-id=\"123\" data-diff-suggestion-comment=\"Grammar fix\">\n    <span data-diff-suggestion-old>teh quick</span>\n    <span data-diff-suggestion-new>the quick</span>\n  </span>\n`;\n\n// Insert the HTML directly\neditor.commands.insertContent(diffHTML);\n```\n\n### Programmatic Suggestion Creation\n\n```typescript\n// Create suggestion programmatically\neditor.commands.insertDiffSuggestion({\n  id: Date.now().toString(),\n  comment: 'AI suggested improvement'\n});\n```\n\nFor additional usage scenarios and implementation samples, refer to the examples in the repository.\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Type Checking\n\n```bash\nnpm run type-check\n```\n\n### Watch Mode\n\n```bash\nnpm run dev\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.","readmeFilename":"README.md","_rev":"1-6e9af983d6df036cc714ab2152c081d2"}