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.