# Sajari UI

This is a work in progress of the Sajari UI component library, based on [Tailwind](https://tailwindcss.com).

## The approach

We're going to build components using Tailwind but rather than expose the `className` prop on all components and let it be a free-for-all, we're going to go for an approach similar to styled system using style props but rather than `m={4}` we have to use the full className so `purgeCSS` works correctly so our version of that would be `margin="m-4"`. We're also using TypeScript so all classNames have to be in their own type - e.g. a `Margin` type would contain all possible [margin classNames](https://tailwindcss.com/docs/margin), including any variants.

## Adding it to a project

### 1. Install the packages

To install the **production** package run `yarn add @sajari-ui/core`.

To develop locally, you can link the package using yarn:

- Run `yarn link` in this folder (`/packages/sajari-ui`). This will link all local installs to this package.
- In the consuming project run `yarn link "@sajari-ui/core"` and then `yarn add @sajari-ui/core@link:0.1.0` to install the package.

#### Peer dependencies

- `yarn add -D postcss postcss-clean postcss-cli autoprefixer`
- `yarn add tailwindcss`

### 2. Create stylesheet

Create the base stylesheet. Later this will be included in the package.

```css
/* purgecss start ignore */
@tailwind base;

@tailwind components;
/* purgecss end ignore */

@tailwind utilities;
```

### 3. Setup PostCSS

Create a postcss config with this as the content:

```javascript
const { tailwindConfig } = require('@sajari-ui/core');

tailwindConfig.purge = {
  mode: 'all',
  content: ['./src/**/*.tsx', '../../node_modules/@sajari-ui/core/dist/*.js'],
};

module.exports = {
  plugins: [
    require('tailwindcss')(tailwindConfig),
    require('autoprefixer'),
    require('postcss-clean')({
      level: 2, // Merge duplicated declarations
    }),
  ],
};
```

🚨 **NOTE**: The `tailwindConfig.purge.content` paths need to be updated to suit your application.

🚨 **NOTE**: The CSS will be purged for production builds only. To enable it always, you can set `tailwindConfig.purge.enabled` to `true`. Unfortunately we have to set `mode` to `all` to allow for the classNames in our package to stay in the CSS.

### 4. Add scripts to package.json for build

Preact CLI and Next come with PostCSS already setup so all you need to do is import the CSS file in your app and it'll get processed via PostCSS. Sadly Create React App isn't so awesome so you need to create an npm script to do it.

Before:

```json
"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}
```

After:

```json
"scripts": {
  "build:css": "postcss src/styles/index.css -o src/index.css",
  "watch:css": "postcss -w src/styles/index.css -o src/index.css",
  "prestart": "npm run prebuild",
  "prebuild": "npm run build:css",
  "start": "run-p watch:css start:react",
  "start:react": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}
```

🚨 **NOTE**: You need to adjust the paths to the CSS file depending on your application. You'll also need to import the **processed** CSS - `/src/index.css` in the example above in your app.

### Example

- See [examples/create-react-app](examples/create-react-app) for using it in a React application.

## Props & Prop Categories

The types created can be used in props as-is or as categorized sets.

- `CommonProps` - `display`, `margin`, `padding`
- `LayoutProps` - `display`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`
- `PositionProps` - `position`, `zIndex`, `offset` (top, right, bottom, left)
- `FlexProps` - `flexDirection`, `flexWrap`, `alignItems`, `alignContent`, `justifyContent`, `order`
- `FlexItemProps` - `alignSelf`, `flex`, `flexGrow`, `flexShrink`

The `index.ts` file in `/src/types` also exports the relevant keys for the categories. These are useful for mapping the props to classNames.

### Generating ClassNames

When consuming the prop categories, you can use two helpers to generate the classNames:

- `mapClassNames` (`/src/utils/styles/map-classnames.ts`) - The arguments are `props` and `keys`. Keys needs to contain the keys for the props you wish to convert to classNames.
- `filterObject` (`/src/utils/object/filter.ts`) - Filter out keys from props - useful for doing `{...rest}` type stuff where you don't want the props to bleed to the DOM element.

## Creating types

We've created a build script to build the TypeScript types based on the Tailwind config. In `/scripts/types` there are two files:

- `types.js` - An array of objects containing all the types we want to build.
- `build.js` - The actual build script to parse the config and create the types.

If you need to add a missing type or update them, you can run `yarn build:types`. The types are committed to source control so this shouldn't need to be run often - only when a change is made to the Tailwind config or we upgrade Tailwind and they add features.

## TODO

- [ ] Better docs
- [x] Create remaining Types that are missing
- [ ] Create more prop categories that are missing
- [ ] Decide which prop categories apply to all components (e.g. `FlexItemProps`)