@dnd-mapp/shared-ui 1.0.0 → 1.1.0

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

@@ -0,0 +1,102 @@
+[← 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 rendering an invisible, bold version of the label to reserve the maximum required space in the DOM grid.
+
+## 🏰 Overview
+
+| Feature              | Details              |
+|----------------------|----------------------|
+| **Selector**         | `dma-active-marker`  |
+| **Format**           | Standalone Component |
+| **Change Detection** | `OnPush`             |
+
+---
+
+## 🚀 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      | Default    | Description                                                            |
+|----------|-----------|------------|------------------------------------------------------------------------|
+| `label`  | `string`  | `required` | The text content to be displayed.                                      |
+| `active` | `boolean` | `false`    | Controls the active (bold) state. Uses `booleanAttribute` transformer. |
+
+---
+
+## 🧪 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 } from '@angular/core';
+import { ActiveMarkerComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-nav-list',
+    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>
+            }
+        </nav>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [ActiveMarkerComponent],
+})
+export class NavListComponent {
+    protected selectedId = 1;
+    protected menuItems = [
+        { id: 1, name: 'Overview' },
+        { id: 2, name: 'Analytics' },
+        { id: 3, name: 'Settings' }
+    ];
+
+    protected select(id: number) {
+        this.selectedId = id;
+    }
+}
+```
+
+### 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]="tab === 'profile'" />
+  <dma-active-marker label="Security" [active]="tab === '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,113 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# App Top Bar `dma-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.
+
+- **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 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>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [AppTopBarComponent, AppTopBarSectionComponent],
+})
+export class RootComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### AppTopBarComponent
+
+#### Content Projection
+
+| Slot                      | Description                                         |
+|:--------------------------|:----------------------------------------------------|
+| `dma-app-top-bar-section` | Used to define alignment groups within the top bar. |
+
+---
+
+### AppTopBarSectionComponent
+
+#### Inputs
+
+| Name         | Type               | Default   | Description                                                                                   |
+|--------------|--------------------|-----------|-----------------------------------------------------------------------------------------------|
+| `[position]` | `'start' \| 'end'` | `'start'` | Determines the alignment. `'start'` sections will grow to fill available space if applicable. |
+
+#### 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 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>
+
+    <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" />
+    </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,98 @@
+[← 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 Tailwind CSS for a flexible, horizontal flexbox layout with standardized spacing.
+
+| Feature              | Details                                |
+|----------------------|----------------------------------------|
+| **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. |
+
+### Host Bindings
+
+| Property | Value                     | Description                                       |
+|----------|---------------------------|---------------------------------------------------|
+| `class`  | `flex items-center gap-4` | Applies horizontal alignment and default spacing. |
+
+---
+
+## 🧪 Examples
+
+### Basic Navigation
+
+A simple implementation featuring a logo and primary navigation links.
+
+```html
+<nav dma-navbar>
+    <img src="logo.svg" alt="App Logo" class="h-8" />
+    <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 class="flex-1"></div>
+            <button class="btn-primary">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,77 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# Navbar Brand Component (`dma-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 { NavbarBrandComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-layout',
+    template: `<dma-navbar-brand imgSrc="assets/logo.svg" brandName="D&D Mapp" />`,
+    imports: [NavbarBrandComponent],
+})
+export class LayoutComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### Inputs
+
+| 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 the `provideRouter` or `RouterModule` is configured in your application.
+
+---
+
+## 🧪 Examples
+
+### Basic Branding
+
+```html
+<dma-navbar-brand 
+    imgSrc="/favicon.ico" 
+    brandName="My Application" 
+/>
+```
+
+### Dynamic Branding
+
+If your brand information comes from a configuration object or a signal:
+
+```html
+<dma-navbar-brand 
+    [imgSrc]="config.logoPath" 
+    [brandName]="config.appName" 
+/>
+```
+
+---
+
+## 📜 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,65 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# NavbarLink Component (`dma-navbar-link`)
+
+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.
+
+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.
+
+---
+
+## 🏰 Overview
+
+- **Selector:** `dma-navbar-link`
+- **Format:** Angular Standalone Component
+
+---
+
+## 🚀 Usage
+
+To use the `NavbarLinkComponent`, import it into your standalone component or Angular module and add it to your template.
+
+```ts
+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>
+    `,
+  imports: [NavbarLinkComponent],
+})
+export class NavContainerComponent {}
+```
+
+---
+
+## 🎨 API Reference
+
+### 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`).                          |
+
+---
+
+## 🧪 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.

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

@@ -0,0 +1,125 @@
+[← Back to Library Overview](../../../../README.md#-component-library)
+
+---
+
+# Navbar Menu `dma-navbar-menu`
+
+The `Navbar Menu` is a specialized navigation component designed to trigger dropdown menus within a navigation bar. It integrates seamlessly with the library's dropdown system, supporting both click-based and hover-based interactions for improved user experience.
+
+## 🏰 Overview
+
+| Feature              | Details              |
+|----------------------|----------------------|
+| **Selector**         | `dma-navbar-menu`    |
+| **Format**           | Standalone Component |
+| **Change Detection** | `OnPush`             |
+
+---
+
+## 🚀 Usage
+
+The component uses content projection to separate the trigger element from the dropdown content.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarMenuComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-nav',
+    template: `
+        <dma-navbar-menu [toggleOnHover]="true">
+            <ng-container ngProjectAs="dropdown-trigger">
+                <span>Products</span>
+            </ng-container>
+            <ng-container ngProjectAs="dropdown-menu">
+                <a href="/link-1">Feature A</a>
+                <a href="/link-2">Feature B</a>
+            </ng-container>
+        </dma-navbar-menu>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarMenuComponent],
+})
+export class NavComponent {
+}
+```
+
+---
+
+## 🎨 API Reference
+
+### Inputs
+
+| Name            | Type      | Default | Description                                                                                                |
+|-----------------|-----------|---------|------------------------------------------------------------------------------------------------------------|
+| `toggleOnHover` | `boolean` | `false` | Whether the dropdown should open and close automatically when the mouse enters or leaves the trigger area. |
+
+### Content Projection Slots
+
+| Selector           | Description                                               |
+|--------------------|-----------------------------------------------------------|
+| `dropdown-trigger` | The element that acts as the button to toggle the menu.   |
+| `dropdown-menu`    | The container holding the navigation links or menu items. |
+
+---
+
+## 🧪 Examples
+
+### Basic Click Toggle
+
+By default, the menu requires a click interaction to open, which is ideal for mobile-responsive headers or complex navigation.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarMenuComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-basic-nav',
+    template: `
+        <dma-navbar-menu>
+            <dropdown-trigger>Settings</dropdown-trigger>
+            <dropdown-menu>
+                <ul>
+                    <li>Profile</li>
+                    <li>Security</li>
+                </ul>
+            </dropdown-menu>
+        </dma-navbar-menu>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarMenuComponent],
+})
+export class BasicNavComponent {
+}
+```
+
+### Hover Activation
+
+Use the `toggleOnHover` input to create a more fluid desktop navigation experience where menus appear instantly on mouseenter.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { NavbarMenuComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-hover-nav',
+    template: `
+        <dma-navbar-menu toggleOnHover>
+            <ng-container ngProjectAs="dropdown-trigger">Resources</ng-container>
+            <ng-container ngProjectAs="dropdown-menu">
+                <nav-item>Documentation</nav-item>
+                <nav-item>API Reference</nav-item>
+            </ng-container>
+        </dma-navbar-menu>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [NavbarMenuComponent],
+})
+export class HoverNavComponent {}
+```
+
+---
+
+## 📜 License
+
+This component is part of the `@dnd-mapp/shared-ui` internal library. All rights reserved. Proprietary and confidential.

package/src/lib/vertical-rule/README.md

@@ -0,0 +1,97 @@
+[← Back to Library Overview](../../../README.md#-component-library)
+
+---
+
+# Vertical Rule Component (`dma-vr`)
+
+The `VerticalRuleComponent` is a structural utility component designed to provide a consistent vertical divider for separating content within layouts, such as navigation bars, toolbars, or flex containers.
+
+## 🏰 Overview
+
+- **Selector**: `dma-vr`
+- **Use Case**: Visual separation of inline elements.
+- **Compatibility**: Designed for use within flexbox or grid containers.
+
+---
+
+## 🚀 Usage
+
+### 1. Import
+
+Add `VerticalRuleComponent` to your standalone component's `imports` array:
+
+```ts
+import { Component } from '@angular/core';
+import { VerticalRuleComponent } from '@dnd-mapp/shared-ui';
+
+@Component({
+    selector: 'app-toolbar',
+    template: `
+        <div class="flex h-10 items-center gap-4">
+            <button dma-button>Save</button>
+            
+            <!-- Vertical Divider -->
+            <dma-vr />
+            
+            <button dma-button>Delete</button>
+        </div>
+    `,
+    imports: [VerticalRuleComponent]
+})
+export class ToolbarComponent {}
+```
+
+### 2. Styles Requirement
+
+For the divider to display correctly, the parent container should have a defined height or use a flex layout. The component is designed to automatically stretch to the height of its container.
+
+---
+
+## 🎨 API Reference
+
+### Selector
+
+`dma-vr`
+
+### Visual Behavior
+
+- **Orientation**: Vertical.
+- **Color**: Preset to the design system's neutral palette.
+- **Thickness**: Single-pixel border (start-aligned).
+
+---
+
+## 🧪 Examples
+
+### Navigation Header
+
+The divider is ideal for separating text links or icons in a header navigation.
+
+```html
+<nav class="flex items-center gap-2 p-4">
+  <span>Character Sheet</span>
+  <dma-vr />
+  <span>Inventory</span>
+  <dma-vr />
+  <span>Spells</span>
+</nav>
+```
+
+### Action Group
+
+Use it to group related actions within a toolbar while maintaining a clear visual distinction between different functional sets.
+
+```html
+<div class="flex h-8 items-center gap-3">
+  <dma-icon-button icon="edit" />
+  <dma-icon-button icon="copy" />
+  <dma-vr />
+  <dma-icon-button icon="trash" />
+</div>
+```
+
+---
+
+## 📜 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.