@knaw-huc/text-annotation-segmenter 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ However, HTML is hierarchical. How to display these kinds of annotations that do
 
 The `segment` function creates an array of segments: a flat, non-overlapping list where each segment links to both the text and all the annotations that apply. Each segment translates into a single DOM element. Elements linked to multiple overlapping annotations can now be decorated with their own styling, classes and callbacks.
 
-A special case is the marker: an annotation of zero width marking a position in the text. Markers result in zero-width segments, also linking all annotations that start at, end at, or span across that position.
+A special case is the marker: an annotation of zero width marking a position in the text. Markers result in zero-width segments, also linking all annotations that start at or span across that position.
 
 ## API
 
@@ -20,6 +20,8 @@ A special case is the marker: an annotation of zero width marking a position in
 - [`TextSegment<T>`](./src/Model.ts) <br /> Output list of segments with character offsets and the annotations that apply.
 - [`groupSegments<T>(segments, predicate): Group<T>[]`](./src/groupSegments.ts) <br /> Group segments into higher-level units (e.g., words, sentences, entities) by collecting all segments that share a matching annotation.
 - [`Group<T>`](./src/groupSegments.ts) <br /> Output group of segments matching the same predicate result.
+- [`mapAnnotationSegmentRanges<T>(segments): Map<T, SegmentRange>`](./src/mapAnnotationSegmentRanges.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
+- [`SegmentRange`](./src/mapAnnotationSegmentRanges.ts) <br /> Start and end segment index of an annotation (end excluding).
 
 ## Example
 

package/dist/Model.d.ts

@@ -1,18 +1,13 @@
-/**
- * Input list of objects linking annotations to the text using character offsets.
- */
-export type AnnotationSegment<T = unknown> = {
+export type Offsets = {
     begin: number;
     end: number;
-    body: T;
 };
 /**
- * Output list of segments with character offsets and the annotations that apply.
+ * Output: segment of text and the annotations that apply.
  */
-export type TextSegment<T = unknown> = {
-    id: SegmentId;
-    begin: number;
-    end: number;
+export type TextSegment<T> = Offsets & {
+    index: SegmentIndex;
+    body: string;
     annotations: T[];
 };
-export type SegmentId = string;
+export type SegmentIndex = number;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { segment } from './segment.ts';
 export type { AnnotationSegmentsByChar } from './segment.ts';
+export { mapAnnotationSegmentRanges } from './mapAnnotationSegmentRanges.ts';
+export type { SegmentRange } from './mapAnnotationSegmentRanges.ts';
 export { groupSegments } from './groupSegments.ts';
 export type { Group } from './groupSegments.ts';
-export type { AnnotationSegment, TextSegment, SegmentId, } from './Model.ts';
+export type { Offsets, TextSegment, SegmentIndex, } from './Model.ts';

package/dist/index.js

@@ -1,21 +1,17 @@
 function segment(text, annotations) {
   const segments = [];
-  let segmentCounter = 0;
+  let segmentCounter = -1;
   const offsetMap = /* @__PURE__ */ new Map(), getOrCreateOffset = (charIndex) => {
     let offset = offsetMap.get(charIndex);
     return offset || (offset = { charIndex, starting: [], ending: [] }, offsetMap.set(charIndex, offset)), offset;
   };
   getOrCreateOffset(0), getOrCreateOffset(text.length);
   for (const annotation of annotations) {
-    if (annotation.begin >= text.length || annotation.end <= 0)
+    const isMarker = annotation.begin === annotation.end;
+    if (isMarker && (annotation.end < 0 || annotation.begin > text.length) || !isMarker && (annotation.end <= 0 || annotation.begin >= text.length))
       continue;
-    const needsClamping = annotation.begin < 0 || annotation.end > text.length;
-    let clamped = annotation;
-    needsClamping && (clamped = {
-      ...annotation,
-      begin: Math.max(0, annotation.begin),
-      end: Math.min(text.length, annotation.end)
-    }), getOrCreateOffset(clamped.begin).starting.push(clamped), getOrCreateOffset(clamped.end).ending.push(clamped);
+    const begin = Math.max(0, annotation.begin), end = Math.min(text.length, annotation.end);
+    getOrCreateOffset(begin).starting.push(annotation), getOrCreateOffset(end).ending.push(annotation);
   }
   const sortedOffsets = [...offsetMap.values()].sort(
     (a, b) => a.charIndex - b.charIndex
@@ -23,11 +19,12 @@ function segment(text, annotations) {
   let lastOffset = 0;
   for (const offset of sortedOffsets) {
     if (offset.charIndex > lastOffset) {
-      const id = `${segmentCounter++}`;
+      const index = ++segmentCounter;
       segments.push({
-        id,
+        index,
         begin: lastOffset,
         end: offset.charIndex,
+        body: text.slice(lastOffset, offset.charIndex),
         annotations: [...activeAnnotations]
       });
     }
@@ -35,22 +32,32 @@ function segment(text, annotations) {
     let hasMarkers = !1;
     const markerSegmentAnnotations = [];
     for (const a of offset.starting)
-      offset.ending.includes(a) ? (hasMarkers = !0, markerSegmentAnnotations.push(a.body)) : activeAnnotations.add(a.body);
-    for (const a of offset.ending)
-      activeAnnotations.delete(a.body);
+      offset.ending.includes(a) ? (hasMarkers = !0, markerSegmentAnnotations.push(a)) : activeAnnotations.add(a);
+    for (const annotation of offset.ending)
+      activeAnnotations.delete(annotation);
     if (hasMarkers) {
       markerSegmentAnnotations.push(...activeAnnotations);
-      const segment2 = `${segmentCounter++}`;
+      const index = ++segmentCounter;
       segments.push({
-        id: segment2,
+        index,
         begin: offset.charIndex,
         end: offset.charIndex,
+        body: "",
         annotations: markerSegmentAnnotations
       });
     }
   }
   return segments;
 }
+function mapAnnotationSegmentRanges(segments) {
+  const ranges = /* @__PURE__ */ new Map();
+  for (let i = 0; i < segments.length; i++)
+    for (const annotation of segments[i].annotations) {
+      const existing = ranges.get(annotation);
+      existing ? existing.endSegment = i + 1 : ranges.set(annotation, { startSegment: i, endSegment: i + 1 });
+    }
+  return ranges;
+}
 function groupSegments(segments, predicate) {
   const groups = /* @__PURE__ */ new Map();
   for (const segment2 of segments) {
@@ -67,5 +74,6 @@ function groupSegments(segments, predicate) {
 }
 export {
   groupSegments,
+  mapAnnotationSegmentRanges,
   segment
 };

package/dist/mapAnnotationSegmentRanges.d.ts

@@ -0,0 +1,12 @@
+import { TextSegment } from './Model';
+export type SegmentRange = {
+    startSegment: number;
+    /**
+     * Excluding last segment
+     */
+    endSegment: number;
+};
+/**
+ * For each annotation, collect the first and last segment index it appears in, keyed by object reference.
+ */
+export declare function mapAnnotationSegmentRanges<T>(segments: TextSegment<T>[]): Map<T, SegmentRange>;

package/dist/segment.d.ts

@@ -1,10 +1,10 @@
-import { AnnotationSegment, TextSegment } from './Model';
+import { Offsets, TextSegment } from './Model';
 /**
  * Split a text into {@link TextSegment}s with character offsets and a list of applying annotations.
  */
-export declare function segment<T>(text: string, annotations: AnnotationSegment<T>[]): TextSegment<T>[];
-export type AnnotationSegmentsByChar<T = unknown> = {
+export declare function segment<T extends Offsets>(text: string, annotations: T[]): TextSegment<T>[];
+export type AnnotationSegmentsByChar<T extends Offsets = Offsets> = {
     charIndex: number;
-    starting: AnnotationSegment<T>[];
-    ending: AnnotationSegment<T>[];
+    starting: T[];
+    ending: T[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knaw-huc/text-annotation-segmenter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knaw-huc/text-annotation-segmenter.git"
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "dev:build": "vite build --watch",
-    "build": "vite build",
+    "build": "npm run test && vite build",
     "test": "vitest run",
     "bench": "vitest bench",
     "prepublishOnly": "npm run build"

package/README.html

@@ -1,41 +0,0 @@
-<h1 id="knaw-huctext-annotation-segmenter"><span class="citation" data-cites="knaw-huc/text-annotation-segmenter">@knaw-huc/text-annotation-segmenter</span></h1>
-<p>Utility functions to help render overlapping annotations in a text.</p>
-<p>Annotations on a text have a non-hierarchical nature, i.e., they can overlap:</p>
-<pre class="text"><code>Aa&lt;bc&gt;bb&lt;cd&gt;cc&lt;/bc&gt;dd&lt;cd&gt;ee.</code></pre>
-<p>However, HTML is hierarchical. How to display these kinds of annotations that do not live inside or next to each other, but cut across each other?</p>
-<p>The <code>segment</code> function creates an array of segments: a flat, non-overlapping list where each segment links to both the text and all the annotations that apply. Each segment translates into a single DOM element. Elements linked to multiple overlapping annotations can now be decorated with their own styling, classes and callbacks.</p>
-<p>A special case is the marker: an annotation of zero width marking a position in the text. Markers result in zero-width segments, also linking all annotations that start at, end at, or span across that position.</p>
-<h2 id="api">API</h2>
-<ul>
-<li><a href="./src/segment.ts"><code>segment&lt;T&gt;(text, annotations): TextSegment&lt;T&gt;[]</code></a> <br /> Split a text into TextSegments with char offsets to the text and a list of applying annotations.</li>
-<li><a href="./src/Model.ts"><code>AnnotationSegment&lt;T&gt;</code></a> <br /> Input list of objects linking annotations to the text using character offsets.</li>
-<li><a href="./src/Model.ts"><code>TextSegment&lt;T&gt;</code></a> <br /> Output list of segments with character offsets and the annotations that apply.</li>
-<li><a href="./src/groupSegments.ts"><code>groupSegments&lt;T&gt;(segments, predicate): Group&lt;T&gt;[]</code></a> <br /> Group segments into higher-level units (e.g., words, sentences, entities) by collecting all segments that share a matching annotation.</li>
-<li><a href="./src/groupSegments.ts"><code>Group&lt;T&gt;</code></a> <br /> Output group of segments matching the same predicate result.</li>
-</ul>
-<h2 id="example">Example</h2>
-<p>Given the text <code>"abc"</code> with two overlapping annotations:</p>
-<div class="sourceCode" id="cb2"><pre class="sourceCode txt"><code class="sourceCode default"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a>         text:  abc</span>
-<span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a>annotation ab:  __</span>
-<span id="cb2-3"><a href="#cb2-3" aria-hidden="true"></a>annotation bc:   __</span></code></pre></div>
-<div class="sourceCode" id="cb3"><pre class="sourceCode ts"><code class="sourceCode typescript"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a><span class="im">import</span> { segment } from <span class="st">&quot;text-annotation-segmenter&quot;</span><span class="op">;</span></span>
-<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a></span>
-<span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a>const text <span class="op">=</span> <span class="st">&#39;abc&#39;</span><span class="op">;</span></span>
-<span id="cb3-4"><a href="#cb3-4" aria-hidden="true"></a>const ab <span class="op">=</span> {id<span class="op">:</span> <span class="st">&#39;ab&#39;</span>}<span class="op">;</span></span>
-<span id="cb3-5"><a href="#cb3-5" aria-hidden="true"></a>const bc <span class="op">=</span> {id<span class="op">:</span> <span class="st">&#39;bc&#39;</span>}<span class="op">;</span></span>
-<span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a></span>
-<span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a>const segments <span class="op">=</span> <span class="fu">segment</span>(text<span class="op">,</span> [</span>
-<span id="cb3-8"><a href="#cb3-8" aria-hidden="true"></a>  {begin<span class="op">:</span> <span class="dv">0</span><span class="op">,</span> end<span class="op">:</span> <span class="dv">2</span><span class="op">,</span> body<span class="op">:</span> ab}<span class="op">,</span></span>
-<span id="cb3-9"><a href="#cb3-9" aria-hidden="true"></a>  {begin<span class="op">:</span> <span class="dv">1</span><span class="op">,</span> end<span class="op">:</span> <span class="dv">3</span><span class="op">,</span> body<span class="op">:</span> bc}<span class="op">,</span></span>
-<span id="cb3-10"><a href="#cb3-10" aria-hidden="true"></a>])<span class="op">;</span></span>
-<span id="cb3-11"><a href="#cb3-11" aria-hidden="true"></a></span>
-<span id="cb3-12"><a href="#cb3-12" aria-hidden="true"></a><span class="fu">expect</span>(segments)<span class="op">.</span><span class="fu">toEqual</span>([</span>
-<span id="cb3-13"><a href="#cb3-13" aria-hidden="true"></a>  {id<span class="op">:</span> <span class="st">&#39;0&#39;</span><span class="op">,</span> begin<span class="op">:</span> <span class="dv">0</span><span class="op">,</span> end<span class="op">:</span> <span class="dv">1</span><span class="op">,</span> annotations<span class="op">:</span> [ab]}<span class="op">,</span></span>
-<span id="cb3-14"><a href="#cb3-14" aria-hidden="true"></a>  {id<span class="op">:</span> <span class="st">&#39;1&#39;</span><span class="op">,</span> begin<span class="op">:</span> <span class="dv">1</span><span class="op">,</span> end<span class="op">:</span> <span class="dv">2</span><span class="op">,</span> annotations<span class="op">:</span> [ab<span class="op">,</span> bc]}<span class="op">,</span></span>
-<span id="cb3-15"><a href="#cb3-15" aria-hidden="true"></a>  {id<span class="op">:</span> <span class="st">&#39;2&#39;</span><span class="op">,</span> begin<span class="op">:</span> <span class="dv">2</span><span class="op">,</span> end<span class="op">:</span> <span class="dv">3</span><span class="op">,</span> annotations<span class="op">:</span> [bc]}<span class="op">,</span></span>
-<span id="cb3-16"><a href="#cb3-16" aria-hidden="true"></a>])<span class="op">;</span></span></code></pre></div>
-<p>More examples:</p>
-<ul>
-<li>For edge cases, see: <a href="./src/segment.spec.ts">segment.spec.ts</a>.</li>
-<li>For benchmarks, see <a href="./src/segment.bench.ts">segment.bench.ts</a>.</li>
-</ul>