@servicetitan/docs-anvil-uikit-contrib 32.4.1 → 32.5.0

package/docs/intl/API/intl-provider.mdx

@@ -0,0 +1,22 @@
+---
+title: IntlProvider
+---
+
+Applications must be wrapped with the `<IntlProvider>` component in order to access internationalization features throughout the application.
+
+`locale` and `timeZone` may be passed to the provider via the `config` prop. `locale` defaults to `en-US` and `timeZone` defaults to the user's local time zone if not provided.
+
+The config object must be wrapped with `useMemo` to avoid unnecessary re-renders.
+
+```tsx
+import { IntlConfig, IntlProvider } from '@servicetitan/intl';
+
+const locale = 'en-US';
+const timeZone = 'America/Los_Angeles';
+const intlConfig: IntlConfig = useMemo(() => ({ locale, timeZone }), [locale, timeZone]);
+return (
+    <IntlProvider config={intlConfig}>
+        <App />
+    </IntlProvider>
+);
+```

package/docs/intl/API/intl-store-provider.mdx

@@ -0,0 +1,23 @@
+---
+title: IntlStoreProvider
+---
+
+Applications may be wrapped with the `<IntlStoreProvider>` component in order to provide access to internationalization features in MobX stores.
+
+`<IntlStoreProvider>` must be a child of `<IntlProvider>`, and should be placed as high in the component tree as possible to ensure all stores have access to the `IntlStore`.
+
+```tsx
+import { IntlProvider } from '@servicetitan/intl';
+import { IntlStoreProvider } from '@servicetitan/intl/mobx';
+
+const locale = 'en-US';
+const timeZone = 'America/Los_Angeles';
+const intlConfig: IntlConfig = useMemo(() => ({ locale, timeZone }), [locale, timeZone]);
+return (
+    <IntlProvider config={intlConfig}>
+        <IntlStoreProvider>
+            <App />
+        </IntlStoreProvider>
+    </IntlProvider>
+);
+```

package/docs/intl/API/intlstore.mdx

@@ -0,0 +1,38 @@
+---
+title: IntlStore
+---
+
+The `IntlStore` is a dependency injected store that provides access to internationalization functionality in MobX stores in situations where formatting within React components is not possible.
+
+:::note
+It is preferred to use the [`useIntl` hook](./use-intl.mdx) instead of directly accessing the `IntlStore`, as it is preferred to do formatting in the "view" layer of your application vs the "data" layer.
+:::
+
+## Overview
+
+The `IntlStore` is an injectable store that maintains an [`intl`](https://formatjs.github.io/docs/react-intl/api#intlshape) object with the same formatting functions and locale information available through the [`useIntl`](./use-intl.mdx) hook. It extends the standard `react-intl` functionality with custom ServiceTitan formatters. The `IntlStore` is provided by a combination of [`IntlProvider`](./intl-provider.mdx) and [`IntlStoreProvider`](./intl-store-provider.mdx), and is updated when `IntlProvider`'s props change.
+
+## Basic Usage
+
+```tsx
+import { inject, injectable } from '@servicetitan/react-ioc';
+import { IntlStore } from '@servicetitan/intl/mobx';
+
+@injectable()
+export class UserService {
+    constructor(@inject(IntlStore) private intlStore: IntlStore) {}
+
+    formatUserData(user: User) {
+        const intl = this.intlStore.intl;
+
+        return {
+            joinDate: intl.formatDate(user.joinDate, { format: 'long' }),
+            balance: intl.formatNumber(user.balance, { style: 'currency', currency: 'USD' })
+        };
+    }
+}
+```
+
+## Available Functions
+
+See [`useIntl`](./use-intl.mdx#available-functions) for a list of functions and properties available in the `intl` object.

package/docs/intl/API/use-intl.mdx

@@ -0,0 +1,64 @@
+---
+title: useIntl
+---
+
+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.
+
+:::note
+If using [`react-intl` Formatted components](https://formatjs.github.io/docs/react-intl/components)--such as those described in [Dates and Time](../dates.mdx), [Numbers and Currency](../numbers.mdx), and [Plurals](../plurals.mdx) documentation--you do not need to use the `useIntl` hook directly.
+:::
+
+## Overview
+
+The `useIntl` hook extends the standard [`react-intl` `useIntl`](https://formatjs.github.io/docs/react-intl/api/#useintl-hook) hook with additional custom formatters specific to ServiceTitan applications. It returns an `intl` object that contains all the formatting functions and locale information.
+
+## Basic Usage
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+
+function MyComponent() {
+    const intl = useIntl();
+
+    return (
+        <div>
+            <p>Current locale: {intl.locale}</p>
+            <p>Current timezone: {intl.timeZone}</p>
+            <p>Formatted date: {intl.formatDate(new Date(), { format: 'short' })}</p>
+            <p>Formatted currency: {intl.formatNumber(1234.56, { style: 'currency', currency: 'USD' })}</p>
+        </div>
+    );
+}
+```
+
+## Available Functions
+
+The [`intl`](https://formatjs.github.io/docs/react-intl/api#intlshape) object returned by `useIntl` provides access to [all standard `Format.js` formatting functions](https://formatjs.github.io/docs/react-intl/api#intlshape), plus custom ServiceTitan formatters:
+
+### Standard Formatting Functions
+
+- [`formatDate()`](../dates.mdx) - Format dates and times
+- [`formatDisplayName()`](https://formatjs.github.io/docs/react-intl/api/#formatdisplayname) - Format display names for locales, currencies, etc.
+- [`formatList()`](https://formatjs.github.io/docs/react-intl/api/#formatlist) - Format lists of items
+- [`formatMessage()`](https://formatjs.github.io/docs/react-intl/api/#formatmessage) - Format messages with interpolation (note: translating messages is not yet configured within ServiceTitan)
+- [`formatNumber()`](../numbers.mdx) - Format numbers and currency
+- [`formatPlural()`](https://formatjs.github.io/docs/react-intl/api/#formatplural) - Handle pluralization
+- [`formatRelativeTime()`](https://formatjs.github.io/docs/react-intl/api/#formatrelativetime) - Format relative time (e.g., "2 hours ago")
+- [`formatTime()`](https://formatjs.github.io/docs/react-intl/api/#formattime) - Format time values
+
+### Custom ServiceTitan Formatters
+
+- [`formatPluralMessage()`](../plurals.mdx#formatpluralmessage) - Provide a number and messages associated with plural forms, and receive the appropriate message for the current locale and plural form
+
+### Locale Information
+
+- `locale` - Current locale (e.g., 'en-US')
+- `timeZone` - Current time zone
+- `messages` - Available messages for the current locale (note: translating messages is not yet configured within ServiceTitan)
+
+## See Also
+
+For detailed information about specific formatting functions and their options, refer to the Format.js documentation:
+
+- [useIntl Hook Documentation](https://formatjs.github.io/docs/react-intl/api/#useintl-hook) which our `useIntl` is a wrapper around
+- [Format.JS Imperative API](https://formatjs.github.io/docs/react-intl/api/) contains all of the formatting functions available on the `intl` object

package/docs/intl/dates.mdx

@@ -0,0 +1,88 @@
+---
+title: Dates and Times
+---
+
+import Tabs from '@theme/Tabs';
+
+Dates and times can be formatted either by using the [`FormattedDate`](#formatteddate) component from `react-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.
+
+## Available Formats
+
+The following standard ServiceTitan formats are available to use as part of date/time formatting. The formats follow the "Dates and time" section of the ["Style Guide - General guidelines"](https://servicetitan.atlassian.net/wiki/spaces/DTW/pages/262701057/Style+Guide+-+General+guidelines#Dates-and-time).
+
+- `short` results in `09/02/25`
+- `long` results in `September 2, 2025`
+- `timeShort` results in `4:00 PM`
+- `timeMedium` results in `4:00:00 PM`
+
+## Usage
+
+### FormattedDate
+
+```tsx
+import { FormattedDate } from 'react-intl';
+...
+<FormattedDate value={new Date()} format="short" />
+// Results in 09/02/25
+<FormattedDate value={new Date()} format="long" />
+// Results in September 2, 2025
+<FormattedDate value={new Date()} format="timeShort" />
+// Results in 4:00 PM
+<FormattedDate value={new Date()} format="timeMedium" />
+// Results in 4:00:00 PM
+```
+
+### formatDate
+
+<Tabs
+    defaultValue="hooks"
+    values={[
+        { label: 'React hooks', value: 'hooks' },
+        { label: 'Store', value: 'store' },
+    ]}
+>
+<TabItem value="hooks">
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+...
+const intl = useIntl();
+...
+intl.formatDate(new Date(), { format: 'short' });
+// Results in 09/02/25
+intl.formatDate(new Date(), { format: 'long' });
+// Results in September 2, 2025
+intl.formatDate(new Date(), { format: 'timeShort' });
+// Results in 4:00 PM
+intl.formatDate(new Date(), { format: 'timeMedium' });
+// Results in 4:00:00 PM
+```
+
+</TabItem>
+<TabItem value="store">
+
+```tsx
+import { IntlStore } from '@servicetitan/intl/mobx';
+...
+@injectable()
+class MyStore {
+    constructor(@inject(IntlStore) private readonly intlStore: IntlStore) {}
+    ...
+    this.intlStore.intl.formatDate(new Date(), { format: 'short' });
+    // Results in 09/02/25
+    this.intlStore.intl.formatDate(new Date(), { format: 'long' });
+    // Results in September 2, 2025
+    this.intlStore.intl.formatDate(new Date(), { format: 'timeShort' });
+    // Results in 4:00 PM
+    this.intlStore.intl.formatDate(new Date(), { format: 'timeMedium' });
+    // Results in 4:00:00 PM
+    ...
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Further customization
+
+If you need to customize the formatting further, `FormattedDate` and `formatDate` accept the same options as the native `Intl.DateTimeFormat` API. See [`Intl.DateTimeFormat` for more information about those options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), and see Format.js [`FormattedDate` documentation](https://formatjs.github.io/docs/react-intl/components/#formatteddate) or [`formatDate` documentation](https://formatjs.github.io/docs/react-intl/api/#formatdate) for more information on how to use them.

package/docs/intl/index.mdx

@@ -0,0 +1,86 @@
+---
+title: Intl (Internationalization)
+---
+
+`@servicetitan/intl` is a solution for helping setup internationalization in React and MobX projects 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* and *timeZone*, and provides that API to `react-intl` to be used within React context, as well as a store to be used within MobX.
+
+## Setup
+
+This project should be installed as one of your project's `dependencies`:
+
+```bash
+npm install @servicetitan/intl
+```
+
+This library has `peerDependencies` for:
+-   `"@servicetitan/react-ioc": ">=22.0.0"`
+-   `"react-intl": ">=7.1.11"`
+
+### IntlProvider
+
+Wrap your application in the `<IntlProvider>` component, providing `locale` and `timeZone` through the `config` prop:
+
+```tsx
+import { IntlProvider } from '@servicetitan/intl';
+
+const locale = 'en-US';
+const timeZone = 'America/Los_Angeles';
+const intlConfig: IntlConfig = useMemo(() => ({ locale, timeZone }), [locale, timeZone]);
+return (
+    <IntlProvider config={intlConfig}>
+        <App />
+    </IntlProvider>
+);
+```
+
+## Features
+
+`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 are particularly useful to us at this stage:
+
+- [Formatting dates and time](./dates.mdx)
+- [Formatting numbers and currency](./numbers.mdx)
+- [Plurals](./plurals.mdx)
+
+:::note
+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.
+:::
+
+## React Hooks vs Store
+
+We recommend using the hooks API to access the internationalization API for most cases, as it is preferred to do formatting in the "view" layer of your application vs the "data" layer.
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+
+function MyComponent() {
+    const intl = useIntl();
+
+    return (
+        <div>
+            <p>Formatted date: {intl.formatDate(new Date(), { format: 'short' })}</p>
+            <p>Formatted currency: {intl.formatNumber(1234.56, { style: 'currency', currency: 'USD' })}</p>
+        </div>
+    );
+}
+```
+
+However, if you have the need to access the internationalization API in MobX stores, you must use an additional wrapper component, [`<IntlStoreProvider>`](./API/intl-store-provider.mdx), and you can use the provided `IntlStore` to access the same functionality.
+
+```tsx
+import { inject, injectable } from '@servicetitan/react-ioc';
+import { IntlStore } from '@servicetitan/intl/mobx';
+
+@injectable()
+export class UserService {
+    constructor(@inject(IntlStore) private intlStore: IntlStore) {}
+
+    formatUserData(user: User) {
+        const intl = this.intlStore.intl;
+
+        return {
+            joinDate: intl.formatDate(user.joinDate, { format: 'long' }),
+            balance: intl.formatNumber(user.balance, { style: 'currency', currency: 'USD' })
+        };
+    }
+}
+```

package/docs/intl/numbers.mdx

@@ -0,0 +1,64 @@
+---
+title: Numbers and Currency
+---
+
+import Tabs from '@theme/Tabs';
+
+Numbers and currency can be formatted either by using the `FormattedNumber` component from `react-intl`, or via the `formatNumber()` 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.
+
+## Usage
+
+### FormattedNumber
+
+```tsx
+import { FormattedNumber } from 'react-intl';
+...
+<FormattedNumber value={1234.56} style="currency" currency="USD" />
+<FormattedNumber value={0.75} style="percent" />
+<FormattedNumber value={1234.567} maximumFractionDigits={2} />
+```
+
+### formatNumber
+
+<Tabs
+    defaultValue="hooks"
+    values={[
+        { label: 'React hooks', value: 'hooks' },
+        { label: 'Store', value: 'store' },
+    ]}
+>
+<TabItem value="hooks">
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+...
+const intl = useIntl();
+...
+intl.formatNumber(1234.56, { style: 'currency', currency: 'USD' });
+intl.formatNumber(0.75, { style: 'percent' });
+intl.formatNumber(1234.567, { maximumFractionDigits: 2 });
+```
+
+</TabItem>
+<TabItem value="store">
+
+```tsx
+import { IntlStore } from '@servicetitan/intl/mobx';
+...
+@injectable()
+class MyStore {
+    constructor(@inject(IntlStore) private readonly intlStore: IntlStore) {}
+    ...
+    this.intlStore.intl.formatNumber(1234.56, { style: 'currency', currency: 'USD' });
+    this.intlStore.intl.formatNumber(0.75, { style: 'percent' });
+    this.intlStore.intl.formatNumber(1234.567, { maximumFractionDigits: 2 });
+    ...
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Further customization
+
+If you need to customize the formatting further, `FormattedNumber` and `formatNumber` accept the same options as the native `Intl.NumberFormat` API. See [`Intl.NumberFormat` for more information about those options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), and see Format.js [`FormattedNumber` documentation](https://formatjs.github.io/docs/react-intl/components/#formattednumber) or [`formatNumber` documentation](https://formatjs.github.io/docs/react-intl/api/#formatnumber) for more information on how to use them.

package/docs/intl/plurals.mdx

@@ -0,0 +1,75 @@
+---
+title: Plurals
+---
+
+import Tabs from '@theme/Tabs';
+
+Plurals can be formatted by using the `FormattedPlural` component from `react-intl`, or via the `formatPluralMessage()` 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.
+
+[`FormattedPlural`](#formattedplural) and [`formatPluralMessage()`](#formatpluralmessage) are only meant to be used with one language. Since ServiceTitan currently only supports English, and [English only uses "one" and "other" forms](https://www.unicode.org/cldr/charts/42/supplemental/language_plural_rules.html#en), those will be the only forms you will use at this time.
+
+:::note
+When ServiceTitan eventually supports multiple languages, the library will be updated to support `FormattedMessage` and `formatMessage`.
+:::
+
+## Usage
+
+### FormattedPlural
+
+See Format.js [FormattedPlural documentation](https://formatjs.github.io/docs/react-intl/components/#formattedplural) for more information.
+
+```tsx
+import { FormattedPlural } from 'react-intl';
+...
+<FormattedPlural value={5} one="item" other="items" />
+```
+
+### formatPluralMessage
+
+`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.
+
+| Name       | Type                  | Description                                          |
+| :--------- | :-------------------- | :--------------------------------------------------- |
+| `value`    | `number`              | The number value to determine the plural form.       |
+| `messages` | `PluralMessages`      | An object containing messages keyed by plural forms.  |
+| `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".
+
+<Tabs
+    defaultValue="hooks"
+    values={[
+        { label: 'React hooks', value: 'hooks' },
+        { label: 'Store', value: 'store' },
+    ]}
+>
+<TabItem value="hooks">
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+...
+const intl = useIntl();
+...
+intl.formatPluralMessage(1, { one: 'item', other: 'items' });
+// Results in "item"
+intl.formatPluralMessage(3, { one: 'item', other: 'items' });
+// Results in "items"
+```
+
+</TabItem>
+<TabItem value="store">
+
+```tsx
+import { IntlStore } from '@servicetitan/intl/mobx';
+...
+@injectable()
+class MyStore {
+    constructor(@inject(IntlStore) private readonly intlStore: IntlStore) {}
+    ...
+    this.intlStore.intl.formatPluralMessage(1, { one: 'item', other: 'items' });
+    // Results in "item"
+    this.intlStore.intl.formatPluralMessage(3, { one: 'item', other: 'items' });
+    // Results in "items"
+}
+```
+
+</TabItem>
+</Tabs>

package/docs/tanstack-query-mobx.mdx

@@ -4,7 +4,7 @@ title: TanStack Query MobX Integration
 
 import {
     AppExample, HasInitialDataExample, NoInitialDataExample, PageExample, StaleTime0Example, StaleTime10MinutesExample
-} from '@servicetitan/tanstack-query-mobx/dist/demo';
+} from '@servicetitan/tanstack-query-mobx/demo';
 
 import { CodeDemo } from '@site/src/components/code-demo';
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-anvil-uikit-contrib",
-    "version": "32.4.1",
+    "version": "32.5.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "5bc4f3c9c8a181df124fdc614964757e5490ea9b"
+    "gitHead": "25988db91418cf6ff9018760bd03ef6c3d7ef8ec"
 }