@dotit/editor

Embeddable WYSIWYG visual editor for IntentText (.it) documents — Word-like pages, a formatting ribbon, trust banner, and WYSIWYG PDF/HTML export. Built for embedding in React apps: ERPs, portals, back offices.

The editor is a controlled component over plain .it source text: you pass the source in, you get the edited source back. Everything the user styles maps to core .it properties, so a document printed through @dotit/core (or this package's export functions) always matches what the user saw on screen.

Install

npm install @dotit/editor @dotit/core react react-dom

Peer dependencies: react >= 18, react-dom >= 18.

Quick start

import { useState } from "react";
import { IntentTextEditor, exportDocumentPDF } from "@dotit/editor";
import "@dotit/editor/style.css";

export function InvoiceEditor() {
  const [source, setSource] = useState("title: Invoice INV-001\n\nHello");
  return (
    <div style={{ height: "100vh" }}>
      <IntentTextEditor value={source} onChange={setSource} theme="corporate" />
      <button onClick={() => exportDocumentPDF(source, "corporate")}>PDF</button>
    </div>
  );
}

The editor fills its parent — give the wrapper an explicit height.

<IntentTextEditor /> props

| Prop | Type | Default | Description | | ----------------- | --------------------------------- | ------------- | ----------- | | value | string | — (required) | Current .it source text (controlled). | | onChange | (source: string) => void | — (required) | Called with the updated .it source on every edit. | | theme | string | "corporate" | Document theme id (see builtinThemes()). Controlled when provided — pair with onThemeChange. | | onThemeChange | (theme: string) => void | — | Called when the user picks a theme in the ribbon. | | readOnly | boolean | false | Force read-only. Sealed documents (freeze: block) are read-only automatically. | | showRibbon | boolean | true | Show the formatting ribbon. | | showTrustBanner | boolean | true | Show the trust status banner + document properties strip. The banner is multi-sign aware — it shows per-signer status (Signed · N/M), flags an older-ruleset seal (Sealed · older ruleset), and shows SEAL BROKEN when a sealed body is tampered. | | onTrustAction | (a: "seal"\|"sign"\|"verify") => void | — | Handle the ribbon's Trust group. The editor only reports intent — wire it to your own dialogs (e.g. core's sealDocument / verifyDocument). The group is hidden when omitted. |

Named exports

| Export | Description | | ------ | ----------- | | IntentTextEditor | The embeddable editor component. | | exportDocumentPDF(source, theme, printMode?) | Opens the browser print dialog (→ Save as PDF). WYSIWYG when the editor is mounted; falls back to core's renderPrint. printMode: "normal" \| "minimal-ink". | | exportDocumentHTML(source, theme, printMode?) | Downloads the print-ready HTML document. | | builtinThemes() | Built-in theme ids for a theme picker. | | printHtmlViaIframe(html) | Low-level: print any HTML document via a hidden iframe. | | sourceToDoc(source) / docToSource(json) | The lossless .it ↔ editor-document bridge (TipTap JSON). | | extractTemplateVariables(source) / buildSampleSkeleton(vars) | Template helpers for {{variable}} authoring. | | extractTrustState(parsedDoc) | Trust lifecycle snapshot (TrustState): tracked / approved / signed / sealed + amendments. | | getPageGeometry(source) / resolvePageTokens(text, page, pages) | Page geometry from the document's own page:/header:/footer: blocks. |

Types: IntentTextEditorProps, TrustAction, PrintMode, TrustState, PageGeometry.

Embedding in an ERP

• Controlled .it in/out. Store the source string wherever you store documents (a DB column is fine — it's plain text). Load it into value, persist what onChange gives you. No editor-specific format ever touches your data.
• Byte-faithful editing (seals never break). Edits change only what actually changed — every untouched block keeps its exact original bytes (comments, blank lines, spacing, bare prose). Opening and saving a document with no change is byte-identical, so a sealed body keeps its content hash through the editor (and sealed documents are read-only on the body anyway). Powered by @dotit/core's reconcileEdit.
• Templates + merge. Author templates with {{variables}} in the editor (they render as chips); merge real data server-side with @dotit/core's parseAndMerge and print with renderPrint — or @dotit/pdf for real PDF bytes.
• PDF from the UI. Call exportDocumentPDF(source, theme) from your own button — it uses the user's browser print dialog and matches the on-screen pages exactly.
• Trust flows. Sealed documents lock automatically. Hook onTrustAction to your approval/signature flows; the editor renders sign:/seal:/approve: blocks as proper signature lines and chips. The trust banner is multi-sign aware (per-signer Signed · N/M; a signer of an earlier version is shown as such, not a blanket "broken"). On the page (and in print/PDF) the editor draws @dotit/core's unified certification band (renderTrustBand + TRUST_BAND_CSS), so it looks identical on screen and on paper; the band has an integrity gate — it verifies before drawing, so a tampered seal never prints as sealed.
• Insert at caret. Dispatch window.dispatchEvent(new CustomEvent("it-insert-text", { detail: "{{customer.name}}" })) to insert text at the cursor (e.g. from your own variable picker).
• Styling. All styles are scoped under .docs-container/.docs-page and ship in one stylesheet (@dotit/editor/style.css); the editor does not depend on host-page CSS resets. One editor instance per page is the supported setup (theme CSS is injected document-wide).

SSR / Next.js

The editor is browser-only (it measures the DOM to paginate). With Next.js or any SSR framework, load it dynamically with SSR disabled:

"use client";
import dynamic from "next/dynamic";
import "@dotit/editor/style.css";

const IntentTextEditor = dynamic(
  () => import("@dotit/editor").then((m) => m.IntentTextEditor),
  { ssr: false },
);

exportDocumentPDF / exportDocumentHTML must also only be called in the browser. For server-side PDF generation use @dotit/pdf.

License

MIT