platformcommons-web-lib 1.0.0

package/documentation/nav.md

@@ -0,0 +1,427 @@
+# Nav Component Documentation
+
+The `NavComponent` is a reusable, configurable navigation control that supports multiple design variants and plug-and-play theming via SCSS mixins and CSS variables.
+
+## Features
+
+- **Multiple Variants**: Ships with three visual styles — `filled`, `underline`, and `pills` — switchable via a single input.
+- **Configurable Items**: Accepts an array of navigation items, each with optional icon, badge count, and disabled state.
+- **Active State Management**: Tracks the selected item via `activeId` and highlights it. Supports an active indicator border (e.g., a red bottom/top border).
+- **Orientation**: Supports `horizontal` (default) and `vertical` layouts.
+- **Theming**: Completely externalized theming support via the Style Externalization pattern.
+- **Styling Overrides**: Per-instance customization via a single `styleConfig` object — no SCSS needed.
+- **Responsive**: Adapts to mobile screens (scrollable horizontal nav or stacking).
+- **i18n Support**: All item labels are passed from the consumer; the component renders whatever strings are provided.
+
+---
+
+## Design Variants
+
+The component ships with three built-in visual variants. The variant is selected via the `variant` input and the visual appearance is controlled entirely by CSS variables.
+
+### Variant 1: `filled` (Default)
+
+The active item has a solid background, creating a "tab" look. Best suited for primary navigation bars.
+
+| Element          | Visual                                                                          |
+| :--------------- | :------------------------------------------------------------------------------ |
+| Container        | Light background (`container-bg`), full width.                                  |
+| Inactive Item    | Transparent background, default text color.                                     |
+| Active Item      | Filled background (`item-active-bg`), bold/contrast text (`item-active-color`). |
+| Active Indicator | Optional bottom border via `item-active-border-color`.                          |
+
+**Use Case**: Top-of-page tab bars (e.g., "Open Tickets / Resolved / Audit").
+
+### Variant 2: `underline`
+
+Minimal style. Active item is indicated by a bottom border line. No background fills.
+
+| Element       | Visual                                                                  |
+| :------------ | :---------------------------------------------------------------------- |
+| Container     | Transparent background with an optional bottom border.                  |
+| Inactive Item | Default text, no background.                                            |
+| Active Item   | Accent text color + a thick bottom border (`item-active-border-color`). |
+| Hover         | Subtle bottom border preview on hover.                                  |
+
+**Use Case**: Sub-section navigation, secondary tabs inside a card or panel.
+
+### Variant 3: `pills`
+
+Active item gets a pill-shaped (fully rounded) background. Inactive items are plain text.
+
+| Element       | Visual                                                           |
+| :------------ | :--------------------------------------------------------------- |
+| Container     | Transparent, typically with some gap between items.              |
+| Inactive Item | Default text, transparent background.                            |
+| Active Item   | Pill-shaped filled background (`item-active-bg`), contrast text. |
+| Hover         | Slightly tinted hover background.                                |
+
+**Use Case**: Filter selectors, toggle groups, compact navigation in toolbars.
+
+---
+
+## 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 `NavModule` into your feature module or `SharedModule`.
+
+```typescript
+import { NavModule } from "@campus-cloud/shared-ui";
+
+@NgModule({
+  imports: [
+    NavModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+---
+
+## Theming & Styling
+
+The Nav Module uses the **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/nav/nav.theme" as nav;
+```
+
+### 2. Define Your Theme
+
+Create a class (or apply to `:root`) and include the mixin.
+
+#### Option A: Use Defaults (No Override)
+
+```scss
+.default-theme-nav {
+  @include nav.nav-theme();
+}
+```
+
+#### Option B: Override Specific Values
+
+```scss
+.my-app-nav-theme {
+  @include nav.nav-theme(
+    (
+      item-active-bg: #1a1a2e,
+      item-active-color: #ffffff,
+      item-active-border-color: #e74c3c,
+    )
+  );
+}
+```
+
+#### Option C: Dark Theme Example
+
+```scss
+.dark-theme-nav {
+  @include nav.nav-theme(
+    (
+      container-bg: #1e1e2f,
+      item-color: #a0a0b0,
+      item-active-bg: #2a2a3d,
+      item-active-color: #ffffff,
+      item-active-border-color: #ff4081,
+      item-hover-bg: #25253a,
+    )
+  );
+}
+```
+
+### 3. Usage in App
+
+Apply the theme class to the wrapper of the nav component.
+
+```html
+<div class="my-app-nav-theme">
+  <lib-nav
+    [items]="navItems"
+    [activeId]="currentTab"
+    variant="filled"
+    (selectionChange)="onTabChange($event)"
+  >
+  </lib-nav>
+</div>
+```
+
+### Configuration Key Reference
+
+The `nav-theme` mixin accepts a map with the following optional keys. Any key not provided will fall back to its default value.
+
+#### Container
+
+| Key                   | Default   | Description                                       |
+| --------------------- | --------- | ------------------------------------------------- |
+| **container-bg**      | `#f5f5f5` | Background color of the nav bar container.        |
+| **container-padding** | `4px`     | Internal padding of the container.                |
+| **container-radius**  | `6px`     | Border radius of the container.                   |
+| **container-border**  | `none`    | Border of the container (e.g., `1px solid #ddd`). |
+| **container-gap**     | `4px`     | Gap between nav items.                            |
+
+#### Item (Default State)
+
+| Key              | Default                | Description                            |
+| ---------------- | ---------------------- | -------------------------------------- |
+| **font-family**  | `'Roboto', sans-serif` | Font stack for item text.              |
+| **font-size**    | `14px`                 | Font size for item text.               |
+| **font-weight**  | `500`                  | Font weight for item text.             |
+| **item-color**   | `#666666`              | Default text color for inactive items. |
+| **item-bg**      | `transparent`          | Background color for inactive items.   |
+| **item-padding** | `8px 16px`             | Padding inside each item.              |
+| **item-radius**  | `4px`                  | Border radius of each item.            |
+| **item-border**  | `none`                 | Border for inactive items.             |
+
+#### Item (Active State)
+
+| Key                          | Default                     | Description                                          |
+| ---------------------------- | --------------------------- | ---------------------------------------------------- |
+| **item-active-bg**           | `#ffffff`                   | Background of the active item.                       |
+| **item-active-color**        | `#1a1a1a`                   | Text color of the active item.                       |
+| **item-active-font-weight**  | `600`                       | Font weight of the active item.                      |
+| **item-active-border-color** | `transparent`               | Bottom or top border color for the active indicator. |
+| **item-active-border-width** | `2px`                       | Thickness of the active indicator border.            |
+| **item-active-shadow**       | `0 1px 3px rgba(0,0,0,0.1)` | Box shadow on the active item.                       |
+
+#### Item (Hover State)
+
+| Key                  | Default   | Description                |
+| -------------------- | --------- | -------------------------- |
+| **item-hover-bg**    | `#eeeeee` | Background color on hover. |
+| **item-hover-color** | `#333333` | Text color on hover.       |
+
+#### Item (Disabled State)
+
+| Key                  | Default | Description                |
+| -------------------- | ------- | -------------------------- |
+| **disabled-opacity** | `0.5`   | Opacity of disabled items. |
+
+#### Badge
+
+| Key                 | Default   | Description                           |
+| ------------------- | --------- | ------------------------------------- |
+| **badge-bg**        | `#e74c3c` | Background color of the badge circle. |
+| **badge-color**     | `#ffffff` | Text color inside the badge.          |
+| **badge-size**      | `18px`    | Size (width/height) of the badge.     |
+| **badge-font-size** | `10px`    | Font size of the badge text.          |
+
+### 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 like `--cc-nav-container-bg` will be undefined, and the component will look broken (transparent, unstyled). Use `Option A` above to get the default look.
+
+**Q: How do I get the "red border" active indicator?**
+A: Override `item-active-border-color` in your theme configuration:
+
+```scss
+.my-theme {
+  @include nav.nav-theme(
+    (
+      item-active-border-color: #e74c3c,
+    )
+  );
+}
+```
+
+**Q: Theme vs `styleConfig` — when to use which?**
+A: Use the **Theme Mixin** (SCSS) when you want a consistent brand look across all `<lib-nav>` instances. Use **`styleConfig`** when you need a one-off customization for a specific instance.
+
+---
+
+## Responsive Design
+
+The component is built with Flexbox and includes a mobile breakpoint at `600px`.
+
+- **Desktop (horizontal)**: Items are laid out in a row. Overflow scrolls if items exceed container width.
+- **Mobile (horizontal)**: Items become scrollable (horizontal scroll with hidden scrollbar) for touch-friendly navigation.
+- **Vertical orientation**: Items stack top-to-bottom. No responsive change needed since it already stacks.
+
+---
+
+## API Reference
+
+### Inputs
+
+| Input         | Type                                 | Default        | Description                                            |
+| ------------- | ------------------------------------ | -------------- | ------------------------------------------------------ |
+| `items`       | `NavItem[]`                          | `[]`           | Array of navigation items to display.                  |
+| `activeId`    | `string \| number \| null`           | `null`         | The `id` of the currently active item.                 |
+| `variant`     | `'filled' \| 'underline' \| 'pills'` | `'filled'`     | Visual style of the navigation.                        |
+| `orientation` | `'horizontal' \| 'vertical'`         | `'horizontal'` | Layout direction.                                      |
+| `styleConfig` | `NavStyleConfig`                     | `{}`           | Object for per-instance styling overrides (see below). |
+
+### Styling Overrides via `styleConfig`
+
+All styling overrides are bundled into a single `NavStyleConfig` object. Import it from the library:
+
+```typescript
+import { NavStyleConfig } from "@campus-cloud/shared-ui";
+```
+
+#### `NavStyleConfig` Interface
+
+```typescript
+export interface NavStyleConfig {
+  // Container
+  width?: string;
+  backgroundColor?: string;
+  borderRadius?: string;
+  border?: string;
+  padding?: string;
+  gap?: string;
+  boxShadow?: string;
+
+  // Item
+  itemColor?: string;
+  itemRadius?: string;
+  itemPadding?: string;
+  fontSize?: string;
+  fontWeight?: string;
+
+  // Active Item
+  activeItemBg?: string;
+  activeItemColor?: string;
+  activeItemFontWeight?: string;
+  activeItemBorderColor?: string;
+
+  // Hover Item
+  hoverItemBg?: string;
+  hoverItemColor?: string;
+
+  // Badge
+  badgeBg?: string;
+  badgeColor?: string;
+}
+```
+
+#### Property Reference
+
+| Property                | Maps to CSS Variable / Style        | Description                    |
+| ----------------------- | ----------------------------------- | ------------------------------ |
+| `width`                 | `style.width`                       | Container width.               |
+| `backgroundColor`       | `--cc-nav-container-bg`             | Container background.          |
+| `borderRadius`          | `--cc-nav-container-radius`         | Container border radius.       |
+| `border`                | `--cc-nav-container-border`         | Container border.              |
+| `padding`               | `--cc-nav-container-padding`        | Container padding.             |
+| `gap`                   | `--cc-nav-container-gap`            | Gap between items.             |
+| `boxShadow`             | `style.box-shadow`                  | Container box shadow.          |
+| `itemColor`             | `--cc-nav-item-color`               | Inactive item text color.      |
+| `itemRadius`            | `--cc-nav-item-radius`              | Item border radius.            |
+| `itemPadding`           | `--cc-nav-item-padding`             | Item padding.                  |
+| `fontSize`              | `--cc-nav-font-size`                | Item font size.                |
+| `fontWeight`            | `--cc-nav-font-weight`              | Item font weight.              |
+| `activeItemBg`          | `--cc-nav-item-active-bg`           | Active item background.        |
+| `activeItemColor`       | `--cc-nav-item-active-color`        | Active item text color.        |
+| `activeItemFontWeight`  | `--cc-nav-item-active-font-weight`  | Active item font weight.       |
+| `activeItemBorderColor` | `--cc-nav-item-active-border-color` | Active indicator border color. |
+| `hoverItemBg`           | `--cc-nav-item-hover-bg`            | Hover background color.        |
+| `hoverItemColor`        | `--cc-nav-item-hover-color`         | Hover text color.              |
+| `badgeBg`               | `--cc-nav-badge-bg`                 | Badge background color.        |
+| `badgeColor`            | `--cc-nav-badge-color`              | Badge text color.              |
+
+### NavItem Interface
+
+```typescript
+export interface NavItem {
+  id: string | number; // Unique identifier for the item.
+  label: string; // Display text (supports i18n — pass translated strings).
+  icon?: string; // Optional icon class (e.g., 'home', 'settings').
+  badge?: string | number; // Optional badge value (e.g., count of unread items).
+  disabled?: boolean; // If true, the item is non-clickable and visually dimmed.
+}
+```
+
+### Usage Examples
+
+#### Basic Usage (with theme class)
+
+```html
+<div class="my-app-nav-theme">
+  <lib-nav
+    [items]="navItems"
+    [activeId]="currentTab"
+    variant="filled"
+    (selectionChange)="onTabChange($event)"
+  >
+  </lib-nav>
+</div>
+```
+
+#### With `styleConfig` Overrides
+
+```typescript
+// component.ts
+import { NavItem, NavStyleConfig } from '@campus-cloud/shared-ui';
+
+navItems: NavItem[] = [
+  { id: 'open', label: 'Open Tickets' },
+  { id: 'resolved', label: 'Resolved' },
+  { id: 'audit', label: 'Audit', badge: 3 },
+];
+
+currentTab = 'open';
+
+navStyle: NavStyleConfig = {
+  backgroundColor: '#ffffff',
+  borderRadius: '8px',
+  gap: '1rem',
+  padding: '0.5rem 1rem',
+  itemColor: '#666',
+  activeItemColor: '#d32f2f',
+  activeItemBorderColor: '#d32f2f',
+};
+
+onTabChange(item: NavItem): void {
+  this.currentTab = item.id;
+}
+```
+
+```html
+<!-- template.html -->
+<lib-nav
+  [items]="navItems"
+  [activeId]="currentTab"
+  variant="underline"
+  [styleConfig]="navStyle"
+  (selectionChange)="onTabChange($event)"
+>
+</lib-nav>
+```
+
+### Outputs
+
+| Output            | Type                    | Description                                                                                 |
+| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `selectionChange` | `EventEmitter<NavItem>` | Emitted when the user clicks a non-disabled item. Payload is the selected `NavItem` object. |
+
+---
+
+## File Structure
+
+```
+src/lib/modules/nav/
+├── nav.module.ts
+├── nav.models.ts          ← NavStyleConfig interface
+├── nav.theme.scss
+└── components/
+    └── nav/
+        ├── nav.component.ts
+        ├── nav.component.html
+        └── nav.component.scss
+```

package/documentation/pagination.md

@@ -0,0 +1,181 @@
+# Pagination Component Documentation
+
+The `PaginationComponent` is a reusable, dynamic pagination control that supports plug-and-play theming via SCSS mixins and CSS variables.
+
+## Features
+
+- **Dynamic Paging**: Automatically calculates pages based on `totalItems` and `itemsPerPage`.
+- **Configurable Items Per Page**: Dropdown to select page size. Automatically hides if only one option is provided.
+- **Theming**: Completely externalized theming support.
+- **Responsive**: Adapts to mobile screens (wraps and stacks controls).
+- **i18n Support**: Configurable labels for "items", "of", and "Per Page".
+
+## 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 `PaginationModule` into your feature module or `SharedModule`.
+
+```typescript
+import { PaginationModule } from "@campus-cloud/shared-ui";
+// Adjust path based on your library structure
+
+@NgModule({
+  imports: [
+    PaginationModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## Theming & Styling
+
+The Pagination 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/pagination/pagination.theme" as
+  pagination;
+```
+
+### 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-pagination {
+  @include pagination.pagination-theme();
+}
+```
+
+#### Option B: Override Specific Values
+
+Pass only the variables you want to change.
+
+```scss
+.my-custom-theme {
+  @include pagination.pagination-theme(
+    (
+      text-color: #333333,
+      btn-active-bg: purple,
+    )
+  );
+}
+```
+
+### 3. Usage in App
+
+Apply the theme class to the wrapper of the pagination component.
+
+```html
+<div class="default-theme-pagination">
+  <lib-pagination ...></lib-pagination>
+</div>
+```
+
+### Configuration Key Reference
+
+The `pagination-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 component.                      |
+| **text-color**         | `#757575`              | Primary text color.                                |
+| **font-size**          | `14px`                 | Base font size.                                    |
+| **select-bg**          | `#f5f5f5`              | Background color of the "Items per page" dropdown. |
+| **select-border**      | `none`                 | Border of the dropdown.                            |
+| **select-radius**      | `4px`                  | Border radius of the dropdown.                     |
+| **select-padding**     | `6px 12px`             | Padding inside the dropdown.                       |
+| **select-text-color**  | `#333`                 | Text color inside the dropdown.                    |
+| **select-arrow-color** | `#f44336`              | Color of the dropdown arrow icon.                  |
+| **btn-size**           | `32px`                 | Width and height of pagination buttons.            |
+| **btn-bg**             | `#ffffff`              | Background color of buttons.                       |
+| **btn-border**         | `1px solid #e0e0e0`    | Border of buttons.                                 |
+| **btn-radius**         | `4px`                  | Border radius of buttons.                          |
+| **btn-text-color**     | `#333`                 | Text color of buttons.                             |
+| **btn-hover-bg**       | `#f5f5f5`              | Background color on hover.                         |
+| **btn-active-bg**      | `#ffffff`              | Background color of the active page button.        |
+| **btn-active-border**  | `1px solid #ff4081`    | Border color of the active page button.            |
+| **btn-active-text**    | `#ff4081`              | Text color of the active page button.              |
+| **disabled-opacity**   | `0.5`                  | Opacity of disabled buttons (First/Last).          |
+| **disabled-bg**        | `#f9f9f9`              | Background color of disabled buttons.              |
+
+### 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 like `--cc-pagination-bg` will be undefined, and the component will look broken (transparent, unstyled). Use `Option A` above to get the default look.
+
+---
+
+## Responsive Design
+
+The component is built with Flexbox and includes a mobile breakpoint at `600px`.
+
+- On desktop, controls and page information are spread apart.
+- On mobile, they stack vertically for better touch accessibility.
+
+## API Reference
+
+### Inputs
+
+| Input             | Type               | Default        | Description                                   |
+| ----------------- | ------------------ | -------------- | --------------------------------------------- |
+| `totalItems`      | `number`           | `0`            | Total number of items to paginate.            |
+| `itemsPerPage`    | `number`           | `10`           | Number of items to show per page.             |
+| `currentPage`     | `number`           | `1`            | The current active page (1-based index).      |
+| `pageSizeOptions` | `number[]`         | `[10, 20, 50]` | Options available in the "Per Page" dropdown. |
+| `labels`          | `PaginationLabels` | `{...}`        | (Optional) i18n labels. See details below.    |
+
+### Internationalization (Labels)
+
+To support multiple languages, you can pass a `labels` object to the component.
+
+**Interface:**
+
+```typescript
+interface PaginationLabels {
+  items: string; // e.g., 'items'
+  of: string; // e.g., 'of'
+  perPage: string; // e.g., 'Per Page'
+}
+```
+
+**Usage Example:**
+
+```typescript
+// in your component.ts
+myLabels = {
+  items: "éléments",
+  of: "de",
+  perPage: "par page",
+};
+```
+
+```html
+<lib-pagination [labels]="myLabels" ...> </lib-pagination>
+```
+
+### Outputs
+
+| Output               | Type                   | Description                                                                 |
+| -------------------- | ---------------------- | --------------------------------------------------------------------------- |
+| `pageChange`         | `EventEmitter<number>` | Emitted when the page number changes. Value is the new page number.         |
+| `itemsPerPageChange` | `EventEmitter<number>` | Emitted when the user selects a different page size. Value is the new size. |