@typbase/codemirror 0.3.1 → 0.4.0

package/dist/index.d.mts

@@ -5,41 +5,63 @@ import { Diagnostic } from "@codemirror/lint";
 import { LRUCache } from "lru-cache";
 import { FileId, SvgRangedFrame, TypstDiagnostic, TypstState } from "@typbase/engine";
 //#region src/notebook.d.ts
-/**
- * Notebook cells. A cell is a `// %%` marker comment plus the content under
- * it, up to the next marker or the end of the document. Offsets are UTF-16
- * and match the engine's `CellSpan`, so `extractCells` results pass through.
- */
-export type NotebookCellType = "markup" | "code";
+export type NotebookCellType = "prose" | "code" | "log" | "hidden";
+/** Every type, in the order the menu lists them. */
+export declare const NOTEBOOK_CELL_TYPES: readonly NotebookCellType[];
+/** True when the cell renders in place rather than showing source plus output. */
+export declare function rendersInPlace(kind: NotebookCellType): boolean;
+/** True when the cell's source is not part of what the reader sees. */
+export declare function hidesSource(kind: NotebookCellType): boolean;
+/** True when the cell has an output area below its source. */
+export declare function hasOutput(kind: NotebookCellType): boolean;
 export interface NotebookCell {
   kind: NotebookCellType;
+  /** `name=` from the attribute line, when it carries one. */
+  name?: string | null;
   marker_start: number;
   marker_end: number;
   content_start: number;
   content_end: number;
 }
-/** Per-cell state the host owns: run counters and visibility. */
 export interface NotebookCellState {
-  /** Execution counter shown as `[n]`; undefined until the cell is run. */
-  count?: number;
-  /** Output hidden until the next run. */
-  cleared?: boolean;
   /** Source hidden behind the header. */
   collapsed?: boolean;
+  /**
+   * Keep the output this cell had when it was held. For the cells where a live
+   * render is wrong or expensive: a heavy query, a non-deterministic one, one
+   * with a side effect. See the note in `NotebookOptions.onCompile`.
+   */
+  held?: boolean;
+  /** The held cell's last output, kept by the host. */
+  frozen?: NotebookCellOutput;
+  /** Output hidden until the cell is refreshed. */
+  cleared?: boolean;
+}
+/** One cell's rendered output: its frames and the diagnostics inside it. */
+export interface NotebookCellOutput {
+  frames: SvgRangedFrame[];
+  diagnostics: TypstDiagnostic[];
 }
 /** UI strings, injected by the app so the package stays i18n-free. */
 export interface NotebookLabels {
-  run: string;
   code: string;
-  markup: string;
+  prose: string;
+  log: string;
+  hidden: string;
+  menu: string;
+  split: string;
+  merge: string;
   moveUp: string;
   moveDown: string;
   duplicate: string;
   remove: string;
+  copy: string;
+  hold: string;
+  release: string;
   clearOutput: string;
   toggleSource: string;
   noOutput: string;
-  error: string;
+  held: string;
 }
 export interface NotebookCompileResult {
   text: string;
@@ -47,43 +69,49 @@ export interface NotebookCompileResult {
   diagnostics: TypstDiagnostic[];
 }
 export interface NotebookOptions {
-  /** Cells for a document text; the host reads them from the engine. */
+  /** Cells for a document text. The host reads them from the engine. */
   cells: (text: string) => NotebookCell[];
-  /** Run/visibility state per cell index. */
+  /** Per-cell state. The host owns it. */
   state?: (index: number) => NotebookCellState | undefined;
-  /** Show `[n]` execution counters. */
-  counters?: () => boolean;
   labels?: NotebookLabels;
   /** Fires whenever the extension re-extracts cells. */
   onCells?: (cells: NotebookCell[]) => void;
   /** Fires when the cursor moves to a different cell. */
   onActiveCell?: (index: number | null) => void;
-  /** Fires after every compile that ran; `run` carries the requested cell. */
-  onRun?: (index: number | "all") => void;
-  /** Fires after a compile with the fresh frames and diagnostics. */
+  /**
+   * Fires after a compile with the fresh frames and diagnostics.
+   */
   onCompile?: (result: NotebookCompileResult) => void;
-  onClearOutput?: (index: number) => void;
-  onToggleCollapse?: (index: number) => void;
-  /** Escape: leave edit mode and select the current cell. */
-  onCommandMode?: () => void;
+  /** A cell's state changed and the decorations need a rebuild. */
+  onStateChange?: () => void;
+  /** A command from the rail's overflow menu, so the app owns the actions. */
+  onCommand?: (command: string, index: number) => void;
+  /** Read-only pages show cells without source or chrome. */
+  readOnly?: () => boolean;
 }
 /** The options of the notebook extension active in this state, if any. */
 export declare const notebookOptionsFacet: Facet<NotebookOptions, NotebookOptions | undefined>;
 export declare function notebookOptions(state: EditorState): NotebookOptions | undefined;
 /** Re-renders notebooks from cached frames without recompiling. */
 export declare const notebookRefreshEffect: import("@codemirror/state").StateEffectType<null>;
-/** Asks the plugin to recompile and report the result through `onRun`. */
-export declare const notebookRunEffect: import("@codemirror/state").StateEffectType<{
-  index: number | "all";
-}>;
-/** First position that belongs to the cell (marker line, or content). */
+/** First position that belongs to the cell (attribute line, or content). */
 export declare function cellStart(cell: NotebookCell): number;
-export declare function hasMarker(cell: NotebookCell): boolean;
-/** Index of the cell containing `pos`; gaps belong to the cell above. */
+/** True when the cell opened with an attribute line rather than a heading. */
+export declare function hasAttribute(cell: NotebookCell): boolean;
+/** Index of the cell containing `pos`. Gaps belong to the cell above. */
 export declare function cellIndexAt(cells: NotebookCell[], pos: number): number;
 export declare function cellsOf(state: EditorState): NotebookCell[];
-/** The marker line for a cell type. Markup is the unlabeled default. */
-export declare function markerText(type: NotebookCellType): string;
+/**
+ * The attribute line for a cell type. Prose needs no `kind=`, so a plain cell is
+ * three characters.
+ */
+export declare function attributeText(type: NotebookCellType, name?: string | null): string;
+/**
+ * Removes cell attribute lines. Notebooks are comments-plus-content, so a
+ * cleaned file is the same document for anyone who does not know the
+ * convention. Only `//%` goes: any other comment is left as written.
+ */
+export declare function stripCellAttributes(text: string): string;
 /** A text replacement plus where the cursor should land after it. */
 export interface CellEdit {
   changes: {
@@ -93,38 +121,41 @@ export interface CellEdit {
   };
   anchor: number;
 }
-export declare function insertCellText(text: string, cells: NotebookCell[], index: number, where: "above" | "below" | "end", type: NotebookCellType, content?: string): CellEdit;
-export declare function duplicateCellText(text: string, cells: NotebookCell[], index: number): CellEdit;
-export declare function deleteCellText(text: string, cells: NotebookCell[], index: number): CellEdit;
-export declare function moveCellText(text: string, cells: NotebookCell[], index: number, delta: -1 | 1): CellEdit | null;
+/**
+ * Splits a cell at `pos` inside its content. The new cell takes the text from
+ * `pos` and inherits the old cell's kind, because a split is a continuation.
+ */
 export declare function splitCellText(text: string, cells: NotebookCell[], index: number, pos: number): CellEdit | null;
-export declare function mergeCellText(text: string, cells: NotebookCell[], index: number): CellEdit | null;
-export declare function setCellTypeText(text: string, cells: NotebookCell[], index: number, type: NotebookCellType): CellEdit;
 /**
- * Removes `// %%` cell markers. Notebooks are comments-plus-content, so a
- * cleaned file is the same document for anyone who does not know the
- * convention.
+ * Merges a cell into the one above. The result takes the lower cell's kind,
+ * since that is the one the reader was last looking at.
  */
-export declare function stripCellMarkers(text: string): string;
-/** Compiles and reports through `onRun`; does not move the cursor. */
-export declare function runCell(view: EditorView, index: number): boolean;
-export declare function runAllCells(view: EditorView): boolean;
+export declare function mergeCellText(cells: NotebookCell[], index: number): CellEdit | null;
+/**
+ * Rewrites a cell's attribute line. A cell that began at a heading has no line
+ * to rewrite, so one is inserted.
+ */
+export declare function setCellTypeText(text: string, cells: NotebookCell[], index: number, type: NotebookCellType): CellEdit | null;
+/** Appends a cell of `type` after `index` (or at the end of the document). */
+export declare function insertCellText(text: string, cells: NotebookCell[], index: number, type: NotebookCellType, content?: string): CellEdit | null;
+export declare function deleteCellText(cells: NotebookCell[], index: number, docLength: number): CellEdit | null;
+/** Copies a cell's kind, name, and body below it. */
+export declare function duplicateCellText(text: string, cells: NotebookCell[], index: number): CellEdit | null;
+/** Selects a cell's content so the keyboard commands act on it. */
 export declare function focusCell(view: EditorView, index: number, edge?: "start" | "end"): boolean;
-export declare function insertCell(view: EditorView, where: "above" | "below" | "end"): boolean;
-export declare function insertCellAt(view: EditorView, index: number, where: "above" | "below" | "end"): boolean;
-export declare function duplicateCell(view: EditorView): boolean;
-export declare function duplicateCellAt(view: EditorView, index: number): boolean;
-export declare function deleteCell(view: EditorView): boolean;
-export declare function deleteCellAt(view: EditorView, index: number): boolean;
-export declare function moveCell(view: EditorView, delta: -1 | 1): boolean;
-export declare function moveCellAt(view: EditorView, index: number, delta: -1 | 1): boolean;
+export declare function currentCell(view: EditorView): number;
+/** Inserts a cell below `index`, or at the end of the document. */
+export declare function insertCell(view: EditorView, type: NotebookCellType, content?: string, index?: number): boolean;
+export declare function duplicateCell(view: EditorView, index?: number): boolean;
+export declare function deleteCell(view: EditorView, index?: number): boolean;
+/** Moves the active cell up or down. */
+export declare function moveCell(view: EditorView, delta: number): boolean;
+export declare function setCellType(view: EditorView, index: number, type: NotebookCellType): boolean;
 export declare function splitCell(view: EditorView): boolean;
 export declare function mergeCell(view: EditorView): boolean;
-export declare function toggleCellType(view: EditorView, index: number): boolean;
-export declare function setCellType(view: EditorView, index: number, type: NotebookCellType): boolean;
 /**
- * Notebook keymap. Mounted with high precedence so Alt-ArrowUp/Down move
- * cells instead of lines and Escape reaches command mode.
+ * The editor's cell commands. Everything here is also in the cell menu, and
+ * every one of them is a text edit, so the undo stack covers them all.
  */
 export declare const notebookKeymap: import("@codemirror/state").Extension;
 //#endregion
@@ -152,23 +183,29 @@ export interface TypstPluginOptions {
   /**
    * Called when a compile into the wasm instance threw. On wasm32 a panic
    * aborts the instance, so the host must recreate `typstState` and remount
-   * the editor; the plugin drops the decorations for the failed pass.
+   * the editor. The plugin drops the decorations for the failed pass.
    */
   onPanic?: (fileId: FileId) => void;
-  /** Called after a compile pass succeeds; the host resets its health and
+  /** Called after a compile pass succeeds. The host resets its health and
    *  heap watchdog on it. */
   onCompile?: () => void;
   /**
    * Opens a link clicked inside a rendered frame. Defaults to a new browser
-   * tab; the app passes its Tauri-aware `openExternal`.
+   * tab. The app passes its Tauri-aware `openExternal`.
    */
   onExternalLink?: (url: string) => void;
   /**
    * Cell rendering and cell commands. When set, the editor behaves like a
-   * notebook: markup cells render inline, code cells render below, and the
+   * notebook: prose cells render inline, code cells render below, and the
    * notebook keymap takes precedence over the line editing bindings.
    */
   notebook?: NotebookOptions;
+  /**
+   * Draw the frames, or show plain source. Defaults to true. A notebook page in
+   * source mode passes false: the cells and their rails stay, but nothing is
+   * rendered, which is the only difference between its write and source modes.
+   */
+  renderFrames?: boolean;
 }
 export declare const typstPlugin: (fileId: FileId, spaceId: string, path: string, text: TextRef, prelude: TextRef, locked: boolean, typstState: TypstState, options?: TypstPluginOptions) => Extension;
 //#endregion
@@ -206,17 +243,16 @@ export interface TypstLinterOptions {
 }
 /**
  * Typst diagnostics as a CodeMirror linter source.
- *
- * This runs in every editor mode and combines with other sources (the
- * spellcheck linter), so neither one replaces the other. The WYSIWYG plugin's
- * compile feeds the cache; split and source mode fall back to a compile here
- * so they get diagnostics too.
  */
 export declare const typstLinter: (fileId: FileId, spaceId: string, path: string, prelude: TextRef, typstState: TypstState, options?: TypstLinterOptions) => import("@codemirror/state").Extension;
 //#endregion
 //#region src/frames.d.ts
 /**
- * Opens an external link for the host. Browsers get a new tab; the app passes
+ * Places the glyph and gradient definitions a frame set references.
+ */
+export declare function installSharedDefs(defs: string | null | undefined): void;
+/**
+ * Opens an external link for the host. Browsers get a new tab. The app passes
  * its `openExternal`, which hands the URL to the system browser in Tauri
  * (a webview has no tab strip, so `window.open` is dropped there).
  */
@@ -241,8 +277,8 @@ export declare function frameSize(frame: SvgRangedFrame): {
  * container keeps max-width: 100% so it never exceeds the line. An explicit
  * container width would make CodeMirror's flex layout grow the content width
  * forever (resize -> wider widget -> wider content). The pinned SVG overflows
- * the clamped container while the pane is narrower than the compiled width;
- * the scroller clips it, so the render stays its size instead of scaling.
+ * the clamped container while the pane is narrower than the compiled width.
+ * The scroller clips it, so the render stays its size instead of scaling.
  */
 export declare function syncFrameContainer(container: HTMLElement, frame: SvgRangedFrame): void;
 /** Fresh frame container for widgets that own their DOM (notebook outputs). */
@@ -266,7 +302,7 @@ export declare function frameIsInactive(view: EditorView, state: EditorState, st
  * the source stays visible with the frame's height reserved, so the pane does
  * not jump between render and source. Matches the inline WYSIWYG behavior.
  *
- * `lineHeights` carries measured source heights from the remeasure pass; when
+ * `lineHeights` carries measured source heights from the remeasure pass. When
  * it is absent the view still reports the widget's height for those lines.
  */
 export declare function frameActiveDecorations(view: EditorView, state: EditorState, frame: SvgRangedFrame, lineHeights?: Map<number, number>): Range<Decoration>[];
@@ -304,6 +340,12 @@ export declare const typstLanguageData: import("@codemirror/state").Extension;
 //#region src/static-highlight.d.ts
 export declare const typstStaticHighlighting: StateField<DecorationSet>;
 //#endregion
+//#region src/sync.d.ts
+/**
+ * Keeps the engine's sources in step with the editor, without rendering.
+ */
+export declare const typstSourceSync: (fileId: FileId, prelude: TextRef, typstState: TypstState) => Extension;
+//#endregion
 //#region src/tooltip.d.ts
 export declare const tooltipStateField: StateField<Tooltip | null>;
 export declare const tooltipViewPlugin: () => ViewPlugin<{
@@ -311,9 +353,14 @@ export declare const tooltipViewPlugin: () => ViewPlugin<{
 }, undefined>;
 //#endregion
 //#region src/widgets.d.ts
+/**
+ * Compiled frames per cache key, where the key is `path:revision:appRevision`.
+ */
 export declare const compileCache: LRUCache<string, {
   frames: SvgRangedFrame[];
   tooltips: SvgRangedFrame[];
+  /** Every equation in the note, not only the one the caret was in. */
+  equationRanges: [number, number][];
   diagnostics: TypstDiagnostic[];
 }, unknown>;
 /**
@@ -321,8 +368,18 @@ export declare const compileCache: LRUCache<string, {
  * app data changed (fonts installed, workspace data, query results).
  */
 export declare const typstRecompileEffect: import("@codemirror/state").StateEffectType<null>;
-export declare const tooltipsStateEffect: import("@codemirror/state").StateEffectType<SvgRangedFrame[]>;
-export declare const tooltipsStateField: StateField<SvgRangedFrame[]>;
+export interface EquationOverlays {
+  /** Rendered overlays, at most one when the render was given a caret. */
+  tooltips: SvgRangedFrame[];
+  /**
+   * Every equation range in the note, not only the one the caret was in. The
+   * popup compares the cursor against these to know when it has entered math
+   * whose overlay the last render skipped.
+   */
+  ranges: [number, number][];
+}
+export declare const tooltipsStateEffect: import("@codemirror/state").StateEffectType<EquationOverlays>;
+export declare const tooltipsStateField: StateField<EquationOverlays>;
 export declare const typstStateField: StateField<DecorationSet>;
 export interface TypstViewPluginOptions {
   onRequests?: TypstRequestHandler;
@@ -330,13 +387,14 @@ export interface TypstViewPluginOptions {
   revision?: () => string | number | undefined;
   /** See TypstPluginOptions#onPanic. */
   onPanic?: (fileId: FileId) => void;
-  /** Called after a compile pass succeeds; the host resets its health and
+  /** Called after a compile pass succeeds. The host resets its health and
    *  heap watchdog on it. */
   onCompile?: () => void;
   /** See TypstPluginOptions#onExternalLink. */
   onExternalLink?: ExternalLinkOpener;
   /** Cell rendering, run effects, and cell commands for notebook mode. */
   notebook?: NotebookOptions;
+  renderFrames?: boolean;
 }
 export declare const typstViewPlugin: (fileId: FileId, spaceId: string, path: string, text: TextRef, prelude: TextRef, locked: boolean, typstState: TypstState, options?: TypstViewPluginOptions) => ViewPlugin<{
   update(update: ViewUpdate): void;