npm - @lukfel/ng-scaffold - Versions diffs - 20.0.10 - Mend

@lukfel/ng-scaffold 20.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

package/.eslintrc.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "extends": "../../.eslintrc.json",
+  "ignorePatterns": [
+    "!**/*"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "*.ts"
+      ],
+      "rules": {
+        "@angular-eslint/directive-selector": [
+          "error",
+          {
+            "type": "attribute",
+            "prefix": "lf",
+            "style": "camelCase"
+          }
+        ],
+        "@angular-eslint/component-selector": [
+          "error",
+          {
+            "type": "element",
+            "prefix": "lf",
+            "style": "kebab-case"
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "*.html"
+      ],
+      "rules": {}
+    }
+  ]
+}

package/README.md ADDED Viewed

@@ -0,0 +1,382 @@
+# Documentation
+## Introduction
+This Angular library provides a foundational scaffold for modern web and mobile applications. It includes essential UI elements such as a header, sidebar, drawer, footer, floating button, and built-in services for theme switching, snackbar notifications, dialog management, and breakpoint detection. Simply wrap your `router-outlet` with the `lf-scaffold` element and configure the `ScaffoldConfig` within the `ScaffoldService`.
+- **NPM**: [@lukfel/ng-scaffold](https://www.npmjs.com/package/@lukfel/ng-scaffold)
+- **Demo**: [lukfel.github.io/ng-scaffold](https://lukfel.github.io/ng-scaffold)
+- **Examples**: [Create a Tournament](https://www.create-a-tournament.com), [What a Waste](https://www.what-a-waste.at), [Uglygotchi](https://www.uglygotchi.at)
+## Installation
+Install the package using npm:
+```sh
+npm install @lukfel/ng-scaffold
+```
+## Module
+Import the `ScaffoldModule` into your `app.module.ts` file.
+* **Note:** (Optional) The library includes a built-in logging service called `Logger`, which logs library deugging events when a `ScaffoldLibraryConfig` is provided and `debugging` is set to `true`. Logging is automatically disabled in production mode when `prodution` is set to `true`.
+```ts
+import { ScaffoldModule } from '@lukfel/ng-scaffold';
+import { isDevMode } from '@angular/core';
+@NgModule({
+  ...
+  imports: [
+    ScaffoldModule.forRoot({ production: !isDevMode(), debugging: isDevMode() }),    // Omit .forRoot(...) if logging is not required
+  ]
+})
+export class AppModule { }
+```
+## Styling
+Import the styles in your `styles.scss` and apply a default theme.
+* **Note:** The library’s styles include Material icons and Roboto font styles.
+```scss
+@use "@lukfel/ng-scaffold/styles" as lf;
+@include lf.scaffold-theme();           // include a default theme
+```
+### Custom Themes (Optional)
+To customize the default theme, define a new theme map specifying `primary`, `accent`, and `warn` colors using Material palettes. Enabling the `dark` option applies a dark theme. Pass your custom theme to `lf.scaffold-theme($my-theme)`.
+```scss
+@use "@lukfel/ng-scaffold/styles" as lf;
+@use '@angular/material' as mat;
+$my-theme: (
+  primary: mat.define-palette(mat.$pink-palette),
+  accent: mat.define-palette(mat.$blue-palette),
+  warn: mat.define-palette(mat.$red-palette),
+  dark: false
+);
+@include lf.scaffold-theme($my-theme);
+```
+### Multiple Themes (Optional)
+To switch between multiple themes dynamically, define additional themes using `lf.scaffold-colors($theme, 'theme-class')`, then apply the class to the `<body class="theme-class">` tag.
+* **Note:** The `ThemeService` allows dynamic theme switching.
+```scss
+@use "@lukfel/ng-scaffold/styles" as lf;
+@use '@angular/material' as mat;
+$my-theme: (
+  primary: mat.define-palette(mat.$pink-palette),
+  accent: mat.define-palette(mat.$blue-palette),
+  warn: mat.define-palette(mat.$red-palette),
+  dark: false
+);
+$my-theme2: (
+  primary: mat.define-palette(mat.$purple-palette),
+  accent: mat.define-palette(mat.$amber-palette),
+  dark: false
+);
+@include lf.scaffold-theme($my-theme);                      // Set the primary theme with lf.scaffold-theme(...)
+@include lf.scaffold-colors($my-theme2, 'my-theme2');       // Set additional themes with lf.scaffold-colors(...)
+```
+### Custom Typography (Optional)
+To change the default typography from Roboto, pass an additional parameter ``font-family`` in the theme map.
+* **Note:** Don't forget to also import and set the font-family in the styles.
+```scss
+@use "@lukfel/ng-scaffold/styles" as lf;
+@use '@angular/material' as mat;
+$my-theme: (
+  primary: mat.define-palette(mat.$pink-palette),
+  accent: mat.define-palette(mat.$blue-palette),
+  warn: mat.define-palette(mat.$red-palette),
+  dark: false,
+  font-family: 'Comic Sans'
+);
+@include lf.scaffold-theme($my-theme);
+body {
+    font-family: "Comic Sans MS" !important;
+}
+```
+## Template
+Wrap your application’s content inside the `lf-scaffold` component in `app.component.html`.
+```html
+<lf-scaffold>
+  <!-- (Optional) drawer content shows inside the left drawer if enabled -->
+  <ng-container drawerContent></ng-container>
+  <router-outlet></router-outlet>
+</lf-scaffold>
+```
+## Configuration
+Import the `ScaffoldService` in `app.component.ts` to manage the `ScaffoldConfig` settings.
+```ts
+import { ScaffoldService } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private scaffoldService: ScaffoldService) {}
+}
+```
+### Update Configuration
+Define the `ScaffoldConfig` in `app.component.ts` and update the `scaffoldConfig` property in `ScaffoldService`.
+* **Notes:**
+    * If a sub-configuration (e.g., `headerConfig`) is missing or does not have `enable: true`, the corresponding UI element will not be displayed.
+    * Refer to the demo project for full configuration details.
+```ts
+import { ScaffoldService, ScaffoldConfig } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  public scaffoldConfig: ScaffoldConfig = {
+    scrollPositionRestoration: true,
+    headerConfig: { enable: true, title: 'Scaffold', subtitle: 'by Lukas Felbinger' },
+    navbarConfig: { enable: true },
+    footerConfig: { enable: true, copyright: '© Lukas Felbinger 2023' },
+    floatingButtonConfig: { enable: true }
+  };
+  constructor(private scaffoldService: ScaffoldService) {
+    this.scaffoldService.scaffoldConfig = this.scaffoldConfig;
+  }
+}
+```
+## Events
+There are two ways to listen to scaffold user events (button clicks, input changes, ...):
+### Option 1 (Recommended) – Subscribe to Observables
+Subscribe to the event Observables and listen to changes
+```ts
+constructor(private scaffoldService: ScaffoldService, private router: Router) {
+  // Listen to click events (header menu and navbar buttons - click)
+  this.scaffoldService.buttonClickEventValue$.subscribe((id: string) => {
+    this.router.navigate([id]);
+  });
+  // Listen to header input change events (header input field - change)
+  this.scaffoldService.headerInputChangeValue$.subscribe((value: string) => {
+    ...
+  });
+}
+```
+### Option 2 – Use Output Events
+Specify the needed output events and call custom methods
+```html
+<lf-scaffold
+  (headerButtonClickEvent)="headerButtonClickEvent($event)"
+  (headerInputSubmitEvent)="headerInputSubmitEvent($event)"
+  (headerInputChangeEvent)="headerInputChangeEvent($event)"
+  (navbarButtonClickEvent)="navbarButtonClickEvent($event)">
+  <router-outlet></router-outlet>
+</lf-scaffold>
+```
+```ts
+// Listen to header click events (header menu buttons - click)
+public headerButtonClickEvent(id: string): void {
+  this.router.navigate([id]);
+}
+// Listen to header input submit events (header input field - submit)
+public headerInputSubmitEvent(value: string): void {
+  ...
+}
+// Listen to header input change events (header input field - change)
+public headerInputChangeEvent(value: string): void {
+  ...
+}
+// Listen to navbar click events (navbar menu buttons - click)
+public navbarButtonClickEvent(id: string): void {
+  this.router.navigate([id]);
+}
+```
+## Additional Services
+This library includes several utility services:
+- **`Logger`** – Development-only logging
+- **`SnackbarService`** – Display snackbar notifications
+- **`DialogService`** – Display custom dialogs
+- **`BreakpointService`** – Detect screen breakpoints
+- **`ThemeService`** – Manage themes dynamically
+- **`RouterService`** – Track route changes and retreive route history
+- **`SeoService`** – Manage meta tags
+- **`LocalStorageService`** – Handle local storage
+### Logger
+Logs internal library information if `debugging` is `true` and hides application logs during production if `production` is `true`.
+* **Note:** `ScaffoldLibraryConfig` must be set during initialization ``ScaffoldModule.forRoot( { production: !isDevMode(), debugging: isDevMode() } )``
+```ts
+import { Logger } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private logger: Logger) {}
+  // Generic api call with logging
+  public apiCallWithLogging(): void {
+    this.apiService.apiCall().then(result => {
+      this.logger.log(result);
+    }).catch(error => {
+      this.logger.error(error);
+    });
+  }
+}
+```
+### SnackbarService
+Provides basic methods to display simple snackbar notifications with or without actions.
+```ts
+import { SnackbarService } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private snackbarService: SnackbarService) {}
+  // Generic api call with snackbar response
+  public apiCallWithSnackbarResponse(): void {
+    this.apiService.apiCall().then(result => {
+      this.snackbarService.openSnackbar('Call was successful');
+    }).catch(error => {
+      this.snackbarService.openSnackbar('Call was not successful');
+    });
+  }
+}
+```
+### DialogService
+Includes a basic confirmation dialog thar returns a `Promise`. Use the method `openCustomDialog` to pass your own dialog template and config.
+```ts
+import { DialogService } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private dialogService: DialogService) {}
+  // Generic api call with a subsequent confirmation dialog
+  public apiCallWithDialogConfirmation(): void {
+    this.dialogService.openConfirmDialog('Do you really want to make this api call?').then(response => {
+      // If the user confirmed the dialog, go through with the api call
+      if(response === true) {
+        this.apiService.apiCall().then(result => {
+          ...
+        }).catch(error => {
+          ...
+        });
+      }
+    });
+  }
+}
+```
+### BreakpointService
+Allows you to subscribe to breakpoint changes.
+```ts
+import { BreakpointService } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private breakpointService: BreakpointService) {
+    this.breakpointService.breakpoint$.subscribe((result: BreakpointState) => {
+      // Check which breakpoint is active
+      if (result.breakpoints[Breakpoints.XSmall]) {
+        ...
+      } else if (result.breakpoints[Breakpoints.Small]) {
+        ...
+      } else if (result.breakpoints[Breakpoints.Medium]) {
+        ...
+      } else if (result.breakpoints[Breakpoints.Large]) {
+        ...
+      }
+    });
+  }
+}
+```
+### ThemeService
+Dynamically change between your defined themes.
+* **Note:** The theme must be defined and included in your styles [see multiple themes](#multiple-themes-optional)
+```ts
+import { ThemeService } from '@lukfel/ng-scaffold';
+export class AppComponent {
+  constructor(private themeService: ThemeService) {
+    this.themeService.setTheme('my-theme2', true);    // the second parameter allows to persists the theme in the LocalStorage (using the built in LocalStorageService)
+  }
+}
+```
+## Interceptors
+Intercept HTTP Calls and automatically show a loading spinner.
+* **Note:** The loading spinner can also be manually shown by udpating the value for `scaffoldConfig.loading` in the `ScaffoldService`
+```ts
+import { ScaffoldModule } from '@lukfel/ng-scaffold';
+import { isDevMode } from '@angular/core';
+@NgModule({
+  ...
+  imports: [
+    ScaffoldModule.forRoot({ production: !isDevMode(), debugging: isDevMode() }),    // Omit .forRoot(...) if logging is not required
+  ],
+  providers: [
+    {
+      provide: HTTP_INTERCEPTORS,
+      useClass: LoadingInterceptor,
+      multi: true
+    }
+  ]
+})
+export class AppModule { }
+```

package/ng-package.json ADDED Viewed

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/ng-scaffold",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  },
+  "assets": ["./styles/*.scss","./styles/**/*"]
+}

package/package.json ADDED Viewed

@@ -0,0 +1,28 @@
+{
+  "name": "@lukfel/ng-scaffold",
+  "version": "20.0.10",
+  "description": "This Angular library provides a basic UI scaffold and services for modern web and mobile apps",
+  "license": "MIT",
+  "author": {
+    "name": "Lukas Felbinger",
+    "url": "https://www.lukasfelbinger.at"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lukfel/ng-scaffold"
+  },
+  "peerDependencies": {
+    "@angular/common": "^20.0.5",
+    "@angular/core": "^20.0.5",
+    "@angular/material": "^20.0.5"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "exports": {
+    "./styles": {
+      "sass": "./styles/style.scss"
+    }
+  },
+  "sideEffects": false
+}

package/src/lib/components/bottom-bar/bottom-bar.component.html ADDED Viewed

@@ -0,0 +1,29 @@
+@if (bottomBarConfig && bottomBarConfig.enable) {
+  <div
+    class="lf-bottom-bar px-4"
+    [ngClass]="bottomBarConfig.class"
+    [class.lf-bottom-bar-show-navbar]="!isMobile && navbarEnabled"
+    [class.lf-bottom-bar-show-navbar-mobile]="isMobile && navbarEnabled">
+    <button mat-icon-button (click)="closeClicked()">
+      <mat-icon>close</mat-icon>
+    </button>
+    @if (bottomBarConfig.message) {
+      <span class="ml-2">{{ bottomBarConfig.message }}</span>
+    }
+    @if (bottomBarConfig.actions) {
+      <div class="lf-bottom-bar-actions ml-4">
+        @for (action of bottomBarConfig.actions; track action) {
+          <button
+            mat-button
+            color="accent"
+            class="lf-bottom-bar-action ml-2"
+            [ngClass]="action.class"
+            (click)="actionClicked(action.id)"
+            [matTooltip]="action.tooltip!">
+            {{ action.label }}
+          </button>
+        }
+      </div>
+    }
+  </div>
+}

package/src/lib/components/bottom-bar/bottom-bar.component.scss ADDED Viewed

@@ -0,0 +1,33 @@
+@use '../../../../styles/variables' as *;
+.lf-bottom-bar {
+  transition: bottom $transition;
+  transition: left $transition;
+  z-index: 101;
+  position: fixed;
+  left: 0;
+  bottom: 0;
+  right: 0;
+  height: $bottom-bar-height;
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  background-color: var(--color-accent);
+  color: white;
+  &.lf-bottom-bar-show-navbar-mobile {
+    bottom: calc($navbar-height-mobile + (2 * $navbar-padding)) !important;
+  }
+  &.lf-bottom-bar-show-navbar {
+    left: calc($navbar-width + (2 * $navbar-padding)) !important;;
+  }
+  .lf-bottom-bar-actions {
+    .lf-bottom-bar-action {
+      color: var(--color-accent) !important;
+      background-color: white !important;
+    }
+  }
+}

package/src/lib/components/bottom-bar/bottom-bar.component.spec.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { SharedModule } from '../../shared/shared.module';
+import { BottomBarComponent } from './bottom-bar.component';
+describe('BottomBarComponent', () => {
+  let component: BottomBarComponent;
+  let fixture: ComponentFixture<BottomBarComponent>;
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      declarations: [BottomBarComponent],
+      imports: [SharedModule]
+    })
+      .compileComponents();
+    fixture = TestBed.createComponent(BottomBarComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/src/lib/components/bottom-bar/bottom-bar.component.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+import { BottomBarConfig } from '../../models';
+@Component({
+    selector: 'lf-bottom-bar',
+    templateUrl: './bottom-bar.component.html',
+    styleUrls: ['./bottom-bar.component.scss'],
+    standalone: false
+})
+export class BottomBarComponent {
+  @Input() public bottomBarConfig: BottomBarConfig | null = null;
+  @Input() public isMobile: boolean = false;
+  @Input() public navbarEnabled: boolean = false;
+  @Output() public bottomBarCloseClickEvent = new EventEmitter<string>();
+  @Output() public bottomBarButtonClickEvent = new EventEmitter<string>();
+  public actionClicked(id?: string): void {
+    if (!id) {
+      return;
+    }
+    this.bottomBarButtonClickEvent.emit(id);
+  }
+  public closeClicked(): void {
+    this.bottomBarCloseClickEvent.emit('bottom-bar_close');
+  }
+}

package/src/lib/components/content-title-card/content-title-card.component.html ADDED Viewed

@@ -0,0 +1,25 @@
+@if (contentTitleCardConfig && contentTitleCardConfig.enable) {
+  <mat-card
+    class="lf-content-title-card mat-elevation-z2 px-4"
+    [ngClass]="contentTitleCardConfig.class">
+    <!-- back button -->
+    @if (contentTitleCardConfig.showBackButton && routeHistory.length > 1) {
+      <button mat-icon-button color="accent" (click)="backButtonClicked()">
+        <mat-icon>arrow_back_ios</mat-icon>
+      </button>
+    }
+    <!-- spacer -->
+    <div style="flex: 1 1 auto"></div>
+    <!-- label -->
+    <span class="lf-content-title-card-label">
+      {{ contentTitleCardConfig.label || "" }}
+    </span>
+    <!-- spacer -->
+    <div style="flex: 1 1 auto"></div>
+    <!-- empty button spacer -->
+    <div
+      [style.width]="
+        contentTitleCardConfig.showBackButton && routeHistory.length > 1 ? '48px' : '0px'
+      "></div>
+  </mat-card>
+}

package/src/lib/components/content-title-card/content-title-card.component.scss ADDED Viewed

@@ -0,0 +1,17 @@
+@use '../../../../styles/variables' as *;
+.lf-content-title-card {
+  z-index: $content-title-card-z-index;
+  height: $content-title-card-height;
+  display: flex;
+  flex-flow: row nowrap;
+  align-items: center;
+  border-radius: 0;
+  .lf-content-title-card-label {
+    font-size: $content-title-card-labe-font-size;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}