@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/cursor/widget-offset.d.ts

@@ -1,54 +1,99 @@
 /**
- * The single DOM Range ↔ raw offset translation point (`docs/design/editor.md`). Atomic
- * inline widgets contribute their raw bytes via data-source-start / data-source-end
- * without contributing to textContent; the walk sums text-node lengths — a leading
- * ambient marker span's text included — plus widget raw lengths, so walk positions are
- * `DomTextOffset` and `ambient/ambient-cursor.ts` owns the ± ambientLength step to raw.
+ * The one place a DOM position is translated to a raw offset and back, and the one place a caret
+ * is written from a raw offset (`docs/design/editor.md`). The walk offset (`DomTextOffset`) sums
+ * text-node lengths, the leading marker prefix's text included, plus each atomic widget's source
+ * length. A raw offset is that minus the prefix length, which this module reads off the DOM.
  */
 import { type VisibilityContext } from '../core/inline/visibility';
 import { type DomTextOffset, type RawOffset } from './coordinate-spaces';
-/** The stamp a block surface writes on its walk container while {@link holdsOnlyMarkerChrome}
- *  holds. Both consumers of the hiding rule — this walk and `styles/editor.css` — read it.
- *  Written in every mode on purpose: it is a content fact, so a flip never finds it stale. */
-export declare const CONTENT_EMPTY_ATTR = "data-content-empty";
-/** The class the preview-inline reveal trigger stamps and this walk's hiding rule reads. One home,
- *  so the stamping and classifying sides cannot drift. */
-export declare const CONSTRUCT_REVEAL_CLASS = "md-construct-reveal";
+/** Marks the span holding a block's bytes past its content: a setext underline, or an ATX
+ *  heading's closing run. Its value is `after-prefix` when the block also drew a prefix span. */
+export declare const BLOCK_SUFFIX_ATTR = "data-block-suffix";
+/** Marks the span holding a block's own marker before its content, a heading's `# `. */
+export declare const BLOCK_PREFIX_ATTR = "data-block-prefix";
+/** How a caret write treats its offset: `reachable` moves it onto a position the mode lets a caret
+ *  sit at (never behind a hidden marker run); `exact` writes it as given. */
+export type CaretClamp = 'reachable' | 'exact';
+/** A span of a block's raw offsets. */
+export interface RawRange {
+    start: number;
+    end: number;
+}
 /**
- * Walk-space offset of a live `(node, offset)` DOM position. A position inside an atomic
- * widget snaps to that widget's own walk boundary (browsers do rebind carets into these
- * contenteditable=false islands); an unreachable one reads as end-of-walk, so callers that
- * must distinguish "not mine" guard containment first.
+ * The container's leading marker prefix span (`- `, `> `), or null. Empty text nodes before it
+ * are skipped, since Chromium leaves them behind and they hold no offset.
  */
+export declare function markerPrefixOf(container: ParentNode): HTMLElement | null;
+/** The marker prefix's walk length: what a raw offset adds to become a walk offset. */
+export declare function markerPrefixLength(container: ParentNode): number;
+/** The raw offset of a live `(node, offset)` DOM position in `el`; a position inside the marker
+ *  prefix reads as raw 0. */
+export declare function rawOffsetAt(el: HTMLElement, node: Node, offset: number): RawOffset;
+/** A raw offset in `container` as a walk offset. */
+export declare function walkOffsetOfRaw(container: ParentNode, raw: number): DomTextOffset;
+/** A walk offset in `container` as a raw offset; one inside the marker prefix reads as raw 0. */
+export declare function rawOfWalkOffset(container: ParentNode, walk: DomTextOffset): RawOffset;
+/** The raw bytes `el` shows, its marker prefix left out: what a prose block reads back as its text.
+ *  `suffix` is the block's structural suffix as rendered; empty when only that is left. */
+export declare function rawTextOfContent(el: HTMLElement, raw: string, suffix: string): string;
+/** Raw offset of the live selection's focus inside `el`, or null when there is no selection or
+ *  its focus sits outside `el`. */
+export declare function rawSelectionFocus(el: HTMLElement): RawOffset | null;
+/** Put a collapsed caret at raw offset `raw` in `el`, the one caret writer. Raw 0 lands just after
+ *  a marker prefix span, since Chromium bounces a caret placed before it. False when refused. */
+export declare function placeCaretAtRaw(el: HTMLElement, raw: number, { clamp }: {
+    clamp: CaretClamp;
+}): boolean;
+/**
+ * Select raw `[anchor, focus]` in `el`, backward when the focus comes first. An endpoint at raw 0
+ * behind a marker prefix lands after the span, as a caret does.
+ */
+export declare function selectRawRange(el: HTMLElement, anchor: number, focus: number): boolean;
+/** Move the live selection's focus to raw `raw` in `el`, keeping its anchor. */
+export declare function extendSelectionToRaw(el: HTMLElement, raw: number): boolean;
+/** Select `el`'s content past its marker prefix and short of a hidden structural suffix (the first
+ *  Ctrl+A, a triple click). With no content, the whole contents, marker included. */
+export declare function selectSurfaceContent(el: HTMLElement): boolean;
+/** A DOM Range over raw `[start, end)` for measuring or decorating; caret writes use {@link
+ *  placeCaretAtRaw}. From raw 0 it starts after the marker prefix span, holding whole elements. */
+export declare function rawRangeToDomRange(container: ParentNode, start: number, end: number): Range | null;
+/** Written on the editable element while {@link holdsOnlyMarkerChrome} holds, and read by this walk
+ *  and `styles/editor.css`. Written in every mode, so a mode switch never finds it stale. */
+export declare const CONTENT_EMPTY_ATTR = "data-content-empty";
+/** The class the preview-inline reveal trigger sets and this walk's hiding rule reads, defined
+ *  once so the two sides cannot drift. */
+export declare const CONSTRUCT_REVEAL_CLASS = "md-construct-reveal";
+/** The DOM-walk offset of a live `(node, offset)` position. One inside an atomic widget snaps to its
+ *  boundary; one outside the container reads as the walk's end, so check containment first. */
 export declare function domTextOffsetAtNode(container: HTMLElement, node: Node, offset: number): DomTextOffset;
-/** Raw offset of the live selection's focus inside `el` through the walk above, or null when
- *  there is no selection or its focus is anchored outside `el`. */
-export declare function selectionFocusWalkOffset(el: HTMLElement, ambientLength: number): RawOffset | null;
 export interface DomPosition {
     node: Node;
     offset: number;
 }
-/**
- * Walk-space offset → live `(node, offset)` DOM position. The model-layer counterpart is
- * `findNodeAtOffset` in `core/inline-render.ts`. Accepts a detached fragment (island
- * application walks builds in progress) with the same arithmetic as a live block element.
- */
+/** A DOM-walk offset back to a live `(node, offset)` position, the DOM side of `findNodeAtOffset`
+ *  in `core/inline-render.ts`. Works on a detached fragment the same way. */
 export declare function findDomTextOffsetTarget(container: ParentNode, target: DomTextOffset): DomPosition | null;
 /**
- * Atomic inline widgets in `container` intersecting the walk-space range [start, end). A
- * widget adds 0 chars to textContent, so a range inside one yields no client rect and
- * callers that must cover it (search highlight, cross-block selection) take its bounding
- * box. A widget's position is its running walk offset, never a compare of `data-source-*`
- * against the ambient-adjusted argument.
+ * {@link findDomTextOffsetTarget}, also saying whether the position sits in visible text at
+ * `target` itself, whose walk offset is then `target` with no second walk to read it back.
  */
+export declare function findDomTextLanding(container: ParentNode, target: DomTextOffset): {
+    position: DomPosition;
+    inTextAtTarget: boolean;
+} | null;
+/** The atomic inline widgets intersecting the DOM-walk range [start, end): a widget adds no text,
+ *  so a caller covering it takes its bounding box. Positions are walk offsets, never `data-source-*`. */
 export declare function widgetsIntersectingRange(container: HTMLElement, start: DomTextOffset, end: DomTextOffset): HTMLElement[];
-/** Total walk length of `container` — its one-past-end walk position. */
+/** The walk's text with marker text and widget bytes blanked to spaces, at the walk's own
+ *  offsets: what a rule that reads words (double- and triple-click) sees as content. */
+export declare function maskedWalkText(container: ParentNode): string;
+/** Whether any visible text in `container` ends past `from`: a caret there has a box of its own,
+ *  which a block of widgets alone never offers. */
+export declare function holdsTextPast(container: ParentNode, from: DomTextOffset): boolean;
+/** Total walk length of `container`: its one-past-end walk position. */
 export declare function containerDomTextLength(container: ParentNode): DomTextOffset;
-/**
- * Walk-space span of the atomic widget strictly containing `offset`, or null when the
- * offset sits in text or exactly on a boundary. Island application snaps replace
- * boundaries outward with this — a text-position range cannot split an atomic widget.
- */
+/** The DOM-walk span of the atomic widget strictly containing `offset`, or null in text or on a
+ *  boundary. A replace decoration snaps outward with it, since a range cannot split a widget. */
 export declare function widgetSpanContainingOffset(container: ParentNode, offset: DomTextOffset): {
     start: DomTextOffset;
     end: DomTextOffset;
@@ -56,83 +101,47 @@ export declare function widgetSpanContainingOffset(container: ParentNode, offset
 /** Raw bytes a DOM subtree stands for: text nodes verbatim, widgets via their source range. */
 export declare function rawTextOfNode(domNode: Node, raw: string): string;
 export declare function createRangeAtDomTextOffsets(container: ParentNode, start: DomTextOffset, end: DomTextOffset): Range | null;
-/**
- * Whether `node` is text the mode CSS paints nothing for — a marker span's own text under a
- * marker-hiding mode with no reveal on it. Detected structurally against the families in
- * `core/inline/visibility.ts`, never by layout: a `getComputedStyle` per keystroke is not
- * affordable, so that vocabulary and `styles/editor.css` move together.
- */
+/** The text length of a block's trailing structure span (`BLOCK_SUFFIX_ATTR`) where the mode
+ *  hides it, else 0: bytes a range the user drew cannot have meant to take. */
+export declare function hiddenSuffixLength(el: HTMLElement): number;
+/** Whether `node` is marker text the mode's CSS paints nothing for, decided from the families in
+ *  `core/inline/visibility.ts`, not layout; that file and `styles/editor.css` change together. */
 export declare function isHiddenMarkerText(node: Node, container: HTMLElement): boolean;
-/**
- * Whether `el`'s OWN text is marker text the container's mode paints nothing for — the
- * element-level form of {@link isHiddenMarkerText}, for a walk that treats such a span as
- * opaque instead of descending into it.
- */
+/** The element form of {@link isHiddenMarkerText}, for a walk that treats such a span as opaque
+ *  instead of descending into it. */
 export declare function isHiddenMarkerRoot(el: Element, container: HTMLElement): boolean;
-/**
- * The DOM-reading twin of `paintsFocusedMarkers`: whether this container's mode paints NO marker
- * in the focused block — neither its own structural prefix (`## `, a fence, a setext underline)
- * nor an inline construct's delimiters. An unstamped container is styled source, which paints.
- */
+/** `hidesDelimitersAtCaret` read from the DOM: whether this container's mode paints no marker in
+ *  the focused block. No mode attribute means styled source, which paints. */
 export declare function revealsNoMarkers(container: ParentNode): boolean;
-/**
- * How this container's bytes read on screen: its mode and its content-empty stamp, resolved here
- * so a rewrite seam needs no marker vocabulary of its own. Chrome standing over no content PAINTS
- * (live-mode.md § 4.1), and a seam holding a license over unseen bytes has nothing to claim there.
- * An unmounted surface reads as source, where nothing hides and no rewrite has a run to move.
- */
+/** How this container's bytes read on screen, its mode plus its content-empty attribute, so a text
+ *  rewrite needs no marker knowledge of its own. An unmounted block reads as source. */
 export declare function screenVisibilityOf(container: ParentNode | null): VisibilityContext;
-/**
- * The extreme walk offsets a caret can occupy in `container`: a hidden marker run or the leading
- * ambient island holds no landable position, so the bound moves past it. Block-edge gates read
- * these rather than 0 / walk length, which a mode painting no marker makes unreachable — a gate
- * testing an offset no keystroke can produce is a dead key. An ALL-hidden container (an empty
- * fence) has no landable offset and answers `{len, len}`, making every `offset <= start` gate true.
- */
+/** The first and last walk offsets a caret can sit at, past hidden marker runs and the marker
+ *  prefix; the checks at a block's edge read these. All-hidden text answers `{len, len}`. */
 export declare function landableDomTextBounds(container: ParentNode): {
     start: DomTextOffset;
     end: DomTextOffset;
 };
-/**
- * Whether every byte `container` holds is marker chrome, at least one span of it a family the
- * empty-construct override paints. The stamp condition the render path writes as
- * `data-content-empty` and the walk reads back — computed WITHOUT reading the stamp, or each
- * render would flip the previous one's answer. Membership and paintability are separate
- * questions: a reference label is chrome that stays hidden, so it is not content standing behind
- * the stamp, and it is not the paint the stamp promises either.
- */
-/**
- * The container's bytes outside its marker chrome — what a painted source holds as CONTENT,
- * whatever the mode paints. A fence with an empty body answers whitespace; the leaf reads that
- * as "nothing here a Backspace could mean but the block".
- */
+/** A `<br>` that gives the caret a line nothing else paints, adding no text. `role` tells the walks
+ *  a hidden fence closer line (`closer`) from a pending hard break's line (`break`). */
+export declare function createCaretAnchor(role?: '' | 'closer' | 'break'): HTMLBRElement;
+/** The container's bytes outside its markers, whatever the mode paints. An empty fence body answers
+ *  whitespace: nothing for Backspace to delete but the block itself. */
 export declare function chromeFreeText(container: ParentNode): string;
+/** Whether every byte is marker text, with a span the empty-construct override paints: the
+ *  `data-content-empty` condition, computed without reading the attribute it sets. */
 export declare function holdsOnlyMarkerChrome(container: ParentNode): boolean;
-/**
- * Whether the mode paints NOTHING landable here: every walk segment is a hidden marker run, so no
- * caret position has a pixel of its own. `invariants/landable-caret.ts` refuses this shape at the
- * focus seam — an empty container (landable at offset 0) and one fronted by the ambient island are
- * not it.
- */
+/** Whether every walk segment is a hidden marker run, so no caret position has a pixel of its own;
+ *  `invariants/landable-caret.ts` refuses this shape when focus lands. */
 export declare function paintsNoLandableContent(container: ParentNode): boolean;
-/**
- * {@link landableDomTextBounds} in the caret's own raw space, or null where the mode paints its
- * markers and the whole raw span is reachable. The one home every caret gate and caret DOOR
- * reads: the arrow exits, the cross-block collapse, and the block-entry seat all ask the same
- * question and must not answer it three ways.
- */
-export declare function landableRawBounds(el: HTMLElement, ambientLength: number): {
-    start: number;
-    end: number;
-} | null;
-/** Clamp a caret offset into `el`'s landable range — identity wherever the markers paint. */
-export declare function clampToLandableRaw(el: HTMLElement, offset: number, ambientLength: number): number;
-/**
- * Whether the first landable position abuts an opaque island (an atomic widget, a decoration
- * island) instead of sitting in text: no text node holds it, so the engine's Home seats the
- * caret past the island and the block's start needs an owned door.
- */
+/** {@link landableDomTextBounds} in raw offsets, or null where the markers paint and all of raw is
+ *  reachable. Every caret check and placement reads this one answer. */
+export declare function landableRawBounds(el: HTMLElement): RawRange | null;
+/** Clamp a caret offset into the range the caret can sit in; a no-op wherever the markers paint. */
+export declare function clampToLandableRaw(el: HTMLElement, offset: number): number;
+/** Whether the first caret position abuts an opaque widget rather than sitting in text: no text
+ *  node holds it, so the browser's Home skips the widget and the editor places the caret itself. */
 export declare function landableStartAbutsIsland(container: ParentNode): boolean;
-/** Whether `node` is an atomic inline widget's element — the island every walk treats as opaque.
- *  The attribute rather than the selector: every walk asks this per node. */
+/** Whether `node` is an atomic inline widget's element, which every walk treats as opaque. Checks
+ *  the attribute rather than a selector because every walk asks this per node. */
 export declare function isAtomicInlineWidget(node: Node): boolean;