@camunda/camunda-composite-components 0.22.7 → 0.23.0

package/lib/esm/src/components/c3-navigation-v2/tools/c3-info-panel.d.ts

@@ -0,0 +1,11 @@
+import type { FC } from 'react';
+export interface InfoPanelElement {
+    key: string;
+    label: string;
+    onClick: () => void;
+}
+export interface C3InfoPanelProps {
+    elements: InfoPanelElement[];
+    title?: string;
+}
+export declare const C3InfoPanel: FC<C3InfoPanelProps>;

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

@@ -0,0 +1,33 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import styled from 'styled-components';
+import { PanelHeader, PanelTitle } from './panel-primitives.js';
+const LinkList = styled.ul `
+  list-style: none;
+  margin: 0;
+  padding: 0.5rem 0;
+`;
+const LinkItem = styled.li ``;
+const LinkButton = styled.button `
+  width: 100%;
+  padding: 0.625rem 1rem;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  color: var(--cds-link-primary);
+  font-size: var(--cds-body-01-font-size);
+  text-decoration: none;
+  transition: background 0.15s;
+
+  &:hover {
+    background: var(--cds-layer-hover);
+    color: var(--cds-link-primary-hover);
+    text-decoration: underline;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--cds-focus);
+    outline-offset: -2px;
+  }
+`;
+export const C3InfoPanel = ({ elements, title = 'Help & Resources', }) => (_jsxs(_Fragment, { children: [_jsx(PanelHeader, { children: _jsx(PanelTitle, { children: title }) }), _jsx(LinkList, { children: elements.map((el) => (_jsx(LinkItem, { children: _jsx(LinkButton, { onClick: el.onClick, children: el.label }) }, el.key))) })] }));

package/lib/esm/src/components/c3-navigation-v2/tools/c3-notifications-panel.d.ts

@@ -0,0 +1,6 @@
+import { type FC } from 'react';
+import type { Notification } from '../../../api/notifications';
+export interface C3NotificationsPanelProps {
+    onLinkClick?: (meta: Notification['meta']) => void;
+}
+export declare const C3NotificationsPanel: FC<C3NotificationsPanelProps>;

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

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs, 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 { Button } from '@carbon/react';
+import { useContext, useEffect } from 'react';
+import styled from 'styled-components';
+import { C3BellIcon } from '../../../assets/c3-icons.js';
+import C3NotificationContainer, { NotificationDescription, NotificationTitle, } from '../../c3-navigation/c3-notification-provider/c3-notification-container.js';
+import { C3NotificationContext } from '../../c3-navigation/c3-notification-provider/c3-notification-provider.js';
+import { PanelHeader, PanelTitle } from './panel-primitives.js';
+const DismissAllButton = styled(Button) `
+  font-size: var(--cds-helper-text-01-font-size);
+  font-weight: var(--cds-helper-text-01-font-weight);
+  line-height: var(--cds-helper-text-01-line-height);
+  letter-spacing: var(--cds-helper-text-01-letter-spacing);
+`;
+const EmptyState = styled.div `
+  padding: 16px;
+`;
+const EmptyStateTitle = styled(NotificationTitle) `
+  margin-top: 24px;
+`;
+const EmptyStateDescription = styled(NotificationDescription) `
+  color: var(--cds-text-secondary);
+  margin-top: 8px;
+`;
+const sortDescending = (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime();
+export const C3NotificationsPanel = ({ onLinkClick, }) => {
+    const { notifications, markAllAsRead, dismiss, dismissAll } = useContext(C3NotificationContext);
+    // C3NotificationContainer ignores its onRead prop; read-state is driven by
+    // panel open/close instead. Since the panel only mounts while its tool is
+    // active, one mount-time pass is enough.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only
+    useEffect(() => {
+        const unread = notifications.filter((n) => n.state === 'new');
+        if (unread.length)
+            markAllAsRead(unread);
+    }, []);
+    return (_jsxs(_Fragment, { children: [_jsxs(PanelHeader, { style: {
+                    width: '100%',
+                    height: 60,
+                    display: 'flex',
+                    flexDirection: 'row',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                }, children: [_jsx(PanelTitle, { children: "Notifications" }), notifications.length > 0 && (_jsx(DismissAllButton, { kind: 'ghost', size: 'sm', onClick: () => dismissAll(notifications), children: "Dismiss all" }))] }), notifications.length > 0 ? ([...notifications]
+                .sort(sortDescending)
+                .map((notification) => (_jsx(C3NotificationContainer, { onRead: () => undefined, onDismiss: () => dismiss(notification), originalOnLinkClick: onLinkClick, onLinkClick: () => onLinkClick?.(notification.meta), unread: false, ...notification }, notification.uuid)))) : (_jsxs(EmptyState, { children: [_jsx(C3BellIcon, { size: 56 }), _jsx(EmptyStateTitle, { children: "No notifications" }), _jsx(EmptyStateDescription, { children: "New updates regarding your processes, clusters and more will appear here." })] }))] }));
+};

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

@@ -0,0 +1,30 @@
+import type { FC, ReactNode } from 'react';
+export interface UserPanelElement {
+    key: string;
+    label: string;
+    onClick: () => void;
+}
+export interface C3UserPanelProps {
+    /** User's display name. */
+    name?: string;
+    /** User's email address. */
+    email?: string;
+    /** App version string shown at the bottom of the panel. */
+    version?: string;
+    /** Called when the user clicks "Log out". Omit to hide the button. */
+    onLogout?: () => void;
+    /** Internal toggle for production features (development use). */
+    stageToggle?: {
+        prodFeaturesEnabled: boolean;
+        toggle: () => void;
+    };
+    /** Arbitrary content rendered between the profile section and the link list. */
+    customSection?: ReactNode;
+    /**
+     * Additional link elements rendered above the built-in legal links
+     * (Terms of use, Privacy policy, Imprint). Elements whose `key` matches
+     * a built-in link (`terms`, `privacy`, `imprint`) replace the default.
+     */
+    elements?: UserPanelElement[];
+}
+export declare const C3UserPanel: FC<C3UserPanelProps>;

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

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs, 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 { Button, FormLabel, RadioButton, RadioButtonGroup, Stack, 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: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  border-bottom: 1px solid var(--cds-border-subtle);
+`;
+const ProfileName = styled.span `
+  font-size: var(--cds-body-01-font-size);
+  font-weight: 600;
+  color: var(--cds-text-primary);
+`;
+const ProfileEmail = styled.span `
+  font-size: var(--cds-label-01-font-size);
+  color: var(--cds-text-secondary);
+`;
+const ThemeSection = styled.div `
+  padding: 1rem;
+  border-bottom: 1px solid var(--cds-border-subtle);
+`;
+const CustomSection = styled.div `
+  border-bottom: 1px solid var(--cds-border-subtle);
+`;
+const ElementList = styled.ul `
+  list-style: none;
+  margin: 0;
+  padding: 0.5rem 0;
+`;
+const ElementItem = styled.li ``;
+const ElementButton = styled.button `
+  width: 100%;
+  padding: 0.625rem 1rem;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  color: var(--cds-link-primary);
+  font-size: var(--cds-body-01-font-size);
+  text-decoration: none;
+  transition: background 0.15s;
+
+  &:hover {
+    background: var(--cds-layer-hover);
+    color: var(--cds-link-primary-hover);
+    text-decoration: underline;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--cds-focus);
+    outline-offset: -2px;
+  }
+`;
+const BottomPinned = styled.div `
+  margin-top: auto;
+  display: flex;
+  flex-direction: column;
+`;
+const BottomActions = styled.div `
+  border-top: 1px solid var(--cds-border-subtle);
+  display: flex;
+  flex-direction: column;
+
+  .cds--btn {
+    max-width: none;
+    width: 100%;
+    justify-content: space-between;
+  }
+`;
+const VersionWrapper = styled.div `
+  padding: 0.5rem 1rem;
+`;
+const VersionText = styled.p `
+  color: var(--cds-text-primary);
+  font-size: var(--cds-label-02-font-size);
+  font-weight: var(--cds-label-02-font-weight);
+  line-height: var(--cds-label-02-line-height);
+  letter-spacing: var(--cds-label-02-letter-spacing);
+`;
+const Copyright = styled.p `
+  color: var(--cds-text-secondary);
+  font-size: var(--cds-label-01-font-size);
+  font-weight: var(--cds-label-01-font-weight);
+  line-height: var(--cds-label-01-line-height);
+  letter-spacing: var(--cds-label-01-letter-spacing);
+`;
+const LEGAL_LINKS = [
+    {
+        key: 'terms',
+        label: 'Terms of use',
+        onClick: () => window.open('https://camunda.com/legal/terms/camunda-platform/camunda-platform-8-saas-trial/', '_blank'),
+    },
+    {
+        key: 'privacy',
+        label: 'Privacy policy',
+        onClick: () => window.open('https://camunda.com/legal/privacy/', '_blank'),
+    },
+    {
+        key: 'imprint',
+        label: '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();
+    const consumerKeys = new Set((elements ?? []).map((e) => e.key));
+    const defaults = LEGAL_LINKS.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: {
+                    padding: '1rem',
+                    borderBottom: '1px solid var(--cds-border-subtle)',
+                }, 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" }) }))] })] }));
+};

package/lib/esm/src/components/c3-navigation-v2/tools/panel-primitives.d.ts

@@ -0,0 +1,7 @@
+import type { FC, HTMLAttributes, ReactNode } from 'react';
+export declare const PanelHeader: FC<HTMLAttributes<HTMLDivElement> & {
+    children?: ReactNode;
+}>;
+export declare const PanelTitle: FC<HTMLAttributes<HTMLSpanElement> & {
+    children?: ReactNode;
+}>;

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

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const headerStyle = {
+    background: 'var(--cds-layer-01)',
+    boxShadow: 'inset 0 -1px 0 var(--cds-border-subtle-01)',
+    padding: '24px 16px 13px',
+    flexShrink: 0,
+};
+const titleStyle = {
+    color: 'var(--cds-text-primary)',
+    fontSize: 'var(--cds-body-01-font-size)',
+    fontWeight: 'var(--cds-body-01-font-weight)',
+    lineHeight: 'var(--cds-body-01-line-height)',
+    letterSpacing: 'var(--cds-body-01-letter-spacing)',
+};
+export const PanelHeader = ({ style, ...props }) => (_jsx("div", { style: { ...headerStyle, ...style }, ...props }));
+export const PanelTitle = ({ style, ...props }) => (_jsx("span", { style: { ...titleStyle, ...style }, ...props }));

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

@@ -0,0 +1,115 @@
+import type { BreadcrumbAction, C3NavigationV2Props, GlobalActionButton, LinkComponent, LinkProps, ToolDescriptor } from './c3-navigation-v2.types';
+type ActiveMatcher = boolean | string | ((activeItemKey: string) => boolean);
+export interface ItemDescriptor {
+    type: 'item';
+    key: string;
+    label: string;
+    icon: React.ComponentType<{
+        size?: number;
+        style?: React.CSSProperties;
+    }>;
+    linkProps?: LinkProps;
+    onClick?: () => void;
+    isActive?: ActiveMatcher;
+    trailingElement?: React.ReactNode;
+}
+export interface GroupItemDescriptor {
+    type: 'group-item';
+    key: string;
+    label: string;
+    icon: React.ComponentType<{
+        size?: number;
+        style?: React.CSSProperties;
+    }>;
+    linkProps?: LinkProps;
+    onClick?: () => void;
+    trailingElement?: React.ReactNode;
+    defaultExpanded?: boolean;
+    isActive?: ActiveMatcher;
+    children: SidebarNodeDescriptor[];
+}
+export interface GroupDescriptor {
+    type: 'group';
+    key: string;
+    label: string;
+    icon: React.ComponentType<{
+        size?: number;
+        style?: React.CSSProperties;
+    }>;
+    trailingElement?: React.ReactNode;
+    defaultExpanded?: boolean;
+    children: SidebarNodeDescriptor[];
+}
+export interface SectionDescriptor {
+    type: 'section';
+    key: string;
+    title?: string;
+    children: SidebarNodeDescriptor[];
+    compact?: boolean;
+}
+export type SidebarNodeDescriptor = ItemDescriptor | GroupItemDescriptor | GroupDescriptor | SectionDescriptor;
+export interface BreadcrumbDropdownItemDescriptor {
+    key: string;
+    label: string;
+    icon?: React.ComponentType<{
+        size?: number;
+        style?: React.CSSProperties;
+    }>;
+    isSelected?: ActiveMatcher;
+    onClick?: () => void;
+    linkProps?: LinkProps;
+    trailingElement?: React.ReactNode;
+}
+export interface BreadcrumbDescriptor {
+    key: string;
+    label: string | ((activeItemKey: string) => string);
+    icon?: React.ComponentType<{
+        size?: number;
+        style?: React.CSSProperties;
+    }>;
+    onClick?: () => void;
+    linkProps?: LinkProps;
+    trailingElement?: React.ReactNode;
+    menuElement?: React.ReactNode;
+    actions?: BreadcrumbAction[];
+    dropdownTitle?: string;
+    dropdownAriaLabel?: string;
+    dropdownItems?: BreadcrumbDropdownItemDescriptor[];
+}
+export interface UseC3NavigationV2Options {
+    app: C3NavigationV2Props['app'];
+    skipToContentTargetId: string;
+    skipToContentLabel?: string;
+    headerAriaLabel?: string;
+    sidebarAriaLabel?: string;
+    /** Used to resolve `isActive` on sidebar items and `isSelected` on breadcrumb dropdown items. */
+    activeItemKey: string;
+    sidebarChildren?: SidebarNodeDescriptor[];
+    breadcrumbs?: BreadcrumbDescriptor[];
+    tools?: ToolDescriptor[];
+    globalActions?: GlobalActionButton[];
+    sidebarExpandedWidth?: string;
+    sidebarCollapsedWidth?: string;
+    defaultSidebarExpanded?: boolean;
+    onSidebarToggle?: (isExpanded: boolean) => void;
+    linkComponent?: LinkComponent;
+    headerTrailingContent?: React.ReactNode;
+}
+export interface UseC3NavigationV2Return {
+    navProps: C3NavigationV2Props;
+    isSidebarExpanded: boolean;
+    setSidebarExpanded: (expanded: boolean) => void;
+    expandedGroups: Set<string>;
+    toggleGroup: (groupKey: string) => void;
+    expandGroup: (groupKey: string) => void;
+    collapseGroup: (groupKey: string) => void;
+    activeToolKey: string | null;
+    setActiveToolKey: (key: string | null) => void;
+}
+/**
+ * State container and props assembler for `C3NavigationV2`. Manages sidebar
+ * expand/collapse, group expand state, tool panel state, and resolves
+ * descriptors (isActive, label functions) into concrete props.
+ */
+export declare function useC3NavigationV2(options: UseC3NavigationV2Options): UseC3NavigationV2Return;
+export {};

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

@@ -0,0 +1,216 @@
+/*
+ * 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 { useCallback, useMemo, useState } from 'react';
+function matchesActive(descriptor, activeItemKey) {
+    if (descriptor.isActive === undefined)
+        return descriptor.key === activeItemKey;
+    if (typeof descriptor.isActive === 'boolean')
+        return descriptor.isActive;
+    if (typeof descriptor.isActive === 'string')
+        return descriptor.isActive === activeItemKey;
+    return descriptor.isActive(activeItemKey);
+}
+function collectDefaultExpanded(nodes, out) {
+    for (const node of nodes) {
+        if ((node.type === 'group-item' || node.type === 'group') &&
+            node.defaultExpanded) {
+            out.add(node.key);
+        }
+        if ('children' in node) {
+            collectDefaultExpanded(node.children, out);
+        }
+    }
+}
+/**
+ * State container and props assembler for `C3NavigationV2`. Manages sidebar
+ * expand/collapse, group expand state, tool panel state, and resolves
+ * 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 [isSidebarExpanded, setIsSidebarExpanded] = useState(defaultSidebarExpanded);
+    const setSidebarExpanded = useCallback((expanded) => {
+        setIsSidebarExpanded(expanded);
+        onSidebarToggle?.(expanded);
+    }, [onSidebarToggle]);
+    const handleToggleSidebar = useCallback(() => {
+        setSidebarExpanded(!isSidebarExpanded);
+    }, [isSidebarExpanded, setSidebarExpanded]);
+    const [expandedGroups, setExpandedGroups] = useState(() => {
+        const initial = new Set();
+        collectDefaultExpanded(sidebarChildren, initial);
+        return initial;
+    });
+    const toggleGroup = useCallback((groupKey) => {
+        setExpandedGroups((prev) => {
+            const next = new Set(prev);
+            if (next.has(groupKey))
+                next.delete(groupKey);
+            else
+                next.add(groupKey);
+            return next;
+        });
+    }, []);
+    const expandGroup = useCallback((groupKey) => {
+        setExpandedGroups((prev) => {
+            if (prev.has(groupKey))
+                return prev;
+            const next = new Set(prev);
+            next.add(groupKey);
+            return next;
+        });
+    }, []);
+    const collapseGroup = useCallback((groupKey) => {
+        setExpandedGroups((prev) => {
+            if (!prev.has(groupKey))
+                return prev;
+            const next = new Set(prev);
+            next.delete(groupKey);
+            return next;
+        });
+    }, []);
+    const [activeToolKey, setActiveToolKey] = useState(null);
+    const handleActiveToolChange = useCallback((key) => setActiveToolKey(key), []);
+    const resolveNodes = useCallback((descriptors) => descriptors.map((desc) => {
+        switch (desc.type) {
+            case 'item':
+                return {
+                    type: 'item',
+                    key: desc.key,
+                    label: desc.label,
+                    icon: desc.icon,
+                    isActive: matchesActive(desc, activeItemKey),
+                    onClick: desc.onClick,
+                    linkProps: desc.linkProps,
+                    trailingElement: desc.trailingElement,
+                };
+            case 'group-item':
+                return {
+                    type: 'group-item',
+                    key: desc.key,
+                    label: desc.label,
+                    icon: desc.icon,
+                    isActive: matchesActive(desc, activeItemKey),
+                    onClick: desc.onClick,
+                    linkProps: desc.linkProps,
+                    trailingElement: desc.trailingElement,
+                    isExpanded: expandedGroups.has(desc.key),
+                    onToggleExpand: () => toggleGroup(desc.key),
+                    children: resolveNodes(desc.children),
+                };
+            case 'group':
+                return {
+                    type: 'group',
+                    key: desc.key,
+                    label: desc.label,
+                    icon: desc.icon,
+                    trailingElement: desc.trailingElement,
+                    isExpanded: expandedGroups.has(desc.key),
+                    onToggleExpand: () => {
+                        if (!isSidebarExpanded) {
+                            setSidebarExpanded(true);
+                            expandGroup(desc.key);
+                        }
+                        else {
+                            toggleGroup(desc.key);
+                        }
+                    },
+                    children: resolveNodes(desc.children),
+                };
+            case 'section':
+                return {
+                    type: 'section',
+                    key: desc.key,
+                    title: desc.title,
+                    compact: desc.compact,
+                    children: resolveNodes(desc.children),
+                };
+            default:
+                return desc;
+        }
+    }), [
+        activeItemKey,
+        expandedGroups,
+        toggleGroup,
+        expandGroup,
+        isSidebarExpanded,
+        setSidebarExpanded,
+    ]);
+    const resolvedChildren = useMemo(() => resolveNodes(sidebarChildren), [resolveNodes, sidebarChildren]);
+    const resolvedBreadcrumbs = useMemo(() => breadcrumbs.map((desc) => ({
+        key: desc.key,
+        label: typeof desc.label === 'function'
+            ? desc.label(activeItemKey)
+            : desc.label,
+        icon: desc.icon,
+        onClick: desc.onClick,
+        linkProps: desc.linkProps,
+        trailingElement: desc.trailingElement,
+        menuElement: desc.menuElement,
+        actions: desc.actions,
+        dropdownTitle: desc.dropdownTitle,
+        dropdownAriaLabel: desc.dropdownAriaLabel,
+        dropdownItems: desc.dropdownItems?.map((item) => ({
+            key: item.key,
+            label: item.label,
+            icon: item.icon,
+            isSelected: matchesActive({ key: item.key, isActive: item.isSelected }, activeItemKey),
+            onClick: item.onClick,
+            linkProps: item.linkProps,
+            trailingElement: item.trailingElement,
+        })),
+    })), [breadcrumbs, activeItemKey]);
+    const hasSidebar = sidebarChildren.length > 0;
+    const sidebarProps = hasSidebar
+        ? {
+            ariaLabel: sidebarAriaLabel,
+            children: resolvedChildren,
+            isExpanded: isSidebarExpanded,
+            onToggleExpanded: handleToggleSidebar,
+            expandedWidth: sidebarExpandedWidth,
+            collapsedWidth: sidebarCollapsedWidth,
+            linkComponent,
+        }
+        : undefined;
+    const navProps = useMemo(() => ({
+        app,
+        skipToContentTargetId,
+        skipToContentLabel,
+        headerAriaLabel,
+        breadcrumbs: resolvedBreadcrumbs,
+        tools,
+        globalActions,
+        sidebar: sidebarProps,
+        linkComponent,
+        headerTrailingContent,
+        activeToolKey,
+        onActiveToolChange: handleActiveToolChange,
+    }), [
+        app,
+        skipToContentTargetId,
+        skipToContentLabel,
+        headerAriaLabel,
+        resolvedBreadcrumbs,
+        tools,
+        globalActions,
+        sidebarProps,
+        linkComponent,
+        headerTrailingContent,
+        activeToolKey,
+        handleActiveToolChange,
+    ]);
+    return {
+        navProps,
+        isSidebarExpanded,
+        setSidebarExpanded,
+        expandedGroups,
+        toggleGroup,
+        expandGroup,
+        collapseGroup,
+        activeToolKey,
+        setActiveToolKey,
+    };
+}

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

@@ -0,0 +1,49 @@
+import type { Notification } from '../../api/notifications';
+import type { ToolDescriptor } from './c3-navigation-v2.types';
+import { type InfoPanelElement } from './tools/c3-info-panel';
+import { type C3UserPanelProps } from './tools/c3-user-panel';
+export interface NotificationsToolOptions {
+    onLinkClick?: (meta: Notification['meta']) => void;
+    ariaLabel?: string;
+}
+export type UserToolOptions = C3UserPanelProps & {
+    ariaLabel?: string;
+};
+export interface HelpToolOptions {
+    onClick: () => void;
+    ariaLabel?: string;
+}
+export interface InfoToolOptions {
+    elements: InfoPanelElement[];
+    title?: string;
+    ariaLabel?: string;
+}
+export interface UseCamundaToolsOptions {
+    /**
+     * Notifications tool with a right-side panel. Omit to hide; pass `{}` for
+     * defaults, or an options object to customise behaviour.
+     */
+    notifications?: NotificationsToolOptions;
+    /**
+     * User/account tool with a right-side panel. Omit to hide; pass `{}` for
+     * defaults, or options with profile/version/stageToggle/customSection.
+     */
+    user?: UserToolOptions;
+    /**
+     * Info/help panel with a list of link elements (docs, academy, support…).
+     * Consumer provides the elements; C3 renders the panel.
+     */
+    info?: InfoToolOptions;
+    /**
+     * Help button with no panel. Consumer provides the onClick action.
+     */
+    help?: HelpToolOptions;
+}
+/**
+ * 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.
+ *
+ * Must be called within a C3UserConfigurationProvider tree (SaaS).
+ */
+export declare const useCamundaTools: (options: UseCamundaToolsOptions) => ToolDescriptor[];