

### `formatRelativeTime` [#formatrelativetime]

Displays how long ago or how far in the future a date is, with human-friendly output like "2 hours ago" or "in 3 days".

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

formatRelativeTime(new Date()); // "just now"
formatRelativeTime(Date.now() - 2 * 60 * 60 * 1000); // "about 2 hours ago" (Unix timestamp)
formatRelativeTime(Date.now() - 3 * 24 * 60 * 60 * 1000); // "3 days ago"
formatRelativeTime(Date.now() + 3 * 24 * 60 * 60 * 1000); // "in 3 days"
formatRelativeTime(Date.now() - 2 * 60 * 60 * 1000, { addApproxPrefix: false }); // "2 hours ago"
```

| Property          | Type      | Default | Description                                     |
| ----------------- | --------- | ------- | ----------------------------------------------- |
| `addSuffix`       | `boolean` | `true`  | Add "ago" or "in" suffix                        |
| `addApproxPrefix` | `boolean` | `true`  | Add "about" prefix for approximate times        |
| `locale`          | `Locale`  | -       | date-fns locale object (from `date-fns/locale`) |

***

## Locale and time zone [#locale-and-time-zone]

`formatShortDate`, `formatLongDate`, `formatTime`, `formatDateTime`, `formatLongDateTime`, `formatDateTimeWithZone` and `formatLongDateTimeWithZone` take a locale string as their second argument, or an options object with a `locale` and an IANA `timeZone`. Without a `timeZone`, dates show in the runtime's time zone, so pass the user's chosen time zone wherever it can differ from the browser's.

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

const date = "2024-01-15T23:30:00Z";

formatShortDate(date, { timeZone: "Australia/Sydney" }); // "16 Jan 2024"
formatShortDate(date, { timeZone: "America/New_York" }); // "15 Jan 2024"
formatShortDate(date, { locale: "en-US", timeZone: "America/New_York" }); // "Jan 15, 2024"
formatShortDate(date, "en-GB"); // locale string: still supported, runtime time zone
```

| Property   | Type     | Default           | Description                                  |
| ---------- | -------- | ----------------- | -------------------------------------------- |
| `locale`   | `string` | `'en-AU'`         | BCP 47 locale code                           |
| `timeZone` | `string` | runtime time zone | IANA time zone, such as `'Australia/Sydney'` |

An unknown time zone throws a `RangeError`, as an invalid locale or currency code does elsewhere in Cubitt's formatters. Formatters are cached per locale and time zone, so formatting in a loop or a table cell doesn't build a new `Intl.DateTimeFormat` each time.

The examples below use `2024-01-15T03:30:00Z`, which is 2:30 pm in Sydney.

***

### `formatShortDate` [#formatshortdate]

Formats dates in a compact, locale-aware format suitable for tables and lists.

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

const date = "2024-01-15T03:30:00Z";

formatShortDate(date, { timeZone: "Australia/Sydney" }); // "15 Jan 2024"
formatShortDate(date, { locale: "en-US", timeZone: "Australia/Sydney" }); // "Jan 15, 2024"
formatShortDate(date, { locale: "de-DE", timeZone: "Australia/Sydney" }); // "15. Jan. 2024"
formatShortDate(new Date()); // today, in the runtime's time zone
formatShortDate(1705289400000, { timeZone: "Australia/Sydney" }); // "15 Jan 2024" (Unix timestamp)
```

| Parameter         | Type                          | Default   | Description                                                 |
| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------- |
| `date`            | `Date \| string \| number`    | -         | Date to format (Date object, ISO string, or Unix timestamp) |
| `localeOrOptions` | `string \| FormatDateOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone }`                      |

***

### `formatLongDate` [#formatlongdate]

Formats dates in a readable, spelled-out format for better readability and accessibility.

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

const date = "2024-01-15T03:30:00Z";

formatLongDate(date, { timeZone: "Australia/Sydney" }); // "15 January 2024"
formatLongDate(date, { locale: "en-US", timeZone: "Australia/Sydney" }); // "January 15, 2024"
formatLongDate(date, { locale: "es-ES", timeZone: "Australia/Sydney" }); // "15 de enero de 2024"
```

| Parameter         | Type                          | Default   | Description                                                 |
| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------- |
| `date`            | `Date \| string \| number`    | -         | Date to format (Date object, ISO string, or Unix timestamp) |
| `localeOrOptions` | `string \| FormatDateOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone }`                      |

***

### `formatTime` [#formattime]

Formats a time in the locale's convention: 12-hour with lowercase am/pm for `en-AU`.

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

const date = "2024-01-15T03:30:00Z";

formatTime(date, { timeZone: "Australia/Sydney" }); // "2:30 pm"
formatTime(date, { timeZone: "America/New_York" }); // "10:30 pm"
formatTime(date, { locale: "en-US", timeZone: "Australia/Sydney" }); // "2:30 PM"
formatTime(date, { locale: "en-GB", timeZone: "Australia/Sydney" }); // "14:30"
```

| Parameter         | Type                          | Default   | Description                                                 |
| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------- |
| `date`            | `Date \| string \| number`    | -         | Date to format (Date object, ISO string, or Unix timestamp) |
| `localeOrOptions` | `string \| FormatDateOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone }`                      |

***

### `formatDateTime` [#formatdatetime]

Combines `formatShortDate` and `formatTime`, joined with "at", for complete timestamp display.

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

const date = "2024-01-15T03:30:00Z";

formatDateTime(date, { timeZone: "Australia/Sydney" }); // "15 Jan 2024 at 2:30 pm"
formatDateTime(date, { timeZone: "America/New_York" }); // "14 Jan 2024 at 10:30 pm"
formatDateTime(date, { locale: "en-US", timeZone: "America/New_York" }); // "Jan 14, 2024 at 10:30 PM"
```

| Parameter         | Type                          | Default   | Description                                                 |
| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------- |
| `date`            | `Date \| string \| number`    | -         | Date to format (Date object, ISO string, or Unix timestamp) |
| `localeOrOptions` | `string \| FormatDateOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone }`                      |

***

### `formatLongDateTime` [#formatlongdatetime]

Combines `formatLongDate` and `formatTime`, joined with "at", for formal, fully spelled-out timestamp display.

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

const date = "2024-01-15T03:30:00Z";

formatLongDateTime(date, { timeZone: "Australia/Sydney" }); // "15 January 2024 at 2:30 pm"
formatLongDateTime(date, { locale: "en-GB", timeZone: "Australia/Sydney" }); // "15 January 2024 at 14:30"
```

| Parameter         | Type                          | Default   | Description                                                 |
| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------- |
| `date`            | `Date \| string \| number`    | -         | Date to format (Date object, ISO string, or Unix timestamp) |
| `localeOrOptions` | `string \| FormatDateOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone }`                      |

***

### `formatDateTimeWithZone` [#formatdatetimewithzone]

Displays timestamps with the time zone for applications where time zone context is important.

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

const date = "2024-01-15T03:30:00Z";

formatDateTimeWithZone(date, { timeZone: "Australia/Sydney" });
// "15 Jan 2024, 2:30 pm AEDT"
formatDateTimeWithZone(date, { timeZone: "Australia/Sydney", timeZoneName: "long" });
// "15 Jan 2024, 2:30 pm Australian Eastern Daylight Time"
formatDateTimeWithZone(date, { locale: "en-US", timeZone: "America/New_York" });
// "Jan 14, 2024, 10:30 PM EST"

// The positional form still works, in the runtime's time zone:
formatDateTimeWithZone(date, "en-AU", "long");
```

| Parameter         | Type                                      | Default   | Description                                                           |
| ----------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------- |
| `date`            | `Date \| string \| number`                | -         | Date to format (Date object, ISO string, or Unix timestamp)           |
| `localeOrOptions` | `string \| FormatDateTimeWithZoneOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone, timeZoneName }`                  |
| `timeZoneName`    | `'short' \| 'long'`                       | `'short'` | Time zone display format, when the second argument is a locale string |

`FormatDateTimeWithZoneOptions` adds `timeZoneName` (`'short' \| 'long'`, default `'short'`) to `locale` and `timeZone`. Short names depend on the locale: `en-US` shows Sydney as "GMT+11", not "AEDT".

***

### `formatLongDateTimeWithZone` [#formatlongdatetimewithzone]

Combines fully spelled-out date and time with the time zone for formal, time-zone-aware timestamp display.

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

const date = "2024-01-15T03:30:00Z";

formatLongDateTimeWithZone(date, { timeZone: "Australia/Sydney" });
// "15 January 2024 at 2:30 pm AEDT"
formatLongDateTimeWithZone(date, { timeZone: "America/New_York", timeZoneName: "long" });
// "14 January 2024 at 10:30 pm Eastern Standard Time"

// The positional form still works, in the runtime's time zone:
formatLongDateTimeWithZone(date, "en-AU", "long");
```

| Parameter         | Type                                      | Default   | Description                                                           |
| ----------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------- |
| `date`            | `Date \| string \| number`                | -         | Date to format (Date object, ISO string, or Unix timestamp)           |
| `localeOrOptions` | `string \| FormatDateTimeWithZoneOptions` | `'en-AU'` | Locale code, or `{ locale, timeZone, timeZoneName }`                  |
| `timeZoneName`    | `'short' \| 'long'`                       | `'short'` | Time zone display format, when the second argument is a locale string |
