Anvil2 React Library

<h1 align="center">
  Anvil2 React Library
</h1>

Anvil2 contains reusable components, fonts, icons, and more for building ServiceTitan products.

# Getting Started

## Installation

We recommend installing Anvil2 by running the following `npm` command (or the equivalent `yarn`/`pnpm` command) in your project folder:

```
npm install @servicetitan/anvil2
```

### Note on versions with MFEs

If you are using a Micro Front End (MFE) with the light bundle, the version of `@servicetitan/anvil2` that is installed in the host app will be used when the MFE is loaded within the host app. If you need features or bug fixes from newer versions, update the version in the host app first.

## Usage

### Components

Components can be imported as named exports from the package root:

```tsx
import { Button, Icon } from "@servicetitan/anvil2";
```

### Icons

Anvil2 icons are expected to be used with the [SVGR](https://github.com/gregberge/svgr) library, which will import SVGs as React components. SVGR should already be part of the latest `@servicetitan/startup` Webpack configuration.

Importing and using an icon:

```tsx
import { Button, Icon } from "@servicetitan/anvil2";

import Warning from "@servicetitan/anvil2/assets/icons/material/round/warning.svg";
import Star from "@servicetitan/anvil2/assets/icons/material/round/star.svg";
import LocalSettings from "@servicetitan/anvil2/assets/icons/st/local_settings.svg";

export const Example = () => (
  <>
    <Icon svg={Warning} size="large" />
    <Button icon={Star} aria-label="Favorite" />
    <Button icon={LocalSettings}>Settings</Button>
  </>
);
```

### CSS Utils

A set of CSS Utils classes are available. See the [source code in our repo](https://github.com/servicetitan/hammer/blob/main/packages/anvil2/public/assets/css-utils) to see the full list.

```tsx
import { Card } from "@servicetitan/anvil2";
import "@servicetitan/anvil2/assets/css-utils/utils.css";

export const Example = () => (
  <>
    <Card className="m-inline-4">Card with inline margin</Card>
  </>
);
```

#### NOTES

- If the `utils.css` file is already loaded by the host app, you might not need to import it.
- There is currently a known issue related to some temporary CSS overrides we've had to make to prevent some legacy CSS in the monolith from overriding Anvil2 component styles. If the CSS util you add doesn't work, and you see something like this in the browser inspector: `:not(.aXNw) [data-anv='text']`, you will need to instead add the styles you want in a custom `className`, and add an `@layer` around it:

```css
@layer application {
  /* replaces .c-danger */
  .custom-class {
    color: var(--status-color-danger);
  }
}
```

> We are actively working on a long-term solution with the Front-End Platform team.

### `AnvilProvider`

When using the Anvil2 component library, we recommend wrapping the top level of your app in the `AnvilProvider` component, which also supports light/dark themes, localization, and `data-tracking-id` configurations:

```tsx
import { AnvilProvider } from "@servicetitan/anvil2";

<AnvilProvider themeData={...} localizationData={...} trackingIdData={...}>
  ...
</AnvilProvider>
```

### Data Tracking IDs for FullStory

In order to enable consistent FullStory data tracking with Anvil2 components, a `data-tracking-id` is automatically generated for all **interactive** components. This id will only change if certain props change, which are determined on a per-component basis.

If your team or product already has a different strategy for tagging components in place, you can disable the auto-generated `data-tracking-id` tags using the `AnvilProvider.trackingIdData` or `TrackingProvider.optOut`:

```tsx
// Using AnvilProvider
<AnvilProvider trackingIdData={{ optOut: true }}>...</AnvilProvider>

// Using TrackingProvider
<TrackingProvider scope="ST" optOut>...</TrackingProvider>
```

# Documentation

You can read the Anvil2 docs at: https://anvil.servicetitan.com/

# Contributing

We welcome contributions of all kinds from design to code!

Please reach out to our team in [#ask-designsystem](https://servicetitan.enterprise.slack.com/archives/CBSRGHTRS) if you would like to make a contribution.

Check out the [root-level Contributing docs](../../README.md#contributing) for more details on making changes to this package.