ailloli_ui_widgets/editor/
builder.rs

1//! Public builder for the generic multi-paragraph editor widget.
2
3use ailloli_ui_core::style::{FlexItemStyle, LayoutSizeHint, LayoutStyle};
4use ailloli_ui_editor::{EditorConfig, EditorStyle, EditorWrapMode};
5use ailloli_ui_runtime::component::{IntoView, Signal, View};
6use ailloli_ui_text::TextBuffer;
7
8use crate::layout::layout_ext::finish_view_sized;
9
10use super::widget::{sanitize_caret_follow_margin_lines, EditorComponent};
11
12/// Multi-paragraph editor backed by a shared [`TextBuffer`] signal.
13///
14/// Edits update the supplied signal synchronously. The default uses
15/// [`EditorConfig::default`], automatic layout, and no initial selection. The
16/// retained widget is focusable, supports multiline keyboard/IME input, and
17/// has a 320×180 logical-pixel intrinsic cap/height before constraints. Wheel
18/// input preserves native horizontal and vertical axes, while `Shift` maps a
19/// vertical wheel delta to horizontal scrolling when wrapping is disabled.
20/// Editing and keyboard navigation keep the caret inside a safe visible region
21/// on both axes and preserve three visible lines below it by default. A caret
22/// already in that region never moves the viewport. Pointer clicks never move
23/// the viewport; pointer selection auto-scrolls only after leaving the visible
24/// text area.
25/// This generic editor intentionally does not paint a visual scrollbar.
26///
27/// # Examples
28///
29/// ```
30/// use ailloli_ui_runtime::component::State;
31/// use ailloli_ui_text::TextBuffer;
32/// use ailloli_ui_widgets::editor::Editor;
33/// let editor = Editor::new(State::new(TextBuffer::from_string("hello")));
34/// let _ = editor;
35/// ```
36pub struct Editor {
37    /// Outer logical sizing policy.
38    pub(crate) layout: LayoutStyle,
39    /// Parent-flex participation metadata.
40    pub(crate) flex_item: FlexItemStyle,
41    /// Caller-owned text buffer synchronized in both directions.
42    pub(crate) buffer: Signal<TextBuffer>,
43    /// Editing and rendering configuration.
44    pub(crate) config: EditorConfig,
45    /// Optional initial UTF-8 byte anchor/caret pair.
46    pub(crate) initial_selection: Option<(usize, usize)>,
47    /// Visible-line safety margin maintained below the revealed caret.
48    pub(crate) caret_follow_margin_lines: f32,
49}
50
51crate::impl_layout_builders_unit!(Editor);
52
53impl Editor {
54    /// Creates an editor bound to shared rope-buffer state.
55    ///
56    /// A standalone [`ailloli_ui_runtime::component::State`] is convenient for examples; component code may
57    /// pass a context-owned [`Signal`] so edits schedule invalidation.
58    ///
59    /// # Examples
60    ///
61    /// ```
62    /// use ailloli_ui_runtime::component::State;
63    /// use ailloli_ui_text::TextBuffer;
64    /// use ailloli_ui_widgets::editor::Editor;
65    /// let editor = Editor::new(State::new(TextBuffer::new()));
66    /// let _ = editor;
67    /// ```
68    pub fn new(buffer: impl Into<Signal<TextBuffer>>) -> Self {
69        Self {
70            layout: LayoutStyle::default(),
71            flex_item: FlexItemStyle::default(),
72            buffer: buffer.into(),
73            config: EditorConfig::default(),
74            initial_selection: None,
75            caret_follow_margin_lines: 3.0,
76        }
77    }
78
79    /// Replaces editor colors and logical-pixel metrics.
80    ///
81    /// # Examples
82    ///
83    /// ```
84    /// use ailloli_ui_editor::EditorStyle;
85    /// use ailloli_ui_runtime::component::State;
86    /// use ailloli_ui_text::TextBuffer;
87    /// use ailloli_ui_widgets::editor::Editor;
88    /// let editor = Editor::new(State::new(TextBuffer::new())).style(EditorStyle::default());
89    /// let _ = editor;
90    /// ```
91    pub fn style(mut self, style: EditorStyle) -> Self {
92        self.config.style = style;
93        self
94    }
95
96    /// Selects soft wrapping or horizontal no-wrap behavior.
97    ///
98    /// # Examples
99    ///
100    /// ```
101    /// use ailloli_ui_editor::EditorWrapMode;
102    /// use ailloli_ui_runtime::component::State;
103    /// use ailloli_ui_text::TextBuffer;
104    /// use ailloli_ui_widgets::editor::Editor;
105    /// let editor = Editor::new(State::new(TextBuffer::new())).wrap_mode(EditorWrapMode::NoWrap);
106    /// let _ = editor;
107    /// ```
108    pub fn wrap_mode(mut self, wrap_mode: EditorWrapMode) -> Self {
109        self.config.wrap_mode = wrap_mode;
110        self
111    }
112
113    /// Sets initial anchor/caret UTF-8 byte offsets.
114    ///
115    /// Both values are independently clamped to buffer length when the retained
116    /// component is first built. They are not ordered or validated as UTF-8
117    /// character boundaries and do not overwrite later retained selection state.
118    ///
119    /// # Examples
120    ///
121    /// ```
122    /// use ailloli_ui_runtime::component::State;
123    /// use ailloli_ui_text::TextBuffer;
124    /// use ailloli_ui_widgets::editor::Editor;
125    /// let editor = Editor::new(State::new(TextBuffer::from_string("hello"))).initial_selection(0, 5);
126    /// let _ = editor;
127    /// ```
128    pub fn initial_selection(mut self, anchor: usize, caret: usize) -> Self {
129        self.initial_selection = Some((anchor, caret));
130        self
131    }
132
133    /// Sets the visible-line safety margin kept below the revealed caret.
134    ///
135    /// The default is three lines. The margin applies to edits, paste, undo,
136    /// redo, IME changes, and keyboard navigation. Reveal always adds only the
137    /// distance by which the caret crosses the safe boundary; pointer clicks
138    /// never request caret following. Negative values become zero and
139    /// non-finite values restore the default.
140    ///
141    /// # Examples
142    ///
143    /// ```
144    /// use ailloli_ui_runtime::component::State;
145    /// use ailloli_ui_text::TextBuffer;
146    /// use ailloli_ui_widgets::editor::Editor;
147    /// let editor = Editor::new(State::new(TextBuffer::new()))
148    ///     .caret_follow_margin_lines(5.0);
149    /// let _ = editor;
150    /// ```
151    pub fn caret_follow_margin_lines(mut self, lines: f32) -> Self {
152        self.caret_follow_margin_lines = sanitize_caret_follow_margin_lines(lines);
153        self
154    }
155}
156
157/// Converts the builder into a retained editor component with flex/size hints.
158impl<A: 'static> IntoView<A> for Editor {
159    fn into_view(self) -> View<A> {
160        finish_view_sized(
161            View::component(EditorComponent {
162                layout: self.layout,
163                buffer: self.buffer,
164                config: self.config,
165                initial_selection: self.initial_selection,
166                caret_follow_margin_lines: self.caret_follow_margin_lines,
167            }),
168            self.flex_item,
169            LayoutSizeHint::from_layout(self.layout),
170        )
171    }
172}