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

package/.github/copilot/WidgetDevelopmentGuide.md

@@ -1,632 +0,0 @@
-# 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**