# Global Side Sheet System

# Global Side Sheet System

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

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

- [.windsurfintructions](.windsurfintructions)
- [AGENTS.md](AGENTS.md)
- [README.md](README.md)
- [docs/ai/README.md](docs/ai/README.md)
- [docs/ai/SKILLS.md](docs/ai/SKILLS.md)
- [docs/ai/patterns.md](docs/ai/patterns.md)
- [docs/gitflow.md](docs/gitflow.md)
- [src/lib/components/BrowserClientInfo.svelte](src/lib/components/BrowserClientInfo.svelte)
- [src/lib/components/ui/sheet/sheet-content.svelte](src/lib/components/ui/sheet/sheet-content.svelte)
- [src/lib/components/ui/sheet/sheet-overlay.svelte](src/lib/components/ui/sheet/sheet-overlay.svelte)
- [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte](src/lib/entity-list/sheets/panels/ColumnsPanel.svelte)
- [src/lib/entity-list/sheets/panels/SearchInPanel.svelte](src/lib/entity-list/sheets/panels/SearchInPanel.svelte)
- [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte](src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte)
- [src/lib/shell/sheets/SheetHeader.svelte](src/lib/shell/sheets/SheetHeader.svelte)
- [src/lib/shell/sheets/SheetHost.svelte](src/lib/shell/sheets/SheetHost.svelte)
- [src/lib/shell/sheets/panels/VersionsPanel.svelte](src/lib/shell/sheets/panels/VersionsPanel.svelte)
- [src/lib/shell/sheets/sheet-manager.svelte.ts](src/lib/shell/sheets/sheet-manager.svelte.ts)

</details>



The Global Side Sheet system provides a unified infrastructure for managing slide-out panels (sheets) across the Primebrick application. It utilizes a singleton manager to control visibility and content, ensuring a consistent user experience while maintaining strict TypeScript type safety for panel properties.

## System Overview

The system is built on three main pillars:
1.  **`sheet-manager.svelte.ts`**: A reactive singleton managing the global state and providing the API to open/close panels [src/lib/shell/sheets/sheet-manager.svelte.ts:1-112]().
2.  **`SheetHost.svelte`**: A root-level component that listens to the manager's state and renders the appropriate panel from a central registry [src/lib/shell/sheets/SheetHost.svelte:1-51]().
3.  **Type-Safe Registry**: A mapping system that correlates `SheetPanelId` with specific property interfaces [src/lib/shell/sheets/sheet-manager.svelte.ts:3-39]().

### Data Flow and Lifecycle

The following diagram illustrates the flow from a UI action to the rendering of a specific panel.

**Sheet Activation Flow**
```mermaid
sequenceDiagram
    participant UI as "UI Component"
    participant SM as "sheet-manager.svelte.ts"
    participant SH as "SheetHost.svelte"
    participant PR as "Panel Registry"

    UI->>SM: openSheet('entity.versionHistory', { entity, rowUuid })
    Note over SM: Updates reactive $state<SheetState>
    SM-->>SH: Reactive update triggers re-render
    SH->>PR: Look up 'entity.versionHistory'
    PR-->>SH: Returns VersionHistoryPanel.svelte
    SH->>SH: Render <Panel {...props} />
```
**Sources:** [src/lib/shell/sheets/sheet-manager.svelte.ts:74-92](), [src/lib/shell/sheets/SheetHost.svelte:27-49]()

## Sheet Manager Singleton

The `sheet-manager.svelte.ts` file defines the global `sheetState` using Svelte 5 runes. It handles the logic for opening, closing, and replacing sheets while managing a race-condition guard for the underlying dialog implementation.

### Key State and Functions

| Entity | Type | Description |
| :--- | :--- | :--- |
| `sheetState` | `$state<SheetState>` | Holds `open`, `panelId`, `props`, `side`, and `modal` status [src/lib/shell/sheets/sheet-manager.svelte.ts:64-72](). |
| `openSheet()` | `Function` | Sets the panel ID and props, then triggers the opening animation [src/lib/shell/sheets/sheet-manager.svelte.ts:74-92](). |
| `closeSheet()` | `Function` | Closes the sheet and clears state on a microtask to allow clean transitions [src/lib/shell/sheets/sheet-manager.svelte.ts:103-112](). |
| `replaceSheet()` | `Function` | Switches the current panel content without closing the sheet container [src/lib/shell/sheets/sheet-manager.svelte.ts:94-101](). |

### Race-Condition Guard: `suppressDialogCloseFromHost`

The underlying `bits-ui` Dialog can occasionally emit an `onOpenChange(false)` event immediately after programmatic activation. To prevent the sheet from closing before it paints, the manager uses a `suppressDialogCloseFromHost` flag [src/lib/shell/sheets/sheet-manager.svelte.ts:44-52](). 

When `openSheet` is called, this flag is set to `true` and then reset to `false` after two `requestAnimationFrame` cycles [src/lib/shell/sheets/sheet-manager.svelte.ts:85-91](). The `SheetHost` checks `shouldSuppressSheetDialogClose()` before executing `closeSheet()` [src/lib/shell/sheets/SheetHost.svelte:35-42]().

**Sources:** [src/lib/shell/sheets/sheet-manager.svelte.ts:44-52](), [src/lib/shell/sheets/sheet-manager.svelte.ts:85-91](), [src/lib/shell/sheets/SheetHost.svelte:35-42]()

## Panel Registry and Type Safety

The system enforces type safety through the `SheetPanelPropsMap`. This ensures that when a developer calls `openSheet`, the IDE and compiler verify that the correct properties are provided for that specific panel ID.

### Registered Panel IDs

The following panels are currently registered in the system:

| Panel ID | Component | Purpose |
| :--- | :--- | :--- |
| `shell.errors` | `ErrorsPanel.svelte` | Displays global application error logs. |
| `shell.versions` | `VersionsPanel.svelte` | Shows frontend/backend versioning and health info [src/lib/shell/sheets/panels/VersionsPanel.svelte:1-101](). |
| `entity.searchIn` | `SearchInPanel.svelte` | Configuration for specific field searching in tables [src/lib/entity-list/sheets/panels/SearchInPanel.svelte:1-79](). |
| `entity.columns` | `ColumnsPanel.svelte` | Drag-and-drop column reordering and visibility [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte:1-180](). |
| `entity.filters` | `FiltersPanel.svelte` | Advanced filtering interface for entity lists. |
| `entity.versionHistory` | `VersionHistoryPanel.svelte` | Detailed audit log for a specific entity record [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:1-201](). |

**Sources:** [src/lib/shell/sheets/sheet-manager.svelte.ts:3-9](), [src/lib/shell/sheets/SheetHost.svelte:18-25]()

### Mapping System Diagram

This diagram maps the logical IDs to their TypeScript interfaces and Svelte components.

**Code Entity Mapping**
```mermaid
classDiagram
    class SheetPanelId {
        <<enumeration>>
        shell.errors
        shell.versions
        entity.searchIn
        entity.columns
        entity.filters
        entity.versionHistory
    }

    class SheetPanelPropsMap {
        shell.errors: Record
        shell.versions: Record
        entity.versionHistory: {entity, rowUuid, columns}
    }

    class Registry {
        'shell.versions' : VersionsPanel.svelte
        'entity.columns' : ColumnsPanel.svelte
        'entity.versionHistory' : VersionHistoryPanel.svelte
    }

    SheetPanelId ..> SheetPanelPropsMap : Defines props for
    SheetPanelId ..> Registry : Keys for lookup
```
**Sources:** [src/lib/shell/sheets/sheet-manager.svelte.ts:3-39](), [src/lib/shell/sheets/SheetHost.svelte:18-25]()

## Layout Components

### SheetHost.svelte
This component is placed at the root of the application shell. It uses `$derived` runes to reactively select the component from the registry based on `sheetState.panelId` [src/lib/shell/sheets/SheetHost.svelte:27-28](). It passes the `panelProps` dynamically using the `{...panelProps}` spread operator [src/lib/shell/sheets/SheetHost.svelte:48]().

### SheetHeader.svelte
A reusable layout component for sheet tops. It provides a standard styling for the title and an optional actions snippet (usually containing a "Close" or "Reset" button) [src/lib/shell/sheets/SheetHeader.svelte:1-21]().

**Standard Usage in Panels:**
Panels define `headerTitle` and `headerActions` snippets and pass them to the `SheetHeader` [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte:37-61]().

```svelte
<SheetHeader title={headerTitle} actions={headerActions} />
```

**Sources:** [src/lib/shell/sheets/SheetHost.svelte:27-49](), [src/lib/shell/sheets/SheetHeader.svelte:12-21](), [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte:61]()

---