@servicetitan/docs-anvil-uikit-contrib 37.0.3 → 38.1.0

package/docs/BREAKING_CHANGES.mdx

@@ -0,0 +1,11 @@
+---
+title: BREAKING CHANGES
+sidebar_position: 0
+---
+
+### [@servicetitan/intl](./intl/) v6.0.0
+
+Renamed [timezone formats](./intl/time#available-formats) to clarify that the timezone is added to the formatted output:
+
+- `shortTimeZone` -> `shortWithTimeZone`
+- `mediumTimeZone` -> `mediumWithTimeZone`

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

@@ -5,7 +5,7 @@ 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](../dates.mdx) and [Plurals](../plurals.mdx) documentation--you do not need to use the `useIntl` hook directly.
+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.
 :::
 
 ## Overview
@@ -37,19 +37,20 @@ The [`intl`](https://formatjs.github.io/docs/react-intl/api#intlshape) object re
 
 ### Standard Formatting Functions
 
-- [`formatDate()`](../dates.mdx) - Format dates
+- [`formatDate()`](../date) - Format date
 - [`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
+- [`formatList()`](https://formatjs.github.io/docs/react-intl/api/#formatlist) - Format list of items
+- [`formatMessage()`](https://formatjs.github.io/docs/react-intl/api/#formatmessage) - Format message with interpolation (note: translating messages is not yet configured within ServiceTitan)
+- [`formatNumber()`](../number) - Format number 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 times
+- [`formatTime()`](../time) - Format time
 
 ### Custom ServiceTitan Formatters
 
-- [`formatCurrency()`](../currency.mdx) - Format currency
-- [`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
+- [`formatCurrency()`](../currency) - Format currency
+- [`formatDateTime()`](../date-time) - Format combined date and time
+- [`formatPluralMessage()`](../plural#formatpluralmessage) - Provide a number and messages associated with plural forms, and receive the appropriate message for the current locale and plural form
 
 ### Properties
 

package/docs/intl/currency.mdx

@@ -2,11 +2,10 @@
 title: Currency
 ---
 
-import {
-    FormattedCurrencyMiniDemo
-} from '@servicetitan/intl/demo';
+import { FormattedCurrencyMiniDemo } from '@servicetitan/intl/demo';
 import { DemoExample } from '@site/src/components/code-demo';
 import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Numbers can be formatted as currency either by using the `FormattedCurrency` component from `@servicetitan/intl`, or via the `formatCurrency()` 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.
 
@@ -36,7 +35,7 @@ function CurrencyExample() {
             <FormattedCurrency value={1234.56} currency="EUR" />
         </>
     );
-};
+}
 ```
 
 ### formatCurrency
@@ -64,7 +63,7 @@ function CurrencyExample() {
             {intl.formatCurrency(1234.56, { style: 'currency', currency: 'EUR' })}
         </>
     );
-};
+}
 ```
 
 </TabItem>

package/docs/intl/date-time.mdx

@@ -0,0 +1,114 @@
+---
+title: Date and Time
+---
+
+import { FormattedDateTimeMiniDemo } from '@servicetitan/intl/demo';
+import { DemoExample } from '@site/src/components/code-demo';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use `FormattedDateTime` and `formatDateTime` to format a date value as a combined date and time.
+
+## Available Formats
+
+The following standard ServiceTitan formats are available (examples are in `en-US` locale).
+
+| Format              | Description                                                                 | Example                          |
+| :------------------ | :-------------------------------------------------------------------------- | :------------------------------- |
+| `short`             | Short date and short time. This is the default when no format is specified. | `01/09/2025, 4:00 PM`            |
+| `shortWithTimeZone` | Short date and short time, with timezone                                    | `01/09/2025, 4:00 PM EST`        |
+| `long`              | Long date and short time                                                    | `January 9, 2025 at 4:00 PM`     |
+| `longWithTimeZone`  | Long date and short time, with timezone                                     | `January 9, 2025 at 4:00 PM EST` |
+
+## Usage
+
+### FormattedDateTime
+
+```tsx
+import { FormattedDateTime } from '@servicetitan/intl';
+
+function DateTimeExample() {
+    const date = new Date('2025-01-09T16:00:00-05:00');
+
+    return (
+        <>
+            <FormattedDateTime value={date} /> {/* 01/09/2025, 4:00 PM */}
+            <FormattedDateTime value={date} format="short" /> {/* 01/09/2025, 4:00 PM */}
+            <FormattedDateTime value={date} format="shortWithTimeZone" /> {/* 01/09/2025, 4:00 PM EST */}
+            <FormattedDateTime value={date} format="long" /> {/* January 9, 2025 at 4:00 PM */}
+            <FormattedDateTime value={date} format="longWithTimeZone" /> {/* January 9, 2025 at 4:00 PM EST */}
+        </>
+    );
+}
+```
+
+### formatDateTime
+
+<Tabs
+    defaultValue="hook"
+    values={[
+        { label: 'React Hook', value: 'hook' },
+        { label: 'MobX Store', value: 'store'}
+    ]}
+>
+<TabItem value="hook">
+
+```tsx
+import { useIntl } from '@servicetitan/intl';
+
+function DateTimeExample() {
+    const { formatDateTime } = useIntl();
+    const date = new Date('2025-01-09T16:00:00-05:00');
+
+    return (
+        <>
+            {formatDateTime(date)} {/* 01/09/2025, 4:00 PM */}
+            {formatDateTime(date, { format: 'short' })} {/* 01/09/2025, 4:00 PM */}
+            {formatDateTime(date, { format: 'shortWithTimeZone' })} {/* 01/09/2025, 4:00 PM EST */}
+            {formatDateTime(date, { format: 'long' })} {/* January 9, 2025 at 4:00 PM */}
+            {formatDateTime(date, { format: 'longWithTimeZone' })} {/* January 9, 2025 at 4:00 PM EST */}
+        </>
+    );
+}
+```
+
+</TabItem>
+<TabItem value="store">
+
+```tsx
+import { inject, injectable } from '@servicetitan/react-ioc';
+import { IntlStore } from '@servicetitan/intl/mobx';
+
+@injectable()
+class MyStore {
+    constructor(@inject(IntlStore) private readonly intlStore: IntlStore) {}
+
+    formatDateTime() {
+        const date = new Date('2025-01-09T16:00:00-05:00');
+        const { formatDateTime } = this.intlStore.intl;
+        return [
+            formatDateTime(date), // 01/09/2025, 4:00 PM
+            formatDateTime(date, { format: 'short' }), // 01/09/2025, 4:00 PM
+            formatDateTime(date, { format: 'shortWithTimeZone' }), // 01/09/2025, 4:00 PM EST
+            formatDateTime(date, { format: 'long' }), // January 9, 2025 at 4:00 PM
+            formatDateTime(date, { format: 'longWithTimeZone' }), // January 9, 2025 at 4:00 PM EST
+        ];
+    }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Further customization
+
+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,
+
+```ts
+const date = new Date('2025-01-09T16:00:00-05:00');
+formatDateTime(date, { format: 'long', weekday: 'short' }); // Thu, January 9, 2025 at 4:00 PM
+```
+
+## Demo
+
+<DemoExample example={FormattedDateTimeMiniDemo} />

package/docs/intl/{dates.mdx → date.mdx}

@@ -1,17 +1,16 @@
 ---
-title: Dates
+title: Date
 ---
 
-import {
-    FormattedDateMiniDemo
-} from '@servicetitan/intl/demo';
+import { FormattedDateMiniDemo } from '@servicetitan/intl/demo';
 import { DemoExample } from '@site/src/components/code-demo';
 import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 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.
 
 :::note
-`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`.
+`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`.
 :::
 
 ## Available Formats

package/docs/intl/index.mdx

@@ -2,10 +2,9 @@
 title: Intl (Internationalization)
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+#### [CHANGELOG (@servicetitan/intl)](https://github.com/servicetitan/anvil-uikit-contrib/blob/master/packages/intl/CHANGELOG.md)
 
-`@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.
+`@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.
 
 ## Setup
 
@@ -16,8 +15,9 @@ npm install @servicetitan/intl
 ```
 
 This library has `peerDependencies` for:
--   `"@servicetitan/react-ioc": ">=22.0.0"`
--   `"react-intl": ">=7.1.11"`
+
+- `"@servicetitan/react-ioc": ">=22.0.0"`
+- `"react-intl": ">=7.1.11"`
 
 ### Provider
 
@@ -73,11 +73,12 @@ If you are instead implementing an MFE but would use the same monolith data, you
 
 `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:
 
-- [Formatting currency](./currency.mdx)
-- [Formatting dates](./dates.mdx)
-- [Formatting numbers](./numbers.mdx)
-- [Formatting times](./times.mdx)
-- [Plurals](./plurals.mdx)
+- [Currency](./currency)
+- [Date](./date)
+- [Date and time](./date-time)
+- [Number](./number)
+- [Time](./time)
+- [Plural](./plural)
 
 :::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.
@@ -117,7 +118,7 @@ export class UserService {
 
         return {
             joinDate: intl.formatDate(user.joinDate),
-            balance: intl.formatCurrency(user.balance)
+            balance: intl.formatCurrency(user.balance),
         };
     }
 }

package/docs/intl/{numbers.mdx → number.mdx}

@@ -1,12 +1,11 @@
 ---
-title: Numbers
+title: Number
 ---
 
-import {
-    FormattedNumberMiniDemo
-} from '@servicetitan/intl/demo';
+import { FormattedNumberMiniDemo } from '@servicetitan/intl/demo';
 import { DemoExample } from '@site/src/components/code-demo';
 import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Numbers can be formatted either by using the `FormattedNumber` component from `@servicetitan/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.
 

package/docs/intl/{plurals.mdx → plural.mdx}

@@ -1,12 +1,11 @@
 ---
-title: Plurals
+title: Plural
 ---
 
-import {
-    FormattedPluralMiniDemo
-} from '@servicetitan/intl/demo';
+import { FormattedPluralMiniDemo } from '@servicetitan/intl/demo';
 import { DemoExample } from '@site/src/components/code-demo';
 import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Plurals can be formatted by using the `FormattedPlural` component from `@servicetitan/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.
 
@@ -32,11 +31,11 @@ import { FormattedPlural } from '@servicetitan/intl';
 
 `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".
+| 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"
@@ -78,7 +77,6 @@ class MyStore {
 </TabItem>
 </Tabs>
 
-
 ### Demo
 
 <DemoExample example={FormattedPluralMiniDemo} />

package/docs/intl/{times.mdx → time.mdx}

@@ -1,12 +1,11 @@
 ---
-title: Times
+title: Time
 ---
 
-import {
-    FormattedTimeMiniDemo
-} from '@servicetitan/intl/demo';
+import { FormattedTimeMiniDemo } from '@servicetitan/intl/demo';
 import { DemoExample } from '@site/src/components/code-demo';
 import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Times can be formatted either by using the [`FormattedTime`](#formattedtime) component from `@servicetitan/intl`, or via the [`formatTime`](#formattime) 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.
 
@@ -19,10 +18,10 @@ The example results that follow use a locale of 'en-US' and time zone of 'Americ
 :::
 
 - `short` results in `4:00 PM` (default)
-- `shortTimezone` results in `4:00 PM EDT`
-- `utc` results in `08:00 PM UTC` (forces UTC timezone and adds leading zero)
+- `shortWithTimeZone` results in `4:00 PM EDT`
 - `medium` results in `4:00:00 PM`
-- `mediumTimeZone` results in `4:00:00 PM EDT`
+- `mediumWithTimeZone` results in `4:00:00 PM EDT`
+- `utc` results in `08:00 PM UTC` (forces UTC timezone and adds leading zero)
 
 ## Usage
 
@@ -38,10 +37,10 @@ function TimeExample() {
         <>
             <FormattedTime value={time} /> {/* "4:00 PM" */}
             <FormattedTime value={time} format="short" /> {/* "4:00 PM" */}
-            <FormattedTime value={time} format="shortTimeZone" /> {/* "4:00 PM EDT" */}
+            <FormattedTime value={time} format="shortWithTimeZone" /> {/* "4:00 PM EDT" */}
             <FormattedTime value={time} format="utc" /> {/* "08:00 PM" UTC*/}
             <FormattedTime value={time} format="medium" /> {/* "4:00:00 PM" */}
-            <FormattedTime value={time} format="mediumTimeZone" /> {/* "4:00:00 PM EDT" */}
+            <FormattedTime value={time} format="mediumWithTimeZone" /> {/* "4:00:00 PM EDT" */}
         </>
     );
 }

package/docs/secrets.mdx

@@ -0,0 +1,23 @@
+---
+title: Secrets
+---
+
+`@servicetitan/secrets` provides a centralized way to manage and distribute shared frontend secrets (API keys, tokens, etc.) across ServiceTitan's applications.
+
+## Quick Start
+
+Import secrets directly from the package:
+
+```ts
+import { arcgisApiKey } from '@servicetitan/secrets';
+
+const mapClient = new ArcGisClient(arcgisApiKey);
+```
+
+## Managing Secrets
+
+For detailed instructions on adding, updating, and managing secrets, see the [package README](https://github.com/servicetitan/anvil-uikit-contrib/blob/master/packages/secrets/README.md).
+
+## Frontend Secrets Only
+
+This package is designed for **frontend secrets only** - secrets that are safe to be public and checked into version control (e.g., read-only API keys, analytics tokens). Never store private keys, database credentials, or backend-only secrets here.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-anvil-uikit-contrib",
-    "version": "37.0.3",
+    "version": "38.1.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "adf2c3ae6e37a646304d21b6701d358a52f8f2e7"
+    "gitHead": "a44925e37020acb2153c7e10215a31cd22d054c1"
 }