@knaw-huc/text-annotation-segmenter 0.1.0

package/README.html

@@ -0,0 +1,41 @@
+<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>

package/README.md

@@ -0,0 +1,56 @@
+  # @knaw-huc/text-annotation-segmenter
+
+Utility functions to help render overlapping annotations in a text.
+
+Annotations on a text have a non-hierarchical nature, i.e., they can overlap:
+```text
+Aa<bc>bb<cd>cc</bc>dd<cd>ee.
+```
+ 
+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?
+
+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.
+
+## 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.
+
+## Example
+
+Given the text `"abc"` with two overlapping annotations:
+
+```txt
+         text:  abc
+annotation ab:  __
+annotation bc:   __
+```
+
+```ts
+import { segment } from "text-annotation-segmenter";
+
+const text = 'abc';
+const ab = {id: 'ab'};
+const bc = {id: 'bc'};
+
+const segments = segment(text, [
+  {begin: 0, end: 2, body: ab},
+  {begin: 1, end: 3, body: bc},
+]);
+
+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]},
+]);
+```
+
+More examples:
+
+- For edge cases, see: [segment.spec.ts](./src/segment.spec.ts).
+- For benchmarks, see [segment.bench.ts](./src/segment.bench.ts).

package/dist/Model.d.ts

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

package/dist/groupSegments.d.ts

@@ -0,0 +1,10 @@
+import { TextSegment } from './Model.ts';
+export type Group<T> = {
+    annotation: T;
+    segments: TextSegment<T>[];
+};
+/**
+ * Group segments into higher-level units (e.g. words, sentences, entities)
+ * by grouping all segments that share a matching annotation.
+ */
+export declare function groupSegments<T>(segments: TextSegment<T>[], predicate: (annotation: T) => boolean): Group<T>[];

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,71 @@
+function segment(text, annotations) {
+  const segments = [];
+  let segmentCounter = 0;
+  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)
+      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 sortedOffsets = [...offsetMap.values()].sort(
+    (a, b) => a.charIndex - b.charIndex
+  ), activeAnnotations = /* @__PURE__ */ new Set();
+  let lastOffset = 0;
+  for (const offset of sortedOffsets) {
+    if (offset.charIndex > lastOffset) {
+      const id = `${segmentCounter++}`;
+      segments.push({
+        id,
+        begin: lastOffset,
+        end: offset.charIndex,
+        annotations: [...activeAnnotations]
+      });
+    }
+    lastOffset = offset.charIndex;
+    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);
+    if (hasMarkers) {
+      markerSegmentAnnotations.push(...activeAnnotations);
+      const segment2 = `${segmentCounter++}`;
+      segments.push({
+        id: segment2,
+        begin: offset.charIndex,
+        end: offset.charIndex,
+        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);
+    }
+  }
+  return [...groups.entries()].map(([annotation, segments2]) => ({
+    annotation,
+    segments: segments2
+  }));
+}
+export {
+  groupSegments,
+  segment
+};

package/dist/orThrow.d.ts

@@ -0,0 +1 @@
+export declare function orThrow(msg: string): never;

package/dist/segment.d.ts

@@ -0,0 +1,10 @@
+import { AnnotationSegment, 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> = {
+    charIndex: number;
+    starting: AnnotationSegment<T>[];
+    ending: AnnotationSegment<T>[];
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@knaw-huc/text-annotation-segmenter",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/knaw-huc/text-annotation-segmenter.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev:build": "vite build --watch",
+    "build": "vite build",
+    "test": "vitest run",
+    "bench": "vitest bench",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.2",
+    "vite": "^7.0.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.16"
+  }
+}