### `truncate` [#truncate]

Shortens text to a specified length with customizable suffix and word boundary handling.

```tsx
import { truncate } from "@tilt-legal/cubitt-components/utilities/formatters";

truncate('This is a long text', 10); // "This is..."
truncate('Long text', 10, { suffix: '…' }); // "Long text…"
truncate('Hello world from Cubitt', 15, { wordBoundary: true }); // "Hello world..."
```

| Property       | Type      | Default | Description                     |
| -------------- | --------- | ------- | ------------------------------- |
| `suffix`       | `string`  | `'...'` | String to append when truncated |
| `wordBoundary` | `boolean` | `false` | Truncate at word boundaries     |

***

### `truncateMiddle` [#truncatemiddle]

Truncates text in the middle, preserving the start and end. Useful for filenames where the extension is important, similar to macOS Finder behavior.

```tsx
import { truncateMiddle } from "@tilt-legal/cubitt-components/utilities/formatters";

truncateMiddle('Short.txt', 20); // "Short.txt"
truncateMiddle('VeryLongFilename.pdf', 15); // "VeryLo…me.pdf"
truncateMiddle('Document_Final_v2.docx', 18); // "Documen…v2.docx"
truncateMiddle('Quarterly_Report_2024_Final.xlsx', 20); // "Quarter…inal.xlsx"
```

| Property   | Type     | Default | Description                   |
| ---------- | -------- | ------- | ----------------------------- |
| `ellipsis` | `string` | `'…'`   | Character to use for ellipsis |

***

### `formatPlural` [#formatplural]

Intelligently handles singular and plural forms with custom plural rules and count display.

```tsx
import { formatPlural } from "@tilt-legal/cubitt-components/utilities/formatters";

formatPlural(1, 'file'); // "1 file"
formatPlural(5, 'file'); // "5 files"
formatPlural(2, 'child', { plural: 'children' }); // "2 children"
formatPlural(0, 'item', { zero: 'no items' }); // "no items"
formatPlural(3, 'person', { includeCount: false }); // "people"
```

| Property       | Type      | Default | Description                 |
| -------------- | --------- | ------- | --------------------------- |
| `plural`       | `string`  | -       | Custom plural form          |
| `includeCount` | `boolean` | `true`  | Include count in output     |
| `zero`         | `string`  | -       | Special form for count of 0 |

***

### `formatList` [#formatlist]

Formats arrays into grammatically correct lists with locale-aware conjunction or disjunction.

```tsx
import { formatList } from "@tilt-legal/cubitt-components/utilities/formatters";

formatList(['apple', 'banana', 'cherry']); // "apple, banana, and cherry"
formatList(['red', 'green'], { type: 'disjunction' }); // "red or green"
formatList(['one', 'two', 'three'], { locale: 'en-US' }); // "one, two, and three"
```

| Property | Type                             | Default         | Description           |
| -------- | -------------------------------- | --------------- | --------------------- |
| `locale` | `string`                         | `'en-AU'`       | Locale for formatting |
| `type`   | `'conjunction' \| 'disjunction'` | `'conjunction'` | List type (and/or)    |

***

### `formatInitials` [#formatinitials]

Extracts initials from a full name, using first and last name only.

```tsx
import { formatInitials } from "@tilt-legal/cubitt-components/utilities/formatters";

formatInitials('John Doe'); // "JD"
formatInitials('Mary Jane Smith'); // "MS"
formatInitials('Alice'); // "A"
formatInitials(''); // ""
```

***

### `highlightText` [#highlighttext]

Wraps matching text in HTML tags for search highlighting with customizable styling.

```tsx
import { highlightText } from "@tilt-legal/cubitt-components/utilities/formatters";

highlightText('Hello World', 'world'); // "Hello <mark>World</mark>"
highlightText('Search result', 'result', {
  tag: 'span',
  className: 'bg-yellow-200'
}); // "Search <span class=\"bg-yellow-200\">result</span>"
```

| Property        | Type      | Default  | Description                 |
| --------------- | --------- | -------- | --------------------------- |
| `caseSensitive` | `boolean` | `false`  | Case-sensitive matching     |
| `tag`           | `string`  | `'mark'` | HTML tag for highlighting   |
| `className`     | `string`  | -        | CSS class for highlight tag |

***

### `capitalize` [#capitalize]

Capitalizes the first letter of a string and converts the rest to lowercase.

```tsx
import { capitalize } from "@tilt-legal/cubitt-components/utilities/formatters";

capitalize('hello world'); // "Hello world"
capitalize('HELLO WORLD'); // "Hello world"
capitalize(''); // ""
```

***

### `toTitleCase` [#totitlecase]

Converts a string to title case by capitalizing the first letter of each word.

```tsx
import { toTitleCase } from "@tilt-legal/cubitt-components/utilities/formatters";

toTitleCase('hello world'); // "Hello World"
toTitleCase('the quick brown fox'); // "The Quick Brown Fox"
toTitleCase('HELLO WORLD'); // "Hello World"
```

***

### `toFieldLabel` [#tofieldlabel]

Converts field paths to human-readable labels, extracting the last segment and handling camelCase, snake\_case, and kebab-case.

```tsx
import { toFieldLabel } from "@tilt-legal/cubitt-components/utilities/formatters";

toFieldLabel('firstName'); // "First name"
toFieldLabel('user_email'); // "User email"
toFieldLabel('kebab-case'); // "Kebab case"
toFieldLabel('camelCaseField'); // "Camel case field"
toFieldLabel('client.name'); // "Name"
toFieldLabel('addresses[0].street'); // "Street"
```