@semantic-components/ui-lab 0.62.0 → 0.63.0

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

@@ -0,0 +1,246 @@
+# Navbar
+
+A responsive navigation bar block with mobile menu support. Automatically adapts between desktop horizontal navigation and a mobile hamburger menu with slide-in drawer.
+
+## Components
+
+- `ScNavbarProvider` - Root provider that manages state and links navbar with mobile menu
+- `ScNavbar` - Root nav element for the main navigation bar
+- `ScNavbarBrand` - Brand/logo section with focus styles
+- `ScNavbarGroup` - Groups navbar elements together (e.g., brand + navigation)
+- `ScNavbarActions` - Right-aligned action buttons container
+- `ScNavbarMobileTrigger` - Mobile menu toggle button (uses content projection for icons)
+- `ScNavbarMobilePortal` - Mobile menu portal using CDK overlay (handles rendering)
+- `ScNavbarMobileMenu` - Mobile menu container with styling (customizable)
+- `ScNavbarMobileLink` - Mobile menu link with auto-close on navigation
+
+## Architecture
+
+The navbar uses a provider pattern similar to the sheet component:
+
+- **Provider**: `ScNavbarProvider` wraps everything and manages state
+- **Navbar**: The actual navigation bar sits inside the provider
+- **Mobile Menu**: The mobile menu portal is a sibling to the navbar (not nested inside)
+- **Components communicate**: All components inject the provider to access shared state
+
+This architecture allows the mobile menu to be positioned independently while maintaining a clean connection to the navbar state.
+
+## Usage
+
+### Basic Navbar
+
+The recommended approach is to use `ScNavigationMenu` for navigation. See the example below.
+
+**Note:** The navbar uses `justify-between` to space its direct children. Use `sc-navbar-group` to keep related elements (like brand and navigation) together on the left side.
+
+### With Navigation Menu
+
+You can integrate `ScNavigationMenu` components for dropdown navigation:
+
+```typescript
+import { SiMenuIcon, SiXIcon } from '@semantic-icons/lucide-icons';
+
+@Component({
+  imports: [
+    ScNavbar,
+    ScNavbarProvider,
+    ScNavbarMobileTrigger,
+    // ... other imports
+    SiMenuIcon,
+    SiXIcon,
+  ],
+  template: `
+    <div sc-navbar-provider>
+      <nav sc-navbar>
+        <div sc-navbar-group>
+          <a sc-navbar-brand routerLink="/">
+            <span>Brand</span>
+          </a>
+
+          <!-- Navigation Menu with Dropdowns -->
+          <nav sc-navigation-menu class="hidden md:flex">
+            <ul sc-navigation-menu-list>
+              <li sc-navigation-menu-item>
+                <button sc-navigation-menu-trigger>Products</button>
+                <div sc-navigation-menu-content>
+                  <ul class="grid w-[400px] gap-3 p-4 md:w-[500px] md:grid-cols-2">
+                    <li>
+                      <a sc-navigation-menu-link routerLink="/products/web">
+                        <div class="text-sm font-medium leading-none">Web Apps</div>
+                        <p class="line-clamp-2 text-sm leading-snug text-muted-foreground">
+                          Build modern web applications
+                        </p>
+                      </a>
+                    </li>
+                    <!-- More items -->
+                  </ul>
+                </div>
+              </li>
+
+              <li sc-navigation-menu-item>
+                <a sc-navigation-menu-link routerLink="/docs">Docs</a>
+              </li>
+            </ul>
+          </nav>
+        </div>
+
+        <div sc-navbar-actions>
+          <button sc-button>Get Started</button>
+          <button sc-navbar-mobile-trigger #trigger="scNavbarMobileTrigger">
+            @if (trigger.isMobileMenuOpen()) {
+              <svg si-x-icon></svg>
+            } @else {
+              <svg si-menu-icon></svg>
+            }
+            <span class="sr-only">
+              {{ trigger.isMobileMenuOpen() ? 'Close menu' : 'Open menu' }}
+            </span>
+          </button>
+        </div>
+      </nav>
+
+      <!-- Mobile Menu -->
+      <div sc-navbar-mobile-portal>
+        <div sc-navbar-mobile-menu>
+          <a sc-navbar-mobile-link routerLink="/products">Products</a>
+          <a sc-navbar-mobile-link routerLink="/docs">Docs</a>
+        </div>
+      </div>
+    </div>
+  `,
+})
+```
+
+**Note:** The navigation menu automatically closes when navigation occurs (via router events).
+
+## Controlling Mobile Menu State
+
+You can control the mobile menu state using two-way binding on the provider:
+
+```html
+<div sc-navbar-provider [(open)]="mobileMenuOpen">
+  <!-- navbar content -->
+</div>
+```
+
+```typescript
+export class MyComponent {
+  readonly mobileMenuOpen = model(false);
+}
+```
+
+## Active State
+
+Use the `active` input to indicate the current page for mobile links:
+
+```html
+<a sc-navbar-mobile-link routerLink="/about" [active]="isAboutPage">About</a>
+```
+
+## With RouterLinkActive
+
+For automatic active state based on the current route:
+
+```html
+<a sc-navbar-mobile-link routerLink="/about" routerLinkActive="active" #rla="routerLinkActive" [active]="rla.isActive">About</a>
+```
+
+## Mobile Menu Behavior
+
+The mobile menu automatically:
+
+- Closes when clicking a mobile link (auto-navigation)
+- Closes when pressing the Escape key
+- Uses CDK overlay for proper z-index stacking and portal rendering
+- Slides in from the top below the navbar
+- Animates smoothly with CSS transitions
+- State is managed by the provider and shared across all components
+
+**Icons**: The mobile trigger uses content projection for icons, allowing consumers to provide their own icons (e.g., hamburger menu when closed, X when open) via the `isMobileMenuOpen()` signal accessible through template references.
+
+## Custom Styling
+
+All components accept a `class` input for custom styles:
+
+```html
+<nav sc-navbar class="sticky top-0 z-50">
+  <a sc-navbar-brand class="text-primary">Brand</a>
+  <nav sc-navigation-menu>
+    <!-- navigation menu items -->
+  </nav>
+</nav>
+```
+
+### Customizing Mobile Menu
+
+The mobile menu container can be styled directly using the `class` input:
+
+```html
+<div sc-navbar-mobile-portal>
+  <div sc-navbar-mobile-menu class="bg-red-500 p-8">
+    <!-- Custom background and padding -->
+  </div>
+</div>
+```
+
+## Inputs
+
+### ScNavbarProvider
+
+| Input   | Type      | Default | Description                           |
+| ------- | --------- | ------- | ------------------------------------- |
+| `class` | `string`  | `''`    | Additional CSS classes                |
+| `open`  | `boolean` | `false` | Two-way binding for mobile menu state |
+
+### ScNavbar
+
+| Input   | Type     | Default | Description            |
+| ------- | -------- | ------- | ---------------------- |
+| `class` | `string` | `''`    | Additional CSS classes |
+
+### ScNavbarMobileMenu
+
+| Input   | Type     | Default | Description            |
+| ------- | -------- | ------- | ---------------------- |
+| `class` | `string` | `''`    | Additional CSS classes |
+
+### ScNavbarMobileTrigger
+
+| Input   | Type     | Default | Description            |
+| ------- | -------- | ------- | ---------------------- |
+| `class` | `string` | `''`    | Additional CSS classes |
+
+**Export As:** `scNavbarMobileTrigger`
+
+**Public Properties (via template reference):**
+
+| Property           | Type              | Description                 |
+| ------------------ | ----------------- | --------------------------- |
+| `isMobileMenuOpen` | `Signal<boolean>` | Whether mobile menu is open |
+
+**Usage:** Use a template reference variable with `#trigger="scNavbarMobileTrigger"` to access the `isMobileMenuOpen()` signal for conditional icon rendering.
+
+### ScNavbarMobileLink
+
+| Input    | Type      | Default | Description                          |
+| -------- | --------- | ------- | ------------------------------------ |
+| `class`  | `string`  | `''`    | Additional CSS classes               |
+| `active` | `boolean` | `false` | Whether the link is currently active |
+
+## CSS Variables
+
+The navbar uses the following CSS variable for positioning:
+
+| Variable          | Default | Description                                           |
+| ----------------- | ------- | ----------------------------------------------------- |
+| `--navbar-height` | `57px`  | Height of the navbar, used to position mobile content |
+
+## Accessibility
+
+- Uses semantic `<nav>` element
+- Mobile trigger includes `aria-expanded` and `aria-controls` attributes
+- Mobile menu has `role="navigation"` and `aria-label="Mobile navigation"`
+- Screen reader text for hamburger icon state changes
+- Uses `inert` attribute to prevent focus on hidden mobile content
+- Overlay is marked with `aria-hidden="true"`
+- All interactive elements have visible focus indicators

package/src/lib/components/navbar/index.ts

@@ -0,0 +1,9 @@
+export { ScNavbar } from './navbar';
+export { ScNavbarProvider } from './navbar-provider';
+export { ScNavbarBrand } from './navbar-brand';
+export { ScNavbarGroup } from './navbar-group';
+export { ScNavbarActions } from './navbar-actions';
+export { ScNavbarMobileTrigger } from './navbar-mobile-trigger';
+export { ScNavbarMobilePortal } from './navbar-mobile-portal';
+export { ScNavbarMobileMenu } from './navbar-mobile-menu';
+export { ScNavbarMobileLink } from './navbar-mobile-link';

package/src/lib/components/navbar/navbar-actions.ts

@@ -0,0 +1,28 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-navbar-actions]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'navbar-actions',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarActions {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('relative z-50', 'flex items-center gap-2', this.classInput()),
+  );
+}

package/src/lib/components/navbar/navbar-brand.ts

@@ -0,0 +1,24 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: '[sc-navbar-brand]',
+  host: {
+    'data-slot': 'navbar-brand',
+    '[class]': 'class()',
+  },
+})
+export class ScNavbarBrand {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'relative z-50',
+      'flex items-center gap-2',
+      'text-lg font-semibold',
+      'text-foreground',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/navbar/navbar-group.ts

@@ -0,0 +1,28 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-navbar-group]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'navbar-group',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarGroup {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('flex items-center gap-6', this.classInput()),
+  );
+}

package/src/lib/components/navbar/navbar-mobile-link.ts

@@ -0,0 +1,28 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'a[sc-navbar-mobile-link], button[sc-navbar-mobile-link]',
+  host: {
+    'data-slot': 'navbar-mobile-link',
+    '[class]': 'class()',
+  },
+})
+export class ScNavbarMobileLink {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly active = input<boolean>(false);
+
+  protected readonly class = computed(() =>
+    cn(
+      'flex items-center',
+      'w-full px-4 py-3 rounded-md',
+      'text-base font-medium',
+      'transition-colors',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      this.active()
+        ? 'bg-accent text-accent-foreground'
+        : 'text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/navbar/navbar-mobile-menu.ts

@@ -0,0 +1,71 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScNavbarProvider } from './navbar-provider';
+
+type ScNavbarMobileMenuState = 'open' | 'closed';
+
+@Component({
+  selector: 'div[sc-navbar-mobile-menu]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'navbar-mobile-menu',
+    id: 'navbar-mobile-menu',
+    role: 'navigation',
+    '[attr.aria-label]': '"Mobile navigation"',
+    '[attr.data-state]': 'state()',
+    '[class]': 'class()',
+    '[tabindex]': '-1',
+    '(animationend)': 'onAnimationEnd($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarMobileMenu {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly provider = inject(ScNavbarProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly state = signal<ScNavbarMobileMenuState>('closed');
+
+  protected readonly class = computed(() =>
+    cn(
+      'md:hidden',
+      'fixed inset-x-0 top-[calc(var(--navbar-height,57px))] bottom-0',
+      'z-50',
+      'flex flex-col gap-2 p-6',
+      'bg-background border-t border-border',
+      'animate-in fade-in-0 slide-in-from-top duration-300',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top data-[state=closed]:duration-300',
+      this.classInput(),
+    ),
+  );
+
+  constructor() {
+    // Sync state with provider's open signal
+    effect(() => {
+      const isOpen = this.provider.open();
+      this.state.set(isOpen ? 'open' : 'closed');
+    });
+  }
+
+  protected onAnimationEnd(event: AnimationEvent): void {
+    // Only trigger cleanup when close animation completes
+    if (
+      this.state() === 'closed' &&
+      event.target === this.elementRef.nativeElement
+    ) {
+      this.provider.onMenuAnimationComplete();
+    }
+  }
+}

package/src/lib/components/navbar/navbar-mobile-portal.ts

@@ -0,0 +1,118 @@
+import { CdkTrapFocus } from '@angular/cdk/a11y';
+import { Overlay, OverlayModule, OverlayRef } from '@angular/cdk/overlay';
+import { TemplatePortal } from '@angular/cdk/portal';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  DestroyRef,
+  effect,
+  inject,
+  input,
+  TemplateRef,
+  ViewChild,
+  ViewContainerRef,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScNavbarProvider } from './navbar-provider';
+
+@Component({
+  selector: 'div[sc-navbar-mobile-portal]',
+  imports: [OverlayModule, CdkTrapFocus],
+  template: `
+    <ng-template #mobileMenuTemplate>
+      <div cdkTrapFocus [cdkTrapFocusAutoCapture]="true">
+        <ng-content />
+      </div>
+    </ng-template>
+  `,
+  host: {
+    'data-slot': 'navbar-mobile-portal',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarMobilePortal {
+  private readonly provider = inject(ScNavbarProvider);
+  private readonly overlay = inject(Overlay);
+  private readonly viewContainerRef = inject(ViewContainerRef);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  @ViewChild('mobileMenuTemplate', { static: true })
+  private mobileMenuTemplate!: TemplateRef<unknown>;
+
+  protected readonly origin = computed(() => this.provider.origin());
+  protected readonly class = computed(() => cn('md:hidden', this.classInput()));
+
+  private overlayRef: OverlayRef = this.overlay.create({
+    positionStrategy: this.overlay.position().global(),
+    hasBackdrop: false,
+    scrollStrategy: this.overlay.scrollStrategies.block(),
+  });
+
+  constructor() {
+    // Cleanup memory when component is destroyed
+    this.destroyRef.onDestroy(() => {
+      this.overlayRef.dispose();
+    });
+
+    // Handle Keyboard Close
+    this.overlayRef.keydownEvents().subscribe((event) => {
+      if (event.key === 'Escape') this.closeMenu();
+    });
+
+    // Update Position Strategy when Origin becomes available
+    effect(() => {
+      const origin = this.origin();
+      if (origin?.elementRef) {
+        const positionStrategy = this.overlay
+          .position()
+          .flexibleConnectedTo(origin.elementRef)
+          .withPositions([
+            {
+              originX: 'start',
+              originY: 'bottom',
+              overlayX: 'start',
+              overlayY: 'top',
+            },
+          ])
+          .withPush(false);
+
+        this.overlayRef.updatePositionStrategy(positionStrategy);
+      }
+    });
+
+    // Use overlayOpen instead of open to delay DOM removal until animation completes
+    effect(() => {
+      if (this.provider.overlayOpen()) {
+        this.attachMenu();
+      } else {
+        this.detachMenu();
+      }
+    });
+  }
+
+  private attachMenu(): void {
+    if (!this.overlayRef.hasAttached()) {
+      const portal = new TemplatePortal(
+        this.mobileMenuTemplate,
+        this.viewContainerRef,
+      );
+      this.overlayRef.attach(portal);
+    }
+  }
+
+  private detachMenu(): void {
+    if (this.overlayRef.hasAttached()) {
+      this.overlayRef.detach();
+    }
+  }
+
+  private closeMenu(): void {
+    this.provider.open.set(false);
+  }
+}

package/src/lib/components/navbar/navbar-mobile-trigger.ts

@@ -0,0 +1,51 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScNavbarProvider } from './navbar-provider';
+
+@Component({
+  selector: 'button[sc-navbar-mobile-trigger]',
+  exportAs: 'scNavbarMobileTrigger',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'navbar-mobile-trigger',
+    type: 'button',
+    '[class]': 'class()',
+    '[attr.aria-expanded]': 'isMobileMenuOpen()',
+    '[attr.aria-controls]': '"navbar-mobile-menu"',
+    '(click)': 'toggleMenu()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarMobileTrigger {
+  readonly provider = inject(ScNavbarProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  readonly isMobileMenuOpen = this.provider.open;
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex items-center justify-center gap-2',
+      'md:hidden',
+      'size-10 rounded-md',
+      'text-foreground',
+      'hover:bg-accent hover:text-accent-foreground',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      '[&_svg]:pointer-events-none [&_svg]:size-6 [&_svg]:shrink-0',
+      this.classInput(),
+    ),
+  );
+
+  toggleMenu(): void {
+    this.provider.open.update((open) => !open);
+  }
+}

package/src/lib/components/navbar/navbar-provider.ts

@@ -0,0 +1,85 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  contentChild,
+  effect,
+  inject,
+  input,
+  model,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { NavigationEnd, Router } from '@angular/router';
+import { filter } from 'rxjs';
+import { cn } from '@semantic-components/ui';
+import { ScNavbar } from './navbar';
+
+@Component({
+  selector: 'div[sc-navbar-provider]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'navbar-provider',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScNavbarProvider {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  /**
+   * Logical state: Controls animation state (open/closed)
+   * - When true: Triggers entry animation
+   * - When false: Triggers exit animation
+   */
+  readonly open = model<boolean>(false);
+
+  /**
+   * Physical state: Controls DOM presence via overlay
+   * - When true: Content exists in DOM (can animate)
+   * - When false: Content removed from DOM
+   * - Stays true during close animation to allow it to complete
+   */
+  readonly overlayOpen = signal<boolean>(false);
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+
+  private readonly navbar = contentChild(ScNavbar);
+  readonly origin = computed(() => this.navbar()?.overlayOrigin);
+
+  private readonly router = inject(Router);
+
+  constructor() {
+    // Close mobile menu on navigation
+    this.router.events
+      .pipe(
+        filter((event) => event instanceof NavigationEnd),
+        filter(() => this.open()),
+        takeUntilDestroyed(),
+      )
+      .subscribe(() => this.open.set(false));
+
+    // Synchronize overlay state with logical state for opening
+    effect(() => {
+      if (this.open()) {
+        // Opening: Mount DOM immediately so animation can start
+        this.overlayOpen.set(true);
+      }
+      // Note: When closing (open = false), overlayOpen stays true
+      // until animation completes (handled by onMenuAnimationComplete)
+    });
+  }
+
+  /**
+   * Called by mobile menu when its close animation completes
+   */
+  onMenuAnimationComplete(): void {
+    if (!this.open()) {
+      this.overlayOpen.set(false);
+    }
+  }
+}