# Camunda Composite Components

Camunda Composite Components (also known as **C3**) is the main software
artifact of the
[Design System Team](https://confluence.camunda.com/display/HAN/Design+System).

We have a dedicated slack channel for everyone having questions, comments, bug
reports or concerns about this repository:
[#camunda-composite-components](https://app.slack.com/client/T0PM0P1SA/C049YH1C202/thread/C03NF7FH17G-1671730364.608129).
For more general questions towards the Design System team, please use
[#ask-cds](https://app.slack.com/client/T0PM0P1SA/C04FUEGLG8N).

If you like the idea of having a repository for your own composite components -
how about you do your own **Camunda Custom Composite Components**? Just go over
[here](https://github.com/camunda-cloud/c4-starter), fork it, lezgo! A list of
C4-Adopters can be found <a href="#c4list">here</a>.

## Storybook

A live view of the `main` branch can be found
[here](https://camunda-composite-components.pages.dev/). When opening a PR, a
version of storybook with the changes is deployed automatically and can be
accessed by clicking on the link in the PR.

## Dev

```bash
# install
yarn

# start storybook
yarn storybook

# build components
yarn build
```

## Release

Simply run our
[release workflow](https://github.com/camunda-cloud/camunda-composite-components/actions/workflows/release.yml)
in the GitHub Actions tab. This will create a new release, publish the package
to npm and update the changelog automatically.

Pushing to `main` will update the storybook available under
[cloudflare page](https://camunda-composite-components.pages.dev/).

## Usage

Example for navbar:

```tsx
import { C3NavigationElementProps } from "@camunda/camunda-composite-components"

// ...

return (
	<C3Navigation
		app={{
			ariaLabel: "Camunda Console",
			name: "Console",
			prefix: "Camunda",
			routeProps: { route: routes.home, router: router },
		}}
		// ...
	/>
)
```

## <a name="c4list"></a> (incomplete) List of adopters of C3+C4

- [Console team](https://confluence.camunda.com/display/HAN/Console+Team)
  started this, their C4 repo can be found
  [here](https://github.com/camunda-cloud/camunda-cloud-management-apps/tree/main/packages/c4)
- [Identity team](https://github.com/camunda/team-identity):
  [c4-identity](https://github.com/camunda-cloud/c4-identity)

## Testing

### Visual regression tests (VRT)

We use [Playwright](https://playwright.dev/docs/intro) screenshot tests to be
aware of any visual changes introduced by dependency updates or changes in the
component code.

#### Running VRT locally

We run VRT inside a docker container to avoid different results caused by
different platforms. Simply run:

```shell
yarn start:docker-storybook
```

then

```shell
yarn test:visual-regression:docker
```

The commands above will:

1. Build storybook.
2. Start a Playwright docker container with the name `c3-visual-regression`.
3. Serve storybook within the docker container.
4. Run the visual regression tests within the docker container.

When developing, it might not always be helpful to run all of these steps at
once. You can find more granular scripts in the [package.json](package.json).

#### Running VRT in the CI

There is a `Visual regression tests` workflow that is triggered automatically on
push. You can also trigger it manually in the `Actions` tab.

If the workflow fails, you can find the test report by navigating to the
workflow run summary, then scrolling down to the `Artifacts` section. Click on
the artifact called `Playwright report` to download it, go to your downloads
folder, then open the `index.html` file of the test report in your browser to
view the report.

#### How to deal with failing tests

When a VRT fails, this can have two reasons:

1. A change was introduced unknowingly. In this case, have a look at the test
   report and check if the change was intended. If it is, proceed with 2.
2. You made a change to the UI on purpose. In this case you need to update the
   screenshot as follows.

Make sure you have the `c3-visual-regression` docker container running, or start
it like described [here](#running-vrt-locally). Then, have a look at the test
report:

```shell
yarn report:visual-regression
```

Double-check that you don't apply any unwanted changes by looking at the
difference that is highlighted in the failed test's report.

To update all screenshots, run:

```shell
yarn update:visual-regression:docker
```

The tests should now pass locally and in the CI. Commit and push the updated
screenshot(s).
