@dnd-mapp/shared-ui 1.0.0 → 2.0.0

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

@@ -0,0 +1,129 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# 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`), 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 **500ms debounce** on value changes to prevent excessive form updates during rapid typing.
+
+- **Selector**: `dma-input`
+- **Format**: Standalone Component
+- **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, signal } from '@angular/core';
+
+@Component({
+    selector: 'app-root',
+    template: `<dma-input inputId="username-field" label="Username" placeholder="TheLegend27" [(value)]="username" />`,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [InputComponent],
+})
+export class RootComponent {
+    protected readonly username = signal('');
+}
+```
+
+---
+
+## 🎨 API Reference
+
+### Inputs
+
+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)
+
+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
+
+### Reactive Forms Integration
+
+Since the component implements `ControlValueAccessor`, it integrates seamlessly with `FormControl`. The `onTouched` event is triggered when the input receives focus.
+
+```ts
+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" />
+        </form>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [ReactiveFormsModule, InputComponent],
+})
+export class ProfileFormComponent {
+    private readonly formBuilder = inject(FormBuilder).nonNullable;
+
+    protected readonly form = this.formBuilder.group({
+        username: this.formBuilder.control('', [Validators.required, Validators.minLength(3)])
+    });
+}
+```
+
+### Read-only State
+
+The `readonly` attribute is transformed using `booleanAttribute`, allowing for easy usage in templates.
+
+```html
+<dma-input readonly inputId="version-id" label="System Version" value="v1.0.4" />
+```
+
+---
+
+## 📜 License
+
+This component is part of the `@dnd-mapp/shared-ui` proprietary library. All rights reserved.

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

@@ -0,0 +1,115 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# Active Marker
+
+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
+
+- **Selector**: `dma-active-marker`
+- **Format**: Standalone Component
+- **Change Detection**: `ChangeDetectionStrategy.OnPush`
+- **Styling**: Scoped SCSS (BEM-less)
+
+---
+
+## 🚀 Usage
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-root',
+    template: `<dma-active-marker label="Dashboard" active />`,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [ActiveMarkerComponent],
+})
+export class RootComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### Inputs
+
+| 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.
+
+---
+
+## 🧪 Examples
+
+### Navigation Menu
+
+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, signal } from '@angular/core';
+import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-nav-list',
+    template: `
+        <nav>
+            @for (item of menuItems; track item.id) {
+                <button (click)="selectedId.set(item.id)">
+                    <dma-active-marker [label]="item.name" [active]="selectedId() === item.id" />
+                </button>
+            }
+        </nav>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [ActiveMarkerComponent],
+})
+export class NavListComponent {
+    protected readonly selectedId = signal(1);
+
+    protected readonly menuItems = [
+        { id: 1, name: 'Overview' },
+        { id: 2, name: 'Analytics' },
+        { id: 3, name: 'Settings' }
+    ];
+}
+```
+
+### Tab Indicators
+
+Ideal for tab headers where centered text must remain perfectly centered regardless of its active state.
+
+```html
+<div class="flex gap-4">
+  <dma-active-marker label="Profile" [active]="currentTab === 'profile'" />
+  <dma-active-marker label="Security" [active]="currentTab === 'security'" />
+</div>
+```
+
+---
+
+## 📜 License
+
+Internal use only. Copyright © 2026 DnD Mapp. All rights reserved.
+
+[← Back to Library Overview](../../../../README.md#-component-library)

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

@@ -0,0 +1,96 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# 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 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
+- **Change Detection**: `OnPush`
+
+---
+
+## 🚀 Usage
+
+```ts
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { AppTopBarComponent, AppTopBarSectionComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-root',
+    template: `
+        <dma-app-top-bar>
+            <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,
+    imports: [AppTopBarComponent, AppTopBarSectionComponent],
+})
+export class RootComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### AppTopBarComponent
+
+#### Content Projection
+
+| Slot                      | Description                                                                      |
+|---------------------------|----------------------------------------------------------------------------------|
+| `dma-app-top-bar-section` | Selects components of type `dma-app-top-bar-section` to define alignment groups. |
+
+---
+
+### AppTopBarSectionComponent
+
+#### Inputs
+
+| 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
+
+| Slot         | Description                                                            |
+|--------------|------------------------------------------------------------------------|
+| `ng-content` | The elements (links, buttons, text) to be rendered within the section. |
+
+---
+
+## 🧪 Examples
+
+### Basic Branding and Navigation
+
+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>
+        Start section
+    </dma-app-top-bar-section>
+
+    <dma-app-top-bar-section position="end">
+        End Section
+    </dma-app-top-bar-section>
+</dma-app-top-bar>
+```
+
+---
+
+## 📜 License
+
+Internal Proprietary Library – All Rights Reserved.

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

@@ -0,0 +1,93 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# Navbar Component `nav[dma-navbar]`
+
+## 🏰 Overview
+
+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 a Scss-based flexible, horizontal flexbox layout with standardized spacing derived from the library's theme variables.
+
+- **Selector**: `nav[dma-navbar]`
+- **Format**: Standalone Component (Attribute-based)
+- **Change Detection**: `ChangeDetectionStrategy.OnPush`
+
+---
+
+## 🚀 Usage
+
+Apply the `dma-navbar` attribute to a `<nav>` element. Use content projection to include your navigation links or branding elements.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-root',
+    template: `
+        <nav dma-navbar>
+            <!-- Content is projected here -->
+        </nav>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarComponent],
+})
+export class RootComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### Content Projection
+
+| Slot           | Description                                                  |
+|----------------|--------------------------------------------------------------|
+| `<ng-content>` | Default slot for navigation links, logos, or action buttons. |
+
+---
+
+## 🧪 Examples
+
+### Basic Navigation
+
+A simple implementation featuring a logo and primary navigation links.
+
+```html
+<nav dma-navbar>
+    <img src="logo.svg" alt="App Logo" />
+    <a href="/dashboard">Dashboard</a>
+    <a href="/settings">Settings</a>
+</nav>
+```
+
+### Navbar with Action Buttons
+
+Using the flex layout to separate navigation items from a call-to-action button.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-header',
+    template: `
+        <nav dma-navbar>
+            <span class="font-bold">D&D Mapp</span>
+            <div style="flex: 1"></div>
+            <button>Logout</button>
+        </nav>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarComponent],
+})
+export class HeaderComponent {}
+```
+
+---
+
+## 📜 License
+
+This component is part of the `@dnd-mapp/shared-ui` internal library. All rights reserved. Proprietary and confidential.

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

@@ -0,0 +1,96 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# 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.
+
+---
+
+## 🏰 Overview
+
+- **Selector:** `dma-navbar-brand`
+- **Format:** Angular Standalone Component
+- **Change Detection:** `OnPush`
+
+---
+
+## 🚀 Usage
+
+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 {}
+```
+
+---
+
+## 🎨 API Reference
+
+### 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.           |
+| `brandName` | `string` | Yes      | The text string to be displayed as the brand name. |
+
+### Routing
+
+The component internally uses `RouterLink` and is hardcoded to navigate to the root path (`/`). Ensure that `provideRouter` is configured in your application bootstrap.
+
+---
+
+## 🧪 Examples
+
+### Basic Branding
+
+```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
+
+Since the component uses Signal inputs, you can pass values from other Signals or standard properties:
+
+```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');
+}
+```
+
+---
+
+## 📜 License
+
+This component is part of the `@dnd-mapp/shared-ui` proprietary library. Refer to the root [LICENSE](https://github.com/dnd-mapp/shared-ui/blob/main/LICENSE) for usage restrictions.

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

@@ -0,0 +1,76 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# NavbarLink
+
+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` 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.
+
+---
+
+## 🏰 Overview
+
+- **Selector:** `dma-navbar-link`
+- **Format:** Angular Standalone Component
+- **Change Detection:** `OnPush`
+
+---
+
+## 🚀 Usage
+
+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',
+    template: `
+        <nav>
+            <dma-navbar-link label="Dashboard" route="/dashboard" />
+            <dma-navbar-link label="Settings" route="/settings" />
+        </nav>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush, 
+    imports: [NavbarLinkComponent],
+})
+export class NavContainerComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### Inputs
+
+| 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`.
+
+---
+
+## 🧪 Examples
+
+### Basic Navigation
+
+```html
+<dma-navbar-link label="Home" route="/home" />
+```
+
+---
+
+## 📜 License
+
+This component is part of the `@dnd-mapp/shared-ui` proprietary library. Refer to the root [LICENSE](https://github.com/dnd-mapp/shared-ui/blob/main/LICENSE) for usage restrictions.