platformcommons-web-lib 1.0.0

package/documentation/alert.md

@@ -0,0 +1,123 @@
+# Alert Component
+
+A customizable alert component that supports standard variants and full style overrides, now with flexible icon support.
+
+## 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 `AlertModule` in your feature module:
+
+```typescript
+import { AlertModule } from "commons-shared-web-ui";
+
+@NgModule({
+  imports: [AlertModule],
+})
+export class FeatureModule {}
+```
+
+2. Include the theme mixin in your global styles:
+
+```scss
+@use "commons-shared-web-ui/lib/modules/alert/alert.theme" as alert;
+
+// Default Theme
+:root {
+  @include alert.alert-theme();
+}
+
+// Custom Theme Override
+.custom-theme {
+  @include alert.alert-theme(
+    (
+      info-bg: #e8f0fe,
+      warning-title-color: #e65100,
+    )
+  );
+}
+```
+
+### Configuration Key Reference
+
+The `alert-theme` mixin accepts a map with the following optional keys.
+
+| Key              | Default                  | Description                          |
+| ---------------- | ------------------------ | ------------------------------------ |
+| **font-family**  | `('Roboto', sans-serif)` | Font stack for the alerts.           |
+| **padding**      | `1rem 2rem`              | Internal padding (16px 32px).        |
+| **radius**       | `0.75rem`                | Border radius (12px).                |
+| **gap**          | `1rem`                   | Gap between icon and content (16px). |
+| **icon-size**    | `1.25rem`                | Size of the icon (20px).             |
+| **title-size**   | `1rem`                   | Font size of the title (16px).       |
+| **message-size** | `0.875rem`               | Font size of the message (14px).     |
+| **info-bg**      | `#F1F3F4`                | Background for info variant.         |
+| **warning-bg**   | `#F9C80E1F`              | Background for warning variant.      |
+| **success-bg**   | `#E6F4EA`                | Background for success variant.      |
+| **error-bg**     | `#FCE8E6`                | Background for error variant.        |
+
+---
+
+## Usage & Examples
+
+### 1. Standard Variants
+
+```html
+<lib-alert variant="info">This is an info alert</lib-alert>
+<lib-alert variant="warning">This is a warning alert</lib-alert>
+<lib-alert variant="success">This is a success alert</lib-alert>
+<lib-alert variant="error">This is an error alert</lib-alert>
+```
+
+### 2. Custom Icons
+
+The alert supports automatic image detection for strings containing path separators or extensions.
+
+```html
+<!-- FontAwesome -->
+<lib-alert icon="fa-solid fa-bell">Custom Bell Icon</lib-alert>
+
+<!-- Auto-detected Image (String) -->
+<lib-alert icon="assets/icons/custom-alert.svg">Image from path</lib-alert>
+
+<!-- Material Icon (Object) -->
+<lib-alert [icon]="{ type: 'material', value: 'check_circle' }"
+  >Material Icon</lib-alert
+>
+```
+
+### 3. Styled Instance
+
+```html
+<lib-alert
+  variant="warning"
+  title="Attention Required"
+  borderRadius="0"
+  backgroundColor="#FFF9C4"
+  borderColor="#FBC02D"
+>
+  This is a highly customized warning alert.
+</lib-alert>
+```
+
+## API Reference
+
+### Inputs
+
+| Input             | Type                              | Default  | Description                                 |
+| ----------------- | --------------------------------- | -------- | ------------------------------------------- |
+| `variant`         | `AlertVariant`                    | `'info'` | Visual style variant.                       |
+| `title`           | `string`                          | `''`     | Optional title.                             |
+| `message`         | `string`                          | `''`     | Main message content.                       |
+| `icon`            | `boolean \| string \| IconConfig` | `true`   | Icon config. Supports auto-image detection. |
+| `customIcon`      | `string`                          | `''`     | Custom CSS class for icon.                  |
+| `width`           | `string`                          | -        | CSS width override.                         |
+| `borderRadius`    | `string`                          | -        | CSS border-radius override.                 |
+| `padding`         | `string`                          | -        | CSS padding override.                       |
+| `backgroundColor` | `string`                          | -        | CSS background-color override.              |
+| `fontSize`        | `string`                          | -        | CSS font-size override.                     |
+| `boxShadow`       | `string`                          | -        | CSS box-shadow override.                    |

package/documentation/button-dropdown.md

@@ -0,0 +1,126 @@
+# Button Dropdown Component
+
+The `ButtonDropdownComponent` (`<lib-button-dropdown>`) groups multiple actions under a single primary button. It perfectly mimics the behavior of the Smart Table's action menu, allowing you to use it on generic detail pages or custom headers.
+
+## Installation
+
+Import the `ButtonDropdownModule` into your feature module. Note that this is separate from the standard `ButtonModule` to support advanced routing and modal integrations.
+
+```typescript
+import { ButtonDropdownModule } from "commons-shared-web-ui";
+
+@NgModule({
+  imports: [
+    ButtonDropdownModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## Basic Usage
+
+The component looks and acts like a normal `<lib-button>` until clicked, at which point it opens a floating menu list of `actions`.
+
+### Component
+
+```typescript
+import { DropdownAction } from "commons-shared-web-ui";
+
+export class MyComponent {
+  userRecord = { id: 123, name: "John Doe" };
+
+  dropdownActions: DropdownAction[] = [
+    {
+      label: "Duplicate",
+      icon: "fa fa-copy",
+      type: "callback",
+      callback: (data) => this.duplicateRecord(data),
+    },
+    {
+      label: "Edit",
+      icon: "fa fa-edit",
+      type: "route",
+      route: "/users/:id/edit", // :id automatically replaced by userRecord.id
+    },
+    {
+      label: "Delete",
+      icon: "fa fa-trash",
+      type: "api",
+      color: "red", // Highlights the text/icon in red and adds a red hover state
+      apiUrl: "https://api.example.com/users/:id",
+      apiMethod: "DELETE",
+      confirmationNeeded: true,
+      confirmationMessage: "Are you sure you want to delete this user?",
+    },
+  ];
+
+  duplicateRecord(user: any) {
+    console.log("Duplicating", user);
+  }
+}
+```
+
+### Template
+
+```html
+<lib-button-dropdown
+  label="Actions"
+  variant="warning"
+  menuTheme="dark"
+  icon="fa fa-chevron-down"
+  [actions]="dropdownActions"
+  [data]="userRecord"
+></lib-button-dropdown>
+```
+
+## API Reference
+
+### Inputs
+
+| Input        | Type              | Default                | Description                                                          |
+| ------------ | ----------------- | ---------------------- | -------------------------------------------------------------------- |
+| `label`      | `string`          | `'Actions'`            | The main text displayed on the button.                               |
+| `variant`    | `ButtonVariant`   | `'primary'`            | The style variant for the toggle button itself.                      |
+| `menuTheme`  | `'light'\|'dark'` | `'light'`              | Toggles the dropdown menu background and text between light/dark.    |
+| `icon`       | `string`          | `'fa fa-chevron-down'` | FontAwesome or Material icon class for the button.                   |
+| `actions`    | `DropdownAction[]`| `[]`                   | Array of action configurations to display in the menu.               |
+| `data`       | `any`             | `null`                 | Context data passed to route parameter parsing or callback methods.  |
+| `disabled`   | `boolean`         | `false`                | Disables the entire dropdown button.                                 |
+
+### DropdownAction Interface
+
+| Property              | Type                                              | Description                                                                                     |
+| --------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `label`               | `string`                                          | Display text for the menu item.                                                                 |
+| `type`                | `'api' \| 'route' \| 'callback'`                  | The execution behavior of the item.                                                             |
+| `icon`                | `string`                                          | (Optional) Icon class for the item (e.g., `fa fa-edit`).                                        |
+| `variant`             | `ButtonVariant`                                   | (Optional) Applies full variant styles (primary, warning, danger, etc.) to the item block.      |
+| `color`               | `string`                                          | (Optional) Generic text color for the item. Using `'red'` triggers a destructive style.                 |
+| `disabled`            | `boolean`                                         | (Optional) Disables this specific item.                                                         |
+| `route`               | `string`                                          | (Required for `type: 'route'`) Internal path. Replaces `:prop` with `data[prop]`.               |
+| `apiUrl`              | `string`                                          | (Required for `type: 'api'`) External URL. Replaces `:prop` with `data[prop]`.                  |
+| `apiMethod`           | `'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'` | (Optional) HTTP method for `api` type. Default is `GET`.                                        |
+| `apiPayload`          | `any`                                             | (Optional) Body payload for POST/PUT/PATCH. Defaults to `data` if not provided.                 |
+| `callback`            | `(data: any) => void`                             | (Required for `type: 'callback'`) Function to execute.                                          |
+| `confirmationNeeded`  | `boolean`                                         | (Optional) Triggers a confirmation modal before execution.                                      |
+| `confirmationTitle`   | `string`                                          | (Optional) Title for the confirmation modal. Default: `'Please Confirm'`.                       |
+| `confirmationMessage` | `string`                                          | (Optional) Message for the confirmation modal.                                                  |
+
+### Outputs
+
+| Output             | Payload                                        | Description                                                          |
+| ------------------ | ---------------------------------------------- | -------------------------------------------------------------------- |
+| `actionClick`      | `{ action: DropdownAction, data: any }`        | Emitted when any item is clicked (after confirmation if applicable). |
+| `apiActionStart`   | `DropdownAction`                               | Emitted when an `api` type action begins execution.                  |
+| `apiActionSuccess` | `{ action: DropdownAction, response: any }`    | Emitted upon successful HTTP execution.                              |
+| `apiActionError`   | `{ action: DropdownAction, error: any }`       | Emitted if the HTTP execution fails.                                 |
+
+## Advanced Execution
+
+Just like the Smart Table, the `ButtonDropdownComponent` takes care of executing its own events.
+
+- **Routing:** Automatically injects the Angular `Router` and executes route changes, handling parameterized `:id` replacements.
+- **API Calls:** If an action has `type: 'api'` and an `apiUrl`, the component constructs the HTTP call, handles payload insertion, and automatically executes the HTTP request, exposing Success/Error events you can listen to if needed.
+- **Confirmations:** Setting `confirmationNeeded: true` entirely intercepts the click, opens a standard `cc-confirmation-modal` overlay, and only proceeds to the route/API/callback if the user clicks "Confirm". No extra component logic is needed!
+  - **Smart Delete Inference:** If the component detects the action is a "Delete" action (via `apiMethod: 'DELETE'`, `variant: 'danger'`, `color: 'red'`, or the word "delete" in the label), the confirmation modal automatically styles itself with a Red Warning Icon, a Red "Delete" confirm button, changes the title to "Confirm Deletion", and generates a fallback message of *"Are you sure you want to delete this item? This action cannot be undone."* if you didn't provide a Custom `confirmationMessage`!

package/documentation/button.md

@@ -0,0 +1,184 @@
+# Button Component Documentation
+
+The `ButtonComponent` is a reusable, themed button control that supports the application's design system with plug-and-play styling.
+
+## Features
+
+- **Standard Variants**: Primary, Warning, Outline, Secondary, Success, Danger, Danger-Outline.
+- **Theming**: Completely externalized theming support via SCSS mixins and CSS variables.
+- **Independent**: No global palette dependencies.
+- **Customization**: Direct input overrides for one-off styling (width, radius, color, etc.).
+
+## 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 `ButtonModule` into your feature module or `SharedModule`.
+
+```typescript
+import { ButtonModule } from "commons-shared-web-ui";
+// Adjust path based on your library structure
+
+@NgModule({
+  imports: [
+    ButtonModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## Theming & Styling
+
+The button uses **CSS Variables**. This means you can change the theme dynamically at runtime by applying a CSS class to a parent element (or the `body`).
+
+### 1. Import the Button Mixin
+
+In your application's styles (e.g., `styles.scss`):
+
+```scss
+@use "commons-shared-web-ui/src/lib/modules/button/button.theme" as button;
+```
+
+### 2. Define Default & Custom Themes
+
+Define your themes by including the mixin with different configurations.
+
+```scss
+// Default Theme (Light Mode)
+:root {
+  @include button.button-theme(); // Default button styles
+}
+
+// Dark Theme Example
+.dark-theme {
+  // Override specific vars for dark mode
+  @include button.button-theme(
+    (
+      primary-bg: #ffffff,
+      primary-color: #000000,
+      secondary-bg: #333333,
+      secondary-color: #ffffff,
+    )
+  );
+}
+
+// Custom Brand Theme
+.brand-theme {
+  @include button.button-theme(
+    (
+      primary-bg: #6200ee,
+      primary-radius: 20px,
+    )
+  );
+}
+```
+
+### 3. Switching Themes
+
+To switch themes, simply toggle the class on a parent element. The components will automatically update.
+
+```html
+<!-- Default Theme -->
+<lib-button variant="primary">Default Button</lib-button>
+
+<!-- Dark Theme -->
+<div class="dark-theme">
+  <lib-button variant="primary">Dark Mode Button</lib-button>
+</div>
+```
+
+### Configuration Key Reference
+
+The `button-theme` mixin accepts a map with the following optional keys. Any key not provided will fall back to its default value.
+
+| Key                  | Default                  | Description                        |
+| -------------------- | ------------------------ | ---------------------------------- |
+| **font-family**      | `('Roboto', sans-serif)` | Font stack for the buttons.        |
+| **font-weight**      | `500`                    | Base font weight.                  |
+| **font-size**        | `1rem`                   | Base font size (16px).             |
+| **padding**          | `0.5rem 1rem`            | Base padding (8px 16px).           |
+| **primary-bg**       | `#262125`                | Background for primary variant.    |
+| **primary-color**    | `#FFFFFF`                | Text color for primary variant.    |
+| **primary-radius**   | `0.5rem`                 | Border radius for primary variant. |
+| **warning-bg**       | `#F9C80E`                | Background for warning variant.    |
+| **secondary-bg**     | `#E8EAED`                | Background for secondary variant.  |
+| **success-bg**       | `#16A34A`                | Background for success variant.    |
+| **danger-bg**        | `#E63E30`                | Background for danger variant.     |
+| **disabled-opacity** | `0.6`                    | Opacity when disabled.             |
+
+> [!NOTE]
+> All variants support `-bg`, `-color`, `-radius`, and `-border` keys in the theme map.
+
+---
+
+## Usage & Examples
+
+### 1. Standard Variants
+
+Pre-defined styles for common use cases.
+
+```html
+<lib-button variant="primary">Primary Action</lib-button>
+<lib-button variant="warning">Warning</lib-button>
+<lib-button variant="secondary">Secondary</lib-button>
+<lib-button variant="outline">Outline</lib-button>
+<lib-button variant="success">Success</lib-button>
+<lib-button variant="danger">Danger</lib-button>
+<lib-button variant="danger-outline">Danger Outline</lib-button>
+```
+
+### 2. Flexible Icons
+
+The button supports three types of icons: FontAwesome, Material Icons, and Images.
+
+```html
+<!-- FontAwesome -->
+<lib-button icon="fa-solid fa-plus">Add Item</lib-button>
+
+<!-- Material Icons -->
+<lib-button [icon]="{ type: 'material', value: 'save' }">Save</lib-button>
+
+<!-- Image Icons (Path or URL) -->
+<lib-button [icon]="{ type: 'img', value: 'assets/google-icon.png' }"
+  >Login with Google</lib-button
+>
+```
+
+### 3. Custom Implementation (Configurable)
+
+You can customize specific instances using inputs.
+
+```html
+<lib-button
+  variant="primary"
+  width="240px"
+  borderRadius="50px"
+  backgroundColor="#6200EE"
+>
+  Custom Wide Button
+</lib-button>
+```
+
+## API Reference
+
+### Inputs
+
+| Input             | Type                                                   | Default     | Description                                              |
+| ----------------- | ------------------------------------------------------ | ----------- | -------------------------------------------------------- |
+| `variant`         | `ButtonVariant`                                        | `'primary'` | Visual style variant.                                    |
+| `type`            | `'button' \| 'submit' \| 'reset'`                      | `'button'`  | HTML button type.                                        |
+| `disabled`        | `boolean`                                              | `false`     | Whether the button is disabled.                          |
+| `icon`            | `boolean \| string \| { type: string, value: string }` | `''`        | Icon configuration. Supports FA class strings or object. |
+| `width`           | `string`                                               | -           | CSS width override.                                      |
+| `height`          | `string`                                               | -           | CSS height override.                                     |
+| `borderRadius`    | `string`                                               | -           | CSS border-radius override.                              |
+| `backgroundColor` | `string`                                               | -           | CSS background-color override.                           |
+| `color`           | `string`                                               | -           | CSS text color override.                                 |
+| `fontSize`        | `string`                                               | -           | CSS font-size override.                                  |
+| `fontWeight`      | `string`                                               | -           | CSS font-weight override.                                |
+| `border`          | `string`                                               | -           | CSS border override.                                     |

package/documentation/cards-usage-guidelines.md

@@ -0,0 +1,131 @@
+# Cards Module Documentation
+
+The `CardsModule` provides reusable, configurable card components with multi-theme support.
+
+## 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 `CardsModule` in your application module:
+
+```typescript
+import { CardsModule } from "shared-ui";
+
+@NgModule({
+  imports: [
+    CardsModule,
+    // ...
+  ],
+})
+export class AppModule {}
+```
+
+## Styling & Theming
+
+The cards rely on global CSS variables. You can override these in your app's `styles.scss` or component styles.
+
+### Themes
+
+The module supports two built-in themes:
+
+- `theme-1`: Compact, native look (Matches strict design).
+- `theme-2`: Spacious, aesthetic look.
+
+Pass the theme name to the component input: `[theme]="'theme-2'"`.
+
+## Components
+
+### 1. Card Type 1 (Text Based)
+
+Ideal for displaying financial stats or summary data.
+
+**Selector**: `<lib-card-type-1>`
+
+**Inputs**:
+
+- `config`: `CardType1Config` (Includes `width`, `height`)
+- `theme`: `'theme-1' | 'theme-2'` (Default: `theme-1`)
+
+**Output**:
+
+- `cardClick`: Emits when card is clicked.
+
+**Usage Example**:
+
+```html
+<lib-card-type-1
+  [config]="grantConfig"
+  [theme]="'theme-1'"
+  (cardClick)="onCardClick()"
+>
+</lib-card-type-1>
+```
+
+```typescript
+import { CardType1Config } from "shared-ui";
+
+grantConfig: CardType1Config = {
+  label: "TOTAL GRANT AMOUNT",
+  value: "₹ 25,00,000",
+  subtext: "Across 3 contracts",
+  width: "300px",
+  height: "150px",
+};
+
+receivedConfig: CardType1Config = {
+  label: "RECEIVED",
+  value: "₹ 18,00,000",
+  valueColor: "#00C853", // Custom color override
+  subtext: "74% Funded",
+};
+```
+
+### 2. Card Type 2 (Icon Based)
+
+Ideal for displaying metrics with an icon.
+
+**Selector**: `<lib-card-type-2>`
+
+**Inputs**:
+
+- `config`: `CardType2Config` (Includes `width`, `height`)
+- `theme`: `'theme-1' | 'theme-2'`
+
+```html
+<lib-card-type-2 [config]="beneficiaryConfig" theme="theme-2">
+</lib-card-type-2>
+```
+
+## Responsive Behavior
+
+Both card types are designed to be responsive.
+
+- The `width` and `height` properties in the `config` object accept any valid CSS unit (px, %, rem, vh, etc.).
+- Even when custom dimensions are provided, cards follow `max-width: 100%` to prevent overflow in smaller containers.
+- If no dimensions are provided, cards default to `100%` width and height, occupying the full area of their parent container.
+
+```typescript
+import { CardType2Config } from "shared-ui";
+
+beneficiaryConfig: CardType2Config = {
+  iconName: "card_membership",
+  iconBackgroundColor: "#FFF8E1",
+  iconColor: "#FF6F00",
+  label: "TOTAL BENEFICIARIES",
+  value: "45,000",
+  targetText: "Target",
+  width: "250px",
+  height: "120px",
+};
+
+// Example with Image Icon
+beneficiaryConfigWithImage: CardType2Config = {
+  iconUrl: "assets/images/custom-icon.png",
+  label: "TOTAL BENEFICIARIES",
+  value: "45,000",
+};
+```