@up42/up-components 0.0.2 → 0.0.3

package/README.md

@@ -1,2 +1,107 @@
-[WIP]
-# UP Components
+# UP Components
+
+UP42's Shared Component Library. This is a cross-team collaborative package that enables us to reuse React components across different projects. The package uses [Storybook](https://storybook.js.org/docs/react/get-started/introduction) to organize and document UI components, and is based on [MUI](https://mui.com/getting-started/usage/) for theming and most of the APIs.
+
+Up Components library provides react components based on [UP42's design system](https://www.figma.com/file/Qd9QmAdQfcsWe3xSKtJWX9FZ/Design-System?node-id=12565%3A3972)
+
+# Getting Started
+
+```bash
+$ npm install @up42/up-components
+```
+
+or
+
+```bash
+$ yarn add @up42/up-components
+```
+
+## Using the up-components in your application
+
+Make sure to wrap your application with the top-level `UpComponentsProvider`.
+
+```tsx
+import { UpComponentsProvider, Button } from '@up42/up-components'
+
+const App = () => (
+  <UpComponentsProvider>
+    <Button>Hello!</Button>
+  </UpComponentsProvider>
+)
+```
+
+## Available Components
+
+To see a list of available components, you can go through Storybook's Component Documentation UI, either at the following links:
+
+- Master version at https://up-components.up42.dev/
+- Preview branch at https://up-components--{branch-name}.branch-preview.up42.dev/
+
+# Developing in the up-components package
+
+This package uses [Rollup](https://github.com/rollup/rollup) for building `esm` and `cjs` modules.
+[npm](https://www.npmjs.com/) version 7 or higher is required install and build the components locally. Yarn is not supported for development as it currently does not properly handle peer dependencies.
+
+## Developing locally
+
+Clone the repository and run.
+
+```bash
+$ npm run storybook
+```
+
+### Adding new components
+
+Components must be added to the `src/components` folder using the following structure:
+
+```
+src
+│ index.ts // export { MyComponent } from 'components'
+└─components
+  │ index.ts // export { MyComponent } from './MyComponent/MyComponent
+  └─MyComponent
+    │ MyComponent.tsx // export const MyComponent
+    │ MyComponent.test.tsx
+    │ MyComponent.overrides.ts
+    │ MyComponent.stories.tsx
+```
+
+- `MyComponent.tsx`: main component structure/logic.
+- `MyComponent.test.tsx`: unit tests for the component.
+- `MyComponent.overrides.ts`: any theme overrides for that component (optional).
+- `MyComponent.stories.tsx`: Storybook documentation.
+
+Components and filenames must use the `UpperCamelCase` pattern. For components that already exist on MUI, using the exact same name is preferred so that they override the MUI export.
+
+### Testing @up42/up-components locally
+
+In order to test the components without publishing a new version, you can use [Yalc](https://github.com/wclr/yalc) to publish the package locally and install it on your app.
+
+Install Yalc in your machine by running:
+
+```bash
+$ yarn global add yalc
+```
+
+Inside `up-components` folder, run
+
+```
+$ yalc publish
+```
+
+In your application, run
+
+```
+$ yalc add @up42/up-components
+```
+
+This should install the local version of `@up42/up-components` in your application so you can test new components before publishing a new version.
+
+## Publishing new versions
+
+A new version is published whenever the version in `package.json` is updated.
+We are using [Semantic Versioning](https://semver.org/) for controlling each release.
+
+- MAJOR version when you make incompatible API changes,
+- MINOR version when you add functionality in a backwards compatible manner, and
+- PATCH version when you make backwards compatible bug fixes.