@adecore/editor-react 0.0.1 → 0.17.0-beta.2

package/src/folding.ts

@@ -0,0 +1,110 @@
+import type { EditorFoldHints, EditorFoldRange, EditorFoldSymbol } from '@adecore/editor';
+import type { DocumentSymbol, DocumentSymbolResult, FoldingRange, SymbolInformation } from '@adecore/lsp';
+import type { EditorLanguage } from './editor-language.ts';
+import { Refresher } from './refresher.ts';
+import { realTimers, type Timers } from './timers.ts';
+
+const METHOD = 'textDocument/foldingRange';
+const PAUSE_MS = 500;
+
+/* The kind of body a symbol has, by LSP symbol kind; a namespace, a property of a type or an enum member has none worth folding. */
+const BODIES: Readonly<Record<number, EditorFoldSymbol['body']>> = {
+    5: 'class',
+    6: 'method',
+    7: 'value',
+    8: 'value',
+    9: 'method',
+    10: 'class',
+    11: 'class',
+    12: 'function',
+    13: 'value',
+    14: 'value',
+    23: 'class'
+};
+
+function walk(symbols: readonly DocumentSymbol[], found: EditorFoldSymbol[]): void {
+    for (const symbol of symbols) {
+        const body = BODIES[symbol.kind];
+        if (body !== undefined && symbol.range.end.line > symbol.range.start.line) {
+            found.push({ range: symbol.range, body });
+        }
+        walk(symbol.children ?? [], found);
+    }
+}
+
+/* The symbols that have a body of more than one line, as what the editor folds them by. */
+export function foldSymbolsOf(result: DocumentSymbolResult): EditorFoldSymbol[] {
+    const found: EditorFoldSymbol[] = [];
+    if (result === null || result.length === 0) {
+        return found;
+    }
+    if ('range' in result[0]!) {
+        walk(result as DocumentSymbol[], found);
+        return found;
+    }
+    for (const symbol of result as SymbolInformation[]) {
+        const body = BODIES[symbol.kind];
+        if (body !== undefined && symbol.location.range.end.line > symbol.location.range.start.line) {
+            found.push({ range: symbol.location.range, body });
+        }
+    }
+    return found;
+}
+
+/* The ranges a server folds that span more than one line. */
+export function foldRangesOf(ranges: readonly FoldingRange[] | null): (EditorFoldRange & { kind?: string })[] {
+    return (ranges ?? [])
+        .filter((range) => range.endLine > range.startLine)
+        .map((range) => ({ startLine: range.startLine, endLine: range.endLine, ...(range.kind === undefined ? {} : { kind: range.kind }) }));
+}
+
+/*
+ * What the servers know about folding: the bodies of the symbols (read from the symbols the document already
+ * has, so nothing is asked twice) and the ranges they fold, such as an element or a Markdown section. The
+ * editor folds what the settings choose by them when the file opens, and keeps them with their text after.
+ */
+export class FoldingFeature {
+    private symbols: EditorFoldSymbol[] = [];
+    private ranges: (EditorFoldRange & { kind?: string })[] = [];
+    private readonly refresher: Refresher;
+    private readonly language: EditorLanguage;
+
+    constructor(language: EditorLanguage, onSymbols: (listener: (result: DocumentSymbolResult) => void) => () => void, timers: Timers = realTimers) {
+        this.language = language;
+        const { editor, project, uri } = language;
+        this.refresher = new Refresher(
+            async (signal) => {
+                if (!project.service.supports(METHOD, uri)) {
+                    return;
+                }
+                const ranges = await project.service.foldingRanges(uri, { signal });
+                if (!signal.aborted) {
+                    this.ranges = foldRangesOf(ranges);
+                    this.publish();
+                }
+            },
+            PAUSE_MS,
+            timers
+        );
+        const symbols = onSymbols((result) => {
+            this.symbols = foldSymbolsOf(result);
+            this.publish();
+        });
+        const edits = editor.onTextChange(() => this.refresher.later());
+        const providers = language.onProvidersChanged(() => {
+            this.refresher.now();
+        });
+        language.onDispose(() => {
+            symbols();
+            edits();
+            providers();
+            this.refresher.dispose();
+            editor.setFoldHints(null);
+        });
+    }
+
+    private publish(): void {
+        const hints: EditorFoldHints = { symbols: this.symbols, ranges: this.ranges };
+        this.language.editor.setFoldHints(hints);
+    }
+}

package/src/highlight-layers.ts

@@ -0,0 +1,37 @@
+import type { Editor, EditorLineHighlight } from '@adecore/editor';
+
+type Provider = () => readonly EditorLineHighlight[];
+
+/*
+ * The editor has one set of tinted lines, and a conflict and a review each have lines to tint. Every
+ * owner hands over a function that says where its lines are now, so setting one owner's never carries
+ * another's from before an edit.
+ */
+export class HighlightLayers {
+    private readonly editor: Editor;
+    private readonly owners = new Map<string, Provider>();
+
+    constructor(editor: Editor) {
+        this.editor = editor;
+    }
+
+    set(owner: string, provider: Provider | null): void {
+        if (provider === null) {
+            this.owners.delete(owner);
+        } else {
+            this.owners.set(owner, provider);
+        }
+        this.editor.setLineHighlights([...this.owners.values()].flatMap((read) => read()));
+    }
+}
+
+const layers = new WeakMap<Editor, HighlightLayers>();
+
+export function highlightLayers(editor: Editor): HighlightLayers {
+    let found = layers.get(editor);
+    if (found === undefined) {
+        found = new HighlightLayers(editor);
+        layers.set(editor, found);
+    }
+    return found;
+}

package/src/highlights.ts

@@ -0,0 +1,123 @@
+import type { DocumentHighlight } from '@adecore/lsp';
+import type { EditorHighlight, EditorHighlightKind, EditorPosition, EditorRange } from '@adecore/editor';
+import { comparePositions, rangeHolds } from './diagnostics-model.ts';
+import { isIdentifierCharacter } from './completion-model.ts';
+import type { EditorLanguage } from './editor-language.ts';
+import { Refresher } from './refresher.ts';
+import { isShortcut } from './shortcut-keys.ts';
+import { realTimers, type Timers } from './timers.ts';
+
+const METHOD = 'textDocument/documentHighlight';
+const PAUSE_MS = 150;
+
+const KINDS: Record<number, EditorHighlightKind> = { 1: 'text', 2: 'read', 3: 'write' };
+
+export function editorHighlightsOf(highlights: readonly DocumentHighlight[]): EditorHighlight[] {
+    return highlights
+        .filter((highlight) => comparePositions(highlight.range.start, highlight.range.end) < 0)
+        .map((highlight) => ({ range: highlight.range, kind: KINDS[highlight.kind ?? 1] ?? 'text' }))
+        .sort((left, right) => comparePositions(left.range.start, right.range.start));
+}
+
+/* The range before the caret when stepping back, or after it when stepping forward, wrapping round the document; null for no ranges. */
+export function neighborRange(ranges: readonly EditorRange[], from: EditorPosition, direction: 1 | -1): EditorRange | null {
+    if (ranges.length === 0) {
+        return null;
+    }
+    const ordered = [...ranges].sort((left, right) => comparePositions(left.start, right.start));
+    if (direction === 1) {
+        return ordered.find((range) => comparePositions(range.start, from) > 0) ?? ordered[0]!;
+    }
+    return [...ordered].reverse().find((range) => comparePositions(range.start, from) < 0) ?? ordered[ordered.length - 1]!;
+}
+
+/*
+ * The other uses of the name at the caret, drawn softly in the text, which the next and previous highlight
+ * keys step through. They are asked for when the caret rests on a name and go with the next edit.
+ */
+export class HighlightsFeature {
+    private readonly language: EditorLanguage;
+    private readonly refresher: Refresher;
+    private current: readonly EditorHighlight[] = [];
+
+    constructor(language: EditorLanguage, timers: Timers = realTimers) {
+        this.language = language;
+        const { editor, project, uri } = language;
+        this.refresher = new Refresher(
+            async (signal) => {
+                if (!project.service.supports(METHOD, uri) || !this.onName()) {
+                    this.clear();
+                    return;
+                }
+                const result = await project.service.documentHighlights(uri, editor.getCaret(), { signal });
+                if (!signal.aborted) {
+                    this.set(result === null ? [] : editorHighlightsOf(result));
+                }
+            },
+            PAUSE_MS,
+            timers
+        );
+        const offs = [
+            editor.onCaret((position) => {
+                // Moving along the same name keeps its marks, which is what makes stepping through them quiet.
+                if (!this.current.some((highlight) => rangeHolds(highlight.range, position))) {
+                    this.clear();
+                }
+                this.refresher.later();
+            }),
+            editor.onTextChange(() => {
+                // The editor drops its marks with the edit; this follows, and asks again when the caret settles.
+                this.current = [];
+                this.refresher.later();
+            }),
+            editor.onKeyDown((event) => {
+                const next = isShortcut(this.language.shortcuts.nextHighlight, event);
+                if (!next && !isShortcut(this.language.shortcuts.previousHighlight, event)) {
+                    return false;
+                }
+                return this.step(next ? 1 : -1);
+            })
+        ];
+        language.onDispose(() => {
+            for (const off of offs) {
+                off();
+            }
+            this.refresher.dispose();
+            editor.setHighlights([]);
+        });
+    }
+
+    /* Puts the caret on the next use of the name, or the one before; false when there are none. */
+    step(direction: 1 | -1): boolean {
+        const { editor } = this.language;
+        const target = neighborRange(
+            this.current.map((highlight) => highlight.range),
+            editor.getCaret(),
+            direction
+        );
+        if (target === null) {
+            return false;
+        }
+        editor.setCaret(target.start, comparePositions(target.start, editor.getCaret()) > 0 ? 'centerDown' : 'centerUp');
+        return true;
+    }
+
+    private onName(): boolean {
+        const { editor } = this.language;
+        const caret = editor.getCaret();
+        const before = caret.character > 0 ? editor.textInRange({ start: { line: caret.line, character: caret.character - 1 }, end: caret }) : '';
+        const after = editor.textInRange({ start: caret, end: { line: caret.line, character: caret.character + 1 } });
+        return (before !== '' && isIdentifierCharacter(before)) || (after !== '' && isIdentifierCharacter(after));
+    }
+
+    private set(highlights: readonly EditorHighlight[]): void {
+        this.current = highlights;
+        this.language.editor.setHighlights(highlights);
+    }
+
+    private clear(): void {
+        if (this.current.length > 0) {
+            this.set([]);
+        }
+    }
+}

package/src/history.ts

@@ -0,0 +1,56 @@
+import type { EditorLanguage } from './editor-language.ts';
+import { isShortcut } from './shortcut-keys.ts';
+
+/* Back, Forward and the list of recent locations over the history the whole project shares. */
+export class HistoryFeature {
+    private readonly language: EditorLanguage;
+
+    constructor(language: EditorLanguage) {
+        this.language = language;
+        const off = language.editor.onKeyDown((event) => {
+            if (isShortcut(this.language.shortcuts.historyBack, event)) {
+                this.back();
+                return true;
+            }
+            if (isShortcut(this.language.shortcuts.historyForward, event)) {
+                this.forward();
+                return true;
+            }
+            if (isShortcut(this.language.shortcuts.recentLocations, event)) {
+                this.recent();
+                return true;
+            }
+            return false;
+        });
+        language.onDispose(off);
+    }
+
+    /* Returns to where the caret was before the last jump; false when there is no such place. */
+    back(): boolean {
+        const place = this.language.project.history.back(this.language.place);
+        if (place === null) {
+            return false;
+        }
+        this.language.visit(place);
+        return true;
+    }
+
+    forward(): boolean {
+        const place = this.language.project.history.forward(this.language.place);
+        if (place === null) {
+            return false;
+        }
+        this.language.visit(place);
+        return true;
+    }
+
+    /* Lists the places of the history under the caret; choosing one jumps there like any other jump. */
+    recent(): void {
+        const places = this.language.project.history.recent(this.language.place);
+        this.language.locations(
+            places.map((place) => ({ uri: place.uri, range: { start: place.position, end: place.position } })),
+            this.language.editor.getCaret(),
+            this.language.project.i18n.t('editor:language.history.recent')
+        );
+    }
+}

package/src/holder.ts

@@ -0,0 +1,19 @@
+export function createHolder<T>() {
+    let value: T | null = null;
+    const listeners = new Set<() => void>();
+    return {
+        get: () => value,
+        set: (next: T | null) => {
+            value = next;
+            for (const listener of listeners) {
+                listener();
+            }
+        },
+        subscribe: (listener: () => void) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        }
+    };
+}

package/src/host-types.ts

@@ -0,0 +1,52 @@
+import type { i18n } from 'i18next';
+import type { Keymap } from '@adecore/editor/keymap';
+import type { ProjectFiles } from './workspace-edit.ts';
+import type { Place } from './navigation-history.ts';
+
+export interface DiskText {
+    text: string;
+    mtime: number;
+}
+
+export interface GitBlameCommit {
+    hash: string;
+    shortHash: string;
+    author: string;
+    email: string;
+    at: number;
+    summary: string;
+}
+
+export interface GitBlameResult {
+    commits: GitBlameCommit[];
+    lines: number[];
+    omitted?: 'untracked' | 'too-large';
+}
+
+export interface EditorNotification {
+    id: string;
+    kind: 'success' | 'error';
+    title: string;
+}
+
+export interface RenameSuggestionsRequest {
+    uri: string;
+    languageId: string;
+    name: string;
+    context: string;
+    uses: readonly string[];
+}
+
+export interface LanguageHost {
+    /* The instance the app hands `UIProvider`, which the features read their words from too; the default instance without one. */
+    readonly i18n?: i18n;
+    readonly folder?: string;
+    readonly files?: ProjectFiles;
+    readonly apple?: boolean;
+    readonly keymap?: Keymap;
+    openPlace?(place: Place): void;
+    pathOfUri?(uri: string): string | null;
+    serverNames?(uri: string): readonly string[];
+    notify?(notification: EditorNotification): void;
+    suggestNames?(request: RenameSuggestionsRequest, signal: AbortSignal): Promise<readonly string[]>;
+}

package/src/hover-content.ts

@@ -0,0 +1,264 @@
+import type { EditorRange } from '@adecore/editor';
+import type { Hover, Location, LocationLink, MarkedString, NavigationResult } from '@adecore/lsp';
+
+export interface SignatureBlock {
+    readonly language: string;
+    readonly code: string;
+}
+
+/* What a server said about a symbol: its signature as code, then prose as markdown. */
+export interface HoverText {
+    readonly signatures: readonly SignatureBlock[];
+    readonly markdown: string;
+}
+
+const FENCE = /^```([\w+#.-]*)[^\n]*\n([\s\S]*?)\n```[ \t]*(?:\n|$)/;
+
+/*
+ * The leading fenced blocks of a markdown text as signatures, and what follows them, minus the rule
+ * between the two that language servers draw, as the prose. A block further down, such as an example
+ * in the documentation, stays where it is.
+ */
+export function splitSignatures(markdown: string): HoverText {
+    const signatures: SignatureBlock[] = [];
+    let rest = markdown.replace(/^\s+/, '');
+    for (let match = FENCE.exec(rest); match !== null; match = FENCE.exec(rest)) {
+        signatures.push({ language: match[1] || 'text', code: match[2]! });
+        rest = rest.slice(match[0].length).replace(/^\s+/, '');
+    }
+    return { signatures, markdown: rest.replace(/^(?:-{3,}|\*{3,})\s*(?:\n|$)/, '').trim() };
+}
+
+function markedStringText(content: MarkedString): HoverText {
+    if (typeof content !== 'string') {
+        return { signatures: [{ language: content.language || 'text', code: content.value }], markdown: '' };
+    }
+    return splitSignatures(content);
+}
+
+/* The text of a hover, whichever of the three shapes the protocol allows it in. */
+export function hoverTextOf(hover: Hover): HoverText {
+    const { contents } = hover;
+    if (Array.isArray(contents)) {
+        const parts = contents.map(markedStringText);
+        return {
+            signatures: parts.flatMap((part) => part.signatures),
+            markdown: parts
+                .map((part) => part.markdown)
+                .filter(Boolean)
+                .join('\n\n')
+        };
+    }
+    if (typeof contents === 'string' || 'language' in contents) {
+        return markedStringText(contents);
+    }
+    // Plain text is text, and not markdown that happens to have underscores in it.
+    return contents.kind === 'plaintext'
+        ? { signatures: [], markdown: contents.value.replace(/([\\`*_{}[\]()#+\-.!|<>~])/g, '\\$1').trim() }
+        : splitSignatures(contents.value);
+}
+
+export function isEmptyHover(text: HoverText): boolean {
+    return text.signatures.length === 0 && text.markdown === '';
+}
+
+function isLink(entry: Location | LocationLink): entry is LocationLink {
+    return 'targetUri' in entry;
+}
+
+/* Where a navigation result leads, as plain locations: the part of a link that names the symbol is the one to land on. */
+export function locationsOf(result: NavigationResult): Location[] {
+    if (result === null) {
+        return [];
+    }
+    const list = Array.isArray(result) ? (result as (Location | LocationLink)[]) : [result];
+    return list.map((entry) => (isLink(entry) ? { uri: entry.targetUri, range: entry.targetSelectionRange } : entry));
+}
+
+export function sameRange(left: EditorRange, right: EditorRange): boolean {
+    return (
+        left.start.line === right.start.line &&
+        left.start.character === right.start.character &&
+        left.end.line === right.end.line &&
+        left.end.character === right.end.character
+    );
+}
+
+/* One `@tag` of a docblock, the way a server writes it into a hover: `_@since_ 1.0` or `*@param* `name` - what it is`. */
+export interface DocTag {
+    readonly name: string;
+    readonly markdown: string;
+}
+
+const TAG_LINE = /^(?:_@([\w-]+)_|\*@([\w-]+)\*|@([\w-]+))(?:\s+|$)([\s\S]*)$/;
+
+/* Tags whose text is a block of its own, which a row of the tag list has no room for. */
+const BLOCK_TAGS = new Set(['example']);
+
+/*
+ * The docblock tags of hover prose apart from the rest, so a card can list them as rows instead of a
+ * paragraph each. Only a paragraph that holds nothing but tag lines is taken; prose that mentions an
+ * `@` stays prose.
+ */
+export function splitDocTags(markdown: string): { readonly markdown: string; readonly tags: readonly DocTag[] } {
+    const tags: DocTag[] = [];
+    const kept: string[] = [];
+    for (const paragraph of markdown.split(/\n{2,}/)) {
+        const lines = paragraph.split('\n');
+        const matches = lines.map((line) => TAG_LINE.exec(line.trim()));
+        const names = matches.map((match) => (match === null ? null : (match[1] ?? match[2] ?? match[3])!));
+        if (paragraph.trim() === '' || names.some((name) => name === null || BLOCK_TAGS.has(name))) {
+            kept.push(paragraph);
+            continue;
+        }
+        matches.forEach((match, index) => {
+            // The TypeScript server puts a dash between a tag, its parameter and its text.
+            const text = match![4]!.replace(/^[\u2014\u2013-]\s*/, '').replace(/^(`[^`]+`)\s+[\u2014\u2013-]\s+/, '$1 ');
+            tags.push({ name: names[index]!, markdown: text.trim() });
+        });
+    }
+    // By name, and in the order written within one name, so parameters keep the order of the signature.
+    return { markdown: kept.join('\n\n').trim(), tags: tags.toSorted((left, right) => left.name.localeCompare(right.name)) };
+}
+
+/* One symbol of a hover. A server can describe several at once, such as a class and its constructor. */
+export interface HoverSection {
+    /* The qualified name a server heads the section with, when it gives one. */
+    readonly title: string | null;
+    readonly signatures: readonly SignatureBlock[];
+    readonly markdown: string;
+    readonly tags: readonly DocTag[];
+    readonly baseline: Baseline | null;
+}
+
+export type BaselineLevel = 'widely' | 'newly' | 'limited';
+
+/* How widely a web feature is available, as the CSS servers state it under a property. */
+export interface Baseline {
+    readonly level: BaselineLevel;
+    readonly text: string;
+}
+
+/* A CSS server draws the status as a data URL image in front of an italic sentence, and a data URL is not an address the markdown renderer lets through. */
+const BASELINE = /!\[Baseline icon\]\([^)\s]*\)[ \t]*_([^\n]+?)_[ \t]*(?:\n|$)/;
+
+/* The Baseline status a text carries, which the card draws with a mark of its own, and the text without it. */
+function takeBaseline(markdown: string): { baseline: Baseline | null; rest: string } {
+    const match = BASELINE.exec(markdown);
+    if (match === null) {
+        return { baseline: null, rest: markdown };
+    }
+    const text = match[1]!.trim();
+    const level = text.startsWith('Widely') ? 'widely' : text.startsWith('Newly') ? 'newly' : 'limited';
+    return { baseline: { level, text }, rest: (markdown.slice(0, match.index) + markdown.slice(match.index + match[0].length)).replace(/\n{3,}/g, '\n\n') };
+}
+
+const RULE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/m;
+const TITLE = /^(?:__(.+)__|\*\*(.+)\*\*)\s*(?:\n|$)/;
+const ANY_FENCE = /```([\w+#.-]*)[^\n]*\n([\s\S]*?)\n```[ \t]*(?:\n|$)/;
+
+/* The PHP server opens every snippet with a tag the reader does not need to see. */
+function withoutOpenTag(block: SignatureBlock): SignatureBlock {
+    return { language: block.language, code: block.code.replace(/^<\?php\s*\n/, '') };
+}
+
+const HTML_CODE = /<(code|pre)>([\s\S]*?)<\/\1>/g;
+const INLINE_TAG = /\{@(see|link|linkplain)\s+([^}\s]+)(?:\s+([^}]+?))?\s*\}/g;
+
+function decodeEntities(text: string): string {
+    return text
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#0?39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+
+function dedent(text: string): string {
+    const lines = text.replace(/^\n+|\s+$/g, '').split('\n');
+    const indents = lines.filter((line) => line.trim() !== '').map((line) => line.length - line.trimStart().length);
+    const common = indents.length === 0 ? 0 : Math.min(...indents);
+    return lines.map((line) => line.slice(common)).join('\n');
+}
+
+/*
+ * What a docblock writes for a reader of its source, written for one of a hover: a `<code>` or `<pre>`
+ * example as a block in the symbol's language, and an inline `{@see Name}` or `{@link Name label}` as
+ * the name in code. Servers pass both on as they are, and markdown would show the tags as text.
+ */
+export function docblockMarkdown(markdown: string, language: string): string {
+    return markdown
+        .replace(HTML_CODE, (_match, _tag: string, body: string) => {
+            const code = decodeEntities(body);
+            return code.includes('\n') ? `\n\n\`\`\`${language}\n${dedent(code)}\n\`\`\`\n\n` : `\`${code.trim()}\``;
+        })
+        .replace(INLINE_TAG, (_match, _tag: string, target: string, label: string | undefined) => (label === undefined ? `\`${target}\`` : label))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+
+/* Markdown cut at its fenced blocks, so a card can draw the blocks as compactly as its signatures. */
+export type MarkdownPart = { readonly kind: 'prose'; readonly text: string } | { readonly kind: 'code'; readonly block: SignatureBlock };
+
+export function markdownParts(markdown: string): MarkdownPart[] {
+    const parts: MarkdownPart[] = [];
+    let rest = markdown;
+    for (let match = ANY_FENCE.exec(rest); match !== null; match = ANY_FENCE.exec(rest)) {
+        const prose = rest.slice(0, match.index).trim();
+        if (prose !== '') {
+            parts.push({ kind: 'prose', text: prose });
+        }
+        parts.push({ kind: 'code', block: { language: match[1] || 'text', code: match[2]! } });
+        rest = rest.slice(match.index + match[0].length);
+    }
+    if (rest.trim() !== '') {
+        parts.push({ kind: 'prose', text: rest.trim() });
+    }
+    return parts;
+}
+
+/* The title is drawn as text, so the escapes that kept it from reading as markdown come off: `A\\B::\_\_construct` is `A\B::__construct`. */
+function unescapeMarkdown(text: string): string {
+    return text.replace(/\\([\\`*_{}[\]()#+\-.!|<>~])/g, '$1');
+}
+
+function sectionOf(chunk: string, leading: readonly SignatureBlock[]): HoverSection {
+    let rest = chunk.trim();
+    const title = TITLE.exec(rest);
+    if (title !== null) {
+        rest = rest.slice(title[0].length).trim();
+    }
+    const signatures = [...leading];
+    // A section's own snippet is its first block; one further down after the prose, such as an example, stays prose.
+    const fence = ANY_FENCE.exec(rest);
+    if (fence !== null && !/@example/.test(rest.slice(0, fence.index))) {
+        signatures.push({ language: fence[1] || 'text', code: fence[2]! });
+        rest = (rest.slice(0, fence.index) + rest.slice(fence.index + fence[0].length)).trim();
+    }
+    const taken = takeBaseline(rest);
+    const doc = splitDocTags(docblockMarkdown(taken.rest, signatures[0]?.language ?? 'text'));
+    return {
+        title: title === null ? null : unescapeMarkdown((title[1] ?? title[2])!.trim()),
+        signatures: signatures.map(withoutOpenTag),
+        markdown: doc.markdown,
+        tags: doc.tags,
+        baseline: taken.baseline
+    };
+}
+
+/* The symbols of a hover apart, split where a server draws a rule between them, each described once. */
+export function hoverSectionsOf(text: HoverText): HoverSection[] {
+    const chunks = text.markdown === '' ? [''] : text.markdown.split(RULE);
+    const sections = chunks.map((chunk, index) => sectionOf(chunk, index === 0 ? text.signatures : []));
+    const seen = new Set<string>();
+    return sections.filter((section) => {
+        const empty =
+            section.title === null && section.signatures.length === 0 && section.markdown === '' && section.tags.length === 0 && section.baseline === null;
+        const key = JSON.stringify([section.title, section.signatures, section.markdown, section.baseline]);
+        if (empty || seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}