Copy page

Frontend

Global Side Sheet System

Global Side Sheet System

Relevant source files

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

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

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

Code
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

Code
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.

Code
<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

---