@trevixal/editor-kit

Documentation · Live editor · Changelog · Issues

Features

• One call mounts the finished editor: mountFullEditor({ element })
• Every extension wired to every other: tables, images, math, diagrams, track changes
• Autosave, themes, a document workspace and a command palette included
• A CDN build that runs from one <script> tag with no bundler
• 14.1 kB minified and gzipped, with TypeScript types in the package

Every package the Trevixal workspace ships, assembled into one call. Where @trevixal/core is the engine and @trevixal/ui is the chrome, this is the finished editor. The thing the demo page was, with the page taken out of it.

npm install @trevixal/editor-kit @trevixal/core @trevixal/ui
Copy

import { mountFullEditor } from '@trevixal/editor-kit'
import '@trevixal/ui/styles.css'
import '@trevixal/editor-kit/styles.css'

const editor = mountFullEditor({ element: document.querySelector('#app') })
Copy

That is the whole integration. Everything below is optional.

What you get

One call builds the page and wires every part of it to every other:

Configuration

Only what a host actually decides. Which extensions, which menus, which panels. Those are not options, because a build with half of them is not what this package is for.

mountFullEditor({
  element,                         // required; it is emptied first
  content: myDocument,             // default: a tour of every block type
  placeholder: 'Write something…',
  author: 'Ada',                   // whose name goes on a tracked change
  namespace: 'my-app',             // the localStorage prefix for everything it saves
  uploadEndpoint: '/api/uploads',  // or null to skip the request and use a data URL
  maxImageBytes: 5 * 1024 * 1024,
  heading: 'My editor',            // or null for none
  paragraphs: ['<b>Some</b> copy.'],
  showSerializedHTML: false,
  aboutRows: [{ term: 'Build', description: 'v2.1' }],
  onChange: (editor) => save(editor.getJSON()),
})
Copy

The returned handle carries the editor, the layout it built, the ui it mounted, and a destroy() that takes all three back.

Where it can run

It reaches for window and document in its first statement, so it has to be called from wherever your framework runs browser-only code (a useEffect, an onMounted, an afterNextRender, an onMount) and never during a server render. The examples do exactly that in eight frameworks; each one is a few lines long.

Call it once per page. Several of the parts it assembles are singletons by nature (the autosave draft, the workspace store, the command palette on document.body) so a second mount sharing a namespace would have two editors writing over one another's saves.

On a server

mountFullEditor is browser-only. The package is not: importing it runs no DOM code, so a Node process can take the schema out of it and render a stored document to HTML with no browser anywhere.

import { createEditor, serializeToHTML } from '@trevixal/core'
import { createFullSchema } from '@trevixal/editor-kit'

const editor = createEditor({ schema: createFullSchema(), content: stored }) // no element
const html = serializeToHTML(editor.state.doc)
editor.destroy()
Copy

createFullSchema() is the schema mountFullEditor builds on, tables, images, blocks, embeds, equations and the track-changes marks. defaultNodes() alone cannot read a document this editor produced. examples/ssr is the runnable version.

From a script tag, with no bundler

There is a second build for pages that have none: one file that defines window.TrevixalKit, with the core, the chrome and every extension inlined because such a page cannot fetch them separately.

<link rel="stylesheet" href="https://unpkg.com/@trevixal/ui/styles.css" />
<link rel="stylesheet" href="https://unpkg.com/@trevixal/editor-kit/styles.css" />
<script src="https://unpkg.com/@trevixal/editor-kit"></script>

<div id="app"></div>
<script>
  TrevixalKit.mountFullEditor({ element: document.querySelector('#app') })
</script>
Copy

It is the largest artefact this workspace publishes, 180 kB gzipped against 36 kB for the core alone, and that is the trade it exists to make. If you have a bundler, import the package instead and let it tree-shake; if you need an editor in a page you cannot build, this is the whole integration. examples/vanilla-cdn runs it, and is four tags and a div long.

Styles

Two stylesheets, in this order:

import '@trevixal/ui/styles.css'          // the editor and its chrome
import '@trevixal/editor-kit/styles.css' // the shell around them
Copy

The second is scoped to .trevixal-full-editor, the class the mount puts on your element, so it does not reach into the rest of your page. The one deliberate exception is the syntax-colour palette: collectDocumentCSS copies those rules into exported and previewed documents, which have none of the shell around them, so they cannot be scoped to it.

The SCSS sources ship too, at @trevixal/editor-kit/scss/*, if you would rather build the palette from your own tokens.

Building it yourself instead

Nothing here is privileged. mountFullEditor is a few hundred lines that import the same public API you have, and src/mount.ts is worth reading if you want most of this editor but not all of it: copy it, delete what you do not want, and you have your own build with no fork of anything.

License

Apache-2.0