@aircall/blocks 0.17.0 → 0.18.0

package/dist/index.js

@@ -1,4 +1,4 @@
-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, 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";
@@ -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, {
@@ -2275,6 +2604,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 +2670,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 +2896,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 +2946,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 +3037,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 +3539,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 +3694,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 +3712,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 +3726,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 +3749,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 +3762,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 +3775,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 +3788,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 +3805,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 +3818,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 +3831,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 +3868,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 +3881,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 +3896,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 +3910,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 +3930,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 +4029,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 +4051,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, 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 };