npm package: @mapwhit/rtl-text
Description: Support for RTL languages for @maphit/tilerenderer.
Author: Mapbox
Latest version: 0.1.0

[![NPM version][npm-image]][npm-url]
[![Build Status][build-image]][build-url]

# @mapwhit/rtl-text

This is a fork if [mapbox-gl-rtl-text]

An [Emscripten] port of a subset of the functionality of [International Components for Unicode (ICU)][ICU] necessary for [tilerenderer] to support right to left text rendering. Supports the Arabic and Hebrew languages, which are written right-to-left.

## Using @mapwhit/rtl-text

```js
import rtlText from '@mapwhit/rtl-text';
const {applyArabicShaping, processBidirectionalText} = await rtlText();

const arabicString = "سلام";
const shapedArabicText = applyArabicShaping(arabicString);
const readyForDisplay = processBidirectionalText(shapedArabicText, []);
```

The default location of the compiled wasm file is the same folder as the javascript. If different it can be provided as a parameter to `rtlText`.

```js
// in browser
const {applyArabicShaping, processBidirectionalText} = await rtlText('https://example.com/rtl/icu-123.wasm');

// in node
const {applyArabicShaping, processBidirectionalText} = await rtlText('/lib/rtl/icu-123.wasm');
```

@mapwhit/rtl-text exposes following functions:

### `applyArabicShaping(unicodeInput)`

Takes an input string in "logical order" (i.e. characters in the order they are typed, not the order they will be displayed) and replaces Arabic characters with the "presentation form" of the character that represents the appropriate glyph based on the character's location within a word.

### `processBidirectionalText(unicodeInput, lineBreakPoints)`

Takes an input string with characters in "logical order", along with a set of chosen line break points, and applies the [Unicode Bidirectional Algorithm] to the string. Returns an ordered set of lines with characters in "visual order" (i.e. characters in the order they are displayed, left-to-right). The algorithm will insert mandatory line breaks (`\n` etc.) if they are not already included in `lineBreakPoints`.

### `processStyledBidirectionalText(unicodeInput, styleIndices, lineBreakPoints)`

Takes an input string in logical order and applies the BiDi algorithm using the chosen line break points to generate a set of lines with the characters re-arranged into visual order.

Also takes an array of "style indices" that specify different styling on the input characters (the styles are represented as integers here, the caller is responsible for the actual implementation of styling). BiDi can both reorder and add/remove characters from the input string, but this function copies style information from the "source" logical characters to their corresponding visual characters in the output.

[tilerenderer]: https://npmjs.org/package/@mapwhit/tilerenderer
[mapbox-gl-rtl-text]: https://npmjs.org/package/@mapbox/mapbox-gl-rtl-text
[Emscripten]: https://github.com/emscripten-core/emscripten
[ICU]: http://site.icu-project.org/
[Unicode Bidirectional Algorithm]: http://unicode.org/reports/tr9/

[npm-image]: https://img.shields.io/npm/v/@mapwhit/rtl-text
[npm-url]: https://npmjs.org/package/@mapwhit/rtl-text

[build-url]: https://github.com/mapwhit/rtl-text/actions/workflows/check.yaml
[build-image]: https://img.shields.io/github/actions/workflow/status/mapwhit/rtl-text/check.yaml?branch=main