@dnd-mapp/shared-ui 0.1.0 → 1.1.0

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.