@mappingfactory/sdk-angular/README.md

Angular SDK for Michelin's Navigation and Mapping Services.

# @mappingfactory/sdk-angular

This library provides a set of Angular services for working with the `@mappingfactory/sdk-js`.
Those services are designed to be easy to use and provide a simple interface for common tasks such as searching for locations, getting directions, displaying and interacting with a map, and displaying a roadsheet.

### Installation

You can install the library using your preferred package manager:

```bash
npm install @mappingfactory/sdk-angular
```

```bash
yarn add @mappingfactory/sdk-angular
```

### Usage

To use the MappingFactory SDK in your Angular project, you first need to initialize the SDK using the `MFCoreService`. This service provides a method for initializing the SDK with your API key and other configuration options.

```typescript
import { Component, OnInit, inject } from "@angular/core";
import { MFCoreService } from "@mappingfactory/sdk-angular";

@Component({
  // ...
})
export class AppComponent implements OnInit {
  mfCoreService: MFCoreService = inject(MFCoreService);

  constructor() {}

  ngOnInit(): void {
    // We initialize the SDK here
    this.mfCoreService.init({
      apiKey: "YOUR_API_KEY",
    });
  }
}
```

Once the SDK is initialized, you can use the other services provided by the SDK to perform various tasks related to mapping and location-based services. Here are some examples:

### Direction Service

The `MFDirectionService` provides methods for calculating directions between two points.

```typescript
import { MFDirectionService } from "@mappingfactory/sdk-angular";

@Injectable()
export class MyService {
  directionService: MFDirectionService = inject(MFDirectionService);

  constructor() {
    this.directionService.init({ geometries: "geojson" });
  }

  async exampleSearch(): Promise<void> {
    const direction = this.directionService.getInstance();

    direction.client.setCoordinates(
      { latitude: 48.8584, longitude: 2.2945 },
      { latitude: 43.2964, longitude: 5.37 }
    );
    const results = await direction.search();

    return results
  }
}
```

### MapLibre Service

The `MFMapLibreService` provides a wrapper around the MapLibre GL library.

```typescript
import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";
import { MFMapLibreService } from "@mappingfactory/sdk-angular";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  directionService: MFDirectionService = inject(MFDirectionService);
  mapLibreService: MFMapLibreService = inject(MFMapLibreService);

  @ViewChild("mapElement", { static: true }) mapElement!: ElementRef;

  constructor() {
    this.directionService.init({ geometries: "geojson" });
    this.mapLibreService.init();
  }

  ngOnInit(): void {
    const direction = this.directionService.getInstance();
    const wrapper = this.mapLibreService.getInstance();
    const maplibre = wrapper._client;

    const map = new maplibre.Map({
      container: this.mapElement.nativeElement,
      style: "https://demotiles.maplibre.org/style.json",
      center: [2.3522, 48.8566], // Paris
      zoom: 5,
    });

    // The `setMap` method saves a reference of the map and creates a new layer
    // for the route and start point.
    direction.setMap(map);
  }
}
```

### Search Service

The `MFSearchService` provides methods that can create autocompletes and use geocoding services.

```typescript
import { MFSearchService } from "@mappingfactory/sdk-angular";
import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  searchService: MFSearchService = inject(MFSearchService);

  @ViewChild("autocomplete", { static: true }) autocompleteElement!: ElementRef;

  ngOnInit(): void {
    this.searchService.init();

    const search = this.searchService.getInstance();

    const autocomplete = await search.autocomplete(
      this.autocompleteElement.nativeElement,
      {
        language: "fr",
      }
    );

    autocomplete._on("selected", (value) => {
      console.log(value);
    });
  }
}
```

### Roadsheet Service

The `MFRoadsheetService` provides methods for generating a "roadsheet" or list of directions for a given route.

```typescript
import {
  MFRoadsheetService,
  MFDirectionService,
} from "@mappingfactory/sdk-angular";
import { OnInit, Component, ElementRef, ViewChild } from "@angular/core";

@Component({
  // ...
})
export class MyComponent implements OnInit {
  directionService: MFDirectionService = inject(MFDirectionService);
  roadsheetService: MFRoadsheetService = inject(MFRoadsheetService);

  async ngOnInit(): Promise<void> {
    this.directionService.init({ geometries: "geojson" });
    this.roadsheetService.init();

    this.createRoadsheet();
  }

  async createRoadsheet(): Promise<void> {
    const direction = this.directionService.getInstance().client;
    const roadsheet = this.roadsheetService.getInstance().client;

    const departure = { latitude: 48.8584, longitude: 2.2945 }; // Paris
    const arrival = { latitude: 43.2964, longitude: 5.37 }; // Marseille

    direction.client.setCoordinates(departure, arrival);

    const results = await direction.search();
    const route = results.routes[0];
    const waypoints = route.waypoints;

    const html = await roadsheet.client.getHtml(route, waypoints);

    console.log(html);
  }
}
```

These are just a few examples of the services provided by this Angular SDK. For more information on how to use the SDK, please refer to the documentation of the [`@mappingfactory/sdk-js`](https://www.npmjs.com/package/@mappingfactory/sdk-js) package.

### Components

#### MichelinMap

The `MichelinMap` component is a part of `@mappingfactory/sdk-angular` that simplifies the process of adding and interacting with a `MapLibre` map in your Angular application. This component utilizes the `MFMapLibreService` service to manage map-related functionalities.

##### Features

- Easy integration of MapLibre maps.
- Customizable map options.
- Callback function (`onMapInit`) for further map customization after initialization.

##### Props

`options`: A set of options to configure the `MapLibre` instance (excluding the `container` property, which is handled by the component).
`onMapInit`: An optional callback that is invoked with the map instance after the map is initialized and styles are loaded. This can be useful for adding layers, sources or even with the `MFDirectionService` service to add a route to the map.

##### Example Usage

Use the `MichelinMap` component where needed.

```html
<michelin-map
  [options]="mapOptions"
  (onMapInit)="onMapInit($event)"
></michelin-map>
```

```typescript
mapOptions = {
  style: "https://demotiles.maplibre.org/style.json",
  center: [2.3522, 48.8566], // Paris
  zoom: 5,
};

public onMapInit(map: Map): void {
  console.log('Map is ready:', map);

  // In this example, 'click' is an event of type MapEventType
  // provided by the MapLibre-GL library.
  // You can customize event handlers according to your specific needs.
  map.on('click', () => {
    console.log('map click');
  });
}
```

#### MichelinAutocomplete

The `MichelinAutocomplete` component is a part of `@mappingfactory/sdk-angular` designed to provide an easy-to-use interface for implementing autocomplete functionality in your Angular applications. This component utilizes the `MFSearchService` service to manage autocomplete functionalities related to location and address search.

##### Features

- Autocomplete functionality for searching locations and addresses.
- Customizable options for search behavior and appearance.
- Callbacks for various autocomplete events like selection, opening, closing, searching, and more.

##### Props

- `options`: Custom options to configure the autocomplete behavior and appearance.
- `onSelect`: Callback fired when an item is selected from the autocomplete suggestions.
- `onDropdownOpen`: Callback fired when the dropdown opens.
- `onDropDownClose`: Callback fired when the dropdown closes.
- `onSearch`: Callback fired when a search is initiated.
- `onNoResults`: Callback fired when no results are found.
- `onError`: Callback fired when there is an error in searching.
- `onSuccess`: Callback fired when a search is successful.
- `onClear`: Callback fired when the autocomplete input is cleared.
- `onInit`: Callback fired when the autocomplete manager is initialized.

##### Example Usage

Use the `MichelinAutocomplete` component where needed.

```html
<michelin-autocomplete
  [id]="'autocompleteId'"
  (onSelect)="onSelectResult($event)"
></michelin-autocomplete>
```

```typescript
public onSelectResult(value): void {
  // do something with the selected value
}
```

You can customize it by passing different options and handling various events according to your application's needs.

<hr />

### Development Environment Setup

To run this project locally, navigate to the Project Directory and follow these steps:

#### Install Dependencies:

Use `npm` to install the project's dependencies, you'll need to install the dependencies inside the root directory, `demo` folder and the `projects/mapping-factory-sdk-angular` using the following command:

```shell
npm install
```

#### Build the Project for Development:

Now that the dependencies are installed, you can build the SDK using the following command:

```shell
npm run build
```

> Note
> This command needs to be run in the root directory of the project.

This command will output a `dist` folder in the root directory. This folder contains the compiled SDK files that are ready to be published to NPM.

#### Run the demo for Development:

You'll need to pack the `dist` folder using the following command:

```shell
npm run pack
```

This will create a `.tgz` file that can be installed using `npm` inside the `demo` folder using the following command:

```shell
npm install ../mappingfactory-sdk-angular-1.0.0.tgz
```

Now that the dependencies are installed, you can build the SDK using the following command:

```shell
npm run start
```

> Note
> This command needs to be run in the root directory of the project or the `demo` folder.

#### Apply my changes from the SDK inside the demo:

If you want to see your changes inside the demo, you'll need to build and pack the `dist` folder using the following command:

```shell
npm run pack
```

This will create a `.tgz` file that can be installed using `npm` inside the `demo` folder using the following command:

```shell
npm install ../mappingfactory-sdk-angular-1.0.0.tgz
```