TailwindApp Web UI
[Component Documentation and Playgrounds here](https://web-ui.tailwindapp.com/)
## Installation
TailwindApp Web UI is available as an [npm package](https://www.npmjs.com/package/@tailwindapp/web-ui).
```bash
# install the package into a React application
npm install @tailwindapp/web-ui
```
| Build Status | Docs Status |
|--------------|---------------|
|  |  |
## Usage
Here is a quick example to get you started:
```jsx
import React, {Fragment} from 'react';
import { render } from "react-dom";
import { MessagePopover } from "@tailwindapp/web-ui";
const App = () => (
My Target
);
render(, document.getElementById("root"));
```
## Contributing to TailwindApp Web UI
### Installing to Local System
Clone the repo to your local system and install the packages.
```bash
git clone git@github.com:tailwind/web-ui.git
# change into that directory
cd web-ui
# install packages
npm i
```
### Component Architecture
Our convention is to create a directory that matches the component name but in snake-case.
So a component named `MyTestComponent` would be placed inside a directory called
`my-test-component`. Also, there are 4 required files for each component:
- Component main file (`my-test-component.tsx`)
- Preferably a functional component (using [react hooks](https://reactjs.org/docs/hooks-intro.html) if local state is needed)
- Component test file (`my-test-component.test.tsx`)
- Component Storybook stories file (`my-test-component.stories.tsx`)
- Component styles file (`my-test-component.styles.scss`)
**NOTE** You can use [code generation](CODEGEN.md) to create this directory and all files
(as well as adding the export declaration to the `src/lib/index.js` file).
### Start and Watch Docs (Storybook - [docs](https://storybook.js.org/))
During development, you'll want to hot-reload the documentation pages. By default, this page will start at
`http://localhost:9009/`
```bash
# generate documentation and reload when files change
npm run docs:watch
```
### Run and Watch the Playground File
We run a standalone CRA (create-react-app) application. You can use the `./src/index.js` file as a "playground" environment. By
default, this page will start at `http://localhost:3000/tailwind/web-ui`.
**NOTE** The playground file is intentionally ignored in the `.gitignore` file so you can
edit it as needed for your development purposes.
```bash
# start and watch the playground environment
npm run start
```
### Developing components alongside the consuming React application with `npm link`
Sometimes it is helpful to develop new components in isolation but still review them in context of the final consuming
application. You can use `npm link` ([docs](https://medium.com/dailyjs/how-to-use-npm-link-7375b6219557)) to create a symlink to the local `@tailwindapp/web-ui` from the consuming application. (Consuming application would be an application like `tailwind/app`).
```bash
# from the root of your local install of @tailwindapp/web-ui
npm link
npm run start
```
```bash
# from the root of the consuming application
npm link @tailwindapp/web-ui
npm run start # or whatever command used to 'watch' that application
```
After linking the local library, you can import a component into the consuming application, make changes to that
component and see the changes within your consuming application.
### Exposing Components
Before a component can be imported into another application, it must be exposed to the library. This is
done by importing the component and then exporting it as a named component within the ./src/index.js
file. For example:
```js
export { MessagePopover } from "./message-popover/message-popover";
export { GridTile } from "./grid-tile/grid-tile-view";
export { Button } from "./button/button";
export { SimpleDropdown } from "./simple-dropdown/simple-dropdown"
```
Then the external application would import a specific component as a named component:
```jsx
import { MessagePopover } from '@tailwindapp/web-ui';
```
### Code Generation Script
To aid in creating a new component with all required files and export declaration,
you can use the [code generation script](CODEGEN.md)
```bash
npm run codegen
```
### Deploying a New Version of the Library
To deploy a new version of the library, you'll need to tag it and push the tag to Github.
To correctly tag the version use the `npm version` command. This will bump the version of the package and commit it, along with tagging the git commit.
You should follow semver guidelines for version numbers.
See https://semver.org/ for information on versions and see https://docs.npmjs.com/cli/version for more details on how to use `npm version`
#### Steps to Tag and Deploy
First, we need to make sure there are no errors by running the two commands.
```
npm run docs:build
```
```
npm run build
```
Now that we are sure there are no errors, checkout a new branch to make the deployment.
```
git checkout -b deploy/feature-name
```
In the new branch, update the version and tag the commit.
```
npm version patch
```
Then push the commit and the tag to Github.
```
git push && git push origin --tags
```
Create a new pull request.
After merging, AWS will run `buildspec.deploy.yml` and publish the latest version to NPM.