xertica-ui 2.1.2 → 2.1.4

package/dist/components/assistant/xertica-assistant/parts/AssistantDocumentEditor.d.ts

@@ -0,0 +1,17 @@
+interface EditingDocument {
+    content: string;
+    title: string;
+}
+interface AssistantDocumentEditorProps {
+    document: EditingDocument;
+    isMobile: boolean;
+    containerWidth: string;
+    onClose: () => void;
+    onChange: (doc: EditingDocument) => void;
+}
+/**
+ * AssistantDocumentEditor — Overlay panel with a rich text editor for editing documents
+ * generated by the assistant. Slides in from the left of the assistant panel.
+ */
+export declare function AssistantDocumentEditor({ document, isMobile, containerWidth, onClose, onChange, }: AssistantDocumentEditorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/AssistantFeedbackDialog.d.ts

@@ -0,0 +1,19 @@
+export interface EvaluationState {
+    isOpen: boolean;
+    messageId: string | null;
+    type?: 'dislike' | null;
+    category?: string | null;
+    reason: string;
+}
+interface AssistantFeedbackDialogProps {
+    state: EvaluationState;
+    onReasonChange: (reason: string) => void;
+    onClose: () => void;
+    onSubmit: () => void;
+}
+/**
+ * AssistantFeedbackDialog — Modal dialog for collecting negative feedback (dislike) on messages.
+ * Supports both categorized feedback (from feedbackOptions) and free-text input.
+ */
+export declare function AssistantFeedbackDialog({ state, onReasonChange, onClose, onSubmit, }: AssistantFeedbackDialogProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/AssistantHeader.d.ts

@@ -0,0 +1,11 @@
+interface AssistantHeaderProps {
+    isExpanded: boolean;
+    onToggle: () => void;
+    onNavigateFullPage?: () => void;
+}
+/**
+ * AssistantHeader — Top bar shown in expanded/collapsed (non-fullPage) mode.
+ * Contains the Xertica Orbe logo, title, expand-to-full-page button, and toggle button.
+ */
+export declare function AssistantHeader({ isExpanded, onToggle, onNavigateFullPage, }: AssistantHeaderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/AssistantMessageBubble.d.ts

@@ -0,0 +1,29 @@
+import type { Message, SearchResult } from '../types';
+interface AssistantMessageBubbleProps {
+    msg: Message;
+    copiedId: string | null;
+    generatingPodcastId: string | null;
+    executingCommand: string | null;
+    savedSearches: string[];
+    enablePodcastGeneration: boolean;
+    feedbackOptions?: string[];
+    onCopyMessage: (content: string, id: string) => void;
+    onToggleFavorite: (id: string) => void;
+    onGeneratePodcast: (id: string, content: string) => void;
+    onDownloadDocument: (content: string, fileName: string) => void;
+    onDownloadPodcast: (audioUrl: string, fileName: string) => void;
+    onEditDocument: (content: string, title: string) => void;
+    onOpenSearchResult: (result: SearchResult) => void;
+    onExecuteSearchCommand: (commandId: string, query: string, results: SearchResult[], messageId: string) => void;
+    onEvaluationClick: (id: string, type: 'like' | 'dislike') => void;
+    onOpenFeedbackDialog: (id: string, category: string | null) => void;
+}
+/**
+ * AssistantMessageBubble — Renders a single chat message with all supported content types:
+ * plain text, Markdown, charts, tables, documents, podcasts, and search results.
+ *
+ * Handles both user and assistant message styles, plus per-message action buttons
+ * (copy, like/dislike, podcast generation).
+ */
+export declare function AssistantMessageBubble({ msg, copiedId, generatingPodcastId, executingCommand, savedSearches, enablePodcastGeneration, feedbackOptions, onCopyMessage, onToggleFavorite, onGeneratePodcast, onDownloadDocument, onDownloadPodcast, onEditDocument, onOpenSearchResult, onExecuteSearchCommand, onEvaluationClick, onOpenFeedbackDialog, }: AssistantMessageBubbleProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/AssistantTabBar.d.ts

@@ -0,0 +1,13 @@
+import type { AssistantTab } from '../types';
+interface AssistantTabBarProps {
+    activeTab: AssistantTab;
+    showHistory: boolean;
+    showFavorites: boolean;
+    onTabChange: (tab: AssistantTab) => void;
+}
+/**
+ * AssistantTabBar — Navigation tabs for Chat, History, and Favorites.
+ * Only rendered in expanded (non-fullPage) mode when at least one secondary tab is enabled.
+ */
+export declare function AssistantTabBar({ activeTab, showHistory, showFavorites, onTabChange, }: AssistantTabBarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/AssistantTypingIndicator.d.ts

@@ -0,0 +1,4 @@
+/**
+ * AssistantTypingIndicator — Animated three-dot indicator shown while the assistant is processing.
+ */
+export declare function AssistantTypingIndicator(): import("react/jsx-runtime").JSX.Element;

package/dist/components/assistant/xertica-assistant/parts/AssistantWelcomeScreen.d.ts

@@ -0,0 +1,17 @@
+import type { Suggestion } from '../types';
+interface AssistantWelcomeScreenProps {
+    userName: string;
+    welcomeMessage: string;
+    suggestions: Suggestion[];
+    richSuggestions: Suggestion[];
+    showMoreSuggestions: boolean;
+    onSetShowMoreSuggestions: (show: boolean) => void;
+    onSendSuggestion: (text: string) => void;
+    onRichSuggestionClick: (suggestion: Suggestion) => void;
+}
+/**
+ * AssistantWelcomeScreen — Empty state shown when there are no messages yet.
+ * Displays the Xertica Orbe, a greeting, and suggestion chips.
+ */
+export declare function AssistantWelcomeScreen({ userName, welcomeMessage, suggestions, richSuggestions, showMoreSuggestions, onSetShowMoreSuggestions, onSendSuggestion, onRichSuggestionClick, }: AssistantWelcomeScreenProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/assistant/xertica-assistant/parts/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sub-components for XerticaAssistant.
+ *
+ * These are internal building blocks — not part of the public library API.
+ * Import them only from within the `xertica-assistant` directory.
+ */
+export { AssistantCollapsedView } from './AssistantCollapsedView';
+export { AssistantHeader } from './AssistantHeader';
+export { AssistantTabBar } from './AssistantTabBar';
+export { AssistantWelcomeScreen } from './AssistantWelcomeScreen';
+export { AssistantMessageBubble } from './AssistantMessageBubble';
+export { AssistantTypingIndicator } from './AssistantTypingIndicator';
+export { AssistantConversationList } from './AssistantConversationList';
+export { AssistantFeedbackDialog } from './AssistantFeedbackDialog';
+export { AssistantDocumentEditor } from './AssistantDocumentEditor';
+export type { EvaluationState } from './AssistantFeedbackDialog';

package/dist/components/assistant/xertica-assistant/types.d.ts

@@ -0,0 +1,106 @@
+import type { ReactNode } from 'react';
+/**
+ * @file types.ts
+ * Shared TypeScript types for the XerticaAssistant component and related hooks/contexts.
+ *
+ * These types are the single source of truth — imported by:
+ *  - `xertica-assistant.tsx`
+ *  - `use-assistant.ts`
+ *  - `contexts/AssistenteContext.tsx`
+ */
+/** Supported message sender types in the assistant */
+export type MessageType = 'user' | 'assistant' | 'system';
+/** Supported attachment types that can be included in messages */
+export type AttachmentType = 'file' | 'audio' | 'image' | 'video' | 'document' | 'podcast' | 'search';
+/** Supported search result categories */
+export type SearchResultType = 'document' | 'project' | 'conversation' | 'file' | 'contact';
+/** Layout mode for the assistant panel */
+export type AssistantMode = 'collapsed' | 'expanded' | 'fullPage';
+/** Available tabs in the assistant panel */
+export type AssistantTab = 'chat' | 'historico' | 'favoritos';
+/**
+ * Individual search result item returned by an assistant search query.
+ */
+export interface SearchResult {
+    id: string;
+    type: SearchResultType;
+    title: string;
+    description: string;
+    path: string;
+    relevance: number;
+    lastModified?: string;
+}
+/**
+ * Metadata about a search source (e.g., a document repository or knowledge base).
+ */
+export interface SearchSource {
+    name: string;
+    count: number;
+}
+/**
+ * A quick-action command shown below a search result message.
+ */
+export interface SearchCommand {
+    id: string;
+    icon: string;
+    label: string;
+    description: string;
+}
+/**
+ * A single chat message in the assistant conversation.
+ */
+export interface Message {
+    id: string;
+    type: MessageType;
+    content: string;
+    timestamp: Date;
+    isFavorite?: boolean;
+    attachmentType?: AttachmentType;
+    attachmentName?: string;
+    documentContent?: string;
+    documentTitle?: string;
+    audioUrl?: string;
+    searchResults?: SearchResult[];
+    searchSources?: SearchSource[];
+    searchCommands?: SearchCommand[];
+    chartData?: any[];
+    chartConfig?: any;
+    tableData?: {
+        caption?: string;
+        headers: string[];
+        rows: (string | ReactNode)[][];
+    };
+    evaluation?: 'like' | 'dislike';
+    evaluationReason?: string;
+}
+/**
+ * A saved conversation entry shown in the history panel.
+ */
+export interface Conversation {
+    id: string;
+    title: string;
+    lastMessage?: string;
+    timestamp: string;
+    isFavorite: boolean;
+    messages: Message[];
+}
+/**
+ * A suggested prompt shown to the user in the chat input area.
+ */
+export interface Suggestion {
+    id: string;
+    text: string;
+    icon?: ReactNode;
+}
+/**
+ * A mock response entry used in demo mode.
+ * Matches a user message via `trigger` and returns a predefined `response`.
+ */
+export interface MockResponse {
+    /** String or regex to match against the user's message */
+    trigger: string | RegExp;
+    /** Response content — either a plain string or a partial Message object */
+    response: string | Partial<Message>;
+    /** Optional delay in milliseconds before the response appears */
+    delay?: number;
+}

package/dist/components/assistant/xertica-assistant/use-assistant.d.ts

@@ -0,0 +1,125 @@
+import type { Message, Conversation, Suggestion, AssistantTab, AssistantMode, SearchResult, MockResponse } from './types';
+export interface UseAssistantProps {
+    /** Layout mode for the assistant panel */
+    mode?: AssistantMode;
+    /** Controlled expansion state */
+    isExpanded?: boolean;
+    /** Toggle callback for controlled expansion */
+    onToggle?: () => void;
+    /** Initially selected tab */
+    defaultTab?: AssistantTab;
+    /** Enables demo mode with mock AI responses */
+    demoMode?: boolean;
+    /** Custom mock responses for demo mode */
+    customResponses?: MockResponse[];
+    /** Pre-loaded messages to hydrate an existing conversation */
+    initialMessages?: Message[];
+    /** Previously saved conversations */
+    savedConversations?: Conversation[];
+    /** Suggested prompts shown in the empty state */
+    suggestions?: Suggestion[];
+    /** Callback fired when the user sends a message */
+    onSendMessage?: (message: string) => void;
+    /** Whether the assistant is currently processing a response */
+    isProcessing?: boolean;
+    /** Custom response generator — overrides demo mode defaults */
+    responseGenerator?: (message: string) => Promise<string | Partial<Message>> | string | Partial<Message>;
+    /** Extended suggestions shown when the user clicks "More suggestions" */
+    richSuggestions?: Suggestion[];
+    /** Callback fired when the user clicks a rich suggestion */
+    onRichAction?: (actionId: string, actionText: string) => void;
+    /** Callback fired when the user rates a message */
+    onEvaluation?: (messageId: string, type: 'like' | 'dislike', reason?: string) => void;
+    /** Negative feedback categories shown in the dislike dropdown */
+    feedbackOptions?: string[];
+}
+export interface UseAssistantReturn {
+    isFullPage: boolean;
+    isExpanded: boolean;
+    isMobile: boolean;
+    abaSelecionada: AssistantTab;
+    setAbaSelecionada: (tab: AssistantTab) => void;
+    mensagens: Message[];
+    setMensagens: React.Dispatch<React.SetStateAction<Message[]>>;
+    mensagem: string;
+    setMensagem: (value: string) => void;
+    conversas: Conversation[];
+    conversaAtual: string | null;
+    conversasFiltradas: Conversation[];
+    copiedId: string | null;
+    generatingPodcastId: string | null;
+    executingCommand: string | null;
+    savedSearches: string[];
+    editingDocument: {
+        content: string;
+        title: string;
+    } | null;
+    setEditingDocument: (doc: {
+        content: string;
+        title: string;
+    } | null) => void;
+    showMoreSuggestions: boolean;
+    setShowMoreSuggestions: (show: boolean) => void;
+    evaluationState: {
+        isOpen: boolean;
+        messageId: string | null;
+        type: 'dislike' | null;
+        category?: string | null;
+        reason: string;
+    };
+    setEvaluationState: React.Dispatch<React.SetStateAction<UseAssistantReturn['evaluationState']>>;
+    sugestoes: Suggestion[];
+    messagesEndRef: React.RefObject<HTMLDivElement>;
+    fileInputRef: React.RefObject<HTMLInputElement>;
+    audioInputRef: React.RefObject<HTMLInputElement>;
+    handleToggle: () => void;
+    handleExpandWithTab: (tab: AssistantTab) => void;
+    handleEnviarMensagem: (arg?: string | any) => Promise<void>;
+    handleToggleFavorite: (messageId: string) => void;
+    handleCopyMessage: (content: string, messageId: string) => Promise<void>;
+    handleGeneratePodcast: (messageId: string, content: string) => Promise<void>;
+    handleDownloadDocument: (content: string, fileName: string) => void;
+    handleDownloadPodcast: (audioUrl: string, fileName: string) => void;
+    handleEditDocument: (content: string, title: string) => void;
+    handleNovaConversa: () => void;
+    handleSelecionarConversa: (conversaId: string) => void;
+    handleToggleFavoritaConversa: (conversaId: string) => void;
+    handleOpenSearchResult: (result: SearchResult) => void;
+    handleExecuteSearchCommand: (commandId: string, searchTerm: string, results: SearchResult[], messageId: string) => Promise<void>;
+    handleRichSuggestionClick: (suggestion: Suggestion) => void;
+    handleEvaluationClick: (messageId: string, type: 'like' | 'dislike') => void;
+    openFeedbackDialog: (messageId: string, category: string | null) => void;
+    handleSubmitDislike: () => void;
+}
+/**
+ * `useAssistant` — Headless hook for the XerticaAssistant component.
+ *
+ * Encapsulates all state management and business logic for the AI assistant panel.
+ * Use this hook when you need to build a fully custom assistant UI while reusing
+ * the same state logic as the default `XerticaAssistant` component.
+ *
+ * @example
+ * ```tsx
+ * import { useAssistant } from 'xertica-ui/assistant';
+ *
+ * function MyCustomAssistant() {
+ *   const {
+ *     mensagens,
+ *     mensagem,
+ *     setMensagem,
+ *     handleEnviarMensagem,
+ *     isExpanded,
+ *     handleToggle,
+ *   } = useAssistant({ demoMode: true });
+ *
+ *   return (
+ *     <div>
+ *       {mensagens.map(msg => <p key={msg.id}>{msg.content}</p>)}
+ *       <input value={mensagem} onChange={e => setMensagem(e.target.value)} />
+ *       <button onClick={() => handleEnviarMensagem()}>Send</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAssistant({ mode, isExpanded: controlledIsExpanded, onToggle, defaultTab, demoMode, customResponses, initialMessages, savedConversations, suggestions: propSuggestions, onSendMessage, isProcessing, responseGenerator, richSuggestions, onRichAction, onEvaluation, }?: UseAssistantProps): UseAssistantReturn;

package/dist/components/assistant/xertica-assistant/xertica-assistant.d.ts

@@ -1,99 +1,5 @@
-import React from 'react';
-/**
- * Supported message sender types in the assistant
- */
-export type MessageType = 'user' | 'assistant' | 'system';
-/**
- * Supported attachment types that can be included in messages
- */
-export type AttachmentType = 'file' | 'audio' | 'image' | 'video' | 'document' | 'podcast' | 'search';
-/**
- * Supported search result categories
- */
-export type SearchResultType = 'document' | 'project' | 'conversation' | 'file' | 'contact';
-/**
- * Individual search result item returned by an assistant search query
- */
-export interface SearchResult {
-    id: string;
-    type: SearchResultType;
-    title: string;
-    description: string;
-    path: string;
-    relevance: number;
-    lastModified?: string;
-}
-/**
- * Metadata about a search source (e.g., a document repository or knowledge base)
- */
-export interface SearchSource {
-    name: string;
-    count: number;
-}
-/**
- * A quick-action command shown below a search result message
- */
-export interface SearchCommand {
-    id: string;
-    icon: string;
-    label: string;
-    description: string;
-}
-/**
- * A single chat message in the assistant conversation
- */
-export interface Message {
-    id: string;
-    type: MessageType;
-    content: string;
-    timestamp: Date;
-    isFavorite?: boolean;
-    attachmentType?: AttachmentType;
-    attachmentName?: string;
-    documentContent?: string;
-    documentTitle?: string;
-    audioUrl?: string;
-    searchResults?: SearchResult[];
-    searchSources?: SearchSource[];
-    searchCommands?: SearchCommand[];
-    chartData?: any[];
-    chartConfig?: any;
-    tableData?: {
-        caption?: string;
-        headers: string[];
-        rows: (string | React.ReactNode)[][];
-    };
-    evaluation?: 'like' | 'dislike';
-    evaluationReason?: string;
-}
-/**
- * A saved conversation entry shown in the history panel
- */
-export interface Conversation {
-    id: string;
-    title: string;
-    lastMessage?: string;
-    timestamp: string;
-    isFavorite: boolean;
-    messages: Message[];
-}
-/**
- * A suggested prompt shown to the user in the chat input area
- */
-export interface Suggestion {
-    id: string;
-    text: string;
-    icon?: React.ReactNode;
-}
-/**
- * Layout mode for the assistant panel
- */
-export type AssistantMode = 'collapsed' | 'expanded' | 'fullPage';
-/**
- * Available tabs in the assistant panel
- */
-export type AssistantTab = 'chat' | 'historico' | 'favoritos';
-import { type MockResponse } from '../../shared/assistant-utils';
+import type { MessageType, AttachmentType, SearchResultType, AssistantMode, AssistantTab, SearchResult, SearchSource, SearchCommand, Message, Conversation, Suggestion, MockResponse } from './types';
+export type { MessageType, AttachmentType, SearchResultType, AssistantMode, AssistantTab, SearchResult, SearchSource, SearchCommand, Message, Conversation, Suggestion, MockResponse, };
 export interface XerticaAssistantProps {
     /**
      * Layout mode for the assistant panel
@@ -147,6 +53,11 @@ export interface XerticaAssistantProps {
      * Suggested prompts shown to the user in the empty state
      */
     suggestions?: Suggestion[];
+    /**
+     * Subtitle shown below the user's name in the empty state.
+     * @default 'Como posso ajudar?'
+     */
+    welcomeMessage?: string;
     /**
      * Callback fired when the user sends a message
      */
@@ -274,4 +185,4 @@ export interface XerticaAssistantProps {
  * 2. Use `onSendMessage` to capture user input and `responseGenerator` to provide AI responses in demo mode.
  * 3. Supports automatic Markdown rendering and syntax-highlighted code blocks.
  */
-export declare function XerticaAssistant({ mode, isExpanded: controlledIsExpanded, onToggle, defaultTab, demoMode, onNavigateSettings, onNavigateFullPage, userName, initialMessages, savedConversations, suggestions: propSuggestions, onSendMessage, onFileAttach, isProcessing, width, height, className, mobileFloating, customResponses, responseGenerator, richSuggestions, onRichAction, onEvaluation, feedbackOptions, showHistory, showFavorites, enableAudioInput, enableFileAttachment, enableDocumentCreation, enablePodcastGeneration, enableSearch, }: XerticaAssistantProps): import("react/jsx-runtime").JSX.Element;
+export declare function XerticaAssistant({ mode, isExpanded: controlledIsExpanded, onToggle, defaultTab, demoMode, onNavigateSettings, onNavigateFullPage, userName, initialMessages, savedConversations, suggestions: propSuggestions, onSendMessage, onFileAttach, isProcessing, width, height, className, mobileFloating, customResponses, responseGenerator, richSuggestions, welcomeMessage, onRichAction, onEvaluation, feedbackOptions, showHistory, showFavorites, enableAudioInput, enableFileAttachment, enableDocumentCreation, enablePodcastGeneration, enableSearch, }: XerticaAssistantProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/hooks/index.d.ts

@@ -5,3 +5,6 @@ export * from '../../contexts/BrandColorsContext';
 export * from '../../contexts/AssistenteContext';
 export * from '../../contexts/ApiKeyContext';
 export { useMobile, useIsMobile } from '../shared/use-mobile';
+export { useLayoutShortcuts } from './use-layout-shortcuts';
+export { useAudioPlayer } from '../media/audio-player/use-audio-player';
+export type { UseAudioPlayerProps, UseAudioPlayerReturn } from '../media/audio-player/use-audio-player';

package/dist/components/hooks/use-layout-shortcuts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `useLayoutShortcuts` — Registra atalhos de teclado globais para controle de layout.
+ *
+ * Deve ser usado uma única vez no componente raiz da aplicação (ex: `App.tsx` ou `Layout.tsx`).
+ * Extrai a responsabilidade de atalhos de teclado do `LayoutContext`, seguindo o
+ * princípio de responsabilidade única.
+ *
+ * **Atalhos registrados:**
+ * - `Ctrl+B` / `Cmd+B` — Alterna a sidebar
+ *
+ * @example
+ * ```tsx
+ * // Em App.tsx ou no componente de layout raiz:
+ * import { useLayoutShortcuts } from 'xertica-ui/hooks';
+ *
+ * function AppLayout({ children }: { children: React.ReactNode }) {
+ *   useLayoutShortcuts(); // registra Ctrl+B para toggle da sidebar
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ */
+export declare function useLayoutShortcuts(): void;

package/dist/components/layout/sidebar/index.d.ts

@@ -1 +1,3 @@
 export * from './sidebar';
+export { useSidebar } from './use-sidebar';
+export type { UseSidebarProps } from './use-sidebar';

package/dist/components/layout/sidebar/sidebar.d.ts

@@ -33,6 +33,14 @@ export interface RouteConfig {
     /** Child routes exposed via contextual menu button at the end of the item */
     children?: RouteConfig[];
 }
+export interface NavigationItem {
+    path: string;
+    label: string;
+    icon?: any;
+    active: boolean;
+    children?: RouteConfig[];
+    actions?: ActionMenuItem[];
+}
 export interface SidebarFilterConfig {
     show: boolean;
     content?: React.ReactNode;
@@ -116,6 +124,66 @@ export interface SidebarProps {
     /** Pixel width when expanded (desktop) */
     width?: number;
 }
+/**
+ * Root container for the Sidebar. Provides context to all sub-components.
+ * Use this when building a fully custom sidebar layout.
+ *
+ * @example
+ * <Sidebar.Root expanded={expanded} onToggle={toggle} width={280}>
+ *   <Sidebar.Header logo={<MyLogo />} />
+ *   <Sidebar.Nav navigationGroups={groups} />
+ *   <Sidebar.Footer user={user} onLogout={logout} />
+ * </Sidebar.Root>
+ */
+declare function SidebarRoot({ expanded: expandedProp, onToggle: onToggleProp, navigate: navigateProp, location: locationProp, width: widthProp, children, className, }: {
+    expanded?: boolean;
+    onToggle?: () => void;
+    navigate?: (path: string) => void;
+    location?: {
+        pathname: string;
+    };
+    width?: number;
+    children: React.ReactNode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Toggle button + logo header area for the Sidebar.
+ */
+declare function SidebarHeader({ logo, logoCollapsed, }: {
+    logo?: React.ReactNode;
+    logoCollapsed?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Navigation area for the Sidebar (default variant).
+ * Renders grouped or flat navigation items with overflow handling.
+ */
+declare function SidebarNav({ navigationGroups, routes, variant, }: {
+    navigationGroups?: RouteGroup[];
+    routes?: RouteConfig[];
+    variant?: "default" | "assistant";
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Assistant-specific search + fixed area header for the Sidebar.
+ */
+declare function SidebarSearch({ fixedArea, search, }: {
+    fixedArea?: SidebarFixedAreaConfig;
+    search?: SidebarSearchConfig;
+}): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Footer area for the Sidebar with user info, settings, and logout.
+ */
+declare function SidebarFooter({ user, onLogout, onSettingsClick, showUser, showSettings, showLogout, }: {
+    user?: {
+        name?: string;
+        email?: string;
+        avatar?: string;
+    } | null;
+    onLogout?: () => void;
+    onSettingsClick?: () => void;
+    showUser?: boolean;
+    showSettings?: boolean;
+    showLogout?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Primary navigation sidebar component.
  *
@@ -127,9 +195,21 @@ export interface SidebarProps {
  * This component is autonomous: it works out-of-the-box using local state or
  * integrates automatically with `LayoutContext` if wrapped in `LayoutProvider`.
  *
+ * For advanced customization, use the Compound Component API:
+ * `<Sidebar.Root>`, `<Sidebar.Header>`, `<Sidebar.Search>`, `<Sidebar.Nav>`, `<Sidebar.Footer>`
+ *
  * @ai-rules
  * 1. NEVER recreate the sidebar with raw Tailwind classes — always use this component.
  * 2. Use `variant="assistant"` for AI/tool sidebars; use `variant="default"` for standard navigation.
  * 3. Supports `Ctrl+B` keyboard shortcut automatically via `LayoutProvider`.
  */
 export declare function Sidebar({ expanded: expandedProp, onToggle: onToggleProp, user, onLogout, onSettingsClick, location: locationProp, navigate: navigateProp, routes, logo, logoCollapsed, variant, fixedArea, search, navigationGroups, footer, showFooter, width: widthProp, }: SidebarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Sidebar {
+    var Root: typeof SidebarRoot;
+    var Header: typeof SidebarHeader;
+    var Search: typeof SidebarSearch;
+    var Nav: typeof SidebarNav;
+    var Footer: typeof SidebarFooter;
+}
+export { useSidebar } from "./use-sidebar";
+export type { UseSidebarProps } from "./use-sidebar";

package/dist/components/layout/sidebar/use-sidebar.d.ts

@@ -0,0 +1,22 @@
+import { RouteGroup } from "./sidebar";
+export interface UseSidebarProps {
+    defaultExpanded?: boolean;
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    navigationGroups?: RouteGroup[];
+}
+export declare function useSidebar({ defaultExpanded, expanded: controlledExpanded, onExpandedChange, navigationGroups, }?: UseSidebarProps): {
+    expanded: boolean;
+    setExpanded: (value: boolean | ((prev: boolean) => boolean)) => void;
+    toggleExpanded: () => void;
+    isMobileViewport: boolean;
+    hasOverflow: boolean;
+    visibleItems: RouteGroup[];
+    overflowItems: RouteGroup[];
+    openSubmenu: string | null;
+    setOpenSubmenu: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    isFilterOpen: boolean;
+    setIsFilterOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    navRef: import("react").RefObject<HTMLElement>;
+    navigationGroups: RouteGroup[];
+};

package/dist/components/media/audio-player/AudioPlayer.d.ts

@@ -32,5 +32,8 @@ export interface AudioPlayerProps {
 }
 /**
  * Unified Audio Player component.
+ *
+ * All state and logic is managed by the `useAudioPlayer` headless hook.
+ * This component is responsible only for rendering.
  */
-export declare function AudioPlayer({ src, title, artist, subtitle, autoPlay, className, variant, isOpen, onClose, duration: initialDuration, currentTime: initialTime, colorVariant, enableAutoFloat, onCloseFloating }: AudioPlayerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AudioPlayer({ src, title, artist, subtitle, autoPlay, className, variant, isOpen, onClose, duration: initialDuration, currentTime: initialTime, colorVariant, enableAutoFloat, onCloseFloating, }: AudioPlayerProps): import("react/jsx-runtime").JSX.Element | null;