ngx-st-sap-installed-instruments 18.0.0 → 18.0.1

package/README.md

@@ -1,11 +1,477 @@
 # NgxStSapInstalledInstruments
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.0.
+Angular components for displaying and managing SAP installed instruments (equipment) with details, service contracts, and activities.
 
-## Code scaffolding
+## Table of Contents
+- [Overview](#overview)
+- [Installation](#installation)
+- [Components](#components)
+- [Examples](#examples)
 
-Run `ng generate component component-name --project ngx-st-sap-installed-instruments` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-st-sap-installed-instruments`.
-> Note: Don't forget to add `--project ngx-st-sap-installed-instruments` or else it will be added to the default project in your `angular.json` file. 
+---
+
+## Overview
+
+The `ngx-st-sap-installed-instruments` library provides components for managing installed instruments/equipment in SAP including:
+- Searchable list of installed instruments
+- Detailed instrument information
+- Service contracts view
+- Service calls and activities
+- Attachments management
+- Territory filtering
+
+---
+
+## Installation
+
+```bash
+npm install ngx-st-sap-installed-instruments
+```
+
+Import the module in your application:
+
+```typescript
+import { NgxStSapInstalledInstrumentsModule } from 'ngx-st-sap-installed-instruments';
+
+@NgModule({
+  imports: [
+    NgxStSapInstalledInstrumentsModule
+  ]
+})
+export class AppModule { }
+```
+
+---
+
+## Components
+
+### SapInstalledInstrumentList
+
+Main component displaying searchable list of installed instruments.
+
+#### Selector
+```html
+<app-sap-installed-instrument-list></app-sap-installed-instrument-list>
+```
+
+#### Inputs
+
+##### `accessToken`
+- **Type:** `string`
+- **Description:** Authentication token for API requests.
+- **Example:**
+  ```typescript
+  [accessToken]="authToken"
+  ```
+
+##### `territoryFilter` (required)
+- **Type:** `boolean`
+- **Description:** When true, filters instruments by user's territory.
+- **Example:**
+  ```typescript
+  [territoryFilter]="true"
+  ```
+
+##### `showWithCardContent`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Wraps the component in a Material card.
+- **Example:**
+  ```typescript
+  [showWithCardContent]="false"
+  ```
+
+##### `useMapButton`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows a map button for location visualization.
+- **Example:**
+  ```typescript
+  [useMapButton]="true"
+  ```
+
+#### Features
+- Search by multiple criteria:
+  - Customer name
+  - Instrument serial number
+  - Item code
+  - Installation date range
+- Sort by various fields
+- Territory-based filtering
+- Pagination
+- Direct navigation to details
+- URL query parameter persistence
+
+#### Example
+
+```html
+<app-sap-installed-instrument-list
+  [accessToken]="token"
+  [territoryFilter]="true"
+  [showWithCardContent]="true"
+  [useMapButton]="false">
+</app-sap-installed-instrument-list>
+```
+
+```typescript
+export class InstrumentsComponent {
+  token = this.authService.getAccessToken();
+}
+```
+
+---
+
+### SapInstalledInstrumentListTable
+
+Table component showing the list of instruments.
+
+Used internally by SapInstalledInstrumentList but can be used standalone.
+
+#### Features
+- Sortable columns
+- Clickable rows for navigation
+- Display key information:
+  - Customer name
+  - Item code and description
+  - Serial number
+  - Internal serial number
+  - Installation date
+  - Status
+
+---
+
+### SapInstalledInstrumentListSearch
+
+Search form component for filtering instruments.
+
+Used internally by SapInstalledInstrumentList.
+
+#### Features
+- Customer search
+- Serial number search
+- Item code search
+- Date range picker for installation date
+- Clear filters button
+- Form validation
+
+---
+
+### SapInstalledInstrumentDetails
+
+Detailed view of a single installed instrument.
+
+#### Selector
+```html
+<app-sap-installed-instrument-details></app-sap-installed-instrument-details>
+```
+
+#### Features
+- Complete instrument information
+- Service contracts section
+- Service calls list
+- Activities log
+- Attachments
+- Tabbed interface
+
+---
+
+### DataDetailsView
+
+Displays the core data of the installed instrument.
+
+#### Features
+- Customer information
+- Item details
+- Serial numbers
+- Installation date
+- Location information
+- Status
+- Notes
+
+---
+
+### ServiceContractsListView
+
+Shows active and historical service contracts.
+
+#### Features
+- Contract number and description
+- Start and end dates
+- Contract status
+- Coverage details
+- Link to contract details
+
+---
+
+### ServiceContractDetailsView
+
+Detailed view of a single service contract.
+
+---
+
+### CallsListView
+
+Displays service calls related to the instrument.
+
+#### Features
+- Call ID and subject
+- Priority level
+- Status
+- Assigned technician
+- Creation and resolution dates
+- Call description
+
+---
+
+### CallDetailsView
+
+Detailed view of a service call.
+
+---
+
+### ActivitiesListView
+
+Shows activities/notes related to the instrument.
+
+#### Features
+- Activity type
+- Date and time
+- Performed by
+- Description
+- Duration
+
+---
+
+### ActivityDetailsView
+
+Detailed view of a single activity.
+
+---
+
+### AttachmentsListView
+
+Displays and manages attachments for the instrument.
+
+Uses the `ngx-st-attachments` component internally.
+
+---
+
+## Examples
+
+### Basic Instrument List
+
+```html
+<div class="instruments-page">
+  <h1>Installed Instruments</h1>
+  
+  <app-sap-installed-instrument-list
+    [accessToken]="accessToken"
+    [territoryFilter]="true">
+  </app-sap-installed-instrument-list>
+</div>
+```
+
+```typescript
+export class InstrumentsPageComponent {
+  accessToken: string;
+
+  constructor(private authService: AuthService) {
+    this.accessToken = this.authService.getToken();
+  }
+}
+```
+
+### With Map Integration
+
+```html
+<app-sap-installed-instrument-list
+  [accessToken]="accessToken"
+  [territoryFilter]="false"
+  [useMapButton]="true">
+</app-sap-installed-instrument-list>
+```
+
+### Without Card Wrapper (Custom Layout)
+
+```html
+<mat-card class="custom-instruments-card">
+  <mat-card-header>
+    <mat-card-title>Equipment List</mat-card-title>
+    <mat-card-subtitle>All installed instruments</mat-card-subtitle>
+  </mat-card-header>
+  
+  <mat-card-content>
+    <app-sap-installed-instrument-list
+      [accessToken]="accessToken"
+      [territoryFilter]="filterByTerritory"
+      [showWithCardContent]="false">
+    </app-sap-installed-instrument-list>
+  </mat-card-content>
+</mat-card>
+```
+
+### Instrument Details Page
+
+```html
+<div class="instrument-details-page">
+  <mat-toolbar>
+    <button mat-icon-button (click)="goBack()">
+      <mat-icon>arrow_back</mat-icon>
+    </button>
+    <span>Instrument Details</span>
+  </mat-toolbar>
+  
+  <app-sap-installed-instrument-details
+    [instrumentId]="instrumentId">
+  </app-sap-installed-instrument-details>
+</div>
+```
+
+```typescript
+export class InstrumentDetailsComponent implements OnInit {
+  instrumentId: string;
+
+  constructor(
+    private route: ActivatedRoute,
+    private location: Location
+  ) {}
+
+  ngOnInit() {
+    this.instrumentId = this.route.snapshot.params['id'];
+  }
+
+  goBack() {
+    this.location.back();
+  }
+}
+```
+
+### With Territory Filter Toggle
+
+```html
+<div class="instruments-with-filter">
+  <mat-toolbar>
+    <span>Installed Instruments</span>
+    <span class="toolbar-spacer"></span>
+    <mat-slide-toggle
+      [(ngModel)]="filterByTerritory"
+      (change)="onFilterChange()">
+      My Territory Only
+    </mat-slide-toggle>
+  </mat-toolbar>
+  
+  <app-sap-installed-instrument-list
+    [accessToken]="accessToken"
+    [territoryFilter]="filterByTerritory">
+  </app-sap-installed-instrument-list>
+</div>
+```
+
+```typescript
+export class InstrumentsComponent {
+  accessToken: string;
+  filterByTerritory = true;
+
+  constructor(private authService: AuthService) {
+    this.accessToken = this.authService.getToken();
+  }
+
+  onFilterChange() {
+    console.log('Territory filter:', this.filterByTerritory);
+  }
+}
+```
+
+### Complete Page with Search Persistence
+
+The component automatically saves search filters and sorting to URL query parameters, allowing users to bookmark or share specific searches.
+
+```typescript
+export class InstrumentsComponent {
+  // Component automatically reads from URL on init
+  // Example URL: /instruments?customerName=ABC&serialNumber=12345&active=asc
+}
+```
+
+### Custom Routing Configuration
+
+```typescript
+const routes: Routes = [
+  {
+    path: 'instruments',
+    component: InstrumentsListComponent
+  },
+  {
+    path: 'instruments/:id',
+    component: InstrumentDetailsComponent
+  }
+];
+```
+
+---
+
+## Features
+
+### Smart Search
+- Multiple search criteria
+- Date range filtering
+- Real-time filtering
+- Search persistence in URL
+
+### Sorting
+- Sort by any column
+- Ascending/descending
+- Sort state persistence
+
+### Territory Filtering
+- Filter by user's assigned territory
+- Optional - can show all instruments
+- Useful for sales organizations
+
+### Navigation
+- Click any row to view details
+- Browser back button support
+- Shareable URLs with search state
+
+### Responsive Design
+- Card-based layout
+- Mobile-friendly
+- Responsive table
+
+---
+
+## Data Models
+
+### SapInstalledInstrumentListModel
+
+```typescript
+interface SapInstalledInstrumentListModel {
+  insID: number;                 // Instrument ID
+  itemCode: string;              // Item code
+  itemName: string;              // Item description
+  manufacturerSerialNumber: string;  // Serial number
+  internalSerialNum: string;     // Internal serial number
+  customer: string;              // Customer name
+  customerCode: string;          // Customer code
+  installDate: Date;             // Installation date
+  statusOfSerialNumber: string;  // Status
+  location: string;              // Installation location
+}
+```
+
+### InstalledInstrumentFormModel
+
+```typescript
+interface InstalledInstrumentFormModel {
+  customerName?: string;
+  serialNumber?: string;
+  itemCode?: string;
+  installationDateFrom?: Date;
+  installationDateTo?: Date;
+}
+```
+
+---
 
 ## Build
 
@@ -15,10 +481,3 @@ Run `ng build ngx-st-sap-installed-instruments` to build the project. The build
 
 After building your library with `ng build ngx-st-sap-installed-instruments`, go to the dist folder `cd dist/ngx-st-sap-installed-instruments` and run `npm publish`.
 
-## Running unit tests
-
-Run `ng test ngx-st-sap-installed-instruments` to execute the unit tests via [Karma](https://karma-runner.github.io).
-
-## Further help
-
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.