react-native-arabic-autoheight-text/README.md

Smart Arabic/RTL text renderer for React Native using WebView: auto height, proper justification, line clamp, and skeleton loading.

# 🇸🇦 react-native-arabic-autoheight-text  
**Beautiful Arabic & RTL text inside WebView — Auto Height + Proper Typography**

[![npm version](https://img.shields.io/npm/v/react-native-arabic-autoheight-text.svg)](https://www.npmjs.com/package/react-native-arabic-autoheight-text)
[![license](https://img.shields.io/npm/l/react-native-arabic-autoheight-text.svg)](./LICENSE)
[![platforms](https://img.shields.io/badge/platforms-ios%20%7C%20android-lightgrey.svg)]()
[![TypeScript Friendly](https://img.shields.io/badge/TypeScript-ready-blue.svg)]()

A tiny, drop-in React Native component for **Arabic / RTL text rendering** with:

- 🚀 Auto height inside WebView (no internal scrolling)
- 🕌 Perfect RTL direction + correct justification
- ✂️ Line clamping using CSS (`numberOfLines`)
- 🎨 React Native `TextStyle` → CSS conversion (fontSize, color, margins…)
- 🦴 Built-in or custom skeleton loader
- 🧠 Handles multiline real Arabic text (not flipped / broken in RN `<Text>`)

Perfect for **news articles، المحتوى التعليمي، وصف المنتجات، النصوص الطويلة…**  
حيث `<Text>` لا يقدم نفس الجودة أو المرونة.

---

## 📦 Installation

```bash
yarn add react-native-arabic-autoheight-text react-native-webview react-native-skeleton-placeholder
# or
npm install react-native-arabic-autoheight-text react-native-webview react-native-skeleton-placeholder
```

iOS pods:

```bash
cd ios && pod install
```

---

## 🧩 Usage

### Minimal example

```tsx
import RtlTextView from 'react-native-arabic-autoheight-text';

<RtlTextView
  text="هذا النص سيتم ضبط ارتفاعه تلقائياً حسب المحتوى"
  textStyle={{ fontSize: 18, color: '#333', marginTop: 10 }}
/>
```

---

### With line clamping

```tsx
<RtlTextView
  text="نص عربي طويل سيتم قصه بعد ثلاثة أسطر فقط..."
  numberOfLines={3}
/>
```

---

### With custom skeleton

```tsx
<RtlTextView
  text="جارٍ تحميل المحتوى..."
  renderSkeleton={() => (
    <View style={{ height: 60, borderRadius: 8, backgroundColor: '#EEE' }} />
  )}
/>
```

---

### Passing WebView props

```tsx
<RtlTextView
  text="Arabic Text with additional WebView config"
  webviewProps={{
    decelerationRate: 'normal',
  }}
/>
```

---

## 🔧 Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `string` | — | Arabic text content to display |
| `textStyle` | `StyleProp<TextStyle> \| StyleProp<TextStyle>[]` | — | Styles extracted and converted to CSS |
| `numberOfLines` | `number` | `undefined` | CSS line-clamp to restrict visible lines |
| `isDark` | `boolean` | `false` | Changes skeleton colors for dark mode |
| `fontFamily` | `string` | from `textStyle.fontFamily` | Overrides font family in WebView |
| `renderSkeleton` | `() => React.ReactNode` | default skeleton | Custom loader |
| `skeletonProps` | `Record<string, any>` | {} | Extra props forwarded to built-in skeleton |
| `webviewProps` | `WebViewProps` | {} | Forwarded to `<WebView />` |
| `containerStyle` | `StyleProp<ViewStyle>` | {} | Wrapper styling |

---

## 🎨 Styling & RTL Behavior

Extracted from `textStyle` (prefers last non-null value):

- color, backgroundColor
- fontFamily, fontSize, fontWeight, lineHeight
- width
- margins (`marginStart`, `marginEnd`, `marginTop`, `marginBottom`, `marginHorizontal`, `marginVertical`)
- textAlign + alignment correction for RTL

> Using `marginStart` + `marginEnd` recommended for smarter RTL spacing.

---

## 🔤 Arabic Fonts

The internal HTML includes support for:

- **IBM Plex Sans Arabic**
- Any custom RTL font installed in RN

Just pass:

```ts
textStyle={{ fontFamily: 'IBM Plex Sans Arabic' }}
```

> Ensure fonts are linked properly in your RN project (Android + iOS).

---

## ⚠️ Notes

- Uses `WebView` → preferred for *complex Arabic layout*
- Smooth auto measurement → **no scrolling** inside WebView
- `numberOfLines` based on CSS → behaves a bit differently than RN `<Text>`

---

## 🛠 Troubleshooting

| Issue | Fix |
|------|-----|
| Skips font on first render | Pass explicit `fontFamily` prop |
| Text flushes left sometimes | Add `textAlign: 'justify'` |
| Skeleton overlaps | Skeleton auto hides after measurement timeout |
| Height wrong on first frame | WebView recalculates on load + font load |

---

## 🗺 Roadmap

- Mixed LTR/RTL detection
- Custom HTML wrapper / CSS injection
- Expandable “Read more” text
- Accessibility improvements

PRs welcome ✨

---

## 👤 Author

Built with ❤️ by **Ahmed Hegazy**  
📧 ahmedmhegazy.eg@gmail.com

---

## 📄 License

MIT — Use freely for commercial & open-source projects.