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

$3

Empty shell - demo / source

!empty shell demo image

Concrete angular routes - demo / source

!concrete angular routes demo image

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

!dynamic routes demo image

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

$3

``bash
npm i @jamesbenrobb/app-shell@latest
`






$3

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

@include app-shell.setJBRAppShellVars();
`






$3

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


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






$3

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


@Component({
selector: 'app-root',
standalone: true,
imports: [
AppShellLayoutComponent
],
template:


,
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




$3

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



$3

The following tokens are exposed:

- AppShellMenuConfigService
- AppShellRouteManagerService

`ts
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

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.

`ts
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)
]
};
`



$3

The following token is exposed:

- AppShellSearchService

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

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


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

class MySearchService implements SearchService {

readonly #results = new Subject();
readonly results$: Observable = this.#results.asObservable();

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



$3

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

`ts
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();
}
`

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

`ts
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

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


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



$3

The app layout component has a default unnamed content slot.

`html





`

$3

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

`html





`

$3

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:

`scss
@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
`html

...

`
or
`html

...

``