@foblex/platform/README.md

An Angular library providing a set of services for supporting server-side rendering (SSR) and other features.

# Angular Platform & Browser Utility Library

This Angular library provides a set of services to assist with platform detection, server-side rendering (SSR) support, and browser utilities. The library offers services to determine browser and operating system details, manage browser-specific objects like window and localStorage, and work with DOM-related tasks such as converting units to pixels.

## Features

- **Platform Detection**: Detects browser types (e.g., Edge, Firefox, Safari) and operating systems (e.g., Windows, MacOS, iOS, Android).

- **Server-Side Rendering (SSR) Compatibility**: Provides mock implementations of window and localStorage for SSR environments.

- **Browser Services**: Utilities for interacting with window, document, and converting CSS units to pixels.

## Installation

To install the library in your Angular project, run:

```bash
npm install @foblex/platform
```

## Usage

### PlatformService

The PlatformService allows you to detect the browser, operating system, and other platform-related properties.

#### Example

```typescript
import { PlatformService } from '@foblex/platform';

@Component({
  selector: 'app-root',
  template: `<h1>Platform Detection</h1>`
})
export class AppComponent {
  constructor(private platformService: PlatformService) {
    console.log('Is Browser:', this.platformService.isBrowser);
    console.log('Operating System:', this.platformService.getOS());
  }
}
```
  
### BrowserService

The BrowserService provides easy access to browser-related objects like window, localStorage, and document. It includes a utility method to convert various CSS units to pixel values.

#### Example

```typescript
import { BrowserService } from '@foblex/platform';

@Component({
  selector: 'app-root',
  template: `<h1>Browser Utilities</h1>`
})
export class AppComponent {
  constructor(private browserService: BrowserService) {
    console.log('Document Title:', this.browserService.getTitle());
    console.log('Pixels from 50%:', this.browserService.toPixels('50%', 800, 600, '16px'));
  }

  setTitle(title: string): void {
    this.browserService.setTitle(title);
  }
}
```

### Window & LocalStorage Injection Tokens

This library provides injectable tokens (F_WINDOW and F_LOCAL_STORAGE) that abstract away window and localStorage for use in both browser and server-side environments.

#### Example

```typescript
import { Component, Inject } from '@angular/core';
import { F_WINDOW, F_LOCAL_STORAGE } from '@foblex/platform';

@Component({
  selector: 'app-root',
  template: `<h1>SSR Safe Window & LocalStorage</h1>`
})
export class AppComponent {
  constructor(
    @Inject(F_WINDOW) private windowService: WindowService,
    @Inject(F_LOCAL_STORAGE) private localStorageService: LocalStorageService
  ) {
    console.log('Window Inner Width:', this.windowService.innerWidth);
    this.localStorageService.setItem('key', 'value');
  }
}
```

## API

### PlatformService

- isBrowser: boolean - Determines if the current platform is a browser.
- EDGE: boolean - Detects Microsoft Edge browser.
- TRIDENT: boolean - Detects Internet Explorer (Trident engine).
- BLINK: boolean - Detects Blink engine (used by Chrome).
- WEBKIT: boolean - Detects WebKit engine (used by Safari).
- IOS: boolean - Detects iOS devices.
- FIREFOX: boolean - Detects Mozilla Firefox.
- ANDROID: boolean - Detects Android devices.
- SAFARI: boolean - Detects Safari browser.
- getOS(): EOperationSystem | undefined - Returns the operating system.

### BrowserService

- window: IWindowService - Provides access to window or a server-safe mock.
- localStorage: ILocalStorage - Provides access to localStorage or a server-safe mock.
- document: Document - Provides access to the document object.
- toPixels(value: string, clientWidth: number, clientHeight: number, fontSize: string): number - Converts CSS units (%, em, rem, vh, vw) to pixels.

### Window Injection Token (F_WINDOW)

Injects window object or a server-safe mock of window.

### LocalStorage Injection Token (F_LOCAL_STORAGE)

Injects localStorage object or a server-safe mock of localStorage.

## License

[MIT License](./LICENSE)