@bloomreach/react-banana-ui 1.1.0-next.1

package/README.md

@@ -0,0 +1,310 @@
+# React Banana UI
+
+This is a component library of all basic and common components across all
+bloomreach project apps. This will be primarily primitive components and
+possibly some specialized items as well.
+
+
+## Viewing Available Components
+
+Visit the library [storybook](https://design.corp.bloomreach.com/storybooks/react-banana-ui/master/) to view the latest available components.
+
+
+## Using library in a project
+
+Install the following libraries to the project dependencies
+
+```sh
+npm i --save --save-exact @bloomreach/react-banana-ui @bloomreach/banana-theme
+```
+
+**Note:**
+
+The library `@bloomreach/banana-theme` is required only to bring fonts used by default in the global design system which is going to be used across all Bloomreach applications.
+Using it as a separate dependency in the end application is a temporary solution and will be changed in the near future by hiding inside `@bloomreach/react-banana-ui` library.
+
+### Components
+
+In case project settings are properly established, use the components in the application like so
+
+```javascript
+import { <ComponentName> } from "@bloomreach/react-banana-ui";
+```
+
+### Styles & Fonts
+
+Do the following steps to make styles and fonts available
+
+* Import the library styles along with fonts by adding the following lines in the main application style file
+
+  ```css
+  // main.scss
+
+  @import '@bloomreach/banana-theme/css/fonts.css';
+  @import '@bloomreach/react-banana-ui/style.css';
+
+  ...
+  ```
+* Additionally, set the `font-family` property to the root element using CSS custom properties available from the library
+
+  ```css
+  // main.scss
+
+  ...
+
+  html, body {
+    font-family: var(--broccoli-font-family-primary);
+  }
+
+  ...
+  ```
+
+The full list of available CSS custom properties will be available soon. Now just use the browser dev tools to see all available CSS custom properties. Filter them with the `--broccoli-` prefix to reduce the amount.
+
+**ATTENTION:**
+
+Please, avoid using `--banana-...` CSS custom properties as they are intended to be used inside the library itself.
+
+
+## Development
+
+### Prerequisites
+- Node.js 18.X
+- NPM 9.x
+
+Install all dependencies
+```sh
+npm ci
+```
+
+Run the storybook
+
+```sh
+npm run start
+```
+
+After that, any changes in the source code will automatically be reflected in the storybook.
+
+## Branching types
+
+To manage and automate complex release workflow based on multiple Git branches and distribution channels used the `semantic-release` library. Check the [documentation](https://semantic-release.gitbook.io/semantic-release/) for more details. The current setup is reduced and simplified as much as possible, however, it is flexible and might be extended in the future if needed.
+
+The current branch types are explained below.
+
+* The `master` branch - is a permanent branch, where releases happen for the latest versions. All versions from that branch will be published to the npm registry with a `latest` dist-tag;
+* The `next` branch should be used when we want to develop an important feature, which is a breaking change. Considering the scope of this feature we want to make it available, at first, only to a limited amount of users in order to get feedback or run tests. Once we get that feedback we can make improvements and ultimately make the new feature available to all users by merging changes into the `master` branch; Releases from the `next` branch will be published to the npm registry with a `next` dist-tag;
+* The maintenance branches (i.e. `2.x` to maintain release `v2`). The maintenance branch is a type of branch that allows publishing releases with a [semantic version](https://semver.org/) on top of the codebase of an old release. This is useful when you need to provide fixes or features to users who cannot upgrade to the last version of the package;
+* Feature branches (like `feature/BR-XX-my-awesome-feature`, `fix/BR-XX-that-is-life`) or any other kind of branch to commit small units of work that do not produce releases (until merged into one of the branches above). These branches are ignored from now on as they don’t have to trigger releases;
+
+
+The following changes should be done to change or extend the current setup:
+
+* Add a new release/maintenance/pre-release branch to the `semantic-release` configuration in `./.releaserc`, check the [documentation](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches) for more details;
+* Update the Gitlab pipeline `release` job to allow running it with the new branch, check `./.gitlab-ci.yml`;
+* Verify that the new branch is marked as `protected` in the repository settings.
+
+Find more examples of possible release workflows in the official `semantic-release` [documentation](https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow).
+
+## Commit Message Format
+
+To have an automated release process the git commit messages must follow the following format.
+This specification following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). It provides an easy set of rules for creating an explicit commit history. This convention dovetails with [semantic version](http://semver.org/), by describing the features, fixes, and breaking changes made in commit messages.
+
+Each commit message consists of a **header**, a **body**, and a **footer**.
+
+```
+<header>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The `header` is mandatory and must conform to the [Commit Message Header](#commit-message-header) format.
+
+The `body` is optional. When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-message-body) format.
+
+The `footer` is optional. The [Commit Message Footer](#commit-message-footer) format describes what the footer is used for and the structure it must have.
+
+### The commit contains the following structural elements:
+
+* `fix`: a commit of the type fix patches a bug in your codebase (this correlates with `PATCH` in Semantic Versioning).
+* `feat`: a commit of the type feat introduces a new feature to the codebase (this correlates with `MINOR` in Semantic Versioning).
+* `BREAKING CHANGE`: a commit that has a footer BREAKING CHANGE:, or appends a `!` after the `type/scope`, introduces a breaking API change (correlating with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
+* types other than `fix`: and `feat`: are allowed, see [types](#type).
+* footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.
+
+Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a **BREAKING CHANGE**).
+
+### Commit Message Header
+
+```
+<type>(<scope>): <short summary>
+  │       │             │
+  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
+  │       │
+  │       └─⫸ Commit Scope: Right now not used but will be expanded in the near future.
+  │
+  └─⫸ Commit Type: build|chore|ci|docs|feat|feature|fix|perf|refactor|style|test.
+```
+
+The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional and not used now.
+
+#### Type
+
+Must be one of the following:
+
+* `build` - changes that affect the build system or external dependencies; Hidden from the release notes;
+* `chore` - changes which are not fit to the rest of the types. Hidden from the release notes;
+* `ci` - changes to our CI configuration files and scripts. Hidden from the release notes;
+* `docs` - documentation only changes. Hidden from the release notes;
+* `feat` - a new feature. Appeared in the release notes under section `Features`;
+* `feature` - the alias for the type`feat`;
+* `fix` - a bug fix. Appeared in the release notes under section `Bug Fixes`;
+* `perf` - a code change that improves performance. Appeared in the release notes under section `Performance Improvements`;
+* `refactor` - a code change that neither fixes a bug nor adds a feature. Hidden from the release notes;
+* `revert` - revert of the previous changes. Appeared in the release notes under section `Reverts`;
+* `style` - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc). Hidden from the release notes;
+* `test` - adding missing tests or correcting existing tests. Hidden from the release notes.
+
+If the prefix is `feat`, `fix`, `perf` or `revert`, it will appear in the release notes. However if there is any **BREAKING CHANGE**, the commit will always appear in the changelog.
+
+Other prefixes are up to your discretion. Suggested prefixes are `build`, `ci`, `docs` ,`style`, `refactor`, `style`, `test` and `chore` for non-changelog related tasks.
+
+#### Scope
+
+Not used currently.
+
+#### Summary
+Use the summary field to provide a succinct description of the change:
+
+* use the imperative, present tense: "change" not "changed" nor "changes"
+* don't capitalize the first letter
+* no dot (.) at the end
+
+### Commit Message Body
+
+Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
+
+Explain the motivation for the change in the commit message body. This commit message should explain why you are making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
+
+### Commit Message Footer
+
+The footer can contain information about breaking changes and is also the place to reference Jira tickets, and other MRs that this commit closes or is related to.
+
+For example:
+
+```
+BREAKING CHANGE: <breaking change summary>
+<BLANK LINE>
+<breaking change description + migration instructions>
+<BLANK LINE>
+<BLANK LINE>
+<Closes|Fixes> BR-<issue number>
+```
+
+Breaking Change section should start with the phrase **BREAKING CHANGE:** followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
+
+Similarly, a Deprecation section should start with **DEPRECATED:** followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path.
+
+### Revert commits
+
+If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
+
+The content of the commit message body should contain:
+
+* information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
+* a clear description of the reason for reverting the commit message.
+
+
+## Creating a new component
+
+To create a new component, run the following command
+
+```sh
+npm run generate
+```
+
+and then follow the instructions to create the all required sets of files for the new component. It will create the following files:
+
+```
+component-name.tsx // Main component file
+component-name.scss // Component styles
+component-name.spec.tsx // Unit tests
+component-name.stories.tsx // Storybook stories
+component-name.qa.stories.tsx // E2E tests stories
+component-name.test.tsx // E2E tests
+```
+
+**Note**: The script doesn't create the `index.ts` file inside `./src/components/<group>` folder. It should be created manually or updated already existing `index.ts` file.
+
+
+## Storybook
+
+The [Storybook](https://design.corp.bloomreach.com/storybooks/react-banana-ui/master/) is used to develop and view components in isolation. The storybook files should end with `*.stories.tsx` and be placed close to the component or module which is going to be documented for all new or rewritten components. The `./stories` folder should locate only generic information about the library itself and additionally, complex stories involving multiple components.
+
+The old components stories are located in the `./stories` folder. They are going to be removed soon. In case the new implementation is ready but the old one is still available to prevent breaking changes, please, mark the old stories as **DEPRECATED** to group them, see for example: `./stories/components/buttons`.
+
+## Autogen
+
+### Icons
+
+The icon files and exports are auto-generated using the script at `scripts/gen-icons`. If new icons are added in the banana-theme project, run `npm run generate:icons` to regenerate the icon exports
+
+## Testing
+
+When adding changes for any component part of the library it is mandatory to have them covered by tests. These tests need to be meaningful and developed with extensive coverage in mind. By their nature components will be used in a wide variety of scenarios and so extensive coverage is crucial in order to avoid unpredictable results.
+The library is developed with a two-level testing approach in mind like unit tests and E2E tests. Each component should have unit tests and E2E tests. The unit tests should cover the component logic and the E2E tests should cover the component behavior in the real browser environment together with visual regression testing.
+
+### Unit tests
+
+The [Vitest](https://vitest.dev/) unit test framework is used for the unit testing. The unit test files should end with `*.spec.ts(x)` and place close to the component or module which is going to be tested.
+
+### End-to-end tests
+
+The [Playwright](https://playwright.dev/) test framework is used for end-to-end testing. All tests are located in the component or module folder and should end with `*.test.ts(x)`. The e2e tests run against special storybook stories which contain different scenarios for the test component.
+The stories for the e2e test should be located in the same place as tests and component stories and end with `*.qa.stories.ts(x)`. The title of test stories should contain `QA` at the end and look something like this: `<Component Group>/<Component Name>/QA`. The e2e stories should be used only for e2e tests and not for documentation purposes. The e2e stories should reuse the component stories metadata and base stories as much as possible but at the same time, they should give flexibility to test different scenarios.
+
+The purpose of using the e2e tests is to eliminate any manual QA work and provide high-quality components to the end-users. In that case, each component should be covered with e2e tests and visual regression tests and have comprehensive coverage based on the different scenarios and component states. The downside of this comprehensive approach is that the e2e tests are slow and take time to run and increasing the number of tests will increase the time to run them. So, please, be aware of that and try to find a balance between the number of tests and the time to run them but always keep in mind that **the quality of the components is the most important thing** and CI tome always might be improved, optimized etc.
+
+#### Run e2e tests
+
+- Use the command `npm run e2e` to start end-to-end tests inside the Docker container (the `docker` and `docker compose` should be installed on your machine).
+- When tests are done check the Playwright output in the console if some of the tests failed use the following command to open the Playwright report: `npm run e2e:report`
+
+#### Update failed visual regression tests
+
+- If the failure appeared in the visual regression tests and those changes are correct, please update the existing reference images with the following command: `npm run e2e:update`. The Playwright will generate new correct reference images which should be committed to the repository
+
+### The e2e tests configuration for CI and local development
+
+All e2e tests run locally in Docker container based on the official image, see Playwright [documentation](https://playwright.dev/docs/docker) for more details. Tests run inside the Docker container to keep a predictable environment for each developers and CI.
+CI setup its own job based on the same Docker image and almost repeat the same commands as it done in `docker-compose.yml` file.
+
+#### IMPORTANT
+
+Please, be aware that in case of any changes in the CI setup for the `e2e tests` job, see `.gitlab-ci.yml` they should be applied to the local setup in the `docker-compose.yml` and vice-versa.
+
+## Releasing
+
+The release of the new version is going to be done automatically when the changes reach one of the [release branches](#branching-types) and commit messages contain one of the [structural elements](#the-commit-contains-the-following-structural-elements).
+
+To preview the possible release version and release notes based on already existing commits run the following command
+
+```sh
+npm run release:dry-run
+```
+
+The Gitlab pipeline runs all the checks and if the library is in good order:
+
+* The [release notes](./RELEASE_NOTES.md) will be updated according commit messages history;
+* The library version will be bumped;
+* The new commit will be created with a version and changed release notes;
+* The new git tag will be created in the repository;
+* The new version of the library will be published to npm;
+
+Only a few manual steps should be done after all:
+
+* Announce in the slack channel [#react-banana-ui-component-library](https://bloomreach.slack.com/archives/C05E4672ZLZ) about new release :tada:;
+* Mark the new version as `released` in the [releases section in Jira](https://bloomreach.atlassian.net/projects/BU?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page) once the ticket is merged and closed;
+* Take a break and then pick up the next challenge :muscle:!