commons-shared-web-ui 0.0.62 → 0.0.63

package/documentation/snackbar.md

@@ -1,118 +0,0 @@
-# Snackbar Component
-
-The Configurable Snackbar component (`lib-snackbar`) is a fully customizable toast-style notification module built on top of `@angular/material/snack-bar`. It supports four distinct UI variants (success, error, warning, info) and is powered by a robust SCSS CSS-variables-based theming engine matching the design system of the `nav` and `pagination` components.
-
-## Implementation Details
-
-### Module Import
-
-To use the Snackbar, import the `SnackbarModule` into your Angular application module.
-
-```typescript
-import { SnackbarModule } from "commons-shared-web-ui";
-
-@NgModule({
-  imports: [SnackbarModule],
-})
-export class AppModule {}
-```
-
-### Displaying a Snackbar Programmatically
-
-The `SnackbarService` is provided in root and handles the instantiation of the custom component template seamlessly. You inject the service into your component/service:
-
-```typescript
-import { Component } from "@angular/core";
-import { SnackbarService } from "commons-shared-web-ui";
-
-@Component({
-  selector: "app-example",
-  template: `<button (click)="submitForm()">Submit</button>`,
-})
-export class ExampleComponent {
-  constructor(private snackbarService: SnackbarService) {}
-
-  submitForm() {
-    // Show a basic success toast
-    this.snackbarService.success("Form submitted successfully!");
-
-    // Show a basic error toast
-    this.snackbarService.error("Failed to submit form.");
-  }
-}
-```
-
-### Core Service API Methods
-
-- `success(message: string, duration?: number)`
-- `error(message: string, duration?: number)`
-- `warning(message: string, duration?: number)`
-- `info(message: string, duration?: number)`
-- `show(config: SnackbarConfig)`
-
-The `show()` method provides advanced initialization:
-
-```typescript
-this.snackbarService.show({
-  message: "Custom positioned explicit alert.",
-  variant: "warning",
-  duration: 8000,
-  horizontalPosition: "center",
-  verticalPosition: "bottom",
-  showCloseButton: true,
-});
-```
-
-### Models
-
-#### `SnackbarConfig`
-
-| Property             | Type                                                | Default | Description                                                   |
-| -------------------- | --------------------------------------------------- | ------- | ------------------------------------------------------------- |
-| `message`            | `string`                                            | -       | **Required.** The primary text to display in the snackbar.    |
-| `variant`            | `'success' \| 'error' \| 'warning' \| 'info'`       | `info`  | The visual severity of the toast, driving icon and colors.    |
-| `duration`           | `number`                                            | `5000`  | Auto-dismiss duration in milliseconds.                        |
-| `horizontalPosition` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'` | `right` | Standard Material horizontal anchoring.                       |
-| `verticalPosition`   | `'top' \| 'bottom'`                                 | `top`   | Standard Material vertical anchoring.                         |
-| `showCloseButton`    | `boolean`                                           | `false` | Renders a manual "X" close button inside the toast if `true`. |
-
-## Customizing Theming & SCSS Overrides
-
-The notification toasts strictly use CSS variables that can be fully overridden in your consumer application.
-
-You can customize the styling of the snackbars globally in your application's main `styles.scss` using the exposed SCSS mixin `@include snackbar-theme(...)`.
-
-```scss
-@use "commons-shared-web-ui/lib/modules/snackbar/snackbar.theme.scss" as
-  snackbar;
-
-// Configure your application's specific branding limits
-:root {
-  @include snackbar.snackbar-theme(
-    (
-      font-family: (
-        "Roboto",
-        sans-serif,
-      ),
-      radius: 4px,
-      min-width: 350px,
-      padding: 16px 20px,
-      icon-size: 24px,
-
-      // Branding Success overrides
-      success-bg: #e8f5e9,
-      success-color: #2e7d32,
-      success-border: #c8e6c9,
-      success-icon-color: #388e3c,
-
-      // Branding Error overrides
-      error-bg: #ffebee,
-      error-color: #c62828,
-      error-border: #ef9a9a,
-      error-icon-color: #d32f2f,
-    )
-  );
-}
-```
-
-If you only want to style the snackbar component exclusively within a nested layout or micro-frontend element space, simply invoke the mixin inside a constrained selector instead of `:root`.

package/documentation/style-externalization.md

@@ -1,88 +0,0 @@
-# Style Externalization Guide
-
-This guide describes the recommended pattern for externalizing styles in the shared UI library. This approach allows consuming applications (MFEs, Shell) to have full control over the visual appearance of components without modifying the library code.
-
-## The Approach: Mixin + CSS Variables
-
-The core idea is to separate the **Theme Definition** (colors, fonts, etc.) from the **Component Implementation** (layout, structure).
-
-1.  **Library provides a Mixin**: The shared library exports a SCSS mixin that accepts a configuration map.
-2.  **Mixin generates CSS Variables**: The mixin processes the map and outputs CSS Custom Properties (Variables).
-3.  **Component uses CSS Variables**: The component's SCSS file uses _only_ `var(--...)` for dynamic styles.
-4.  **Consumer applies Mixin**: The parent app imports the mixin and generates the specific theme classes it needs.
-
-## Implementation Steps for Library Developers
-
-### 1. Create a `_theme.scss` file
-
-Create a file next to your component (e.g., `my-component.theme.scss`).
-
-```scss
-@use "sass:map";
-
-// 1. Define Defaults
-$default-config: (
-  primary-color: #007bff,
-  bg-color: #ffffff,
-  border-radius: 4px,
-);
-
-// 2. Create the Mixin
-@mixin my-component-theme($user-config: ()) {
-  $config: map.merge($default-config, $user-config);
-
-  // 3. Output Variables
-  --cc-comp-primary: #{map.get($config, primary-color)};
-  --cc-comp-bg: #{map.get($config, bg-color)};
-  --cc-comp-radius: #{map.get($config, border-radius)};
-}
-```
-
-### 2. Update Component SCSS
-
-Refactor `my-component.component.scss` to use the variables.
-
-```scss
-.my-component {
-  background-color: var(--cc-comp-bg);
-  border-radius: var(--cc-comp-radius);
-
-  .btn {
-    background-color: var(--cc-comp-primary);
-  }
-}
-```
-
-## Usage for Application Developers
-
-In your application's `styles.scss`:
-
-```scss
-@use "path/to/shared-ui/my-component.theme" as myComp;
-
-// Define a Light Theme
-.light-theme-app {
-  @include myComp.my-component-theme(
-    (
-      primary-color: blue,
-      bg-color: white,
-    )
-  );
-}
-
-// Define a Dark Theme
-.dark-theme-app {
-  @include myComp.my-component-theme(
-    (
-      primary-color: lightblue,
-      bg-color: #333,
-    )
-  );
-}
-```
-
-## Benefits
-
-- **True Decoupling**: The library has no opinion on the "Dark Mode" implementation of the parent app.
-- **Responsiveness**: CSS variables are runtime-dynamic.
-- **Maintenance**: Adding a new style parameter (e.g., specific padding) is as easy as adding a variable map.

package/documentation/summary-card.md

@@ -1,279 +0,0 @@
-# Summary Card Component Documentation
-
-The `SummaryCardComponent` is a flexible and themeable card component for displaying key metrics and information with support for icons, images, and customizable layouts.
-
-## Features
-
-- **Icon or Image Support**: Display either a Material icon or custom image
-- **Flexible Description Layout**: Position description text either below the value (default) or inline (right side)
-- **Fully Configurable Colors**: Customize colors for value, header, description, icon, and icon background
-- **Theme Support**: Two built-in themes (theme-1: clean/minimal, theme-2: aesthetic/modern)
-- **Responsive Design**: Mobile-friendly with responsive breakpoints
-- **Click Interaction**: Optional click events with disabled state support
-- **Theming**: Completely externalized theming support via SCSS mixins
-
-## 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
-```
-
-Import the `SummaryCardModule` into your feature module or `SharedModule`.
-
-```typescript
-import { SummaryCardModule } from "@campus-cloud/shared-ui";
-
-@NgModule({
-  imports: [
-    SummaryCardModule,
-    // ...
-  ],
-})
-export class MyFeatureModule {}
-```
-
-## Theming & Styling
-
-The Summary Card Module uses a **Theme Externalization** pattern. It does not ship with hardcoded themes. Instead, the usage context (Parent App) **MUST** define the theme using the provided SCSS mixin.
-
-### 1. Import the Mixin
-
-In your application's global styles (e.g., `styles.scss` or a dedicated theme file):
-
-```scss
-@use "commons-shared-web-ui/src/lib/modules/summary-card/summary-card.theme"
-  as summary-card;
-```
-
-### 2. Define Your Theme
-
-Create a class (or apply to `:root`) and include the mixin.
-
-#### Option A: Use Defaults (No Override)
-
-If you want the default look but still need the styles to load:
-
-```scss
-.default-theme-summary-card {
-  @include summary-card.summary-card-theme();
-}
-```
-
-#### Option B: Override Specific Values
-
-Pass only the variables you want to change.
-
-```scss
-.my-custom-theme {
-  @include summary-card.summary-card-theme(
-    (
-      theme-1-bg: #ffffff,
-      theme-2-shadow: 0 10px 30px -10px rgba(0, 0, 0, 0.1),
-    )
-  );
-}
-```
-
-### 3. Usage in App
-
-Apply the theme class to the wrapper of the summary card component.
-
-```html
-<div class="default-theme-summary-card">
-  <lib-summary-card
-    [config]="cardConfig"
-    [theme]="'theme-1'"
-  ></lib-summary-card>
-</div>
-```
-
-### Configuration Key Reference
-
-The `summary-card-theme` mixin accepts a map with the following optional keys. Any key not provided will fall back to its default value.
-
-| Key                | Default                                | Description                        |
-| ------------------ | -------------------------------------- | ---------------------------------- |
-| **theme-1-border** | `1px solid #e8eaed`                    | Border for theme-1 cards           |
-| **theme-1-shadow** | `0 1px 3px rgba(0, 0, 0, 0.1)`         | Shadow for theme-1 cards           |
-| **theme-1-bg**     | `#ffffff`                              | Background color for theme-1 cards |
-| **theme-2-border** | `none`                                 | Border for theme-2 cards           |
-| **theme-2-shadow** | `0 10px 30px -10px rgba(0, 0, 0, 0.1)` | Shadow for theme-2 cards           |
-| **theme-2-bg**     | `#ffffff`                              | Background color for theme-2 cards |
-
-### FAQ: Theme Configuration
-
-**Q: Where should I put the theme configuration?**
-A: In the `styles.scss` (or equivalent global stylesheet) of the application that is **rendering** the component.
-
-- If used in a **Remote MFE**: Define it in the MFE's `styles.scss`.
-- If used in the **Shell**: Define it in the Shell's `styles.scss`.
-
-**Q: Do I have to import it if I don't want to override anything?**
-A: **Yes**. The component relies 100% on CSS variables. If you do not include the mixin (even without arguments), variables will be undefined, and the component will look broken. Use `Option A` above to get the default look.
-
----
-
-## API Reference
-
-### Inputs
-
-| Input    | Type                     | Default     | Description               |
-| -------- | ------------------------ | ----------- | ------------------------- |
-| `config` | `SummaryCardConfig`      | required    | Card configuration object |
-| `theme`  | `'theme-1' \| 'theme-2'` | `'theme-1'` | Theme variant             |
-
-### Outputs
-
-| Output      | Type                 | Description                  |
-| ----------- | -------------------- | ---------------------------- |
-| `cardClick` | `EventEmitter<void>` | Emitted when card is clicked |
-
-### SummaryCardConfig Interface
-
-| Property              | Type                   | Default       | Description                              |
-| --------------------- | ---------------------- | ------------- | ---------------------------------------- |
-| `header`              | `string`               | required      | Header text (usually uppercase label)    |
-| `value`               | `string`               | required      | Main value to display                    |
-| `description`         | `string`               | optional      | Additional description text              |
-| `icon`                | `string`               | optional      | Material icon name (e.g., 'location_on') |
-| `iconImage`           | `string`               | optional      | URL for custom image icon                |
-| `descriptionPosition` | `'bottom' \| 'inline'` | `'bottom'`    | Position of description text             |
-| `valueColor`          | `string`               | theme default | Custom color for value text              |
-| `headerColor`         | `string`               | theme default | Custom color for header text             |
-| `descriptionColor`    | `string`               | theme default | Custom color for description text        |
-| `iconColor`           | `string`               | theme default | Custom color for icon                    |
-| `iconBackgroundColor` | `string`               | theme default | Background color for icon container      |
-| `iconClass`           | `string`               | optional      | Additional CSS classes for icon          |
-| `valueClass`          | `string`               | optional      | Additional CSS classes for value         |
-| `headerClass`         | `string`               | optional      | Additional CSS classes for header        |
-| `descriptionClass`    | `string`               | optional      | Additional CSS classes for description   |
-| `isDisabled`          | `boolean`              | `false`       | Disable click interaction                |
-| `isClickable`         | `boolean`              | `true`        | Whether card is clickable                |
-
-## Usage Examples
-
-### Basic Example
-
-```typescript
-import { SummaryCardModule } from "shared-ui";
-
-// In your component
-cardConfig = {
-  header: "TOTAL GRANT AMOUNT",
-  value: "₹ 25,00,000",
-  description: "Across 3 campaigns",
-};
-```
-
-```html
-<lib-summary-card
-  [config]="cardConfig"
-  [theme]="'theme-1'"
-  (cardClick)="onCardClick()"
->
-</lib-summary-card>
-```
-
-### With Icon
-
-```typescript
-cardConfig = {
-  header: "APPROVED STATES",
-  value: "02",
-  description: "Karnataka, Maharashtra",
-  icon: "location_on",
-  iconBackgroundColor: "#fff0f0",
-  iconColor: "#c21e25",
-};
-```
-
-### With Image
-
-```typescript
-cardConfig = {
-  header: "TOTAL BENEFICIARIES",
-  value: "45,000",
-  description: "Target",
-  iconImage: "assets/icons/beneficiaries.png",
-  iconBackgroundColor: "#fff7e6",
-  iconColor: "#fa8c16",
-};
-```
-
-### With Inline Description
-
-```typescript
-cardConfig = {
-  header: "RECCE STATUS",
-  value: "Completed",
-  description: "75% Approval Rate",
-  descriptionPosition: "inline", // Description appears on the right side of value
-  valueColor: "#52c41a",
-};
-```
-
-### With Custom Colors
-
-```typescript
-cardConfig = {
-  header: "EXPECTED IMPACT",
-  value: "2,150",
-  description: "Beneficiaries found",
-  valueColor: "#1890ff",
-  headerColor: "#8c8c8c",
-  descriptionColor: "#595959",
-};
-```
-
-## Themes
-
-### Theme 1 (Clean & Minimal)
-
-- Clean borders and subtle shadows
-- Compact padding
-- Professional appearance
-- Best for dashboard layouts
-
-### Theme 2 (Aesthetic & Modern)
-
-- No borders, elevated shadows
-- Generous padding
-- Modern gradient icon backgrounds
-- Best for landing pages and marketing content
-
-## Responsive Design
-
-The component automatically adjusts for mobile devices:
-
-- Icon margins reduce on smaller screens
-- Font sizes scale down appropriately
-- Maintains readability and touch targets
-
-## Accessibility
-
-- Semantic HTML structure
-- Proper color contrast ratios
-- Click events respect disabled state
-- Icon alt text support for images
-
-## Playground Example
-
-You can use the following configuration in the UI Playground to test the component:
-
-```json
-{
-  "config": {
-    "header": "TOTAL GRANT AMOUNT",
-    "value": "₹ 25,00,000",
-    "description": "Across 3 campaigns",
-    "icon": "work_outline",
-    "iconBackgroundColor": "#E3F2FD",
-    "iconColor": "#1976D2"
-  },
-  "labels": {
-    "iconAlt": "Grant Icon"
-  }
-}
-```

package/documentation/table-column-configuration.md

@@ -1,221 +0,0 @@
-# Table Column Configuration Module
-
-The `TableColumnConfigurationModule` provides a single component, `lib-table-column-configuration`, that lets an **end user** decide which **columns** of a Smart Table are **visible**, without touching the config by hand.
-
-It takes a `TableConfig` (the same config format used by `SmartTableModule`) as input and produces a **modified copy** of that config on demand. It is the table counterpart of [`lib-form-field-configuration`](./form-field-configuration.md) and is designed to be dropped inside a `cc-confirmation-modal` (a "Configure columns" dialog) on any list page.
-
-> The component only edits one thing per column: **visibility** (`isEnabled` / `visible`). It never changes labels, types, sorting, actions, or any other part of the config — only the `columns` array's visibility flags.
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [How it works](#how-it-works)
-- [API Reference](#api-reference)
-- [Locking columns (non-hideable)](#locking-columns-non-hideable)
-- [Input → Output config](#input--output-config)
-- [Translating labels](#translating-labels)
-- [Making the table honour hidden columns](#making-the-table-honour-hidden-columns)
-- [Styling / theming](#styling--theming)
-
----
-
-## Installation
-
-Import `TableColumnConfigurationModule` (and, typically, `ConfirmationModalModule`) into your Angular module:
-
-```typescript
-import {
-  TableColumnConfigurationModule,
-  ConfirmationModalModule,
-} from 'commons-shared-web-ui';
-
-@NgModule({
-  imports: [
-    TableColumnConfigurationModule,
-    ConfirmationModalModule,
-  ],
-})
-export class DonorsModule {}
-```
-
----
-
-## Quick Start
-
-Put the component inside your "Configure columns" modal and read the result back on confirm using a template reference and `getUpdatedConfig()`.
-
-```html
-<button (click)="openConfigure = true">Configure columns</button>
-
-<cc-confirmation-modal
-  [isOpen]="openConfigure"
-  [config]="{
-    title: 'Configure columns',
-    subtitle: 'Donors',
-    confirmButton: { label: 'Save changes', type: 'primary' },
-    size: 'md'
-  }"
-  (confirm)="onSaveColumnConfig()"
-  (cancel)="openConfigure = false"
-  (close)="openConfigure = false"
->
-  <lib-table-column-configuration
-    #columnConfig
-    [config]="tableConfig"
-    [translate]="translateFn"
-  />
-</cc-confirmation-modal>
-```
-
-```typescript
-import { ViewChild } from '@angular/core';
-import { TableColumnConfigurationComponent, TableConfig } from 'commons-shared-web-ui';
-
-export class DonorsPage {
-  openConfigure = false;
-  tableConfig: TableConfig = /* your master config */;
-
-  @ViewChild('columnConfig') columnConfig!: TableColumnConfigurationComponent;
-
-  // Optional: wire your i18n instant() so labels aren't raw keys
-  translateFn = (key: string) => this.translate.instant(key);
-
-  onSaveColumnConfig(): void {
-    const updated = this.columnConfig.getUpdatedConfig();
-    if (updated) {
-      this.tableConfig = updated;      // hand back the modified config
-      // persist it / feed it to <lib-smart-table>, etc.
-    }
-    this.openConfigure = false;
-  }
-}
-```
-
-The dialog chrome (title, "Cancel" / "Save changes" buttons, scrolling body) is provided by `cc-confirmation-modal`. `lib-table-column-configuration` renders only the legend and the configurable column list.
-
----
-
-## How it works
-
-1. You pass a `TableConfig` via `[config]`.
-2. The component **deep-clones** the config internally, so your object is **never mutated**.
-3. It walks `config.columns` and renders one row per column with its label and a **visibility** toggle.
-4. The user toggles visibility.
-5. When you call `getUpdatedConfig()`, the current selections are written back onto the clone (`isEnabled` / `visible` per column) and a fresh copy is returned.
-
-Only the `columns` array is touched. `actions`, `topBarButtons`, `pagination`, `searchConfig`, etc. pass through untouched.
-
----
-
-## API Reference
-
-| Input / Output / Method | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `[config]` | `TableConfig` | — | **Required.** The table config to configure. Deep-cloned internally; never mutated. |
-| `[translate]` | `(key: string) => string` | `undefined` | Optional label translator (e.g. ngx-translate `instant`). Applied to each column label at render time. |
-| `[showLegend]` | `boolean` | `true` | Show the "👁 Visible" legend row. |
-| `getUpdatedConfig()` | `() => TableConfig \| null` | — | **Method.** Returns a fresh, modified copy of the config with the current visibility choices applied. Returns `null` if no config has been loaded. Call it from your modal's confirm handler. |
-
-The component is `OnPush` and self-contained — it does **not** emit a live change event. Read the result on demand via `getUpdatedConfig()`.
-
----
-
-## Locking columns (non-hideable)
-
-Some columns must always be present — e.g. you can't hide **Donor Name**. Mark them in the config with `lockVisibility` on the column:
-
-| Flag | Effect in the configurator |
-| :--- | :--- |
-| `lockVisibility: true` | The visibility toggle is replaced by a 🔒 lock icon. The column is always visible and cannot be turned off. |
-
-```jsonc
-{
-  "key": "name",
-  "label": "PROGRAM_MANAGEMENT.DONORS.COLUMNS.DONOR_NAME",
-  "type": "text",
-  "sortable": true,
-  "lockVisibility": true    // can never be hidden
-}
-```
-
----
-
-## Input → Output config
-
-The component maps its one control onto the column's visibility flags, so the output plugs straight back into `<lib-smart-table>`:
-
-| UI control | Written to `TableColumn` |
-| :--- | :--- |
-| Visibility toggle | `isEnabled`, `visible` (both `true`/`false`) |
-
-**Example — before:**
-
-```jsonc
-{ "key": "website", "label": "...WEBSITE", "type": "text", "sortable": false }
-```
-
-**After the user hides it:**
-
-```jsonc
-{ "key": "website", "label": "...WEBSITE", "type": "text", "sortable": false,
-  "isEnabled": false, "visible": false }
-```
-
-A column defaults to visible when both `isEnabled` and `visible` are absent.
-
----
-
-## Translating labels
-
-Configs usually store i18n **keys** in `label` (e.g. `PROGRAM_MANAGEMENT.DONORS.COLUMNS.DONOR_NAME`). Pass a `translate` function to render human-readable labels — exactly like `lib-form-field-configuration`:
-
-```typescript
-translateFn = (key: string) => this.translate.instant(key);
-```
-
-```html
-<lib-table-column-configuration [config]="tableConfig" [translate]="translateFn" />
-```
-
-If `translate` is omitted, the raw label (or `key`) is shown. Translation is display-only — the output config keeps the original keys.
-
----
-
-## Making the table honour hidden columns
-
-The configurator writes `isEnabled: false` onto hidden columns (the same convention `SmartTable` already uses for actions via `isEnabled !== false`). If your Smart Table should stop rendering hidden columns, filter them where you build/pass the config, e.g.:
-
-```typescript
-const visibleConfig = {
-  ...updated,
-  columns: updated.columns.filter(c => c.isEnabled !== false),
-};
-```
-
----
-
-## Styling / theming
-
-The toggle and lock are **self-contained** (drawn in the module's own CSS) so they stay compact in the dense row. Everything ships neutral defaults and is themeable via CSS custom properties. Override any of these on a parent element:
-
-| Variable | Purpose | Default |
-| :--- | :--- | :--- |
-| `--tcc-toggle-on-bg` | Visibility toggle when ON | `#2f9e6f` (green) |
-| `--tcc-toggle-off-bg` | Visibility toggle when OFF | `#cbd2d9` |
-| `--tcc-toggle-width` / `--tcc-toggle-height` | Toggle pill size | `38px` / `22px` |
-| `--tcc-col-label-color` | Column label colour | `#1f2933` |
-| `--tcc-count-color` (legend) | Legend text colour | `#52606d` |
-| `--tcc-col-bg` / `--tcc-col-hover-bg` | Column row background / hover | `#ffffff` / `#f8fafc` |
-| `--tcc-eye-color` / `--tcc-eye-off-color` | Visible / hidden eye icon | `#6b7280` / `#b0b6be` |
-| `--tcc-lock-color` | Lock icon colour | `#9aa2ab` |
-
-Example — recolour the toggle to your brand:
-
-```css
-lib-table-column-configuration {
-  --tcc-toggle-on-bg: #1a73e8;
-}
-```