ailloli_ui_widgets/editor/code_builder.rs
1//! Public builder for the document-aware code editor widget.
2
3use ailloli_ui_core::style::{FlexItemStyle, LayoutSizeHint, LayoutStyle};
4use ailloli_ui_editor::{
5 CodeEditorConfig, CodeEditorFeatureFlags, CodeFileSummary, CodeTheme, Diagnostic, Document,
6 EditorLanguage, EditorScrollbarStyle, EditorWrapMode, FoldRegion, GutterConfig, SearchQuery,
7};
8use ailloli_ui_runtime::component::{IntoView, Signal, View};
9use ailloli_ui_runtime::input::EventCtx;
10use std::rc::Rc;
11
12use crate::layout::layout_ext::finish_view_sized;
13
14use super::code_widget::CodeEditorComponent;
15use super::widget::sanitize_caret_follow_margin_lines;
16
17/// Shared retained callback invoked after a text edit updates the document.
18///
19/// # Examples
20///
21/// ```
22/// use ailloli_ui_editor::{Document, DocumentId};
23/// use ailloli_ui_runtime::component::State;
24/// use ailloli_ui_text::TextBuffer;
25/// use ailloli_ui_widgets::editor::CodeEditor;
26/// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new())))
27/// .on_document_change_ctx(|_ctx, _document| {});
28/// let _ = editor;
29/// ```
30pub(crate) type DocumentChangeHandler<A> = Rc<dyn Fn(&mut EventCtx<A>, Document)>;
31
32/// Code-oriented editor backed by an [`ailloli_ui_editor::Document`] signal.
33///
34/// Edits synchronize the document version/dirty flag, update the supplied
35/// signal, refresh syntax/search/folds, and then invoke the optional change
36/// handler. Defaults come from [`CodeEditorConfig`]; optional prop vectors
37/// replace their corresponding session models when enabled. The default wrap
38/// mode is no-wrap, so long lines scroll horizontally. Overflowing axes paint
39/// interactive overlay scrollbars whose thumbs can be dragged from the exact
40/// pressed point and whose track clicks center the thumb; those interactions
41/// never move the caret. Editing
42/// and keyboard navigation follow the caret on both axes and preserve three
43/// visible lines below it by default. A caret already in the safe region never
44/// moves the viewport. Clicks never move the viewport, and pointer selection
45/// auto-scrolls only outside the text viewport.
46///
47/// # Examples
48///
49/// ```
50/// use ailloli_ui_editor::{Document, DocumentId};
51/// use ailloli_ui_runtime::component::State;
52/// use ailloli_ui_text::TextBuffer;
53/// use ailloli_ui_widgets::editor::CodeEditor;
54/// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new())));
55/// let _ = editor;
56/// ```
57pub struct CodeEditor<A = ()> {
58 /// Outer logical sizing policy.
59 pub(crate) layout: LayoutStyle,
60 /// Parent-flex participation metadata.
61 pub(crate) flex_item: FlexItemStyle,
62 /// Caller-owned document state synchronized in both directions.
63 pub(crate) document: Signal<Document>,
64 /// Editing, rendering, and feature configuration.
65 pub(crate) config: CodeEditorConfig,
66 /// Optional language override applied to the document.
67 pub(crate) language: Option<EditorLanguage>,
68 /// Optional initial horizontal/vertical offsets in logical pixels.
69 pub(crate) initial_scroll: Option<(f32, f32)>,
70 /// Optional initial search query.
71 pub(crate) search_query: Option<SearchQuery>,
72 /// Optional active search match index.
73 pub(crate) search_active_match: Option<usize>,
74 /// Diagnostics projected over the document.
75 pub(crate) diagnostics: Vec<Diagnostic>,
76 /// Optional active diagnostic index.
77 pub(crate) active_diagnostic: Option<usize>,
78 /// Optional caller-provided fold regions.
79 pub(crate) fold_regions: Option<Vec<FoldRegion>>,
80 /// Optional precomputed symbol summary.
81 pub(crate) symbol_summary: Option<CodeFileSummary>,
82 /// Optional initial UTF-8 byte anchor/caret pair.
83 pub(crate) initial_selection: Option<(usize, usize)>,
84 /// Visible-line safety margin maintained below the revealed caret.
85 pub(crate) caret_follow_margin_lines: f32,
86 /// Optional callback invoked after document-changing edits.
87 pub(crate) on_document_change: Option<DocumentChangeHandler<A>>,
88}
89
90crate::impl_layout_builders!(CodeEditor);
91
92impl<A: 'static> CodeEditor<A> {
93 /// Creates a code editor bound to shared document state.
94 ///
95 /// # Examples
96 ///
97 /// ```
98 /// use ailloli_ui_editor::{Document, DocumentId};
99 /// use ailloli_ui_runtime::component::State;
100 /// use ailloli_ui_text::TextBuffer;
101 /// use ailloli_ui_widgets::editor::CodeEditor;
102 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new())));
103 /// let _ = editor;
104 /// ```
105 pub fn new(document: impl Into<Signal<Document>>) -> Self {
106 Self {
107 layout: LayoutStyle::default(),
108 flex_item: FlexItemStyle::default(),
109 document: document.into(),
110 config: CodeEditorConfig::default(),
111 language: None,
112 initial_scroll: None,
113 search_query: None,
114 search_active_match: None,
115 diagnostics: Vec::new(),
116 active_diagnostic: None,
117 fold_regions: None,
118 symbol_summary: None,
119 initial_selection: None,
120 caret_follow_margin_lines: 3.0,
121 on_document_change: None,
122 }
123 }
124
125 /// Forces one language instead of document/path-derived resolution.
126 ///
127 /// # Examples
128 ///
129 /// ```
130 /// use ailloli_ui_editor::{Document, DocumentId, EditorLanguage};
131 /// use ailloli_ui_runtime::component::State;
132 /// use ailloli_ui_text::TextBuffer;
133 /// use ailloli_ui_widgets::editor::CodeEditor;
134 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).language(EditorLanguage::Rust);
135 /// let _ = editor;
136 /// ```
137 pub fn language(mut self, language: EditorLanguage) -> Self {
138 self.language = Some(language);
139 self
140 }
141
142 /// Replaces code colors and synchronizes generic editor background/foreground.
143 ///
144 /// # Examples
145 ///
146 /// ```
147 /// use ailloli_ui_editor::{CodeTheme, Document, DocumentId};
148 /// use ailloli_ui_runtime::component::State;
149 /// use ailloli_ui_text::TextBuffer;
150 /// use ailloli_ui_widgets::editor::CodeEditor;
151 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).theme(CodeTheme::dark());
152 /// let _ = editor;
153 /// ```
154 pub fn theme(mut self, theme: CodeTheme) -> Self {
155 self.config.theme = theme;
156 self.config.editor.style.bg = theme.background;
157 self.config.editor.style.fg = theme.foreground;
158 self
159 }
160
161 /// Replaces gutter enablement, width, line-number, fold, and diagnostic settings.
162 ///
163 /// # Examples
164 ///
165 /// ```
166 /// use ailloli_ui_editor::{Document, DocumentId, GutterConfig};
167 /// use ailloli_ui_runtime::component::State;
168 /// use ailloli_ui_text::TextBuffer;
169 /// use ailloli_ui_widgets::editor::CodeEditor;
170 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).gutter(GutterConfig::default());
171 /// let _ = editor;
172 /// ```
173 pub fn gutter(mut self, gutter: GutterConfig) -> Self {
174 self.config.gutter = gutter;
175 self
176 }
177
178 /// Replaces syntax/search/diagnostic/folding/symbol feature flags.
179 ///
180 /// Disabled features clear or skip the corresponding retained model.
181 ///
182 /// # Examples
183 ///
184 /// ```
185 /// use ailloli_ui_editor::{CodeEditorFeatureFlags, Document, DocumentId};
186 /// use ailloli_ui_runtime::component::State;
187 /// use ailloli_ui_text::TextBuffer;
188 /// use ailloli_ui_widgets::editor::CodeEditor;
189 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).features(CodeEditorFeatureFlags::default());
190 /// let _ = editor;
191 /// ```
192 pub fn features(mut self, features: CodeEditorFeatureFlags) -> Self {
193 self.config.features = features;
194 self
195 }
196
197 /// Enables/disables line numbers and ensures the gutter is enabled when true.
198 ///
199 /// Passing `false` hides line numbers but deliberately does not disable a
200 /// gutter that may still show folds or diagnostics.
201 ///
202 /// # Examples
203 ///
204 /// ```
205 /// use ailloli_ui_editor::{Document, DocumentId};
206 /// use ailloli_ui_runtime::component::State;
207 /// use ailloli_ui_text::TextBuffer;
208 /// use ailloli_ui_widgets::editor::CodeEditor;
209 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).line_numbers(false);
210 /// let _ = editor;
211 /// ```
212 pub fn line_numbers(mut self, enabled: bool) -> Self {
213 self.config.gutter.enabled = self.config.gutter.enabled || enabled;
214 self.config.gutter.line_numbers = enabled;
215 self
216 }
217
218 /// Selects soft wrapping or horizontal no-wrap behavior.
219 ///
220 /// # Examples
221 ///
222 /// ```
223 /// use ailloli_ui_editor::{Document, DocumentId, EditorWrapMode};
224 /// use ailloli_ui_runtime::component::State;
225 /// use ailloli_ui_text::TextBuffer;
226 /// use ailloli_ui_widgets::editor::CodeEditor;
227 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).wrap_mode(EditorWrapMode::SoftWrap);
228 /// let _ = editor;
229 /// ```
230 pub fn wrap_mode(mut self, wrap_mode: EditorWrapMode) -> Self {
231 self.config.editor.wrap_mode = wrap_mode;
232 self
233 }
234
235 /// Shows or hides editor-engine scrollbars without disabling scrolling.
236 ///
237 /// # Examples
238 ///
239 /// ```
240 /// use ailloli_ui_editor::{Document, DocumentId};
241 /// use ailloli_ui_runtime::component::State;
242 /// use ailloli_ui_text::TextBuffer;
243 /// use ailloli_ui_widgets::editor::CodeEditor;
244 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).scrollbars(false);
245 /// let _ = editor;
246 /// ```
247 pub fn scrollbars(mut self, enabled: bool) -> Self {
248 self.config.scrollbars.enabled = enabled;
249 self
250 }
251
252 /// Replaces editor scrollbar colors and logical-pixel geometry.
253 ///
254 /// # Examples
255 ///
256 /// ```
257 /// use ailloli_ui_editor::{Document, DocumentId, EditorScrollbarStyle};
258 /// use ailloli_ui_runtime::component::State;
259 /// use ailloli_ui_text::TextBuffer;
260 /// use ailloli_ui_widgets::editor::CodeEditor;
261 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).scrollbar_style(EditorScrollbarStyle::default());
262 /// let _ = editor;
263 /// ```
264 pub fn scrollbar_style(mut self, style: EditorScrollbarStyle) -> Self {
265 self.config.scrollbars.style = style;
266 self
267 }
268
269 /// Sets initial x/y scroll offsets in logical pixels.
270 ///
271 /// Each coordinate is floored at zero; negative and `NaN` values become
272 /// zero. The offsets are reapplied when an external document replacement is
273 /// observed, then normal editor metrics clamp them during frame building.
274 ///
275 /// # Examples
276 ///
277 /// ```
278 /// use ailloli_ui_editor::{Document, DocumentId};
279 /// use ailloli_ui_runtime::component::State;
280 /// use ailloli_ui_text::TextBuffer;
281 /// use ailloli_ui_widgets::editor::CodeEditor;
282 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).initial_scroll(12.0, 24.0);
283 /// let _ = editor;
284 /// ```
285 pub fn initial_scroll(mut self, x: f32, y: f32) -> Self {
286 self.initial_scroll = Some((x.max(0.0), y.max(0.0)));
287 self
288 }
289
290 /// Supplies the retained search query when search is enabled.
291 ///
292 /// # Examples
293 ///
294 /// ```
295 /// use ailloli_ui_editor::{Document, DocumentId, SearchQuery};
296 /// use ailloli_ui_runtime::component::State;
297 /// use ailloli_ui_text::TextBuffer;
298 /// use ailloli_ui_widgets::editor::CodeEditor;
299 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).search_query(SearchQuery::new("fn"));
300 /// let _ = editor;
301 /// ```
302 pub fn search_query(mut self, query: SearchQuery) -> Self {
303 self.search_query = Some(query);
304 self
305 }
306
307 /// Requests the active match index for the supplied search query.
308 ///
309 /// Out-of-range handling is delegated to the editor search state.
310 ///
311 /// # Examples
312 ///
313 /// ```
314 /// use ailloli_ui_editor::{Document, DocumentId};
315 /// use ailloli_ui_runtime::component::State;
316 /// use ailloli_ui_text::TextBuffer;
317 /// use ailloli_ui_widgets::editor::CodeEditor;
318 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).search_active_match(0);
319 /// let _ = editor;
320 /// ```
321 pub fn search_active_match(mut self, active_match: usize) -> Self {
322 self.search_active_match = Some(active_match);
323 self
324 }
325
326 /// Replaces local/LSP diagnostics when diagnostics are enabled.
327 ///
328 /// Empty clears diagnostics; ranges remain UTF-8 byte ranges governed by
329 /// the editor model.
330 ///
331 /// # Examples
332 ///
333 /// ```
334 /// use ailloli_ui_editor::{Diagnostic, DiagnosticSeverity, Document, DocumentId};
335 /// use ailloli_ui_runtime::component::State;
336 /// use ailloli_ui_text::TextBuffer;
337 /// use ailloli_ui_widgets::editor::CodeEditor;
338 /// let diagnostic = Diagnostic::new(0..1, DiagnosticSeverity::Warning, "check");
339 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::from_string("x")))).diagnostics(vec![diagnostic]);
340 /// let _ = editor;
341 /// ```
342 pub fn diagnostics(mut self, diagnostics: Vec<Diagnostic>) -> Self {
343 self.diagnostics = diagnostics;
344 self
345 }
346
347 /// Requests one diagnostic index as active.
348 ///
349 /// The value is forwarded without range validation; missing indexes simply
350 /// produce no active diagnostic decoration/hit.
351 ///
352 /// # Examples
353 ///
354 /// ```
355 /// use ailloli_ui_editor::{Document, DocumentId};
356 /// use ailloli_ui_runtime::component::State;
357 /// use ailloli_ui_text::TextBuffer;
358 /// use ailloli_ui_widgets::editor::CodeEditor;
359 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).active_diagnostic(0);
360 /// let _ = editor;
361 /// ```
362 pub fn active_diagnostic(mut self, active_diagnostic: usize) -> Self {
363 self.active_diagnostic = Some(active_diagnostic);
364 self
365 }
366
367 /// Replaces fold-region geometry when folding is enabled.
368 ///
369 /// If IDs and line bounds match retained regions, their current collapsed
370 /// state wins so a parent rebuild does not reopen user-toggled folds.
371 ///
372 /// # Examples
373 ///
374 /// ```
375 /// use ailloli_ui_editor::{Document, DocumentId, FoldRegion};
376 /// use ailloli_ui_runtime::component::State;
377 /// use ailloli_ui_text::TextBuffer;
378 /// use ailloli_ui_widgets::editor::CodeEditor;
379 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).fold_regions(vec![FoldRegion::new(0, 2)]);
380 /// let _ = editor;
381 /// ```
382 pub fn fold_regions(mut self, fold_regions: Vec<FoldRegion>) -> Self {
383 self.fold_regions = Some(fold_regions);
384 self
385 }
386
387 /// Supplies a precomputed symbol graph when symbol support is enabled.
388 ///
389 /// The current widget retains this metadata but has no symbol navigation UI;
390 /// it does not alter paint output yet.
391 ///
392 /// # Examples
393 ///
394 /// ```
395 /// use ailloli_ui_editor::{CodeFileSummary, Document, DocumentId, DocumentVersion, EditorLanguage};
396 /// use ailloli_ui_runtime::component::State;
397 /// use ailloli_ui_text::TextBuffer;
398 /// use ailloli_ui_widgets::editor::CodeEditor;
399 /// let summary = CodeFileSummary { document_id: DocumentId(1), path: None, language: EditorLanguage::Rust, version: DocumentVersion(0), symbols: vec![], edges: vec![] };
400 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).symbol_summary(summary);
401 /// let _ = editor;
402 /// ```
403 pub fn symbol_summary(mut self, summary: CodeFileSummary) -> Self {
404 self.symbol_summary = Some(summary);
405 self
406 }
407
408 /// Sets initial anchor/caret UTF-8 byte offsets.
409 ///
410 /// Values are independently clamped to document byte length on first build,
411 /// but are not ordered or validated as UTF-8 character boundaries.
412 ///
413 /// # Examples
414 ///
415 /// ```
416 /// use ailloli_ui_editor::{Document, DocumentId};
417 /// use ailloli_ui_runtime::component::State;
418 /// use ailloli_ui_text::TextBuffer;
419 /// use ailloli_ui_widgets::editor::CodeEditor;
420 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::from_string("hello")))).initial_selection(0, 5);
421 /// let _ = editor;
422 /// ```
423 pub fn initial_selection(mut self, anchor: usize, caret: usize) -> Self {
424 self.initial_selection = Some((anchor, caret));
425 self
426 }
427
428 /// Sets the visible-line safety margin kept below the revealed caret.
429 ///
430 /// The default is three lines. The margin applies to edits, paste, undo,
431 /// redo, IME changes, and keyboard navigation. Reveal always adds only the
432 /// distance by which the caret crosses the safe boundary; pointer clicks
433 /// never request caret following. Negative values become zero and
434 /// non-finite values restore the default.
435 ///
436 /// # Examples
437 ///
438 /// ```
439 /// use ailloli_ui_editor::{Document, DocumentId};
440 /// use ailloli_ui_runtime::component::State;
441 /// use ailloli_ui_text::TextBuffer;
442 /// use ailloli_ui_widgets::editor::CodeEditor;
443 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(
444 /// DocumentId(1),
445 /// TextBuffer::new(),
446 /// )))
447 /// .caret_follow_margin_lines(5.0);
448 /// let _ = editor;
449 /// ```
450 pub fn caret_follow_margin_lines(mut self, lines: f32) -> Self {
451 self.caret_follow_margin_lines = sanitize_caret_follow_margin_lines(lines);
452 self
453 }
454
455 /// Maps each edited document into an application action.
456 ///
457 /// The handler runs only after a text-changing edit has synchronized the
458 /// document, not for selection, scroll, or external prop updates.
459 ///
460 /// # Examples
461 ///
462 /// ```
463 /// use ailloli_ui_editor::{Document, DocumentId};
464 /// use ailloli_ui_runtime::component::State;
465 /// use ailloli_ui_text::TextBuffer;
466 /// use ailloli_ui_widgets::editor::CodeEditor;
467 /// enum Action { Changed(Document) }
468 /// let editor: CodeEditor<Action> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).on_document_change(Action::Changed);
469 /// let _ = editor;
470 /// ```
471 pub fn on_document_change(mut self, f: impl Fn(Document) -> A + 'static) -> Self {
472 self.on_document_change = Some(Rc::new(move |ctx, document| ctx.dispatch(f(document))));
473 self
474 }
475
476 /// Handles edited documents with mutable runtime event-context access.
477 ///
478 /// # Examples
479 ///
480 /// ```
481 /// use ailloli_ui_editor::{Document, DocumentId};
482 /// use ailloli_ui_runtime::component::State;
483 /// use ailloli_ui_text::TextBuffer;
484 /// use ailloli_ui_widgets::editor::CodeEditor;
485 /// let editor: CodeEditor<()> = CodeEditor::new(State::new(Document::new(DocumentId(1), TextBuffer::new()))).on_document_change_ctx(|_ctx, _document| {});
486 /// let _ = editor;
487 /// ```
488 pub fn on_document_change_ctx(
489 mut self,
490 f: impl Fn(&mut EventCtx<A>, Document) + 'static,
491 ) -> Self {
492 self.on_document_change = Some(Rc::new(f));
493 self
494 }
495}
496
497/// Converts the builder into a retained code-editor component with layout hints.
498impl<A: 'static> IntoView<A> for CodeEditor<A> {
499 fn into_view(self) -> View<A> {
500 finish_view_sized(
501 View::component(CodeEditorComponent {
502 layout: self.layout,
503 document: self.document,
504 config: self.config,
505 language: self.language,
506 initial_scroll: self.initial_scroll,
507 search_query: self.search_query,
508 search_active_match: self.search_active_match,
509 diagnostics: self.diagnostics,
510 active_diagnostic: self.active_diagnostic,
511 fold_regions: self.fold_regions,
512 symbol_summary: self.symbol_summary,
513 initial_selection: self.initial_selection,
514 caret_follow_margin_lines: self.caret_follow_margin_lines,
515 on_document_change: self.on_document_change,
516 }),
517 self.flex_item,
518 LayoutSizeHint::from_layout(self.layout),
519 )
520 }
521}