File

libs/ui/navigation/src/lib/nav/navigation.component.ts

Description

A responsive, horizontal navigation.

Implements

OnInit AfterViewInit

Example

<ts-navigation
  [items]="navigationItems$ | async"
  [user]="currentUser$ | async"
  userNameLength="20"
  welcomeMessage="Hi!"
  welcomeMsgLength="25"
  (action)="myMethod($event)"
></ts-navigation>

<example-url>https://getterminus.github.io/ui-demos-release/components/navigation</example-url>

Metadata

changeDetection ChangeDetectionStrategy.OnPush
encapsulation ViewEncapsulation.None
exportAs tsNavigation
host {
}
selector ts-navigation
styleUrls ./navigation.component.scss
templateUrl ./navigation.component.html

Index

Properties
Methods
Inputs
Outputs
HostListeners
Accessors

Constructor

constructor(changeDetectorRef: ChangeDetectorRef)
Parameters :
Name Type Optional
changeDetectorRef ChangeDetectorRef No

Inputs

items
Type : []

Accept the array of navigation items and trigger setup

user
Type : TsUser

Accept the user data

userNameLength
Default value : DEFAULT_USER_NAME_MAX_LENGTH

Define the user name length

welcomeMessage
Default value : 'Welcome'

Define the welcome message

welcomeMsgLength
Default value : DEFAULT_WELCOME_MESSAGE_MAX_LENGTH

Define the welcome message length

Outputs

action
Type : EventEmitter<TsNavigationPayload>

Emit the click event with the TsNavigationPayload

HostListeners

window:resize
window:resize()

Trigger a layout update when the window resizes

Methods

Public isExternalLink
isExternalLink(destination: string | string[])

If the destination is a string and begins with http

Parameters :
Name Type Optional Description
destination string | string[] No
  • The destination to check
Returns : boolean

Boolean determining if the link is external

Public trackByFn
trackByFn(index)

Function for tracking for-loops changes

Parameters :
Name Optional Description
index No
  • The item index
Returns : number

The unique ID

Properties

Public hiddenItems
Type : BehaviorSubject<TsNavigationItem[]>
Default value : new BehaviorSubject([] as TsNavigationItem[])

Define the list of hidden items

Public iconDropDown
Default value : faCaretDown

Define the dropdown icon

Public visibleItems
Default value : new BehaviorSubject<TsNavigationItem[]>([])

The collection of visible navigation items

Public visibleItemsList
Type : ElementRef
Decorators :
@ViewChild('visibleItemsList', {static: true})

Element reference for visible list items

Public visibleLinkElement
Type : QueryList<ElementRef>
Decorators :
@ViewChildren('visibleLinkElement')

Query list of all elements from the visible items list

Accessors

usersFullName
getusersFullName()

Getter to return the user's full name if it exists

Returns : string | null
visibleItemsLength
getvisibleItemsLength()

Getter to return the count of visible items

Returns : number
items
setitems(value: [])

Accept the array of navigation items and trigger setup

Parameters :
Name Type Optional
value [] No
Returns : void
import {
  AfterViewInit,
  ChangeDetectionStrategy,
  ChangeDetectorRef,
  Component,
  ElementRef,
  EventEmitter,
  HostListener,
  Input,
  OnInit,
  Output,
  QueryList,
  ViewChild,
  ViewChildren,
  ViewEncapsulation,
} from '@angular/core';
import { faCaretDown } from '@fortawesome/pro-solid-svg-icons/faCaretDown';
import { BehaviorSubject } from 'rxjs';

import { groupBy } from '@terminus/fe-utilities';

/**
 * Define the user object interface
 */
export interface TsUser {
  /**
   * The user's full name
   */
  fullName: string;
}

/**
 * Base allowed keys for an item passed to the {@link TsNavigationComponent}
 */
export interface NavigationItemBase {
  /**
   * The value to use as the item text
   */
  name: string;
  /**
   * Define if the item should only be allowed in the secondary navigation
   */
  // TODO: API change for clarity
  alwaysHidden: boolean;
  /**
   * Define if the item is disabled
   */
  isDisabled?: boolean;
  /**
   * Define if the item is for admin functionality only
   */
  // TODO: API change for clarity. Should likely be something more general that defines how the link is treated rather than where it takes
  // the user.
  isForAdmin?: boolean;
}

/**
 * Link specific keys for an item passed to the {@link TsNavigationComponent}
 */
export interface TsNavigationLinkItem extends NavigationItemBase {
  /**
   * The destination for items with a 'navigate' action. Single strings are used for external
   * locations while an array of strings are used for routerLinks
   */
  destination: string | string[];
  /**
   * Whether this link should navigate via the router or standard href
   */
  isExternal?: boolean;
}

/**
 * Action specific keys for an item passed to the {@link TsNavigationComponent}
 */
export interface TsNavigationActionItem extends NavigationItemBase {
  /**
   * The action to emit upon interaction
   */
  action: {
    type: string;
  };
}

/**
 * Determine if a navigation item is a {@link TsNavigationLinkItem}
 *
 * @param x - The item to check
 * @returns True if the item is a TsNavigationLinkItem
 */
export const isLinkItem =
  (x: TsNavigationLinkItem | TsNavigationActionItem): x is TsNavigationLinkItem => !!(x as TsNavigationLinkItem).destination;

/**
 * Define the allowed keys and types for an item passed to the {@link TsNavigationComponent}
 */
export type TsNavigationItem = TsNavigationLinkItem | TsNavigationActionItem;

/**
 * Define the expected response from the {@link TsNavigationComponent} emitter
 */
export interface TsNavigationPayload {
  /**
   * The mouse click event
   */
  event: MouseEvent;

  /**
   * The selected item
   */
  action: {
    type: string;
  };
}

const DEFAULT_USER_NAME_MAX_LENGTH = 20;
const DEFAULT_WELCOME_MESSAGE_MAX_LENGTH = 20;

/**
 * A responsive, horizontal navigation.
 *
 * @example
 * <ts-navigation
 *              [items]="navigationItems$ | async"
 *              [user]="currentUser$ | async"
 *              userNameLength="20"
 *              welcomeMessage="Hi!"
 *              welcomeMsgLength="25"
 *              (action)="myMethod($event)"
 * ></ts-navigation>
 *
 * <example-url>https://getterminus.github.io/ui-demos-release/components/navigation</example-url>
 */
@Component({
  selector: 'ts-navigation',
  templateUrl: './navigation.component.html',
  styleUrls: ['./navigation.component.scss'],
  host: { class: 'ts-navigation' },
  encapsulation: ViewEncapsulation.None,
  changeDetection: ChangeDetectionStrategy.OnPush,
  exportAs: 'tsNavigation',
})
export class TsNavigationComponent implements OnInit, AfterViewInit {
  /**
   * Store a pristine copy of the navigation items
   */
  private pristineItems!: TsNavigationItem[];

  /**
   * Getter to return the available navigation width
   *
   * @returns The available navigation space
   */
  private get availableSpace(): number {
    const NAV_WIDTH_BUFFER = 10;

    return this.visibleItemsList.nativeElement.offsetWidth - NAV_WIDTH_BUFFER;
  }

  /**
   * Define an array of widths at which to break the navigation
   */
  private breakWidths: number[] = [];

  /**
   * Define the list of hidden items
   */
  public hiddenItems: BehaviorSubject<TsNavigationItem[]> = new BehaviorSubject([] as TsNavigationItem[]);

  /**
   * Define the dropdown icon
   */
  public iconDropDown = faCaretDown;

  /**
   * Getter to return the user's full name if it exists
   *
   * @returns The user's full name
   */
  public get usersFullName(): string | null {
    const userExists = !!this.user;
    const nameExists = userExists && (this.user.fullName.length > 0);

    return (userExists && nameExists) ? this.user.fullName : null;
  }

  /**
   * The collection of visible navigation items
   */
  public visibleItems = new BehaviorSubject<TsNavigationItem[]>([]);

  /**
   * Getter to return the count of visible items
   *
   * @returns The number of visible items
   */
  public get visibleItemsLength(): number {
    return this.visibleItems.getValue().length;
  }

  /**
   * Accept the array of navigation items and trigger setup
   *
   * @param value
   */
  @Input()
  public set items(value: TsNavigationItem[]) {
    // Filter out disabled items
    this.pristineItems = value.filter((item: TsNavigationItem) => !item.isDisabled);
    this.setUpInitialArrays(this.pristineItems);
    this.generateBreakWidths();
    this.updateLists();
  }

  /**
   * Accept the user data
   */
  @Input()
  public user!: TsUser;

  /**
   * Define the user name length
   */
  @Input()
  public userNameLength = DEFAULT_USER_NAME_MAX_LENGTH;

  /**
   * Define the welcome message
   */
  @Input()
  public welcomeMessage = 'Welcome';

  /**
   * Define the welcome message length
   */
  @Input()
  public welcomeMsgLength = DEFAULT_WELCOME_MESSAGE_MAX_LENGTH;

  /**
   * Element reference for visible list items
   */
  @ViewChild('visibleItemsList', { static: true })
  public visibleItemsList!: ElementRef;

  /**
   * Query list of all elements from the visible items list
   */
  @ViewChildren('visibleLinkElement')
  public visibleLinkElement!: QueryList<ElementRef>;

  /**
   * Emit the click event with the {@link TsNavigationPayload}
   */
  @Output()
  public readonly action: EventEmitter<TsNavigationPayload> = new EventEmitter();

  /**
   * Trigger a layout update when the window resizes
   */
  @HostListener('window:resize')
  public onResize(): void {
    this.updateLists();
  }

  constructor(private changeDetectorRef: ChangeDetectorRef) {}

  /**
   * Set up initial link groups
   */
  public ngOnInit(): void {
    this.setUpInitialArrays(this.pristineItems);
  }

  /**
   * Trigger initial layout update after the view initializes
   */
  public ngAfterViewInit(): void {
    this.generateBreakWidths();
    this.updateLists();
    this.changeDetectorRef.detectChanges();
  }

  /**
   * Generate the array of breakWidths
   */
  private generateBreakWidths(): void {
    let totalSpace = 0;
    this.breakWidths.length = 0;

    // Loop through the visible links
    this.visibleLinkElement.forEach((item: ElementRef) => {
      // Tally up the total space
      totalSpace += item.nativeElement.offsetWidth;
      // Add the total space as a breakpoint
      this.breakWidths.push(totalSpace);
    });
  }

  /**
   * Clone the nav items and split into the initially visible/hidden lists
   *
   * @param items - The complete list of navigation items
   */
  private setUpInitialArrays(items: TsNavigationItem[]): void {
    // Clone the items and define the external flag for links only
    const allItems = items.map(i => {
      const item: TsNavigationItem = { ...i };
      if (isLinkItem(item)) {
        item.isExternal = this.isExternalLink(item.destination);
      }
      return item;
    });

    // Create an object with the arrays separated
    const splitArrays = groupBy(allItems, 'alwaysHidden');

    // Push the separated arrays
    this.visibleItems.next(splitArrays.false);
    this.hiddenItems.next(splitArrays.true);

    this.changeDetectorRef.detectChanges();
  }

  /**
   * Move items between the two lists as required by the available space
   */
  private updateLists(): void {
    const requiredSpace = this.breakWidths[this.visibleItemsLength - 1];

    // If there is not enough space
    if (requiredSpace > this.availableSpace) {
      // Pull the last link out of the visible array
      const currentVisible: TsNavigationItem[] = this.visibleItems.getValue();
      const itemToMove = currentVisible.pop();
      const updatedHiddenArray: TsNavigationItem[] = this.hiddenItems.getValue();

      // If an item was found, add it to the beginning of the hidden items array
      // istanbul ignore else
      if (itemToMove) {
        updatedHiddenArray.unshift(itemToMove);
      }

      // Push out the updated value
      this.hiddenItems.next(updatedHiddenArray);

      // Trigger another layout check
      this.updateLists();
    } else if (this.availableSpace > this.breakWidths[this.visibleItemsLength]) {
      // Else, if there is more than enough space

      // Pull the first item from the hidden array
      const currentHidden = this.hiddenItems.getValue();
      const itemToMove = currentHidden.shift();
      const updatedVisibleArray: TsNavigationItem[] = this.visibleItems.getValue();

      // If an item was found, add it to the beginning of the hidden items array
      // istanbul ignore else
      if (itemToMove) {
        updatedVisibleArray.push(itemToMove);
      }

      // Add it to the end of the visible array
      this.visibleItems.next(updatedVisibleArray);
    }

    this.changeDetectorRef.detectChanges();
  }

  /**
   * If the destination is a string and begins with `http`
   *
   * @param destination - The destination to check
   * @returns Boolean determining if the link is external
   */
  public isExternalLink(destination: string | string[]): boolean {
    return destination.indexOf('http') >= 0;
  }

  /**
   * Function for tracking for-loops changes
   *
   * @param index - The item index
   * @returns The unique ID
   */
  public trackByFn(index): number {
    return index;
  }
}

result-matching ""

    No results matching ""