# UI Component Library # UI Component Library
Relevant source files The following files were used as context for generating this wiki page: - [.windsurfintructions](.windsurfintructions) - [AGENTS.md](AGENTS.md) - [README.md](README.md) - [components.json](components.json) - [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) - [postcss.config.js](postcss.config.js) - [src/app.css](src/app.css) - [src/lib/components/AppTopbar.svelte](src/lib/components/AppTopbar.svelte) - [src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte](src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte) - [src/lib/components/ui/checkbox/checkbox.svelte](src/lib/components/ui/checkbox/checkbox.svelte) - [src/lib/components/ui/input-group/input-group-addon.svelte](src/lib/components/ui/input-group/input-group-addon.svelte) - [src/lib/components/ui/input-group/input-group-button.svelte](src/lib/components/ui/input-group/input-group-button.svelte) - [src/lib/components/ui/input-group/input-group-input.svelte](src/lib/components/ui/input-group/input-group-input.svelte) - [src/lib/components/ui/input-group/input-group-text.svelte](src/lib/components/ui/input-group/input-group-text.svelte) - [src/lib/components/ui/input-group/input-group-textarea.svelte](src/lib/components/ui/input-group/input-group-textarea.svelte) - [src/lib/components/ui/input-group/input-group.svelte](src/lib/components/ui/input-group/input-group.svelte) - [src/lib/components/ui/textarea/index.ts](src/lib/components/ui/textarea/index.ts)
The Primebrick frontend employs a two-tier component architecture designed for maximum reusability and maintainability. It separates low-level UI primitives from domain-specific application components, all built using **Svelte 5 Runes** (`$state`, `$derived`, `$props`) and **TailwindCSS v4** [AGENTS.md:12-25](), [README.md:41-48](). ## Component Hierarchy The library is organized into two primary directories within `src/lib/components/`: | Tier | Directory | Description | | :--- | :--- | :--- | | **Primitives** | `ui/*` | Vendored **Shadcn-Svelte** components (e.g., Button, Input, Checkbox). These are generic, style-focused, and located in `src/lib/components/ui/` [README.md:37-39](). | | **Domain/App** | `*` (root) | Higher-level components specific to the Primebrick ecosystem (e.g., `AppSidebar`, `CommandPalette`, `EntityListTable`). These wrap primitives to provide business logic [README.md:37-39](). | ### UI Primitive Vendor Workflow Primitives are based on the **Shadcn-Svelte** registry (Nova style) using **Lucide** icons [components.json:15-17](). While vendored, they are often customized to fit the Primebrick design system, such as the `Checkbox` which includes an `indeterminate` state [src/lib/components/ui/checkbox/checkbox.svelte:11-38](). ### Data Flow & Coding Standards All components must follow strict Svelte 5 conventions: * **Props**: Passed via `$props()` with explicit TypeScript interfaces [AGENTS.md:16-18](). * **Events**: Handled via callback functions passed as props (e.g., `onclick`, `onchange`) rather than `createEventDispatcher` [AGENTS.md:22-23](). * **Composition**: Utilizes `Snippet` for passing HTML or other components as children [AGENTS.md:24-25](). ### Component Architecture Mapping The following diagram illustrates how "Natural Language" UI requirements map to specific "Code Entities" within the two-tier system. **UI System Entity Mapping** ```mermaid graph TD subgraph "Natural Language Space" A["'A standard text field'"] B["'A grouped input with a prefix'"] C["'A toggle for boolean settings'"] D["'A complex data grid'"] end subgraph "Code Entity Space" subgraph "UI Primitives (src/lib/components/ui/)" A1["Input.svelte"] B1["input-group.svelte"] B2["input-group-addon.svelte"] C1["Switch.svelte"] end subgraph "Domain Components (src/lib/components/)" D1["EntityListTable.svelte"] D2["AppSidebar.svelte"] end end A --> A1 B --> B1 B --> B2 C --> C1 D --> D1 D1 -.-> A1 ``` **Sources:** [README.md:32-40](), [src/lib/components/ui/input-group/input-group.svelte:1-20](), [AGENTS.md:27-40]() ## Component Categories Detailed documentation for specific components is divided into the following child pages: ### [Form & Input Components](#8.1) Covers the foundational elements for data entry. This includes standard primitives like `Input` and `Textarea`, as well as specialized wrappers like `InputGroup` for addons and buttons [src/lib/components/ui/input-group/input-group-input.svelte:1-22](). It also details `Checkbox` support for indeterminate states [src/lib/components/ui/checkbox/checkbox.svelte:1-38]() and Zod-integrated error displays. ### [Date Dropper & Wheel Picker](#8.2) Documents the custom `DateDropper` and `WheelPicker` systems. These components handle complex date/time selections, supporting both `CalendarDate` and `CalendarDateTime` types with integrated IANA timezone toggles for global record management. ### [Navigation & Overlay Components](#8.3) Focuses on the spatial layout and temporary UI layers. This includes the `Sidebar` primitive suite (Provider, Trigger, Rail) [src/lib/components/AppTopbar.svelte:6-124](), `DropdownMenu` enhancements for row-chrome styling, and the `CommandPalette` for global keyboard-driven navigation [src/lib/components/AppTopbar.svelte:5-128](). ### [Feedback & Display Components](#8.4) Details how the system communicates state to the user. This covers `Alert` variants mapped to `ImpactLevel` (CRITICAL, HIGH, etc.) [src/lib/components/AppTopbar.svelte:24-89](), `Badge` color mapping, and the `Sonner` toast integration. It also includes data visualization tools like the `JsonTableViewer` and drag-and-drop `Sortable` utilities. ## Theming and Design Tokens The UI library is powered by a dual-layer CSS variable system defined in `src/app.css`. It maps standard HSL/OKLCH values to semantic Tailwind v4 tokens like `--color-primary`, `--color-critical`, and `--color-sidebar-chrome` [src/app.css:9-71](). **Component Style Relationship** ```mermaid graph LR subgraph "Design Tokens (src/app.css)" T1["--color-primary"] T2["--color-critical"] T3["--radius-md"] end subgraph "UI Primitives" P1["Button.svelte"] P2["Alert.svelte"] P3["Input.svelte"] end subgraph "Domain Logic" L1["appErrors Store"] L2["ImpactLevel"] end T1 --> P1 T2 --> P2 T3 --> P3 L1 --> L2 L2 --> P2 ``` **Sources:** [src/app.css:9-71](), [src/lib/components/AppTopbar.svelte:24-89](), [src/lib/errors/app-errors.ts:20]() **Sources:** * [AGENTS.md:12-40]() * [README.md:20-53]() * [src/app.css:1-71]() * [components.json:1-21]() * [src/lib/components/AppTopbar.svelte:1-180]() * [src/lib/components/ui/checkbox/checkbox.svelte:1-38]() * [src/lib/components/ui/input-group/input-group-input.svelte:1-22]() ---