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

package/README.md

@@ -15,17 +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.
-- [`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).
+- [`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
@@ -34,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,9 +1,12 @@
+/**
+ * Start and end character, end excluding last character
+ */
 export type Offsets = {
     begin: number;
     end: number;
 };
 /**
- * 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> = Offsets & {
     index: SegmentIndex;

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,7 +1,8 @@
 export { segment } from './segment.ts';
 export type { AnnotationSegmentsByChar } from './segment.ts';
-export { mapAnnotationSegmentRanges } from './mapAnnotationSegmentRanges.ts';
-export type { SegmentRange } from './mapAnnotationSegmentRanges.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 { Group, SegmentGroup } from './groupSegments.ts';
 export type { Offsets, TextSegment, SegmentIndex, } from './Model.ts';
+export type { GetOffsets } from './GetOffsets.ts';

package/dist/index.js

@@ -1,4 +1,4 @@
-function segment(text, annotations) {
+function segment(text, annotations, getOffsets) {
   const segments = [];
   let segmentCounter = -1;
   const offsetMap = /* @__PURE__ */ new Map(), getOrCreateOffset = (charIndex) => {
@@ -7,10 +7,10 @@ function segment(text, annotations) {
   };
   getOrCreateOffset(0), getOrCreateOffset(text.length);
   for (const annotation of annotations) {
-    const isMarker = annotation.begin === annotation.end;
-    if (isMarker && (annotation.end < 0 || annotation.begin > text.length) || !isMarker && (annotation.end <= 0 || annotation.begin >= text.length))
+    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 begin = Math.max(0, annotation.begin), end = Math.min(text.length, annotation.end);
+    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(
@@ -49,31 +49,56 @@ function segment(text, annotations) {
   }
   return segments;
 }
-function mapAnnotationSegmentRanges(segments) {
-  const ranges = /* @__PURE__ */ new Map();
+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 = ranges.get(annotation);
-      existing ? existing.endSegment = i + 1 : ranges.set(annotation, { startSegment: i, endSegment: i + 1 });
+      const existing = offsets.get(annotation);
+      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { beginSegment: i, endSegment: i + 1 });
     }
-  return ranges;
+  return offsets;
 }
-function groupSegments(segments, predicate) {
-  const groups = /* @__PURE__ */ new Map();
+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 match = segment2.annotations.find(predicate);
-    if (match) {
-      let list = groups.get(match);
-      list || (list = [], groups.set(match, list)), list.push(segment2);
-    }
+    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,
-  mapAnnotationSegmentRanges,
   segment
 };

package/dist/segment.d.ts

@@ -1,9 +1,10 @@
-import { Offsets, 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 extends Offsets>(text: string, annotations: T[]): TextSegment<T>[];
-export type AnnotationSegmentsByChar<T extends Offsets = Offsets> = {
+export declare function segment<T>(text: string, annotations: T[], getOffsets: GetOffsets<T>): TextSegment<T>[];
+export type AnnotationSegmentsByChar<T> = {
     charIndex: number;
     starting: T[];
     ending: T[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knaw-huc/text-annotation-segmenter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knaw-huc/text-annotation-segmenter.git"

package/dist/mapAnnotationSegmentRanges.d.ts

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