@bloomreach/react-banana-ui 1.32.1 → 1.33.0

package/README.md

@@ -1,12 +1,56 @@
 # 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.
+A TypeScript React component library of primitive and common UI components used across Bloomreach apps.
+
+## Table of Contents
+
+- [Viewing Available Components](#viewing-available-components)
+- [Guide from Figma Design to the React Banana UI Components](#guide-from-figma-design-to-the-react-banana-ui-components)
+- [Using library in a project](#using-library-in-a-project)
+  - [Components](#components)
+  - [Styles & Fonts](#styles--fonts)
+  - [IMPORTANT](#important)
+- [Development](#development)
+  - [Prerequisites](#prerequisites)
+  - [Getting Started](#getting-started)
+  - [Build](#build)
+  - [Docker Services](#docker-services)
+- [Branching types](#branching-types)
+- [Commit Message Format](#commit-message-format)
+  - [The commit contains the following structural elements:](#the-commit-contains-the-following-structural-elements)
+  - [Commit Message Header](#commit-message-header)
+    - [Type](#type)
+    - [Scope](#scope)
+    - [Summary](#summary)
+  - [Commit Message Body](#commit-message-body)
+  - [Commit Message Footer](#commit-message-footer)
+  - [Revert commits](#revert-commits)
+- [Creating a new component](#creating-a-new-component)
+- [Storybook](#storybook)
+- [Autogen](#autogen)
+  - [Icons](#icons)
+- [Testing](#testing)
+  - [Unit tests](#unit-tests)
+  - [End-to-end tests](#end-to-end-tests)
+    - [Run e2e tests](#run-e2e-tests)
+    - [Update failed visual regression tests](#update-failed-visual-regression-tests)
+    - [The e2e tests configuration for CI and local development](#the-e2e-tests-configuration-for-ci-and-local-development)
+    - [Configuration Synchronization](#configuration-synchronization)
+- [Releasing](#releasing)
+  - [GitLab Pipeline](#gitlab-pipeline)
+- [Contributing Guidelines](#contributing-guidelines)
+- [Code Quality Standards](#code-quality-standards)
+  - [Linting & Formatting](#linting--formatting)
+  - [Git Hooks (Husky)](#git-hooks-husky)
+  - [Security Best Practices](#security-best-practices)
+  - [Performance Guidelines](#performance-guidelines)
+  - [CSS Performance](#css-performance)
+  - [Performance Budgets](#performance-budgets)
+  - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
 
 ## Viewing Available Components
 
-Visit the library [storybook](https://design.corp.bloomreach.com/storybooks/react-banana-ui/master/) to view the latest available components.
+Visit the library [Storybook](https://design.corp.bloomreach.com/storybooks/react-banana-ui/master/) to view the latest available components.
 
 ## Guide from Figma Design to the React Banana UI Components
 
@@ -20,60 +64,111 @@ Install the library as a dependency in the project
 npm i --save --save-exact @bloomreach/react-banana-ui
 ```
 
+This package requires React 17/18 as peer dependencies:
+
+- react (peer)
+- react-dom (peer)
+- @types/react (optional peer in TS projects)
+
 ### Components
 
-In case project settings are properly established, use the components in the application like so
+To use components in your application, import them as named exports:
 
-```javascript
-import { <ComponentName> } from "@bloomreach/react-banana-ui";
+```tsx
+import { Button } from '@bloomreach/react-banana-ui';
+
+function MyComponent() {
+  return <Button onClick={() => console.log('Button clicked!')}>Click Me</Button>;
+}
 ```
 
+Prefer named imports for effective tree shaking.
+
 ### Styles & Fonts
 
-Do the following steps to make styles and fonts available
+To make the library's styles and fonts available in your project, follow these steps:
 
-- Import the library styles in the main application style file as the following line
+1.  **Import the main stylesheet**: Add the following line to your main application's style file (e.g., `main.scss` or `index.css`):
 
-  ```css
-  // main.scss
+    ```css
+    /* main.scss */
 
-  @import '@bloomreach/react-banana-ui/style.css';
+    @import '@bloomreach/react-banana-ui/style.css';
 
-  ...
-  ```
+    /* ... other styles ... */
+    ```
 
-- The font family for your `html` and `body` tags are already specified in the library styles
+2.  **Font Family**: The `html` and `body` tags' font families are already defined within the library's styles, ensuring consistent typography across your application without additional configuration.
 
 ### IMPORTANT
 
-Please, avoid using `--rbui-...` and/or `--banana-...` CSS custom properties directly in the application styles
-as they are intended to be used inside the library only.
-Stick to use library components to bring the styles into the application.
+**Avoid directly using `--rbui-...` and/or `--banana-...` CSS custom properties in your application styles.** These variables are intended for internal library use only. Always use the library components to ensure proper styling and adherence to the design system.
 
 ## Development
 
+This section outlines the necessary steps and commands for developing with the React Banana UI library.
+
 ### Prerequisites
 
-- Node.js (latest LTS)
-- NPM (latest, compatible with Node.js)
+Ensure you have the following installed:
+
+- **Node.js**: >=18
+- **NPM**: >=9
+
+### Getting Started
+
+1.  **Install Dependencies**: Run the following command to install all project dependencies:
+
+    ```sh
+    npm ci
+    ```
+
+    This command performs a clean installation of dependencies, ensuring consistency across environments.
+
+2.  **Run Storybook**: Start the Storybook development server (alias of `npm run storybook`) to view and develop components in isolation:
+
+    ```sh
+    npm run start
+    ```
+
+    Storybook will open at http://localhost:6006, and any changes saved in the source code will automatically reflect in the Storybook UI.
 
-Install all dependencies
+3.  **Generate New Components**: To create a new component with the standard file structure, use the component generation script:
+
+    ```sh
+    npm run generate
+    ```
+
+    Follow the prompts to set up your new component. More details can be found in the [Creating a new component](#creating-a-new-component) section.
+
+### Build
+
+To build the library for production, run the following command:
 
 ```sh
-npm ci
+npm run build
 ```
 
-Run the storybook
+This command compiles the TypeScript code, bundles the components, and generates the necessary output files for distribution. The built files will be located in the `dist/` directory.
+
+To build the Storybook for deployment, run the following command:
 
 ```sh
-npm run start
+npm run storybook:build
 ```
 
-After that, any changes in the source code will automatically be reflected in the storybook.
+This command compiles the Storybook stories and generates a static Storybook build, which can be deployed to a web server. The output will be in the `storybook-static/` directory.
+
+### Docker Services
+
+We use Docker Compose to manage various services required for local development and testing. The `docker-compose.yml` file defines these services.
+
+- **Playwright E2E Testing**: The `e2e` service in `docker-compose.yml` sets up a Playwright test environment within a Docker container, ensuring consistent end-to-end test execution across different environments. You can run these tests using `npm run e2e`.
+- **SonarQube Analysis**: The `sonar` service provides a local SonarQube instance for static code analysis. This helps in identifying code quality and security vulnerabilities early in the development cycle. You can start this service and perform analysis using `npm run sonar` (after configuring SonarQube locally). Ensure the `SONAR_TOKEN` environment variable is set.
 
 ## 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.
+To manage and automate complex release workflow based on multiple Git branches and distribution channels, we utilize the `semantic-release` library. Refer to the [documentation](https://semantic-release.gitbook.io/semantic-release/) for comprehensive details. Our current setup is streamlined but designed for future extensibility.
 
 The current branch types are explained below.
 
@@ -84,8 +179,8 @@ The current branch types are explained below.
 
 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`;
+- Add a new release/maintenance/pre-release branch to the `semantic-release` configuration in `./release.config.cjs`, 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).
@@ -232,41 +327,67 @@ The old components stories are located in the `./stories` folder. They are going
 
 ### 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
+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.
+
+Note: running the generator deletes and recreates `src/components/foundations/icon/icons/`.
 
 ## 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.
+Comprehensive testing is crucial for maintaining the quality and stability of the React Banana UI library. We employ a two-level testing strategy: unit tests for isolated logic and end-to-end (E2E) tests for overall component behavior in a real browser environment, including visual regression. Each new or modified component is expected to have thorough test coverage.
 
 ### 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.
+We use the [Vitest](https://vitest.dev/) framework for unit testing. Unit test files should end with `*.spec.ts(x)` and be co-located with the component or module being tested. When writing unit tests:
+
+- **Focus on isolated logic**: Test individual functions, components, or modules in isolation, mocking dependencies as needed.
+- **Cover edge cases**: Ensure your tests cover boundary conditions, invalid inputs, and error states.
+- **Assert component behavior**: Verify that components render correctly, respond to user interactions, and manage their state as expected.
+
+Common unit test commands:
+
+```sh
+npm test
+npm run test:watch
+npm run test:ui
+npm run test:coverage
+```
 
 ### 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.
+We utilize the [Playwright](https://playwright.dev/) framework for end-to-end testing. These tests are co-located with their respective components (files ending with `*.test.ts(x)`) and run against dedicated Storybook stories (`*.qa.stories.ts(x)`). The primary goal of E2E tests is to eliminate manual QA efforts and ensure high-quality components for end-users. Key aspects of our E2E testing strategy include:
 
-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.
+- **Comprehensive Scenarios**: Each component should be covered with E2E tests that simulate various user interactions, component states, and different scenarios.
+- **Visual Regression Testing**: This is a critical part of our E2E suite, ensuring that visual changes are intentional and do not introduce unexpected regressions. When visual failures occur and are deemed correct, update the snapshots using `npm run e2e:update`.
+- **Balancing Coverage and Performance**: While extensive coverage is vital, E2E tests can be slow. Strive for a balance between comprehensive test scenarios and efficient test execution. Prioritize the quality of components, and always consider performance optimizations for CI.
 
 #### 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`
+- For a local run without Docker, use `npm run e2e:internal` (builds Storybook then runs Playwright).
 
 #### 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
+- 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.
+- **Important**: Playwright snapshots should always be generated within the Docker environment (`npm run e2e:update` will use Docker by default). This ensures consistency with the Linux environment used in the GitLab pipeline, preventing discrepancies caused by operating system-specific rendering differences.
 
 ### 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.
+E2E tests are executed in a Docker container, both locally and in CI, leveraging the official Playwright Docker image. This approach ensures a consistent and predictable testing environment across all development and integration stages. The CI setup mirrors the local `docker-compose.yml` configuration.
+
+#### Configuration Synchronization
+
+It is crucial to **keep the CI setup for the `e2e tests` job (defined in `.gitlab-ci.yml`) synchronized with the local Docker Compose configuration (`docker-compose.yml`)**. Any changes made to one should be carefully applied to the other to maintain environment consistency and avoid unexpected test failures.
+
+## Contributing Guidelines
 
-#### IMPORTANT
+We welcome contributions to the React Banana UI library! To ensure a smooth and collaborative development process, please adhere to the following guidelines:
 
-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.
+- **Commit Message Format**: All commit messages must follow the [Conventional Commits specification](#commit-message-format). This helps automate releases and generate accurate changelogs. Please review the [Commit Message Format](#commit-message-format) section for detailed instructions.
+- **Testing**: Before submitting any changes, ensure your code is thoroughly tested. This includes both [Unit Tests](#unit-tests) for isolated logic and [End-to-end Tests](#end-to-end-tests) for comprehensive component behavior and visual regression. Refer to the [Testing](#testing) section for detailed guidance on writing and running tests.
+- **Code Quality**: Maintain high code quality by adhering to the project's linting, formatting, and security best practices. (Refer to the `always_applied_workspace_rules` in the documentation for more details.)
+- **Development Workflow**: Follow the established [Development](#development) workflow for installing dependencies, running Storybook, and generating new components.
+- **Branching**: Understand and follow our [Branching types](#branching-types) for feature development, bug fixes, and releases.
 
 ## Releasing
 
@@ -278,16 +399,74 @@ To preview the possible release version and release notes based on already exist
 npm run release:dry-run
 ```
 
-The Gitlab pipeline runs all the checks and if the library is in good order:
+See `MIGRATION.md` for migration guidance and `RELEASE_NOTES.md` for detailed changes between versions.
+
+### GitLab Pipeline
+
+The GitLab pipeline automates the build, test, and deployment processes for the React Banana UI library. It consists of several stages, each designed to ensure code quality, functionality, and proper release management.
+
+- **Build Stage**: This stage is responsible for compiling the TypeScript code, bundling the components, and generating the necessary output files for distribution. It also builds the Storybook for deployment.
+- **Test Stage**: In this stage, unit tests and end-to-end (E2E) tests are executed to ensure the functionality and visual integrity of the components.
+- **Lint Stage**: This stage performs linting and formatting checks on the codebase to enforce code quality standards.
+- **Type Check Stage**: TypeScript type checking is performed in this stage to catch any type-related issues.
+- **Deploy Stage**: This final stage is responsible for publishing the new version of the library to npm and updating the release notes, provided all previous stages pass successfully.
+
+The GitLab pipeline runs all the checks and if the library is in good order, the following automated steps occur:
+
+1.  The [release notes](./RELEASE_NOTES.md) will be updated according to commit messages history;
+2.  The library version will be bumped;
+3.  A new commit will be created with the updated version and release notes;
+4.  A new Git tag will be created in the repository;
+5.  The new version of the library will be published to npm;
+
+After these automated steps, a few manual actions are required:
+
+1.  Announce the new release in the slack channel [#react-banana-ui-component-library](https://bloomreach.slack.com/archives/C05E4672ZLZ) :tada:;
+2.  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;
+3.  Take a break and then pick up the next challenge :muscle:!
+
+## Code Quality Standards
+
+This section outlines the code quality standards enforced in the React Banana UI library, covering linting, formatting, security, and performance. Adhering to these standards ensures maintainable, secure, and performant code.
+
+### Linting & Formatting
+
+- **ESLint Configuration**: We use a comprehensive ESLint configuration to enforce code quality and consistency. Refer to the `eslint.config.js` file for detailed rules.
+- **Import Organization**: Maintain a structured import order for readability and consistency. Generally, external libraries come first, followed by internal utilities, components, types, and finally, styles.
+- **Prettier Settings**: Our codebase adheres to a strict Prettier formatting configuration. Ensure your code is formatted using the provided scripts (`npm run format` / `npm run format:check`).
+- **Quality Scripts**: Utilize `npm run lint` (`npm run lint:fix` for auto-fixing), `npm run format` (`npm run format:check` for checking), and `npm run check:types` for type validation.
+
+### Git Hooks (Husky)
+
+We utilize [Husky](https://typicode.github.io/husky/#/) to manage Git hooks, ensuring that certain scripts are run automatically before commits or pushes. This helps maintain code quality and consistency across the repository.
+
+- **Pre-commit hook**: Runs `npm run lint` and `npm run format` to check for linting errors and enforce code formatting before a commit is created. This ensures that only properly formatted and linted code is committed to the repository.
+- **Pre-push hook**: Runs `npm run check:types` to perform TypeScript type checking before code is pushed to the remote repository. This helps catch type-related issues early in the development cycle.
+
+### Security Best Practices
+
+- **Input Validation**: Use specific types (avoid `any`), union types for variants (e.g., `primary | secondary`), and avoid `dangerouslySetInnerHTML`. Sanitize `className` inputs to allow only trusted class combinations.
+- **Event Handler Security**: Prevent default actions when components are loading or disabled. Safely call optional callbacks using optional chaining (e.g., `onClick?.(event)`).
+- **XSS Prevention**: Avoid `dangerouslySetInnerHTML`, leverage React's built-in escaping, validate SVG props, and use trusted sources for assets.
+- **Dependency Security**: Regularly run `npm run security-audit`, adhere to specified Node.js and npm version requirements, control React peer dependencies, and commit `package-lock.json`.
+
+### Performance Guidelines
+
+- **Component Optimization**: Memoize expensive components (`memo`) and calculations (`useMemo`), and useCallback for event handlers to prevent unnecessary re-renders.
+- **Bundle Optimization**: Prefer named imports (e.g., `import { Button } from ...`) for effective tree shaking and modular utility imports.
+- **Efficient Patterns**: Memoize class computations with `useMemo`, avoid inline object creation for styles, and use controlled value hooks.
+- **Memory Management**: Implement cleanup functions in `useEffect` for subscriptions and event listeners to prevent memory leaks.
+
+### CSS Performance
+
+- **Efficient Selectors**: Favor single-class selectors (e.g., `.rbui-button--primary`) over complex, nested selectors. Use design tokens (e.g., `var(--banana-text-primary)`) and avoid deep nesting (max 3 levels).
+
+### Performance Budgets
 
-- 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;
+- **Bundle size**: Aim for minimal bundle sizes, typically <50KB per component and <100KB for core components.
+- **Build Optimization**: Externalize peer dependencies to reduce bundle size.
+- **Asset Optimization**: Optimize SVG assets for efficient loading.
 
-Only a few manual steps should be done after all:
+### Common Pitfalls to Avoid
 
-- 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:!
+Avoid inline arrow functions for `onClick`, inline style objects, and unmemoized expensive calculations.