@televet/kibble-ui 0.1.0-beta.1

package/README.md

@@ -0,0 +1,397 @@
+# Kibble
+
+Kibble is a React component library for use at TeleVet.
+
+https://televet.github.io/kibble-ui/
+
+## 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}`
+
+#### Add NPM_TOKEN environment variable
+
+In your .bash_profile or .zshrc
+`export NPM_TOKEN=SOME_TOKEN`
+
+#### Install in project
+
+`npm i --save @televet/kibble-ui`
+
+```
+import {
+  ThemeProvider,
+  theme,
+  Button,
+  .... and all other components
+} from 'kibble-ui';
+```
+
+### Development Setup
+
+`$ npm i` - Install dependencies.  
+`npm run start` runs CRA in development mode with hot reloading. Open http://localhost:3000 to see your code live.
+
+#### Linking Projects for Local Development
+
+```
+cd ~/kibble-ui                              # go into the package directory
+npm run build                               # ensure there are build files available for the package to reference
+npm link ../clinic-web/node_modules/react   # links kibble-ui react to clinic-web react to prevent two versions of react. See reference to this error here: https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
+
+# You may need to run the link commands using sudo if you get a permissions error
+
+# Navigate to project directory and update package.json to point to your local copy of kibble-ui
+# "@televet/kibble-ui": "./../kibble-ui"
+
+cd ~/clinic-web                             # go into a project directory
+npm install                                 # fresh install without kibble ui
+
+# To see what links you've created globally you can run the following command
+npm list -g
+
+# To see what links an individual project is currently using run the following command from within that projects root folder
+npm list -link
+```
+
+#### Unlinking Projects after Local Development is Complete
+
+```
+# remove link to local files
+npm install --save @televet/kibble-ui   # re-install published project
+```
+
+#### `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
+
+Template has [Storybook](https://storybook.js.org/) configuration to handle documentation and examples.
+
+```bash
+npm run start # starts Storybook in development mode, http://localhost:6006/
+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 [one of these commands](https://docs.npmjs.com/updating-your-published-package-version-number).
+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
+yarn lint:js # runs eslint in src directory
+yarn fix:js # runs eslint in src directory with --fix parameter
+```
+
+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
+yarn lint:style # runs stylelint in src directory
+yarn fix:style # runs stylelint in src directory with --fix parameter
+```
+
+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:
+
+```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.
+
+## Style options
+
+### CSS modules
+
+Template uses vanilla CSS with `autoprefixer` enabled. To avoid classname collisions and reduce nesting we are using `css-modules`. To make css-modules work, stylesheet file name should have `.module` suffix.
+
+```jsx
+import React from 'react';
+import classes from './Component.module.css';
+
+const Component = () => <div className={classes.wrapper}>Component</div>;
+```
+
+### Add SASS/SCSS
+
+SASS/SCSS support comes "out of the box" in CRA. To enable it:
+
+1. Install `node-sass`
+
+   ```shell script
+   yarn add node-sass gatsby-plugin-sass --dev
+   ```
+
+2. Change `.lintstagedrc` to lint `scss` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.scss": ["stylelint --fix"]
+   }
+   ```
+
+3. Change `rollup.config.js` to support `scss` files:
+
+```js
+postcss({
+  extract: process.env.REACT_APP_PKG_STYLE || pkg.style,
+  inline: false,
+  plugins: postcssPlugins,
+  extensions: ['scss'], // <=== here
+}),
+```
+
+4. Add scss support to Docz. Create `gatsby-config.js` in the root of project.
+
+```js
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-sass`,
+      options: {
+        // Override the file regex for SASS
+        sassRuleTest: /\.s(a|c)ss$/,
+        // Override the file regex for CSS modules
+        sassRuleModulesTest: /\.module\.s(a|c)ss$/,
+      },
+    },
+  ],
+};
+```
+
+5. Import `scss` files straight into Component.
+
+   ```jsx
+   import React from 'react';
+   import classes from './Component.module.scss'; // note the changed extension
+
+   const Component = () => <div className={classes.wrapper}>Component</div>;
+   ```
+
+You can see all changes required to enable SASS/SCSS in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/11).
+
+### Add PostCSS
+
+1. Install `postcss-cli` and related plugins:
+   ```shell script
+   yarn add --dev postcss-nested postcss-cli postcss-preset-env npm-run-all
+   ```
+2. Modify package scripts:
+
+   ```json
+   {
+     "build:style": "postcss src/**/*.pcss --dir src --base src --ext css",
+     "watch:style": "yarn build:style -w",
+     "start": "npm-run-all -p watch:style start:js",
+     "start:js": "react-scripts start",
+     "build:js": "react-scripts build",
+     "build": "npm-run-all build:style build:js"
+   }
+   ```
+
+3. Add postcss support to Docz. Create `gatsby-config.js` in the root of project.
+
+   ```js
+   // gatsby-config.js
+   module.exports = {
+     plugins: [`gatsby-plugin-postcss`],
+   };
+   ```
+
+4. Add `postcss.config.js` file in the root folder. With following configuration:
+
+   ```js
+   const pkg = require('./package.json');
+
+   module.exports = {
+     plugins: [
+       require('postcss-nested'), // handle nested selectors, like LESS or SASS
+       require('postcss-preset-env')({
+         browsers: pkg.browserslist.production, // use browsers list from production mode
+         stage: 1,
+       }),
+     ],
+   };
+   ```
+
+5. Add rule to `.gitignore` and `.stylelintrc` to ignore all css files, since we are generating them.
+
+   #### .gitignore
+
+   ```gitignore
+   # css
+   *.css
+   ```
+
+   #### .stylelintrc
+
+   ```json
+   {
+     "ignoreFiles": ["**/*.snap", "**/*.css"]
+   }
+   ```
+
+6. Change `.lintstagedrc` to lint `pcss` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.pcss": ["stylelint --fix"]
+   }
+   ```
+
+You can see all changes required to enable PostCSS in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/12).
+
+### Add Less
+
+1. Install `less` and related plugins:
+   ```shell script
+   yarn add --dev less less-watch-compiler gatsby-plugin-less npm-run-all
+   ```
+2. Modify package scripts:
+
+   ```json
+   {
+     "build:style": "yarn watch:style --run-once",
+     "watch:style": "less-watch-compiler src src",
+     "start": "npm-run-all -p watch:style start:js",
+     "start:js": "react-scripts start",
+     "build:js": "react-scripts build",
+     "build": "npm-run-all build:style build:js"
+   }
+   ```
+
+3. Add less support to Docz. Create `gatsby-config.js` in the root of project.
+
+   ```js
+   // gatsby-config.js
+   module.exports = {
+     plugins: [`gatsby-plugin-less`],
+   };
+   ```
+
+4. Add rule to `.gitignore` and `.stylelintrc` to ignore all css files, since we are generating them.
+
+   #### .gitignore
+
+   ```gitignore
+   # css
+   *.css
+   ```
+
+   #### .stylelintrc
+
+   ```json
+   {
+     "ignoreFiles": ["**/*.snap", "**/*.css"]
+   }
+   ```
+
+5. Change `.lintstagedrc` to lint `less` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.less": ["stylelint --fix"]
+   }
+   ```
+
+You can see all changes required to enable Less in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/10).
+
+## 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"
+```
+
+## Technologies Used
+
+- [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/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/index.d.ts

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