@pepperi-addons/ngx-lib-react 0.5.7 → 0.5.8

package/SERVICES.md

@@ -0,0 +1,419 @@
+# Using PEP-NgxLib Utilities in React
+
+## ⚠️ IMPORTANT: No Angular Service Classes Are Exported
+
+`@pepperi-addons/ngx-lib-react` does **not** export Angular service classes such
+as `PepHttpService`, `PepSessionService`, or `PepCustomizationService`.
+
+Directly exporting those services would pull Angular and its DI runtime into
+your React bundle, causing:
+
+- Massive bundle size increase
+- Build errors / version conflicts
+- Runtime errors in React-only environments
+
+Instead, the React package exposes:
+
+1. **Standalone HTTP helpers** with no Angular dependency.
+2. **Bridge-based helpers** that call selected Angular services via the
+   Elements bundle at runtime (through `window.pepperi.services`).
+
+## ✅ Alternatives for React
+
+Instead of Angular services, use these React-friendly alternatives:
+
+### For UUID Generation
+```typescript
+// Use crypto.randomUUID() (modern browsers)
+const uuid = crypto.randomUUID();
+
+// Or use a library like 'uuid'
+import { v4 as uuidv4 } from 'uuid';
+const uuid = uuidv4();
+```
+
+### For Email/URL Validation
+```typescript
+// Use native JavaScript
+const isValidEmail = (email: string) => {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+};
+
+const isValidUrl = (url: string) => {
+    try {
+        new URL(url);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+// Or use a library like 'validator'
+import validator from 'validator';
+const isValid = validator.isEmail('test@example.com');
+```
+
+### For Cookie Management
+```typescript
+// Use js-cookie library
+import Cookies from 'js-cookie';
+
+Cookies.set('myCookie', 'value', { expires: 7 });
+const value = Cookies.get('myCookie');
+Cookies.remove('myCookie');
+```
+
+### For Color Utilities
+```typescript
+// Use a library like 'color' or 'tinycolor2'
+import Color from 'color';
+
+const rgb = Color('#FF5733').rgb().object();
+const contrast = Color('#FF5733').isDark() ? '#FFFFFF' : '#000000';
+```
+
+## Summary
+
+**No Angular service classes are exported from this package.** Use:
+
+1. **HTTP helper functions** for API calls (`pepHttpGet`, `pepHttpPost`, etc.).
+2. **Bridge-based helpers** to access `PepHttpService`, `PepSessionService`,
+   and `PepCustomizationService` via the Elements bundle.
+3. **Custom element components** for UI (`PepDialog`, `PepSnackBar`, etc.).
+4. **Standard JavaScript libraries** for utilities (uuid, validator,
+   js-cookie, color, etc.).
+
+## Bridge-Based Service Helpers (via Elements bundle)
+
+In addition to the standalone HTTP helpers, the React package exposes
+**bridge-based helpers** that call selected Angular services at runtime via the
+Angular Elements bundle. This lets you reuse existing Pepperi logic without
+importing Angular into the React build.
+
+> These helpers require that the Elements bundle is loaded and
+> `NgxLibElementsModule` has run, so that `window.pepperi.services` is
+> populated (see README for how to load the Elements scripts).
+
+### PepHttpService helpers
+
+```ts
+import {
+    pepHttpGetViaService,
+    pepHttpPostViaService,
+    pepHttpGetWapi,
+    pepHttpPostWapi,
+    pepHttpGetPapi,
+    pepHttpPostPapi,
+} from '@pepperi-addons/ngx-lib-react';
+
+// PAPI example
+const accounts = await pepHttpGetPapi<any[]>('/accounts');
+
+// WAPI example
+const created = await pepHttpPostWapi('/transactions', { Amount: 10 });
+```
+
+### PepSessionService helpers
+
+```ts
+import {
+    pepGetIdpToken,
+    pepGetWapiBaseUrl,
+    pepGetPapiBaseUrl,
+    pepSessionGetObject,
+    pepSessionSetObject,
+    pepSessionRemoveObject,
+} from '@pepperi-addons/ngx-lib-react';
+
+const token = pepGetIdpToken();
+const wapiBaseUrl = pepGetWapiBaseUrl();
+const papiBaseUrl = pepGetPapiBaseUrl();
+
+pepSessionSetObject('myKey', { foo: 'bar' });
+const value = pepSessionGetObject<{ foo: string }>('myKey');
+pepSessionRemoveObject('myKey');
+```
+
+### PepCustomizationService helpers (theme & layout)
+
+```ts
+import {
+    pepGetBrandingTheme,
+    pepGetThemeVariables,
+    pepSetThemeVariables,
+    pepGetThemeVariable,
+    pepGetTopBarHeight,
+    pepHideFooter,
+    pepShowFooter,
+} from '@pepperi-addons/ngx-lib-react';
+
+const theme = pepGetBrandingTheme();
+const vars = pepGetThemeVariables();
+
+pepSetThemeVariables({
+    '--pep-color-user-primary': '#83b30c',
+    '--pep-color-user-secondary': '#6c757d',
+});
+
+const topBarHeight = pepGetTopBarHeight();
+pepHideFooter();
+pepShowFooter();
+```
+
+Use these helpers when you want behavior identical to the Angular app (e.g.
+PAPI/WAPI base URL resolution, theme persistence) but from React.
+
+### PepTranslateService helpers (i18n)
+
+```ts
+import {
+    pepTranslateInstant,
+    pepTranslateGet,
+    pepTranslateUse,
+    pepTranslateGetDefaultLang,
+    pepTranslateGetCurrentLang,
+} from '@pepperi-addons/ngx-lib-react';
+
+// Synchronous lookup (for already-loaded keys)
+const label = pepTranslateInstant('Buttons.Save');
+
+// Ensure a specific language is active (returns a Promise that resolves when loaded)
+await pepTranslateUse('en');
+
+// Async lookup (waits for translations to load)
+const texts = await pepTranslateGet<{ [key: string]: string }>([
+    'Buttons.Save',
+    'Buttons.Cancel',
+]);
+
+const currentLang = pepTranslateGetCurrentLang();
+const defaultLang = pepTranslateGetDefaultLang();
+```
+
+These helpers are thin wrappers over `window.pepperi.services.translate` which is
+initialized by the Elements bundle (`NgxLibElementsModule`). Make sure the
+Elements scripts are loaded before calling them.
+
+### PepAddonService helpers (addons & CPI)
+
+```ts
+import {
+    pepAddonGetApi,
+    pepAddonPostApi,
+    pepAddonGetCpi,
+    pepAddonPostCpi,
+    pepAddonGetServerBaseUrl,
+    pepAddonGetStaticFolder,
+    pepAddonSetStaticFolder,
+} from '@pepperi-addons/ngx-lib-react';
+
+// Classic addon API (sync or async)
+const result = await pepAddonGetApi<any>(
+    '00000000-0000-0000-0000-000000000000',
+    'api',
+    'my_function'
+);
+
+// CPI call example
+const cpiResult = await pepAddonGetCpi<any>(
+    '00000000-0000-0000-0000-000000000000',
+    '/my/relative/url'
+);
+
+// Static folder helpers
+const baseUrl = pepAddonGetServerBaseUrl('00000000-0000-0000-0000-000000000000');
+const staticFolder = pepAddonGetStaticFolder('00000000-0000-0000-0000-000000000000');
+pepAddonSetStaticFolder('/my/addon/', '00000000-0000-0000-0000-000000000000');
+```
+
+These map directly to `PepAddonService` and rely on `window.pepperi.services.addon`.
+
+### PepColorService helpers (color utilities)
+
+```ts
+import {
+    pepFindClosestAccessibleColor,
+    pepLightOrDark,
+} from '@pepperi-addons/ngx-lib-react';
+
+const adjusted = pepFindClosestAccessibleColor('#ffffff', '#000000', 4.5);
+const tone = pepLightOrDark('#83b30c'); // 'light' | 'dark'
+```
+
+These wrap `window.pepperi.services.color` (PepColorService) to reuse Pepperi’s
+accessibility-oriented color logic.
+
+### PepLoaderService helpers (global loader)
+
+```ts
+import { pepLoaderShow, pepLoaderHide } from '@pepperi-addons/ngx-lib-react';
+
+async function doSomething() {
+    try {
+        pepLoaderShow();
+        // ... async work ...
+    } finally {
+        pepLoaderHide();
+    }
+}
+```
+
+These call `window.pepperi.services.loader.show()` / `.hide()`, which in turn
+drive the global Pepperi loader via `PepLoaderService`.
+
+### PepDialogService helpers (default dialogs)
+
+```ts
+import {
+    pepOpenDefaultDialog,
+    pepOpenColorPickerDialog,
+    PepDialogActionsType,
+    PepDialogSizeType,
+} from '@pepperi-addons/ngx-lib-react';
+
+// Default dialog example
+await pepOpenDefaultDialog<void>({
+    title: 'Confirm Action',
+    content: 'Opened from React via pepOpenDefaultDialog helper',
+    actionsType: 'cancel-continue' as PepDialogActionsType,
+    showClose: true,
+    showHeader: true,
+    showFooter: true,
+
+    // Optional dialog config forwarded to PepDialogService.getDialogConfig
+    size: 'small' as PepDialogSizeType, // 'inline' | 'small' | 'regular' | 'large' | 'full-screen'
+    disableClose: false,
+    hasBackdrop: true,
+    minWidth: '320px',
+    maxWidth: '600px',
+    maxHeight: '80vh',
+    panelClass: 'my-custom-dialog-class',
+});
+
+// Color picker dialog example
+const colorResult = await pepOpenColorPickerDialog<any>({
+    value: '#ff0000',
+    type: 'regular',
+    showAAComplient: true,
+    checkAAComplient: true,
+});
+```
+
+`pepOpenDefaultDialog` and `pepOpenColorPickerDialog` are thin Promise-based
+wrappers over `window.pepperi.services.dialog`. They rely on the same
+`PepDialogService` implementation used by Angular apps, so all Pepperi dialog
+styling and behavior (including size classes from `PepDialogSizeType`) apply.
+
+### React-only JSX dialog helper (openReactPepDialog)
+
+In addition to the service-based dialogs, the React package exposes a
+**React-only helper** for opening a Pepperi dialog shell with custom JSX
+content.
+
+```ts
+import { openReactPepDialog, PepDialogSizeType } from '@pepperi-addons/ngx-lib-react';
+
+const result = await openReactPepDialog<boolean>({
+    title: 'React JSX Dialog',
+    size: 'small' as PepDialogSizeType, // optional: controls the size CSS class
+    renderContent: (close) => (
+        <>
+            {/* 1) First top-level wrapper = dialog body (mat-dialog-content) */}
+            <div pep-dialog-content>
+                <p>This dialog body is pure React JSX.</p>
+                <p>It still uses the Pepperi dialog shell.</p>
+            </div>
+
+            {/* 2) Second top-level wrapper = dialog actions (mat-dialog-actions) */}
+            <div
+                pep-dialog-actions
+                className="pep-spacing-element-negative"
+                style={{ display: 'flex', justifyContent: 'flex-end' }}
+            >
+                <button
+                    className="pep-spacing-element mat-button pep-button md weak"
+                    onClick={() => close(false)}
+                >
+                    Cancel
+                </button>
+                <button
+                    className="pep-spacing-element mat-button pep-button md strong"
+                    onClick={() => close(true)}
+                >
+                    OK
+                </button>
+            </div>
+        </>
+    ),
+});
+```
+
+Notes:
+
+- `openReactPepDialog` is **pure React** – it does not call `PepDialogService`.
+- It renders a `PepDialog` web component inside a Pepperi-styled overlay using
+  the same DOM structure and CSS classes as the Angular dialogs.
+- The `size` option is optional; when provided, it adds the corresponding size
+  class (e.g. `small`, `regular`, `large`) to the dialog container.
+- Starting from `@pepperi-addons/ngx-lib-react@0.5.7`, `PepDialog` uses
+  **React portals** to inject JSX into the internal Angular
+  `mat-dialog-content` / `mat-dialog-actions` containers.
+- For correct placement:
+  - `renderContent` should return **exactly two logical top-level children**
+    (usually wrapped in a fragment `<>...</>`).
+  - The **first** child is treated as the **content wrapper** and rendered into
+    `mat-dialog-content`.
+  - The **second** child is treated as the **actions wrapper** and rendered into
+    `mat-dialog-actions`.
+  - Inside these wrappers you can use either plain HTML elements or Pepperi
+    React components (`PepSelect`, `PepButton`, etc.).
+
+Example mirroring a permissions dialog (body with two selects + footer button):
+
+```tsx
+import { openReactPepDialog, PepSelect, PepButton } from '@pepperi-addons/ngx-lib-react';
+
+async function openPermissionsDialogDemo() {
+    await openReactPepDialog<void>({
+        title: 'Add Permission',
+        size: 'regular',
+        renderContent: () => (
+            <>
+                <div pep-dialog-content className="permissions-dialog-content">
+                    <PepSelect
+                        keyProp="addon"
+                        label="Select an Addon"
+                        options={addonOptions}
+                        value={selectedAddonKey}
+                        emptyOption={false}
+                        onValueChange={setSelectedAddonKey}
+                    />
+
+                    <PepSelect
+                        keyProp="editor"
+                        label="Select an Editor"
+                        options={editorOptions}
+                        value={selectedEditorKey}
+                        emptyOption={false}
+                        disabled={!selectedAddonKey}
+                        onValueChange={setSelectedEditorKey}
+                    />
+                </div>
+
+                <div pep-dialog-actions className="permissions-dialog-actions">
+                    <PepButton
+                        value="Confirm"
+                        styleType="strong"
+                        disabled={!selectedAddonKey || !selectedEditorKey}
+                        onButtonClick={handleConfirmClick}
+                    />
+                </div>
+            </>
+        ),
+    });
+}
+```
+
+## Support
+
+For issues or questions about specific services, please refer to the main PEP-NgxLib documentation or contact the Pepperi development team.

package/i18n/ar.ngx-lib.json

@@ -0,0 +1,180 @@
+{
+    "COLOR": {
+        "AA_COMPLIENT": "AA Compliant",
+        "ADD_VALUE_HERE": "Or add (hsl, reg, hex)",
+        "CHANGE_HUE": "Change hue",
+        "CHANGE_SATURATION": "Change saturation",
+        "CHANGE_LIGHTNESS": "Change lightness",
+        "DIALOG_TITLE": "Color picker"
+    },
+    "CHECKBOX": {
+        "TRUE": "True",
+        "FALSE": "False"
+    },
+    "CHIPS": {
+        "ADD_CHIP": "Add Chip"
+    },
+    "IMAGE": {
+        "NO_IMAGE": "No image",
+        "CLICK_TO_ENLARGE": "Click to enlarge"
+    },
+    "FILE": {
+        "HINT": "Drag and drop a file here or click",
+        "UPLOADING_FILE": "Uploading File",
+        "SEE_ORIGINAL": "See original"
+    },
+    "QS": {
+        "ORDER": "Order"
+    },
+    "INTERNAL_PAGE": {
+        "CLICK_TO_ORDER": "Click to order"
+    },
+    "PROFILE_DATA_VIEWS_LIST": {
+        "ADD_PROFILE": "Add profile",
+        "SELECT_PROFILE_DIALOG_TITLE": "Select profile",
+        "SELECT_PROFILE": "Select a profile",
+        "IMPORT_PROFILE_DIALOG_TITLE": "Import to {{ profileTitle }}",
+        "IMPORT_FROM_PROFILE": "Import from",
+        "IMPORT_FROM_PROFILE_DESC": "You can select a profile to copy its configuration to the added profile. Leave this option empty for a default profile hierarchy configuration",
+        "DEFAULT_PROFILE": "(Default profile)",
+        "NO_FIELDS_ASSIGNED": "No fields were assigned"
+    },
+    "RICH_TEXTAREA": {
+        "HINT": "Enter Text"
+    },
+    "SEARCH": {
+        "HINT": "Search",
+        "MORE_RESULTS": "More Results"
+    },
+    "SELECT": {
+        "HINT": "Please select an option"
+    },
+    "SIGNATURE": {
+        "HINT": "Signature",
+        "TAP_TO_SIGN": "Tap to Sign",
+        "DIALOG_TITLE": "Add signature here"
+    },
+    "SMART_FILTERS": {
+        "TITLE": "Smart filters",
+        "IS_ON": "Is on",
+        "CHOOSE_TIME": "Choose time",
+        "AMOUNT": "Amount",
+        "VALUE": "Value",
+        "TIME_UNIT": "Time unit",
+        "START_DATE": "Start date",
+        "END_DATE": "End date",
+        "CHOOSE_DATE": "Choose a date",
+        "TYPE": "Type",
+        "MIN": "Min",
+        "MAX": "Max",
+        "SEARCH": "Search",
+        "NO_SEARCH_RESULTS": "No results found",
+        "NO_OPTIONS": "No options",
+        "OPERATORS": {
+            "IN_THE_LAST": "In the last",
+            "IN_THE_LAST_CALENDAR": "In the last (calendar)",
+            "IN_THE_LAST_VARIABLE": "In the last (variable)",
+            "TODAY": "Today",
+            "THIS_WEEK": "This week",
+            "THIS_MONTH": "This month",
+            "DATE_RANGE": "Between",
+            "DATE_RANGE_VARIABLE": "Between (variable)",
+            "DUE_IN": "Due in",
+            "ON": "On",
+            "NOT_IN_THE_LAST": "Not in the last",
+            "NOT_IN_THE_LAST_CALENDAR": "Not in the last (calendar)",
+            "NOT_DUE_IN": "Not due in",
+            "IS_EMPTY": "Is empty",
+            "IS_NOT_EMPTY": "Is not empty",
+            "NOT_EQUAL": "Not equal",
+            "NOT_EQUAL_TO_VARIABLE": "Not equal to (variable)",
+            "LESS_THEN_OR_EQUAL": "Less than or equal to",
+            "LESS_THEN": "Less than",
+            "LESS_THAN_VARIABLE": "Less than (variable)",
+            "EQUAL": "Equal",
+            "EQUAL_TO_VARIABLE": "Equal to (variable)",
+            "IN_VARIABLE": "In (variable)",
+            "GREATER_THEN": "Greater than",
+            "GREATER_THEN_OR_EQUAL": "Greater than or equal to",
+            "GREATER_THAN_VARIABLE": "Greater than (variable)",
+            "NUMBER_RANGE": "Between",
+            "CONTAINS": "Contains",
+            "IN": "In",
+            "BEGINS_WITH": "Begins with",
+            "ENDS_WITH": "Ends with"
+        },
+        "OPERATOR_UNITS": {
+            "DAYS": "Days",
+            "WEEKS": "Weeks",
+            "MONTHS": "Months",
+            "YEARS": "Years"
+        }
+    },
+    "ACTIONS": {
+        "APPLY": "Apply",
+        "CANCEL": "Cancel",
+        "CLEAR": "Clear",
+        "CLEAR_ALL": "Clear All",
+        "CLOSE": "Close",
+        "CONTINUE": "Continue",
+        "CREATE_NEW": "Create new",
+        "DELETE": "Delete",
+        "DONE": "Done",
+        "OK": "Ok",
+        "REMOVE": "Remove",
+        "SAVE": "Save",
+        "IMPORT": "Import"
+    },
+    "LIST": {
+        "ALL": "All",
+        "NONE": "None",
+        "PAGER_PREVIOUS": "Previous",
+        "PAGER_NEXT": "Next",
+        "PAGER_OUT_OF": "Out of",
+        "PAGER_PAGE": "Page",
+        "SELECT": "Select",
+        "SELECTED": "selected",
+        "SORT_BY": "Sort by",
+        "SORT_ASC": "Ascending",
+        "SORT_DESC": "Descending",
+        "TOTAL_RESULTS": "<span class='bold number'>{{ totalRows }}{{ unknownCount }}</span> results",
+        "TOTAL_RESULT": "<span class='bold number'>{{ totalRows }}</span> result",
+        "TOTAL_RESULTS_OUT_OF": "<span class='bold number'>{{ xRows }}</span> of <span class='bold number'>{{ totalRows }}</span> results",
+        "TOTAL_RESULT_OUT_OF_RESULT": "<span class='bold number'>{{ xRows }}</span> of <span class='bold number'>{{ totalRows }}</span> result",
+        "TOTAL_OF": "At total of: ",
+        "NO_DATA_FOUND": "No results were found.",
+        "NO_DATA_FOUND_SUGGESTIONS_TITLE": "We have some suggestions:",
+        "NO_DATA_FOUND_SUGGESTIONS_LIST": "<li>Make sure that all words are spelled correctly.</li><li>Try different keywords.</li><li>Try more general keywords.</li>"
+    },
+    "MESSAGES": {
+        "TITLE_NOTICE": "Notice",
+        "ERROR_CASE_QUANTITY_LIMIT": "Case quantity",
+        "ERROR_FAILD_TO_LOAD_EXTENSION": "Failed to upload file, {{fileExtension}} format is not supported",
+        "ERROR_FAILD_TO_LOAD_SIZE": "Failed to upload file, file size limitation is - {{fileSize}} MB",
+        "ERROR_INVALID_FIELDS": "Please validate the following fields:",
+        "ERROR_INVENTORY_LIMIT": "Max quantity",
+        "ERROR_IS_NOT_VALID": "{{field}} is not valid",
+        "ERROR_IS_REQUIRED": "{{field}} is mandatory",
+        "ERROR_MANDATORY_FIELDS": "Required fields:",
+        "ERROR_MAX_QUANTITY_LIMIT": "Max quantity",
+        "ERROR_MIN_QUANTITY_LIMIT": "Min quantity",
+        "ERROR_RANGE_IS_NOT_VALID": "Value should be between {{min}} and {{max}}",
+        "ERROR_INVALID_PATTERN": "Invalid Character",
+        "INFO_LOADING_FILE": "Loading",
+        "INFO_MISSING_FILE": "Missing file",
+        "INFO_MISSING_IMAGE": "Missing image",
+        "INFO_MISSING_SIGNATURE": "Signature missing"
+    },
+    "DATE_AGO": {
+        "JUST_NOW": "Just now",
+        "SECOND": "second",
+        "MINUTE": "minute",
+        "HOUR": "hour",
+        "DAY": "day",
+        "WEEK": "week",
+        "MONTH": "month",
+        "YEAR": "year",
+        "SINGULAR": " ago",
+        "PLURAL": "'s ago"
+    }
+}