react-pdf-rtl 0.1.1

package/README.md

@@ -0,0 +1,234 @@
+# react-pdf-rtl
+
+> RTL (Hebrew & Arabic) support for [`@react-pdf/renderer`](https://react-pdf.org/)
+
+`@react-pdf/renderer` is a fantastic library — but Hebrew and Arabic text rendering is broken out of the box. Mixed content like `"חפירה וביסוס - 3 מ״ק"` renders reversed. Currency `₪1,500` gets scrambled. Tables need `row-reverse` everywhere. Font setup is undocumented.
+
+This library fixes all of that.
+
+---
+
+## Installation
+
+```bash
+npm install react-pdf-rtl
+# peer dependencies
+npm install @react-pdf/renderer react
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { Document, Page } from "@react-pdf/renderer";
+import {
+  setupHebrewPDF,
+  RTLText,
+  RTLTable,
+  RTLSummaryRow,
+  RTLDivider,
+  getRTLPageStyle,
+} from "react-pdf-rtl";
+
+// Register Rubik font + disable hyphenation — call once at module level
+setupHebrewPDF();
+
+const pageStyle = getRTLPageStyle("Rubik");
+
+export function QuotePDF({ items, total }) {
+  return (
+    <Document>
+      <Page size="A4" style={pageStyle}>
+        <RTLText style={{ fontSize: 20, fontWeight: "bold" }}>
+          הצעת מחיר
+        </RTLText>
+
+        <RTLDivider marginVertical={12} />
+
+        <RTLTable
+          columns={[
+            { header: "תיאור עבודה", key: "description", flex: 3 },
+            { header: "כמות", key: "quantity", flex: 1, align: "center" },
+            { header: "יחידה", key: "unit", flex: 1, align: "center" },
+            { header: "מחיר יחידה", key: "unitPrice", flex: 1, isCurrency: true },
+            { header: 'סה"כ', key: "total", flex: 1, isCurrency: true },
+          ]}
+          data={items}
+          headerBg="#1F2937"
+          headerColor="#EAB308"
+        />
+
+        <RTLDivider marginVertical={8} />
+
+        <RTLSummaryRow label='סה"כ לפני מע"מ' value={total} isCurrency />
+        <RTLSummaryRow label='מע"מ 18%' value={total * 0.18} isCurrency />
+        <RTLSummaryRow
+          label="סכום סופי לתשלום"
+          value={total * 1.18}
+          isCurrency
+          bold
+        />
+      </Page>
+    </Document>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### Font Setup
+
+#### `setupHebrewPDF(fontFamily?)`
+One-shot setup. Registers font + disables hyphenation. Call once at module level.
+```ts
+setupHebrewPDF();           // defaults to "Rubik"
+setupHebrewPDF("NotoSansHebrew");
+```
+
+#### `registerRubik()`
+Registers Rubik (weights 300, 400, 500, 700) from Google Fonts CDN.
+
+#### `registerNotoSansHebrew()`
+Registers Noto Sans Hebrew from Google Fonts CDN.
+
+#### `registerRTLFont(options)`
+Register any custom font:
+```ts
+registerRTLFont({
+  family: "MyFont",
+  fonts: [
+    { src: "/fonts/MyFont-Regular.ttf", fontWeight: "normal" },
+    { src: "/fonts/MyFont-Bold.ttf", fontWeight: "bold" },
+  ],
+});
+```
+
+#### `disableHyphenation()`
+Prevents Hebrew words from being split mid-word. Called automatically by `setupHebrewPDF`.
+
+---
+
+### Components
+
+#### `<RTLText>`
+Drop-in replacement for `<Text>` with automatic RTL detection and bidi wrapping.
+
+```tsx
+<RTLText style={{ fontSize: 14 }}>חפירה וביסוס - 3 מ"ק</RTLText>
+<RTLText direction="rtl">כותרת</RTLText>
+<RTLText direction="ltr">English text</RTLText>
+<RTLText direction="auto">auto-detected</RTLText>  {/* default */}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `string \| number` | — | Text content |
+| `style` | `Style` | — | react-pdf style |
+| `direction` | `"rtl" \| "ltr" \| "auto"` | `"auto"` | Force or auto-detect direction |
+| `wrap` | `boolean` | `true` | Allow text wrapping |
+
+#### `<RTLView>`
+A `<View>` pre-set with `flexDirection: "row-reverse"` and `textAlign: "right"`.
+
+```tsx
+<RTLView style={{ gap: 8 }}>
+  <RTLText>תיאור</RTLText>
+  <Text>₪1,200</Text>
+</RTLView>
+```
+
+#### `<RTLTable>`
+Full RTL-aware table. Columns rendered right-to-left. Hebrew cells auto-wrapped.
+
+```tsx
+<RTLTable
+  columns={[
+    { header: "תיאור", key: "description", flex: 3 },
+    { header: "כמות", key: "qty", flex: 1, align: "center" },
+    { header: "מחיר", key: "price", flex: 1, isCurrency: true },
+  ]}
+  data={rows}
+  headerBg="#1F2937"
+  headerColor="#FFFFFF"
+  stripeBg="#F9FAFB"
+/>
+```
+
+| Column Prop | Type | Description |
+|------------|------|-------------|
+| `header` | `string` | Column header (auto RTL-wrapped) |
+| `key` | `string` | Row data key |
+| `flex` | `number` | Relative width |
+| `width` | `number` | Fixed width in pts |
+| `align` | `"right" \| "left" \| "center"` | Cell text alignment |
+| `isCurrency` | `boolean` | Formats as `₪1,500` |
+| `render` | `(value, row) => string` | Custom cell renderer |
+
+#### `<RTLSummaryRow>`
+Label + value row for totals, right-aligned label, left-aligned value.
+
+```tsx
+<RTLSummaryRow label='סה"כ' value={12500} isCurrency bold />
+```
+
+#### `<RTLDivider>`
+Simple horizontal rule.
+```tsx
+<RTLDivider color="#E5E7EB" thickness={1} marginVertical={8} />
+```
+
+#### `getRTLPageStyle(fontFamily?)`
+Returns a base `Style` object for RTL pages.
+```ts
+const style = getRTLPageStyle("Rubik");
+// { fontFamily: "Rubik", direction: "rtl", textAlign: "right", padding: ... }
+```
+
+---
+
+### Utilities
+
+#### `hasRTLChars(str)`
+Returns `true` if string contains any Hebrew/Arabic characters.
+
+#### `isRTLDominant(str)`
+Returns `true` if the majority of alphabetic characters are RTL.
+
+#### `wrapRTL(str)` / `wrapLTR(str)`
+Manually wrap text in Unicode bidi markers (`\u202B...\u202C`).
+
+#### `smartWrap(str)`
+Auto-detect direction and wrap accordingly. Pure numbers are left unchanged.
+
+#### `formatCurrencyRTL(amount, symbol?, locale?)`
+Format a number as currency, ensuring `₪` and digits render correctly in RTL context.
+```ts
+formatCurrencyRTL(1500)           // ₪1,500 (correct RTL direction)
+formatCurrencyRTL(1500, "$", "en-US") // $1,500
+```
+
+#### `splitBidiSegments(str)`
+Split mixed text into RTL/LTR/neutral segments:
+```ts
+splitBidiSegments("שלום world 123")
+// [
+//   { text: "שלום ", direction: "rtl" },
+//   { text: "world ", direction: "ltr" },
+//   { text: "123", direction: "neutral" },
+// ]
+```
+
+---
+
+## Why This Exists
+
+The [`diegomura/react-pdf`](https://github.com/diegomura/react-pdf) issue tracker has RTL/Hebrew bug reports dating back to 2019 ([#732](https://github.com/diegomura/react-pdf/issues/732), [#1571](https://github.com/diegomura/react-pdf/issues/1571), [#3010](https://github.com/diegomura/react-pdf/issues/3010)) with no official fix. This library provides a battle-tested layer on top.
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,259 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { Style } from '@react-pdf/types';
+
+interface RTLTextProps {
+    children: string | number;
+    style?: Style | Style[];
+    /** Force direction instead of auto-detecting */
+    direction?: "rtl" | "ltr" | "auto";
+    wrap?: boolean;
+    debug?: boolean;
+}
+/**
+ * Drop-in replacement for @react-pdf/renderer's <Text> with RTL support.
+ *
+ * Automatically:
+ * - Detects Hebrew/Arabic content and applies RLE bidi markers
+ * - Handles mixed content (Hebrew text + numbers) correctly
+ * - Preserves LTR content unchanged
+ *
+ * @example
+ * <RTLText style={{ fontSize: 14 }}>חפירה וביסוס - 3 מ"ק</RTLText>
+ * <RTLText>Item description in English</RTLText>
+ */
+declare function RTLText({ children, style, direction, wrap, debug }: RTLTextProps): react_jsx_runtime.JSX.Element;
+interface RTLViewProps {
+    children: React.ReactNode;
+    style?: Style | Style[];
+    debug?: boolean;
+}
+/**
+ * A <View> pre-configured for RTL layout.
+ * Sets flexDirection to "row-reverse" and textAlign to "right".
+ * Use as a wrapper for rows in RTL documents.
+ *
+ * @example
+ * <RTLView style={{ marginBottom: 8 }}>
+ *   <RTLText>תיאור עבודה</RTLText>
+ *   <Text>₪1,200</Text>
+ * </RTLView>
+ */
+declare function RTLView({ children, style, debug }: RTLViewProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns base styles for an RTL page layout.
+ * Pass your fontFamily to get consistent defaults.
+ *
+ * @example
+ * const pageStyle = getRTLPageStyle("Rubik");
+ */
+declare function getRTLPageStyle(fontFamily?: string): Style;
+interface RTLTableColumn {
+    /** Column header label */
+    header: string;
+    /** Key in the data row object */
+    key: string;
+    /** Flex width (like CSS flex) */
+    flex?: number;
+    /** Explicit width in pts */
+    width?: number;
+    /** Text alignment within the cell */
+    align?: "right" | "left" | "center";
+    /** If true, formats value as currency using formatCurrencyRTL */
+    isCurrency?: boolean;
+    /** Custom cell renderer */
+    render?: (value: unknown, row: Record<string, unknown>) => string;
+}
+interface RTLTableProps {
+    columns: RTLTableColumn[];
+    data: Record<string, unknown>[];
+    fontFamily?: string;
+    /** Header background color */
+    headerBg?: string;
+    /** Header text color */
+    headerColor?: string;
+    /** Row stripe color (alternating rows) */
+    stripeBg?: string;
+    /** Border color */
+    borderColor?: string;
+    /** Font size for table content */
+    fontSize?: number;
+}
+/**
+ * A fully RTL-aware table component for @react-pdf/renderer.
+ *
+ * Renders columns right-to-left, handles Hebrew text in cells,
+ * and supports currency formatting out of the box.
+ *
+ * @example
+ * <RTLTable
+ *   columns={[
+ *     { header: "תיאור", key: "description", flex: 3 },
+ *     { header: "כמות", key: "quantity", flex: 1, align: "center" },
+ *     { header: "מחיר יחידה", key: "unitPrice", flex: 1, isCurrency: true },
+ *     { header: 'סה"כ', key: "total", flex: 1, isCurrency: true },
+ *   ]}
+ *   data={boqItems}
+ *   headerBg="#1a1a1a"
+ *   headerColor="#EAB308"
+ * />
+ */
+declare function RTLTable({ columns, data, fontFamily, headerBg, headerColor, stripeBg, borderColor, fontSize, }: RTLTableProps): react_jsx_runtime.JSX.Element;
+interface RTLDividerProps {
+    color?: string;
+    thickness?: number;
+    marginVertical?: number;
+}
+/**
+ * A simple horizontal divider for RTL PDF documents.
+ */
+declare function RTLDivider({ color, thickness, marginVertical }: RTLDividerProps): react_jsx_runtime.JSX.Element;
+interface RTLSummaryRowProps {
+    label: string;
+    value: string | number;
+    isCurrency?: boolean;
+    bold?: boolean;
+    fontSize?: number;
+    color?: string;
+    fontFamily?: string;
+}
+/**
+ * A label + value row for totals/summaries in RTL layout.
+ * Label on the right, value on the left — as expected in Hebrew documents.
+ *
+ * @example
+ * <RTLSummaryRow label='סה"כ לפני מע"מ' value={12500} isCurrency bold />
+ * <RTLSummaryRow label='מע"מ 18%' value={2250} isCurrency />
+ * <RTLSummaryRow label="סכום סופי" value={14750} isCurrency bold color="#EAB308" />
+ */
+declare function RTLSummaryRow({ label, value, isCurrency, bold, fontSize, color, fontFamily, }: RTLSummaryRowProps): react_jsx_runtime.JSX.Element;
+
+type RTLFontWeight = "normal" | "bold" | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+interface RTLFontSource {
+    src: string;
+    fontWeight?: RTLFontWeight;
+    fontStyle?: "normal" | "italic";
+}
+interface RegisterRTLFontOptions {
+    /** Font family name, e.g. "Rubik" */
+    family: string;
+    /** Array of font sources (different weights/styles) */
+    fonts: RTLFontSource[];
+}
+/**
+ * Registers a font family with @react-pdf/renderer.
+ * Wraps Font.register with sensible defaults for RTL fonts.
+ *
+ * @example
+ * registerRTLFont({
+ *   family: "Rubik",
+ *   fonts: [
+ *     { src: "/fonts/Rubik-Regular.ttf", fontWeight: "normal" },
+ *     { src: "/fonts/Rubik-Bold.ttf", fontWeight: "bold" },
+ *   ],
+ * });
+ */
+declare function registerRTLFont(options: RegisterRTLFontOptions): void;
+/**
+ * Registers the Rubik font from Google Fonts CDN.
+ * Rubik is the recommended font for Hebrew PDFs — designed for Hebrew,
+ * supports all weights, and renders cleanly in @react-pdf/renderer.
+ *
+ * Weights registered: 300 (Light), 400 (Regular), 500 (Medium), 700 (Bold)
+ */
+declare function registerRubik(): void;
+/**
+ * Registers Noto Sans Hebrew from Google Fonts CDN.
+ * Good fallback if Rubik is not desired — extensive Hebrew glyph coverage.
+ */
+declare function registerNotoSansHebrew(): void;
+/**
+ * Disables font hyphenation — critical for Hebrew text.
+ * Hebrew words should never be hyphenated mid-word.
+ */
+declare function disableHyphenation(): void;
+/**
+ * One-shot setup: registers Rubik + disables hyphenation.
+ * This is the recommended setup for Hebrew PDFs.
+ *
+ * @example
+ * // At the top of your PDF component file:
+ * setupHebrewPDF();
+ */
+declare function setupHebrewPDF(fontFamily?: "Rubik" | "NotoSansHebrew"): void;
+
+/**
+ * Unicode bidi control characters
+ */
+declare const BIDI: {
+    /** Right-to-Left Embedding — forces RTL rendering for the embedded text */
+    readonly RLE: "‫";
+    /** Left-to-Right Embedding */
+    readonly LRE: "‪";
+    /** Pop Directional Formatting — ends the current embedding */
+    readonly PDF: "‬";
+    /** Right-to-Left Mark — invisible RTL directional mark */
+    readonly RLM: "‏";
+    /** Left-to-Right Mark */
+    readonly LRM: "‎";
+    /** Right-to-Left Override — strongly forces RTL */
+    readonly RLO: "‮";
+};
+/**
+ * Returns true if the string contains any RTL characters (Hebrew, Arabic, etc.)
+ * FIX: coerces input to string — safe when called from JS without types
+ */
+declare function hasRTLChars(str: unknown): boolean;
+/**
+ * Returns true if the MAJORITY of the string's alphabetic content is RTL.
+ * Useful for mixed strings like "מחיר: 120 ₪" — still considered RTL.
+ * FIX: coerces input to string — safe when called from JS without types
+ */
+declare function isRTLDominant(str: unknown): boolean;
+/**
+ * Wraps text in RLE...PDF bidi markers so @react-pdf/renderer
+ * renders it right-to-left correctly, including mixed content.
+ *
+ * FIX: idempotent — guards against double-wrapping (broken bidi nesting)
+ */
+declare function wrapRTL(text: string): string;
+/**
+ * Wraps text in LRE...PDF for explicit LTR segments inside an RTL document.
+ * FIX: idempotent — guards against double-wrapping
+ */
+declare function wrapLTR(text: string): string;
+/**
+ * Smart wrap: auto-detects direction and wraps accordingly.
+ * FIX: accepts string | number | null | undefined — BoQ fields are often numbers
+ */
+declare function smartWrap(text: string | number | null | undefined): string;
+/**
+ * Formats a currency amount for RTL display.
+ * Ensures the symbol (₪) and number don't get scrambled in bidi context.
+ *
+ * FIX: throws RangeError on NaN/Infinity with clear message
+ * FIX: handles negative amounts correctly (discounts, returns)
+ */
+declare function formatCurrencyRTL(amount: number, symbol?: string, locale?: string): string;
+/**
+ * Splits mixed RTL/LTR text into segments with direction metadata.
+ * Reconstructs exactly: splitBidiSegments(s).map(s => s.text).join('') === s
+ *
+ * FIX: uses Array.from() to correctly handle surrogate pairs (emoji, rare Unicode)
+ */
+type TextSegment = {
+    text: string;
+    direction: "rtl" | "ltr" | "neutral";
+};
+declare function splitBidiSegments(text: string): TextSegment[];
+/**
+ * Returns true if the string already contains bidi control characters.
+ */
+declare function hasBidiMarkers(text: string): boolean;
+/**
+ * Strips all bidi control characters from a string.
+ * Use for: extracting plain text for storage, search, or logging.
+ */
+declare function stripBidiMarkers(text: string): string;
+
+export { BIDI, RTLDivider, type RTLDividerProps, type RTLFontSource, type RTLFontWeight, RTLSummaryRow, type RTLSummaryRowProps, RTLTable, type RTLTableColumn, type RTLTableProps, RTLText, type RTLTextProps, RTLView, type RTLViewProps, type RegisterRTLFontOptions, type TextSegment, disableHyphenation, formatCurrencyRTL, getRTLPageStyle, hasBidiMarkers, hasRTLChars, isRTLDominant, registerNotoSansHebrew, registerRTLFont, registerRubik, setupHebrewPDF, smartWrap, splitBidiSegments, stripBidiMarkers, wrapLTR, wrapRTL };