@camunda/camunda-composite-components 0.23.3 → 0.24.0

package/lib/esm/src/components/c3-navigation-v2/tools/c3-user-panel.js

@@ -4,11 +4,9 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * under one or more contributor license agreements. Licensed under a commercial license.
  * You may not use this file except in compliance with the commercial license.
  */
-import { Button, FormLabel, RadioButton, RadioButtonGroup, Stack, Toggle, } from '@carbon/react';
+import { Button, Toggle } from '@carbon/react';
 import { ArrowRight } from '@carbon/react/icons/index.esm.js';
 import styled from 'styled-components';
-import { useC3Profile, } from '../../c3-user-configuration/c3-profile-provider/c3-profile-provider.js';
-import { useC3UserConfiguration } from '../../c3-user-configuration/c3-user-configuration-provider.js';
 import { PanelHeader, PanelTitle } from './panel-primitives.js';
 const ProfileSection = styled.div `
   padding: var(--cds-spacing-05);
@@ -26,10 +24,6 @@ const ProfileEmail = styled.span `
   font-size: var(--cds-label-01-font-size);
   color: var(--cds-text-secondary);
 `;
-const ThemeSection = styled.div `
-  padding: var(--cds-spacing-05);
-  border-bottom: 1px solid var(--cds-border-subtle-01);
-`;
 const CustomSection = styled.div `
   border-bottom: 1px solid var(--cds-border-subtle-01);
 `;
@@ -95,31 +89,30 @@ const Copyright = styled.p `
   line-height: var(--cds-label-01-line-height);
   letter-spacing: var(--cds-label-01-letter-spacing);
 `;
-const LEGAL_LINKS = [
+const buildLegalLinks = (labels) => [
     {
         key: 'terms',
-        label: 'Terms of use',
+        label: labels?.termsOfUse ?? 'Terms of use',
         onClick: () => window.open('https://camunda.com/legal/terms/camunda-platform/camunda-platform-8-saas-trial/', '_blank'),
     },
     {
         key: 'privacy',
-        label: 'Privacy policy',
+        label: labels?.privacyPolicy ?? 'Privacy policy',
         onClick: () => window.open('https://camunda.com/legal/privacy/', '_blank'),
     },
     {
         key: 'imprint',
-        label: 'Imprint',
+        label: labels?.imprint ?? 'Imprint',
         onClick: () => window.open('https://camunda.com/legal/imprint/', '_blank'),
     },
 ];
-export const C3UserPanel = ({ name, email, version, onLogout, stageToggle, customSection, elements, }) => {
-    const { handleTheme } = useC3UserConfiguration();
-    const { theme, onThemeChange } = useC3Profile();
+export const C3UserPanel = ({ name, email, version, onLogout, stageToggle, customSection, elements, title = 'Account', labels, }) => {
     const consumerKeys = new Set((elements ?? []).map((e) => e.key));
-    const defaults = LEGAL_LINKS.filter((l) => !consumerKeys.has(l.key));
+    const defaults = buildLegalLinks(labels).filter((l) => !consumerKeys.has(l.key));
     const allElements = [...(elements ?? []), ...defaults];
-    return (_jsxs(_Fragment, { children: [_jsx(PanelHeader, { children: _jsx(PanelTitle, { children: "Account" }) }), (name || email) && (_jsxs(ProfileSection, { children: [name && _jsx(ProfileName, { children: name }), email && _jsx(ProfileEmail, { children: email })] })), customSection && _jsx(CustomSection, { children: customSection }), handleTheme && (_jsx(ThemeSection, { children: _jsxs(Stack, { gap: 3, children: [_jsx(FormLabel, { children: "Theme" }), _jsxs(RadioButtonGroup, { name: 'theme', valueSelected: theme, onChange: (value) => onThemeChange(value), orientation: 'vertical', children: [_jsx(RadioButton, { value: 'light', labelText: 'Light', id: 'theme-light' }), _jsx(RadioButton, { value: 'dark', labelText: 'Dark', id: 'theme-dark' }), _jsx(RadioButton, { value: 'system', labelText: 'System', id: 'theme-system' })] })] }) })), stageToggle && (_jsx("div", { style: {
+    return (_jsxs(_Fragment, { children: [title && (_jsx(PanelHeader, { children: _jsx(PanelTitle, { children: title }) })), (name || email) && (_jsxs(ProfileSection, { children: [name && _jsx(ProfileName, { children: name }), email && _jsx(ProfileEmail, { children: email })] })), customSection && _jsx(CustomSection, { children: customSection }), stageToggle && (_jsx("div", { style: {
                     padding: 'var(--cds-spacing-05)',
                     borderBottom: '1px solid var(--cds-border-subtle-01)',
-                }, children: _jsx(Toggle, { id: 'stage-toggle', labelText: 'Production features', toggled: stageToggle.prodFeaturesEnabled, onToggle: stageToggle.toggle, size: 'sm' }) })), allElements.length > 0 && (_jsx(ElementList, { children: allElements.map((element) => (_jsx(ElementItem, { children: _jsx(ElementButton, { type: 'button', onClick: element.onClick, children: element.label }) }, element.key))) })), _jsxs(BottomPinned, { children: [version && (_jsxs(VersionWrapper, { children: [_jsx(VersionText, { children: version }), _jsxs(Copyright, { children: ["\u00A9 Camunda Services GmbH ", new Date().getFullYear()] })] })), onLogout && (_jsx(BottomActions, { children: _jsx(Button, { kind: 'ghost', size: 'lg', onClick: onLogout, renderIcon: ArrowRight, children: "Log out" }) }))] })] }));
+                }, children: _jsx(Toggle, { id: 'stage-toggle', labelText: 'Production features', toggled: stageToggle.prodFeaturesEnabled, onToggle: stageToggle.toggle, size: 'sm' }) })), allElements.length > 0 && (_jsx(ElementList, { children: allElements.map((element) => (_jsx(ElementItem, { children: _jsx(ElementButton, { type: 'button', onClick: element.onClick, children: element.label }) }, element.key))) })), _jsxs(BottomPinned, { children: [version && (_jsxs(VersionWrapper, { children: [_jsx(VersionText, { children: version }), _jsx(Copyright, { children: labels?.copyright?.(new Date().getFullYear()) ??
+                                    `© Camunda Services GmbH ${new Date().getFullYear()}` })] })), onLogout && (_jsx(BottomActions, { children: _jsx(Button, { kind: 'ghost', size: 'lg', onClick: onLogout, renderIcon: ArrowRight, children: labels?.logOut ?? 'Log out' }) }))] })] }));
 };

package/lib/esm/src/components/c3-navigation-v2/use-c3-navigation-v2.d.ts

@@ -1,4 +1,4 @@
-import type { BreadcrumbAction, C3NavigationV2Props, GlobalActionButton, LinkComponent, LinkProps, ToolDescriptor } from './c3-navigation-v2.types';
+import type { BreadcrumbAction, C3NavigationV2Props, GlobalActionButton, LinkComponent, LinkProps, SidebarLabels, ToolDescriptor } from './c3-navigation-v2.types';
 type ActiveMatcher = boolean | string | ((activeItemKey: string) => boolean);
 export interface ItemDescriptor {
     type: 'item';
@@ -82,6 +82,8 @@ export interface UseC3NavigationV2Options {
     skipToContentLabel?: string;
     headerAriaLabel?: string;
     sidebarAriaLabel?: string;
+    /** Forwarded to `C3Sidebar` `labels`. */
+    sidebarLabels?: SidebarLabels;
     /** Used to resolve `isActive` on sidebar items and `isSelected` on breadcrumb dropdown items. */
     activeItemKey: string;
     sidebarChildren?: SidebarNodeDescriptor[];

package/lib/esm/src/components/c3-navigation-v2/use-c3-navigation-v2.js

@@ -30,7 +30,7 @@ function collectDefaultExpanded(nodes, out) {
  * descriptors (isActive, label functions) into concrete props.
  */
 export function useC3NavigationV2(options) {
-    const { app, skipToContentTargetId, skipToContentLabel, headerAriaLabel, sidebarAriaLabel = 'Main navigation', activeItemKey, sidebarChildren = [], breadcrumbs = [], tools, globalActions, sidebarExpandedWidth, sidebarCollapsedWidth, defaultSidebarExpanded = true, onSidebarToggle, linkComponent, headerTrailingContent, } = options;
+    const { app, skipToContentTargetId, skipToContentLabel, headerAriaLabel, sidebarAriaLabel = 'Main navigation', sidebarLabels, activeItemKey, sidebarChildren = [], breadcrumbs = [], tools, globalActions, sidebarExpandedWidth, sidebarCollapsedWidth, defaultSidebarExpanded = true, onSidebarToggle, linkComponent, headerTrailingContent, } = options;
     const [isSidebarExpanded, setIsSidebarExpanded] = useState(defaultSidebarExpanded);
     const setSidebarExpanded = useCallback((expanded) => {
         setIsSidebarExpanded(expanded);
@@ -173,6 +173,7 @@ export function useC3NavigationV2(options) {
             expandedWidth: sidebarExpandedWidth,
             collapsedWidth: sidebarCollapsedWidth,
             linkComponent,
+            labels: sidebarLabels,
         }
         : undefined;
     const navProps = useMemo(() => ({

package/lib/esm/src/components/c3-navigation-v2/use-camunda-tools.d.ts

@@ -1,10 +1,16 @@
+import { type FC, type ReactNode } from 'react';
 import type { Notification } from '../../api/notifications';
 import type { ToolDescriptor } from './c3-navigation-v2.types';
 import { type InfoPanelElement } from './tools/c3-info-panel';
+import { type C3NotificationsPanelLabels } from './tools/c3-notifications-panel';
 import { type C3UserPanelProps } from './tools/c3-user-panel';
 export interface NotificationsToolOptions {
     onLinkClick?: (meta: Notification['meta']) => void;
     ariaLabel?: string;
+    /** Forwarded to `C3NotificationsPanel`. */
+    title?: string | null;
+    /** Forwarded to `C3NotificationsPanel`. */
+    labels?: C3NotificationsPanelLabels;
 }
 export type UserToolOptions = C3UserPanelProps & {
     ariaLabel?: string;
@@ -15,7 +21,8 @@ export interface HelpToolOptions {
 }
 export interface InfoToolOptions {
     elements: InfoPanelElement[];
-    title?: string;
+    /** Forwarded to `C3InfoPanel`. */
+    title?: string | null;
     ariaLabel?: string;
 }
 export interface UseCamundaToolsOptions {
@@ -39,11 +46,27 @@ export interface UseCamundaToolsOptions {
      */
     help?: HelpToolOptions;
 }
+export interface UseCamundaToolsReturn {
+    tools: ToolDescriptor[];
+    /**
+     * Wraps the consumer's nav subtree with the providers the requested tools
+     * depend on. Currently only notifications needs a provider; when omitted,
+     * `ToolsProvider` passes children through unchanged. Wrap the
+     * `<C3NavigationV2>` render with this so the tool components can read their
+     * context inside the JSX they're rendered into.
+     */
+    ToolsProvider: FC<{
+        children: ReactNode;
+    }>;
+}
 /**
  * Single helper entry point for the standard Camunda tool set.
- * Returns a ToolDescriptor[] ready to pass into C3NavigationV2's `tools` prop.
- * Custom tools can be appended to the returned array.
+ * Returns a `ToolDescriptor[]` for `C3NavigationV2`'s `tools` prop plus a
+ * `ToolsProvider` that conditionally mounts the providers each requested tool
+ * depends on. Custom tools can be appended to the returned array; if they
+ * have their own provider needs, layer a separate wrapper outside
+ * `ToolsProvider`.
  *
- * Must be called within a C3UserConfigurationProvider tree (SaaS).
+ * Must be called within a `C3UserConfigurationProvider` tree (SaaS).
  */
-export declare const useCamundaTools: (options: UseCamundaToolsOptions) => ToolDescriptor[];
+export declare const useCamundaTools: (options: UseCamundaToolsOptions) => UseCamundaToolsReturn;

package/lib/esm/src/components/c3-navigation-v2/use-camunda-tools.js

@@ -1,75 +1,94 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 /*
  * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
  * under one or more contributor license agreements. Licensed under a commercial license.
  * You may not use this file except in compliance with the commercial license.
  */
-import { HeaderGlobalAction } from '@carbon/react';
-import { Help as HelpIcon, Information, Notification as NotificationIcon, UserAvatar, } from '@carbon/react/icons/index.esm.js';
+import { HeaderGlobalAction as HeaderGlobalActionBase } from '@carbon/react';
+import { Help as HelpIcon, Notification as NotificationIcon, UserAvatar, } from '@carbon/react/icons/index.esm.js';
 import { useContext, useMemo } from 'react';
 import { C3NotificationsUnreadIcon } from '../../assets/c3-icons.js';
-import { C3NotificationContext } from '../c3-navigation/c3-notification-provider/c3-notification-provider.js';
+import { useC3HelpCenter } from '../c3-help-center/c3-help-center-provider.js';
+import C3NotificationProvider, { C3NotificationContext, } from '../c3-navigation/c3-notification-provider/c3-notification-provider.js';
 import { C3InfoPanel } from './tools/c3-info-panel.js';
-import { C3NotificationsPanel } from './tools/c3-notifications-panel.js';
+import { C3NotificationsPanel, } from './tools/c3-notifications-panel.js';
 import { C3UserPanel } from './tools/c3-user-panel.js';
+/**
+ * Carbon's `HeaderGlobalAction` is typed as `React.FC` and omits both `ref`
+ * (the component uses `forwardRef` internally) and `leaveDelayMs`. Both work
+ * at runtime, so we widen the type at the import site — same pattern as
+ * `c3-navigation-appbar` / `-sidebar`.
+ */
+const HeaderGlobalAction = HeaderGlobalActionBase;
 /**
  * Single helper entry point for the standard Camunda tool set.
- * Returns a ToolDescriptor[] ready to pass into C3NavigationV2's `tools` prop.
- * Custom tools can be appended to the returned array.
+ * Returns a `ToolDescriptor[]` for `C3NavigationV2`'s `tools` prop plus a
+ * `ToolsProvider` that conditionally mounts the providers each requested tool
+ * depends on. Custom tools can be appended to the returned array; if they
+ * have their own provider needs, layer a separate wrapper outside
+ * `ToolsProvider`.
  *
- * Must be called within a C3UserConfigurationProvider tree (SaaS).
+ * Must be called within a `C3UserConfigurationProvider` tree (SaaS).
  */
 export const useCamundaTools = (options) => {
-    const { notifications, isFetching } = useContext(C3NotificationContext);
-    const hasUnread = !isFetching && notifications.some((n) => n.state === 'new');
-    return useMemo(() => {
-        const tools = [];
+    const { launcherButtonRef: helpButtonRef } = useC3HelpCenter();
+    const tools = useMemo(() => {
+        const result = [];
         if (options.notifications !== undefined) {
             const notifOptions = options.notifications;
             const label = notifOptions.ariaLabel ?? 'Notifications';
-            tools.push({
+            result.push({
                 key: 'notifications',
                 label,
-                renderButton: ({ onClick, isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'center', ...{ leaveDelayMs: 100 }, children: hasUnread ? (_jsx(C3NotificationsUnreadIcon, { size: 20 })) : (_jsx(NotificationIcon, { size: 20 })) })),
-                panel: (_jsx(C3NotificationsPanel, { onLinkClick: notifOptions.onLinkClick })),
+                renderButton: ({ onClick, isActive }) => {
+                    const { notifications, isFetching } = useContext(C3NotificationContext);
+                    const hasUnread = !isFetching && notifications.some((n) => n.state === 'new');
+                    return (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'center', leaveDelayMs: 100, children: hasUnread ? (_jsx(C3NotificationsUnreadIcon, { size: 20 })) : (_jsx(NotificationIcon, { size: 20 })) }));
+                },
+                panel: (_jsx(C3NotificationsPanel, { onLinkClick: notifOptions.onLinkClick, title: notifOptions.title, labels: notifOptions.labels })),
             });
         }
         if (options.info !== undefined) {
             const { elements, title, ariaLabel } = options.info;
             const label = ariaLabel ?? 'Info';
-            tools.push({
+            result.push({
                 key: 'info',
                 label,
-                renderButton: ({ onClick, isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'center', ...{ leaveDelayMs: 100 }, children: _jsx(Information, { size: 20 }) })),
+                renderButton: ({ onClick, isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'center', leaveDelayMs: 100, children: _jsx(HelpIcon, { size: 20 }) })),
                 panel: (_jsx(C3InfoPanel, { elements: elements, title: title })),
             });
         }
         if (options.help !== undefined) {
             const { onClick, ariaLabel } = options.help;
             const label = ariaLabel ?? 'Help';
-            tools.push({
+            result.push({
                 key: 'help',
                 label,
-                renderButton: ({ isActive: _isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, tooltipAlignment: 'center', ...{ leaveDelayMs: 100 }, children: _jsx(HelpIcon, { size: 20 }) })),
+                renderButton: ({ isActive: _isActive }) => (_jsx(HeaderGlobalAction, { ref: helpButtonRef, "aria-label": label, onClick: onClick, tooltipAlignment: 'center', leaveDelayMs: 100, children: _jsx(HelpIcon, { size: 20 }) })),
                 // no panel, help is a plain button
             });
         }
         if (options.user !== undefined) {
             const { ariaLabel, ...panelProps } = options.user;
             const label = ariaLabel ?? 'Account';
-            tools.push({
+            result.push({
                 key: 'user',
                 label,
-                renderButton: ({ onClick, isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'end', ...{ leaveDelayMs: 100 }, children: _jsx(UserAvatar, { size: 20 }) })),
+                renderButton: ({ onClick, isActive }) => (_jsx(HeaderGlobalAction, { "aria-label": label, onClick: onClick, isActive: isActive, tooltipAlignment: 'end', leaveDelayMs: 100, children: _jsx(UserAvatar, { size: 20 }) })),
                 panel: (_jsx(C3UserPanel, { ...panelProps })),
             });
         }
-        return tools;
+        return result;
     }, [
-        hasUnread,
         options.notifications,
         options.info,
         options.help,
         options.user,
+        helpButtonRef,
     ]);
+    const ToolsProvider = useMemo(() => {
+        const needsNotifications = options.notifications !== undefined;
+        return ({ children }) => needsNotifications ? (_jsx(C3NotificationProvider, { children: children })) : (_jsx(_Fragment, { children: children }));
+    }, [options.notifications !== undefined]);
+    return { tools, ToolsProvider };
 };

package/lib/esm/src/components/c3-navigation-v2/use-cluster-sidebar-entries.js

@@ -24,15 +24,17 @@ function buildClusterSidebarEntries(clusters, { isAppVisible, resolveClusterLink
             if (!endpoint)
                 return [];
             const teaser = appTeaserRoutes?.[resolvedApp] ?? appTeaserRoutes?.[app];
-            // Admin has no dedicated status on the cluster DTO and doesn't depend
-            // on zeebe being up (it manages the cluster itself). Always link to
-            // the endpoint when present; consumers can still override via
-            // `appTeaserRoutes.admin` / `.identity` if they want a teaser page.
-            const linkProps = isAdminApp(app)
+            // Admin/identity has no dedicated status on the cluster DTO; it rides
+            // the same ingress as zeebe, so we gate its link on zeebe's health —
+            // matching V1's "zeebe as admin health proxy" contract. Consumers can
+            // still surface a teaser via `appTeaserRoutes.admin` / `.identity`
+            // when the link is unavailable.
+            const healthKey = isAdminApp(app)
+                ? 'zeebe'
+                : resolvedApp;
+            const linkProps = cluster.status?.[healthKey] === 'Healthy'
                 ? (teaser ?? { href: endpoint })
-                : cluster.status?.[resolvedApp] === 'Healthy'
-                    ? { href: endpoint }
-                    : teaser;
+                : teaser;
             if (!linkProps)
                 return [];
             return [

package/lib/esm/src/components/c3-navigation-v2/use-cluster-webapp-breadcrumbs.d.ts

@@ -3,30 +3,28 @@ import type { BreadcrumbDescriptor } from './use-c3-navigation-v2';
 export interface UseClusterWebappBreadcrumbsOptions {
     /** The app currently being viewed. */
     currentApp: CamundaApp;
-    /**
-     * Optional resolver to convert an endpoint URL into linkProps.
-     * Defaults to `(url) => ({ href: url })`. Override to support
-     * client-side routing (e.g. returning `{ to: path }` for internal links).
-     */
-    resolveLinkProps?: (url: string, app: string) => {
-        href?: string;
-        to?: string;
-        [key: string]: unknown;
-    };
 }
 /**
  * Builds the standard breadcrumb chain for a cluster-scoped Camunda webapp:
  *
- *   [Org] > [Cluster] > [App ▾]
+ *   [Org ▾] > [Cluster ▾] > [App ▾]
  *
- * - **Org crumb**: shown when org data is available (SaaS). Links back to
- *   web modeler at the org level.
- * - **Cluster crumb**: shown when cluster data is available. Links back to
- *   web modeler / console at the cluster level.
- * - **App crumb**: always shown. Includes a dropdown to switch between
- *   sibling apps on the same cluster (filtered to apps with endpoints).
+ * - **Org crumb**: shown when org data is available (SaaS). Label links back
+ *   to web modeler for the current org. Dropdown switches orgs and lands on
+ *   web modeler scoped to the selected org. Dropdown only renders when there
+ *   is at least one sibling org and the current cluster exposes a modeler
+ *   endpoint to derive sibling URLs from.
+ * - **Cluster crumb**: shown when cluster data is available. Label links back
+ *   to web modeler / console at the cluster level. Dropdown switches clusters
+ *   while staying on `currentApp`, filtered to clusters that expose an
+ *   endpoint for that app (alias-aware via `getEndpointForApp`).
+ * - **App crumb**: always shown. Dropdown switches between sibling apps on
+ *   the same cluster (filtered to apps with endpoints).
  *
- * Crumbs are omitted when the underlying data is unavailable, so the same
+ * Each dropdown follows the breadcrumb convention: clicking the label
+ * navigates, clicking the chevron opens the dropdown. Items are listed in
+ * source order with the current entry marked `isSelected`. Crumbs and
+ * dropdowns are omitted when the underlying data is unavailable, so the same
  * hook works for both SaaS (full chain) and Self-Managed (partial or single
  * crumb) without any environment flag.
  */

package/lib/esm/src/components/c3-navigation-v2/use-cluster-webapp-breadcrumbs.js

@@ -1,3 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 /*
  * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
  * under one or more contributor license agreements. Licensed under a commercial license.
@@ -5,7 +6,8 @@
  */
 import { Building, CloudApp } from '@carbon/react/icons/index.esm.js';
 import { useMemo } from 'react';
-import { APP_ICONS, getReadableAppName } from '../../utils/camunda.js';
+import { APP_ICONS, getEndpointForApp, getReadableAppName, isAdminApp, resolveAdminAppName, } from '../../utils/camunda.js';
+import { C3ClusterTag } from '../c3-cluster-tag/c3-cluster-tag.js';
 import { useC3Profile } from '../c3-user-configuration/c3-profile-provider/c3-profile-provider.js';
 import { useC3UserConfiguration } from '../c3-user-configuration/c3-user-configuration-provider.js';
 /**
@@ -20,77 +22,185 @@ const SWITCHABLE_APPS = [
     'optimize',
     'admin',
 ];
+/**
+ * Replaces the path of `modelerEndpoint` with `/org/{orgId}`. Used to derive
+ * the modeler URL for sibling orgs from the current cluster's modeler
+ * endpoint. Assumes all modeler URLs share the same host across orgs (SaaS
+ * pattern).
+ */
+function buildModelerOrgUrl(modelerEndpoint, orgId) {
+    try {
+        const url = new URL(modelerEndpoint);
+        url.pathname = `/org/${orgId}`;
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Builds the standard breadcrumb chain for a cluster-scoped Camunda webapp:
  *
- *   [Org] > [Cluster] > [App ▾]
+ *   [Org ▾] > [Cluster ▾] > [App ▾]
  *
- * - **Org crumb**: shown when org data is available (SaaS). Links back to
- *   web modeler at the org level.
- * - **Cluster crumb**: shown when cluster data is available. Links back to
- *   web modeler / console at the cluster level.
- * - **App crumb**: always shown. Includes a dropdown to switch between
- *   sibling apps on the same cluster (filtered to apps with endpoints).
+ * - **Org crumb**: shown when org data is available (SaaS). Label links back
+ *   to web modeler for the current org. Dropdown switches orgs and lands on
+ *   web modeler scoped to the selected org. Dropdown only renders when there
+ *   is at least one sibling org and the current cluster exposes a modeler
+ *   endpoint to derive sibling URLs from.
+ * - **Cluster crumb**: shown when cluster data is available. Label links back
+ *   to web modeler / console at the cluster level. Dropdown switches clusters
+ *   while staying on `currentApp`, filtered to clusters that expose an
+ *   endpoint for that app (alias-aware via `getEndpointForApp`).
+ * - **App crumb**: always shown. Dropdown switches between sibling apps on
+ *   the same cluster (filtered to apps with endpoints).
  *
- * Crumbs are omitted when the underlying data is unavailable, so the same
+ * Each dropdown follows the breadcrumb convention: clicking the label
+ * navigates, clicking the chevron opens the dropdown. Items are listed in
+ * source order with the current entry marked `isSelected`. Crumbs and
+ * dropdowns are omitted when the underlying data is unavailable, so the same
  * hook works for both SaaS (full chain) and Self-Managed (partial or single
  * crumb) without any environment flag.
  */
 export function useClusterWebappBreadcrumbs(options) {
-    const { currentApp, resolveLinkProps = (url) => ({ href: url }) } = options;
-    const { clusters, activeOrg } = useC3Profile();
+    const { currentApp } = options;
+    const { clusters, activeOrg, orgs } = useC3Profile();
     const config = useC3UserConfiguration();
     const currentClusterUuid = config.currentClusterUuid;
     const currentCluster = useMemo(() => clusters?.find((c) => c.uuid === currentClusterUuid) ?? null, [clusters, currentClusterUuid]);
     return useMemo(() => {
         const crumbs = [];
+        const modelerUrl = currentCluster?.endpoints?.modeler;
         // ── Org crumb ──────────────────────────────────────────────────────────
         if (activeOrg) {
-            const modelerUrl = currentCluster?.endpoints?.modeler;
+            const allOrgs = orgs ?? [];
+            const hasSiblings = allOrgs.filter((o) => o.uuid !== activeOrg.uuid).length > 0;
+            const orgDropdownItems = hasSiblings && modelerUrl
+                ? allOrgs.flatMap((o) => {
+                    const isCurrent = o.uuid === activeOrg.uuid;
+                    if (isCurrent) {
+                        return [
+                            {
+                                key: o.uuid,
+                                label: o.name,
+                                icon: Building,
+                                isSelected: true,
+                            },
+                        ];
+                    }
+                    const href = buildModelerOrgUrl(modelerUrl, o.uuid);
+                    if (!href)
+                        return [];
+                    return [
+                        {
+                            key: o.uuid,
+                            label: o.name,
+                            icon: Building,
+                            isSelected: false,
+                            linkProps: { href },
+                        },
+                    ];
+                })
+                : undefined;
             crumbs.push({
                 key: 'org',
                 label: activeOrg.name,
                 icon: Building,
-                ...(modelerUrl
-                    ? { linkProps: resolveLinkProps(modelerUrl, 'org') }
+                ...(modelerUrl ? { linkProps: { href: modelerUrl } } : {}),
+                ...(orgDropdownItems
+                    ? {
+                        dropdownTitle: 'Switch organization',
+                        dropdownAriaLabel: 'Switch organization',
+                        dropdownItems: orgDropdownItems,
+                    }
                     : {}),
             });
         }
         // ── Cluster crumb ──────────────────────────────────────────────────────
         if (currentCluster) {
-            const modelerUrl = currentCluster.endpoints?.modeler;
             const clusterUrl = modelerUrl
                 ? `${modelerUrl}?fromCluster=${currentCluster.uuid}`
                 : undefined;
+            const reachableClusters = (clusters ?? []).filter((c) => c.uuid === currentCluster.uuid ||
+                getEndpointForApp(currentApp, c.endpoints));
+            const hasSiblings = reachableClusters.filter((c) => c.uuid !== currentCluster.uuid).length >
+                0;
+            const clusterDropdownItems = hasSiblings
+                ? reachableClusters.map((c) => {
+                    const isCurrent = c.uuid === currentCluster.uuid;
+                    const stage = c.labels?.camunda?.[0];
+                    return {
+                        key: c.uuid,
+                        label: c.name,
+                        icon: CloudApp,
+                        isSelected: isCurrent,
+                        ...(isCurrent
+                            ? {}
+                            : {
+                                linkProps: {
+                                    href: getEndpointForApp(currentApp, c.endpoints) ?? '',
+                                },
+                            }),
+                        ...(stage
+                            ? { trailingElement: _jsx(C3ClusterTag, { stage: stage, subtle: true }) }
+                            : {}),
+                    };
+                })
+                : undefined;
             crumbs.push({
                 key: 'cluster',
                 label: currentCluster.name,
                 icon: CloudApp,
-                ...(clusterUrl
-                    ? { linkProps: resolveLinkProps(clusterUrl, 'cluster') }
+                ...(clusterUrl ? { linkProps: { href: clusterUrl } } : {}),
+                ...(clusterDropdownItems
+                    ? {
+                        dropdownTitle: 'Switch cluster',
+                        dropdownAriaLabel: 'Switch cluster',
+                        dropdownItems: clusterDropdownItems,
+                    }
                     : {}),
             });
         }
         // ── App crumb ──────────────────────────────────────────────────────────
-        const appLabel = getReadableAppName(currentApp);
-        const appIcon = APP_ICONS[currentApp];
-        const siblingApps = SWITCHABLE_APPS.filter((app) => app !== currentApp && currentCluster?.endpoints?.[app]);
-        const dropdownItems = siblingApps.length > 0
-            ? [
-                {
-                    key: currentApp,
-                    label: appLabel,
-                    icon: appIcon,
-                    isSelected: true,
-                },
-                ...siblingApps.map((app) => ({
+        // Resolve label/icon via the same admin↔identity aliasing the sidebar
+        // entries use (`useClusterSidebarEntries`), so older clusters that expose
+        // only `identity` render as "Identity" instead of disappearing.
+        // `SWITCHABLE_APPS` carries only the canonical `admin` key; consumers
+        // that pass `currentApp: 'identity'` (legacy code path) still match the
+        // switcher row via this normalisation, otherwise the current entry
+        // would be missing from the dropdown and nothing would be selected.
+        const switcherKey = isAdminApp(currentApp) ? 'admin' : currentApp;
+        const resolvedCurrentApp = isAdminApp(currentApp) && currentCluster
+            ? resolveAdminAppName(currentCluster)
+            : currentApp;
+        const appLabel = getReadableAppName(resolvedCurrentApp);
+        const appIcon = APP_ICONS[resolvedCurrentApp];
+        const reachableApps = currentCluster
+            ? SWITCHABLE_APPS.filter((app) => app === switcherKey ||
+                getEndpointForApp(app, currentCluster.endpoints))
+            : [switcherKey];
+        const hasSiblingApps = reachableApps.filter((app) => app !== switcherKey).length > 0;
+        const dropdownItems = hasSiblingApps && currentCluster
+            ? reachableApps.map((app) => {
+                const isCurrent = app === switcherKey;
+                const resolvedApp = isAdminApp(app)
+                    ? resolveAdminAppName(currentCluster)
+                    : app;
+                return {
                     key: app,
-                    label: getReadableAppName(app),
-                    icon: APP_ICONS[app],
-                    isSelected: false,
-                    linkProps: resolveLinkProps(currentCluster?.endpoints[app] ?? '', app),
-                })),
-            ]
+                    label: getReadableAppName(resolvedApp),
+                    icon: APP_ICONS[resolvedApp],
+                    isSelected: isCurrent,
+                    ...(isCurrent
+                        ? {}
+                        : {
+                            linkProps: {
+                                href: getEndpointForApp(app, currentCluster.endpoints) ?? '',
+                            },
+                        }),
+                };
+            })
             : undefined;
         crumbs.push({
             key: 'app',
@@ -105,5 +215,5 @@ export function useClusterWebappBreadcrumbs(options) {
                 : {}),
         });
         return crumbs;
-    }, [activeOrg, currentCluster, currentApp, resolveLinkProps]);
+    }, [activeOrg, orgs, clusters, currentCluster, currentApp]);
 }

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

@@ -15,8 +15,8 @@ export { C3LicenseTag, type C3LicenseTagProps, } from './components/c3-license-t
 export { default as C3Navigation } from './components/c3-navigation';
 export { C3NavigationAppProps, C3NavigationElementProps, C3NavigationNavBarElement, C3NavigationNavBarProps, C3NavigationNavBarSubElement, C3NavigationProps, } from './components/c3-navigation/c3-navigation.types';
 export { C3NavigationSideBarBaseProps } from './components/c3-navigation/c3-navigation-sidebar/c3-navigation-sidebar.types';
-export type { AppProps as C3NavV2AppProps, BreadcrumbDescriptor, BreadcrumbDropdownItem, BreadcrumbSegment, C3NavigationV2Props, C3NotificationsPanelProps, C3UserPanelProps, GlobalActionButton, GroupDescriptor, GroupItemDescriptor, HelpToolOptions, ItemDescriptor, LinkComponent, LinkProps, NotificationsToolOptions, SectionDescriptor, SidebarGroup, SidebarGroupItem, SidebarItem, SidebarNode, SidebarNodeDescriptor, SidebarProps, SidebarSection, ToolDescriptor, UseC3NavigationV2Options, UseC3NavigationV2Return, UseCamundaToolsOptions, UseClusterSidebarEntriesOptions, UserToolOptions, } from './components/c3-navigation-v2';
-export { C3BreadcrumbBar as preview_C3BreadcrumbBar, C3NavigationV2 as preview_C3NavigationV2, C3NotificationsPanel as preview_C3NotificationsPanel, C3Sidebar as preview_C3Sidebar, C3ToolsArea as preview_C3ToolsArea, C3UserPanel as preview_C3UserPanel, useC3NavigationV2 as preview_useC3NavigationV2, useCamundaTools as preview_useCamundaTools, useClusterSidebarEntries as preview_useClusterSidebarEntries, useClusterWebappBreadcrumbs as preview_useClusterWebappBreadcrumbs, } from './components/c3-navigation-v2';
+export type { AppProps as C3NavV2AppProps, BreadcrumbDescriptor, BreadcrumbDropdownItem, BreadcrumbSegment, C3NavigationV2Props, C3NotificationsPanelLabels, C3NotificationsPanelProps, C3ThemeSelectorLabels, C3ThemeSelectorProps, C3UserPanelLabels, C3UserPanelProps, GlobalActionButton, GroupDescriptor, GroupItemDescriptor, HelpToolOptions, ItemDescriptor, LinkComponent, LinkProps, NotificationsToolOptions, SectionDescriptor, SidebarGroup, SidebarGroupItem, SidebarItem, SidebarLabels, SidebarNode, SidebarNodeDescriptor, SidebarProps, SidebarSection, ToolDescriptor, UseC3NavigationV2Options, UseC3NavigationV2Return, UseCamundaToolsOptions, UseClusterSidebarEntriesOptions, UserToolOptions, } from './components/c3-navigation-v2';
+export { C3BreadcrumbBar as preview_C3BreadcrumbBar, C3NavigationV2 as preview_C3NavigationV2, C3NotificationsPanel as preview_C3NotificationsPanel, C3Sidebar as preview_C3Sidebar, C3ThemeSelector, C3ToolsArea as preview_C3ToolsArea, C3UserPanel as preview_C3UserPanel, useC3NavigationV2 as preview_useC3NavigationV2, useCamundaTools as preview_useCamundaTools, useClusterSidebarEntries as preview_useClusterSidebarEntries, useClusterWebappBreadcrumbs as preview_useClusterWebappBreadcrumbs, } from './components/c3-navigation-v2';
 export { C3BreadcrumbProps } from './components/c3-page/c3-breadcrumb/c3-breadcrumb.types';
 export { C3Page } from './components/c3-page/c3-page';
 export { C3PageProps } from './components/c3-page/c3-page.types';

package/lib/esm/src/index.js

@@ -13,7 +13,7 @@ export { C3HelpCenter } from './components/c3-help-center/c3-help-center.js';
 export { useC3HelpCenter } from './components/c3-help-center/c3-help-center-provider.js';
 export { C3LicenseTag, } from './components/c3-license-tag/index.js';
 export { default as C3Navigation } from './components/c3-navigation/index.js';
-export { C3BreadcrumbBar as preview_C3BreadcrumbBar, C3NavigationV2 as preview_C3NavigationV2, C3NotificationsPanel as preview_C3NotificationsPanel, C3Sidebar as preview_C3Sidebar, C3ToolsArea as preview_C3ToolsArea, C3UserPanel as preview_C3UserPanel, useC3NavigationV2 as preview_useC3NavigationV2, useCamundaTools as preview_useCamundaTools, useClusterSidebarEntries as preview_useClusterSidebarEntries, useClusterWebappBreadcrumbs as preview_useClusterWebappBreadcrumbs, } from './components/c3-navigation-v2/index.js';
+export { C3BreadcrumbBar as preview_C3BreadcrumbBar, C3NavigationV2 as preview_C3NavigationV2, C3NotificationsPanel as preview_C3NotificationsPanel, C3Sidebar as preview_C3Sidebar, C3ThemeSelector, C3ToolsArea as preview_C3ToolsArea, C3UserPanel as preview_C3UserPanel, useC3NavigationV2 as preview_useC3NavigationV2, useCamundaTools as preview_useCamundaTools, useClusterSidebarEntries as preview_useClusterSidebarEntries, useClusterWebappBreadcrumbs as preview_useClusterWebappBreadcrumbs, } from './components/c3-navigation-v2/index.js';
 export { C3Page } from './components/c3-page/c3-page.js';
 export { C3ResponsiveStack } from './components/c3-responsive-stack/c3-responsive-stack.js';
 export { useC3Profile } from './components/c3-user-configuration/c3-profile-provider/c3-profile-provider.js';