# @isa/utils/format-name

A utility library for consistently formatting person and organisation names across the ISA-Frontend application.

## Overview

This library provides a single utility function `formatName` that standardizes the display of names by combining first name, last name, and organisation name components according to a consistent business rule. The function handles optional parameters gracefully and filters out empty or undefined values to produce clean, readable name strings.

The formatting follows the convention:
- Personal names are displayed as "LastName FirstName"
- Organisation names are separated from personal names with " - "
- Any combination of components can be provided
- Empty or undefined values are automatically excluded from the output

## Installation

```ts
import { formatName } from '@isa/utils/format-name';
```

## API Reference

### Functions

#### `formatName(params): string`

Formats a name by combining first name, last name, and organisation name according to business rules.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `params` | `object` | Yes | An object containing the name components |
| `params.firstName` | `string` | No | The person's first name |
| `params.lastName` | `string` | No | The person's last name |
| `params.organisationName` | `string` | No | The organisation name |

**Returns:** `string` - The formatted name string

**Formatting Rules:**
- Names are formatted as "LastName FirstName"
- Organisation name is separated from the personal name with " - "
- Empty or undefined values are filtered out
- If all values are empty/undefined, returns an empty string

## Usage Examples

### Format a person with first and last name

```ts
const result = formatName({
  firstName: 'John',
  lastName: 'Doe'
});
// Returns: "Doe John"
```

### Format a person with organisation

```ts
const result = formatName({
  firstName: 'John',
  lastName: 'Doe',
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp - Doe John"
```

### Format organisation only

```ts
const result = formatName({
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp"
```

### Format with partial personal name

```ts
// Only last name
const result1 = formatName({
  lastName: 'Doe'
});
// Returns: "Doe"

// Only first name
const result2 = formatName({
  firstName: 'John'
});
// Returns: "John"

// Organisation with partial personal name
const result3 = formatName({
  firstName: 'John',
  organisationName: 'Acme Corp'
});
// Returns: "Acme Corp - John"
```

### Handle empty values

```ts
// Empty strings are filtered out
const result1 = formatName({
  firstName: '',
  lastName: '',
  organisationName: ''
});
// Returns: ""

// Undefined values are filtered out
const result2 = formatName({});
// Returns: ""
```

## Use Cases

This utility is commonly used in:
- Customer management interfaces (CRM)
- Order processing displays
- User profile presentations
- Report generation
- Any UI component that needs to display person or organisation names consistently

## Testing

The library includes comprehensive test coverage for all formatting scenarios. Run tests with:

```bash
nx test utils-format-name
```