ngx-kit 6.0.1 → 6.1.0

package/gradient-picker/README.md

@@ -1,41 +1,41 @@
 # ngx-kit/gradient-picker
 
-انتخاب‌گر گرادیانِ خطی/شعاعی با چند color-stop قابل‌درگ، خروجیِ رشته‌ی CSS آماده‌ی استفاده.
+A linear/radial gradient picker with multiple draggable color stops, outputting a ready-to-use CSS string.
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-## استفاده
+## Usage
 
 ```html
 <ngx-input-gradient [(ngModel)]="gradientCss"></ngx-input-gradient>
 ```
 
-یا به‌عنوان دایرکتیو روی یه input معمولی:
+Or as a directive on a plain input:
 
 ```html
 <input type="text" [ngxInputGradient]="gradientCss" (change)="gradientCss = $event" />
 ```
 
-مقدار خروجی یه رشته‌ی معتبرِ CSS مثل `linear-gradient(90deg, #ff0000 0%, #0000ff 100%)` هست که مستقیم توی `background`/`background-image` قابل‌استفاده‌ست.
+The output is a valid CSS string like `linear-gradient(90deg, #ff0000 0%, #0000ff 100%)`, ready to use directly in `background`/`background-image`.
 
 ## API
 
-| ورودی                             | نوع                           | پیش‌فرض  | توضیح                                                   |
-| --------------------------------- | ----------------------------- | -------- | ------------------------------------------------------- |
-| `theme`                           | `'light' \| 'dark' \| 'auto'` | `'auto'` | تمِ پنل                                                 |
-| `setInputBackground` _(دایرکتیو)_ | `boolean`                     | `true`   | پس‌زمینه‌ی input رو به گرادیانِ انتخاب‌شده تنظیم می‌کنه |
-| `change` _(دایرکتیو)_             | `EventEmitter<string>`        |          | رشته‌ی گرادیانِ جدید                                    |
+| Input | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Panel theme |
+| `setInputBackground` *(directive)* | `boolean` | `true` | Sets the input's background to the selected gradient |
+| `change` *(directive)* | `EventEmitter<string>` | | The new gradient string |
 
-## نکات UI
+## UI notes
 
-- هر color-stop با کلیک روی نوارِ گرادیان اضافه می‌شه و با درگ جابه‌جا می‌شه.
-- برای حذف یه stop، دوبار کلیک روش کنید (یا دکمه‌ی حذف اگه نمایش داده بشه).
-- برای تنظیم رنگِ هر stop، از همون پنلِ `ngx-kit/color-picker` استفاده می‌شه (این پکیج بهش وابسته‌ست).
+- Add a color stop by clicking on the gradient bar; drag to move it.
+- Double-click a stop to remove it (or use the delete button if shown).
+- Each stop's color is edited with the same `ngx-kit/color-picker` panel (this package depends on it).
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-خودکار پشتیبانی می‌شه.
+Supported automatically.

package/image-editor/README.md

@@ -1,14 +1,14 @@
 # ngx-kit/image-editor
 
-ویرایشگر تصویر روی پایه‌ی Canvas خام: کراپ با گوشه‌های قابل‌درگ، چرخش (سریع ۹۰° و آزاد)، روشنایی/کنتراست/اشباع، فیلترهای آماده (سیاه‌وسفید، سپیا، معکوس)، یه فیلترِ **کارتونی واقعی** (Posterize + لبه‌یابی Sobel، دستی پیاده‌سازی‌شده چون معادل بومی نداره)، و فشرده‌سازیِ خروجی با کیفیتِ قابل‌تنظیم.
+An image editor built on raw Canvas: crop with draggable corner handles, rotation (quick 90° and free), brightness/contrast/saturation, built-in filters (grayscale, sepia, invert), a **real cartoon filter** (posterize + Sobel edge detection, hand-implemented since there's no native equivalent), and output compression with adjustable quality.
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-## استفاده
+## Usage
 
 ```html
 <ngx-image-editor [source]="selectedFile" (saved)="onSaved($event)" (cancelled)="onCancelled()" />
@@ -16,29 +16,29 @@ npm install ngx-kit
 
 ```ts
 onSaved(result: NgxImageEditorResult) {
-  // result.blob (برای آپلود)، result.dataUrl (برای پیش‌نمایش فوری)، result.width/height
+  // result.blob (for uploading), result.dataUrl (for an instant preview), result.width/height
 }
 ```
 
 ## API
 
-| ورودی                                | نوع                                           | پیش‌فرض        | توضیح                                         |
-| ------------------------------------ | --------------------------------------------- | -------------- | --------------------------------------------- |
-| `source`                             | `File \| Blob \| string \| null` **(اجباری)** |                | فایل/بلاب/data-URL منبع                       |
-| `aspectRatio`                        | `number`                                      | آزاد           | قفلِ نسبتِ کراپ (مثلاً `1` برای آواتار مربعی) |
-| `outputMaxWidth` / `outputMaxHeight` | `number`                                      | بدون محدودیت   | فشرده‌سازیِ ابعاد در خروجیِ نهایی             |
-| `outputType`                         | `'image/jpeg' \| 'image/png' \| 'image/webp'` | `'image/jpeg'` |                                               |
-| `displayMaxWidth`                    | `number`                                      | `420`          | حداکثر عرضِ نمایشِ ناحیه‌ی کراپ روی صفحه      |
+| Input | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` | `File \| Blob \| string \| null` **(required)** | | The source file/blob/data URL |
+| `aspectRatio` | `number` | free | Lock the crop's aspect ratio (e.g. `1` for a square avatar) |
+| `outputMaxWidth` / `outputMaxHeight` | `number` | unlimited | Resize the final output's dimensions |
+| `outputType` | `'image/jpeg' \| 'image/png' \| 'image/webp'` | `'image/jpeg'` | |
+| `displayMaxWidth` | `number` | `420` | Max display width for the crop area on screen |
 
-| خروجی       | نوع                                                         | توضیح |
-| ----------- | ----------------------------------------------------------- | ----- |
-| `saved`     | `NgxImageEditorResult` (`{ blob, dataUrl, width, height }`) |       |
-| `cancelled` | `void`                                                      |       |
+| Output | Type | Description |
+| --- | --- | --- |
+| `saved` | `NgxImageEditorResult` (`{ blob, dataUrl, width, height }`) | |
+| `cancelled` | `void` | |
 
-## معماریِ داخلی (چرا سریعه)
+## Internal architecture (why it's fast)
 
-تمام تعاملِ زنده (چرخوندن، جابه‌جا/ریسایزِ کراپ‌باکس، پیش‌نمایشِ فیلترها حتی کارتونی) روی یه کپیِ کوچیک‌شده از تصویر (حداکثر ۱۲۰۰px) انجام می‌شه — فقط لحظه‌ی `save()`، رندرِ نهایی از روی تصویرِ اصلیِ کامل انجام می‌شه. `brightness`/`contrast`/`saturate`/`grayscale`/`sepia`/`invert` همه با `ctx.filter` بومیِ Canvas 2D پیاده شدن (شتاب‌دهی‌شده توسطِ مرورگر)؛ فقط فیلترِ کارتونی (که معادلِ بومی نداره) با پردازشِ پیکسلی جداگانه انجام می‌شه.
+All live interaction (rotating, moving/resizing the crop box, previewing filters including cartoon) happens on a downscaled copy of the image (max 1200px) — only when you call `save()` is the final render done from the full-resolution original. `brightness`/`contrast`/`saturate`/`grayscale`/`sepia`/`invert` are all implemented with Canvas 2D's native `ctx.filter` (browser-accelerated); only the cartoon filter (which has no native equivalent) is done with separate pixel processing.
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-خودکار پشتیبانی می‌شه.
+Supported automatically.

package/menu/README.md

@@ -1,14 +1,14 @@
 # ngx-kit/menu
 
-منوی کشویی و منوی راست‌کلیک (context menu)، با موقعیت‌دهیِ هوشمند نسبت به anchor (از `ngx-kit/shared`'s `OverlayService`).
+Dropdown menu and context (right-click) menu, with smart positioning relative to an anchor (via `ngx-kit/shared`'s `OverlayService`).
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-## استفاده‌ی پایه (منوی کشویی)
+## Basic usage (dropdown menu)
 
 ```ts
 import { NgxMenuModule } from 'ngx-kit/menu';
@@ -17,57 +17,57 @@ import { NgxMenuModule } from 'ngx-kit/menu';
   standalone: true,
   imports: [NgxMenuModule],
   template: `
-    <button [ngxMenu]="userMenu">باز کردن منو</button>
+    <button [ngxMenu]="userMenu">Open menu</button>
 
     <ngx-menu #userMenu="ngxMenu">
-      <ngx-menu-item (click)="editProfile()">ویرایش پروفایل</ngx-menu-item>
-      <ngx-menu-item (click)="logout()">خروج</ngx-menu-item>
+      <ngx-menu-item (click)="editProfile()">Edit profile</ngx-menu-item>
+      <ngx-menu-item (click)="logout()">Sign out</ngx-menu-item>
       <ngx-menu-divider></ngx-menu-divider>
-      <ngx-menu-item [ngxMenu]="subMenu">تنظیمات بیشتر ›</ngx-menu-item>
+      <ngx-menu-item [ngxMenu]="subMenu">More settings ›</ngx-menu-item>
     </ngx-menu>
 
     <ngx-menu #subMenu="ngxMenu">
-      <ngx-menu-item>گزینه‌ی الف</ngx-menu-item>
-      <ngx-menu-item>گزینه‌ی ب</ngx-menu-item>
+      <ngx-menu-item>Option A</ngx-menu-item>
+      <ngx-menu-item>Option B</ngx-menu-item>
     </ngx-menu>
   `,
 })
 export class MyComponent {}
 ```
 
-نکته‌ی مهم: محتوای `<ngx-menu>` تا وقتی از طریق `[ngxMenu]` (یا `[ngxContextMenu]`) trigger نشه رندر نمی‌شه — یعنی `<ngx-menu>` رو نمی‌شه مستقیم و بدون یه trigger، به‌عنوان یه لیستِ همیشه-نمایان (مثل یه سایدبار) استفاده کرد؛ برای اون منظور از یه لیست معمولی با استایل مشابه استفاده کنید.
+Important: `<ngx-menu>`'s content isn't rendered until it's triggered via `[ngxMenu]` (or `[ngxContextMenu]`) — so you can't use `<ngx-menu>` directly, without a trigger, as an always-visible list (like a sidebar). For that, use a regular list styled similarly.
 
-منوی تودرتو (زیرمنو) هم همون‌طور که بالا دیدید، فقط با گذاشتن `[ngxMenu]` روی خودِ `<ngx-menu-item>` کار می‌کنه.
+Nested menus (submenus) work exactly as shown above, just by putting `[ngxMenu]` on the `<ngx-menu-item>` itself.
 
-## منوی راست‌کلیک
+## Right-click (context) menu
 
 ```html
-<div [ngxContextMenu]="rightClickMenu">راست‌کلیک کن روی من</div>
+<div [ngxContextMenu]="rightClickMenu">Right-click me</div>
 
 <ngx-menu #rightClickMenu="ngxMenu">
-  <ngx-menu-item>کپی</ngx-menu-item>
-  <ngx-menu-item>چسباندن</ngx-menu-item>
+  <ngx-menu-item>Copy</ngx-menu-item>
+  <ngx-menu-item>Paste</ngx-menu-item>
 </ngx-menu>
 ```
 
 ## API
 
-### دایرکتیو `[ngxMenu]`
+### `[ngxMenu]` directive
 
-| ورودی       | نوع                           | توضیح                                                                |
-| ----------- | ----------------------------- | -------------------------------------------------------------------- |
-| `ngxMenu`   | `NgxMenu \| TemplateRef`      | رفرنسِ منویی که باید باز بشه                                         |
-| `placement` | `'top' \| 'bottom' \| 'auto'` | جهتِ باز شدن؛ پیش‌فرض `'auto'` (خودکار انتخاب می‌شه اگه فضا کم باشه) |
+| Input | Type | Description |
+| --- | --- | --- |
+| `ngxMenu` | `NgxMenu \| TemplateRef` | Reference to the menu to open |
+| `placement` | `'top' \| 'bottom' \| 'auto'` | Opening direction; defaults to `'auto'` (picked automatically if there isn't enough room) |
 
 ### `<ngx-menu>`
 
-| ورودی   | نوع      | توضیح                   |
-| ------- | -------- | ----------------------- |
-| `class` | `string` | کلاسِ CSS اضافی روی پنل |
+| Input | Type | Description |
+| --- | --- | --- |
+| `class` | `string` | Extra CSS class on the panel |
 
-### شخصی‌سازی ظاهر
+### Styling
 
-از طریق CSS custom properties:
+Via CSS custom properties:
 
 ```css
 ngx-menu {
@@ -80,6 +80,6 @@ ngx-menu {
 }
 ```
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-هر دو خودکار پشتیبانی می‌شن (از طریق `ngx-kit/shared`'s `OverlayService`/`DirectionService` و `light-dark()`)؛ کار اضافه‌ای لازم نیست.
+Both are supported automatically (via `ngx-kit/shared`'s `OverlayService`/`DirectionService` and `light-dark()`); no extra work needed.

package/message/README.md

@@ -1,70 +1,70 @@
 # ngx-kit/message
 
-دیالوگ‌های alert/confirm (شبیه SweetAlert)، با API استاتیک قابل‌فراخوانی از هرجای اپ.
+Alert/confirm dialogs (SweetAlert-style), with a static API callable from anywhere in the app.
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-## راه‌اندازی
+## Setup
 
-``` typescript
+```ts
 // app.config.ts
 import { provideMessage } from 'ngx-kit/message';
 
 export const appConfig: ApplicationConfig = {
-  providers: [provideMessage({ confirmButtonText: 'باشه' /* پیش‌فرض‌های سراسری */ })],
+  providers: [provideMessage({ confirmButtonText: 'OK' /* global defaults */ })],
 };
 ```
 
-## استفاده
+## Usage
 
 ```ts
 import { MSG } from 'ngx-kit/message';
 
-MSG.success('ذخیره شد!', 'تغییرات با موفقیت ثبت شدن.');
-MSG.error('خطا', 'مشکلی پیش اومد.');
-MSG.warning('هشدار', 'مطمئنید؟');
-MSG.info('اطلاع', 'این یه پیامِ اطلاعاتیه.');
-MSG.question('سؤال', 'ادامه بدیم؟');
-MSG.loading('در حال پردازش…');
+MSG.success('Saved!', 'Your changes were saved successfully.');
+MSG.error('Error', 'Something went wrong.');
+MSG.warning('Warning', 'Are you sure?');
+MSG.info('Heads up', 'This is an informational message.');
+MSG.question('Question', 'Continue?');
+MSG.loading('Processing…');
 
-// کنترلِ کامل روی گزینه‌ها:
+// full control over options:
 const result = MSG.show({
-  title: 'حذف شود؟',
-  text: 'این عمل قابل بازگشت نیست.',
+  title: 'Delete this?',
+  text: 'This action cannot be undone.',
   showCancelButton: true,
   showDenyButton: true,
-  confirmButtonText: 'بله، حذف کن',
+  confirmButtonText: 'Yes, delete it',
 });
 result.afterClose.subscribe((r) => console.log(r));
 ```
 
 ## API
 
-### `MSG` (و alias آن `Modal`)
+### `MSG` (and its alias `Modal`)
 
-| متد                                                               | امضا                       | توضیح           |
-| ----------------------------------------------------------------- | -------------------------- | --------------- |
-| `show(options?)`                                                  | `IMessageOptions`          | کنترلِ کامل     |
-| `info` / `success` / `warning` / `error` / `question` / `loading` | `(title, text?, options?)` | میان‌برهای رایج |
+| Method | Signature | Description |
+| --- | --- | --- |
+| `show(options?)` | `IMessageOptions` | Full control |
+| `info` / `success` / `warning` / `error` / `question` / `loading` | `(title, text?, options?)` | Common shortcuts |
 
-### `IMessageOptions` (مهم‌ترین فیلدها)
+### `IMessageOptions` (key fields)
 
-| فیلد                                                        | نوع           | پیش‌فرض                      | توضیح                                                                                                             |
-| ----------------------------------------------------------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `title` / `text` / `html`                                   | `string`      |                              | محتوا (`html` سنیتایز نمی‌شه — مسئولیتِ escape با خودتونه)                                                        |
-| `icon`                                                      | `MessageIcon` |                              | آیکونِ نمایشی                                                                                                     |
-| `showConfirmButton` / `showDenyButton` / `showCancelButton` | `boolean`     | `true` / `false` / `false`   |                                                                                                                   |
-| `confirmButtonText` / `denyButtonText` / `cancelButtonText` | `string`      | `'OK'` / `'No'` / `'Cancel'` |                                                                                                                   |
-| `allowOutsideClick` / `allowEscapeKey` / `allowEnterKey`    | `boolean`     | `true`                       | نحوه‌ی بستنِ پیام                                                                                                 |
-| `showCloseButton`                                           | `boolean`     | `false`                      | دکمه‌ی ✕                                                                                                          |
-| `useOverlay`                                                | `boolean`     |                              | برای وقتی که داخل یه دیالوگِ دیگه (مثلاً Angular Material) استفاده می‌شه، لایه‌ی نمایشی رو به بالاترین سطح می‌بره |
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` / `text` / `html` | `string` | | Content (`html` is not sanitized — escaping is your responsibility) |
+| `icon` | `MessageIcon` | | Icon shown |
+| `showConfirmButton` / `showDenyButton` / `showCancelButton` | `boolean` | `true` / `false` / `false` | |
+| `confirmButtonText` / `denyButtonText` / `cancelButtonText` | `string` | `'OK'` / `'No'` / `'Cancel'` | |
+| `allowOutsideClick` / `allowEscapeKey` / `allowEnterKey` | `boolean` | `true` | How the message can be dismissed |
+| `showCloseButton` | `boolean` | `false` | The ✕ button |
+| `useOverlay` | `boolean` | | For when it's used inside another dialog (e.g. Angular Material), raises the display layer to the top |
 
-اگه چند پیام هم‌زمان باز باشن، Escape/Enter فقط روی **آخرین (بالاترین) پیام** اثر می‌کنه، نه همه‌شون.
+If several messages are open at once, Escape/Enter only affect the **last (topmost) message**, not all of them.
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-خودکار پشتیبانی می‌شه.
+Supported automatically.

package/notify/README.md

@@ -1,56 +1,58 @@
 # ngx-kit/notify
 
-نوتیفیکیشن/toast گوشه‌ی صفحه، با API استاتیک، صف‌بندیِ خودکار (وقتی تعداد از حد مجاز بیشتر بشه)، و مکث‌کردنِ تایمر روی هاور.
+Corner toast notifications, with a static API, automatic queueing (once the visible count exceeds the limit), and the timer pausing on hover.
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-## راه‌اندازی
+## Setup
 
 ```ts
 // app.config.ts
 import { provideNotify } from 'ngx-kit/notify';
 
 export const appConfig: ApplicationConfig = {
-  providers: [provideNotify({ timeout: 4000, position: 'top-center', dismissible: true })],
+  providers: [
+    provideNotify({ timeout: 4000, position: 'top-center', dismissible: true }),
+  ],
 };
 ```
 
-## استفاده
+## Usage
 
 ```ts
 import { Notify } from 'ngx-kit/notify';
 
-Notify.success('ذخیره شد');
-Notify.error('پیام رو نتونستیم ارسال کنیم', 'دوباره تلاش کنید');
-Notify.warning('اتصال ضعیف است');
-Notify.info('نسخه‌ی جدید موجوده', undefined, { timeout: 8000 });
+Notify.success('Saved');
+Notify.error('We couldn\'t send your message', 'Try again');
+Notify.warning('Weak connection');
+Notify.info('A new version is available', undefined, { timeout: 8000 });
 ```
 
 ## API
 
 ### `Notify`
 
-| متد                                           | امضا                                                |
-| --------------------------------------------- | --------------------------------------------------- |
+| Method | Signature |
+| --- | --- |
 | `show(type, message, description?, options?)` | `type: 'info' \| 'success' \| 'warning' \| 'error'` |
-| `info` / `success` / `warning` / `error`      | `(message, description?, options?)`                 |
+| `info` / `success` / `warning` / `error` | `(message, description?, options?)` |
 
 ### `NgxNotifyOptions`
 
-| فیلد           | نوع                     | پیش‌فرض        | توضیح                                                      |
-| -------------- | ----------------------- | -------------- | ---------------------------------------------------------- |
-| `timeout`      | `number` (ms)           | `3000`         | مدتِ نمایش قبل از بسته‌شدنِ خودکار                         |
-| `position`     | `NgxNotifyPositionType` | `'top-center'` | گوشه/مرکزِ نمایش                                           |
-| `maxVisible`   | `number`                | `10`           | بیشتر از این تعداد صف می‌شن، نه هم‌پوشانی                  |
-| `allowHtml`    | `boolean`               | `false`        | اگه `true`، پیام به‌عنوان HTML رندر می‌شه (سنیتایز نمی‌شه) |
-| `pauseOnHover` | `boolean`               | `true`         | تایمر با هاور موس متوقف می‌شه                              |
-| `dismissible`  | `boolean`               | `true`         | نمایشِ دکمه‌ی بستن                                         |
-| `closeOnTap`   | `boolean`               | `true`         | با کلیک روی خودِ نوتیفیکیشن بسته بشه                       |
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout` | `number` (ms) | `3000` | How long it's shown before auto-dismissing |
+| `position` | `NgxNotifyPositionType` | `'top-center'` | Corner/center to display in |
+| `maxVisible` | `number` | `10` | Beyond this count, notifications queue instead of overlapping |
+| `allowHtml` | `boolean` | `false` | If `true`, the message is rendered as HTML (not sanitized) |
+| `pauseOnHover` | `boolean` | `true` | The timer pauses while the mouse hovers |
+| `dismissible` | `boolean` | `true` | Show a close button |
+| `closeOnTap` | `boolean` | `true` | Clicking the notification itself closes it |
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-خودکار پشتیبانی می‌شه.
+Supported automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-kit",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Angular input components",
   "author": "Mohammadreza Samani <mr.samani1368@gmail.com>",
   "license": "MIT",

package/shared/README.md

@@ -1,27 +1,27 @@
 # ngx-kit/shared
 
-ابزارها و سرویس‌های مشترکی که بقیه‌ی بسته‌های `ngx-kit` روشون بنا شدن: مدیریت اورلی/دیالوگ، تشخیص جهت صفحه (RTL/LTR)، تشخیص تنظیمات مرورگر، و چند کامپوننت پایه‌ی قابل‌استفاده‌ی مجدد (اسلایدر، رنج‌اسلایدر، صفحه‌ی اشباع رنگ).
+Shared utilities and services that the rest of the `ngx-kit` packages are built on: overlay/dialog management, page-direction (RTL/LTR) detection, browser-preference detection, and a few reusable base components (slider, range slider, color-saturation panel).
 
-معمولاً مستقیم به این پکیج نیازی ندارید — بقیه‌ی بسته‌ها به‌صورت خودکار بهش وابسته‌ان. ولی اگه دارید یه کامپوننت سفارشی می‌سازید که باید با بقیه‌ی کتابخونه هم‌خونی داشته باشه (دارک‌مود، RTL، درگ‌وپرفورمنس)، از همین ابزارها استفاده کنید.
+You usually won't need this package directly — the other packages depend on it automatically. But if you're building a custom component that should stay consistent with the rest of the library (dark mode, RTL, drag performance), use these same utilities.
 
-## نصب
+## Install
 
 ```bash
 npm install ngx-kit
 ```
 
-سبک‌های پایه (شامل `color-scheme` که دارک‌مود رو فعال می‌کنه) رو یک‌بار در سراسر اپ ایمپورت کنید:
+Import the base styles (which enable dark mode via `color-scheme`) once, app-wide:
 
 ```scss
 // styles.scss
 @import 'ngx-kit/styles/all.css';
 ```
 
-## سرویس‌ها
+## Services
 
 ### `OverlayService`
 
-موتور اصلی پشتِ همه‌ی چیزهای شناور کتابخونه (منو، دیالوگ، پاپ‌آپ‌های رنگ/گرادیان/زاویه). یک المنت انگولاری رو داخل یک `<dialog>` بومیِ مرورگر (`showModal()`) نمایش می‌ده و نسبت به یک anchor موقعیت‌دهی می‌کنه.
+The engine behind everything floating in the library (menus, dialogs, the color/gradient/angle picker popups). Renders an Angular component inside a native `<dialog>` (`showModal()`) and positions it relative to an anchor.
 
 ```ts
 import { OverlayService } from 'ngx-kit/shared';
@@ -38,20 +38,20 @@ const ref = overlay.open({
   margin: 8,
 });
 
-ref.close(); // OverlayRef.close() آرگومان یا afterClosed نداره؛ برای اون‌جور رفتار (نتیجه‌ی بازگشتی، افترکلوز) از ngx-kit/dialog استفاده کنید که روی همین سرویس بنا شده
+ref.close(); // OverlayRef.close() takes no argument and has no afterClosed; for that (return value, afterClosed) use ngx-kit/dialog, which is built on top of this service
 ```
 
-چیزهایی که به‌صورت خودکار برات مدیریت می‌شه:
+What's handled for you automatically:
 
-- **موقعیت‌دهی هوشمند**: اگه فضای کافی پایین anchor نباشه، خودکار بالا می‌ره (`placement:'auto'`).
-- **بستن با کلیک بیرون**: با تشخیص کلیک روی backdrop، نه با listener سراسری روی document.
-- **پشته‌بندی درست**: چند اورلیِ هم‌زمان (مثلاً یه منوی زیرمنو‌دار) درست کار می‌کنن؛ Escape فقط آخرین (بالاترین) اورلی رو می‌بنده.
-- **بازگشتِ فوکوس**: بعد از بسته‌شدن، فوکوس به همون المنتی که قبلش فوکوس داشت برمی‌گرده (دسترس‌پذیری).
-- **RTL خودکار**: alignment و placement بر اساس جهت واقعیِ صفحه (نه فقط یه فرض ثابت) حساب می‌شن.
+- **Smart positioning**: if there isn't enough room below the anchor, it flips above (`placement: 'auto'`).
+- **Click-outside dismissal**: detected via the backdrop click, not a global `document` listener.
+- **Correct stacking**: multiple simultaneous overlays (e.g. a menu with a submenu) work correctly; Escape only closes the last (topmost) overlay.
+- **Focus restoration**: after closing, focus returns to whatever had focus before the overlay opened (accessibility).
+- **Automatic RTL**: alignment and placement are computed against the page's actual direction (not a fixed assumption).
 
 ### `DirectionService`
 
-یه سیگنال (`isRtl(): boolean`) که با `MutationObserver` روی attribute-ی `dir` عنصر `<html>` گوش می‌ده و به‌محض تغییرش، ری‌اکتیو آپدیت می‌شه — یعنی اگه اپ شما زبان رو runtime عوض کنه، همه‌چیز خودکار هماهنگ می‌مونه.
+A signal (`isRtl(): boolean`) that watches the `<html>` element's `dir` attribute with a `MutationObserver` and updates reactively the moment it changes — so if your app switches languages at runtime, everything stays in sync automatically.
 
 ```ts
 const direction = inject(DirectionService);
@@ -62,14 +62,14 @@ direction.isRtl(); // signal<boolean>
 
 ```ts
 const browser = inject(BrowserService);
-browser.prefersDarkMode; // boolean — یه‌بار در لحظه‌ی ساخت سرویس خونده می‌شه
+browser.prefersDarkMode; // boolean — read once at service construction time
 ```
 
-## ابزارهای Utility
+## Utilities
 
 ### `startDragSession(callbacks)`
 
-جایگزینِ الگوی مشکل‌دارِ `@HostListener('document:mousemove', ...)` که listener رو برای کل عمر کامپوننت روی `document` نگه می‌داره (حتی وقتی دراگی در جریان نیست — یه مشکل واقعیِ پرفورمنس روی صفحاتی با چند نمونه‌ی هم‌زمان). این تابع فقط در طول یک درگِ واقعی، listener اضافه می‌کنه و خودش پاک می‌کنه؛ `touchmove` هم با `{passive:false}` مدیریت می‌شه، پس درگ‌کردن روی موبایل صفحه رو اسکرول نمی‌کنه.
+Replaces the problematic `@HostListener('document:mousemove', ...)` pattern, which keeps a listener attached to `document` for the entire lifetime of the component — even when nothing is being dragged (a real performance issue on pages with many simultaneous instances). This function only adds a listener for the duration of an actual drag and removes it itself; `touchmove` is handled with `{passive: false}`, so dragging on mobile doesn't also scroll the page.
 
 ```ts
 import { startDragSession } from 'ngx-kit/shared';
@@ -80,7 +80,7 @@ function onPointerDown(ev: MouseEvent | TouchEvent) {
   stop?.();
   stop = startDragSession({
     onMove: (ev) => {
-      /* آپدیت موقعیت */
+      /* update position */
     },
     onEnd: () => {
       stop = undefined;
@@ -89,29 +89,29 @@ function onPointerDown(ev: MouseEvent | TouchEvent) {
 }
 ```
 
-> اگه کامپوننت‌تون `OnPush` هست و از `startDragSession` (به‌جای `@HostListener`) استفاده می‌کنید، حتماً داخل `onMove`/`onEnd` خودتون `ChangeDetectorRef.markForCheck()` رو صدا بزنید — برخلاف `@HostListener` که خودکار view رو dirty می‌کنه، `addEventListener` دستی این کار رو نمی‌کنه.
+> If your component is `OnPush` and uses `startDragSession` (instead of `@HostListener`), make sure to call `ChangeDetectorRef.markForCheck()` inside `onMove`/`onEnd` yourself — unlike `@HostListener`, which automatically marks the view dirty, a manual `addEventListener` does not.
 
 ### `getOffsetPosition(event, element)`
 
-موقعیت pointer/touch رو نسبت به گوشه‌ی بالا-چپِ یه المنت مشخص برمی‌گردونه؛ برای پیاده‌سازیِ کامپوننت‌های درگ‌محور (اسلایدر، انتخاب‌گر رنگ و ...) استفاده می‌شه.
+Returns the pointer/touch position relative to an element's top-left corner; used to implement drag-based components (sliders, color pickers, etc.).
 
 ### `mergeConfig(base, override)`
 
-ادغام عمیقِ دو آبجکت کانفیگ (برای الگوی `provideXxx({...})` که همه‌ی کتابخونه ازش استفاده می‌کنه).
+Deep-merges two config objects (for the `provideXxx({...})` pattern used throughout the library).
 
-## کامپوننت‌های پایه
+## Base components
 
-اینا رو مستقیم هم می‌شه استفاده کرد، ولی بیشتر به‌عنوان بلوک‌های سازنده‌ی کامپوننت‌های دیگه (مثل `color-picker`, `box-shadow`) طراحی شدن:
+These can be used directly, but they're mostly designed as building blocks for other components (like `color-picker`, `box-shadow`):
 
-| کامپوننت               | Selector             | توضیح                                                               |
-| ---------------------- | -------------------- | ------------------------------------------------------------------- |
-| `SliderComponent`      | `slider`             | اسلایدر تک‌مقداره، `ControlValueAccessor`، `[min]`/`[max]`/`[step]` |
-| `RangeSliderComponent` | `range-slider`       | اسلایدر بازه‌ای (دو thumb)                                          |
-| `SaturationComponent`  | داخلی (color-picker) | صفحه‌ی دوبعدیِ انتخاب اشباع/روشنایی رنگ                             |
+| Component | Selector | Description |
+| --- | --- | --- |
+| `SliderComponent` | `slider` | Single-value slider, `ControlValueAccessor`, `[min]`/`[max]`/`[step]` |
+| `RangeSliderComponent` | `range-slider` | Range slider (two thumbs) |
+| `SaturationComponent` | internal (color-picker) | 2D saturation/lightness picker panel |
 
-## دارک‌مود و RTL
+## Dark mode and RTL
 
-هر دو مستقیماً روی `ngx-kit/shared` تکیه دارن:
+Both rely directly on `ngx-kit/shared`:
 
-- **دارک‌مود**: از تابع CSS بومیِ `light-dark()` استفاده می‌شه. برای این‌که کار کنه، باید `color-scheme: light dark` (یا `only light`/`only dark` برای force کردن دستی) روی `:root` ست بشه — این کار با ایمپورت‌کردن `ngx-kit/styles/all.css` خودکار انجام می‌شه. برای force کردن دستیِ تم (مستقل از `prefers-color-scheme` سیستم)، `data-ngx-theme="dark"` یا `"light"` رو روی `<html>`/`<body>` بذارید.
-- **RTL**: با `dir="rtl"` روی `<html>` فعال می‌شه؛ همه‌جای کتابخونه از CSS logical properties (`inset-inline-start` و ...) استفاده شده، پس نیازی به استایل جداگانه نیست.
+- **Dark mode**: uses the native CSS `light-dark()` function. For it to work, `color-scheme: light dark` (or `only light`/`only dark` to force it manually) must be set on `:root` — this happens automatically when you import `ngx-kit/styles/all.css`. To force a theme manually (independent of the OS's `prefers-color-scheme`), set `data-ngx-theme="dark"` or `"light"` on `<html>`/`<body>`.
+- **RTL**: enabled via `dir="rtl"` on `<html>`; the whole library uses CSS logical properties (`inset-inline-start`, etc.), so no separate styling is needed.