platformcommons-web-lib 1.0.0

package/documentation/confirmation-modal.md

@@ -0,0 +1,250 @@
+# Confirmation Modal Component
+
+The `ConfirmationModalComponent` is a flexible dialog component used for confirming actions, displaying alerts, or presenting custom content with a consistent design.
+
+## Installation
+
+To install the latest version of the `commons-shared-web-ui` library, run the following command:
+
+```bash
+npm install commons-shared-web-ui@latest
+```
+
+1. Import `ConfirmationModalModule` in your feature module:
+
+```typescript
+import { ConfirmationModalModule } from "commons-shared-web-ui";
+
+@NgModule({
+  imports: [ConfirmationModalModule],
+})
+export class FeatureModule {}
+```
+
+2. Include the theme mixin in your global styles:
+
+```scss
+@use "commons-shared-web-ui/lib/modules/confirmation-modal/confirmation-modal.theme"
+  as modal;
+
+:root {
+  @include modal.confirmation-modal-theme();
+}
+```
+
+## Usage
+
+Use the component in your template and control its visibility via the `isOpen` input.
+
+```html
+<cc-confirmation-modal
+  [isOpen]="isModalOpen"
+  [config]="modalConfig"
+  (confirm)="onConfirm()"
+  (cancel)="onCancel()"
+  (close)="onClose()"
+>
+  <!-- Optional: Project custom content here -->
+  <p>This action cannot be undone.</p>
+</cc-confirmation-modal>
+```
+
+### Configuration (`ConfirmationModalConfig`)
+
+The appearance and behavior are controlled via the `config` input.
+
+```typescript
+import { ConfirmationModalConfig } from "commons-shared-web-ui";
+
+modalConfig: ConfirmationModalConfig = {
+  title: "Delete Item?",
+  headerTheme: "dark", // 'light' | 'dark'
+  confirmButton: {
+    label: "Delete",
+    type: "danger",
+  },
+  cancelButton: {
+    label: "Cancel",
+    show: true,
+  },
+};
+```
+
+## API Reference
+
+### Inputs
+
+| `isOpen`          | `boolean`                 | `false` | Controls the visibility of the modal.                                      |
+| `config`          | `ConfirmationModalConfig` | -       | Configuration object for the modal.                                        |
+| `confirmDisabled` | `boolean`                 | `false` | Direct override to disable the confirm button (useful for file uploads).   |
+| `confirmLoading`  | `boolean`                 | `false` | Direct override to show loading on the confirm button (shows a spinner).  |
+
+### Outputs
+
+| Output    | Type                 | Description                                                                   |
+| --------- | -------------------- | ----------------------------------------------------------------------------- |
+| `confirm` | `EventEmitter<void>` | Emitted when the confirm button is clicked.                                   |
+| `cancel`  | `EventEmitter<void>` | Emitted when the cancel button is clicked.                                    |
+| `close`   | `EventEmitter<void>` | Emitted when the modal is closed (via backdrop, escape key, or close button). |
+| `showCodeSnippet` | `EventEmitter<void>` | Emitted when the code snippet button is clicked.                      |
+
+### ConfirmationModalConfig Interface
+
+```typescript
+export interface ConfirmationModalConfig {
+  // Header
+  title: string;
+  headerTheme?: "light" | "dark";
+  icon?: string | {
+    type: "material" | "custom";
+    value: string;
+    color?: string;
+  };
+
+  // Modal appearance
+  width?: string;
+  size?: "sm" | "md" | "lg" | "xl"; // sm: 400px, md: 560px, lg: 720px, xl: 1200px
+  customClass?: string;
+  type?: "modal" | "side-panel";
+  panelPosition?: "left" | "right" | "top" | "bottom";
+  panelSpacing?: string;
+  panelWidth?: string;
+  panelHeight?: string;
+
+  // Style Overrides (Direct inputs)
+  backgroundColor?: string;
+  borderRadius?: string;
+  borderTopLeftRadius?: string;
+  borderTopRightRadius?: string;
+  borderBottomLeftRadius?: string;
+  borderBottomRightRadius?: string;
+  padding?: string;
+  headerBackgroundColor?: string;
+  headerTextColor?: string;
+  headerBorderBottom?: string;
+  bodyTextColor?: string;
+  footerBackgroundColor?: string;
+  footerBorderTop?: string;
+
+  // Buttons
+  confirmButton: {
+    label: string;
+    type: "primary" | "danger" | "warning";
+    disabled?: boolean;
+    loading?: boolean;
+  };
+  cancelButton?: {
+    label?: string;
+    show?: boolean;
+  };
+
+  // Custom Footer
+  customFooter?: boolean; // Set to true to replace default buttons with custom footer content
+
+  // Body layout
+  formMode?: boolean; // Set to true when projecting a lib-smart-form — removes body padding and enforces 360px min-height with skeleton spinner
+
+  // Behavior
+  closeOnBackdrop?: boolean;
+  closeOnEsc?: boolean;
+  showCloseButton?: boolean;
+  showCodeSnippetButton?: boolean;
+
+  // Accessibility
+  ariaLabel?: string;
+  ariaDescribedBy?: string;
+
+  // i18n Labels
+  labels?: {
+      closeAriaLabel?: string;
+      codeSnippetAriaLabel?: string;
+      codeSnippetTitle?: string;
+      iconAltText?: string;
+  };
+}
+```
+
+### Configuration Key Reference
+
+The `confirmation-modal-theme` mixin accepts a map with the following optional keys.
+
+| Key                 | Default                       | Description                     |
+| ------------------- | ----------------------------- | ------------------------------- |
+| **bg**              | `#FFFFFF`                     | Background color of the modal.  |
+| **radius**          | `0.75rem`                     | Border radius (12px).           |
+| **shadow**          | `0 4px 24px rgba(0,0,0,0.15)` | Box shadow of the modal.        |
+| **title-font-size** | `1.25rem`                     | Font size of the title (20px).  |
+| **title-color**     | `#111827`                     | Text color of the title.        |
+| **body-padding**    | `1.5rem`                      | Padding for the body (24px).    |
+| **footer-bg**       | `#F9FAFB`                     | Background color of the footer. |
+| **footer-padding**  | `1rem 1.5rem`                 | Padding for the footer.         |
+| **body-padding**    | `1.5rem`                      | Body padding when `formMode` is not set. |
+
+---
+
+## Usage & Examples
+
+### 1. Basic Confirmation
+
+```typescript
+modalConfig: ConfirmationModalConfig = {
+  title: "Delete User?",
+  confirmButton: { label: "Delete", type: "danger" },
+  cancelButton: { label: "Cancel", show: true },
+};
+```
+
+### 2. Smart Form in Modal (`formMode`)
+
+When projecting a `lib-smart-form`, set `formMode: true` in the config. This applies zero body padding and a 360 px minimum height so the modal stays stable while the form skeleton loads.
+
+```typescript
+formModalConfig: ConfirmationModalConfig = {
+  title: "Edit Student",
+  formMode: true,
+  confirmButton: { label: "Save", type: "primary" },
+  cancelButton: { label: "Cancel", show: true },
+};
+```
+
+```html
+<cc-confirmation-modal [isOpen]="isFormOpen" [config]="formModalConfig">
+  <lib-smart-form [formId]="formId" (formSubmit)="onSubmit($event)" />
+</cc-confirmation-modal>
+```
+
+> **Note:** Without `formMode: true`, the modal body uses the default `1.5rem` padding and natural content height — correct for plain text confirmations. Only set `formMode: true` when a `lib-smart-form` is projected.
+
+### 3. Dark Header (Premium Design)
+
+```typescript
+modalConfig: ConfirmationModalConfig = {
+  title: "Create Project",
+  headerTheme: "dark", // Native support for dark header
+  confirmButton: { label: "Continue", type: "primary" },
+};
+```
+
+### 4. Side Panel Mode
+
+The component can also act as a sliding side panel. You can configure its position and spacing from the viewport edges.
+
+```typescript
+sidePanelConfig: ConfirmationModalConfig = {
+  title: "Filters",
+  type: "side-panel",
+  panelPosition: "right",
+  panelSpacing: "16px",
+  panelWidth: "400px",
+  confirmButton: { label: "Apply Filters", type: "primary" },
+  cancelButton: { label: "Reset", show: true }
+};
+```
+
+```html
+<cc-confirmation-modal [isOpen]="isPanelOpen" [config]="sidePanelConfig">
+  <div class="panel-content">
+    <!-- Panel specific content -->
+  </div>
+</cc-confirmation-modal>
+```

package/documentation/filter-sidebar.md

@@ -0,0 +1,178 @@
+# Filter Sidebar Component
+
+A configuration-driven sidebar component for filtering lists and tables. It supports advanced configuration, form integration via `ControlValueAccessor`, and granular event handling.
+
+## Features
+
+- **Dynamic Configuration**: Fully driven by a JSON configuration object.
+- **Form Integration**: Implements `ControlValueAccessor` for usage with `[(ngModel)]` or `[formControl]`.
+- **Multiple Input Types**: Supports `select`, `accordion` (multi-select checkboxes), `checkbox-group`, and `radio-group`.
+- **Tabs Support**: Configurable top-level tabs for switching contexts.
+- **Granular Events**: Emits changes per filter, on apply, and on clear.
+
+## Installation
+
+To install the latest version of the `commons-shared-web-ui` library, run the following command:
+
+```bash
+npm install commons-shared-web-ui@latest
+```
+
+1. Import `FilterSidebarModule` in your feature module:
+
+```typescript
+import { FilterSidebarModule } from "commons-shared-web-ui";
+
+@NgModule({
+  imports: [FilterSidebarModule],
+})
+export class FeatureModule {}
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<lib-filter-sidebar
+  [config]="filterConfig"
+  [(ngModel)]="currentFilters"
+  (filterApply)="onApply($event)"
+>
+</lib-filter-sidebar>
+```
+
+### Configuration Example
+
+```typescript
+import { FilterConfig } from "commons-shared-web-ui";
+
+const filterConfig: FilterConfig = {
+  tabs: {
+    items: [
+      {
+        id: "existing",
+        label: "Invite Existing User",
+        icon: "fa-regular fa-user",
+      },
+      { id: "new", label: "Invite New User", icon: "fa-solid fa-user-plus" },
+    ],
+    defaultActive: "existing",
+  },
+  sections: [
+    {
+      type: "select",
+      key: "beneficiaryType",
+      title: "Beneficiary Type",
+      placeholder: "Select Type",
+      options: [
+        { label: "Parents", value: "parents" },
+        { label: "Students", value: "students" },
+      ],
+    },
+    {
+      type: "accordion",
+      key: "gender",
+      title: "Gender",
+      multi: true, // Checkboxes inside accordion
+      options: [
+        { label: "Male", value: "male" },
+        { label: "Female", value: "female" },
+      ],
+    },
+  ],
+  actions: {
+    apply: { label: "Apply Filter" },
+    clear: { label: "Clear Filter" },
+  },
+};
+```
+
+### Configuration Key Reference
+
+The `filter-sidebar-theme` mixin accepts a map with the following optional keys.
+
+| Key                       | Default   | Description                      |
+| ------------------------- | --------- | -------------------------------- |
+| **bg-color**              | `#ffffff` | Sidebar background color.        |
+| **border-color**          | `#E5E7EB` | Sidebar border color.            |
+| **width**                 | `300px`   | Sidebar width.                   |
+| **tab-active-bg**         | `#FEF2F2` | Background of active tab.        |
+| **tab-active-color**      | `#EF4444` | Text color of active tab.        |
+| **section-title-color**   | `#374151` | Default section title color.     |
+| **accordion-title-color** | `#111827` | Accordion header text color.     |
+| **footer-bg**             | `#ffffff` | Actions footer background color. |
+
+---
+
+## Usage & Examples
+
+### 1. Complex Sections Example
+
+```typescript
+sections: [
+  {
+    type: "select",
+    key: "category",
+    title: "Project Category",
+    options: [
+      { label: "Web", value: "web" },
+      { label: "Mobile", value: "mobile" },
+    ],
+  },
+  {
+    type: "accordion",
+    key: "tags",
+    title: "Popular Tags",
+    multi: true,
+    options: [
+      { label: "Angular", value: "angular" },
+      { label: "Sass", value: "sass" },
+    ],
+  },
+  {
+    type: "radio-group",
+    key: "status",
+    title: "Project Status",
+    options: [
+      { label: "Active", value: "active" },
+      { label: "Archived", value: "archived" },
+    ],
+  },
+];
+```
+
+### 2. Tabs Integration
+
+```typescript
+tabs: {
+  items: [
+    { id: 'filters', label: 'Filters', icon: 'fa-solid fa-filter' },
+    { id: 'presets', label: 'Saved Presets', icon: 'fa-regular fa-star' }
+  ],
+  defaultActive: 'filters'
+}
+```
+
+## API Reference
+
+### Inputs
+
+| Input            | Type           | Description           |
+| ---------------- | -------------- | --------------------- |
+| `config`         | `FilterConfig` | Structure definition. |
+| `initialFilters` | `FilterOutput` | Initial values.       |
+
+### FilterConfig Interface
+
+```typescript
+export interface FilterConfig {
+  tabs?: { items: FilterTab[]; defaultActive?: string };
+  sections: FilterSection[];
+  actions?: {
+    apply?: { label?: string; visible?: boolean };
+    clear?: { label?: string; visible?: boolean };
+  };
+  settings?: { collapsible?: boolean };
+}
+```

package/documentation/filter-table-selector.md

@@ -0,0 +1,228 @@
+# Filter Table Selector Component Documentation
+
+The `FilterTableSelectorComponent` is a composite, configuration-driven component designed for complex selection workflows. It combines a powerful left-hand filter panel (powered by `SmartForm`) with a right-hand data table (powered by `SmartTable`).
+
+It is ideal for scenarios like "Add Beneficiaries", "Select Staff", or "Assign Assets" where users need to search and filter through large datasets before making one or more selections.
+
+## Features
+
+- **Split-Pane Layout**: Side-by-side filter form and data table for an efficient selection experience.
+- **Dynamic Filtering**: Filters are defined via standard `SmartForm` JSON schemas, supporting dropdowns, multi-selects, and dependencies.
+- **Cross-Page Selection**: Tracks selected items across multiple pages of pagination.
+- **Configurable Selection**: Supports both Single Select (Radio) and Multi Select (Checkbox) modes.
+- **i18n Ready**: All labels, placeholders, and headers are resolved via provided translation maps.
+- **Pre-selection Support**: Automatically checks rows that were previously selected.
+- **Responsive**: Adapts to mobile views with a toggleable filter panel.
+
+## Installation
+
+The component is part of the `FilterTableSelectorModule`.
+
+```typescript
+import { FilterTableSelectorModule } from "@campus-cloud/shared-ui";
+
+@NgModule({
+  imports: [
+    FilterTableSelectorModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## Basic Usage
+
+1.  **Define Configuration**: Create a `FilterTableSelectorConfig` object.
+2.  **Provide Labels**: Pass a flat i18n map for translating all keys in the config.
+3.  **Handle Events**: Listen to `onSubmit` to get the array of selected row objects.
+
+### Template
+```html
+<lib-filter-table-selector
+  [config]="selectorConfig"
+  [labels]="labels"
+  [preSelectedRows]="alreadySelectedItems"
+  (onSubmit)="handleSelection($event)"
+  (onCancel)="closeModal()"
+>
+</lib-filter-table-selector>
+```
+
+### Component
+```typescript
+import { FilterTableSelectorConfig } from "@campus-cloud/shared-ui";
+
+export class MyComponent {
+  labels = {
+    'MY_MODULE.TITLE': 'Select Participants',
+    'MY_MODULE.APPLY': 'Apply Filters',
+    'MY_MODULE.COLUMN.NAME': 'Full Name',
+    // ...
+  };
+
+  selectorConfig: FilterTableSelectorConfig = {
+    title: 'MY_MODULE.TITLE',
+    filterConfig: {
+      smartFormConfig: { /* SmartForm JSON Schema */ },
+      filterParamMapping: [
+        { formFieldName: 'gender', apiParamKey: 'genderCode' }
+      ],
+      applyFilterLabel: 'MY_MODULE.APPLY'
+    },
+    tableConfig: {
+      apiUrl: 'gateway/my-service/api/v1/items',
+      columns: [
+        { key: 'fullName', label: 'MY_MODULE.COLUMN.NAME', type: 'text' }
+      ],
+      pagination: { enabled: true }
+    },
+    selectionConfig: {
+      multiSelect: true,
+      selectionCountLabel: 'SELECTED: {selected} of {total}',
+      submitButtonLabel: 'Add Selected',
+      cancelButtonLabel: 'Cancel'
+    }
+  };
+
+  handleSelection(selectedRows: any[]) {
+    console.log('Selected items:', selectedRows);
+  }
+}
+```
+
+## Configuration Reference
+
+### FilterTableSelectorConfig
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `title` | `string` | i18n key for the component header. |
+| `filterConfig` | `FilterPanelConfig` | Configuration for the left-hand filter panel. |
+| `tableConfig` | `FilterTableConfig` | Configuration for the right-hand table. |
+| `selectionConfig` | `SelectionConfig` | Labels and behavior for selection and buttons. |
+
+### FilterPanelConfig
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `smartFormConfig` | `FormSchema` | Full `SmartForm` JSON schema. |
+| `filterParamMapping` | `FilterParamMap[]` | Maps form field names to API query parameters. |
+| `defaultValues` | `Record<string, any>` | (Optional) Values pre-filled in the form and applied to the initial table load. |
+| `disabledFields` | `string[]` | (Optional) Fields to render as read-only. Their values are preserved on Clear Filter. |
+| `applyFilterLabel` | `string` | i18n key for the "Apply" button. |
+| `clearFilterLabel` | `string` | i18n key for the "Clear" button. |
+
+### FilterParamMap
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `formFieldName` | `string` | Field name in the SmartForm schema. |
+| `apiParamKey` | `string` | Query parameter key to append to the Table API URL. |
+
+### SelectionConfig
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `multiSelect` | `boolean` | Enable checkbox (true) or radio (false) selection. |
+| `selectionCountLabel`| `string` | i18n key for the counter text. Supports `{selected}` and `{total}` placeholders. |
+| `submitButtonLabel` | `string` | i18n key for the primary action button. |
+| `cancelButtonLabel` | `string` | i18n key for the secondary action button. |
+
+## Inputs & Outputs
+
+### Inputs
+
+| Input | Type | Description |
+| :--- | :--- | : :--- |
+| `[config]` | `FilterTableSelectorConfig` | (Required) The main configuration object. |
+| `[labels]` | `Record<string, string>` | (Required) Translation map for all i18n keys used in the config. |
+| `[preSelectedRows]`| `any[]` | (Optional) Array of row objects to be pre-checked on load. |
+
+### Outputs
+
+| Output | Description | Payload |
+| :--- | :--- | :--- |
+| `(onSubmit)` | Emitted when the primary button is clicked. | `any[]` (Array of selected row objects) |
+| `(onCancel)` | Emitted when the secondary button is clicked. | `void` |
+
+## Filtering Logic
+
+1.  When the component initializes, it builds query parameters from `filterConfig.defaultValues`.
+2.  The Table API URL is updated: `baseUrl?param1=val1&param2=val2...`.
+3.  When the user clicks "Apply Filter", the component reads the current `SmartForm` values and maps them using `filterParamMapping`.
+4.  If a field contains an array (e.g., from a multi-select dropdown), it is automatically converted to a comma-separated string for the API.
+5.  The table is reloaded with the new URL.
+
+## Examples
+
+### 1. Invite Participants Selector
+
+This example demonstrates a typical setup for a selection modal with geographic filters.
+
+```typescript
+this.config = {
+  title: 'EVENT.ADD_CANDIDATES',
+  filterConfig: {
+    smartFormConfig: {
+      entityType: 'FILTER',
+      sectionConfig: {
+        children: [
+          {
+            name: 'gender',
+            label: 'COMMON.GENDER',
+            type: 'DROPDOWN',
+            subType: 'MULTI',
+            optionConfig: {
+              apiUrl: 'gateway/mdm/genders',
+              labelPath: 'name',
+              valuePath: 'code',
+              dataPath: 'data'
+            }
+          }
+        ]
+      }
+    },
+    filterParamMapping: [
+      { formFieldName: 'gender', apiParamKey: 'genderCodes' }
+    ],
+    applyFilterLabel: 'COMMON.APPLY',
+    clearFilterLabel: 'COMMON.CLEAR'
+  },
+  tableConfig: {
+    apiUrl: 'gateway/search/users',
+    columns: [
+      { key: 'fullName', label: 'COMMON.NAME', type: 'text' },
+      { key: 'email', label: 'COMMON.EMAIL', type: 'text' }
+    ],
+    pagination: { enabled: true }
+  },
+  selectionConfig: {
+    multiSelect: true,
+    selectionCountLabel: 'COMMON.SELECTED_COUNT', // e.g. "{selected} selected"
+    submitButtonLabel: 'COMMON.ADD',
+    cancelButtonLabel: 'COMMON.CANCEL'
+  }
+};
+```
+
+## Clear Filter Behavior
+
+The "Clear Filter" button performs the following actions:
+1.  Resets all form fields to their values defined in `filterConfig.defaultValues`.
+2.  If a field is listed in `filterConfig.disabledFields`, its current value is preserved.
+3.  The `SmartForm` component is destroyed and re-initialized to ensure a clean state.
+4.  The table is automatically reloaded with the default parameters.
+
+## Theming
+
+The component uses standard CSS variables. It primarily inherits styles from the `SmartForm` and `SmartTable` components. You can customize the layout gaps and panel widths using the following variables in your `variables.scss`:
+
+```scss
+// Layout spacing
+--fts-gap: 1.5rem;
+--fts-filter-panel-width: 320px;
+--fts-footer-padding: 1rem 1.5rem;
+
+// Mobile specific
+--fts-mobile-breakpoint: 768px;
+```