@pretextbook/web-editor 0.0.20 → 0.0.22

package/README.md

@@ -19,12 +19,17 @@ import '@pretextbook/web-editor/dist/web-editor.css';
 
 function App() {
   const [content, setContent] = useState('');
+  const [sourceFormat, setSourceFormat] = useState<'pretext' | 'latex'>('pretext');
   const [title, setTitle] = useState('My Document');
 
   return (
     <Editors
       content={content}
-      onContentChange={setContent}
+      sourceFormat={sourceFormat}
+      onContentChange={(value, meta) => {
+        setContent(value || '');
+        setSourceFormat(meta?.sourceFormat || 'pretext');
+      }}
       title={title}
       onTitleChange={setTitle}
       onSaveButton={() => console.log('Save clicked')}
@@ -63,18 +68,45 @@ All button styles, layout, and MenuBar styling will work automatically without a
 The `Editors` component accepts the following props:
 
 ```tsx
+type SourceFormat = 'pretext' | 'latex';
+
+interface EditorContentChange {
+  sourceContent: string;
+  sourceFormat: SourceFormat;
+  pretextContent?: string;
+  pretextError?: string;
+}
+
 interface editorProps {
-  content: string;                          // The current PreTeXt content
-  onContentChange: (value: string | undefined) => void;  // Called when content changes
+  content: string;                          // The canonical source content
+  sourceFormat?: SourceFormat;              // The canonical source format
+  pretextContent?: string;                  // Optional derived PreTeXt for previewing LaTeX sources
+  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
+  onSave?: () => void;                      // Keyboard save callback
+  onPreviewRebuild?: (content: string, title: string, postToIframe: (url: string, data: any) => void) => void;
 }
 ```
 
+For LaTeX-authored documents, the editor can now derive previewable PreTeXt on the fly. The simple preview remains read-only until the document is explicitly converted to PreTeXt source.
+
+When a document is in LaTeX mode, the toolbar exposes a `Convert to PreTeXt` action. That action replaces the canonical source with the latest generated PreTeXt so the visual editor can become editable.
+
+### Persistence recommendation
+
+For consuming apps, the recommended storage model is:
+
+- store one canonical source: `content` plus `sourceFormat`
+- optionally store derived `pretextContent` as a cache for LaTeX-authored documents
+- do not treat LaTeX and PreTeXt as two independently editable canonical sources
+
+Once a user clicks `Convert to PreTeXt`, the canonical source should become PreTeXt. If your product needs an audit trail, keep the original LaTeX separately in your own persistence layer.
+
 ## Features
 
 - **Visual Editor**: Intuitive WYSIWYG editor for PreTeXt documents using Tiptap

package/dist/components/CodeEditor.d.ts

@@ -1,8 +1,42 @@
+import type { SourceFormat } from "../types/editor";
 interface CodeEditorProps {
+    /** The current source content to display. */
     content: string;
+    /** Determines the Monaco language mode (`"xml"` for PreTeXt, `"latex"` for LaTeX). */
+    sourceFormat: SourceFormat;
+    /** Called (debounced 500 ms) whenever the user edits the content. */
     onChange: (value: string | undefined) => void;
+    /** If provided, Ctrl+Enter in the editor triggers this callback. */
     onRebuild?: () => void;
+    /** If provided, Ctrl+S in the editor triggers this callback. */
     onSave?: () => void;
+    /**
+     * If provided, a "Convert to PreTeXt" button is shown in the toolbar.
+     * Called when the user clicks to promote the derived PreTeXt to the canonical source.
+     */
+    onConvertToPretext?: () => void;
+    /**
+     * Controls whether the "Convert to PreTeXt" button is enabled.
+     * Should be `false` when conversion has failed.
+     */
+    canConvertToPretext?: boolean;
+    /**
+     * The already-converted PreTeXt content.  Shown in the confirmation dialog
+     * so the user can review before committing.  Only meaningful when
+     * `sourceFormat` is `"latex"`.
+     */
+    pretextContent?: string;
 }
-declare const CodeEditor: ({ content, onChange, onRebuild, onSave }: CodeEditorProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Monaco-based code editor with an attached toolbar.
+ *
+ * Manages its own undo/redo state so the toolbar buttons stay in sync with
+ * the editor model.  `onRebuild` and `onSave` callbacks are stored in refs
+ * so keyboard shortcuts registered at mount time always call the latest
+ * version without needing to re-register.
+ *
+ * Content is synced from props only when the prop value differs from what the
+ * editor model already contains, to prevent cursor jumps on re-render.
+ */
+declare const CodeEditor: ({ content, sourceFormat, onChange, onRebuild, onSave, onConvertToPretext, canConvertToPretext, pretextContent, }: CodeEditorProps) => import("react/jsx-runtime").JSX.Element;
 export default CodeEditor;

package/dist/components/CodeEditorMenu.d.ts

@@ -1,12 +1,33 @@
 import React from "react";
 import "./CodeEditorMenu.css";
+import type { SourceFormat } from "../types/editor";
 interface CodeEditorMenuProps {
+    /** Current source content; passed to the formatter when the user clicks "Format PreTeXt". */
     content: string;
+    /** Determines which toolbar actions are available (e.g. formatting is PreTeXt-only). */
+    sourceFormat: SourceFormat;
+    /** Called with the formatted content after a successful format operation. */
     onContentChange: (newContent: string) => void;
+    /** Called when the user clicks "Import LaTeX" to open the import dialog. */
+    onOpenLatexImport: () => void;
+    /** Triggers an undo in the Monaco editor.  Passed through from the parent. */
     onUndo: () => void;
+    /** Triggers a redo in the Monaco editor.  Passed through from the parent. */
     onRedo: () => void;
+    /** Whether the undo button should be enabled. */
     canUndo: boolean;
+    /** Whether the redo button should be enabled. */
     canRedo: boolean;
+    /**
+     * If provided, a "Convert to PreTeXt" button is shown.
+     * Called when the user clicks to promote the derived PreTeXt to the canonical source.
+     */
+    onConvertToPretext?: () => void;
+    /**
+     * Controls whether the "Convert to PreTeXt" button is enabled.
+     * Should be `false` when conversion has failed.
+     */
+    canConvertToPretext?: boolean;
 }
 declare const CodeEditorMenu: React.FC<CodeEditorMenuProps>;
 export default CodeEditorMenu;

package/dist/components/ConvertToPretextDialog.d.ts

@@ -0,0 +1,18 @@
+import "./LatexImportDialog.css";
+interface ConvertToPretextDialogProps {
+    /** The current LaTeX source to display (read-only) on the left. */
+    latexSource: string;
+    /** The already-converted PreTeXt to display (read-only) on the right. */
+    pretextContent: string;
+    /** Called when the user confirms the conversion. */
+    onConfirm: () => void;
+    /** Called when the dialog should close without converting. */
+    onClose: () => void;
+}
+/**
+ * Confirmation dialog shown before permanently replacing LaTeX source with
+ * the derived PreTeXt.  Displays the current LaTeX and the converted PreTeXt
+ * side-by-side so the user can review before committing.
+ */
+declare const ConvertToPretextDialog: ({ latexSource, pretextContent, onConfirm, onClose, }: ConvertToPretextDialogProps) => import("react/jsx-runtime").JSX.Element;
+export default ConvertToPretextDialog;

package/dist/components/Editors.d.ts

@@ -1,15 +1,68 @@
 import "./Editors.css";
+import type { EditorContentChange, SourceFormat } from "../types/editor";
 export interface editorProps {
+    /** The source content string (PreTeXt XML or LaTeX). */
     content: string;
-    onContentChange: (value: string | undefined) => void;
+    /**
+     * The format of `content`.  Defaults to `"pretext"` when omitted.
+     * When set to `"latex"`, the editor displays a LaTeX code editor and
+     * derives a read-only PreTeXt preview via conversion.
+     */
+    sourceFormat?: SourceFormat;
+    /**
+     * Pre-computed PreTeXt XML corresponding to `content`.
+     * Providing this avoids running the conversion on first render when the
+     * host already has a cached result.  Only meaningful when
+     * `sourceFormat` is not `"pretext"`.
+     */
+    pretextContent?: string;
+    /**
+     * Called whenever the source content changes (user edits in the code
+     * editor or WYSIWYG editor).
+     *
+     * @param value - The new source string (`undefined` is passed by Monaco on
+     *   certain edge cases; treat it as an empty string).
+     * @param meta - The full derived {@link EditorContentChange} state at the
+     *   time of the change, including the converted PreTeXt and any error.
+     */
+    onContentChange: (value: string | undefined, meta?: EditorContentChange) => void;
+    /** Document title shown in the menu bar title field. */
     title?: string;
+    /** Called when the user edits the title field. */
     onTitleChange?: (value: string) => void;
+    /** If provided, a Save button is rendered in the menu bar. */
     onSaveButton?: () => void;
+    /** Label for the Save button.  Defaults to `"Save"`. */
     saveButtonLabel?: string;
+    /** If provided, a Cancel button is rendered in the menu bar. */
     onCancelButton?: () => void;
+    /** Label for the Cancel button.  Defaults to `"Cancel"`. */
     cancelButtonLabel?: string;
+    /**
+     * If provided, `onSave` is called on Ctrl+S in addition to `onSaveButton`.
+     * Useful when the host wants a keyboard shortcut to trigger saving without
+     * necessarily showing an explicit Save button.
+     */
     onSave?: () => void;
+    /**
+     * If provided, the right-hand panel shows a full iframe-based preview
+     * instead of the Tiptap visual editor, and a rebuild button / Ctrl+Enter
+     * shortcut become active.
+     *
+     * @param content - The current PreTeXt XML to render.
+     * @param title - The current document title.
+     * @param postToIframe - Helper to post a message into the preview iframe.
+     */
     onPreviewRebuild?: (content: string, title: string, postToIframe: (url: string, data: any) => void) => void;
 }
+/**
+ * Top-level editor component that wires together the Monaco code editor and
+ * the right-hand preview panel (either Tiptap visual editor or full iframe
+ * preview).  Also owns the menu bar and responsive layout logic.
+ *
+ * Content state is derived from props on every render via `useMemo` so the
+ * parent always controls the source of truth; the component itself holds no
+ * long-lived content state.
+ */
 declare const Editors: (props: editorProps) => import("react/jsx-runtime").JSX.Element;
 export default Editors;

package/dist/components/LatexImportDialog.d.ts

@@ -0,0 +1,14 @@
+import "./LatexImportDialog.css";
+interface LatexImportDialogProps {
+    /** Called when the dialog should close (Cancel button, Escape key, or after "Copy and Close"). */
+    onClose: () => void;
+}
+/**
+ * Modal dialog that lets the user paste, open, or drag-and-drop a `.tex` file,
+ * convert it to PreTeXt, and copy the result to the clipboard.
+ *
+ * The dialog does not modify the editor content directly; it relies on the
+ * user copying the output and pasting it wherever needed.
+ */
+declare const LatexImportDialog: ({ onClose }: LatexImportDialogProps) => import("react/jsx-runtime").JSX.Element;
+export default LatexImportDialog;

package/dist/components/MenuBar.d.ts

@@ -1,14 +1,29 @@
+import "./MenuBar.css";
 export interface MenuBarProps {
+    /**
+     * Whether the "Full" preview mode is active.
+     * The toggle slider reflects `isChecked === true` → Full, `false` → Simple.
+     */
     isChecked: boolean;
+    /** Called when the user clicks the Simple/Full preview mode toggle. */
     onChange: () => void;
+    /** Current document title shown in the editable title field. */
     title?: string;
+    /** Called when the user changes the title field value. */
     onTitleChange?: (value: string) => void;
+    /** If provided, a Save button is rendered. */
     onSaveButton?: () => void;
+    /** Label for the Save button.  Defaults to `"Save"`. */
     saveButtonLabel?: string;
+    /** If provided, a Cancel button is rendered. */
     onCancelButton?: () => void;
+    /** Label for the Cancel button.  Defaults to `"Cancel"`. */
     cancelButtonLabel?: string;
+    /**
+     * When `false`, the Simple/Full preview mode toggle is hidden entirely.
+     * Defaults to showing the toggle.
+     */
     showPreviewModeToggle?: boolean;
 }
-import "./MenuBar.css";
 declare const MenuBar: (props: MenuBarProps) => import("react/jsx-runtime").JSX.Element;
 export default MenuBar;

package/dist/components/VisualEditor.d.ts

@@ -2,12 +2,35 @@ import "katex/dist/katex.min.css";
 import "../styles.scss";
 import "./VisualEditor.css";
 interface VisualEditorProps {
+    /** PreTeXt XML string to render and (optionally) edit. */
     content: string;
+    /**
+     * Called (debounced 500 ms) with the updated PreTeXt XML whenever the user
+     * edits content.  Only fired when editing is enabled.
+     */
     onChange: (html: string) => void;
+    /**
+     * Whether editing is permitted.  Defaults to `true`.
+     * When `false`, the "Edit" toggle is hidden and the editor stays read-only.
+     */
+    canEdit?: boolean;
+    /**
+     * Message displayed instead of the "Edit" toggle when `canEdit` is `false`.
+     * Explains to the user why editing is unavailable (e.g. LaTeX source mode).
+     */
+    editDisabledReason?: string;
 }
-interface VisualEditorProps {
-    content: string;
-    onChange: (html: string) => void;
-}
-declare const VisualEditor: ({ content, onChange }: VisualEditorProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Tiptap-based visual (WYSIWYG) preview/editor for PreTeXt content.
+ *
+ * In read-only mode it renders a styled preview of the PreTeXt XML.
+ * When the user enables the "Edit" toggle, editing becomes active and
+ * changes are serialised back to PreTeXt via `json2ptx` and reported to
+ * the parent via `onChange`.
+ *
+ * External content changes (e.g. the user typing in the code editor) are
+ * applied via `setContent` only when the update did not originate inside
+ * this component, preventing feedback loops.
+ */
+declare const VisualEditor: ({ content, onChange, canEdit, editDisabledReason, }: VisualEditorProps) => import("react/jsx-runtime").JSX.Element;
 export default VisualEditor;

package/dist/contentConversion.d.ts

@@ -0,0 +1,46 @@
+import type { SourceFormat } from "./types/editor";
+/** Returned by {@link derivePretextContent}. Exactly one of the two fields will be set. */
+export interface DerivedPretextResult {
+    /** The converted (or pass-through) PreTeXt XML string. */
+    pretextContent?: string;
+    /** Human-readable error when conversion fails. */
+    pretextError?: string;
+}
+/**
+ * Inspects `content` and returns the most likely {@link SourceFormat}.
+ *
+ * Rules (applied in order):
+ * 1. Empty/whitespace-only → `"pretext"` (safe default).
+ * 2. Starts with `<` → `"pretext"` (XML document).
+ * 3. Contains any {@link LATEX_FORMAT_MARKERS} → `"latex"`.
+ * 4. Otherwise → `"pretext"`.
+ */
+export declare function detectSourceFormat(content: string): SourceFormat;
+/**
+ * Converts a LaTeX document string to formatted PreTeXt XML.
+ *
+ * @param latexContent - The raw LaTeX source to convert.
+ * @returns The formatted PreTeXt XML string, or `""` if `latexContent` is blank.
+ * @throws If the underlying `latexToPretext` conversion throws.
+ */
+export declare function convertLatexToPretext(latexContent: string): string;
+/**
+ * Normalises an unknown thrown value into a displayable error message.
+ *
+ * @param error - The value caught in a `catch` block.
+ * @returns A non-empty string suitable for showing to the user.
+ */
+export declare function getConversionErrorMessage(error: unknown): string;
+/**
+ * Derives PreTeXt content from `sourceContent` according to `sourceFormat`.
+ *
+ * - If `sourceFormat` is `"pretext"`, the content is returned as-is.
+ * - If `sourceFormat` is `"latex"`, the content is converted via
+ *   {@link convertLatexToPretext}.  Conversion errors are caught and returned
+ *   as `pretextError` so callers never need a try/catch.
+ *
+ * @param sourceContent - The raw source string.
+ * @param sourceFormat - The format of `sourceContent`.
+ * @returns A {@link DerivedPretextResult} with either `pretextContent` or `pretextError`.
+ */
+export declare function derivePretextContent(sourceContent: string, sourceFormat: SourceFormat): DerivedPretextResult;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import './index.css';
 export { default as Editors } from './components/Editors';
 export type { editorProps } from './components/Editors';
+export { convertLatexToPretext, derivePretextContent, detectSourceFormat, } from './contentConversion';
+export type { EditorContentChange, EditorContentState, SourceFormat, } from './types/editor';
 export { default as CodeEditor } from './components/CodeEditor';
 export { default as VisualEditor } from './components/VisualEditor';
 export { default as FullPreview } from './components/FullPreview';