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.

<UiProvider>
  <App>
</UiProvider>

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 browser API.

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 component is used. It will receive the same props the 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.

/** @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

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.

Running tests

Tests are run using vitest, 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

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

Right

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