xertica-ui 2.5.2 → 2.6.0

package/components/layout/header/header.mdx

@@ -1,117 +1,117 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as HeaderStories from './header.stories';
-
-<Meta of={HeaderStories} />
-
-<Title />
-<Subtitle>The primary Top Bar component for the application shell.</Subtitle>
-
-The `Header` represents the global top bar of the application ecosystem. It provides navigation context (breadcrumbs), system controls (language and theme), and management of the logged-in user profile.
-
-<Primary />
-
-## Properties
-
-The `Header` is highly configurable, allowing for everything from basic title control to complete customization of the user menu.
-
-<Controls />
-
----
-
-## Usage Differentiation
-
-It is essential to understand the difference between the **Header** and the **PageHeader** to maintain visual consistency:
-
-- **Header (Global)**: Fixed top bar (`sticky`). Contains the navigation trail (breadcrumbs) and the user profile. There is only **ONE** per application.
-- **PageHeader (Local)**: Located inside the content area. Contains the large page title (`h1`), subtitle, and specific action buttons (such as "Save" or "New").
-
----
-
-## Navigation Modes
-
-### 1. Breadcrumbs (Default — Recommended)
-
-The **primary pattern**. Use `breadcrumbs` for any page with navigation hierarchy. The component supports **unlimited** depth levels — do not limit to 2 or 3 items.
-
-<Canvas of={HeaderStories.Default} />
-
-### 2. Deep Navigation (5+ Levels)
-
-Breadcrumbs gracefully handle deeply nested navigation structures with automatic separators and horizontal scrolling.
-
-<Canvas of={HeaderStories.DeepNavigation} />
-
-### 3. Title Only (Exception)
-
-Use `title` **only** when the page is a standalone top-level page with no navigation context (e.g., a standalone dashboard or landing page). This renders a plain text label without separators.
-
-> [!WARNING]
-> The `title`-only pattern is the **exception**, not the default. Always prefer `breadcrumbs` when the page has any navigation hierarchy.
-
-<Canvas of={HeaderStories.TitleOnly} />
-
-### 4. SPA Navigation (React Router)
-
-Use the `renderLink` prop to integrate with client-side routers like React Router or Next.js Link. This prevents full-page reloads when users click breadcrumb links.
-
-```tsx
-import { Link } from 'react-router-dom';
-
-<Header
-  breadcrumbs={[...]}
-  renderLink={(href, props) => <Link to={href} {...props} />}
-/>
-```
-
-<Canvas of={HeaderStories.WithReactRouter} />
-
-### 5. Global Actions and User Menu
-
-Use the `actions` prop for buttons that should always be visible (such as notifications or messages). The `user` prop allows for full customization of the profile dropdown.
-
-<Canvas of={HeaderStories.WithActions} />
-
----
-
-## Fallback Logic
-
-The `Header` ensures a navigation area is **never empty**:
-
-1. **Breadcrumbs** → If provided, renders the full navigation trail with separators.
-2. **Title** → If provided (without breadcrumbs), renders a simple text label.
-3. **Default** → If neither is provided, falls back to `Xertica.ai`.
-
----
-
-## Best Practices & AI Rules
-
-> [!IMPORTANT]
-> - **Breadcrumbs First** — Always prefer `breadcrumbs` for navigable pages. Use `title` only for standalone pages with no hierarchy.
-> - **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
-> - **Mobile Navigation** — The `Header` contains the automatic trigger to open/close the Sidebar on mobile devices following the `LayoutContext` state.
-> - **Height Consistency** — The header has a fixed height of `64px` (`h-[64px]`). Its breadcrumbs are automatically truncated on small screens to prevent layout breaking.
-> - **Right Area Actions** — Use `actions` for frequently used interaction items. Less used configuration items should be placed inside `user.menuItems`.
-
-### Developer Integration Guide
-```tsx
-import { Header } from 'xertica-ui/layout';
-import { Home, Settings, Users } from 'lucide-react';
-
-export function MyLayout({ children }) {
-  return (
-    <div className="flex flex-col min-h-screen">
-      <Header 
-        breadcrumbs={[
-          { label: 'Home', href: '/', icon: <Home className="size-4" /> },
-          { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
-          { label: 'Team Management' },
-        ]}
-        user={{ name: "John Doe", email: "john@example.com" }}
-      />
-      <main className="flex-1 p-6">
-        {children}
-      </main>
-    </div>
-  )
-}
-```
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as HeaderStories from './header.stories';
+
+<Meta of={HeaderStories} />
+
+<Title />
+<Subtitle>The primary Top Bar component for the application shell.</Subtitle>
+
+The `Header` represents the global top bar of the application ecosystem. It provides navigation context (breadcrumbs), system controls (language and theme), and management of the logged-in user profile.
+
+<Primary />
+
+## Properties
+
+The `Header` is highly configurable, allowing for everything from basic title control to complete customization of the user menu.
+
+<Controls />
+
+---
+
+## Usage Differentiation
+
+It is essential to understand the difference between the **Header** and the **PageHeader** to maintain visual consistency:
+
+- **Header (Global)**: Fixed top bar (`sticky`). Contains the navigation trail (breadcrumbs) and the user profile. There is only **ONE** per application.
+- **PageHeader (Local)**: Located inside the content area. Contains the large page title (`h1`), subtitle, and specific action buttons (such as "Save" or "New").
+
+---
+
+## Navigation Modes
+
+### 1. Breadcrumbs (Default — Recommended)
+
+The **primary pattern**. Use `breadcrumbs` for any page with navigation hierarchy. The component supports **unlimited** depth levels — do not limit to 2 or 3 items.
+
+<Canvas of={HeaderStories.Default} />
+
+### 2. Deep Navigation (5+ Levels)
+
+Breadcrumbs gracefully handle deeply nested navigation structures with automatic separators and horizontal scrolling.
+
+<Canvas of={HeaderStories.DeepNavigation} />
+
+### 3. Title Only (Exception)
+
+Use `title` **only** when the page is a standalone top-level page with no navigation context (e.g., a standalone dashboard or landing page). This renders a plain text label without separators.
+
+> [!WARNING]
+> The `title`-only pattern is the **exception**, not the default. Always prefer `breadcrumbs` when the page has any navigation hierarchy.
+
+<Canvas of={HeaderStories.TitleOnly} />
+
+### 4. SPA Navigation (React Router)
+
+Use the `renderLink` prop to integrate with client-side routers like React Router or Next.js Link. This prevents full-page reloads when users click breadcrumb links.
+
+```tsx
+import { Link } from 'react-router-dom';
+
+<Header
+  breadcrumbs={[...]}
+  renderLink={(href, props) => <Link to={href} {...props} />}
+/>
+```
+
+<Canvas of={HeaderStories.WithReactRouter} />
+
+### 5. Global Actions and User Menu
+
+Use the `actions` prop for buttons that should always be visible (such as notifications or messages). The `user` prop allows for full customization of the profile dropdown.
+
+<Canvas of={HeaderStories.WithActions} />
+
+---
+
+## Fallback Logic
+
+The `Header` ensures a navigation area is **never empty**:
+
+1. **Breadcrumbs** → If provided, renders the full navigation trail with separators.
+2. **Title** → If provided (without breadcrumbs), renders a simple text label.
+3. **Default** → If neither is provided, falls back to `Xertica.ai`.
+
+---
+
+## Best Practices & AI Rules
+
+> [!IMPORTANT]
+> - **Breadcrumbs First** — Always prefer `breadcrumbs` for navigable pages. Use `title` only for standalone pages with no hierarchy.
+> - **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
+> - **Mobile Navigation** — The `Header` contains the automatic trigger to open/close the Sidebar on mobile devices following the `LayoutContext` state.
+> - **Height Consistency** — The header has a fixed height of `64px` (`h-[64px]`). Its breadcrumbs are automatically truncated on small screens to prevent layout breaking.
+> - **Right Area Actions** — Use `actions` for frequently used interaction items. Less used configuration items should be placed inside `user.menuItems`.
+
+### Developer Integration Guide
+```tsx
+import { Header } from 'xertica-ui/layout';
+import { Home, Settings, Users } from 'lucide-react';
+
+export function MyLayout({ children }) {
+  return (
+    <div className="flex flex-col min-h-screen">
+      <Header 
+        breadcrumbs={[
+          { label: 'Home', href: '/', icon: <Home className="size-4" /> },
+          { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
+          { label: 'Team Management' },
+        ]}
+        user={{ name: "John Doe", email: "john@example.com" }}
+      />
+      <main className="flex-1 p-6">
+        {children}
+      </main>
+    </div>
+  )
+}
+```

package/components/layout/header/header.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
+import { renderWithProviders as render } from '../../../test/render';
 import { describe, it, expect, vi } from 'vitest';
 import { Header } from './header';
 import React from 'react';

package/components/layout/sidebar/sidebar.mdx

@@ -1,99 +1,99 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas, ArgTypes } from '@storybook/addon-docs/blocks';
-import * as SidebarStories from './sidebar.stories';
-
-<Meta of={SidebarStories} />
-
-# Sidebar
-
-<Subtitle>Customized navigation shell for enterprise platforms.</Subtitle>
-
-<Description>
-The Sidebar is the main structural component of the application layout. It supports responsive toggling, hierarchical navigation groups, and an advanced **Assistant Mode** for AI-driven or tool-centric interfaces.
-</Description>
-
-<Primary />
-
-## Interactive Props
-<ArgTypes of={SidebarStories.Default} />
-
----
-
-## Autonomous Operation
-
-The Sidebar component is designed to be **autonomous**. While it is typically used with `LayoutProvider`, it can function completely independently:
-
-- **Automatic Context Detection**: If a `LayoutProvider` is found, it synchronizes with the global state (expanded, width, toggles).
-- **Local State Fallback**: If no context is provided, it manages its own `expanded` state internally.
-- **Optional Props**: All structural props (`expanded`, `onToggle`, `navigate`, `location`) are now optional with smart fallbacks to global objects or local state.
-
-```tsx
-// Simple, autonomous usage
-<Sidebar routes={myRoutes} />
-```
-
----
-
-## Usage Patterns
-
-### Traditional System Navigation
-The `default` variant provides a clean, standard list of routes. Use this for management dashboards and settings-heavy areas.
-
-<Canvas>
-  <SidebarStories.Default />
-</Canvas>
-
-### AI Assistant & Monitoring
-The `assistant` variant is designed for dynamic content like conversation history, project monitoring, and searchable toolsets. It supports search filters, primary action buttons, and progress indicators within descriptions.
-
-<Canvas>
-  <SidebarStories.Assistant />
-</Canvas>
-
-### Compact (Collapsed) View
-Maximizes the workspace by collapsing the sidebar to an icon-only strip. Interactive tooltips provide context for each item.
-
-<Canvas>
-  <SidebarStories.Collapsed />
-</Canvas>
-
----
-
-## Layout Features
-
-### Keyboard Shortcuts
-The sidebar expansion can be toggled using the global shortcut:
-- **`Ctrl + B`** (Windows/Linux)
-- **`Cmd + B`** (macOS)
-
-### State Persistence
-The expansion state is automatically persisted in a cookie (`sidebar_state`), ensuring the user's preference is maintained across page reloads and sessions.
-
----
-
-## Technical Integration
-
-### Global Layout Hook
-The Sidebar should ideally be synchronized with the `useLayout()` hook to ensure the main application container adjusts its padding accordingly.
-
-```tsx
-import { Sidebar } from 'xertica-ui/layout';
-import { useLayout } from 'xertica-ui/hooks';
-
-const { sidebarExpanded, toggleSidebar, sidebarWidth } = useLayout();
-
-return (
-  <Sidebar
-    expanded={sidebarExpanded}
-    onToggle={toggleSidebar}
-    width={sidebarWidth}
-    // ...
-  />
-);
-```
-
-### AI Best Practices
-
-> [!TIP]
-> - **Primary Actions** — Use the `fixedArea` property to place critical CTA buttons (like "New Conversation") always in view.
-> - **Search & Filtering** — Enable `search.filter` to allow users to toggle between different states (e.g., Active, Archived).
-> - **Contextual Menus** — Add `actions` to navigation items to provide quick management (Rename, Delete, Move) without leaving the current view.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as SidebarStories from './sidebar.stories';
+
+<Meta of={SidebarStories} />
+
+# Sidebar
+
+<Subtitle>Customized navigation shell for enterprise platforms.</Subtitle>
+
+<Description>
+The Sidebar is the main structural component of the application layout. It supports responsive toggling, hierarchical navigation groups, and an advanced **Assistant Mode** for AI-driven or tool-centric interfaces.
+</Description>
+
+<Primary />
+
+## Interactive Props
+<ArgTypes of={SidebarStories.Default} />
+
+---
+
+## Autonomous Operation
+
+The Sidebar component is designed to be **autonomous**. While it is typically used with `LayoutProvider`, it can function completely independently:
+
+- **Automatic Context Detection**: If a `LayoutProvider` is found, it synchronizes with the global state (expanded, width, toggles).
+- **Local State Fallback**: If no context is provided, it manages its own `expanded` state internally.
+- **Optional Props**: All structural props (`expanded`, `onToggle`, `navigate`, `location`) are now optional with smart fallbacks to global objects or local state.
+
+```tsx
+// Simple, autonomous usage
+<Sidebar routes={myRoutes} />
+```
+
+---
+
+## Usage Patterns
+
+### Traditional System Navigation
+The `default` variant provides a clean, standard list of routes. Use this for management dashboards and settings-heavy areas.
+
+<Canvas>
+  <SidebarStories.Default />
+</Canvas>
+
+### AI Assistant & Monitoring
+The `assistant` variant is designed for dynamic content like conversation history, project monitoring, and searchable toolsets. It supports search filters, primary action buttons, and progress indicators within descriptions.
+
+<Canvas>
+  <SidebarStories.Assistant />
+</Canvas>
+
+### Compact (Collapsed) View
+Maximizes the workspace by collapsing the sidebar to an icon-only strip. Interactive tooltips provide context for each item.
+
+<Canvas>
+  <SidebarStories.Collapsed />
+</Canvas>
+
+---
+
+## Layout Features
+
+### Keyboard Shortcuts
+The sidebar expansion can be toggled using the global shortcut:
+- **`Ctrl + B`** (Windows/Linux)
+- **`Cmd + B`** (macOS)
+
+### State Persistence
+The expansion state is automatically persisted in a cookie (`sidebar_state`), ensuring the user's preference is maintained across page reloads and sessions.
+
+---
+
+## Technical Integration
+
+### Global Layout Hook
+The Sidebar should ideally be synchronized with the `useLayout()` hook to ensure the main application container adjusts its padding accordingly.
+
+```tsx
+import { Sidebar } from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
+
+const { sidebarExpanded, toggleSidebar, sidebarWidth } = useLayout();
+
+return (
+  <Sidebar
+    expanded={sidebarExpanded}
+    onToggle={toggleSidebar}
+    width={sidebarWidth}
+    // ...
+  />
+);
+```
+
+### AI Best Practices
+
+> [!TIP]
+> - **Primary Actions** — Use the `fixedArea` property to place critical CTA buttons (like "New Conversation") always in view.
+> - **Search & Filtering** — Enable `search.filter` to allow users to toggle between different states (e.g., Active, Archived).
+> - **Contextual Menus** — Add `actions` to navigation items to provide quick management (Rename, Delete, Move) without leaving the current view.