@devhouse.int/angular-reusable-components 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,517 @@
-# Temporary Holding Version
+# @devhouse.int/angular-reusable-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+‏مكتبة مكوّنات Angular قابلة لإعادة الاستخدام لمشاريع DevHouse — مبنية على **Angular 20**
+‏(standalone components) و**DevExtreme 26.1.4**، وتدعم العربية وRTL.
+
+‏المكتبة **مفكوكة الارتباط عن أي تطبيق**: كل ما تحتاجه من خدمات (بيانات، صلاحيات، ترجمة،
+‏إشعارات، سير عمل …) يصلها من المشروع المستضيف عبر **injection tokens**، فلا تعتمد على
+‏خدمات مشروع بعينه.
+
+---
+
+## المتطلبات
+
+```jsonc
+"@angular/common"   "^20.1.0"
+"@angular/core"     "^20.1.0"
+"@angular/forms"    "^20.1.0"
+"@angular/router"   "^20.1.0"
+"devextreme"        "^26.1.4"
+"devextreme-angular" "^26.1.4"
+"leaflet"           "^1.9.4"   // لـ MapLocationPicker فقط
+"rxjs"              "^7.8.0"
+```
+
+## التثبيت
+
+‏للتجربة من npm:
+>
+> ```sh
+> npm install @devhouse.int/angular-reusable-components@0.1.0
+> ```
+
+---
+
+## ⚠️ اقرأ هذا أولاً — قاعدة الـProviders
+
+‏بعض المكوّنات تحتاج providers للوصول إلى بيانات التطبيق وخدماته. الترجمة اختيارية،
+‏وتستخدم المكوّنات النص الافتراضي إذا لم يمرّر التطبيق إعداد ترجمة.
+
+‏معنى ذلك عملياً: إذا استخدمت مكوّناً ولم توفّر الـtoken الذي يطلبه، فلن يفشل البناء بل
+‏سينهار المكوّن **وقت التشغيل** بخطأ Angular من نوع:
+
+```
+NullInjectorError: No provider for InjectionToken WORKFLOW_TOOLBAR_PROVIDER!
+```
+
+‏فراجع جدول المكوّنات أدناه لمعرفة الـproviders التي يحتاجها كل مكوّن.
+‏الـproviders التي يطلبها.
+
+‏ولا يلزم توفير كل الـproviders؛ وفّر فقط ما تطلبه المكوّنات التي تستعملها
+‏— **‏وانتبه للاعتمادات غير المباشرة** المعلَّمة بـ‏¹ و‏² في الجدول: مكوّن يضمّ مكوّناً آخر
+‏يرث متطلّباته.
+‏مثلاً مشروع يستخدم `app-lookup-edit` وحده يحتاج اثنين فقط.
+
+---
+
+## المكوّنات (٣٧ مكوّناً)
+
+‏العمود الأخير يذكر **الـtokens الإجبارية** لكل مكوّن.
+
+### الإدخال والبحث (Lookups)
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `LookupEditComponent` | `app-lookup-edit`، `lookup-edit` | `LOOKUP_DATA_PROVIDER` + `LOOKUP_GRID_PROVIDER` ‏¹ |
+| `LookupPopupComponent` | `app-lookup-popup`، `lookup-popup` | `LOOKUP_GRID_PROVIDER` ‏¹ |
+| `LookupDynamicGridComponent` | `app-lookup-dynamic-grid` | `LOOKUP_GRID_PROVIDER` |
+| `GridLookupComponent` | `app-grid-lookup` | `LOOKUP_GRID_PROVIDER` |
+| `AppSmartLookupComponent` | `app-smart-lookup` | — |
+| `SelectBoxWithLinkComponent` | `app-select-box-with-link` | — |
+
+> ‏**¹ اعتماد غير مباشر — انتبه له.** `LookupEditComponent` يحتوي بداخله
+> ‏`LookupPopupComponent`، وهذا بدوره يحتوي `LookupDynamicGridComponent`. فالحقل نفسه يعمل
+> ‏بـ`LOOKUP_DATA_PROVIDER` وحده، لكن **بمجرّد أن يضغط المستخدم زر العدسة** تُنشأ الشبكة
+> ‏وتنهار بـ`NullInjectorError` إن لم يكن `LOOKUP_GRID_PROVIDER` موفَّراً. وفّر الاثنين معاً.
+
+### المحرّرات
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `ImageEditComponent` | `app-image-edit` | — |
+| `FileEditComponent` | `app-file-edit` | `REUSABLE_COMPONENTS_CONFIG` |
+| `DxDateBoxRangeComponent` | `app-dx-date-box-range` | — |
+| `EquationEditorComponent` | `app-equation-editor` | — |
+| `MapLocationPickerComponent` | `app-map-location-picker` | — |
+
+### النماذج والتنقّل
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `FormNavigatorComponent` | `app-form-navigator` | `FORM_NAVIGATOR_ADAPTER` + `LOOKUP_GRID_PROVIDER` + `INFO_USER_PROVIDER` ‏² (+ `RECORD_SUBSCRIPTION_PROVIDER` عند `allowSubscribe`) |
+| `EditFormButtonsComponent` | `app-edit-form-buttons` | `FORM_NAVIGATOR_ADAPTER` |
+| `SaveOnlyButtonsComponent` | `app-save-only-buttons` | — |
+| `FilterPanelComponent` | `app-filter-panel` | `LOOKUP_DATA_PROVIDER` + `LOOKUP_GRID_PROVIDER` ‏³ |
+| `GroupingLevelComponent` | `app-grouping-level` | `FORM_NAVIGATOR_ADAPTER` |
+| `FnIconComponent` | `app-fn-icon` | — |
+
+> ‏**² `FormNavigatorComponent` يضمّ ثلاثة مكوّنات أخرى.** `LookupPopupComponent`
+> ‏و`InfoPopupComponent` **يُنشآن مع كل متنقّل بلا شرط**، فـ`LOOKUP_GRID_PROVIDER`
+> ‏و`INFO_USER_PROVIDER` **إجباريان** لأي شاشة تستعمل المتنقّل — لا خيار فيهما.
+> ‏أمّا `SubscribeButtonComponent` فمحاط بـ`@if (allowSubscribe && …)`، فـ
+> ‏`RECORD_SUBSCRIPTION_PROVIDER` لا يلزم إلّا إذا فعّلت `allowSubscribe`.
+
+> ‏**³ `FilterPanelComponent` يضمّ `LookupEditComponent` و`GridLookupComponent` داخل `*dxTemplate`.**
+> ‏فلا يلزمان إلّا إذا كانت لوحة التصفية تحوي فلاتر من نوع lookup — وهذا يُحسم وقت
+> ‏التشغيل حسب الميتاداتا، فالأمن توفيرهما.
+
+### المرفقات
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `FileManagerComponent` | `app-file-manager` | `FILE_MANAGER_PROVIDER` + `FORM_NAVIGATOR_ADAPTER` |
+
+### سير العمل (Workflow)
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `WorkflowActionsComponent` | `app-workflow-actions` | `WORKFLOW_ACTIONS_PROVIDER` + `FORM_NAVIGATOR_ADAPTER` |
+| `WorkflowToolbarComponent` | `app-workflow-toolbar` | `WORKFLOW_TOOLBAR_PROVIDER` + `FORM_NAVIGATOR_ADAPTER` |
+
+### الأبعاد المالية
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `FinancialDimensionsPopupComponent` | `app-financial-dimensions-popup` | `FINANCIAL_DIMENSIONS_PROVIDER` |
+| `FinancialDimensionValuesComponent` | `app-financial-dimension-values` | `FINANCIAL_DIMENSION_VALUES_PROVIDER` + `LOOKUP_GRID_PROVIDER` + `FORM_NAVIGATOR_ADAPTER` |
+
+### الصلاحيات
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `PermissionSelectorComponent` | `app-permission-selector` | — |
+| `PermissionSelectorItemComponent` | `app-permission-selector-item` | — |
+
+### السجلّات والإشعارات
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `RecordChangeLogPopupComponent` | `app-record-change-log-popup` | `RECORD_CHANGE_LOG_PROVIDER` |
+| `SubscribeButtonComponent` | `app-subscribe-button` | `RECORD_SUBSCRIPTION_PROVIDER` |
+| `InfoPopupComponent` | `app-info-popup` | `INFO_USER_PROVIDER` |
+| `MessageContentPopupComponent` | `app-message-content-popup` | — |
+| `JournalEntryViewerComponent` | `app-journal-entry-viewer` | `JOURNAL_ENTRY_VIEWER_PROVIDER` |
+| `QueryActionsToolbarComponent` | `app-query-actions-toolbar` | — |
+| `ReceiptPreviewComponent` | `app-receipt-preview` | `REUSABLE_COMPONENTS_CONFIG` (`isArabic`) |
+| `ReportWorkflowActionsComponent` | `app-report-workflow-actions` | — |
+| `ReversalDatePopupComponent` | `app-reversal-date-popup` | `REUSABLE_COMPONENTS_CONFIG` (`translate`) |
+| `WorkflowConfirmDialogComponent` | `app-workflow-confirm-dialog` | — |
+
+### التخطيط
+
+| المكوّن | الـselector | ‏Tokens مطلوبة |
+|---|---|---|
+| `AppToolbarComponent` | `app-toolbar` | — |
+| `AppToolbarItemComponent` | `app-toolbar-item` | — |
+| `AppBorderWrapperComponent` | `app-border-wrapper` | — |
+
+### توجيهات (Directives)
+
+| الاسم | الـselector |
+|---|---|
+| `DxFormItemsOutletDirective` | ‏يُستخدم داخل `app-filter-panel` |
+
+---
+
+## مرجع الـProviders (١٤)
+
+### ‏١. `REUSABLE_COMPONENTS_CONFIG` — إعدادات عامة
+
+‏عنوان الـAPI. يستخدمه `FileEditComponent`.
+
+```ts
+import { provideReusableComponents } from '@devhouse.int/angular-reusable-components';
+
+provideReusableComponents({ apiUrl: 'https://api.example.com/api' })
+```
+
+‏حقول اختيارية: `translate(key, fallback)` و`isArabic()`. أولوية الترجمة في كل المكوّنات
+(بايب `localize` الموحّد): `config.translate` ← `FORM_NAVIGATOR_ADAPTER.translate` ← النصّ الافتراضي.
+
+> ‏`ReportWorkflowActionsComponent` لا يحمل أي معرّفات حالات أو إجراءات افتراضية (تخصّ دورة عمل
+> كل مستأجر): مرّر `draftStatusId` و`approvedStatusId` و`archivedStatusId` و`approveActionId` و
+> `unapproveActionId` و`archiveActionId` و`unarchiveActionId`، وإلا بقيت الأزرار المقابلة معطّلة.
+
+### ‏٢. `LOOKUP_DATA_PROVIDER` — بيانات الـlookup
+
+‏يستخدمه `LookupEditComponent`. كل دالة تقبل الإرجاع بـ`Promise` أو `Observable` أو قيمة مباشرة.
+
+```ts
+import { provideLookup } from '@devhouse.int/angular-reusable-components';
+
+provideLookup({
+  // يحوّل مفتاحاً واحداً إلى صف للعرض (أو null إن لم يوجد)
+  resolve: (ctx, key) => api.resolve(ctx.lookupId, key, ctx.parameters),
+  // بحث نصّي — يُرجع { items, columns?, title? }
+  search:  (ctx, query) => api.search(ctx.lookupId, query, ctx.parameters),
+})
+```
+
+‏`ctx` من نوع `LookupContext` ويحمل: `lookupId` · `parameters` · `lookupParameterSource` ·
+‏`lookupParameters`. والصف المُرجَع `LookupItem` = `{ id, value, label, rowData }`.
+
+### ‏٣. `LOOKUP_GRID_PROVIDER` — الشبكات المعتمدة على الميتاداتا
+
+‏يستخدمه `LookupDynamicGridComponent` و`GridLookupComponent` و`FinancialDimensionValuesComponent`.
+
+```ts
+{
+  provide: LOOKUP_GRID_PROVIDER,
+  useValue: {
+    getSysLookup:      (id) => Observable<any>,   // تعريف الـlookup من الميتاداتا
+    createDataSource:  (...args) => Promise<any>, // DataSource/CustomStore للشبكة
+    toCamelCase:       (value: string) => string, // تطبيع أسماء الأعمدة
+    createGridColumns: (...args) => any[],        // بناء أعمدة DevExtreme
+  },
+}
+```
+
+‏تُصدَّر معه أدوات مساعدة: `LookupValueType` (تعداد أنواع القيم) و`LINQ_SELECT_COMMAND_TYPE`
+‏و`lookupValueToArray()`.
+
+### ‏٤. `FORM_NAVIGATOR_ADAPTER` — الأكثر استعمالاً ⭐
+
+‏**‏مطلوب لسبعة مكوّنات**: `FormNavigatorComponent` · `EditFormButtonsComponent` ·
+‏`FileManagerComponent` · `FinancialDimensionValuesComponent` · `GroupingLevelComponent` ·
+‏`WorkflowActionsComponent` · `WorkflowToolbarComponent`.
+
+‏هذا هو الجسر الذي يستبدل خدمات الصلاحيات والترجمة والإشعارات والتحميل في المشروع المستضيف:
+
+```ts
+{
+  provide: FORM_NAVIGATOR_ADAPTER,
+  useValue: {
+    // الصلاحيات — تقود إظهار/تعطيل أزرار المتنقّل
+    permissions$: Observable<FormNavigatorPermissions | null>,
+    loadPermissions: () => void,
+
+    // الترجمة
+    translate: (key: string, fallback: string) => string,
+    messages: {                       // نصوص جاهزة تستخدمها المكوّنات مباشرةً
+      Load_Data_ERROR, NOT_FOUND, NO_PERMISSION, SAVE_ERROR, SAVE_SUCCESS,
+      DELETE_ERROR, DUPLICATE_ERROR, DUPLICATE_SUCCESS, VALIDATION_REQUIRED,
+    },
+
+    // التنبيهات والتأكيدات
+    notify:  (type: 'success'|'error'|'info'|'warning', message: string) => void,
+    confirm: (type: 'delete'|'duplicate'|'unsaved') => Promise<boolean>,
+
+    // تتبّع تحميل السجل (لانتظار اكتمال الـlookups قبل اعتبار السجل جاهزاً)
+    beginRecordLoad:    () => number,
+    waitForLookups:     (loadId: number) => Promise<void>,
+    isRecordLoadActive: (loadId: number) => boolean,
+
+    // لوحة التحميل المشتركة
+    showLoading: (message: string) => void,
+    hideLoading: () => void,
+  },
+}
+```
+
+‏`FormNavigatorPermissions` يضمّ ١٥ صلاحية اختيارية: `canInsert` · `canUpdate` · `canOpen` ·
+‏`canDelete` · `canPrint` · `canExecute` · `canExport` · `canImport` · `canQuery` ·
+‏`canPrintreport` · `canDesignreport` · `canAssign` · `canShare` · `canBrowse` · `canLogin`.
+
+### ‏٥. `FILE_MANAGER_PROVIDER` — مدير المرفقات
+
+```ts
+{
+  provide: FILE_MANAGER_PROVIDER,
+  useValue: {
+    // عنوان RemoteFileSystemProvider الخاص بـDevExtreme
+    getFileSystemEndpoint: (attachmentSourceId, entityKey) => string,
+
+    // ⚠️ مهم: نقل DevExtreme لا يمرّ على HttpInterceptors، فترويسات الهوية
+    //    (مثل X-Tenant-Domain) يجب تمريرها هنا صراحةً
+    fileSystemRequestHeaders: () => Record<string, string>,
+
+    createTagsStore: () => any,                    // { id, name_Ar }
+    addURL:                     (data) => Observable<unknown>,
+    uploadManual:               (...) => Observable<any>,
+    updateFileMetadataWithFile: (...) => Observable<any>,
+    downloadFile:               (fileId) => Observable<Blob>,
+    getAttachmentTags:          (attachmentId) => Observable<any[]>,
+    setAttachmentTagsById:      (attachmentId, tags) => Observable<unknown>,
+  },
+}
+```
+
+### ‏٦. `WORKFLOW_ACTIONS_PROVIDER` — شريط إجراءات سير العمل
+
+```ts
+{
+  provide: WORKFLOW_ACTIONS_PROVIDER,
+  useValue: {
+    // كل ما يحتاجه الشريط في نداء واحد (يرجع 200 دائماً، لا 404)
+    getDocumentContext: (documentTypeId, documentId) => Observable<WorkflowDocumentContext>,
+    applyTransition:    (instanceId, input) => Observable<WorkflowInstanceResult>,
+    // يُطلَق عند تغيّر سير العمل من تبويب/شاشة أخرى فيعيد الشريط التحميل
+    workflowUpdates$:   Observable<{ documentTypeId, documentId }>,
+    isArabic:           () => boolean,
+  },
+}
+```
+
+‏تُصدَّر معه دالتان لتلوين الأزرار حسب نوع الانتقال
+‏(`APPROVE` أخضر · `REJECT` أحمر · `ESCALATE` برتقالي):
+‏`workflowTransitionColor()` و`workflowTransitionButtonClass()`.
+
+### ‏٧. `WORKFLOW_TOOLBAR_PROVIDER` — شريط أدوات سير العمل
+
+```ts
+{
+  provide: WORKFLOW_TOOLBAR_PROVIDER,
+  useValue: {
+    getAvailableWorkflowActions: (workflowId, statusId) => Observable<any[]>,
+    // يحوّل الإجراءات الخام إلى عناصر شريط:
+    // { text, iconClass, btnClass, hint, onClick, disabled?, visible? }
+    mapWorkflowActionsItems: (actions, applyWorkflowCallback) => any[],
+  },
+}
+```
+
+### ‏٨. `FINANCIAL_DIMENSIONS_PROVIDER` — نافذة الأبعاد المالية
+
+```ts
+{
+  provide: FINANCIAL_DIMENSIONS_PROVIDER,
+  useValue: {
+    getDimensionsByAccount:   (accountId, combinationId?) => Promise<FinancialDimensionVm[]>,
+    getAllDimensions:         () => Promise<FinancialDimensionVm[]>,
+    getCombinationSelections: (dimensions, combinationId) => Promise<DimensionSelectionsMap>,
+    buildPayload:             (dimensions, selections, accountId) => any,
+    createOrGetCombination:   (payload) => Promise<{ id, display_Value }>,
+  },
+}
+```
+
+### ‏٩. `FINANCIAL_DIMENSION_VALUES_PROVIDER` — شبكة قيم الأبعاد
+
+```ts
+{
+  provide: FINANCIAL_DIMENSION_VALUES_PROVIDER,
+  useValue: {
+    dimensionLookupId:        any,   // معرّف lookup الأبعاد
+    dimensionValueLookupId:   any,   // معرّف lookup القيم
+    fieldDataParameterSource: string | number,
+    loadValues:     (options) => Observable<any>,
+    loadDimensions: (options) => Observable<any>,
+  },
+}
+```
+
+### ‏١٠. `RECORD_CHANGE_LOG_PROVIDER` — سجلّ تغييرات السجل
+
+```ts
+{
+  provide: RECORD_CHANGE_LOG_PROVIDER,
+  useValue: {
+    getLog: (tableName: string, recordId: string) => Observable<RecordChangeLogResult>,
+  },
+}
+```
+
+‏`RecordChangeLogResult` = `{ table_Name, record_Id, created_By, created_On, modified_By,
+‏modified_On, changes[] }`، وكل عنصر في `changes` = `{ column_Name, old_Value, new_Value,
+‏changed_On, changed_By }`.
+
+### ‏١١. `RECORD_SUBSCRIPTION_PROVIDER` — الاشتراك في إشعارات سجل
+
+```ts
+{
+  provide: RECORD_SUBSCRIPTION_PROVIDER,
+  useValue: {
+    isSubscribed: (recordId) => Observable<boolean>,
+    getMine:      () => Observable<RecordSubscriptionItem[]>,
+    subscribe:    (recordId, prefs: SubscriptionPrefs) => Observable<unknown>,
+    unsubscribe:  (recordId) => Observable<unknown>,
+  },
+}
+```
+
+‏`SubscriptionPrefs` = أحداث (`notifyOnUpdate` · `notifyOnStatusChange` · `notifyOnDelete`)
+‏وقنوات (`channelInApp` · `channelEmail` · `channelWhatsapp` · `channelSms`).
+
+### ‏١٢. `INFO_USER_PROVIDER` — بيانات المستخدم لنافذة المعلومات
+
+```ts
+{
+  provide: INFO_USER_PROVIDER,
+  useValue: { getById: (id) => Observable<unknown> | Promise<unknown> },
+}
+```
+
+### ‏١٣. `LINQ_SELECT_COMMAND_TYPE` — ثابت لا token
+
+‏ليس injection token بل **ثابت مُصدَّر** قيمته `2`، يُستخدم عند التفريق بين أوامر
+‏الـlookup من نوع LINQ ومن نوع SQL.
+
+---
+
+## مثال توصيل كامل
+
+‏مشروع يستخدم المتنقّل والـlookups وشريط سير العمل:
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import {
+  provideReusableComponents,
+  provideLookup,
+  FORM_NAVIGATOR_ADAPTER,
+  LOOKUP_GRID_PROVIDER,
+  WORKFLOW_TOOLBAR_PROVIDER,
+} from '@devhouse.int/angular-reusable-components';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideReusableComponents({ apiUrl: environment.apiUrl }),
+
+    provideLookup({
+      resolve: (ctx, key)   => inject(LookupApi).resolve(ctx.lookupId, key, ctx.parameters),
+      search:  (ctx, query) => inject(LookupApi).search(ctx.lookupId, query, ctx.parameters),
+    }),
+
+    // خدمة موجودة عندك بنفس الشكل؟ استخدم useExisting بدل useValue
+    { provide: LOOKUP_GRID_PROVIDER,      useExisting: MyLookupGridService },
+    { provide: WORKFLOW_TOOLBAR_PROVIDER, useExisting: MyWorkflowActionService },
+
+    {
+      provide: FORM_NAVIGATOR_ADAPTER,
+      useFactory: () => {
+        const perms  = inject(PermissionService);
+        const i18n   = inject(TranslateService);
+        const loader = inject(LoadingService);
+        return {
+          permissions$: perms.permissions$,
+          loadPermissions: () => perms.load(),
+          translate: (k, fb) => i18n.get(k) ?? fb,
+          messages: MY_MESSAGES,
+          notify:  (type, msg) => notify(msg, type),
+          confirm: (type) => myConfirm(type),
+          beginRecordLoad: () => Date.now(),
+          waitForLookups: async () => {},
+          isRecordLoadActive: () => false,
+          showLoading: (m) => loader.show(m),
+          hideLoading: () => loader.hide(),
+        };
+      },
+    },
+  ],
+};
+```
+
+‏ثم في المكوّن:
+
+```ts
+import { LookupEditComponent } from '@devhouse.int/angular-reusable-components';
+
+@Component({ imports: [LookupEditComponent], /* … */ })
+```
+
+```html
+<app-lookup-edit [lookupId]="'customers'" caption="العميل" [(idValue)]="customerId" />
+```
+
+---
+
+## نموذج التحرير داخل نافذة منبثقة (Embedded form)
+
+‏منذ **‏0.4.0** يستطيع `EditFormButtonsComponent` أن يعمل داخل نافذة منبثقة فوق الشبكة بدل
+‏فتح تبويب متصفّح جديد. وضع المسار (route) **لم يتغيّر إطلاقاً**: كل المُدخلات الجديدة
+‏اختيارية، وعدم ضبطها يعني السلوك القديم حرفياً.
+
+```html
+<app-edit-form-buttons
+  [embedded]="true"
+  [embeddedMode]="'edit'"
+  [embeddedId]="selectedId"
+  (saved)="grid.refresh()"
+  (closed)="popupVisible = false"
+/>
+```
+
+| | |
+|---|---|
+| `embedded` | ‏`true` = داخل نافذة، `false` (الافتراضي) = وضع المسار |
+| `embeddedMode` | ‏`'new'` أو `'edit'` |
+| `embeddedId` | ‏معرّف السجل عند التعديل |
+| `(saved)` | ‏يُطلَق بعد كل حفظ ناجح — بديل `postMessage` |
+| `(closed)` | ‏يُطلَق عند انتهاء الشاشة — المضيف يغلق النافذة |
+
+‏وللشاشة المستضيفة يوجد العقد `EmbeddedFormHost` وحارس النوع `isEmbeddedFormHost()`،
+‏فتستطيع الشبكة المضيفة أن تتحقّق قبل إنشاء المكوّن وتتراجع إلى `window.open` إن لم تكن
+‏الشاشة محوَّلة بعد.
+
+**‏مهم:** أغلِق النافذة عبر `requestClose()` لا بإخفائها مباشرةً — كي يمرّ الإغلاق بمسار
+‏الشاشة الطبيعي (بما فيه تأكيد التغييرات غير المحفوظة).
+
+---
+
+## البناء
+
+```sh
+npm install
+npm run build     # ng-packagr → dist/
+```
+
+---
+
+## ملاحظات
+
+- ‏`MapLocationPickerComponent` يحتاج `leaflet` وملفات أنماطه في المشروع المستضيف.
+- ‏نقل DevExtreme الداخلي (‏`RemoteFileSystemProvider` في مدير المرفقات) **لا يمرّ على
+  ‏`HttpInterceptors`** الخاصة بـAngular — مرّر ترويسات الهوية عبر
+  ‏`fileSystemRequestHeaders()`.
+- ‏معظم النصوص الافتراضية عربية، وتُستبدَل عبر `translate()` و`messages` في
+  ‏`FORM_NAVIGATOR_ADAPTER`.