xertica-ui 2.2.1 → 2.4.0

package/docs/components/header.md

@@ -1,177 +1,177 @@
-# Header
-
-## Overview
-
-The `Header` is the global application top bar — a fixed-height strip (`64px`) rendered at the top of the application shell. It provides a standardized navigation trail (breadcrumbs) and universal system controls.
-
-It is part of the application's "Global Shell" and is designed to work in tandem with the `Sidebar` via the `LayoutContext`.
-
----
-
-## Key Features
-
-- **Breadcrumb Navigation**: The primary pattern. Supports unlimited depth levels for complex navigation hierarchies.
-- **Title Fallback**: Exception pattern for standalone pages with no navigation hierarchy — renders a plain text label.
-- **Breadcrumb Slot**: Custom element rendered immediately after the breadcrumb area (badges, buttons, chips, etc.).
-- **Responsive Navigation**: Includes a mobile hamburger toggle that synchronizes with the `Sidebar` state.
-- **Unified Controls**: Centralizes language selection, theme switching, and user profile management.
-- **Universal Actions**: Supports a custom set of sticky action buttons (like Notifications or Search) next to the user profile.
-
----
-
-## When to Use
-
-- **Always** included in the main application layout (`LayoutContent` or equivalent).
-- **Always prefer breadcrumbs** — they are the primary and recommended navigation pattern.
-- Use `title` **only** for standalone top-level pages with no parent/navigation context.
-
----
-
-## Anatomy
-
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│ [☰] Home > Settings  [BreadcrumbSlot]     [Actions] [Language] [☀] [User] │
-└──────────────────────────────────────────────────────────────────────────┘
-```
-
-- **Left Section**: Mobile menu trigger, Breadcrumb trail (or title), and optional `breadcrumbSlot`.
-- **Right Section**: Configurable action buttons, system toggles, and the User Profile dropdown.
-
----
-
-## Props
-
-| Prop                   | Type                                                                              | Default | Description                                                                                                                |
-| ---------------------- | --------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `title`                | `string`                                                                          | —       | Page title for standalone pages with **no** navigation hierarchy. Exception pattern — prefer `breadcrumbs`.                |
-| `breadcrumbs`          | `BreadcrumbType[]`                                                                | —       | **Primary pattern.** Navigation breadcrumb trail. Supports unlimited levels. Last item without `href` is the current page. |
-| `breadcrumbSlot`       | `ReactNode`                                                                       | —       | Custom element rendered immediately after the breadcrumb/title. Accepts any ReactNode — badges, buttons, chips.            |
-| `renderLink`           | `(href: string, props: { className?: string; children: ReactNode }) => ReactNode` | —       | Custom link renderer for SPA navigation (React Router, Next.js). When omitted, uses standard `<a>` tags.                   |
-| `showLanguageSelector` | `boolean`                                                                         | `true`  | Whether to show the standard language switcher.                                                                            |
-| `showThemeToggle`      | `boolean`                                                                         | `true`  | Whether to show the light/dark mode toggle button.                                                                         |
-| `user`                 | `HeaderUser`                                                                      | —       | User information and custom profile dropdown menu configuration.                                                           |
-| `actions`              | `HeaderAction[]`                                                                  | —       | Custom global action buttons (e.g., Notifications, Help).                                                                  |
-| `showSettings`         | `boolean`                                                                         | `false` | Quick access settings icon (renders before the user profile).                                                              |
-| `showLogout`           | `boolean`                                                                         | `false` | Quick logout icon (renders as the absolute last item).                                                                     |
-| `className`            | `string`                                                                          | —       | Additional CSS classes for the header container.                                                                           |
-
----
-
-## Navigation Modes
-
-### Breadcrumbs (Default — Recommended)
-
-The primary and recommended pattern. Use for any page with a navigation hierarchy.
-
-```tsx
-<Header
-  breadcrumbs={[
-    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
-    { label: 'Settings', href: '/settings' },
-    { label: 'Team Management' },
-  ]}
-/>
-```
-
-### Deep Navigation (Unlimited Levels)
-
-Breadcrumbs support any depth — do not artificially limit to 2 or 3 items.
-
-```tsx
-<Header
-  breadcrumbs={[
-    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
-    { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
-    { label: 'Organization', href: '/settings/org', icon: <FolderOpen className="size-4" /> },
-    { label: 'Teams', href: '/settings/org/teams', icon: <Users className="size-4" /> },
-    { label: 'Engineering', href: '/settings/org/teams/engineering' },
-    { label: 'Access Policies' },
-  ]}
-/>
-```
-
-### Title Only (Exception)
-
-Use **only** for standalone pages with no navigation hierarchy.
-
-```tsx
-<Header title="Dashboard" />
-```
-
-### With Breadcrumb Slot
-
-Render badges, buttons, or status chips immediately after the breadcrumb.
-
-```tsx
-import { Badge, Button } from 'xertica-ui/ui';
-
-<Header
-  breadcrumbs={[{ label: 'Home', href: '/' }, { label: 'Deployments' }]}
-  breadcrumbSlot={
-    <div className="flex items-center gap-2">
-      <Badge variant="warning">Beta</Badge>
-      <Button variant="outline" size="sm">
-        Sync
-      </Button>
-    </div>
-  }
-/>;
-```
-
----
-
-## Fallback Logic
-
-The `Header` ensures a navigation area is **never empty**:
-
-1. **Breadcrumbs**: If provided, renders the full navigation trail.
-2. **Title**: If provided (without breadcrumbs), renders a simple standalone text label.
-3. **Default**: If neither is provided, falls back to `Xertica.ai`.
-
----
-
-## SPA Navigation (renderLink)
-
-By default, breadcrumb links render as standard `<a>` tags causing full-page reloads. Use `renderLink` to integrate with client-side routers:
-
-### React Router
-
-```tsx
-import { Link } from 'react-router-dom';
-
-<Header
-  breadcrumbs={[...]}
-  renderLink={(href, props) => <Link to={href} {...props} />}
-/>
-```
-
-### Next.js
-
-```tsx
-import NextLink from 'next/link';
-
-<Header
-  breadcrumbs={[...]}
-  renderLink={(href, props) => <NextLink href={href} {...props} />}
-/>
-```
-
----
-
-## AI Rules
-
-- **Breadcrumbs First** — Always prefer `breadcrumbs` for pages with navigation context. Use `title` only for standalone pages.
-- **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
-- **SPA Navigation** — Always use `renderLink` in React Router or Next.js projects to prevent full-page reloads.
-- **breadcrumbSlot** — Use for contextual page-level indicators (environment badge, sync button, status chip) that belong visually next to the page title.
-- **Integration** — Must be placed at the top of the application shell. Do not use multiple `Header` components in the same layout.
-- **Mobile** — The component automatically handles the `LayoutContext` toggle. Do not wrap it in another button for mobile sidebar control.
-
----
-
-## Related Components
-
-- [`PageHeader`](./page-header.md) — Local content header (used INSIDE the page for titles and local actions).
-- [`Sidebar`](./sidebar.md) — The vertical navigation panel.
-- [`Breadcrumb`](./breadcrumb.md) — The underlying UI primitive.
+# Header
+
+## Overview
+
+The `Header` is the global application top bar — a fixed-height strip (`64px`) rendered at the top of the application shell. It provides a standardized navigation trail (breadcrumbs) and universal system controls.
+
+It is part of the application's "Global Shell" and is designed to work in tandem with the `Sidebar` via the `LayoutContext`.
+
+---
+
+## Key Features
+
+- **Breadcrumb Navigation**: The primary pattern. Supports unlimited depth levels for complex navigation hierarchies.
+- **Title Fallback**: Exception pattern for standalone pages with no navigation hierarchy — renders a plain text label.
+- **Breadcrumb Slot**: Custom element rendered immediately after the breadcrumb area (badges, buttons, chips, etc.).
+- **Responsive Navigation**: Includes a mobile hamburger toggle that synchronizes with the `Sidebar` state.
+- **Unified Controls**: Centralizes language selection, theme switching, and user profile management.
+- **Universal Actions**: Supports a custom set of sticky action buttons (like Notifications or Search) next to the user profile.
+
+---
+
+## When to Use
+
+- **Always** included in the main application layout (`LayoutContent` or equivalent).
+- **Always prefer breadcrumbs** — they are the primary and recommended navigation pattern.
+- Use `title` **only** for standalone top-level pages with no parent/navigation context.
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ [☰] Home > Settings  [BreadcrumbSlot]     [Actions] [Language] [☀] [User] │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+- **Left Section**: Mobile menu trigger, Breadcrumb trail (or title), and optional `breadcrumbSlot`.
+- **Right Section**: Configurable action buttons, system toggles, and the User Profile dropdown.
+
+---
+
+## Props
+
+| Prop                   | Type                                                                              | Default | Description                                                                                                                |
+| ---------------------- | --------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `title`                | `string`                                                                          | —       | Page title for standalone pages with **no** navigation hierarchy. Exception pattern — prefer `breadcrumbs`.                |
+| `breadcrumbs`          | `BreadcrumbType[]`                                                                | —       | **Primary pattern.** Navigation breadcrumb trail. Supports unlimited levels. Last item without `href` is the current page. |
+| `breadcrumbSlot`       | `ReactNode`                                                                       | —       | Custom element rendered immediately after the breadcrumb/title. Accepts any ReactNode — badges, buttons, chips.            |
+| `renderLink`           | `(href: string, props: { className?: string; children: ReactNode }) => ReactNode` | —       | Custom link renderer for SPA navigation (React Router, Next.js). When omitted, uses standard `<a>` tags.                   |
+| `showLanguageSelector` | `boolean`                                                                         | `true`  | Whether to show the standard language switcher.                                                                            |
+| `showThemeToggle`      | `boolean`                                                                         | `true`  | Whether to show the light/dark mode toggle button.                                                                         |
+| `user`                 | `HeaderUser`                                                                      | —       | User information and custom profile dropdown menu configuration.                                                           |
+| `actions`              | `HeaderAction[]`                                                                  | —       | Custom global action buttons (e.g., Notifications, Help).                                                                  |
+| `showSettings`         | `boolean`                                                                         | `false` | Quick access settings icon (renders before the user profile).                                                              |
+| `showLogout`           | `boolean`                                                                         | `false` | Quick logout icon (renders as the absolute last item).                                                                     |
+| `className`            | `string`                                                                          | —       | Additional CSS classes for the header container.                                                                           |
+
+---
+
+## Navigation Modes
+
+### Breadcrumbs (Default — Recommended)
+
+The primary and recommended pattern. Use for any page with a navigation hierarchy.
+
+```tsx
+<Header
+  breadcrumbs={[
+    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
+    { label: 'Settings', href: '/settings' },
+    { label: 'Team Management' },
+  ]}
+/>
+```
+
+### Deep Navigation (Unlimited Levels)
+
+Breadcrumbs support any depth — do not artificially limit to 2 or 3 items.
+
+```tsx
+<Header
+  breadcrumbs={[
+    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
+    { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
+    { label: 'Organization', href: '/settings/org', icon: <FolderOpen className="size-4" /> },
+    { label: 'Teams', href: '/settings/org/teams', icon: <Users className="size-4" /> },
+    { label: 'Engineering', href: '/settings/org/teams/engineering' },
+    { label: 'Access Policies' },
+  ]}
+/>
+```
+
+### Title Only (Exception)
+
+Use **only** for standalone pages with no navigation hierarchy.
+
+```tsx
+<Header title="Dashboard" />
+```
+
+### With Breadcrumb Slot
+
+Render badges, buttons, or status chips immediately after the breadcrumb.
+
+```tsx
+import { Badge, Button } from 'xertica-ui/ui';
+
+<Header
+  breadcrumbs={[{ label: 'Home', href: '/' }, { label: 'Deployments' }]}
+  breadcrumbSlot={
+    <div className="flex items-center gap-2">
+      <Badge variant="warning">Beta</Badge>
+      <Button variant="outline" size="sm">
+        Sync
+      </Button>
+    </div>
+  }
+/>;
+```
+
+---
+
+## Fallback Logic
+
+The `Header` ensures a navigation area is **never empty**:
+
+1. **Breadcrumbs**: If provided, renders the full navigation trail.
+2. **Title**: If provided (without breadcrumbs), renders a simple standalone text label.
+3. **Default**: If neither is provided, falls back to `Xertica.ai`.
+
+---
+
+## SPA Navigation (renderLink)
+
+By default, breadcrumb links render as standard `<a>` tags causing full-page reloads. Use `renderLink` to integrate with client-side routers:
+
+### React Router
+
+```tsx
+import { Link } from 'react-router-dom';
+
+<Header
+  breadcrumbs={[...]}
+  renderLink={(href, props) => <Link to={href} {...props} />}
+/>
+```
+
+### Next.js
+
+```tsx
+import NextLink from 'next/link';
+
+<Header
+  breadcrumbs={[...]}
+  renderLink={(href, props) => <NextLink href={href} {...props} />}
+/>
+```
+
+---
+
+## AI Rules
+
+- **Breadcrumbs First** — Always prefer `breadcrumbs` for pages with navigation context. Use `title` only for standalone pages.
+- **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
+- **SPA Navigation** — Always use `renderLink` in React Router or Next.js projects to prevent full-page reloads.
+- **breadcrumbSlot** — Use for contextual page-level indicators (environment badge, sync button, status chip) that belong visually next to the page title.
+- **Integration** — Must be placed at the top of the application shell. Do not use multiple `Header` components in the same layout.
+- **Mobile** — The component automatically handles the `LayoutContext` toggle. Do not wrap it in another button for mobile sidebar control.
+
+---
+
+## Related Components
+
+- [`PageHeader`](./page-header.md) — Local content header (used INSIDE the page for titles and local actions).
+- [`Sidebar`](./sidebar.md) — The vertical navigation panel.
+- [`Breadcrumb`](./breadcrumb.md) — The underlying UI primitive.