@skysoftware-co/bayan-core-widgets-ui 0.0.6 → 0.0.8

package/.editorconfig

@@ -0,0 +1,17 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+ij_typescript_use_double_quotes = false
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.github/copilot/WidgetDevelopmentGuide.md

@@ -0,0 +1,632 @@
+# Bayan Core Widgets – Widget Development Guide
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Required Packages & Dependencies](#required-packages--dependencies)
+- [Widget Project Structure](#widget-project-structure)
+- [Widget Standards & Rules](#widget-standards--rules)
+- [Sample Widget: Full Functionality](#sample-widget-full-functionality)
+- [Input & Output Guidelines](#input--output-guidelines)
+- [Translation & Pipes](#translation--pipes)
+- [API Calls](#api-calls)
+- [Naming Standards](#naming-standards)
+- [Versioning Standards](#versioning-standards)
+- [Code Style & Best Practices](#code-style--best-practices)
+
+---
+
+## Project Overview
+
+This repository provides reusable, standalone Angular widgets for Bayan products.
+
+Use a generic library project naming convention for guidance:
+
+`projects/namespace-ui/`
+
+---
+
+## Required Packages & Dependencies
+
+- `@skysoftware-co/bayan-components-ui`  
+  Provides shared UI components (e.g., Employee Badge).
+- `@skysoftware-co/sky-components-ui`  
+  Provides additional UI elements (e.g., cards, dividers).
+- `@fortawesome/pro-light-svg-icons`  
+  For icon support.
+- `@skysoftware-co/bayan-hr-widgets-ui`  
+  The main widgets package.
+
+**Install via npm:**
+npm install @skysoftware-co/bayan-hr-widgets-ui
+
+
+---
+
+## Widget Project Structure
+
+Each widget should be a standalone Angular component, placed under:
+
+`projects/namespace-ui/src/lib/<widget-name>/`
+
+Example:
+`projects/namespace-ui/src/lib/top-menu-widget/`
+
+Shared reusable DTOs and services used by more than one widget must be placed under:
+
+`projects/namespace-ui/src/lib/shared/`
+
+Examples:
+`projects/namespace-ui/src/lib/shared/menu.dtos.ts`
+`projects/namespace-ui/src/lib/shared/menu.service.ts`
+
+---
+
+## Widget Standards & Rules
+
+- **Standalone Components:**  
+  Use Angular standalone components for each widget.
+- **Inputs/Outputs:**  
+  All external data must be passed via `@Input()` properties.  
+  All events must be emitted via `@Output()` EventEmitters.
+- **API Integration:**  
+  Reuse an exported service from `@skysoftware-co/sky-components-ui` before creating any new Widgets-local service.  
+  Create a dedicated Widgets service only when the package does not provide the required behavior.  
+  Accept `baseUrl` as an input for API endpoints.
+- **Shared Surface Placement:**
+  If a DTO or service is reusable across multiple widgets, place it in `projects/namespace-ui/src/lib/shared/` instead of inside a widget folder.
+- **Repo Targeting:**
+  If another repository is mentioned as a source example, treat it as reference-only unless the user explicitly asks to edit that repository.
+- **Portal Reference Rule:**
+  Copy behavior and contracts from Portal code when needed, but do not copy Portal-specific folder structure into this widgets library.
+- **Blocked Service Names:**  
+  Never create Widgets-local services named `CookiesService`, `SecureCookieService`, `SecureStorageService`, `LocalStorageService`, `EncryptionService`, `TranslationService`, `SkyScreenService`, or `SkyPDFService` because those must be reused from `@skysoftware-co/sky-components-ui`.
+- **Translation:**  
+  Reuse the translation service and pipes exported by `@skysoftware-co/sky-components-ui` for all user-facing text instead of creating local equivalents in Widgets.
+- **Styling:**  
+  Use CSS classes as input properties for customization.
+- **Error Handling:**  
+  Emit errors via an `errorOccurred` output event.
+- **Loading State:**  
+  Emit loading state changes via an `isLoadingChanged` output event.
+- **Pipes:**  
+  Reuse exported pipes from `@skysoftware-co/sky-components-ui` before creating a new pipe in Widgets.
+- **Blocked Pipe Names:**  
+  Never create Widgets-local pipes named `capitalizefirst`, `highlight`, `safe`, or `translate` because those must be reused from `@skysoftware-co/sky-components-ui`.
+
+
+---
+
+
+## Widget Documentation Requirements
+
+For this repository, documentation must live at the library project level:
+
+`projects/namespace-ui/README.md`
+
+Do not create widget README files inside `src/`, `src/lib/`, or the widget folder unless the user explicitly requests them.
+
+The project-level README must include:
+
+1. **Widget Description:**  
+   A concise summary of the widget’s purpose and functionality.
+
+2. **Inputs Table:**  
+   A table listing all `@Input()` properties, their types, default values, and descriptions.
+
+3. **Outputs Table:**  
+   A table listing all `@Output()` events, their types, and descriptions.
+
+4. **Usage Example:**  
+   A code snippet showing how to use the widget in a template.
+
+**Example README.md structure:**
+The project-level README should include the following sections:
+
+Widget <Widget Name> 
+
+1. Widget Description
+•	A concise summary of the widget’s purpose and functionality.
+
+2. Inputs Table
+•	List all @Input() properties.
+•	For each input, provide:
+•	Name
+•	Type
+•	Default Value
+•	Description
+
+3. Outputs Table
+•	List all @Output() events.
+•	For each output, provide:
+•	Name
+•	Type
+•	Description
+
+4. Usage Example
+•	Show a code snippet demonstrating how to use the widget in a template.
+---
+
+
+Example README.md Structure
+# <Widget Name> Widget
+
+## Description
+
+Briefly describe what this widget does and where it is used.
+
+## Inputs
+
+| Name         | Type    | Default Value | Description                        |
+|--------------|---------|--------------|------------------------------------|
+| baseUrl      | string  | ''           | Base URL for API requests.         |
+| headerTitle  | string  | 'Title'      | The title displayed in the header. |
+| isEnabled    | boolean | true         | Enables or disables the widget.    |
+
+## Outputs
+
+| Name             | Type                  | Description                          |
+|------------------|----------------------|--------------------------------------|
+| isLoadingChanged | EventEmitter<boolean> | Emits when loading state changes.    |
+| errorOccurred    | EventEmitter<string>  | Emits when an error occurs.          |
+
+## Usage
+
+
+<hr-widget-name> [baseUrl]="baseUrl" 
+                  [headerTitle]="'My Widget'" [isEnabled]="true" (isLoadingChanged)="onLoadingChanged($event)" (errorOccurred)="onError($event)"> 
+</hr-widget-name>
+
+
+---
+Rules
+•	The Inputs and Outputs tables must include all parameters, with their type, default value (for inputs), and a clear description.
+•	Use Markdown tables as shown above for clarity and readability.
+•	Update the README.md whenever inputs or outputs change.
+•	All new widgets must be documented in the project-level README before merging.
+•	Use clear, concise language and keep tables up to date.
+---
+
+
+
+
+# 📦 Shared Angular Library/Widget Development Guide (Generic)
+
+This section defines the **standard rules and structure** for creating shared Angular library projects (widgets/modules) for any business domain (HR, Payroll, Insurance, etc.).
+
+---
+
+## 1. Library Project Structure
+
+**Standard folder layout:**
+
+```
+projects/
+  namespace-ui/
+    README.md
+    src/
+      lib/
+        shared/
+        [feature1]/
+        [feature2]/
+      assets/
+    package.json
+    ng-package.json
+    tsconfig.*.json
+```
+- Each feature/widget in its own folder under `lib/`
+- Shared DTOs and shared services in `lib/shared/`
+- All assets (images, translations, etc.) in `src/assets/`
+- Project-level `README.md` documents usage, inputs/outputs, and dependencies
+
+## 2. Component/Widget Design Rules
+
+- Use **Angular standalone components** for all widgets
+- Expose all visual and behavioral options via `@Input` properties
+- Use `@Output` for all events
+- **Never hardcode styles**: use `[class]` bindings and allow override via `@Input`
+- Default to **Bootstrap 5** utility classes for layout and spacing
+- Use **FontAwesome** for icons via `@fortawesome/angular-fontawesome`
+- All user-facing text must be localizable (see below)
+
+## 3. Localization & Lexicon
+
+- All user-facing text must:
+  - Be passed through a translation pipe (e.g., `{{ 'LabelKey' | translate }}`)
+  - Or be exposed as an `@Input` for override
+- Use a shared lexicon/service for all keys; never hardcode literal text
+- Add new label keys to the lexicon and document them in the library README
+
+## 4. Dependencies & References
+
+- **Always import:**
+  - `@skysoftware-co/[core-ui]` for shared UI elements (badges, icons, alerts, etc.)
+  - `@ngx-translate/core` for translation support
+  - `@fortawesome/angular-fontawesome` for icons
+  - **Bootstrap 5** for layout and utility classes
+- List all peer dependencies in `package.json`
+
+## 5. Styling
+
+- All styles must be class-based and overridable via `@Input`
+- No inline or hardcoded styles in templates
+- Use Bootstrap and custom classes for all layout/appearance
+
+## 6. Documentation
+
+- Document all `@Input` and `@Output` properties in the library/feature README
+- List all required dependencies and peer dependencies
+- Provide usage examples with translation and style override
+- Document all label keys and their purpose
+
+## 7. Reusable Patterns
+
+- Use a constants service for all default values that may need override
+- Define all widget data types in a shared `types` folder
+- Use a shared translation pipe for all localization
+
+## 8. Checklist for New Shared Libraries
+
+- [ ] Use standalone Angular components
+- [ ] All styles via `[class]` and `@Input` properties
+- [ ] All text via translation pipe or `@Input`
+- [ ] Use SkySoftware, Bootstrap, FontAwesome as described
+- [ ] Expose all events via `@Output`
+- [ ] Document all inputs/outputs and usage
+- [ ] Add all label keys to system lexicon
+- [ ] README includes structure, usage, and dependency info
+
+---
+
+## 9. Data Flow, Events, and API Integration in Widgets
+
+### Inputs: Passing Data from Parent to Widget
+- Every widget **must define `@Input` properties** for all data and configuration needed from the parent.
+- Use strongly typed `@Input` properties for all data models, configuration, and visual options.
+- Document each `@Input` in the widget README, including type, default, and description.
+- Example:
+  ```typescript
+  @Input() employee: EmployeeModel | null = null;
+  @Input() baseUrl: string = '';
+  @Input() customLabels: Record<string, string> = {};
+  ```
+- **Best Practice:** Use `@Input` for all data, not service injection, to maximize reusability and testability.
+
+### Outputs: Emitting Events for Parent Customization
+- Use `@Output` EventEmitter for all user actions or important state changes inside the widget.
+- Document each `@Output` in the widget README, including event type and when it fires.
+- Example:
+  ```typescript
+  @Output() actionClicked = new EventEmitter<ActionType>();
+  @Output() dataChanged = new EventEmitter<WidgetData>();
+  ```
+- **Pattern:**
+  - Fire an event on any button click, selection, or internal action that may require parent handling.
+  - Allow parent to subscribe and override or extend widget behavior.
+- **Usage Example:**
+  ```html
+  <my-widget [data]="item" (actionClicked)="onAction($event)"></my-widget>
+  ```
+
+### Custom Translate Pipe & Lexicon Support
+- Widgets must use a **custom translation pipe** (e.g., `myTranslate`) for all user-facing text.
+- The pipe should:
+  - Support multiple languages (en, ar, fr, etc.)
+  - Allow injection of a user-defined lexicon (object or service)
+  - Fallback to default keys if not found in lexicon
+- **Pattern:**
+  ```typescript
+  @Pipe({ name: 'myTranslate', standalone: true })
+  export class MyTranslatePipe implements PipeTransform {
+    constructor(private lexiconService: LexiconService) {}
+    transform(key: string): string {
+      return this.lexiconService.translate(key);
+    }
+  }
+  ```
+- **Widget Usage:**
+  ```html
+  <span>{{ 'WidgetTitle' | myTranslate }}</span>
+  ```
+- **Parent can provide lexicon via service or `@Input` for full customization.**
+
+### API Calls and baseUrl Pattern
+- If a widget needs to call an API, always expose a `@Input() baseUrl: string` property.
+- All internal HTTP calls must use this `baseUrl` as the root for endpoints.
+- **Do not hardcode URLs**; always build from `baseUrl` + relative path.
+- Example:
+  ```typescript
+  @Input() baseUrl: string = '';
+  // ...
+  this.http.get(`${this.baseUrl}/widget/data`)
+  ```
+- **Best Practice:**
+  - Document all API endpoints used by the widget in the README.
+  - Allow parent to override `baseUrl` for different environments or backends.
+
+---
+
+## 10. Referencing Widget Packages in Angular Projects
+
+To use a shared widget library (such as HR widgets, Timekeeping widgets, etc.) in your Angular project:
+
+### 2. Import the Widget Module/Component
+- For standalone components, import directly in your feature/component:
+  ```typescript
+  import { HrMyMainDetailsWidgetComponent } from '@skysoftware-co/bayan-hr-widgets-ui';
+  import { TimekeepingWidgetComponent } from '@skysoftware-co/bayan-timekeeping-widgets-ui';
+  ```
+- Add to the `imports` array of your standalone component:
+  ```typescript
+  @Component({
+    standalone: true,
+    imports: [HrMyMainDetailsWidgetComponent, ...],
+    // ...
+  })
+  export class MyFeatureComponent {}
+  ```
+
+### 3. Use the Widget in Your Template
+- Example:
+  ```html
+  <hr-my-main-details-widget [employee]="employeeData" (actionClicked)="onAction($event)"></hr-my-main-details-widget>
+  <timekeeping-widget [baseUrl]="apiUrl"></timekeeping-widget>
+  ```
+
+### 4. Peer Dependencies
+- Ensure your project has all required peer dependencies (Angular, Bootstrap, FontAwesome, ngx-translate, etc.)
+- See the widget package README for details.
+
+---
+
+**Tip:** Always check the widget package documentation for specific usage, available inputs/outputs, and required setup steps.
+
+---
+
+**Summary:**
+- All widgets must use `@Input` for data/config, `@Output` for events, a custom translate pipe for localization, and `baseUrl` for API calls. This ensures maximum reusability, testability, and external customization.
+
+---
+
+**This standard applies to all shared Angular library projects in Bayan. Use this as a reference for any new library/module creation.**
+
+# i18n JSON File Policy
+- All translation files in assets/i18n/ (en.json, ar.json, fr.json) must use a flat key-value structure (dot notation), e.g.:
+  ```json
+  {
+    "APP.TITLE": "...",
+    "APP.WELCOME": "..."
+  }
+  ```
+- Nested objects are forbidden in translation files.
+- All documentation, code, and translation usage must follow this flat key policy.
+# Widgets Project Creation Standards
+
+## 1. Localization & Internationalization
+- Every widget must support localization using ngx-translate or a compatible translation service.
+- The assets/i18n folder must include at least en.json, ar.json, and fr.json.
+- All display text must use translation keys; never hardcode strings in templates or code.
+- Widgets must accept a lexicon/dictionary input (object of key/value pairs) to override or extend translations at runtime.
+- The lexicon should be merged with system translations, allowing dynamic dictionary updates.
+
+## 2. Widget Inputs & Outputs
+- All widgets must expose configuration via strongly typed `@Input()` properties.
+- All outputs/events must use `@Output()` and be clearly documented.
+- Inputs and outputs must be listed in the README and in the public API.
+- Inputs should allow for customization of appearance, data, and behavior.
+
+## 3. Lexicon/Dictionary Usage
+- The system lexicon (dictionary of key/value pairs) must be used as the primary source for translation overrides.
+- Widgets should check the lexicon for a key before falling back to the default translation.
+- Lexicon structure example:
+  ```typescript
+  lexicon = { 'WIDGET.TITLE': 'Custom Title', 'WIDGET.BUTTON': 'Go' };
+  ```
+- Provide a clear API for passing the lexicon to widgets.
+
+## 4. Theming, Styling, and Bootstrap Usage
+- Always use the portal's theme library and Bootstrap 5 utility classes before introducing any new custom CSS.
+- Custom classes must only be added if Bootstrap 5 and theme classes cannot achieve the required design.
+- All custom styles must be placed in the assets/Styles/ folder, never inline or in per-component files for shared logic.
+- Support RTL and LTR directions and theme switching if required.
+
+## 5. Required Files and Logic
+- Each widget must include:
+  - Standalone Angular component (with OnPush change detection)
+  - Strongly typed input/output
+  - Localization support (translation keys, lexicon input)
+  - Theming support (theme and Bootstrap classes)
+  - Unit tests
+  - Documentation (README)
+- The library must include:
+  - i18n folder with at least 3 languages
+  - Styles folder for shared/custom styles
+  - public-api.ts exporting all widgets/services
+  - Constants/configuration service
+  - Example usage in README
+  
+## Widgets Library Project Rules & Policies (HR Widgets Reference)
+
+### 1. Project Structure & Standards
+- Use Angular CLI to scaffold the library (Angular 19+).
+- Place all widgets under `projects/[library-name]/src/lib/`.
+- Each widget must be in its own folder, with a standalone component.
+- Shared services, types, and assets must be organized under `lib/services/`, `lib/shared/`, and `src/assets/`.
+- Use a public API file (`public-api.ts`) to export all widgets and services.
+
+### 2. Internationalization & Localization
+- Widgets must support multiple languages (en, ar, fr) by reusing the translation service exported from `@skysoftware-co/sky-components-ui`.
+- Reuse translation pipes exported from `@skysoftware-co/sky-components-ui` and do not create duplicate translation pipes in the Widgets project unless no shared option exists.
+- All user-facing text must use translation keys, never hardcoded strings.
+- Allow lexicon overrides for custom translations.
+
+### 3. Theming & Styling
+- All style classes must be customizable via input properties.
+- Use CSS classes for all visual customization; never use inline styles.
+- Support dark/light themes and RTL/LTR direction if required by the host portal.
+
+### 4. Inputs & Outputs
+- All widget inputs must be strongly typed and documented.
+- Use Angular’s `@Input()` and `@Output()` for configuration and events.
+- Document all input properties and output events in the README.
+
+### 5. Dependency Management
+- List all required peer dependencies in package.json (e.g., @skysoftware-co/bayan-components-ui).
+- Use a .npmrc file for private registry access and never commit sensitive tokens.
+
+### 6. Build & Publish
+- Use Angular CLI build commands (`ng build [project]`) for building.
+- Publish only the dist output (never source files) using `npm publish`.
+- Ensure the package is versioned and changelog is updated for each release.
+
+### 7. Testing
+- Write unit tests for all widgets using Jasmine/Karma.
+- Ensure 100% test coverage for public APIs.
+
+### 8. Documentation
+- Provide a detailed README with usage, setup, and input/output documentation.
+- Include setup steps for translation, theming, and peer dependencies.
+
+### 9. Constants & Configuration
+- Expose a constants service for default values (e.g., HrConstantsService).
+- Allow runtime overrides for all constants.
+
+### 10. Forbidden Patterns
+- No direct API calls inside widgets; all data must come from inputs or services.
+- No hardcoded text, styles, or colors.
+- No global state; widgets must be stateless or use provided services only.
+
+
+---
+
+## Sample Widget: Full Functionality
+
+**Component Example:**
+import { Component, Input, Output, EventEmitter, OnInit } from '@angular/core'; 
+import { SharedTranslatePipe, SharedWidgetDataService } from '@skysoftware-co/sky-components-ui';
+
+@Component({ 
+  selector: 'hr-my-sample-widget',
+   standalone: true, 
+  imports: [SharedTranslatePipe],
+  templateUrl: './my-sample-widget.component.html' }) 
+  
+  export class MySampleWidgetComponent implements OnInit { 
+    @Input({ required: true }) baseUrl: string = '';
+     @Input() someInput: string = '';
+      @Output() isLoadingChanged = new EventEmitter<boolean>(); 
+      @Output() errorOccurred = new EventEmitter<string>();
+
+  constructor(private readonly widgetDataService: SharedWidgetDataService) {
+
+}
+
+ngOnInit(): void {
+   this.isLoadingChanged.emit(true);
+    this.widgetDataService.getData(this.baseUrl) .subscribe({ 
+    next: data => {
+       /* handle data */ this.isLoadingChanged.emit(false); }, 
+    error: err => { 
+      this.errorOccurred.emit(err); this.isLoadingChanged.emit(false); 
+      } 
+  });
+ } }
+
+
+**Translation Example:**
+<span>{{ 'MyWidgetTitle' | hrTranslate }}</span>
+
+
+**Pipe Example:**
+<span>{{ value | myCustomPipe }}</span>
+
+---
+
+## Input & Output Guidelines
+
+- **Inputs:**  
+  Use `@Input()` for all configurable properties (e.g., `baseUrl`, CSS classes, labels).
+- **Outputs:**  
+  Use `@Output()` for all events (e.g., `isLoadingChanged`, `errorOccurred`, custom events).
+
+---
+
+## Translation & Pipes
+
+- **Translation:**  
+  - Inject and configure the shared translation service exported by `@skysoftware-co/sky-components-ui` in your app.
+  - Use the shared translation pipe exported by `@skysoftware-co/sky-components-ui` for all static and dynamic text.
+- **Pipes:**  
+  - Reuse formatting, filtering, and translation pipes from `@skysoftware-co/sky-components-ui` before creating a new pipe in Widgets.
+
+---
+
+## API Calls
+
+- **Service Layer:**  
+  - Reuse an exported shared service from `@skysoftware-co/sky-components-ui` when it already covers the widget need.
+  - Create a dedicated Widgets service only when the shared package does not provide the required API abstraction.
+  - Accept `baseUrl` as an input and append endpoint paths as needed.
+- **Versioning:**  
+  - Pass `api-version` header as required (e.g., `api-version: 2`).
+
+**Example:**
+this.http.get(${this.baseUrl}/hr/widgets/my-widget, {
+   headers: { 'api-version': '2' } })
+
+
+---
+
+## Naming Standards
+
+- **Project/Package:**  
+  - Use kebab-case for npm packages: `@skysoftware-co/bayan-hr-widgets-ui`
+- **Component:**  
+  - Prefix with `hr-`, use kebab-case: `hr-my-sample-widget`
+- **Class/Service:**  
+  - Use PascalCase: `MySampleWidgetComponent`, `MySampleWidgetService`
+- **Inputs/Outputs:**  
+  - Use camelCase: `baseUrl`, `isLoadingChanged`
+
+---
+
+## Versioning Standards
+
+- **NPM Package:**  
+  - Use [SemVer](https://semver.org/): `MAJOR.MINOR.PATCH`
+- **API Calls:**  
+  - Use `api-version` header or query parameter for versioning.
+
+---
+
+## Code Style & Best Practices
+
+- **Follow Angular and TypeScript best practices.**
+- **Use strong typing for all inputs, outputs, and service responses.**
+- **Document all public APIs and inputs/outputs in JSDoc or markdown.**
+- **Keep widgets focused and reusable.**
+- **Emit loading and error states for all async operations.**
+- **Use dependency injection for services.**
+- **Avoid hardcoding strings; use translation keys.**
+
+---
+
+## Example: Creating a New Widget
+
+1. **Generate Component:**
+   ng generate component my-sample-widget --project shared-ui --standalone
+
+
+2. **Create Service:**
+   ng generate service services/my-sample-widget --project shared-ui
+
+
+3. **Implement Inputs/Outputs, Translation, API Calls, and Error Handling as shown above.**
+
+---
+
+**For more details, refer to the existing widgets in `projects/shared-ui/src/lib/` and the main [README.md](./README.md).**
+
+---
+
+**End of Guide**