SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
use crate::ui_kit::BackingTooltipExt as _;
use solidcraft_engine::panels::*;
/// Content receives this value separately from state/model/command services. All
/// geometry is already in logical units; do not multiply it by egui UI scale.
#[derive(Clone, Debug, PartialEq)]
pub struct PanelContext {
pub instance: InstanceId,
pub owner: super::ContentOwner,
pub workspace: WorkspaceId,
pub document: Option<DocumentId>,
pub viewport: ViewportId,
pub native_host: Option<HostId>,
pub outer: LogicalRect,
pub usable_body: Option<LogicalRect>,
pub flow: Flow,
pub size_class: SizeClass,
pub focused: bool,
pub direction: Direction,
pub motion: Motion,
}
impl PanelContext {
pub fn validate(&self) -> PanelResult<()> {
valid_id(&self.instance.0)?;
self.owner.validate()?;
LocalScope { workspace: self.workspace.clone(), document: self.document.clone(), viewport: self.viewport.clone() }.validate()?;
self.outer.validate()?;
if let Some(body) = self.usable_body {
body.validate()?;
if !self.outer.contains_rect(body) {
return Err(error(Rule::Bounds, "presentation body outside host"));
}
}
if let Some(host) = &self.native_host {
valid_id(&host.0)?;
if self.viewport.0 != host.0 {
return Err(error(Rule::Placement, "native presentation has wrong local viewport"));
}
}
if let super::ContentOwner::Document(document) = &self.owner
&& self.document.as_ref() != Some(document)
{
return Err(error(Rule::Placement, "presentation document differs from content owner"));
}
if let super::ContentOwner::Workspace(workspace) = &self.owner
&& self.workspace != *workspace
{
return Err(error(Rule::Placement, "presentation workspace differs from content owner"));
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Motion {
Reduced,
Animated,
}
impl Motion {
/// Reparent/focus must not wait for animation completion, including at zero duration.
pub fn duration_ms(self, requested: u16) -> u16 {
if self == Self::Reduced { 0 } else { requested.min(500) }
}
}
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct LocalScope {
pub workspace: WorkspaceId,
pub document: Option<DocumentId>,
pub viewport: ViewportId,
}
impl LocalScope {
pub fn validate(&self) -> PanelResult<()> {
valid_id(&self.workspace.0)?;
valid_id(&self.viewport.0)?;
if let Some(id) = &self.document {
valid_id(&id.0)?;
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq)]
pub enum LocalRequest {
KeyboardOwner { instance: InstanceId, control: ControlId },
ReleaseKeyboard { instance: InstanceId },
Focus { instance: InstanceId, control: ControlId },
FileDrop { instance: InstanceId, name: String, bytes: Vec<u8> },
PointerDrop { instance: InstanceId, at: Point, payload: String },
Overlay { instance: InstanceId, region: InputRegion },
ClearOverlays { instance: InstanceId },
Clipboard { instance: InstanceId, text: String },
Pick { instance: InstanceId, at: Point },
}
impl LocalRequest {
pub fn instance(&self) -> &InstanceId {
match self {
Self::KeyboardOwner { instance, .. }
| Self::ReleaseKeyboard { instance }
| Self::Focus { instance, .. }
| Self::FileDrop { instance, .. }
| Self::PointerDrop { instance, .. }
| Self::Overlay { instance, .. }
| Self::ClearOverlays { instance }
| Self::Clipboard { instance, .. }
| Self::Pick { instance, .. } => instance,
}
}
pub fn validate(&self) -> PanelResult<()> {
valid_id(&self.instance().0)?;
match self {
Self::KeyboardOwner { control, .. } | Self::Focus { control, .. } => valid_id(&control.0)?,
Self::FileDrop { name, bytes, .. } => {
if name.is_empty() || name.len() > 256 || bytes.len() > MAX_ENVELOPE_BYTES {
return Err(error(Rule::CollectionLimit, "file drop bound"));
}
}
Self::PointerDrop { at, payload, .. } => {
at.validate()?;
if payload.len() > 4096 {
return Err(error(Rule::CollectionLimit, "pointer drop payload bound"));
}
}
Self::Overlay { region, .. } => {
valid_id(®ion.control.0)?;
region.bounds.validate()?;
if region.accessible_name.is_empty() || region.accessible_name.len() > 256 {
return Err(error(Rule::Bounds, "overlay semantic name bound"));
}
}
Self::Clipboard { text, .. } if text.len() > MAX_ENVELOPE_BYTES => return Err(error(Rule::CollectionLimit, "clipboard bound")),
Self::Pick { at, .. } => at.validate()?,
_ => {}
}
Ok(())
}
}
/// Services must reject cross-document/viewport delivery. A native redock drops
/// host-local focus/overlays but retains the content controller and its owner.
pub trait PanelLocalServices {
fn request(&mut self, scope: &LocalScope, request: LocalRequest) -> PanelResult<()>;
/// Optional UI-only provenance for an actual overlay Area. Existing local
/// providers receive the same typed request; no layer enters saved state.
fn request_overlay_layer(&mut self, scope: &LocalScope, instance: &InstanceId, region: InputRegion, _layer: egui::LayerId) -> PanelResult<()> {
self.request(scope, LocalRequest::Overlay { instance: instance.clone(), region })
}
/// Report a response just created by the current content render. The host
/// uses this optional provenance to retain/restore focus; reporting never
/// requests focus or stores editor state. Hidden or disabled controls are
/// ineligible, and absence of a report must never fall back to an old widget.
fn register_focus_response(&mut self, _scope: &LocalScope, _instance: &InstanceId, _response: &egui::Response) -> PanelResult<()> {
Ok(())
}
fn release(&mut self, scope: &LocalScope, instance: &InstanceId);
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RuntimeAction {
pub id: ControlId,
pub label: String,
pub enabled: bool,
pub disabled_reason: Option<String>,
/// Toggle state, when the action represents a persistent on/off choice.
pub pressed: Option<bool>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PanelPresentation {
/// Already localised by content; fixtures use specimen text only.
pub title: String,
pub icon: String,
pub status: Option<String>,
pub attention: bool,
pub actions: Vec<RuntimeAction>,
}
impl PanelPresentation {
pub fn validate(&self) -> PanelResult<()> {
if self.title.is_empty() || self.title.len() > 256 || self.status.as_ref().is_some_and(|s| s.len() > 1024) || self.actions.len() > MAX_TABS {
return Err(error(Rule::CollectionLimit, "presentation bound"));
}
valid_id(&self.icon)?;
let mut ids = std::collections::BTreeSet::new();
for action in &self.actions {
valid_id(&action.id.0)?;
if !ids.insert(&action.id) {
return Err(error(Rule::DuplicateId, "duplicate content action"));
}
if action.label.is_empty()
|| action.label.len() > 256
|| action.disabled_reason.as_ref().is_some_and(|r| r.is_empty() || r.len() > 256)
|| !action.enabled && action.disabled_reason.is_none()
{
return Err(error(Rule::Bounds, "content action label/reason bound"));
}
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ContentSlot {
Header,
Body,
Footer,
/// One total short-wide row, sharing its height with the host controls.
Inline,
}
/// A frame-scoped content binding. Application bodies may borrow their existing
/// owner for this paint without storing that borrow in a retained controller.
/// The host supplies the same bounded slot and focus services as ordinary content.
pub trait FramePanelContent {
fn render(
&mut self,
slot: ContentSlot,
ui: &mut egui::Ui,
context: &PanelContext,
content: &mut dyn super::PanelController,
services: &mut super::ContentServices<'_>,
) -> PanelResult<()> {
if slot == ContentSlot::Inline { content.render_inline(ui, context, services) } else { content.render(slot, ui, context, services) }
}
}
pub(super) struct ControllerFrameContent;
impl FramePanelContent for ControllerFrameContent {}
/// Shared host adapter seam. Geometry is resolved by the host; content chooses
/// its own scrolling within slots. The egui adapter below owns one kit Container.
pub trait PanelHost {
fn mount(
&mut self,
geometry: &ResolvedPanel,
presentation: &PanelPresentation,
context: &PanelContext,
content: &mut dyn PanelController,
services: &mut ContentServices<'_>,
) -> PanelResult<()>;
}
/// Two-phase host effects. `prepare` is side-effect-free and fallible; `commit`
/// cannot fail. Native adapters must stage resources before acknowledging prepare
/// and retain/restorable resources until the layout transaction commits.
pub trait NativeHostAdapter {
fn capabilities(&self) -> HostCapabilities;
fn prepare(&self, effects: &[HostEffect]) -> PanelResult<()>;
fn commit(&mut self, effects: &[HostEffect]);
}
/// Persistent truthful default for the internal in-app host. It owns no native
/// resources and must never acknowledge a create/rebind/release effect.
#[derive(Default)]
pub struct InAppNativeAdapter;
impl NativeHostAdapter for InAppNativeAdapter {
fn capabilities(&self) -> HostCapabilities {
HostCapabilities { native_windows: false, persistence: false, max_native_hosts: 0 }
}
fn prepare(&self, effects: &[HostEffect]) -> PanelResult<()> {
if effects
.iter()
.any(|effect| matches!(effect, HostEffect::CreateNative { .. } | HostEffect::RebindNative { .. } | HostEffect::ReleaseNative { .. }))
{
return Err(error(Rule::Capability, "in-app adapter has no native resources"));
}
Ok(())
}
fn commit(&mut self, _effects: &[HostEffect]) {}
}
/// Existing ui_kit is the outer boundary. This adapter paints into host-provided
/// space; it does not invent windows, docking gestures or a second camera path.
pub struct EguiPanelHost<'a> {
pub ui: &'a mut egui::Ui,
}
impl PanelHost for EguiPanelHost<'_> {
fn mount(
&mut self,
geometry: &ResolvedPanel,
presentation: &PanelPresentation,
context: &PanelContext,
content: &mut dyn PanelController,
services: &mut ContentServices<'_>,
) -> PanelResult<()> {
geometry.validate()?;
presentation.validate()?;
context.validate()?;
if geometry.instance != context.instance || geometry.outer != context.outer || geometry.body != context.usable_body {
return Err(error(Rule::Placement, "host geometry differs from presentation context"));
}
// This reference adapter draws/interacts with one full rectangular card.
// Rich sparse/translucent regions belong to the surface host adapter.
if geometry.painted.len() != 1
|| geometry.painted.first() != Some(&geometry.outer)
|| geometry.input.len() != 1
|| !geometry.input.first().is_some_and(|region| region.role == InputRole::Surface && region.bounds == geometry.outer)
{
return Err(error(Rule::Capability, "reference egui host requires one full painted/input surface"));
}
let rect = |r: LogicalRect| egui::Rect::from_min_size(egui::pos2(r.origin.x, r.origin.y), egui::vec2(r.size.width, r.size.height));
let outer = rect(geometry.outer);
let body = geometry.body.map(rect);
let parent_clip = self.ui.clip_rect().intersect(outer);
let container = crate::ui_kit::Container::new(self.ui.ctx(), crate::ui_kit::Surface::Panel);
let frame = container.frame(self.ui.ctx(), crate::theme::Tokens::get().dialog_body, crate::frame::Side::Left).inner_margin(0);
let mut failure = None;
self.ui.scope_builder(
egui::UiBuilder::new().scope_id(egui::Id::unique(("panel_runtime", &geometry.instance.0, &context.owner))).max_rect(outer),
|ui| {
ui.set_clip_rect(ui.clip_rect().intersect(parent_clip));
container.show_frame(ui, frame, outer, |ui| {
// Slots have explicit bounds. No mandatory ScrollArea around content.
let header = egui::Rect::from_min_max(outer.min, egui::pos2(outer.right(), body.map_or(outer.bottom(), |body| body.top())));
let footer = body.map(|body| egui::Rect::from_min_max(egui::pos2(outer.left(), body.bottom()), outer.max));
for (slot, bounds) in [(ContentSlot::Header, Some(header)), (ContentSlot::Body, body), (ContentSlot::Footer, footer)] {
let Some(bounds) = bounds else {
continue;
};
if failure.is_some() {
break;
}
ui.scope_builder(egui::UiBuilder::new().id_salt(slot as u8).max_rect(bounds), |ui| {
ui.set_clip_rect(ui.clip_rect().intersect(bounds));
if slot == ContentSlot::Header {
// Dynamic title/status have semantic metadata; content owns
// additional controls and returns requests through services.
let tokens = crate::theme::Tokens::get();
let ink = if presentation.attention { tokens.form_primary } else { tokens.form_ink };
let mut response = ui.label(egui::RichText::new(&presentation.title).color(ink));
if let Some(status) = &presentation.status {
response = response.backing_on_hover_text(status);
}
response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Label, true, &presentation.title));
}
if slot == ContentSlot::Footer && !presentation.actions.is_empty() {
egui::ScrollArea::horizontal().id_salt("panel_actions").show(ui, |ui| {
ui.horizontal(|ui| {
for action in &presentation.actions {
let response = ui
.push_id(&action.id.0, |ui| {
ui.add_enabled_ui(action.enabled, |ui| {
crate::ui_kit::button(ui, action.label.as_str(), crate::ui_kit::Button::Small)
})
.inner
})
.inner;
if let Some(pressed) = action.pressed {
ui.ctx().accesskit_node_builder(response.id, |node| node.set_toggled(pressed.into()));
}
let clicked = response.clicked();
if let Some(reason) = &action.disabled_reason {
response.backing_on_disabled_hover_text(reason);
}
if clicked
&& failure.is_none()
&& let Err(reason) = content.action(&context.owner, &action.id, services)
{
failure = Some(reason);
}
}
});
});
}
if geometry.body.is_some()
&& let Err(reason) = content.render(slot, ui, context, services)
{
failure = Some(reason);
}
});
}
ui.set_min_size(outer.size());
});
},
);
if let Some(reason) = failure {
return Err(reason);
}
Ok(())
}
}
use super::{ContentServices, PanelController};