@up42/up-components 0.0.21 → 0.1.2

package/README.md

@@ -1,2 +1,152 @@
-[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)
+
+## 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/
+
+You can also import components from the `@mui/material` directly from the package, instead of using `@mui`:
+
+```diff
+- import { Accordion } from '@mui/material';
++ import { Accordion } from '@up42/up-components'
+```
+
+**Note:** UP Components currently exports all [MUI components](https://mui.com/components/) on top of our custom ones. Which means that the existing MUI documentation can be used for any component not yet documented on our own [Storybook](https://up-components.up42.dev/). In case of conflicts, our custom documentation prevails over MUI.
+
+## 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.
+
+Import paths to internal modules always have to be relative:
+
+```diff
+- import { MyUtil } from 'global/utils'
++ import { MyUtil } from '../../global/utils'
+```
+
+### 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.
+
+### Design System Tokens 
+[UP42 tokens](https://github.com/up42/design-system-tokens) are also exposed as part of UpComponents.
+
+
+```diff
+- import tokens from '@up42/constellation-tokens/dist/json/tokens.json'
++ import { tokens } from "@up42/up-components"
+```
+
+## Publishing new versions
+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.
+
+### How should I write my commits?
+We follow the [Conventional Commit](https://www.conventionalcommits.org) specification. The most important prefixes you should have in mind are:
+
+- `fix`: which represents bug fixes, and correlates to a SemVer `PATCH`.
+- `feat`: which represents a new feature, and correlates to a SemVer `MINOR`.
+- `feat|fix!`: which represent a breaking change (indicated by the `!`) and will result in a SemVer `MAJOR`.
+
+Other prefixes like `chore:`, `refactor:`, `test:`, etc. can be used, but won't be included in the `CHANGELOG.md` file.
+
+### Usage
+
+```bash
+$ npm run release
+```
+
+This command is going to:
+- bump the version in `package.json` and `package-lock.json`.
+- output changes to `CHANGELOG.md`.
+- commit `package-lock.json` and `package.json` and `CHANGELOG.md`.
+
+We use [Standard Version](https://github.com/conventional-changelog/standard-version) for the automated releasing PR commit.