@jamesbenrobb/app-shell

App Shell

What.

A simple, configurable, app template built with Angular Material components, that's decoupled from both content and router implementation.

You get:

• Colour modes
• Breadcrumbs
• Search input
• Side menu nav tree
• Header slot
• Content slot
• Configurable themes

Demos

Empty shell - demo / source

Concrete angular routes - demo / source

Dynamic routes - demo / source - implemented with @jamesbenrobb/dynamic-routes-ngx

Why.

Whilst creating Documentor it occurred to me that it would be useful to abstract out the underlying dynamic routing implementation/behaviour to use for other apps.

Annoyingly, once this was complete, it then occurred to me that it would also be useful to abstract out the UI app shell to use with different routing solutions. This is the result.

Examples of use:

1. Angular router inspector
2. Portfolio V3
3. JBR Libs docs
   
   

How.

1. Install
2. Include styles
3. Add providers
4. Add the layout component
5. Configure for your own use
   
   

Install

npm i @jamesbenrobb/app-shell@latest

Include styles

@use "@jamesbenrobb/app-shell" as app-shell;

@include app-shell.setJBRAppShellVars();

Add providers

import {ApplicationConfig} from '@angular/core';
import {getJBRAppShellProviders} from "@jamesbenrobb/app-shell";


export const appConfig: ApplicationConfig = {
  providers: [
    getJBRAppShellProviders()
  ]
};

Add the layout component

import { Component } from '@angular/core';
import {AppShellLayoutComponent} from "@jamesbenrobb/app-shell";


@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    AppShellLayoutComponent
  ],
  template: `
    <jbr-app-shell-layout>
    </jbr-app-shell-layout>
  `,
  styleUrl: './app.component.scss'
})
export class AppComponent {}

Configure for your own use.

1. Provider options
2. Configure navigation
3. Configure search input
4. Add your own content
5. Add your own header content
6. Add your own side menu component
7. Declare your own light and dark themes
   
   

Provider options

export type AppShellOptions = {
  displayColorModeBtn?: boolean,
  displayBreadcrumbs?: boolean,
  sideMenuComponentType?: string
}

Configure navigation

The following tokens are exposed:

• AppShellMenuConfigService
• AppShellRouteManagerService

import {Provider} from "@angular/core";
import {NavConfig, NavItemNode} from "@jamesbenrobb/ui";
import {AppShellMenuConfigService, AppShellRouteManagerService} from "@jamesbenrobb/app-shell";
import {Router} from "@angular/router";

const navMenuProvider: Provider = {
  provide: AppShellMenuConfigService,
  useFactory: () => convertRoutes(inject(Router).config)
}

const routeManagerProvider: Provider = {
  provide: AppShellRouteManagerService,
  useFactory: () => new DefaultAngularRouteManager(inject(Router))
}


function convertRoutes(): NavConfig {
    const items: NavConfig = // logic that converts angular routes into an array of NavItemNode 
    return items;
}


class DefaultAngularRouteManager implements AppShellRouteManager {

  readonly #router: Router;

  readonly urlChange$: Observable<string>

  constructor(router: Router) {
    this.#router = router;

    this.urlChange$ = this.#router.events.pipe(
      filter((event): event is NavigationEnd => event instanceof NavigationEnd),
      map((event: NavigationEnd) => {
        return (event as NavigationEnd).url;
      })
    );
  }

  navigateByUrl(path: string): void {
    this.#router.navigateByUrl(path);
  }
}

Or use the getJBRAppShellAngularRouterProviders helper provider in @jamesbenrobb/app-shell-routing-adaptors, which does exactly the same as above.

import {ApplicationConfig} from '@angular/core';
import {getJBRAppShellProviders} from "@jamesbenrobb/app-shell";
import {getJBRAppShellAngularRouterProviders} from "@jamesbenrobb/app-shell-routing-adaptors"
import {routes} from "./app.routes";


export const appConfig: ApplicationConfig = {
  providers: [
    getJBRAppShellProviders(),
    getJBRAppShellAngularRouterProviders(routes)
  ]
};

Configure search input

The following token is exposed:

• AppShellSearchService

By providing this token the search input is automatically displayed in the header.

import {Observable, Subject} from "rxjs";
import {SearchService} from '@jamesbenrobb/app-shell';


const provider: Provider = {
  provide: AppShellSearchService,
  useClass: MySearchService
}

class MySearchService implements SearchService<string> {

  readonly #results = new Subject<string[]>();
  readonly results$: Observable<string[]> = this.#results.asObservable();

  search(query: string): void {
    const result: string[] = // search something
    this.#results.next(result);
  }
}

Add your own side menu component

By default a slightly modified version of mat-tree is used. If you wish to supply your own menu first create a menu component that implements SideMenuComponentIO

import {Component, Input, Output} from "@angular/core";
import {SideMenuComponentIO} from "@jamesbenrobb/app-shell";
import {NavItemNode} from "@jamesbenrobb/ui";


@Component({
  selector: 'my-side-menu',
  templateUrl: '...',
  styleUrls: ['...'],
  standalone: true
})
export class MySideMenuComponent implements SideMenuComponentIO {
  @Input() menuNodes?: NavItemNode[];
  @Input() currentNodes?: NavItemNode[];

  @Output() nodeSelected = new EventEmitter<NavItemNode>();
}

Register the component with the ComponentLoaderMapService (see details on registering components here) and add the provider to your app

import {Provider} from "@angular/core";
import {ComponentLoaderMapService} from "@jamesbenrobb/ui";


const provider: Provider = {
  provide: ComponentLoaderMapService,
  useValue: {
    'my-side-menu': {
      import: () => import('./my-side-menu.component'),
      componentName: 'MySideMenuComponent'
    }
  },
  multi: true
}

Supply the registered name of you side menu component to getJBRAppShellProviders

import {ApplicationConfig} from '@angular/core';
import {getJBRAppShellProviders} from "@jamesbenrobb/app-shell";


export const appConfig: ApplicationConfig = {
  providers: [
    getJBRAppShellProviders({
      sideMenuComponentType: 'my-side-menu'
    })
  ]
};

Add your own content

The app layout component has a default unnamed content slot.

<jbr-app-shell-layout>
  <div>I'm the content</div>
</jbr-app-shell-layout>

Add your own header content

The app layout component header has a named content slot that can be used to project bespoke content.

<jbr-app-shell-layout>
  <div jbr-dra-header-content>I'm the header text</div>
</jbr-app-shell-layout>

Declare your own light and dark themes

Approximately 90% of the app uses Angular Material components and the other 10% support being themed.

To supply your own themes the setJBRAppShellVars mixin has the following optional arguments:

@use '@angular/material' as mat;
@use "@jamesbenrobb/app-shell" as app-shell;

@include app-shell.setJBRAppShellVars(
    $light-theme, // an Angular material light theme created with mat.define-light-theme
    $dark-theme, // an Angular material dark theme created with mat.define-dark-theme
    $typography, // an Angular material typography config created with mat.define-typography-config
    $side-menu-width // a custom width for the side menu - defaults to 320px
);

The app also comes with a light/dark mode switch that sets a data-* attribute on body. When explicitly selected, the switch also stores the users preference in LocalStorage, overriding the mode of the OS. The following can be used to style your own components

<body [data-color-mode]="light">
...
</body>

or

<body [data-color-mode]="dark">
...
</body>