CPT2 Common UI

Common UI components styled with Tailwindcss

Use

The CPT2 Common UI package exposes a collection of Tailwind CSS formatted UI components.

Install it

npm i @cpt2/cpt2-common-ui

Also install the various peer dependencies

I'm going to assume you have react and react-dom installed, but you will need the following FontAwesome libraries.

npm i @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome

You'll also need react-router-dom, as we use its Link component.

npm i react-router-dom

Use the components

Standard components

import {
  ActionCard,
  ActivityCard,
  AdminCard,
  Alert,
  AlertFloating,
  Avatar,
  AvatarGroup,
  Badge,
  BadgeGroup,
  Banner,
  Breadcrumbs,
  Button,
  Checkbox,
  CollapsibleCard,
  DateCard,
  DraggableCardsWrapper,
  DropdownMenu,
  EventCard,
  FormInput,
  FormSelect,
  GenericCard,
  Icon,
  InfoCard,
  InlineEditor,
  Modal,
  Navbar,
  Notification,
  NotificationBadge,
  Questionnaire,
  RadioGroup,
  Ratio,
  RoleCard,
  SectionTitle,
  SelectMenu,
  Sidebar,
  SlideOver,
  SquareButton,
  StackedEditor,
  Stepper,
  SubHeader,
  TabNav,
  Table,
  TaskCard,
  Timeline,
  Toggle,
  Tooltip,
  UserCard
} from '@cpt2/cpt2-common-ui'

We also export some so-called 'pure' components, which are display only versions of components that otherwise manage their own state. We do this so that external component users can manage the state of these components themselves.

import {
  PureAlertFloating,
  PureBanner,
  PureCollapsibleCard,
  PureInlineEditor,
  PureNotification,
  PureToggle
} from '@cpt2/cpt2-common-ui'

Utils

import { utils } from '@cpt2/cpt2-common-ui'

• classNames — combines various individual class names together into a single string, and eliminates any that are null, empty or otherwise falsy.
• clickable — a wrapper around a component that applies a clickable button if there is an onClick handler in the props.
• makeGroupReducer — handy when you need to group an array of objects by their id, name, slug, or whatever, into a set of ordered arrays
• makeIndexReducer — handy when you need to index an array of objects by their id, name, slug, or whatever.
• makeVariantFinder — a factory for making variant finders given a set of variants and an optional default key.
• noop - a function that does nothing
• reorder - a function that reorders an array
• serialCommaList — a function that formats a list of words separated by commas, including an Oxford comma as appropriate.

Hooks

import { hooks } from '@cpt2/cpt2-common-ui'

• useViewport — returns a current width and attaches a window.resize handler to maintain that width.

Storybook

You can preview the components via the following storybooks.

| name | branch | deploys on | status | url | | ---- | ------ | ---------- | ------ | --- | | storybook-dev | develop | PRs and Merge | | cpt2-common-ui.netlify.app | | storybook-prod | main | PRs and Merge | n/a | n/a |

Development

Please review the contributing notes before proceeding.

| branch | ci status | coverage | notes | | ------ | --------- | -------- | ----- | | develop | | | work in progress | | main | | | production release |

Prerequisites

• NodeJS, version 14.17.5 (LTS) (I use nvm to manage Node versions — brew install nvm.)
• npm, version 6.x This is installed with NodeJS on mac and linux systems by default.

Handy to have

• credible-platform DNS configuration via GoDaddy (You'll need the correct permissions for this to work).
• CPT2 account on Netlify.

Install dependencies

npm ci

Installation troubleshooting

If you find yourself needing to do a complete wipe and reinstall of dependencies you'll discover that the versions of babel-loader and webpack that Storybook uses are not aligned with the versions in react-scripts. This will cause all kinds of errors.

To fix this:

1. First rm -rf node_modules to nuke your node_modules folder, then
2. rm package-lock.json to get rid of the broken package-lock.json file.
3. Now run npm i --package-lock-only [email protected] [email protected].
4. Open up your package.json file and remove babel-loader and webpack from dependencies and save it.
5. Now you can run npm install and the dependencies will be correctly aligned.

Run the Storybook

npm start

Open localhost:6006 to view it in the browser.

The site will reload if you make edits. You will also see any lint errors in the console.

• See storybook.js.org for more information.

Run the unit tests

npm test

Launches the test runner in interactive watch mode.

• See create-react-app/docs/running tests for more information.

Build a release

npm run build

Publish a release

You must be a member of the cpt2 organisation on npmjs.com.

Read the section on creating a production release in the contributing notes.

Contributing

Please see the contributing notes.