# Navigation & Overlay Components

# Navigation & Overlay Components

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [src/lib/components/ui/breadcrumb/breadcrumb-ellipsis.svelte](src/lib/components/ui/breadcrumb/breadcrumb-ellipsis.svelte)
- [src/lib/components/ui/breadcrumb/breadcrumb.svelte](src/lib/components/ui/breadcrumb/breadcrumb.svelte)
- [src/lib/components/ui/choicebox/choicebox-description.svelte](src/lib/components/ui/choicebox/choicebox-description.svelte)
- [src/lib/components/ui/choicebox/choicebox-item.svelte](src/lib/components/ui/choicebox/choicebox-item.svelte)
- [src/lib/components/ui/choicebox/choicebox-title.svelte](src/lib/components/ui/choicebox/choicebox-title.svelte)
- [src/lib/components/ui/choicebox/choicebox.svelte](src/lib/components/ui/choicebox/choicebox.svelte)
- [src/lib/components/ui/choicebox/ctx.ts](src/lib/components/ui/choicebox/ctx.ts)
- [src/lib/components/ui/choicebox/index.ts](src/lib/components/ui/choicebox/index.ts)
- [src/lib/components/ui/command/command-item.svelte](src/lib/components/ui/command/command-item.svelte)
- [src/lib/components/ui/command/command-link-item.svelte](src/lib/components/ui/command/command-link-item.svelte)
- [src/lib/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte](src/lib/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte)
- [src/lib/components/ui/dropdown-menu/dropdown-menu-item-selected.ts](src/lib/components/ui/dropdown-menu/dropdown-menu-item-selected.ts)
- [src/lib/components/ui/dropdown-menu/dropdown-menu-item.svelte](src/lib/components/ui/dropdown-menu/dropdown-menu-item.svelte)
- [src/lib/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte](src/lib/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte)
- [src/lib/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte](src/lib/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte)
- [src/lib/components/ui/label/index.ts](src/lib/components/ui/label/index.ts)
- [src/lib/components/ui/label/label.svelte](src/lib/components/ui/label/label.svelte)
- [src/lib/components/ui/menu-row-chrome.ts](src/lib/components/ui/menu-row-chrome.ts)
- [src/lib/components/ui/popover/index.ts](src/lib/components/ui/popover/index.ts)
- [src/lib/components/ui/popover/popover-content.svelte](src/lib/components/ui/popover/popover-content.svelte)
- [src/lib/components/ui/popover/popover-trigger.svelte](src/lib/components/ui/popover/popover-trigger.svelte)
- [src/lib/components/ui/sidebar/sidebar-menu-button.svelte](src/lib/components/ui/sidebar/sidebar-menu-button.svelte)
- [src/lib/components/ui/sidebar/sidebar-menu-sub-button.svelte](src/lib/components/ui/sidebar/sidebar-menu-sub-button.svelte)
- [src/lib/components/ui/sidebar/sidebar-rail.svelte](src/lib/components/ui/sidebar/sidebar-rail.svelte)
- [src/lib/components/ui/sidebar/sidebar-trigger.svelte](src/lib/components/ui/sidebar/sidebar-trigger.svelte)
- [src/lib/components/ui/tabs/tabs-trigger.svelte](src/lib/components/ui/tabs/tabs-trigger.svelte)

</details>



This section covers the interactive navigation and overlay primitives used throughout the Primebrick frontend. These components are built upon **Bits UI** (the headless foundation for Shadcn-Svelte) and customized with the application's specific "chrome" styling to ensure visual consistency across menus, sidebars, and selection widgets.

## Dropdown Menu & Menu Chrome

The Dropdown Menu system utilizes a shared styling logic called "Menu Row Chrome" to maintain consistency between standard dropdowns, the command palette, and sidebar navigation items [src/lib/components/ui/menu-row-chrome.ts:1-7]().

### Menu Row Chrome Styling
The system defines specific CSS classes for different interaction states:
*   **Neutral Hover**: Uses `zinc-200` (light) or `zinc-700` (dark) to highlight items without shifting layout [src/lib/components/ui/menu-row-chrome.ts:20-21]().
*   **Selected Surface**: Active items (like the current language or active sidebar route) use a `sky-100` background in light mode and `neutral-800` in dark mode [src/lib/components/ui/menu-row-chrome.ts:10-17]().
*   **Soft Frames**: Items use `border-transparent` by default so that adding a border on highlight does not cause "reflow" or jitter [src/lib/components/ui/menu-row-chrome.ts:6-7]().

### Specialized Items
*   **DropdownMenuItem**: Supports a `destructive` variant for delete actions, applying `text-destructive` and specialized hover states [src/lib/components/ui/dropdown-menu/dropdown-menu-item.svelte:28-29]().
*   **CheckboxItem**: Integrates the `Checkbox` component within the dropdown row, supporting `indeterminate` states [src/lib/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte:34-37]().
*   **RadioItem**: Displays a `CircleIcon` indicator when selected, used for single-choice lists like pagination sizes or language selection [src/lib/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte:27-36]().
*   **SubTrigger & SubContent**: Used for nested menus. The `SubTrigger` automatically appends a `ChevronRightIcon` [src/lib/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte:33]().

**Sources:** [src/lib/components/ui/menu-row-chrome.ts:1-75](), [src/lib/components/ui/dropdown-menu/dropdown-menu-item.svelte:1-32](), [src/lib/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte:1-40](), [src/lib/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte:1-37](), [src/lib/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte:1-34]().

---

## Sidebar Primitives

The sidebar architecture is a multi-component system that manages layout, state (collapsed vs. expanded), and navigation links.

### Core Components
| Component | Description |
| :--- | :--- |
| `SidebarProvider` | Context provider managing the `sidebar` state (expanded/collapsed/mobile) [src/lib/components/ui/sidebar/context.svelte.js](). |
| `SidebarMenuButton` | The primary interactive link. Supports `isActive` state which applies `menuSidebarActiveChrome` [src/lib/components/ui/sidebar/sidebar-menu-button.svelte:64-78](). |
| `SidebarMenuSubButton` | A smaller variant for nested navigation items within a group. |
| `SidebarTrigger` | A button that toggles the sidebar state via the context. |
| `SidebarRail` | A hit area on the edge of the sidebar for resizing or manual toggling. |
| `SidebarInset` | The main content wrapper that adjusts its padding based on sidebar state. |

### Logic & Tooltips
`SidebarMenuButton` includes built-in `Tooltip` integration. When the sidebar is in `collapsed` state, the button automatically renders its content inside a Tooltip if `tooltipContent` is provided [src/lib/components/ui/sidebar/sidebar-menu-button.svelte:94-111]().

**Sources:** [src/lib/components/ui/sidebar/sidebar-menu-button.svelte:1-112](), [src/lib/components/ui/menu-row-chrome.ts:68-74]().

---

## Popover & Tabs

### Popover
The `Popover` component is used for floating panels that appear relative to a trigger (e.g., the User Profile menu).
*   **Implementation**: Wraps `bits-ui` Popover with standard Primebrick styling [src/lib/components/ui/popover/index.ts:1-18]().
*   **Positioning**: Defaults to a `sideOffset` of 4px and center alignment [src/lib/components/ui/popover/popover-content.svelte:7-9]().
*   **Z-Index**: Set to `z-120` to ensure it appears above most shell elements [src/lib/components/ui/popover/popover-content.svelte:20]().

### Tabs
Tabs are used primarily in the Settings area to switch between Profile, Security, and Organization views.
*   **Variants**: Supports `default` (pill style) and `line` (underline style) variants [src/lib/components/ui/tabs/tabs-trigger.svelte:16-19]().
*   **Active State**: The `line` variant uses an `after:` pseudo-element to animate a bottom border highlight [src/lib/components/ui/tabs/tabs-trigger.svelte:19]().

**Sources:** [src/lib/components/ui/popover/index.ts:1-18](), [src/lib/components/ui/popover/popover-content.svelte:1-24](), [src/lib/components/ui/tabs/tabs-trigger.svelte:1-23]().

---

## Choicebox Selection Widget

The `Choicebox` is a high-level selection widget used for large, descriptive radio-style options (e.g., selecting a Template Type).

### Component Structure
The Choicebox uses a context-based pattern to manage selection state among its children.

**Choicebox Component Relationship**
```mermaid
graph TD
    subgraph "Choicebox System"
        CB["Choicebox.svelte"] -- "provides" --> CTX["Choicebox Context"]
        CTX -- "consumes" --> CBI["ChoiceboxItem.svelte"]
        CBI -- "contains" --> CBT["ChoiceboxTitle.svelte"]
        CBI -- "contains" --> CBD["ChoiceboxDescription.svelte"]
    end

    style CB stroke-width:2px
    style CBI stroke-width:2px
```

### Key Functions
*   **getChoiceboxContext()**: Retrieves the reactive state from the parent `Choicebox` [src/lib/components/ui/choicebox/ctx.ts]().
*   **handleClick()**: Triggered on `ChoiceboxItem`. It calls `ctx.setActive(value)` to update the global selection [src/lib/components/ui/choicebox/choicebox-item.svelte:21-25]().
*   **Keyboard Navigation**: Supports `Enter` and `Space` keys to select options for accessibility [src/lib/components/ui/choicebox/choicebox-item.svelte:27-32]().

**Sources:** [src/lib/components/ui/choicebox/choicebox-item.svelte:1-53](), [src/lib/components/ui/choicebox/ctx.ts](), [src/lib/components/ui/choicebox/index.ts:1-15]().

---

## Component Mapping: Code to UI Space

The following diagram maps technical Svelte components to their visual representation in the application shell.

**UI Surface Mapping**
```mermaid
graph LR
    subgraph "Navigation Components"
        "AppSidebar.svelte" --> "SidebarProvider"
        "AppSidebar.svelte" --> "SidebarMenuButton"
        "AppTopbar.svelte" --> "Breadcrumb"
        "AppTopbar.svelte" --> "DropdownMenu"
    end

    subgraph "Overlay Components"
        "EntityListTable.svelte" --> "Popover"
        "SettingsLayout.svelte" --> "Tabs"
        "TemplateForms" --> "Choicebox"
    end

    "SidebarMenuButton" --- "menuSidebarActiveChrome"
    "DropdownMenu" --- "menuListSelectedSurfaceDropdownClasses"
```

**Sources:** [src/lib/components/ui/menu-row-chrome.ts:10-17](), [src/lib/components/ui/menu-row-chrome.ts:68-74](), [src/lib/components/ui/dropdown-menu/dropdown-menu-item-selected.ts:8-11]().

---