Treedown-aligner NPM

TreedownAligner

TreedownAligner is a react component library. Its components enable users to view and modify alignments between texts with the aid source language syntax via Treedown.

View Demo.

TreedownAligner is a react component written in Typesript using Redux for state management. Included is a <Workbench /> component that wraps TreedownAligner for local development and testing.

Consuming Application Quickstart

Install: npm install treedown-aligner
Import: import TreedownAligner from 'treedown-aligner';
Render: () => { return <TreedownAligner /> } (see below for proper usage)

Note: expected peer dependencies

The following peer dependencies are required:

react
react-dom

The component currently supports react v18.x.

Local development Quickstart

Install dependencies: yarn
Run local server: yarn start (starts local CRA server with component wrapper in a UI workbench)
Build: yarn build

Basic Usage

After install, import the react component:

import TreedownEditor from 'treedown-aligner';

In your render function, include the component with some props:

<TreedownEditor
  theme="day"
  corpora={[<...>]}
  alignments={[<...>]}
  alignmentUpdated={(newAlignmentData) => {
    // persist alignment data here
  }}
/>

Properties and Options

`theme`

string: 'day' | 'night'

specifies which css theme is used.

`localizationCode`

string

NOT YET IMPLEMENTED

The consuming application can provide a localizationCode that component will conform internationalized UI elements to. The ISO 639-3 is expected. Supported languages are:

English (eng)
something else here...
something else here...

`corpora`

Corpus[]

Corpora is the plural form of corpus. A corpus is one body of text that the user will interact with when using this component. Up to 4 corpus entities can be supplied.

A Corpus looks like:

interface Corpus {
  id: string;
  name: string;
  fullName: string;
  language: string;

  words: Word[];
  fullText?: string;
  viewType?: CorpusViewType;
  syntax?: SyntaxRoot;
}

id: string unique identifier for the corpus
name: string short name, like NIV
fullName long name, like New International Version
language language code via ISO 639-3
words: Word[] object representing a word in the corpus. See Word below.
fullText?: string optional - full unsegmented text of the corpus
syntax?: SyntaxRoot optional - syntactic parsing of the corpus. See SyntaxRoot below.

`Word`

Word is an object representing a word in a corpus. In English, words are surrounded by whitespace, but in other languages not neccesarily.

A Word looks like:

export interface Word {
  id: string;
  corpusId: string;

  text: string;
  position: number;
}

id: string unique indetifier. used to correlate with Alignment data
corpusId: string unique identifier of the corpus the words belongs to
text: string content of the word
position: number sequential position of the word in the corpus

`SyntaxRoot`

In some use cases, one of the supplied corpora can have syntax data. In this case, "Syntax data" is a tree-like structure denoting words, word groups, and their relationships to other. The component current supports a json representation of Lowfat Syntax XML.

Note: The component could recieve lowfat xml in string form and then internally convert to json structure. This may be preferable.

`alignments`

Alignment[]

An Alignment is a set of data the describes the relationship between two corpora. The component enables users to view and modify alignment data. It also uses alignment data to generate syntactic views in treedown notation.

interface Alignment {
  source: string;
  target: string;
  polarity: AlignmentPolarity;
  links: Link[];
}

source: string id of the source corpus
target: string id of the target corpus
polarity: AlignmentPolarity describes the directionality of the alignment see AlignmentPolarity below.
links: Link[] relationship entities between the two corpora. see Links

`AlignmentPolarity`

An AlignmentPolarity describes the "sides" of an alignment and their attributes. Each alignment dataset much be specified with either a PrimaryAlignmentPolarity or a SecondaryAlignmentPolarity.

interface PrimaryAlignmentPolarity {
  type: 'primary';
  syntaxSide: 'sources' | 'targets';
  nonSyntaxSide: 'sources' | 'targets';
}

type: 'primary'
syntaxSide: 'sources' | 'targets'
nonSyntaxSide: 'sources' | 'targets'

interface SecondaryAlignmentPolarity {
  type: 'secondary';
  mappedSide: 'sources' | 'targets';
  nonMappedSide: 'sources' | 'targets';
}

type: 'secondary'
mappedSide: 'sources' | 'targets'
nonMappedSide: 'sources' | 'targets'

Links

Link[]

A Link is a single instance of alignment data. It describes the relationship between the words of two corpora. The strings on either side of the link are IDs of words that were cpecified in the provided Corpus[]. There can be one or many words on either side of a Link.

export interface Link {
  _id?: string;
  sources: string[];
  targets: string[];
}

wip _id?: string unqiue indentifier for the link. probably should just generate internally
sources: string[] array of Word IDs on the source side of the link
targets: string[] array of Word IDs on the target side of the link

`alignmentUpdated`

This is function provided by the consuming application that is called when a user saves alignment data. At the time of invocation, the current alignment state is passed to the function which can be used to display, send, or persist the user's alignment data.