@qumra/arabic-canvas

Render Arabic text correctly (shaping + letter joining + RTL) onto a canvas, ready to print as an image.

Part of the @qumra suite — and Qumra's competitive edge. Thermal printers cannot reliably print Arabic as text, so the only dependable approach is to render it as an image. This package does exactly that, leaning on the browser's text-shaping engine (Canvas 2D) which joins letters and handles direction automatically.

Features

• 🅰️ Correct Arabic — shaping, letter joining, and RTL handled by the browser engine.
• 🧾 Two entry points: renderArabic (free text) and renderReceipt (full layout).
• ↩️ Automatic word wrapping for lines wider than the paper.
• 📐 Height auto-rounded to a multiple of 8 (an ESC/POS requirement).
• 🧩 Low-level canvas helpers exported for building custom layouts.

Installation

npm install @qumra/arabic-canvas

Quick start

import { renderArabic, renderReceipt } from '@qumra/arabic-canvas';
import { QumraReceiptEncoder } from '@qumra/receipt-encoder';

// A single line (defaults to 58mm / 384 dots — pass width: 576 for 80mm)
const canvas = renderArabic('مرحباً بكم في قمرة');

// Or a full receipt layout
const receipt = renderReceipt({
  storeName: 'متجر قمرة',
  items: [{ name: 'قهوة', price: '15.00' }],
  total: '15.00',
  footer: 'شكراً لزيارتكم',
});

const data = new QumraReceiptEncoder().initialize().image(receipt).cut().encode();

API

renderArabic(text, options?) → HTMLCanvasElement

Renders text (one or more lines separated by \n).

| Option | Default | Description | |---|---|---| | width | 384 | Image width in dots (58mm; use 576 for 80mm). | | fontSize | 28 | Font size in pixels. | | fontFamily | 'sans-serif' | Font family. | | align | 'right' | 'right' \| 'center' \| 'left'. | | padding | 16 | Side padding in pixels. | | wrap | true | Wrap lines wider than the image. |

renderReceipt(content, options?) → HTMLCanvasElement

Renders a full receipt layout (header, items with prices, total, footer).

content: {
  storeName?: string; address?: string; date?: string;
  items?: { name: string; price: string | number }[];
  total?: string | number; footer?: string;
}
options?: { width?: number; fontFamily?: string; padding?: number; wrap?: boolean }

width defaults to 384 (58mm). The image height is rounded up to a multiple of 8.

Low-level helpers

| Export | Description | |---|---| | createCanvas(width, height) | Canvas with height rounded to a multiple of 8. | | ctxOf(canvas) | A 2D context configured for top-baseline drawing. | | prepareSurface(ctx, w, h) | White background + black ink. | | createMeasureContext() | A 1×1 context for measuring text width. | | wrapLine · wrapLines | Pure, testable word-wrap utilities. |

Requirements

• Requires a browser environment (Canvas 2D) — available in the browser and the Electron renderer.
• Node support (server-side rendering via node-canvas) is on the roadmap.

Related packages

• @qumra/receipt-encoder — consumes this package's canvas via image().
• @qumra/pos — the all-in-one facade.

License

MIT © Qumra