xertica-ui 2.2.1 → 2.4.0

package/docs/layout.md

@@ -1,143 +1,143 @@
-# Layout System — Xertica UI
-
-The Xertica UI layout system provides centralized state management for the application shell — sidebar, assistant panel, and responsive behavior. It is consumed via a React context hook and must not be replicated with local state.
-
----
-
-## Overview
-
-The layout is built around a three-column shell:
-
-```
-┌──────────────┬─────────────────────────┬──────────────┐
-│   Sidebar    │    Main Content Area    │  AI Panel    │
-│ (collapsed:  │                         │ (assistant,  │
-│   80px)      │  paddingLeft = sidebar  │   optional)  │
-│ (expanded:   │                         │              │
-│  sidebarWidth│      (Header at top)    │              │
-└──────────────┴─────────────────────────┴──────────────┘
-```
-
-- **Sidebar** and **AI Panel** are mutually exclusive — opening one closes the other.
-- The **main content area** adjusts its `paddingLeft` dynamically based on sidebar state and width.
-- **Mobile**: The sidebar overlays content instead of pushing it. The `Header` component provides the toggle trigger.
-
----
-
-## LayoutContext API
-
-`LayoutContext` is injected by `<LayoutProvider>` which is included inside `<XerticaProvider>`. You never instantiate it directly.
-
-### Hook
-
-```tsx
-import { useLayout } from 'xertica-ui/hooks';
-
-const {
-  sidebarExpanded,
-  setSidebarExpanded,
-  toggleSidebar,
-  sidebarWidth,
-  setSidebarWidth,
-  assistenteExpanded,
-  setAssistenteExpanded,
-  toggleAssistente,
-  toggleAssistenteWithTab,
-} = useLayout();
-```
-
-### Context Properties
-
-| Property                  | Type                      | Default | Description                                                      |
-| ------------------------- | ------------------------- | ------- | ---------------------------------------------------------------- |
-| `sidebarExpanded`         | `boolean`                 | `false` | Whether the sidebar is currently expanded (persisted in cookies) |
-| `setSidebarExpanded`      | `(v: boolean) => void`    | —       | Directly set sidebar expanded state                              |
-| `toggleSidebar`           | `() => void`              | —       | Toggle sidebar (auto-closes assistant if open)                   |
-| `sidebarWidth`            | `number`                  | `280`   | Expanded sidebar width in pixels                                 |
-| `setSidebarWidth`         | `(width: number) => void` | —       | Update the expanded sidebar width globally                       |
-| `assistenteExpanded`      | `boolean`                 | `false` | Whether the AI assistant panel is open                           |
-| `setAssistenteExpanded`   | `(v: boolean) => void`    | —       | Directly set assistant expanded state                            |
-| `toggleAssistente`        | `() => void`              | —       | Toggle assistant (auto-closes sidebar if open)                   |
-| `toggleAssistenteWithTab` | `(tab: string) => void`   | —       | Open assistant and navigate to a specific tab                    |
-| `isMobile`                | `boolean`                 | `false` | Whether the viewport is currently in mobile mode (< 768px)       |
-
-### Features
-
-- **Persistence**: The `sidebarExpanded` state is automatically saved in a cookie named `sidebar_state`.
-- **Shortcuts**: Toggling the sidebar expansion can be done via `Ctrl+B` (Windows/Linux) or `Cmd+B` (macOS).
-- **Autonomous Sidebar**: The `Sidebar` component will work even without `LayoutProvider`, although it won't synchronize with other layout-aware components.
-
----
-
-## Usage Patterns
-
-### Reading Sidebar State in a Content Container
-
-The main content container must offset itself based on the sidebar state. Always use `sidebarWidth` from context — never hardcode pixel values:
-
-```tsx
-import { useLayout } from 'xertica-ui/hooks';
-
-function PageContent({ children }) {
-  const { sidebarExpanded, sidebarWidth } = useLayout();
-
-  return (
-    <div
-      style={{
-        paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px',
-      }}
-      className="flex-1 flex flex-col overflow-hidden transition-all duration-300"
-    >
-      {children}
-    </div>
-  );
-}
-```
-
-> **80px** is the fixed collapsed sidebar width. This must not change.
-
-### Full Page Layout Shell
-
-```tsx
-import { Sidebar, Header } from 'xertica-ui/layout';
-import { useLayout } from 'xertica-ui/hooks';
-import { useNavigate, useLocation } from 'react-router-dom';
-
-function AppLayout({ user, onLogout }) {
-  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
-  const navigate = useNavigate();
-  const location = useLocation();
-
-  return (
-    <div className="h-screen flex bg-muted overflow-hidden relative">
-      <Sidebar
-        expanded={sidebarExpanded}
-        width={sidebarWidth}
-        onToggle={toggleSidebar}
-        user={user}
-        onLogout={onLogout}
-        location={location}
-        navigate={navigate}
-        routes={routes}
-      />
-      <div
-        style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}
-        className="flex-1 flex flex-col overflow-hidden transition-all duration-300"
-      >
-        <Header title="Dashboard" />
-        <main className="flex-1 overflow-y-auto bg-muted p-6">{children}</main>
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-## AI Rules
-
-- **State Management** — Never use `useState` to manage sidebar expanded/collapsed state in page components.
-- **Never** hardcode `paddingLeft: '280px'` or `pl-64` — use `sidebarWidth` from context.
-- **Mobile** — The component automatically handles the `LayoutContext` toggle via the `Header` hamburger icon.
-- `sidebarWidth` only affects the **expanded desktop state**. The collapsed state is always `80px`.
-- Use `toggleSidebar()` / `toggleAssistente()` — not `setSidebarExpanded(true)` — for user-triggered actions, since the toggle functions handle mutual exclusion.
+# Layout System — Xertica UI
+
+The Xertica UI layout system provides centralized state management for the application shell — sidebar, assistant panel, and responsive behavior. It is consumed via a React context hook and must not be replicated with local state.
+
+---
+
+## Overview
+
+The layout is built around a three-column shell:
+
+```
+┌──────────────┬─────────────────────────┬──────────────┐
+│   Sidebar    │    Main Content Area    │  AI Panel    │
+│ (collapsed:  │                         │ (assistant,  │
+│   80px)      │  paddingLeft = sidebar  │   optional)  │
+│ (expanded:   │                         │              │
+│  sidebarWidth│      (Header at top)    │              │
+└──────────────┴─────────────────────────┴──────────────┘
+```
+
+- **Sidebar** and **AI Panel** are mutually exclusive — opening one closes the other.
+- The **main content area** adjusts its `paddingLeft` dynamically based on sidebar state and width.
+- **Mobile**: The sidebar overlays content instead of pushing it. The `Header` component provides the toggle trigger.
+
+---
+
+## LayoutContext API
+
+`LayoutContext` is injected by `<LayoutProvider>` which is included inside `<XerticaProvider>`. You never instantiate it directly.
+
+### Hook
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+const {
+  sidebarExpanded,
+  setSidebarExpanded,
+  toggleSidebar,
+  sidebarWidth,
+  setSidebarWidth,
+  assistenteExpanded,
+  setAssistenteExpanded,
+  toggleAssistente,
+  toggleAssistenteWithTab,
+} = useLayout();
+```
+
+### Context Properties
+
+| Property                  | Type                      | Default | Description                                                      |
+| ------------------------- | ------------------------- | ------- | ---------------------------------------------------------------- |
+| `sidebarExpanded`         | `boolean`                 | `false` | Whether the sidebar is currently expanded (persisted in cookies) |
+| `setSidebarExpanded`      | `(v: boolean) => void`    | —       | Directly set sidebar expanded state                              |
+| `toggleSidebar`           | `() => void`              | —       | Toggle sidebar (auto-closes assistant if open)                   |
+| `sidebarWidth`            | `number`                  | `280`   | Expanded sidebar width in pixels                                 |
+| `setSidebarWidth`         | `(width: number) => void` | —       | Update the expanded sidebar width globally                       |
+| `assistenteExpanded`      | `boolean`                 | `false` | Whether the AI assistant panel is open                           |
+| `setAssistenteExpanded`   | `(v: boolean) => void`    | —       | Directly set assistant expanded state                            |
+| `toggleAssistente`        | `() => void`              | —       | Toggle assistant (auto-closes sidebar if open)                   |
+| `toggleAssistenteWithTab` | `(tab: string) => void`   | —       | Open assistant and navigate to a specific tab                    |
+| `isMobile`                | `boolean`                 | `false` | Whether the viewport is currently in mobile mode (< 768px)       |
+
+### Features
+
+- **Persistence**: The `sidebarExpanded` state is automatically saved in a cookie named `sidebar_state`.
+- **Shortcuts**: Toggling the sidebar expansion can be done via `Ctrl+B` (Windows/Linux) or `Cmd+B` (macOS).
+- **Autonomous Sidebar**: The `Sidebar` component will work even without `LayoutProvider`, although it won't synchronize with other layout-aware components.
+
+---
+
+## Usage Patterns
+
+### Reading Sidebar State in a Content Container
+
+The main content container must offset itself based on the sidebar state. Always use `sidebarWidth` from context — never hardcode pixel values:
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+function PageContent({ children }) {
+  const { sidebarExpanded, sidebarWidth } = useLayout();
+
+  return (
+    <div
+      style={{
+        paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px',
+      }}
+      className="flex-1 flex flex-col overflow-hidden transition-all duration-300"
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+> **80px** is the fixed collapsed sidebar width. This must not change.
+
+### Full Page Layout Shell
+
+```tsx
+import { Sidebar, Header } from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+function AppLayout({ user, onLogout }) {
+  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  return (
+    <div className="h-screen flex bg-muted overflow-hidden relative">
+      <Sidebar
+        expanded={sidebarExpanded}
+        width={sidebarWidth}
+        onToggle={toggleSidebar}
+        user={user}
+        onLogout={onLogout}
+        location={location}
+        navigate={navigate}
+        routes={routes}
+      />
+      <div
+        style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}
+        className="flex-1 flex flex-col overflow-hidden transition-all duration-300"
+      >
+        <Header title="Dashboard" />
+        <main className="flex-1 overflow-y-auto bg-muted p-6">{children}</main>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+- **State Management** — Never use `useState` to manage sidebar expanded/collapsed state in page components.
+- **Never** hardcode `paddingLeft: '280px'` or `pl-64` — use `sidebarWidth` from context.
+- **Mobile** — The component automatically handles the `LayoutContext` toggle via the `Header` hamburger icon.
+- `sidebarWidth` only affects the **expanded desktop state**. The collapsed state is always `80px`.
+- Use `toggleSidebar()` / `toggleAssistente()` — not `setSidebarExpanded(true)` — for user-triggered actions, since the toggle functions handle mutual exclusion.