text-to-svg-hb/README.md

Convert text to SVG paths with HarfBuzz support for complex text shaping

# text-to-svg-hb

A Node.js library that converts text to SVG paths using HarfBuzz for complex text shaping. This library is particularly useful for handling complex scripts like Arabic, Devanagari, and other writing systems that require proper text shaping.

## Features

- Complex text shaping using HarfBuzz
- Support for multiple writing systems and scripts
- Proper handling of bidirectional text (RTL/LTR)
- Text alignment options
- Line wrapping with max width
- Customizable font size and color
- Option to combine paths into a single path or keep them separate
- SVG optimization using SVGO

## Installation

```bash
npm install text-to-svg-hb
```

## Usage

```typescript
import { textToSVG } from 'text-to-svg-hb';

// Example with separate paths (default)
const result = await textToSVG('مرحبا بالعالم', {
  fontPath: './fonts/NotoNaskhArabic-Regular.ttf',
  fontSize: 72,
  direction: 'rtl',
  script: 'arab',
  language: 'ar',
  color: '#000000',
  combinePaths: false // Get multi-path SVG with separate paths for each glyph
});

// Example with combined paths
const result2 = await textToSVG('Hello World', {
  fontPath: './fonts/NotoSans-Regular.ttf',
  fontSize: 72,
  color: '#000000',
  combinePaths: true // Get single-path SVG with all glyphs merged
});

console.log(result.svg); // SVG string
console.log(result.canvasWidth, result.canvasHeight); // Canvas dimensions
```

## API

### textToSVG(text: string, options: TextToSVGOptions): Promise<SVGResult>

#### Options

- `fontPath` (required): Path to the font file
- `fontSize` (required): Font size in pixels
- `lineHeight` (optional): Line height multiplier (default: 1.2)
- `maxWidth` (optional): Maximum width for text wrapping
- `textAlign` (optional): Text alignment ('left' | 'center' | 'right')
- `color` (optional): Text color (default: '#000000')
- `direction` (optional): Text direction ('ltr' | 'rtl')
- `script` (optional): ISO 15924 script code (default: 'latn')
- `language` (optional): BCP 47 language tag (default: 'en')
- `combinePaths` (optional): Whether to combine all paths into one (default: false)

#### Return Value

```typescript
interface SVGResult {
  canvasWidth: number;  // Width of the SVG canvas
  canvasHeight: number; // Height of the SVG canvas
  svg: string;         // SVG string (either multi-path or single-path based on combinePaths)
}
```

## Examples

### Arabic Text with Separate Paths

```typescript
const result = await textToSVG('مرحبا بالعالم', {
  fontPath: './fonts/NotoNaskhArabic-Regular.ttf',
  fontSize: 72,
  direction: 'rtl',
  script: 'arab',
  language: 'ar',
  color: '#000000',
  combinePaths: false
});
```

This will generate an SVG with separate paths for each glyph, which is useful when you need to:
- Animate individual characters
- Apply different styles to different parts of the text
- Need more control over the individual glyphs

### Latin Text with Combined Paths

```typescript
const result = await textToSVG('Hello World', {
  fontPath: './fonts/NotoSans-Regular.ttf',
  fontSize: 72,
  color: '#000000',
  combinePaths: true
});
```

This will generate an SVG with a single path containing all glyphs, which is useful when you need to:
- Reduce file size
- Apply a single style to the entire text
- Need simpler SVG structure

## Requirements

- Node.js 14 or higher
- A font file that supports the script you want to use

## License

MIT