npm package: @planningcenter/doxy-web
Description: Doxy for Church Center Web
Author: Josh Wilkerson
Latest version: 2.8.8

# doxy-web

Unified styles + React components for Church Center Web.

## Links

- [NPM package](https://www.npmjs.com/package/@planningcenter/doxy-web)
- [Github repository](https://github.com/planningcenter/doxy-web)
- [Storybook (documentation)](https://planningcenter.github.io/doxy-web)

## Getting Started

```
cd Code
git clone git@github.com:planningcenter/doxy-web.git
cd doxy-web
yarn install
```

## Development Scripts

- `yarn start` - compiles SCSS/JS + runs Storybook using `localhost`
- `yarn develop` - compiles SCSS/JS + watches `src` directory for changes
- `yarn develop:yalc` - compiles/watches SCSS/JS and locally publishes bundled code via `yalc` (this is the preferred way to test package changes locally in `church-center` or proxied app - (check out the [yalc development guide](docs/yalc-development-guide.md) for more details)
- `yarn test` - runs defined component tests using Jest
- `yarn test:watch` - runs tests + watches `src` directory for changes

#### Local Development Process:

1. Run `yarn start` to use Storybook development environment

- using local `pco-box` - [`http://localhost:3000`](http://localhost:3000)
- using `pco cloud-box` - [`http://first.churchcenter.test:3000`](http://first.churchcenter.test:3000)

2. In separate terminal, run `yarn develop:yalc` to watch `src` for changes and push to `yalc` registry
3. In `church-center` (or proxied app), run `yalc add @planningcenter/doxy-web` to consume/test local changes

#### "Sandbox" Development Environment

The sandbox provides another local testing/development environment where multiple UI elements/components can be viewed simultaneously.
This is especially useful for making new CSS changes because you can see multiple instances of the UI states vs. in Storybook, where you can only toggle 1 state at a time.

1. Run `yarn sandbox` (parallel command for `yarn develop:yalc` & `cd sandbox && yarn start`)
2. Follow `localhost` link in terminal to view local Parcel app

**To add new views**

1. Add a contextually-named component to `sandbox/src/pages` directory and export from [`pages/index.js`](https://github.com/planningcenter/doxy-web/blob/main/sandbox/src/pages/index.js)
2. Import page/component to [`src/App.jsx`](https://github.com/planningcenter/doxy-web/blob/main/sandbox/src/App.jsx) and add to [`<Router />`](https://github.com/planningcenter/doxy-web/blob/main/sandbox/src/App.jsx#L35) with path
3. Add corresponding `<Link />` to [`src/components/Sidebar.jsx`](https://github.com/planningcenter/doxy-web/blob/main/sandbox/src/components/Sidebar.jsx#L60)

## Contributing

- New versions to `@planningcenter/doxy-web` are made using a "batched" process by deploying changes to NPM from `main`.
- All changes should be made using a "feature branch" forked from `main` and merged using our standard PR process.
- Changes should be documented in the CHANGELOG before merging the approved PR.

## Pre-release Versions

See [How we pre-release](https://www.notion.so/planningcenter/How-We-Pre-release-bd60e000b7f14fd7ab85a476e71e0e64?pvs=4) on Notion for detailed instructions/exampled.

## Versioning + Deploying to NPM

Refer to the [Planning Center release strategy](https://www.notion.so/planningcenter/Package-handling-at-Planning-Center-aka-How-we-npm-b1c78de88e124f7ca41955e0b082f55f#9bc8c7658fcf4db586e1e43549ebb61a) on Notion.

## Deploying Storybook:

- `yarn deploy:storybook`
- view changes: [https://planningcenter.github.io/doxy-web/](https://planningcenter.github.io/doxy-web/)

## Consumable CSS

Import `@planningcenter/doxy-web/dist/css/doxy-web`

## Importing React Components

`import { Heading } from "@planningcenter/doxy-web"`