@knaw-huc/text-annotation-segmenter 0.1.1 → 0.3.0

package/README.md

@@ -15,15 +15,18 @@ A special case is the marker: an annotation of zero width marking a position in
 
 ## API
 
-- [`segment<T>(text, annotations): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with char offsets to the text and a list of applying annotations.
-- [`AnnotationSegment<T>`](./src/Model.ts) <br /> Input list of objects linking annotations to the text using character offsets.
-- [`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.
+- [`segment<T>(text, annotations, getOffsets): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with char offsets to the text and a list of applying annotations.
+- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end offsets of text segment (excluding last character), plus the annotations that apply.
+- [`groupSegments<T>(segments, isGroup, getId): SegmentGroup<T>[]`](src/groupSegments.ts) <br /> Recursively group segments into higher-level units (e.g., words, paragraphs, divs) by collecting all segments that share a matching annotation.
+- [`SegmentGroup<T>`](src/groupSegments.ts) <br /> A `Group<T>` (with annotation and recursive children) or `Ungrouped<T>` (with plain segments).
+- [`findSegmentOffsets<T>(segments): Map<T, SegmentOffsets>`](src/findSegmentOffsets.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
+- [`SegmentOffsets`](src/findSegmentOffsets.ts) <br /> Start and end segment index of an annotation (excluding end segment).
 
 ## Example
 
-Given the text `"abc"` with two overlapping annotations:
+### Create text segments
+
+A text 'abc' with two overlapping annotations at 'ab' and 'bc' will be split up in three segments:
 
 ```txt
          text:  abc
@@ -32,24 +35,67 @@ annotation bc:   __
 ```
 
 ```ts
-import { segment } from "text-annotation-segmenter";
+import { segment } from "@knaw-huc/text-annotation-segmenter";
 
 const text = 'abc';
-const ab = {id: 'ab'};
-const bc = {id: 'bc'};
+const ab = {id: 'ab', begin: 0, end: 2};
+const bc = {id: 'bc', begin: 1, end: 3};
 
-const segments = segment(text, [
-  {begin: 0, end: 2, body: ab},
-  {begin: 1, end: 3, body: bc},
-]);
+const segments = segment(text, [ab, bc], (a) => a);
 
 expect(segments).toEqual([
-  {id: '0', begin: 0, end: 1, annotations: [ab]},
-  {id: '1', begin: 1, end: 2, annotations: [ab, bc]},
-  {id: '2', begin: 2, end: 3, annotations: [bc]},
+  {index: 0, begin: 0, end: 1, body: 'a', annotations: [ab]},
+  {index: 1, begin: 1, end: 2, body: 'ab', annotations: [ab, bc]},
+  {index: 2, begin: 2, end: 3, body: 'c', annotations: [bc]},
+]);
+```
+
+### Group segments
+
+We can use segments to build up a hierachy of elements:
+
+Given the text 'ab' with a section spanning the whole text and a paragraph spanning the first half:
+
+```txt
+       text:  aabb
+    section:  ____
+  paragraph:  __
+```
+
+```ts
+import {segment, groupSegments} from "@knaw-huc/text-annotation-segmenter";
+
+const text = 'aabb';
+const section = {id: 'section', type: 'section', begin: 0, end: 4};
+const paragraph = {id: 'paragraph', type: 'paragraph', begin: 0, end: 2};
+
+const segments = segment(text, [section, paragraph], (a) => a);
+
+const isGroup = a => a.type === 'section' || a.type === 'paragraph';
+const getId = a => a.id;
+
+const groups = groupSegments(
+  segments,
+  isGroup,
+  getId,
+);
+
+expect(groups).toEqual([
+  {
+    isGroup: true, annotation: section, children: [
+      {
+        isGroup: true, annotation: paragraph, children: [
+          {isGroup: false, segments: [segments[0]]}
+        ]
+      },
+      {isGroup: false, segments: [segments[1]]},
+    ]
+  }
 ]);
 ```
 
+---
+
 More examples:
 
 - For edge cases, see: [segment.spec.ts](./src/segment.spec.ts).

package/dist/GetId.d.ts

@@ -0,0 +1 @@
+export type GetId<T> = (annotation: T) => string;

package/dist/GetOffsets.d.ts

@@ -0,0 +1,2 @@
+import { Offsets } from './Model.ts';
+export type GetOffsets<T> = (annotation: T) => Offsets;

package/dist/Model.d.ts

@@ -1,18 +1,16 @@
 /**
- * Input: object linking annotation to the text using character offsets.
+ * Start and end character, end excluding last character
  */
-export type AnnotationOffsets<T = unknown> = {
+export type Offsets = {
     begin: number;
     end: number;
-    body: T;
 };
 /**
- * Output: segment of text and the annotations that apply.
+ * Output: start and end offsets of text segment (excluding last character), plus 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/findSegmentOffsets.d.ts

@@ -0,0 +1,13 @@
+import { TextSegment } from './Model';
+export type SegmentOffsets = {
+    beginSegment: 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 findSegmentOffsets<T>(segments: TextSegment<T>[]): Map<T, SegmentOffsets>;

package/dist/groupSegments.d.ts

@@ -1,10 +1,23 @@
-import { TextSegment } from './Model.ts';
+import { TextSegment } from './Model';
+import { GetId } from './GetId.ts';
+export type SegmentGroup<T> = Group<T> | Ungrouped<T>;
 export type Group<T> = {
+    isGroup: true;
     annotation: T;
+    children: SegmentGroup<T>[];
+};
+export type Ungrouped<T> = {
+    isGroup: false;
     segments: TextSegment<T>[];
 };
 /**
- * Group segments into higher-level units (e.g. words, sentences, entities)
- * by grouping all segments that share a matching annotation.
+ * Recursively group a list of segments into higher-level units (e.g. words,
+ * paragraphs or divs) by segments that share a matching annotation.
+ *
+ * Example: text "aabb" with section (0–4) and paragraph (0–2) produces:
+ * [group(section): [group(paragraph("aa")), ungrouped("bb")]]
+ *
+ * Note: annotations are assumed to be ordered by nesting depth
+ * in each segment's annotations array, outer-first.
  */
-export declare function groupSegments<T>(segments: TextSegment<T>[], predicate: (annotation: T) => boolean): Group<T>[];
+export declare function groupSegments<T>(segments: TextSegment<T>[], isGroup: (annotation: T) => boolean, getId: GetId<T>): SegmentGroup<T>[];

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { segment } from './segment.ts';
 export type { AnnotationSegmentsByChar } from './segment.ts';
+export { findSegmentOffsets } from './findSegmentOffsets.ts';
+export type { SegmentOffsets } from './findSegmentOffsets.ts';
 export { groupSegments } from './groupSegments.ts';
-export type { Group } from './groupSegments.ts';
-export type { AnnotationOffsets, TextSegment, SegmentId, } from './Model.ts';
+export type { Group, SegmentGroup } from './groupSegments.ts';
+export type { Offsets, TextSegment, SegmentIndex, } from './Model.ts';
+export type { GetOffsets } from './GetOffsets.ts';

package/dist/index.js

@@ -1,21 +1,17 @@
-function segment(text, annotations) {
+function segment(text, annotations, getOffsets) {
   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 offsets = getOffsets(annotation), isMarker = offsets.begin === offsets.end;
+    if (isMarker && (offsets.end < 0 || offsets.begin > text.length) || !isMarker && (offsets.end <= 0 || offsets.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, offsets.begin), end = Math.min(text.length, offsets.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,37 +32,73 @@ 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 groupSegments(segments, predicate) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const segment2 of segments) {
-    const match = segment2.annotations.find(predicate);
-    if (match) {
-      let list = groups.get(match);
-      list || (list = [], groups.set(match, list)), list.push(segment2);
+function findSegmentOffsets(segments) {
+  const offsets = /* @__PURE__ */ new Map();
+  for (let i = 0; i < segments.length; i++)
+    for (const annotation of segments[i].annotations) {
+      const existing = offsets.get(annotation);
+      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { beginSegment: i, endSegment: i + 1 });
     }
+  return offsets;
+}
+function groupSegments(segments, isGroup, getId) {
+  return group(segments, isGroup, getId, 0);
+}
+function group(segments, isGroup, getId, depth) {
+  return groupByAnnotation(segments, isGroup, getId, depth).map(
+    (group2) => group2.annotation ? createGroup(group2.annotation, group2.segments, isGroup, getId, depth) : createUngrouped(group2.segments)
+  );
+}
+function groupByAnnotation(segments, isGroup, getId, depth) {
+  const groups = [];
+  let currentId, currentGroup;
+  for (const segment2 of segments) {
+    const annotation = getGroupAnnotation(segment2, isGroup, depth), id = annotation ? getId(annotation) : void 0;
+    !currentGroup || id !== currentId ? (currentGroup = annotation ? { annotation, segments: [segment2] } : { segments: [segment2] }, groups.push(currentGroup), currentId = id) : currentGroup.segments.push(segment2);
   }
-  return [...groups.entries()].map(([annotation, segments2]) => ({
+  return groups;
+}
+function getGroupAnnotation(segment2, isGroup, depth) {
+  let groupIndex = 0;
+  for (const annotation of segment2.annotations)
+    if (isGroup(annotation)) {
+      if (groupIndex === depth)
+        return annotation;
+      groupIndex++;
+    }
+}
+function createGroup(annotation, segments, isGroup, getId, depth) {
+  return {
+    isGroup: !0,
     annotation,
-    segments: segments2
-  }));
+    children: group(segments, isGroup, getId, depth + 1)
+  };
+}
+function createUngrouped(segments) {
+  return {
+    isGroup: !1,
+    segments
+  };
 }
 export {
+  findSegmentOffsets,
   groupSegments,
   segment
 };

package/dist/segment.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knaw-huc/text-annotation-segmenter",
-  "version": "0.1.1",
+  "version": "0.3.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>