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}