PreTeXt Plus Editor

An in-browser editor for PreTeXt documents with visual and code editing modes.

Installation

npm install @pretextbook/web-editor

Usage

Basic Setup

import React, { useState } from "react";
import {
  Editors,
  type FeedbackSubmission,
  type PretextProjectCopyRequest,
} from "@pretextbook/web-editor";
import "@pretextbook/web-editor/dist/web-editor.css";

function App() {
  const [source, setSource] = useState("");
  const [sourceFormat, setSourceFormat] = useState<"pretext" | "latex">(
    "pretext",
  );
  const [title, setTitle] = useState("My Document");

  const handleFeedbackSubmit = async (feedback: FeedbackSubmission) => {
    await fetch("/api/editor-feedback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(feedback),
    });
  };

  const handleCreatePretextProjectCopy = async (
    request: PretextProjectCopyRequest,
  ) => {
    await fetch("/api/projects/create_pretext_copy", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    });
  };

  return (
    <Editors
      source={source}
      sourceFormat={sourceFormat}
      onContentChange={(value, meta) => {
        setSource(value || "");
        setSourceFormat(meta?.sourceFormat || "pretext");
      }}
      title={title}
      onTitleChange={setTitle}
      onSaveButton={() => console.log("Save clicked")}
      saveButtonLabel="Save"
      onCancelButton={() => console.log("Cancel clicked")}
      cancelButtonLabel="Cancel"
      projectUrl={window.location.href}
      onFeedbackSubmit={handleFeedbackSubmit}
      onCreatePretextProjectCopy={handleCreatePretextProjectCopy}
    />
  );
}

export default App;

Styling

Important: This package uses Tailwind CSS internally, but all styles are pre-compiled and bundled in the CSS file. You don't need to install or configure Tailwind CSS in your project.

Simply import the CSS file:

import "@pretextbook/web-editor/dist/web-editor.css";

Or in your CSS file:

@import "@pretextbook/web-editor/dist/web-editor.css";

All button styles, layout, and MenuBar styling will work automatically without any additional setup.

@import "@pretextbook/web-editor/dist/web-editor.css";

Props

The Editors component accepts the following props:

type SourceFormat = "pretext" | "latex";

interface FeedbackSubmission {
  context: string;
  email?: string;
  message: string;
  includeCurrentSource: boolean;
  currentSource?: string;
  projectUrl?: string;
  sourceFormat?: SourceFormat;
  title?: string;
  submittedAt: string;
}

interface PretextProjectCopyRequest {
  pretextSource: string;
  title: string;
  projectUrl?: string;
}

interface EditorContentChange {
  sourceContent: string;
  sourceFormat: SourceFormat;
  pretextSource?: string;
  pretextError?: string;
  docinfo?: string;
  commonDocinfo?: string;
  useCommonDocinfo?: boolean;
}

interface editorProps {
  source: string; // The canonical source content
  sourceFormat?: SourceFormat; // The canonical source format
  pretextSource?: string; // Optional derived PreTeXt for previewing LaTeX sources
  docinfo?: string; // Project-specific docinfo XML
  commonDocinfo?: string; // User-level common docinfo/preamble XML
  useCommonDocinfo?: boolean; // Use common docinfo for this project
  onUseCommonDocinfoChange?: (value: boolean) => void;
  onCommonDocinfoChange?: (value: string) => void;
  onContentChange: (
    value: string | undefined,
    meta?: EditorContentChange,
  ) => void;
  title?: string; // Document title
  onTitleChange?: (value: string) => void; // Called when title changes
  onSaveButton?: () => void; // Save button callback
  saveButtonLabel?: string; // Custom save button text
  onCancelButton?: () => void; // Cancel button callback
  cancelButtonLabel?: string; // Custom cancel button text
  onFeedbackSubmit?: (feedback: FeedbackSubmission) => void | Promise<void>;
  projectUrl?: string;
  onCreatePretextProjectCopy?: (
    request: PretextProjectCopyRequest,
  ) => void | Promise<void>;
  onSave?: () => void; // Keyboard save callback
  onPreviewRebuild?: (
    source: string,
    title: string,
    postToIframe: (url: string, data: any) => void,
  ) => void;
}

interface DocinfoEditorCloseValue {
  docinfo: string;
  commonDocinfo: string;
  useCommonDocinfo: boolean;
}

interface DocinfoEditorProps {
  docinfo: string;
  onClose: (value: DocinfoEditorCloseValue | undefined) => void;
  showCommonDocinfoControls?: boolean;
  commonDocinfo?: string;
  initialUseCommonDocinfo?: boolean;
}

DocinfoEditor is exported for host apps that want to edit user-level common docinfo directly.

For LaTeX-authored documents, the editor derives previewable PreTeXt on the fly. The simple preview remains read-only for the LaTeX source project; visual editing becomes available in the new PreTeXt copy your app creates.

When a document is in LaTeX mode and onCreatePretextProjectCopy is provided, the toolbar exposes a Convert to PreTeXt action. Clicking it opens a confirmation dialog and, if confirmed, sends the converted PreTeXt to your callback so your app can create a new project copy.

The current LaTeX project is not replaced by this action.

When onFeedbackSubmit is provided, the editor shows Give feedback links in the main menu and LaTeX conversion dialog. The popup collects:

• optional email address
• required feedback message
• optional inclusion of current source
• project URL (when available)

The collected payload is sent to your callback so your app can email it, store it, or route it to another workflow.

Rails Integration Pattern

const handleFeedbackSubmit = async (feedback: FeedbackSubmission) => {
  await fetch("/editor_feedback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ editor_feedback: feedback }),
  });
};

const handleCreatePretextProjectCopy = async (
  request: PretextProjectCopyRequest,
) => {
  await fetch("/projects/create_pretext_copy", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ project_copy: request }),
  });
};

Typical server behavior:

• Feedback endpoint stores the message and optionally sends an email to support.
• Project-copy endpoint creates a new project with the same title and pretextSource as canonical source.
• Original project remains unchanged.

Persistence recommendation

For consuming apps, the recommended storage model is:

• store one canonical source: source plus sourceFormat
• optionally store derived pretextSource as a cache for LaTeX-authored documents
• do not treat LaTeX and PreTeXt as two independently editable canonical sources

If your product needs an audit trail, keep the original LaTeX and created PreTeXt copy linked in your own persistence layer.

Features

• Visual Editor: Intuitive WYSIWYG editor for PreTeXt documents using Tiptap
• Code Editor: Monaco-powered code editor with syntax highlighting
• Full Preview: Full-page preview of your document
• Synchronized Editing: Changes in one editor instantly reflect in the other
• Split View: View code and visual editor side-by-side
• Math Support: KaTeX support for rendering mathematical expressions
• Keyboard Shortcuts: Intuitive keyboard navigation and commands

Peer Dependencies

This package requires:

• react >= 16.8.0
• react-dom >= 16.8.0

These must be installed separately in your project.

Browser Support

This package requires a modern browser with ES2020 support.

Development

For development setup:

npm install
npm run dev

To build the library:

npm run build

To build the demo application:

npm run build:demo

Publishing

See PUBLISHING.md for instructions on publishing to npm.

License

MIT