@dnd-mapp/shared-ui 1.1.0 → 2.0.0

package/src/lib/forms/input/README.md

@@ -4,38 +4,38 @@
 
 # Input Component `dma-input`
 
-A versatile, accessible text input component designed for the `@dnd-mapp` ecosystem. It features built-in support for Angular Forms (ControlValueAccessor), custom validation styling, and debounced input handling to optimize performance.
+A versatile, accessible text input component designed for the `@dnd-mapp` ecosystem. It features built-in support for Angular Forms (`ControlValueAccessor`), reactive validation styling, and an internal debounce mechanism to optimize performance.
 
 ## 🏰 Overview
 
-The `InputComponent` provides a styled wrapper around the native HTML input element. It includes integrated label handling, status-based border coloring (valid/invalid/touched), and a 500 ms debounce on value changes to prevent excessive form updates during rapid typing.
+The `InputComponent` provides a styled wrapper around the native HTML input element. It includes integrated label handling, status-based border coloring (valid/invalid/touched), and a **500ms debounce** on value changes to prevent excessive form updates during rapid typing.
 
 - **Selector**: `dma-input`
 - **Format**: Standalone Component
-- **Change Detection**: OnPush
+- **Change Detection**: `OnPush`
+- **Form Support**: Full `ControlValueAccessor` integration
 
 ---
 
 ## 🚀 Usage
 
+### Basic Usage with Signals
+
+The component uses Angular's `model()` for the value, allowing for easy two-way binding.
+
 ```ts
 import { InputComponent } from '@dnd-mapp/shared-ui';
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 
 @Component({
     selector: 'app-root',
-    template: `      
-        <dma-input
-            inputId="username"
-            label="Username"
-            placeholder="Enter your character name"
-            [(value)]="userName"
-        />
-    `,
+    template: `<dma-input inputId="username-field" label="Username" placeholder="TheLegend27" [(value)]="username" />`,
     changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [InputComponent],
 })
-export class MyComponent {}
+export class RootComponent {
+    protected readonly username = signal('');
+}
 ```
 
 ---
@@ -44,58 +44,82 @@ export class MyComponent {}
 
 ### Inputs
 
-| Name          | Type      | Default    | Description                                                 |
-|---------------|-----------|------------|-------------------------------------------------------------|
-| `inputId`     | `string`  | `required` | The unique ID for the internal input and label association. |
-| `label`       | `string`  | `required` | The text label displayed above the input field.             |
-| `placeholder` | `string`  | `''`       | The hint text displayed when the input is empty.            |
-| `readonly`    | `boolean` | `false`    | If true, the input is present but non-editable.             |
+Controlled via Angular Signal inputs.
+
+| Name          | Type      | Required | Default | Description                                                                 |
+|---------------|-----------|----------|---------|-----------------------------------------------------------------------------|
+| `inputId`     | `string`  | Yes      | -       | The unique ID used to associate the label with the input.                   |
+| `label`       | `string`  | Yes      | -       | The text label displayed above the input field.                             |
+| `placeholder` | `string`  | No       | `''`    | The hint text displayed when the input is empty.                            |
+| `readonly`    | `boolean` | No       | `false` | If true, the input is present but non-editable (uses `booleanAttribute`).   |
 
 ### Models (Two-way Data Binding)
 
-| Name       | Type      | Default | Description                                                |
-|------------|-----------|---------|------------------------------------------------------------|
-| `value`    | `string`  | `''`    | The current text value of the input. Supports `[(value)]`. |
-| `disabled` | `boolean` | `false` | Controls the disabled state of the input.                  |
+Controlled via Angular Signal models. These can be used with `[(value)]` or updated via Reactive Forms.
+
+| Name       | Type      | Default | Description                                                           |
+|------------|-----------|---------|-----------------------------------------------------------------------|
+| `value`    | `string`  | `''`    | The current text value.                                               |
+| `disabled` | `boolean` | `false` | Controls the disabled state. Automatically handled by Reactive Forms. |
+
+---
+
+## ⚙️ Technical Details
+
+### Debounce Logic
+
+To improve performance and reduce unnecessary change detection cycles, the component uses an internal `Subject` and `debounceTime(500)`. When a user types:
+
+1. The internal `onInput` event triggers.
+2. The value is held for 500ms.
+3. After the timer clears, `onChange` is called, updating the model and notifying any parent Angular Form.
+
+### Validation States
+
+The component automatically styles itself based on Angular Form CSS classes:
+
+- **Valid & Touched**: Displays a green border.
+- **Invalid & Touched**: Displays a red border and red text.
+- **Disabled**: Applies a background tint, reduces opacity, and changes the cursor to `not-allowed`.
 
 ---
 
 ## 🧪 Examples
 
-### 1. Reactive Forms Integration
+### Reactive Forms Integration
 
-Since the component implements `ControlValueAccessor`, it integrates seamlessly with `FormControl`.
+Since the component implements `ControlValueAccessor`, it integrates seamlessly with `FormControl`. The `onTouched` event is triggered when the input receives focus.
 
 ```ts
-import { Component, ChangeDetectionStrategy } from '@angular/core';
-import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
 import { InputComponent } from '@dnd-mapp/shared-ui';
 
 @Component({
     selector: 'app-profile-form',
     template: `
         <form [formGroup]="form">
-            <dma-input 
-                label="Username"
-                inputId="username-field"
-                formControlName="username"
-            />
+            <dma-input label="Username" inputId="username-field" formControlName="username" />
         </form>
     `,
     changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [ReactiveFormsModule, InputComponent],
 })
 export class ProfileFormComponent {
-    username = new FormControl('', [Validators.required, Validators.minLength(3)]);
+    private readonly formBuilder = inject(FormBuilder).nonNullable;
+
+    protected readonly form = this.formBuilder.group({
+        username: this.formBuilder.control('', [Validators.required, Validators.minLength(3)])
+    });
 }
 ```
 
-### 2. Read-only State
+### Read-only State
 
-Useful for displaying data that was previously entered but cannot be changed in the current context.
+The `readonly` attribute is transformed using `booleanAttribute`, allowing for easy usage in templates.
 
 ```html
-<dma-input readonly inputId="char-id-001" label="Character ID" value="#88219" />
+<dma-input readonly inputId="version-id" label="System Version" value="v1.0.4" />
 ```
 
 ---

package/src/lib/nav/active-marker/README.md

@@ -4,15 +4,14 @@
 
 # Active Marker
 
-A specialized text component designed to prevent layout shifts (CLS) when toggling between normal and bold font weights. It achieves this by rendering an invisible, bold version of the label to reserve the maximum required space in the DOM grid.
+A specialized text component designed to prevent layout shifts (CLS) when toggling between normal and bold font weights. It achieves this by using a CSS Grid-based "ghosting" technique: rendering an invisible, bold version of the label to reserve the maximum required space, ensuring the container dimensions remain constant regardless of the active state.
 
 ## 🏰 Overview
 
-| Feature              | Details              |
-|----------------------|----------------------|
-| **Selector**         | `dma-active-marker`  |
-| **Format**           | Standalone Component |
-| **Change Detection** | `OnPush`             |
+- **Selector**: `dma-active-marker`
+- **Format**: Standalone Component
+- **Change Detection**: `ChangeDetectionStrategy.OnPush`
+- **Styling**: Scoped SCSS (BEM-less)
 
 ---
 
@@ -37,10 +36,27 @@ export class RootComponent {}
 
 ### Inputs
 
-| Name     | Type      | Default    | Description                                                            |
-|----------|-----------|------------|------------------------------------------------------------------------|
-| `label`  | `string`  | `required` | The text content to be displayed.                                      |
-| `active` | `boolean` | `false`    | Controls the active (bold) state. Uses `booleanAttribute` transformer. |
+| Name     | Type      | Required | Default | Description                                                                                                            |
+|----------|-----------|----------|---------|------------------------------------------------------------------------------------------------------------------------|
+| `label`  | `string`  | Yes      | -       | The text content to be displayed.                                                                                      |
+| `active` | `boolean` | No       | `false` | Controls the active state. Uses `booleanAttribute` for flexible template usage (e.g., `<dma-active-marker active />`). |
+
+### Host Classes
+
+| Class     | Condition          | Result                                                                      |
+|-----------|--------------------|-----------------------------------------------------------------------------|
+| `.active` | `active()` is true | Changes color to `$neutral-900` and font-weight to `$font-weight-semibold`. |
+
+---
+
+## 🛠️ Implementation Details
+
+### Layout Shift Prevention
+
+The component uses `display: grid` on the host. Both the visible label and the "spacer" label are assigned to `grid-column: 1` and `grid-row: 1`.
+
+1. **`.label-spacer`**: Always rendered with `visibility: hidden` and `font-weight: $font-weight-semibold`. This forces the grid cell to always be wide enough for the boldest version of the text.
+2. **Visible Span**: Layers directly on top of the spacer. Its weight and color toggle based on the `.active` host class.
 
 ---
 
@@ -51,7 +67,7 @@ export class RootComponent {}
 Use the component in a sidebar or menu to highlight the current route without causing the menu width to "jitter" when the font weight increases.
 
 ```ts
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
 
 @Component({
@@ -59,9 +75,9 @@ import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
     template: `
         <nav>
             @for (item of menuItems; track item.id) {
-                <a (click)="select(item.id)">
-                    <dma-active-marker [label]="item.name" [active]="selectedId === item.id" />
-                </a>
+                <button (click)="selectedId.set(item.id)">
+                    <dma-active-marker [label]="item.name" [active]="selectedId() === item.id" />
+                </button>
             }
         </nav>
     `,
@@ -69,16 +85,13 @@ import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
     imports: [ActiveMarkerComponent],
 })
 export class NavListComponent {
-    protected selectedId = 1;
-    protected menuItems = [
+    protected readonly selectedId = signal(1);
+
+    protected readonly menuItems = [
         { id: 1, name: 'Overview' },
         { id: 2, name: 'Analytics' },
         { id: 3, name: 'Settings' }
     ];
-
-    protected select(id: number) {
-        this.selectedId = id;
-    }
 }
 ```
 
@@ -88,8 +101,8 @@ Ideal for tab headers where centered text must remain perfectly centered regardl
 
 ```html
 <div class="flex gap-4">
-  <dma-active-marker label="Profile" [active]="tab === 'profile'" />
-  <dma-active-marker label="Security" [active]="tab === 'security'" />
+  <dma-active-marker label="Profile" [active]="currentTab === 'profile'" />
+  <dma-active-marker label="Security" [active]="currentTab === 'security'" />
 </div>
 ```
 

package/src/lib/nav/app-top-bar/README.md

@@ -2,13 +2,13 @@
 
 ---
 
-# App Top Bar `dma-app-top-bar`
+# App Top Bar
 
 A flexible and layout-oriented header component designed to host navigation, branding, and action elements. It uses a composition-based approach with dedicated sections to ensure consistent spacing and alignment across the application.
 
 ## 🏰 Overview
 
-The `AppTopBarComponent` acts as a container that leverages Tailwind CSS for layout and provides a specific slot for `AppTopBarSectionComponent` instances. This allows developers to easily group elements at the start or end of the bar.
+The `AppTopBarComponent` acts as a flexbox container that provides a specific slot for `AppTopBarSectionComponent` instances. It handles the top-level layout, background colors, and borders, while the sections handle internal alignment and spacing.
 
 - **Selector**: `dma-app-top-bar`
 - **Format**: Standalone Component
@@ -26,8 +26,13 @@ import { AppTopBarComponent, AppTopBarSectionComponent } from '@dnd-mapp/shared-
     selector: 'app-root',
     template: `
         <dma-app-top-bar>
-            <dma-app-top-bar-section position="start"><span>Logo</span></dma-app-top-bar-section>
-            <dma-app-top-bar-section position="end"><button>Profile</button></dma-app-top-bar-section>
+            <dma-app-top-bar-section>
+                <span>Logo</span>
+            </dma-app-top-bar-section>
+            
+            <dma-app-top-bar-section position="end">
+                <button>Profile</button>
+            </dma-app-top-bar-section>
         </dma-app-top-bar>
     `,
     changeDetection: ChangeDetectionStrategy.OnPush,
@@ -44,9 +49,9 @@ export class RootComponent {}
 
 #### Content Projection
 
-| Slot                      | Description                                         |
-|:--------------------------|:----------------------------------------------------|
-| `dma-app-top-bar-section` | Used to define alignment groups within the top bar. |
+| Slot                      | Description                                                                      |
+|---------------------------|----------------------------------------------------------------------------------|
+| `dma-app-top-bar-section` | Selects components of type `dma-app-top-bar-section` to define alignment groups. |
 
 ---
 
@@ -54,9 +59,9 @@ export class RootComponent {}
 
 #### Inputs
 
-| Name         | Type               | Default   | Description                                                                                   |
-|--------------|--------------------|-----------|-----------------------------------------------------------------------------------------------|
-| `[position]` | `'start' \| 'end'` | `'start'` | Determines the alignment. `'start'` sections will grow to fill available space if applicable. |
+| Name         | Type               | Default   | Description                                                                                                                               |
+|--------------|--------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| `[position]` | `'start' \| 'end'` | `'start'` | Determines the alignment. Sections with `position="start"` will `flex-grow` to fill available space, pushing "end" sections to the right. |
 
 #### Content Projection
 
@@ -74,34 +79,12 @@ A standard layout with a title on the left and a single action on the right.
 
 ```html
 <dma-app-top-bar>
-    <dma-app-top-bar-section position="start">
-        <img src="logo.png" alt="Logo" class="h-6" />
-        <h1 class="text-lg font-bold">D&D Mapp</h1>
+    <dma-app-top-bar-section>
+        Start section
     </dma-app-top-bar-section>
 
     <dma-app-top-bar-section position="end">
-        <button class="btn-primary">Logout</button>
-    </dma-app-top-bar-section>
-</dma-app-top-bar>
-```
-
-### Complex Action Bar
-
-Using multiple items within the sections to create a rich interface.
-
-```html
-<dma-app-top-bar>
-    <dma-app-top-bar-section position="start">
-        <dma-icon dma-bars-icon />
-        <nav>
-            <a href="#">Dashboard</a>
-            <a href="#">Campaigns</a>
-        </nav>
-    </dma-app-top-bar-section>
-
-    <dma-app-top-bar-section position="end">
-        <dma-search-input />
-        <dma-avatar user="Oscar" />
+        End Section
     </dma-app-top-bar-section>
 </dma-app-top-bar>
 ```

package/src/lib/nav/navbar/README.md

@@ -8,13 +8,11 @@
 
 The `NavbarComponent` serves as a semantic navigation container for the `@dnd-mapp/shared-ui` library. It uses an attribute selector on the standard HTML `<nav>` element to provide consistent layout styling while maintaining accessibility and SEO standards.
 
-Designed for high-performance applications, it utilizes `OnPush` change detection and leverages Tailwind CSS for a flexible, horizontal flexbox layout with standardized spacing.
+Designed for high-performance applications, it utilizes `OnPush` change detection and leverages a Scss-based flexible, horizontal flexbox layout with standardized spacing derived from the library's theme variables.
 
-| Feature              | Details                                |
-|----------------------|----------------------------------------|
-| **Selector**         | `nav[dma-navbar]`                      |
-| **Format**           | Standalone Component (Attribute-based) |
-| **Change Detection** | `ChangeDetectionStrategy.OnPush`       |
+- **Selector**: `nav[dma-navbar]`
+- **Format**: Standalone Component (Attribute-based)
+- **Change Detection**: `ChangeDetectionStrategy.OnPush`
 
 ---
 
@@ -28,12 +26,15 @@ import { NavbarComponent } from '@dnd-mapp/shared-ui';
 
 @Component({
     selector: 'app-root',
-    template: `<nav dma-navbar><!-- Content is projected here --></nav>`,
+    template: `
+        <nav dma-navbar>
+            <!-- Content is projected here -->
+        </nav>
+    `,
     changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [NavbarComponent],
 })
-export class RootComponent {
-}
+export class RootComponent {}
 ```
 
 ---
@@ -46,12 +47,6 @@ export class RootComponent {
 |----------------|--------------------------------------------------------------|
 | `<ng-content>` | Default slot for navigation links, logos, or action buttons. |
 
-### Host Bindings
-
-| Property | Value                     | Description                                       |
-|----------|---------------------------|---------------------------------------------------|
-| `class`  | `flex items-center gap-4` | Applies horizontal alignment and default spacing. |
-
 ---
 
 ## 🧪 Examples
@@ -62,7 +57,7 @@ A simple implementation featuring a logo and primary navigation links.
 
 ```html
 <nav dma-navbar>
-    <img src="logo.svg" alt="App Logo" class="h-8" />
+    <img src="logo.svg" alt="App Logo" />
     <a href="/dashboard">Dashboard</a>
     <a href="/settings">Settings</a>
 </nav>
@@ -81,8 +76,8 @@ import { NavbarComponent } from '@dnd-mapp/shared-ui';
     template: `
         <nav dma-navbar>
             <span class="font-bold">D&D Mapp</span>
-            <div class="flex-1"></div>
-            <button class="btn-primary">Logout</button>
+            <div style="flex: 1"></div>
+            <button>Logout</button>
         </nav>
     `,
     changeDetection: ChangeDetectionStrategy.OnPush,

package/src/lib/nav/navbar-brand/README.md

@@ -2,7 +2,7 @@
 
 ---
 
-# Navbar Brand Component (`dma-navbar-brand`)
+# Navbar Brand
 
 The `NavbarBrandComponent` is a foundational UI element for application navigation bars. It provides a standardized way to display a brand logo alongside a brand name, automatically linking back to the application root.
 
@@ -21,11 +21,13 @@ The `NavbarBrandComponent` is a foundational UI element for application navigati
 To use the `NavbarBrandComponent`, import it into your standalone component or Angular module, and then add it to your template.
 
 ```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { NavbarBrandComponent } from '@dnd-mapp/shared-ui';
 
 @Component({
     selector: 'app-layout',
     template: `<dma-navbar-brand imgSrc="assets/logo.svg" brandName="D&D Mapp" />`,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [NavbarBrandComponent],
 })
 export class LayoutComponent {}
@@ -37,6 +39,8 @@ export class LayoutComponent {}
 
 ### Inputs
 
+The component uses Angular Signals for its input properties.
+
 | Name        | Type     | Required | Description                                        |
 |-------------|----------|----------|----------------------------------------------------|
 | `imgSrc`    | `string` | Yes      | The source URL for the brand logo image.           |
@@ -44,7 +48,7 @@ export class LayoutComponent {}
 
 ### Routing
 
-The component internally uses `RouterLink` and is hardcoded to navigate to the root path (`/`). Ensure that the `provideRouter` or `RouterModule` is configured in your application.
+The component internally uses `RouterLink` and is hardcoded to navigate to the root path (`/`). Ensure that `provideRouter` is configured in your application bootstrap.
 
 ---
 
@@ -52,22 +56,37 @@ The component internally uses `RouterLink` and is hardcoded to navigate to the r
 
 ### Basic Branding
 
-```html
-<dma-navbar-brand 
-    imgSrc="/favicon.ico" 
-    brandName="My Application" 
-/>
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarBrandComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-root',
+    template: '<dma-navbar-brand imgSrc="/favicon.ico" brandName="My Application" />',
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarBrandComponent],
+})
+export class RootComponent {}
 ```
 
 ### Dynamic Branding
 
-If your brand information comes from a configuration object or a signal:
+Since the component uses Signal inputs, you can pass values from other Signals or standard properties:
 
-```html
-<dma-navbar-brand 
-    [imgSrc]="config.logoPath" 
-    [brandName]="config.appName" 
-/>
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { NavbarBrandComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-root',
+    template: '<dma-navbar-brand [imgSrc]="logo()" [brandName]="name()" />',
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarBrandComponent],
+})
+export class RootComponent {
+    protected readonly logo = signal('assets/dynamic-logo.svg');
+    protected readonly name = signal('Prototyping App');
+}
 ```
 
 ---

package/src/lib/nav/navbar-link/README.md

@@ -2,11 +2,11 @@
 
 ---
 
-# NavbarLink Component (`dma-navbar-link`)
+# NavbarLink
 
-A lightweight, navigation-aware component designed for use within navigation bars. It handles active state detection automatically, ensuring that the link is visually highlighted when the current route matches its destination.
+A navigation-aware component designed for use within navigation bars. It handles active state detection using Angular's functional `isActive` utility and provides a consistent visual experience for routing.
 
-The `NavbarLinkComponent` provides a wrapper around Angular's `RouterLink`. A key feature of this component is its layout stability: it uses a hidden "bold" placeholder to pre-calculate the space required for its active state. This prevents the "shaking" or layout shifting effect that often occurs when a font weight changes from normal to bold upon selection.
+The `NavbarLinkComponent` integrates with the Angular Router to automatically determine its active state. It manages navigation both through a standard `[routerLink]` directive for accessibility (allowing right-clicks/middle-clicks) and a programmatic `onClick` handler.
 
 ---
 
@@ -14,25 +14,28 @@ The `NavbarLinkComponent` provides a wrapper around Angular's `RouterLink`. A ke
 
 - **Selector:** `dma-navbar-link`
 - **Format:** Angular Standalone Component
+- **Change Detection:** `OnPush`
 
 ---
 
 ## 🚀 Usage
 
-To use the `NavbarLinkComponent`, import it into your standalone component or Angular module and add it to your template.
+To use the `NavbarLinkComponent`, import it into your standalone component and add it to your template.
 
 ```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { NavbarLinkComponent } from '@dnd-mapp/shared-ui';
 
-@Component({ 
-    selector: 'app-nav-container', 
+@Component({
+    selector: 'app-nav-container',
     template: `
         <nav>
             <dma-navbar-link label="Dashboard" route="/dashboard" />
             <dma-navbar-link label="Settings" route="/settings" />
         </nav>
     `,
-  imports: [NavbarLinkComponent],
+    changeDetection: ChangeDetectionStrategy.OnPush, 
+    imports: [NavbarLinkComponent],
 })
 export class NavContainerComponent {}
 ```
@@ -43,10 +46,18 @@ export class NavContainerComponent {}
 
 ### Inputs
 
-| Name    | Type     | Required | Description                                                                 |
-|---------|----------|----------|-----------------------------------------------------------------------------|
-| `label` | `string` | Yes      | The text to be displayed inside the link.                                   |
-| `route` | `string` | Yes      | The destination URL path (passed to `routerLink`).                          |
+| Name    | Type     | Required | Description                                                                  |
+|---------|----------|----------|------------------------------------------------------------------------------|
+| `label` | `string` | **Yes**  | The text label passed to the internal active marker.                         |
+| `route` | `string` | **Yes**  | The destination URL path used for both navigation and active state matching. |
+
+### Active State Logic
+
+The component uses a `Signal<boolean>` to track the active state. It is considered active if the current URL matches the `route` input based on the following criteria:
+
+- **Paths:** `subset` (Matches if the route is a prefix of the current URL).
+- **Query Params:** `subset`.
+- **Fragments/Matrix Params:** `ignored`.
 
 ---