@camunda/camunda-composite-components 0.0.0-rc-20250210082942

package/README.md

@@ -0,0 +1,149 @@
+# 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/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).

package/lib/esm/package.json

@@ -0,0 +1,116 @@
+{
+    "name": "@camunda/camunda-composite-components",
+    "version": "0.16.0",
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "clean": "rimraf lib/",
+        "build": "pnpm clean && tsc",
+        "storybook": "storybook dev -p 6006",
+        "start": "pnpm storybook",
+        "build-storybook": "storybook build",
+        "build:all": "pnpm build && pnpm build-storybook",
+        "serve:storybook": "serve ./storybook-static -p 6006 -n -L",
+        "prepare": "husky",
+        "format": "prettier --write .",
+        "lint": "eslint src/",
+        "lint:fix": "eslint --fix src/",
+        "test:ts": "tsc --noEmit --project ./tsconfig.json",
+        "test:storybook": "TEST_A11Y=true test-storybook",
+        "test:storybook:smoke": "test-storybook",
+        "start:docker-storybook": "pnpm build-storybook && docker-compose up -d && docker-compose exec c3-visual-regression pnpm serve:storybook",
+        "test:visual-regression": "wait-on http://localhost:6006 && PWTEST_SKIP_TEST_OUTPUT=1 pnpm playwright test",
+        "test:visual-regression:ui": "pnpm test:playwright --ui",
+        "report:visual-regression": "pnpm playwright show-report",
+        "update:visual-regression": "pnpm playwright test --update-snapshots",
+        "test:visual-regression:docker": "docker exec -it -t c3-visual-regression pnpm test:visual-regression",
+        "update:visual-regression:docker": "docker exec -it -t c3-visual-regression pnpm update:visual-regression",
+        "test": "pnpm test:ts && pnpm test:storybook && pnpm test:visual-regression:docker"
+    },
+    "devDependencies": {
+        "@babel/core": "7.25.7",
+        "@babel/preset-env": "7.25.7",
+        "@babel/preset-react": "7.25.7",
+        "@babel/preset-typescript": "7.25.7",
+        "@carbon/react": "1.69.0",
+        "@mdx-js/react": "3.0.1",
+        "@playwright/test": "1.45.2",
+        "@semantic-release/changelog": "6.0.3",
+        "@semantic-release/git": "10.0.1",
+        "@storybook/addon-a11y": "8.2.9",
+        "@storybook/addon-actions": "8.2.9",
+        "@storybook/addon-docs": "8.2.9",
+        "@storybook/addon-essentials": "8.2.9",
+        "@storybook/addon-interactions": "8.2.9",
+        "@storybook/addon-links": "8.2.9",
+        "@storybook/addon-mdx-gfm": "8.2.9",
+        "@storybook/addon-webpack5-compiler-babel": "3.0.3",
+        "@storybook/blocks": "8.2.9",
+        "@storybook/preset-scss": "1.0.3",
+        "@storybook/react": "8.2.9",
+        "@storybook/react-webpack5": "8.2.9",
+        "@storybook/test": "8.2.9",
+        "@storybook/test-runner": "0.19.1",
+        "@types/carbon-components-react": "7.55.10",
+        "@types/event-source-polyfill": "1.0.5",
+        "@types/mixpanel-browser": "2.49.0",
+        "@types/node": "20.12.4",
+        "@types/react": "18.0.28",
+        "@types/react-dom": "18.0.11",
+        "@types/styled-components": "5.1.34",
+        "@typescript-eslint/eslint-plugin": "7.17.0",
+        "@typescript-eslint/parser": "7.17.0",
+        "axe-playwright": "2.0.1",
+        "babel-loader": "9.2.1",
+        "conventional-changelog-conventionalcommits": "7.0.2",
+        "copyfiles": "2.4.1",
+        "css-loader": "7.1.0",
+        "eslint": "8.57.0",
+        "eslint-config-prettier": "9.1.0",
+        "eslint-import-resolver-typescript": "3.6.1",
+        "eslint-plugin-import": "2.29.1",
+        "eslint-plugin-prettier": "5.2.1",
+        "eslint-plugin-react": "7.35.0",
+        "eslint-plugin-react-hooks": "4.6.2",
+        "eslint-plugin-storybook": "0.8.0",
+        "event-source-polyfill": "1.0.31",
+        "husky": "9.1.2",
+        "mixpanel-browser": "2.49.0",
+        "prettier": "3.3.3",
+        "react": "18.2.0",
+        "react-dom": "18.2.0",
+        "rimraf": "6.0.1",
+        "sass": "1.74.1",
+        "sass-loader": "14.1.1",
+        "semantic-release": "23.0.7",
+        "serve": "14.2.1",
+        "storybook": "8.2.9",
+        "style-loader": "4.0.0",
+        "styled-components": "6.1.8",
+        "typescript": "4.9.5",
+        "wait-on": "7.2.0",
+        "webpack": "5.94.0"
+    },
+    "dependencies": {
+        "jwt-decode": "4.0.0",
+        "react-error-boundary": "4.0.13",
+        "react-markdown": "8.0.7"
+    },
+    "peerDependencies": {
+        "@carbon/react": "1.x",
+        "event-source-polyfill": "1.0.x",
+        "react": "18.x",
+        "react-dom": "18.x",
+        "styled-components": "5.x || 6.x"
+    },
+    "description": "Camunda Composite Components",
+    "main": "./lib/esm/src/index.js",
+    "types": "./lib/esm/src/index.d.ts",
+    "files": [
+        "/lib"
+    ],
+    "author": "Camunda",
+    "license": "Apache-2.0"
+}

package/lib/esm/src/api/api.d.ts

@@ -0,0 +1,28 @@
+import { Endpoints, Stage } from "./endpoints.const";
+export interface RequestPayload {
+    url: string;
+    base?: "notifications" | "accounts";
+    stage?: Stage;
+    endpoints?: Endpoints;
+    method?: "get" | "post" | "put" | "delete" | "patch";
+    headers?: {
+        [key: string]: string;
+    };
+    type?: "json" | "text" | "form" | "none";
+    responseType?: "json" | "text" | "none";
+    camundaAuth?: {
+        token: string;
+        refreshTokenMethod?: () => Promise<string>;
+    };
+    body?: string | FormData | {
+        [key: string]: unknown;
+    };
+    enableLogs?: boolean;
+}
+export type RequestResponse<R = undefined> = {
+    success: boolean;
+    result?: R;
+    status?: number;
+    error?: string;
+};
+export declare const request: <R = undefined>(payload: RequestPayload) => Promise<RequestResponse<R>>;

package/lib/esm/src/api/api.js

@@ -0,0 +1,86 @@
+import { getEndpoint, NOTIFICATIONS, ACCOUNTS, } from "./endpoints.const";
+import { JWTUtils } from "./jwt.utils";
+export const request = async (payload) => {
+    const headers = {};
+    if (payload.camundaAuth) {
+        if (JWTUtils.isExpired(payload.camundaAuth.token) &&
+            payload.camundaAuth.refreshTokenMethod) {
+            const newToken = await payload.camundaAuth?.refreshTokenMethod?.();
+            headers.Authorization = `Bearer ${newToken}`;
+        }
+        else {
+            headers.Authorization = `Bearer ${payload.camundaAuth.token}`;
+        }
+    }
+    const type = payload.type ?? "json";
+    if (type) {
+        switch (type) {
+            case "json":
+                headers["Content-Type"] = "application/json";
+                break;
+            case "text":
+                headers["Content-Type"] = "text/plain";
+                break;
+        }
+    }
+    const body = payload.body && type === "json"
+        ? JSON.stringify(payload.body)
+        : payload.body instanceof FormData
+            ? payload.body
+            : undefined;
+    let base;
+    if (payload.base) {
+        switch (payload.base) {
+            case "notifications":
+                if (payload.endpoints?.notifications) {
+                    base = payload.endpoints.notifications;
+                }
+                else if (payload.stage) {
+                    base = getEndpoint(payload.stage, NOTIFICATIONS);
+                }
+                break;
+            case "accounts":
+                if (payload.endpoints?.accounts) {
+                    base = payload.endpoints.accounts;
+                }
+                else if (payload.stage) {
+                    base = getEndpoint(payload.stage, ACCOUNTS);
+                }
+        }
+    }
+    const url = base ? `${base}/${payload.url}` : payload.url;
+    try {
+        const response = await fetch(url, {
+            method: payload.method ? payload.method.toUpperCase() : "GET",
+            headers,
+            body,
+        });
+        if (response.status >= 400) {
+            if (payload.enableLogs)
+                console.error(response.statusText, response.status);
+            return {
+                success: false,
+                status: response.status,
+                error: response.statusText,
+            };
+        }
+        const responseType = payload.responseType ?? type;
+        let res;
+        switch (responseType) {
+            case "json":
+                res = await response.json();
+                break;
+            case "text":
+                res = await response.text();
+                break;
+            default:
+                res = response;
+        }
+        return { success: true, result: res };
+    }
+    catch (error) {
+        if (payload.enableLogs)
+            console.error("API request failed:", error);
+        return { success: false, error: error?.toString() };
+    }
+};

package/lib/esm/src/api/endpoints.const.d.ts

@@ -0,0 +1,19 @@
+export interface Endpoint {
+    id: string;
+    dev: string;
+    int: string;
+    prod: string;
+}
+export interface Endpoints {
+    notifications?: string;
+    accounts?: string;
+}
+export declare const NOTIFICATIONS: Endpoint;
+export declare const ACCOUNTS: Endpoint;
+export type Stage = "dev" | "int" | "prod";
+export declare function getEndpoint(stage: Stage, endpoint: Endpoint): string;
+export declare function getEndpointByOptions(options: {
+    stage?: Stage;
+    endpoints?: Endpoints;
+    endpoint: Endpoint;
+}): string;

package/lib/esm/src/api/endpoints.const.js

@@ -0,0 +1,44 @@
+export const NOTIFICATIONS = {
+    id: "notifications",
+    dev: "https://notifications.cloud.dev.ultrawombat.com",
+    int: "https://notifications.cloud.ultrawombat.com",
+    prod: "https://notifications.cloud.camunda.io",
+};
+export const ACCOUNTS = {
+    id: "accounts",
+    dev: "https://accounts.cloud.dev.ultrawombat.com",
+    int: "https://accounts.cloud.ultrawombat.com",
+    prod: "https://accounts.cloud.camunda.io",
+};
+export function getEndpoint(stage, endpoint) {
+    switch (stage) {
+        case "dev":
+            return endpoint.dev;
+        case "int":
+            return endpoint.int;
+        case "prod":
+            return endpoint.prod;
+        default:
+            throw new Error(`Unknown stage: ${stage}`);
+    }
+}
+export function getEndpointByOptions(options) {
+    switch (options.endpoint.id) {
+        case "notifications":
+            if (options.endpoints?.notifications) {
+                return options.endpoints.notifications;
+            }
+            else if (options.stage) {
+                return getEndpoint(options.stage, options.endpoint);
+            }
+            break;
+        case "accounts":
+            if (options.endpoints?.accounts) {
+                return options.endpoints.accounts;
+            }
+            else if (options.stage) {
+                return getEndpoint(options.stage, options.endpoint);
+            }
+    }
+    throw new Error(`Missing stage or notifications endpoint`);
+}

package/lib/esm/src/api/help-center.d.ts

@@ -0,0 +1,41 @@
+import { HelpCenterConfig } from "../components/c3-help-center/defaultHelpCenterConfig";
+import { Persona, TileConfig, WpCardType } from "../components/c3-help-center/c3-help-center.types";
+import { OnboardingConfig } from "../components/c3-onboarding-survey/defaultOnboardingConfig";
+import { RequestPayload, RequestResponse } from "./api";
+export declare const getConfig: (accessToken: string, audience: string, orgId: string) => Promise<RequestResponse<HelpCenterConfig | null>>;
+export declare const getTiles: ({ accessToken, tileConfig, salesPlanType, clusterIds, persona, flags, cloudAudience, }: {
+    accessToken: string;
+    tileConfig: TileConfig[];
+    cloudAudience: string;
+    persona: {
+        [id: string]: unknown;
+    };
+    clusterIds: string[];
+    salesPlanType: string;
+    flags: string[];
+}) => Promise<RequestResponse<WpCardType[]>>;
+export declare const getOnboardingConfig: ({ camundaAuth, audience, orgId, }: {
+    audience: string;
+    camundaAuth: RequestPayload["camundaAuth"];
+    orgId: string;
+}) => Promise<RequestResponse<OnboardingConfig>>;
+export declare const updatePersona: ({ newPersona, audience, accessToken, orgId, userId, }: {
+    newPersona: Persona;
+    audience: string;
+    orgId: string;
+    userId: string;
+    accessToken: string;
+}) => Promise<RequestResponse<undefined>>;
+export declare const submitSurvey: ({ audience, token, data, }: {
+    audience: string;
+    token: string;
+    data: Persona & {
+        email: string;
+        orgUuid: string;
+    };
+}) => Promise<RequestResponse<undefined>>;
+export declare const submitFeedback: ({ token, audience, formData, }: {
+    token: string;
+    audience: string;
+    formData: FormData;
+}) => Promise<RequestResponse<undefined>>;

package/lib/esm/src/api/help-center.js

@@ -0,0 +1,47 @@
+import { recommendations } from "../components/c3-help-center/recommendations";
+import { request } from "./api";
+export const getConfig = async (accessToken, audience, orgId) => {
+    return await request({
+        url: `https://helpcenter.${audience}/helpcenter/config/${orgId}`,
+        camundaAuth: {
+            token: accessToken,
+        },
+    });
+};
+export const getTiles = async ({ accessToken, tileConfig, salesPlanType, clusterIds, persona, flags, cloudAudience, }) => {
+    const availableTileTypes = recommendations(persona, flags, tileConfig, salesPlanType, clusterIds?.length > 0);
+    return await request({
+        url: `https://helpcenter.${cloudAudience}/cards?card_id=${availableTileTypes.join(",")}`,
+        responseType: "json",
+        camundaAuth: { token: accessToken },
+    });
+};
+export const getOnboardingConfig = ({ camundaAuth, audience, orgId, }) => request({
+    url: `https://helpcenter.${audience}/survey/config/${orgId}`,
+    camundaAuth,
+    type: "json",
+});
+export const updatePersona = async ({ newPersona, audience, accessToken, orgId, userId, }) => request({
+    url: `https://helpcenter.${audience}/persona`,
+    method: "patch",
+    camundaAuth: { token: accessToken },
+    type: "json",
+    body: { persona: newPersona, userId, orgId },
+    responseType: "text",
+});
+export const submitSurvey = async ({ audience, token, data, }) => request({
+    method: "post",
+    url: `https://helpcenter.${audience}/survey/submit`,
+    camundaAuth: { token },
+    type: "json",
+    body: { data },
+    responseType: "text",
+});
+export const submitFeedback = async ({ token, audience, formData, }) => request({
+    method: "post",
+    url: `https://helpcenter.${audience}/feedback/submit`,
+    camundaAuth: { token },
+    body: formData,
+    type: "form",
+    responseType: "text",
+});

package/lib/esm/src/api/jwt.utils.d.ts

@@ -0,0 +1,5 @@
+export declare class JWTUtils {
+    static decode(token: string): any;
+    static getExpiration(token: string): number;
+    static isExpired(token: string): boolean;
+}

package/lib/esm/src/api/jwt.utils.js

@@ -0,0 +1,23 @@
+export class JWTUtils {
+    static decode(token) {
+        const base64Url = token.split(".")[1];
+        const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+        const jsonPayload = decodeURIComponent(window
+            .atob(base64)
+            .split("")
+            .map(function (c) {
+            return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
+        })
+            .join(""));
+        return JSON.parse(jsonPayload);
+    }
+    static getExpiration(token) {
+        const decoded = JWTUtils.decode(token);
+        return decoded.exp;
+    }
+    static isExpired(token) {
+        const expiration = JWTUtils.getExpiration(token);
+        const now = new Date().getTime() / 1000;
+        return expiration < now;
+    }
+}

package/lib/esm/src/api/notifications.d.ts

@@ -0,0 +1,41 @@
+import { C3NotificationsProps } from "../components/c3-navigation/c3-navigation.types";
+import { RequestResponse } from "./api";
+export interface Notification {
+    uuid: string;
+    userId?: string;
+    orgId?: string;
+    timestamp: number;
+    source: string;
+    type: string;
+    title: string;
+    description: string;
+    state: string;
+    meta?: {
+        identifier?: string;
+        href?: string;
+        label?: string;
+        entity?: {
+            id: string;
+            type: string;
+        };
+        parentEntity?: {
+            id: string;
+            type: string;
+        };
+    };
+}
+export type AnalyticsEvent = "notification-panel-opened" | "notification-clicked-cta";
+export declare class NotificationService {
+    static getNotifications(options: C3NotificationsProps): Promise<RequestResponse<Notification[]>>;
+    static sendAnalyticsEvent(options: C3NotificationsProps, eventOptions: {
+        event: AnalyticsEvent;
+        id?: string;
+    }): void;
+    static changeState(options: C3NotificationsProps, notificationId: string, operation: "read" | "dismiss"): void;
+    static markManyAsRead(options: C3NotificationsProps, notificationIds: string[]): void;
+    static dismissAll(options: C3NotificationsProps, orgId: string): void;
+    static notificationsStream(options: C3NotificationsProps, handler: (notification: Notification) => void): void;
+    static updateNotifications(allNotifications: Notification[], newNotification: Notification): Notification[];
+    static updateNotificationState(allNotifications: Notification[], notificationId: string, newState: "read" | "dismiss"): Notification[];
+    static updateNotificationStates(allNotifications: Notification[], notificationIds: string[], newState: "read" | "dismiss"): Notification[];
+}