feat(gpui): add dock, effect stack, node graph, and timeline widgets

Implements four workspace widget modules with accompanying learn examples: - dock: dockable panel layout system (tabs, splits, drag-to-dock) with serde-based persistence via PanelRegistry / DockLayoutState - effect_stack: linear effect-stack inspector widget - node_graph: node-graph editor (nodes, ports, wires, pan/zoom canvas) - timeline: video-editing timeline (tracks, clips, ruler, playhead) Timeline snapping prefers the earlier frame when two snap points are equally close, with SnapKind priority breaking same-frame ties.
2026-08-09 03:31:06 +08:00
parent 6043651563
commit ad7c965c5a
33 changed files with 10601 additions and 0 deletions
@@ -0,0 +1,234 @@
+//! Data-source traits and identifier types for the node-graph editor.
+//!
+//! The widget is fully data-agnostic: it reads everything it displays through
+//! the traits in this file and never mutates the underlying model. The
+//! embedding application implements these traits over its own graph (for Oak:
+//! the `oakengine` node graph) and reacts to the [`NodeGraphEvent`]s emitted
+//! by the view.
+//!
+//! [`NodeGraphEvent`]: crate::node_graph::NodeGraphEvent
+
+use crate::{Hsla, Pixels, Point, SharedString};
+
+/// Unique identifier of a node within the graph.
+///
+/// Typically a newtype over the host application's own node key (e.g. an
+/// engine node handle). The widget only requires that ids are cheap to copy,
+/// totally ordered (for selection sets) and hashable (for lookup maps).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct NodeId(pub u64);
+
+/// Unique identifier of a port within the graph.
+///
+/// Port ids are *globally* unique, not per-node, so that a single [`PortId`]
+/// is enough to address an endpoint of a connection request. The app is free
+/// to pack a node id and a per-node port index into the `u64` however it
+/// likes.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PortId(pub u64);
+
+/// Unique identifier of an edge (a connection between two ports).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct EdgeId(pub u64);
+
+/// Whether a port accepts incoming connections or produces outgoing ones.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum PortKind {
+    /// A port that consumes data; conventionally drawn on the left side of a
+    /// node and accepts connections *from* an [`PortKind::Output`] port.
+    Input,
+    /// A port that produces data; conventionally drawn on the right side of a
+    /// node and connects *to* an [`PortKind::Input`] port.
+    Output,
+}
+
+/// A lightweight, app-defined descriptor of the data flowing through a port.
+///
+/// The widget does not interpret data types semantically — it uses the
+/// [`color`](Self::color) to tint port dots and wires, and uses
+/// [`PartialEq`] only as a convenience for *default* visual hints. The
+/// authoritative compatibility check is always
+/// [`NodeGraphDataSource::can_connect`], so an app may implement subtyping,
+/// implicit conversions (e.g. `int → float`) or direction-dependent rules
+/// there without this type needing to model them.
+///
+/// # Equality contract
+///
+/// Two [`PortDataType`] values are considered the same type when their
+/// `name`s are equal; the color is *not* part of equality. Apps that want
+/// distinct types sharing a name should disambiguate the name.
+#[derive(Clone, Debug)]
+pub struct PortDataType {
+    /// Human-readable type name, e.g. `"video"`, `"audio"`, `"matte"`.
+    /// Also used as the identity of the type (see type-level docs).
+    pub name: SharedString,
+    /// Color used to tint port dots and wires carrying this type.
+    pub color: Hsla,
+}
+
+impl PortDataType {
+    /// Creates a new data-type descriptor with the given display name and
+    /// tint color.
+    pub fn new(name: impl Into<SharedString>, color: Hsla) -> Self {
+        Self {
+            name: name.into(),
+            color,
+        }
+    }
+}
+
+impl PartialEq for PortDataType {
+    fn eq(&self, other: &Self) -> bool {
+        self.name == other.name
+    }
+}
+
+impl Eq for PortDataType {}
+
+/// A single port on a node.
+///
+/// Ports are the endpoints of edges. Each port has a globally unique
+/// [`PortId`], a direction ([`PortKind`]) and a [`PortDataType`] used for
+/// tinting.
+pub trait PortData {
+    /// Returns the globally unique identifier of this port.
+    fn id(&self) -> PortId;
+
+    /// Returns whether this is an input or an output port.
+    fn kind(&self) -> PortKind;
+
+    /// Returns the short label drawn next to the port dot (e.g. `"in"`,
+    /// `"mask"`). May be empty, in which case only the dot is drawn.
+    fn label(&self) -> SharedString;
+
+    /// Returns the data type of this port, used to tint the port dot and any
+    /// wires connected to it.
+    fn data_type(&self) -> PortDataType;
+
+    /// Returns whether this port currently has at least one edge attached.
+    ///
+    /// Used only for rendering (connected dots are filled, unconnected dots
+    /// are hollow) and for styling during wire drags; the widget does not
+    /// enforce any cardinality rules from it — that is the job of
+    /// [`NodeGraphDataSource::can_connect`].
+    fn is_connected(&self) -> bool;
+}
+
+/// A single node in the graph.
+///
+/// Nodes are rectangular cards with a header, a column of input ports on the
+/// left and a column of output ports on the right (see
+/// [`NodeElement`](crate::node_graph::NodeElement)).
+pub trait NodeData {
+    /// The port type used by this node's inputs and outputs.
+    type Port: PortData;
+
+    /// Returns the unique identifier of this node.
+    fn id(&self) -> NodeId;
+
+    /// Returns the title drawn in the node's header.
+    fn title(&self) -> SharedString;
+
+    /// Returns the position of the node's top-left corner in *graph space*
+    /// (the document coordinate system).
+    ///
+    /// Graph space is an unbounded, zoom-independent coordinate system: a
+    /// node at `point(px(100.), px(40.))` stays attached to that document
+    /// location regardless of pan and zoom. The view converts to screen
+    /// coordinates with
+    /// [`GraphViewState::graph_to_screen`](crate::node_graph::GraphViewState::graph_to_screen).
+    fn position(&self) -> Point<Pixels>;
+
+    /// Returns the input ports of this node, in top-to-bottom draw order.
+    fn inputs(&self) -> Vec<Self::Port>;
+
+    /// Returns the output ports of this node, in top-to-bottom draw order.
+    fn outputs(&self) -> Vec<Self::Port>;
+
+    /// Returns an optional accent color for the node header, or `None` to use
+    /// the theme default. Apps typically use this to group nodes by category
+    /// (inputs, transforms, color management, outputs, …).
+    fn header_color(&self) -> Option<Hsla>;
+
+    /// Returns whether the node is collapsed to just its header.
+    ///
+    /// Collapsed nodes draw no ports and cannot be connection targets. The
+    /// collapsed state itself belongs to the app's model (or view state); the
+    /// widget only reflects it.
+    fn is_collapsed(&self) -> bool;
+
+    /// Returns whether the node is enabled.
+    ///
+    /// Disabled nodes (e.g. a bypassed effect) are drawn dimmed. This is a
+    /// purely visual hint; the widget does not change interaction behavior
+    /// for disabled nodes.
+    fn is_enabled(&self) -> bool;
+}
+
+/// A single directed connection from an output port to an input port.
+pub trait EdgeData {
+    /// Returns the unique identifier of this edge.
+    fn id(&self) -> EdgeId;
+
+    /// Returns the id of the node the connection starts at.
+    fn from_node(&self) -> NodeId;
+
+    /// Returns the id of the output port the connection starts at.
+    fn from_port(&self) -> PortId;
+
+    /// Returns the id of the node the connection ends at.
+    fn to_node(&self) -> NodeId;
+
+    /// Returns the id of the input port the connection ends at.
+    fn to_port(&self) -> PortId;
+}
+
+/// The data source backing a [`NodeGraphView`](crate::node_graph::NodeGraphView).
+///
+/// The app implements this trait over its engine model and places it in an
+/// `Entity`. The view re-reads `nodes()` and `edges()` every frame in which
+/// the entity notifies, so implementations should be cheap snapshots or
+/// borrow from cached data.
+///
+/// All methods take `&self`; the widget never mutates the source. Edits
+/// arrive back at the app as [`NodeGraphEvent`]s.
+///
+/// [`NodeGraphEvent`]: crate::node_graph::NodeGraphEvent
+pub trait NodeGraphDataSource {
+    /// The node type returned by [`nodes()`](Self::nodes).
+    type Node: NodeData;
+    /// The edge type returned by [`edges()`](Self::edges).
+    type Edge: EdgeData;
+
+    /// Returns all nodes to display, in no required order (the view sorts for
+    /// painting; selection order is unaffected).
+    fn nodes(&self) -> Vec<Self::Node>;
+
+    /// Returns all edges to display. Edges referencing ports or nodes that
+    /// are not part of [`nodes()`](Self::nodes) are ignored by the view.
+    fn edges(&self) -> Vec<Self::Edge>;
+
+    /// Returns whether connecting output port `from` to input port `to`
+    /// would be valid.
+    ///
+    /// This is the single place where the app enforces its connection rules:
+    /// data-type compatibility (including implicit conversions), cycle
+    /// prevention, port cardinality, node enablement, and so on. The view
+    /// calls this:
+    ///
+    /// - *continuously during a wire drag* to highlight compatible target
+    ///   ports and to mark the ghost wire as valid/invalid, and
+    /// - *once on drop* before emitting
+    ///   [`NodeGraphEvent::ConnectionRequested`](crate::node_graph::NodeGraphEvent::ConnectionRequested)
+    ///   — a drop on a port for which this returns `false` cancels the drag
+    ///   silently.
+    ///
+    /// It must be cheap, pure, and consistent: the same arguments must yield
+    /// the same answer within a frame. The view passes output port first,
+    /// input port second, regardless of which end the user started the drag
+    /// from. Returning `true` here does not commit the app to accepting the
+    /// connection; the engine may still reject it when the event arrives
+    /// (e.g. it raced with another edit), in which case the app simply does
+    /// not apply it.
+    fn can_connect(&self, from: PortId, to: PortId) -> bool;
+}