platformcommons-web-lib 1.0.0

package/documentation/snackbar.md

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

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

@@ -0,0 +1,279 @@
+# 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/ng-package.json

@@ -0,0 +1,28 @@
+{
+    "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
+    "dest": "./dist/commons-shared-web-ui",
+    "lib": {
+        "entryFile": "src/public-api.ts"
+    },
+    "assets": [
+        "src/lib/styles/global.scss",
+        "src/lib/styles/utilities.scss",
+        "src/lib/modules/pagination/pagination.theme.scss",
+        "src/lib/modules/summary-card/summary-card.theme.scss",
+        "src/lib/modules/button/button.theme.scss",
+        "src/lib/modules/alert/alert.theme.scss",
+        "src/lib/modules/confirmation-modal/confirmation-modal.theme.scss",
+        "src/lib/modules/filter-sidebar/filter-sidebar.theme.scss",
+        "src/lib/modules/filter/filter.theme.scss",
+        "src/lib/modules/nav/nav.theme.scss",
+        "src/lib/modules/configurable-form/configurable-form.theme.scss",
+        "src/lib/modules/form-components/form-components.theme.scss",
+        "src/lib/modules/form-components/**/_theme.scss",
+        "src/lib/modules/smart-table/smart-table.theme.scss",
+        "src/lib/modules/smart-form/smart-form.theme.scss",
+        "src/lib/modules/side-nav/side-nav.theme.scss",
+        "src/lib/modules/form-builder/form-builder.theme.scss",
+        "src/lib/modules/filter-table-selector/filter-table-selector.theme.scss",
+        "src/lib/modules/snackbar/snackbar.theme.scss"
+    ]
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "platformcommons-web-lib",
+    "version": "1.0.0",
+    "peerDependencies": {
+        "@angular/animations": "20.3.15",
+        "@angular/cdk": "20.2.14",
+        "@angular/common": "20.3.15",
+        "@angular/compiler": "20.3.15",
+        "@angular/core": "20.3.15",
+        "@angular/forms": "20.3.15",
+        "@angular/material": "20.2.14",
+        "@angular/platform-browser": "20.3.15",
+        "@angular/platform-browser-dynamic": "20.3.15",
+        "@angular/router": "20.3.15",
+        "rxjs": "7.8.0",
+        "tslib": "^2.3.0",
+        "zone.js": "~0.14.0 || ~0.15.0",
+        "ngx-quill": "^28.0.0",
+        "quill": "^2.0.3"
+    },
+    "dependencies": {
+        "tslib": "^2.3.0"
+    },
+    "devDependencies": {
+        "@angular-devkit/build-angular": "20.3.13",
+        "@angular/animations": "20.3.15",
+        "@angular/cdk": "20.2.14",
+        "@angular/cli": "20.3.13",
+        "@angular/common": "20.3.15",
+        "@angular/compiler": "20.3.15",
+        "@angular/compiler-cli": "20.3.15",
+        "@angular/core": "20.3.15",
+        "@angular/forms": "20.3.15",
+        "@angular/material": "20.2.14",
+        "@angular/platform-browser": "20.3.15",
+        "@angular/platform-browser-dynamic": "20.3.15",
+        "@angular/router": "20.3.15",
+        "@types/jasmine": "~3.10.0",
+        "@types/node": "^20.11.1",
+        "jasmine-core": "~4.0.0",
+        "karma": "^6.4.4",
+        "karma-chrome-launcher": "~3.1.0",
+        "karma-coverage": "~2.1.0",
+        "karma-jasmine": "~4.0.0",
+        "karma-jasmine-html-reporter": "~1.7.0",
+        "ng-packagr": "^20.0.0",
+        "rxjs": "7.8.0",
+        "typescript": "^5.9.3",
+        "zone.js": "~0.15.0"
+    },
+    "scripts": {
+        "build": "ng-packagr -p ng-package.json"
+    }
+}

package/src/lib/modules/alert/alert.models.ts

@@ -0,0 +1,6 @@
+export type AlertVariant = 'info' | 'warning' | 'warning-shadow' | 'success' | 'error';
+export type IconInput = boolean | string | { type: 'material' | 'fontawesome' | 'img'; value: string };
+
+export interface AlertLabels {
+    iconAltText?: string;
+}

package/src/lib/modules/alert/alert.module.ts

@@ -0,0 +1,16 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { AlertComponent } from './components/alert/alert.component';
+
+@NgModule({
+    declarations: [
+        AlertComponent
+    ],
+    imports: [
+        CommonModule
+    ],
+    exports: [
+        AlertComponent
+    ]
+})
+export class AlertModule { }

package/src/lib/modules/alert/alert.theme.scss

@@ -0,0 +1,85 @@
+@use 'sass:map';
+
+$default-alert-config: (
+    font-family: ('Roboto', sans-serif),
+
+    // Structure (Default values in rem, assuming 16px root)
+    padding: 1rem 2rem,
+    // 16px 32px
+    radius: 0.75rem,
+    // 12px
+    gap: 1rem,
+    // 16px
+
+    // Icon
+    icon-size: 1.25rem,
+    // 20px
+    icon-margin-top: 0.125rem,
+    // 2px
+
+    // Text
+    title-size: 1rem,
+    // 16px
+    title-line-height: 1.5rem,
+    // 24px
+    message-size: 0.875rem,
+    // 14px
+
+    // Info
+    info-bg: #F1F3F4,
+    info-color: #3C4043,
+
+    // Warning
+    warning-bg: #F9C80E1F,
+    warning-color: #3C4043,
+    // Default text color for warning usually dark
+    warning-title-color: #3C4043,
+    // Making title dark for better contrast with light yellow bg
+    warning-shadow: none,
+    // Removing shadow as per clean flat design, or keeping if specified. User said "warning-shadow" variant exists.
+
+    // Success
+    success-bg: #E6F4EA,
+    // Light green similar to Info/Error pattern
+    success-color: #16A34A,
+
+    // Error
+    error-bg: #FCE8E6,
+    // Light red
+    error-color: #D93025
+);
+
+@mixin alert-theme($user-config: ()) {
+    $config: map.merge($default-alert-config, $user-config);
+
+    --cc-alert-font-family: #{map.get($config, font-family)};
+
+    // Structure
+    --cc-alert-padding: #{map.get($config, padding)};
+    --cc-alert-radius: #{map.get($config, radius)};
+    --cc-alert-gap: #{map.get($config, gap)};
+
+    // Icon
+    --cc-alert-icon-size: #{map.get($config, icon-size)};
+    --cc-alert-icon-margin-top: #{map.get($config, icon-margin-top)};
+
+    // Text
+    --cc-alert-title-size: #{map.get($config, title-size)};
+    --cc-alert-title-line-height: #{map.get($config, title-line-height)};
+    --cc-alert-message-size: #{map.get($config, message-size)};
+
+    // Colors
+    --cc-alert-info-bg: #{map.get($config, info-bg)};
+    --cc-alert-info-color: #{map.get($config, info-color)};
+
+    --cc-alert-warning-bg: #{map.get($config, warning-bg)};
+    --cc-alert-warning-color: #{map.get($config, warning-color)};
+    --cc-alert-warning-title-color: #{map.get($config, warning-title-color)};
+    --cc-alert-warning-shadow: #{map.get($config, warning-shadow)};
+    --cc-alert-success-bg: #{map.get($config, success-bg)};
+    --cc-alert-success-color: #{map.get($config, success-color)};
+
+    --cc-alert-error-bg: #{map.get($config, error-bg)};
+    --cc-alert-error-color: #{map.get($config, error-color)};
+    --cc-alert-warning-shadow: 0 0.25rem 0.25rem rgba(0, 0, 0, 0.25); // 0px 4px 4px
+}