commons-shared-web-ui 0.0.50 → 0.0.51

package/documentation/confirmation-modal.md

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

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

@@ -1,228 +0,0 @@
-# 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;
-```