@servicetitan/docs-anvil-uikit-contrib 37.0.2 → 38.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/BREAKING_CHANGES.mdx +11 -0
- package/docs/intl/API/use-intl.mdx +9 -8
- package/docs/intl/date-time.mdx +114 -0
- package/docs/intl/{dates.mdx → date.mdx} +3 -5
- package/docs/intl/index.mdx +13 -9
- package/docs/intl/{numbers.mdx → number.mdx} +2 -4
- package/docs/intl/{plurals.mdx → plural.mdx} +7 -10
- package/docs/intl/{times.mdx → time.mdx} +7 -9
- package/docs/startup-jest/startup-jest.jpg +0 -0
- package/docs/startup-jest/startup-jest.mdx +25 -0
- package/package.json +2 -2
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: BREAKING CHANGES
|
|
3
|
+
sidebar_position: 0
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
### [@servicetitan/intl](./intl/) v6.0.0
|
|
7
|
+
|
|
8
|
+
Renamed [timezone formats](./intl/time#available-formats) to clarify that the timezone is added to the formatted output:
|
|
9
|
+
|
|
10
|
+
- `shortTimeZone` -> `shortWithTimeZone`
|
|
11
|
+
- `mediumTimeZone` -> `mediumWithTimeZone`
|
|
@@ -5,7 +5,7 @@ title: useIntl
|
|
|
5
5
|
The `useIntl` hook is the primary way to access direct internationalization functions in your React components. It provides access to all formatting functions and locale information needed for internationalization.
|
|
6
6
|
|
|
7
7
|
:::note
|
|
8
|
-
If using [`react-intl` Formatted components](https://formatjs.github.io/docs/react-intl/components)--such as those described in [
|
|
8
|
+
If using [`react-intl` Formatted components](https://formatjs.github.io/docs/react-intl/components)--such as those described in [Date](../date) and [Plural](../plural) documentation--you do not need to use the `useIntl` hook directly.
|
|
9
9
|
:::
|
|
10
10
|
|
|
11
11
|
## Overview
|
|
@@ -37,19 +37,20 @@ The [`intl`](https://formatjs.github.io/docs/react-intl/api#intlshape) object re
|
|
|
37
37
|
|
|
38
38
|
### Standard Formatting Functions
|
|
39
39
|
|
|
40
|
-
- [`formatDate()`](../
|
|
40
|
+
- [`formatDate()`](../date) - Format date
|
|
41
41
|
- [`formatDisplayName()`](https://formatjs.github.io/docs/react-intl/api/#formatdisplayname) - Format display names for locales, currencies, etc.
|
|
42
|
-
- [`formatList()`](https://formatjs.github.io/docs/react-intl/api/#formatlist) - Format
|
|
43
|
-
- [`formatMessage()`](https://formatjs.github.io/docs/react-intl/api/#formatmessage) - Format
|
|
44
|
-
- [`formatNumber()`](../
|
|
42
|
+
- [`formatList()`](https://formatjs.github.io/docs/react-intl/api/#formatlist) - Format list of items
|
|
43
|
+
- [`formatMessage()`](https://formatjs.github.io/docs/react-intl/api/#formatmessage) - Format message with interpolation (note: translating messages is not yet configured within ServiceTitan)
|
|
44
|
+
- [`formatNumber()`](../number) - Format number and currency
|
|
45
45
|
- [`formatPlural()`](https://formatjs.github.io/docs/react-intl/api/#formatplural) - Handle pluralization
|
|
46
46
|
- [`formatRelativeTime()`](https://formatjs.github.io/docs/react-intl/api/#formatrelativetime) - Format relative time (e.g., "2 hours ago")
|
|
47
|
-
- [`formatTime()`](
|
|
47
|
+
- [`formatTime()`](../time) - Format time
|
|
48
48
|
|
|
49
49
|
### Custom ServiceTitan Formatters
|
|
50
50
|
|
|
51
|
-
- [`formatCurrency()`](../currency
|
|
52
|
-
- [`
|
|
51
|
+
- [`formatCurrency()`](../currency) - Format currency
|
|
52
|
+
- [`formatDateTime()`](../date-time) - Format combined date and time
|
|
53
|
+
- [`formatPluralMessage()`](../plural#formatpluralmessage) - Provide a number and messages associated with plural forms, and receive the appropriate message for the current locale and plural form
|
|
53
54
|
|
|
54
55
|
### Properties
|
|
55
56
|
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Date and Time
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
import { FormattedDateTimeMiniDemo } from '@servicetitan/intl/demo';
|
|
6
|
+
import { DemoExample } from '@site/src/components/code-demo';
|
|
7
|
+
import Tabs from '@theme/Tabs';
|
|
8
|
+
import TabItem from '@theme/TabItem';
|
|
9
|
+
|
|
10
|
+
Use `FormattedDateTime` and `formatDateTime` to format a date value as a combined date and time.
|
|
11
|
+
|
|
12
|
+
## Available Formats
|
|
13
|
+
|
|
14
|
+
The following standard ServiceTitan formats are available (examples are in `en-US` locale).
|
|
15
|
+
|
|
16
|
+
| Format | Description | Example |
|
|
17
|
+
| :------------------ | :--------------------------------------- | :------------------------------- |
|
|
18
|
+
| `short` | Short date and short time | `01/09/2025, 4:00 PM` |
|
|
19
|
+
| `shortWithTimeZone` | Short date and short time, with timezone | `01/09/2025, 4:00 PM EST` |
|
|
20
|
+
| `long` | Long date and short time | `January 9, 2025 at 4:00 PM` |
|
|
21
|
+
| `longWithTimeZone` | Long date and short time, with timezone | `January 9, 2025 at 4:00 PM EST` |
|
|
22
|
+
|
|
23
|
+
## Usage
|
|
24
|
+
|
|
25
|
+
### FormattedDateTime
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { FormattedDateTime } from '@servicetitan/intl';
|
|
29
|
+
|
|
30
|
+
function DateTimeExample() {
|
|
31
|
+
const date = new Date('2025-01-09T16:00:00-05:00');
|
|
32
|
+
|
|
33
|
+
return (
|
|
34
|
+
<>
|
|
35
|
+
<FormattedDateTime value={date} /> {/* 01/09/2025, 4:00 PM */}
|
|
36
|
+
<FormattedDateTime value={date} format="short" /> {/* 01/09/2025, 4:00 PM */}
|
|
37
|
+
<FormattedDateTime value={date} format="shortWithTimeZone" /> {/* 01/09/2025, 4:00 PM EST */}
|
|
38
|
+
<FormattedDateTime value={date} format="long" /> {/* January 9, 2025 at 4:00 PM */}
|
|
39
|
+
<FormattedDateTime value={date} format="longWithTimeZone" /> {/* January 9, 2025 at 4:00 PM EST */}
|
|
40
|
+
</>
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### formatDateTime
|
|
46
|
+
|
|
47
|
+
<Tabs
|
|
48
|
+
defaultValue="hook"
|
|
49
|
+
values={[
|
|
50
|
+
{ label: 'React Hook', value: 'hook' },
|
|
51
|
+
{ label: 'MobX Store', value: 'store'}
|
|
52
|
+
]}
|
|
53
|
+
>
|
|
54
|
+
<TabItem value="hook">
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
import { useIntl } from '@servicetitan/intl';
|
|
58
|
+
|
|
59
|
+
function DateTimeExample() {
|
|
60
|
+
const { formatDateTime } = useIntl();
|
|
61
|
+
const date = new Date('2025-01-09T16:00:00-05:00');
|
|
62
|
+
|
|
63
|
+
return (
|
|
64
|
+
<>
|
|
65
|
+
{formatDateTime(date)} {/* 01/09/2025, 4:00 PM */}
|
|
66
|
+
{formatDateTime(date, { format: 'short' })} {/* 01/09/2025, 4:00 PM */}
|
|
67
|
+
{formatDateTime(date, { format: 'shortWithTimeZone' })} {/* 01/09/2025, 4:00 PM EST */}
|
|
68
|
+
{formatDateTime(date, { format: 'long' })} {/* January 9, 2025 at 4:00 PM */}
|
|
69
|
+
{formatDateTime(date, { format: 'longWithTimeZone' })} {/* January 9, 2025 at 4:00 PM EST */}
|
|
70
|
+
</>
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
</TabItem>
|
|
76
|
+
<TabItem value="store">
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
import { inject, injectable } from '@servicetitan/react-ioc';
|
|
80
|
+
import { IntlStore } from '@servicetitan/intl/mobx';
|
|
81
|
+
|
|
82
|
+
@injectable()
|
|
83
|
+
class MyStore {
|
|
84
|
+
constructor(@inject(IntlStore) private readonly intlStore: IntlStore) {}
|
|
85
|
+
|
|
86
|
+
formatDateTime() {
|
|
87
|
+
const date = new Date('2025-01-09T16:00:00-05:00');
|
|
88
|
+
const { formatDateTime } = this.intlStore.intl;
|
|
89
|
+
return [
|
|
90
|
+
formatDateTime(date), // 01/09/2025, 4:00 PM
|
|
91
|
+
formatDateTime(date, { format: 'short' }), // 01/09/2025, 4:00 PM
|
|
92
|
+
formatDateTime(date, { format: 'shortWithTimeZone' }), // 01/09/2025, 4:00 PM EST
|
|
93
|
+
formatDateTime(date, { format: 'long' }), // January 9, 2025 at 4:00 PM
|
|
94
|
+
formatDateTime(date, { format: 'longWithTimeZone' }), // January 9, 2025 at 4:00 PM EST
|
|
95
|
+
];
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
</TabItem>
|
|
101
|
+
</Tabs>
|
|
102
|
+
|
|
103
|
+
### Further customization
|
|
104
|
+
|
|
105
|
+
To customize the formatting, pass `FormattedDateTime` and `formatDateTime` the same [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options) as the native `Intl.DateTimeFormat` API. For example,
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
const date = new Date('2025-01-09T16:00:00-05:00');
|
|
109
|
+
formatDateTime(date, { format: 'long', weekday: 'short' }); // Thu, January 9, 2025 at 4:00 PM
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Demo
|
|
113
|
+
|
|
114
|
+
<DemoExample example={FormattedDateTimeMiniDemo} />
|
|
@@ -1,17 +1,15 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: Date
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
import {
|
|
6
|
-
FormattedDateMiniDemo
|
|
7
|
-
} from '@servicetitan/intl/demo';
|
|
5
|
+
import { FormattedDateMiniDemo } from '@servicetitan/intl/demo';
|
|
8
6
|
import { DemoExample } from '@site/src/components/code-demo';
|
|
9
7
|
import Tabs from '@theme/Tabs';
|
|
10
8
|
|
|
11
9
|
Dates can be formatted either by using the [`FormattedDate`](#formatteddate) component from `@servicetitan/intl`, or via the [`formatDate`](#formatdate) function as part of the `intl` object, which can be retrieved via the [`useIntl`](./API/use-intl.mdx) hook or through the [`IntlStore`](./API/intlstore.mdx) store.
|
|
12
10
|
|
|
13
11
|
:::note
|
|
14
|
-
`FormattedDate` is a wrapper around `react-intl`'s `FormattedDate` component, but defaults the `format` to
|
|
12
|
+
`FormattedDate` is a wrapper around `react-intl`'s `FormattedDate` component, but defaults the `format` to _short_. Make sure you import it from `@servicetitan/intl`, not `react-intl`.
|
|
15
13
|
:::
|
|
16
14
|
|
|
17
15
|
## Available Formats
|
package/docs/intl/index.mdx
CHANGED
|
@@ -2,10 +2,12 @@
|
|
|
2
2
|
title: Intl (Internationalization)
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
+
#### [CHANGELOG (@servicetitan/intl)](https://github.com/servicetitan/anvil-uikit-contrib/blob/master/packages/intl/CHANGELOG.md)
|
|
6
|
+
|
|
5
7
|
import Tabs from '@theme/Tabs';
|
|
6
8
|
import TabItem from '@theme/TabItem';
|
|
7
9
|
|
|
8
|
-
`@servicetitan/intl` is a solution for helping setup internationalization in React projects (with optional MobX store) that is a light wrapper around [`Format.js`](https://formatjs.github.io/) and [`react-intl`](https://formatjs.github.io/docs/react-intl/). This library creates an internationalization API with a provided
|
|
10
|
+
`@servicetitan/intl` is a solution for helping setup internationalization in React projects (with optional MobX store) that is a light wrapper around [`Format.js`](https://formatjs.github.io/) and [`react-intl`](https://formatjs.github.io/docs/react-intl/). This library creates an internationalization API with a provided _locale_, _timeZone_, and _currency_, and provides that API to `react-intl` to be used within React context, as well as a store to be used within MobX.
|
|
9
11
|
|
|
10
12
|
## Setup
|
|
11
13
|
|
|
@@ -16,8 +18,9 @@ npm install @servicetitan/intl
|
|
|
16
18
|
```
|
|
17
19
|
|
|
18
20
|
This library has `peerDependencies` for:
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
+
|
|
22
|
+
- `"@servicetitan/react-ioc": ">=22.0.0"`
|
|
23
|
+
- `"react-intl": ">=7.1.11"`
|
|
21
24
|
|
|
22
25
|
### Provider
|
|
23
26
|
|
|
@@ -73,11 +76,12 @@ If you are instead implementing an MFE but would use the same monolith data, you
|
|
|
73
76
|
|
|
74
77
|
`Format.js` and `react-intl` provide many components and utilities for handling internationalization, including caching and wrapping most of the [native `Intl` formatters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). The following APIs are particularly useful to us at this stage:
|
|
75
78
|
|
|
76
|
-
- [
|
|
77
|
-
- [
|
|
78
|
-
- [
|
|
79
|
-
- [
|
|
80
|
-
- [
|
|
79
|
+
- [Currency](./currency)
|
|
80
|
+
- [Date](./date)
|
|
81
|
+
- [Date and time](./date-time)
|
|
82
|
+
- [Number](./number)
|
|
83
|
+
- [Time](./time)
|
|
84
|
+
- [Plural](./plural)
|
|
81
85
|
|
|
82
86
|
:::note
|
|
83
87
|
Translating messages is not yet supported, as we currently have no need for it. But using `@servicetitan/intl` ensures the framework is in place for when we do begin translating messages.
|
|
@@ -117,7 +121,7 @@ export class UserService {
|
|
|
117
121
|
|
|
118
122
|
return {
|
|
119
123
|
joinDate: intl.formatDate(user.joinDate),
|
|
120
|
-
balance: intl.formatCurrency(user.balance)
|
|
124
|
+
balance: intl.formatCurrency(user.balance),
|
|
121
125
|
};
|
|
122
126
|
}
|
|
123
127
|
}
|
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: Number
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
import {
|
|
6
|
-
FormattedNumberMiniDemo
|
|
7
|
-
} from '@servicetitan/intl/demo';
|
|
5
|
+
import { FormattedNumberMiniDemo } from '@servicetitan/intl/demo';
|
|
8
6
|
import { DemoExample } from '@site/src/components/code-demo';
|
|
9
7
|
import Tabs from '@theme/Tabs';
|
|
10
8
|
|
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: Plural
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
import {
|
|
6
|
-
FormattedPluralMiniDemo
|
|
7
|
-
} from '@servicetitan/intl/demo';
|
|
5
|
+
import { FormattedPluralMiniDemo } from '@servicetitan/intl/demo';
|
|
8
6
|
import { DemoExample } from '@site/src/components/code-demo';
|
|
9
7
|
import Tabs from '@theme/Tabs';
|
|
10
8
|
|
|
@@ -32,11 +30,11 @@ import { FormattedPlural } from '@servicetitan/intl';
|
|
|
32
30
|
|
|
33
31
|
`formatPluralMessage` is a custom formatter which accepts a number value, an object of messages keyed by plural forms, and [`Intl.PluralRules` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options). It returns the message corresponding to the plural form of the value for the current locale.
|
|
34
32
|
|
|
35
|
-
| Name | Type | Description
|
|
36
|
-
| :--------- | :-------------------- |
|
|
37
|
-
| `value` | `number` | The number value to determine the plural form.
|
|
38
|
-
| `messages` | `PluralMessages` | An object containing messages keyed by plural forms.
|
|
39
|
-
| `options?`
|
|
33
|
+
| Name | Type | Description |
|
|
34
|
+
| :--------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
35
|
+
| `value` | `number` | The number value to determine the plural form. |
|
|
36
|
+
| `messages` | `PluralMessages` | An object containing messages keyed by plural forms. |
|
|
37
|
+
| `options?` | `FormatPluralOptions` | [Options to customize the pluralization behavior](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options). Defaults to using "cardinal". |
|
|
40
38
|
|
|
41
39
|
<Tabs
|
|
42
40
|
defaultValue="hooks"
|
|
@@ -78,7 +76,6 @@ class MyStore {
|
|
|
78
76
|
</TabItem>
|
|
79
77
|
</Tabs>
|
|
80
78
|
|
|
81
|
-
|
|
82
79
|
### Demo
|
|
83
80
|
|
|
84
81
|
<DemoExample example={FormattedPluralMiniDemo} />
|
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: Time
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
import {
|
|
6
|
-
FormattedTimeMiniDemo
|
|
7
|
-
} from '@servicetitan/intl/demo';
|
|
5
|
+
import { FormattedTimeMiniDemo } from '@servicetitan/intl/demo';
|
|
8
6
|
import { DemoExample } from '@site/src/components/code-demo';
|
|
9
7
|
import Tabs from '@theme/Tabs';
|
|
10
8
|
|
|
@@ -19,10 +17,10 @@ The example results that follow use a locale of 'en-US' and time zone of 'Americ
|
|
|
19
17
|
:::
|
|
20
18
|
|
|
21
19
|
- `short` results in `4:00 PM` (default)
|
|
22
|
-
- `
|
|
23
|
-
- `utc` results in `08:00 PM UTC` (forces UTC timezone and adds leading zero)
|
|
20
|
+
- `shortWithTimeZone` results in `4:00 PM EDT`
|
|
24
21
|
- `medium` results in `4:00:00 PM`
|
|
25
|
-
- `
|
|
22
|
+
- `mediumWithTimeZone` results in `4:00:00 PM EDT`
|
|
23
|
+
- `utc` results in `08:00 PM UTC` (forces UTC timezone and adds leading zero)
|
|
26
24
|
|
|
27
25
|
## Usage
|
|
28
26
|
|
|
@@ -38,10 +36,10 @@ function TimeExample() {
|
|
|
38
36
|
<>
|
|
39
37
|
<FormattedTime value={time} /> {/* "4:00 PM" */}
|
|
40
38
|
<FormattedTime value={time} format="short" /> {/* "4:00 PM" */}
|
|
41
|
-
<FormattedTime value={time} format="
|
|
39
|
+
<FormattedTime value={time} format="shortWithTimeZone" /> {/* "4:00 PM EDT" */}
|
|
42
40
|
<FormattedTime value={time} format="utc" /> {/* "08:00 PM" UTC*/}
|
|
43
41
|
<FormattedTime value={time} format="medium" /> {/* "4:00:00 PM" */}
|
|
44
|
-
<FormattedTime value={time} format="
|
|
42
|
+
<FormattedTime value={time} format="mediumWithTimeZone" /> {/* "4:00:00 PM EDT" */}
|
|
45
43
|
</>
|
|
46
44
|
);
|
|
47
45
|
}
|
|
Binary file
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Startup Jest
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
import ExampleSetup from './startup-jest.jpg';
|
|
6
|
+
|
|
7
|
+
`@servicetitan/startup-jest` is a small package that allows WebStorm/Riders's Run/Debug Configurations to work with startup's [test](/docs/frontend/uikit/startup/test) command.
|
|
8
|
+
|
|
9
|
+
Use this package if your repository uses `startup test` and you want to run tests in WebStorm/Rider. It causes the IDE to run tests with the same configuration as when you run `startup test` manually.
|
|
10
|
+
|
|
11
|
+
## Setup
|
|
12
|
+
|
|
13
|
+
Add `@servicetitan/startup-jest` to your project's `devDependencies`. E.g.,
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm add --save-dev @servicetitan/startup-jest
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Set the **Jest package** in WebStorm/Rider's Run/Debug Configuration to the path to `@servicetitan/startup-jest` in your project's `node_modules`. For example,
|
|
20
|
+
|
|
21
|
+
<img src={ExampleSetup} />
|
|
22
|
+
|
|
23
|
+
## See Also
|
|
24
|
+
|
|
25
|
+
- [startup test](/docs/frontend/uikit/startup/test) -- how to configure and run tests
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@servicetitan/docs-anvil-uikit-contrib",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "38.0.0",
|
|
4
4
|
"description": "",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -16,5 +16,5 @@
|
|
|
16
16
|
"cli": {
|
|
17
17
|
"webpack": false
|
|
18
18
|
},
|
|
19
|
-
"gitHead": "
|
|
19
|
+
"gitHead": "774667ac1539f03863a89549b3cd938f78d2d03e"
|
|
20
20
|
}
|