Skip to main content

fc_ui/
lib.rs

1#![allow(missing_docs)]
2
3//! # fc-ui: Professional UI Component Library for GPUI
4//!
5//! A comprehensive, themeable component library inspired by shadcn/ui, designed specifically
6//! for building polished desktop applications using GPUI. Provides a complete set of
7//! reusable components with consistent styling, smooth animations, and progressively tested
8//! accessibility support.
9//! ## Architecture Overview
10//!
11//! The library is organized into several key modules:
12//! - `theme`: Design tokens and theming system with light/dark variants
13//! - `components`: Core interactive elements (buttons, inputs, selects, etc.)
14//! - `display`: Presentation components (tables, cards, badges, etc.)
15//! - `navigation`: Navigation components (sidebars, menus, tabs, etc.)
16//! - `overlays`: Modal dialogs, popovers, tooltips, and command palettes
17//! - `animations`: Professional animation presets and easing functions
18//!
19//! ## Key Features
20//!
21//! - **Theme System**: Design tokens across 18 preset themes with light and dark
22//!   variants; the active theme is installed explicitly via `theme::install_theme`
23//!   (the library does not track the system appearance automatically)
24//! - **Accessibility**: Keyboard support across controls, with tested AccessKit semantics for
25//!   Button, Checkbox, Select, Input, and Dialog
26//! - **Performance**: Optimized rendering with virtual scrolling for large datasets
27//! - **Animation**: Smooth, professional animations using spring physics and easing curves
28//! - **Type Safety**: Strong typing throughout with compile-time guarantees
29//!
30//! ## Design Philosophy
31//!
32//! Components follow shadcn/ui principles with GPUI-specific optimizations:
33//! - Composition over inheritance for flexible component APIs
34//! - Builder pattern for ergonomic component construction
35//! - Entity-based state management for complex interactive components
36//! - Consistent naming and styling patterns across all components
37//!
38//! ## Usage Example
39//!
40//! ```rust,ignore
41//! use fc_ui::{prelude::*, theme};
42//!
43//! // Initialize theme and components
44//! fn init_app(cx: &mut gpui::App) {
45//!     theme::install_theme(cx, theme::Theme::dark());
46//!     fc_ui::init(cx);
47//! }
48//!
49//! // Use components in your views
50//! fn render(cx: &mut gpui::App) -> impl gpui::IntoElement {
51//!     div()
52//!         .child(Button::new("Click me").on_click(|_, _, _| println!("Clicked!")))
53//!         .child(Input::new(&input_state).placeholder("Enter text..."))
54//! }
55//! ```
56//!
57
58extern crate gpui;
59
60mod capabilities;
61
62#[cfg(test)]
63mod init_contract_tests;
64
65pub mod animate;
66pub mod animated_state;
67pub mod animation_coordinator;
68pub mod animations;
69pub mod charts;
70pub mod components;
71pub mod content_transition;
72pub mod display;
73pub mod gestures;
74pub mod gpui_ext;
75pub mod layout;
76pub mod navigation;
77pub mod overlays;
78pub mod prelude;
79pub mod responsive;
80pub mod scroll_physics;
81pub mod spring;
82pub mod styled_ext;
83pub mod theme;
84pub mod transitions;
85pub mod virtual_list;
86
87/// Extension traits for common types
88pub mod util;
89
90/// Font loading and registration
91pub mod fonts;
92
93/// Icon configuration for custom asset paths
94pub mod icon_config;
95
96/// HTTP client for remote image loading
97pub mod http;
98
99// Re-export commonly used icon configuration functions
100pub use icon_config::set_icon_base_path;
101
102// Re-export HTTP client functions
103pub use http::{init_http, init_http_with_user_agent, DEFAULT_USER_AGENT};
104#[cfg(feature = "http")]
105pub use http::{try_init_http, try_init_http_with_user_agent, HttpInitError, HttpSetup};
106
107/// Error returned by explicit root initialization.
108#[cfg(feature = "http")]
109#[derive(Debug)]
110pub enum InitError {
111    /// A root initializer has already completed for this application.
112    AlreadyInitialized,
113    /// The requested built-in HTTP client could not be constructed.
114    Http(HttpInitError),
115}
116
117#[cfg(feature = "http")]
118impl std::fmt::Display for InitError {
119    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
120        match self {
121            Self::AlreadyInitialized => formatter.write_str("fc-ui is already initialized"),
122            Self::Http(error) => write!(formatter, "{error}"),
123        }
124    }
125}
126
127#[cfg(feature = "http")]
128impl std::error::Error for InitError {
129    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
130        match self {
131            Self::AlreadyInitialized => None,
132            Self::Http(error) => Some(error),
133        }
134    }
135}
136
137#[cfg(feature = "http")]
138impl From<HttpInitError> for InitError {
139    fn from(error: HttpInitError) -> Self {
140        Self::Http(error)
141    }
142}
143
144fn init_capabilities(cx: &mut gpui::App) {
145    capabilities::foundation::init(cx);
146
147    // GPUI resolves same-depth keybinding conflicts in reverse registration order.
148    // Keep this historical cross-capability sequence stable for downstream applications.
149    capabilities::controls::init_before_image_viewer(cx);
150    capabilities::media::init_image(cx);
151    capabilities::controls::init_after_image_viewer(cx);
152    capabilities::media::init_video(cx);
153    #[cfg(feature = "editor")]
154    capabilities::editor::init(cx);
155    capabilities::navigation::init(cx);
156    capabilities::overlays::init(cx);
157}
158
159/// Initialize the UI library without changing GPUI's HTTP client.
160///
161/// This registers all necessary keybindings, fonts, and component systems. Use
162/// [`try_init_with`] when the built-in HTTP client is required for remote images.
163pub fn init(cx: &mut gpui::App) {
164    if !capabilities::foundation::initialization::begin(cx, "fc-ui") {
165        return;
166    }
167
168    init_capabilities(cx);
169}
170
171/// Initialize the UI library with an explicit HTTP-client policy.
172///
173/// Unlike [`init`], this reports an error when root initialization has already
174/// completed, so a requested HTTP policy is never silently ignored.
175#[cfg(feature = "http")]
176pub fn try_init_with(cx: &mut gpui::App, http: HttpSetup) -> Result<(), InitError> {
177    if capabilities::foundation::initialization::is_initialized(cx, "fc-ui") {
178        return Err(InitError::AlreadyInitialized);
179    }
180
181    http::try_init_http_with_setup(cx, http)?;
182
183    if !capabilities::foundation::initialization::begin(cx, "fc-ui") {
184        return Err(InitError::AlreadyInitialized);
185    }
186
187    init_capabilities(cx);
188    Ok(())
189}