@aircall/blocks 0.17.0 → 0.18.1

package/dist/index.js

@@ -1,15 +1,15 @@
-import { Anchor, Badge, Button, CounterBadge, DropdownMenu, DropdownMenuAddon, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Field, FieldContent, FieldDescription, FieldError, FieldLabel, FieldLabelAside, FieldLabelInfo, FieldLabelRow, HoverCard, HoverCardContent, HoverCardTrigger, InputGroup, InputGroupButton, InputGroupTextarea, Item, ItemActions, ItemContent, ItemGroup, ItemMedia, ItemTitle, Popover, PopoverContent, PopoverTrigger, Separator, Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarProvider, Spinner, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TabsList, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipTrigger, cn, registerI18nNamespace, useDsLocale, useDsTranslation, useSidebar } from "@aircall/ds";
+import { Anchor, Badge, Button, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle, CounterBadge, DropdownMenu, DropdownMenuAddon, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Field, FieldContent, FieldDescription, FieldError, FieldLabel, FieldLabelAside, FieldLabelInfo, FieldLabelRow, HoverCard, HoverCardContent, HoverCardTrigger, InputGroup, InputGroupButton, InputGroupTextarea, Item, ItemActions, ItemContent, ItemGroup, ItemMedia, ItemTitle, Popover, PopoverContent, PopoverTrigger, Separator, Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarProvider, Skeleton, Spinner, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TabsList, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipTrigger, cn, registerI18nNamespace, useDsLocale, useDsTranslation, useSidebar } from "@aircall/ds";
 import * as React from "react";
 import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { AircallLoader, AircallLogo, AircallMark, ArrowUp, Check, ChevronDown, ChevronLeft, ChevronRight, Copy, Ellipsis, ExternalLink, FileText, Frown, History, LockKeyhole, Meh, Menu, MessageSquare, Minus, PanelLeft, PanelLeftClose, PanelLeftOpen, Plus, Search, Settings, Smile, Sprout, Square, SquareArrowOutUpRight, ThumbsDown, ThumbsDownFilled, ThumbsUp, ThumbsUpFilled, TriangleAlert } from "@aircall/react-icons";
+import { AircallLoader, AircallLogo, AircallMark, ArrowDownRight, ArrowUp, ArrowUpRight, Check, ChevronDown, ChevronLeft, ChevronRight, Copy, Ellipsis, ExternalLink, FileText, Frown, History, LockKeyhole, Meh, Menu, MessageSquare, Minus, PanelLeft, PanelLeftClose, PanelLeftOpen, Plus, Search, Settings, Smile, Sprout, Square, SquareArrowOutUpRight, ThumbsDown, ThumbsDownFilled, ThumbsUp, ThumbsUpFilled, TriangleAlert } from "@aircall/react-icons";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { useCallbackRef, useControllableState, useIsMounted, useUnmount } from "@aircall/hooks";
 import { cva } from "class-variance-authority";
-import { createFormHook, createFormHookContexts } from "@tanstack/react-form";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
+import { createFormHook, createFormHookContexts } from "@tanstack/react-form";
 
 //#region src/i18n/locales/de.ts
 const de = {
@@ -360,6 +360,7 @@ const EmptyStateMedia = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 EmptyStateMedia.displayName = "EmptyStateMedia";
+/** Title line of an empty state. Wraps the DS `EmptyTitle`. */
 const EmptyStateTitle = React.forwardRef((componentProps, forwardRef) => {
 	return /* @__PURE__ */ jsx(EmptyTitle, {
 		ref: forwardRef,
@@ -367,6 +368,7 @@ const EmptyStateTitle = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 EmptyStateTitle.displayName = "EmptyStateTitle";
+/** Supporting description text of an empty state. Wraps the DS `EmptyDescription`. */
 const EmptyStateDescription = React.forwardRef((componentProps, forwardRef) => {
 	return /* @__PURE__ */ jsx(EmptyDescription, {
 		ref: forwardRef,
@@ -388,6 +390,11 @@ const EmptyStateActions = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 EmptyStateActions.displayName = "EmptyStateActions";
+/**
+* Action button for an empty state — the only button allowed inside one. Wraps
+* the DS `Button` with `size` locked to `default` for visual consistency across
+* empty states; consumers still choose the `variant`.
+*/
 const EmptyStateButton = React.forwardRef((componentProps, forwardRef) => {
 	return /* @__PURE__ */ jsx(Button, {
 		ref: forwardRef,
@@ -396,6 +403,13 @@ const EmptyStateButton = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 EmptyStateButton.displayName = "EmptyStateButton";
+/**
+* External "Learn more"-style link for an empty state. Renders a real `<a>` (via
+* `EmptyStateButton` with `variant="link"`) that opens in a new tab. Pass
+* `children` to override the default "Learn more" label, including any icon.
+*
+* @default children "Learn more"
+*/
 const EmptyStateExternalLink = React.forwardRef((componentProps, forwardRef) => {
 	const { href, children = "Learn more", ...props } = componentProps;
 	return /* @__PURE__ */ jsx(EmptyStateButton, {
@@ -411,6 +425,11 @@ const EmptyStateExternalLink = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 EmptyStateExternalLink.displayName = "EmptyStateExternalLink";
+/**
+* Builds one preset's per-variant parts (`Root`, `Media`, `Title`, `Description`)
+* from its icon, default copy, and a11y role. Returns an object of `forwardRef`
+* components that reuse the shared empty-state parts; renders no DOM itself.
+*/
 function createEmptyStateVariant(config) {
 	const Root = React.forwardRef((componentProps, forwardRef) => /* @__PURE__ */ jsx(EmptyState, {
 		ref: forwardRef,
@@ -452,10 +471,18 @@ function createEmptyStateVariant(config) {
 
 //#endregion
 //#region src/components/coming-soon.tsx
+const ComingSoon = createEmptyStateVariant({
+	name: "ComingSoon",
+	icon: /* @__PURE__ */ jsx(Sprout, {}),
+	titleKey: "emptyState.comingSoon.title",
+	descriptionKey: "emptyState.comingSoon.description"
+});
 /**
-* ComingSoon — empty state shown when a feature exists in the UI but is not yet
-* available. Compose it from its parts:
+* Root of the "Coming soon" empty state — shown when a feature exists in the UI
+* but is not yet available. Renders a `<div>` (the DS `Empty` container); compose
+* it from its parts.
 *
+* @example
 * ```tsx
 * <ComingSoonEmptyState>
 *   <EmptyStateHeader>
@@ -469,62 +496,87 @@ function createEmptyStateVariant(config) {
 *   </EmptyStateActions>
 * </ComingSoonEmptyState>
 * ```
-*
-* `ComingSoonTitle` / `ComingSoonDescription` render the design copy by default;
-* pass children to override (e.g. for i18n).
 */
-const ComingSoon = createEmptyStateVariant({
-	name: "ComingSoon",
-	icon: /* @__PURE__ */ jsx(Sprout, {}),
-	titleKey: "emptyState.comingSoon.title",
-	descriptionKey: "emptyState.comingSoon.description"
-});
 const ComingSoonEmptyState = ComingSoon.Root;
+/** Decorative media slot of the "Coming soon" empty state (a sprout icon). Renders a `<div>`, hidden from assistive tech. */
 const ComingSoonMedia = ComingSoon.Media;
+/** Title line of the "Coming soon" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const ComingSoonTitle = ComingSoon.Title;
+/** Supporting description text of the "Coming soon" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const ComingSoonDescription = ComingSoon.Description;
 
 //#endregion
 //#region src/components/restricted-access.tsx
-/**
-* RestrictedAccess — shown when the user lacks permission to view a page.
-* Pair it with an `EmptyStateExternalLink` for the "Learn more" action.
-*/
 const RestrictedAccess = createEmptyStateVariant({
 	name: "RestrictedAccess",
 	icon: /* @__PURE__ */ jsx(LockKeyhole, {}),
 	titleKey: "emptyState.restrictedAccess.title",
 	descriptionKey: "emptyState.restrictedAccess.description"
 });
+/**
+* Root of the "Restricted access" empty state — shown when the user lacks
+* permission to view a page. Renders a `<div>` (the DS `Empty` container); pair
+* it with an `EmptyStateExternalLink` for the "Learn more" action.
+*
+* @example
+* ```tsx
+* <RestrictedAccessEmptyState>
+*   <EmptyStateHeader>
+*     <RestrictedAccessMedia />
+*     <RestrictedAccessTitle />
+*     <RestrictedAccessDescription />
+*   </EmptyStateHeader>
+*   <EmptyStateActions>
+*     <EmptyStateExternalLink href={docsUrl} />
+*   </EmptyStateActions>
+* </RestrictedAccessEmptyState>
+* ```
+*/
 const RestrictedAccessEmptyState = RestrictedAccess.Root;
+/** Decorative media slot of the "Restricted access" empty state (a locked padlock icon). Renders a `<div>`, hidden from assistive tech. */
 const RestrictedAccessMedia = RestrictedAccess.Media;
+/** Title line of the "Restricted access" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const RestrictedAccessTitle = RestrictedAccess.Title;
+/** Supporting description text of the "Restricted access" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const RestrictedAccessDescription = RestrictedAccess.Description;
 
 //#endregion
 //#region src/components/not-found.tsx
-/**
-* NotFound — shown when a page/route cannot be found. Pair it with an
-* `EmptyStateButton` for the navigation action (e.g. "Go to inbox").
-*/
 const NotFound = createEmptyStateVariant({
 	name: "NotFound",
 	icon: /* @__PURE__ */ jsx(Search, {}),
 	titleKey: "emptyState.notFound.title",
 	descriptionKey: "emptyState.notFound.description"
 });
+/**
+* Root of the "Not found" empty state — shown when a page or route cannot be
+* found. Renders a `<div>` (the DS `Empty` container); pair it with an
+* `EmptyStateButton` for the navigation action (e.g. "Go to inbox").
+*
+* @example
+* ```tsx
+* <NotFoundEmptyState>
+*   <EmptyStateHeader>
+*     <NotFoundMedia />
+*     <NotFoundTitle />
+*     <NotFoundDescription />
+*   </EmptyStateHeader>
+*   <EmptyStateActions>
+*     <EmptyStateButton onClick={goToInbox}>Go to inbox</EmptyStateButton>
+*   </EmptyStateActions>
+* </NotFoundEmptyState>
+* ```
+*/
 const NotFoundEmptyState = NotFound.Root;
+/** Decorative media slot of the "Not found" empty state (a search icon). Renders a `<div>`, hidden from assistive tech. */
 const NotFoundMedia = NotFound.Media;
+/** Title line of the "Not found" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NotFoundTitle = NotFound.Title;
+/** Supporting description text of the "Not found" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NotFoundDescription = NotFound.Description;
 
 //#endregion
 //#region src/components/no-data.tsx
-/**
-* NoData — shown when a search or filter returns no results. Pair it with an
-* `EmptyStateButton` for the "Reset" action. Appears in response to a user
-* action, so it announces politely via `role="status"`.
-*/
 const NoData = createEmptyStateVariant({
 	name: "NoData",
 	icon: /* @__PURE__ */ jsx(Search, {}),
@@ -532,35 +584,71 @@ const NoData = createEmptyStateVariant({
 	descriptionKey: "emptyState.noData.description",
 	role: "status"
 });
+/**
+* Root of the "No data" empty state — shown when a search or filter returns no
+* results. Renders a `<div>` (the DS `Empty` container) with `role="status"` so
+* it announces politely after a user action; pair it with an `EmptyStateButton`
+* for the "Reset" action.
+*
+* @example
+* ```tsx
+* <NoDataEmptyState>
+*   <EmptyStateHeader>
+*     <NoDataMedia />
+*     <NoDataTitle />
+*     <NoDataDescription />
+*   </EmptyStateHeader>
+*   <EmptyStateActions>
+*     <EmptyStateButton variant="outline" onClick={resetFilters}>Reset</EmptyStateButton>
+*   </EmptyStateActions>
+* </NoDataEmptyState>
+* ```
+*/
 const NoDataEmptyState = NoData.Root;
+/** Decorative media slot of the "No data" empty state (a search icon). Renders a `<div>`, hidden from assistive tech. */
 const NoDataMedia = NoData.Media;
+/** Title line of the "No data" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NoDataTitle = NoData.Title;
+/** Supporting description text of the "No data" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NoDataDescription = NoData.Description;
 
 //#endregion
 //#region src/components/no-support.tsx
-/**
-* NoSupport — shown when the current browser can't render a page. Pair it with
-* an `EmptyStateExternalLink` for the "Learn more" action.
-*/
 const NoSupport = createEmptyStateVariant({
 	name: "NoSupport",
 	icon: /* @__PURE__ */ jsx(Settings, {}),
 	titleKey: "emptyState.noSupport.title",
 	descriptionKey: "emptyState.noSupport.description"
 });
+/**
+* Root of the "No support" empty state — shown when the current browser can't
+* render a page. Renders a `<div>` (the DS `Empty` container); pair it with an
+* `EmptyStateExternalLink` for the "Learn more" action.
+*
+* @example
+* ```tsx
+* <NoSupportEmptyState>
+*   <EmptyStateHeader>
+*     <NoSupportMedia />
+*     <NoSupportTitle />
+*     <NoSupportDescription />
+*   </EmptyStateHeader>
+*   <EmptyStateActions>
+*     <EmptyStateExternalLink href={docsUrl} />
+*   </EmptyStateActions>
+* </NoSupportEmptyState>
+* ```
+*/
 const NoSupportEmptyState = NoSupport.Root;
+/** Decorative media slot of the "No support" empty state (a settings icon). Renders a `<div>`, hidden from assistive tech. */
 const NoSupportMedia = NoSupport.Media;
+/** Title line of the "No support" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NoSupportTitle = NoSupport.Title;
+/** Supporting description text of the "No support" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const NoSupportDescription = NoSupport.Description;
 
 //#endregion
 //#region src/components/unknown-error.tsx
-/**
-* UnknownError — shown when content fails to load unexpectedly. Pair it with an
-* `EmptyStateButton` (primary) for the "Try again" action. As an error state it
-* announces assertively via `role="alert"`.
-*/
 const UnknownError = createEmptyStateVariant({
 	name: "UnknownError",
 	icon: /* @__PURE__ */ jsx(TriangleAlert, {}),
@@ -568,9 +656,32 @@ const UnknownError = createEmptyStateVariant({
 	descriptionKey: "emptyState.unknownError.description",
 	role: "alert"
 });
+/**
+* Root of the "Unknown error" empty state — shown when content fails to load
+* unexpectedly. Renders a `<div>` (the DS `Empty` container) with `role="alert"`
+* so it announces assertively; pair it with a primary `EmptyStateButton` for the
+* "Try again" action.
+*
+* @example
+* ```tsx
+* <UnknownErrorEmptyState>
+*   <EmptyStateHeader>
+*     <UnknownErrorMedia />
+*     <UnknownErrorTitle />
+*     <UnknownErrorDescription />
+*   </EmptyStateHeader>
+*   <EmptyStateActions>
+*     <EmptyStateButton onClick={retry}>Try again</EmptyStateButton>
+*   </EmptyStateActions>
+* </UnknownErrorEmptyState>
+* ```
+*/
 const UnknownErrorEmptyState = UnknownError.Root;
+/** Decorative media slot of the "Unknown error" empty state (a warning triangle icon). Renders a `<div>`, hidden from assistive tech. */
 const UnknownErrorMedia = UnknownError.Media;
+/** Title line of the "Unknown error" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const UnknownErrorTitle = UnknownError.Title;
+/** Supporting description text of the "Unknown error" empty state. Renders a `<div>` with the design copy by default; pass children to override. */
 const UnknownErrorDescription = UnknownError.Description;
 
 //#endregion
@@ -904,6 +1015,19 @@ function useCopyButtonContext() {
 	if (ctx === null) throw new Error("CopyButtonIcon and CopyButtonLabel must be rendered inside a CopyButton.");
 	return ctx;
 }
+/**
+* Copy-to-clipboard button. Composes DS `Button`; copies `value` on click and
+* exposes a `copied` state (auto-reset after `timeout`) to its `CopyButtonIcon`
+* and `CopyButtonLabel` children via context. Renders a `<button>`.
+*
+* @example
+* ```tsx
+* <CopyButton value="npm i @aircall/ds">
+*   <CopyButtonIcon />
+*   <CopyButtonLabel />
+* </CopyButton>
+* ```
+*/
 const CopyButton = React.forwardRef((componentProps, forwardRef) => {
 	const { value, timeout, onCopied, variant = "outline", children, ...buttonProps } = componentProps;
 	const { copy, copied } = useCopyToClipboard(value, {
@@ -924,6 +1048,10 @@ const CopyButton = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 CopyButton.displayName = "CopyButton";
+/**
+* Icon for `CopyButton` that swaps between a copy glyph and a check glyph based on
+* the parent's copied state. Renders an `<svg>`. Must be used inside a `CopyButton`.
+*/
 const CopyButtonIcon = React.forwardRef((componentProps, forwardRef) => {
 	const { className } = componentProps;
 	const { copied } = useCopyButtonContext();
@@ -933,6 +1061,10 @@ const CopyButtonIcon = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 CopyButtonIcon.displayName = "CopyButtonIcon";
+/**
+* Text label for `CopyButton` that shows `label` normally and `copiedLabel` after a
+* successful copy. Renders a `<span>`. Must be used inside a `CopyButton`.
+*/
 const CopyButtonLabel = React.forwardRef((componentProps, forwardRef) => {
 	const { label = "Copy", copiedLabel = "Copied", className } = componentProps;
 	const { copied } = useCopyButtonContext();
@@ -1039,6 +1171,22 @@ const MARKDOWN_COMPONENTS = {
 		...props
 	})
 };
+/**
+* Renders a chatbot response from markdown, splitting it into markdown text and
+* embedded component blocks (table, audio, transcript, loading), with a sources
+* hover card and copy / thumbs-up / thumbs-down feedback controls. Renders a
+* `<div>` (`data-slot="chatbot-response-block"`).
+*
+* @example
+* ```tsx
+* <ChatbotResponseBlock
+*   messageId="msg-1"
+*   markdown="**Hello** from the assistant"
+*   sources={[{ title: 'Help center', url: 'https://help.aircall.io' }]}
+*   onFeedback={value => console.log(value)}
+* />
+* ```
+*/
 function ChatbotResponseBlock({ messageId, markdown, streaming = false, sources, onFeedback, className }) {
 	const t = useDsTranslation("blocks");
 	const [feedback, setFeedback] = useState(null);
@@ -1156,6 +1304,26 @@ function ChatbotResponseLoading({ text, className }) {
 
 //#endregion
 //#region src/components/chatbot-page.tsx
+/**
+* Root layout shell for the AI chatbot experience; provides the `SidebarProvider`
+* context required by `ChatbotSidebar` and lays out the sidebar and content
+* columns. Renders a `SidebarProvider` (a `<div>` wrapper) with the sidebar width
+* preset and full-height overrides for panel/modal contexts.
+*
+* @example
+* ```tsx
+* <ChatbotPage>
+*   <ChatbotSidebar conversations={[...]} />
+*   <ChatbotPageContent>
+*     <ChatbotPageBody>
+*       <ChatbotPageHeading>Need help?</ChatbotPageHeading>
+*       <ChatbotInput />
+*     </ChatbotPageBody>
+*     <ChatbotPageFooter betaTermsHref="https://legal.aircall.io/..." />
+*   </ChatbotPageContent>
+* </ChatbotPage>
+* ```
+*/
 const ChatbotPage = React.forwardRef((componentProps, forwardRef) => {
 	const { children, className } = componentProps;
 	return /* @__PURE__ */ jsx(SidebarProvider, {
@@ -1474,6 +1642,19 @@ function ChatbotPanelHeader({ title = "Ask Aircall", onMenu, menuContent, menuOp
 //#region src/components/chatbot-sidebar.tsx
 const SIDEBAR_MIN_WIDTH = 140;
 const SIDEBAR_MAX_WIDTH = 480;
+/**
+* Conversation-history sidebar: an optional "New Chat" entry plus a scrollable,
+* resizable list of recent conversations, each with an optional trailing ⋯ menu.
+* Renders the DS `Sidebar` (a `<div>`), or a plain `<div>` when `popup`. Must be
+* rendered inside a `SidebarProvider`.
+*
+* @example
+* ```tsx
+* <SidebarProvider>
+*   <ChatbotSidebar conversations={items} onSelectConversation={open} />
+* </SidebarProvider>
+* ```
+*/
 const ChatbotSidebar = React.forwardRef((componentProps, forwardRef) => {
 	const { conversations, activeConversationId, onNewChat, onSelectConversation, renderConversationMenuContent, recentLabel = "Recent", showNewChat = true, popup = false, className } = componentProps;
 	const t = useDsTranslation("blocks");
@@ -1565,6 +1746,17 @@ ChatbotSidebar.displayName = "ChatbotSidebar";
 
 //#endregion
 //#region src/components/chatbot-panel-suggestion.tsx
+/**
+* Pill-shaped prompt suggestion shown in the chatbot panel; a preset styling of
+* `Button` with a green border and surface background. Renders a `<button>`.
+*
+* @example
+* ```tsx
+* <ChatbotPanelSuggestion onClick={() => ask('How do I set my phone line?')}>
+*   How do I set my phone line?
+* </ChatbotPanelSuggestion>
+* ```
+*/
 function ChatbotPanelSuggestion({ className, ...props }) {
 	return /* @__PURE__ */ jsx(Button, {
 		"data-slot": "chatbot-panel-suggestion",
@@ -1597,6 +1789,18 @@ const textareaVariants = cva([
 		expanded: false
 	}
 });
+/**
+* Chatbot message composer: an auto-growing `InputGroup` textarea with a send/stop
+* button, plus optional suggestion pills and a conversation-history popover. Works
+* controlled (`value` + `onValueChange`) or uncontrolled. Enter submits;
+* Shift+Enter inserts a newline. Renders the DS `InputGroup` (a `<div>`) wrapping a
+* `<textarea>`.
+*
+* @example
+* ```tsx
+* <ChatbotInput value={text} onValueChange={setText} onSubmit={send} />
+* ```
+*/
 function ChatbotInput({ className, value, onValueChange, onSubmit, onStop, placeholder, loading = false, size = "default", expanded = false, disabled, suggestions, onSuggestionClick, conversations, activeConversationId, onSelectConversation, ...textareaProps }) {
 	const t = useDsTranslation("blocks");
 	const [currentValue = "", setCurrentValue] = useControllableState({
@@ -1715,6 +1919,16 @@ function ChatbotInput({ className, value, onValueChange, onSubmit, onStop, place
 
 //#endregion
 //#region src/components/chatbot-user-message.tsx
+/**
+* Right-aligned chat bubble for a user's message; clamps long content to six
+* lines with a "Show more" / "Show less" toggle. Renders a `<div>`
+* (`data-slot="chatbot-user-message"`).
+*
+* @example
+* ```tsx
+* <ChatbotUserMessage>How do I set up my phone number?</ChatbotUserMessage>
+* ```
+*/
 function ChatbotUserMessage({ className, children, ...props }) {
 	const [expanded, setExpanded] = useState(false);
 	const [showToggle, setShowToggle] = useState(false);
@@ -1744,6 +1958,25 @@ function ChatbotUserMessage({ className, children, ...props }) {
 
 //#endregion
 //#region src/components/dashboard-standalone-page.tsx
+/**
+* Full-screen takeover shell for focused, sidebar-less flows; renders a flex-row `<div>`
+* holding one or more `DashboardStandalonePageContent` panels side by side.
+*
+* @example
+* ```tsx
+* <DashboardStandalonePage>
+*   <DashboardStandalonePageContent>
+*     <DashboardStandalonePageHeader>
+*       <DashboardStandalonePageTitle>Create user</DashboardStandalonePageTitle>
+*       <DashboardStandalonePageActions side="start">
+*         <DashboardStandalonePageAction>Cancel</DashboardStandalonePageAction>
+*       </DashboardStandalonePageActions>
+*     </DashboardStandalonePageHeader>
+*     <DashboardStandalonePageMain>…</DashboardStandalonePageMain>
+*   </DashboardStandalonePageContent>
+* </DashboardStandalonePage>
+* ```
+*/
 const DashboardStandalonePage = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1754,6 +1987,10 @@ const DashboardStandalonePage = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardStandalonePage.displayName = "DashboardStandalonePage";
+/**
+* Rounded, bordered content panel that fills the shell; renders a `<div>`.
+* Typically wraps a `DashboardStandalonePageHeader` above a `DashboardStandalonePageMain`.
+*/
 const DashboardStandalonePageContent = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1764,6 +2001,10 @@ const DashboardStandalonePageContent = React.forwardRef((componentProps, forward
 	});
 });
 DashboardStandalonePageContent.displayName = "DashboardStandalonePageContent";
+/**
+* Fixed-height (64px) header bar with an optically centered title and absolutely
+* positioned action slots; renders a `<header>`.
+*/
 const DashboardStandalonePageHeader = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("header", {
@@ -1774,6 +2015,9 @@ const DashboardStandalonePageHeader = React.forwardRef((componentProps, forwardR
 	});
 });
 DashboardStandalonePageHeader.displayName = "DashboardStandalonePageHeader";
+/**
+* Centered, truncated page title in the header; renders an `<h1>`.
+*/
 const DashboardStandalonePageTitle = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("h1", {
@@ -1784,6 +2028,9 @@ const DashboardStandalonePageTitle = React.forwardRef((componentProps, forwardRe
 	});
 });
 DashboardStandalonePageTitle.displayName = "DashboardStandalonePageTitle";
+/**
+* Optional subtitle stacked beneath the title in the header; renders a `<p>`.
+*/
 const DashboardStandalonePageDescription = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("p", {
@@ -1794,6 +2041,10 @@ const DashboardStandalonePageDescription = React.forwardRef((componentProps, for
 	});
 });
 DashboardStandalonePageDescription.displayName = "DashboardStandalonePageDescription";
+/**
+* Action slot absolutely pinned to the header's left or right edge; renders a `<div>`.
+* Sitting outside the flow, it never shifts the centered title.
+*/
 const DashboardStandalonePageActions = React.forwardRef((componentProps, forwardRef) => {
 	const { side = "end", className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1805,6 +2056,9 @@ const DashboardStandalonePageActions = React.forwardRef((componentProps, forward
 	});
 });
 DashboardStandalonePageActions.displayName = "DashboardStandalonePageActions";
+/**
+* Header action button rendering a ds `Button` (ghost, `lg` by default); renders a `<button>`.
+*/
 const DashboardStandalonePageAction = React.forwardRef((componentProps, forwardRef) => {
 	const { variant = "ghost", ...props } = componentProps;
 	return /* @__PURE__ */ jsx(Button, {
@@ -1815,6 +2069,9 @@ const DashboardStandalonePageAction = React.forwardRef((componentProps, forwardR
 	});
 });
 DashboardStandalonePageAction.displayName = "DashboardStandalonePageAction";
+/**
+* Scrollable, transparent content area below the header inside the panel; renders a `<main>`.
+*/
 const DashboardStandalonePageMain = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("main", {
@@ -1828,6 +2085,21 @@ DashboardStandalonePageMain.displayName = "DashboardStandalonePageMain";
 
 //#endregion
 //#region src/components/dashboard-page.tsx
+/**
+* Full-screen outer shell for a dashboard view; renders a `<div>`.
+* Stacks an optional `DashboardPageBanner` above a `DashboardSidebarProvider`
+* that holds the sidebar and a `DashboardPageContent`.
+*
+* @example
+* ```tsx
+* <DashboardPage>
+*   <DashboardSidebarProvider>
+*     <DashboardSidebar>…</DashboardSidebar>
+*     <DashboardPageContent>…</DashboardPageContent>
+*   </DashboardSidebarProvider>
+* </DashboardPage>
+* ```
+*/
 const DashboardPage = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1838,6 +2110,10 @@ const DashboardPage = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardPage.displayName = "DashboardPage";
+/**
+* Full-width top row that sits flush above the sidebar/content row; renders a `<div>`.
+* Use to host trial notices, announcements, or any ds `Banner`.
+*/
 const DashboardPageBanner = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1848,16 +2124,22 @@ const DashboardPageBanner = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardPageBanner.displayName = "DashboardPageBanner";
+/**
+* White content card filling the right column beside the sidebar; renders a `<div>`.
+*/
 const DashboardPageContent = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
 		ref: forwardRef,
 		"data-slot": "dashboard-page-content",
-		className: cn("flex-1 min-w-0 flex flex-col bg-background rounded-xl border border-border overflow-hidden", "[&:has([data-slot=dph-tabs])>[data-slot=dph]]:border-b-0", className),
+		className: cn("flex-1 min-w-0 h-full flex flex-col bg-background rounded-xl border border-border overflow-hidden", "[&:has([data-slot=dph-tabs])>[data-slot=dph]]:border-b-0", className),
 		...props
 	});
 });
 DashboardPageContent.displayName = "DashboardPageContent";
+/**
+* Scrollable content area inside `DashboardPageContent`; renders a `<main>`.
+*/
 const DashboardPageMain = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("main", {
@@ -1868,6 +2150,9 @@ const DashboardPageMain = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardPageMain.displayName = "DashboardPageMain";
+/**
+* Left-aligned tab bar placed as a sibling of `DashboardPageHeader`; renders a ds `TabsList`.
+*/
 const DashboardPageTabs = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx(TabsList, {
@@ -1881,6 +2166,20 @@ DashboardPageTabs.displayName = "DashboardPageTabs";
 
 //#endregion
 //#region src/components/dashboard-page-header.tsx
+/**
+* Header for a `DashboardPageContent`; renders a `<div>` that establishes a
+* `@container` context with an inner CSS-grid its sub-components self-place into.
+*
+* @example
+* ```tsx
+* <DashboardPageHeader>
+*   <DashboardPageHeaderTitle>Team</DashboardPageHeaderTitle>
+*   <DashboardPageHeaderActions>
+*     <DashboardPageHeaderAction>Invite</DashboardPageHeaderAction>
+*   </DashboardPageHeaderActions>
+* </DashboardPageHeader>
+* ```
+*/
 const DashboardPageHeader = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1896,6 +2195,9 @@ const DashboardPageHeader = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardPageHeader.displayName = "DashboardPageHeader";
+/**
+* Back-navigation row for Level 2 headers; renders a `<div>` in the grid `nav` area.
+*/
 const DashboardPageHeaderNav = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1907,6 +2209,10 @@ const DashboardPageHeaderNav = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardPageHeaderNav.displayName = "DashboardPageHeaderNav";
+/**
+* Back button rendering a ghost, small ds `Button` with a leading chevron icon.
+* Accepts a render prop so it can become an `<a>` or router `<Link>`.
+*/
 const DashboardPageHeaderNavBack = React.forwardRef((componentProps, forwardRef) => {
 	const { children, ...props } = componentProps;
 	return /* @__PURE__ */ jsxs(Button, {
@@ -1919,6 +2225,9 @@ const DashboardPageHeaderNavBack = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardPageHeaderNavBack.displayName = "DashboardPageHeaderNavBack";
+/**
+* Icon/flag slot shown left of the title; renders a `<div>` in the grid `prefix` area.
+*/
 const DashboardPageHeaderPrefix = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1930,6 +2239,9 @@ const DashboardPageHeaderPrefix = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardPageHeaderPrefix.displayName = "DashboardPageHeaderPrefix";
+/**
+* Wrapper that stacks the title and subtitle; renders a `<div>` in the grid `info` area.
+*/
 const DashboardPageHeaderTitleGroup = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1941,6 +2253,10 @@ const DashboardPageHeaderTitleGroup = React.forwardRef((componentProps, forwardR
 	});
 });
 DashboardPageHeaderTitleGroup.displayName = "DashboardPageHeaderTitleGroup";
+/**
+* Page title; renders an `<h1>`, self-placing in the grid `info` area or deferring
+* layout to `DashboardPageHeaderTitleGroup` when nested inside one.
+*/
 const DashboardPageHeaderTitle = React.forwardRef((componentProps, forwardRef) => {
 	const { size = "lg", className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("h1", {
@@ -1952,6 +2268,9 @@ const DashboardPageHeaderTitle = React.forwardRef((componentProps, forwardRef) =
 	});
 });
 DashboardPageHeaderTitle.displayName = "DashboardPageHeaderTitle";
+/**
+* Optional subtitle line/block placed beneath the title; renders a `<div>`.
+*/
 const DashboardPageHeaderSubtitle = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1963,6 +2282,9 @@ const DashboardPageHeaderSubtitle = React.forwardRef((componentProps, forwardRef
 	});
 });
 DashboardPageHeaderSubtitle.displayName = "DashboardPageHeaderSubtitle";
+/**
+* Muted, clamped description text under the title; renders a `<div>`.
+*/
 const DashboardPageHeaderDescription = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1974,6 +2296,9 @@ const DashboardPageHeaderDescription = React.forwardRef((componentProps, forward
 	});
 });
 DashboardPageHeaderDescription.displayName = "DashboardPageHeaderDescription";
+/**
+* Flex container for header actions; renders a `<div>` in the grid `actions` area.
+*/
 const DashboardPageHeaderActions = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -1985,6 +2310,10 @@ const DashboardPageHeaderActions = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardPageHeaderActions.displayName = "DashboardPageHeaderActions";
+/**
+* Header action button rendering a ds `Button` locked to the actions area sizes;
+* renders a `<button>` (defaults to a labeled `lg` CTA, or `icon-lg` for icon-only triggers).
+*/
 const DashboardPageHeaderAction = React.forwardRef((componentProps, forwardRef) => {
 	const { size = "lg", ...props } = componentProps;
 	return /* @__PURE__ */ jsx(Button, {
@@ -2194,6 +2523,380 @@ const ScoreBadge = React.forwardRef((componentProps, forwardRef) => {
 });
 ScoreBadge.displayName = "ScoreBadge";
 
+//#endregion
+//#region src/helpers/format-kpi.ts
+/** Empty KPI placeholder matching Figma empty tiles and ScoreBadge. */
+const KPI_EMPTY = "--";
+/** Default secondary unit for clock durations. */
+function clockDurationUnit(scale) {
+	return scale === "hours" ? "hr/min" : "min/sec";
+}
+/**
+* Locale decimal separator (e.g. `.` for `en-US`, `,` for `fr-FR`).
+*/
+function getDecimalSeparator(locale) {
+	return new Intl.NumberFormat(locale).formatToParts(1.1).find((p) => p.type === "decimal")?.value ?? ".";
+}
+/**
+* Split a locale-formatted number on its decimal separator so the integer group
+* can use primary typography and the fraction (+ unit) secondary typography.
+*/
+function splitFormattedNumber(formatted, locale) {
+	const dec = getDecimalSeparator(locale);
+	const idx = formatted.indexOf(dec);
+	if (idx === -1) return {
+		primary: formatted,
+		secondary: ""
+	};
+	return {
+		primary: formatted.slice(0, idx),
+		secondary: formatted.slice(idx)
+	};
+}
+/**
+* Split a duration string on the leading digit run (`"1h 2min 3s"` → `"1"` + `"h 2min 3s"`).
+*/
+function splitLeadingDigits(text) {
+	const match = /^(\d+)([\s\S]*)$/.exec(text);
+	if (!match) return null;
+	return {
+		primary: match[1],
+		secondary: match[2]
+	};
+}
+/**
+* Format seconds into a readable duration (e.g. `1h 2min 3s`).
+* Implemented without `date-fns`.
+*
+* @example
+* formatSecondsToDuration(0) // => "0s"
+* formatSecondsToDuration(60) // => "1min 0s"
+* formatSecondsToDuration(3600) // => "1h 0min 0s"
+*/
+function formatSecondsToDuration(totalSeconds) {
+	const s = Math.max(0, Math.floor(totalSeconds));
+	const days = Math.floor(s / 86400);
+	const hours = Math.floor(s % 86400 / 3600);
+	const minutes = Math.floor(s % 3600 / 60);
+	const seconds = s % 60;
+	if (days) return `${days}d ${hours}h ${minutes}min ${seconds}s`;
+	if (hours) return `${hours}h ${minutes}min ${seconds}s`;
+	if (minutes) return `${minutes}min ${seconds}s`;
+	return `${seconds}s`;
+}
+/**
+* Format seconds as a zero-padded clock duration (`HH:MM` / `MM:SS`).
+* The full clock string is primary typography; the unit is appended separately.
+*
+* @example
+* formatSecondsToClock(75180, 'hours') // => { primary: "20:53", secondary: "" }
+* formatSecondsToClock(304, 'minutes') // => { primary: "05:04", secondary: "" }
+*/
+function formatSecondsToClock(totalSeconds, scale) {
+	const s = Math.max(0, Math.floor(totalSeconds));
+	if (scale === "hours") {
+		const hours = Math.floor(s / 3600);
+		const minutes$1 = Math.floor(s % 3600 / 60);
+		return {
+			primary: `${String(hours).padStart(2, "0")}:${String(minutes$1).padStart(2, "0")}`,
+			secondary: ""
+		};
+	}
+	const minutes = Math.floor(s / 60);
+	const seconds = s % 60;
+	return {
+		primary: `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`,
+		secondary: ""
+	};
+}
+/**
+* Format a KPI `value` for split typography display.
+* Returns `null` for empty / non-finite values (caller renders {@link KPI_EMPTY}).
+*
+* Contract:
+* - `string` is always opaque text (`kind` is ignored). Coerce at the call site
+*   if the API sent a numeric string and you need `number` / `percent` / `duration`.
+* - `number` / `percent` / `duration` require a finite `number`.
+*/
+function formatKpiValue(value, kind, locale, { formatOptions, durationStyle = "long", durationScale = "minutes" } = {}) {
+	if (kind === "text" || typeof value === "string") {
+		const text = String(value);
+		if (text === "") return null;
+		return {
+			primary: text,
+			secondary: ""
+		};
+	}
+	if (!Number.isFinite(value)) return null;
+	if (kind === "duration") {
+		if (durationStyle === "clock") return formatSecondsToClock(value, durationScale);
+		const formatted = formatSecondsToDuration(value);
+		return splitLeadingDigits(formatted) ?? {
+			primary: formatted,
+			secondary: ""
+		};
+	}
+	const options = kind === "percent" ? {
+		style: "percent",
+		maximumFractionDigits: 1,
+		...formatOptions
+	} : {
+		maximumFractionDigits: 1,
+		minimumFractionDigits: 0,
+		...formatOptions
+	};
+	return splitFormattedNumber(new Intl.NumberFormat(locale, options).format(kind === "percent" ? value / 100 : value), locale);
+}
+
+//#endregion
+//#region src/components/kpi.tsx
+const TREND_ICON = {
+	up: ArrowUpRight,
+	down: ArrowDownRight,
+	neutral: Minus
+};
+const TONE_CLASS = {
+	positive: "text-chart-1",
+	negative: "text-destructive",
+	neutral: "text-muted-foreground"
+};
+const KpiCardContext = React.createContext(null);
+function useKpiCardDisabled() {
+	return React.useContext(KpiCardContext)?.disabled ?? false;
+}
+function resolveKind(value, kind) {
+	if (typeof value === "string") return "text";
+	if (kind) return kind;
+	return "number";
+}
+function TrendGlyph({ trend, tone, className }) {
+	const Icon = TREND_ICON[trend];
+	return /* @__PURE__ */ jsx(Icon, {
+		"aria-hidden": "true",
+		className: cn("shrink-0", TONE_CLASS[tone], className)
+	});
+}
+/**
+* KPI tile container. Thin wrapper around DS `Card` (`size="sm"` by default)
+* that provides a `disabled` context for nested {@link KpiValue}s.
+* When `disabled`, applies `opacity-50` and `cursor-not-allowed`, and blocks
+* activation of nested interactive values.
+* Compose with DS `CardHeader` / `CardTitle` / `CardContent` / `CardAction`,
+* {@link KpiValue}, and {@link KpiDescription}.
+*
+* @example
+* ```tsx
+* import { CardHeader, CardTitle, CardContent } from '@aircall/ds';
+* import { KpiCard, KpiValue, KpiDescription } from '@aircall/blocks';
+*
+* <KpiCard>
+*   <CardHeader>
+*     <CardTitle>Answered</CardTitle>
+*   </CardHeader>
+*   <CardContent className="flex flex-col gap-1">
+*     <KpiValue value={123.1} kind="percent" trend="up" tone="positive" />
+*     <KpiDescription trend="up" tone="positive">+2.48% vs previous period</KpiDescription>
+*   </CardContent>
+* </KpiCard>
+* ```
+*/
+const KpiCard = React.forwardRef((componentProps, forwardRef) => {
+	const { className, size = "sm", disabled = false, children, ...props } = componentProps;
+	return /* @__PURE__ */ jsx(KpiCardContext.Provider, {
+		value: { disabled },
+		children: /* @__PURE__ */ jsx(Card, {
+			ref: forwardRef,
+			"data-slot": "kpi-card",
+			"data-disabled": disabled || void 0,
+			"aria-disabled": disabled || void 0,
+			size,
+			className: cn("gap-2 data-[size=sm]:gap-2", disabled && "cursor-not-allowed opacity-50", className),
+			...props,
+			children
+		})
+	});
+});
+KpiCard.displayName = "KpiCard";
+/**
+* KPI metric value. Formats via `useDsLocale` and renders primary (and optional
+* secondary) typography, with trend variants. Passing `onClick` makes the value
+* interactive (button + dotted underline). Prefer {@link KpiCard}`s `disabled`
+* for tile-level muting; a local `disabled` still works for standalone use.
+* Compose inside DS `CardContent` with {@link KpiDescription}.
+*
+* Prop naming: `kind` + `formatOptions` for formatting; `trend` is direction
+* (icon); `tone` is meaning (color) — "up" is not always good.
+*
+* @example
+* ```tsx
+* <KpiValue value={123.1} kind="percent" trend="up" tone="positive" />
+* ```
+*/
+const KpiValue = React.forwardRef((componentProps, forwardRef) => {
+	const { className, value, kind: kindProp, formatOptions, durationStyle = "long", durationScale = "minutes", unit, trend, tone = "neutral", active = false, disabled: disabledProp = false, children, onClick, render, ...props } = componentProps;
+	const locale = useDsLocale();
+	const cardDisabled = useKpiCardDisabled();
+	const isDisabled = Boolean(disabledProp || cardDisabled);
+	const isInteractive = typeof onClick === "function";
+	const kind = resolveKind(value, kindProp);
+	let content;
+	const valueUnderlineClassName = cn(isInteractive && "border-b border-current", isInteractive && !active && "border-dotted", isInteractive && active && "border-solid");
+	const trendGlyph = trend ? /* @__PURE__ */ jsx(TrendGlyph, {
+		trend,
+		tone: disabledProp && !cardDisabled ? "neutral" : tone,
+		className: "size-6"
+	}) : null;
+	if (children != null) content = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("span", {
+		className: cn("inline-flex items-baseline gap-0.5", valueUnderlineClassName),
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "text-3xl font-bold",
+			children
+		}), unit != null && unit !== "" && /* @__PURE__ */ jsx("span", {
+			className: "pt-2 text-xl leading-none font-semibold",
+			children: unit
+		})]
+	}), trendGlyph] });
+	else {
+		const formatted = value == null || typeof value === "number" && !Number.isFinite(value) ? null : formatKpiValue(value, kind, locale, {
+			formatOptions,
+			durationStyle,
+			durationScale
+		});
+		const resolvedUnit = unit !== void 0 ? unit : kind === "duration" && durationStyle === "clock" ? clockDurationUnit(durationScale) : void 0;
+		const unitNode = resolvedUnit != null && resolvedUnit !== "" ? resolvedUnit : null;
+		if (!formatted) content = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+			className: cn("text-3xl font-bold", valueUnderlineClassName),
+			children: KPI_EMPTY
+		}), trendGlyph] });
+		else {
+			const hasSecondary = formatted.secondary !== "" || unitNode != null;
+			content = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("span", {
+				className: cn("inline-flex items-baseline gap-0.5", valueUnderlineClassName),
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-3xl font-bold",
+					children: formatted.primary
+				}), hasSecondary && /* @__PURE__ */ jsxs("span", {
+					className: "pt-2 text-xl leading-none font-semibold",
+					children: [
+						formatted.secondary,
+						formatted.secondary !== "" && unitNode != null ? " " : null,
+						unitNode
+					]
+				})]
+			}), trendGlyph] });
+		}
+	}
+	const rootClassName = cn("inline-flex w-fit items-center gap-0.5 font-sans", disabledProp && !cardDisabled ? "text-muted-foreground" : active && isInteractive && !isDisabled ? "text-primary" : "text-foreground", isInteractive && !isDisabled && cn("cursor-pointer border-0 bg-transparent p-0 transition-colors active:opacity-60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50", active ? "hover:text-primary/80" : "hover:text-muted-foreground"), isInteractive && isDisabled && "cursor-not-allowed border-0 bg-transparent p-0", className);
+	return useRender({
+		defaultTagName: isInteractive ? "button" : "div",
+		props: mergeProps({
+			ref: forwardRef,
+			className: rootClassName,
+			children: content,
+			...isInteractive ? {
+				type: "button",
+				onClick,
+				disabled: isDisabled,
+				"aria-pressed": active
+			} : isDisabled ? { "aria-disabled": true } : {}
+		}, props),
+		render,
+		state: {
+			slot: "kpi-value",
+			active,
+			disabled: isDisabled,
+			interactive: isInteractive,
+			trend,
+			tone
+		}
+	});
+});
+KpiValue.displayName = "KpiValue";
+/**
+* Supporting comparison / context line under a {@link KpiValue}. Compose as a
+* sibling inside DS `CardContent` — not the metric title (`CardTitle` owns that).
+*
+* Text stays foreground; `trend` / `tone` only color the trailing icon so an
+* upward change that is bad uses `trend="up" tone="negative"`.
+*
+* @example
+* ```tsx
+* <KpiDescription trend="up" tone="positive">+2.48% vs previous period</KpiDescription>
+* <KpiDescription trend="up" tone="negative">+12% abandoned</KpiDescription>
+* ```
+*/
+const KpiDescription = React.forwardRef(function KpiDescription(componentProps, forwardRef) {
+	const { className, trend, tone = "neutral", children, ...props } = componentProps;
+	return /* @__PURE__ */ jsxs("div", {
+		ref: forwardRef,
+		"data-slot": "kpi-description",
+		"data-trend": trend,
+		"data-tone": tone,
+		className: cn("inline-flex items-center gap-0.5 font-sans text-xs font-medium text-foreground", className),
+		...props,
+		children: [children, trend ? /* @__PURE__ */ jsx(TrendGlyph, {
+			trend,
+			tone,
+			className: "size-3"
+		}) : null]
+	});
+});
+KpiDescription.displayName = "KpiDescription";
+/**
+* Loading placeholder sized for a {@link KpiValue} row. Thin wrapper around
+* DS `Skeleton` (`h-4 w-[45px]` with vertical margin to match the value row).
+* Swap in place of {@link KpiValue} while data loads.
+*
+* @example
+* ```tsx
+* <CardContent>
+*   {loading ? <KpiValueSkeleton /> : <KpiValue value={123} />}
+* </CardContent>
+* ```
+*/
+const KpiValueSkeleton = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx(Skeleton, {
+		ref: forwardRef,
+		"data-slot": "kpi-value-skeleton",
+		className: cn("my-[9px] h-4 w-[45px]", className),
+		...props
+	});
+});
+KpiValueSkeleton.displayName = "KpiValueSkeleton";
+/**
+* Loading placeholder sized for a {@link KpiDescription} row. Thin wrapper
+* around DS `Skeleton` (`12×144`, matching `text-xs` comparison copy).
+* Swap in place of {@link KpiDescription} while data loads.
+*
+* @example
+* ```tsx
+* <CardContent className="flex flex-col gap-1">
+*   {loading ? (
+*     <>
+*       <KpiValueSkeleton />
+*       <KpiDescriptionSkeleton />
+*     </>
+*   ) : (
+*     <>
+*       <KpiValue value={123} />
+*       <KpiDescription>+2.48% vs previous period</KpiDescription>
+*     </>
+*   )}
+* </CardContent>
+* ```
+*/
+const KpiDescriptionSkeleton = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx(Skeleton, {
+		ref: forwardRef,
+		"data-slot": "kpi-description-skeleton",
+		className: cn("h-3 w-36", className),
+		...props
+	});
+});
+KpiDescriptionSkeleton.displayName = "KpiDescriptionSkeleton";
+
 //#endregion
 //#region src/components/sentiment-badge.tsx
 const SENTIMENT_BADGE = {
@@ -2275,6 +2978,20 @@ function ChatbotPanelTrigger({ children = "Ask anything", icon = /* @__PURE__ */
 
 //#endregion
 //#region src/components/chatbot-expand-suggestion.tsx
+/**
+* Displays category filter pills and a list of clickable suggestion rows for the
+* chatbot idle state. Renders a `<div>` wrapping an optional `ToggleGroup` of
+* category pills and a list of `Item` rows separated by `Separator`.
+*
+* @example
+* ```tsx
+* <ChatbotExpandSuggestion
+*   categories={[{ value: 'billing', label: 'Billing' }]}
+*   suggestions={[{ id: '1', text: 'How do I reset my password?' }]}
+*   onSuggestionClick={suggestion => console.log(suggestion.text)}
+* />
+* ```
+*/
 const ChatbotExpandSuggestion = React.forwardRef((componentProps, forwardRef) => {
 	const { categories, selectedCategory: selectedCategoryProp, onCategoryChange, label = "Suggestions", suggestions, onSuggestionClick, className, ...props } = componentProps;
 	const [selectedCategory, setSelectedCategory] = useControllableState({
@@ -2327,6 +3044,21 @@ const MAX_WIDTH = 768;
 const KEYBOARD_RESIZE_STEP = 16;
 const DISCLAIMER_LINK_HREF = "https://legal.aircall.io/#template-9jw4r0usl";
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+* Presentational chatbot surface — header, scrollable conversation area (or a
+* built-in empty state), composer, and disclaimer — in a width-resizable shell.
+* Owns no visibility state (the consumer controls show/hide); pass the conversation
+* as `children`, and no children renders the empty state. Renders a `<div>`
+* container.
+*
+* @example
+* ```tsx
+* <ChatbotPanel onClose={close} onSubmit={send}>
+*   <ChatbotUserMessage>Hi</ChatbotUserMessage>
+*   <ChatbotResponseBlock>Hello!</ChatbotResponseBlock>
+* </ChatbotPanel>
+* ```
+*/
 function ChatbotPanel({ title, onMenu, conversations, activeConversationId, onNewChat, onSelectConversation, renderConversationMenuContent, onExpand, onClose, emptyTitle, emptyDescription, suggestions = [], onSuggestionSelect, inputValue, onInputValueChange, onSubmit, onStop, loading = false, loadingText, placeholder, autoFocus, disclaimer, resizable = true, defaultWidth = DEFAULT_WIDTH, minWidth = MIN_WIDTH, maxWidth = MAX_WIDTH, onWidthChange, className, style, children, ...props }) {
 	const t = useDsTranslation("blocks");
 	const [menuOpen, setMenuOpen] = React.useState(false);
@@ -2538,9 +3270,49 @@ function ChatbotPanel({ title, onMenu, conversations, activeConversationId, onNe
 */
 const { fieldContext, formContext, useFieldContext, useFormContext } = createFormHookContexts();
 
+//#endregion
+//#region src/components/save-bar.tsx
+function SaveBar({ isDirty, isSubmitting, canSubmit, onReset, submitLabel = "Save changes", savingLabel = "Saving…", resetLabel = "Discard", className }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "card-footer",
+		className: cn("grid transition-[grid-template-rows] duration-300 ease-in-out", isDirty ? "grid-rows-[1fr]" : "grid-rows-[0fr]", className),
+		children: /* @__PURE__ */ jsx("div", {
+			className: "overflow-hidden",
+			children: /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-end gap-2 border-t p-4",
+				children: [/* @__PURE__ */ jsx(Button, {
+					type: "button",
+					variant: "ghost",
+					onClick: onReset,
+					disabled: !isDirty || isSubmitting,
+					children: resetLabel
+				}), /* @__PURE__ */ jsx(Button, {
+					type: "submit",
+					disabled: !isDirty || !canSubmit || isSubmitting,
+					children: isSubmitting ? savingLabel : submitLabel
+				})]
+			})
+		})
+	});
+}
+
 //#endregion
 //#region src/components/card-save-bar.tsx
-function CardSaveBar({ submitLabel = "Save changes", savingLabel = "Saving…", resetLabel = "Discard" }) {
+/**
+* Save/discard bar for card-layout forms — the TanStack Form adapter around
+* `SaveBar`. Reads `isDirty`, `isSubmitting`, and `canSubmit` from form context
+* and renders `SaveBar` (which owns the animation, buttons, and the
+* `data-slot="card-footer"` that flushes it to the card edge).
+*
+* Must be placed **inside** the `<form>` element and wrapped by `form.AppForm`
+* (or any `formContext` provider).
+*
+* @example
+* <form.AppForm>
+*   <form.CardSaveBar submitLabel="Save" resetLabel="Discard" />
+* </form.AppForm>
+*/
+function CardSaveBar({ submitLabel, savingLabel, resetLabel }) {
 	const form = useFormContext();
 	return /* @__PURE__ */ jsx(form.Subscribe, {
 		selector: (s) => ({
@@ -2548,31 +3320,34 @@ function CardSaveBar({ submitLabel = "Save changes", savingLabel = "Saving…",
 			isSubmitting: s.isSubmitting,
 			canSubmit: s.canSubmit
 		}),
-		children: ({ isDirty, isSubmitting, canSubmit }) => /* @__PURE__ */ jsx("div", {
-			className: cn("grid transition-[grid-template-rows] duration-300 ease-in-out", isDirty ? "grid-rows-[1fr]" : "grid-rows-[0fr]"),
-			children: /* @__PURE__ */ jsx("div", {
-				className: "overflow-hidden",
-				children: /* @__PURE__ */ jsxs("div", {
-					className: "flex items-center justify-end gap-2 border-t px-6 py-3",
-					children: [/* @__PURE__ */ jsx(Button, {
-						type: "button",
-						variant: "ghost",
-						onClick: () => form.reset(),
-						disabled: !isDirty || isSubmitting,
-						children: resetLabel
-					}), /* @__PURE__ */ jsx(Button, {
-						type: "submit",
-						disabled: !isDirty || !canSubmit || isSubmitting,
-						children: isSubmitting ? savingLabel : submitLabel
-					})]
-				})
-			})
+		children: ({ isDirty, isSubmitting, canSubmit }) => /* @__PURE__ */ jsx(SaveBar, {
+			isDirty,
+			isSubmitting,
+			canSubmit,
+			onReset: () => form.reset(),
+			submitLabel,
+			savingLabel,
+			resetLabel
 		})
 	});
 }
 
 //#endregion
 //#region src/components/submit-button.tsx
+/**
+* Context-aware submit button. Disables itself when the form cannot be submitted or is submitting.
+* Shows `loadingLabel` (default `"Saving…"`) while submitting.
+*
+* Renders a DS `<Button type="submit">` (a `<button>` element).
+* Must be a descendant of `form.AppForm` (or any `formContext` provider).
+* Use for inline/flat layouts where `CardSaveBar` is not needed.
+* Accepts all `Button` props except `type` and `disabled` (managed internally).
+*
+* @example
+* <form.AppForm>
+*   <form.SubmitButton loadingLabel="Saving…">Save</form.SubmitButton>
+* </form.AppForm>
+*/
 function SubmitButton({ children = "Submit", loadingLabel, className, ...buttonProps }) {
 	return /* @__PURE__ */ jsx(useFormContext().Subscribe, {
 		selector: (s) => ({
@@ -2636,6 +3411,13 @@ function toFieldErrors(errors) {
 
 //#endregion
 //#region src/components/form-field.tsx
+/**
+* Internal layout shell shared by every `Form*Field` wrapper. Normalizes the
+* `label` / `description` props, lays out the `Field → label row → description →
+* control → error` skeleton per `orientation` / `controlVariant`, and applies the
+* error-display policy plus `data-invalid`. Reads the bound field from context,
+* so it must render inside `form.AppField`. Renders a DS `Field`.
+*/
 function FormFieldShell({ label, description, necessityIndicator, id, children, orientation = "vertical", controlPosition = "end", controlVariant = "fill" }) {
 	const errors = useFieldContext().state.meta.errors;
 	const labelContent = typeof label === "string" ? label : label?.content;
@@ -3131,34 +3913,147 @@ function FormToggleGroupField(props) {
 }
 
 //#endregion
-//#region src/components/save-bar.tsx
-function SaveBar({ isDirty, isSubmitting, canSubmit, onReset, submitLabel = "Save changes", savingLabel = "Saving…", resetLabel = "Discard", className }) {
-	return /* @__PURE__ */ jsx("div", {
-		className: cn("grid transition-[grid-template-rows] duration-300 ease-in-out", isDirty ? "grid-rows-[1fr]" : "grid-rows-[0fr]", className),
-		children: /* @__PURE__ */ jsx("div", {
-			className: "overflow-hidden",
-			children: /* @__PURE__ */ jsxs("div", {
-				className: "flex items-center justify-end gap-2 border-t px-4 py-2",
-				children: [/* @__PURE__ */ jsx(Button, {
-					type: "button",
-					variant: "ghost",
-					size: "sm",
-					onClick: onReset,
-					disabled: !isDirty || isSubmitting,
-					children: resetLabel
-				}), /* @__PURE__ */ jsx(Button, {
-					type: "submit",
-					size: "sm",
-					disabled: !isDirty || !canSubmit || isSubmitting,
-					children: isSubmitting ? savingLabel : submitLabel
-				})]
-			})
-		})
+//#region src/components/setting-card.tsx
+/**
+* Root container for a setting card. Renders the DS `Card`.
+*
+* By default the level (and therefore the background) is detected automatically:
+* a top-level card is level 1 (muted background, borderless); a card nested
+* inside another card's `SettingCardContent` becomes level 2 (white background,
+* border). Pass `level` to force a specific level — needed for the rare third
+* nesting level, which reuses the level-1 look (`level={1}`).
+*
+* @example
+* ```tsx
+* <SettingCard>
+*   <SettingCardHeader>
+*     <SettingCardTitle>Call recording</SettingCardTitle>
+*     <SettingCardDescription>Record inbound and outbound calls.</SettingCardDescription>
+*     <SettingCardAction>
+*       <Switch checked={enabled} onCheckedChange={setEnabled} />
+*     </SettingCardAction>
+*   </SettingCardHeader>
+*   {enabled && <SettingCardContent>…</SettingCardContent>}
+* </SettingCard>
+* ```
+*
+* @example
+* ```tsx
+* // With a save/discard bar: put the form on the OUTER level and drop
+* // `form.CardSaveBar` in as the last child. It reads dirty/submitting/canSubmit
+* // from form context, slides in when dirty, and carries `data-slot="card-footer"`
+* // so the card flushes it to the edge automatically. No `className` needed.
+* <form onSubmit={e => { e.preventDefault(); void form.handleSubmit(); }}>
+*   <SettingCard>
+*     <SettingCardHeader>
+*       <SettingCardTitle>Profile</SettingCardTitle>
+*       <SettingCardDescription>Update your display name.</SettingCardDescription>
+*     </SettingCardHeader>
+*     <SettingCardContent>…</SettingCardContent>
+*     <form.AppForm>
+*       <form.CardSaveBar resetLabel="Undo" />
+*     </form.AppForm>
+*   </SettingCard>
+* </form>
+* ```
+*/
+const SettingCard = React.forwardRef((componentProps, forwardRef) => {
+	const { className, level, ...props } = componentProps;
+	const isAuto = level === void 0;
+	return /* @__PURE__ */ jsx(Card, {
+		ref: forwardRef,
+		"data-level": level,
+		className: cn(isAuto && "bg-accent border-transparent [[data-setting-card-content]_&]:border-border [[data-setting-card-content]_&]:bg-card", level === 1 && "bg-accent border-transparent", level === 2 && "border-border bg-card", className),
+		...props
 	});
-}
+});
+SettingCard.displayName = "SettingCard";
+/**
+* Header row of a setting card. Wraps DS `CardHeader`, which lays out the
+* title/description on the left and the `SettingCardAction` on the right.
+*/
+const SettingCardHeader = React.forwardRef((componentProps, forwardRef) => /* @__PURE__ */ jsx(CardHeader, {
+	ref: forwardRef,
+	...componentProps
+}));
+SettingCardHeader.displayName = "SettingCardHeader";
+/**
+* Title of a setting card. Wraps DS `CardTitle`, overriding its type ramp so
+* weight and size follow the card's level (auto-detected from nesting, like the
+* background): level 1 is 18px bold, level 2 (nested) is 16px medium. A forced
+* level-1 card that is still nested (the rare 3rd level) keeps the 16px-medium
+* title, matching the design guidance for that case.
+*/
+const SettingCardTitle = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx(CardTitle, {
+		ref: forwardRef,
+		"data-slot": "setting-card-title",
+		className: cn("text-lg font-bold", "[[data-setting-card-content]_&]:text-base [[data-setting-card-content]_&]:font-medium", className),
+		...props
+	});
+});
+SettingCardTitle.displayName = "SettingCardTitle";
+/**
+* Supporting description under the title. Wraps DS `CardDescription` (14px muted).
+* Inline links (e.g. "Learn more") can be placed inside its children.
+*/
+const SettingCardDescription = React.forwardRef((componentProps, forwardRef) => /* @__PURE__ */ jsx(CardDescription, {
+	ref: forwardRef,
+	...componentProps
+}));
+SettingCardDescription.displayName = "SettingCardDescription";
+/**
+* Top-right control slot of the header — holds a single control, either a
+* `<Switch>` (toggle card) or a `<Button>` (action card). Wraps DS `CardAction`.
+* The two never co-occur, so this is one slot, not two.
+*/
+const SettingCardAction = React.forwardRef((componentProps, forwardRef) => /* @__PURE__ */ jsx(CardAction, {
+	ref: forwardRef,
+	...componentProps
+}));
+SettingCardAction.displayName = "SettingCardAction";
+/**
+* Body of a setting card. Wraps DS `CardContent` and carries the
+* `data-setting-card-content` marker that drives nesting detection: any
+* `SettingCard` rendered inside here auto-detects level 2.
+*
+* For progressive disclosure, render this conditionally — mount it only when
+* the header's toggle is on — so gated fields never mount while disabled.
+*/
+const SettingCardContent = React.forwardRef((componentProps, forwardRef) => {
+	const { className, ...props } = componentProps;
+	return /* @__PURE__ */ jsx(CardContent, {
+		ref: forwardRef,
+		"data-setting-card-content": "",
+		className: cn("flex flex-col gap-4", className),
+		...props
+	});
+});
+SettingCardContent.displayName = "SettingCardContent";
 
 //#endregion
 //#region src/components/dashboard-sidebar.tsx
+/**
+* Context provider and flex-row layout wrapping the sidebar and page content;
+* renders a ds `SidebarProvider`. Provides the state consumed by `useDashboardSidebar`.
+*
+* @example
+* ```tsx
+* <DashboardSidebarProvider>
+*   <DashboardSidebar>
+*     <DashboardSidebarContent>
+*       <DashboardSidebarMenu>
+*         <DashboardSidebarMenuItem>
+*           <DashboardSidebarMenuButton icon={<Home />}>Home</DashboardSidebarMenuButton>
+*         </DashboardSidebarMenuItem>
+*       </DashboardSidebarMenu>
+*     </DashboardSidebarContent>
+*   </DashboardSidebar>
+*   <DashboardPageContent>…</DashboardPageContent>
+* </DashboardSidebarProvider>
+* ```
+*/
 const DashboardSidebarProvider = React.forwardRef((componentProps, forwardRef) => {
 	const { className, style, ...props } = componentProps;
 	return /* @__PURE__ */ jsx(SidebarProvider, {
@@ -3173,6 +4068,10 @@ const DashboardSidebarProvider = React.forwardRef((componentProps, forwardRef) =
 	});
 });
 DashboardSidebarProvider.displayName = "DashboardSidebarProvider";
+/**
+* Root sidebar column that grows/shrinks with the collapse state; renders a `<div>`.
+* Holds `DashboardSidebarHeader`, `DashboardSidebarContent`, and `DashboardSidebarFooter`.
+*/
 const DashboardSidebar = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	const { state } = useSidebar();
@@ -3187,6 +4086,9 @@ const DashboardSidebar = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardSidebar.displayName = "DashboardSidebar";
+/**
+* Top bar of the sidebar that houses the collapse toggle; renders a `<div>`.
+*/
 const DashboardSidebarHeader = React.forwardRef((componentProps, forwardRef) => {
 	const { className, children, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3198,6 +4100,10 @@ const DashboardSidebarHeader = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardSidebarHeader.displayName = "DashboardSidebarHeader";
+/**
+* Collapse/expand toggle rendering a ghost, icon ds `Button`; renders a `<button>`.
+* Swaps its icon and aria-label based on the sidebar state.
+*/
 const DashboardSidebarTrigger = React.forwardRef((componentProps, forwardRef) => {
 	const { className, onClick, ...props } = componentProps;
 	const { toggleSidebar, state } = useSidebar();
@@ -3217,6 +4123,9 @@ const DashboardSidebarTrigger = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardSidebarTrigger.displayName = "DashboardSidebarTrigger";
+/**
+* Scrollable middle section of the sidebar (scrollbar hidden); renders a `<div>`.
+*/
 const DashboardSidebarContent = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3227,6 +4136,9 @@ const DashboardSidebarContent = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardSidebarContent.displayName = "DashboardSidebarContent";
+/**
+* Frosted-glass bottom section of the sidebar; renders a `<div>`.
+*/
 const DashboardSidebarFooter = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3237,6 +4149,9 @@ const DashboardSidebarFooter = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardSidebarFooter.displayName = "DashboardSidebarFooter";
+/**
+* Groups a set of menu items (optionally labelled); renders a `<div>`.
+*/
 const DashboardSidebarGroup = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3247,6 +4162,10 @@ const DashboardSidebarGroup = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardSidebarGroup.displayName = "DashboardSidebarGroup";
+/**
+* Section heading for a group, hidden when the sidebar is collapsed; renders a `<div>`
+* by default, overridable via the `render` prop.
+*/
 const DashboardSidebarGroupLabel = React.forwardRef((componentProps, forwardRef) => {
 	const { className, render, ...props } = componentProps;
 	return useRender({
@@ -3260,6 +4179,9 @@ const DashboardSidebarGroupLabel = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardSidebarGroupLabel.displayName = "DashboardSidebarGroupLabel";
+/**
+* List container for menu items; renders a `<ul>`.
+*/
 const DashboardSidebarMenu = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("ul", {
@@ -3270,6 +4192,9 @@ const DashboardSidebarMenu = React.forwardRef((componentProps, forwardRef) => {
 	});
 });
 DashboardSidebarMenu.displayName = "DashboardSidebarMenu";
+/**
+* Wrapper for a single menu row; renders a `<li>` (relative, for badge positioning).
+*/
 const DashboardSidebarMenuItem = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("li", {
@@ -3280,6 +4205,10 @@ const DashboardSidebarMenuItem = React.forwardRef((componentProps, forwardRef) =
 	});
 });
 DashboardSidebarMenuItem.displayName = "DashboardSidebarMenuItem";
+/**
+* Pill-shaped navigation item with a leading icon circle and optional trailing action;
+* renders a `<button>` by default, overridable via the `render` prop (e.g. a router `<Link>`).
+*/
 const DashboardSidebarMenuButton = React.forwardRef((componentProps, forwardRef) => {
 	const { className, render, isActive = false, disabled = false, icon, action, children, ...props } = componentProps;
 	const buttonContent = /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -3313,6 +4242,9 @@ const DashboardSidebarMenuButton = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardSidebarMenuButton.displayName = "DashboardSidebarMenuButton";
+/**
+* Right-aligned slot (ml-auto) for trailing content inside a menu row; renders a `<div>`.
+*/
 const DashboardSidebarMenuAddon = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3323,6 +4255,11 @@ const DashboardSidebarMenuAddon = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardSidebarMenuAddon.displayName = "DashboardSidebarMenuAddon";
+/**
+* Notification count badge for a menu item; renders a ds `CounterBadge` positioned
+* absolutely at the row's right edge (moves to the icon corner when collapsed).
+* Place it inside `DashboardSidebarMenuItem`, as a sibling of the button.
+*/
 const DashboardSidebarMenuBadge = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx(CounterBadge, {
@@ -3333,6 +4270,10 @@ const DashboardSidebarMenuBadge = React.forwardRef((componentProps, forwardRef)
 	});
 });
 DashboardSidebarMenuBadge.displayName = "DashboardSidebarMenuBadge";
+/**
+* Popover-style panel (white card with border and shadow) opening beside a trigger;
+* renders a `<div>`. Hosts `DashboardSidebarSubmenuItem` and `DashboardSidebarSubmenuSeparator`.
+*/
 const DashboardSidebarSubmenu = React.forwardRef((componentProps, forwardRef) => {
 	const { className, ...props } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3343,6 +4284,10 @@ const DashboardSidebarSubmenu = React.forwardRef((componentProps, forwardRef) =>
 	});
 });
 DashboardSidebarSubmenu.displayName = "DashboardSidebarSubmenu";
+/**
+* One row inside a submenu; renders a `<div>` by default, overridable via the `render`
+* prop (e.g. an `<a>` or router `<Link>` for navigation).
+*/
 const DashboardSidebarSubmenuItem = React.forwardRef((componentProps, forwardRef) => {
 	const { className, render, isActive = false, ...props } = componentProps;
 	return useRender({
@@ -3359,6 +4304,9 @@ const DashboardSidebarSubmenuItem = React.forwardRef((componentProps, forwardRef
 	});
 });
 DashboardSidebarSubmenuItem.displayName = "DashboardSidebarSubmenuItem";
+/**
+* Thin horizontal divider between submenu items; renders a `<div>`.
+*/
 const DashboardSidebarSubmenuSeparator = React.forwardRef((componentProps, forwardRef) => {
 	const { className } = componentProps;
 	return /* @__PURE__ */ jsx("div", {
@@ -3455,6 +4403,20 @@ function NavItem({ item, renderLink }) {
 	})] }), countBadge] });
 	return /* @__PURE__ */ jsxs(DashboardSidebarMenuItem, { children: [React.cloneElement(buttonEl, {}, item.label, trailing), countBadge] });
 }
+/**
+* Data-driven sidebar navigation. Maps a `groups` array into the
+* `DashboardSidebar` primitives, rendering each item as a link, a dropdown
+* submenu, or an action button (with optional badges, counts, and tooltips).
+*
+* Renders a fragment of `DashboardSidebarGroup` sections — it has no wrapper
+* element of its own, so place it inside a `DashboardSidebarContent`.
+*
+* @example
+* <DashboardSidebarNav
+*   groups={groups}
+*   renderLink={href => <Link to={href} />}
+* />
+*/
 function DashboardSidebarNav({ groups, renderLink }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: groups.map((group) => /* @__PURE__ */ jsxs(DashboardSidebarGroup, { children: [group.label && /* @__PURE__ */ jsx(DashboardSidebarGroupLabel, { children: group.label }), /* @__PURE__ */ jsx(DashboardSidebarMenu, { children: group.items.map((item) => /* @__PURE__ */ jsx(NavItem, {
 		item,
@@ -3463,4 +4425,4 @@ function DashboardSidebarNav({ groups, renderLink }) {
 }
 
 //#endregion
-export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotResponseLoading, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageDescription, DashboardStandalonePageHeader, DashboardStandalonePageMain, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormArrayField, FormComboboxField, FormFieldBase, FormFieldShell, FormInputField, FormMultiComboboxField, FormNumericField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, PERCENTAGE_THRESHOLDS, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, ScoreBadge, SentimentBadge, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };
+export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotResponseLoading, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageDescription, DashboardStandalonePageHeader, DashboardStandalonePageMain, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormArrayField, FormComboboxField, FormFieldBase, FormFieldShell, FormInputField, FormMultiComboboxField, FormNumericField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, KpiCard, KpiDescription, KpiDescriptionSkeleton, KpiValue, KpiValueSkeleton, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, PERCENTAGE_THRESHOLDS, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, ScoreBadge, SentimentBadge, SettingCard, SettingCardAction, SettingCardContent, SettingCardDescription, SettingCardHeader, SettingCardTitle, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };