#6108 - Relation support for the Apache Annotator HTML editor mode

- Add relation rendering to the Apache Annotator HTML editor: relations with both endpoints inside the effect-range band are drawn as full arcs, band-crossing relations as directional up/down stubs whose clickable tip jumps to the far endpoint, and pass-through relations are not drawn (RelationVisualizer)
- Add relation-creation by dragging from a span: a drag state machine (IDLE -> ARMED -> DRAGGING -> COMMIT/CANCEL) with window-level capture listeners so a release outside the iframe still resolves and does not leak into span creation (RelationDragController)
- Add hover-surfaced relation-creation "grips": a small drag affordance anchored above a hovered span's start that proxies the span without competing with the native text-selection gesture (RelationGripLayer)
- Add a target-disambiguation popup ("relation-target" mode) so a relation drag ending on overlapping spans lets the user pick which span is the target; dismissing cancels the relation (ApacheAnnotatorSelector.pickRelationTarget)
- Add a pooled per-color SVG arrowhead marker registry plus an svgEl element-creation helper (ArrowMarkerPool)
- Add a relation-labels preference and toolbar toggle: labels shown at rest vs. on hover, applied as a pure CSS mode flip without re-rendering
- Add line-spacing presets (low/mid/high/xhigh) with toolbar S/M/L/X buttons, applied as a class on the editor root; cap the arc bow scale so xhigh stacking matches the high preset
- Re-band the relation overlay around the current viewport on manual scroll, coalesced to one redraw per frame
- Fix overlay sizing so it collapses to zero before measuring content extent, preventing scrolling past the text into a blank region with no arcs (#6108)
- Add showRelationLabels and lineSpacing to the editor user-preferences schema
- Document ViewportTracker's visible range as a superset (recomputed only when elements are added), and remove dead display-style probing code
- Add distinctHighlightStack and fanAngle helpers (Utilities)
- Remove the invalid bugs URL from inception-assistant-ui package.json

Author: reckart

inception/inception-assistant-ui/src/main/ts_template/package.json

@@ -19,9 +19,6 @@
     "type": "git",
     "url": "git+https://github.com/inception-project/inception.git"
   },
-  "bugs": {
-    "url": "https://github.com/inception-project/issues"
-  },
   "overrides": {
     "minimatch": "${minimatch.version}",
     "immutable": "${immutable.version}",

inception/inception-html-apache-annotator-editor/src/main/java/de/tudarmstadt/ukp/inception/apacheannotatoreditor/ApacheAnnotatorHtmlAnnotationEditorFactoryUserPreferences.schema.json

@@ -28,6 +28,13 @@
     },
     "keyboardCursorEnabled": {
       "type": "boolean"
+    },
+    "showRelationLabels": {
+      "type": "boolean"
+    },
+    "lineSpacing": {
+      "type": "string",
+      "enum": ["low", "mid", "high", "xhigh"]
     }
   },
   "additionalProperties": false

inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorEditor.scss

@@ -113,12 +113,33 @@ sec-wrap {
 
 .i7n-wrapper {
     position: relative;
-    line-height: 1.8;
+    line-height: 1.8; // default; overridden by the .iaa-line-spacing-* presets below
     overflow: auto;
     padding-left: var(--vertical-tray-width-left);
     padding-right: var(--vertical-tray-width-right);
 }
 
+/**
+ * Line-spacing presets. Toggled as a class on the editor root by applyLineSpacing();
+ * line-height inherits down to the document content.
+ */
+.iaa-line-spacing-low {
+    line-height: 1.4;
+}
+
+.iaa-line-spacing-mid {
+    line-height: 1.8;
+}
+
+.iaa-line-spacing-high {
+    line-height: 2.6;
+}
+
+.iaa-line-spacing-xhigh {
+    line-height: 5.2; // double the `high` preset; the arc bow scale is already capped (see
+                      // ARC_BOW_SCALE_MAX) so the stacked-arc bow matches `high` rather than scaling further.
+}
+
 /**
  * Annotation highlight.
  */

inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorEditor.ts

@@ -27,7 +27,12 @@ import { ApacheAnnotatorVisualizer } from './ApacheAnnotatorVisualizer.svelte';
 import { ApacheAnnotatorSelector } from './ApacheAnnotatorSelector';
 import { normalizeSectionsForPinning } from './SectionPinning';
 import ApacheAnnotatorToolbar from './ApacheAnnotatorToolbar.svelte';
-import { annotatorState } from './ApacheAnnotatorState.svelte';
+import {
+    annotatorState,
+    defaultAnnotatorPreferences as defaultPreferences,
+    LINE_SPACINGS,
+    type LineSpacing,
+} from './ApacheAnnotatorState.svelte';
 import AnnotationDetailPopOver from '@inception-project/inception-js-api/src/widget/AnnotationDetailPopOver.svelte';
 import { mount, tick, unmount } from 'svelte';
 import {
@@ -71,24 +76,13 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
         this.ajax = ajax;
         this.root = element;
         this.userPreferencesKey = userPreferencesKey;
-        // Settled during init by normalizeSectionsForPinning (Step 1 below).
+        // Settled during init by normalizeSectionsForPinning.
         this.sectionSelector = '';
         this.protectedElements = protectedElements;
         this.documentStructure = documentStructure;
         const protectedSel = [...protectedElements].join(',');
         this.protectedElementsMatcher = compileNsSelector(protectedSel) || undefined;
 
-        const defaultPreferences = {
-            showLabels: true,
-            showAggregatedLabels: false,
-            showEmptyHighlights: false,
-            showDocumentStructure: false,
-            showImages: true,
-            showTables: true,
-            documentStructureWidth: 0.2,
-            protectElements: true,
-            keyboardCursorEnabled: false,
-        };
         let preferences = Object.assign({}, defaultPreferences);
 
         ajax.loadPreferences(userPreferencesKey)
@@ -97,6 +91,8 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
                 console.log('Loaded preferences', preferences);
 
                 annotatorState.showLabels = preferences.showLabels ?? defaultPreferences.showLabels;
+                annotatorState.showRelationLabels =
+                    preferences.showRelationLabels ?? defaultPreferences.showRelationLabels;
                 annotatorState.showAggregatedLabels =
                     preferences.showAggregatedLabels ?? defaultPreferences.showAggregatedLabels;
                 annotatorState.showEmptyHighlights =
@@ -111,55 +107,57 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
                     preferences.protectElements ?? defaultPreferences.protectElements;
                 annotatorState.keyboardCursorEnabled =
                     preferences.keyboardCursorEnabled ?? defaultPreferences.keyboardCursorEnabled;
+                const loadedLineSpacing = preferences.lineSpacing ?? defaultPreferences.lineSpacing;
+                annotatorState.lineSpacing = LINE_SPACINGS.includes(
+                    loadedLineSpacing as LineSpacing
+                )
+                    ? (loadedLineSpacing as LineSpacing)
+                    : 'mid';
+                this.applyLineSpacing();
             })
             .then(() => {
-                // Move all content into a document container
                 const documentContainer = this.root.ownerDocument.createElement('div');
                 documentContainer.classList.add('iaa-document-container');
                 [...this.root.ownerDocument.body.children].forEach((child) =>
                     documentContainer.appendChild(child)
                 );
 
-                // Step 1 (rendering fix): make section elements pinnable and
-                // settle the section selector. Schema-free; see SectionPinning.
-                // Must run before the IDs are assigned so they land on the
-                // wrapper elements rather than the soon-to-be-buried originals.
+                // Make section elements pinnable and settle the section selector. This must run
+                // before the IDs are assigned so they land on the wrapper elements rather than the
+                // soon-to-be-buried originals.
                 this.sectionSelector = normalizeSectionsForPinning(
                     documentContainer,
                     sectionElementLocalNames
                 );
                 this.ensureSectionElementsHaveAnId();
 
-                // Step 2 (table of contents): build the outline for the
-                // navigator. Operates on the post-pinning DOM; owns title and
-                // scroll-target extraction per format.
+                // Build the outline for the navigator, operating on the post-pinning DOM.
                 this.documentStructure.preprocess(documentContainer);
 
-                // Set up a container for the document navigation sidebar
                 this.navigatorContainer = this.root.ownerDocument.createElement('div');
                 this.navigatorContainer.classList.add('iaa-document-navigator');
 
-                // Set up a split pane to host the document and the document structure navigation sidebar
                 this.horizSplitPane = this.createHorizontalSplitPane(
                     this.navigatorContainer,
                     documentContainer
                 );
 
-                // Add the split pane to the document
                 this.root.ownerDocument.body.appendChild(this.horizSplitPane);
 
-                // Add the editor components for the document container
+                // The selector is created first so the visualizer's relation-drag controller can
+                // defer multi-hit target disambiguation to it.
+                this.selector = new ApacheAnnotatorSelector(this.root, this.ajax);
                 this.vis = new ApacheAnnotatorVisualizer(
                     this.root,
                     this.ajax,
-                    this.sectionSelector
+                    this.sectionSelector,
+                    (clientX, clientY, targets, onPick) =>
+                        this.selector.pickRelationTarget(clientX, clientY, targets, onPick)
                 );
                 this.vis.protectedElementSelector = [...protectedElements].join(',');
-                this.selector = new ApacheAnnotatorSelector(this.root, this.ajax);
 
                 this.documentContainer = documentContainer;
 
-                // Add auxiliary controls
                 this.documentStructureNavigator = this.createDocumentNavigator(
                     this.navigatorContainer,
                     documentContainer,
@@ -184,10 +182,8 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
                     },
                 });
 
-                // Event handler for creating an annotion or selecting an annotation
                 this.root.addEventListener('mouseup', (e) => this.onMouseUp(e));
 
-                // Event handler for opening the context menu
                 this.root.addEventListener('contextmenu', (e) => this.onRightClick(e));
 
                 // Prevent right-click from triggering a selection event
@@ -233,7 +229,6 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
         divider.addEventListener('mousedown', (e) => {
             if (e.buttons !== 1) return;
 
-            // Clean up any previous resize operation
             if (this.activeResizeCleanup) {
                 this.activeResizeCleanup();
             }
@@ -357,10 +352,37 @@ export class ApacheAnnotatorEditor implements AnnotationEditor {
                 keyboardCursorPreferencesChanged: (e: Event) => {
                     this.keyboardMode?.enable(annotatorState.keyboardCursorEnabled);
                 },
+                lineSpacingPreferencesChanged: (e: Event) => {
+                    this.applyLineSpacing();
+                    // The new line-height reflows the text, moving every highlight. Re-materialize
+                    // the locked section dimensions and re-render so arcs/stubs follow the new
+                    // positions. Only the geometry changed — the annotation data is unchanged — so
+                    // re-render from the cached data instead of a full server round-trip.
+                    this.vis?.optimizeLayout('line spacing');
+                    this.vis?.rerender();
+                },
+                relationLabelPreferencesChanged: (e: Event) => {
+                    // Pure visual toggle — the labels are already drawn, so just flip the mode.
+                    this.vis?.refreshRelationLabelMode();
+                },
             },
         });
     }
 
+    /**
+     * Apply the active line-spacing preset as a class on the editor root, matching the
+     * class-toggle pattern used by the other visual preferences (e.g. `iaa-hide-images`).
+     * The heights live in SCSS; `line-height` inherits down to the document content.
+     */
+    private applyLineSpacing(): void {
+        const root = this.root as HTMLElement;
+        LINE_SPACINGS.forEach((s) => root.classList.remove(`iaa-line-spacing-${s}`));
+        const spacing = LINE_SPACINGS.includes(annotatorState.lineSpacing)
+            ? annotatorState.lineSpacing
+            : 'mid';
+        root.classList.add(`iaa-line-spacing-${spacing}`);
+    }
+
     private createDocumentNavigator(
         target: HTMLElement,
         documentContainer: HTMLElement,

inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorSelector.ts

@@ -28,8 +28,12 @@ import { createPopper, type Instance } from '@popperjs/core';
  *   selection is offered (no ❌); activating an entry selects it.
  * - `keyboard-delete`: opened via the keyboard to pick an annotation to delete.
  *   Activating an entry deletes it and the entry is styled as destructive.
+ * - `relation-target`: opened by a relation-creation drag that ended on a stack of
+ *   several spans. Activating an entry resolves the
+ *   pending pick callback with the chosen vid instead of selecting/deleting; dismissing
+ *   the popup cancels the relation. No ❌ buttons.
  */
-type PopupMode = 'mouse' | 'keyboard-select' | 'keyboard-delete';
+type PopupMode = 'mouse' | 'keyboard-select' | 'keyboard-delete' | 'relation-target';
 
 export class ApacheAnnotatorSelector {
     private ajax: DiamAjax;
@@ -45,6 +49,10 @@ export class ApacheAnnotatorSelector {
     private focusFallback: HTMLElement | undefined;
     private popupKeydownHandler: ((e: KeyboardEvent) => void) | undefined;
     private popupMode: PopupMode = 'mouse';
+    // In 'relation-target' mode, the drag controller's callback to resolve with the
+    // chosen target vid. Cleared (without being called) when the popup is dismissed,
+    // which the controller treats as a cancel.
+    private pendingTargetPick: ((vid: VID) => void) | undefined;
 
     public constructor(element: Element, ajax: DiamAjax) {
         this.ajax = ajax;
@@ -111,8 +119,24 @@ export class ApacheAnnotatorSelector {
         return true;
     }
 
+    /**
+     * Ask the user which of several overlapping spans is a relation's target. The popup
+     * opens at the drop point; `onPick` fires with the chosen vid, or not at all if the
+     * popup is dismissed (which the caller treats as a cancel). `hls` must already be deduplicated by vid.
+     */
+    public pickRelationTarget(
+        clientX: number,
+        clientY: number,
+        hls: HTMLElement[],
+        onPick: (vid: VID) => void
+    ): void {
+        this.destroyPopup();
+        if (hls.length === 0) return;
+        this.pendingTargetPick = onPick;
+        this.createPopup(clientX, clientY, hls, true, 'relation-target');
+    }
+
     private onMouseDown(event: Event): void {
-        // Destroy popup if clicked outside of popup
         if (!this.isVisible()) {
             return;
         }
@@ -141,6 +165,7 @@ export class ApacheAnnotatorSelector {
         this.activeIndex = -1;
         this.focusFallback = undefined;
         this.popupMode = 'mouse';
+        this.pendingTargetPick = undefined;
     }
 
     public isVisible(): boolean {
@@ -153,7 +178,6 @@ export class ApacheAnnotatorSelector {
         this.destroyPopup();
 
         const hls = event.target instanceof Node ? highlights(event.target) : [];
-        // No need to show selector if there is no annotation
         if (hls.length === 0) return;
 
         if (
@@ -205,12 +229,16 @@ export class ApacheAnnotatorSelector {
         // Make the menu focusable so it can capture keyboard navigation keys.
         this.popupContent.tabIndex = -1;
 
-        // In the keyboard modes, show a header indicating whether picking an entry
-        // selects or deletes it.
+        // Outside plain mouse mode, show a header indicating what activating an entry does.
         if (mode !== 'mouse') {
             const header = document.createElement('div');
             header.classList.add('iaa-menu-header');
-            header.textContent = mode === 'keyboard-delete' ? 'Delete…' : 'Select…';
+            header.textContent =
+                mode === 'keyboard-delete'
+                    ? 'Delete…'
+                    : mode === 'relation-target'
+                      ? 'Relation target…'
+                      : 'Select…';
             this.popupContent.appendChild(header);
         }
 
@@ -303,16 +331,27 @@ export class ApacheAnnotatorSelector {
 
     /**
      * Perform the popup's primary action on an entry: delete in keyboard-delete mode,
-     * otherwise select.
+     * resolve the relation-target pick in relation-target mode, otherwise select.
      */
     private activateItem(event: Event, id: VID) {
         if (this.popupMode === 'keyboard-delete') {
             this.onDeleteAnnotation(event, id);
+        } else if (this.popupMode === 'relation-target') {
+            this.onPickRelationTarget(event, id);
         } else {
             this.onSelectAnnotation(event, id);
         }
     }
 
+    private onPickRelationTarget(event: Event, id: VID) {
+        event.stopPropagation();
+        // Capture before destroyPopup() clears it: destroy first so the controller's
+        // createRelationAnnotation runs against a torn-down popup, then resolve.
+        const pick = this.pendingTargetPick;
+        this.destroyPopup();
+        pick?.(id);
+    }
+
     private onSelectAnnotation(event: Event, id: VID) {
         console.log(`Selecting annotation ${id}`);
         event.stopPropagation();

inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorState.svelte.ts

@@ -16,8 +16,16 @@
  * limitations under the License.
  */
 
-export const annotatorState = $state({
+/**
+ * Line-spacing presets. The actual line-heights live in SCSS next to the
+ * `.i7n-wrapper` rule (`iaa-line-spacing-low|mid|high|xhigh`); `mid` is the default.
+ */
+export type LineSpacing = 'low' | 'mid' | 'high' | 'xhigh';
+export const LINE_SPACINGS: readonly LineSpacing[] = ['low', 'mid', 'high', 'xhigh'];
+
+export const defaultAnnotatorPreferences = {
     showLabels: true,
+    showRelationLabels: true,
     showAggregatedLabels: false,
     showEmptyHighlights: false,
     showDocumentStructure: false,
@@ -26,4 +34,7 @@ export const annotatorState = $state({
     showTables: true,
     protectElements: true,
     keyboardCursorEnabled: false,
-});
+    lineSpacing: 'mid' as LineSpacing,
+};
+
+export const annotatorState = $state({ ...defaultAnnotatorPreferences });