@televet/kibble-ui 0.1.0 → 1.0.0

package/README.md

@@ -1,44 +1,204 @@
-[![Build Status](https://travis-ci.com/morewings/cra-template-npm-library.svg?branch=master)](https://travis-ci.com/morewings/cra-template-npm-library)
-[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=morewings/cra-template-npm-library)](https://dependabot.com)
-[![dependencies Status](https://david-dm.org/morewings/cra-template-npm-library/status.svg)](https://david-dm.org/morewings/cra-template-npm-library)
-[![Netlify Status](https://api.netlify.com/api/v1/badges/7448a6f6-8be5-4d26-b886-f59db21ebb4e/deploy-status)](https://app.netlify.com/sites/cra-template-npm-library/deploys)
-[![npm version](https://badge.fury.io/js/cra-template-npm-library.svg)](https://www.npmjs.com/package/cra-template-npm-library)
-[![npm](https://img.shields.io/npm/dm/cra-template-npm-library)](https://www.npmjs.com/package/cra-template-npm-library)
+# Kibble
 
-# NPM library Create React App template
+Kibble is a React component library for use at TeleVet.
 
-[Create React App](https://github.com/facebook/create-react-app) (CRA) template to build and publish NPM libraries with **rollup**, **eslint** and **stylelint** configurations. See [full documentation](https://cra-template-npm-library.netlify.com/).
+https://televet.github.io/kibble-ui/
 
-## Usage
+## Usage within a Televet Project
+
+### New Project Setup
+
+If your project does not include a `.npmrc`, create it and add the following:
+
+`//registry.npmjs.org/:_authToken=${NPM_TOKEN}`
+
+Then add the NPM_TOKEN environment variable to your .bash_profile or .zshrc
+
+`export NPM_TOKEN=${SOME_TOKEN}`
+
+Note: The NPM token can be found here in our [shared accounts table](https://www.notion.so/televet/Shared-Accounts-c691ae4e0dc8482c876aa0f4a56d8ea7)
+
+### Install in project
+
+`npm i --save @televet/kibble-ui`
+
+```
+import {
+  ThemeProvider,
+  theme,
+  Button,
+  .... and all other components
+} from 'kibble-ui';
+```
+
+## Development Setup
+
+### Linking Projects for Local Development
+
+```
+$ cd kibble-ui           # navigate into the package directory
+$ rm -rf node_modules    # remove existing node_modules
+$ npm run build          # ensure there are build files available for the package to reference
+
+# Update your library's package.json so that react and react-dom are pointing to your projects node_modules versions of these two packages. See reference to mutliple versions of react error here for more info on why this is necessary: https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
+
+# "react": "../clinic-web/node_modules/react"
+# "react-dom": "../clinic-web/node_modules/react-dom"
+
+$ npm i                  # install packages
+$ npm run start          # start the development server
+
+# Navigate to project directory and update package.json to point to your local copy of your library
+# "@televet/kibble-ui": "./../kibble-ui"
+
+$ cd clinic-web          # go into a project directory
+$ rm -rf node_modules    # remove existing node_modules
+$ npm install            # fresh install with local version of kibble ui
+$ npm run start          # start the development server
+
+# When linking local packages like this your text editor may display errors saying the package cannot be found, however, if you restart your editor these errors should dissapear.
+```
+
+### Unlinking Projects after Local Development is Complete
+
+```
+# Inside of library
+$ git checkout package.json
+$ rm -rf node_modules
+$ npm install
+
+# Inside of project
+$ git checkout package.json
+$ rm -rf node_modules
+$ npm install
+```
+
+### `src` directory structure
+
+Development takes place inside `src` directory. This is where your library code should live, this code will be bundled with rollup and published to NPM. Exports from `src/index.js` will be included in the library. Files with the `.stories.*` extension will be compiled and built to the `docs` folder and deployed with github pages.
+
+```bash
+|-- src # library code
+|   |-- components
+|   |   |-- ComponentName # Component will be exposed as a part of library
+|   |   |   |-- Component.spec.js # test file
+|   |   |   |-- __snapshots__
+|   |   |   |   └── Component.spec.js.snap # test snapshot
+|   |   |   |-- Component.stories.tsx # storybook file
+|   |   |   └── index.tsx
+|   |-- providers
+|   |   |-- ThemeProvider
+|   |-- theme
+|   |   |-- blur.ts
+|   |   |-- borders.ts
+|   |   |-- breakpoints.ts
+|   |   |-- colors.ts
+|   |   |-- fonts.ts
+|   |   |-- fontSizes.ts
+|   |   |-- fontWeights.ts
+|   |   |-- index.ts
+|   |   |-- letterSpacings.ts
+|   |   |-- lineHeights.ts
+|   |   |-- radii.ts
+|   |   |-- shadows.ts
+|   |   |-- sizes.ts
+|   |   |-- space.ts
+|   |   |-- transitions.ts
+|   |   |-- zIndeces.ts
+|   └── index.js # entry point for rollup build
+└── setupTests.js
+```
+
+## Build
+
+This site uses [Storybook](https://storybook.js.org/) configuration to handle documentation and examples.
+
+```bash
+npm run build # bundles library code to `build` folder, and documentation code to `docs` folder in the root of project.
+```
+
+You can view live documentation here after deploying: https://televet.github.io/kibble-ui/
+
+## Deploy and Publish
+
+1. Update npm version number with `npm version <patch, major, or minor>`. Read more about [the version options](https://docs.npmjs.com/updating-your-published-package-version-number) here.
+2. Run `npm run build`
+3. Commit changes to git.
+4. When pushing to master, GitHub will publish the package to npm with latest changes.
+
+This repository is using a [GitHub Worflow](https://docs.github.com/en/actions/using-workflows). See the `.github` folder for more information.
+
+## Test
+
+Please include tests next to the file you are testing.  
+`npm run test` - Run all tests  
+`npm run test:watch` - Watch tests
+
+## Lint
+
+On commit, [husky](https://github.com/typicode/husky) will run [lint-staged](https://github.com/okonet/lint-staged) with `eslint --fix` command on staged files, preventing you from committing badly formatted code. You can change or disable this behavior inside `.linstagedrc` config file. Before each push tests will run in the same manner.
+
+### Caveats
+
+- If pre-commit hooks not work (e. g. your code is not linted after commit), run `yarn add husky` in your project folder.
+
+#### eslint
 
 ```shell script
-npx create-react-app %PROJECT_NAME% --template npm-library
-``` 
-Or
-```shell script
-yarn create react-app %PROJECT_NAME% --template npm-library
+yarn lint:js # runs eslint in src directory
+yarn fix:js # runs eslint in src directory with --fix parameter
 ```
 
-Then
+Template extends [CRA eslint rules](https://github.com/facebook/create-react-app/tree/master/packages/eslint-config-react-app) with custom set, tailored for reasonable and clean development process. I added `prettier` to force consistent formatting and `eslint-plugin-fp` to avoid accidental mutations. Don't like trailing semicolons? Feel free to [tweak prettier rules](https://prettier.io/docs/en/configuration.html) inside `.prettierrc` file to match your code style.
+
+#### stylelint
 
 ```shell script
-cd %PROJECT_NAME%
-yarn start
+yarn lint:style # runs stylelint in src directory
+yarn fix:style # runs stylelint in src directory with --fix parameter
 ```
 
-## Features
+Template includes [stylelint](https://stylelint.io/), to check CSS/SASS/LESS files. We are using [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard) rule set extended with:
 
-- Handles all modern JS features.
-- Bundles `commonjs` and `es` module formats.
-- [Husky](https://github.com/typicode/husky) for git hooks.
-- [Eslint](https://eslint.org/) and [stylelint](https://stylelint.io/).
-- [Rollup](https://rollupjs.org/guide/en/) for bundling.
-- [Babel](https://babeljs.io/) for transpiling.
-- [Jest](https://jestjs.io/) and [react-testing-library](https://testing-library.com/docs/react-testing-library/intro) for testing.
-- Supports CSS modules, SASS/SCSS, Less and PostCSS.
-- [Storybook](https://storybook.js.org/) for documentation and demo.
-- And [much more](https://cra-template-npm-library.netlify.com/).
+```js
+// Check `calc` functions formatting, required for `calc` to work in IE11
+"function-calc-no-unspaced-operator": true,
+// Custom rules (aka CSS vars) should go first
+"order/order": [
+  "custom-properties",
+  "declarations"
+],
+// Require rules to be in alphabetical order
+"order/properties-alphabetical-order": true,
+// Disallow vendor prefixes, since CRA has autoprefixer enabled
+"property-no-vendor-prefix": true,
+"media-feature-name-no-vendor-prefix": true,
+"at-rule-no-vendor-prefix": true,
+"selector-no-vendor-prefix": true,
+// Limit rules nesting for readablity purposes
+"max-nesting-depth": 3,
+// Limit selector complexity for readablity purposes
+"selector-max-compound-selectors": 5
+```
+
+Stylelint errors don't prevent build of application in development mode.
+
+## Peer Dependencies
+
+Please see below. These must be dependencies in your project to use this library
+
+```
+"react": ">=16.8.0",
+"react-dom": ">=16.8.0",
+"prop-types": ">=15.0.0"
+```
 
-## Contributors
+## Technologies Used
 
-@morewings, @sky0matic
+- [Create React App](https://github.com/facebook/create-react-app) - (CRA) template to build and publish NPM libraries with **rollup**, **eslint** and **stylelint** configurations.
+- [Chakra UI](https://chakra-ui.com/) - Chakra UI is a simple, modular and accessible component library that gives you the building blocks you need to build your React applications.
+- [Styled Components](https://styled-components.com/docs) - Visual primitives for the component age.
+- [rollup.js](https://rollupjs.org/guide/en/) - Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application.
+- [Storybook](https://storybook.js.org/docs/basics/introduction/) - Build bulletproof UI components faster.
+- [Storybook DocsPage](https://github.com/storybookjs/storybook/tree/master/addons/docs#docspage) - DocsPage pulls information from your stories, components, source code, and story metadata to construct a sensible, zero-config default.
+- [React Testing Library](https://testing-library.com/docs/intro) - Simple and complete testing utilities that encourage good testing practices

package/build/components/Banner/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+declare const Banner: () => JSX.Element;
+export default Banner;

package/build/components/Button/index.d.ts

@@ -0,0 +1,5 @@
+import { ReactNode } from 'react';
+declare const Button: ({ children }: {
+    children: ReactNode;
+}) => JSX.Element;
+export default Button;

package/build/components/Input/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+declare const KInput: () => JSX.Element;
+export default KInput;

package/build/index.d.ts

@@ -1,3 +1,5 @@
-import theme from './theme/theme';
-import ThemeProvider from './providers/ThemeProvider/ThemeProvider';
-export { theme, ThemeProvider };
+import theme, { ITheme } from './theme';
+import KibbleThemeProvider from './providers/ThemeProvider';
+import Button from './components/Button';
+import Banner from './components/Banner';
+export { theme, ITheme, KibbleThemeProvider, Button, Banner };