@elabs-ai/components-editor 4.0.0

package/dist/markdown-editor-DfBZibAn.d.ts

@@ -0,0 +1,702 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+import * as monaco from 'monaco-editor';
+import { IRange } from 'monaco-editor';
+import { Ctx } from '@milkdown/kit/ctx';
+import { Schema, NodeType } from '@milkdown/kit/prose/model';
+import { Command } from '@milkdown/kit/prose/state';
+
+type MonacoCodeEditor = monaco.editor.IStandaloneCodeEditor;
+/** A Monaco editor action (system command + optional hotkey + palette/menu entry). */
+type EditorAction = monaco.editor.IActionDescriptor;
+interface CodeEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled content. Pair with `onChange`. */
+    value?: string;
+    /** Initial content for uncontrolled use. */
+    defaultValue?: string;
+    /** Fires on every edit with the full document text. */
+    onChange?: (value: string) => void;
+    /** Monaco language id (e.g. "typescript", "json"). Defaults to "typescript". */
+    language?: string;
+    /** Model path/URI — drives per-file language services + diagnostics. */
+    path?: string;
+    /** Render the editor read-only. */
+    readOnly?: boolean;
+    /** Editor height. Number → px. Defaults to "100%" (size via the parent). */
+    height?: number | string;
+    /** Passthrough Monaco construction options (merged over the defaults). */
+    options?: monaco.editor.IStandaloneEditorConstructionOptions;
+    /**
+     * Accessible name for the editor. Maps onto Monaco's `ariaLabel` construction
+     * option AND the inner screen-reader `<textarea>` (`aria-label`), so assistive
+     * tech announces a name. Spreading `aria-label` via `...props` only lands on the
+     * wrapper div and never reaches Monaco's focusable textarea — use this instead.
+     */
+    ariaLabel?: string;
+    /** Sets `aria-invalid` on Monaco's inner `<textarea>` to convey validity. */
+    ariaInvalid?: boolean;
+    /** Sets `aria-describedby` on Monaco's inner `<textarea>` (e.g. an error id). */
+    ariaDescribedBy?: string;
+    /**
+     * Right-click menu. `"brand"` (default) replaces Monaco's built-in menu with
+     * brand-ui's `ContextMenu`; `"monaco"` keeps Monaco's themed menu; `"none"`
+     * disables it.
+     */
+    contextMenu?: "brand" | "monaco" | "none";
+    /** Called once the editor instance + monaco namespace are ready. */
+    onMount?: (editor: MonacoCodeEditor, monacoApi: typeof monaco) => void;
+    /**
+     * Declarative Monaco editor actions — each registers a command (run on its
+     * `keybindings`, in the command palette, and optionally the context menu via
+     * `contextMenuGroupId`). Wraps `editor.addAction`; re-registered when the array
+     * identity changes, disposed on unmount. Build keybindings with the re-exported
+     * `monaco` namespace, e.g. `keybindings: [monaco.KeyMod.CtrlCmd | monaco.KeyCode.Slash]`.
+     *
+     * Note: a context-menu entry only shows when `contextMenu="monaco"`, but the
+     * keybinding and command palette work regardless. Memoize `actions` to avoid
+     * re-registering on every render.
+     */
+    actions?: EditorAction[];
+}
+/**
+ * A token-themed Monaco editor wrapped as a brand-ui React component. Monaco
+ * renders its own editing surface + widgets; this wrapper owns lifecycle,
+ * controlled/uncontrolled value, and applies the brand theme bridge so the
+ * editor matches the active `data-theme` (all three themes).
+ *
+ * Workers (for completions/diagnostics) are wired by importing
+ * `@elabs-ai/components-editor/monaco-environment` once at the app entry.
+ */
+declare const CodeEditor: react.ForwardRefExoticComponent<CodeEditorProps & react.RefAttributes<monaco.editor.IStandaloneCodeEditor | null>>;
+
+/**
+ * CalcBlock contracts — the shape the consumer's `evaluate` hook returns.
+ *
+ * The library RENDERS; the consumer EVALUATES. The math engine is app/domain
+ * logic and must NOT live in the design system — so these are pure types and the
+ * library never bundles a calculator (mirrors how `resolveUrl` keeps URL
+ * resolution in the consumer). A consumer produces a `CalcSheet` from a ```calc
+ * source; CalcBlock paints it.
+ */
+type CalcValueKind = "number" | "quantity" | "currency" | "date" | "duration" | "percent" | "text" | "error";
+/** A typed result value; `display` is the locale-formatted, tabular-ready string. */
+interface CalcValue {
+    kind: CalcValueKind;
+    raw: number | string;
+    unit?: string;
+    display: string;
+}
+type CalcTokenKind = "number" | "unit" | "currency" | "operator" | "function" | "constant" | "comment" | "var-def" | "var-ref" | "line-ref" | "unknown";
+/** One highlighted span within a source line — 0-based columns, `end` exclusive. */
+interface CalcToken {
+    start: number;
+    end: number;
+    kind: CalcTokenKind;
+    /** `false` → a non-fatal warning style (unknown identifier / dangling ref). */
+    resolved: boolean;
+}
+/**
+ * Presentation hint: a rule (horizontal divider) drawn below a row — a `"dotted"`
+ * hairline, a `"single"` solid line, or a `"double"` line (e.g. above a subtotal).
+ * Pure presentation: the library renders it; the evaluator decides which rows get one.
+ */
+type CalcRule = "dotted" | "single" | "double";
+/**
+ * Presentation hint: tint a row's background with a semantic status wash
+ * (theme-safe `bg-<token>/10`, matching the house status vocabulary). `"muted"`
+ * is a neutral, non-status tint. The evaluator decides; the library paints.
+ */
+type CalcTint = "primary" | "success" | "warning" | "destructive" | "info" | "muted";
+/** One evaluated source line: its highlight tokens, and a value OR an error. */
+interface CalcLineResult {
+    /** 1-based line within the calc source. */
+    line: number;
+    tokens: CalcToken[];
+    value?: CalcValue;
+    /** A per-line error rendered inline; never thrown. */
+    error?: {
+        message: string;
+    };
+    /** Presentation hint: draw a rule (divider) below this row. */
+    rule?: CalcRule;
+    /** Presentation hint: tint this row's background with a semantic wash. */
+    tint?: CalcTint;
+}
+interface CalcSheet {
+    results: CalcLineResult[];
+    /** Running total for the block. */
+    total?: CalcValue;
+}
+interface CalcContext {
+    docPath?: string;
+}
+/** The consumer-supplied evaluator (sync, like `resolveUrl`). */
+type EvaluateCalc = (source: string, ctx?: CalcContext) => CalcSheet;
+/**
+ * Tokenize ONE calc source line into highlight spans (the columns the library
+ * paints). Called per line, so the returned {@link CalcToken} `start`/`end`
+ * columns are relative to `line` — the same shape `evaluate` already returns on
+ * each `CalcLineResult.tokens`. Sync, like `resolveUrl`.
+ */
+type CalcTokenize = (line: string, ctx?: CalcContext) => CalcToken[];
+/** A completion category — drives the icon (Monaco) / glyph + label (WYSIWYG). */
+type CalcCompletionKind = "variable" | "function" | "unit" | "currency" | "constant" | "reference" | "keyword" | "snippet";
+/** One autocomplete suggestion offered inside a ```calc fence. */
+interface CalcCompletion {
+    /** Text shown in the completion list. */
+    label: string;
+    /** Text inserted when the item is chosen (replaces the typed `prefix`). */
+    insert: string;
+    /** Secondary detail shown muted beside the label (e.g. a type or preview). */
+    detail?: string;
+    /** Category; selects the suggestion icon. Defaults to `"variable"`. */
+    kind?: CalcCompletionKind;
+}
+/** What the editor knows at the caret when it asks the consumer for completions. */
+interface CalcCompletionContext extends CalcContext {
+    /** The full calc fence body (all lines). */
+    source: string;
+    /** The current line's text (the line the caret is on). */
+    line: string;
+    /** 1-based line of the caret within the fence body. */
+    lineNumber: number;
+    /** 0-based caret column within `line`. */
+    column: number;
+    /** The identifier characters immediately before the caret (the word typed). */
+    prefix: string;
+}
+/** Suggest completions at the caret inside a ```calc fence (sync). */
+type CalcComplete = (ctx: CalcCompletionContext) => CalcCompletion[];
+/**
+ * The opt-in authoring hooks threaded onto `MarkdownEditor` / `MarkdownWorkspace`
+ * via the `calc` prop (off by default). Each capability is independent:
+ *   - `tokenize` → syntax highlighting (falls back to `evaluate`'s per-line
+ *     `tokens` when omitted, so a consumer who already wrote `evaluate` gets
+ *     highlighting for free).
+ *   - `evaluate` → per-line result inlays (the computed answer, shown after the
+ *     line). Reuses the existing {@link EvaluateCalc} contract.
+ *   - `complete` → autocomplete inside the fence (Monaco surface).
+ */
+interface CalcEditorHooks {
+    tokenize?: CalcTokenize;
+    complete?: CalcComplete;
+    evaluate?: EvaluateCalc;
+}
+
+/**
+ * Engine-agnostic completion-provider contract (#283) — the `completions` prop
+ * on `MarkdownWorkspace` (and, via it, the WYSIWYG `MarkdownEditor`).
+ *
+ * ISOLATION INVARIANT (mirrors `editor-content-access.ts`): this file imports
+ * NOTHING engine-specific — no `monaco-editor`, no `@milkdown`. It is the
+ * dependency-light leaf both engine adapters (`editor-completions-monaco.ts` for
+ * Monaco, `markdown-editor/completions/` for Milkdown/ProseMirror) build on, so a
+ * consumer can import the TYPES with zero engine imports (#283 acceptance: "zero
+ * `monaco-editor` imports in app code").
+ *
+ * D5 / the calc `complete` hook precedent: the library only REGISTERS the
+ * provider and RENDERS its suggestions — candidate list, filtering/ranking, and
+ * insert text are entirely consumer-owned. Nothing here fetches anything; a
+ * throwing/rejecting `provide()` degrades to "no suggestions" (never blanks or
+ * throws), the same degrade-safely contract as `resolveResults`/`CalcBlock`.
+ */
+/** One completion candidate a provider offers at the caret. */
+interface EditorCompletionItem {
+    /** Text shown in the suggestion list. */
+    label: string;
+    /** Text inserted when the item is chosen. */
+    insertText: string;
+    /** Secondary detail shown muted beside the label. */
+    detail?: string;
+    /**
+     * Start column (1-based, Monaco convention) of the already-typed token to
+     * replace. Defaults to the start of the "trigger query" — the run of text
+     * typed since the provider's trigger character (see {@link triggerQueryStart}).
+     */
+    replaceFrom?: number;
+}
+/** What a provider knows at the caret when it is asked for completions. */
+interface EditorCompletionContext {
+    /** The full document text. */
+    source: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column. */
+    column: number;
+    /** The full text of the current line. */
+    lineText: string;
+}
+/**
+ * A declarative completion source. Registered ONCE per `MarkdownWorkspace` (or
+ * `MarkdownEditor`) tree via the `completions` prop — the library owns the
+ * engine registration lifecycle (Monaco's `registerCompletionItemProvider` is
+ * global-per-language, refcounted here; see `editor-completions-monaco.ts`).
+ */
+interface EditorCompletionProvider {
+    /** Stable id — surfaced for consumer bookkeeping (not currently rendered). */
+    id: string;
+    /** Characters that (re)open the suggestion list, e.g. `["["]`. */
+    triggerCharacters?: string[];
+    /** Return the candidates for the caret described by `ctx`. May be async. */
+    provide(ctx: EditorCompletionContext): EditorCompletionItem[] | Promise<EditorCompletionItem[]>;
+}
+/**
+ * Find the 1-based column right after the LAST occurrence, before `column`, of
+ * any of `triggerCharacters` in `lineText` — the start of the "trigger query"
+ * (the text typed since the trigger character). `null` when no trigger
+ * character precedes the caret on this line (falls back to inserting at the
+ * bare caret — see {@link resolveReplaceRange}).
+ *
+ * Deliberately the LAST occurrence, not the first: `[[note` (triggerCharacters
+ * `["["]`) resolves the query start to right after the SECOND `[`, so the
+ * inserted text replaces only `note`, preserving the `[[` the user typed.
+ */
+declare function triggerQueryStart(lineText: string, column: number, triggerCharacters: string[] | undefined): number | null;
+/** A 1-based, Monaco-`IRange`-shaped span (structural — no monaco import). */
+interface CompletionReplaceRange {
+    startLineNumber: number;
+    startColumn: number;
+    endLineNumber: number;
+    endColumn: number;
+}
+/**
+ * Resolve the range an item's `insertText` replaces: `item.replaceFrom` when
+ * given, else the trigger-query start (see {@link triggerQueryStart}), else the
+ * bare caret (a pure insert, nothing replaced). Always ends at the caret, on
+ * the caret's line — a completion never spans multiple lines.
+ */
+declare function resolveReplaceRange(item: EditorCompletionItem, position: {
+    lineNumber: number;
+    column: number;
+}, lineText: string, triggerCharacters: string[] | undefined): CompletionReplaceRange;
+/** One resolved completion item, paired with the provider that produced it. */
+interface CompletionMatch {
+    provider: EditorCompletionProvider;
+    item: EditorCompletionItem;
+}
+/**
+ * Call every provider's `provide(ctx)`, collect the results, and pair each item
+ * back with its provider (so a caller can resolve a per-provider replace range
+ * via that provider's `triggerCharacters`). Never throws: a provider whose
+ * `provide()` throws or whose returned promise rejects contributes zero items
+ * (mirrors `resolveResults`'s calc-hook degrade-safely contract) — one bad
+ * provider never blanks another's suggestions.
+ */
+declare function collectCompletions(providers: EditorCompletionProvider[], ctx: EditorCompletionContext): Promise<CompletionMatch[]>;
+
+/**
+ * Engine-agnostic editor content-access interface + Monaco adapter.
+ *
+ * ISOLATION INVARIANT: this file imports ONLY `monaco-editor` and the
+ * `MonacoCodeEditor` type from `../code-editor`. It MUST NOT import
+ * `editor-content-access-prose.ts` or anything from `@milkdown`, or the
+ * `@milkdown` graph leaks into the `.` barrel (#271-inverse).
+ */
+
+/** A snapshot of the editor's current selection. Text, not engine positions —
+ *  that is what an AI assistant needs and it keeps the interface engine-agnostic. */
+interface EditorSelection {
+    /**
+     * The selected text. Plain text for Monaco. For the Milkdown WYSIWYG it is the
+     * selection SERIALIZED TO MARKDOWN by default (so `**bold**`, links, lists round-trip);
+     * pass `{ fidelity: "plainText" }` to the adapter to get `doc.textBetween` instead.
+     */
+    text: string;
+    /** `true` when the selection is collapsed (a bare caret, nothing highlighted). */
+    empty: boolean;
+}
+/**
+ * Engine-agnostic, text-oriented access to an editor's content + selection — the
+ * uniform surface an external AI assistant drives across the Monaco code editors
+ * AND the Milkdown WYSIWYG markdown editor.
+ *
+ * D5: this manipulates EDITOR CONTENT only. It performs no model calls, no transport,
+ * no fetch. The app owns the AI call and APPLIES the result via these methods.
+ *
+ * `replaceSelection` and `insertAtCursor` are equivalent primitives (both replace the
+ * active range; an empty range is the caret) — two names for two reader intents.
+ */
+interface EditorContentAccess {
+    /** The full document text (Monaco: source; Milkdown: serialized markdown). */
+    getText(): string;
+    /** A snapshot of the current selection (selected text + whether collapsed). */
+    getSelection(): EditorSelection;
+    /** Replace the current selection; a collapsed selection inserts at the caret. */
+    replaceSelection(text: string): void;
+    /**
+     * Insert at the caret; a non-empty selection is replaced (platform "typing" semantics).
+     * Equivalent to `replaceSelection` — two names for two reader intents (agent-legibility).
+     */
+    insertAtCursor(text: string): void;
+    /** Move focus to the editing surface (so the user can keep typing after an apply). */
+    focus(): void;
+    /**
+     * Subscribe to selection changes. Fires with a fresh `EditorSelection` whenever the
+     * selection or caret moves. Returns an unsubscribe function — the caller MUST call it
+     * (e.g. in a React effect cleanup) to dispose the underlying engine listener.
+     */
+    onSelectionChange(listener: (selection: EditorSelection) => void): () => void;
+}
+/**
+ * Wrap a live Monaco `IStandaloneCodeEditor` as the engine-agnostic
+ * {@link EditorContentAccess}. The `CodeEditor` / `DiffEditor` / `CodeWorkspace`
+ * `ref` already exposes the raw Monaco instance — pass it here to get the
+ * uniform shape used by the markdown surfaces.
+ *
+ * For a `DiffEditor`, pass the modified (editable) side:
+ * `monacoContentAccess(diffRef.current!.getModifiedEditor())`.
+ *
+ * @example
+ *   const editorRef = useRef<MonacoCodeEditor>(null);
+ *   // ...later
+ *   const access = monacoContentAccess(editorRef.current!);
+ *   access.insertAtCursor(aiText);
+ */
+declare function monacoContentAccess(editor: MonacoCodeEditor): EditorContentAccess;
+
+/**
+ * paste-embed — ProseMirror plugin + helper for image paste/drop embedding.
+ *
+ * When `onEmbedAsset` is provided by the host:
+ *   1. Intercepts paste (from clipboard) or drop events carrying image files.
+ *   2. Inserts an inline "uploading…" widget Decoration at the caret/drop position.
+ *   3. Calls `onEmbedAsset(file)` and on resolve inserts a real image node, removing
+ *      the placeholder.
+ *   4. On reject removes the placeholder and renders a transient inline error
+ *      decoration (role="alert", auto-dismissed after 4 s) + toast.error().
+ *
+ * The plugin is a raw `$prose` ProseMirror plugin (same pattern as the slash menu),
+ * so it pulls zero new dependencies beyond what Milkdown already provides.
+ *
+ * A11y:
+ *   - Upload placeholder: role="status" aria-live="polite"
+ *   - Error decoration: role="alert" (assertive; fires once and auto-dismisses)
+ *
+ * Motion: gated via `duration-normal ease-standard motion-reduce:transition-none`
+ * token utilities (defined in @elabs-ai/components-tokens).
+ */
+
+/** The host-provided hook: receives a File, resolves to a URL/path string. */
+type EmbedAssetFn = (file: File) => Promise<string>;
+
+interface IterationEditRequest {
+    /** Which directive asked to be edited. */
+    kind: "iterate" | "pivot";
+    /** The current template markdown (the node body, serialized). */
+    template: string;
+    /** Apply the edited template back to the node. */
+    onSave: (template: string) => void;
+    /**
+     * The directive's current attributes (value lists, bind name, layout) — present
+     * when the node-view supports GUIDED re-editing (A5). The
+     * `IterationBuilderProvider` reads these to reopen the builder with its data;
+     * the template-only `IterationTemplateProvider` ignores them.
+     */
+    attributes?: Record<string, string>;
+    /**
+     * Write back BOTH the attributes and the template (the guided builder path). When
+     * present it is preferred over {@link onSave} (which only rewrites the body).
+     */
+    onSaveData?: (next: {
+        attributes: Record<string, string>;
+        template: string;
+    }) => void;
+    /**
+     * Directly rewrite the node's attributes (e.g. the node-menu's "Change layout" /
+     * "Transpose" actions) without touching the template body. Additive (#223) —
+     * present alongside {@link onSave}/{@link onSaveData} for back-compat; a
+     * consumer-side surface (a future dialog action) can reach the same write the
+     * node-view's own menu uses.
+     */
+    onSetAttributes?: (attributes: Record<string, string>) => void;
+    /**
+     * Replace the ENTIRE directive node with plain markdown — e.g. the node-menu's
+     * "Convert to static" action (the evaluated, populated result). After this the
+     * node stops being a `:::iterate`/`:::pivot` directive. Additive (#223).
+     */
+    onReplaceWithMarkdown?: (markdown: string) => void;
+}
+/** A consumer handler that opens the template editor for a request. */
+type IterationEditHandler = (request: IterationEditRequest) => void;
+/** Provide a handler to enable the node-view `⋯` re-edit affordance. */
+declare const IterationEditContext: react.Context<IterationEditHandler | null>;
+
+/**
+ * Pure ProseMirror insertion commands for the slash menu.
+ *
+ * The load-bearing logic of the slash menu lives here, deliberately decoupled
+ * from Milkdown's context and from React: an `insertBrandDirective` factory that
+ * builds the right `brand_container_directive` / `brand_leaf_directive` node (from
+ * the schemas in `directive-nodes.ts`) with sensible default attrs + a placeholder
+ * body, replaces the active slash range (or inserts at the cursor), and drops the
+ * caret into the first editable field. Because it takes the NodeTypes/Schema as
+ * arguments (not a Milkdown `Ctx`), it is unit-testable against a hand-built
+ * ProseMirror state and its output round-trips losslessly through the editor's
+ * existing `toMarkdown` runners (asserted in insert-directive.test.ts).
+ *
+ * `resolveBrandInsert` is the thin Milkdown-aware adapter: it reads the NodeTypes
+ * from the editor `Ctx` and returns the same pure command — so the slash plugin
+ * and any direct caller share one implementation.
+ */
+
+/** A `[from, to)` document range to replace (the typed `/query`), or `null`. */
+interface SlashRange {
+    from: number;
+    to: number;
+}
+/** The directive names the slash menu can insert as brand blocks. */
+type InsertableDirective = "card" | "callout" | "timeline" | "metric" | "iterate" | "pivot";
+/**
+ * The pure insertion command. Builds the directive node from the given
+ * NodeTypes + schema and replaces `range` (or the current selection when
+ * `range` is null), then positions the caret in the first editable field
+ * (the body's start for containers; just after the atomic leaf for metric).
+ *
+ * Returns a ProseMirror `Command` `(state, dispatch?) => boolean`.
+ */
+declare function insertBrandDirective(name: InsertableDirective, containerType: NodeType, leafType: NodeType, schema: Schema, range: SlashRange | null): Command;
+/** Map a basic-block id to a ProseMirror command that inserts the native node. */
+declare function insertBasicBlock(id: BasicBlockId, schema: Schema, range: SlashRange | null): Command;
+/** Seed body for a fresh ```calc fence — a tiny ledger so highlight + inlays show at once. */
+declare const CALC_FENCE_SEED: string;
+/**
+ * Insert a ```calc fence (a `code_block` with `language: "calc"`) seeded with a
+ * short example, then drop the caret into the body. The editor's calc layer
+ * (`calc-editor-prose`) highlights + adds result inlays once `calc` hooks are wired;
+ * with none it is just a fenced code block (and renders as a `CalcBlock` in preview
+ * when `evaluate` is supplied) — so inserting one is always safe.
+ */
+declare function insertCalcFence(schema: Schema, range: SlashRange | null, seed?: string): Command;
+/** Milkdown-aware adapter for {@link insertCalcFence}. */
+declare function resolveCalcInsert(ctx: Ctx, range: SlashRange | null): boolean;
+
+/**
+ * The brand slash-command registry — pure, typed, tree-shakeable data.
+ *
+ * Each command is a label + group + match keywords + an icon + a `run` that
+ * inserts the corresponding block at the caret. `run` is given a
+ * {@link SlashInsertContext} (the Milkdown `Ctx` + the active `/query` range);
+ * brand directives delegate to `resolveBrandInsert`, basic blocks to
+ * `resolveBasicInsert` — so the SAME registry drives the menu and any
+ * programmatic insert, and the load-bearing insertion logic stays in
+ * `insert-directive.ts` (unit-tested there).
+ *
+ * Defaults: card · callout · metric · timeline ("Brand blocks") +
+ * heading · bullet-list · ordered-list · quote · code · divider ("Basic").
+ * Consumers can extend or replace the list via the `slashMenu` prop.
+ *
+ * `runInSource` (#299) is an OPTIONAL, ADDITIVE second handler for the Monaco
+ * source pane — `run` (Milkdown) stays untouched, so the 12 default commands
+ * need zero migration. `MonacoCodeEditor` / `IRange` / `EditorContentAccess`
+ * below are TYPE-ONLY imports (erased at build) — this file stays free of any
+ * `monaco-editor` RUNTIME import, so the Milkdown-facing `slash/index.ts`
+ * barrel this file feeds still pulls zero Monaco code.
+ */
+
+/** The native (non-directive) blocks the slash menu can insert. */
+type BasicBlockId = "heading" | "bullet-list" | "ordered-list" | "quote" | "code" | "divider";
+/**
+ * Context handed to a {@link SlashCommand.run}. `ctx` is the live Milkdown editor
+ * context; `range` is the `[from, to)` document range of the typed trigger +
+ * query (so the command replaces it), or `null` to insert at the caret.
+ */
+interface SlashInsertContext {
+    ctx: Ctx;
+    range: SlashRange | null;
+}
+/**
+ * Context handed to a {@link SlashCommand.runInSource} (#299) — the Monaco
+ * SOURCE-pane counterpart to {@link SlashInsertContext}. By the time this runs,
+ * the typed `/query` trigger has already been stripped from the document (the
+ * same edit `cancel` uses), so the handler starts from a clean doc.
+ */
+interface SourceSlashContext {
+    /** The raw Monaco editor instance — full imperative access when needed. */
+    editor: MonacoCodeEditor;
+    /**
+     * Model range the typed `/query` trigger occupied (already removed by the
+     * time this fires) — `null` on the hotkey path, where no `/` was ever typed.
+     */
+    range: IRange | null;
+    /** Engine-agnostic content access (get/replace-selection/insert-at-cursor). */
+    content: EditorContentAccess;
+}
+/** One entry in the slash menu. Pure data + an insertion `run`. */
+interface SlashCommand {
+    /** Stable id (used as the React key + `aria-activedescendant` target). */
+    id: string;
+    /** Visible label, e.g. "Card". */
+    label: string;
+    /** Grouping header, e.g. "Brand blocks" | "Basic". */
+    group?: string;
+    /** A short description shown under the label. */
+    description?: string;
+    /** Extra fuzzy-match aids beyond the label (matched case-insensitively). */
+    keywords?: string[];
+    /** Leading icon (a Lucide glyph or any node). */
+    icon?: ReactNode;
+    /**
+     * Markdown SNIPPET the source / split toolbar's Insert menu inserts (text mode).
+     * Optional: commands without one — the basic blocks, which already have their
+     * own toolbar buttons — don't appear in that menu. Brand blocks set this so the
+     * source toolbar inserts the SAME directive / fence the WYSIWYG `run` builds, so
+     * the two surfaces stay at parity. (A4)
+     */
+    snippet?: string;
+    /** Insert the block at the caret. WYSIWYG (Milkdown) — UNCHANGED (#299). */
+    run: (ctx: SlashInsertContext) => void;
+    /**
+     * OPTIONAL source-pane (Monaco) handler (#299) — for a RUN-ONLY command (no
+     * `snippet`, e.g. an "Ask AI" entry) that can't express itself as a markdown
+     * insert. When present, selecting the command in the Monaco source-pane menu
+     * (`MonacoSlashMenu`) strips the typed `/query` first, then calls this with
+     * the live editor + the (now-stripped) trigger range + engine-agnostic
+     * content access — instead of the `snippet`-only `commitSnippet` fallback. A
+     * command needs only ONE of `snippet` / `runInSource` to appear in source (both
+     * is fine too — `runInSource` wins there since it's the more capable handler).
+     */
+    runInSource?: (ctx: SourceSlashContext) => void;
+    /**
+     * OPTIONAL guided variant (#223, WYSIWYG only). When present AND the
+     * consumer has wired an `IterationEditContext` handler (an
+     * `IterationBuilderProvider` / `IterationTemplateProvider` above the
+     * editor), this REPLACES `run` — it opens the guided modal seeded blank
+     * instead of inserting a bare directive. Falls back to `run` when no
+     * handler is available, so the 12 non-guided default commands need zero
+     * changes. Set on the `iterate` / `pivot` commands only.
+     */
+    guided?: (insert: SlashInsertContext, handler: IterationEditHandler) => void;
+}
+/**
+ * The default command list. Brand blocks first (the wedge), then the basics.
+ * The brand-block icons reuse the `data-brand-directive` chrome look via Lucide
+ * stand-ins (the editor renders the real component once inserted).
+ */
+declare const BRAND_SLASH_COMMANDS: SlashCommand[];
+/**
+ * Filter a command list by a query (case-insensitive substring over label +
+ * keywords). An empty query returns the full list (in registry order).
+ */
+declare function filterSlashCommands(commands: SlashCommand[], query: string): SlashCommand[];
+/** Preserve registry order while grouping; used by the menu to render headers. */
+declare function groupSlashCommands(commands: SlashCommand[]): {
+    group: string;
+    commands: SlashCommand[];
+}[];
+
+/**
+ * Imperative handle exposed via `ref`.
+ *
+ * Extends {@link EditorContentAccess} so any consumer of a `MarkdownEditor`
+ * ref can drive AI editing operations (insert, replace, subscribe to selection)
+ * through the engine-agnostic interface, alongside the markdown-specific helpers.
+ *
+ * `getText()` is an alias for `getMarkdown()` (same output; both return the full
+ * document serialized to markdown). The duplication is intentional: `getText`
+ * satisfies the `EditorContentAccess` interface contract; `getMarkdown` is the
+ * historically-named markdown-specific method. JSDoc notes the equivalence.
+ */
+interface MarkdownEditorHandle extends EditorContentAccess {
+    /**
+     * Serialize the current document to a markdown string.
+     * Equivalent to `getText()` — both return the full document as markdown.
+     */
+    getMarkdown: () => string;
+    /**
+     * Serialize the current document, or `null` while the engine is still
+     * booting. Used to capture the pre-edit normalization BASELINE for the
+     * lossless-edit merge (WI-1) — unlike `getMarkdown` it never falls back to
+     * the raw input, so a non-null result is always the editor's own output.
+     */
+    serialized: () => string | null;
+    /**
+     * Best-effort: scroll the heading whose outline slug matches into view (#273).
+     * Walks the ProseMirror doc for `heading` nodes, slugifies their text with the
+     * same algorithm as `parseMarkdownOutline`, and scrolls the first match into
+     * view. No-op (never throws) while the engine is booting or if no match.
+     */
+    scrollToHeading: (slug: string) => void;
+    /**
+     * Best-effort: scroll toward FULL-SOURCE 1-based `line` by resolving the
+     * nearest preceding heading in the ProseMirror doc (no exact source map in
+     * WYSIWYG — Milkdown keeps no `data-sourcepos`). No-op when no preceding
+     * heading is found or while booting. (#273)
+     *
+     * For precise navigation, prefer `scrollToHeading(slug)` — the workspace
+     * resolves the slug from the line via `parseMarkdownOutline` + `fmOffset`
+     * before forwarding here.
+     */
+    revealLine: (line: number, opts?: {
+        center?: boolean;
+    }) => void;
+}
+interface MarkdownEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled markdown value. Pair with `onChange`. */
+    value?: string;
+    /** Initial markdown for uncontrolled use. */
+    defaultValue?: string;
+    /** Fires on every edit with the full markdown document. */
+    onChange?: (markdown: string) => void;
+    /** Render the editor read-only (still selectable, not editable). */
+    readOnly?: boolean;
+    /**
+     * Accessible name for the editable surface. Milkdown/ProseMirror renders an ARIA
+     * `textbox` (`contenteditable`); without a name, screen readers announce an
+     * unlabeled field. Set onto the ProseMirror view's `attributes`. Default
+     * `"Markdown editor"`.
+     */
+    ariaLabel?: string;
+    /**
+     * Enable the `/` command menu (insert brand `:::` directives + basic blocks
+     * live at the caret). `true` (default) uses the built-in
+     * {@link BRAND_SLASH_COMMANDS}; pass a `commands` array to extend/replace them,
+     * or `false` to disable. The `trigger` defaults to `"/"`.
+     *
+     * Pass `shortcut` (default `"Mod-Shift-O"`) to control the keyboard shortcut that
+     * opens the menu at the caret without typing the trigger character — works in
+     * BOTH the WYSIWYG pane and the Monaco source pane (#271).
+     */
+    slashMenu?: boolean | {
+        commands?: SlashCommand[];
+        trigger?: string;
+        shortcut?: string;
+    };
+    /**
+     * Opt-in calc authoring inside ```calc fences (off by default). Supply the
+     * consumer's hooks — `tokenize` (highlight), `evaluate` (result inlays), and/or
+     * `complete` (autocomplete; Monaco surface). The library DECORATES, the consumer
+     * COMPUTES — no calc engine is bundled. Mirrors `MarkdownPreview`'s `evaluate`.
+     */
+    calc?: CalcEditorHooks;
+    /**
+     * Declarative completion providers (#283) — e.g. `[[wikilink]]` autocomplete.
+     * Off by default; mirrors the `slashMenu`/`calc` opt-in pattern. Each provider
+     * registers a `triggerCharacters` set + a `provide(ctx)` that returns
+     * candidates; the library owns detecting the trigger and rendering/inserting.
+     *
+     * This is a DELIBERATELY MINIMAL, best-effort mirror of the Monaco source-pane
+     * behavior (see `markdown-editor/completions/completions-prose.ts` for the
+     * exact gaps — no real cross-block line/column, a plain listbox instead of a
+     * native suggest widget). Forwarded from `MarkdownWorkspace`'s `completions`
+     * prop, which also wires the FULL Monaco/source-pane path.
+     */
+    completions?: EditorCompletionProvider[];
+    /**
+     * Host-provided callback for image paste/drop embedding.
+     *
+     * When set, the editor intercepts paste and drop events that contain image
+     * files, shows an inline "uploading…" placeholder, calls this function with
+     * the `File`, and on resolve inserts `![filename](returnedPath)` in the
+     * document. On reject the placeholder is removed and an inline error chip
+     * (+ toast) is shown — the document never contains a broken image.
+     *
+     * If not set, the editor's default paste/drop behavior is unchanged.
+     *
+     * The library NEVER stores assets — all persistence is the host's responsibility.
+     */
+    onEmbedAsset?: EmbedAssetFn;
+}
+
+declare const MarkdownEditor: react.ForwardRefExoticComponent<MarkdownEditorProps & react.RefAttributes<MarkdownEditorHandle>>;
+
+export { type CalcValueKind as A, BRAND_SLASH_COMMANDS as B, CodeEditor as C, type CompletionMatch as D, type EditorContentAccess as E, type CompletionReplaceRange as F, type EditorCompletionContext as G, type EditorCompletionItem as H, type IterationEditHandler as I, type InsertableDirective as J, IterationEditContext as K, type IterationEditRequest as L, type MonacoCodeEditor as M, type SlashInsertContext as N, type SlashRange as O, type SourceSlashContext as P, collectCompletions as Q, filterSlashCommands as R, type SlashCommand as S, groupSlashCommands as T, insertBasicBlock as U, insertBrandDirective as V, insertCalcFence as W, resolveCalcInsert as X, resolveReplaceRange as Y, triggerQueryStart as Z, type CodeEditorProps as a, type EditorAction as b, type EditorSelection as c, type EmbedAssetFn as d, MarkdownEditor as e, type MarkdownEditorHandle as f, type MarkdownEditorProps as g, type EditorCompletionProvider as h, type CalcEditorHooks as i, type EvaluateCalc as j, type CalcValue as k, type CalcTokenKind as l, monacoContentAccess as m, type BasicBlockId as n, CALC_FENCE_SEED as o, type CalcComplete as p, type CalcCompletion as q, type CalcCompletionContext as r, type CalcCompletionKind as s, type CalcContext as t, type CalcLineResult as u, type CalcRule as v, type CalcSheet as w, type CalcTint as x, type CalcToken as y, type CalcTokenize as z };