@merakite/tiptap-bubble
v0.4.0
Published
Tiptap rich text editor bundle for Bubble.io.
Readme
@merakite/tiptap-bubble
A Tiptap v3 rich text editor bundle for Bubble.io, loaded through a thin Bubble plugin. It stores sanitized HTML in an existing text field, compatible with the Quill editor it replaces.
The public interface and storage format are defined in docs/API_CONTRACT.md. Task briefs are in docs/tasks/. Project rules are in CLAUDE.md.
Status
Task 06 (0.4.0: a "Text alignment" dropdown, align, replaces the four alignment buttons in the default toolbar; see docs/tasks/TASK_06_ALIGN_MENU.md). Task 05 (0.3.0) added smart fields, workspace fonts and type presets, text and highlight colours from host palettes, tables as content, and auditHTML (see docs/tasks/TASK_05_SMART_FIELDS_AND_FONTS.md). The bundle exposes the full contract API: version, mount(el, options), renderHTML(content, options?), renderInto(el, content, options?) and auditHTML(content, options?). Images upload through a host-provided upload.handler; the Bubble plugin's handler stores them as private files in the app's own storage (see docs/BUBBLE_UPLOADS.md). The plugin's code and setup guide are in bubble-plugin/. Releases are staged on npm by GitHub Actions and approved by the owner: see docs/RELEASING.md.
Usage
Load by exact version only:
<script src="https://cdn.jsdelivr.net/npm/@merakite/[email protected]/dist/tiptap-editor.js"></script>const editor = TiptapBubble.mount(el, {
docId: task.id,
content: task.description,
onUpdate: (payload) => { /* save payload.html to the record whose id is payload.docId */ },
})
editor.loadDocument(otherTask.id, otherTask.description) // switch records
const view = TiptapBubble.renderInto(listItemEl, storedValue, { maxHeight: 120 }) // read-only
const html = TiptapBubble.renderHTML(storedValue) // canonical, sanitized HTML; "" when emptyDevelopment
Node 24 (.nvmrc).
| Command | What it does |
|---|---|
| npm run dev | Local harness: fixtures (/harness/index.html), interactive editor with a mock upload server and a fake host upload handler (/harness/editor.html), renderInto cards (/harness/cards.html), the Bubble plugin on a simulated Bubble page (/harness/bubble.html) |
| npm test | Tests (Vitest + jsdom) |
| npm run test:watch | Tests in watch mode |
| npm run typecheck | tsc --noEmit |
| npm run build | Builds dist/tiptap-editor.js (single IIFE, CSS injected by JS) |
| npm run test:e2e | Playwright end-to-end tests against the harness (Chromium) |
See docs/TESTING.md for details.
Layout
src/
index.ts public API (version, mount, renderHTML, renderInto, auditHTML)
editor/ mount and the editor handle, toolbar, popovers, uploads, paste
render-into.ts read-only renderer (no editor instance)
main.ts IIFE entry: installs window.TiptapBubble with the double-load guard
pipeline.ts content in → document → canonical HTML out
formats.ts host lists: smart fields, fonts, type presets, colour palettes, Quill maps
colors.ts colour parsing and OKLab snapping for imported inline colours
schema/ Tiptap extensions (Quill-compatible task lists and alignment, embed, smart field, font, colour, type preset, table)
import/ legacy HTML import rules, plain text import, auditHTML
export/ canonical HTML output
sanitize/ DOMPurify input and output passes, URL policy
embeds/ embed provider registry (Loom), iframe builder
styles/ content and editor CSS, scoped under .ttb-root
bubble-plugin/ Bubble plugin code (pasted into Bubble's plugin editor) and SETUP.md
build/ build-time helpers (CSS injection)
fixtures/ live-descriptions.json (production values) and synthetic/ fixtures
tests/ Vitest suites
e2e/ Playwright suites (run against the harness)
harness/ fixture viewer, editor harness, mock upload server, renderInto cards, Bubble simulation, sample host lists and CSS
scripts/ audit-formatting.mjs: auditHTML over real data exports
docs/design/ toolbar reference and the latest screenshot from the visual test