Custom Components & Hooks
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Barekey UI layer utilizes a specialized set of custom components and hooks designed to manage organization-level workspaces, project variables, and complex layout states. These tools provide a consistent developer experience (DX) across the platform, abstracting complex logic such as role-based UI variations, responsive sidebar states, and sophisticated variable drafting mechanisms.
The architecture emphasizes a "Vercel/Apple-tier DX" by providing clean, minimal, and fast interactive elements. Key systems include a custom sidebar management system, specialized organization metric displays, and a robust state machine for managing environment variable drafts before they are persisted to the Convex backend.
Sources: AGENTS.md:10-15, pkg/ui/src/components/custom/org-workspace.tsx
Organization Workspace Components
The project provides a dedicated suite of components in org-workspace.tsx to handle the visual representation of organization and project-level data. These components are designed to be reusable across various "Org-scoped" pages like Overview, Members, and Projects.
Core Workspace Components
| Component | Description | Key Features |
|---|---|---|
OrgPageHero | A high-level section header for organization pages. | Radial gradients, customizable tags, and action buttons. |
OrgMetricCard | A card used to display key statistics (e.g., storage, requests). | Supports different "tones" (accent, muted) and icons. |
OrgIdentityChip | A compact display for organization identity. | Shows avatar, name, and slug; includes backdrop blur effects. |
OrgRoleBadge | A variant-aware badge for user roles. | Automatically maps Clerk roles (e.g., org:admin) to UI variants. |
OrgSectionCard | A layout container for grouping related content. | Supports titles, descriptions, and header actions. |
Sources: pkg/ui/src/components/custom/org-workspace.tsx:43-165
Role-Based UI Logic
The OrgRoleBadge and roleVariant utility functions determine the visual styling of a user's role within an organization based on strings retrieved from Clerk or Convex.
The logic maps administrative roles to high-contrast styles while general memberships use secondary or outline styles.
Sources: pkg/ui/src/components/custom/org-workspace.tsx:21-38
Navigation & Sidebar System
The sidebar system is implemented as a compound component structure that manages responsive states and keyboard shortcuts. It leverages a context-based provider to sync the sidebar's "expanded" or "collapsed" state across the application.
Sidebar Architecture
The SidebarProvider manages the global navigation state, including persisting the user's preference in a cookie named sidebar_state.
The system includes a keyboard shortcut (Cmd+B or Ctrl+B) to toggle visibility and uses the useIsMobile hook to switch between a standard desktop layout and a mobile-friendly Sheet component.
Sources: pkg/ui/src/components/ui/sidebar.tsx:39-105
Sheet & Drawer Implementation
For mobile views and overlays, the project uses a Sheet component built on @base-ui/react/dialog. This provides the foundation for the mobile sidebar and other slide-out interfaces.
| Component | Purpose |
|---|---|
SheetOverlay | Provides a backdrop with blur and fade animations. |
SheetContent | Container for the drawer content, supporting top, bottom, left, and right sides. |
SheetTrigger | Interactive element that opens the sheet. |
Sources: pkg/ui/src/components/ui/sheet.tsx:13-75
Variable Management Logic
The variables page implementation in pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx represents one of the most complex state management areas in the UI. It uses a "drafting" system to allow users to stage multiple changes before committing them to the database.
The Draft State Machine
Variables are not saved immediately upon editing. Instead, a StageDraftState tracks new rows, updated values, and pending deletions for a specific environment stage (e.g., development, production).
The logic includes:
hasPersistedDraftChanges: Checks if there are pending creates, updates, or deletes.upsertVariableDraftByName: Intelligent logic that either updates an existing variable's value or adds it to thenewRowsarray if it doesn't exist.importTextSource: A utility to parse.envformatted text from clipboard or file uploads into the draft state.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:50-85, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:185-225
Data Structures for Variables
The UI differentiates between variables that already exist in the database and those newly created in the current session.
type VariableDisplayRow =
| {
key: string;
type: "existing";
id: Id<"projectVariables">;
name: string;
kind: "secret";
// ... metadata
}
| {
key: string;
type: "new";
localId: string;
name: string;
kind: "secret";
};
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:110-125
Summary
Custom components and hooks in Barekey serve as the primary abstraction for managing complex state and consistent visuals. The SidebarProvider and associated components ensure a responsive navigation experience, while the specialized OrgWorkspace components provide a tailored UI for team-based secret management. The variable drafting system specifically allows for batch operations, improving performance and user control when managing sensitive environment configurations.