npm package: @ndlib/component-library
Description: This is the repo for The Hesburgh Component Library, a set of React components that escapsulate the design patterns used by the Hesburgh Library IT department.
Latest version: 1.0.41

# Hesburgh Component Library

This is the repo for The Hesburgh Component Library, a set of React components that escapsulate the
design patterns used by the Hesburgh Library IT department.

## Using the library

### Installation

To install the library in your project, run

```
yarn install @ndlib/component-library
```

### Setup

#### UiProvider

In order for styles to be applied correctly, the `UiProvider` component must be included at the top of your project.

```tsx
<UiProvider>
  <App>
</UiProvider>
```

#### UiProviderV2

If you are using Version 2 components, you must use the `UiProviderV2` component at the top of your project as it compiles styles differently.

```tsx
<UIProviderV2>
  <App>
</UiProviderV2>
```

For frameworks that split application code by pages, it is recommended to add this provider at the root level rather than
at the page level. In Gatsby, this can be done using the [wrapRootElement](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-browser/#wrapRootElement) browser API.

```tsx
exports.wrapRootElement = ({ element }) => {
  return <UiProvider>{element}</UiProvider>
}
```

#### Configuring Link

By default, the `Link` component in this library will use a native HTML `<a>` component in its implementation. This behavior can be overriden
by setting the `link.internalLink` and/or `link.externalLink` property on the `components` prop of the `UiProvider` component. If a custom component
is provided, the custom component will be rendered by when the <Link /> component is used. It will receive the same props the <Link> receives, as well as an
`sx` object with default link styles from the theme and any custom styles provided.

Note that the `theme-ui` jsx transform is needed in order to convert the `sx` prop into a stylesheet definition.

```tsx
/** @jsxImportSource theme-ui */
import { Link } from 'gatsby'

const CustomInternalLink = ({ sx, ...rest}) => ()
  return <Link sx={sx} {...rest} />
)

const WrappedApp = () => {
  <UiProvider components={{
    link: {
      internalLink: CustomInternalLink
    }
  }}>
    <App />
  </UiProvider>
}
```

## Running locally

Dependencies must be installed before storybook can be started. Dependencies can be installed with: `yarn install`.

To build and deploy your storybook locally for development, run `yarn start`

## Testing locally

If you wish to test your changes locally in another project that uses the component library, use the following steps:

1. Run `yarn build`
2. Enter `pwd` in the terminal to generate the path where the component library is located on your machine
3. In the package.json of the project you wish to test the locally modified component library in, replace the version of the component library with `"file:///<PATH>"`
4. Run `yarn install` or `npm run install`

If you need to make a change in the component library and test again:

1. Rerun `yarn build` in the component library
2. In your other project, change the package.json to use the version number again instead of the path
3. Run `yarn install` or `npm run install` again
4. Change the version back to the path, and run `yarn install` or `npm run install` again

## Deploying Storybook

Whenever a commit is added to the main branch, the contents of the `/docs` folder will be deployed to our Github pages site.

To build a new version of the storybook to be deployed, run `yarn build-storybook`. Our storybook build uses [vite](https://vitejs.dev/).

## Running tests

Tests are run using [vitest](https://vitest.dev/), a test-runner built for vite that is similar to jest. Test suite can be run with: `yarn test`

## Linting

Changes should be linted before commits. Run our linter with `yarn lint`. Failed linting will block builds and deploys. Our lint process uses `eslint` and `prettier`.
Running `yarn lint:fix` will fix any issues that can be automatically fixed.

## Building for npm

The build process for the npm module for this library uses `tsc`. ESM exports are used to better support tree-shaking. When adding new code to this library,
be careful to ensure than importing the module do not cause side-effects. In other words, don't execute any process or do any state management outside
of exported properties or functions because this code might be removed by tree-shaker. See examples below:

### Wrong

```jsx
// This code may get removed by tree-shaker
setTimeout(() => {
  console.log('hello world')
})
```

### Right

```jsx
export const myFunction = () => {
  setTimeout(() => {
    console.log('hello world')
  })
}
```