@knaw-huc/text-annotation-segmenter 0.4.0 → 0.5.1

package/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2026 KNAW-HuC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,28 +1,41 @@
   # @knaw-huc/text-annotation-segmenter
 
-Utility functions to help render overlapping annotations in a text.
+[![npm version](https://img.shields.io/npm/v/@knaw-huc/text-annotation-segmenter.svg?color=green)](https://www.npmjs.com/package/@knaw-huc/text-annotation-segmenter)
+
+Utility functions to render annotations with character offsets 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.
+         text:  abc
+annotation ab:  __
+annotation bc:   __
 ```
  
-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?
+However, HTML is hierarchical. How to display annotations that do not live inside or next to each other, but that 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 or span across that position.
+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/jsx element. Elements linked to multiple overlapping annotations can now be decorated with their own styling, classes and callbacks:
+```html
+<span class="ab">a</span>
+<span class="ab bc">b</span>
+<span class="bc">c</span>
+```
 
 ## API
 
-- [`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.
+### Functions
+
+- [`segment<T>(text, annotations, getOffsets, getMarkerPosition?): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with character offsets to the text and a list of applying annotations.
 - [`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).
+- [`collectGroupSegments<T>(group): TextSegment<T>[]`](src/groupSegments.ts) <br /> Recursively collect all TextSegments from a Group.
 - [`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.
+
+### Types
+
+- [`SegmentGroup<T>`](src/groupSegments.ts) <br /> A `Group<T>` (with annotation and recursive children) or `Ungrouped<T>` (with plain segments).
 - [`SegmentOffsets`](src/findSegmentOffsets.ts) <br /> Start and end segment index of an annotation (excluding end segment).
+- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end offsets of text segment (excluding last character), plus the annotations that apply.
 
-## Example
+## Examples
 
 ### Create text segments
 
@@ -42,14 +55,17 @@ const ab = {id: 'ab', begin: 0, end: 2};
 const bc = {id: 'bc', begin: 1, end: 3};
 
 const getOffsets = annotation => annotation;
+
 const segments = segment(text, [ab, bc], getOffsets);
 
 expect(segments).toEqual([
   {index: 0, begin: 0, end: 1, body: 'a', annotations: [ab]},
-  {index: 1, begin: 1, end: 2, body: 'ab', annotations: [ab, bc]},
+  {index: 1, begin: 1, end: 2, body: 'b', annotations: [ab, bc]},
   {index: 2, begin: 2, end: 3, body: 'c', annotations: [bc]},
 ]);
 ```
+- More examples: [segment.spec.ts](./src/segment.spec.ts).
+- Benchmarks: [segment.bench.ts](./src/segment.bench.ts).
 
 ### Group segments
 
@@ -58,9 +74,9 @@ 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:  __
+     text:  aabb
+  section:  ____
+paragraph:  __
 ```
 
 ```ts
@@ -81,24 +97,55 @@ const groups = groupSegments(
   isGroup,
   getId,
 );
+const aaSegment = segments[0];
+const bbSegment = segments[1];
 
 expect(groups).toEqual([
-  {
-    isGroup: true, annotation: section, children: [
-      {
-        isGroup: true, annotation: paragraph, children: [
-          {isGroup: false, segments: [segments[0]]}
-        ]
-      },
-      {isGroup: false, segments: [segments[1]]},
-    ]
-  }
+  {annotation: section, isGroup: true, children: [
+    {annotation: paragraph, isGroup: true, children: [
+        {segments: [aaSegment], isGroup: false}
+    ]},
+    {segments: [bbSegment], isGroup: false},
+  ]}
 ]);
 ```
+- More examples: [groupSegments.spec.ts](./src/groupSegments.spec.ts).
+- Benchmarks: [groupSegments.bench.ts](./src/groupSegments.bench.ts).
 
----
 
-More examples:
+### Markers
 
-- For edge cases, see: [segment.spec.ts](./src/segment.spec.ts).
-- For benchmarks, see [segment.bench.ts](./src/segment.bench.ts).
+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 annotations that cover, start or end at that position:
+
+```text
+text with marker:  a‸b
+annotation a:      _
+annotation b:        _
+```
+
+```ts
+const text = 'ab';
+const marker: Annotation = {begin: 1, end: 1, id: 'm'};
+const a: Annotation = {begin: 0, end: 1, id: 'a'};
+const b: Annotation = {begin: 1, end: 2, id: 'b'};
+
+const segments = segment(text, [marker, a, b], getOffsets);
+const markerSegment = segments[1];
+expect(markerSegment).toEqual(
+  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, a]},
+);
+```
+Notice how the marker is 'postfixed' to the previous annotation. When the marker shares its character index with the start and end offsets of annotations, by default the marker segment will only include the annotations that end at that offset (e.g: a note at the end of a paragraph).
+
+However, markers can also be prefixed to annotations that share their start offset with the marker, using the `getMarkerPosition` parameter of the `segment` function:
+
+```ts
+const getMarkerPosition = a => a.id === 'm' ? 'prefix' : 'postfix'
+const segments = segment(text, [marker, a, b], getOffsets, getMarkerPosition);
+
+const markerSegment = segments[1];
+expect(markerSegment).toEqual(
+  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, b]},
+);
+```
+More examples: [segment.spec.ts](./src/segment.spec.ts#L118).

package/dist/collectGroupSegments.d.ts

@@ -0,0 +1,6 @@
+import { TextSegment } from './Model.ts';
+import { Group } from './groupSegments.ts';
+/**
+ * Recursively collect all {@link TextSegment}s from a {@link Group}
+ */
+export declare function collectGroupSegments<T>(group: Group<T>): TextSegment<T>[];

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { AnnotationSegmentsByChar } from './segment.ts';
 export { findSegmentOffsets } from './findSegmentOffsets.ts';
 export type { SegmentOffsets } from './findSegmentOffsets.ts';
 export { groupSegments } from './groupSegments.ts';
+export { collectGroupSegments } from './collectGroupSegments.ts';
 export type { Group, SegmentGroup } from './groupSegments.ts';
 export type { Offsets, TextSegment, SegmentIndex, MarkerPosition, } from './Model.ts';
 export type { GetOffsets } from './GetOffsets.ts';

package/dist/index.js

@@ -95,7 +95,13 @@ function createUngrouped(segments) {
     segments
   };
 }
+function collectGroupSegments(group2) {
+  return group2.children.flatMap(
+    (child) => child.isGroup ? collectGroupSegments(child) : child.segments
+  );
+}
 export {
+  collectGroupSegments,
   findSegmentOffsets,
   groupSegments,
   segment

package/dist/segment.d.ts

@@ -3,6 +3,24 @@ import { GetOffsets } from './GetOffsets.ts';
 import { GetMarkerPosition } from './GetMarkerPosition.ts';
 /**
  * Split a text into {@link TextSegment}s with character offsets and a list of applying annotations.
+ *
+ * @param text Text to split into segments
+ *
+ * @param annotations Annotations linked to text using character offsets
+ *
+ * @param getOffsets Find the character begin and end index of an annotation
+ *
+ * @param getMarkerPosition Should a marker segment be prefixed or postfixed?
+ * - 'prefix': include annotations that start at marker offset
+ * - 'postfix': include annotations that end at marker offset
+ *
+ * For example, consider two paragraphs: <p1>aa</p1><marker/><p2>bb</p2>
+ * The annotation <marker/> shares the end character index with annotation <p1>,
+ * and the begin character index with annotation <p2>:
+ * - with 'postfix': segment (2,2) will contain annotations [marker, p1]
+ * - with 'prefix': segment (2,2) will contain annotations [marker, p2]
+ *
+ * By default, markers are postfixed.
  */
 export declare function segment<T>(text: string, annotations: T[], getOffsets: GetOffsets<T>, getMarkerPosition?: GetMarkerPosition<T>): TextSegment<T>[];
 export type AnnotationSegmentsByChar<T> = {

package/package.json

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