@vscode/markdown-editor 0.0.2-20 → 0.0.2-22

package/dist/index.d.ts

@@ -109,7 +109,7 @@ declare abstract class BlockAstNodeBase extends AstNode {
 /**
  * One block's place in the rendered document.
  *
- * `height` is in CSS pixels. It is either a real DOM measurement
+ * Geometry is in editor-local CSS pixels. `height` is either a real DOM measurement
  * (`isMeasured: true`) or an estimate produced when the block is not
  * currently mounted (`isMeasured: false`). Estimates exist so virtual
  * rendering can size the scroll container without mounting every block.
@@ -124,6 +124,13 @@ export declare interface BlockMeasurement {
     readonly block: BlockAstNode;
     readonly absoluteStart: number;
     readonly height: number;
+    /** Local border box when mounted and measured. */
+    readonly rect: Rect2D | undefined;
+    /** Local horizontal padding-box clip when this block scrolls horizontally. */
+    readonly viewportClip: {
+        readonly left: number;
+        readonly right: number;
+    } | undefined;
     readonly isMeasured: boolean;
     readonly visualLineMap: VisualLineMap | undefined;
     readonly viewNode: ViewNode | undefined;
@@ -605,10 +612,9 @@ export declare const cursorUp: VisualCursorCommand;
  * derived subscribed.
  */
 export declare class CursorView extends Disposable {
-    private readonly _parent;
     readonly element: HTMLElement;
     readonly rendering: IObservable<CursorViewRendering>;
-    constructor(_parent: HTMLElement, options: CursorViewOptions);
+    constructor(options: CursorViewOptions);
 }
 
 export declare interface CursorViewOptions {
@@ -622,7 +628,7 @@ export declare interface CursorViewOptions {
     readonly blocks?: IObservable<readonly SelectionBlock[]>;
     /**
      * When set, the caret is drawn over the transient empty paragraph instead
-     * of at {@link offset} — its rect (in client coordinates) comes straight
+     * of at {@link offset} — its editor-local rect comes straight
      * from that synthetic element's geometry, since it has no visual-line-map
      * entry. Takes priority over the normal offset-based placement.
      */
@@ -886,6 +892,34 @@ export declare interface EditorControllerOptions {
     readonly clipboardStrategy?: IClipboardStrategy;
 }
 
+/**
+ * The editor overlay's local CSS-pixel coordinate space.
+ *
+ * Browser geometry and pointer APIs expose viewport client coordinates. This
+ * boundary converts them immediately into the coordinate system shared by the
+ * editor content and its overlays. Range rectangles are axis-aligned, so the
+ * current implementation deliberately supports positive axis-aligned scale and
+ * translation only.
+ */
+export declare class EditorCoordinateSpace {
+    private readonly _getLocalToClientMatrix;
+    static forSvgOverlay(overlay: SVGSVGElement): EditorCoordinateSpace;
+    private constructor();
+    capture(): EditorCoordinateTransform;
+}
+
+/** A stable coordinate conversion captured for one measurement operation. */
+export declare class EditorCoordinateTransform {
+    private readonly _localToClient;
+    private readonly _clientToLocal;
+    constructor(_localToClient: DOMMatrix);
+    toLocalPoint(point: Pick<Point2D, 'x' | 'y'>): Point2D;
+    toClientPoint(point: Pick<Point2D, 'x' | 'y'>): Point2D;
+    toLocalRect(rect: Pick<DOMRectReadOnly, 'left' | 'top' | 'width' | 'height'>): Rect2D;
+    toClientRect(rect: Pick<Rect2D, 'left' | 'top' | 'width' | 'height'>): Rect2D;
+    private _convertRect;
+}
+
 export declare class EditorModel {
     private readonly _parser;
     /**
@@ -1041,6 +1075,7 @@ export declare class EditorView extends Disposable {
     readonly element: HTMLElement;
     readonly editContext: EditContext;
     readonly measuredLayout: MeasuredLayoutModel;
+    readonly coordinateSpace: EditorCoordinateSpace;
     /**
      * Inner container that holds the rendered document and the cursor/selection
      * overlays. The outer {@link element} spans the full width; this container
@@ -1052,6 +1087,7 @@ export declare class EditorView extends Disposable {
     private readonly _selectionView;
     private readonly _gutterMarkersView;
     private readonly _diffHighlightsView;
+    private _readonlyToggleButton;
     /**
      * The mounted block sequence, in source order. Rebuilt (not mutated) each
      * frame by {@link DocumentViewNode.create}; the view just swaps one
@@ -1072,7 +1108,7 @@ export declare class EditorView extends Disposable {
     private readonly _viewData;
     get viewData(): IObservable<DocumentViewData | undefined>;
     /**
-     * Caret rect (client coords) for the transient empty paragraph, or
+     * Caret rect (editor-local coordinates) for the transient empty paragraph, or
      * `undefined` when none is armed. Set each frame from the synthetic
      * paragraph element's geometry and fed to the {@link CursorView}, which has
      * no visual-line-map entry to place the caret from otherwise.
@@ -1120,11 +1156,14 @@ export declare class EditorView extends Disposable {
      * {@link EditorModel.readonlyMode}: when locked (read-only) every block stays
      * in its clean rendered form (no markdown markers revealed) and edits are
      * ignored, while text selection still works. The control lives in a
-     * zero-height *sticky* host so the lock stays pinned to the top-right corner
-     * of the scroll container as the document scrolls. The current mode is also
-     * mirrored onto the root as `.md-readonly` for any CSS hooks.
+     * zero-height *sticky* host inside the centered content container, so the
+     * lock follows the content's right edge and remains pinned as the document
+     * scrolls. The current mode is also mirrored onto the root as `.md-readonly`
+     * for any CSS hooks.
      */
     private _setupReadonlyToggle;
+    /** Draws attention to the mode toggle after text input is attempted while locked. */
+    showReadonlyEditingAttempt(): void;
     focus(): void;
     /**
      * Own point→offset resolution. When `true` (the default),
@@ -1190,9 +1229,9 @@ export declare interface EditorViewOptions extends BlockViewOptions {
      */
     readonly classNames?: readonly string[];
     /**
-     * Whether to render the sticky edit/read-only toggle in the top-right
-     * corner. Defaults to `true`; set to `false` to omit it (e.g. in fixtures
-     * that focus on selection rendering).
+     * Whether to render the sticky edit/read-only toggle at the top-right edge
+     * of the content. Defaults to `true`; set to `false` to omit it (e.g. in
+     * fixtures that focus on selection rendering).
      */
     readonly showReadonlyToggle?: boolean;
     /**
@@ -1779,8 +1818,8 @@ export declare class MeasuredLayoutDebugRendering {
  * Exposes two DOM nodes the caller can place independently:
  *
  *  - {@link overlayElement} — absolutely positioned; the caller mounts it
- *    inside the editor element so dashed line-bands and run-boxes line up
- *    with the editor's client coordinates.
+ *    inside the editor overlay container so dashed line-bands and run-boxes
+ *    share the measured editor-local coordinates.
  *  - {@link infoElement} — block-flow; the caller mounts it as a sibling
  *    *below* the editor. Contains the per-block summary table that used
  *    to live on the overlay.
@@ -1791,7 +1830,6 @@ export declare class MeasuredLayoutDebugRendering {
  * the derived subscribed.
  */
 export declare class MeasuredLayoutDebugView extends Disposable {
-    private readonly _overlayParent;
     readonly overlayElement: HTMLElement;
     readonly infoElement: HTMLElement;
     readonly rendering: IObservable<MeasuredLayoutDebugRendering>;
@@ -1804,6 +1842,7 @@ export declare class MeasuredLayoutDebugView extends Disposable {
 
 export declare interface MeasuredLayoutDebugViewOptions {
     readonly model: MeasuredLayoutModel;
+    readonly coordinateSpace: EditorCoordinateSpace;
     /**
      * DEBUG ONLY. Maps an absolute source offset to a fill color for that
      * character's glyph rect. The fixture passes the same function to the
@@ -1838,10 +1877,9 @@ export declare interface MeasuredLayoutDebugViewOptions {
 export declare class MeasuredLayoutModel {
     readonly measurements: ISettableObservable<readonly BlockMeasurement[], void>;
     /**
-     * Concatenated visual line map across all mounted blocks. Lines are
-     * left in DOM (client-coordinate) y order — each per-block map already
-     * uses absolute client coordinates from `getClientRects()`, so the
-     * concatenation is well-formed without re-sorting.
+     * Concatenated visual line map across all mounted blocks. Every per-block
+     * map uses the same editor-local coordinate space, so concatenation is
+     * well-formed without translation or re-sorting.
      */
     readonly visualLineMap: IObservableWithChange<VisualLineMap, void>;
 }
@@ -1984,7 +2022,9 @@ declare class PendingParagraphViewData {
 }
 
 /**
- * Immutable point in 2D space, in CSS-pixel client coordinates.
+ * Immutable point in a caller-defined 2D CSS-pixel coordinate space.
+ * Coordinate-owning APIs must document whether values are viewport-client or
+ * editor-local; values from different spaces must not be mixed.
  */
 export declare class Point2D {
     readonly x: number;
@@ -1995,8 +2035,8 @@ export declare class Point2D {
 }
 
 /**
- * Immutable axis-aligned rectangle in 2D space, in CSS-pixel client
- * coordinates. `x`/`y` is the top-left corner, growing right/down.
+ * Immutable axis-aligned rectangle in a caller-defined 2D CSS-pixel coordinate
+ * space. `x`/`y` is the top-left corner, growing right/down.
  *
  * Half-open in both dimensions: `right` and `bottom` are excluded.
  */
@@ -2064,17 +2104,13 @@ export { Selection_2 as Selection }
 export declare interface SelectionBlock {
     readonly block: BlockAstNode;
     readonly absoluteStart: number;
-    readonly viewNode: ViewNode;
-    readonly element: HTMLElement;
-    /**
-     * The block's horizontal scroll viewport. Equal to {@link element} for every
-     * block whose element is itself the `overflow-x: auto` scroller (code, math,
-     * unhandled), but the wrapping `.md-table-wrapper` for a table, whose
-     * {@link element} is the content-sized inner `<table>`. Only
-     * {@link blockViewportClip} needs the scroll box; connector/rect geometry
-     * still uses {@link element}.
-     */
-    readonly scrollElement: HTMLElement;
+    /** Block border box in editor-local coordinates. */
+    readonly rect: Rect2D;
+    /** Visible horizontal padding-box bounds for a scrolling block. */
+    readonly viewportClip: {
+        readonly left: number;
+        readonly right: number;
+    } | undefined;
 }
 
 export declare type SelectionCommand = (ctx: CursorCommandContext, offset: SourceOffset) => Selection_2;
@@ -2106,11 +2142,10 @@ export declare interface SelectionRect {
  * envelope shape used by IDE selection rendering.
  */
 export declare class SelectionView extends Disposable {
-    private readonly _parent;
     readonly element: SVGSVGElement;
     readonly rendering: IObservable<SelectionViewRendering>;
     private readonly _path;
-    constructor(_parent: HTMLElement, options: SelectionViewOptions);
+    constructor(options: SelectionViewOptions);
 }
 
 export declare interface SelectionViewOptions {
@@ -2580,7 +2615,8 @@ export declare class VisualLine {
 
 /**
  * Geometry of the rendered document, as a map from source offsets to 2D
- * positions and back.
+ * positions and back. All geometry is expressed in the editor overlay's local
+ * CSS-pixel coordinate space.
  *
  * Structure (top to bottom):
  *
@@ -2615,7 +2651,7 @@ export declare class VisualLineMap {
     static measure(blockViews: readonly {
         readonly absoluteStart: number;
         readonly viewNode: ViewNode;
-    }[]): VisualLineMap;
+    }[], coordinateSpace: EditorCoordinateSpace, transform?: EditorCoordinateTransform): VisualLineMap;
     constructor(lines: readonly VisualLine[]);
     get lineCount(): number;
     get isEmpty(): boolean;
@@ -2700,6 +2736,7 @@ declare interface VisualRunSource {
     readonly textNode: Text;
     /** Offset within `textNode.data` corresponding to `sourceRange.start`. */
     readonly textNodeStart: number;
+    readonly coordinateSpace: EditorCoordinateSpace;
 }
 
 export declare class VscodeStackedCommentsView extends StackedCommentsPresenter {