@acrolinx/sidebar-sdk 2.0.1 → 2.0.3

package/README.md

@@ -92,7 +92,7 @@ The process to update your existing integration is straightforward and involves
 ## Serve Tests for Development
 
 - Run 'npm run test'
-- Browser with ViTest running will open 
+- Browser with ViTest running will open
 
 ## License
 

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { AcrolinxPlugin as AcrolinxPlugin_2 } from '@acrolinx/sidebar-interface';
+import * as acrolinxSidebarInterfaces from '@acrolinx/sidebar-interface';
 import { AcrolinxStorage } from '@acrolinx/sidebar-interface';
 import { Check } from '@acrolinx/sidebar-interface';
 import { CheckedDocumentPart } from '@acrolinx/sidebar-interface';
 import { CheckInformationKeyValuePair } from '@acrolinx/sidebar-interface';
 import { CheckResult } from '@acrolinx/sidebar-interface';
 import { default as default_2 } from '@ckeditor/ckeditor5-build-inline';
+import { Diff } from 'diff-match-patch';
 import { DocumentSelection } from '@acrolinx/sidebar-interface';
 import { Editor } from 'tinymce';
 import { EditorFromTextArea } from 'codemirror';
@@ -83,6 +85,8 @@ export declare interface AcrolinxPluginConfig extends InitParameters {
     log?: (logEntry: LogEntry) => void;
 }
 
+declare type AcrolinxSidebar = acrolinxSidebarInterfaces.AcrolinxSidebar;
+
 export declare interface AcrolinxSidebarIntegration {
     AcrolinxPlugin: typeof AcrolinxPlugin;
     autoBindFloatingSidebar: typeof autoBindFloatingSidebar;
@@ -92,6 +96,7 @@ export declare interface AcrolinxSidebarIntegration {
     createPluginMessageAdapter: typeof createPluginMessageAdapter;
     loadSidebarCode: typeof loadSidebarCode;
     getSelectionHtmlRanges: typeof getSelectionHtmlRanges;
+    extractTextDomMapping: typeof extractTextDomMapping;
     adapter: {
         AbstractRichtextEditorAdapter: typeof AbstractRichtextEditorAdapter;
         AutoBindAdapter: typeof AutoBindAdapter;
@@ -101,20 +106,24 @@ export declare interface AcrolinxSidebarIntegration {
         CodeMirror6Adapter: typeof CodeMirror6Adapter;
         CodeMirrorAdapter: typeof CodeMirrorAdapter;
         ContentEditableAdapter: typeof ContentEditableAdapter;
+        HerettoContentEditableAdapter: typeof HerettoContentEditableAdapter;
         AsyncContentEditableAdapter: typeof StateBasedContentEditableAdapter;
         InputAdapter: typeof InputAdapter;
         MultiEditorAdapter: typeof MultiEditorAdapter;
         AsyncMultiEditorAdapter: typeof AsyncMultiEditorAdapter;
         TinyMCEAdapter: typeof TinyMCEAdapter;
         XeditorAdapter: typeof XeditorAdapter;
+        QuipAdapter: typeof QuipAdapter;
+        SynchronizeAsyncAdapter: typeof SynchronizeAsyncAdapter;
     };
     lookup: {
         lookupMatches: typeof lookupMatches;
     };
-    extractTextDomMapping: typeof extractTextDomMapping;
 }
 
-declare type AdapterConf = HasEditorID | HasElement;
+declare type AcrolinxSidebarPlugin = acrolinxSidebarInterfaces.AcrolinxPlugin;
+
+export declare type AdapterConf = HasEditorID | HasElement;
 
 export declare interface AdapterInterface extends CommonAdapterInterface {
     selectRanges(checkId: string, matches: Match[]): void;
@@ -123,11 +132,15 @@ export declare interface AdapterInterface extends CommonAdapterInterface {
 
 declare type AddSingleAdapterOptions = WrapperConfOptions;
 
-declare interface AlignedMatch<T extends Match> {
+export declare interface AlignedMatch<T extends Match> {
     originalMatch: T;
     range: [number, number];
 }
 
+export declare function assertElementIsDisplayed(element: Element): void;
+
+export declare function assign<T, U>(obj: T, update: U): T & U;
+
 export declare interface AsyncAdapterInterface extends CommonAdapterInterface {
     readonly isAsync: true;
     readonly requiresSynchronization: boolean;
@@ -163,7 +176,7 @@ export declare class AsyncMultiEditorAdapter extends MultiEditorAdapter implemen
     replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): Promise<void>;
 }
 
-declare interface AsyncStorage {
+export declare interface AsyncStorage {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
 }
@@ -172,6 +185,10 @@ declare type AttributeMap = {
     [key: string]: any;
 };
 
+export declare const AUTO_SELF_CLOSING_LINE_TAGS: Readonly<{
+    [key: string]: boolean;
+}>;
+
 export declare class AutoBindAdapter implements AdapterInterface {
     private conf;
     private multiAdapter;
@@ -185,19 +202,20 @@ export declare class AutoBindAdapter implements AdapterInterface {
     replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): void;
 }
 
-declare interface AutobindConfig extends CommonAdapterConf {
+export declare interface AutobindConfig extends CommonAdapterConf {
     enableQuipAdapter?: boolean;
+    enableHerettoAdapter?: boolean;
 }
 
 export declare function autoBindFloatingSidebar(basicConf: AutoBindFloatingSidebarConfig): Promise<FloatingSidebar>;
 
 export declare function autoBindFloatingSidebarAsync(basicConf: AutoBindFloatingSidebarConfig): Promise<FloatingSidebar>;
 
-declare interface AutoBindFloatingSidebarConfig extends AcrolinxPluginConfig, MultiEditorAdapterConfig, AutobindConfig {
+export declare interface AutoBindFloatingSidebarConfig extends AcrolinxPluginConfig, MultiEditorAdapterConfig, AutobindConfig {
     asyncStorage?: AsyncStorage;
 }
 
-declare interface AutobindWrapperAttributes {
+export declare interface AutobindWrapperAttributes {
     'original-id'?: string;
     'original-class'?: string;
     'original-name'?: string;
@@ -206,6 +224,10 @@ declare interface AutobindWrapperAttributes {
     [key: string]: string | undefined;
 }
 
+export declare function bindAdaptersForCurrentPage(conf?: AutobindConfig): AdapterInterface[];
+
+export declare const browser: DetectedBrowser;
+
 declare interface CheckContentResult {
     dom: HTMLElement;
     text: string;
@@ -241,6 +263,15 @@ export declare class CKEditorAdapter extends AbstractRichtextEditorAdapter {
     isInWysiwygMode(): boolean;
 }
 
+export declare const CLIENT_COMPONENT_MAIN_FALLBACK: {
+    id: string;
+    name: string;
+    version: string;
+    category: string;
+}[];
+
+export declare const CLOSE_ICON_CLASS = "acrolinxFloatingSidebarCloseIcon";
+
 export declare class CodeMirror6Adapter implements AdapterInterface {
     private config;
     private currentContentChecking?;
@@ -299,7 +330,7 @@ declare type CodeMirrorAdapterConf = {
     format?: string;
 };
 
-declare interface CommonAdapterConf {
+export declare interface CommonAdapterConf {
     scrollOffsetY?: number;
     disableInputEventSimulation?: boolean;
 }
@@ -314,6 +345,15 @@ export declare interface CommonAdapterInterface {
     onInitFinished?(result: InitResult): void;
 }
 
+export declare function concatTextMappings(textMappings: TextDomMapping[]): TextDomMapping;
+
+/**
+ * Connects to a sidebar iframe that is on a different domain and uses the plugin message adapter.
+ */
+export declare function connectAcrolinxPluginToMessages(acrolinxPlugin: InternalAcrolinxSidebarPluginInterface, sidebarWindowIframe: HTMLIFrameElement): void;
+
+export declare function containsText(s: string): boolean;
+
 export declare class ContentEditableAdapter extends AbstractRichtextEditorAdapter {
     element: HTMLElement;
     constructor(conf: AdapterConf);
@@ -323,57 +363,156 @@ export declare class ContentEditableAdapter extends AbstractRichtextEditorAdapte
     getEditorDocument(): Document;
 }
 
-declare type ContentExtractionResult = SuccessfulContentExtractionResult | HasError;
+export declare type ContentExtractionResult = SuccessfulContentExtractionResult | HasError;
+
+export declare function createOffsetMappingArray(diffs: Diff[]): OffSetAlign[];
 
 /**
  * Used inside of a sidebar iframe on a different domain.
  */
 export declare function createPluginMessageAdapter(win?: Window & typeof globalThis): AcrolinxPlugin_2;
 
-declare interface DomPosition {
+export declare function deepCloneWithHTMLElement<T>(obj: T): T;
+
+export declare function deepFreezed<T>(o: T): T;
+
+export declare const DEFAULT_POS: Position;
+
+export declare class Deferred<T> {
+    resolve: (x: T) => void;
+    reject: (x: T) => void;
+    promise: Promise<T>;
+    constructor();
+}
+
+export declare interface DetectedBrowser {
+    name: string;
+    version: string;
+}
+
+export declare interface DomPosition {
     node: Node;
     offset: number;
 }
 
+export declare function domPosition(node: Node, offset: number): DomPosition;
+
+export declare const EDITABLE_ELEMENTS_SELECTOR: string;
+
 declare type ElementHtmlGetter = (el: HTMLElement) => string;
 
-declare interface EscapeHtmlCharactersResult {
+export declare function enableLogging(): void;
+
+export declare function escapeHtmlCharacters(text: string): EscapeHtmlCharactersResult;
+
+export declare interface EscapeHtmlCharactersResult {
     escapedText: string;
     backwardAlignment: OffSetAlign[];
 }
 
-declare interface ExtractContentForCheckOpts {
+export declare interface ExtractContentForCheckOpts {
     checkSelection?: boolean;
 }
 
+export declare function extractText(s: string): [string, OffSetAlign[]];
+
 export declare function extractTextDomMapping(node: Node): TextDomMapping;
 
-declare interface FloatingSidebar {
+export declare function findDisplacement(offsetMappingArray: OffSetAlign[], originalIndex: number): number;
+
+export declare function findNewIndex(offsetMappingArray: OffSetAlign[], originalIndex: number): number;
+
+export declare interface FloatingSidebar {
     toggleVisibility(): void;
     remove(): void;
 }
 
-declare interface FloatingSidebarConfig {
+export declare interface FloatingSidebarConfig {
     asyncStorage: AsyncStorage;
     sidebarContainerId?: string;
 }
 
+export declare const FOOTER = "acrolinxFloatingSidebarFooter";
+
+export declare const FOOTER_HEIGHT = 34;
+
 declare type Format = 'TEXT' | 'MARKDOWN';
 
+export declare function getAutobindWrapperAttributes(element: Element): AutobindWrapperAttributes;
+
+export declare function getCompleteFlagLength<T extends Match>(matches: AlignedMatch<T>[]): number;
+
+export declare function getEditableElements(doc?: Document | ShadowRoot | HTMLElement): Element[];
+
+export declare function getElementFromAdapterConf(conf: AdapterConf): HTMLElement;
+
+export declare function getEndDomPos(endIndex: number, domPositions: DomPosition[]): DomPosition;
+
 export declare function getSelectionHtmlRanges(editorElement: HTMLElement, getElementHtml?: ElementHtmlGetter): [number, number][];
 
-declare interface HasEditorID extends CommonAdapterConf {
+export declare function grepAttributeValues(html: string, attribute: string): string[];
+
+export declare interface HasEditorID extends CommonAdapterConf {
     editorId: string;
 }
 
-declare interface HasElement extends CommonAdapterConf {
+export declare function hasEditorID(a: AdapterConf): a is HasEditorID;
+
+export declare interface HasElement extends CommonAdapterConf {
     element: HTMLElement;
 }
 
-declare interface HasError {
+export declare function hasElement(a: AdapterConf): a is HasElement;
+
+export declare interface HasError {
     error: any;
 }
 
+export declare function hasError(a: ContentExtractionResult): a is HasError;
+
+/**
+ * Custom adapter for Heretto.com that extends AsyncContentEditableAdapter
+ * with custom selectRanges and replaceRanges implementation.
+ *
+ */
+export declare class HerettoContentEditableAdapter extends StateBasedContentEditableAdapter {
+    constructor(conf: AdapterConf);
+    /**
+     * Override selectRanges to add Heretto-specific event dispatching.
+     *
+     * @param checkId - The check ID
+     * @param matches - Array of matches to select
+     * @returns Promise that resolves when selection is complete
+     */
+    selectRanges(checkId: string, matches: Match[]): Promise<void>;
+    /**
+     * Dispatch mouseup and selectionchange events to notify Heretto's GWT editor
+     * about the selection change.
+     */
+    private dispatchHerettoSelectionEvents;
+    /**
+     * Override replaceRanges with custom implementation for Heretto.com.
+     * Uses paste event to apply replacements in the Heretto editor.
+     *
+     * The replacement is done asynchronously:
+     * 1. First select the text
+     * 2. Wait for selection events to propagate
+     * 3. Apply replacement via paste event
+     *
+     * @param checkId - The check ID
+     * @param matchesWithReplacement - Array of matches with replacement suggestions
+     * @returns Promise that resolves when replacement is complete, rejects on error
+     */
+    replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): Promise<void>;
+    /**
+     * Apply replacement text using the paste event.
+     *
+     * @param replacementText - The text to insert in place of the selection
+     * @throws Error if editor is not found or not editable
+     */
+    private applyReplacementViaPaste;
+}
+
 export declare function initFloatingSidebar(config: FloatingSidebarConfig): FloatingSidebar;
 
 export declare class InputAdapter implements AdapterInterface {
@@ -401,7 +540,63 @@ declare type InputAdapterConf = AdapterConf & {
     format?: Format;
 };
 
-declare type InputFormat = 'HTML' | 'TEXT';
+export declare type InputFormat = 'HTML' | 'TEXT';
+
+declare interface InternalAcrolinxSidebarPluginInterface extends AcrolinxSidebarPlugin {
+    requestInit(acrolinxSidebarArg?: AcrolinxSidebar): void;
+}
+
+export declare function internalFetch(url: string): Promise<string>;
+
+export declare const IS_DRAGGED_CLASS = "acrolinxFloatingSidebarIsDragged";
+
+export declare const IS_RESIZING_CLASS = "acrolinxFloatingSidebarIsResizing";
+
+export declare function isAsyncAdapterInterface(a: AdapterInterface | AsyncAdapterInterface): a is AsyncAdapterInterface;
+
+export declare function isChrome(): boolean;
+
+/**
+ * We don't want to destroy markup/markdown.
+ */
+export declare function isDangerousToReplace(checkedDocumentContent: string, originalMatch: Match): boolean;
+
+export declare function isDisplayed(element: Element): boolean;
+
+export declare function isFromSameOrigin(url: string): boolean;
+
+/**
+ * Check if the element is in a Heretto.com DITA editor.
+ *
+ * Detection is based on multiple robust identifiers:
+ * 1. Domain check: must be on heretto.com
+ * 2. Iframe ID: element must be inside iframe with id "gwt-debug-PreviewViewImpl.previewFrame"
+ * 3. Body class: Heretto editor body has class "heretto"
+ *
+ * @param el - The element to check
+ * @returns true if element is in the Heretto DITA editor
+ */
+export declare function isHeretto(el: Element): boolean;
+
+export declare function isIFrame(el: Element): el is HTMLIFrameElement;
+
+export declare function isProbablyUndesiredField(el: Element): boolean;
+
+export declare function isPromise<T>(result: T | Promise<T>): result is Promise<T>;
+
+export declare function isSuccessfulContentExtractionResult(a: ContentExtractionResult): a is SuccessfulContentExtractionResult;
+
+/**
+ * Exported only for testing.
+ */
+export declare function keepVisible({ left, top, height }: Position, windowWidth?: number, windowHeight?: number): Position;
+
+export declare function loadFromLocalStorage<T>(key: string): T | null;
+
+/**
+ * Exported only for testing.
+ */
+export declare function loadInitialPos(asyncStorage: AsyncStorage): Promise<Position>;
 
 /**
  * Loads the Styles and Scripts of the sidebar into the current window.
@@ -411,6 +606,10 @@ declare type InputFormat = 'HTML' | 'TEXT';
  */
 export declare function loadSidebarCode(sidebarBaseUrl: string): Promise<void>;
 
+export declare function log(message: any, ...args: any[]): void;
+
+export declare function logTime(text: string, f: Function): any;
+
 /**
  * @param {string} checkedDocument Text or HTML of the document (at check time)
  * @param {string} currentDocument Text or HTML of the current document
@@ -447,18 +646,68 @@ export declare class MultiEditorAdapter implements AdapterInterface {
     replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): void;
 }
 
-declare interface MultiEditorAdapterConfig {
+export declare interface MultiEditorAdapterConfig {
     aggregateFormat?: 'AUTO' | 'HTML';
     documentHeader?: string;
     rootElement?: WrapperConfOptions;
     beforeCheck?: (multiAdapter: MultiEditorAdapter) => void;
 }
 
-declare interface OffSetAlign {
+export declare const NEW_LINE_TAGS: Readonly<{
+    [key: string]: boolean;
+}>;
+
+export declare interface OffSetAlign {
     oldPosition: number;
     diffOffset: number;
 }
 
+export declare function parseUrl(href: string): {
+    protocol: string;
+    host: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    hash: string;
+};
+
+export declare interface Position extends PositionUpdate {
+    top: number;
+    left: number;
+    height: number;
+}
+
+export declare const POSITION_KEY = "acrolinx.plugins.floatingSidebar.position";
+
+export declare interface PositionUpdate {
+    top?: number;
+    left?: number;
+    height?: number;
+}
+
+export declare type PromiseProvider<T> = () => PromiseLike<T>;
+
+/**
+ * Just a proof of concept.
+ */
+export declare class QuipAdapter extends AbstractRichtextEditorAdapter {
+    element: HTMLElement;
+    constructor(conf: AdapterConf);
+    getEditorElement(): HTMLElement;
+    getContent(): string;
+    protected getSelection(): DocumentSelection;
+    getEditorDocument(): Document;
+    replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): Promise<void>;
+}
+
+export declare function rangeContent(content: string, m: {
+    range: [number, number];
+}): string;
+
+export declare function rebaseRelativeUrl(url: string, sidebarBaseUrl: string): string;
+
+export declare function rebaseRelativeUrls(sidebarHtml: string, sidebarBaseUrl: string): string;
+
 declare interface RegisteredAdapter {
     id: string;
     adapter: AdapterInterface | AsyncAdapterInterface;
@@ -472,6 +721,57 @@ declare interface RemappedMatches<T extends Match> {
     adapter: AdapterInterface;
 }
 
+export declare function removeNode(node: Node): void;
+
+export declare const RESIZE_ICON_CLASS = "acrolinxFloatingSidebarResizeIcon";
+
+export declare function saveToLocalStorage<T>(key: string, object: T): void;
+
+export declare function scrollIntoView(targetEl: HTMLElement, windowTopOffset?: number, localTopOffset?: number): void;
+
+/**
+ * @return indicates if it succeeded
+ */
+export declare function scrollIntoViewCenteredIfPossible(targetEl: HTMLElement): boolean;
+
+export declare function scrollIntoViewCenteredWithFallback(targetEl: HTMLElement): void;
+
+export declare let SIDEBAR_CONTAINER_ID: string;
+
+export declare const SIDEBAR_DRAG_OVERLAY_ID = "acrolinxDragOverlay";
+
+export declare const SIDEBAR_GLASS_PANE_ID = "acrolinxFloatingSidebarGlassPane";
+
+export declare const SIDEBAR_ID = "acrolinxFloatingSidebar";
+
+export declare const SIDEBAR_SDK_COMPONENT: {
+    id: string;
+    name: string;
+    version: string;
+};
+
+export declare class SidebarURLInvalidError extends Error {
+    message: string;
+    configuredSidebarURL: string;
+    htmlLoaded: string;
+    details: string;
+    constructor(message: string, configuredSidebarURL: string, htmlLoaded: string);
+}
+
+export declare function simulateInputEvent(props: SimulateInputEventProps): void;
+
+export declare type SimulateInputEventProps = {
+    startNode: Node;
+    endNode: Node;
+    eventType: string;
+    startOffset: number;
+    endOffset: number;
+    replacement: string;
+    disableSimulation?: boolean;
+};
+
+export declare function sortedIndexBy<T>(array: T[], value: T, iteratee: (item: T) => number): number;
+
 export declare class StateBasedContentEditableAdapter extends AbstractRichtextEditorAdapter implements AsyncAdapterInterface {
     element: HTMLElement;
     constructor(conf: AdapterConf);
@@ -488,26 +788,49 @@ export declare class StateBasedContentEditableAdapter extends AbstractRichtextEd
     scrollIntoView(sel: Selection): Promise<void>;
 }
 
-declare interface SuccessfulCheckResult {
+export declare interface SuccessfulCheckResult {
     checkedPart: CheckedDocumentPart;
     embedCheckInformation?: CheckInformationKeyValuePair[];
     inputFormat?: string;
 }
 
-declare interface SuccessfulContentExtractionResult {
+export declare interface SuccessfulContentExtractionResult {
     content: string;
     documentReference?: string;
     selection?: DocumentSelection;
     externalContent?: ExternalContent;
 }
 
-declare interface TextDomMapping {
+/**
+ * This wrapper around an AsyncAdapterInterface synchronizes all calls to selectRanges and replaceRanges.
+ * Thereby it prevents concurrency issues, that could arise from concurrent calls to these methods in some
+ * adapters.
+ */
+export declare class SynchronizeAsyncAdapter implements AsyncAdapterInterface {
+    private readonly adapter;
+    readonly isAsync = true;
+    readonly requiresSynchronization = false;
+    readonly getAutobindWrapperAttributes?: () => AutobindWrapperAttributes;
+    readonly getFormat?: () => string;
+    private workQueue;
+    constructor(adapter: AsyncAdapterInterface);
+    extractContentForCheck(opts: ExtractContentForCheckOpts): ContentExtractionResult | Promise<ContentExtractionResult>;
+    registerCheckCall(checkInfo: Check): void;
+    registerCheckResult(checkResult: SuccessfulCheckResult): void;
+    selectRanges(checkId: string, matches: Match[]): Promise<void>;
+    replaceRanges(checkId: string, matchesWithReplacement: MatchWithReplacement[]): Promise<void>;
+    onInitFinished(result: InitResult): void;
+}
+
+export declare interface TextDomMapping {
     text: string;
     domPositions: DomPosition[];
 }
 
 declare type TextMapping = TextDomMapping;
 
+export declare function textMapping(text: string, domPositions: DomPosition[]): TextDomMapping;
+
 declare type TextMapping_2 = TextDomMapping;
 
 export declare class TinyMCEAdapter extends AbstractRichtextEditorAdapter {
@@ -520,8 +843,23 @@ export declare class TinyMCEAdapter extends AbstractRichtextEditorAdapter {
     getEditorDocument(): Document;
 }
 
+export declare const TITLE_BAR_CLASS = "acrolinxFloatingSidebarTitleBar";
+
+export declare function toSet(keys: string[]): Readonly<{
+    [key: string]: boolean;
+}>;
+
 declare type ValidInputElement = HTMLInputElement | HTMLTextAreaElement;
 
+export declare function waitMs(ms: number): Promise<unknown>;
+
+export declare class WorkQueue {
+    private workTodo;
+    private currentWork?;
+    addWork<T>(work: PromiseProvider<T>): Promise<T>;
+    private doRemainingWork;
+}
+
 declare interface WrapperConf extends WrapperConfOptions {
     tagName: string;
     attributes: AttributeMap;