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}