Common/TreeView/
TreeViewProvider.rs

1// File: Common/Source/TreeView/TreeViewProvider.rs
2// Role: Defines the abstract service trait for creating and managing tree
3// views. Responsibilities:
4//   - Provide a contract for registering and unregistering tree data providers.
5//   - Define the "push" operations extensions can use to control the view's
6//     appearance (e.g., reveal, refresh, set title).
7//   - Define the "pull" operations the host can use to fetch tree data on
8//     demand (getChildren, getTreeItem).
9
10//! # TreeViewProvider Trait
11//!
12//! Defines the abstract service trait for creating and managing tree views
13//! contributed by extensions.
14
15use async_trait::async_trait;
16use serde_json::Value;
17
18use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
19
20/// An abstract service contract for an environment component that can manage
21/// the lifecycle and data flow for custom tree views.
22///
23/// This trait uses a hybrid model:
24/// - "Push" methods are called by the extension host (`Cocoon`) to manage the
25///   view's state and appearance in the main host (`Mountain`).
26/// - "Pull" methods are called by the main host (`Mountain`) to request data
27///   from the provider in the extension host (`Cocoon`) on-demand (e.g., when a
28///   user expands a node).
29#[async_trait]
30pub trait TreeViewProvider: Environment + Send + Sync {
31	// --- Methods called BY the extension host (PUSH) ---
32
33	/// Informs the host that a new tree data provider has been registered by
34	/// an extension. The host should prepare to display a tree view with the
35	/// given ID and options.
36	/// # Parameters
37	/// * `ViewIdentifier`: A unique identifier for the tree view.
38	/// * `OptionsValue`: DTO containing options like `CanSelectMany`.
39	async fn RegisterTreeDataProvider(
40		&self,
41
42		ViewIdentifier:String,
43
44		// DTO: TreeViewOptionsDTO
45		OptionsValue:Value,
46	) -> Result<(), CommonError>;
47
48	/// Informs the host that a tree data provider has been disposed of.
49	/// # Parameters
50	/// * `ViewIdentifier`: The ID of the tree view to unregister.
51	async fn UnregisterTreeDataProvider(&self, ViewIdentifier:String) -> Result<(), CommonError>;
52
53	/// Asks the host UI to reveal and/or expand a specific item in a tree view.
54	/// # Parameters
55	/// * `ViewIdentifier`: The ID of the target tree view.
56	/// * `ItemHandle`: The unique handle of the item to reveal.
57	/// * `OptionsValue`: DTO specifying reveal options like `select` and
58	///   `focus`.
59	async fn RevealTreeItem(
60		&self,
61
62		ViewIdentifier:String,
63
64		ItemHandle:String,
65
66		// DTO: RevealOptionsDTO
67		OptionsValue:Value,
68	) -> Result<(), CommonError>;
69
70	/// Notifies the host that some or all of the data in a tree view has
71	/// changed and needs to be re-fetched and re-rendered.
72	/// # Parameters
73	/// * `ViewIdentifier`: The ID of the tree view to refresh.
74	/// * `ItemsToRefreshValue`: Optional. If `None`, the entire tree is
75	///   refreshed. If `Some`, it's a DTO representing the specific items that
76	///   have changed, allowing for targeted updates.
77	async fn RefreshTreeView(
78		&self,
79
80		ViewIdentifier:String,
81
82		// DTO: Option<TreeItemDTO> or Vec<TreeItemDTO>
83		ItemsToRefreshValue:Option<Value>,
84	) -> Result<(), CommonError>;
85
86	/// Sets a message to be displayed in the tree view's empty state.
87	/// # Parameters
88	/// * `ViewIdentifier`: The ID of the target tree view.
89	/// * `Message`: An optional message to display. `None` clears the message.
90	async fn SetTreeViewMessage(&self, ViewIdentifier:String, Message:Option<String>) -> Result<(), CommonError>;
91
92	/// Sets the title and description of the tree view container.
93	/// # Parameters
94	/// * `ViewIdentifier`: The ID of the target tree view.
95	/// * `Title`: An optional new title for the view. `None` might reset to
96	///   default.
97	/// * `Description`: An optional description or sub-title. `None` clears it.
98	async fn SetTreeViewTitle(
99		&self,
100
101		ViewIdentifier:String,
102
103		Title:Option<String>,
104
105		Description:Option<String>,
106	) -> Result<(), CommonError>;
107
108	/// Sets a badge (e.g., a number) on the tree view's container icon.
109	/// # Parameters
110	/// * `ViewIdentifier`: The ID of the target tree view.
111	/// * `BadgeValue`: A DTO for the badge, or `None` to clear it.
112	async fn SetTreeViewBadge(
113		&self,
114
115		ViewIdentifier:String,
116
117		// DTO: TreeViewBadgeDTO
118		BadgeValue:Option<Value>,
119	) -> Result<(), CommonError>;
120
121	// --- Methods called BY the host (PULL) ---
122
123	/// Retrieves the children for a given tree element.
124	/// # Parameters
125	/// * `ViewIdentifier`: The ID of the target tree view.
126	/// * `ElementHandle`: An optional handle for the parent element. If `None`,
127
128	///   the root-level items should be returned.
129	/// # Returns
130	/// A vector of `TreeItemDTO`s representing the children.
131	async fn GetChildren(&self, ViewIdentifier:String, ElementHandle:Option<String>)
132	-> Result<Vec<Value>, CommonError>;
133
134	/// Retrieves the full `TreeItem` DTO for a given element handle.
135	/// This is used by the host to get the display properties of an item.
136	/// # Parameters
137	/// * `ViewIdentifier`: The ID of the target tree view.
138	/// * `ElementHandle`: The handle of the element to retrieve.
139	/// # Returns
140	/// A `TreeItemDTO` as a JSON value.
141	async fn GetTreeItem(&self, ViewIdentifier:String, ElementHandle:String) -> Result<Value, CommonError>;
142}
Common/TreeView/TreeViewProvider.rs

Common/TreeView/
TreeViewProvider.rs
