@camunda/camunda-composite-components

Camunda Composite Components

Camunda Composite Components (also known as C3) is the main software artifact of the Design System Team.

We have a dedicated slack channel for everyone having questions, comments, bug reports or concerns about this repository: #camunda-composite-components. For more general questions towards the Design System team, please use #ask-cds.

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, fork it, lezgo! A list of C4-Adopters can be found here.

Storybook

A live view of the main branch can be found here. 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

# install
yarn

# start storybook
yarn storybook

# build components
yarn build

Release

Simply run our release workflow 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.

Usage

Example for navbar:

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

// ...

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

Opt into SSE by using the C3ClusterUpdateManager Provider

// App.tsx
import { C3ClusterUpdateManager } from "@camunda/camunda-composite-components"

return (
	<C3ClusterUpdateManager stage={getEnv()} userToken={auth.token!}>
		<App />
	</C3ClusterUpdateManager>
)

Listen for SSE events from anywhere in your app

// ClusterPage.tsx

useEffect(() => {
	const handler = (event) => {
		const data = event.detail

		if (data && data.org && data.org === currentOrgId) {
			switch (data.entity) {
				case "cluster": {
				}
				case "cluster-client": {
				}
				case "alert-subscription": {
				}
				case "connector-secrets": {
				}
				case "console-api-client": {
				}
				case "backup": {
				}
			}
		}
	}

	window.addEventListener("clusterchange", handler)

	return () => {
		window.removeEventListener("clusterchange", handler)
	}
}, [])

(incomplete) List of adopters of C3+C4

• Console team started this, their C4 repo can be found here
• Identity team: c4-identity

Testing

Visual regression tests (VRT)

We use Playwright 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:

yarn start:docker-storybook

then

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.

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. Then, have a look at the test report:

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:

yarn update:visual-regression:docker

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