npm package: @tailwindapp/web-ui
Description: <h1 align="center">TailwindApp Web UI</h1>
Latest version: 1.5.22


<h1 align="center">TailwindApp Web UI</h1>

[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 |
|--------------|---------------|
| ![build-status](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiSHphb0FTR1N3NFFhQU52cnpPeEttQWxUa0lmN2tRUWxqclFLRXhFYURKVmFrRDNXTGtiUWxaVzF6dEhKZk5qd1FTYXlTd0p4OXpjYWxNV0I5MnV6dmFrPSIsIml2UGFyYW1ldGVyU3BlYyI6IjlYbDRsL3ZucWJWM1ZHc3ciLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master) | ![docs-status](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiRWFFR0NYTVF1alY0TGpMempTbXl6ZjdZb2NSTkJ2ZWM1TkU3blA1R04xeklaR2pMZXBYSlp3RUVRTWVXZ0tYNmxJN29ONDVEbHc3N2JrNXNjcEc3SXFjPSIsIml2UGFyYW1ldGVyU3BlYyI6ImV5NUdLT28wY0dqSDgxZGUiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master) |


## 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 = () => (
 <Fragment>
	 <div id="myTarget">My Target</div>
	 <MessagePopover target={'myTarget'} message={'My Message'} show={true} />
 </Fragment>);

render(<App />, 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.