Skip to main content

ratatui_flow/
direction.rs

1//! Flow direction for graph layout: which way the tree "grows" from root to
2//! children, and (independently) whether the main axis is mirrored so the root
3//! ends up at the far edge.
4//!
5//! ## Coordinate model
6//!
7//! All layout and routing happens in a single off-screen **canvas** coordinate
8//! space with origin at the top-left, `x` growing right, `y` growing down.
9//! `place_node` always advances the **main axis** (the flow axis) away from the
10//! root and stacks siblings along the **cross axis**; a final mirror step flips
11//! the main axis onto the screen so the root lands at the configured edge.
12//!
13//! | Direction | main axis | cross axis | root lands at | mirror main axis? |
14//! |-----------|-----------|------------|--------------|-------------------|
15//! | `Rtl` (default) | x (horizontal) | y | right edge   | yes               |
16//! | `Ltr`           | x (horizontal) | y | left edge    | no                |
17//! | `Ttb`           | y (vertical)   | x | top edge     | no                |
18//! | `Btt`           | y (vertical)   | x | bottom edge  | yes               |
19//!
20//! `Rtl` (the default) is byte-for-byte identical to the pre-parameterization
21//! hard-coded layout — `FlowDirection::default() == FlowDirection::Rtl`.
22
23use crate::connection::Direction;
24
25/// Which way a [`crate::NodeGraph`] flows: the main axis along which children
26/// are laid out away from the root, and which screen edge the root anchors to.
27///
28/// See the [module docs][self] for the full coordinate model. The default
29/// (`Rtl`) preserves the original hard-coded behavior exactly — roots on the
30/// right, children flowing leftward.
31#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
32pub enum FlowDirection {
33	/// Left-to-right: root at the left edge, children flow rightward.
34	Ltr,
35	/// Right-to-left: root at the right edge, children flow leftward.
36	/// (The original hard-coded behavior; the default.)
37	#[default]
38	Rtl,
39	/// Top-to-bottom: root at the top edge, children flow downward.
40	Ttb,
41	/// Bottom-to-top: root at the bottom edge, children flow upward.
42	Btt,
43}
44
45impl FlowDirection {
46	/// `true` when the main axis is horizontal (`Ltr`/`Rtl`); `false` when it is
47	/// vertical (`Ttb`/`Btt`). Determines whether the main axis is `x` and the
48	/// cross axis is `y`, or vice versa.
49	pub(crate) fn is_horizontal(self) -> bool {
50		matches!(self, FlowDirection::Ltr | FlowDirection::Rtl)
51	}
52
53	/// The canvas-axis [`Direction`] a connection **leaves** the `from` node on
54	/// (the out-port side). This is the entry direction assigned to the pathing
55	/// `start` cell. It must point at an edge of the port cell that is **not**
56	/// blocked by the node's `block_zone`, i.e. toward the open side the
57	/// connection runs into.
58	///
59	/// Matches the pre-parameterization hard-coded values for `Ltr`/`Rtl`
60	/// (`West`); the vertical directions pick the open-facing side after the
61	/// main-axis mirror (`North` for `Ttb`, `South` for `Btt`).
62	pub(crate) fn main_out_direction(self) -> Direction {
63		match self {
64			FlowDirection::Ltr | FlowDirection::Rtl => Direction::West,
65			FlowDirection::Ttb => Direction::North,
66			FlowDirection::Btt => Direction::South,
67		}
68	}
69
70	/// The canvas-axis [`Direction`] a connection **enters** the `to` node on
71	/// (the in-port side): the opposite of [`main_out_direction`][Self::main_out_direction].
72	pub(crate) fn main_in_direction(self) -> Direction {
73		match self.main_out_direction() {
74			Direction::East => Direction::West,
75			Direction::West => Direction::East,
76			Direction::North => Direction::South,
77			Direction::South => Direction::North,
78		}
79	}
80
81	/// Whether the main axis is mirrored when transforming canvas→screen
82	/// coordinates (i.e. the root ends up at the *far* edge rather than the
83	/// origin edge). `Rtl` and `Btt` mirror; `Ltr` and `Ttb` do not.
84	pub(crate) fn mirror_main_axis(self) -> bool {
85		matches!(self, FlowDirection::Rtl | FlowDirection::Btt)
86	}
87}