@typbase/codemirror 0.2.1

package/dist/index.d.mts

@@ -0,0 +1,346 @@
+import { CompletionContext, CompletionResult } from "@codemirror/autocomplete";
+import { Decoration, DecorationSet, EditorView, Tooltip, ViewPlugin, ViewUpdate, WidgetType } from "@codemirror/view";
+import { EditorState, Extension, Facet, Range, StateField } from "@codemirror/state";
+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 interface NotebookCell {
+  kind: NotebookCellType;
+  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;
+}
+/** UI strings, injected by the app so the package stays i18n-free. */
+export interface NotebookLabels {
+  run: string;
+  code: string;
+  markup: string;
+  moveUp: string;
+  moveDown: string;
+  duplicate: string;
+  remove: string;
+  clearOutput: string;
+  toggleSource: string;
+  noOutput: string;
+  error: string;
+}
+export interface NotebookCompileResult {
+  text: string;
+  frames: SvgRangedFrame[];
+  diagnostics: TypstDiagnostic[];
+}
+export interface NotebookOptions {
+  /** Cells for a document text; the host reads them from the engine. */
+  cells: (text: string) => NotebookCell[];
+  /** Run/visibility state per cell index. */
+  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. */
+  onCompile?: (result: NotebookCompileResult) => void;
+  onClearOutput?: (index: number) => void;
+  onToggleCollapse?: (index: number) => void;
+  /** Escape: leave edit mode and select the current cell. */
+  onCommandMode?: () => void;
+}
+/** 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). */
+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. */
+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;
+/** A text replacement plus where the cursor should land after it. */
+export interface CellEdit {
+  changes: {
+    from: number;
+    to?: number;
+    insert: string;
+  };
+  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;
+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.
+ */
+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 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 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.
+ */
+export declare const notebookKeymap: import("@codemirror/state").Extension;
+//#endregion
+//#region src/types.d.ts
+/**
+ * A minimal readable text handle. Vue refs (`Ref<string>`) satisfy this shape
+ * structurally, so both mnemo and Typbase can pass their refs unchanged.
+ */
+interface TextRef {
+  value: string;
+}
+/** Resolves the files a compile asked for (query JSON, embedded pages). */
+type TypstRequestHandler = (requests: import("@typbase/engine").TypstRequest[], spaceId: string) => Promise<boolean> | boolean;
+//#endregion
+//#region src/plugin.d.ts
+export interface TypstPluginOptions {
+  /**
+   * Called when Typst needs a source, file, or package that is not loaded
+   * yet. Return true when the request caused the world to change, so the
+   * editor recompiles.
+   */
+  onRequests?: TypstRequestHandler;
+  /** The revision of the document. */
+  revision?: () => string | number | undefined;
+  /**
+   * 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.
+   */
+  onPanic?: (fileId: FileId) => void;
+  /** 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`.
+   */
+  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 keymap takes precedence over the line editing bindings.
+   */
+  notebook?: NotebookOptions;
+}
+export declare const typstPlugin: (fileId: FileId, spaceId: string, path: string, text: TextRef, prelude: TextRef, locked: boolean, typstState: TypstState, options?: TypstPluginOptions) => Extension;
+//#endregion
+//#region src/commands.d.ts
+export declare function toggleStrong(view: EditorView): boolean;
+export declare function toggleEmph(view: EditorView): boolean;
+export declare function toggleUnderline(view: EditorView): boolean;
+export declare function toggleStrike(view: EditorView): boolean;
+export declare function toggleMath(view: EditorView): boolean;
+export declare function insertTabLike(view: EditorView): boolean;
+export declare function toggleCode(view: EditorView): boolean;
+export declare function insertFontFamily(n: EditorView, font: string): boolean;
+export declare function cycleHeading(view: EditorView): boolean;
+export declare function insertAtCursor(n: EditorView, e: string): void;
+export declare function wrapOrInsert(view: EditorView, prefix: string, suffix: string, insert: string): void;
+interface Replacement {
+  regex: RegExp;
+  replacement: string;
+}
+export declare function toggleAroundSelection(view: EditorView, prefixes: (string | Replacement)[], suffixes: (string | Replacement)[], preferNextLevel?: boolean): null;
+export declare function toggleList(n: EditorView): boolean;
+export declare function toggleEnum(n: EditorView): boolean;
+export declare function toggleListLike(view: EditorView, prefix: string): void;
+export declare function cursorAddVertical(view: EditorView, offset: number): boolean;
+//#endregion
+//#region src/diagnostics.d.ts
+export declare function rememberDiagnostics(path: string, text: string, diagnostics: TypstDiagnostic[]): void;
+/** Converts engine diagnostics into CodeMirror lint diagnostics. */
+export declare function toLintDiagnostics(typstDiagnostics: TypstDiagnostic[]): Diagnostic[];
+export interface TypstLinterOptions {
+  onRequests?: TypstRequestHandler;
+  onPanic?: (fileId: FileId) => void;
+  /** Called after a diagnostics compile succeeds. */
+  onCompile?: () => void;
+}
+/**
+ * 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
+ * its `openExternal`, which hands the URL to the system browser in Tauri
+ * (a webview has no tab strip, so `window.open` is dropped there).
+ */
+export type ExternalLinkOpener = (url: string) => void;
+/**
+ * The compiled size of an SVG frame, from the markup's viewBox. The viewBox
+ * is the page width the engine laid out at (pt), and the app renders one
+ * Typst point per CSS pixel, so the numbers map to px directly.
+ *
+ * `frame.render.width` is the chunk's bounding-box width, which does not
+ * change with the pane for fixed-size blocks (images, boxes). The viewBox
+ * width is the correct resize key and the size to pin: a render laid out
+ * for a wider pane must keep its size, not be stretched by CSS while a
+ * resize is in flight.
+ */
+export declare function frameSize(frame: SvgRangedFrame): {
+  width: number;
+  height: number;
+};
+/**
+ * Pins a container's SVG to the compiled frame size (via CSS variables). The
+ * 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.
+ */
+export declare function syncFrameContainer(container: HTMLElement, frame: SvgRangedFrame): void;
+/** Fresh frame container for widgets that own their DOM (notebook outputs). */
+export declare function createFrameContainer(frame: SvgRangedFrame): HTMLElement;
+/**
+ * Click handling shared by inline widgets and notebook outputs: typbase://
+ * links are left for the host's anchor router, external links confirm first
+ * and go through `openExternal`, anything else maps back into the compiled
+ * document and moves the cursor. Alt-click edits the link instead of
+ * following it.
+ */
+export declare function attachFrameInteractions(container: HTMLElement, view: EditorView, frame: SvgRangedFrame, fileId: FileId, typstState: TypstState, openExternal?: ExternalLinkOpener): void;
+/**
+ * True when the selection does not touch `start..end`, so the frame can render
+ * as a widget instead of showing source. Shared by the inline WYSIWYG pass and
+ * the notebook markup cells.
+ */
+export declare function frameIsInactive(view: EditorView, state: EditorState, start: number, end: number): boolean;
+/**
+ * Line decorations that stand in for a frame while the cursor is inside it:
+ * 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
+ * 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>[];
+export declare class TypstWidget extends WidgetType {
+  private readonly view;
+  private readonly frame;
+  private readonly locked;
+  private readonly fileId;
+  private readonly typstState;
+  private readonly openExternal?;
+  private container;
+  private readonly size;
+  constructor(view: EditorView, frame: SvgRangedFrame, locked: boolean, fileId: FileId, typstState: TypstState, openExternal?: ExternalLinkOpener | undefined);
+  eq(other: TypstWidget): boolean;
+  toDOM(): HTMLElement;
+  get estimatedHeight(): number;
+}
+//#endregion
+//#region src/highlight.d.ts
+export declare const typstSyntaxHighlighting: (fileId: FileId, typstState: TypstState) => StateField<DecorationSet>;
+export declare const parseBackticks: (str: string, into: HTMLElement) => void;
+//#endregion
+//#region src/hover.d.ts
+export declare const typstHoverTooltip: (fileId: FileId, typstState: TypstState) => import("@codemirror/state").Extension & {
+  active: import("@codemirror/state").StateField<readonly import("@codemirror/view").Tooltip[]>;
+};
+//#endregion
+//#region src/keymap.d.ts
+export declare const typstKeymap: import("@codemirror/state").Extension;
+//#endregion
+//#region src/language.d.ts
+export declare function autocomplete(context: CompletionContext, fileId: FileId, typstState: TypstState): Promise<CompletionResult | null>;
+export declare const typstLanguageData: import("@codemirror/state").Extension;
+//#endregion
+//#region src/static-highlight.d.ts
+export declare const typstStaticHighlighting: StateField<DecorationSet>;
+//#endregion
+//#region src/tooltip.d.ts
+export declare const tooltipStateField: StateField<Tooltip | null>;
+export declare const tooltipViewPlugin: () => ViewPlugin<{
+  update(update: ViewUpdate): void;
+}, undefined>;
+//#endregion
+//#region src/widgets.d.ts
+export declare const compileCache: LRUCache<string, {
+  frames: SvgRangedFrame[];
+  tooltips: SvgRangedFrame[];
+  diagnostics: TypstDiagnostic[];
+}, unknown>;
+/**
+ * Dispatch this to recompile even when the document did not change. Used when
+ * 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 declare const typstStateField: StateField<DecorationSet>;
+export interface TypstViewPluginOptions {
+  onRequests?: TypstRequestHandler;
+  /** Extra component of the compile cache key: app data revisions. */
+  revision?: () => string | number | undefined;
+  /** See TypstPluginOptions#onPanic. */
+  onPanic?: (fileId: FileId) => void;
+  /** 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;
+}
+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;
+  destroy(): void;
+}, undefined>;
+//#endregion
+export type { TextRef, TypstRequestHandler };